fullcourtdefense-cli 1.26.14 → 1.26.16

package/dist/actionPolicyEngine.d.ts

@@ -17,15 +17,47 @@
  * they diverge. Change this file? Copy it to the other location verbatim.
  */
 export type ActionPolicyVerdict = 'allow' | 'block' | 'require_approval' | 'log';
+/**
+ * Constraint operators. `not_matches` is the glob complement of `matches`: it is what lets an
+ * allow-list be expressed under "most restrictive verdict wins" — `to matches *@company.com ->
+ * allow` needs a `to not_matches *@company.com -> block` partner, because an unconstrained block
+ * rule would match every call and swallow the allow.
+ */
+export type ActionPolicyConstraintOperator = 'contains' | 'not_contains' | 'equals' | 'not_equals' | 'gt' | 'lt' | 'matches' | 'not_matches';
 export interface ActionPolicyConstraint {
     field: string;
-    operator: 'contains' | 'not_contains' | 'equals' | 'not_equals' | 'gt' | 'lt' | 'matches';
+    operator: ActionPolicyConstraintOperator;
     value: string;
 }
+/**
+ * Who resolves a `require_approval` verdict.
+ *   - `org`       — an admin in the console / Slack (default; the only scope with no human at the keyboard).
+ *   - `developer` — the developer running the agent confirms in their IDE's own permission prompt
+ *                   (Cursor `permission: ask`, Claude `permissionDecision: ask`) or a terminal y/N.
+ *                   Only meaningful where a human is present — see `effectiveApprovalScope`.
+ */
+export type ActionPolicyApprovalScope = 'developer' | 'org';
+/** How long a developer's confirmation is remembered for the same tool + operation. */
+export type ActionPolicyApprovalRemember = 'none' | 'session' | '1h';
+/** What happens when nobody answers within the approval window. */
+export type ActionPolicyApprovalOnTimeout = 'block' | 'org';
+export interface ActionPolicyApproval {
+    scope?: ActionPolicyApprovalScope;
+    remember?: ActionPolicyApprovalRemember;
+    onTimeout?: ActionPolicyApprovalOnTimeout;
+}
+/** Fully-resolved approval options (every field present) attached to a `require_approval` result. */
+export interface ResolvedActionPolicyApproval {
+    scope: ActionPolicyApprovalScope;
+    remember: ActionPolicyApprovalRemember;
+    onTimeout: ActionPolicyApprovalOnTimeout;
+}
 export interface ActionPolicyRule {
     operations: string[];
     verdict: ActionPolicyVerdict;
     constraints?: ActionPolicyConstraint[];
+    /** Approval routing for `require_approval` rules. Absent = org admin approval, no memory, block on timeout. */
+    approval?: ActionPolicyApproval;
 }
 export interface ActionPolicyTargeting {
     developerNames?: string[];
@@ -59,11 +91,36 @@ export interface EngineCheckResult {
     resourceType?: string;
     matchedRule?: string;
     reason?: string;
+    /**
+     * Resolved approval routing — present only when `verdict === 'require_approval'`. When several
+     * approval rules match, the most restrictive option wins per field (org > developer, none >
+     * session > 1h, block > org) so one permissive rule can never loosen another.
+     */
+    approval?: ResolvedActionPolicyApproval;
     /** Monitor-stage policies that matched (would-block / would-approve) without enforcing. */
     monitorMatches?: ActionPolicyMonitorMatch[];
     /** Org-scoped policies skipped because the call carried no developerName (for caller-side logging). */
     skippedOrgPolicies?: string[];
 }
+export declare const DEFAULT_ACTION_POLICY_APPROVAL: ResolvedActionPolicyApproval;
+/**
+ * Normalize a rule's approval options: unknown / missing values fall back to the DEFAULT
+ * (org, none, block) — the strictest — so a typo in a policy document can never widen who
+ * may approve.
+ */
+export declare function resolveApprovalOptions(approval?: ActionPolicyApproval): ResolvedActionPolicyApproval;
+/**
+ * Where an approval actually goes given who is present at the enforcement point.
+ *
+ * `developer` scope means "the human running the agent confirms in their IDE". That human only
+ * exists on an end machine. Ephemeral machines (CI runners, containers, cloud coding agents) and
+ * SDK-embedded online services have no keyboard, so a developer-scoped rule there degrades to the
+ * org admin queue — never to a silent self-approval, and never to allow. Pure and shared so the
+ * backend, the CLI hook and the SDK agree on this fallback without a network round-trip.
+ */
+export declare function effectiveApprovalScope(approval: ActionPolicyApproval | ResolvedActionPolicyApproval | undefined, presence: {
+    humanPresent: boolean;
+}): ActionPolicyApprovalScope;
 /**
  * Derive the set of canonical operations a tool represents from its NAME and declared inventory
  * actions. This is the "declared operations" model: the tool's identity/declaration defines what

package/dist/actionPolicyEngine.js

@@ -18,11 +18,60 @@
  * they diverge. Change this file? Copy it to the other location verbatim.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ACTION_POLICY_APPROVAL = void 0;
+exports.resolveApprovalOptions = resolveApprovalOptions;
+exports.effectiveApprovalScope = effectiveApprovalScope;
 exports.deriveToolOperations = deriveToolOperations;
 exports.toolCapabilities = toolCapabilities;
 exports.evaluateActionPolicies = evaluateActionPolicies;
 exports.inferToolContext = inferToolContext;
 exports.inventoryToolMatchesActionPolicy = inventoryToolMatchesActionPolicy;
+exports.DEFAULT_ACTION_POLICY_APPROVAL = {
+    scope: 'org',
+    remember: 'none',
+    onTimeout: 'block',
+};
+const APPROVAL_SCOPE_RANK = { developer: 0, org: 1 };
+const APPROVAL_REMEMBER_RANK = { '1h': 0, session: 1, none: 2 };
+const APPROVAL_ON_TIMEOUT_RANK = { org: 0, block: 1 };
+/**
+ * Normalize a rule's approval options: unknown / missing values fall back to the DEFAULT
+ * (org, none, block) — the strictest — so a typo in a policy document can never widen who
+ * may approve.
+ */
+function resolveApprovalOptions(approval) {
+    const scope = approval?.scope;
+    const remember = approval?.remember;
+    const onTimeout = approval?.onTimeout;
+    return {
+        scope: scope === 'developer' || scope === 'org' ? scope : exports.DEFAULT_ACTION_POLICY_APPROVAL.scope,
+        remember: remember === 'session' || remember === '1h' || remember === 'none' ? remember : exports.DEFAULT_ACTION_POLICY_APPROVAL.remember,
+        onTimeout: onTimeout === 'org' || onTimeout === 'block' ? onTimeout : exports.DEFAULT_ACTION_POLICY_APPROVAL.onTimeout,
+    };
+}
+/** Field-wise most-restrictive merge of two resolved approval options. */
+function mergeApprovalOptions(a, b) {
+    return {
+        scope: APPROVAL_SCOPE_RANK[b.scope] > APPROVAL_SCOPE_RANK[a.scope] ? b.scope : a.scope,
+        remember: APPROVAL_REMEMBER_RANK[b.remember] > APPROVAL_REMEMBER_RANK[a.remember] ? b.remember : a.remember,
+        onTimeout: APPROVAL_ON_TIMEOUT_RANK[b.onTimeout] > APPROVAL_ON_TIMEOUT_RANK[a.onTimeout] ? b.onTimeout : a.onTimeout,
+    };
+}
+/**
+ * Where an approval actually goes given who is present at the enforcement point.
+ *
+ * `developer` scope means "the human running the agent confirms in their IDE". That human only
+ * exists on an end machine. Ephemeral machines (CI runners, containers, cloud coding agents) and
+ * SDK-embedded online services have no keyboard, so a developer-scoped rule there degrades to the
+ * org admin queue — never to a silent self-approval, and never to allow. Pure and shared so the
+ * backend, the CLI hook and the SDK agree on this fallback without a network round-trip.
+ */
+function effectiveApprovalScope(approval, presence) {
+    const resolved = resolveApprovalOptions(approval);
+    if (resolved.scope === 'developer' && presence.humanPresent)
+        return 'developer';
+    return 'org';
+}
 function matchesGlob(value, pattern) {
     const escaped = pattern
         .replace(/[.+^${}()|[\]\\]/g, '\\$&')
@@ -174,6 +223,8 @@ function evaluateConstraint(constraint, context) {
                 return !actualNorm.includes(expectedNorm);
             case 'matches':
                 return matchesGlob(actualNorm, expectedNorm);
+            case 'not_matches':
+                return !matchesGlob(actualNorm, expectedNorm);
             default:
                 return false;
         }
@@ -190,6 +241,8 @@ function evaluateConstraint(constraint, context) {
                 return !actual.toLowerCase().includes(expected.toLowerCase());
             case 'matches':
                 return matchesGlob(actual, expected);
+            case 'not_matches':
+                return !matchesGlob(actual, expected);
             default:
                 return false;
         }
@@ -207,6 +260,7 @@ function evaluateConstraint(constraint, context) {
                 return capabilityMatch;
             case 'not_equals':
             case 'not_contains':
+            case 'not_matches':
                 return !capabilityMatch;
             default:
                 return false;
@@ -227,6 +281,8 @@ function evaluateConstraint(constraint, context) {
             return parseFloat(actual) < parseFloat(expected);
         case 'matches':
             return matchesGlob(actual, expected);
+        case 'not_matches':
+            return !matchesGlob(actual, expected);
         default:
             return false;
     }
@@ -528,6 +584,16 @@ function evaluateActionPolicies(policies, toolName, operation, context = {}, dec
                     resourceType: policy.resourceType,
                     matchedRule,
                     reason: `Action policy "${policy.name}": ${rule.operations.join('/')} ${rule.verdict === 'block' ? 'blocked' : rule.verdict === 'require_approval' ? 'requires approval' : rule.verdict}`,
+                    ...(rule.verdict === 'require_approval' ? { approval: resolveApprovalOptions(rule.approval) } : {}),
+                };
+            }
+            else if (rule.verdict === 'require_approval' && worstResult.verdict === 'require_approval') {
+                // A second approval rule matched: keep the first rule's attribution but tighten the
+                // approval routing to the most restrictive of both (a developer-scoped rule can never
+                // relax an org-scoped one that also fires).
+                worstResult = {
+                    ...worstResult,
+                    approval: mergeApprovalOptions(worstResult.approval || exports.DEFAULT_ACTION_POLICY_APPROVAL, resolveApprovalOptions(rule.approval)),
                 };
             }
         }

package/dist/commands/ciProtect.d.ts

@@ -28,6 +28,8 @@ export interface CiProtectArgs {
     hooks?: string;
     /** 'false' => skip wrapping MCP client configs with the gateway. */
     gateway?: string;
+    /** 'true' => allow replacing an existing developer-machine enrollment (see assertNotEnrolledLaptop). */
+    force?: string;
 }
 interface CiContext {
     provider: string;

package/dist/commands/ciProtect.js

@@ -1,44 +1,9 @@
 "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.detectCiContext = detectCiContext;
 exports.ciProtectCommand = ciProtectCommand;
-const fs = __importStar(require("fs"));
 const config_1 = require("../config");
-const installClaudeHook_1 = require("./installClaudeHook");
-const mcpGateway_1 = require("./mcpGateway");
+const ephemeralStack_1 = require("./ephemeralStack");
 /** Detect the pipeline from standard CI env vars (GitHub Actions, GitLab CI). */
 function detectCiContext(env = process.env) {
     if (env.GITHUB_ACTIONS === 'true') {
@@ -89,6 +54,9 @@ async function ciProtectCommand(args, config) {
         throw new Error('An organization API key is required. Add FCD_API_KEY to the repo/pipeline secrets '
             + '(create one in the dashboard: Workspace → API keys) or pass --api-key.');
     }
+    // Before any network call or file write: never overwrite a developer's enrollment
+    // (self-hosted runner that is also someone's workstation).
+    (0, ephemeralStack_1.assertNotEnrolledLaptop)('pipeline', { force: args.force === 'true' });
     const detected = detectCiContext();
     const provider = (args.provider || detected?.provider || 'generic-ci').trim();
     const repo = (args.repo || detected?.repo || '').trim();
@@ -129,62 +97,26 @@ async function ciProtectCommand(args, config) {
         shieldKey: result.shieldKey,
         apiUrl,
     });
+    (0, ephemeralStack_1.writeEphemeralIdentityMarker)('pipeline', result.machineId);
     // Attribute every subsequent hook/gateway event in this job to the PIPELINE
     // machine record: current process + GITHUB_ENV for the steps that follow
     // (where the AI agent actually runs).
-    const identityEnv = {
+    (0, ephemeralStack_1.exportIdentityEnv)({
         FCD_MACHINE_ID: result.machineId,
         FCD_DEVELOPER_NAME: `ci@${repo.toLowerCase()}`,
         FCD_MACHINE_HOSTNAME: result.pipeline.key,
-    };
-    for (const [key, value] of Object.entries(identityEnv))
-        process.env[key] = value;
-    if (process.env.GITHUB_ENV) {
-        try {
-            fs.appendFileSync(process.env.GITHUB_ENV, Object.entries(identityEnv).map(([k, v]) => `${k}=${v}\n`).join(''));
-        }
-        catch { /* non-GitHub runner with a stray env var — identity still set for this process */ }
-    }
+    }, { githubEnvPath: process.env.GITHUB_ENV });
     console.log(`\x1b[32m✓ ${result.reused ? 'Pipeline re-enrolled' : 'Pipeline enrolled'}\x1b[0m  ${result.shieldName}`);
     console.log(`  Mode:    ${result.enforcementMode} · Config: ${savedPath}`);
-    // Same protection stack as laptops. The Claude-format hook covers Claude
-    // Code, VS Code agent mode, and Copilot CLI — the common CI agents.
-    if (args.hooks !== 'false') {
-        console.log('\n\x1b[1mInstalling runtime hook (Claude Code / VS Code / Copilot CLI)…\x1b[0m');
-        const hookArgs = {
-            shieldId: result.shieldId,
-            shieldKey: result.shieldKey,
-            apiUrl,
-            events: 'tools,prompt',
-        };
-        try {
-            await (0, installClaudeHook_1.installClaudeHookCommand)(hookArgs, config);
-            await sendLog([{ level: 'success', message: 'Runtime hook installed (Claude Code / VS Code / Copilot CLI)' }]);
-        }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            console.log(`Hook install skipped: ${reason}`);
-            await sendLog([{ level: 'warn', message: `Runtime hook install skipped: ${reason}` }]);
-        }
-    }
-    if (args.gateway !== 'false') {
-        console.log('\n\x1b[1mWrapping MCP client configs with the gateway…\x1b[0m');
-        const gatewayArgs = {
-            shieldId: result.shieldId,
-            shieldKey: result.shieldKey,
-            apiUrl,
-            clients: 'all',
-        };
-        try {
-            await (0, mcpGateway_1.protectAllCommand)(gatewayArgs, config);
-            await sendLog([{ level: 'success', message: 'MCP client configs wrapped with the FullCourtDefense gateway' }]);
-        }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            console.log(`MCP gateway wrap skipped: ${reason}`);
-            await sendLog([{ level: 'warn', message: `MCP gateway wrap skipped: ${reason}` }]);
-        }
-    }
+    // Same protection stack as laptops (shared with workload-protect).
+    await (0, ephemeralStack_1.installEphemeralProtectionStack)({
+        shieldId: result.shieldId,
+        shieldKey: result.shieldKey,
+        apiUrl,
+        hooks: args.hooks,
+        gateway: args.gateway,
+        sendLog,
+    }, config);
     console.log('\n\x1b[32mDone.\x1b[0m This job\'s AI tool calls are now policy-checked and streamed to the fleet console.');
     console.log(`Pipeline appears in AI Fleet → Machines → CI pipelines as \x1b[1m${repo} · ${workflow}\x1b[0m.`);
     await sendLog([{ level: 'success', message: `Protection active (${result.enforcementMode} mode) — this job's AI tool calls are policy-checked and recorded` }], 'succeeded');

package/dist/commands/daemon.js

@@ -145,6 +145,14 @@ const HEARTBEAT_DEADLINE_MS = envMs('FCD_DAEMON_HEARTBEAT_DEADLINE_MS', 120_000)
  */
 const RESUME_BEAT_MS = envMs('FCD_DAEMON_RESUME_BEAT_MS', 30_000);
 const RESUME_JUMP_MS = envMs('FCD_DAEMON_RESUME_JUMP_MS', 120_000);
+/**
+ * Report-in attempts after a resume, and the base delay between them (linear
+ * backoff: 10s, 20s, 30s, 40s). Sized to outlast a normal Wi-Fi reassociation
+ * plus DHCP/DNS, so waking on a slow network costs seconds of staleness rather
+ * than a whole reporting window.
+ */
+const RESUME_REPORT_ATTEMPTS = envMs('FCD_DAEMON_RESUME_ATTEMPTS', 5);
+const RESUME_RETRY_BASE_MS = envMs('FCD_DAEMON_RESUME_RETRY_MS', 10_000);
 /** Delay before the one-time initial discovery sweep on a fresh machine. */
 const INITIAL_DISCOVER_DELAY_MS = envMs('FCD_DAEMON_INITIAL_DISCOVER_MS', 2 * 60_000);
 /** A discovery upload older than this is stale — the daemon catches up itself. */
@@ -582,30 +590,49 @@ async function runDaemon(args, config) {
      * back within one heartbeat instead of up to an hour later (the 8/12
      * incident: re-enroll fixed the hooks instantly while the daemon kept
      * 401-ing for 16 more minutes).
+     *
+     * The same applies when the daemon already HOLDS credentials: a re-enroll
+     * rotates the shield key, so the key in memory is dead the moment
+     * ~/.fullcourtdefense.yml is rewritten. Until 9/3 this function returned
+     * early whenever creds were present, and a re-enrolled laptop's daemon kept
+     * 401-ing (bundle, heartbeat, telemetry) until someone killed the process.
+     * Now a changed enrollment file reloads credentials whether or not the
+     * daemon had some — one heartbeat later it is on the new key.
      */
     const recoverCredentialsIfMissing = () => {
-        if (creds.shieldId && creds.shieldKey)
-            return;
         let enrollmentChanged = false;
         try {
             const mtime = fs.statSync((0, config_1.getHomeConfigPath)()).mtimeMs;
-            enrollmentChanged = mtime !== lastEnrollmentMtimeMs;
+            // First observation only records the baseline; a later different mtime is a re-enroll.
+            enrollmentChanged = lastEnrollmentMtimeMs !== 0 && mtime !== lastEnrollmentMtimeMs;
             lastEnrollmentMtimeMs = mtime;
         }
         catch { /* no config file — the tick cadence below applies */ }
-        credRecoveryTicks += 1;
-        if (!enrollmentChanged && credRecoveryTicks > 3 && credRecoveryTicks % 12 !== 0)
+        const missing = !(creds.shieldId && creds.shieldKey);
+        if (!missing && !enrollmentChanged)
             return;
+        if (missing) {
+            credRecoveryTicks += 1;
+            if (!enrollmentChanged && credRecoveryTicks > 3 && credRecoveryTicks % 12 !== 0)
+                return;
+        }
         try {
             const fresh = (0, config_1.resolveCliCredentials)((0, config_1.loadConfig)(args.config), {
                 shieldId: args.shieldId,
                 shieldKey: args.shieldKey,
                 apiUrl: args.apiUrl,
             });
-            if (fresh.shieldId && fresh.shieldKey) {
+            if (!fresh.shieldId || !fresh.shieldKey)
+                return;
+            const rotated = fresh.shieldId !== creds.shieldId || fresh.shieldKey !== creds.shieldKey || fresh.apiUrl !== creds.apiUrl;
+            if (missing) {
                 Object.assign(creds, fresh);
                 log('Credentials recovered — telemetry and control-plane sync restored.');
             }
+            else if (rotated) {
+                Object.assign(creds, fresh);
+                log(`Enrollment changed on disk — reloaded credentials (shield ${fresh.shieldId}); telemetry and control-plane sync continue on the new key.`);
+            }
         }
         catch { /* next tick */ }
     };
@@ -1298,6 +1325,14 @@ async function runDaemon(args, config) {
         recoverCredentialsIfMissing();
         if (!creds.shieldId)
             return;
+        // Did THIS beat actually record daemon liveness upstream? `flushSpool`
+        // reports every failure by returning null and never throws, so without
+        // this flag a heartbeat that never left the machine was indistinguishable
+        // from a delivered one — and the loop happily waited a full cadence before
+        // trying again. `null` also covers the case where a hook flusher held the
+        // flush lock, which drops the daemon marker specifically (hook flushes do
+        // not set `daemon: true`), so retrying soon is right in that case too.
+        let reported = false;
         try {
             let integrity = (0, integrity_1.getLocalIntegrityReport)({ requireDaemon: true });
             // A failing verdict used to be REPORTED and nothing more, so a machine
@@ -1348,6 +1383,7 @@ async function runDaemon(args, config) {
                     }
                     : undefined,
             });
+            reported = result !== null;
             if (result && unreportedCrash)
                 (0, daemonForensics_1.markPostmortemReported)();
             if (result && result.accepted > 0)
@@ -1358,8 +1394,13 @@ async function runDaemon(args, config) {
         }
         catch { /* spool stays on disk for the next tick */ }
         // Settle any in-flight upgrade_cli action (success once the new build is
-        // live, failure when the target never arrived).
+        // live, failure when the target never arrived). Runs BEFORE the failure
+        // signal below so a lost heartbeat can never strand a pending upgrade.
         await verifyPendingUpgrade();
+        // Surface the miss to the caller (poll loop / resume path) so it retries in
+        // seconds. Nothing else can tell them: liveness has exactly one writer.
+        if (!reported)
+            throw new Error('heartbeat did not reach the backend — daemon liveness was not recorded');
     };
     // --- boot ---------------------------------------------------------------
     // Self-heal autostart + watchdog tasks: machines installed by older versions
@@ -1385,7 +1426,19 @@ async function runDaemon(args, config) {
     // would report a false "damaged" state (and fire admin integrity alerts)
     // for a condition the very next line repairs.
     await reprotect(['startup pass']);
-    await heartbeat();
+    // The FIRST beat must not be able to abort the rest of this function.
+    // `heartbeat` throws when the report did not reach the backend (that is how
+    // the poll loop knows to retry in seconds), and an exception here propagates
+    // out of `runDaemon` and skips every loop registered below it — the heartbeat
+    // loop, the resume timer and the bundle poll. The process itself survives on
+    // the `unhandledRejection` handler, which is worse than dying: it holds the
+    // pid lock, so the scheduled task declines to start a replacement, and it
+    // never polls the bundle, so no remote action can reach it. Booting before
+    // the network is up (captive portal, VPN, resumed in a lift) is routine, and
+    // the heartbeat loop below retries within seconds.
+    await heartbeat().catch(error => {
+        log(`First heartbeat did not reach the backend (${error?.message || String(error)}) — the heartbeat loop will retry shortly.`);
+    });
     // Claude Desktop chat guard (Windows, advisory): Claude Desktop's regular
     // chat has no hook and never hits an MCP server, so it is the one machine
     // surface neither hooks nor the gateway can see. Supervise the advisory guard
@@ -1535,6 +1588,39 @@ async function runDaemon(args, config) {
     // closes the reporting gap and removes the evidence of a hang that never
     // happened. Both calls go through runWithDeadline, so a resume that lands on
     // sockets which died during sleep cannot leak an unhandled rejection.
+    // The resume beat is RETRIED, because it fires the instant the wall-clock
+    // jump is noticed — which on a laptop is reliably before Wi-Fi has
+    // reassociated. As a single shot, the one beat whose whole job is to prove
+    // the daemon survived the sleep was also the likeliest to be lost, and modern
+    // standby routinely re-suspends the machine before the next cadence tick, so
+    // liveness could stay stale indefinitely while IDE-hook flushes kept the
+    // machine "online" — a live daemon displayed as down.
+    let resumeReportInFlight = false;
+    const reportInAfterResume = async () => {
+        if (resumeReportInFlight)
+            return; // a previous resume is still catching up
+        resumeReportInFlight = true;
+        try {
+            for (let attempt = 1; attempt <= RESUME_REPORT_ATTEMPTS; attempt++) {
+                let failed = false;
+                const outcome = await (0, pollLoop_1.runWithDeadline)({
+                    run: heartbeat,
+                    deadlineMs: HEARTBEAT_DEADLINE_MS,
+                    onError: () => { failed = true; },
+                });
+                if (outcome === 'settled' && !failed)
+                    return; // liveness recorded
+                if (attempt === RESUME_REPORT_ATTEMPTS) {
+                    log(`Resume report-in did not land after ${attempt} attempt(s) — the scheduled heartbeat keeps retrying.`);
+                    return;
+                }
+                await new Promise(resolve => setTimeout(resolve, RESUME_RETRY_BASE_MS * attempt));
+            }
+        }
+        finally {
+            resumeReportInFlight = false;
+        }
+    };
     let lastResumeBeatMs = Date.now();
     const resumeTimer = setInterval(() => {
         const now = Date.now();
@@ -1544,7 +1630,7 @@ async function runDaemon(args, config) {
             return;
         log(`Resume detected: ${Math.round(drift / 1000)}s of wall time elapsed while suspended — refreshing liveness and reporting in now.`);
         (0, daemonForensics_1.touchDaemonAlive)();
-        void (0, pollLoop_1.runWithDeadline)({ run: heartbeat, deadlineMs: HEARTBEAT_DEADLINE_MS });
+        void reportInAfterResume();
         void (0, pollLoop_1.runWithDeadline)({ run: pollBundle, deadlineMs: BUNDLE_POLL_DEADLINE_MS });
     }, RESUME_BEAT_MS);
     // PowerShell transcript retention (Windows): the Transcription policy FCD

package/dist/commands/demoActions.d.ts

@@ -0,0 +1,117 @@
+import type { BotGuardConfig } from '../config';
+import { type LocalSafetySnapshot } from '../localSafetySnapshot';
+export interface DemoActionsArgs {
+    live?: string;
+    json?: string;
+    demoPolicies?: string;
+    timeout?: string;
+}
+export type DemoEvent = 'shell' | 'mcp' | 'read' | 'file';
+export interface DemoScenario {
+    id: string;
+    /** One line a security lead understands. */
+    title: string;
+    event: DemoEvent;
+    /** Payload in the exact shape the IDE hook receives. */
+    payload: Record<string, unknown>;
+    /** What the scenario is meant to show. */
+    why: string;
+}
+export interface DemoScenarioResult {
+    id: string;
+    title: string;
+    event: DemoEvent;
+    action: string;
+    permission: 'allow' | 'deny' | 'ask' | 'unknown';
+    reason?: string;
+    /**
+     * Catalog rules that matched at WARN level (recorded as findings, action allowed). Shown so
+     * an allowed credential read is not mistaken for "not noticed": the org can flip these
+     * rules to block in the console. Offline replay only.
+     */
+    flagged?: string[];
+    /** Monitor/shadow machines allow and report what WOULD have been blocked. */
+    wouldBlock?: boolean;
+    latencyMs: number;
+    raw?: Record<string, unknown>;
+}
+export interface DemoActionsReport {
+    mode: 'offline' | 'live';
+    policySource: 'machine-cache' | 'demo-policies';
+    machineMode: 'block' | 'monitor' | 'shadow' | 'unknown';
+    policyCount: number;
+    shieldId: string;
+    scenarios: DemoScenarioResult[];
+    summary: {
+        allow: number;
+        deny: number;
+        ask: number;
+        wouldBlock: number;
+        unknown: number;
+    };
+}
+/**
+ * Policies seeded when the machine has no cached bundle (not enrolled). Plain
+ * action policies in the shape the engine evaluates — labelled so the output
+ * cannot be mistaken for the org's real configuration.
+ */
+export declare const DEMO_POLICIES: ({
+    id: string;
+    name: string;
+    resourceType: string;
+    rules: {
+        operations: string[];
+        verdict: string;
+    }[];
+} | {
+    id: string;
+    name: string;
+    resourceType: string;
+    rules: {
+        operations: string[];
+        verdict: string;
+        constraints: {
+            field: string;
+            operator: string;
+            value: string;
+        }[];
+    }[];
+})[];
+export declare const DEMO_SCENARIOS: DemoScenario[];
+/**
+ * Build the throw-away HOME for an offline replay. Copies this machine's cached
+ * policy bundle when there is one (refreshed so the hook does not try to
+ * revalidate against the dead API), otherwise seeds the demo policy set.
+ */
+export interface OfflineHome {
+    home: string;
+    policySource: 'machine-cache' | 'demo-policies';
+    shieldId: string;
+    /** Machine mode carried over from the cache (`monitor` machines record would-block instead of denying). */
+    mode: 'block' | 'monitor' | 'shadow';
+    /** Number of org action policies in the replayed cache (0 = enrolled org without policies yet). */
+    policyCount: number;
+}
+export declare function prepareOfflineHome(realHome: string, shieldId: string, forceDemoPolicies?: boolean): OfflineHome;
+interface RunOptions {
+    cliPath: string;
+    home: string;
+    /** Offline replay: explicit sandbox credentials + dead API. Live: absent — the hook loads the machine's real config (incl. DPAPI keys). */
+    sandbox?: {
+        apiUrl: string;
+        shieldId: string;
+        shieldKey: string;
+    };
+    timeoutMs: number;
+    developerId: string;
+}
+export declare function runScenario(scenario: DemoScenario, opts: RunOptions): DemoScenarioResult;
+/**
+ * Which catalog rules matched at WARN level for a scenario — the same scan the hook ran
+ * (same guard, same snapshot) — so the report can show "allowed, but flagged". The hook
+ * spools these as findings; it does not put them in the verdict it hands the IDE.
+ */
+export declare function flaggedRules(scenario: DemoScenario, snapshot: LocalSafetySnapshot | undefined): string[];
+export declare function renderReport(report: DemoActionsReport): string;
+export declare function demoActionsCommand(args: DemoActionsArgs, config: BotGuardConfig): Promise<void>;
+export {};