@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/dist/identity_writer.js

@@ -1,174 +1,5 @@
-// CREDPATH SL-2 — the identity file WRITER. The contract (key set, value shapes, path, trusted
-// walk) is the client's `identity_file.ts`; nothing here restates it. This module only decides
-// which VALUES go in, and writes them the way the reader will accept.
-//
-// Order matters, because the Portal enrollment token is single-use
-// (Consiliency/message-board#521): `resolveIdentityDeployment` runs BEFORE enrollment commits,
-// so a missing or secret-shaped deployment value is refused while the token is still unspent.
-// Only then does enrollment run, and `identityValuesFromEnrollment` + `writeIdentityFile` turn
-// its outcome into the file.
-import { createHash } from "node:crypto";
-import { constants as FS } from "node:fs";
-import * as fs from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { CredentialResolutionError, DEPLOYMENT_ENV_ALIASES, describeMissingDeploymentFields, identityConfigRoot, resolveDeploymentField, identityFilePath, serializeIdentityFile, walkTrustedDirectory, } from "@consiliency/agent-board-client";
-async function syncDirectory(path) {
-    const handle = await fs.open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-/** Create `path` exclusively (never following a planted link) at 0600, write, fsync. */
-export async function writeOwnerOnlyFile(path, content) {
-    const handle = await fs.open(path, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW, 0o600);
-    try {
-        await handle.writeFile(content, "utf8");
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-/**
- * Write `content` to `path` so a reader sees the old file or the whole new one, never a
- * part: an exclusive 0600 temp beside it, fsync'd, renamed over it, then the directory
- * fsync'd. On any throw before the rename the temp is removed.
- */
-export async function writeOwnerOnlyFileAtomic(path, content, options = {}) {
-    const sync = options.syncDirectory ?? syncDirectory;
-    const temp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-    try {
-        await writeOwnerOnlyFile(temp, content);
-        await fs.rename(temp, path);
-    }
-    catch (error) {
-        await fs.unlink(temp).catch(() => { });
-        throw error;
-    }
-    await sync(dirname(path));
-}
-/**
- * Where each deployment value is read, in precedence order: the client's one alias table
- * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
- * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
- * the same table, so the two cannot disagree. The generic Supabase names are in no list: a
- * generic key never fills an identity field, here or in the loader.
- */
-export const DEPLOYMENT_ENV_NAMES = Object.freeze({
-    boardUrl: DEPLOYMENT_ENV_ALIASES.boardUrl,
-    sessionUrl: DEPLOYMENT_ENV_ALIASES.sessionUrl,
-    publishableKey: DEPLOYMENT_ENV_ALIASES.publishableKey,
-});
-const DEPLOYMENT_FILE_KEYS = {
-    boardUrl: "AGENT_BOARD_URL",
-    sessionUrl: "AGENT_BOARD_SESSION_URL",
-    publishableKey: "AGENT_BOARD_PUBLISHABLE_KEY",
-};
-// Well-shaped stand-ins for the values only the enrollment outcome supplies. The preflight
-// substitutes ONE deployment value into this map and lets `serializeIdentityFile` judge it, so
-// the shape rule applied here is the parser's own, never a second copy.
-const PREFLIGHT_STAND_INS = {
-    AGENT_BOARD_URL: "https://preflight.invalid",
-    AGENT_BOARD_SESSION_URL: "https://preflight.invalid/session",
-    AGENT_BOARD_PUBLISHABLE_KEY: "sb_publishable_preflight",
-    AGENT_BOARD_AGENT_SLUG: "preflight",
-    AGENT_BOARD_EXPECTED_AGENT_HANDLE: "preflight",
-    AGENT_BOARD_AGENT_KEY_REFERENCE: "os_keychain:preflight",
-    AGENT_BOARD_SIGNING_KEY_ID: "preflight",
-    AGENT_BOARD_SIGNING_KEY_VERSION: "1",
-    AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT: `sha256:${"A".repeat(43)}`,
-    MESSAGE_BOARD_AGENT_AUTH_MODE: "keystore_session",
-};
-/**
- * The deployment half of an identity, read and shape-checked before enrollment commits. Each
- * value is the shipped default, or env under the board group's all-or-nothing rule (the
- * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
- * naming the variable that switched the group off; not the non-secret shape its key requires →
- * `identity_secret_value`. Both name the variable, never the value.
- */
-export function resolveIdentityDeployment(env) {
-    const deployment = {};
-    for (const field of Object.keys(DEPLOYMENT_ENV_NAMES)) {
-        const resolved = resolveDeploymentField(env, field);
-        if (resolved.value === undefined) {
-            throw new CredentialResolutionError("identity_incomplete", `cannot write an identity file: no ${DEPLOYMENT_FILE_KEYS[field]} for it ${describeMissingDeploymentFields([field], resolved.switchedBy)}`);
-        }
-        // A default is named by the file key it fills: it came from no variable.
-        const found = { name: resolved.name ?? `the default ${DEPLOYMENT_FILE_KEYS[field]}`, value: resolved.value };
-        try {
-            serializeIdentityFile({ ...PREFLIGHT_STAND_INS, [DEPLOYMENT_FILE_KEYS[field]]: found.value });
-        }
-        catch (error) {
-            if (error.code !== "identity_secret_value")
-                throw error;
-            throw new CredentialResolutionError("identity_secret_value", `${found.name} is not the non-secret shape ${DEPLOYMENT_FILE_KEYS[field]} requires; an identity file carries public values only`);
-        }
-        deployment[field] = found.value;
-    }
-    return deployment;
-}
-// ---------------------------------------------------------------------------------------------
-// Outcome → values → file
-// ---------------------------------------------------------------------------------------------
-/** `sha256:` + base64url, over the DECODED public key — exactly what fleet finalize recomputes. */
-function publicKeyFingerprint(agentPublicKey) {
-    const publicKey = Buffer.from(agentPublicKey, "base64url");
-    // The same refusal finalize makes: a value that is not canonical base64url of 32 bytes would
-    // still hash to a plausible fingerprint, of a key that is not the enrolled one. The
-    // re-encode comparison is also the charset and padding check.
-    if (publicKey.length !== 32 || publicKey.toString("base64url") !== agentPublicKey) {
-        throw new CredentialResolutionError("identity_public_key_invalid", "the enrollment outcome's public key is not a 32-byte base64url key");
-    }
-    return `sha256:${createHash("sha256").update(publicKey).digest("base64url")}`;
-}
-/**
- * The identity file's values for an enrolled agent. The URLs and publishable key come only
- * from `deployment`; everything else from the outcome. Validated by the client's serializer
- * before it is returned.
- */
-export function identityValuesFromEnrollment(outcome, deployment) {
-    const values = {
-        AGENT_BOARD_URL: deployment.boardUrl,
-        AGENT_BOARD_SESSION_URL: deployment.sessionUrl,
-        AGENT_BOARD_PUBLISHABLE_KEY: deployment.publishableKey,
-        AGENT_BOARD_AGENT_SLUG: outcome.agentHandle,
-        AGENT_BOARD_EXPECTED_AGENT_HANDLE: outcome.agentHandle,
-        // The form `fleet_onboarding.ts` checks: `${resolver}:${handle}`.
-        AGENT_BOARD_AGENT_KEY_REFERENCE: `${outcome.keyReference.resolver}:${outcome.keyReference.handle}`,
-        // `keyId`, the server's key identity /session mints against — NOT `signingKeyId`, the row.
-        AGENT_BOARD_SIGNING_KEY_ID: outcome.keyId,
-        AGENT_BOARD_SIGNING_KEY_VERSION: String(outcome.keyVersion),
-        AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT: publicKeyFingerprint(outcome.agentPublicKey),
-        MESSAGE_BOARD_AGENT_AUTH_MODE: "keystore_session",
-    };
-    serializeIdentityFile(values);
-    return values;
-}
-async function mkdirPrivate(path) {
-    await fs.mkdir(path, { mode: 0o700 }).catch((error) => {
-        if (error.code !== "EEXIST")
-            throw error;
-    });
-}
-/**
- * Write `harness`'s identity file for this host. Every refusal (bad harness, relative root,
- * invalid host, bad value) fires before the first filesystem change. The directory is then
- * put through the reader's own trusted walk, so the writer never produces a file the loader
- * would refuse to open. Returns the path written.
- */
-export async function writeIdentityFile(harness, values, env, options = {}) {
-    const path = identityFilePath(harness, env);
-    const content = serializeIdentityFile(values);
-    const configRoot = identityConfigRoot(env);
-    const strictFrom = join(configRoot, "agent-board");
-    await fs.mkdir(configRoot, { recursive: true, mode: 0o700 });
-    await mkdirPrivate(strictFrom);
-    await mkdirPrivate(join(strictFrom, "identities"));
-    await mkdirPrivate(dirname(path));
-    walkTrustedDirectory(dirname(path), strictFrom);
-    await writeOwnerOnlyFileAtomic(path, content, options);
-    return path;
-}
+// CREDPATH SL-2 — the identity file writer. ONBOARD SL-1 (IF-0-ONBOARD-9) moved its bodies to the
+// client (`@consiliency/agent-board-client`, `identity_writer.ts`) so the MCP server's in-chat
+// enrollment writes the same file through the same code; this module keeps every export, as a
+// re-export, so no cli caller changes.
+export { DEPLOYMENT_ENV_NAMES, identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, writeOwnerOnlyFile, writeOwnerOnlyFileAtomic, } from "@consiliency/agent-board-client";

package/dist/keyslot_status.d.ts

@@ -0,0 +1,134 @@
+/** 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>;
+export interface MeasureSlotsOptions extends Omit<MeasureOptions, "harness" | "slot" | "notify" | "skipScan"> {
+    /** The slots to measure. Each name is ALSO its harness: `status.sh --slots` takes no `--harness`. */
+    slots: readonly string[];
+    /** Per-slot events; `progress` is the one shared walk's, so its slot is null. */
+    notify?: (slot: string | null, event: ScanEvent) => void;
+}
+/**
+ * ONBOARD SL-4 (IF-0-ONBOARD-1 "a key scan at most once per host"): several keyslots measured with
+ * ONE filesystem walk, in the same two phases as `measureKeyslot`. One slot IS `measureKeyslot`
+ * (the `--harness` form, byte-identical to a single-harness setup). Two or more use
+ * `status.sh --slots a,b,… --json`: phase 1 (`--scan-cache only`) for every slot, then ONE phase 2
+ * over just the slots phase 1 left without a valid cache. That form has no `--harness`, so each
+ * name is both the harness and the slot — true for setup, which never names a slot of its own.
+ * Each slot's phase `code` is its own line's `exit`; the process exit is only the worst of them.
+ * Lines are matched by their `slot` field, never by position. Never throws for a child's failure.
+ */
+export declare function measureKeyslots(options: MeasureSlotsOptions): Promise<Map<string, KeyslotMeasurement>>;

package/dist/keyslot_status.js

@@ -0,0 +1,348 @@
+// #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. `setup --all` measures several slots through `measureKeyslots`
+// (`status.sh --slots`, one walk). 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();
+}
+/** status.sh `--slots` output: one JSON object per line, each naming its own slot. */
+const parseSlotReports = (stdout) => {
+    const reports = new Map();
+    for (const line of stdout.split("\n")) {
+        const report = parseReport(line);
+        if (report && typeof report.slot === "string" && !reports.has(report.slot))
+            reports.set(report.slot, report);
+    }
+    return reports;
+};
+/**
+ * ONBOARD SL-4 (IF-0-ONBOARD-1 "a key scan at most once per host"): several keyslots measured with
+ * ONE filesystem walk, in the same two phases as `measureKeyslot`. One slot IS `measureKeyslot`
+ * (the `--harness` form, byte-identical to a single-harness setup). Two or more use
+ * `status.sh --slots a,b,… --json`: phase 1 (`--scan-cache only`) for every slot, then ONE phase 2
+ * over just the slots phase 1 left without a valid cache. That form has no `--harness`, so each
+ * name is both the harness and the slot — true for setup, which never names a slot of its own.
+ * Each slot's phase `code` is its own line's `exit`; the process exit is only the worst of them.
+ * Lines are matched by their `slot` field, never by position. Never throws for a child's failure.
+ */
+export async function measureKeyslots(options) {
+    const slots = [...new Set(options.slots)];
+    const measured = new Map();
+    if (slots.length === 1) {
+        const [slot] = slots;
+        const { notify, slots: _slots, ...rest } = options;
+        void _slots;
+        measured.set(slot, await measureKeyslot({ ...rest, harness: slot, slot, ...(notify ? { notify: (event) => notify(slot, event) } : {}) }));
+        return measured;
+    }
+    if (slots.length === 0)
+        return measured;
+    const file = join(options.dir, "status.sh");
+    if (!existsSync(file)) {
+        for (const slot of slots)
+            measured.set(slot, { absent: true, code: null, report: null, phases: [], timedOut: false, folders: null });
+        return measured;
+    }
+    const run = options.run ?? defaultStorageRunner;
+    const budgets = { ...DEFAULT_BUDGETS, ...options.budgets };
+    const notify = options.notify ?? (() => { });
+    const phases = new Map(slots.map((slot) => [slot, []]));
+    const scanTimedOut = new Set();
+    let folders = null;
+    const call = async (mode, names) => {
+        const scanning = mode !== "only";
+        const args = ["--slots", names.join(","), "--json", "--scan-cache", mode, ...(scanning ? ["--scan-timeout", String(Math.max(1, Math.ceil(budgets.scanMs / 1000)))] : [])];
+        const outcome = await run(file, args, {
+            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(null, { kind: "progress", folders });
+                }
+                : undefined,
+        });
+        const reports = parseSlotReports(outcome.stdout);
+        const called = new Map();
+        for (const name of names) {
+            const report = reports.get(name) ?? null;
+            // A process that did not exit on its own judged nothing, whatever it printed first.
+            const code = outcome.code === null ? null : typeof report?.exit === "number" ? report.exit : outcome.code;
+            const phase = { mode, code, timedOut: outcome.timedOut === true, report: outcome.code === null ? null : report };
+            phases.get(name).push(phase);
+            called.set(name, phase);
+        }
+        return called;
+    };
+    let toScan = slots;
+    const phase1 = options.scan === "fresh" ? null : await call("only", slots);
+    if (phase1 !== null) {
+        if (options.scan === "only")
+            toScan = [];
+        else {
+            toScan = slots.filter((slot) => {
+                const phase = phase1.get(slot);
+                if (phase.code === null || phase.report === null)
+                    return false;
+                if (scanSourceOf(phase.report) !== "none")
+                    return false;
+                return !(phase.code === 1 && (options.onFailure ?? "stop") === "stop");
+            });
+        }
+    }
+    if (toScan.length > 0) {
+        for (const slot of toScan)
+            notify(slot, { kind: "before", phase1: phase1?.get(slot)?.report ?? null });
+        const phase2 = await call(options.scan === "fresh" ? "fresh" : "use", toScan);
+        for (const [slot, phase] of phase2) {
+            if (phase.timedOut)
+                scanTimedOut.add(slot);
+            notify(slot, { kind: "result", phase });
+        }
+    }
+    for (const slot of slots) {
+        const list = phases.get(slot);
+        const last = list.at(-1);
+        measured.set(slot, { absent: false, code: last ? last.code : null, report: last ? last.report : null, phases: list, timedOut: scanTimedOut.has(slot), folders });
+    }
+    return measured;
+}