fullcourtdefense-cli 1.6.14 → 1.7.0

package/dist/commands/flushSpool.d.ts

@@ -0,0 +1,13 @@
+import { BotGuardConfig } from '../config';
+export interface FlushSpoolArgs {
+    apiUrl?: string;
+    shieldId?: string;
+    shieldKey?: string;
+    heartbeat?: string;
+}
+/**
+ * `fullcourtdefense flush-spool` — drain the local telemetry spool to the backend
+ * and send a heartbeat. Normally invoked detached by the hook; can also be run
+ * from cron/launchd/Task Scheduler for steady liveness on idle machines.
+ */
+export declare function flushSpoolCommand(args: FlushSpoolArgs, config: BotGuardConfig): Promise<void>;

package/dist/commands/flushSpool.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushSpoolCommand = flushSpoolCommand;
+const config_1 = require("../config");
+const telemetry_1 = require("../telemetry");
+/**
+ * `fullcourtdefense flush-spool` — drain the local telemetry spool to the backend
+ * and send a heartbeat. Normally invoked detached by the hook; can also be run
+ * from cron/launchd/Task Scheduler for steady liveness on idle machines.
+ */
+async function flushSpoolCommand(args, config) {
+    const creds = (0, config_1.resolveCliCredentials)(config, {
+        shieldId: args.shieldId,
+        shieldKey: args.shieldKey,
+        apiUrl: args.apiUrl,
+    });
+    if (!creds.shieldId)
+        return; // nothing to attribute to
+    const result = await (0, telemetry_1.flushSpool)({
+        apiUrl: creds.apiUrl,
+        shieldId: creds.shieldId,
+        shieldKey: creds.shieldKey,
+        heartbeat: args.heartbeat !== 'false',
+    });
+    if (result) {
+        console.log(`Flushed ${result.accepted} event(s)${result.deduped ? `, ${result.deduped} deduped` : ''}.`);
+    }
+}

package/dist/commands/hook.d.ts

@@ -25,6 +25,7 @@ export interface HookArgs {
     shieldId?: string;
     shieldKey?: string;
     shadow?: string;
+    enforce?: string;
     failClosed?: string;
     timeout?: string;
     approvalMode?: string;

package/dist/commands/hook.js

@@ -38,6 +38,8 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const config_1 = require("../config");
+const runtimeConfig_1 = require("../runtimeConfig");
+const telemetry_1 = require("../telemetry");
 const deterministicGuard_1 = require("./deterministicGuard");
 const taintLedger_1 = require("./taintLedger");
 const DEBUG_LOG = path.join(os.homedir(), '.fullcourtdefense-hook.log');
@@ -323,7 +325,11 @@ function machineMetadata() {
     };
 }
 async function hookCommand(args, config) {
-    const shadow = args.shadow === 'true';
+    // Mode is server-authoritative (pulled from the cached runtime bundle), with
+    // local flags as explicit overrides. Resolved after creds below.
+    let shadow = args.shadow === 'true';
+    const forceMonitor = args.shadow === 'true';
+    const forceEnforce = args.enforce === 'true';
     const failClosed = args.failClosed === 'true';
     const timeoutMs = Number(args.timeout) > 0 ? Number(args.timeout) : 8000;
     const approvalMode = args.approvalMode === 'wait' ? 'wait' : 'block';
@@ -337,6 +343,24 @@ async function hookCommand(args, config) {
     const shieldId = creds.shieldId;
     const shieldKey = creds.shieldKey;
     const apiUrl = creds.apiUrl;
+    // Server-authoritative enforcement mode: the console flips shield.mode and the
+    // machine applies it on the next poll. Cached locally (stale-while-error), so
+    // this is instant when fresh and bounded (~1.5s) only when stale.
+    if (!forceMonitor && !forceEnforce && shieldId) {
+        try {
+            const bundle = await (0, runtimeConfig_1.getRuntimeBundle)({ apiUrl, shieldId, shieldKey });
+            if (bundle.source !== 'default') {
+                shadow = bundle.mode !== 'block'; // 'monitor'/'shadow' => report-only
+                dbg({ phase: 'mode_resolved', mode: bundle.mode, source: bundle.source, shadow });
+            }
+        }
+        catch { /* keep the local default */ }
+    }
+    if (forceEnforce)
+        shadow = false;
+    // Keep device liveness fresh during active use (throttled, detached — never blocks).
+    if (shieldId)
+        (0, telemetry_1.triggerFlush)(false);
     let raw = '';
     let stdinErr = '';
     const isTTY = !!process.stdin.isTTY;
@@ -437,6 +461,8 @@ async function enforceActionPolicy(ctx) {
             respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${localBlock.reason}`);
             return;
         }
+        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: localBlock.reason, ruleId: localBlock.ruleId, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(true);
         respond(true, `Blocked by FullCourtDefense local guard — ${localBlock.reason}`, `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry.`);
         return;
     }
@@ -453,6 +479,8 @@ 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;
     }
@@ -487,6 +515,7 @@ async function enforceActionPolicy(ctx) {
         clearTimeout(timer);
         if (!resp.ok) {
             dbg({ phase: 'policy_http_error', event, status: resp.status });
+            (0, telemetry_1.spoolEvent)({ decision: 'allow', toolName: call.toolName, reason: `degraded: backend HTTP ${resp.status}`, offlineEnforced: true });
             respond(false, undefined, degradedAllowMessage(event, `Backend returned HTTP ${resp.status}.`));
             return;
         }
@@ -500,6 +529,8 @@ async function enforceActionPolicy(ctx) {
     }
     catch (err) {
         dbg({ phase: 'policy_exception', event, error: err instanceof Error ? err.message : String(err) });
+        (0, telemetry_1.spoolEvent)({ decision: 'allow', toolName: call.toolName, reason: `degraded: ${err instanceof Error ? err.message : String(err)}`, offlineEnforced: true });
+        (0, telemetry_1.triggerFlush)(false);
         respond(false, undefined, degradedAllowMessage(event, `Hook error: ${err instanceof Error ? err.message : String(err)}.`));
         return;
     }

package/dist/commands/installAll.js

@@ -33,7 +33,8 @@ async function installAllCommand(args, config) {
             shieldKey: creds.shieldKey,
             apiUrl: creds.apiUrl,
             project: args.cursorProject,
-            events: 'prompt,shell,mcp',
+            // Scope is MCP/tool actions only — prompt text never leaves the machine.
+            events: 'shell,mcp',
             failClosed: 'true',
         };
         try {

package/dist/commands/login.d.ts

@@ -0,0 +1,15 @@
+import { BotGuardConfig } from '../config';
+export interface LoginArgs {
+    /** Reusable, non-expiring fleet enrollment token (or FCD_ENROLL_TOKEN env). */
+    token?: string;
+    apiUrl?: string;
+}
+/**
+ * `fullcourtdefense login` — zero-paste machine enrollment.
+ *
+ * The machine authenticates to the org with a reusable fleet token (distributed
+ * by IT/MDM), self-enrolls under its stable machine id, and receives a dedicated
+ * per-machine Shield (monitor-first). Credentials are written to
+ * ~/.fullcourtdefense.yml so no manual copy/paste of Shield IDs/keys is needed.
+ */
+export declare function loginCommand(args: LoginArgs, config: BotGuardConfig): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loginCommand = loginCommand;
+const config_1 = require("../config");
+const machineIdentity_1 = require("../machineIdentity");
+/**
+ * `fullcourtdefense login` — zero-paste machine enrollment.
+ *
+ * The machine authenticates to the org with a reusable fleet token (distributed
+ * by IT/MDM), self-enrolls under its stable machine id, and receives a dedicated
+ * per-machine Shield (monitor-first). Credentials are written to
+ * ~/.fullcourtdefense.yml so no manual copy/paste of Shield IDs/keys is needed.
+ */
+async function loginCommand(args, config) {
+    const creds = (0, config_1.resolveCliCredentials)(config, { apiUrl: args.apiUrl });
+    const apiUrl = creds.apiUrl;
+    const token = (args.token || process.env.FCD_ENROLL_TOKEN || '').trim();
+    if (!token) {
+        throw new Error('A fleet enrollment token is required. Pass --token <token> or set FCD_ENROLL_TOKEN.\n'
+            + 'An org admin issues one from the AI Fleet console (Settings → Fleet enrollment token).');
+    }
+    const identity = (0, machineIdentity_1.getMachineIdentity)();
+    const shieldName = (0, machineIdentity_1.suggestedShieldName)(identity);
+    console.log('\x1b[1mEnrolling this machine…\x1b[0m');
+    console.log(`  Device:  ${identity.developerName}`);
+    console.log(`  OS:      ${identity.osFriendly}`);
+    console.log(`  Shield:  ${shieldName}`);
+    const resp = await fetch(`${apiUrl}/api/cli/enroll`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-fleet-token': token,
+        },
+        body: JSON.stringify({
+            machineId: identity.machineId,
+            user: identity.user,
+            hostname: identity.hostname,
+            developerName: identity.developerName,
+            osFriendly: identity.osFriendly,
+            platform: identity.platform,
+            shieldName,
+        }),
+    });
+    const data = (await resp.json().catch(() => ({})));
+    if (!resp.ok || data.success === false || !data.data) {
+        throw new Error(data.error || `Enrollment failed (HTTP ${resp.status})`);
+    }
+    const result = data.data;
+    const savedPath = (0, config_1.saveSetupConfig)({
+        organizationId: result.organizationId,
+        shieldId: result.shieldId,
+        shieldKey: result.shieldKey,
+        apiUrl,
+    });
+    console.log('');
+    console.log(`\x1b[32m✓ ${result.reused ? 'Re-enrolled' : 'Enrolled'}\x1b[0m  ${result.shieldName}`);
+    console.log(`  Mode:    ${result.mode} (monitor-first — no blocking until you enable enforcement)`);
+    console.log(`  Config:  ${savedPath}`);
+    console.log('');
+    console.log('Next: \x1b[1mfullcourtdefense install-all\x1b[0m to wrap your MCP clients and Cursor hooks.');
+}

package/dist/index.js

@@ -40,6 +40,8 @@ const credits_1 = require("./commands/credits");
 const init_1 = require("./commands/init");
 const doctor_1 = require("./commands/doctor");
 const configure_1 = require("./commands/configure");
+const login_1 = require("./commands/login");
+const flushSpool_1 = require("./commands/flushSpool");
 const discover_1 = require("./commands/discover");
 const hook_1 = require("./commands/hook");
 const installCursorHook_1 = require("./commands/installCursorHook");
@@ -435,6 +437,24 @@ async function main() {
             await (0, configure_1.configureCommand)(args, config);
             break;
         }
+        case 'login': {
+            const args = {
+                token: flags.token || flags['enroll-token'],
+                apiUrl: flags['api-url'],
+            };
+            await (0, login_1.loginCommand)(args, config);
+            break;
+        }
+        case 'flush-spool': {
+            const args = {
+                apiUrl: flags['api-url'],
+                shieldId: flags['shield-id'],
+                shieldKey: flags['shield-key'],
+                heartbeat: flags.heartbeat,
+            };
+            await (0, flushSpool_1.flushSpoolCommand)(args, config);
+            break;
+        }
         case 'credits': {
             const args = {
                 apiKey: flags['api-key'],
@@ -488,6 +508,7 @@ async function main() {
                 shieldId: flags['shield-id'],
                 shieldKey: flags['shield-key'],
                 shadow: flags.shadow,
+                enforce: flags.enforce,
                 failClosed: flags['fail-closed'],
                 timeout: flags.timeout,
                 approvalMode: flags['approval-mode'],

package/dist/machineIdentity.d.ts

@@ -0,0 +1,23 @@
+export interface MachineIdentity {
+    /** Stable, OS-native hardware/OS id (hashed). Same value across networks + reboots. */
+    machineId: string;
+    /** Raw OS user name. */
+    user: string;
+    /** Normalized hostname (lowercased, `.local`/domain suffix stripped). */
+    hostname: string;
+    /** Human display identity, e.g. `boazl@boaz-pc`. Normalized for dedupe. */
+    developerName: string;
+    /** node platform: win32 | darwin | linux | ... */
+    platform: NodeJS.Platform;
+    /** Friendly OS label, e.g. `Windows 11`, `macOS 14`, `Ubuntu 22.04`. */
+    osFriendly: string;
+}
+/** Normalize a hostname: strip `.local`/domain suffix, lowercase. */
+export declare function normalizeHostname(raw: string): string;
+/**
+ * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
+ */
+export declare function getMachineIdentity(): MachineIdentity;
+/** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
+export declare function suggestedShieldName(identity?: MachineIdentity): string;

package/dist/machineIdentity.js

@@ -0,0 +1,147 @@
+"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.normalizeHostname = normalizeHostname;
+exports.getMachineIdentity = getMachineIdentity;
+exports.suggestedShieldName = suggestedShieldName;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+/**
+ * OS-agnostic stable machine identity.
+ *
+ * The problem this solves: `os.hostname()` is unstable — macOS returns a
+ * transient Bonjour/`.local` name that changes per network, Linux hostnames are
+ * often generic (`localhost`, container ids), and Windows uppercases the name.
+ * Relying on it produces duplicate / drifting fleet entries for the SAME laptop.
+ *
+ * So we key fleet identity on an OS-native STABLE machine id:
+ *   - Windows: MachineGuid (HKLM\SOFTWARE\Microsoft\Cryptography)
+ *   - macOS:   IOPlatformUUID (ioreg)
+ *   - Linux:   /etc/machine-id (fallback /var/lib/dbus/machine-id)
+ *
+ * `username@hostname` is kept only as a human-readable display label.
+ */
+let cached;
+function safe(fn) {
+    try {
+        const value = fn();
+        return value && value.trim() ? value.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Normalize a hostname: strip `.local`/domain suffix, lowercase. */
+function normalizeHostname(raw) {
+    return raw
+        .trim()
+        .replace(/\.local$/i, '')
+        .replace(/\..*$/, '') // drop any remaining domain suffix
+        .toLowerCase() || 'unknown-host';
+}
+/** Raw OS-native stable id (UNHASHED). Internal — prefer `getMachineIdentity().machineId`. */
+function rawStableId() {
+    const platform = os.platform();
+    if (platform === 'win32') {
+        return safe(() => {
+            const out = (0, child_process_1.execFileSync)('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], { encoding: 'utf8', windowsHide: true, timeout: 4000 });
+            const match = out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i);
+            return match ? match[1] : undefined;
+        });
+    }
+    if (platform === 'darwin') {
+        return safe(() => {
+            const out = (0, child_process_1.execFileSync)('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 4000 });
+            const match = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+            return match ? match[1] : undefined;
+        });
+    }
+    // linux + others
+    return (safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
+        || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')));
+}
+function friendlyOs() {
+    const platform = os.platform();
+    const release = os.release();
+    if (platform === 'win32') {
+        // Windows 11 reports 10.0.22000+; 10.0.x below that is Windows 10.
+        const build = parseInt(release.split('.')[2] || '0', 10);
+        return build >= 22000 ? 'Windows 11' : 'Windows 10';
+    }
+    if (platform === 'darwin') {
+        const major = parseInt(release.split('.')[0] || '0', 10);
+        // Darwin kernel major -> macOS major (Darwin 23 => macOS 14, etc.)
+        const macMajor = major >= 20 ? major - 9 : major;
+        return macMajor > 0 ? `macOS ${macMajor}` : 'macOS';
+    }
+    if (platform === 'linux') {
+        const pretty = safe(() => {
+            const osRelease = fs.readFileSync('/etc/os-release', 'utf8');
+            const match = osRelease.match(/^PRETTY_NAME="?([^"\n]+)"?/m);
+            return match ? match[1] : undefined;
+        });
+        return pretty || 'Linux';
+    }
+    return `${platform} ${release}`;
+}
+/**
+ * Compute (and cache) the stable machine identity. The raw OS id is hashed
+ * (SHA-256, 32 hex chars) so we never transmit the raw hardware UUID.
+ */
+function getMachineIdentity() {
+    if (cached)
+        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
+    // composite so we still produce a deterministic id on locked-down machines.
+    const raw = rawStableId() || `${hostname}|${user}|${os.platform()}|${os.arch()}`;
+    const machineId = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
+    cached = {
+        machineId,
+        user,
+        hostname,
+        developerName: `${user.toLowerCase()}@${hostname}`,
+        platform: os.platform(),
+        osFriendly: friendlyOs(),
+    };
+    return cached;
+}
+/** Suggested per-machine Shield name, e.g. `boazl@boaz-pc · Windows 11`. */
+function suggestedShieldName(identity = getMachineIdentity()) {
+    return `${identity.developerName} · ${identity.osFriendly}`;
+}

package/dist/runtimeConfig.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Server-authoritative enforcement mode + policy version, pulled from
+ * GET /api/cli/bundle and cached locally so the hot path (the Cursor hook) never
+ * blocks on the network for the mode decision.
+ *
+ * Behavior:
+ *   - Fresh cache (< TTL): return immediately, no network.
+ *   - Stale cache: try a SHORT-timeout refresh; on success update + return; on
+ *     failure fall back to the last cached value (stale-while-error / fail-static).
+ *   - No cache + network fails: return source 'default' so the caller applies its
+ *     local fallback (the install-time flag).
+ *
+ * A console "Enforce" click flips shield.mode server-side; the machine picks it up
+ * on the next refresh (no push to the machine required).
+ */
+export type ShieldMode = 'block' | 'monitor' | 'shadow';
+export interface RuntimeBundle {
+    mode: ShieldMode;
+    version: string;
+    policyCount?: number;
+    pollIntervalMs?: number;
+}
+export interface FetchBundleInput {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    /** Override cache TTL (ms). */
+    ttlMs?: number;
+    /** Force a network refresh regardless of cache freshness. */
+    force?: boolean;
+}
+export interface EffectiveBundle extends RuntimeBundle {
+    source: 'server' | 'cache' | 'default';
+}
+/**
+ * Resolve the effective runtime bundle for a Shield, using the local cache when
+ * fresh and refreshing (briefly) when stale. Never throws — falls back to cache
+ * or a 'default' marker so the caller can apply its local fallback.
+ */
+export declare function getRuntimeBundle(input: FetchBundleInput): Promise<EffectiveBundle>;

package/dist/runtimeConfig.js

@@ -0,0 +1,109 @@
+"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.getRuntimeBundle = getRuntimeBundle;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const CACHE_PATH = path.join(os.homedir(), '.fullcourtdefense-runtime.json');
+const DEFAULT_TTL_MS = 60_000;
+const REFRESH_TIMEOUT_MS = 1_500; // tight: the hook must stay fast
+function readCacheFile() {
+    try {
+        const raw = fs.readFileSync(CACHE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCacheFile(data) {
+    try {
+        fs.writeFileSync(CACHE_PATH, JSON.stringify(data), { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* cache is best-effort */ }
+}
+function isMode(value) {
+    return value === 'block' || value === 'monitor' || value === 'shadow';
+}
+/**
+ * Resolve the effective runtime bundle for a Shield, using the local cache when
+ * fresh and refreshing (briefly) when stale. Never throws — falls back to cache
+ * or a 'default' marker so the caller can apply its local fallback.
+ */
+async function getRuntimeBundle(input) {
+    const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
+    const cache = readCacheFile();
+    const cached = cache[input.shieldId];
+    const fresh = cached && Date.now() - cached.fetchedAt < ttl;
+    if (cached && fresh && !input.force) {
+        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+    }
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (input.shieldKey)
+            headers['x-shield-key'] = input.shieldKey;
+        if (cached?.version)
+            headers['If-None-Match'] = cached.version;
+        const resp = await fetch(`${input.apiUrl}/api/cli/bundle?shieldId=${encodeURIComponent(input.shieldId)}`, { method: 'GET', headers, signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) });
+        // 304 Not Modified — cache is still valid; refresh its timestamp.
+        if (resp.status === 304 && cached) {
+            cache[input.shieldId] = { ...cached, fetchedAt: Date.now() };
+            writeCacheFile(cache);
+            return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+        }
+        if (resp.ok) {
+            const body = await resp.json().catch(() => ({}));
+            if (body.success && body.data && isMode(body.data.mode)) {
+                const entry = {
+                    mode: body.data.mode,
+                    version: body.data.version,
+                    policyCount: body.data.policyCount,
+                    pollIntervalMs: body.data.pollIntervalMs,
+                    fetchedAt: Date.now(),
+                };
+                cache[input.shieldId] = entry;
+                writeCacheFile(cache);
+                return { ...entry, source: 'server' };
+            }
+        }
+    }
+    catch { /* fall through to cache / default */ }
+    if (cached) {
+        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+    }
+    return { mode: 'block', version: '', source: 'default' };
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,36 @@
+export interface SpoolEvent {
+    eventId: string;
+    type: 'verdict';
+    decision: 'allow' | 'block' | 'approval' | 'mask';
+    toolName?: string;
+    operation?: string;
+    reason?: string;
+    ruleId?: string;
+    /** True when this decision was enforced locally while the backend was unreachable. */
+    offlineEnforced?: boolean;
+    occurredAt: string;
+}
+/** Append one decision to the spool. Never throws (telemetry must not break the hook). */
+export declare function spoolEvent(event: Omit<SpoolEvent, 'eventId' | 'occurredAt' | 'type'> & Partial<Pick<SpoolEvent, 'occurredAt' | 'type'>>): void;
+export interface FlushInput {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    /** Include a heartbeat in this flush (drives device liveness). */
+    heartbeat?: boolean;
+    agentVersion?: string;
+    /** Whether protection points still look intact (tamper signal). */
+    integrityOk?: boolean;
+    timeoutMs?: number;
+}
+/** Drain the spool to the backend in one batch (+ optional heartbeat). Returns accepted count. */
+export declare function flushSpool(input: FlushInput): Promise<{
+    accepted: number;
+    deduped: number;
+} | null>;
+/**
+ * Opportunistically spawn a DETACHED flusher so the hot path (hook) never blocks
+ * on network I/O. Throttled via a marker file. `immediate` bypasses the throttle
+ * (used for critical blocks). The child reads creds from ~/.fullcourtdefense.yml.
+ */
+export declare function triggerFlush(immediate?: boolean): void;

package/dist/telemetry.js

@@ -0,0 +1,170 @@
+"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.spoolEvent = spoolEvent;
+exports.flushSpool = flushSpool;
+exports.triggerFlush = triggerFlush;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const machineIdentity_1 = require("./machineIdentity");
+/**
+ * Local-first telemetry: every enforcement decision is appended to an on-disk
+ * spool (instant, offline-safe) and flushed to the backend in batches. Critical
+ * blocks trigger an immediate (detached) flush; everything else drains on the
+ * next opportunistic/heartbeat flush. Decisions enforced while the backend was
+ * unreachable are tagged `offlineEnforced` and replayed (idempotent on eventId)
+ * when connectivity returns.
+ */
+const SPOOL_PATH = path.join(os.homedir(), '.fullcourtdefense-spool.jsonl');
+const FLUSH_MARKER = path.join(os.homedir(), '.fullcourtdefense-flush.ts');
+const FLUSH_THROTTLE_MS = 30_000; // don't spawn a flusher more than this often
+const MAX_BATCH = 200;
+/** Append one decision to the spool. Never throws (telemetry must not break the hook). */
+function spoolEvent(event) {
+    try {
+        const full = {
+            eventId: crypto.randomUUID(),
+            occurredAt: event.occurredAt || new Date().toISOString(),
+            type: 'verdict',
+            decision: event.decision,
+            toolName: event.toolName,
+            operation: event.operation,
+            reason: event.reason,
+            ruleId: event.ruleId,
+            offlineEnforced: event.offlineEnforced,
+        };
+        fs.appendFileSync(SPOOL_PATH, JSON.stringify(full) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+function readSpool() {
+    try {
+        const raw = fs.readFileSync(SPOOL_PATH, 'utf-8');
+        return raw.split('\n').map(l => l.trim()).filter(Boolean).map(l => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        }).filter((e) => !!e && !!e.eventId);
+    }
+    catch {
+        return [];
+    }
+}
+function rewriteSpool(remaining) {
+    try {
+        if (remaining.length === 0) {
+            if (fs.existsSync(SPOOL_PATH))
+                fs.unlinkSync(SPOOL_PATH);
+            return;
+        }
+        fs.writeFileSync(SPOOL_PATH, remaining.map(e => JSON.stringify(e)).join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+/** Drain the spool to the backend in one batch (+ optional heartbeat). Returns accepted count. */
+async function flushSpool(input) {
+    const all = readSpool();
+    const batch = all.slice(0, MAX_BATCH);
+    const overflow = all.slice(MAX_BATCH);
+    if (batch.length === 0 && !input.heartbeat)
+        return null;
+    const identity = (0, machineIdentity_1.getMachineIdentity)();
+    const headers = { 'Content-Type': 'application/json' };
+    if (input.shieldKey)
+        headers['x-shield-key'] = input.shieldKey;
+    try {
+        const resp = await fetch(`${input.apiUrl}/api/cli/events:batch`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                shieldId: input.shieldId,
+                machineId: identity.machineId,
+                heartbeat: input.heartbeat
+                    ? { agentVersion: input.agentVersion, integrityOk: input.integrityOk, coverage: 'hooks' }
+                    : undefined,
+                events: batch,
+            }),
+            signal: AbortSignal.timeout(input.timeoutMs ?? 8000),
+        });
+        if (!resp.ok)
+            return null;
+        const body = await resp.json().catch(() => ({}));
+        if (!body.success)
+            return null;
+        // Successfully delivered → drop the flushed events, keep any overflow.
+        rewriteSpool(overflow);
+        return body.data || { accepted: batch.length, deduped: 0 };
+    }
+    catch {
+        return null; // keep the spool intact for the next attempt (offline-safe)
+    }
+}
+/**
+ * Opportunistically spawn a DETACHED flusher so the hot path (hook) never blocks
+ * on network I/O. Throttled via a marker file. `immediate` bypasses the throttle
+ * (used for critical blocks). The child reads creds from ~/.fullcourtdefense.yml.
+ */
+function triggerFlush(immediate = false) {
+    try {
+        if (!immediate) {
+            try {
+                const last = Number(fs.readFileSync(FLUSH_MARKER, 'utf-8'));
+                if (Number.isFinite(last) && Date.now() - last < FLUSH_THROTTLE_MS)
+                    return;
+            }
+            catch { /* no marker yet */ }
+        }
+        try {
+            fs.writeFileSync(FLUSH_MARKER, String(Date.now()), 'utf-8');
+        }
+        catch { /* ignore */ }
+        const entry = process.argv[1];
+        if (!entry)
+            return;
+        const child = (0, child_process_1.spawn)(process.execPath, [entry, 'flush-spool', '--heartbeat', 'true'], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.unref();
+    }
+    catch { /* best-effort */ }
+}

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.6.14"
+  "version": "1.7.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.6.14",
+  "version": "1.7.0",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {