fullcourtdefense-cli 1.26.3 → 1.26.4

package/dist/commands/daemon.js

@@ -59,6 +59,7 @@ const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const config_1 = require("../config");
 const distress_1 = require("../distress");
+const pollLoop_1 = require("../pollLoop");
 const selfTest_1 = require("../selfTest");
 const daemonForensics_1 = require("../daemonForensics");
 const securityAgents_1 = require("../securityAgents");
@@ -107,6 +108,14 @@ const RESCAN_INTERVAL_MS = envMs('FCD_DAEMON_RESCAN_MS', 5 * 60_000);
 const HEARTBEAT_INTERVAL_MS = envMs('FCD_DAEMON_HEARTBEAT_MS', 5 * 60_000);
 /** Bundle (mode / suspension / policy version) poll cadence. */
 const BUNDLE_POLL_MS = envMs('FCD_DAEMON_BUNDLE_POLL_MS', 60_000);
+/**
+ * Hard ceilings for one poll attempt (see startPollLoop). Generous multiples of
+ * the work each poll actually does — a bundle poll is a 1.5s fetch plus an 8s
+ * snapshot refresh, a heartbeat is a spool flush plus a log upload — so these
+ * only ever fire on a genuinely hung socket, never on a merely slow network.
+ */
+const BUNDLE_POLL_DEADLINE_MS = envMs('FCD_DAEMON_BUNDLE_DEADLINE_MS', 45_000);
+const HEARTBEAT_DEADLINE_MS = envMs('FCD_DAEMON_HEARTBEAT_DEADLINE_MS', 120_000);
 /** Delay before the one-time initial discovery sweep on a fresh machine. */
 const INITIAL_DISCOVER_DELAY_MS = envMs('FCD_DAEMON_INITIAL_DISCOVER_MS', 2 * 60_000);
 /** A discovery upload older than this is stale — the daemon catches up itself. */
@@ -1287,33 +1296,35 @@ async function runDaemon(args, config) {
     // The bundle poll additionally honors the server's pollIntervalMs, and the
     // next tick is scheduled only AFTER the previous poll finishes — a slow
     // gate can never pile up overlapping polls.
-    const jittered = (baseMs) => Math.max(5_000, Math.round(baseMs * (0.8 + Math.random() * 0.4)));
-    let bundleTimer;
-    const scheduleBundlePoll = () => {
-        if (stopped)
-            return;
-        bundleTimer = setTimeout(async () => {
-            try {
-                await pollBundle();
-            }
-            catch { /* poll never throws, but never stop the loop */ }
-            scheduleBundlePoll();
-        }, jittered(bundlePollBaseMs));
-    };
-    scheduleBundlePoll();
-    let heartbeatTimer;
-    const scheduleHeartbeat = () => {
-        if (stopped)
-            return;
-        heartbeatTimer = setTimeout(async () => {
-            try {
-                await heartbeat();
-            }
-            catch { /* keep the loop alive */ }
-            scheduleHeartbeat();
-        }, jittered(HEARTBEAT_INTERVAL_MS));
-    };
-    scheduleHeartbeat();
+    //
+    // Both loops run through startPollLoop, which bounds every attempt with a
+    // hard deadline. A poll that never settles (socket dead without a FIN after
+    // sleep / VPN change / proxy drop — `AbortSignal.timeout` does not always
+    // rescue that) used to kill its loop for the life of the process. When that
+    // happened to the bundle poll, remote actions — whose ONLY delivery path is
+    // this poll — silently expired unacknowledged while heartbeats kept the
+    // machine looking healthy. Abandoning the hung attempt restores delivery on
+    // the next tick and leaves a `poll_stalled` signal in the fleet.
+    const bundleLoop = (0, pollLoop_1.startPollLoop)({
+        run: pollBundle,
+        intervalMs: () => bundlePollBaseMs,
+        deadlineMs: BUNDLE_POLL_DEADLINE_MS,
+        onStalled: deadlineMs => {
+            log(`Bundle poll did not finish within ${Math.round(deadlineMs / 1000)}s — abandoned; remote actions and policy updates were delayed. Next poll continues normally.`);
+            (0, distress_1.reportDistress)('bundle', distress_1.DISTRESS.POLL_STALLED, `bundle poll exceeded ${deadlineMs}ms`);
+        },
+        onError: error => log(`Bundle poll error: ${error instanceof Error ? error.message : String(error)}`),
+    });
+    const heartbeatLoop = (0, pollLoop_1.startPollLoop)({
+        run: heartbeat,
+        intervalMs: () => HEARTBEAT_INTERVAL_MS,
+        deadlineMs: HEARTBEAT_DEADLINE_MS,
+        onStalled: deadlineMs => {
+            log(`Heartbeat did not finish within ${Math.round(deadlineMs / 1000)}s — abandoned; spooled events stay on disk for the next tick.`);
+            (0, distress_1.reportDistress)('heartbeat', distress_1.DISTRESS.POLL_STALLED, `heartbeat exceeded ${deadlineMs}ms`);
+        },
+        onError: error => log(`Heartbeat error: ${error instanceof Error ? error.message : String(error)}`),
+    });
     // PowerShell transcript retention (Windows): the Transcription policy FCD
     // enables writes a file per session forever — prune anything older than the
     // retention window once a day (plus once shortly after boot, so laptops
@@ -1337,10 +1348,8 @@ async function runDaemon(args, config) {
         stopped = true;
         log(`Received ${signal} — shutting down.`);
         clearInterval(rescanTimer);
-        if (bundleTimer)
-            clearTimeout(bundleTimer);
-        if (heartbeatTimer)
-            clearTimeout(heartbeatTimer);
+        bundleLoop.stop();
+        heartbeatLoop.stop();
         clearTimeout(transcriptPruneBootTimer);
         clearInterval(transcriptPruneTimer);
         clearTimeout(discoverCatchUpBootTimer);

package/dist/distress.d.ts

@@ -48,6 +48,12 @@ export declare const DISTRESS: {
     readonly MACHINE_KEYFILE_ACL_FAILED: "machine_keyfile_acl_failed";
     /** Fail-closed engaged: hook is BLOCKING user actions because the policy gate is persistently unreachable. */
     readonly HOOK_FAIL_CLOSED: "hook_fail_closed";
+    /**
+     * A daemon poll never settled and was abandoned at its deadline. Usually a
+     * socket that died without a FIN (sleep / VPN / proxy). Self-heals on the
+     * next tick — but while it lasted, remote actions were undeliverable.
+     */
+    readonly POLL_STALLED: "poll_stalled";
     /** Anything nobody predicted — reported via reportUnexpected(). */
     readonly UNEXPECTED: "unexpected_error";
 };

package/dist/distress.js

@@ -93,6 +93,12 @@ exports.DISTRESS = {
     MACHINE_KEYFILE_ACL_FAILED: 'machine_keyfile_acl_failed',
     /** Fail-closed engaged: hook is BLOCKING user actions because the policy gate is persistently unreachable. */
     HOOK_FAIL_CLOSED: 'hook_fail_closed',
+    /**
+     * A daemon poll never settled and was abandoned at its deadline. Usually a
+     * socket that died without a FIN (sleep / VPN / proxy). Self-heals on the
+     * next tick — but while it lasted, remote actions were undeliverable.
+     */
+    POLL_STALLED: 'poll_stalled',
     /** Anything nobody predicted — reported via reportUnexpected(). */
     UNEXPECTED: 'unexpected_error',
 };

package/dist/pollLoop.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Self-healing poll scheduler for the resident daemon.
+ *
+ * WHY THIS EXISTS (a real production incident, 2026-08-22)
+ * The daemon's loops schedule the next tick only AFTER the current attempt
+ * settles — deliberate, so a slow control plane can never stack overlapping
+ * polls on a developer's laptop. The hidden cost: an attempt that NEVER
+ * settles kills the loop for the lifetime of the process.
+ *
+ * That is not theoretical. `fetch` can hang indefinitely despite its
+ * `AbortSignal.timeout` when the underlying socket dies without a FIN —
+ * laptop sleep, VPN/Wi-Fi change, or a corporate proxy silently dropping an
+ * idle connection. On the incident machine the bundle poll hung at 15:59 and
+ * never ran again, while heartbeats, hooks, and the watchdog all kept working
+ * for three hours. The machine therefore looked perfectly healthy in the
+ * console — but the bundle poll is the ONLY delivery path for remote actions,
+ * so every admin fix (upgrade, repair protection, collect diagnostics)
+ * silently expired unacknowledged. The worst possible failure mode: a machine
+ * we cannot reach that reports itself fine.
+ *
+ * The fix is a hard per-attempt deadline. When it expires we abandon the
+ * attempt (logging + distress so the fleet SEES it) and schedule the next
+ * tick anyway. The orphaned promise gets a permanent catch so a late
+ * rejection can never surface as an unhandled rejection and take the daemon
+ * down with it.
+ *
+ * Pure and injectable (timers + clock) so the "loop survives a poll that
+ * never settles" property is unit-tested without waiting on real minutes.
+ */
+export interface PollLoopHandle {
+    stop(): void;
+    /** Attempts abandoned at the deadline — exposed for tests/diagnostics. */
+    stalledCount(): number;
+}
+export interface PollLoopInput {
+    /** One attempt. May reject, and may never settle — both are survivable. */
+    run: () => Promise<unknown>;
+    /**
+     * Base cadence, read fresh before every tick so the server can retune a
+     * whole fleet (bundle `pollIntervalMs`) without a new CLI.
+     */
+    intervalMs: () => number;
+    /**
+     * Hard ceiling for a single attempt. Keep it below the interval so an
+     * abandoned attempt cannot overlap the next one for long.
+     */
+    deadlineMs: number;
+    /** Called once per abandoned attempt (log + distress at the call site). */
+    onStalled?: (deadlineMs: number) => void;
+    /** Called when an attempt rejects. Never rethrow from here. */
+    onError?: (error: unknown) => void;
+    /** Cadence jitter fraction (0..1, default 0.2) — a proxied fleet must not poll in lockstep. */
+    jitter?: number;
+    /** Injectable timers for tests. */
+    timers?: {
+        setTimeout: (fn: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+    };
+    /** Injectable randomness for deterministic tests. */
+    random?: () => number;
+}
+/**
+ * Await `run()` but never longer than `deadlineMs`. Resolves 'settled' when the
+ * attempt finished (fulfilled or rejected) and 'abandoned' when the deadline
+ * won the race.
+ */
+export declare function runWithDeadline(input: Pick<PollLoopInput, 'run' | 'deadlineMs' | 'onError' | 'timers'>): Promise<'settled' | 'abandoned'>;
+/**
+ * Start a loop that runs `run()` forever on a jittered cadence and CANNOT be
+ * killed by an attempt that hangs or throws.
+ */
+export declare function startPollLoop(input: PollLoopInput): PollLoopHandle;

package/dist/pollLoop.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Self-healing poll scheduler for the resident daemon.
+ *
+ * WHY THIS EXISTS (a real production incident, 2026-08-22)
+ * The daemon's loops schedule the next tick only AFTER the current attempt
+ * settles — deliberate, so a slow control plane can never stack overlapping
+ * polls on a developer's laptop. The hidden cost: an attempt that NEVER
+ * settles kills the loop for the lifetime of the process.
+ *
+ * That is not theoretical. `fetch` can hang indefinitely despite its
+ * `AbortSignal.timeout` when the underlying socket dies without a FIN —
+ * laptop sleep, VPN/Wi-Fi change, or a corporate proxy silently dropping an
+ * idle connection. On the incident machine the bundle poll hung at 15:59 and
+ * never ran again, while heartbeats, hooks, and the watchdog all kept working
+ * for three hours. The machine therefore looked perfectly healthy in the
+ * console — but the bundle poll is the ONLY delivery path for remote actions,
+ * so every admin fix (upgrade, repair protection, collect diagnostics)
+ * silently expired unacknowledged. The worst possible failure mode: a machine
+ * we cannot reach that reports itself fine.
+ *
+ * The fix is a hard per-attempt deadline. When it expires we abandon the
+ * attempt (logging + distress so the fleet SEES it) and schedule the next
+ * tick anyway. The orphaned promise gets a permanent catch so a late
+ * rejection can never surface as an unhandled rejection and take the daemon
+ * down with it.
+ *
+ * Pure and injectable (timers + clock) so the "loop survives a poll that
+ * never settles" property is unit-tested without waiting on real minutes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithDeadline = runWithDeadline;
+exports.startPollLoop = startPollLoop;
+const MIN_DELAY_MS = 5_000;
+/**
+ * Await `run()` but never longer than `deadlineMs`. Resolves 'settled' when the
+ * attempt finished (fulfilled or rejected) and 'abandoned' when the deadline
+ * won the race.
+ */
+async function runWithDeadline(input) {
+    const timers = input.timers || { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: handle => clearTimeout(handle) };
+    // The catch is attached NOW and stays attached: if this attempt is abandoned
+    // and rejects minutes later, the rejection is already handled.
+    let attemptSettled = false;
+    const attempt = (async () => {
+        try {
+            await input.run();
+        }
+        catch (error) {
+            try {
+                input.onError?.(error);
+            }
+            catch { /* a reporter must never break the loop */ }
+        }
+        finally {
+            attemptSettled = true;
+        }
+    })();
+    let deadlineHandle;
+    const deadline = new Promise(resolve => {
+        deadlineHandle = timers.setTimeout(() => resolve(), input.deadlineMs);
+    });
+    await Promise.race([attempt, deadline]);
+    timers.clearTimeout(deadlineHandle);
+    return attemptSettled ? 'settled' : 'abandoned';
+}
+/**
+ * Start a loop that runs `run()` forever on a jittered cadence and CANNOT be
+ * killed by an attempt that hangs or throws.
+ */
+function startPollLoop(input) {
+    const timers = input.timers || { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: handle => clearTimeout(handle) };
+    const random = input.random || Math.random;
+    const jitter = Math.min(Math.max(input.jitter ?? 0.2, 0), 0.9);
+    let stopped = false;
+    let stalled = 0;
+    let tickHandle;
+    const nextDelay = () => {
+        const base = input.intervalMs();
+        const safeBase = Number.isFinite(base) && base > 0 ? base : MIN_DELAY_MS;
+        const factor = 1 - jitter + random() * jitter * 2;
+        return Math.max(MIN_DELAY_MS, Math.round(safeBase * factor));
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        tickHandle = timers.setTimeout(async () => {
+            if (stopped)
+                return;
+            const outcome = await runWithDeadline({
+                run: input.run,
+                deadlineMs: input.deadlineMs,
+                onError: input.onError,
+                timers,
+            });
+            if (outcome === 'abandoned') {
+                stalled += 1;
+                try {
+                    input.onStalled?.(input.deadlineMs);
+                }
+                catch { /* never break the loop */ }
+            }
+            schedule();
+        }, nextDelay());
+    };
+    schedule();
+    return {
+        stop() {
+            stopped = true;
+            timers.clearTimeout(tickHandle);
+        },
+        stalledCount() {
+            return stalled;
+        },
+    };
+}

package/dist/version.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.26.3",
+  "version": "1.26.4",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {
@@ -53,6 +53,7 @@
     "test:scan-root-compaction": "npm run build && node scripts/test-scan-root-compaction.js",
     "test:dpapi-config": "npm run build && node scripts/test-dpapi-config.js",
     "test:distress-ledger": "npm run build && node scripts/test-distress-ledger.js",
+    "test:poll-loop": "npm run build && node scripts/test-poll-loop-resilience.js",
     "test:deep-selftest": "npm run build && node scripts/test-deep-selftest.js",
     "test:update-loop": "npm run build && node scripts/test-update-loop-detection.js",
     "test:bricked-rescue": "npm run build && node scripts/test-bricked-machine-rescue.js",