fullcourtdefense-cli 1.26.3 → 1.26.5

package/dist/hookIo.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_DEBUG_VERBOSE = exports.HOOK_DEBUG_LOG = void 0;
+exports.dbg = dbg;
+exports.readStdin = readStdin;
+exports.mapHookFlags = mapHookFlags;
+exports.parseHookFlags = parseHookFlags;
+exports.slimHookEntryPath = slimHookEntryPath;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Hook I/O leaf — the pieces of the hook runtime that BOTH entries share:
+ *
+ *   - `dist/hookSlim.js` (the slim hook entry installed into IDE hook configs)
+ *   - `dist/index.js hook` (the full CLI's hook command, and the daemon's
+ *     in-process evaluator)
+ *
+ * COLD-START CONTRACT: this module is on the slim entry's module graph, which
+ * is loaded on EVERY IDE hook event. It may import Node built-ins ONLY —
+ * every additional module here is bytes the customer's EDR re-scans per
+ * docker command. `scripts/test-slim-hook.js` enforces the graph budget.
+ */
+exports.HOOK_DEBUG_LOG = path.join(os.homedir(), '.fullcourtdefense-hook.log');
+/**
+ * Verbose diagnostics (FCD_HOOK_DEBUG=1) additionally log content previews
+ * (raw payload + prompt text snippets). Default logging keeps operational
+ * metadata only — user prompt content must never sit in a plaintext file on
+ * a customer laptop unless support explicitly opts in.
+ */
+exports.HOOK_DEBUG_VERBOSE = process.env.FCD_HOOK_DEBUG === '1';
+/** Rotate the hook log when it grows past this size (same scheme as daemon.log). */
+const DEBUG_LOG_MAX_BYTES = 1_000_000;
+// Checked once per (short-lived) hook process: unbounded hook.log growth was
+// real customer disk churn — and every append to a huge file re-triggers AV
+// scanning. One stat per process is enough for a hook run; the resident
+// daemon (verdict IPC evaluation) re-checks every 500 writes so a long
+// uptime can't outgrow the cap either.
+let debugLogRotationChecked = false;
+let debugLogWritesSinceCheck = 0;
+/** Append a diagnostic line so we can see exactly what the IDE invoked + the verdict. */
+function dbg(obj) {
+    try {
+        debugLogWritesSinceCheck += 1;
+        if (!debugLogRotationChecked || debugLogWritesSinceCheck >= 500) {
+            debugLogRotationChecked = true;
+            debugLogWritesSinceCheck = 0;
+            try {
+                if (fs.existsSync(exports.HOOK_DEBUG_LOG) && fs.statSync(exports.HOOK_DEBUG_LOG).size > DEBUG_LOG_MAX_BYTES) {
+                    fs.renameSync(exports.HOOK_DEBUG_LOG, `${exports.HOOK_DEBUG_LOG}.1`);
+                }
+            }
+            catch { /* rotation is best-effort */ }
+        }
+        fs.appendFileSync(exports.HOOK_DEBUG_LOG, JSON.stringify({ t: new Date().toISOString(), ...obj }) + '\n');
+    }
+    catch { /* ignore */ }
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        if (stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        // Read raw BYTES (no setEncoding) and decode the whole payload as UTF-8 once.
+        // Per-chunk string decoding + concat corrupts multibyte chars (e.g. Hebrew),
+        // turning them into Latin-1 mojibake before they ever reach the backend.
+        const chunks = [];
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            let buf = Buffer.concat(chunks);
+            // Strip UTF-8 BOM at the byte level (Cursor on Windows prepends EF BB BF).
+            if (buf.length >= 3 && buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF) {
+                buf = buf.subarray(3);
+            }
+            resolve(buf.toString('utf8'));
+        };
+        stdin.on('data', (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        stdin.on('end', finish);
+        stdin.on('error', finish);
+        // Safety: if nothing arrives, don't hang forever.
+        setTimeout(finish, 2000).unref?.();
+    });
+}
+/**
+ * kebab-case CLI flags -> the camelCase HookArgs shape. ONE mapping shared by
+ * the full CLI entry (`index.ts` case 'hook') and the slim entry, so the
+ * daemon's IPC evaluator always receives identical argument shapes no matter
+ * which entry the IDE invoked.
+ */
+function mapHookFlags(flags) {
+    return {
+        event: flags.event,
+        apiUrl: flags['api-url'],
+        shieldId: flags['shield-id'],
+        shieldKey: flags['shield-key'],
+        shadow: flags.shadow,
+        enforce: flags.enforce,
+        failClosed: flags['fail-closed'],
+        localOnly: flags['local-only'],
+        timeout: flags.timeout,
+        approvalMode: flags['approval-mode'],
+        approvalTimeoutMs: flags['approval-timeout-ms'],
+        approvalPollMs: flags['approval-poll-ms'],
+    };
+}
+/**
+ * Minimal `--flag value` / `--flag=value` parser with the same semantics as
+ * the full CLI's parseArgs, restricted to what a hook command line carries.
+ * Positionals (the literal `hook` subcommand kept in installed commands for
+ * the managed-entry repair marker) are ignored.
+ */
+function parseHookFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('-'))
+            continue;
+        const key = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
+        const eqIdx = key.indexOf('=');
+        if (eqIdx !== -1) {
+            flags[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+            flags[key] = next;
+            i++;
+        }
+        else {
+            flags[key] = 'true';
+        }
+    }
+    return flags;
+}
+/**
+ * Absolute path of the slim hook entry that sits next to a given CLI script
+ * (`dist/index.js` -> `dist/hookSlim.js`). Installers prefer the slim entry
+ * when it exists; older installs (pre-slim dist) keep pointing at index.js.
+ */
+function slimHookEntryPath(cliScriptPath) {
+    try {
+        const candidate = path.join(path.dirname(cliScriptPath), 'hookSlim.js');
+        return fs.existsSync(candidate) ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hookSlim.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * SLIM HOOK ENTRY — what the IDE actually spawns on every hook event.
+ *
+ * The per-event tax on a hook used to be loading the ENTIRE CLI (dist/index.js
+ * and its transitive graph) just to ask the resident daemon one question over
+ * the verdict pipe. On a normal laptop that is tens of milliseconds; on a
+ * locked-down corporate machine whose EDR re-scans every loaded file, it is
+ * the 1-5s "sticky" pause a docker-heavy customer feels dozens of times an
+ * hour. This entry exists to make the common path (daemon up, IPC verdict)
+ * load almost nothing:
+ *
+ *   node boot -> hookSlim.js -> hookIo.js + verdictIpcClient.js  (3 small files,
+ *   Node built-ins only) -> named-pipe verdict -> print -> exit.
+ *
+ * FALLBACK PARITY: when the daemon is unreachable, this entry lazily requires
+ * the full hook evaluation (`commands/hook.evaluateHookRequest`) — literally
+ * the same code the full CLI runs — so behavior with the daemon down is
+ * byte-identical to `index.js hook`. The slim win applies exactly where it
+ * matters: the warm, common case.
+ *
+ * FAIL-OPEN CONTRACT (same as the full hook): any unexpected error must never
+ * surface as a stack trace, a nonzero exit, or a blocked command. The ONE
+ * exception is the admin kill-switch — a crash on a suspended machine still
+ * denies, so a broken install can never unlock a machine an admin suspended.
+ *
+ * COLD-START CONTRACT: static imports here are restricted to the two leaves
+ * below (Node built-ins only). Everything else loads lazily, and ONLY on the
+ * fallback path. `scripts/test-slim-hook.js` fails CI if the warm-path module
+ * graph grows.
+ */
+export {};

package/dist/hookSlim.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * SLIM HOOK ENTRY — what the IDE actually spawns on every hook event.
+ *
+ * The per-event tax on a hook used to be loading the ENTIRE CLI (dist/index.js
+ * and its transitive graph) just to ask the resident daemon one question over
+ * the verdict pipe. On a normal laptop that is tens of milliseconds; on a
+ * locked-down corporate machine whose EDR re-scans every loaded file, it is
+ * the 1-5s "sticky" pause a docker-heavy customer feels dozens of times an
+ * hour. This entry exists to make the common path (daemon up, IPC verdict)
+ * load almost nothing:
+ *
+ *   node boot -> hookSlim.js -> hookIo.js + verdictIpcClient.js  (3 small files,
+ *   Node built-ins only) -> named-pipe verdict -> print -> exit.
+ *
+ * FALLBACK PARITY: when the daemon is unreachable, this entry lazily requires
+ * the full hook evaluation (`commands/hook.evaluateHookRequest`) — literally
+ * the same code the full CLI runs — so behavior with the daemon down is
+ * byte-identical to `index.js hook`. The slim win applies exactly where it
+ * matters: the warm, common case.
+ *
+ * FAIL-OPEN CONTRACT (same as the full hook): any unexpected error must never
+ * surface as a stack trace, a nonzero exit, or a blocked command. The ONE
+ * exception is the admin kill-switch — a crash on a suspended machine still
+ * denies, so a broken install can never unlock a machine an admin suspended.
+ *
+ * COLD-START CONTRACT: static imports here are restricted to the two leaves
+ * below (Node built-ins only). Everything else loads lazily, and ONLY on the
+ * fallback path. `scripts/test-slim-hook.js` fails CI if the warm-path module
+ * graph grows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const hookIo_1 = require("./hookIo");
+const verdictIpcClient_1 = require("./verdictIpcClient");
+function emitFailOpen(event, message) {
+    // Mirror of the full hook's failOpenOutcome, reachable only when even the
+    // lazy fallback could not load (corrupt install). Best effort all the way
+    // down; the kill-switch check and spool are each allowed to fail alone.
+    let suspended = false;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        suspended = require('./runtimeConfig').isSuspendedByCache();
+    }
+    catch { /* runtime cache unreadable — stay fail-open */ }
+    try {
+        (0, hookIo_1.dbg)({ phase: 'slim_fail_open', event, error: message.slice(0, 300), suspended });
+    }
+    catch { /* never throw */ }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const telemetry = require('./telemetry');
+        telemetry.setVerdictPath('fail_open');
+        telemetry.spoolEvent({
+            decision: suspended ? 'block' : 'allow',
+            toolName: event || 'unknown',
+            operation: `${event || 'unknown'}:hook_error`,
+            reason: suspended
+                ? `Hook error on a SUSPENDED machine — denied (kill-switch holds): ${message.slice(0, 200)}`
+                : `Hook error failed open: ${message.slice(0, 200)}`,
+            offlineEnforced: true,
+            ...(suspended ? { severity: 'critical', source: 'backend' } : {}),
+        });
+        telemetry.triggerFlush(true);
+    }
+    catch { /* telemetry unavailable — the verdict below still stands */ }
+    const verdict = suspended
+        ? {
+            continue: false,
+            permission: 'deny',
+            user_message: 'This machine is suspended by your security team — all AI agent actions are blocked. Contact your admin to resume it.',
+            agent_message: 'FullCourtDefense: this machine is suspended by an administrator. Stop — do not retry any action until it is resumed.',
+        }
+        : { continue: true, permission: 'allow' };
+    try {
+        process.stdout.write(JSON.stringify(verdict) + '\n');
+    }
+    catch { /* stdout gone */ }
+    process.exit(0);
+}
+async function main() {
+    const startedAt = Date.now();
+    const flags = (0, hookIo_1.parseHookFlags)(process.argv.slice(2));
+    const args = (0, hookIo_1.mapHookFlags)(flags);
+    try {
+        const raw = await (0, hookIo_1.readStdin)();
+        // FAST PATH: the resident daemon computes the verdict with everything warm.
+        // Bounded hard (connect ~250ms, response ~2.5s) — any non-verdict outcome
+        // falls through to the full evaluation below. FCD_VERDICT_IPC=off opts out.
+        if (process.env.FCD_VERDICT_IPC !== 'off') {
+            const ipc = await (0, verdictIpcClient_1.requestDaemonVerdict)(args, raw, undefined, startedAt);
+            if (ipc.outcome === 'verdict') {
+                (0, hookIo_1.dbg)({ phase: 'ipc_verdict', event: args.event, exitCode: ipc.exitCode, entry: 'slim' });
+                if (ipc.stderr) {
+                    try {
+                        process.stderr.write(ipc.stderr);
+                    }
+                    catch { /* stderr gone */ }
+                }
+                if (ipc.stdout) {
+                    try {
+                        process.stdout.write(ipc.stdout);
+                    }
+                    catch { /* stdout gone */ }
+                }
+                process.exit(ipc.exitCode ?? 0);
+            }
+            (0, hookIo_1.dbg)({ phase: 'ipc_unavailable', event: args.event, detail: ipc.detail, entry: 'slim' });
+        }
+        // FALLBACK: daemon down/busy — load the full evaluation lazily. This is
+        // the exact code `index.js hook` runs (including its own fail-open and
+        // kill-switch handling), so daemon-down behavior is identical to the
+        // pre-slim hook. evaluateHookRequest never rejects by contract.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { evaluateHookRequest } = require('./commands/hook');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { loadConfig } = require('./config');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { markVerdictTiming } = require('./telemetry');
+        const result = await markVerdictTiming({ startedAt, path: 'local' }, () => evaluateHookRequest(args, raw, loadConfig()));
+        if (result.stderr) {
+            try {
+                process.stderr.write(result.stderr);
+            }
+            catch { /* stderr gone */ }
+        }
+        if (result.stdout) {
+            try {
+                process.stdout.write(result.stdout);
+            }
+            catch { /* stdout gone */ }
+        }
+        process.exit(result.exitCode);
+    }
+    catch (err) {
+        emitFailOpen(args.event, err instanceof Error ? err.message : String(err));
+    }
+}
+// Main-guarded so importing this module (tests, tooling) never runs the hook.
+if (require.main === module) {
+    void main();
+}

package/dist/index.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // touching this file.
 const config_1 = require("./config");
 const hook_1 = require("./commands/hook");
+const hookIo_1 = require("./hookIo");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 function readCliVersion() {
@@ -679,20 +680,9 @@ async function main() {
             break;
         }
         case 'hook': {
-            const args = {
-                event: flags.event,
-                apiUrl: flags['api-url'],
-                shieldId: flags['shield-id'],
-                shieldKey: flags['shield-key'],
-                shadow: flags.shadow,
-                enforce: flags.enforce,
-                failClosed: flags['fail-closed'],
-                localOnly: flags['local-only'],
-                timeout: flags.timeout,
-                approvalMode: flags['approval-mode'],
-                approvalTimeoutMs: flags['approval-timeout-ms'],
-                approvalPollMs: flags['approval-poll-ms'],
-            };
+            // ONE flag mapping shared with the slim entry (hookSlim.ts) — the daemon
+            // IPC evaluator must see identical argument shapes from both entries.
+            const args = (0, hookIo_1.mapHookFlags)(flags);
             await (0, hook_1.hookCommand)(args, config);
             break;
         }

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;
+        },
+    };
+}