fullcourtdefense-cli 1.26.4 → 1.26.6

package/dist/verdictIpc.js

@@ -33,163 +33,33 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERDICT_IPC_PROTOCOL_VERSION = void 0;
-exports.verdictTokenFile = verdictTokenFile;
-exports.verdictPipePath = verdictPipePath;
-exports.requestDaemonVerdict = requestDaemonVerdict;
+exports.verdictTokenFile = exports.verdictPipePath = exports.requestDaemonVerdict = exports.VERDICT_IPC_PROTOCOL_VERSION = void 0;
 exports.startVerdictServer = startVerdictServer;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
 const telemetry_1 = require("./telemetry");
+const verdictIpcClient_1 = require("./verdictIpcClient");
 /**
- * Daemon verdict IPC — the resident-agent pattern real endpoint products use
- * (one resident process; per-event interceptors are thin clients that ask it
- * over local IPC), applied to the IDE hook path.
+ * Daemon verdict IPC — SERVER side (runs inside the resident daemon).
  *
- * Why: every IDE hook event spawns a fresh Node process. The spawn itself is
- * unavoidable (the IDE invokes a command), but everything AFTER it — config
- * parse, credential resolution, bundle read, snapshot load, policy evaluation,
- * possible network — used to repeat per event. The daemon is already resident
- * with all of that warm in memory, so the spawned hook becomes a THIN CLIENT:
- * it forwards `{args, stdin}` over a named pipe (Windows) / Unix domain socket
- * and prints the verdict the daemon computed in single-digit milliseconds.
+ * The resident-agent pattern real endpoint products use: one resident process;
+ * per-event interceptors are thin clients that ask it over local IPC. The
+ * daemon is already resident with config, credentials, bundle, and snapshot
+ * warm in memory, so a spawned hook becomes a THIN CLIENT that forwards
+ * `{args, stdin}` over a named pipe (Windows) / Unix domain socket and prints
+ * the verdict the daemon computed in single-digit milliseconds.
  *
- * Fallback contract: ANY failure — pipe missing, handshake error, slow or
- * busy daemon (response cap ~2.5s) — makes the hook silently fall back to its
- * full local evaluation, identical to before this feature existed. Local
- * re-evaluation after a partial daemon evaluation is safe: verdict
- * computation is read-mostly (worst case a duplicate telemetry event), and
- * enforcement is never weakened by evaluating twice. The cap guarantees a
- * busy daemon (blocking schtasks call, GC pause) can never make a hook
- * SLOWER than the pre-IPC status quo.
- *
- * Security: named pipes are reachable by other local users by default, so the
- * server requires a per-boot random token stored under ~/.fullcourtdefense
- * (user-profile ACL). A client that cannot read the token cannot get verdicts.
- * The protocol is line-delimited JSON — one request line, one response line.
+ * The client half lives in `verdictIpcClient.ts` — a Node-builtins-only leaf
+ * shared with the slim hook entry (`hookSlim.ts`), whose module graph must
+ * stay tiny because it loads on every IDE hook event. This file re-exports
+ * the client API so existing imports keep working.
  */
-exports.VERDICT_IPC_PROTOCOL_VERSION = 1;
-function stateDir() {
-    return path.join(os.homedir(), '.fullcourtdefense');
-}
-function verdictTokenFile() {
-    return path.join(stateDir(), 'verdict-ipc-token');
-}
-function verdictPipePath() {
-    // Test isolation / unusual environments: explicit endpoint override.
-    const override = process.env.FCD_VERDICT_PIPE;
-    if (override)
-        return override;
-    if (process.platform === 'win32') {
-        // Per-user pipe name: two users on one machine each get their own daemon.
-        const user = (os.userInfo().username || 'user').replace(/[^a-zA-Z0-9_-]/g, '_');
-        return `\\\\.\\pipe\\fullcourtdefense-verdict-${user}`;
-    }
-    return path.join(stateDir(), 'verdict.sock');
-}
-function readToken() {
-    try {
-        const token = fs.readFileSync(verdictTokenFile(), 'utf8').trim();
-        return token.length >= 16 ? token : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-// ---------------------------------------------------------------------------
-// Client (thin hook side)
-// ---------------------------------------------------------------------------
-const CONNECT_TIMEOUT_MS = 250;
-const RESPONSE_TIMEOUT_MS = 2_500;
-/**
- * Ask the resident daemon for a verdict. Bounded hard: connect budget ~250ms
- * (a missing pipe fails in <1ms with ENOENT — the common daemon-down case
- * costs nothing), response capped at ~2.5s. A verdict that legitimately needs
- * longer than that (synchronous approval wait, no-cache gate call) is exactly
- * the case where the IPC saves nothing — the local evaluation path handles it
- * with its own bounded waits. Never throws.
- *
- * Burst behavior: an agent firing many commands at once (docker compose +
- * exec + build in flight together) means many hooks connecting to the ONE
- * pipe simultaneously — some connects lose the race (EBUSY / connect
- * timeout) while the daemon is demonstrably alive (token present). Those
- * get ONE short jittered retry; hard failures (ENOENT stale pipe, refused)
- * still fall back to local evaluation instantly.
- */
-async function requestDaemonVerdict(args, stdin, responseTimeoutMs = RESPONSE_TIMEOUT_MS, clientStartedAt) {
-    const first = await attemptDaemonVerdict(args, stdin, responseTimeoutMs, clientStartedAt);
-    if (first.outcome === 'unavailable' && /EBUSY|busy|EAGAIN|connect timeout/i.test(first.detail || '')) {
-        await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 30)));
-        return attemptDaemonVerdict(args, stdin, responseTimeoutMs, clientStartedAt);
-    }
-    return first;
-}
-function attemptDaemonVerdict(args, stdin, responseTimeoutMs, clientStartedAt) {
-    return new Promise((resolve) => {
-        const token = readToken();
-        if (!token) {
-            resolve({ outcome: 'unavailable', detail: 'no ipc token (daemon not running or old version)' });
-            return;
-        }
-        let settled = false;
-        const finish = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(connectTimer);
-            clearTimeout(responseTimer);
-            try {
-                socket.destroy();
-            }
-            catch { /* already gone */ }
-            resolve(result);
-        };
-        const fail = (detail) => finish({ outcome: 'unavailable', detail });
-        const socket = net.connect({ path: verdictPipePath() });
-        const connectTimer = setTimeout(() => fail('connect timeout'), CONNECT_TIMEOUT_MS);
-        const responseTimer = setTimeout(() => fail('response timeout'), responseTimeoutMs);
-        socket.on('error', (err) => fail(err.message));
-        socket.on('connect', () => {
-            clearTimeout(connectTimer);
-            const request = { v: exports.VERDICT_IPC_PROTOCOL_VERSION, token, args, stdin, t0: clientStartedAt };
-            try {
-                socket.write(JSON.stringify(request) + '\n');
-            }
-            catch (err) {
-                fail(err instanceof Error ? err.message : String(err));
-            }
-        });
-        let buffer = '';
-        socket.on('data', (chunk) => {
-            buffer += chunk.toString('utf8');
-            const nl = buffer.indexOf('\n');
-            if (nl === -1)
-                return;
-            try {
-                const resp = JSON.parse(buffer.slice(0, nl));
-                if (resp.error || typeof resp.stdout !== 'string') {
-                    // The daemon declined (protocol mismatch, internal error). Nothing
-                    // was decided — treat as unavailable so the hook evaluates locally.
-                    finish({ outcome: 'unavailable', detail: resp.error || 'malformed response' });
-                    return;
-                }
-                finish({
-                    outcome: 'verdict',
-                    stdout: resp.stdout,
-                    stderr: resp.stderr || '',
-                    exitCode: typeof resp.exitCode === 'number' ? resp.exitCode : 0,
-                });
-            }
-            catch (err) {
-                fail(err instanceof Error ? err.message : String(err));
-            }
-        });
-        socket.on('close', () => fail('connection closed'));
-    });
-}
+var verdictIpcClient_2 = require("./verdictIpcClient");
+Object.defineProperty(exports, "VERDICT_IPC_PROTOCOL_VERSION", { enumerable: true, get: function () { return verdictIpcClient_2.VERDICT_IPC_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "requestDaemonVerdict", { enumerable: true, get: function () { return verdictIpcClient_2.requestDaemonVerdict; } });
+Object.defineProperty(exports, "verdictPipePath", { enumerable: true, get: function () { return verdictIpcClient_2.verdictPipePath; } });
+Object.defineProperty(exports, "verdictTokenFile", { enumerable: true, get: function () { return verdictIpcClient_2.verdictTokenFile; } });
 /**
  * Start the verdict server inside the daemon. Returns undefined when the
  * endpoint cannot be created (another daemon holds the pipe, filesystem
@@ -204,13 +74,13 @@ function startVerdictServer(evaluate, log) {
     // path until the next daemon restart.
     const removeTokenIfOurs = () => {
         try {
-            if (fs.readFileSync(verdictTokenFile(), 'utf8') === token) {
-                fs.unlinkSync(verdictTokenFile());
+            if (fs.readFileSync((0, verdictIpcClient_1.verdictTokenFile)(), 'utf8') === token) {
+                fs.unlinkSync((0, verdictIpcClient_1.verdictTokenFile)());
             }
         }
         catch { /* absent or unreadable — nothing of ours to clean */ }
     };
-    const pipePath = verdictPipePath();
+    const pipePath = (0, verdictIpcClient_1.verdictPipePath)();
     if (process.platform !== 'win32') {
         // A stale socket file from a crashed daemon blocks listen() with EADDRINUSE.
         try {
@@ -244,18 +114,24 @@ function startVerdictServer(evaluate, log) {
                     request = JSON.parse(line);
                 }
                 catch {
-                    reply({ v: exports.VERDICT_IPC_PROTOCOL_VERSION, error: 'malformed request' });
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, error: 'malformed request' });
                     return;
                 }
-                if (request.v !== exports.VERDICT_IPC_PROTOCOL_VERSION) {
-                    reply({ v: exports.VERDICT_IPC_PROTOCOL_VERSION, error: `unsupported protocol version ${request.v}` });
+                if (request.v !== verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION) {
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, error: `unsupported protocol version ${request.v}` });
                     return;
                 }
                 // Timing-safe token check — the pipe is reachable by other local users.
                 const expected = Buffer.from(token);
                 const got = Buffer.from(String(request.token || ''));
                 if (got.length !== expected.length || !crypto.timingSafeEqual(expected, got)) {
-                    reply({ v: exports.VERDICT_IPC_PROTOCOL_VERSION, error: 'unauthorized' });
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, error: 'unauthorized' });
+                    return;
+                }
+                // Liveness ping (watchdog hung-daemon check / startup pid-reuse
+                // check): answer immediately, never evaluate.
+                if (request.ping === true) {
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, pong: true });
                     return;
                 }
                 try {
@@ -264,52 +140,92 @@ function startVerdictServer(evaluate, log) {
                     // developer waited. Per-request (AsyncLocalStorage), so concurrent
                     // hooks in this one daemon never borrow each other's timings.
                     const result = await (0, telemetry_1.markVerdictTiming)({ startedAt: typeof request.t0 === 'number' ? request.t0 : Date.now(), path: 'ipc' }, () => evaluate(request.args || {}, String(request.stdin ?? '')));
-                    reply({ v: exports.VERDICT_IPC_PROTOCOL_VERSION, ...result });
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, ...result });
                 }
                 catch (err) {
                     // Evaluator bug — tell the client to fall back locally (which will
                     // itself fail open if the same bug reproduces there).
-                    reply({ v: exports.VERDICT_IPC_PROTOCOL_VERSION, error: err instanceof Error ? err.message : String(err) });
+                    reply({ v: verdictIpcClient_1.VERDICT_IPC_PROTOCOL_VERSION, error: err instanceof Error ? err.message : String(err) });
                 }
             })();
         });
     });
-    server.on('error', (err) => {
-        // EADDRINUSE here means another daemon already serves verdicts — leave
-        // its token untouched. removeTokenIfOurs is a no-op unless we had already
-        // published our own token (listen succeeded earlier).
-        log(`Verdict IPC: server error (${err.message}) — hooks will evaluate locally.`);
-        removeTokenIfOurs();
-    });
-    try {
-        server.listen(pipePath, () => {
-            if (process.platform !== 'win32') {
-                try {
-                    fs.chmodSync(pipePath, 0o600);
-                }
-                catch { /* best-effort */ }
+    // EADDRINUSE recovery: a wedged predecessor (or a stale unix socket) can
+    // hold the endpoint at boot. Giving up permanently downgraded every hook on
+    // the machine to the slow local path for the daemon's whole life. Instead,
+    // retry on a timer — the kernel frees a Windows named pipe the moment its
+    // owner dies (e.g. the watchdog recycles it), and the retry takes over.
+    const LISTEN_RETRY_MS = Math.max(100, Number(process.env.FCD_IPC_LISTEN_RETRY_MS) || 60_000);
+    let closedByUs = false;
+    let retryTimer;
+    let retries = 0;
+    const onListening = () => {
+        if (process.platform !== 'win32') {
+            try {
+                fs.chmodSync(pipePath, 0o600);
             }
-            // Publish the token only now that the pipe is actually owned by us.
+            catch { /* best-effort */ }
+        }
+        if (retries > 0)
+            log(`Verdict IPC: endpoint freed after ${retries} retr${retries === 1 ? 'y' : 'ies'} — taking over.`);
+        retries = 0;
+        // Publish the token only now that the pipe is actually owned by us.
+        try {
+            fs.mkdirSync((0, verdictIpcClient_1.verdictStateDir)(), { recursive: true });
+            fs.writeFileSync((0, verdictIpcClient_1.verdictTokenFile)(), token, { encoding: 'utf8', mode: 0o600 });
+            log(`Verdict IPC: serving hook verdicts on ${pipePath} (thin-client hooks, ms verdicts).`);
+        }
+        catch (err) {
+            log(`Verdict IPC: could not write token file (${err instanceof Error ? err.message : String(err)}) — hooks will evaluate locally.`);
             try {
-                fs.mkdirSync(stateDir(), { recursive: true });
-                fs.writeFileSync(verdictTokenFile(), token, { encoding: 'utf8', mode: 0o600 });
-                log(`Verdict IPC: serving hook verdicts on ${pipePath} (thin-client hooks, ms verdicts).`);
+                server.close();
             }
-            catch (err) {
-                log(`Verdict IPC: could not write token file (${err instanceof Error ? err.message : String(err)}) — hooks will evaluate locally.`);
-                try {
-                    server.close();
-                }
-                catch { /* best-effort */ }
+            catch { /* best-effort */ }
+        }
+    };
+    const tryListen = () => {
+        try {
+            server.listen(pipePath, onListening);
+        }
+        catch (err) {
+            log(`Verdict IPC: listen failed (${err instanceof Error ? err.message : String(err)}) — hooks will evaluate locally.`);
+        }
+    };
+    server.on('error', (err) => {
+        // removeTokenIfOurs is a no-op unless we had already published our own
+        // token (listen succeeded earlier) — a live daemon's token is untouched.
+        removeTokenIfOurs();
+        const code = err.code;
+        if (!closedByUs && code === 'EADDRINUSE') {
+            if (retries === 0) {
+                log(`Verdict IPC: endpoint busy (${err.message}) — retrying every ${Math.round(LISTEN_RETRY_MS / 1000)}s until it frees; hooks evaluate locally meanwhile.`);
             }
-        });
-    }
-    catch (err) {
-        log(`Verdict IPC: listen failed (${err instanceof Error ? err.message : String(err)}) — hooks will evaluate locally.`);
-        return undefined;
-    }
+            retries += 1;
+            retryTimer = setTimeout(() => {
+                if (closedByUs)
+                    return;
+                if (process.platform !== 'win32') {
+                    // A crashed owner leaves the socket FILE behind; unlink so the
+                    // retry can bind. The pid lock guarantees no healthy daemon owns it.
+                    try {
+                        fs.unlinkSync(pipePath);
+                    }
+                    catch { /* not there — fine */ }
+                }
+                tryListen();
+            }, LISTEN_RETRY_MS);
+            if (typeof retryTimer.unref === 'function')
+                retryTimer.unref();
+            return;
+        }
+        log(`Verdict IPC: server error (${err.message}) — hooks will evaluate locally.`);
+    });
+    tryListen();
     return {
         close() {
+            closedByUs = true;
+            if (retryTimer)
+                clearTimeout(retryTimer);
             // Remove the token FIRST so new hook processes stop trying the pipe —
             // but only if it is still ours (a newer daemon may have taken over).
             removeTokenIfOurs();
@@ -319,7 +235,7 @@ function startVerdictServer(evaluate, log) {
             catch { /* best-effort */ }
             if (process.platform !== 'win32') {
                 try {
-                    fs.unlinkSync(verdictPipePath());
+                    fs.unlinkSync((0, verdictIpcClient_1.verdictPipePath)());
                 }
                 catch { /* best-effort */ }
             }

package/dist/verdictIpcClient.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Verdict IPC — CLIENT side (thin hook -> resident daemon).
+ *
+ * Split from the server half (`verdictIpc.ts`) on purpose: the client is on
+ * the slim hook entry's module graph, loaded on EVERY IDE hook event, so it
+ * may import Node built-ins ONLY. The server half runs inside the resident
+ * daemon where module weight is irrelevant. `scripts/test-slim-hook.js`
+ * enforces the graph budget.
+ *
+ * Fallback contract: ANY failure — pipe missing, handshake error, slow or
+ * busy daemon (response cap ~2.5s) — makes the hook silently fall back to its
+ * full local evaluation, identical to before this feature existed. Local
+ * re-evaluation after a partial daemon evaluation is safe: verdict
+ * computation is read-mostly (worst case a duplicate telemetry event), and
+ * enforcement is never weakened by evaluating twice. The cap guarantees a
+ * busy daemon (blocking schtasks call, GC pause) can never make a hook
+ * SLOWER than the pre-IPC status quo.
+ *
+ * Security: named pipes are reachable by other local users by default, so the
+ * server requires a per-boot random token stored under ~/.fullcourtdefense
+ * (user-profile ACL). A client that cannot read the token cannot get verdicts.
+ * The protocol is line-delimited JSON — one request line, one response line.
+ */
+export declare const VERDICT_IPC_PROTOCOL_VERSION = 1;
+export interface VerdictRequest {
+    v: number;
+    token: string;
+    /** HookArgs as parsed by the CLI entry (all-string values). */
+    args: Record<string, string | undefined>;
+    /** Raw stdin payload exactly as the IDE piped it (BOM already stripped). */
+    stdin: string;
+    /**
+     * Client's `Date.now()` at hook start, so the daemon-written telemetry event
+     * carries the wall time the DEVELOPER waited (process spawn + pipe + verdict),
+     * not just the daemon's own evaluation slice. Optional on purpose: during a
+     * staged rollout an old client omits it (daemon falls back to its own clock)
+     * and an old daemon ignores it — same-machine clock, so no skew.
+     */
+    t0?: number;
+    /**
+     * Liveness ping (watchdog / startup pid-reuse check): the server replies
+     * `{ pong: true }` without evaluating anything. Watchdog and daemon always
+     * ship in the same build (one install, one scheduled task target), so no
+     * cross-version compatibility concern.
+     */
+    ping?: boolean;
+}
+export interface VerdictResponse {
+    v: number;
+    /** Present on evaluation success. */
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    /** Present when the daemon could not evaluate — client falls back locally. */
+    error?: string;
+    /** Reply to a liveness ping. */
+    pong?: boolean;
+}
+/** Result of a client attempt. Anything but 'verdict' → evaluate locally. */
+export interface VerdictClientResult {
+    outcome: 'verdict' | 'unavailable';
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    detail?: string;
+}
+export declare function verdictStateDir(): string;
+export declare function verdictTokenFile(): string;
+export declare function verdictPipePath(): string;
+/**
+ * Ask the resident daemon for a verdict. Bounded hard: connect budget ~250ms
+ * (a missing pipe fails in <1ms with ENOENT — the common daemon-down case
+ * costs nothing), response capped at ~2.5s. A verdict that legitimately needs
+ * longer than that (synchronous approval wait, no-cache gate call) is exactly
+ * the case where the IPC saves nothing — the local evaluation path handles it
+ * with its own bounded waits. Never throws.
+ *
+ * Burst behavior: an agent firing many commands at once (docker compose +
+ * exec + build in flight together) means many hooks connecting to the ONE
+ * pipe simultaneously — some connects lose the race (EBUSY / connect
+ * timeout) while the daemon is demonstrably alive (token present). Those
+ * get ONE short jittered retry; hard failures (ENOENT stale pipe, refused)
+ * still fall back to local evaluation instantly.
+ */
+export declare function requestDaemonVerdict(args: Record<string, string | undefined>, stdin: string, responseTimeoutMs?: number, clientStartedAt?: number): Promise<VerdictClientResult>;
+/**
+ * Liveness probe result for the verdict endpoint:
+ *  - 'responsive'   — something answered on the pipe (any parseable reply,
+ *                     including 'unauthorized': the server is alive).
+ *  - 'unresponsive' — the endpoint EXISTS (connect succeeded, or the pipe is
+ *                     busy) but nothing answered within the budget. On
+ *                     Windows a named pipe is a kernel object freed when its
+ *                     owner dies, so an existing-but-silent endpoint means a
+ *                     live-but-wedged owner.
+ *  - 'no-endpoint'  — nothing is serving the pipe/socket at all.
+ */
+export type VerdictServerProbe = 'responsive' | 'unresponsive' | 'no-endpoint';
+/**
+ * Probe the verdict server without evaluating anything. Used by the watchdog
+ * (hung-daemon detection) and by daemon startup (pid-reuse detection). Never
+ * throws; bounded by `timeoutMs`.
+ */
+export declare function probeVerdictServer(timeoutMs?: number): Promise<VerdictServerProbe>;