fullcourtdefense-cli 1.26.15 → 1.26.17

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/cliVersion.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The installed CLI version.
+ *
+ * `process.env.npm_package_version` is only populated when npm itself runs the
+ * script (`npm run …`). A container entrypoint, an MSI install, or a CI step
+ * calling the `fullcourtdefense` binary directly gets `undefined` — which is how
+ * enrolled workloads ended up with a blank CLI version in the fleet console.
+ * Resolve it from disk instead: the build stamp `dist/version.json` first
+ * (same source `--version` prints), then the package manifest.
+ */
+export declare function cliVersion(): string | undefined;

package/dist/cliVersion.js

@@ -0,0 +1,65 @@
+"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.cliVersion = cliVersion;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * The installed CLI version.
+ *
+ * `process.env.npm_package_version` is only populated when npm itself runs the
+ * script (`npm run …`). A container entrypoint, an MSI install, or a CI step
+ * calling the `fullcourtdefense` binary directly gets `undefined` — which is how
+ * enrolled workloads ended up with a blank CLI version in the fleet console.
+ * Resolve it from disk instead: the build stamp `dist/version.json` first
+ * (same source `--version` prints), then the package manifest.
+ */
+function cliVersion() {
+    const candidates = [
+        path.join(__dirname, 'version.json'),
+        path.resolve(__dirname, '..', 'package.json'),
+    ];
+    for (const file of candidates) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (typeof parsed.version === 'string' && parsed.version)
+                return parsed.version;
+        }
+        catch {
+            // try the next location
+        }
+    }
+    return undefined;
+}

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,10 @@
 "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 cliVersion_1 = require("../cliVersion");
+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 +55,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();
@@ -113,7 +82,7 @@ async function ciProtectCommand(args, config) {
             workflow,
             runId,
             runUrl,
-            cliVersion: process.env.npm_package_version,
+            cliVersion: (0, cliVersion_1.cliVersion)(),
         }),
     });
     const data = (await resp.json().catch(() => ({})));
@@ -129,62 +98,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

@@ -590,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 */ }
     };

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 {};