@consiliency/agent-board-cli 1.27.0 → 1.28.0

package/dist/keyslot_status.js

@@ -0,0 +1,242 @@
+// #552 IF-552-3 — the ONE place in the cli that spawns the packaged keyslot `status.sh`. Setup (the
+// key step, the loader refresh, the re-read before enrolling) and doctor (`key_storage`) all measure
+// a keyslot through `measureKeyslot`, so the scan cache, the two budgets and the process-group
+// cleanup are decided once. KSC-7 pins that no other cli source names `"status.sh"` as a call
+// argument (by the TypeScript AST).
+//
+//   phase 1   `status.sh --scan-cache only` under the STATUS budget (180 s): every measurement, and
+//             the scan only if a valid cache holds it. Never scans.
+//   phase 2   only when phase 1's report says `scan.source: "none"` (no valid cache) and phase 1 did
+//             not exit 1 (unless the caller asked `onFailure: "scan"`): the caller's `before`
+//             notice, then `--scan-cache use` (or `fresh`) under the SCAN budget (30 min), with
+//             `status.sh`'s own progress lines relayed as they arrive, then the `result` notice.
+//
+// The default runner spawns `status.sh` detached, in its own process group, and on its timeout, or on
+// this process's exit, SIGINT or SIGTERM, kills that group; `status.sh` forwards to its scan stage
+// (which `timeout` leads in a group of its own) and bounds it itself (`--scan-timeout`).
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** The status budget: phase 1 (`--scan-cache only`) and every call that never scans. */
+export const STATUS_TIMEOUT_MS = 180_000;
+/** The scan budget (owner answer 2): phase 2, and `status.sh --scan-timeout` in seconds. */
+export const STATUS_SCAN_TIMEOUT_MS = 1_800_000;
+/**
+ * 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 const SCAN_TOMBSTONE_WAIT_MS = 300_000;
+export const SCAN_KILL_AFTER_MS = 10_000;
+export const SCAN_LOCK_WAIT_MS = 10_000;
+/**
+ * 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 function scanBackstopMs(waits) {
+    return waits.lockWaitMs + 2 * waits.killAfterMs + waits.tombstoneWaitMs + waits.marginMs;
+}
+export const SCAN_BACKSTOP_MS = scanBackstopMs({
+    lockWaitMs: SCAN_LOCK_WAIT_MS, killAfterMs: SCAN_KILL_AFTER_MS, tombstoneWaitMs: SCAN_TOMBSTONE_WAIT_MS, marginMs: 60_000,
+});
+const liveGroups = new Set();
+let handlersInstalled = false;
+const killGroup = (pid, signal = "SIGTERM") => {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // already gone
+    }
+};
+const onExit = () => {
+    for (const pid of liveGroups)
+        killGroup(pid);
+};
+const onSignal = (signal) => {
+    onExit();
+    uninstallHandlers();
+    // Die by that signal, as the process would have without this handler.
+    process.kill(process.pid, signal);
+};
+const onSigint = () => onSignal("SIGINT");
+const onSigterm = () => onSignal("SIGTERM");
+function installHandlers() {
+    if (handlersInstalled)
+        return;
+    handlersInstalled = true;
+    process.on("exit", onExit);
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+}
+function uninstallHandlers() {
+    if (!handlersInstalled)
+        return;
+    handlersInstalled = false;
+    process.removeListener("exit", onExit);
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigterm);
+}
+/**
+ * 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 const defaultStorageRunner = (file, args, { env, timeoutMs = STATUS_TIMEOUT_MS, onStderrLine }) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spawn(file, [...args], { env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch {
+        resolve({ code: null, stdout: "", stderr: "" });
+        return;
+    }
+    const pid = child.pid;
+    let stdout = "";
+    let stderr = "";
+    let pending = "";
+    let timedOut = false;
+    let settled = false;
+    if (pid !== undefined) {
+        liveGroups.add(pid);
+        installHandlers();
+    }
+    const timer = setTimeout(() => {
+        timedOut = true;
+        if (pid !== undefined)
+            killGroup(pid);
+    }, timeoutMs);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+        pending += chunk;
+        let newline = pending.indexOf("\n");
+        while (newline >= 0) {
+            const line = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            if (onStderrLine)
+                onStderrLine(line);
+            newline = pending.indexOf("\n");
+        }
+    });
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (pid !== undefined) {
+            liveGroups.delete(pid);
+            if (liveGroups.size === 0)
+                uninstallHandlers();
+        }
+        if (pending !== "" && onStderrLine)
+            onStderrLine(pending);
+        resolve({ code: timedOut ? null : code, stdout, stderr, ...(timedOut ? { timedOut: true } : {}) });
+    };
+    child.on("error", () => finish(null));
+    child.on("close", (exit) => finish(typeof exit === "number" ? exit : null));
+});
+export const DEFAULT_BUDGETS = Object.freeze({ statusMs: STATUS_TIMEOUT_MS, scanMs: STATUS_SCAN_TIMEOUT_MS, backstopMs: SCAN_BACKSTOP_MS });
+export const PROGRESS_LINE = /^status: scan: still scanning \((\d+) folders so far\)$/;
+/** The relayed progress text, before the caller's prefix. */
+export const progressText = (folders) => `checking… still scanning (${folders} folders so far)`;
+const parseReport = (stdout) => {
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** `scan` of a status report, or an empty object. */
+export function scanOf(report) {
+    const scan = report?.scan;
+    return scan && typeof scan === "object" && !Array.isArray(scan) ? scan : {};
+}
+/** `scan.source`: `fresh`, `cached` or `none`; anything else (an older status.sh, no scan at all) reads `none`. */
+export function scanSourceOf(report) {
+    const source = scanOf(report).source;
+    return source === "fresh" || source === "cached" ? source : "none";
+}
+/** `scan.cache` as `{state, reason}` strings (reason "" when null). */
+export function cacheStateOf(report) {
+    const cache = scanOf(report).cache;
+    return {
+        state: typeof cache?.state === "string" ? cache.state : "",
+        reason: typeof cache?.reason === "string" ? cache.reason : "",
+    };
+}
+/** IF-552-3: measure a keyslot in up to two phases. Never throws for a child's failure. */
+export async function measureKeyslot(options) {
+    const file = join(options.dir, "status.sh");
+    if (!existsSync(file))
+        return { absent: true, code: null, report: null, phases: [], timedOut: false, folders: null };
+    const phases = [];
+    let folders = null;
+    let timedOut = false;
+    let lastReport = null;
+    // The measurement so far: the LAST phase's exit and report, always together. An unreadable
+    // phase-2 report is null here, never phase 1's: phase 1 said `scan_not_cached`, and pairing its
+    // report with phase 2's exit 0 authorized a pass (#552 review r1b, codex). Callers that report a
+    // timeout read phase 1 from `phases` themselves.
+    const result = () => {
+        const last = phases.at(-1);
+        return { absent: false, code: last ? last.code : null, report: lastReport, phases, timedOut, folders };
+    };
+    const run = options.run ?? defaultStorageRunner;
+    const budgets = { ...DEFAULT_BUDGETS, ...options.budgets };
+    const base = ["--harness", options.harness, "--slot", options.slot, "--json"];
+    const notify = options.notify ?? (() => { });
+    const call = async (mode) => {
+        const scanning = mode !== "only";
+        const args = [...base, "--scan-cache", mode, ...(scanning ? ["--scan-timeout", String(Math.max(1, Math.ceil(budgets.scanMs / 1000)))] : [])];
+        const outcome = await run(file, args, {
+            // Arms status.sh's parent watch (its ticker ends the scan if this process dies); a hand run,
+            // which has no such variable naming its parent, is never killed for being reparented.
+            env: { ...options.env, KEYSEAL_SCAN_WATCH_PID: String(process.pid) },
+            timeoutMs: scanning ? budgets.scanMs + budgets.backstopMs : budgets.statusMs,
+            onStderrLine: scanning
+                ? (line) => {
+                    const match = PROGRESS_LINE.exec(line);
+                    if (!match)
+                        return;
+                    folders = Number(match[1]);
+                    notify({ kind: "progress", folders });
+                }
+                : undefined,
+        });
+        const phase = { mode, code: outcome.code, timedOut: outcome.timedOut === true, report: parseReport(outcome.stdout) };
+        phases.push(phase);
+        lastReport = phase.report;
+        return phase;
+    };
+    let phase1 = null;
+    if (options.scan !== "fresh") {
+        phase1 = await call("only");
+        if (options.scan === "only")
+            return result();
+        // A phase 1 that did not complete, or said nothing, is the caller's to report (status_did_not_complete).
+        if (phase1.code === null || phase1.report === null)
+            return result();
+        if (scanSourceOf(phase1.report) !== "none")
+            return result();
+        if (phase1.code === 1 && (options.onFailure ?? "stop") === "stop")
+            return result();
+        if (options.skipScan?.(phase1.report))
+            return result();
+    }
+    notify({ kind: "before", phase1: phase1?.report ?? null });
+    const phase2 = await call(options.scan === "fresh" ? "fresh" : "use");
+    timedOut = phase2.timedOut;
+    notify({ kind: "result", phase: phase2 });
+    return result();
+}

package/dist/setup.js

@@ -4,9 +4,11 @@ import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 import { IDENTITY_HARNESSES, createAgentBoardClient, enrollCommitMarker, identityConfigRoot, identityFilePath, normalizeKeyReference, readIdentityFile, readSessionRecords, resolveCredentials, resolveEnrollEndpoint, resolveEnrollmentDescriptor, resolveHostSegment, walkTrustedDirectory, } from "@consiliency/agent-board-client";
 import { bakedAssets as defaultBakedAssets, resolveKeyslotDir } from "./assets.js";
+import { defaultStorageRunner } from "./keyslot_status.js";
 import { authoredCode, fileIdentityEnv, runDoctor } from "./doctor.js";
 import { identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, writeOwnerOnlyFile } from "./identity_writer.js";
-import { SLOT_RE, defaultStorageRunner, repairKeyDir, keyslotSocketDir, selectKeyStorage as defaultSelectKeyStorage, } from "./setup_storage.js";
+import { cacheStateOf, measureKeyslot } from "./keyslot_status.js";
+import { SLOT_RE, repairKeyDir, keyslotSocketDir, selectKeyStorage as defaultSelectKeyStorage, } from "./setup_storage.js";
 import { SETUP_SCOPES, defaultChildRunner, installHarness, scopeRefusal, which, } from "./setup_writers.js";
 export const SETUP_STEPS = Object.freeze(["preflight", "deps", "key", "enroll", "identity", "board", "harness", "doctor"]);
 export const DEFAULT_SUDO = "/usr/bin/sudo";
@@ -319,6 +321,7 @@ export async function runSetup(options, deps = {}) {
     out.record("deps", deps_.status, deps_.reason, deps_.fix);
     // ---- key --------------------------------------------------------------------------------
     let keyReference;
+    let keyScan;
     if (identity.kind === "present") {
         keyReference = identity.values.AGENT_BOARD_AGENT_KEY_REFERENCE;
         const slot = keyslotOf(keyReference, env);
@@ -351,9 +354,20 @@ export async function runSetup(options, deps = {}) {
         for (const repair of selection.repairs)
             out.notes.push(`key: repaired ${repair}`);
         if (selection.storage === "refused") {
-            out.record("key", "failed", selection.reason, selection.fix);
+            // #552: a scan that gave up is undetermined (2); every other refusal, a found copy included, is 1.
+            out.record("key", selection.status ?? "failed", selection.reason, selection.fix);
             return out.report();
         }
+        if ((selection.storage === "sealed" || selection.storage === "unsealed") && selection.slot) {
+            // #552 IF-552-3 "Re-read before enrolling": a tombstone written after (or during) this step's
+            // scan stops setup here, before any enrollment call.
+            const reread = await rereadBeforeEnroll(h, selection.slot, env, deps, selection.keyScan);
+            if (reread) {
+                out.record("key", "failed", reread.reason, reread.fix);
+                return out.report();
+            }
+            keyScan = selection.keyScan;
+        }
         if (selection.storage === "os_keychain") {
             keyReference = `os_keychain:agent-board/${resolveHostSegment(env) ?? slug}/${h}`;
         }
@@ -477,7 +491,12 @@ export async function runSetup(options, deps = {}) {
     // ---- doctor -----------------------------------------------------------------------------
     let report;
     try {
-        report = await (deps.doctor ?? runDoctor)({ harness: h, env, cwd, ...deps.doctorOptions });
+        // #552: the key step's FRESH scan is carried in-process; doctor uses it only where the cache
+        // could not store it (IF-552-3's three conditions). A cached key-step result carries nothing.
+        const setupScan = keyScan?.source === "fresh"
+            ? { setupScan: { inputs: keyScan.inputs, scan: keyScan.scan, scannedAt: keyScan.scannedAt, cacheWrite: keyScan.cacheWrite } }
+            : {};
+        report = await (deps.doctor ?? runDoctor)({ harness: h, env, cwd, ...deps.doctorOptions, ...setupScan });
     }
     catch (error) {
         out.record("doctor", "undetermined", authoredCode(error, "doctor_threw"));
@@ -529,7 +548,7 @@ export async function runSetup(options, deps = {}) {
  * running one, and the measurement is taken again.
  */
 async function refreshLoader(harness, slot, env, deps) {
-    const runStorage = deps.storage?.run ?? defaultStorageRunner;
+    const runStorage = deps.storage?.run;
     let dir;
     try {
         dir = deps.storage?.keyslotDir ?? resolveKeyslotDir();
@@ -537,22 +556,18 @@ async function refreshLoader(harness, slot, env, deps) {
     catch {
         return { status: "undetermined", reason: "keyslot_scripts_absent", fix: "the packaged keyslot scripts are missing: reinstall @consiliency/agent-board-cli" };
     }
+    // #552: loader fields only, so `--scan-cache only`: this never scans (S-3).
     const measure = async () => {
-        const status = await runStorage(join(dir, "status.sh"), ["--harness", harness, "--slot", slot, "--json"], { env });
-        try {
-            const loader = JSON.parse(status.stdout).loader;
-            return loader ? { recorded: loader.recorded_sha256, running: loader.running_sha256 } : null;
-        }
-        catch {
-            return null;
-        }
+        const measured = await measureKeyslot({ dir, harness, slot, env, scan: "only", run: runStorage, budgets: deps.storage?.statusBudgets });
+        const loader = measured.report?.loader;
+        return loader ? { recorded: loader.recorded_sha256, running: loader.running_sha256 } : null;
     };
     const before = await measure();
     if (before === null || typeof before.running !== "string")
         return { status: "undetermined", reason: "loader_unmeasured", fix: "status.sh did not report the loader: run the packaged status.sh --json" };
     if (before.recorded === before.running)
         return { status: "already", reason: "identity_present" };
-    const refresh = await runStorage(join(dir, "provision.sh"), ["--harness", harness, "--slot", slot, "--refresh-loader"], { env });
+    const refresh = await (runStorage ?? defaultStorageRunner)(join(dir, "provision.sh"), ["--harness", harness, "--slot", slot, "--refresh-loader"], { env });
     if (refresh.code !== 0)
         return { status: "failed", reason: "loader_refresh_failed", fix: "provision.sh --refresh-loader failed: run it by hand and read what it reports" };
     const after = await measure();
@@ -560,6 +575,37 @@ async function refreshLoader(harness, slot, env, deps) {
         return { status: "failed", reason: "loader_refresh_unverified", fix: "after --refresh-loader the slot still runs another loader version: run the packaged status.sh --json" };
     return { status: "done", reason: "loader_refreshed" };
 }
+/** Cache reads that are STRUCTURAL: the cache cannot serve on this host at all. */
+const STRUCTURAL_UNUSABLE = /^(untrusted:.+|state_root_relative|machine_id_unreadable)$/;
+/**
+ * #552 IF-552-3 "Re-read before enrolling": `status.sh --scan-cache only` once more, judged on its
+ * `scan.cache`. `miss:cleared` (a tombstone) → plaintext_copy_found; `hit` → proceed; a structural
+ * `unusable`, or `miss:absent` where the key step's own write was `not_written:untrusted_dir` or
+ * `write_failed` → proceed on the key step's own clean result; anything else (`lock_busy`, expired,
+ * future, format, input_changed) → scan_not_completed. null = proceed.
+ */
+async function rereadBeforeEnroll(harness, slot, env, deps, keyScan) {
+    let dir;
+    try {
+        dir = deps.storage?.keyslotDir ?? resolveKeyslotDir();
+    }
+    catch {
+        return { reason: "scan_not_completed", fix: "the packaged keyslot scripts are missing: reinstall @consiliency/agent-board-cli" };
+    }
+    const measured = await measureKeyslot({ dir, harness, slot, env, scan: "only", run: deps.storage?.run, budgets: deps.storage?.statusBudgets });
+    const { state, reason } = cacheStateOf(measured.report);
+    const statusCmd = `the packaged status.sh --harness ${harness} --json`;
+    if (state === "miss" && reason === "cleared") {
+        return { reason: "plaintext_copy_found", fix: `another scan found a plaintext copy of this key after setup's own scan, so it is NOT enrolled: run ${statusCmd} to list the copies, delete them and re-run setup; if a copy may have left this host, run provision.sh --harness ${harness} --rotate instead` };
+    }
+    if (state === "hit")
+        return null;
+    if (state === "unusable" && STRUCTURAL_UNUSABLE.test(reason))
+        return null;
+    if (state === "miss" && reason === "absent" && (keyScan?.cacheWrite === "not_written:untrusted_dir" || keyScan?.cacheWrite === "not_written:write_failed"))
+        return null;
+    return { reason: "scan_not_completed", fix: `the scan cache could not be confirmed before enrolling (${state || "no report"}${reason ? `:${reason}` : ""}), so this key is NOT enrolled: re-run setup, or run ${statusCmd}` };
+}
 export function formatSetupReport(report) {
     return [...report.steps.map((step) => `${step.status.padEnd(12)} ${step.step}: ${step.reason}`), ...report.notes, `exit ${report.exit}`].join("\n");
 }

package/dist/setup_storage.d.ts

@@ -1,7 +1,24 @@
 import { type OsKeychainProbeResult } from "@consiliency/agent-board-client";
+import { defaultStorageRunner, measureKeyslot, type KeyslotMeasurement, type RunOutcome, type ScanBudgets, type StorageRunner } from "./keyslot_status.js";
+export { defaultStorageRunner, type RunOutcome, type StorageRunner };
 export type KeyStorage = "os_keychain" | "sealed" | "unsealed" | "external" | "refused";
+/**
+ * #552 IF-552-3: the key step's completed, clean scan of THIS key, as setup needs it afterwards:
+ * the re-read before enrolling, and (only when `source` is `fresh`) the carry to its own doctor.
+ */
+export interface KeyStepScan {
+    source: "fresh" | "cached";
+    inputs: Record<string, unknown>;
+    scan: Record<string, unknown>;
+    /** The scan's start, epoch seconds (from `scan.scanned_at`). */
+    scannedAt: number;
+    /** The key step's own cache write, `<state>:<reason>`. */
+    cacheWrite: string;
+}
 export interface KeyStorageSelection {
     storage: KeyStorage;
+    /** For a refusal: `failed` (exit 1, the default) or `undetermined` (exit 2: `scan_timed_out`). */
+    status?: "failed" | "undetermined";
     /** An authored code: never a path or any other file string. */
     reason: string;
     /** For a refusal: what the user runs or changes. */
@@ -15,16 +32,9 @@ export interface KeyStorageSelection {
     slot?: string;
     /** The #536 repairs performed, by name, in order. */
     repairs: string[];
+    /** sealed/unsealed: the key step's completed, clean scan (IF-552-3). */
+    keyScan?: KeyStepScan;
 }
-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;
-}
-export type StorageRunner = (file: string, args: readonly string[], options: {
-    env: NodeJS.ProcessEnv;
-}) => Promise<RunOutcome>;
 /** The `deps` step's result, as far as a refusal needs it. */
 export interface DepsOutcome {
     status: "done" | "already" | "skipped" | "failed" | "undetermined";
@@ -53,9 +63,12 @@ export interface KeyStorageContext {
     machineIdFile?: string;
     bash?: string;
     systemctl?: string;
+    /** #552 IF-552-4: the key step's notices (`key: …`), one line each. Default `process.stderr`. */
+    notify?: (line: string) => void;
+    /** #552: the status.sh budgets (tests). */
+    statusBudgets?: Partial<ScanBudgets>;
 }
 export declare const SLOT_RE: RegExp;
-export declare const defaultStorageRunner: StorageRunner;
 /** The opt-in record's host comparand: sha256 of the whole machine-id file, first 16 hex (`sha256sum <`). */
 export declare function machineIdOf(file?: string): string | null;
 /** `$XDG_RUNTIME_DIR/agent-board`, where each keyslot's agent socket lives (constants.sh). */
@@ -104,6 +117,18 @@ export declare const EXTERNAL_FIELDS: readonly ["machine_id", "uid", "socket"];
  * canonical `socket=` (absolute, its own realpath) that is the same device and inode. Empty = valid.
  */
 export declare function externalDeclarationProblems(env: NodeJS.ProcessEnv, socketPath: string, uid: number, machineId: string | null): string[];
+/**
+ * IF-552-3 "Setup's enrollment gate": enroll only after a completed, clean scan of this key, fresh or
+ * cached. A found copy is `plaintext_copy_found` (1); a scan that gave up is `scan_timed_out` (2);
+ * anything else that is not a completed scan is `scan_not_completed` (1). null = the scan passed.
+ */
+export declare function scanGate(harness: string, measured: KeyslotMeasurement): {
+    status: "failed" | "undetermined";
+    reason: string;
+    fix: string;
+} | null;
+/** IF-552-4: setup's `key: ` notices for one measurement. */
+export declare function keyScanNotices(harness: string, notify: (line: string) => void): (event: Parameters<NonNullable<Parameters<typeof measureKeyslot>[0]["notify"]>>[0]) => void;
 /** The #536 repair, then the full ancestor walk. Returns the repairs, or the problems. */
 export declare function repairKeyDir(env: NodeJS.ProcessEnv, uid: number): {
     repairs: string[];

package/dist/setup_storage.js

@@ -19,23 +19,17 @@
 // Every `reason` is an authored code, never file content; the human fix is in `fix`. The same
 // module holds the owner-only KEY=value record reader that doctor's `key_storage` uses for the
 // unsealed opt-in and the external-agent declaration (IF-0-KEYSEAL-6: "checked like the opt-in").
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { OS_KEYCHAIN_SERVICE, probeOsKeychainRoundTrip } from "@consiliency/agent-board-client";
 import { resolveKeyslotDir } from "./assets.js";
+import { cacheStateOf, defaultStorageRunner, measureKeyslot, progressText, scanOf, scanSourceOf, } from "./keyslot_status.js";
+export { defaultStorageRunner };
 export const SLOT_RE = /^[a-z][a-z0-9-]{0,31}$/;
 const REFERENCE_LINE = /^agent_socket:\/\S+#[A-Za-z0-9_-]{43}$/;
 /** States in which `systemctl --user` has a manager answering. */
 const MANAGER_REACHABLE = new Set(["initializing", "starting", "running", "degraded", "maintenance", "stopping"]);
-const RUN_TIMEOUT_MS = 180_000;
-export const defaultStorageRunner = (file, args, { env }) => new Promise((resolve) => {
-    execFile(file, [...args], { env, timeout: RUN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
-        const code = error ? (typeof error.code === "number" && !error.killed ? error.code : null) : 0;
-        resolve({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
-    });
-});
 const currentUid = () => (typeof process.getuid === "function" ? process.getuid() : -1);
 const configRoot = (env) => {
     const xdg = env.XDG_CONFIG_HOME?.trim();
@@ -265,6 +259,79 @@ export function externalDeclarationProblems(env, socketPath, uid, machineId) {
 // selectKeyStorage
 // ---------------------------------------------------------------------------------------------
 const refused = (reason, fix, repairs = []) => ({ storage: "refused", reason, fix, repairs });
+const epochOf = (iso) => {
+    if (typeof iso !== "string")
+        return null;
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+};
+const isoPlus = (epoch, seconds) => new Date((epoch + seconds) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+/**
+ * IF-552-3 "Setup's enrollment gate": enroll only after a completed, clean scan of this key, fresh or
+ * cached. A found copy is `plaintext_copy_found` (1); a scan that gave up is `scan_timed_out` (2);
+ * anything else that is not a completed scan is `scan_not_completed` (1). null = the scan passed.
+ */
+export function scanGate(harness, measured) {
+    const report = measured.report;
+    const scan = scanOf(report);
+    const reasons = Array.isArray(report?.exit2_reasons) ? report.exit2_reasons : [];
+    const scanPhase = measured.phases.find((phase) => phase.mode !== "only");
+    const statusCmd = `the packaged status.sh --harness ${harness} --json`;
+    // Only the helper's own scan budget, or status.sh's own self-bound, is a timeout. Any other kill
+    // of the scan is a scan that did not complete (#552 review r1).
+    if (measured.timedOut || reasons.includes("scan_timed_out")) {
+        return { status: "undetermined", reason: "scan_timed_out", fix: `the plaintext-copy scan gave up after 30 min, so this key is NOT enrolled; re-running setup is safe (provision.sh does not re-key a committed slot), or finish the scan by hand with ${statusCmd}` };
+    }
+    const source = scanSourceOf(report);
+    const matches = Array.isArray(scan.plaintext_matches) ? scan.plaintext_matches : null;
+    const checks = report?.checks;
+    if (source !== "none" && matches !== null && matches.length > 0) {
+        return { status: "failed", reason: "plaintext_copy_found", fix: `a plaintext copy of the new key was found, so it is NOT enrolled: delete the copies ${statusCmd} lists and re-run setup (a committed slot is not re-keyed); if a copy may have left this host, run provision.sh --harness ${harness} --rotate instead` };
+    }
+    if ((scanPhase && scanPhase.code === null) || source === "none" || matches === null || checks?.scan?.ok !== true) {
+        return { status: "failed", reason: "scan_not_completed", fix: `the plaintext-copy scan did not complete, so this key is NOT enrolled: run ${statusCmd} and resolve what it reports, then re-run setup` };
+    }
+    return null;
+}
+/** The key step's scan, recorded for the re-read and the carry (the gate passed). */
+function keyStepScan(report) {
+    const scan = scanOf(report);
+    const source = scanSourceOf(report);
+    const inputs = scan.inputs;
+    const scannedAt = epochOf(scan.scanned_at);
+    if (source === "none" || !inputs || typeof inputs !== "object" || scannedAt === null)
+        return undefined;
+    const { state, reason } = cacheStateOf(report);
+    return { source, inputs: inputs, scan, scannedAt, cacheWrite: `${state}:${reason}` };
+}
+/** IF-552-4: setup's `key: ` notices for one measurement. */
+export function keyScanNotices(harness, notify) {
+    return (event) => {
+        if (event.kind === "before") {
+            const scan = scanOf(event.phase1);
+            const cache = scan.cache;
+            const last = typeof cache?.last_scanned_at === "string" ? cache.last_scanned_at : "never";
+            const why = typeof cache?.read === "string" ? cache.read : "no cache";
+            notify(`key: checking your home and temp folders for stray plaintext copies of the key; on a large home this can take several minutes (last scan: ${last}, ${why})`);
+        }
+        else if (event.kind === "progress") {
+            notify(`key: ${progressText(event.folders)}`);
+        }
+        else {
+            const report = event.phase.report;
+            const scan = scanOf(report);
+            const matches = Array.isArray(scan.plaintext_matches) ? scan.plaintext_matches.length : null;
+            if (scanSourceOf(report) === "none" || matches === null)
+                return;
+            if (matches > 0) {
+                notify(`key: found ${matches} plaintext cop${matches === 1 ? "y" : "ies"} of the key; run the packaged status.sh --harness ${harness} --json to list them`);
+                return;
+            }
+            const start = epochOf(scan.scanned_at);
+            notify(`key: no plaintext copy of the key found (${typeof scan.candidates === "number" ? scan.candidates : "?"} candidate files, ${typeof scan.duration_s === "number" ? scan.duration_s : "?"} s); doctor reuses this until ${start === null ? "24 h after the scan" : isoPlus(start, 86_400)} or the key changes; \`agent-board doctor --harness ${harness} --rescan\` scans again`);
+        }
+    };
+}
 /** The #536 repair, then the full ancestor walk. Returns the repairs, or the problems. */
 export function repairKeyDir(env, uid) {
     const repairs = [];
@@ -457,16 +524,30 @@ export async function selectKeyStorage(ctx) {
             const line = provision.stdout.split("\n").map((entry) => entry.trim()).filter(Boolean).at(-1) ?? "";
             if (!REFERENCE_LINE.test(line))
                 return refused("provision_output_unrecognised", "provision.sh exited 0 without printing an agent_socket: reference; run it by hand and report the output", repairs);
-            const status = await run(join(dir, "status.sh"), ["--harness", ctx.harness, "--slot", slot, "--json"], { env });
-            let mode = null;
-            try {
-                mode = JSON.parse(status.stdout).mode;
+            // #552: one measurement, scanning only when no valid cache holds this key's scan, with
+            // notices before and after. Setup's onFailure is `scan`: a phase-1 exit 1 beside a measured
+            // mode still gets its scan (status.sh scans even on a contradiction).
+            const notify = ctx.notify ?? ((text) => { process.stderr.write(`${text}\n`); });
+            const notices = keyScanNotices(ctx.harness, notify);
+            const measured = await measureKeyslot({
+                dir, harness: ctx.harness, slot, env, scan: "use", onFailure: "scan", run: ctx.run, budgets: ctx.statusBudgets,
+                notify: notices,
+            });
+            if (!measured.phases.some((phase) => phase.mode !== "only") && scanSourceOf(measured.report) === "cached") {
+                notify(`key: plaintext-copy scan cached at ${String(scanOf(measured.report).scanned_at)}`);
             }
-            catch {
-                mode = null;
+            const mode = measured.report?.mode;
+            if (mode === "sealed" || mode === "unsealed") {
+                const gate = scanGate(ctx.harness, measured);
+                if (gate)
+                    return { storage: "refused", status: gate.status, reason: gate.reason, fix: gate.fix, repairs };
+                return { storage: mode, reason: `keyslot_${mode}`, keyReference: line, slot, repairs, keyScan: keyStepScan(measured.report) };
             }
-            if (mode === "sealed" || mode === "unsealed")
-                return { storage: mode, reason: `keyslot_${mode}`, keyReference: line, slot, repairs };
+            const gate = scanGate(ctx.harness, measured);
+            // A scan that ran but whose report could not be read is a scan that did not complete.
+            const scanned = measured.phases.some((phase) => phase.mode !== "only");
+            if (gate && (gate.reason !== "scan_not_completed" || scanned))
+                return { storage: "refused", status: gate.status, reason: gate.reason, fix: gate.fix, repairs };
             return refused("keyslot_mode_unmeasured", "provision.sh succeeded but status.sh does not measure the slot as sealed or unsealed: run the packaged status.sh --json and resolve what it reports", repairs);
         }
         if (provision.code === 2) {