fullcourtdefense-cli 1.26.4 → 1.26.6

package/dist/distress.js

@@ -99,6 +99,23 @@ exports.DISTRESS = {
      * next tick — but while it lasted, remote actions were undeliverable.
      */
     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.
+     */
+    DAEMON_HUNG: 'daemon_hung',
+    /**
+     * The daemon exited itself after repeated uncaught exceptions in a short
+     * window (process state suspect); the supervisor restarts it clean.
+     */
+    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.
+     */
+    SPOOL_WRITE_FAILED: 'spool_write_failed',
     /** Anything nobody predicted — reported via reportUnexpected(). */
     UNEXPECTED: 'unexpected_error',
 };

package/dist/hookIo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hook I/O leaf — the pieces of the hook runtime that BOTH entries share:
+ *
+ *   - `dist/hookSlim.js` (the slim hook entry installed into IDE hook configs)
+ *   - `dist/index.js hook` (the full CLI's hook command, and the daemon's
+ *     in-process evaluator)
+ *
+ * COLD-START CONTRACT: this module is on the slim entry's module graph, which
+ * is loaded on EVERY IDE hook event. It may import Node built-ins ONLY —
+ * every additional module here is bytes the customer's EDR re-scans per
+ * docker command. `scripts/test-slim-hook.js` enforces the graph budget.
+ */
+export declare const HOOK_DEBUG_LOG: string;
+/**
+ * Verbose diagnostics (FCD_HOOK_DEBUG=1) additionally log content previews
+ * (raw payload + prompt text snippets). Default logging keeps operational
+ * metadata only — user prompt content must never sit in a plaintext file on
+ * a customer laptop unless support explicitly opts in.
+ */
+export declare const HOOK_DEBUG_VERBOSE: boolean;
+/** Append a diagnostic line so we can see exactly what the IDE invoked + the verdict. */
+export declare function dbg(obj: Record<string, unknown>): void;
+export declare function readStdin(): Promise<string>;
+/**
+ * kebab-case CLI flags -> the camelCase HookArgs shape. ONE mapping shared by
+ * the full CLI entry (`index.ts` case 'hook') and the slim entry, so the
+ * daemon's IPC evaluator always receives identical argument shapes no matter
+ * which entry the IDE invoked.
+ */
+export declare function mapHookFlags(flags: Record<string, string>): Record<string, string | undefined>;
+/**
+ * Minimal `--flag value` / `--flag=value` parser with the same semantics as
+ * the full CLI's parseArgs, restricted to what a hook command line carries.
+ * Positionals (the literal `hook` subcommand kept in installed commands for
+ * the managed-entry repair marker) are ignored.
+ */
+export declare function parseHookFlags(argv: string[]): Record<string, string>;
+/**
+ * Absolute path of the slim hook entry that sits next to a given CLI script
+ * (`dist/index.js` -> `dist/hookSlim.js`). Installers prefer the slim entry
+ * when it exists; older installs (pre-slim dist) keep pointing at index.js.
+ */
+export declare function slimHookEntryPath(cliScriptPath: string): string | undefined;

package/dist/hookIo.js

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

package/dist/hookSlim.d.ts

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

package/dist/hookSlim.js

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

package/dist/index.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // touching this file.
 const config_1 = require("./config");
 const hook_1 = require("./commands/hook");
+const hookIo_1 = require("./hookIo");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 function readCliVersion() {
@@ -137,6 +138,9 @@ function printHelp() {
     doctor      First step. Checks outbound HTTPS access to FullCourtDefense.
                 --perf measures this machine's real per-event overhead
                 (hook latency, spawn floor, cmd-guard cost, disk footprint).
+                --health prints an mdatp-health-style per-subsystem status
+                table (enrollment, credentials, hooks, updater, tasks).
+                --edr prints the narrowest AV/EDR allowlist guidance for IT.
     login       Enrolls this machine with a fleet enrollment token and saves
                 per-machine Shield credentials to ~/.fullcourtdefense.yml.
     configure   Legacy/manual setup: saves org API key, Organization ID,
@@ -518,6 +522,8 @@ async function main() {
             const args = {
                 apiUrl: flags['api-url'],
                 perf: flags.perf,
+                health: flags.health,
+                edr: flags.edr,
             };
             const { doctorCommand } = await Promise.resolve().then(() => __importStar(require('./commands/doctor')));
             await doctorCommand(args, config);
@@ -679,20 +685,9 @@ async function main() {
             break;
         }
         case 'hook': {
-            const args = {
-                event: flags.event,
-                apiUrl: flags['api-url'],
-                shieldId: flags['shield-id'],
-                shieldKey: flags['shield-key'],
-                shadow: flags.shadow,
-                enforce: flags.enforce,
-                failClosed: flags['fail-closed'],
-                localOnly: flags['local-only'],
-                timeout: flags.timeout,
-                approvalMode: flags['approval-mode'],
-                approvalTimeoutMs: flags['approval-timeout-ms'],
-                approvalPollMs: flags['approval-poll-ms'],
-            };
+            // ONE flag mapping shared with the slim entry (hookSlim.ts) — the daemon
+            // IPC evaluator must see identical argument shapes from both entries.
+            const args = (0, hookIo_1.mapHookFlags)(flags);
             await (0, hook_1.hookCommand)(args, config);
             break;
         }
@@ -771,6 +766,7 @@ async function main() {
                 json: flags.json,
                 noDaemon: flags['no-daemon'],
                 acceptDisclosure: flags['accept-disclosure'],
+                mode: flags.mode,
             };
             const { onboardCommand } = await Promise.resolve().then(() => __importStar(require('./commands/onboard')));
             await onboardCommand(args, config);

package/dist/integrity.js

@@ -105,6 +105,12 @@ function getLocalIntegrityReport(options = {}) {
     }
     else if (cursorHooks.staleEntries > 0)
         reasons.push('cursor_hook_stale_path');
+    // A managed entry mutated to weaken enforcement (hand-added `--shadow true`):
+    // the hook ignores the flag on managed invocations, and the tamper is
+    // reported here so the fleet console sees the edit instead of it being
+    // silently neutralized.
+    if (cursorHooks.existed && (cursorHooks.weakenedEntries || 0) > 0)
+        reasons.push('cursor_hook_changed');
     const claudeHooks = (0, installClaudeHook_1.inspectClaudeManagedHooks)();
     if (!claudeHooks.existed || claudeHooks.managedEntries === 0) {
         if ((0, appDetection_1.isClaudeFamilyAppInstalled)())
@@ -112,6 +118,8 @@ function getLocalIntegrityReport(options = {}) {
     }
     else if (claudeHooks.staleEntries > 0)
         reasons.push('claude_hook_stale_path');
+    if (claudeHooks.existed && (claudeHooks.weakenedEntries || 0) > 0)
+        reasons.push('claude_hook_changed');
     const daemonRunning = isDaemonRunning();
     if (options.requireDaemon && !daemonRunning)
         reasons.push('daemon_not_running');

package/dist/localSafetySnapshot.d.ts

@@ -36,5 +36,14 @@ export declare function hookSnapshotIdentity(): {
     machineName: string;
 };
 export declare function clearLocalSafetySnapshotCache(input: Pick<LocalSafetySnapshotInput, 'apiUrl' | 'shieldId' | 'developerName' | 'machineName'>): void;
+/**
+ * Remove EVERY Local Safety snapshot cache file, regardless of the identity
+ * that keyed it. Used on (re-)enrollment and explicit policy refresh: cache
+ * files are keyed by sha1(apiUrl|shieldId|developer|machine), so after a
+ * shield/identity change a targeted unlink can miss files written under an
+ * old key — leaving a stale (possibly enforcing) snapshot for whichever
+ * surface still resolves that old identity.
+ */
+export declare function clearAllLocalSafetySnapshotCaches(): void;
 export declare function loadLocalSafetySnapshot(input: LocalSafetySnapshotInput): Promise<LocalSafetySnapshot | undefined>;
 export declare function snapshotToScanOptions(snapshot: LocalSafetySnapshot | undefined, extra?: Pick<LocalSafetyScanOptions, 'cwd' | 'inspectScripts'>): LocalSafetyScanOptions;

package/dist/localSafetySnapshot.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hookSnapshotIdentity = hookSnapshotIdentity;
 exports.clearLocalSafetySnapshotCache = clearLocalSafetySnapshotCache;
+exports.clearAllLocalSafetySnapshotCaches = clearAllLocalSafetySnapshotCaches;
 exports.loadLocalSafetySnapshot = loadLocalSafetySnapshot;
 exports.snapshotToScanOptions = snapshotToScanOptions;
 const crypto = __importStar(require("crypto"));
@@ -64,10 +65,40 @@ function readCache(file) {
 function writeCache(file, snapshot) {
     try {
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
+        // Atomic write-temp-rename: hooks read this file on their hot path — a
+        // torn read must never make a policy snapshot unparseable mid-refresh.
+        const tmp = `${file}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
+        fs.renameSync(tmp, file);
     }
     catch { /* best-effort */ }
 }
+/**
+ * Fallback when the derived cache key has no file: the freshest snapshot on
+ * disk under ANY key. Cache keys hash the caller's identity, and that
+ * identity has drifted across surfaces/versions (gateway --developer-name vs
+ * hook username@hostname vs normalized machine identity) — after an upgrade
+ * the old surface's cache would otherwise be invisible and an OFFLINE block
+ * machine would silently downgrade its catalog rules to warn. All snapshot
+ * files in this per-user dir belong to this machine's enrollment (enrollment
+ * clears them all), so the freshest one is always safe to serve.
+ */
+function readFreshestAnyCache() {
+    try {
+        let best;
+        for (const name of fs.readdirSync(CACHE_DIR)) {
+            if (!/^local-safety-[0-9a-f]{40}\.json$/i.test(name))
+                continue;
+            const parsed = readCache(path.join(CACHE_DIR, name));
+            if (parsed && (!best || parsed.loadedAt > best.loadedAt))
+                best = parsed;
+        }
+        return best;
+    }
+    catch {
+        return undefined;
+    }
+}
 function toRuleAction(value) {
     // Explicit 'block' is preserved (not treated as absent): warn-by-default
     // items (e.g. env_workspace) need an org's explicit block override to
@@ -135,9 +166,30 @@ function clearLocalSafetySnapshotCache(input) {
     }
     catch { /* cache may not exist */ }
 }
+/**
+ * Remove EVERY Local Safety snapshot cache file, regardless of the identity
+ * that keyed it. Used on (re-)enrollment and explicit policy refresh: cache
+ * files are keyed by sha1(apiUrl|shieldId|developer|machine), so after a
+ * shield/identity change a targeted unlink can miss files written under an
+ * old key — leaving a stale (possibly enforcing) snapshot for whichever
+ * surface still resolves that old identity.
+ */
+function clearAllLocalSafetySnapshotCaches() {
+    try {
+        for (const name of fs.readdirSync(CACHE_DIR)) {
+            if (/^local-safety-[0-9a-f]{40}\.json$/i.test(name)) {
+                try {
+                    fs.unlinkSync(path.join(CACHE_DIR, name));
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    catch { /* cache dir may not exist */ }
+}
 async function loadLocalSafetySnapshot(input) {
     const file = cachePath(input);
-    const cached = readCache(file);
+    const cached = readCache(file) || readFreshestAnyCache();
     const hashMatches = !input.expectedPolicyHash || cached?.snapshot.policyHash === input.expectedPolicyHash;
     if (cached && hashMatches && Date.now() - cached.loadedAt < CACHE_TTL_MS)
         return cached.snapshot;
@@ -175,6 +227,10 @@ function snapshotToScanOptions(snapshot, extra = {}) {
     return {
         disabledBuiltInItemIds: snapshot?.disabledBuiltInItemIds,
         itemActions: snapshot?.itemActions,
+        // Signals to the guard whether a real snapshot was resolved. Without one,
+        // the guard defaults to warn (never catalog hard-block) for unarmed/offline
+        // machines instead of over-blocking.
+        snapshotPresent: snapshot !== undefined,
         customBlocks: snapshot?.customBlocks,
         trustedScriptPaths: snapshot?.trustedScriptPaths,
         policyHash: snapshot?.policyHash,