fullcourtdefense-cli 1.26.5 → 1.26.7

package/dist/daemonForensics.d.ts

@@ -73,5 +73,32 @@ export declare function recordUncleanDeathFromWatchdog(isPidAlive: (pid: number)
 export declare function touchDaemonAlive(): void;
 /** Record an intentional shutdown so the next boot knows this was NOT a kill. */
 export declare function recordCleanExit(reason: string): void;
+/**
+ * A pid can lie in two ways: the daemon process exists but its event loop is
+ * WEDGED (never heartbeats, never serves the pipe, never polls the control
+ * plane), or the daemon died long ago and the OS RECYCLED its pid for an
+ * unrelated process. Both look "alive" to a pid check; both mean the machine
+ * has no working control plane. The alive-marker freshness plus a verdict-pipe
+ * probe tells them apart:
+ *
+ *   marker fresh                        → healthy (heartbeats are running)
+ *   marker stale + pipe answers         → healthy (only the marker write fails)
+ *   marker stale + pipe exists, silent  → hung (kernel frees a named pipe when
+ *                                         its owner dies, so a silent endpoint
+ *                                         means a live-but-wedged owner)
+ *   marker stale + no pipe endpoint     → pid recycled (daemon is gone; do NOT
+ *                                         kill the unrelated process)
+ */
+export type DaemonHealthClass = 'dead' | 'healthy' | 'hung' | 'pid_reused' | 'indeterminate';
+/** Marker older than this is stale — 4 missed 5-minute heartbeats. */
+export declare function daemonHungAfterMs(): number;
+export declare function classifyDaemonHealth(input: {
+    pidAlive: boolean;
+    pid: number | undefined;
+    marker: DaemonAliveMarker | undefined;
+    staleAfterMs: number;
+    pipeProbe: 'responsive' | 'unresponsive' | 'no-endpoint' | 'not-probed';
+    nowMs?: number;
+}): DaemonHealthClass;
 /** Stamp the post-mortem as delivered so heartbeats stop re-sending it. */
 export declare function markPostmortemReported(): void;

package/dist/daemonForensics.js

@@ -43,6 +43,8 @@ exports.recordDaemonStart = recordDaemonStart;
 exports.recordUncleanDeathFromWatchdog = recordUncleanDeathFromWatchdog;
 exports.touchDaemonAlive = touchDaemonAlive;
 exports.recordCleanExit = recordCleanExit;
+exports.daemonHungAfterMs = daemonHungAfterMs;
+exports.classifyDaemonHealth = classifyDaemonHealth;
 exports.markPostmortemReported = markPostmortemReported;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -178,6 +180,31 @@ function recordCleanExit(reason) {
     marker.cleanExit = { at: new Date().toISOString(), reason: reason.slice(0, 120) };
     writeJson(aliveMarkerFile(), marker);
 }
+/** Marker older than this is stale — 4 missed 5-minute heartbeats. */
+function daemonHungAfterMs() {
+    const env = Number(process.env.FCD_DAEMON_HUNG_AFTER_MS);
+    return Number.isFinite(env) && env > 0 ? env : 20 * 60_000;
+}
+function classifyDaemonHealth(input) {
+    if (!input.pidAlive || !input.pid)
+        return 'dead';
+    const marker = input.marker;
+    // No marker for this pid (marker deleted, or owned by a different pid):
+    // freshness cannot be judged — stay conservative, never kill on a guess.
+    if (!marker || marker.pid !== input.pid)
+        return 'indeterminate';
+    const last = Date.parse(marker.lastAliveAt || marker.startedAt || '');
+    const age = (input.nowMs ?? Date.now()) - last;
+    if (!Number.isFinite(age) || age <= input.staleAfterMs)
+        return 'healthy';
+    if (input.pipeProbe === 'responsive')
+        return 'healthy';
+    if (input.pipeProbe === 'unresponsive')
+        return 'hung';
+    if (input.pipeProbe === 'no-endpoint')
+        return 'pid_reused';
+    return 'indeterminate';
+}
 /** Stamp the post-mortem as delivered so heartbeats stop re-sending it. */
 function markPostmortemReported() {
     const pm = readPostmortem();

package/dist/distress.d.ts

@@ -54,6 +54,23 @@ export declare const DISTRESS: {
      * next tick — but while it lasted, remote actions were undeliverable.
      */
     readonly POLL_STALLED: "poll_stalled";
+    /**
+     * The watchdog found the daemon process alive but WEDGED — alive-marker
+     * stale past the bound and the verdict pipe silent — and recycled it.
+     */
+    readonly DAEMON_HUNG: "daemon_hung";
+    /**
+     * The daemon exited itself after repeated uncaught exceptions in a short
+     * window (process state suspect); the supervisor restarts it clean.
+     */
+    readonly UNCAUGHT_BURST: "uncaught_burst";
+    /**
+     * The telemetry spool could not be written (disk full, ACL, AV lock) — the
+     * machine is still enforcing, but its decisions are being LOST locally and
+     * will never reach the console. Deserves an admin's attention because a
+     * quiet machine and a machine that cannot record look identical otherwise.
+     */
+    readonly SPOOL_WRITE_FAILED: "spool_write_failed";
     /** Anything nobody predicted — reported via reportUnexpected(). */
     readonly UNEXPECTED: "unexpected_error";
 };

package/dist/distress.js

@@ -99,6 +99,23 @@ exports.DISTRESS = {
      * next tick — but while it lasted, remote actions were undeliverable.
      */
     POLL_STALLED: 'poll_stalled',
+    /**
+     * The watchdog found the daemon process alive but WEDGED — alive-marker
+     * stale past the bound and the verdict pipe silent — and recycled it.
+     */
+    DAEMON_HUNG: 'daemon_hung',
+    /**
+     * The daemon exited itself after repeated uncaught exceptions in a short
+     * window (process state suspect); the supervisor restarts it clean.
+     */
+    UNCAUGHT_BURST: 'uncaught_burst',
+    /**
+     * The telemetry spool could not be written (disk full, ACL, AV lock) — the
+     * machine is still enforcing, but its decisions are being LOST locally and
+     * will never reach the console. Deserves an admin's attention because a
+     * quiet machine and a machine that cannot record look identical otherwise.
+     */
+    SPOOL_WRITE_FAILED: 'spool_write_failed',
     /** Anything nobody predicted — reported via reportUnexpected(). */
     UNEXPECTED: 'unexpected_error',
 };

package/dist/hookIo.js

@@ -135,6 +135,7 @@ function mapHookFlags(flags) {
         shieldKey: flags['shield-key'],
         shadow: flags.shadow,
         enforce: flags.enforce,
+        fcdManaged: flags['fcd-managed'],
         failClosed: flags['fail-closed'],
         localOnly: flags['local-only'],
         timeout: flags.timeout,

package/dist/index.js

@@ -138,6 +138,9 @@ function printHelp() {
     doctor      First step. Checks outbound HTTPS access to FullCourtDefense.
                 --perf measures this machine's real per-event overhead
                 (hook latency, spawn floor, cmd-guard cost, disk footprint).
+                --health prints an mdatp-health-style per-subsystem status
+                table (enrollment, credentials, hooks, updater, tasks).
+                --edr prints the narrowest AV/EDR allowlist guidance for IT.
     login       Enrolls this machine with a fleet enrollment token and saves
                 per-machine Shield credentials to ~/.fullcourtdefense.yml.
     configure   Legacy/manual setup: saves org API key, Organization ID,
@@ -519,6 +522,8 @@ async function main() {
             const args = {
                 apiUrl: flags['api-url'],
                 perf: flags.perf,
+                health: flags.health,
+                edr: flags.edr,
             };
             const { doctorCommand } = await Promise.resolve().then(() => __importStar(require('./commands/doctor')));
             await doctorCommand(args, config);
@@ -761,6 +766,7 @@ async function main() {
                 json: flags.json,
                 noDaemon: flags['no-daemon'],
                 acceptDisclosure: flags['accept-disclosure'],
+                mode: flags.mode,
             };
             const { onboardCommand } = await Promise.resolve().then(() => __importStar(require('./commands/onboard')));
             await onboardCommand(args, config);

package/dist/integrity.js

@@ -105,6 +105,12 @@ function getLocalIntegrityReport(options = {}) {
     }
     else if (cursorHooks.staleEntries > 0)
         reasons.push('cursor_hook_stale_path');
+    // A managed entry mutated to weaken enforcement (hand-added `--shadow true`):
+    // the hook ignores the flag on managed invocations, and the tamper is
+    // reported here so the fleet console sees the edit instead of it being
+    // silently neutralized.
+    if (cursorHooks.existed && (cursorHooks.weakenedEntries || 0) > 0)
+        reasons.push('cursor_hook_changed');
     const claudeHooks = (0, installClaudeHook_1.inspectClaudeManagedHooks)();
     if (!claudeHooks.existed || claudeHooks.managedEntries === 0) {
         if ((0, appDetection_1.isClaudeFamilyAppInstalled)())
@@ -112,6 +118,8 @@ function getLocalIntegrityReport(options = {}) {
     }
     else if (claudeHooks.staleEntries > 0)
         reasons.push('claude_hook_stale_path');
+    if (claudeHooks.existed && (claudeHooks.weakenedEntries || 0) > 0)
+        reasons.push('claude_hook_changed');
     const daemonRunning = isDaemonRunning();
     if (options.requireDaemon && !daemonRunning)
         reasons.push('daemon_not_running');

package/dist/localSafetySnapshot.d.ts

@@ -36,5 +36,14 @@ export declare function hookSnapshotIdentity(): {
     machineName: string;
 };
 export declare function clearLocalSafetySnapshotCache(input: Pick<LocalSafetySnapshotInput, 'apiUrl' | 'shieldId' | 'developerName' | 'machineName'>): void;
+/**
+ * Remove EVERY Local Safety snapshot cache file, regardless of the identity
+ * that keyed it. Used on (re-)enrollment and explicit policy refresh: cache
+ * files are keyed by sha1(apiUrl|shieldId|developer|machine), so after a
+ * shield/identity change a targeted unlink can miss files written under an
+ * old key — leaving a stale (possibly enforcing) snapshot for whichever
+ * surface still resolves that old identity.
+ */
+export declare function clearAllLocalSafetySnapshotCaches(): void;
 export declare function loadLocalSafetySnapshot(input: LocalSafetySnapshotInput): Promise<LocalSafetySnapshot | undefined>;
 export declare function snapshotToScanOptions(snapshot: LocalSafetySnapshot | undefined, extra?: Pick<LocalSafetyScanOptions, 'cwd' | 'inspectScripts'>): LocalSafetyScanOptions;

package/dist/localSafetySnapshot.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hookSnapshotIdentity = hookSnapshotIdentity;
 exports.clearLocalSafetySnapshotCache = clearLocalSafetySnapshotCache;
+exports.clearAllLocalSafetySnapshotCaches = clearAllLocalSafetySnapshotCaches;
 exports.loadLocalSafetySnapshot = loadLocalSafetySnapshot;
 exports.snapshotToScanOptions = snapshotToScanOptions;
 const crypto = __importStar(require("crypto"));
@@ -64,10 +65,40 @@ function readCache(file) {
 function writeCache(file, snapshot) {
     try {
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
+        // Atomic write-temp-rename: hooks read this file on their hot path — a
+        // torn read must never make a policy snapshot unparseable mid-refresh.
+        const tmp = `${file}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
+        fs.renameSync(tmp, file);
     }
     catch { /* best-effort */ }
 }
+/**
+ * Fallback when the derived cache key has no file: the freshest snapshot on
+ * disk under ANY key. Cache keys hash the caller's identity, and that
+ * identity has drifted across surfaces/versions (gateway --developer-name vs
+ * hook username@hostname vs normalized machine identity) — after an upgrade
+ * the old surface's cache would otherwise be invisible and an OFFLINE block
+ * machine would silently downgrade its catalog rules to warn. All snapshot
+ * files in this per-user dir belong to this machine's enrollment (enrollment
+ * clears them all), so the freshest one is always safe to serve.
+ */
+function readFreshestAnyCache() {
+    try {
+        let best;
+        for (const name of fs.readdirSync(CACHE_DIR)) {
+            if (!/^local-safety-[0-9a-f]{40}\.json$/i.test(name))
+                continue;
+            const parsed = readCache(path.join(CACHE_DIR, name));
+            if (parsed && (!best || parsed.loadedAt > best.loadedAt))
+                best = parsed;
+        }
+        return best;
+    }
+    catch {
+        return undefined;
+    }
+}
 function toRuleAction(value) {
     // Explicit 'block' is preserved (not treated as absent): warn-by-default
     // items (e.g. env_workspace) need an org's explicit block override to
@@ -135,9 +166,30 @@ function clearLocalSafetySnapshotCache(input) {
     }
     catch { /* cache may not exist */ }
 }
+/**
+ * Remove EVERY Local Safety snapshot cache file, regardless of the identity
+ * that keyed it. Used on (re-)enrollment and explicit policy refresh: cache
+ * files are keyed by sha1(apiUrl|shieldId|developer|machine), so after a
+ * shield/identity change a targeted unlink can miss files written under an
+ * old key — leaving a stale (possibly enforcing) snapshot for whichever
+ * surface still resolves that old identity.
+ */
+function clearAllLocalSafetySnapshotCaches() {
+    try {
+        for (const name of fs.readdirSync(CACHE_DIR)) {
+            if (/^local-safety-[0-9a-f]{40}\.json$/i.test(name)) {
+                try {
+                    fs.unlinkSync(path.join(CACHE_DIR, name));
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    catch { /* cache dir may not exist */ }
+}
 async function loadLocalSafetySnapshot(input) {
     const file = cachePath(input);
-    const cached = readCache(file);
+    const cached = readCache(file) || readFreshestAnyCache();
     const hashMatches = !input.expectedPolicyHash || cached?.snapshot.policyHash === input.expectedPolicyHash;
     if (cached && hashMatches && Date.now() - cached.loadedAt < CACHE_TTL_MS)
         return cached.snapshot;
@@ -175,6 +227,10 @@ function snapshotToScanOptions(snapshot, extra = {}) {
     return {
         disabledBuiltInItemIds: snapshot?.disabledBuiltInItemIds,
         itemActions: snapshot?.itemActions,
+        // Signals to the guard whether a real snapshot was resolved. Without one,
+        // the guard defaults to warn (never catalog hard-block) for unarmed/offline
+        // machines instead of over-blocking.
+        snapshotPresent: snapshot !== undefined,
         customBlocks: snapshot?.customBlocks,
         trustedScriptPaths: snapshot?.trustedScriptPaths,
         policyHash: snapshot?.policyHash,

package/dist/machineIdentity.js

@@ -40,6 +40,7 @@ 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"));
 /**
  * OS-agnostic stable machine identity.
  *
@@ -100,6 +101,53 @@ function rawStableId() {
     return (safe(() => fs.readFileSync('/etc/machine-id', 'utf8'))
         || safe(() => fs.readFileSync('/var/lib/dbus/machine-id', 'utf8')));
 }
+/**
+ * Where the FALLBACK machine id is persisted when no OS-native stable id is
+ * readable (locked-down registry / missing /etc/machine-id). Two locations:
+ *
+ *  - machine-wide (ProgramData on Windows): shared by EVERY user AND the
+ *    SYSTEM/S4U daemon tasks. Without it, the composite fallback — which
+ *    includes the username — gives the daemon (running as SYSTEM) a DIFFERENT
+ *    machineId than the enrolling user, creating duplicate fleet records with
+ *    split telemetry for the same laptop.
+ *  - per-user (~/.fullcourtdefense): fallback when ProgramData is not
+ *    writable; keeps the id stable across upgrades for that user at least.
+ *
+ * The persisted value is the final HASHED id (never the raw composite).
+ */
+function persistedIdPaths() {
+    const perUser = path.join(os.homedir(), '.fullcourtdefense', 'machine-id');
+    if (os.platform() === 'win32') {
+        const programData = process.env.ProgramData || 'C:\\ProgramData';
+        return { machineWide: path.join(programData, 'FullCourtDefense', 'machine-id'), perUser };
+    }
+    return { perUser };
+}
+function readPersistedFallbackId() {
+    const { machineWide, perUser } = persistedIdPaths();
+    for (const file of [machineWide, perUser]) {
+        if (!file)
+            continue;
+        const value = safe(() => fs.readFileSync(file, 'utf8'));
+        if (value && /^[0-9a-f]{16,64}$/i.test(value))
+            return value.toLowerCase();
+    }
+    return undefined;
+}
+function persistFallbackId(machineId) {
+    const { machineWide, perUser } = persistedIdPaths();
+    for (const file of [machineWide, perUser]) {
+        if (!file)
+            continue;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const tmp = `${file}.tmp-${process.pid}`;
+            fs.writeFileSync(tmp, machineId, 'utf8');
+            fs.renameSync(tmp, file);
+        }
+        catch { /* best-effort — the composite recomputes deterministically for this user */ }
+    }
+}
 function friendlyOs() {
     const platform = os.platform();
     const release = os.release();
@@ -149,10 +197,28 @@ function getMachineIdentity() {
     }
     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);
+    // Seed the hash with the OS-native id when available; otherwise reuse the
+    // persisted fallback id (so every user + the SYSTEM daemon on the same
+    // locked-down machine converge on ONE identity); only then compute the
+    // legacy composite — and persist it so future contexts converge on it.
+    const nativeRaw = rawStableId();
+    let machineId;
+    if (nativeRaw) {
+        machineId = crypto.createHash('sha256').update(nativeRaw).digest('hex').slice(0, 32);
+    }
+    else {
+        const persisted = readPersistedFallbackId();
+        if (persisted) {
+            machineId = persisted;
+        }
+        else {
+            // Composite keeps the pre-existing shape (incl. username) so machines
+            // already enrolled on this path keep their identity across upgrades.
+            const composite = `${hostname}|${user}|${os.platform()}|${os.arch()}`;
+            machineId = crypto.createHash('sha256').update(composite).digest('hex').slice(0, 32);
+            persistFallbackId(machineId);
+        }
+    }
     cached = {
         machineId,
         user,

package/dist/runtimeConfig.d.ts

@@ -90,6 +90,15 @@ export interface FetchBundleInput {
     ttlMs?: number;
     /** Force a network refresh regardless of cache freshness. */
     force?: boolean;
+    /**
+     * Fetch timeout override (ms). Default is the tight hot-path budget
+     * (REFRESH_TIMEOUT_MS = 1.5s) — a hook must never stall a command on a slow
+     * control plane. Diagnostic callers (doctor --health, deep self-test) pass a
+     * generous value instead: a bundle answer at 3s is a healthy backend, not a
+     * "no live bundle" failure. The 2h workday simulation surfaced this — ~1 in
+     * 6 health checkpoints false-alarmed on p95 latency spikes.
+     */
+    timeoutMs?: number;
     /**
      * Hot-path caller (hook / MCP gateway): when the cached mode is monitor or
      * shadow, accept a STALE cache without a synchronous refresh — the resident
@@ -101,6 +110,8 @@ export interface FetchBundleInput {
 }
 export interface EffectiveBundle extends RuntimeBundle {
     source: 'server' | 'cache' | 'default';
+    /** Epoch ms of the last server 200/304 that confirmed this bundle (absent on the 'default' fallback). */
+    serverValidatedAt?: number;
 }
 /**
  * Resolve the effective runtime bundle for a Shield, using the local cache when
@@ -128,6 +139,7 @@ export declare function validateShieldCredentials(input: {
     apiUrl: string;
     shieldId: string;
     shieldKey?: string;
+    timeoutMs?: number;
 }): Promise<CredentialValidationResult>;
 /**
  * Drop every cached runtime bundle at enrollment time.