fullcourtdefense-cli 1.22.8 → 1.24.0

package/dist/commands/approve.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `fullcourtdefense approve [id] [--deny]` — resolve taint-guard approve-once
+ * requests from the developer's OWN terminal.
+ *
+ * With no id: lists pending requests (id, age, held action, destinations).
+ * With an id: approves the single held action (or denies with --deny).
+ *
+ * This command is deliberately terminal-only and local: the agent-side hook
+ * blocks any AI agent that tries to run it (local-taint-self-approval), so a
+ * decision here always comes from the human at the keyboard.
+ */
+export interface ApproveArgs {
+    id?: string;
+    deny?: boolean;
+    json?: boolean;
+}
+export declare function approveCommand(args: ApproveArgs): Promise<void>;

package/dist/commands/approve.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.approveCommand = approveCommand;
+const taintLedger_1 = require("./taintLedger");
+function ageSeconds(createdAt) {
+    const created = Date.parse(createdAt);
+    return Number.isFinite(created) ? Math.max(0, Math.round((Date.now() - created) / 1000)) : 0;
+}
+async function approveCommand(args) {
+    if (!args.id) {
+        const pending = (0, taintLedger_1.listTaintApprovals)();
+        if (args.json) {
+            console.log(JSON.stringify({ pending }, null, 2));
+            return;
+        }
+        if (pending.length === 0) {
+            console.log('No pending approve-once requests.');
+            console.log('(Requests appear here when the taint guard holds an agent action for your decision.)');
+            return;
+        }
+        console.log(`\x1b[1m${pending.length} pending approve-once request${pending.length === 1 ? '' : 's'}:\x1b[0m\n`);
+        for (const req of pending) {
+            console.log(`  \x1b[1m${req.id}\x1b[0m  (${ageSeconds(req.createdAt)}s ago)  ${req.toolName} -> ${req.targets.join(', ') || 'external destination'}`);
+            if (req.detail)
+                console.log(`      ${req.detail}`);
+            console.log(`      approve: fullcourtdefense approve ${req.id}`);
+            console.log(`      deny:    fullcourtdefense approve ${req.id} --deny\n`);
+        }
+        return;
+    }
+    const result = (0, taintLedger_1.resolveTaintApproval)(args.id, args.deny ? 'denied' : 'approved');
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(result.ok ? `\x1b[32m${result.message}\x1b[0m` : `\x1b[31m${result.message}\x1b[0m`);
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/commands/ciProtect.d.ts

@@ -0,0 +1,42 @@
+import { BotGuardConfig } from '../config';
+/**
+ * `fullcourtdefense ci-protect` — one-command runtime protection for CI jobs.
+ *
+ * A CI runner is born, runs one job with an AI agent inside, and dies — no
+ * human to click a consent dialog, no durable disk for a fleet token. So the
+ * flow differs from laptop onboarding in exactly two ways:
+ *
+ *   1. Auth is the org API key (FCD_API_KEY repo secret) — the admin who put
+ *      it there consented for the pipeline.
+ *   2. Fleet identity is the PIPELINE (provider/repo/workflow), not the
+ *      runner: the backend converges every run onto one machine record, and
+ *      we export FCD_MACHINE_ID so the hooks installed here attribute all
+ *      events to that pipeline record.
+ *
+ * Everything else is the exact laptop stack: same Claude-format hook, same
+ * MCP gateway, same vendored policy engine enforcing offline.
+ */
+export interface CiProtectArgs {
+    apiKey?: string;
+    apiUrl?: string;
+    provider?: string;
+    repo?: string;
+    workflow?: string;
+    runId?: string;
+    runUrl?: string;
+    /** 'false' => skip installing the Claude-format runtime hook. */
+    hooks?: string;
+    /** 'false' => skip wrapping MCP client configs with the gateway. */
+    gateway?: string;
+}
+interface CiContext {
+    provider: string;
+    repo?: string;
+    workflow?: string;
+    runId?: string;
+    runUrl?: string;
+}
+/** Detect the pipeline from standard CI env vars (GitHub Actions, GitLab CI). */
+export declare function detectCiContext(env?: NodeJS.ProcessEnv): CiContext | undefined;
+export declare function ciProtectCommand(args: CiProtectArgs, config: BotGuardConfig): Promise<void>;
+export {};

package/dist/commands/ciProtect.js

@@ -0,0 +1,191 @@
+"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");
+/** Detect the pipeline from standard CI env vars (GitHub Actions, GitLab CI). */
+function detectCiContext(env = process.env) {
+    if (env.GITHUB_ACTIONS === 'true') {
+        const repo = env.GITHUB_REPOSITORY || undefined;
+        const runId = env.GITHUB_RUN_ID || undefined;
+        return {
+            provider: 'github-actions',
+            repo,
+            workflow: env.GITHUB_WORKFLOW || undefined,
+            runId,
+            runUrl: repo && runId ? `${env.GITHUB_SERVER_URL || 'https://github.com'}/${repo}/actions/runs/${runId}` : undefined,
+        };
+    }
+    if (env.GITLAB_CI === 'true') {
+        return {
+            provider: 'gitlab-ci',
+            repo: env.CI_PROJECT_PATH || undefined,
+            workflow: env.CI_JOB_NAME || env.CI_PIPELINE_NAME || undefined,
+            runId: env.CI_PIPELINE_ID || undefined,
+            runUrl: env.CI_PIPELINE_URL || undefined,
+        };
+    }
+    return undefined;
+}
+/**
+ * Best-effort log streaming to the dashboard's CI Pipelines page — the admin
+ * watches this job's protection steps live without opening GitHub. Never
+ * throws and never blocks the job for more than a few seconds.
+ */
+function ciLogSender(apiUrl, apiKey, ctx) {
+    return async (lines, status) => {
+        try {
+            await fetch(`${apiUrl}/api/cli/ci-log`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+                body: JSON.stringify({ ...ctx, lines, status }),
+                signal: AbortSignal.timeout(4000),
+            });
+        }
+        catch { /* log delivery is best-effort */ }
+    };
+}
+async function ciProtectCommand(args, config) {
+    const creds = (0, config_1.resolveCliCredentials)(config, { apiUrl: args.apiUrl });
+    const apiUrl = creds.apiUrl;
+    const apiKey = (args.apiKey || process.env.FCD_API_KEY || '').trim();
+    if (!apiKey) {
+        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.');
+    }
+    const detected = detectCiContext();
+    const provider = (args.provider || detected?.provider || 'generic-ci').trim();
+    const repo = (args.repo || detected?.repo || '').trim();
+    const workflow = (args.workflow || detected?.workflow || '').trim();
+    if (!repo || !workflow) {
+        throw new Error('Could not detect the pipeline identity. On GitHub Actions / GitLab CI it is auto-detected; '
+            + 'elsewhere pass --repo <org/repo> --workflow <name>.');
+    }
+    const runId = (args.runId || detected?.runId || '').trim() || undefined;
+    const runUrl = (args.runUrl || detected?.runUrl || '').trim() || undefined;
+    console.log('\x1b[1m\x1b[36mFullCourtDefense — CI runtime protection\x1b[0m');
+    console.log(`  Pipeline: ${provider}/${repo}/${workflow}`);
+    if (runId)
+        console.log(`  Run:      ${runId}`);
+    const sendLog = ciLogSender(apiUrl, apiKey, { provider, repo, workflow, runId, runUrl });
+    const resp = await fetch(`${apiUrl}/api/cli/enroll/ci`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+        body: JSON.stringify({
+            provider,
+            repo,
+            workflow,
+            runId,
+            runUrl,
+            cliVersion: process.env.npm_package_version,
+        }),
+    });
+    const data = (await resp.json().catch(() => ({})));
+    if (!resp.ok || data.success === false || !data.data) {
+        const reason = data.error || `CI enrollment failed (HTTP ${resp.status})`;
+        await sendLog([{ level: 'error', message: `Enrollment failed: ${reason}` }], 'failed');
+        throw new Error(reason);
+    }
+    const result = data.data;
+    const savedPath = (0, config_1.saveSetupConfig)({
+        organizationId: result.organizationId,
+        shieldId: result.shieldId,
+        shieldKey: result.shieldKey,
+        apiUrl,
+    });
+    // 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 = {
+        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 */ }
+    }
+    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}` }]);
+        }
+    }
+    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/hook.js

@@ -826,6 +826,84 @@ async function hookCommand(args, config) {
     // Unknown event → nothing to enforce.
     respond(false);
 }
+/**
+ * Approve-once for a taint-guard block: hold the action, alert the human at
+ * the keyboard, and poll for their one-time decision from their OWN terminal
+ * (`fullcourtdefense approve <ID>`). Returns true only when the developer
+ * approved — the caller then continues the normal pipeline for this single
+ * action. In every other outcome (denied / timeout / disabled / store error)
+ * this function responds with a block and the caller must return.
+ *
+ * The approval ID is shown ONLY via the native OS alert and the developer's
+ * terminal — never in the agent-visible messages — so a compromised agent
+ * cannot learn or redeem it (and self-protection blocks it from trying).
+ */
+async function runTaintApproveOnce(ctx, event, call, sessId, taintFinding) {
+    const { respond } = ctx;
+    const hardBlock = () => {
+        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: taintFinding.reason, ruleId: taintFinding.ruleId, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(true);
+        respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason}`, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} Do not retry.`);
+        return false;
+    };
+    const approveOnceEnabled = process.env.FCD_TAINT_APPROVE_ONCE_DISABLED !== 'true'
+        && process.env.FCD_TAINT_APPROVE_ONCE_DISABLED !== '1'
+        && ctx.approvalMode !== 'block';
+    if (!approveOnceEnabled)
+        return hardBlock();
+    const approval = (0, taintLedger_1.createTaintApproval)({
+        sessionId: sessId,
+        event,
+        toolName: call.toolName,
+        reason: taintFinding.reason,
+        detail: taintFinding.sink.detail,
+        targets: taintFinding.sink.targets,
+    });
+    if (!approval)
+        return hardBlock();
+    const timeoutMs = Number(process.env.FCD_TAINT_APPROVAL_TIMEOUT_MS) > 0
+        ? Number(process.env.FCD_TAINT_APPROVAL_TIMEOUT_MS)
+        : 120000; // local developer decision — short window, they are at the keyboard
+    const targetText = taintFinding.sink.targets.join(', ') || 'an external destination';
+    // forceWindow: a toast can be swallowed by Focus Assist; this decision must be seen.
+    (0, notify_1.notifyOs)({
+        forceWindow: true,
+        title: 'FullCourtDefense — approve once?',
+        message: `Agent action held: ${call.toolName} -> ${targetText}\n`
+            + `${approval.detail}\n\n`
+            + `Allow ONCE:  fullcourtdefense approve ${approval.id}\n`
+            + `Deny:        fullcourtdefense approve ${approval.id} --deny\n`
+            + `(run "fullcourtdefense approve" to list; expires in ${Math.round(timeoutMs / 60000)} min)`,
+    });
+    dbg({ phase: 'taint_approve_once_wait', event, tool: call.toolName, approvalId: approval.id, timeoutMs });
+    const outcome = await (0, taintLedger_1.waitForTaintApproval)(approval.id, timeoutMs, Math.max(750, Math.min(ctx.approvalPollMs, 2000)));
+    dbg({ phase: 'taint_approve_once_outcome', approvalId: approval.id, outcome });
+    if (outcome === 'approved') {
+        (0, telemetry_1.spoolEvent)({
+            decision: 'allow',
+            toolName: call.toolName,
+            reason: `Developer approved once after taint-guard hold (${taintFinding.ruleId}): ${taintFinding.reason}`,
+            ruleId: taintFinding.ruleId,
+            offlineEnforced: true,
+        });
+        (0, telemetry_1.triggerFlush)(true);
+        (0, notify_1.notifyOs)({ title: 'FullCourtDefense — approved once', message: `${call.toolName} -> ${targetText} will continue.` });
+        return true;
+    }
+    (0, telemetry_1.spoolEvent)({
+        decision: 'block',
+        toolName: call.toolName,
+        reason: `${taintFinding.reason} Developer ${outcome === 'denied' ? 'denied the approve-once request' : 'did not respond to the approve-once request'}.`,
+        ruleId: taintFinding.ruleId,
+        offlineEnforced: true,
+    });
+    (0, telemetry_1.triggerFlush)(true);
+    respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason} `
+        + (outcome === 'denied'
+            ? 'You denied the approve-once request.'
+            : 'The approve-once request expired with no decision. If you want this action, re-run it and approve from your own terminal (fullcourtdefense approve).'), `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} The developer was asked and did not approve. Do not retry.`);
+    return false;
+}
 async function enforceActionPolicy(ctx) {
     const { event, payload, apiUrl, shieldId, shieldKey, shadow, timeoutMs, respond, effectivePolicyHash } = ctx;
     const call = buildToolCall(event, payload);
@@ -858,6 +936,21 @@ async function enforceActionPolicy(ctx) {
         respond(true, localBlockUserMessage(localBlock), `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry.`);
         return;
     }
+    // --- Taint-guard self-protection (always enforced before anything taint) ---
+    // The agent must never resolve approve-once requests or touch the taint
+    // state directory; otherwise a compromised agent could approve itself.
+    const selfApproval = (0, taintLedger_1.detectTaintSelfApproval)(event, call.toolName, call.toolArgs);
+    if (selfApproval) {
+        dbg({ phase: 'taint_self_approval_block', event, tool: call.toolName });
+        if (shadow) {
+            respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${selfApproval.reason}`);
+            return;
+        }
+        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: selfApproval.reason, ruleId: 'local-taint-self-approval', offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(true);
+        respond(true, `Blocked by FullCourtDefense self-protection — ${selfApproval.reason}`, `FullCourtDefense blocked this ${event} locally (local-taint-self-approval): ${selfApproval.reason} Do not retry.`);
+        return;
+    }
     // --- Deterministic taint tracking (local, no backend) ---
     // Evaluate the sink against the PRIOR ledger state first, BEFORE this event
     // records its own ingress (so a lone remote pull doesn't self-taint then
@@ -871,10 +964,11 @@ async function enforceActionPolicy(ctx) {
             respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${taintFinding.reason}`);
             return;
         }
-        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: taintFinding.reason, ruleId: taintFinding.ruleId, offlineEnforced: true });
-        (0, telemetry_1.triggerFlush)(true);
-        respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason}`, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} Do not retry.`);
-        return;
+        const approved = await runTaintApproveOnce(ctx, event, call, sessId, taintFinding);
+        if (!approved)
+            return; // runTaintApproveOnce already responded (blocked)
+        // Developer approved this single action — continue the normal pipeline so
+        // Action Policies and server checks still apply to it.
     }
     // Record untrusted ingress for this event (never blocks).
     (0, taintLedger_1.noteIngress)(sessId, event, call.toolName, call.toolArgs);

package/dist/commands/taintLedger.d.ts

@@ -55,4 +55,48 @@ export declare function detectSink(event: EventKind, toolName: string, toolArgs:
 export declare function checkTaintedSink(sessionId: string, event: EventKind, toolName: string, toolArgs: Record<string, unknown>): TaintFinding | undefined;
 /** Record ingress for an event if applicable. Safe to call on every event. */
 export declare function noteIngress(sessionId: string, event: EventKind, toolName: string, toolArgs: Record<string, unknown>, workspacePath?: string): TaintSource | undefined;
+export type TaintApprovalStatus = 'pending' | 'approved' | 'denied';
+export interface TaintApprovalRequest {
+    id: string;
+    sessionId: string;
+    status: TaintApprovalStatus;
+    event: string;
+    toolName: string;
+    reason: string;
+    /** The exact command/action detail being held (shown to the human, never to the agent). */
+    detail: string;
+    targets: string[];
+    createdAt: string;
+}
+/** Create a pending approve-once request for a taint finding. Returns undefined on disk errors. */
+export declare function createTaintApproval(input: {
+    sessionId: string;
+    event: string;
+    toolName: string;
+    reason: string;
+    detail: string;
+    targets: string[];
+}): TaintApprovalRequest | undefined;
+/** All live pending approve-once requests (expired ones are pruned). */
+export declare function listTaintApprovals(): TaintApprovalRequest[];
+/** Resolve a pending request (developer's terminal). Returns an outcome message. */
+export declare function resolveTaintApproval(id: string, decision: 'approved' | 'denied'): {
+    ok: boolean;
+    message: string;
+};
+/**
+ * Block until the request is approved/denied or the timeout elapses.
+ * ALWAYS consumes (deletes) the request file on exit — the decision applies to
+ * the single held action only and can never be redeemed later.
+ */
+export declare function waitForTaintApproval(id: string, timeoutMs: number, pollMs: number): Promise<'approved' | 'denied' | 'timeout'>;
+/**
+ * Deterministic rule: any agent attempt to run the approve command, or to
+ * read/write the taint state directory (pending IDs / ledger files), is
+ * blocked regardless of taint state. Only a human in their own terminal may
+ * resolve approve-once requests.
+ */
+export declare function detectTaintSelfApproval(event: EventKind, toolName: string, toolArgs: Record<string, unknown>): {
+    reason: string;
+} | undefined;
 export {};

package/dist/commands/taintLedger.js

@@ -42,6 +42,12 @@ exports.classifyIngress = classifyIngress;
 exports.detectSink = detectSink;
 exports.checkTaintedSink = checkTaintedSink;
 exports.noteIngress = noteIngress;
+exports.createTaintApproval = createTaintApproval;
+exports.listTaintApprovals = listTaintApprovals;
+exports.resolveTaintApproval = resolveTaintApproval;
+exports.waitForTaintApproval = waitForTaintApproval;
+exports.detectTaintSelfApproval = detectTaintSelfApproval;
+const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -368,3 +374,206 @@ function noteIngress(sessionId, event, toolName, toolArgs, workspacePath) {
         markTaint(sessionId, source);
     return source;
 }
+// ---------------------------------------------------------------------------
+// Approve-once — one-shot human approval for a taint-blocked action
+// ---------------------------------------------------------------------------
+//
+// When the taint guard blocks a sink, the hook can HOLD the action and ask the
+// human at the keyboard for a one-time decision instead of hard-failing:
+//
+//   1. hook writes a pending request file under ~/.fullcourtdefense/taint/approvals/
+//   2. the developer sees a native OS alert and runs, in their OWN terminal:
+//        fullcourtdefense approve <ID>            (allow this one action)
+//        fullcourtdefense approve <ID> --deny     (reject it)
+//   3. the hook polls the file; on approval the HELD action continues, once.
+//
+// One-shot by construction: the waiting hook deletes the request file the
+// moment it resolves (approved, denied, or timed out). A late `approve` after
+// timeout finds nothing to approve — a previously blocked command can never be
+// released retroactively. Approving never whitelists the host or the session;
+// the very next unrequested sink is checked again from scratch.
+//
+// The agent must never approve its own actions. `detectTaintSelfApproval`
+// gives the hook a deterministic rule that blocks any agent attempt to run the
+// approve command or to touch the taint state directory (which would let it
+// read pending IDs or forge an "approved" status).
+const APPROVAL_TTL_MS = 10 * 60 * 1000; // pending requests older than 10 min are dead
+/** Unambiguous alphabet (no 0/O/1/I/L) so IDs are easy to retype from an alert. */
+const APPROVAL_ID_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+function approvalsDir() {
+    return path.join(taintDir(), 'approvals');
+}
+function approvalPath(id) {
+    return path.join(approvalsDir(), `${id.toUpperCase().replace(/[^A-Z0-9]/g, '')}.json`);
+}
+function newApprovalId() {
+    const bytes = crypto.randomBytes(6);
+    let id = '';
+    for (const b of bytes)
+        id += APPROVAL_ID_ALPHABET[b % APPROVAL_ID_ALPHABET.length];
+    return id;
+}
+function readApproval(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!parsed.id || !parsed.createdAt)
+            return undefined;
+        return {
+            id: parsed.id,
+            sessionId: parsed.sessionId || '',
+            status: parsed.status === 'approved' || parsed.status === 'denied' ? parsed.status : 'pending',
+            event: parsed.event || 'unknown',
+            toolName: parsed.toolName || '',
+            reason: parsed.reason || '',
+            detail: parsed.detail || '',
+            targets: Array.isArray(parsed.targets) ? parsed.targets.filter(t => typeof t === 'string') : [],
+            createdAt: parsed.createdAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isExpired(req) {
+    const created = Date.parse(req.createdAt);
+    return !Number.isFinite(created) || Date.now() - created > APPROVAL_TTL_MS;
+}
+/** Best-effort removal of expired approval request files. */
+function pruneApprovals() {
+    try {
+        const dir = approvalsDir();
+        if (!fs.existsSync(dir))
+            return;
+        for (const name of fs.readdirSync(dir)) {
+            const file = path.join(dir, name);
+            const req = readApproval(file);
+            if (!req || isExpired(req)) {
+                try {
+                    fs.unlinkSync(file);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* ignore */ }
+}
+/** Create a pending approve-once request for a taint finding. Returns undefined on disk errors. */
+function createTaintApproval(input) {
+    try {
+        fs.mkdirSync(approvalsDir(), { recursive: true });
+        pruneApprovals();
+        const req = {
+            id: newApprovalId(),
+            sessionId: input.sessionId,
+            status: 'pending',
+            event: input.event,
+            toolName: input.toolName,
+            reason: input.reason.slice(0, 600),
+            detail: input.detail.slice(0, 400),
+            targets: input.targets.slice(0, 10),
+            createdAt: nowIso(),
+        };
+        fs.writeFileSync(approvalPath(req.id), JSON.stringify(req, null, 2), 'utf8');
+        return req;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** All live pending approve-once requests (expired ones are pruned). */
+function listTaintApprovals() {
+    pruneApprovals();
+    try {
+        const dir = approvalsDir();
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const name of fs.readdirSync(dir)) {
+            const req = readApproval(path.join(dir, name));
+            if (req && req.status === 'pending')
+                out.push(req);
+        }
+        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    catch {
+        return [];
+    }
+}
+/** Resolve a pending request (developer's terminal). Returns an outcome message. */
+function resolveTaintApproval(id, decision) {
+    const file = approvalPath(id);
+    const req = fs.existsSync(file) ? readApproval(file) : undefined;
+    if (!req || isExpired(req)) {
+        return { ok: false, message: `No pending approve-once request "${id.toUpperCase()}" — it may have expired or already resolved. Run "fullcourtdefense approve" to list pending requests.` };
+    }
+    if (req.status !== 'pending') {
+        return { ok: false, message: `Request ${req.id} was already ${req.status}.` };
+    }
+    try {
+        fs.writeFileSync(file, JSON.stringify({ ...req, status: decision }, null, 2), 'utf8');
+        return { ok: true, message: `${decision === 'approved' ? 'Approved' : 'Denied'} ${req.id}: ${req.toolName} -> ${req.targets.join(', ') || 'external destination'}. ${decision === 'approved' ? 'The held action will continue once.' : 'The held action stays blocked.'}` };
+    }
+    catch (err) {
+        return { ok: false, message: `Could not write decision: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Block until the request is approved/denied or the timeout elapses.
+ * ALWAYS consumes (deletes) the request file on exit — the decision applies to
+ * the single held action only and can never be redeemed later.
+ */
+async function waitForTaintApproval(id, timeoutMs, pollMs) {
+    const file = approvalPath(id);
+    const deadline = Date.now() + Math.max(1000, timeoutMs);
+    try {
+        while (Date.now() < deadline) {
+            const req = fs.existsSync(file) ? readApproval(file) : undefined;
+            if (!req)
+                return 'denied'; // file vanished — treat as not approved
+            if (req.status === 'approved')
+                return 'approved';
+            if (req.status === 'denied')
+                return 'denied';
+            await new Promise(resolve => setTimeout(resolve, Math.max(250, pollMs)));
+        }
+        return 'timeout';
+    }
+    finally {
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* already gone */ }
+    }
+}
+// --- Self-protection: the agent must never approve its own held actions -----
+const SELF_APPROVE_CMD = /\b(?:fullcourtdefense|fcd|botguard)(?:\.cmd|\.exe|\.ps1|\.js)?["']?\s+(?:approve|deny)\b/i;
+const TAINT_STATE_PATH = /\.fullcourtdefense[\\/]+taint\b/i;
+/**
+ * Deterministic rule: any agent attempt to run the approve command, or to
+ * read/write the taint state directory (pending IDs / ledger files), is
+ * blocked regardless of taint state. Only a human in their own terminal may
+ * resolve approve-once requests.
+ */
+function detectTaintSelfApproval(event, toolName, toolArgs) {
+    if (!taintEnabled())
+        return undefined;
+    // For file edits/reads only the TARGET PATH matters — file contents may
+    // legitimately mention these strings (e.g. this repo's own source/tests).
+    const strings = event === 'file' || event === 'read'
+        ? [
+            typeof toolArgs.path === 'string' ? toolArgs.path : '',
+            typeof toolArgs.file_path === 'string' ? toolArgs.file_path : '',
+        ].filter(Boolean)
+        : [...collectStringValues(toolArgs), toolName];
+    for (const value of strings) {
+        if (event === 'shell' || event === 'mcp') {
+            if (SELF_APPROVE_CMD.test(value)) {
+                return { reason: 'Agents may not run the FullCourtDefense approve command. Only the developer, from their own terminal, can resolve approve-once requests.' };
+            }
+        }
+        if (TAINT_STATE_PATH.test(value)) {
+            return { reason: 'Agents may not access the FullCourtDefense taint state directory (approval requests and session ledgers are human-only).' };
+        }
+    }
+    return undefined;
+}

package/dist/index.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const config_1 = require("./config");
 const scan_1 = require("./commands/scan");
 const credits_1 = require("./commands/credits");
+const approve_1 = require("./commands/approve");
 const init_1 = require("./commands/init");
 const doctor_1 = require("./commands/doctor");
 const configure_1 = require("./commands/configure");
@@ -49,6 +50,7 @@ const installCursorHook_1 = require("./commands/installCursorHook");
 const installClaudeHook_1 = require("./commands/installClaudeHook");
 const mcpGateway_1 = require("./commands/mcpGateway");
 const installAll_1 = require("./commands/installAll");
+const ciProtect_1 = require("./commands/ciProtect");
 const onboard_1 = require("./commands/onboard");
 const uninstallAll_1 = require("./commands/uninstallAll");
 const verifyRemoved_1 = require("./commands/verifyRemoved");
@@ -178,6 +180,17 @@ function printHelp() {
                 Use --schedule logon to upload inventory/posture at machine login.
     agent-ci    CI/CD gate for agents and tools only. Fails builds on risky MCP,
                 agent instruction, gateway, policy, or secret drift. Not a bot scan.
+    ci-protect  One command for CI jobs that run AI agents (Claude Code, Copilot,
+                MCP tools): enrolls the PIPELINE as an ephemeral fleet endpoint
+                (auto-detected on GitHub Actions / GitLab CI), installs the runtime
+                hook + MCP gateway, and streams every tool call to the fleet
+                console. Auth: FCD_API_KEY secret (org API key).
+    approve     Resolve a taint-guard "approve once" request from YOUR terminal.
+                When the hook holds an agent action (unrequested network/git
+                destination after untrusted web/MCP content), run
+                "fullcourtdefense approve <ID>" to allow that single action, or
+                add --deny. Bare "approve" lists pending requests. Agents are
+                blocked from running this command themselves.
     install-cursor-hook
                 Installs a Cursor hook so EVERY agent action on this machine is
                 checked against your org's Action Policies — in any repo/folder.
@@ -563,6 +576,19 @@ async function main() {
             await (0, credits_1.creditsCommand)(args, config);
             break;
         }
+        case 'approve': {
+            // `approve <id>` / `approve <id> --deny` / bare `approve` lists pending.
+            // parseArgs quirk: `approve --deny <id>` puts the id into flags.deny.
+            const denyValue = flags.deny;
+            const idFromDeny = denyValue && denyValue !== 'true' && denyValue !== 'false' ? denyValue : undefined;
+            const args = {
+                id: positional[0] || idFromDeny,
+                deny: denyValue !== undefined && denyValue !== 'false',
+                json: flags.json === 'true',
+            };
+            await (0, approve_1.approveCommand)(args);
+            break;
+        }
         case 'discover': {
             const args = {
                 type: flags.type,
@@ -585,6 +611,21 @@ async function main() {
             await (0, discover_1.discoverCommand)(args, config);
             break;
         }
+        case 'ci-protect': {
+            const args = {
+                apiKey: flags['api-key'],
+                apiUrl: flags['api-url'],
+                provider: flags.provider,
+                repo: flags.repo,
+                workflow: flags.workflow,
+                runId: flags['run-id'],
+                runUrl: flags['run-url'],
+                hooks: flags.hooks,
+                gateway: flags.gateway,
+            };
+            await (0, ciProtect_1.ciProtectCommand)(args, config);
+            break;
+        }
         case 'agent-ci': {
             const args = {
                 failOn: flags['fail-on'],

package/dist/machineIdentity.js

@@ -131,6 +131,22 @@ function friendlyOs() {
 function getMachineIdentity() {
     if (cached)
         return cached;
+    // Ephemeral fleet override: on CI runners the PIPELINE is the fleet identity,
+    // not the disposable runner hardware. `ci-protect` enrolls the pipeline and
+    // exports these envs (via GITHUB_ENV) so every subsequent hook/gateway
+    // process in the job attributes its events to the pipeline machine record.
+    const ciMachineId = (process.env.FCD_MACHINE_ID || '').trim();
+    if (ciMachineId) {
+        cached = {
+            machineId: ciMachineId.slice(0, 64),
+            user: 'ci',
+            hostname: (process.env.FCD_MACHINE_HOSTNAME || 'ci-pipeline').trim().toLowerCase().slice(0, 160) || 'ci-pipeline',
+            developerName: (process.env.FCD_DEVELOPER_NAME || 'ci@pipeline').trim().toLowerCase().slice(0, 160) || 'ci@pipeline',
+            platform: os.platform(),
+            osFriendly: 'CI runner',
+        };
+        return cached;
+    }
     const user = safe(() => os.userInfo().username) || process.env.USER || process.env.USERNAME || 'unknown-user';
     const hostname = normalizeHostname(safe(() => os.hostname()) || 'unknown-host');
     // Seed the hash with the OS-native id when available; fall back to a stable

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.22.8"
+  "version": "1.24.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.22.8",
+  "version": "1.24.0",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {
@@ -23,6 +23,8 @@
     "test:honeypot": "npm run build && node scripts/test-honeypot.js",
     "test:browser-credentials-rule": "npm run build && node scripts/test-browser-credentials-rule.js",
     "test:taint-ledger": "npm run build && node scripts/test-taint-ledger.js",
+    "test:taint-approvals": "npm run build && node scripts/test-taint-approvals.js",
+    "test:taint-approve-once": "npm run build && node scripts/test-taint-approve-once.js",
     "test:shell-audit": "npm run build && node scripts/test-shell-audit.js",
     "test:audit-restore": "node scripts/test-audit-restore.js",
     "test:shell-guard": "npm run build && node scripts/test-shell-guard.js",