fullcourtdefense-cli 1.34.21 → 1.34.25

package/dist/distress.d.ts

@@ -32,6 +32,8 @@ export declare const DISTRESS: {
     readonly AUTH_BROKEN: "auth_broken";
     /** Control plane unreachable (network / DNS / proxy / timeout). */
     readonly NETWORK_DOWN: "network_down";
+    /** A policy response arrived, but the replacement cache could not be saved. */
+    readonly POLICY_CACHE_WRITE_FAILED: "policy_cache_write_failed";
     /**
      * Control plane REACHED and credentials accepted, but it refused the policy
      * request (HTTP 400/404/409/422/5xx). A server-side or data fault — the fix

package/dist/distress.js

@@ -77,6 +77,8 @@ exports.DISTRESS = {
     AUTH_BROKEN: 'auth_broken',
     /** Control plane unreachable (network / DNS / proxy / timeout). */
     NETWORK_DOWN: 'network_down',
+    /** A policy response arrived, but the replacement cache could not be saved. */
+    POLICY_CACHE_WRITE_FAILED: 'policy_cache_write_failed',
     /**
      * Control plane REACHED and credentials accepted, but it refused the policy
      * request (HTTP 400/404/409/422/5xx). A server-side or data fault — the fix

package/dist/frictionRollout.js

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../../backend/src/modules/discovery/friction-rollout.ts
+var friction_rollout_exports = {};
+__export(friction_rollout_exports, {
+  assessFrictionRollout: () => assessFrictionRollout
+});
+module.exports = __toCommonJS(friction_rollout_exports);
+function assessFrictionRollout(input) {
+  const value = input;
+  if (!value || typeof value.baselineVersion !== "string" || typeof value.candidateVersion !== "string" || !/^\d+\.\d+\.\d+$/.test(value.baselineVersion) || !/^\d+\.\d+\.\d+$/.test(value.candidateVersion) || !["replay", "real_hook", "real_ide", "production"].includes(String(value.evidenceLevel)) || !Array.isArray(value.observations) || value.observations.length > 2e3) throw new Error("Invalid paired evidence");
+  const artifact = (raw, bundled = false) => {
+    const item = raw;
+    if (!item || !Number.isSafeInteger(item.revision) || Number(item.revision) < (bundled ? 0 : 1) || typeof item.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(item.sha256)) throw new Error("Invalid detector artifact identity");
+    return { revision: Number(item.revision), sha256: item.sha256 };
+  };
+  const hasDetection = value.baselineDetection !== void 0 || value.candidateDetection !== void 0;
+  const baselineDetection = hasDetection ? artifact(value.baselineDetection, true) : void 0;
+  const candidateDetection = hasDetection ? artifact(value.candidateDetection) : void 0;
+  const sameCli = value.baselineVersion === value.candidateVersion;
+  if (baselineDetection && candidateDetection) {
+    if (candidateDetection.revision < baselineDetection.revision || candidateDetection.revision === baselineDetection.revision && candidateDetection.sha256 !== baselineDetection.sha256) {
+      throw new Error("Detector revision downgrade or reuse");
+    }
+  }
+  if (sameCli && (!baselineDetection || !candidateDetection || candidateDetection.revision <= baselineDetection.revision || candidateDetection.sha256 === baselineDetection.sha256)) throw new Error("Same CLI requires distinct, increasing detector artifacts");
+  const verdicts = ["allow", "block", "require_approval"];
+  const seen = /* @__PURE__ */ new Set();
+  let fixed = 0, regressed = 0, unchanged = 0, missingEffects = 0, remainingErrors = 0;
+  let benign = 0, guarded = 0, baselineInterruptions = 0, candidateInterruptions = 0;
+  const families = /* @__PURE__ */ new Set();
+  const machines = /* @__PURE__ */ new Set();
+  for (const row of value.observations) {
+    if (!row || !["caseId", "family", "machineId", "policyHash"].every((key2) => typeof row[key2] === "string" && /^[a-zA-Z0-9_.:-]{1,100}$/.test(row[key2])) || ![row.expected, row.baseline, row.candidate].every((v) => verdicts.includes(v)) || typeof row.sideEffectVerified !== "boolean") throw new Error("Invalid observation");
+    const key = JSON.stringify([row.machineId, row.caseId, row.policyHash]);
+    if (seen.has(key)) throw new Error("Duplicate paired observation");
+    seen.add(key);
+    families.add(row.family);
+    machines.add(row.machineId);
+    const before = row.baseline === row.expected, after = row.candidate === row.expected;
+    if (!before && after) fixed++;
+    else if (before && !after) regressed++;
+    else unchanged++;
+    if (!after) remainingErrors++;
+    if (!row.sideEffectVerified) missingEffects++;
+    if (row.expected === "allow") {
+      benign++;
+      if (row.baseline !== "allow") baselineInterruptions++;
+      if (row.candidate !== "allow") candidateInterruptions++;
+    } else guarded++;
+  }
+  const reasons = [];
+  if (!benign || !guarded) reasons.push("Both benign actions and prohibited/approval counterparts are required");
+  if (!fixed) reasons.push("No measured correction");
+  if (regressed || remainingErrors) reasons.push("Candidate has regressions or unresolved mismatches");
+  if (missingEffects) reasons.push("Actual side-effect verification is missing");
+  if (value.evidenceLevel !== "production") reasons.push("This evidence cannot establish production improvement");
+  return {
+    schema: "fcd.paired-feedback.v1",
+    baselineVersion: value.baselineVersion,
+    candidateVersion: value.candidateVersion,
+    ...hasDetection ? { baselineDetection, candidateDetection } : {},
+    changeKind: sameCli ? "detector_only" : hasDetection && baselineDetection.sha256 !== candidateDetection.sha256 ? "cli_and_detector" : "cli",
+    evidenceLevel: value.evidenceLevel,
+    cases: seen.size,
+    families: families.size,
+    machines: machines.size,
+    fixed,
+    regressed,
+    unchanged,
+    remainingErrors,
+    missingEffects,
+    benign,
+    guarded,
+    baselineInterruptions,
+    candidateInterruptions,
+    eligibleForOwnerReview: reasons.length === 0,
+    reasons,
+    automaticPublication: false,
+    note: "Labels and side effects are reviewer-supplied evidence, not independently verified by this gate. Publication requires reviewed signed release evidence."
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assessFrictionRollout
+});

package/dist/gatewayRuntime.d.ts

@@ -0,0 +1,19 @@
+export interface GatewayRuntime {
+    executable: string;
+    entry: string;
+}
+/**
+ * Keep wrappers already owned by the MSI on its maintained runtime when a
+ * developer invokes another CLI copy. Unknown/missing runtimes still converge
+ * to the invoking CLI; arbitrary existing executables are never trusted merely
+ * because they exist. Only the canonical packaged Windows installation qualifies.
+ */
+export declare function resolveGatewayRuntime(current: GatewayRuntime, existing?: {
+    command?: unknown;
+    args?: unknown;
+}, options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): GatewayRuntime;
+/** Hooks share the gateway's installed owner, including the older full entry. */
+export declare function resolveHookRuntime(current: GatewayRuntime, existingCommand?: string): GatewayRuntime;

package/dist/gatewayRuntime.js

@@ -0,0 +1,93 @@
+"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.resolveGatewayRuntime = resolveGatewayRuntime;
+exports.resolveHookRuntime = resolveHookRuntime;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Keep wrappers already owned by the MSI on its maintained runtime when a
+ * developer invokes another CLI copy. Unknown/missing runtimes still converge
+ * to the invoking CLI; arbitrary existing executables are never trusted merely
+ * because they exist. Only the canonical packaged Windows installation qualifies.
+ */
+function resolveGatewayRuntime(current, existing, options = {}) {
+    if ((options.platform || process.platform) !== 'win32')
+        return current;
+    const env = options.env || process.env;
+    const normalize = (value) => path.resolve(value).toLowerCase();
+    const existingArgs = Array.isArray(existing?.args) ? existing.args : [];
+    for (const base of [env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', env.ProgramFiles || 'C:\\Program Files']) {
+        const root = path.join(base, 'FullCourtDefense');
+        const installed = { executable: path.join(root, 'runtime', 'node.exe'), entry: path.join(root, 'dist', 'index.js') };
+        // A fresh development-only config remains local to that runtime. Once the
+        // installed daemon owns it, other copies preserve that owner on every pass.
+        const belongsToInstall = [current.entry, existingArgs[0]].some(value => typeof value === 'string' && normalize(value) === normalize(installed.entry));
+        if (!belongsToInstall)
+            continue;
+        try {
+            const files = [root, path.dirname(installed.executable), path.dirname(installed.entry), installed.executable, installed.entry, path.join(root, 'package.json')];
+            if (files.some(file => fs.lstatSync(file).isSymbolicLink()))
+                continue;
+            if (!fs.statSync(installed.executable).isFile() || !fs.statSync(installed.entry).isFile())
+                continue;
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            if (pkg.name !== 'fullcourtdefense-cli')
+                continue;
+            return installed;
+        }
+        catch { /* Missing installation: repair using the running CLI. */ }
+    }
+    return current;
+}
+/** Hooks share the gateway's installed owner, including the older full entry. */
+function resolveHookRuntime(current, existingCommand) {
+    const invocation = existingCommand?.match(/^(?:"[^"]*"|\S+)\s+(?:"([^"]*)"|(\S+))\s+hook(?:\s|$)/);
+    const gatewayEntry = (entry) => path.basename(entry).toLowerCase() === 'hookslim.js'
+        ? path.join(path.dirname(entry), 'index.js') : entry;
+    const previousEntry = invocation?.[1] || invocation?.[2];
+    const mapped = { ...current, entry: gatewayEntry(current.entry) };
+    const owner = resolveGatewayRuntime(mapped, previousEntry ? { args: [gatewayEntry(previousEntry)] } : undefined);
+    if (owner === mapped)
+        return current;
+    const slim = path.join(path.dirname(owner.entry), 'hookSlim.js');
+    try {
+        const stat = fs.lstatSync(slim);
+        if (stat.isFile() && !stat.isSymbolicLink())
+            return { ...owner, entry: slim };
+    }
+    catch { /* Older installed releases use the full entry. */ }
+    return owner;
+}

package/dist/hookSlim.js

@@ -91,19 +91,28 @@ async function main() {
             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) {
+                const verdict = { stdout: ipc.stdout || '', stderr: ipc.stderr || '', exitCode: ipc.exitCode ?? 0 };
+                // The daemon never opens a window; an `ask` carries a dialog envelope for
+                // THIS process (the developer's session). Loaded only when one is present,
+                // so the warm allow/deny path stays three files.
+                if (verdict.stdout.includes('"fcdAsk"')) {
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    const { emitVerdictForIde } = require('./askDialog');
+                    await emitVerdictForIde(args, verdict, 'slim-ipc');
+                }
+                if (verdict.stderr) {
                     try {
-                        process.stderr.write(ipc.stderr);
+                        process.stderr.write(verdict.stderr);
                     }
                     catch { /* stderr gone */ }
                 }
-                if (ipc.stdout) {
+                if (verdict.stdout) {
                     try {
-                        process.stdout.write(ipc.stdout);
+                        process.stdout.write(verdict.stdout);
                     }
                     catch { /* stdout gone */ }
                 }
-                process.exit(ipc.exitCode ?? 0);
+                process.exit(verdict.exitCode);
             }
             (0, hookIo_1.dbg)({ phase: 'ipc_unavailable', event: args.event, detail: ipc.detail, entry: 'slim' });
         }
@@ -118,19 +127,9 @@ async function main() {
         // 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);
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { emitVerdictForIde } = require('./askDialog');
+        await emitVerdictForIde(args, result, 'slim-local');
     }
     catch (err) {
         emitFailOpen(args.event, err instanceof Error ? err.message : String(err));

package/dist/index.js

@@ -137,6 +137,13 @@ function printHelp() {
                 Exits 1 when remnants are found. Works via npx after the CLI
                 itself is uninstalled.
     doctor      First step. Checks outbound HTTPS access to FullCourtDefense.
+    protection-check
+                Test supported action boundaries and report verified coverage.
+    protected-run
+                Launch with this computer's signed folder/site limits.
+                --inspect shows settings; --command "your-agent" starts it.
+                Missing OS prerequisites or expired settings stop the launch.
+    hotfix-status  Show loaded detector revision, update state and fallback status.
                 --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
@@ -459,6 +466,7 @@ async function main() {
         apiKey: flags['api-key'],
     });
     const buildGatewayArgs = () => ({
+        mcpServerName: flags['mcp-server-name'],
         mcpCommand: flags['mcp-command'],
         mcpArgs: flags['mcp-args'],
         mcpUrl: flags['mcp-url'],
@@ -542,6 +550,26 @@ async function main() {
             printHelp();
             break;
         }
+        case 'protected-run': {
+            const { protectedRunCommand } = await Promise.resolve().then(() => __importStar(require('./commands/protectedRun')));
+            await protectedRunCommand(config, flags.command, flags.inspect === 'true');
+            break;
+        }
+        case 'protection-check': {
+            const { runBoundaryVerification } = await Promise.resolve().then(() => __importStar(require('./boundaryVerification')));
+            const report = await runBoundaryVerification();
+            if (flags.json === 'true')
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                console.log('Action Protection — local checker verification');
+                console.log('Private sample policy; no submitted command or tool is executed.');
+                for (const check of report.checks)
+                    console.log(`${check.boundary}: ${check.status} (${check.allowed} allowed sample, ${check.denied} blocked sample)`);
+                console.log('This checks the CLI, not IDE integration or OS containment. Use --json for the full report.');
+            }
+            process.exitCode = report.checks.some(check => check.status === 'failed') ? 1 : 0;
+            break;
+        }
         case 'doctor': {
             const args = {
                 apiUrl: flags['api-url'],
@@ -553,6 +581,13 @@ async function main() {
             await doctorCommand(args, config);
             break;
         }
+        case 'hotfix-status': {
+            const { localDetectorUpdates } = await Promise.resolve().then(() => __importStar(require('./localDetectionUpdates')));
+            const { cliVersion } = await Promise.resolve().then(() => __importStar(require('./cliVersion')));
+            console.log(JSON.stringify({ cliVersion: cliVersion(), detector: localDetectorUpdates.getDetectorStatus(),
+                note: 'Acceptance is not proof of correction. Compare the reported action and prohibited counterparts under the same policy.' }, null, 2));
+            break;
+        }
         case 'demo-actions': {
             const { demoActionsCommand } = await Promise.resolve().then(() => __importStar(require('./commands/demoActions')));
             await demoActionsCommand({ live: flags.live, json: flags.json, demoPolicies: flags['demo-policies'], timeout: flags.timeout }, config);

package/dist/localDetectionUpdates.d.ts

@@ -1,2 +1,4 @@
 import { DetectionUpdates } from './detectionUpdates';
-export declare const localDetectionUpdates: DetectionUpdates;
+import { DetectorUpdates } from './detectorUpdates';
+export declare const localDetectionUpdates: DetectionUpdates<import("./detectionData").DetectionData>;
+export declare const localDetectorUpdates: DetectorUpdates;

package/dist/localDetectionUpdates.js

@@ -33,9 +33,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.localDetectionUpdates = void 0;
+exports.localDetectorUpdates = exports.localDetectionUpdates = void 0;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const detectionUpdates_1 = require("./detectionUpdates");
+const detectorUpdates_1 = require("./detectorUpdates");
+const machineIdentity_1 = require("./machineIdentity");
 exports.localDetectionUpdates = new detectionUpdates_1.DetectionUpdates(path.join(os.homedir(), '.fullcourtdefense', 'detection-update.json'));
 exports.localDetectionUpdates.loadLocal();
+exports.localDetectorUpdates = new detectorUpdates_1.DetectorUpdates(path.join(os.homedir(), '.fullcourtdefense', 'detector-update-v1.json'), undefined, 'stable', (0, machineIdentity_1.getMachineIdentity)().machineId);
+exports.localDetectorUpdates.loadLocal();
+// Long-running gateways observe the daemon's accepted cache without a restart.
+// This timer is background-only and never keeps a short-lived hook alive.
+setInterval(() => { exports.localDetectionUpdates.loadLocal(); exports.localDetectorUpdates.loadLocal(); }, 30_000).unref();

package/dist/localSafetySnapshot.d.ts

@@ -17,6 +17,8 @@ export interface LocalSafetySnapshotInput {
     machineName: string;
     expectedPolicyHash?: string;
     timeoutMs?: number;
+    /** Explicit background refresh must fetch and persist a verified replacement. */
+    requireServerValidation?: boolean;
     /**
      * Hot-path caller on a monitor/shadow machine: any cached snapshot wins
      * immediately (even stale / hash-mismatched) — the resident daemon owns
@@ -37,13 +39,15 @@ export declare function hookSnapshotIdentity(): {
 };
 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
+ * Remove Local Safety snapshot cache files, regardless of their identity key.
+ * Enrollment clears all; a verified refresh preserves the newly saved hash.
+ * Returns false when an old cache could not be removed, so remote refresh
+ * does not claim convergence while another surface can still use stale rules.
+ * 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 clearAllLocalSafetySnapshotCaches(preservePolicyHash?: string): boolean;
 export declare function loadLocalSafetySnapshot(input: LocalSafetySnapshotInput): Promise<LocalSafetySnapshot | undefined>;
-export declare function snapshotToScanOptions(snapshot: LocalSafetySnapshot | undefined, extra?: Pick<LocalSafetyScanOptions, 'cwd' | 'inspectScripts'>): LocalSafetyScanOptions;
+export declare function snapshotToScanOptions(snapshot: LocalSafetySnapshot | undefined, extra?: Pick<LocalSafetyScanOptions, 'cwd' | 'inspectScripts' | 'mcpServerName'>): LocalSafetyScanOptions;

package/dist/localSafetySnapshot.js

@@ -44,6 +44,7 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const deterministicGuard_1 = require("./commands/deterministicGuard");
 const honeypot_1 = require("./honeypot");
+const distress_1 = require("./distress");
 const CACHE_TTL_MS = 60_000;
 const CACHE_DIR = path.join(os.homedir(), '.fullcourtdefense');
 function cachePath(input) {
@@ -55,9 +56,12 @@ function cachePath(input) {
 function readCache(file) {
     try {
         const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-        if (!parsed?.snapshot || typeof parsed.loadedAt !== 'number')
+        if (!parsed?.snapshot || typeof parsed.loadedAt !== 'number' || !Number.isFinite(parsed.loadedAt) || parsed.loadedAt < 0)
             return undefined;
-        return parsed;
+        // Parseable JSON can still be a partial write or an invalid old cache.
+        // Apply the same policy validation used for a server replacement.
+        const snapshot = toSnapshot(parsed.snapshot);
+        return snapshot ? { loadedAt: parsed.loadedAt, snapshot } : undefined;
     }
     catch {
         return undefined;
@@ -72,7 +76,10 @@ function writeCache(file, snapshot) {
         fs.writeFileSync(tmp, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
         fs.renameSync(tmp, file);
     }
-    catch { /* best-effort */ }
+    catch (error) {
+        (0, distress_1.reportDistress)('shell_policy', distress_1.DISTRESS.POLICY_CACHE_WRITE_FAILED, 'Could not save the shell policy cache; refresh is incomplete');
+        throw error;
+    }
 }
 /**
  * Fallback when the derived cache key has no file: the freshest snapshot on
@@ -109,8 +116,14 @@ function toRuleAction(value) {
 function toSnapshot(data) {
     if (!data || typeof data !== 'object')
         return undefined;
-    // Anything unrecognized falls back to 'block' (fail strict); recognized
-    // entries — including explicit 'block' — are kept verbatim.
+    if (typeof data.policyHash !== 'string' || !data.policyHash.trim()
+        || !Array.isArray(data.disabledBuiltInItemIds) || data.disabledBuiltInItemIds.some((id) => typeof id !== 'string')
+        || !Array.isArray(data.customBlocks) || data.customBlocks.some((item) => !item || typeof item.pattern !== 'string' || !item.pattern
+        || (item.action !== undefined && !toRuleAction(item.action)))
+        || (data.itemActions !== undefined && (!data.itemActions || typeof data.itemActions !== 'object' || Array.isArray(data.itemActions)
+            || Object.values(data.itemActions).some(value => !toRuleAction(value)))))
+        return undefined;
+    // Invalid actions were rejected above; keep explicit 'block' overrides too.
     let itemActions;
     if (data.itemActions && typeof data.itemActions === 'object' && !Array.isArray(data.itemActions)) {
         for (const [itemId, raw] of Object.entries(data.itemActions)) {
@@ -179,33 +192,45 @@ 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
+ * Remove Local Safety snapshot cache files, regardless of their identity key.
+ * Enrollment clears all; a verified refresh preserves the newly saved hash.
+ * Returns false when an old cache could not be removed, so remote refresh
+ * does not claim convergence while another surface can still use stale rules.
+ * 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() {
+function clearAllLocalSafetySnapshotCaches(preservePolicyHash) {
+    let cleared = true;
     try {
         for (const name of fs.readdirSync(CACHE_DIR)) {
             if (/^local-safety-[0-9a-f]{40}\.json$/i.test(name)) {
+                if (preservePolicyHash && readCache(path.join(CACHE_DIR, name))?.snapshot.policyHash === preservePolicyHash)
+                    continue;
                 try {
                     fs.unlinkSync(path.join(CACHE_DIR, name));
                 }
-                catch { /* best-effort */ }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        cleared = false;
+                }
             }
         }
     }
-    catch { /* cache dir may not exist */ }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            cleared = false;
+    }
+    return cleared;
 }
 async function loadLocalSafetySnapshot(input) {
     const file = cachePath(input);
     const cached = readCache(file) || readFreshestAnyCache();
     const hashMatches = !input.expectedPolicyHash || cached?.snapshot.policyHash === input.expectedPolicyHash;
-    if (cached && hashMatches && Date.now() - cached.loadedAt < CACHE_TTL_MS)
+    if (!input.requireServerValidation && cached && hashMatches && Date.now() - cached.loadedAt < CACHE_TTL_MS)
         return cached.snapshot;
-    if (cached && input.preferCached)
+    if (!input.requireServerValidation && cached && input.preferCached)
         return cached.snapshot;
     const headers = { 'Content-Type': 'application/json' };
     if (input.shieldKey)
@@ -223,9 +248,9 @@ async function loadLocalSafetySnapshot(input) {
         });
         if (resp.ok) {
             const body = await resp.json().catch(() => ({}));
-            if (body.success) {
+            if (body.success === true) {
                 const snapshot = toSnapshot(body.data);
-                if (snapshot) {
+                if (snapshot && (!input.requireServerValidation || !input.expectedPolicyHash || snapshot.policyHash === input.expectedPolicyHash)) {
                     writeCache(file, snapshot);
                     return snapshot;
                 }
@@ -233,6 +258,8 @@ async function loadLocalSafetySnapshot(input) {
         }
     }
     catch { /* offline-safe fallback below */ }
+    if (input.requireServerValidation)
+        throw new Error('Shell policy refresh did not receive and save the expected snapshot; cached rules remain available');
     return cached?.snapshot;
 }
 function snapshotToScanOptions(snapshot, extra = {}) {

package/dist/mcpToolReview.d.ts

@@ -0,0 +1,17 @@
+import { VerifiableMachineAction } from './machineActionVerify';
+import { ToolTrustSettings } from './mcpToolTrust';
+/** Retain the signed requirement even when the general bundle ages out offline. */
+export declare class ToolReviewLease {
+    private machineId;
+    private shieldId;
+    private file;
+    private remembered?;
+    private loaded;
+    constructor(machineId: string, shieldId: string, apiUrl: string, directory?: string);
+    settings(candidate?: VerifiableMachineAction | null): ToolTrustSettings | undefined;
+}
+export declare function verifiedToolTrust(envelope: VerifiableMachineAction, machineId: string, shieldId: string): ToolTrustSettings;
+/** Preserve every declared field and exhaust pagination before fingerprinting. */
+export declare function readCompleteToolCatalog(request: (params: Record<string, unknown>) => Promise<unknown>): Promise<Array<Record<string, unknown> & {
+    name: string;
+}>>;