fullcourtdefense-cli 1.26.2 → 1.26.3

package/dist/commands/hook.js

@@ -684,6 +684,13 @@ async function evaluateHookRequest(args, stdinRaw, config) {
  * through respond() inside and never reach this catch.
  */
 async function hookCommand(args, config) {
+    // Start of the developer's wait. Taken once here and carried (in-memory) so
+    // every event this hook spools reports real latency, and the daemon can
+    // report the FULL wait rather than just its own slice. No probe, no timer.
+    const startedAt = Date.now();
+    return (0, telemetry_1.markVerdictTiming)({ startedAt, path: 'local' }, () => hookCommandOuter(args, config, startedAt));
+}
+async function hookCommandOuter(args, config, startedAt) {
     try {
         let raw = '';
         let stdinErr = '';
@@ -700,7 +707,7 @@ async function hookCommand(args, config) {
         // the full local evaluation below, so the daemon can never make a hook
         // slower than it was before this feature. FCD_VERDICT_IPC=off opts out.
         if (process.env.FCD_VERDICT_IPC !== 'off') {
-            const ipc = await (0, verdictIpc_1.requestDaemonVerdict)(args, raw);
+            const ipc = await (0, verdictIpc_1.requestDaemonVerdict)(args, raw, undefined, startedAt);
             if (ipc.outcome === 'verdict') {
                 dbg({ phase: 'ipc_verdict', event: args.event, exitCode: ipc.exitCode });
                 if (ipc.stderr) {
@@ -744,6 +751,12 @@ async function hookCommand(args, config) {
  */
 function failOpenOutcome(event, message) {
     const toolName = event || 'unknown';
+    // Label the spooled event below as a crash-allow: a rising fail_open rate is
+    // the fleet's earliest signal that the guard itself is broken on a machine.
+    try {
+        (0, telemetry_1.setVerdictPath)('fail_open');
+    }
+    catch { /* never throw */ }
     let suspended = false;
     try {
         suspended = (0, runtimeConfig_1.isSuspendedByCache)();

package/dist/commands/mcpGateway.js

@@ -878,6 +878,13 @@ class McpGatewayServer {
         (0, telemetry_1.triggerFlush)(decision === 'block');
     }
     async handleToolCall(params) {
+        // Passive perf stamp for every event this call spools: how long the agent
+        // waited for OUR decision (path 'gateway'). Pure in-memory context — no
+        // probe, no I/O; the clock is restarted after the downstream call so the
+        // tool's own runtime is never billed to FullCourtDefense.
+        return (0, telemetry_1.markVerdictTiming)({ startedAt: Date.now(), path: 'gateway' }, () => this.handleToolCallInner(params));
+    }
+    async handleToolCallInner(params) {
         await this.ensureDownstream();
         const toolName = String(params.name || '');
         if (!toolName)
@@ -1248,6 +1255,9 @@ class McpGatewayServer {
             let rawResult = await this.downstream.callTool(toolName, toolArgs);
             downstreamRan = true;
             downstreamResult = rawResult;
+            // Response-side events must measure our scanning overhead, not the
+            // tool's execution time (see restartVerdictTiming).
+            (0, telemetry_1.restartVerdictTiming)();
             const responseOutcome = (0, deterministicGuard_1.resolveDeterministicTextResponse)(contentToText(rawResult), (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
             for (const warning of responseOutcome.warnings) {
                 this.spoolLocalFinding(warning, toolName, operation, 'warn');

package/dist/telemetry.d.ts

@@ -16,8 +16,44 @@ export interface SpoolEvent {
     policyHash?: string;
     /** True when this decision was enforced locally while the backend was unreachable. */
     offlineEnforced?: boolean;
+    /**
+     * Wall time the developer actually waited for this verdict, in ms — measured
+     * from the moment the hook process started to the moment the decision was
+     * spooled. Passive: computed from timestamps already taken on the hot path
+     * (see markVerdictTiming), never an extra probe, timer, or process.
+     */
+    latencyMs?: number;
+    /** Which path produced the verdict (see VerdictPath). */
+    verdictPath?: VerdictPath;
     occurredAt: string;
 }
+/**
+ * How a verdict was produced — the difference between a healthy machine and a
+ * degraded one:
+ *  - `ipc`        resident daemon answered the thin client (the fast path)
+ *  - `local`      full local evaluation in the hook process (daemon down/busy)
+ *  - `gateway`    resident MCP gateway decided in-process (its own fast path)
+ *  - `fail_open`  the hook crashed and allowed by contract
+ */
+export type VerdictPath = 'ipc' | 'local' | 'fail_open' | 'gateway';
+interface VerdictTiming {
+    startedAt: number;
+    path: VerdictPath;
+}
+/** Run one hook evaluation with timing attached to everything it spools. */
+export declare function markVerdictTiming<T>(timing: VerdictTiming, fn: () => T): T;
+/**
+ * Re-label the current evaluation (e.g. it ended in the fail-open handler).
+ * Keeps the original start time so latency still covers the full wait.
+ */
+export declare function setVerdictPath(path: VerdictPath): void;
+/**
+ * Restart the current evaluation's clock. Used by the MCP gateway right after
+ * the downstream tool returns: everything spooled from then on (response
+ * scanning, masking, bookkeeping) must report OUR overhead, not the tool's own
+ * runtime — a 30s build tool is not a 30s FullCourtDefense stall.
+ */
+export declare function restartVerdictTiming(): void;
 /** Append one decision to the spool. Never throws (telemetry must not break the hook). */
 export declare function spoolEvent(event: Omit<SpoolEvent, 'eventId' | 'occurredAt' | 'type'> & Partial<Pick<SpoolEvent, 'occurredAt' | 'type'>>): void;
 export interface FlushInput {
@@ -76,3 +112,4 @@ export declare function flushSpool(input: FlushInput): Promise<{
  * (used for critical blocks). The child reads creds from ~/.fullcourtdefense.yml.
  */
 export declare function triggerFlush(immediate?: boolean): void;
+export {};

package/dist/telemetry.js

@@ -33,9 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.markVerdictTiming = markVerdictTiming;
+exports.setVerdictPath = setVerdictPath;
+exports.restartVerdictTiming = restartVerdictTiming;
 exports.spoolEvent = spoolEvent;
 exports.flushSpool = flushSpool;
 exports.triggerFlush = triggerFlush;
+const async_hooks_1 = require("async_hooks");
 const child_process_1 = require("child_process");
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
@@ -63,9 +67,50 @@ const MAX_BATCH = 200;
 const MAX_SPOOL_EVENTS = 2_000;
 /** Cheap pre-check: skip the trim parse entirely until the file is plausibly over cap. */
 const SPOOL_TRIM_BYTES = 2 * 1024 * 1024;
+/**
+ * Per-evaluation timing context.
+ *
+ * AsyncLocalStorage (not a module variable) because the daemon evaluates
+ * several hook requests CONCURRENTLY in one process: a shared variable would
+ * attribute one hook's start time to another hook's event. The store follows
+ * each request's own async chain, so every spooled event gets its own numbers.
+ *
+ * Cost on the hot path: one object allocation per hook evaluation. No I/O, no
+ * timer, no network — the fields ride along on the verdict event the CLI was
+ * already spooling.
+ */
+const verdictTiming = new async_hooks_1.AsyncLocalStorage();
+/** Run one hook evaluation with timing attached to everything it spools. */
+function markVerdictTiming(timing, fn) {
+    return verdictTiming.run(timing, fn);
+}
+/**
+ * Re-label the current evaluation (e.g. it ended in the fail-open handler).
+ * Keeps the original start time so latency still covers the full wait.
+ */
+function setVerdictPath(path) {
+    const store = verdictTiming.getStore();
+    if (store)
+        store.path = path;
+}
+/**
+ * Restart the current evaluation's clock. Used by the MCP gateway right after
+ * the downstream tool returns: everything spooled from then on (response
+ * scanning, masking, bookkeeping) must report OUR overhead, not the tool's own
+ * runtime — a 30s build tool is not a 30s FullCourtDefense stall.
+ */
+function restartVerdictTiming() {
+    const store = verdictTiming.getStore();
+    if (store)
+        store.startedAt = Date.now();
+}
 /** Append one decision to the spool. Never throws (telemetry must not break the hook). */
 function spoolEvent(event) {
     try {
+        // Passive perf stamp: pure arithmetic on a timestamp the hot path already
+        // took. Absent when a caller spools outside a hook evaluation (guards,
+        // onboard) — the backend treats missing fields as "no sample".
+        const timing = verdictTiming.getStore();
         const full = {
             eventId: crypto.randomUUID(),
             occurredAt: event.occurredAt || new Date().toISOString(),
@@ -84,6 +129,8 @@ function spoolEvent(event) {
             explanation: event.explanation,
             policyHash: event.policyHash,
             offlineEnforced: event.offlineEnforced,
+            latencyMs: timing ? Math.max(0, Date.now() - timing.startedAt) : undefined,
+            verdictPath: timing?.path,
         };
         fs.appendFileSync(SPOOL_PATH, JSON.stringify(full) + '\n', { encoding: 'utf-8', mode: 0o600 });
         enforceSpoolCap();

package/dist/verdictIpc.d.ts

@@ -33,6 +33,14 @@ export interface VerdictRequest {
     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;
 }
 export interface VerdictResponse {
     v: number;
@@ -68,7 +76,7 @@ export declare function verdictPipePath(): string;
  * 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): Promise<VerdictClientResult>;
+export declare function requestDaemonVerdict(args: Record<string, string | undefined>, stdin: string, responseTimeoutMs?: number, clientStartedAt?: number): Promise<VerdictClientResult>;
 export interface VerdictServerHandle {
     close(): void;
 }

package/dist/verdictIpc.js

@@ -43,6 +43,7 @@ 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");
 /**
  * Daemon verdict IPC — the resident-agent pattern real endpoint products use
  * (one resident process; per-event interceptors are thin clients that ask it
@@ -118,15 +119,15 @@ const RESPONSE_TIMEOUT_MS = 2_500;
  * 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) {
-    const first = await attemptDaemonVerdict(args, stdin, responseTimeoutMs);
+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);
+        return attemptDaemonVerdict(args, stdin, responseTimeoutMs, clientStartedAt);
     }
     return first;
 }
-function attemptDaemonVerdict(args, stdin, responseTimeoutMs) {
+function attemptDaemonVerdict(args, stdin, responseTimeoutMs, clientStartedAt) {
     return new Promise((resolve) => {
         const token = readToken();
         if (!token) {
@@ -153,7 +154,7 @@ function attemptDaemonVerdict(args, stdin, responseTimeoutMs) {
         socket.on('error', (err) => fail(err.message));
         socket.on('connect', () => {
             clearTimeout(connectTimer);
-            const request = { v: exports.VERDICT_IPC_PROTOCOL_VERSION, token, args, stdin };
+            const request = { v: exports.VERDICT_IPC_PROTOCOL_VERSION, token, args, stdin, t0: clientStartedAt };
             try {
                 socket.write(JSON.stringify(request) + '\n');
             }
@@ -258,7 +259,11 @@ function startVerdictServer(evaluate, log) {
                     return;
                 }
                 try {
-                    const result = await evaluate(request.args || {}, String(request.stdin ?? ''));
+                    // Attach the requesting hook's own start time to whatever this
+                    // evaluation spools, so fleet telemetry reports the wall time the
+                    // 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 });
                 }
                 catch (err) {

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.26.2"
+  "version": "1.26.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.26.2",
+  "version": "1.26.3",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {