fullcourtdefense-cli 1.26.4 → 1.26.6

package/dist/commands/mcpGateway.js

@@ -236,6 +236,7 @@ function resolveGatewayConfig(args, config, defaults = {}) {
         approvalTimeoutMs: Number(args.approvalTimeoutMs) > 0 ? Number(args.approvalTimeoutMs) : 60_000,
         approvalPollMs: Math.max(1000, Number(args.approvalPollMs) > 0 ? Number(args.approvalPollMs) : 3000),
         scanResponse: args.scanResponse === 'true',
+        scanResponseExplicit: args.scanResponse !== undefined,
         failClosed: args.failClosed !== 'false',
         failClosedExplicit: args.failClosed !== undefined,
     };
@@ -342,6 +343,33 @@ function contentToText(result) {
         return String(result);
     }
 }
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Text a response-side deterministic scan must see. contentToText() only reads
+ * `type:'text'` items — a secret riding a non-text shape (resource blob,
+ * structuredContent, extra result fields) would bypass the scan entirely. The
+ * scan input is the readable text PLUS the full JSON serialization when the
+ * result carries more than plain text (the text stays first and verbatim so
+ * multi-line patterns keep matching).
+ */
+function responseScanText(result) {
+    const text = contentToText(result);
+    if (typeof result === 'string')
+        return text;
+    const serialized = safeStringify(result);
+    // All-text results serialize to roughly the text plus JSON scaffolding; only
+    // append when the serialization carries meaningfully more payload.
+    if (serialized && serialized.length > text.length + 64)
+        return `${text}\n${serialized}`;
+    return text;
+}
 /**
  * Redact mask-action secrets from an MCP tool result IN PLACE of blocking it.
  * Only the shapes contentToText() reads are rewritable (plain string, text
@@ -373,29 +401,86 @@ function maskToolResult(result, maskFindings) {
             };
         }
     }
-    // Fail-strict verification: every masked secret must be gone from what a
-    // client would actually read out of this result.
-    const remaining = contentToText(masked);
-    const fullyMasked = secrets.every(({ secret }) => !remaining.includes(secret));
+    // Fail-strict verification: every masked secret must be gone from the WHOLE
+    // result — not just the text items a client usually reads. A secret hiding
+    // in a non-text shape (resource blob, structuredContent, extra fields) must
+    // flip fullyMasked=false so enforce mode blocks instead of leaking it. The
+    // JSON-escaped form is checked too (quotes/backslashes in the secret would
+    // otherwise dodge the serialized comparison).
+    const remaining = `${contentToText(masked)}\n${safeStringify(masked)}`;
+    const fullyMasked = secrets.every(({ secret }) => !remaining.includes(secret) && !remaining.includes(JSON.stringify(secret).slice(1, -1)));
     return { masked, fullyMasked };
 }
+/** Line-buffer hard cap: a downstream emitting one endless line must not OOM the proxy. */
+const MAX_LINE_BUFFER_BYTES = 32 * 1024 * 1024;
+/** cmd.exe metacharacters that would change meaning inside a shell:true spawn. */
+const CMD_SHELL_METACHARS = /[&|<>^%!"\r\n]/;
+/**
+ * Resolve a bare Windows command through PATH + PATHEXT (what a shell would
+ * do) so the gateway can spawn the real target with shell:false. Returns
+ * undefined when nothing resolves.
+ */
+function resolveWindowsCommand(command) {
+    if (path.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+        return fs.existsSync(command) ? command : undefined;
+    }
+    const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+    const exts = path.extname(command)
+        ? ['']
+        : (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = path.join(dir, command + ext.toLowerCase());
+            try {
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
+            catch { /* unreadable PATH entry */ }
+        }
+    }
+    return undefined;
+}
+/**
+ * Spawn the downstream WITHOUT an interpreting shell whenever possible.
+ * shell:true on every Windows spawn (the old behavior) let metacharacters in
+ * a workspace-supplied command/args run arbitrary cmd.exe syntax. Now:
+ *   - real executables (.exe/.com, or anything non-Windows) spawn shell:false;
+ *   - .cmd/.bat shims genuinely need cmd.exe — those spawn shell:true only
+ *     after the command AND args are checked for shell metacharacters.
+ */
+function spawnDownstream(command, args) {
+    if (process.platform !== 'win32') {
+        return (0, child_process_1.spawn)(command, args, { stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    }
+    const resolved = resolveWindowsCommand(command);
+    const target = resolved || command;
+    const needsShell = /\.(cmd|bat)$/i.test(target) || !resolved;
+    if (!needsShell) {
+        return (0, child_process_1.spawn)(target, args, { stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    }
+    for (const part of [command, ...args]) {
+        if (CMD_SHELL_METACHARS.test(part)) {
+            throw new Error(`Downstream MCP command contains shell metacharacters and cannot be run safely through cmd.exe: ${part.slice(0, 120)}`);
+        }
+    }
+    return (0, child_process_1.spawn)(target, args, { stdio: ['pipe', 'pipe', 'pipe'], shell: true });
+}
 class StdioMcpClient {
+    onClosed;
     child;
     buffer = '';
     nextId = 1;
     pending = new Map();
-    constructor(command, args) {
+    constructor(command, args, onClosed) {
+        this.onClosed = onClosed;
         if (!command)
             throw new Error('Missing downstream MCP command. Pass --mcp-command.');
-        this.child = (0, child_process_1.spawn)(command, args, {
-            stdio: ['pipe', 'pipe', 'pipe'],
-            shell: process.platform === 'win32',
-        });
+        this.child = spawnDownstream(command, args);
         this.child.stdout.setEncoding('utf8');
         this.child.stdout.on('data', chunk => this.onData(chunk));
         this.child.stderr.on('data', chunk => process.stderr.write(String(chunk)));
-        this.child.on('error', error => this.rejectAll(error));
-        this.child.on('exit', code => this.rejectAll(new Error(`Downstream MCP server exited (${code ?? 'signal'}).`)));
+        this.child.on('error', error => { this.rejectAll(error); this.onClosed?.(); });
+        this.child.on('exit', code => { this.rejectAll(new Error(`Downstream MCP server exited (${code ?? 'signal'}).`)); this.onClosed?.(); });
     }
     async initialize() {
         await this.request('initialize', {
@@ -431,10 +516,17 @@ class StdioMcpClient {
         this.write({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
-                this.pending.delete(id);
-                reject(new Error(`MCP request timed out: ${method}`));
+                this.pending.delete(String(id));
+                // A downstream that ignores a request for a full minute is hung, not
+                // slow — kill it so the exit handler rejects everything in flight and
+                // the gateway respawns a fresh downstream on the next call.
+                try {
+                    this.child.kill();
+                }
+                catch { /* already gone */ }
+                reject(new Error(`MCP request timed out: ${method} — downstream server killed; it restarts on the next call.`));
             }, 60000);
-            this.pending.set(id, { resolve, reject, timeout });
+            this.pending.set(String(id), { resolve, reject, timeout });
         });
     }
     notify(method, params) {
@@ -447,8 +539,14 @@ class StdioMcpClient {
         this.buffer += chunk;
         while (true) {
             const lineEnd = this.buffer.indexOf('\n');
-            if (lineEnd === -1)
+            if (lineEnd === -1) {
+                // Cap the partial-line buffer: one endless line must not OOM the proxy.
+                if (this.buffer.length > MAX_LINE_BUFFER_BYTES) {
+                    this.buffer = '';
+                    process.stderr.write('[downstream] dropped an oversized partial line (buffer cap)\n');
+                }
                 return;
+            }
             const raw = this.buffer.slice(0, lineEnd).trim();
             this.buffer = this.buffer.slice(lineEnd + 1);
             if (!raw)
@@ -465,13 +563,14 @@ class StdioMcpClient {
                 process.stderr.write(`[downstream] ${raw}\n`);
                 continue;
             }
-            if (typeof message.id !== 'number')
+            // JSON-RPC ids may legally be strings — some servers echo "1" for 1.
+            if (message.id === undefined || message.id === null)
                 continue;
-            const pending = this.pending.get(message.id);
+            const pending = this.pending.get(String(message.id));
             if (!pending)
                 continue;
             clearTimeout(pending.timeout);
-            this.pending.delete(message.id);
+            this.pending.delete(String(message.id));
             if (message.error)
                 pending.reject(new Error(message.error.message || 'MCP request failed'));
             else
@@ -797,8 +896,13 @@ class McpGatewayServer {
         this.buffer += chunk;
         while (true) {
             const lineEnd = this.buffer.indexOf('\n');
-            if (lineEnd === -1)
+            if (lineEnd === -1) {
+                if (this.buffer.length > MAX_LINE_BUFFER_BYTES) {
+                    this.buffer = '';
+                    process.stderr.write('FullCourtDefense gateway: dropped an oversized partial line from the client (buffer cap)\n');
+                }
                 return;
+            }
             const raw = this.buffer.slice(0, lineEnd).trim();
             this.buffer = this.buffer.slice(lineEnd + 1);
             if (!raw)
@@ -816,7 +920,8 @@ class McpGatewayServer {
         }
     }
     async handleMessage(message) {
-        if (!message.id && message.method?.startsWith('notifications/'))
+        // id may legally be 0 or "" — only a genuinely ABSENT id marks a notification.
+        if ((message.id === undefined || message.id === null) && message.method?.startsWith('notifications/'))
             return;
         try {
             if (message.method === 'initialize') {
@@ -851,13 +956,27 @@ class McpGatewayServer {
     }
     async ensureDownstream() {
         if (!this.downstreamReady) {
-            this.downstream = this.downstreamSpec.kind === 'http'
+            const client = this.downstreamSpec.kind === 'http'
                 ? new HttpMcpClient(this.downstreamSpec.url, this.downstreamSpec.headers)
-                : new StdioMcpClient(this.downstreamSpec.command, this.downstreamSpec.args);
-            this.downstreamReady = this.downstream.initialize();
+                : new StdioMcpClient(this.downstreamSpec.command, this.downstreamSpec.args, () => this.resetDownstream(client));
+            this.downstream = client;
+            // A failed initialize must NOT poison the cached promise forever (every
+            // later call would rethrow the same startup error) — reset so the next
+            // call spawns a fresh downstream.
+            this.downstreamReady = client.initialize().catch(err => {
+                this.resetDownstream(client);
+                throw err;
+            });
         }
         await this.downstreamReady;
     }
+    /** Forget a dead/failed downstream so the next call respawns it. */
+    resetDownstream(client) {
+        if (this.downstream === client) {
+            this.downstream = undefined;
+            this.downstreamReady = undefined;
+        }
+    }
     /** Spool a locally-enforced deterministic block so it reaches Live Enforcement even offline. */
     spoolLocalFinding(finding, toolName, operation, decision = 'block') {
         (0, telemetry_1.spoolEvent)({
@@ -924,6 +1043,22 @@ class McpGatewayServer {
                     machineName: os.hostname(),
                     hotPath: true,
                 });
+                // Admin kill-switch: a suspended machine denies every tool call. This
+                // check sits OUTSIDE the source gate below — a 'default' bundle can
+                // carry suspended:true from the signed last-known-suspended marker
+                // (cache file deleted), and that must still deny.
+                if (bundle.suspended === true) {
+                    (0, telemetry_1.spoolEvent)({
+                        decision: 'block',
+                        toolName,
+                        operation: 'mcp:suspended',
+                        reason: 'Machine suspended by an administrator (kill-switch).',
+                        source: 'backend',
+                        severity: 'critical',
+                    });
+                    (0, telemetry_1.triggerFlush)(true);
+                    throw blockError('This machine is suspended by your security team — all AI agent actions are blocked. Contact your admin to resume it.');
+                }
                 if (bundle.source !== 'default') {
                     expectedPolicyHash = bundle.policyHash || bundle.version;
                     cachedPolicies = bundle.actionPolicies;
@@ -935,19 +1070,6 @@ class McpGatewayServer {
                     if (!this.gatewayConfig.failClosedExplicit && typeof bundle.failClosed === 'boolean') {
                         this.gatewayConfig.failClosed = bundle.failClosed;
                     }
-                    // Admin kill-switch: a suspended machine denies every tool call.
-                    if (bundle.suspended === true) {
-                        (0, telemetry_1.spoolEvent)({
-                            decision: 'block',
-                            toolName,
-                            operation: 'mcp:suspended',
-                            reason: 'Machine suspended by an administrator (kill-switch).',
-                            source: 'backend',
-                            severity: 'critical',
-                        });
-                        (0, telemetry_1.triggerFlush)(true);
-                        throw blockError('This machine is suspended by your security team — all AI agent actions are blocked. Contact your admin to resume it.');
-                    }
                 }
             }
             catch (err) {
@@ -955,12 +1077,18 @@ class McpGatewayServer {
                     throw err;
                 /* cached/default snapshot still applies */
             }
+            // Snapshot cache key uses the SHARED hook identity (not the gateway's
+            // configurable developerName): the daemon warms exactly one snapshot
+            // file per machine under hookSnapshotIdentity() — keying by the gateway
+            // identity produced a second, never-warmed cache file, so every gateway
+            // call risked paying the fetch timeout the daemon exists to absorb.
+            const snapshotIdentity = (0, localSafetySnapshot_1.hookSnapshotIdentity)();
             const snapshot = await (0, localSafetySnapshot_1.loadLocalSafetySnapshot)({
                 apiUrl: this.gatewayConfig.apiUrl,
                 shieldId: this.gatewayConfig.shieldId,
                 shieldKey: this.gatewayConfig.shieldKey,
-                developerName: this.gatewayConfig.developerName,
-                machineName: os.hostname(),
+                developerName: snapshotIdentity.developerName,
+                machineName: snapshotIdentity.machineName,
                 expectedPolicyHash,
                 preferCached: reportOnlyMode,
             });
@@ -1258,7 +1386,10 @@ class McpGatewayServer {
             // Response-side events must measure our scanning overhead, not the
             // tool's execution time (see restartVerdictTiming).
             (0, telemetry_1.restartVerdictTiming)();
-            const responseOutcome = (0, deterministicGuard_1.resolveDeterministicTextResponse)(contentToText(rawResult), (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
+            // responseScanText: readable text PLUS the JSON serialization when the
+            // result carries non-text shapes — a secret in a resource blob or
+            // structured field must not bypass the scan.
+            const responseOutcome = (0, deterministicGuard_1.resolveDeterministicTextResponse)(responseScanText(rawResult), (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
             for (const warning of responseOutcome.warnings) {
                 this.spoolLocalFinding(warning, toolName, operation, 'warn');
                 process.stderr.write(`FullCourtDefense warning (${warning.itemId}): ${warning.reason}\n`);
@@ -1297,6 +1428,11 @@ class McpGatewayServer {
                     }
                 }
                 rawResult = masked;
+                // Keep the fail-open snapshot in sync: if a LATER step (role limits,
+                // cloud scan) hits an unexpected bug, the top-level catch returns
+                // downstreamResult — which must be the MASKED payload, never the
+                // pre-mask original with the secret still in it.
+                downstreamResult = masked;
                 for (const finding of responseOutcome.maskFindings) {
                     this.spoolLocalFinding(finding, toolName, operation, 'mask');
                     process.stderr.write(`FullCourtDefense masked a ${finding.itemId} in the ${toolName} response.\n`);
@@ -1331,9 +1467,34 @@ class McpGatewayServer {
                     }
                 }
             }
-            const finalResult = this.gatewayConfig.scanResponse
-                ? await this.api.scanToolResponse({ toolName, operation, toolArgs, result: rawResult })
-                : rawResult;
+            // Effective cloud response scanning: explicit flag wins; otherwise the
+            // machine's mode decides — ON for block machines, OFF for monitor.
+            const effectiveScanResponse = this.gatewayConfig.scanResponseExplicit
+                ? this.gatewayConfig.scanResponse
+                : !reportOnlyMode;
+            let finalResult = rawResult;
+            if (effectiveScanResponse) {
+                try {
+                    finalResult = await this.api.scanToolResponse({ toolName, operation, toolArgs, result: rawResult });
+                }
+                catch (scanErr) {
+                    if (isBlockError(scanErr))
+                        throw scanErr; // Shield verdict — a real block
+                    // Scan API/infra failure. On an ENFORCING machine, returning the raw
+                    // response would silently skip the org's exfil scan — that is a
+                    // block, not a fail-open. Monitor machines record and pass through.
+                    const detail = scanErr instanceof Error ? scanErr.message : String(scanErr);
+                    if (!reportOnlyMode) {
+                        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName, operation, reason: `response scan unavailable (block mode): ${detail.slice(0, 200)}`, offlineEnforced: true });
+                        (0, telemetry_1.triggerFlush)(true);
+                        throw blockError(`FullCourtDefense could not scan the ${toolName} response (${detail}) and this machine enforces response scanning — response withheld. Retry once the scan service is reachable.`);
+                    }
+                    (0, telemetry_1.spoolEvent)({ decision: 'warn', toolName, operation, reason: `[monitor] response scan unavailable: ${detail.slice(0, 200)}`, offlineEnforced: true });
+                    (0, telemetry_1.triggerFlush)(false);
+                    process.stderr.write(`FullCourtDefense (monitor): response scan unavailable for ${toolName} (${detail}) — response passed through.\n`);
+                    finalResult = rawResult;
+                }
+            }
             // Post-call audit is fire-and-forget: the verdict is already made and the
             // tool already ran. Awaiting the report here held the IDE's tool response
             // hostage for the full network timeout (up to 10s) — pure perceived lag.
@@ -1358,6 +1519,33 @@ class McpGatewayServer {
             // verdicts, not the tool's own failure): a bug in our preflight or
             // response-scanning code must never break the developer's tool call.
             // One silent stderr line + one spooled event, then the real result.
+            //
+            // EXCEPT the kill-switch: "exception = allow" must not bypass an admin
+            // suspension. Mirrors the hook's failOpenOutcome contract — a suspended
+            // machine denies even when our own code crashed.
+            let suspendedOnFailOpen = false;
+            if (!isBlockError(error)) {
+                try {
+                    suspendedOnFailOpen = (0, runtimeConfig_1.isSuspendedByCache)();
+                }
+                catch { /* never throw */ }
+            }
+            if (!isBlockError(error) && suspendedOnFailOpen) {
+                try {
+                    (0, telemetry_1.spoolEvent)({
+                        decision: 'block', toolName, operation,
+                        reason: `Gateway error on a SUSPENDED machine — denied (kill-switch holds): ${message.slice(0, 200)}`,
+                        offlineEnforced: true, severity: 'critical', source: 'backend',
+                    });
+                    (0, telemetry_1.triggerFlush)(true);
+                }
+                catch { /* never throw */ }
+                return {
+                    isError: true,
+                    blocked: true,
+                    content: [{ type: 'text', text: 'This machine is suspended by your security team — all AI agent actions are blocked. Contact your admin to resume it.' }],
+                };
+            }
             if (!isBlockError(error) && downstreamRan) {
                 // Post-call scan bug: the tool already succeeded — return its result.
                 try {
@@ -1508,7 +1696,10 @@ function buildGatewayCommandArgs(gatewayConfig, downstream, options = {}) {
         '--approval-mode', gatewayConfig.approvalMode,
         '--approval-timeout-ms', String(gatewayConfig.approvalTimeoutMs),
         '--approval-poll-ms', String(gatewayConfig.approvalPollMs),
-        '--scan-response', String(gatewayConfig.scanResponse),
+        // Only bake --scan-response when the installer was given it explicitly.
+        // Otherwise the runtime decides per machine mode (block → scan on,
+        // monitor → off) instead of pinning install-time state forever.
+        ...(gatewayConfig.scanResponseExplicit ? ['--scan-response', String(gatewayConfig.scanResponse)] : []),
         // Only bake --fail-closed into the installed config when the installer was
         // given it explicitly. Otherwise the runtime gateway follows the machine's
         // server-authoritative stance from /api/cli/bundle (same as the IDE hooks).

package/dist/commands/onboard.d.ts

@@ -17,6 +17,15 @@ export interface OnboardArgs extends InstallAllArgs {
     noDaemon?: string;
     /** 'true' => skip the interactive trust disclosure (automation/MDM; the MSI consents via its own dialog). */
     acceptDisclosure?: string;
+    /**
+     * Requested enforcement mode (`--mode` / MSI `FCD_INSTALL_MODE`). The
+     * control plane deliberately owns the machine's mode — every (re-)enrollment
+     * starts in monitor and an admin promotes from the console. This flag is
+     * accepted for compatibility but only ACKNOWLEDGED: a non-monitor request
+     * prints an explicit note instead of being silently dropped, so an MDM
+     * operator who set FCD_INSTALL_MODE=block learns where mode is actually set.
+     */
+    mode?: string;
 }
 /**
  * `fullcourtdefense onboard` — the one-command path from a fresh machine to a

package/dist/commands/onboard.js

@@ -310,6 +310,13 @@ async function onboardCommand(args, config) {
     // mode so nothing in the developer's workflow breaks while the fleet baselines
     // this machine. Admins promote it to blocking mode from the fleet console.
     console.log(`${DIM}New machines start in ${RESET}${BOLD}monitor mode${RESET}${DIM} — every agent action is recorded and analyzed, nothing is blocked yet. Your admin promotes the machine to blocking mode from the fleet console once its workflow is baselined.${RESET}\n`);
+    const requestedMode = (args.mode || process.env.FCD_INSTALL_MODE || '').trim().toLowerCase();
+    if (requestedMode && requestedMode !== 'monitor') {
+        // Honest acknowledgement instead of a silently-dropped flag: enrollment is
+        // monitor-first by design (control plane owns the mode), so a requested
+        // 'block'/'shadow' does not take effect at install time.
+        console.log(`${YELLOW}Note: --mode ${requestedMode} was requested, but enrollment always starts in monitor mode — the machine's mode is managed centrally. Promote it from the fleet console after enrollment.${RESET}\n`);
+    }
     // Trust disclosure first — nothing touches the machine before consent.
     // Dry runs report the plan without changing anything, so no prompt there.
     if (!dryRun && !(await confirmTrustDisclosure(args))) {

package/dist/commands/watchdog.d.ts

@@ -4,8 +4,11 @@ import { BotGuardConfig } from '../config';
  * 5 minutes) so machine health stays observable even when the daemon itself
  * is dead. Three jobs, all best-effort, never throws, exits 0:
  *
- *   1. Liveness: is the daemon running? If not, detect + persist the unclean
- *      death post-mortem (the daemon can no longer say how it died).
+ *   1. Liveness: is the daemon RESPONSIVE — not merely "a pid exists"? A
+ *      wedged daemon (stale alive-marker + silent verdict pipe) is recycled;
+ *      a recycled pid (marker stale, no pipe endpoint at all) is treated as
+ *      dead WITHOUT touching the unrelated process now holding that pid.
+ *      Either way, detect + persist the unclean death post-mortem.
  *   2. Revival: relaunch a dead daemon (plain detached node — no shells).
  *   3. Beacon: report daemon state to the console so the dashboard can tell
  *      "daemon dead since 11:02" apart from "machine off".

package/dist/commands/watchdog.js

@@ -37,6 +37,8 @@ exports.watchdogCommand = watchdogCommand;
 const config_1 = require("../config");
 const daemon_1 = require("./daemon");
 const daemonForensics_1 = require("../daemonForensics");
+const verdictIpcClient_1 = require("../verdictIpcClient");
+const distress_1 = require("../distress");
 const machineIdentity_1 = require("../machineIdentity");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -64,10 +66,37 @@ async function watchdogCommand(args, config) {
     const state = (0, daemon_1.daemonRuntimeState)();
     let relaunched = false;
     let postmortem = (0, daemonForensics_1.readPostmortem)();
-    if (!state.alive) {
+    // Beyond "the pid exists": a wedged daemon or a recycled pid both pass a
+    // plain pid check while the machine has no working control plane. Classify
+    // with the alive-marker freshness + a verdict-pipe probe.
+    let health = state.alive ? 'healthy' : 'dead';
+    if (state.alive && state.pid) {
+        health = (0, daemonForensics_1.classifyDaemonHealth)({
+            pidAlive: true,
+            pid: state.pid,
+            marker: (0, daemonForensics_1.readAliveMarker)(),
+            staleAfterMs: (0, daemonForensics_1.daemonHungAfterMs)(),
+            pipeProbe: await (0, verdictIpcClient_1.probeVerdictServer)(1_500),
+        });
+    }
+    if (health === 'hung' && state.pid && process.env.FCD_WATCHDOG_NO_RELAUNCH !== '1') {
+        // Positive evidence this pid IS our daemon (it still owns the verdict
+        // endpoint) and it is wedged — recycle it so the relaunch below starts
+        // clean. The distress ledger survives; the fresh daemon's first heartbeat
+        // ships the story to the fleet.
+        (0, distress_1.reportDistress)('watchdog', distress_1.DISTRESS.DAEMON_HUNG, `daemon pid ${state.pid} unresponsive (alive-marker stale + verdict pipe silent) — recycled by watchdog`);
+        (0, daemon_1.forceStopPid)(state.pid);
+    }
+    // NOTE for 'pid_reused': the pid belongs to an UNRELATED process — never
+    // kill it. The daemon is simply gone; fall through to the dead path. The
+    // relaunched daemon's own startup detects the recycled pid-file owner and
+    // takes over the lock without touching that process.
+    const effectivelyDead = !state.alive || health === 'hung' || health === 'pid_reused';
+    if (effectivelyDead) {
         // The daemon is down — capture how it died BEFORE reviving it (the fresh
-        // daemon rewrites the alive marker on boot).
-        postmortem = (0, daemonForensics_1.recordUncleanDeathFromWatchdog)(daemon_1.pidIsAlive) || postmortem;
+        // daemon rewrites the alive marker on boot). For a recycled pid the
+        // marker's pid is alive but is not the daemon, so force the detection.
+        postmortem = (0, daemonForensics_1.recordUncleanDeathFromWatchdog)(health === 'pid_reused' ? () => false : daemon_1.pidIsAlive) || postmortem;
         // Revival can be disabled for tests/diagnostics; default is on.
         if (process.env.FCD_WATCHDOG_NO_RELAUNCH !== '1') {
             relaunched = (0, daemon_1.spawnDetachedDaemon)();
@@ -87,11 +116,12 @@ async function watchdogCommand(args, config) {
         shieldId: creds.shieldId,
         machineId: identity.machineId,
         agentVersion: cliVersion(),
-        daemonAlive: state.alive,
+        daemonAlive: state.alive && !effectivelyDead,
         daemonPid: state.pid,
         daemonVersion: state.version,
         daemonStartedAt: state.startedAt,
         relaunched: relaunched || undefined,
+        daemonHealth: health === 'hung' || health === 'pid_reused' ? health : undefined,
         lastCrash: crashSummary(postmortem),
     };
     const headers = { 'Content-Type': 'application/json' };

package/dist/config.js

@@ -564,7 +564,12 @@ function writeSetupConfig(target, input) {
     }
     setTopLevel('apiUrl', input.apiUrl);
     fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, `${lines.filter((line, idx, arr) => !(line === '' && arr[idx - 1] === '')).join('\n').trim()}\n`, 'utf-8');
+    // Atomic write-temp-rename: this file carries the machine's enrollment
+    // (shieldId + key location). A crash/kill mid-write must never leave a torn
+    // config — a half-written yml makes every hook 401 until manual re-enroll.
+    const tmp = `${target}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, `${lines.filter((line, idx, arr) => !(line === '' && arr[idx - 1] === '')).join('\n').trim()}\n`, 'utf-8');
+    fs.renameSync(tmp, target);
     return target;
 }
 function saveSetupConfig(input, targetPath) {

package/dist/daemonForensics.d.ts

@@ -73,5 +73,32 @@ export declare function recordUncleanDeathFromWatchdog(isPidAlive: (pid: number)
 export declare function touchDaemonAlive(): void;
 /** Record an intentional shutdown so the next boot knows this was NOT a kill. */
 export declare function recordCleanExit(reason: string): void;
+/**
+ * A pid can lie in two ways: the daemon process exists but its event loop is
+ * WEDGED (never heartbeats, never serves the pipe, never polls the control
+ * plane), or the daemon died long ago and the OS RECYCLED its pid for an
+ * unrelated process. Both look "alive" to a pid check; both mean the machine
+ * has no working control plane. The alive-marker freshness plus a verdict-pipe
+ * probe tells them apart:
+ *
+ *   marker fresh                        → healthy (heartbeats are running)
+ *   marker stale + pipe answers         → healthy (only the marker write fails)
+ *   marker stale + pipe exists, silent  → hung (kernel frees a named pipe when
+ *                                         its owner dies, so a silent endpoint
+ *                                         means a live-but-wedged owner)
+ *   marker stale + no pipe endpoint     → pid recycled (daemon is gone; do NOT
+ *                                         kill the unrelated process)
+ */
+export type DaemonHealthClass = 'dead' | 'healthy' | 'hung' | 'pid_reused' | 'indeterminate';
+/** Marker older than this is stale — 4 missed 5-minute heartbeats. */
+export declare function daemonHungAfterMs(): number;
+export declare function classifyDaemonHealth(input: {
+    pidAlive: boolean;
+    pid: number | undefined;
+    marker: DaemonAliveMarker | undefined;
+    staleAfterMs: number;
+    pipeProbe: 'responsive' | 'unresponsive' | 'no-endpoint' | 'not-probed';
+    nowMs?: number;
+}): DaemonHealthClass;
 /** Stamp the post-mortem as delivered so heartbeats stop re-sending it. */
 export declare function markPostmortemReported(): void;

package/dist/daemonForensics.js

@@ -43,6 +43,8 @@ exports.recordDaemonStart = recordDaemonStart;
 exports.recordUncleanDeathFromWatchdog = recordUncleanDeathFromWatchdog;
 exports.touchDaemonAlive = touchDaemonAlive;
 exports.recordCleanExit = recordCleanExit;
+exports.daemonHungAfterMs = daemonHungAfterMs;
+exports.classifyDaemonHealth = classifyDaemonHealth;
 exports.markPostmortemReported = markPostmortemReported;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -178,6 +180,31 @@ function recordCleanExit(reason) {
     marker.cleanExit = { at: new Date().toISOString(), reason: reason.slice(0, 120) };
     writeJson(aliveMarkerFile(), marker);
 }
+/** Marker older than this is stale — 4 missed 5-minute heartbeats. */
+function daemonHungAfterMs() {
+    const env = Number(process.env.FCD_DAEMON_HUNG_AFTER_MS);
+    return Number.isFinite(env) && env > 0 ? env : 20 * 60_000;
+}
+function classifyDaemonHealth(input) {
+    if (!input.pidAlive || !input.pid)
+        return 'dead';
+    const marker = input.marker;
+    // No marker for this pid (marker deleted, or owned by a different pid):
+    // freshness cannot be judged — stay conservative, never kill on a guess.
+    if (!marker || marker.pid !== input.pid)
+        return 'indeterminate';
+    const last = Date.parse(marker.lastAliveAt || marker.startedAt || '');
+    const age = (input.nowMs ?? Date.now()) - last;
+    if (!Number.isFinite(age) || age <= input.staleAfterMs)
+        return 'healthy';
+    if (input.pipeProbe === 'responsive')
+        return 'healthy';
+    if (input.pipeProbe === 'unresponsive')
+        return 'hung';
+    if (input.pipeProbe === 'no-endpoint')
+        return 'pid_reused';
+    return 'indeterminate';
+}
 /** Stamp the post-mortem as delivered so heartbeats stop re-sending it. */
 function markPostmortemReported() {
     const pm = readPostmortem();

package/dist/distress.d.ts

@@ -54,6 +54,23 @@ export declare const DISTRESS: {
      * next tick — but while it lasted, remote actions were undeliverable.
      */
     readonly POLL_STALLED: "poll_stalled";
+    /**
+     * The watchdog found the daemon process alive but WEDGED — alive-marker
+     * stale past the bound and the verdict pipe silent — and recycled it.
+     */
+    readonly DAEMON_HUNG: "daemon_hung";
+    /**
+     * The daemon exited itself after repeated uncaught exceptions in a short
+     * window (process state suspect); the supervisor restarts it clean.
+     */
+    readonly UNCAUGHT_BURST: "uncaught_burst";
+    /**
+     * The telemetry spool could not be written (disk full, ACL, AV lock) — the
+     * machine is still enforcing, but its decisions are being LOST locally and
+     * will never reach the console. Deserves an admin's attention because a
+     * quiet machine and a machine that cannot record look identical otherwise.
+     */
+    readonly SPOOL_WRITE_FAILED: "spool_write_failed";
     /** Anything nobody predicted — reported via reportUnexpected(). */
     readonly UNEXPECTED: "unexpected_error";
 };