Fix 16 code quality issues from comprehensive review

- Remove unused pino dep, dead spawnProxy function, unused variables
- Dynamic CLI version from package.json, bump to 0.1.1
- Add closed guard to logger enqueue, flush pendingClientRequests on exit
- Scope hallucination detection to tools/call only, add time window
- Add SIGTERM handler to tailSession, incremental byte reads for tail
- Shell-safe quoting in init commands, skip fake commands when no config
- Add npx flight pattern detection for idempotent wrapping
- Add tsconfig.test.json for test/bench type checking
- Add close event to JsonRpcParser interface, fix test type errors
- Fix alerts test to filter by session_id (avoid cross-test pollution)
- Bump Node engine to >=20.11.0, CI matrix to 20.x/22.x
- Add status note to PRD

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

Author: lewisnsmith

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 22]
+        node-version: ['20.x', '22.x']
 
     steps:
       - uses: actions/checkout@v4

docs/flight-prd.md

@@ -1,5 +1,7 @@
 # Product Requirements Document: Flight Proxy
 
+> **Status:** This document describes the full v1.0 vision. For current implementation status, see the [README](../README.md).
+
 ## Overview
 
 **Product Name:** Flight Proxy

package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-proxy",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP flight recorder and token optimizer for AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.test.json",
     "bench": "npx tsx bench/throughput.ts",
     "check": "npm run lint && npm run typecheck && npm run test",
     "prepublishOnly": "npm run build"
@@ -30,17 +30,16 @@
     "tool-calling",
     "flight-recorder"
   ],
-  "author": "",
+  "author": "Lewis Smith",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=20.11.0"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "commander": "^14.0.3",
-    "pino": "^10.3.1"
+    "commander": "^14.0.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

src/cli.ts

@@ -1,14 +1,18 @@
 import { Command } from "commander";
+import { createRequire } from "node:module";
 import { startProxy } from "./proxy.js";
 import { initClaude, initClaudeCode, getClaudeConfigPath, getClaudeCodeConfigPath } from "./init.js";
 import { listSessions, tailSession, viewSession, filterSessions, inspectCall, listAlerts } from "./log-commands.js";
 
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as { version: string };
+
 const program = new Command();
 
 program
   .name("flight")
   .description("MCP flight recorder and token optimizer for AI coding agents")
-  .version("0.2.0");
+  .version(pkg.version);
 
 program
   .command("proxy")

src/init.ts

@@ -30,11 +30,15 @@ export function wrapWithFlight(servers: Record<string, McpServerEntry>): Record<
   const wrapped: Record<string, McpServerEntry> = {};
 
   for (const [name, server] of Object.entries(servers)) {
-    // Skip if already wrapped
+    // Skip if already wrapped (direct invocation or via npx)
     if (server.command === "flight" || server.command === "flight-proxy") {
       wrapped[name] = server;
       continue;
     }
+    if (server.args?.[0] === "flight" && server.args?.[1] === "proxy") {
+      wrapped[name] = server;
+      continue;
+    }
 
     const args = ["proxy", "--cmd", server.command];
     if (server.args && server.args.length > 0) {
@@ -118,15 +122,17 @@ export async function initClaudeCode(options: ClaudeCodeInitOptions = {}): Promi
     };
   }
 
-  // Non-apply mode: print claude mcp add-json commands
+  // Non-apply mode: print claude mcp add-json commands (only for real configs)
   const commands: string[] = [];
-  for (const [name, server] of Object.entries(wrapped)) {
-    const json = JSON.stringify(server);
-    // Escape single quotes for shell safety: replace ' with '\''
-    const escapedJson = json.replace(/'/g, "'\\''");
-    const escapedName = name.replace(/'/g, "'\\''");
-    const scopeFlag = scope === "project" ? " --scope project" : "";
-    commands.push(`claude mcp add-json '${escapedName}' '${escapedJson}'${scopeFlag}`);
+  if (configFound) {
+    for (const [name, server] of Object.entries(wrapped)) {
+      const json = JSON.stringify(server);
+      // Escape single quotes for shell safety: replace ' with '\''
+      const escapedJson = json.replace(/'/g, "'\\''");
+      const escapedName = name.replace(/'/g, "'\\''");
+      const scopeFlag = scope === "project" ? " --scope project" : "";
+      commands.push(`claude mcp add-json '${escapedName}' '${escapedJson}'${scopeFlag}`);
+    }
   }
 
   // Also write snippet for reference

src/json-rpc.ts

@@ -14,6 +14,7 @@ export interface JsonRpcMessage {
 export interface JsonRpcParser extends EventEmitter {
   on(event: "message", listener: (msg: JsonRpcMessage) => void): this;
   on(event: "error", listener: (err: Error) => void): this;
+  on(event: "close", listener: () => void): this;
 }
 
 export function parseJsonRpcStream(input: Readable): JsonRpcParser {

src/log-commands.ts

@@ -1,4 +1,4 @@
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile, stat, open } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { watch } from "node:fs";
@@ -163,36 +163,49 @@ export async function tailSession(sessionId?: string): Promise<void> {
     // ignore
   }
 
+  let partialLine = "";
+
   const watcher = watch(filePath, async () => {
     try {
       const s = await stat(filePath);
       if (s.size <= lastSize) return;
 
-      const content = await readFile(filePath, "utf-8");
-      const lines = content.trim().split("\n").filter(Boolean);
-
-      // Parse only genuinely new lines
-      const newLines = lines.slice(lastLineCount);
-      for (const line of newLines) {
-        try {
-          const entry = JSON.parse(line) as LogEntry;
-          console.log(formatEntryLine(entry));
-        } catch {
-          // skip malformed lines during active writing
+      // Read only new bytes from the file
+      const fd = await open(filePath, "r");
+      try {
+        const newBytes = Buffer.alloc(s.size - lastSize);
+        await fd.read(newBytes, 0, newBytes.length, lastSize);
+        const chunk = partialLine + newBytes.toString("utf-8");
+        const lines = chunk.split("\n");
+
+        // Last element may be a partial line (no trailing newline yet)
+        partialLine = lines.pop() ?? "";
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const entry = JSON.parse(line) as LogEntry;
+            console.log(formatEntryLine(entry));
+          } catch {
+            // skip malformed lines during active writing
+          }
         }
+        lastSize = s.size;
+      } finally {
+        await fd.close();
       }
-      lastLineCount = lines.length;
-      lastSize = s.size;
     } catch {
       // ignore read errors during active writing
     }
   });
 
-  // Keep alive until Ctrl+C
-  process.once("SIGINT", () => {
+  // Keep alive until terminated
+  const cleanup = () => {
     watcher.close();
     process.exit(0);
-  });
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
 
   await new Promise(() => {}); // block forever
 }
@@ -234,7 +247,8 @@ export async function filterSessions(options: {
   let entries = await readLogEntries(file);
 
   if (options.tool) {
-    entries = entries.filter((e) => e.tool_name === options.tool || e.method.includes(options.tool!));
+    const toolFilter = options.tool;
+    entries = entries.filter((e) => e.tool_name === toolFilter || e.method.includes(toolFilter));
   }
   if (options.errors) {
     entries = entries.filter((e) => e.error);

src/logger.ts

@@ -171,7 +171,7 @@ export async function createSessionLogger(logDir?: string, redactionOptions?: Re
   }
 
   function enqueue(line: string) {
-    if (!loggingEnabled) return;
+    if (!loggingEnabled || closed) return;
     if (logSizeCapped) return;
     if (writeQueue.length >= MAX_QUEUE_DEPTH) {
       process.stderr.write("[flight] Warning: log queue full, dropping entry\n");
@@ -203,17 +203,20 @@ export async function createSessionLogger(logDir?: string, redactionOptions?: Re
       let prevErrorMethod: string | undefined;
 
       if (direction === "client->server") {
-        // Hallucination detection: check if the most recent server response was an error
-        // and this new request is for a different tool (not a retry)
-        const lastResponse = recentResponses.length > 0
-          ? recentResponses[recentResponses.length - 1]
-          : undefined;
-        if (lastResponse?.isError && (now - lastResponse.timestamp) < HALLUCINATION_WINDOW_MS) {
-          prevErrorToolName = lastResponse.toolName;
-          prevErrorMethod = lastResponse.method;
-          const isRetry = msg.method === lastResponse.method && toolName === lastResponse.toolName;
-          if (!isRetry) {
-            hallucinationHint = true;
+        // Hallucination detection: only applies to tools/call requests following a tools/call error
+        // (not notifications, resources/list, or other non-tool methods)
+        if (msg.method === "tools/call") {
+          const lastResponse = recentResponses.length > 0
+            ? recentResponses[recentResponses.length - 1]
+            : undefined;
+          if (lastResponse?.isError && lastResponse.method === "tools/call"
+              && (now - lastResponse.timestamp) < HALLUCINATION_WINDOW_MS) {
+            prevErrorToolName = lastResponse.toolName;
+            prevErrorMethod = lastResponse.method;
+            const isRetry = toolName === lastResponse.toolName;
+            if (!isRetry) {
+              hallucinationHint = true;
+            }
           }
         }
 

src/proxy.ts

@@ -160,11 +160,19 @@ export async function startProxy(options: ProxyOptions): Promise<void> {
 
   // Handle upstream exit
   upstream.on("close", async (code) => {
-    // Flush held error responses for any pending retries so the client isn't left hanging
+    // Flush held error responses for any pending retries
     for (const heldError of pendingRetries.values()) {
       process.stdout.write(JSON.stringify(heldError) + "\n");
     }
     pendingRetries.clear();
+    // Send error responses for any requests that never got a reply
+    for (const [id] of pendingClientRequests) {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: "2.0", id,
+        error: { code: -32000, message: "Upstream process exited" },
+      }) + "\n");
+    }
+    pendingClientRequests.clear();
     await logger.close();
     process.exit(code ?? 0);
   });

test/alerts.test.ts

@@ -126,8 +126,12 @@ describe("Alert System", () => {
 
     const content = await readFile(alertPath, "utf-8");
     const lines = content.trim().split("\n").filter(Boolean);
-    const lastAlert = JSON.parse(lines[lines.length - 1]) as AlertEntry;
+    const sessionAlerts = lines
+      .map((l) => JSON.parse(l) as AlertEntry)
+      .filter((a) => a.session_id === logger.sessionId);
 
+    expect(sessionAlerts.length).toBeGreaterThanOrEqual(1);
+    const lastAlert = sessionAlerts[sessionAlerts.length - 1];
     expect(lastAlert.severity).toBe("error");
     expect(lastAlert.message).toBe("Search failed");
   });