fix: harden critical paths — SIGTERM test, retry state machine, PD extraction

Three reviews (admissions, Anthropic staff, CEO hold-scope) converged on
the same gaps. This commit addresses them:

- Add SIGTERM integration test validating log flush on signal (was untested)
- Refactor retry manager to explicit discriminated union state (was two
  synchronized maps that could desync)
- Remove unused lastLineCount variable (lint fix)
- Extract schema compression and file locking into dedicated modules
  (pd-schema.ts, file-lock.ts) for the PD redesign
- Fix proxy signal handlers to delegate cleanup through upstream close
  event with 5s safety timeout (was calling process.exit directly,
  losing PD usage data)
- Add CLAUDE.md with project conventions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lewisnsmith

CLAUDE.md

@@ -0,0 +1,62 @@
+# Flight — MCP Flight Recorder & Token Optimizer
+
+## Stack
+
+TypeScript, Node 20+, ESM modules, Vitest, tsup, Commander
+
+## Project Structure
+
+```
+src/
+  cli.ts               — Commander CLI entry point
+  proxy.ts             — stdio proxy: spawn upstream, bidirectional JSON-RPC forwarding
+  json-rpc.ts          — streaming JSON-RPC parser
+  logger.ts            — session logger with async write queue and alert detection
+  progressive-disclosure.ts — PD handler: phase logic, usage tracking, tool filtering
+  pd-schema.ts         — pure schema compression utilities
+  file-lock.ts         — advisory file locking (O_CREAT|O_EXCL)
+  retry.ts             — automatic retry manager for transient MCP errors
+  hooks.ts             — Claude Code hook installation/removal
+  init.ts              — Claude/Claude Code config file management
+  setup.ts             — interactive setup wizard
+  summary.ts           — session summary computation
+  stats.ts             — usage statistics
+  lifecycle.ts         — log compression and garbage collection
+  export.ts            — CSV/JSONL export
+  replay.ts            — tool call replay from logs
+  log-commands.ts      — CLI subcommands for log inspection
+  index.ts             — public API re-exports
+```
+
+## Commands
+
+```bash
+npm run build       # Build with tsup
+npm run test        # Run tests (vitest)
+npm run lint        # ESLint
+npm run typecheck   # tsc --noEmit (src + test)
+npm run check       # lint + typecheck + test (use before committing)
+```
+
+## Key Patterns
+
+- **Handler result objects** — `PDResponseResult` carries rewritten responses, log metadata, and status messages in one return value. Callers branch on fields, not exceptions.
+- **Async write queue** — Logger batches writes with a flush timer; `closeSync()` drains synchronously for signal handlers.
+- **File locking** — `acquireLock(path)` uses `O_CREAT|O_EXCL` with PID-based stale detection. Returns `""` on timeout (best-effort, never blocks).
+- **JSON-RPC streaming** — `parseJsonRpcStream` is a newline-delimited JSON parser on Node readable streams, emitting typed `JsonRpcMessage` events.
+- **Progressive disclosure phases** — Phase 1 (observation), Phase 2 (schema compression), Phase 3 (compression + filtering with `discover_tools`).
+
+## Testing
+
+- Tests live in `test/` alongside source
+- Mock MCP server pattern: spawn a test server, connect via proxy, assert on JSON-RPC messages
+- `test/simulate/` contains validation harnesses for Claude API compatibility
+- Run `npm run test` — all tests should pass before any PR
+
+## Git Conventions
+
+- Commit format: `<type>: <description>` (feat, fix, refactor, docs, test, chore)
+- Messages explain WHY, not what
+- One logical change per commit
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for deeper design details.

src/file-lock.ts

@@ -0,0 +1,68 @@
+/**
+ * Advisory file locking using atomic O_CREAT|O_EXCL.
+ * Caller provides the full lock file path, making this module reusable.
+ */
+
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_WAIT_MS = 2000;
+const LOCK_STALE_MS = 10_000;
+
+/**
+ * Acquire an advisory file lock at `lockPath`.
+ * Returns the lock path on success, or "" on timeout (best-effort — don't block the caller).
+ */
+export async function acquireLock(lockPath: string): Promise<string> {
+  await mkdir(dirname(lockPath), { recursive: true });
+
+  const deadline = Date.now() + LOCK_MAX_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      // O_CREAT | O_EXCL — atomic creation, fails if file exists
+      const handle = await open(lockPath, "wx");
+      await handle.writeFile(String(process.pid));
+      await handle.close();
+      return lockPath;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+        // Check for stale lock
+        try {
+          const content = await readFile(lockPath, "utf-8");
+          const lockStat = await stat(lockPath);
+          const age = Date.now() - lockStat.mtimeMs;
+          if (age > LOCK_STALE_MS) {
+            // Stale lock — remove and retry
+            try { await unlink(lockPath); } catch { /* race with another cleaner */ }
+            continue;
+          }
+          // Check if the PID is still alive
+          const pid = parseInt(content, 10);
+          if (pid && !isNaN(pid)) {
+            try { process.kill(pid, 0); } catch {
+              // Process is dead — stale lock
+              try { await unlink(lockPath); } catch { /* race */ }
+              continue;
+            }
+          }
+        } catch {
+          // Can't read lock file, will retry
+        }
+        await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+        continue;
+      }
+      throw err;
+    }
+  }
+  // Timeout — proceed without lock (best-effort, don't block the session)
+  return "";
+}
+
+/**
+ * Release an advisory file lock. No-op if lockPath is empty (lock was never acquired).
+ */
+export async function releaseLock(lockPath: string): Promise<void> {
+  if (!lockPath) return;
+  try { await unlink(lockPath); } catch { /* already removed */ }
+}

src/log-commands.ts

@@ -187,13 +187,11 @@ export async function tailSession(sessionId?: string): Promise<void> {
   console.log(`${C.dim}  Press Ctrl+C to stop${C.reset}\n`);
 
   // Print existing entries
-  let lastLineCount = 0;
   try {
     const entries = await readLogEntries(file);
     for (const entry of entries) {
       console.log(formatEntryLine(entry));
     }
-    lastLineCount = entries.length;
   } catch {
     // File might be empty
   }

src/pd-schema.ts

@@ -0,0 +1,59 @@
+/**
+ * Schema compression utilities for progressive disclosure.
+ * Pure functions — no I/O, no side effects.
+ */
+
+export function estimateTokens(obj: unknown): number {
+  return Math.ceil(JSON.stringify(obj).length / 4);
+}
+
+/**
+ * Compress a JSON Schema by stripping property descriptions, examples,
+ * defaults, $comment, and redundant additionalProperties on nested objects.
+ * Preserves: property names, type, required, enum, oneOf/anyOf/allOf.
+ */
+export function compressSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  return compressNode(schema, /* isRoot */ true) as Record<string, unknown>;
+}
+
+function compressNode(node: unknown, isRoot: boolean): unknown {
+  if (node === null || node === undefined || typeof node !== "object") {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((item) => compressNode(item, false));
+  }
+
+  const obj = node as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    // Strip fields on non-root nodes
+    if (!isRoot) {
+      if (key === "description") continue;
+      if (key === "examples") continue;
+      if (key === "default") continue;
+      if (key === "$comment") continue;
+      if (key === "additionalProperties" && value === false) continue;
+    }
+
+    // Recurse into nested structures
+    if (key === "properties" && typeof value === "object" && value !== null) {
+      const props = value as Record<string, unknown>;
+      const compressed: Record<string, unknown> = {};
+      for (const [propName, propSchema] of Object.entries(props)) {
+        compressed[propName] = compressNode(propSchema, false);
+      }
+      result[key] = compressed;
+    } else if (key === "items" && typeof value === "object") {
+      result[key] = compressNode(value, false);
+    } else if ((key === "oneOf" || key === "anyOf" || key === "allOf") && Array.isArray(value)) {
+      result[key] = value.map((item) => compressNode(item, false));
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}