fullcourtdefense-cli 1.37.0 → 1.39.0

package/dist/askDialog.d.ts

@@ -15,7 +15,9 @@
  *
  * and answers the IDE `allow` or `deny`. The IDE's own card is the fallback only
  * where no dialog is possible (no display, dialog binary missing) or where the
- * org chose it (`FCD_ASK_CHANNEL=ide`). The envelope never reaches the IDE.
+ * org chose it (`FCD_ASK_CHANNEL=ide`) — and never for a client that reports a
+ * permission mode in which it may answer its own card (v139 F-13 / F-33): our
+ * dialog asks there, or the action is denied. The envelope never reaches the IDE.
  *
  * Deterministic all the way: the rule that asked is named in the envelope, the
  * grant is bound to that rule's hash, and nothing here re-evaluates the action.
@@ -56,8 +58,31 @@ export interface AskEnvelope {
     reason: string;
     /** The client the runtime event records as `agentClient` (cursor, claude-code, …): the dialog names the same agent as the console. */
     agentClient?: string;
+    /**
+     * The asking call's correlation identity (session / run / tool call id): the
+     * dialog's outcome is recorded by this process, outside that call's
+     * evaluation, and must name the same action. Older hook builds omit it.
+     */
+    identity?: {
+        sessionId?: string;
+        runId?: string;
+        instanceId?: string;
+        attemptId?: string;
+    };
+    /**
+     * The permission mode the asking client reported (Claude Code `permission_mode`).
+     * A mode in which the IDE may answer its own card (`idePromptState` = auto) never
+     * gets the question: our dialog asks, or the action is denied. Absent: the client
+     * does not say (Cursor, VS Code, Copilot CLI) or an older hook build.
+     */
+    ideMode?: string;
 }
-export type AskResolution = 'allow' | 'allow_always' | 'deny' | 'timeout' | 'ide';
+/**
+ * How an ask ended in the per-event process. `ide`: handed to the IDE's own card.
+ * `ide_auto`: no FullCourtDefense dialog was possible and the IDE runs in a mode that
+ * may answer its own card — denied, never handed over.
+ */
+export type AskResolution = 'allow' | 'allow_always' | 'deny' | 'timeout' | 'ide' | 'ide_auto';
 export interface HookVerdict {
     stdout: string;
     stderr: string;
@@ -81,12 +106,19 @@ export declare function takeAskEnvelope(stdout: string): {
  * Last step of the per-event hook process (full and slim entries alike): an `ask`
  * verdict is put to the developer in the FullCourtDefense dialog and becomes the
  * IDE's allow / deny; anything else — and an ask where no dialog is possible — is
- * written as-is with the envelope removed. Then the process exits.
+ * written as-is with the envelope removed (an ask the IDE may answer on its own is
+ * denied instead, v139 F-13). Then the process exits.
  */
 export declare function emitVerdictForIde(args: {
     event?: string;
     agentClient?: string;
 }, result: HookVerdict, entry: 'ipc' | 'local' | 'slim-ipc' | 'slim-local'): Promise<never>;
+/**
+ * The verdict when the dialog step itself failed (emitVerdictForIde's catch): the dialog
+ * step must never break the verdict, so the IDE ask goes out with the envelope stripped —
+ * or, where the IDE may answer its own card, a deny (v139 F-13). Never throws.
+ */
+export declare function verdictAfterDialogError(result: HookVerdict, clientLabel?: string): HookVerdict;
 /**
  * Resolve an `ask` verdict with the developer. Returns the verdict to hand to the
  * IDE (envelope removed) and how it was resolved. Any verdict without an envelope,

package/dist/askDialog.js

@@ -5,6 +5,7 @@ exports.askChannel = askChannel;
 exports.attachAskEnvelope = attachAskEnvelope;
 exports.takeAskEnvelope = takeAskEnvelope;
 exports.emitVerdictForIde = emitVerdictForIde;
+exports.verdictAfterDialogError = verdictAfterDialogError;
 exports.resolveAskWithDialog = resolveAskWithDialog;
 /**
  * The developer's question, answered in OUR dialog — one flow for every IDE.
@@ -23,13 +24,16 @@ exports.resolveAskWithDialog = resolveAskWithDialog;
  *
  * and answers the IDE `allow` or `deny`. The IDE's own card is the fallback only
  * where no dialog is possible (no display, dialog binary missing) or where the
- * org chose it (`FCD_ASK_CHANNEL=ide`). The envelope never reaches the IDE.
+ * org chose it (`FCD_ASK_CHANNEL=ide`) — and never for a client that reports a
+ * permission mode in which it may answer its own card (v139 F-13 / F-33): our
+ * dialog asks there, or the action is denied. The envelope never reaches the IDE.
  *
  * Deterministic all the way: the rule that asked is named in the envelope, the
  * grant is bound to that rule's hash, and nothing here re-evaluates the action.
  */
 const devConfirm_1 = require("./devConfirm");
 const telemetry_1 = require("./telemetry");
+const actionIdentity_1 = require("./actionIdentity");
 const hookIo_1 = require("./hookIo");
 const callerEnv_1 = require("./callerEnv");
 /** Field on the verdict JSON that carries the envelope. Stripped before the IDE sees the verdict. */
@@ -96,7 +100,8 @@ function rewriteDecision(decision, allowed, userMsg, agentMsg) {
  * Last step of the per-event hook process (full and slim entries alike): an `ask`
  * verdict is put to the developer in the FullCourtDefense dialog and becomes the
  * IDE's allow / deny; anything else — and an ask where no dialog is possible — is
- * written as-is with the envelope removed. Then the process exits.
+ * written as-is with the envelope removed (an ask the IDE may answer on its own is
+ * denied instead, v139 F-13). Then the process exits.
  */
 async function emitVerdictForIde(args, result, entry) {
     // This process ends with the verdict below: an upload the dialog's outcome
@@ -118,9 +123,8 @@ async function emitVerdictForIde(args, result, entry) {
         final = resolved;
     }
     catch (err) {
-        // The dialog step must never break the verdict: fall back to the IDE ask (envelope stripped).
         (0, hookIo_1.dbg)({ phase: 'ask_dialog_error', event: args.event, entry, error: err instanceof Error ? err.message : String(err) });
-        final = { ...result, stdout: takeAskEnvelope(result.stdout).stdout };
+        final = verdictAfterDialogError(result, args.agentClient);
     }
     if (final.stderr) {
         try {
@@ -136,6 +140,22 @@ async function emitVerdictForIde(args, result, entry) {
     }
     return process.exit(final.exitCode);
 }
+/**
+ * The verdict when the dialog step itself failed (emitVerdictForIde's catch): the dialog
+ * step must never break the verdict, so the IDE ask goes out with the envelope stripped —
+ * or, where the IDE may answer its own card, a deny (v139 F-13). Never throws.
+ */
+function verdictAfterDialogError(result, clientLabel) {
+    const taken = takeAskEnvelope(result.stdout);
+    let final = { ...result, stdout: taken.stdout };
+    try {
+        if (taken.decision && taken.envelope && decisionAsks(taken.decision) && (0, devConfirm_1.idePromptState)(taken.envelope.ideMode) === 'auto') {
+            final = denyNoHumanPrompt({ ...final, envelope: taken.envelope }, taken.decision, taken.envelope, clientLabel);
+        }
+    }
+    catch { /* the verdict must still be written */ }
+    return final;
+}
 /**
  * Resolve an `ask` verdict with the developer. Returns the verdict to hand to the
  * IDE (envelope removed) and how it was resolved. Any verdict without an envelope,
@@ -154,8 +174,18 @@ async function resolveAskWithDialog(verdict, options = {}) {
     // left for a person to read and answer: the IDE's own ask card takes the
     // question instead, so the hook still answers inside the IDE's window.
     const dialogTimeoutMs = Math.min(options.timeoutMs ?? exports.ASK_DIALOG_TIMEOUT_MS, options.deadlineAt === undefined ? Number.POSITIVE_INFINITY : options.deadlineAt - Date.now());
-    if (askChannel() === 'ide' || !canAsk || dialogTimeoutMs < MIN_DIALOG_TIMEOUT_MS)
-        return { ...clean, resolution: 'ide' };
+    // v139 F-13 / F-33: the IDE's card is a channel only where it can reach a person. A
+    // client that reports a mode in which it may answer its own card (Claude Code
+    // bypassPermissions, acceptEdits, auto, dontAsk) never gets the question, whatever
+    // FCD_ASK_CHANNEL / FCD_HOOK_IDE_TIMEOUT_MS say (both reachable from an IDE settings
+    // env block the agent can write): our dialog asks, or — no dialog possible here — the
+    // action is denied. A client that does not say keeps today's routing; its card's
+    // answer is recorded as unverified and never becomes memory (settlePostExecution).
+    const ideMayAnswerItself = (0, devConfirm_1.idePromptState)(envelope.ideMode) === 'auto';
+    const dialogPossible = canAsk && dialogTimeoutMs >= MIN_DIALOG_TIMEOUT_MS;
+    if (!dialogPossible || (askChannel() === 'ide' && !ideMayAnswerItself)) {
+        return ideMayAnswerItself ? denyNoHumanPrompt(clean, decision, envelope, options.clientLabel) : { ...clean, resolution: 'ide' };
+    }
     const grantHash = envelope.ruleHash || envelope.policyHash;
     const grantLimits = envelope.grantLimits === null ? undefined : (envelope.grantLimits || { ttlMs: devConfirm_1.GRANT_TTL_MS });
     const allowAlways = envelope.remember !== 'none' && Boolean(grantHash) && Boolean(grantLimits) && (0, devConfirm_1.grantOffered)(envelope.scope);
@@ -186,8 +216,16 @@ async function resolveAskWithDialog(verdict, options = {}) {
         outcome = 'unavailable';
     }
     if (outcome === 'unavailable')
-        return { ...clean, resolution: 'ide' };
+        return ideMayAnswerItself ? denyNoHumanPrompt(clean, decision, envelope, options.clientLabel) : { ...clean, resolution: 'ide' };
     const policyLabel = envelope.policyName ? ` (${envelope.policyName})` : '';
+    // The outcome is the asking call's: its client and identity, not this process's.
+    // No latency / verdict path: the ask itself recorded the hook's wait (one health
+    // sample per call), and the person's answer time is confirmLatencyMs.
+    const outcomeFacts = (askOutcome) => ({
+        askOutcome,
+        ...(envelope.agentClient || options.clientLabel ? { agentClient: envelope.agentClient || options.clientLabel } : {}),
+        ...envelopeIdentity(envelope),
+    });
     if (outcome === 'allow' || outcome === 'allow_always') {
         // Same bookkeeping the post-execution hook would have done for an IDE Allow.
         (0, devConfirm_1.settleDeveloperConfirmation)(envelope.event, envelope.toolName, envelope.argsDigest);
@@ -210,6 +248,7 @@ async function resolveAskWithDialog(verdict, options = {}) {
             approvalScope: 'developer',
             approvedBy: 'developer',
             confirmLatencyMs: latencyMs,
+            ...outcomeFacts(granted ? 'allowed_always' : 'allowed'),
         });
         (0, telemetry_1.triggerFlush)(false);
         const agentMsg = granted
@@ -230,6 +269,9 @@ async function resolveAskWithDialog(verdict, options = {}) {
         policyHash: envelope.policyHash,
         approvalScope: 'developer',
         confirmLatencyMs: latencyMs,
+        // No answer is not a rule's block: the action did not run (the IDE gets the
+        // same deny), but nobody decided against it — recorded as an unanswered ask.
+        ...outcomeFacts(timedOut ? 'unanswered' : 'denied'),
     });
     (0, telemetry_1.triggerFlush)(true);
     const userMsg = timedOut
@@ -240,3 +282,54 @@ async function resolveAskWithDialog(verdict, options = {}) {
         : `FullCourtDefense: the developer denied this ${envelope.event} in the confirmation dialog. Do not retry or work around it.`;
     return { ...clean, stdout: JSON.stringify(rewriteDecision(decision, false, userMsg, agentMsg)), exitCode: 0, resolution: outcome };
 }
+/**
+ * v139 F-13: the ask cannot reach a person — no FullCourtDefense dialog is possible here
+ * and the IDE runs in a mode that may answer its own card (or refuse it unseen). Denied
+ * with an honest record (nobody answered), and the pending marker is dropped so no later
+ * post-execution hook can settle it.
+ */
+function denyNoHumanPrompt(clean, decision, envelope, clientLabel) {
+    try {
+        (0, devConfirm_1.rejectDeveloperConfirmation)(envelope.event, envelope.toolName, envelope.argsDigest);
+    }
+    catch { /* the deny below still stands */ }
+    const policyLabel = envelope.policyName ? ` (${envelope.policyName})` : '';
+    const agentClient = envelope.agentClient || clientLabel;
+    const client = agentClient || 'the agent';
+    const mode = envelope.ideMode || 'auto-approve';
+    try {
+        (0, telemetry_1.spoolEvent)({
+            decision: 'block',
+            toolName: envelope.toolName,
+            operation: envelope.operation,
+            // The gateway's "confirmation not possible" family: nobody could be asked, which the
+            // fleet keeps as a block alert (backend fleet-block-alerts.ts), unlike a dialog timeout.
+            reason: `developer confirmation not possible (the FullCourtDefense dialog cannot be shown here and ${client} runs in "${mode}" mode, which may answer its own prompt without showing it to a person) — denied${policyLabel}`,
+            ruleId: envelope.policyId,
+            policyHash: envelope.policyHash,
+            approvalScope: 'developer',
+            // Nobody answered: not a rule's block and not a person's deny.
+            askOutcome: 'unanswered',
+            ...(agentClient ? { agentClient } : {}),
+            ...envelopeIdentity(envelope),
+        });
+        (0, telemetry_1.triggerFlush)(true);
+    }
+    catch { /* the deny below still stands */ }
+    const userMsg = `FullCourtDefense stopped this ${envelope.event}: a rule asks you to confirm it${policyLabel}, but ${client} is in "${mode}" mode, which may approve its own prompts without showing them to you, and the FullCourtDefense dialog cannot be shown here. Switch the agent to a mode that asks you, or run it where the FullCourtDefense dialog can appear, to be asked.`;
+    const agentMsg = `${userMsg} Do not retry or work around it.`;
+    return { ...clean, stdout: JSON.stringify(rewriteDecision(decision, false, userMsg, agentMsg)), exitCode: 0, resolution: 'ide_auto' };
+}
+/** The asking call's identity from the envelope: well-formed parts only. */
+function envelopeIdentity(envelope) {
+    const raw = envelope.identity;
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const out = {};
+    for (const key of ['sessionId', 'runId', 'instanceId', 'attemptId']) {
+        const value = (0, actionIdentity_1.identityPart)(raw[key]);
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}

package/dist/awakeClock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Was the MACHINE asleep, or only the daemon's event loop?
+ *
+ * The daemon detects a resume from sleep by a beat that observes far more
+ * wall time than its interval. A long synchronous stretch on its own loop
+ * looks the same: 2026-10-02 06:58, a 201 s protect-all pass ended and two
+ * seconds later the daemon logged "Resume detected: 237s ... suspended",
+ * re-reported in and recorded network_down [x30] from timeouts that ran out
+ * inside the stall — while hook.log showed hooks every few seconds throughout.
+ *
+ * This clock ticks on a worker thread, which keeps running while the main
+ * loop is blocked and stops only when the whole process (the machine) does.
+ * A long main-loop gap with no long gap here was a stall, not a suspend.
+ * One thread, a 1 s timer, no process and no I/O.
+ */
+export declare const AWAKE_TICK_MS = 1000;
+/** A worker gap this short through a long main-loop gap: the machine stayed awake. */
+export declare const AWAKE_GAP_MAX_MS = 10000;
+export interface AwakeClock {
+    /** Longest gap between ticks since the previous call (including the time since the last tick). Undefined once the clock is gone. */
+    takeMaxGapMs(): number | undefined;
+    stop(): void;
+}
+export declare function startAwakeClock(tickMs?: number): AwakeClock | undefined;
+/**
+ * Pure: what a gap of `driftMs` between two beats of the daemon's loop was.
+ * Without the awake clock (it could not start) every long gap stays a suspend,
+ * as before.
+ */
+export declare function classifyClockJump(input: {
+    driftMs: number;
+    jumpMs: number;
+    awakeGapMs?: number;
+}): 'none' | 'stall' | 'suspend';

package/dist/awakeClock.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AWAKE_GAP_MAX_MS = exports.AWAKE_TICK_MS = void 0;
+exports.startAwakeClock = startAwakeClock;
+exports.classifyClockJump = classifyClockJump;
+const worker_threads_1 = require("worker_threads");
+/**
+ * Was the MACHINE asleep, or only the daemon's event loop?
+ *
+ * The daemon detects a resume from sleep by a beat that observes far more
+ * wall time than its interval. A long synchronous stretch on its own loop
+ * looks the same: 2026-10-02 06:58, a 201 s protect-all pass ended and two
+ * seconds later the daemon logged "Resume detected: 237s ... suspended",
+ * re-reported in and recorded network_down [x30] from timeouts that ran out
+ * inside the stall — while hook.log showed hooks every few seconds throughout.
+ *
+ * This clock ticks on a worker thread, which keeps running while the main
+ * loop is blocked and stops only when the whole process (the machine) does.
+ * A long main-loop gap with no long gap here was a stall, not a suspend.
+ * One thread, a 1 s timer, no process and no I/O.
+ */
+exports.AWAKE_TICK_MS = 1_000;
+/** A worker gap this short through a long main-loop gap: the machine stayed awake. */
+exports.AWAKE_GAP_MAX_MS = 10_000;
+function startAwakeClock(tickMs = exports.AWAKE_TICK_MS) {
+    try {
+        // [0] last tick (wall ms), [1] longest gap between ticks since the last read.
+        const shared = new Float64Array(new SharedArrayBuffer(16));
+        shared[0] = Date.now();
+        const source = `
+      const { workerData } = require('worker_threads');
+      const clock = new Float64Array(workerData);
+      let last = Date.now();
+      setInterval(() => {
+        const now = Date.now();
+        if (now - last > clock[1]) clock[1] = now - last;
+        last = now;
+        clock[0] = now;
+      }, ${Math.max(100, Math.floor(tickMs))});
+    `;
+        const worker = new worker_threads_1.Worker(source, {
+            eval: true,
+            workerData: shared.buffer,
+            resourceLimits: { maxOldGenerationSizeMb: 16, maxYoungGenerationSizeMb: 4 },
+            stdout: true,
+            stderr: true,
+        });
+        worker.unref();
+        let alive = true;
+        worker.on('error', () => { alive = false; });
+        worker.on('exit', () => { alive = false; });
+        return {
+            takeMaxGapMs() {
+                if (!alive)
+                    return undefined;
+                const gap = Math.max(shared[1], Date.now() - shared[0]);
+                shared[1] = 0;
+                return gap;
+            },
+            stop() {
+                alive = false;
+                void worker.terminate().catch(() => { });
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pure: what a gap of `driftMs` between two beats of the daemon's loop was.
+ * Without the awake clock (it could not start) every long gap stays a suspend,
+ * as before.
+ */
+function classifyClockJump(input) {
+    if (input.driftMs < input.jumpMs)
+        return 'none';
+    if (input.awakeGapMs !== undefined && input.awakeGapMs < exports.AWAKE_GAP_MAX_MS)
+        return 'stall';
+    return 'suspend';
+}

package/dist/backupManifest.d.ts

@@ -1,7 +1,20 @@
+/** Distinct recent versions kept per config, besides its oldest (original) copy. */
+export declare const KEEP_RECENT_BACKUPS = 3;
 export declare function backupManifestPath(): string;
 /** Every recorded backup path (absent/corrupt manifest = empty list). */
 export declare function readBackupManifest(): string[];
-/** Record one backup file path. Deduped, capped, never throws. */
+/** Record one backup file path. Deduped, never throws. */
 export declare function recordConfigBackup(backupPath: string): void;
 /** Drop entries whose backup file no longer exists (post-cleanup compaction). */
 export declare function pruneBackupManifest(): void;
+/** This config's safety copies next to it (`<name>.fcd-backup-<ms>`), oldest first. */
+export declare function listConfigBackups(file: string): string[];
+/**
+ * Back `file` up next to itself before FullCourtDefense rewrites it — once per
+ * distinct content: a version already kept (a rewrite that only flips the
+ * runtime path back and forth, a pass that writes the same content) adds no
+ * copy. Afterwards the config keeps its oldest copy (the original, before
+ * FullCourtDefense first changed it) and its KEEP_RECENT newest. Returns the
+ * new copy, or undefined when none was needed (or it failed). Never throws.
+ */
+export declare function createConfigBackup(file: string, now?: number): string | undefined;

package/dist/backupManifest.js

@@ -33,10 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEEP_RECENT_BACKUPS = void 0;
 exports.backupManifestPath = backupManifestPath;
 exports.readBackupManifest = readBackupManifest;
 exports.recordConfigBackup = recordConfigBackup;
 exports.pruneBackupManifest = pruneBackupManifest;
+exports.listConfigBackups = listConfigBackups;
+exports.createConfigBackup = createConfigBackup;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -51,11 +54,21 @@ const path = __importStar(require("path"));
  * authoritative list at cleanup time (union-ed with the known-dir scan for
  * backups created by older CLI versions).
  *
+ * Bounded (2026-10: 5,517 copies, 9.8 MB, and a manifest silently cut at its
+ * newest 2,000 entries, so uninstall missed most of them): a config keeps the
+ * copy taken before FullCourtDefense first changed it plus its last
+ * KEEP_RECENT distinct versions (createConfigBackup), and the manifest drops
+ * only entries whose file is gone — never a live one.
+ *
  * Best-effort by design: a manifest write failure must never break a protect
  * operation, and cleanup falls back to the directory scan.
  */
 const MANIFEST_NAME = 'backup-manifest.json';
-const MAX_ENTRIES = 2000;
+/** Size guard for the manifest file itself; reached only after every missing-file entry is dropped. */
+const MAX_ENTRIES = 20_000;
+/** Distinct recent versions kept per config, besides its oldest (original) copy. */
+exports.KEEP_RECENT_BACKUPS = 3;
+const BACKUP_INFIX = '.fcd-backup-';
 function backupManifestPath() {
     return path.join(os.homedir(), '.fullcourtdefense', MANIFEST_NAME);
 }
@@ -70,23 +83,105 @@ function readBackupManifest() {
         return [];
     }
 }
-/** Record one backup file path. Deduped, capped, never throws. */
-function recordConfigBackup(backupPath) {
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Read-modify-write the manifest under a short lock, written atomically
+ * (temp + rename): concurrent protect passes (daemon, CLI, hooks) no longer
+ * drop each other's entries. Bounded wait; never throws.
+ */
+function updateManifest(change) {
+    const file = backupManifestPath();
+    const lock = `${file}.lock`;
+    let held = false;
     try {
-        const existing = readBackupManifest();
-        if (existing.includes(backupPath))
-            return;
-        const entries = [...existing, backupPath].slice(-MAX_ENTRIES);
-        const file = backupManifestPath();
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, `${JSON.stringify({ backups: entries }, null, 2)}\n`, 'utf8');
+        // Protect passes only (daemon, housekeeping worker, CLI) — never a hook: a short wait is fine.
+        const deadline = Date.now() + 2_000;
+        for (let attempt = 0; attempt < 1_000 && !held; attempt += 1) {
+            try {
+                fs.writeFileSync(lock, String(process.pid), { flag: 'wx' });
+                held = true;
+            }
+            catch (error) {
+                // EPERM/EACCES: Windows reports a lock file being deleted that way — still contention.
+                const code = error.code;
+                if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EACCES')
+                    break;
+                try {
+                    if (Date.now() - fs.statSync(lock).mtimeMs > 10_000) {
+                        fs.unlinkSync(lock);
+                        continue;
+                    }
+                }
+                catch { /* released meanwhile */ }
+                if (Date.now() >= deadline)
+                    break;
+                sleepSync(5);
+            }
+        }
+        const before = readBackupManifest();
+        const next = change(before);
+        if (!next)
+            return;
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            if (next.length === 0) {
+                fs.rmSync(file, { force: true });
+                return;
+            }
+            fs.writeFileSync(tmp, `${JSON.stringify({ backups: next }, null, 2)}\n`, 'utf8');
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    fs.renameSync(tmp, file);
+                    break;
+                }
+                catch (error) {
+                    // Windows: a reader (or a scanner) holding the file open fails the rename for a moment.
+                    const code = error.code;
+                    if (attempt >= 20 || (code !== 'EPERM' && code !== 'EACCES' && code !== 'EBUSY'))
+                        throw error;
+                    sleepSync(10);
+                }
+            }
+        }
+        catch {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* not there */ }
+        }
     }
     catch { /* best effort — cleanup still has the directory scan */ }
+    finally {
+        if (held) {
+            try {
+                fs.unlinkSync(lock);
+            }
+            catch { /* gone */ }
+        }
+    }
+}
+/** Drop entries whose file is gone; only then, if still over the guard, the oldest. */
+function bounded(entries) {
+    if (entries.length <= MAX_ENTRIES)
+        return entries;
+    const live = entries.filter(entry => { try {
+        return fs.existsSync(entry);
+    }
+    catch {
+        return true;
+    } });
+    return live.length <= MAX_ENTRIES ? live : live.slice(-MAX_ENTRIES);
+}
+/** Record one backup file path. Deduped, never throws. */
+function recordConfigBackup(backupPath) {
+    updateManifest(existing => (existing.includes(backupPath) ? undefined : bounded([...existing, backupPath])));
 }
 /** Drop entries whose backup file no longer exists (post-cleanup compaction). */
 function pruneBackupManifest() {
-    try {
-        const existing = readBackupManifest();
+    updateManifest((existing) => {
         const remaining = existing.filter(entry => {
             try {
                 return fs.existsSync(entry);
@@ -95,14 +190,80 @@ function pruneBackupManifest() {
                 return true;
             }
         });
-        if (remaining.length === existing.length)
-            return;
-        const file = backupManifestPath();
-        if (remaining.length === 0) {
-            fs.rmSync(file, { force: true });
-            return;
+        return remaining.length === existing.length ? undefined : remaining;
+    });
+}
+/** This config's safety copies next to it (`<name>.fcd-backup-<ms>`), oldest first. */
+function listConfigBackups(file) {
+    const dir = path.dirname(file);
+    const prefix = `${path.basename(file)}${BACKUP_INFIX}`;
+    try {
+        return fs.readdirSync(dir)
+            .filter(name => name.startsWith(prefix) && /^\d+$/.test(name.slice(prefix.length)))
+            .sort((a, b) => Number(a.slice(prefix.length)) - Number(b.slice(prefix.length)))
+            .map(name => path.join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function sameContent(file, content) {
+    try {
+        return fs.statSync(file).size === content.length && fs.readFileSync(file).equals(content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Back `file` up next to itself before FullCourtDefense rewrites it — once per
+ * distinct content: a version already kept (a rewrite that only flips the
+ * runtime path back and forth, a pass that writes the same content) adds no
+ * copy. Afterwards the config keeps its oldest copy (the original, before
+ * FullCourtDefense first changed it) and its KEEP_RECENT newest. Returns the
+ * new copy, or undefined when none was needed (or it failed). Never throws.
+ */
+function createConfigBackup(file, now = Date.now()) {
+    try {
+        const content = fs.readFileSync(file);
+        const existing = listConfigBackups(file);
+        if (existing.some(copy => sameContent(copy, content)))
+            return undefined;
+        let stamp = now;
+        let backup = '';
+        for (let attempt = 0; attempt < 5; attempt += 1, stamp += 1) {
+            backup = `${file}${BACKUP_INFIX}${stamp}`;
+            try {
+                fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST' || attempt === 4)
+                    throw error;
+            }
         }
-        fs.writeFileSync(file, `${JSON.stringify({ backups: remaining }, null, 2)}\n`, 'utf8');
+        // Backups can embed live credentials and land in project-local dirs no
+        // scan can enumerate — record each one so uninstall can delete them all.
+        recordConfigBackup(backup);
+        const all = [...existing, backup];
+        const keep = new Set([all[0], ...all.slice(-exports.KEEP_RECENT_BACKUPS)]);
+        const pruned = [];
+        for (const copy of all) {
+            if (keep.has(copy))
+                continue;
+            try {
+                fs.rmSync(copy, { force: true });
+                pruned.push(copy);
+            }
+            catch { /* left for uninstall */ }
+        }
+        if (pruned.length > 0) {
+            const gone = new Set(pruned);
+            updateManifest(entries => entries.filter(entry => !gone.has(entry)));
+        }
+        return backup;
+    }
+    catch {
+        return undefined;
     }
-    catch { /* best effort */ }
 }

package/dist/callerEnv.d.ts

@@ -11,7 +11,7 @@
  *
  * Node built-ins only: this leaf is on the slim hook's warm-path module graph.
  */
-export declare const CALLER_ENV_KEYS: readonly ["FCD_HUMAN_PRESENT", "FCD_EPHEMERAL", "FULLCOURTDEFENSE_EPHEMERAL", "CI", "GITHUB_ACTIONS", "GITLAB_CI", "TF_BUILD", "JENKINS_URL", "BUILDKITE", "CIRCLECI", "DISPLAY", "WAYLAND_DISPLAY", "FCD_ASK_CHANNEL", "FCD_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "FCD_RUN_ID", "GITHUB_RUN_ID", "CI_PIPELINE_ID", "FCD_WORKLOAD_INSTANCE_ID", "CLAUDECODE", "CLAUDE_PROJECT_DIR", "VSCODE_PID", "TERM_PROGRAM", "WORKSPACE_PATH", "FCD_HOOK_IDE_TIMEOUT_MS", "FCD_TAINT_APPROVE_ONCE_DISABLED", "FCD_TAINT_APPROVAL_TIMEOUT_MS", "FCD_HOOK_DEBUG", "CLOUDSDK_CORE_PROJECT", "CLOUDSDK_ACTIVE_CONFIG_NAME", "CLOUDSDK_CONFIG", "APPDATA", "AWS_PROFILE", "AWS_DEFAULT_PROFILE", "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_ACCESS_KEY_ID", "KUBECONFIG", "HELM_KUBECONTEXT", "HELM_NAMESPACE", "HELM_KUBEAPISERVER", "HELM_KUBETOKEN", "HELM_KUBEASUSER", "DOCKER_HOST", "DOCKER_CONTEXT", "AZURE_CONFIG_DIR", "AZURE_DEFAULTS_GROUP", "TF_WORKSPACE", "TF_DATA_DIR", "PGHOST", "PGDATABASE", "PGSERVICE", "MYSQL_HOST"];
+export declare const CALLER_ENV_KEYS: readonly ["FCD_HUMAN_PRESENT", "FCD_EPHEMERAL", "FULLCOURTDEFENSE_EPHEMERAL", "CI", "GITHUB_ACTIONS", "GITLAB_CI", "TF_BUILD", "JENKINS_URL", "BUILDKITE", "CIRCLECI", "DISPLAY", "WAYLAND_DISPLAY", "FCD_ASK_CHANNEL", "FCD_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "FCD_RUN_ID", "GITHUB_RUN_ID", "CI_PIPELINE_ID", "FCD_WORKLOAD_INSTANCE_ID", "CLAUDECODE", "CLAUDE_PROJECT_DIR", "VSCODE_PID", "TERM_PROGRAM", "WORKSPACE_PATH", "FCD_HOOK_IDE_TIMEOUT_MS", "FCD_TAINT_APPROVE_ONCE_DISABLED", "FCD_TAINT_APPROVAL_TIMEOUT_MS", "FCD_HOOK_DEBUG", "FCD_MONITOR_HINTS", "FCD_PERF_PROBE", "CLOUDSDK_CORE_PROJECT", "CLOUDSDK_ACTIVE_CONFIG_NAME", "CLOUDSDK_CONFIG", "APPDATA", "AWS_PROFILE", "AWS_DEFAULT_PROFILE", "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_ACCESS_KEY_ID", "KUBECONFIG", "HELM_KUBECONTEXT", "HELM_NAMESPACE", "HELM_KUBEAPISERVER", "HELM_KUBETOKEN", "HELM_KUBEASUSER", "DOCKER_HOST", "DOCKER_CONTEXT", "AZURE_CONFIG_DIR", "AZURE_DEFAULTS_GROUP", "TF_WORKSPACE", "TF_DATA_DIR", "PGHOST", "PGDATABASE", "PGSERVICE", "MYSQL_HOST"];
 export type CallerEnvSnapshot = Partial<Record<(typeof CALLER_ENV_KEYS)[number], string>>;
 /**
  * Keys a decision reads only for WHETHER they are set (cloudGrantTools: static
@@ -60,6 +60,26 @@ export declare function ideHookTimeoutMs(env?: NodeJS.ProcessEnv): number;
 export declare function applyIdeTimeoutArg(seconds: string | undefined, env?: NodeJS.ProcessEnv): void;
 /** Absolute time every wait inside a hook must end by, leaving the margin before the IDE's timeout. */
 export declare function ideWaitCutoff(startedAt: number, ideTimeoutMs?: number): number;
+/**
+ * One truthiness rule for FCD_* switches: `1`, `true`, `yes`, `on` (any case,
+ * surrounding spaces ignored). Unset, empty, `0`, `false`, `off` and anything
+ * else are off. New switches use it; the existing decision switches
+ * (FCD_HUMAN_PRESENT, FCD_EPHEMERAL, ...) keep their exact historical spellings,
+ * because widening them would change a verdict for the same input.
+ */
+export declare function envFlag(value: string | undefined): boolean;
+/**
+ * The test-run markers set on THIS process (names; empty for every install).
+ * scripts/lib/no-real-dialog.js sets FCD_TEST_NO_REAL_DIALOG, the sandboxed
+ * daemon harnesses FCD_TEST_SANDBOX_ROOT, scripts/lib/fake-os-dialog.js
+ * FCD_FAKE_DIALOG_PID. No install, MSI, scheduled task or IDE hook config sets
+ * one. Read from process.env, never from a caller snapshot: the guards they
+ * drive (testRunGuard.ts, devConfirm, notify) protect this process's desktop
+ * and profile.
+ */
+export declare function testRunMarkers(env?: NodeJS.ProcessEnv): string[];
+/** A test run that promised no real OS dialog or notification on this desktop (devConfirm, notify). */
+export declare function noRealUiUnderTest(env?: NodeJS.ProcessEnv): boolean;
 /** CI / pipeline environments — no human at a keyboard. Shared by hooks and discovery. */
 export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
 /**