@consiliency/agent-board-cli 1.27.1 → 1.28.0

package/dist/assets.json

@@ -2,5 +2,5 @@
   "mcpVersion": "1.32.0",
   "piVersion": "0.4.2",
   "opencodeVersion": "0.2.2",
-  "releaseTag": "v1.56.0"
+  "releaseTag": "v1.57.0"
 }

package/dist/cli.js

@@ -3189,6 +3189,7 @@ function addDoctorCommand(program, io, doctor) {
         // Not `requiredOption`: commander's own usage exit would bypass the JSON envelope (#402).
         .option("--harness <harness>", "the harness to check (agy, claude, codex, grok, opencode, pi)")
         .option("--json", "print the report as JSON")
+        .option("--rescan", "scan for plaintext copies of a keyslot key now, instead of reusing a scan from the last 24 hours")
         .action(async (options) => {
         const harness = String(options.harness ?? "");
         let report;
@@ -3201,7 +3202,7 @@ function addDoctorCommand(program, io, doctor) {
             return;
         }
         try {
-            report = await doctor({ harness });
+            report = await doctor({ harness, ...(options.rescan === true ? { rescan: true } : {}) });
         }
         catch (error) {
             writeFailureEnvelope(io, toOperationFailure("agent_board.doctor", error));

package/dist/doctor.d.ts

@@ -1,5 +1,6 @@
 import { type IdentityHarness, type OperationSuccess, type OsKeychainBackendOptions, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
 import { type ClaudePluginSummary, type RegistrationFs, type RegQuery, type RegistrationVerdict, type ScopeContext } from "./doctor_scopes.js";
+import { type ScanBudgets, type StorageRunner } from "./keyslot_status.js";
 export type DoctorStatus = "pass" | "fail" | "undetermined";
 export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime"];
 export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number];
@@ -25,10 +26,31 @@ export interface PluginReport {
     version_from: "source" | "cache" | null;
     auto_update: ClaudePluginSummary["autoUpdate"];
 }
+/**
+ * #552 IF-552-3 — when the plaintext-key scan behind `key_storage` ran, and from where. A report,
+ * never a check: it does not change the exit. Present only once status.sh's measurement fields
+ * matched doctor's own (a report about another host, user or slot does not say when OUR scan ran).
+ * `source`: `fresh` (this doctor scanned), `cached` (a valid scan cache), `setup_run` (setup's
+ * in-process result, carried only where the cache could not store it), or `none` with `gave_up`
+ * when the scan hit its 30-minute bound.
+ */
+export interface KeyStorageScanReport {
+    source: "fresh" | "cached" | "setup_run" | "none";
+    scanned_at: string | null;
+    age_s: number | null;
+    duration_s: number | null;
+    cache_state: string | null;
+    gave_up?: {
+        after_s: number;
+        folders: number | null;
+    };
+}
 export interface DoctorReport {
     harness: IdentityHarness;
     exit: 0 | 1 | 2;
     checks: Record<DoctorCheckName, DoctorCheck>;
+    /** keyslot identities only (IF-552-3). */
+    key_storage_scan?: KeyStorageScanReport;
     /** claude only. */
     plugin?: PluginReport;
     /** claude only: wake hooks per required event in doctor's cwd, across settings and plugins. */
@@ -113,7 +135,44 @@ export interface DoctorOptions {
     machineIdFile?: string;
     /** key_storage: doctor's own uid. Default `process.getuid()`. */
     uid?: number;
+    /** `--rescan`: phase 2 always runs, as `--scan-cache fresh` (IF-552-3). */
+    rescan?: boolean;
+    /**
+     * SETUP ONLY, never a CLI flag: the key step's FRESH, validated clean scan, carried in-process so
+     * setup scans once where the cache could not store it. Used only under IF-552-3's three conditions.
+     */
+    setupScan?: SetupScan;
+    /** key_storage: where the scan notices go. Default `process.stderr`. */
+    writeStderr?: (line: string) => void;
+    /** key_storage: the status.sh runner and budgets (tests). */
+    statusRunner?: StorageRunner;
+    statusBudgets?: Partial<ScanBudgets>;
+    /** key_storage: the clock the carry's validity window reads, epoch seconds. Default now. */
+    nowSeconds?: () => number;
+}
+/** The key step's clean fresh scan, as setup carries it to its own doctor (IF-552-3). */
+export interface SetupScan {
+    /** `scan.inputs` of the key step's report: every field must deep-equal phase 1's. */
+    inputs: Record<string, unknown>;
+    /** The scan object itself (clean: `plaintext_matches` empty). */
+    scan: Record<string, unknown>;
+    /** The scan's start, epoch seconds. */
+    scannedAt: number;
+    /** The key step's own cache write, `<state>:<reason>` (e.g. `not_written:write_failed`). */
+    cacheWrite: string;
 }
+/** The IF-552-2 validity window, the same for the carry: `scannedAt ≤ now + 300` and `now − scannedAt < 86400`. */
+export declare const SCAN_CACHE_TTL_S = 86400;
+export declare const SCAN_CACHE_FUTURE_S = 300;
+/**
+ * IF-552-3's carry: setup's result serves instead of phase 2 only when (1) phase 1's `scan.inputs`
+ * deep-equals the carried inputs, (2) the cache could not serve STRUCTURALLY (phase 1 `unusable`
+ * with a structural reason, or `miss:absent` beside a key-step write of `not_written:untrusted_dir`
+ * or `write_failed`; `lock_busy` never qualifies: a held lock may be a tombstone being written), and
+ * (3) the carried scan is inside the validity window. Reads phase 1's `scan.cache`, never only
+ * `exit2_reasons`.
+ */
+export declare function carryQualifies(phase1: Record<string, unknown>, carried: SetupScan, now: number): boolean;
 /**
  * An error's `code`, only when this repository wrote it: a member of the derived
  * AUTHORED_CAUSE_CODES that this instance carries under the authored provenance brand — the
@@ -151,6 +210,8 @@ export declare function osKeychainProbe(spawn?: OsKeychainExec, where?: Pick<OsK
 /** The default agent_socket probe: the loaded key's fingerprint, derived from the agent's identity list. */
 export declare const agentSocketProbe: KeystoreProbe;
 export declare const OS_KEYCHAIN_PRESENT = "present; key_id proven server-side by whoami; file fingerprint unverified for os_keychain";
+/** Every exit-2 cause status.sh can emit (KSC-8 derives the list from status.sh and probe.sh). */
+export declare const STATUS_EXIT2_REASON: RegExp;
 interface FileIdentity {
     handle: string;
     fingerprint: string;

package/dist/doctor.js

@@ -9,14 +9,14 @@
 // only with a live `wake_producer` at its expected tier, so 0 is never returned without runtime
 // evidence. Output is names and codes only: no identity value, key or path content is printed,
 // and an error's `code` is printed only when this repository authored it (`authoredCode`).
-import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, readdirSync } from "node:fs";
+import { readdirSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join, resolve } from "node:path";
 import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, normalizeKeyReference, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
 import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
 import { resolveKeyslotDir } from "./assets.js";
+import { cacheStateOf, measureKeyslot, progressText, scanOf, scanSourceOf, STATUS_SCAN_TIMEOUT_MS, } from "./keyslot_status.js";
 import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
 export const DOCTOR_CHECKS = Object.freeze([
     "identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime",
@@ -63,6 +63,42 @@ function pinCheck(verdict, entries, cwd, fs) {
         return { ...verdict, status: "fail", reason: [...earlier, "plugin_pin_mismatch"].join(",") };
     return { ...verdict, status: verdict.status === "fail" ? "fail" : "undetermined", reason: [...earlier, "plugin_pin_ambiguous"].join(",") };
 }
+/** The IF-552-2 validity window, the same for the carry: `scannedAt ≤ now + 300` and `now − scannedAt < 86400`. */
+export const SCAN_CACHE_TTL_S = 86_400;
+export const SCAN_CACHE_FUTURE_S = 300;
+/** Cache states that are STRUCTURAL: the cache cannot serve here at all. `lock_busy` never is. */
+const STRUCTURAL_UNUSABLE = /^(untrusted:.+|state_root_relative|machine_id_unreadable)$/;
+const UNWRITABLE_WRITE = new Set(["not_written:untrusted_dir", "not_written:write_failed"]);
+const sameJson = (a, b) => {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => sameJson(a[k], b[k]));
+};
+/**
+ * IF-552-3's carry: setup's result serves instead of phase 2 only when (1) phase 1's `scan.inputs`
+ * deep-equals the carried inputs, (2) the cache could not serve STRUCTURALLY (phase 1 `unusable`
+ * with a structural reason, or `miss:absent` beside a key-step write of `not_written:untrusted_dir`
+ * or `write_failed`; `lock_busy` never qualifies: a held lock may be a tombstone being written), and
+ * (3) the carried scan is inside the validity window. Reads phase 1's `scan.cache`, never only
+ * `exit2_reasons`.
+ */
+export function carryQualifies(phase1, carried, now) {
+    const inputs = scanOf(phase1).inputs;
+    if (!inputs || typeof inputs !== "object" || !sameJson(inputs, carried.inputs))
+        return false;
+    const { state, reason } = cacheStateOf(phase1);
+    const structural = (state === "unusable" && STRUCTURAL_UNUSABLE.test(reason))
+        || (state === "miss" && reason === "absent" && UNWRITABLE_WRITE.has(carried.cacheWrite));
+    if (!structural)
+        return false;
+    return carried.scannedAt <= now + SCAN_CACHE_FUTURE_S && now - carried.scannedAt < SCAN_CACHE_TTL_S;
+}
 /** The binary's managed-settings directory per platform (`Zh()`, 2.1.283). */
 function defaultClaudeManagedDir(platform) {
     if (platform === "darwin")
@@ -273,17 +309,8 @@ async function keystoreCheck(values, env, probe) {
  *  - status.sh absent, unrunnable, timed out or unparseable → 2.
  */
 const STATUS_MODES = new Set(["sealed", "unsealed", "contradiction", "undetermined"]);
-const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|capability_(error|incapable|incapable-for-keyslot))$/;
-const STATUS_TIMEOUT_MS = 180_000;
-function runStatus(file, args, env) {
-    return new Promise((done) => {
-        execFile(file, args, { env, timeout: STATUS_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout) => {
-            const failure = error;
-            const code = !failure ? 0 : typeof failure.code === "number" && !failure.killed ? failure.code : null;
-            done({ code, stdout: String(stdout ?? "") });
-        });
-    });
-}
+/** Every exit-2 cause status.sh can emit (KSC-8 derives the list from status.sh and probe.sh). */
+export const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|scan_not_cached|scan_timed_out|capability_(error|incapable|incapable-for-keyslot))$/;
 /** The keyslot whose socket is the same file as `socket`, or null. */
 function matchKeyslot(socket, env) {
     const dir = keyslotSocketDir(env);
@@ -309,7 +336,18 @@ function matchKeyslot(socket, env) {
     }
     return null;
 }
+/** A keyslot socket's shape: `<dir>/agent-board/<slot>.sock`, the slot a name the keyslot scripts accept. */
+function keyslotShaped(socket) {
+    const match = /\/agent-board\/([^/]+)\.sock$/.exec(socket);
+    return match !== null && SLOT_RE.test(match[1]);
+}
+const isoOf = (value) => (typeof value === "string" ? value : null);
+const numOf = (value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
 async function keyStorageCheck(harness, values, fileEnv, env, options) {
+    const judged = await keyStorageJudge(harness, values, fileEnv, env, options);
+    return "check" in judged ? judged : { check: judged };
+}
+async function keyStorageJudge(harness, values, fileEnv, env, options) {
     let reference;
     try {
         reference = normalizeKeyReference(values[KEY_REFERENCE_KEY]);
@@ -333,6 +371,10 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
         const problems = externalDeclarationProblems(env, socket, uid, machineId);
         if (problems.length === 0)
             return check("pass", "external");
+        // #552: with no runtime dir the keyslot cannot be located at all. Only a socket of the keyslot's
+        // own shape says so; any other undeclared socket stays external_undeclared.
+        if (keyslotSocketDir(env) === null && keyslotShaped(socket))
+            return check("undetermined", "runtime_dir_unset");
         return check("undetermined", problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch");
     }
     let dir;
@@ -342,21 +384,54 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
     catch {
         return check("undetermined", "status_absent");
     }
-    if (!existsSync(join(dir, "status.sh")))
+    const writeStderr = options.writeStderr ?? ((line) => { process.stderr.write(`${line}\n`); });
+    const now = options.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+    let carried = false;
+    const measured = await measureKeyslot({
+        dir, harness, slot, env, scan: options.rescan ? "fresh" : "use", onFailure: "stop", run: options.statusRunner, budgets: options.statusBudgets,
+        skipScan: (phase1) => {
+            carried = options.setupScan !== undefined && carryQualifies(phase1, options.setupScan, now());
+            return carried;
+        },
+        notify: (event) => {
+            if (event.kind === "before") {
+                const { state, reason } = cacheStateOf(event.phase1);
+                const why = options.rescan ? "rescan requested" : `${state}${reason ? `:${reason}` : ""}` || "no cache";
+                writeStderr(`doctor: key_storage: scanning for plaintext copies of the key (${why}); this can take several minutes on a large home`);
+            }
+            else if (event.kind === "progress") {
+                writeStderr(`doctor: key_storage: ${progressText(event.folders)}`);
+            }
+        },
+    });
+    if (measured.absent)
         return check("undetermined", "status_absent");
-    const run = await runStatus(join(dir, "status.sh"), ["--harness", harness, "--slot", slot, "--json"], env);
-    if (run.code === null)
+    const scanPhase = measured.phases.find((phase) => phase.mode !== "only");
+    const phase1 = measured.phases.find((phase) => phase.mode === "only");
+    // A phase 1 that did not finish is status_did_not_complete; a SCAN that did not is scan_timed_out.
+    if (phase1 && phase1.code === null)
         return check("undetermined", "status_did_not_complete");
-    let report;
-    try {
-        const parsed = JSON.parse(run.stdout);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            throw new Error("not an object");
-        report = parsed;
+    // Only the helper's own budget is a timeout. Any other end of the scan without a report (SIGKILL:
+    // code null; TERM/INT, which status.sh traps: 143/130 with no JSON) is undetermined
+    // status_unreadable, the same for every signal: doctor could not finish checking, and AC-7 keeps
+    // doctor's key_storage reasons (#552 review r2). Setup, which must not enroll, refuses instead.
+    const budgetS = Math.round((options.statusBudgets?.scanMs ?? STATUS_SCAN_TIMEOUT_MS) / 1000);
+    // The helper's own scan budget ran out: scan_timed_out at once. Phase 1's report is never judged in
+    // its place (#552 review r2, gemini): it answers a different question (the cache), and judging it
+    // turned a timeout into whatever phase 1 said.
+    if (scanPhase !== undefined && scanPhase.timedOut) {
+        return {
+            check: check("undetermined", "scan_timed_out"),
+            scan: { source: "none", scanned_at: null, age_s: null, duration_s: null, cache_state: null, gave_up: { after_s: budgetS, folders: measured.folders } },
+        };
     }
-    catch {
+    if (scanPhase !== undefined && scanPhase.code === null)
+        return check("undetermined", "status_unreadable");
+    if (scanPhase === undefined && measured.code === null)
+        return check("undetermined", "status_did_not_complete");
+    const report = measured.report;
+    if (report === null)
         return check("undetermined", "status_unreadable");
-    }
     const seam = typeof env.KEYSEAL_TEST_ROOT === "string" && env.KEYSEAL_TEST_ROOT !== "";
     const own = {
         machine_id: (value) => machineId !== null && value === machineId,
@@ -371,24 +446,58 @@ async function keyStorageCheck(harness, values, fileEnv, env, options) {
         if (!matches(report[field]))
             return check("undetermined", `status_field_mismatch:${field}`);
     }
-    if (run.code === 1)
-        return check("fail", "keyslot_status_failed");
-    if (run.code === 2) {
-        const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+    // The report is about this host, user and slot: now it may say when OUR scan ran.
+    const scanReport = (source, of) => {
+        const scan = scanOf(of);
+        const { state, reason } = cacheStateOf(of);
+        return {
+            source, scanned_at: isoOf(scan.scanned_at), age_s: numOf(scan.age_s), duration_s: numOf(scan.duration_s),
+            cache_state: state === "" ? null : `${state}${reason ? `:${reason}` : ""}`,
+        };
+    };
+    const gaveUp = () => ({
+        check: check("undetermined", "scan_timed_out"),
+        scan: { ...scanReport("none", report), gave_up: { after_s: budgetS, folders: measured.folders } },
+    });
+    const code = measured.code;
+    const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+    let scan;
+    let effectiveCode = code;
+    if (carried && options.setupScan) {
+        // Setup's result stands in for phase 2: scan_not_cached is satisfied by it.
+        scan = {
+            source: "setup_run", scanned_at: new Date(options.setupScan.scannedAt * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"),
+            age_s: now() - options.setupScan.scannedAt, duration_s: numOf(options.setupScan.scan.duration_s), cache_state: scanReport("none", report).cache_state,
+        };
+        if (code === 2 && reasons.length === 1 && reasons[0] === "scan_not_cached")
+            effectiveCode = 0;
+    }
+    else {
+        const source = scanSourceOf(report);
+        if (source !== "none")
+            scan = scanReport(source, report);
+    }
+    const withScan = (result) => (scan ? { check: result, scan } : { check: result });
+    if (effectiveCode === 1)
+        return withScan(check("fail", "keyslot_status_failed"));
+    if (effectiveCode === 2) {
+        // status.sh's own self-bound: the scan gave up, and nothing else is undetermined.
+        if (scanPhase !== undefined && reasons.length === 1 && reasons[0] === "scan_timed_out")
+            return gaveUp();
         const named = reasons.length > 0 && reasons.every((reason) => typeof reason === "string" && STATUS_EXIT2_REASON.test(reason));
-        return check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined");
+        return withScan(check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined"));
     }
-    if (run.code !== 0)
-        return check("undetermined", "status_unexpected_exit");
+    if (effectiveCode !== 0)
+        return withScan(check("undetermined", "status_unexpected_exit"));
     if (report.mode === "sealed")
-        return check("pass", "sealed");
+        return withScan(check("pass", "sealed"));
     if (report.mode === "unsealed") {
         const optin = report.optin;
         if (optin?.ok !== true)
-            return check("fail", "unsealed_optin_invalid");
-        return unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid");
+            return withScan(check("fail", "unsealed_optin_invalid"));
+        return withScan(unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid"));
     }
-    return check("undetermined", "status_mode_unexpected");
+    return withScan(check("undetermined", "status_mode_unexpected"));
 }
 async function whoamiCheck(client, expectedHandle) {
     let rows;
@@ -494,6 +603,7 @@ export async function runDoctor(options) {
     const cwd = options.cwd ?? process.cwd();
     const trust = options.trust ?? {};
     const checks = {};
+    let keyStorageScan;
     let values = null;
     try {
         values = (await readIdentityFile({ ...trust, harness, env })).values;
@@ -511,7 +621,9 @@ export async function runDoctor(options) {
     else {
         const fileEnv = fileIdentityEnv(env, values);
         checks.keystore_key = await keystoreCheck(values, fileEnv, options.probeKeystore ?? defaultKeystoreProbe);
-        checks.key_storage = await keyStorageCheck(harness, values, fileEnv, env, options);
+        const storage = await keyStorageCheck(harness, values, fileEnv, env, options);
+        checks.key_storage = storage.check;
+        keyStorageScan = storage.scan;
         let client = null;
         try {
             client = (options.createClient ?? defaultClient)(fileEnv);
@@ -570,6 +682,8 @@ export async function runDoctor(options) {
     const statuses = Object.values(ordered).map((item) => item.status);
     const exit = statuses.every((status) => status === "pass") ? 0 : statuses.includes("fail") ? 1 : 2;
     const report = { harness, exit, checks: ordered };
+    if (keyStorageScan)
+        report.key_storage_scan = keyStorageScan;
     const here = verdicts[0];
     if (harness === "claude") {
         const plugin = here.plugin;
@@ -594,6 +708,16 @@ export async function runDoctor(options) {
     }
     return report;
 }
+/** An age in seconds, as a short human span. */
+function ago(seconds) {
+    if (seconds === null)
+        return "?";
+    if (seconds < 120)
+        return `${seconds} s`;
+    if (seconds < 7200)
+        return `${Math.floor(seconds / 60)} min`;
+    return `${Math.floor(seconds / 3600)} h`;
+}
 /** Human-readable form; `--json` prints the report object itself. */
 export function formatDoctorReport(report) {
     const lines = DOCTOR_CHECKS.map((name) => `${report.checks[name].status.padEnd(12)} ${name}: ${report.checks[name].reason}`);
@@ -610,6 +734,23 @@ export function formatDoctorReport(report) {
             counts ? `hooks SessionStart=${counts.SessionStart} FileChanged=${counts.FileChanged}` : "hooks undetermined",
         ].join(" "));
     }
+    const scan = report.key_storage_scan;
+    if (scan) {
+        const rescan = `\`agent-board doctor --harness ${report.harness} --rescan\``;
+        if (scan.gave_up) {
+            const after = scan.gave_up.after_s > 0 && scan.gave_up.after_s % 60 === 0 ? `${scan.gave_up.after_s / 60} min` : `${scan.gave_up.after_s} s`;
+            lines.push(`${"scan".padEnd(12)} gave up after ${after} (${scan.gave_up.folders ?? "?"} folders so far); ${rescan} retries`);
+        }
+        else if (scan.source === "fresh") {
+            lines.push(`${"scan".padEnd(12)} fresh (${scan.duration_s ?? "?"} s)${report.checks.key_storage.status === "pass" ? ", no plaintext copy found" : ""}`);
+        }
+        else if (scan.source === "setup_run") {
+            lines.push(`${"scan".padEnd(12)} setup's scan at ${scan.scanned_at ?? "?"} (${ago(scan.age_s)} ago), no plaintext copy found`);
+        }
+        else if (scan.source === "cached") {
+            lines.push(`${"scan".padEnd(12)} cached at ${scan.scanned_at ?? "?"} (${ago(scan.age_s)} ago); ${rescan} scans again`);
+        }
+    }
     if (report.managed_policy) {
         const policy = report.managed_policy;
         lines.push([

package/dist/keyslot_status.d.ts

@@ -0,0 +1,117 @@
+/** The status budget: phase 1 (`--scan-cache only`) and every call that never scans. */
+export declare const STATUS_TIMEOUT_MS = 180000;
+/** The scan budget (owner answer 2): phase 2, and `status.sh --scan-timeout` in seconds. */
+export declare const STATUS_SCAN_TIMEOUT_MS = 1800000;
+/**
+ * The helper's own kill fires this long after the scan budget: a backstop, never the bound. It must
+ * outlast everything `status.sh` legitimately does AFTER its stage's deadline: the stage's
+ * `--kill-after` grace, and a found copy's tombstone waiting out a held cache lock (#552 review r1: a
+ * shorter backstop turned a found copy into `scan_timed_out` with no tombstone). KSC-13 derives the
+ * floor from lib.sh.
+ */
+export declare const SCAN_TOMBSTONE_WAIT_MS = 300000;
+export declare const SCAN_KILL_AFTER_MS = 10000;
+export declare const SCAN_LOCK_WAIT_MS = 10000;
+/**
+ * The waits status.sh may spend outside its stage's deadline that lib.sh bounds: the start read's
+ * lock wait, the stage's `--kill-after` grace and status.sh's own group reap (each up to
+ * kill-after), then the longest commit (a tombstone's lock wait) (#552 review r1b: the budget must
+ * never cut a found copy's tombstone wait short). The checks status.sh runs BEFORE the scan (probe,
+ * units, chain, agent, the blob's decrypt) have no bound of their own here: only `marginMs` covers
+ * them (#552 review r2). KSC-13 derives the waits from lib.sh; SC-20 runs the formula scaled.
+ */
+export declare function scanBackstopMs(waits: {
+    lockWaitMs: number;
+    killAfterMs: number;
+    tombstoneWaitMs: number;
+    marginMs: number;
+}): number;
+export declare const SCAN_BACKSTOP_MS: number;
+export interface RunOutcome {
+    /** null when the child did not exit on its own (killed, timed out, not spawned). */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** The runner's own timeout fired. */
+    timedOut?: boolean;
+}
+export interface RunOptions {
+    env: NodeJS.ProcessEnv;
+    /** Default `STATUS_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Each complete stderr line, as it arrives (progress relay). */
+    onStderrLine?: (line: string) => void;
+}
+export type StorageRunner = (file: string, args: readonly string[], options: RunOptions) => Promise<RunOutcome>;
+/**
+ * The default runner: detached (its own process group), stdout collected, stderr relayed line by line
+ * AS IT ARRIVES, and the whole group killed on the timeout or when this process exits or is
+ * interrupted. A signal handler removes itself and re-raises, so the process still dies by it.
+ */
+export declare const defaultStorageRunner: StorageRunner;
+export type ScanMode = "use" | "only" | "fresh";
+export interface ScanBudgets {
+    statusMs: number;
+    scanMs: number;
+    backstopMs: number;
+}
+export declare const DEFAULT_BUDGETS: ScanBudgets;
+export interface KeyslotPhase {
+    mode: ScanMode;
+    code: number | null;
+    timedOut: boolean;
+    /** The parsed JSON object, or null when stdout was not one. */
+    report: Record<string, unknown> | null;
+}
+/** What a caller is told while a scan runs. The caller words it (setup: `key: `, doctor: `doctor: key_storage: `). */
+export type ScanEvent = {
+    kind: "before";
+    phase1: Record<string, unknown> | null;
+} | {
+    kind: "progress";
+    folders: number;
+} | {
+    kind: "result";
+    phase: KeyslotPhase;
+};
+export interface KeyslotMeasurement {
+    /** `status.sh` is not in the packaged directory (doctor: `status_absent`). */
+    absent: boolean;
+    /** The last phase's exit code (null: it did not exit on its own). */
+    code: number | null;
+    /** The last phase's report (phase 2's when it ran, else phase 1's). */
+    report: Record<string, unknown> | null;
+    phases: KeyslotPhase[];
+    /** The SCAN phase (phase 2, or a `fresh` call) hit the helper's backstop. */
+    timedOut: boolean;
+    /** The last `still scanning` count relayed, if any. */
+    folders: number | null;
+}
+export interface MeasureOptions {
+    dir: string;
+    harness: string;
+    slot: string;
+    env: NodeJS.ProcessEnv;
+    scan: ScanMode;
+    /** `stop` (doctor): a phase-1 exit 1 returns without phase 2. `scan` (setup): phase 2 still runs. Default `stop`. */
+    onFailure?: "stop" | "scan";
+    notify?: (event: ScanEvent) => void;
+    budgets?: Partial<ScanBudgets>;
+    run?: StorageRunner;
+    /** Doctor's carry: return true to skip phase 2 on this phase-1 report (setup's in-process result serves). */
+    skipScan?: (phase1: Record<string, unknown>) => boolean;
+}
+export declare const PROGRESS_LINE: RegExp;
+/** The relayed progress text, before the caller's prefix. */
+export declare const progressText: (folders: number) => string;
+/** `scan` of a status report, or an empty object. */
+export declare function scanOf(report: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/** `scan.source`: `fresh`, `cached` or `none`; anything else (an older status.sh, no scan at all) reads `none`. */
+export declare function scanSourceOf(report: Record<string, unknown> | null | undefined): "fresh" | "cached" | "none";
+/** `scan.cache` as `{state, reason}` strings (reason "" when null). */
+export declare function cacheStateOf(report: Record<string, unknown> | null | undefined): {
+    state: string;
+    reason: string;
+};
+/** IF-552-3: measure a keyslot in up to two phases. Never throws for a child's failure. */
+export declare function measureKeyslot(options: MeasureOptions): Promise<KeyslotMeasurement>;