@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/dist/setup_all.d.ts

@@ -0,0 +1,51 @@
+import { type IdentityHarness } from "@consiliency/agent-board-client";
+import { type SetupDeps, type SetupReport, type SetupStep, type StaleSession } from "./setup.js";
+export interface SetupAllOptions {
+    invite?: boolean;
+    inviteFile?: string;
+    scope?: string;
+    /** Each `<harness>=<slug>`; a harness without one gets `<short host>-<harness>`. */
+    slugs?: readonly string[];
+    allowUnsealedKey?: boolean;
+    installDeps?: boolean;
+    /** Default true; `--no-follow-symlinks` is passed to every pair. */
+    followSymlinks?: boolean;
+    harness?: string;
+    agentSocket?: string;
+    clearPending?: boolean;
+}
+export type SetupPairStatus = "done" | "already" | "failed" | "undetermined" | "absent";
+export interface SetupAllPair {
+    harness: IdentityHarness;
+    status: SetupPairStatus;
+    /** null for an absent harness. */
+    slug: string | null;
+    steps: SetupStep[];
+    notes: string[];
+    staleSessions: StaleSession[];
+}
+export interface SetupAllReport {
+    /** The run's own steps (preflight). */
+    steps: SetupStep[];
+    /** One per identity harness, in IDENTITY_HARNESSES order. */
+    pairs: SetupAllPair[];
+    exit: 0 | 1 | 2;
+    notes: string[];
+}
+export type SetupAllRunner = (options: SetupAllOptions) => Promise<SetupAllReport>;
+/**
+ * A pair is `already` when this host already had its identity AND its registration was exact: the
+ * enroll and harness steps both say so. A failed or undetermined step outranks it.
+ */
+export declare function pairStatus(report: SetupReport): Exclude<SetupPairStatus, "absent">;
+export declare function runSetupAll(options: SetupAllOptions, deps?: SetupDeps): Promise<SetupAllReport>;
+export declare function formatSetupAllReport(report: SetupAllReport): string;
+/** `--json`: the run's steps and each pair's step objects. Notes stay human (stderr). */
+export declare function setupAllJson(report: SetupAllReport): Record<string, unknown>;
+/** The `setup --all` command body: run, print, return the exit. */
+export declare function setupAllCommand(run: SetupAllRunner, io: {
+    writeStdout(message: string): void;
+    writeStderr(message: string): void;
+}): (options: SetupAllOptions, output: {
+    json: boolean;
+}) => Promise<0 | 1 | 2>;

package/dist/setup_all.js

@@ -0,0 +1,164 @@
+// ONBOARD IF-0-ONBOARD-1 — `agent-board setup --all`: every identity harness on this host in one run.
+//
+//   preflight  run-level refusals (`--agent-socket`, `--clear-pending`, `--harness`, a malformed
+//              `--slug <harness>=<slug>`), then the invite, read and parsed ONCE: a malformed
+//              invite refuses the whole run before any pair enrolls
+//   the set    derived from IDENTITY_HARNESSES, never listed: a harness is present when its CLI is on
+//              PATH (`harnessCliPath`); an absent one is reported `absent`, never skipped silently
+//   pairs      every present pair runs setup's preflight, deps and key PREPARATION; then ONE key
+//              scan covers every keyslot pair's key (`status.sh --slots`, one walk; a keychain host
+//              never scans); then each pair's storage is finalized from that scan; then each pair
+//              enrolls, writes its identity, redeems the invite, registers and runs doctor, in turn
+//   failures   a failed pair never stops the others; a refused redeem is `invite_unusable` for that
+//              pair and the later pairs still try their own
+//   exit       the worst pair's: failed (1) outranks undetermined (2), which outranks 0; `absent`
+//              counts as 0
+//
+// Capacity is never pre-checked: an invite's remaining uses and board are creator-only reads, and a
+// fresh host has no identity to read them with. The redeem RPC's refusal is uniform, and setup never
+// tells its causes apart.
+import { IDENTITY_HARNESSES, } from "@consiliency/agent-board-client";
+import { finishSetupPair, inviteBoardNote, readSetupInvite, setupStorageContext, startSetupPair, } from "./setup.js";
+import { finalizeKeyStorage, measureKeyStorage } from "./setup_storage.js";
+import { harnessCliPath } from "./setup_writers.js";
+const worst = (statuses) => (statuses.includes("failed") ? 1 : statuses.includes("undetermined") ? 2 : 0);
+/**
+ * A pair is `already` when this host already had its identity AND its registration was exact: the
+ * enroll and harness steps both say so. A failed or undetermined step outranks it.
+ */
+export function pairStatus(report) {
+    const exit = worst(report.steps.map((step) => step.status));
+    if (exit === 1)
+        return "failed";
+    if (exit === 2)
+        return "undetermined";
+    const status = (name) => report.steps.find((step) => step.step === name)?.status;
+    return status("enroll") === "already" && status("harness") === "already" ? "already" : "done";
+}
+/** `--slug <harness>=<slug>`, each harness at most once. The slug itself is judged by the pair's preflight. */
+function parseSlugOverrides(entries) {
+    const slugs = new Map();
+    for (const entry of entries) {
+        const eq = entry.indexOf("=");
+        const harness = eq > 0 ? entry.slice(0, eq) : "";
+        if (!IDENTITY_HARNESSES.includes(harness)) {
+            return { reason: "slug_override_invalid", fix: `with --all, --slug takes <harness>=<slug>, where <harness> is one of ${IDENTITY_HARNESSES.join(", ")}` };
+        }
+        if (slugs.has(harness))
+            return { reason: "slug_override_repeated", fix: `--slug names ${harness} more than once` };
+        slugs.set(harness, entry.slice(eq + 1));
+    }
+    return slugs;
+}
+export async function runSetupAll(options, deps = {}) {
+    const env = deps.env ?? process.env;
+    const steps = [];
+    const notes = [];
+    const refuse = (reason, fix) => {
+        steps.push({ step: "preflight", status: "failed", reason });
+        notes.push(`preflight: ${fix}`);
+        return { steps, pairs: [], exit: 1, notes };
+    };
+    // ---- run-level preflight --------------------------------------------------------------------
+    if (options.harness !== undefined)
+        return refuse("harness_with_all", "--all sets up every harness on this host: drop --harness, or drop --all");
+    if (options.agentSocket !== undefined)
+        return refuse("agent_socket_with_all", "--agent-socket names one key, so it is refused with --all: set up that harness alone with `agent-board setup --harness <h> --agent-socket <ref>`");
+    if (options.clearPending)
+        return refuse("clear_pending_with_all", "--clear-pending clears one harness's marker, so it is refused with --all: run `agent-board setup --harness <h> --clear-pending`");
+    const slugs = parseSlugOverrides(options.slugs ?? []);
+    if (!(slugs instanceof Map))
+        return refuse(slugs.reason, slugs.fix);
+    // The invite, ONCE, before any pair: every pair redeems this same parsed code.
+    const read = await readSetupInvite(options, deps);
+    if (!("invite" in read))
+        return refuse(read.reason, read.fix);
+    const invite = read.invite;
+    if (invite !== null)
+        notes.push(inviteBoardNote(invite));
+    steps.push({ step: "preflight", status: "done", reason: "ready" });
+    // ---- the harness set, derived -----------------------------------------------------------------
+    const present = new Set(IDENTITY_HARNESSES.filter((harness) => harnessCliPath(harness, env) !== null));
+    for (const harness of slugs.keys()) {
+        if (!present.has(harness))
+            notes.push(`preflight: --slug ${harness}=… is unused: no ${harness} CLI is on PATH`);
+    }
+    // ---- every pair up to its key preparation -------------------------------------------------------
+    const reports = new Map();
+    const started = [];
+    for (const harness of IDENTITY_HARNESSES) {
+        if (!present.has(harness))
+            continue;
+        const start = await startSetupPair({
+            harness,
+            ...(slugs.has(harness) ? { slug: slugs.get(harness) } : {}),
+            ...(options.scope !== undefined ? { scope: options.scope } : {}),
+            allowUnsealedKey: options.allowUnsealedKey === true,
+            installDeps: options.installDeps === true,
+            followSymlinks: options.followSymlinks !== false,
+        }, deps, { invite });
+        if (start.kind === "stopped")
+            reports.set(harness, start.report);
+        else
+            started.push(start.pair);
+    }
+    // ---- ONE key scan for every keyslot pair, then each pair's storage ------------------------------
+    const prepared = started.map((pair) => pair.prepared).filter((entry) => entry !== null);
+    const finalized = finalizeKeyStorage(prepared, await measureKeyStorage(prepared, setupStorageContext(deps)));
+    const selectionOf = new Map(prepared.map((entry, index) => [entry, finalized[index]]));
+    // ---- the rest, pair by pair, continuing past a failure ------------------------------------------
+    for (const pair of started) {
+        reports.set(pair.harness, await finishSetupPair(pair, pair.prepared === null ? null : selectionOf.get(pair.prepared) ?? null));
+    }
+    const pairs = IDENTITY_HARNESSES.map((harness) => {
+        const report = reports.get(harness);
+        if (report === undefined) {
+            return { harness, status: "absent", slug: null, steps: [], notes: [`${harness}: no ${harness} CLI on PATH; install it, then re-run setup --all`], staleSessions: [] };
+        }
+        const slug = started.find((pair) => pair.harness === harness)?.slug ?? null;
+        return { harness, status: pairStatus(report), slug, steps: report.steps, notes: report.notes, staleSessions: report.staleSessions };
+    });
+    const refused = pairs.filter((pair) => pair.steps.some((step) => step.step === "board" && step.status === "failed" && step.reason === "invite_unusable"));
+    if (refused.length > 0) {
+        notes.push(`board: the invite was refused for ${refused.map((pair) => pair.harness).join(", ")}; the board does not say why (used up, revoked, expired, or not usable by that agent), so a new invite may be needed: ask the board owner`);
+    }
+    return { steps, pairs, exit: worst([...steps.map((step) => step.status), ...pairs.map((pair) => pair.status)]), notes };
+}
+export function formatSetupAllReport(report) {
+    const lines = report.steps.map((step) => `${step.status.padEnd(12)} ${step.step}: ${step.reason}`);
+    if (report.pairs.length > 0) {
+        lines.push(`${"harness".padEnd(10)} ${"status".padEnd(12)} ${"slug".padEnd(28)} detail`);
+        for (const pair of report.pairs) {
+            const stop = pair.steps.find((step) => step.status === "failed" || step.status === "undetermined");
+            lines.push(`${pair.harness.padEnd(10)} ${pair.status.padEnd(12)} ${(pair.slug ?? "-").padEnd(28)} ${stop ? `${stop.step}: ${stop.status} ${stop.reason}` : ""}`.trimEnd());
+        }
+        for (const pair of report.pairs)
+            for (const note of pair.notes)
+                lines.push(`[${pair.harness}] ${note}`);
+    }
+    return [...lines, ...report.notes, `exit ${report.exit}`].join("\n");
+}
+/** `--json`: the run's steps and each pair's step objects. Notes stay human (stderr). */
+export function setupAllJson(report) {
+    return {
+        steps: report.steps,
+        pairs: report.pairs.map((pair) => ({ harness: pair.harness, status: pair.status, slug: pair.slug, steps: pair.steps, stale_sessions: pair.staleSessions })),
+        exit: report.exit,
+    };
+}
+/** The `setup --all` command body: run, print, return the exit. */
+export function setupAllCommand(run, io) {
+    return async (options, output) => {
+        const report = await run(options);
+        if (output.json) {
+            io.writeStdout(`${JSON.stringify(setupAllJson(report))}\n`);
+            const notes = [...report.pairs.flatMap((pair) => pair.notes.map((note) => `[${pair.harness}] ${note}`)), ...report.notes];
+            if (notes.length > 0)
+                io.writeStderr(`${notes.join("\n")}\n`);
+        }
+        else {
+            io.writeStdout(`${formatSetupAllReport(report)}\n`);
+        }
+        return report.exit;
+    };
+}

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[];
@@ -122,8 +147,46 @@ export declare function macosKeychainRefusal(probe: OsKeychainProbeResult | null
     reason: string;
     fix: string;
 };
+/**
+ * ONBOARD SL-4: the key storage chosen and provisioned but NOT yet scanned. `selected` is final
+ * (the keychain, an external agent, or a refusal). `keyslot` holds a provisioned slot that may be
+ * used only once `finalizeKeyStorage` has seen a completed scan covering it (IF-552-3).
+ */
+export type PreparedKeyStorage = {
+    kind: "selected";
+    harness: string;
+    selection: KeyStorageSelection;
+} | {
+    kind: "keyslot";
+    harness: string;
+    slot: string;
+    keyReference: string;
+    repairs: string[];
+    keyslotDir: string;
+};
+/** One measurement per keyslot slot, every one from ONE `measureKeyslots` call. */
+export type KeyslotScan = ReadonlyMap<string, KeyslotMeasurement>;
+/**
+ * The ONE measurement for every prepared keyslot pair (IF-0-ONBOARD-1 "a key scan at most once per
+ * host"), with setup's `key: ` notices; null when no pair is a keyslot (a keychain host never
+ * scans). One pair is measured exactly as a single-harness setup always was.
+ */
+export declare function measureKeyStorage(pairs: readonly PreparedKeyStorage[], ctx: Pick<KeyStorageContext, "env" | "run" | "statusBudgets" | "notify">): Promise<KeyslotScan | null>;
+/**
+ * ONBOARD SL-4: each pair's storage. A keyslot pair gets its slot ONLY when `scan` is one completed
+ * measurement covering EVERY keyslot pair's key, and is clean for that key; with no scan, or one
+ * that misses any keyslot pair, every keyslot pair is refused `scan_not_completed`. Other pairs
+ * pass through unchanged. Order is the input's.
+ */
+export declare function finalizeKeyStorage(pairs: readonly PreparedKeyStorage[], scan: KeyslotScan | null): KeyStorageSelection[];
 /**
  * IF-0-SETUP-3: the key storage, measured, in the IF-0-KEYSEAL-6 order. Never throws for a host
- * condition; a refusal carries the fix.
+ * condition; a refusal carries the fix. Prepare, then the one scan, then finalize: the same three
+ * steps `setup --all` runs over every pair.
  */
 export declare function selectKeyStorage(ctx: KeyStorageContext): Promise<KeyStorageSelection>;
+/**
+ * ONBOARD SL-4: the IF-0-KEYSEAL-6 order up to and including provision.sh, and NO scan. A slot is
+ * returned as `keyslot`, never as usable storage: only `finalizeKeyStorage` turns it into one.
+ */
+export declare function prepareKeyStorage(ctx: KeyStorageContext): Promise<PreparedKeyStorage>;

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, measureKeyslots, 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 = [];
@@ -389,23 +456,108 @@ export function macosKeychainRefusal(probe) {
         }
     }
 }
+/**
+ * The ONE measurement for every prepared keyslot pair (IF-0-ONBOARD-1 "a key scan at most once per
+ * host"), with setup's `key: ` notices; null when no pair is a keyslot (a keychain host never
+ * scans). One pair is measured exactly as a single-harness setup always was.
+ */
+export async function measureKeyStorage(pairs, ctx) {
+    const slots = pairs.filter((pair) => pair.kind === "keyslot");
+    if (slots.length === 0)
+        return null;
+    const notify = ctx.notify ?? ((text) => { process.stderr.write(`${text}\n`); });
+    // Several pairs are told apart by harness; one pair's notices are byte-identical to before.
+    const noticesFor = new Map(slots.map((pair) => [pair.slot, keyScanNotices(pair.harness, slots.length === 1 ? notify : (line) => notify(`[${pair.harness}] ${line}`))]));
+    // 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 env = ctx.env ?? process.env;
+    const measured = slots.length === 1
+        ? new Map([[slots[0].slot, await measureKeyslot({
+                    dir: slots[0].keyslotDir, harness: slots[0].harness, slot: slots[0].slot, env, scan: "use", onFailure: "scan", run: ctx.run, budgets: ctx.statusBudgets,
+                    notify: noticesFor.get(slots[0].slot),
+                })]])
+        : await measureKeyslots({
+            // `--slots` names each slot as its own harness: setup's slot is always its harness.
+            dir: slots[0].keyslotDir, slots: slots.map((pair) => pair.slot), env, scan: "use", onFailure: "scan", run: ctx.run, budgets: ctx.statusBudgets,
+            notify: (slot, event) => {
+                if (slot !== null)
+                    noticesFor.get(slot)?.(event);
+                else if (event.kind === "progress")
+                    notify(`key: ${progressText(event.folders)}`);
+            },
+        });
+    for (const pair of slots) {
+        const one = measured.get(pair.slot);
+        if (one && !one.phases.some((phase) => phase.mode !== "only") && scanSourceOf(one.report) === "cached") {
+            notify(`${slots.length === 1 ? "" : `[${pair.harness}] `}key: plaintext-copy scan cached at ${String(scanOf(one.report).scanned_at)}`);
+        }
+    }
+    return measured;
+}
+/** The IF-552-3 gate on one provisioned slot, judged from its measurement. */
+function judgeKeyslot(pair, measured) {
+    const { repairs, slot } = pair;
+    const mode = measured.report?.mode;
+    if (mode === "sealed" || mode === "unsealed") {
+        const gate = scanGate(pair.harness, measured);
+        if (gate)
+            return { storage: "refused", status: gate.status, reason: gate.reason, fix: gate.fix, repairs };
+        return { storage: mode, reason: `keyslot_${mode}`, keyReference: pair.keyReference, slot, repairs, keyScan: keyStepScan(measured.report) };
+    }
+    const gate = scanGate(pair.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);
+}
+/**
+ * ONBOARD SL-4: each pair's storage. A keyslot pair gets its slot ONLY when `scan` is one completed
+ * measurement covering EVERY keyslot pair's key, and is clean for that key; with no scan, or one
+ * that misses any keyslot pair, every keyslot pair is refused `scan_not_completed`. Other pairs
+ * pass through unchanged. Order is the input's.
+ */
+export function finalizeKeyStorage(pairs, scan) {
+    const covered = scan !== null && pairs.every((pair) => pair.kind !== "keyslot" || scan.has(pair.slot));
+    return pairs.map((pair) => {
+        if (pair.kind === "selected")
+            return pair.selection;
+        if (!covered) {
+            return { storage: "refused", status: "failed", reason: "scan_not_completed", repairs: pair.repairs,
+                fix: `no completed plaintext-copy scan covered this key, so it is NOT enrolled: run the packaged status.sh --harness ${pair.harness} --json and resolve what it reports, then re-run setup` };
+        }
+        return judgeKeyslot(pair, scan.get(pair.slot));
+    });
+}
 /**
  * IF-0-SETUP-3: the key storage, measured, in the IF-0-KEYSEAL-6 order. Never throws for a host
- * condition; a refusal carries the fix.
+ * condition; a refusal carries the fix. Prepare, then the one scan, then finalize: the same three
+ * steps `setup --all` runs over every pair.
  */
 export async function selectKeyStorage(ctx) {
+    const prepared = await prepareKeyStorage(ctx);
+    if (prepared.kind === "selected")
+        return prepared.selection;
+    return finalizeKeyStorage([prepared], await measureKeyStorage([prepared], ctx))[0];
+}
+/**
+ * ONBOARD SL-4: the IF-0-KEYSEAL-6 order up to and including provision.sh, and NO scan. A slot is
+ * returned as `keyslot`, never as usable storage: only `finalizeKeyStorage` turns it into one.
+ */
+export async function prepareKeyStorage(ctx) {
+    const selected = (selection) => ({ kind: "selected", harness: ctx.harness, selection });
     const env = ctx.env ?? process.env;
     const platform = ctx.platform ?? process.platform;
     const uid = ctx.uid ?? currentUid();
     const run = ctx.run ?? defaultStorageRunner;
     const slot = ctx.slot ?? ctx.harness;
     if (!SLOT_RE.test(ctx.harness) || !SLOT_RE.test(slot))
-        return refused("bad_slot", "the harness and slot must match ^[a-z][a-z0-9-]{0,31}$");
+        return selected(refused("bad_slot", "the harness and slot must match ^[a-z][a-z0-9-]{0,31}$"));
     // 0. An explicit --agent-socket wins over everything discovery would find — the keychain and a
     //    key slot alike (code review r1, owner decision; a plan amendment to the IF-0-KEYSEAL-6
     //    order, recorded in SL-7): a user who names their own agent means it. Nothing is probed.
     if (ctx.agentSocket !== undefined)
-        return externalAgent(ctx.agentSocket, env, uid, ctx.machineIdFile, []);
+        return selected(externalAgent(ctx.agentSocket, env, uid, ctx.machineIdFile, []));
     // 1. A live keychain round trip.
     let keychain = null;
     try {
@@ -415,7 +567,7 @@ export async function selectKeyStorage(ctx) {
         keychain = null;
     }
     if (keychain?.ok)
-        return { storage: "os_keychain", reason: "keychain_round_trip", repairs: [] };
+        return selected({ storage: "os_keychain", reason: "keychain_round_trip", repairs: [] });
     // 2. Setup's own gate. A failure here skips the key slot, not the external agent.
     let gate = null;
     if (platform !== "linux") {
@@ -435,7 +587,7 @@ export async function selectKeyStorage(ctx) {
                 gate = { reason: "bash_too_old", fix: "the keyslot scripts need bash >= 4 at /bin/bash; install a current bash, or use a desktop keychain" };
         }
     }
-    // 3. The key slot: provision.sh selects the mode; status.sh measures it.
+    // 3. The key slot: provision.sh selects the mode; status.sh measures it, in finalize.
     let slotRefusal = null;
     let repairs = [];
     if (gate === null) {
@@ -444,30 +596,21 @@ export async function selectKeyStorage(ctx) {
             dir = ctx.keyslotDir ?? resolveKeyslotDir();
         }
         catch {
-            return refused("keyslot_scripts_absent", "the packaged keyslot scripts are missing: reinstall @consiliency/agent-board-cli");
+            return selected(refused("keyslot_scripts_absent", "the packaged keyslot scripts are missing: reinstall @consiliency/agent-board-cli"));
         }
         const repaired = repairKeyDir(env, uid);
         repairs = repaired.repairs;
         if (repaired.problems.length > 0) {
-            return refused("unsafe_key_dir", `the key directory is not safe (${repaired.problems.join("; ")}): chmod g-w,o-w on each named directory you own (for a fresh account: chmod g-w ${repaired.root ?? "~/.config"} && chmod 0700 ${repaired.root ?? "~/.config"}/agent-board), then re-run setup`, repairs);
+            return selected(refused("unsafe_key_dir", `the key directory is not safe (${repaired.problems.join("; ")}): chmod g-w,o-w on each named directory you own (for a fresh account: chmod g-w ${repaired.root ?? "~/.config"} && chmod 0700 ${repaired.root ?? "~/.config"}/agent-board), then re-run setup`, repairs));
         }
         const args = ["--harness", ctx.harness, "--slot", slot, ...(ctx.allowUnsealedKey === true ? ["--allow-unsealed-key"] : [])];
         const provision = await run(join(dir, "provision.sh"), args, { env });
         if (provision.code === 0) {
             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;
-            }
-            catch {
-                mode = null;
-            }
-            if (mode === "sealed" || mode === "unsealed")
-                return { storage: mode, reason: `keyslot_${mode}`, keyReference: line, slot, 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);
+                return selected(refused("provision_output_unrecognised", "provision.sh exited 0 without printing an agent_socket: reference; run it by hand and report the output", repairs));
+            // #552: NO scan here. The slot is usable only after `finalizeKeyStorage` sees the one scan.
+            return { kind: "keyslot", harness: ctx.harness, slot, keyReference: line, repairs, keyslotDir: dir };
         }
         if (provision.code === 2) {
             slotRefusal = /incapable_for_keyslot/.test(provision.stderr)
@@ -478,12 +621,12 @@ export async function selectKeyStorage(ctx) {
         }
         else {
             const token = Object.keys(PROVISION_REFUSALS).find((name) => provision.stderr.includes(name));
-            return token
+            return selected(token
                 ? refused(token, PROVISION_REFUSALS[token], repairs)
-                : refused("provision_failed", "provision.sh failed: run the packaged provision.sh by hand and read what it reports", repairs);
+                : refused("provision_failed", "provision.sh failed: run the packaged provision.sh by hand and read what it reports", repairs));
         }
     }
     // 5. Refused, naming the fix.
     const cause = gate ?? slotRefusal ?? { reason: "no_key_storage", fix: "no key storage applies" };
-    return refused(cause.reason, withDeps(cause.fix, ctx.deps), repairs);
+    return selected(refused(cause.reason, withDeps(cause.fix, ctx.deps), repairs));
 }

package/dist/setup_writers.d.ts

@@ -89,6 +89,13 @@ export type ChildRunner = (file: string, args: readonly string[], options: {
 export declare const defaultChildRunner: ChildRunner;
 /** An executable named `name` on `env`'s PATH (never `process.env`'s), or null. */
 export declare function which(name: string, env: NodeJS.ProcessEnv): string | null;
+/**
+ * ONBOARD (IF-0-ONBOARD-1) — the harness presence probe, one rule for every identity harness: the
+ * harness's CLI, named as the harness, is on `env`'s PATH. The pi, opencode and claude writers
+ * need it to install; codex, grok and agy registrations are config files setup writes itself, so
+ * their writer does not require it, and `setup --all` is its only reader for those three.
+ */
+export declare function harnessCliPath(harness: IdentityHarness, env: NodeJS.ProcessEnv): string | null;
 export interface WriterContext {
     harness: IdentityHarness;
     scope: SetupScope;