fullcourtdefense-cli 1.39.2 → 1.40.0

package/dist/agentTerminal.d.ts

@@ -11,16 +11,18 @@ export declare const AGENT_TERMINAL_MARKERS: readonly AgentTerminalMarker[];
 export declare function isAgentDrivenTerminal(env?: NodeJS.ProcessEnv): boolean;
 /** Shown (with the rule name) when an ask lands in an agent-driven terminal with no IDE answer behind it. */
 export declare const AGENT_TERMINAL_ASK_BLOCKED: string;
-/** Shown when the IDE prompt already answered for this exact command. */
-export declare const AGENT_TERMINAL_IDE_CONFIRMED = "allowed through the IDE permission gate; confirmation is recorded by the IDE post-execution hook.";
-/** Pending-marker key the IDE hook wrote for this shell command (see devConfirm.pendingKey). */
+/** Shown when the developer already said Allow for this exact command in the FullCourtDefense dialog (one use). */
+export declare const AGENT_TERMINAL_IDE_CONFIRMED = "allowed: the developer said Allow for this exact command in the FullCourtDefense dialog (that answer is used once).";
+/** Key of this shell command + directory: the hook's marker key (see devConfirm.pendingKey), and the file name of the dialog's single-use answer (terminalAllowance.ts). */
 export declare function ideShellPendingKey(command: string, cwd?: string): string;
-/** Maximum lifetime of an exact-command IDE permission handoff (not consent). */
+/** How long a pending marker lives (the ledger's TTL). Kept for the callers that name it; a pending marker has not been answered and the guards no longer read it. */
 export declare const IDE_CONFIRMATION_WINDOW_MS: number;
 /**
- * Pure decision over a parsed dev-confirm ledger: did the IDE prompt already
- * answer for this command / rule? Used by the in-process tests and mirrored
- * by the generated guard code below.
+ * Pure decision over a parsed dev-confirm ledger: did the developer already
+ * answer for this command / rule? Never — a ledger entry is a question or a
+ * remembered rule, neither of which a terminal guard can match to this exact
+ * command with the hook's complete context. The answer a guard honors is the
+ * dialog's single-use file (terminalAllowance.consumeTerminalAllowance).
  */
 export declare function ideConfirmedFor(ledger: {
     formatVersion?: number;
@@ -38,11 +40,17 @@ export declare function ideConfirmedFor(ledger: {
 /**
  * Node snippet for the cmd.exe guard and the POSIX checker. Defines
  * `agentTerminal()` and `ideConfirmed(line, ruleId)`; expects `fs`, `crypto`,
- * `os` and `path` to be in scope.
+ * `os` and `path` to be in scope. `ideConfirmed` is the guard's side of
+ * terminalAllowance.consumeTerminalAllowance: it reads the dialog's answer for
+ * this exact command + directory, checks it is live and (where both sides know a
+ * session) the same session's, then DELETES it — the delete is the claim, so the
+ * answer is honored once. Anything else, a pending marker included, is false.
  */
 export declare function buildAgentTerminalJs(): string;
 /**
  * PowerShell snippet for the PSReadLine guard. Defines
- * `Test-FcdAgentTerminal` and `Test-FcdIdeConfirmed -Line -RuleId`.
+ * `Test-FcdAgentTerminal` and `Test-FcdIdeConfirmed -Line -RuleId` (the same
+ * consume step as the Node snippet: read the dialog's answer for this exact
+ * command + directory, check it, delete it — once).
  */
 export declare function buildAgentTerminalPs(): string;

package/dist/agentTerminal.js

@@ -46,16 +46,20 @@ exports.buildAgentTerminalPs = buildAgentTerminalPs;
  * keyboard. When an AI agent drives the terminal (Cursor's agent-exec shell,
  * Claude Code's Bash tool, ...) the agent is the one that would type the
  * answer — so an ask there is not a control at all. Rule: in an agent-driven
- * terminal the guard never offers y/N. It honors the answer the developer
- * gave in the IDE, or delegates an explicitly marked exact-command handoff
- * to the IDE permission gate. Handoffs are never recorded as consent. Otherwise
- * blocks with a message that says where the question is answered.
+ * terminal the guard never offers y/N. It honors ONE thing: the developer's
+ * Allow, given in the FullCourtDefense dialog for this exact command and
+ * directory, which the dialog leaves as a single-use answer (terminalAllowance.ts)
+ * that the guard consumes. A PENDING ask marker — the hook raises it before
+ * anybody is asked, and a denied or abandoned IDE card leaves it standing — is
+ * never read as an answer (APPR-13). Otherwise the guard blocks with a message
+ * that says where the question is answered.
  *
  * Pure: no I/O. The guards render these markers + keys into their generated
  * PowerShell / Node code, and `scripts/test-agent-terminal-ask.js` pins that
  * the rendered code and this module agree.
  */
 const crypto = __importStar(require("crypto"));
+const terminalAllowance_1 = require("./terminalAllowance");
 /** Environment markers that an AI agent, not a person, is driving this terminal. */
 exports.AGENT_TERMINAL_MARKERS = [
     { name: 'FCD_AGENT_TERMINAL', equals: '1', agent: 'explicit (org / wrapper opt-in)' },
@@ -80,23 +84,25 @@ function isAgentDrivenTerminal(env = process.env) {
 exports.AGENT_TERMINAL_ASK_BLOCKED = 'an AI agent is driving this terminal, so nobody can answer this Ask here. Not executed. ' +
     'The developer answers Allow / Deny in the IDE prompt (the agent must run the command through the IDE hook), ' +
     'or runs it in their own terminal.';
-/** Shown when the IDE prompt already answered for this exact command. */
-exports.AGENT_TERMINAL_IDE_CONFIRMED = 'allowed through the IDE permission gate; confirmation is recorded by the IDE post-execution hook.';
+/** Shown when the developer already said Allow for this exact command in the FullCourtDefense dialog (one use). */
+exports.AGENT_TERMINAL_IDE_CONFIRMED = 'allowed: the developer said Allow for this exact command in the FullCourtDefense dialog (that answer is used once).';
 // ---------------------------------------------------------------------------
-// Exact command + working directory handoff keys match devConfirm v3.
-// A handoff delegates to the IDE permission gate; it is never consent.
+// Exact command + working directory keys match devConfirm v3: the dialog's
+// Allow is stored under the key the hook's marker had (terminalAllowance.ts).
 // ---------------------------------------------------------------------------
 const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
-/** Pending-marker key the IDE hook wrote for this shell command (see devConfirm.pendingKey). */
+/** Key of this shell command + directory: the hook's marker key (see devConfirm.pendingKey), and the file name of the dialog's single-use answer (terminalAllowance.ts). */
 function ideShellPendingKey(command, cwd = process.cwd()) {
     return sha256(JSON.stringify(['shell', 'shell', sha256(`args-v3:${JSON.stringify({ command, cwd })}`)]));
 }
-/** Maximum lifetime of an exact-command IDE permission handoff (not consent). */
+/** How long a pending marker lives (the ledger's TTL). Kept for the callers that name it; a pending marker has not been answered and the guards no longer read it. */
 exports.IDE_CONFIRMATION_WINDOW_MS = 10 * 60_000;
 /**
- * Pure decision over a parsed dev-confirm ledger: did the IDE prompt already
- * answer for this command / rule? Used by the in-process tests and mirrored
- * by the generated guard code below.
+ * Pure decision over a parsed dev-confirm ledger: did the developer already
+ * answer for this command / rule? Never — a ledger entry is a question or a
+ * remembered rule, neither of which a terminal guard can match to this exact
+ * command with the hook's complete context. The answer a guard honors is the
+ * dialog's single-use file (terminalAllowance.consumeTerminalAllowance).
  */
 function ideConfirmedFor(ledger, command, ruleId, now = Date.now(), sessionId) {
     // Terminal guards lack the hook's complete policy/context snapshot. They
@@ -109,24 +115,30 @@ function ideConfirmedFor(ledger, command, ruleId, now = Date.now(), sessionId) {
 /**
  * Node snippet for the cmd.exe guard and the POSIX checker. Defines
  * `agentTerminal()` and `ideConfirmed(line, ruleId)`; expects `fs`, `crypto`,
- * `os` and `path` to be in scope.
+ * `os` and `path` to be in scope. `ideConfirmed` is the guard's side of
+ * terminalAllowance.consumeTerminalAllowance: it reads the dialog's answer for
+ * this exact command + directory, checks it is live and (where both sides know a
+ * session) the same session's, then DELETES it — the delete is the claim, so the
+ * answer is honored once. Anything else, a pending marker included, is false.
  */
 function buildAgentTerminalJs() {
     const markers = JSON.stringify(exports.AGENT_TERMINAL_MARKERS.map(m => ({ n: m.name, v: m.equals })));
     return [
-        `// Agent-driven terminal: never offer y/N to an AI agent (it would answer itself). Honor the IDE prompt's answer for this exact command, else block.`,
+        `// Agent-driven terminal: never offer y/N to an AI agent (it would answer itself). Honor the developer's Allow in the FullCourtDefense dialog for this exact command (single use), else block.`,
         `const AGENT_MARKERS=${markers};`,
         `function agentTerminal(){const e=process.env;return AGENT_MARKERS.some(m=>m.v!==undefined?e[m.n]===m.v:(typeof e[m.n]==='string'&&e[m.n].length>0));}`,
-        `const IDE_WINDOW_MS=${exports.IDE_CONFIRMATION_WINDOW_MS};`,
+        `const ALLOW_MAX_MS=${terminalAllowance_1.TERMINAL_ALLOWANCE_TTL_MS};`,
         `function sha(s){return crypto.createHash('sha256').update(s).digest('hex');}`,
-        `function ideConfirmed(line,ruleId){try{const ledger=JSON.parse(fs.readFileSync(path.join(os.homedir(),'.fullcourtdefense','dev-confirm.json'),'utf8'));if(ledger.formatVersion!==3)return false;const now=Date.now();const pk=sha(JSON.stringify(['shell','shell',sha('args-v3:'+JSON.stringify({command:line,cwd:process.cwd()}))]));const session=process.env.FCD_SESSION_ID||process.env.CLAUDE_CODE_SESSION_ID||process.env.CODEX_THREAD_ID;if(!session)return false;return (ledger.pending||[]).some(p=>p&&p.permissionHandoff===true&&p.sessionId===session&&p.key===pk&&typeof p.raisedAt==='string'&&now>=Date.parse(p.raisedAt)&&now-Date.parse(p.raisedAt)<IDE_WINDOW_MS);}catch{return false;}}`,
+        `function ideConfirmed(line,ruleId){try{const pk=sha(JSON.stringify(['shell','shell',sha('args-v3:'+JSON.stringify({command:line,cwd:process.cwd()}))]));const file=path.join(os.homedir(),'.fullcourtdefense','terminal-allow',pk+'.json');let a;try{a=JSON.parse(fs.readFileSync(file,'utf8'));}catch{return false;}const now=Date.now(),at=Date.parse(a.confirmedAt),until=Date.parse(a.expiresAt);if(a.formatVersion!==1||a.key!==pk||!(now>=at&&now<until&&until-at<=ALLOW_MAX_MS))return false;const session=process.env.FCD_SESSION_ID||process.env.CLAUDE_CODE_SESSION_ID||process.env.CODEX_THREAD_ID;if(a.sessionId&&session&&a.sessionId!==session)return false;fs.unlinkSync(file);return true;}catch{return false;}}`,
         `const AGENT_ASK_BLOCKED=${JSON.stringify(exports.AGENT_TERMINAL_ASK_BLOCKED)};`,
         `const AGENT_IDE_CONFIRMED=${JSON.stringify(exports.AGENT_TERMINAL_IDE_CONFIRMED)};`,
     ].join('\n');
 }
 /**
  * PowerShell snippet for the PSReadLine guard. Defines
- * `Test-FcdAgentTerminal` and `Test-FcdIdeConfirmed -Line -RuleId`.
+ * `Test-FcdAgentTerminal` and `Test-FcdIdeConfirmed -Line -RuleId` (the same
+ * consume step as the Node snippet: read the dialog's answer for this exact
+ * command + directory, check it, delete it — once).
  */
 function buildAgentTerminalPs() {
     const markers = exports.AGENT_TERMINAL_MARKERS
@@ -134,7 +146,7 @@ function buildAgentTerminalPs() {
         .join(', ');
     return [
         `# Agent-driven terminal: never offer y/N to an AI agent (it would answer itself).`,
-        `# Honor the IDE prompt's answer for this exact command, else block.`,
+        `# Honor the developer's Allow in the FullCourtDefense dialog for this exact command (single use), else block.`,
         `$global:FcdAgentMarkers = @(${markers})`,
         `$global:FcdAgentAskBlocked = '${exports.AGENT_TERMINAL_ASK_BLOCKED.replace(/'/g, "''")}'`,
         `$global:FcdAgentIdeConfirmed = '${exports.AGENT_TERMINAL_IDE_CONFIRMED.replace(/'/g, "''")}'`,
@@ -152,22 +164,22 @@ function buildAgentTerminalPs() {
         `}`,
         `function global:Test-FcdIdeConfirmed { param([string]$Line, [string]$RuleId)`,
         `  try {`,
-        `    $ledgerPath = Join-Path $HOME '.fullcourtdefense\\dev-confirm.json'`,
-        `    if (-not (Test-Path -LiteralPath $ledgerPath)) { return $false }`,
-        `    $ledger = Get-Content -LiteralPath $ledgerPath -Raw | ConvertFrom-Json`,
-        `    if ($ledger.formatVersion -ne 3) { return $false }`,
-        `    $session = $env:FCD_SESSION_ID; if (-not $session) { $session = $env:CLAUDE_CODE_SESSION_ID }; if (-not $session) { $session = $env:CODEX_THREAD_ID }; if (-not $session) { return $false }`,
-        `    $now = [DateTimeOffset]::UtcNow`,
         `    $argsJson = ConvertTo-Json -Compress -InputObject ([ordered]@{command=$Line;cwd=(Get-Location).ProviderPath})`,
         `    $digest = Get-FcdSha256 ('args-v3:' + $argsJson)`,
         `    $pk = Get-FcdSha256 (ConvertTo-Json -Compress -InputObject @('shell','shell',$digest))`,
-        `    foreach ($p in @($ledger.pending)) {`,
-        `      if ($null -ne $p -and $p.permissionHandoff -eq $true -and $p.sessionId -ceq $session -and $p.key -ceq $pk -and $p.raisedAt) {`,
-        `        $raised = if ($p.raisedAt -is [DateTime]) { [DateTimeOffset]$p.raisedAt } else { [DateTimeOffset]::Parse([string]$p.raisedAt, [Globalization.CultureInfo]::InvariantCulture) }`,
-        `        $age = $now - $raised`,
-        `        if ($age.TotalMilliseconds -ge 0 -and $age.TotalMilliseconds -lt ${exports.IDE_CONFIRMATION_WINDOW_MS}) { return $true }`,
-        `      }`,
-        `    }`,
+        `    $file = Join-Path $HOME ('.fullcourtdefense\\terminal-allow\\' + $pk + '.json')`,
+        `    if (-not (Test-Path -LiteralPath $file)) { return $false }`,
+        `    $a = Get-Content -LiteralPath $file -Raw | ConvertFrom-Json`,
+        `    if ($a.formatVersion -ne 1 -or $a.key -cne $pk -or -not $a.confirmedAt -or -not $a.expiresAt) { return $false }`,
+        `    $now = [DateTimeOffset]::UtcNow`,
+        `    $at = if ($a.confirmedAt -is [DateTime]) { [DateTimeOffset]$a.confirmedAt } else { [DateTimeOffset]::Parse([string]$a.confirmedAt, [Globalization.CultureInfo]::InvariantCulture) }`,
+        `    $until = if ($a.expiresAt -is [DateTime]) { [DateTimeOffset]$a.expiresAt } else { [DateTimeOffset]::Parse([string]$a.expiresAt, [Globalization.CultureInfo]::InvariantCulture) }`,
+        `    if ($now -lt $at -or $now -ge $until -or ($until - $at).TotalMilliseconds -gt ${terminalAllowance_1.TERMINAL_ALLOWANCE_TTL_MS}) { return $false }`,
+        `    $session = $env:FCD_SESSION_ID; if (-not $session) { $session = $env:CLAUDE_CODE_SESSION_ID }; if (-not $session) { $session = $env:CODEX_THREAD_ID }`,
+        `    if ($a.sessionId -and $session -and $a.sessionId -cne $session) { return $false }`,
+        `    # The delete is the claim: if another guard took the answer first this throws and the line is NOT allowed.`,
+        `    Remove-Item -LiteralPath $file -Force -ErrorAction Stop`,
+        `    return $true`,
         `  } catch { }`,
         `  return $false`,
         `}`,

package/dist/askDialog.js

@@ -32,6 +32,7 @@ exports.resolveAskWithDialog = resolveAskWithDialog;
  * grant is bound to that rule's hash, and nothing here re-evaluates the action.
  */
 const devConfirm_1 = require("./devConfirm");
+const terminalAllowance_1 = require("./terminalAllowance");
 const telemetry_1 = require("./telemetry");
 const actionIdentity_1 = require("./actionIdentity");
 const hookIo_1 = require("./hookIo");
@@ -236,6 +237,12 @@ async function resolveAskWithDialog(verdict, options = {}) {
         // The MCP gateway sees this exact call next; do not ask the person twice.
         if (envelope.event === 'mcp')
             (0, devConfirm_1.recordConfirmedAction)(envelope.toolName, envelope.argsDigest);
+        // APPR-13: the same for an agent-driven TERMINAL. If the IDE now runs this exact command in a terminal
+        // guarded by an `ask` rule, the guard must not ask again (an agent would answer itself) and must not
+        // block what the developer just allowed: ONE single-use answer for this command + directory. Only
+        // this Allow writes it — never the pending marker, a denied card or a timeout.
+        if (envelope.event === 'shell')
+            (0, terminalAllowance_1.recordTerminalAllowance)((0, devConfirm_1.pendingKey)(envelope.event, envelope.toolName, envelope.argsDigest), envelopeIdentity(envelope).sessionId);
         (0, telemetry_1.spoolEvent)({
             decision: 'allow',
             toolName: envelope.toolName,

package/dist/callerEnv.d.ts

@@ -80,6 +80,12 @@ export declare function envFlag(value: string | undefined): boolean;
 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;
+/**
+ * The scan / config-rewrite / machine-identity containment (testSandbox.ts)
+ * when a suite set FCD_TEST_SANDBOX_ROOT, else undefined. Loaded only then, so
+ * it never joins a hook's module graph on an install.
+ */
+export declare function testSandboxContainment(env?: NodeJS.ProcessEnv): typeof import('./testSandbox') | undefined;
 /** CI / pipeline environments — no human at a keyboard. Shared by hooks and discovery. */
 export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
 /**

package/dist/callerEnv.js

@@ -11,6 +11,7 @@ exports.ideWaitCutoff = ideWaitCutoff;
 exports.envFlag = envFlag;
 exports.testRunMarkers = testRunMarkers;
 exports.noRealUiUnderTest = noRealUiUnderTest;
+exports.testSandboxContainment = testSandboxContainment;
 exports.isCiEnvironment = isCiEnvironment;
 exports.isHumanPresent = isHumanPresent;
 const async_hooks_1 = require("async_hooks");
@@ -183,6 +184,14 @@ function testRunMarkers(env = process.env) {
 function noRealUiUnderTest(env = process.env) {
     return envFlag(env.FCD_TEST_NO_REAL_DIALOG) || !!env.FCD_TEST_SANDBOX_ROOT;
 }
+/**
+ * The scan / config-rewrite / machine-identity containment (testSandbox.ts)
+ * when a suite set FCD_TEST_SANDBOX_ROOT, else undefined. Loaded only then, so
+ * it never joins a hook's module graph on an install.
+ */
+function testSandboxContainment(env = process.env) {
+    return env.FCD_TEST_SANDBOX_ROOT ? require('./testSandbox') : undefined;
+}
 /** CI / pipeline environments — no human at a keyboard. Shared by hooks and discovery. */
 function isCiEnvironment(env = callerEnv()) {
     return env.GITHUB_ACTIONS === 'true'

package/dist/commands/cmdGuard.js

@@ -168,7 +168,7 @@ function buildGuardJs(nodePath, cliEntry) {
         `// made the user's terminal wait for a full CLI process INCLUDING the network`,
         `// flush after every finding. Monitor mode must never add synchronous latency.`,
         `// developer: '' | 'confirmed' | 'remembered' | 'declined' | 'timeout' | 'ide' | 'agent-terminal' — the "ask" outcome, reported with the same facts as an IDE prompt.`,
-        `function spoolEvent(rule,line,decision,developer){try{const ev=line.trim();const evidence=ev.length>180?ev.slice(0,180)+'...':ev;let reason='Shell guard: '+rule.reason;if(developer==='confirmed')reason='developer confirmed in terminal prompt — '+reason;else if(developer==='remembered')reason='developer confirmed earlier in this cmd window (session memory) — '+reason;else if(developer==='declined')reason='developer declined in terminal prompt — '+reason;else if(developer==='timeout')reason='developer confirmation not given (terminal prompt timed out) — '+reason;else if(developer==='ide')reason='delegated to the IDE permission gate (confirmation recorded by post-hook) — '+reason;else if(developer==='agent-terminal')reason='ask cannot be answered in an agent-driven terminal (no IDE confirmation) — '+reason;const event={eventId:crypto.randomUUID(),type:'verdict',decision,toolName:'cmd_terminal',operation:'shell_command',reason,ruleId:rule.id,category:rule.category,severity:rule.severity,source:rule.source,evidence,occurredAt:new Date().toISOString()};if(developer){event.approvalScope='developer';if(developer==='confirmed'||developer==='remembered')event.approvedBy='developer';}fs.appendFileSync(SPOOL_PATH,JSON.stringify(event)+'\\n',{encoding:'utf8',mode:0o600});if(fs.existsSync(NODE_PATH)&&fs.existsSync(CLI_ENTRY)){const c=spawn(NODE_PATH,[CLI_ENTRY,'flush-spool','--heartbeat','true'],{detached:true,stdio:'ignore',windowsHide:true});c.unref();}}catch{}}`,
+        `function spoolEvent(rule,line,decision,developer){try{const ev=line.trim();const evidence=ev.length>180?ev.slice(0,180)+'...':ev;let reason='Shell guard: '+rule.reason;if(developer==='confirmed')reason='developer confirmed in terminal prompt — '+reason;else if(developer==='remembered')reason='developer confirmed earlier in this cmd window (session memory) — '+reason;else if(developer==='declined')reason='developer declined in terminal prompt — '+reason;else if(developer==='timeout')reason='developer confirmation not given (terminal prompt timed out) — '+reason;else if(developer==='ide')reason='the developer said Allow in the FullCourtDefense dialog, used once for this exact command — '+reason;else if(developer==='agent-terminal')reason='ask cannot be answered in an agent-driven terminal (no IDE confirmation) — '+reason;const event={eventId:crypto.randomUUID(),type:'verdict',decision,toolName:'cmd_terminal',operation:'shell_command',reason,ruleId:rule.id,category:rule.category,severity:rule.severity,source:rule.source,evidence,occurredAt:new Date().toISOString()};if(developer){event.approvalScope='developer';if(developer==='confirmed'||developer==='remembered')event.approvedBy='developer';}fs.appendFileSync(SPOOL_PATH,JSON.stringify(event)+'\\n',{encoding:'utf8',mode:0o600});if(fs.existsSync(NODE_PATH)&&fs.existsSync(CLI_ENTRY)){const c=spawn(NODE_PATH,[CLI_ENTRY,'flush-spool','--heartbeat','true'],{detached:true,stdio:'ignore',windowsHide:true});c.unref();}}catch{}}`,
         `function askRemembered(ruleId){try{const m=JSON.parse(fs.readFileSync(ASK_MEMORY_PATH,'utf8'));const until=m&&m[ruleId];return typeof until==='number'&&until>Date.now();}catch{return false;}}`,
         `function rememberAsk(ruleId){try{let m={};try{m=JSON.parse(fs.readFileSync(ASK_MEMORY_PATH,'utf8'))||{};}catch{}m[ruleId]=Date.now()+ASK_REMEMBER_MS;fs.mkdirSync(path.dirname(ASK_MEMORY_PATH),{recursive:true});fs.writeFileSync(ASK_MEMORY_PATH,JSON.stringify(m),{encoding:'utf8',mode:0o600});}catch{}}`,
         (0, agentTerminal_1.buildAgentTerminalJs)(),

package/dist/commands/daemon.js

@@ -146,9 +146,20 @@ const BUNDLE_FETCH_TIMEOUT_MS = envMs('FCD_DAEMON_BUNDLE_TIMEOUT_MS', 10_000);
  * the work each poll actually does — a bundle poll is a 10s 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.
+ * The heartbeat is ONLY the liveness report: the integrity check (a walk of
+ * the scan roots on a loaded laptop) runs apart from it, with its own signal.
  */
 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);
+/** An integrity check (including its repair) slower than this is a `housekeeping_slow` distress signal. */
+const INTEGRITY_SLOW_MS = envMs('FCD_DAEMON_INTEGRITY_SLOW_MS', 60_000);
+/**
+ * The heartbeat's integrity check re-reads the project configs the last
+ * scan-root walk found when that walk is no older than this (three rescan
+ * periods): the rescan is the one deep walk per cycle, and it is what finds a
+ * new config (and repairs it as a discovery).
+ */
+const INTEGRITY_WALK_REUSE_MS = envMs('FCD_DAEMON_WALK_REUSE_MS', 3 * RESCAN_INTERVAL_MS);
 /**
  * Wake-from-sleep detection. Timers are the only awake clock we have: a beat
  * that observes far more wall time than its own interval proves the machine
@@ -874,6 +885,17 @@ async function runDaemon(args, config) {
     let observedConfigurations = new Map();
     let refreshPending = false;
     let lastIntegrityHealFailureAt;
+    /**
+     * The newest integrity verdict this daemon computed by any path (a protection
+     * pass's inspection, the heartbeat's check, a post-repair verification). The
+     * liveness report carries it without waiting for a new check.
+     */
+    let lastIntegrity;
+    let integrityCheckInFlight = false;
+    const noteIntegrity = (report) => {
+        lastIntegrity = report;
+        return report;
+    };
     let suspended = false;
     let stopped = false;
     const executingActionIds = new Set();
@@ -1025,7 +1047,7 @@ async function runDaemon(args, config) {
                 void (async () => {
                     let verified = false;
                     try {
-                        verified = !repairFailed && (await housekeeping.run({ op: 'integrity', requireDaemon: true })).ok;
+                        verified = !repairFailed && noteIntegrity(await housekeeping.run({ op: 'integrity', requireDaemon: true })).ok;
                     }
                     catch { /* cannot verify */ }
                     if (stopped || suspended)
@@ -1087,8 +1109,12 @@ async function runDaemon(args, config) {
         }
         repairInFlight = (async () => {
             const pass = `repair-${++passSeq}`;
+            // The newest verdict this pass saw: a pass that fails leaves its config
+            // as the last inspection found it, and that is what a report must say.
+            let inspected;
+            const inspect = async () => (inspected = await inspectProtection(pass));
             try {
-                const before = await inspectProtection(pass);
+                const before = await inspect();
                 // The inspection ran in the housekeeping worker; an admin suspension
                 // (or shutdown) may have arrived meanwhile. A suspended machine is not
                 // re-protected, whenever the pass was asked for.
@@ -1102,6 +1128,7 @@ async function runDaemon(args, config) {
                 // content change still runs the full idempotent repair pipeline: the
                 // integrity summary does not cover every hook migration/companion.
                 if ((cause === 'integrity' || cause === 'discovery') && !repairFailed && !(0, integrity_1.hasHealableIntegrityReason)(before.reasons)) {
+                    noteIntegrity(before);
                     reportProtectionHealth(before.ok && !repairFailed);
                     return before;
                 }
@@ -1136,8 +1163,10 @@ async function runDaemon(args, config) {
                     else
                         repairWindowKnown = false;
                     await refreshWatchTargets(pass);
-                    integrity = await inspectProtection(pass);
-                    log(`Re-protection pass complete (Cursor hooks ${repaired.cursorHooksHealthy ? 'healthy' : 'unhealthy'}, Claude hooks ${repaired.claudeHooksHealthy ? 'healthy' : 'unhealthy'}).`);
+                    integrity = await inspect();
+                    // F-08: a hook file that is not valid JSON is left alone (it holds the developer's settings; a backup copy was kept) and named here.
+                    const hookState = (healthy, unreadable) => unreadable ? 'unreadable, left untouched' : healthy ? 'healthy' : 'unhealthy';
+                    log(`Re-protection pass complete (Cursor hooks ${hookState(repaired.cursorHooksHealthy, repaired.cursorHooksUnreadable)}, Claude hooks ${hookState(repaired.claudeHooksHealthy, repaired.claudeHooksUnreadable)}).`);
                     if (!(0, integrity_1.hasHealableIntegrityReason)(integrity.reasons) || suspended || stopped)
                         break;
                     if (attempt === 1)
@@ -1150,6 +1179,9 @@ async function runDaemon(args, config) {
                 const external = changedFiles.filter(file => !wrote.includes(file));
                 noteRepairWrites(wrote);
                 repairFailed = false;
+                // The verdict after the pass, never the one before it: a heartbeat in
+                // between must not report damage this pass is already repairing.
+                noteIntegrity(integrity);
                 log(`Re-protection verified: ${integrity.ok ? 'healthy' : 'incomplete'}; `
                     + (repairWindowKnown
                         ? `wrote ${wrote.length} config file(s)${namedFiles(wrote)}; external changes during the pass: ${external.length}${namedFiles(external)}`
@@ -1165,6 +1197,8 @@ async function runDaemon(args, config) {
             catch (error) {
                 repairFailed = true;
                 lastIntegrityHealFailureAt = Date.now();
+                if (inspected)
+                    noteIntegrity(inspected);
                 log(`Re-protection failed: ${error.message}`);
                 reportProtectionHealth(false);
                 // A remote repair must report its execution failure even when the
@@ -1912,21 +1946,82 @@ async function runDaemon(args, config) {
         housekeeping.stats(true);
         loopDelay.reset();
     };
-    const heartbeat = async () => {
-        (0, daemonForensics_1.touchDaemonAlive)();
-        await recoverCredentialsIfMissing();
-        if (!creds.shieldId)
-            return;
-        // Did THIS beat actually record daemon liveness upstream? `flushSpool`
-        // reports every failure by returning null and never throws, so without
-        // this flag a heartbeat that never left the machine was indistinguishable
-        // from a delivered one — and the loop happily waited a full cadence before
-        // trying again. A hook flusher holding the spool lock is not a miss: the
-        // flush op then sends this beat without the spool (housekeepingOps).
-        let reported = false;
-        let refusal;
+    /**
+     * One liveness report: the spool flush, the heartbeat itself and what only
+     * this process knows, through the housekeeping worker (spool read/rewrite,
+     * shell-audit registry probes, guard-rule refresh, EDR probe). `integrity` is
+     * the newest verdict the daemon HAS, not a new check.
+     */
+    const sendHeartbeat = async (integrity, unreportedCrash) => {
+        const shieldId = creds.shieldId;
+        if (!shieldId)
+            throw new Error('no shield configured');
+        const powershell = recoveredPowershell ?? (0, config_1.getPowershellHealth)();
+        return housekeeping.run({
+            op: 'heartbeatFlush',
+            securityAgents: true,
+            input: {
+                apiUrl: creds.apiUrl,
+                shieldId,
+                shieldKey: creds.shieldKey,
+                heartbeat: true,
+                daemon: true,
+                agentVersion: cliVersion(),
+                integrityOk: integrity?.ok,
+                integrityReasons: integrity?.reasons,
+                integrityCheckedAt: integrity?.checkedAt,
+                desktopChatGuard: (0, desktopChatGuard_1.desktopChatGuardSupported)() && (0, desktopChatGuard_1.desktopChatGuardHealthy)(),
+                powershellSpawnOk: powershell?.spawnOk,
+                powershellDecryptOk: powershell?.decryptOk,
+                powershellLanguageMode: powershell?.languageMode,
+                shieldKeySource: (recoveredTrace ?? (0, config_1.getCredentialResolutionTrace)())?.shieldKeySource,
+                distress: (0, distress_1.readDistressSnapshot)(),
+                lastCrash: unreportedCrash
+                    ? {
+                        version: unreportedCrash.version,
+                        startedAt: unreportedCrash.startedAt,
+                        lastAliveAt: unreportedCrash.lastAliveAt,
+                        detectedAt: unreportedCrash.detectedAt,
+                        detectedBy: unreportedCrash.detectedBy,
+                        cause: unreportedCrash.cause,
+                        machineBootedAt: unreportedCrash.machineBootedAt,
+                    }
+                    : undefined,
+                verdictIpc: verdictIpcHealth(),
+                housekeeping: { ...housekeeping.stats() },
+                // The detector that decides verdicts is this process's, not the worker's.
+                detectionUpdatesStatus: localDetectionUpdates_1.localDetectionUpdates.getStatus(),
+                detectorUpdatesStatus: localDetectionUpdates_1.localDetectorUpdates.getDetectorStatus(),
+            },
+        });
+    };
+    const sameIntegrity = (a, b) => !!a && !!b && a.ok === b.ok && [...a.reasons].sort().join('|') === [...b.reasons].sort().join('|');
+    /**
+     * The integrity check and its self-heal, apart from the liveness report. The
+     * check walks the scan roots when it has no recent walk to reuse, which took
+     * 16-165 s on a loaded laptop; as the first step of the heartbeat it held the
+     * report (the console's only evidence that this daemon is alive) behind it,
+     * under the heartbeat's own deadline, and a slow check surfaced as a stalled
+     * poll. `reported` is the verdict the report just carried: when the check
+     * finds a different one, the console is told right away.
+     */
+    const checkIntegrity = async (reported) => {
+        if (integrityCheckInFlight)
+            return; // the previous check is still running (a slow walk): it reports itself
+        integrityCheckInFlight = true;
+        // Only the check itself is timed: a repair in between has its own ceiling and log.
+        let checkMs = 0;
+        const check = async () => {
+            const startedAt = Date.now();
+            try {
+                return await housekeeping.run({ op: 'integrity', requireDaemon: true, reuseWalkMs: INTEGRITY_WALK_REUSE_MS });
+            }
+            finally {
+                checkMs += Date.now() - startedAt;
+            }
+        };
         try {
-            let integrity = await housekeeping.run({ op: 'integrity', requireDaemon: true });
+            let integrity = await check();
             // Recovery outside our repair pass (for example a manual fix) also clears
             // the old failure's backoff. It must not suppress an unrelated later gap.
             // An execution error can concern a component outside this summary (e.g.
@@ -1945,59 +2040,63 @@ async function runDaemon(args, config) {
                     || Date.now() - lastIntegrityHealFailureAt >= INTEGRITY_HEAL_COOLDOWN_MS)
                 && (repairFailed || (0, integrity_1.hasHealableIntegrityReason)(integrity.reasons))) {
                 const repaired = await reprotect(integrity.reasons, 'integrity');
-                integrity = await housekeeping.run({ op: 'integrity', requireDaemon: true });
+                integrity = await check();
                 if (repaired) {
                     log(integrity.ok
                         ? 'Integrity self-heal: protection restored.'
                         : `Integrity self-heal: still failing (${integrity.reasons.join(', ')}) — reported for support.`);
                 }
             }
+            noteIntegrity(integrity);
             if (!suspended)
                 reportProtectionHealth(integrity.ok && !repairFailed);
+            if (!integrity.ok)
+                log(`Integrity warning: ${integrity.reasons.join(', ')}.`);
+            if (checkMs > INTEGRITY_SLOW_MS) {
+                log(`Integrity check took ${Math.round(checkMs / 1000)}s (longer than ${Math.round(INTEGRITY_SLOW_MS / 1000)}s) — local work on this machine is slow; heartbeats are not held for it.`);
+                (0, distress_1.reportDistress)('integrity', distress_1.DISTRESS.HOUSEKEEPING_SLOW, `integrity check took ${Math.round(checkMs / 1000)}s; the heartbeat did not wait for it`);
+            }
+            if (!stopped && creds.shieldId && !sameIntegrity(reported, integrity)) {
+                await sendHeartbeat(integrity, undefined).catch(() => undefined);
+            }
+        }
+        catch (error) {
+            log(`Integrity check failed: ${error?.message || String(error)} — checked again on the next heartbeat.`);
+        }
+        finally {
+            integrityCheckInFlight = false;
+        }
+    };
+    const heartbeat = async () => {
+        (0, daemonForensics_1.touchDaemonAlive)();
+        await recoverCredentialsIfMissing();
+        if (!creds.shieldId)
+            return;
+        // Did THIS beat actually record daemon liveness upstream? `flushSpool`
+        // reports every failure by returning null and never throws, so without
+        // this flag a heartbeat that never left the machine was indistinguishable
+        // from a delivered one — and the loop happily waited a full cadence before
+        // trying again. A hook flusher holding the spool lock is not a miss: the
+        // flush op then sends this beat without the spool (housekeepingOps).
+        let reported = false;
+        let refusal;
+        // Liveness FIRST, carrying the newest integrity verdict the daemon has.
+        // The integrity check follows on its own (checkIntegrity) and never holds
+        // this report: the flush runs on the spare housekeeping worker when the
+        // main one is inside a walk.
+        const carried = lastIntegrity;
+        let checkStarted = false;
+        const startCheck = () => {
+            if (checkStarted)
+                return;
+            checkStarted = true;
+            void checkIntegrity(carried);
+        };
+        try {
             // Report a previous daemon's unclean death exactly once.
             const crash = (0, daemonForensics_1.readPostmortem)();
             const unreportedCrash = crash && !crash.reportedAt ? crash : undefined;
-            const powershell = recoveredPowershell ?? (0, config_1.getPowershellHealth)();
-            // The flush (spool read/rewrite, shell-audit registry probes, guard-rule
-            // refresh, EDR probe) runs in the housekeeping worker; what only this
-            // process knows travels with it.
-            const { result, failure } = await housekeeping.run({
-                op: 'heartbeatFlush',
-                securityAgents: true,
-                input: {
-                    apiUrl: creds.apiUrl,
-                    shieldId: creds.shieldId,
-                    shieldKey: creds.shieldKey,
-                    heartbeat: true,
-                    daemon: true,
-                    agentVersion: cliVersion(),
-                    integrityOk: integrity.ok,
-                    integrityReasons: integrity.reasons,
-                    integrityCheckedAt: integrity.checkedAt,
-                    desktopChatGuard: (0, desktopChatGuard_1.desktopChatGuardSupported)() && (0, desktopChatGuard_1.desktopChatGuardHealthy)(),
-                    powershellSpawnOk: powershell?.spawnOk,
-                    powershellDecryptOk: powershell?.decryptOk,
-                    powershellLanguageMode: powershell?.languageMode,
-                    shieldKeySource: (recoveredTrace ?? (0, config_1.getCredentialResolutionTrace)())?.shieldKeySource,
-                    distress: (0, distress_1.readDistressSnapshot)(),
-                    lastCrash: unreportedCrash
-                        ? {
-                            version: unreportedCrash.version,
-                            startedAt: unreportedCrash.startedAt,
-                            lastAliveAt: unreportedCrash.lastAliveAt,
-                            detectedAt: unreportedCrash.detectedAt,
-                            detectedBy: unreportedCrash.detectedBy,
-                            cause: unreportedCrash.cause,
-                            machineBootedAt: unreportedCrash.machineBootedAt,
-                        }
-                        : undefined,
-                    verdictIpc: verdictIpcHealth(),
-                    housekeeping: { ...housekeeping.stats() },
-                    // The detector that decides verdicts is this process's, not the worker's.
-                    detectionUpdatesStatus: localDetectionUpdates_1.localDetectionUpdates.getStatus(),
-                    detectorUpdatesStatus: localDetectionUpdates_1.localDetectorUpdates.getDetectorStatus(),
-                },
-            });
+            const { result, failure } = await sendHeartbeat(carried, unreportedCrash);
             reported = result !== null;
             if (!reported)
                 refusal = failure;
@@ -2007,11 +2106,11 @@ async function runDaemon(args, config) {
                 (0, daemonForensics_1.markPostmortemReported)();
             if (result && result.accepted > 0)
                 log(`Heartbeat: flushed ${result.accepted} spooled event(s).`);
-            if (!integrity.ok)
-                log(`Integrity warning: ${integrity.reasons.join(', ')}.`);
+            startCheck();
             await uploadLogTail();
         }
         catch { /* spool stays on disk for the next tick */ }
+        startCheck(); // a report that failed to go out never skips the integrity check
         // Settle any in-flight upgrade_cli action (success once the new build is
         // live, failure when the target never arrived). Runs BEFORE the failure
         // signal below so a lost heartbeat can never strand a pending upgrade.

package/dist/commands/deterministicGuard.js

@@ -4401,8 +4401,26 @@ function scanDeterministicToolCall(toolName, toolArgs, options) {
         return tamper;
     return other;
 }
+/**
+ * Could ANY finding for this candidate survive the context gates in
+ * scanBuiltInRules? A finding is kept only for a command, or — for a sensitive
+ * path, a metadata endpoint, a honeypot decoy — where the string can act: a
+ * path argument, a request, an outbound call. Inert text (the content of a file
+ * write or edit, a note an MCP tool stores) can keep none, so scanning it only
+ * produces findings the gates then drop. The matchers cost O(size): a 2 MB file
+ * write held the daemon's verdict loop for 3-5 s (MON-PERF-02). The gates and
+ * this check read the same helpers, so a verdict never changes.
+ */
+function findingCanBeKept(toolName, candidate, outbound) {
+    return isCommandContext(toolName, candidate)
+        || isActionableContext(toolName, candidate)
+        || isMetadataRequestContext(toolName, candidate)
+        || outbound;
+}
 function scanBuiltInRules(toolName, toolArgs, candidates, outbound, options) {
     for (const candidate of candidates) {
+        if (!findingCanBeKept(toolName, candidate, outbound))
+            continue;
         const finding = scanTextValue(toolName, candidate.value, options, isCommandContext(toolName, candidate));
         if (!finding)
             continue;

package/dist/commands/discover.d.ts

@@ -69,6 +69,7 @@ export interface DesktopDiscoveryHost {
     /** True when the scan ran on an ephemeral CI runner (GitHub Actions, GitLab, etc.) — not a user machine. */
     isCi?: boolean;
 }
+export declare function redactCommandArgs(args: string[] | undefined): string[];
 /**
  * Which credential is missing and the most likely reason — diagnosability for
  * remote fleet machines where only the daemon-captured stderr is visible.