@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/dist/setup.js

@@ -2,11 +2,13 @@ import * as nodeFs from "node:fs";
 import { hostname as osHostname } from "node:os";
 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 { IDENTITY_HARNESSES, acquireEnrollmentLock, createAgentBoardClient, displayableInviteLabel, enrollCommitMarker, formatPendingEnrollmentMarker, identityConfigRoot, identityFilePath, listHarnessProcesses, normalizeKeyReference, parseInviteInput, pendingEnrollmentMarkerExists, pendingEnrollmentMarkerPath, 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, finalizeKeyStorage, measureKeyStorage, repairKeyDir, keyslotSocketDir, prepareKeyStorage as defaultPrepareKeyStorage, } 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";
@@ -34,9 +36,6 @@ export function defaultSlug(host, harness) {
     const short = host.split(".")[0].toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
     return `${short || "host"}-${harness}`.slice(0, SLUG_MAX).replace(/-$/, "");
 }
-export function pendingMarkerPath(harness, env) {
-    return join(dirname(identityFilePath(harness, env)), `.setup-enroll-pending-${harness}`);
-}
 /**
  * Codes raised before any token exists (the issuer refused or the device code lapsed), so no
  * /enroll call can have happened: the marker is removed. Read through `authoredCode`, so only a
@@ -125,6 +124,7 @@ function defaultBoardClient(fileEnv) {
 class Run {
     steps = [];
     notes = [];
+    staleSessions = [];
     record(step, status, reason, fix) {
         const entry = { step, status, reason };
         this.steps.push(entry);
@@ -135,7 +135,7 @@ class Run {
     report() {
         const statuses = this.steps.map((step) => step.status);
         const exit = statuses.includes("failed") ? 1 : statuses.includes("undetermined") ? 2 : 0;
-        return { steps: this.steps, exit, notes: this.notes };
+        return { steps: this.steps, exit, notes: this.notes, staleSessions: this.staleSessions };
     }
 }
 /** The exact command a user runs to install the keychain tool on this host, or null. */
@@ -183,8 +183,76 @@ export async function depsStep(ctx) {
 // ---------------------------------------------------------------------------------------------
 // The run
 // ---------------------------------------------------------------------------------------------
-function inviteFromText(text) {
-    return text.trim();
+/** The most of an invite file setup reads: a rendered message is a few KiB. */
+const INVITE_FILE_MAX_BYTES = 65_536;
+/**
+ * IF-0-ONBOARD-2: the invite, read ONCE and parsed by the shared parser. `--invite-file` and a
+ * piped stdin may hold the whole invite message; a terminal takes one hidden line that must be a
+ * bare code. The code never reaches argv, a log or any message: a refusal names only its reason.
+ */
+export async function readSetupInvite(input, deps) {
+    const interactive = deps.interactive ?? process.stdin.isTTY === true;
+    if (input.invite === true && input.inviteFile !== undefined) {
+        return { reason: "invite_flags_conflict", fix: "pass --invite or --invite-file <path>, not both" };
+    }
+    let text;
+    let tty = false;
+    if (input.inviteFile !== undefined) {
+        try {
+            const fd = nodeFs.openSync(input.inviteFile, "r");
+            try {
+                const buffer = Buffer.alloc(INVITE_FILE_MAX_BYTES + 1);
+                const read = nodeFs.readSync(fd, buffer, 0, buffer.length, 0);
+                if (read > INVITE_FILE_MAX_BYTES)
+                    return { reason: "invite_file_too_large", fix: `--invite-file holds more than ${INVITE_FILE_MAX_BYTES} bytes: save only the invite message to it` };
+                text = buffer.subarray(0, read).toString("utf8");
+            }
+            finally {
+                nodeFs.closeSync(fd);
+            }
+        }
+        catch {
+            return { reason: "invite_file_unreadable", fix: "--invite-file names a file setup cannot read: save the invite message to a file you can read and pass its path" };
+        }
+    }
+    else if (input.invite === true) {
+        tty = interactive;
+        text = interactive ? await (deps.prompt ?? defaultPrompt)("Invite code (hidden): ", { secret: true }) : await (deps.readStdin ?? defaultReadStdin)();
+    }
+    else {
+        return { invite: null };
+    }
+    if (text.trim() === "") {
+        return { reason: "invite_missing", fix: "--invite reads the code from the terminal or stdin, and --invite-file from a file; none was given" };
+    }
+    try {
+        return { invite: parseInviteInput(text, { tty }) };
+    }
+    catch (error) {
+        // The parser's messages carry no byte of the input (IF-0-ONBOARD-7).
+        return { reason: authoredCode(error, "invite_unsupported_form"), fix: String(error?.message ?? "the invite could not be read") };
+    }
+}
+/** A label from the message, printable: control characters (an escape sequence, say) removed. */
+const printable = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+/** IF-0-ONBOARD-2 "Board": reported, never checked (setup has no target board). Never the code. */
+export function inviteBoardNote(invite) {
+    // The client's display rule, which re-checks the FINAL text for the code (the parser's own check
+    // is not relied on alone).
+    const label = displayableInviteLabel(invite);
+    if (label !== null)
+        return `preflight: the invite is for board "${label}" (as the invite message says; the redeem names the board joined)`;
+    if (invite.labelSuppressed || invite.boardLabel !== null)
+        return "preflight: the invite's board label contains its code, so it is not shown; the redeem names the board joined";
+    return "preflight: the invite names no board; the redeem names the board joined";
+}
+/**
+ * The redeem RPC's one uniform refusal (`42501 invite is not usable`) covers exhausted, revoked,
+ * expired, creator-suspended, ceiling and per-agent refusals ALIKE, and setup never tells them apart
+ * (IF-0-ONBOARD-1): every one is `invite_unusable`. Anything else keeps the authored code.
+ */
+function redeemRefusal(error) {
+    return error?.code === "42501" ? "invite_unusable" : authoredCode(error, "invite_redeem_failed");
 }
 /** The keyslot a key reference's socket names, when it is one of `$XDG_RUNTIME_DIR/agent-board/<slot>.sock`. */
 function keyslotOf(reference, env) {
@@ -206,7 +274,16 @@ function keyslotOf(reference, env) {
     // Only a name the keyslot scripts accept ever reaches their argv.
     return SLOT_RE.test(slot) ? slot : null;
 }
-export async function runSetup(options, deps = {}) {
+/** The storage context the key step's scan reads (env, runner, budgets, notices). */
+export function setupStorageContext(deps) {
+    return { env: deps.env ?? process.env, ...deps.storage };
+}
+/**
+ * Preflight, deps and the key PREPARATION for one harness. `preset.invite` is an invite the caller
+ * already read and parsed (`setup --all` reads it once for every pair); without it, the invite is
+ * read here.
+ */
+export async function startSetupPair(options, deps = {}, preset) {
     const env = deps.env ?? process.env;
     const cwd = deps.cwd ?? process.cwd();
     const platform = deps.platform ?? process.platform;
@@ -214,51 +291,72 @@ export async function runSetup(options, deps = {}) {
     const prompt = deps.prompt ?? defaultPrompt;
     const run = deps.run ?? defaultChildRunner;
     const out = new Run();
+    const stopped = () => ({ kind: "stopped", report: out.report() });
     // ---- preflight --------------------------------------------------------------------------
     const harness = options.harness;
     if (!IDENTITY_HARNESSES.includes(harness)) {
         out.record("preflight", "failed", "harness_invalid", `--harness must be one of ${IDENTITY_HARNESSES.join(", ")}`);
-        return out.report();
+        return stopped();
     }
     const h = harness;
     let markerPath;
     let identityPath;
     try {
         identityPath = identityFilePath(h, env);
-        markerPath = pendingMarkerPath(h, env);
+        markerPath = pendingEnrollmentMarkerPath(h, env);
     }
     catch (error) {
         out.record("preflight", "failed", authoredCode(error, "identity_path_invalid"), "the identity file's path needs an absolute HOME/XDG_CONFIG_HOME and a valid host name (or MESSAGE_BOARD_WAKE_MACHINE_ID)");
-        return out.report();
+        return stopped();
     }
     if (options.clearPending) {
-        // Runs no step: only this harness's marker, only with no identity file.
-        if (exists(identityPath)) {
-            out.record("clear_pending", "failed", "identity_present", `${h} has an identity file, so its enrollment is not pending; nothing was removed`);
+        // Runs no step: only this harness's marker, only with no identity file, and only under the
+        // enrollment lock. A marker whose enrollment is STILL RUNNING (a setup waiting on the device
+        // approval, or an in-chat sign-in) is live: the Portal shows nothing yet, and deleting it would
+        // leave a lost /enroll response with no record (phase review NEW-1). Such an enrollment holds
+        // the lock, so a held lock refuses and nothing is removed.
+        let lock;
+        try {
+            lock = await acquireEnrollmentLock(h, env);
         }
-        else if (exists(markerPath)) {
-            nodeFs.unlinkSync(markerPath);
-            out.record("clear_pending", "done", "marker_removed");
+        catch (error) {
+            const code = authoredCode(error, "enroll_lock_failed");
+            out.record("clear_pending", "failed", code, code === "enroll_in_progress"
+                ? `an enrollment of ${h} is running on this host right now (a setup waiting for approval, or an in-chat sign-in), so its marker is live and nothing was removed: finish or abandon that enrollment first`
+                : `setup could not take ${h}'s enrollment lock in its identity directory, so nothing was removed: run \`agent-board doctor --harness ${h}\` and fix what it names`);
+            return stopped();
         }
-        else {
-            out.record("clear_pending", "already", "no_marker");
+        try {
+            if (exists(identityPath)) {
+                out.record("clear_pending", "failed", "identity_present", `${h} has an identity file, so its enrollment is not pending; nothing was removed`);
+            }
+            else if (pendingEnrollmentMarkerExists(h, env)) {
+                nodeFs.unlinkSync(markerPath);
+                out.record("clear_pending", "done", "marker_removed");
+            }
+            else {
+                out.record("clear_pending", "already", "no_marker");
+            }
         }
-        return out.report();
+        finally {
+            await lock.release();
+        }
+        return stopped();
     }
     const scope = (options.scope ?? "user");
     if (!SETUP_SCOPES.includes(scope)) {
         out.record("preflight", "failed", "scope_invalid", "--scope is user or local");
-        return out.report();
+        return stopped();
     }
     const refusal = scopeRefusal(h, scope, { env, cwd, fs: deps.writer?.fs, claudeManagedDir: deps.writer?.claudeManagedDir });
     if (refusal) {
         out.record("preflight", "failed", refusal.reason, refusal.fix);
-        return out.report();
+        return stopped();
     }
     const slug = options.slug ?? defaultSlug(resolveHostSegment(env) ?? (deps.hostname ?? osHostname)(), h);
     if (!SLUG.test(slug) || slug.length > SLUG_MAX) {
         out.record("preflight", "failed", "slug_invalid", `--slug must match ^[a-z0-9]+(-[a-z0-9]+)*$ and be at most ${SLUG_MAX} characters`);
-        return out.report();
+        return stopped();
     }
     let assets;
     try {
@@ -266,16 +364,18 @@ export async function runSetup(options, deps = {}) {
     }
     catch {
         out.record("preflight", "failed", "assets_unbaked", "this cli build has no baked versions (dist/assets.json): reinstall @consiliency/agent-board-cli");
-        return out.report();
+        return stopped();
     }
     const identity = await identityState(h, env);
     if (identity.kind === "unreadable") {
         out.record("preflight", "failed", identity.reason, `a ${h} identity file EXISTS but cannot be read safely (its directory or the file is not private to you, or it does not parse): run \`agent-board doctor --harness ${h}\` and fix what it names; setup never enrolls over an existing identity (the Portal token is single-use)`);
-        return out.report();
+        return stopped();
     }
-    if (identity.kind === "absent" && exists(markerPath)) {
+    // IF-0-ONBOARD-9: the marker's EXISTENCE decides, whatever it holds (the in-chat form adds a
+    // `key_ref=` line; setup never reads it).
+    if (identity.kind === "absent" && pendingEnrollmentMarkerExists(h, env)) {
         out.record("preflight", "failed", "enrolled_without_identity", `an earlier setup started enrolling ${h} and did not write its identity file, so an agent MAY exist in the Portal. Check the Portal: if no agent was created, run \`agent-board setup --harness ${h} --clear-pending\` and re-run setup; if one was, revoke it first`);
-        return out.report();
+        return stopped();
     }
     let deployment = null;
     if (identity.kind === "absent") {
@@ -289,23 +389,27 @@ export async function runSetup(options, deps = {}) {
             const descriptor = resolveEnrollmentDescriptor(env, { keyReference: PREFLIGHT_KEY_REFERENCE });
             if (!descriptor.issuer.deviceAuthorizationEndpoint) {
                 out.record("preflight", "failed", "missing_device_endpoint", "the deployment has no device authorization endpoint (MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT)");
-                return out.report();
+                return stopped();
             }
         }
         catch (error) {
             out.record("preflight", "failed", authoredCode(error, "enrollment_config_invalid"), "the deployment values are incomplete: unset the partial MESSAGE_BOARD_ENROLL_* / AGENT_BOARD_* names to use the shipped defaults, or set all of them");
-            return out.report();
+            return stopped();
         }
     }
-    let invite = null;
-    if (options.invite) {
-        invite = interactive
-            ? inviteFromText(await prompt("Invite code (hidden): ", { secret: true }))
-            : inviteFromText(await (deps.readStdin ?? defaultReadStdin)());
-        if (invite === "") {
-            out.record("preflight", "failed", "invite_missing", "--invite reads the code from the terminal or stdin; none was given");
-            return out.report();
+    let invite;
+    if (preset) {
+        invite = preset.invite;
+    }
+    else {
+        const read = await readSetupInvite(options, deps);
+        if (!("invite" in read)) {
+            out.record("preflight", "failed", read.reason, read.fix);
+            return stopped();
         }
+        invite = read.invite;
+        if (invite !== null)
+            out.notes.push(inviteBoardNote(invite));
     }
     out.record("preflight", "done", "ready");
     // ---- deps -------------------------------------------------------------------------------
@@ -317,8 +421,43 @@ export async function runSetup(options, deps = {}) {
             ? { status: "skipped", reason: "agent_socket_given" }
             : await depsStep({ env, platform, interactive, installDeps: options.installDeps === true, run, sudo: deps.sudoPath ?? DEFAULT_SUDO, prompt });
     out.record("deps", deps_.status, deps_.reason, deps_.fix);
+    // ---- key (preparation) --------------------------------------------------------------------
+    const state = { out, options, deps, env, cwd, scope, assets, identity, deployment, invite, identityPath, markerPath };
+    if (identity.kind === "present")
+        return { kind: "started", pair: { harness: h, slug, prepared: null, state } };
+    // #536 as a named step, for EVERY storage: the identity file needs a private agent-board/ too,
+    // and the keychain route never reaches the key slot's own repair.
+    const repaired = repairKeyDir(env, deps.storage?.uid ?? (typeof process.getuid === "function" ? process.getuid() : -1));
+    for (const repair of repaired.repairs)
+        out.notes.push(`key: repaired ${repair}`);
+    if (repaired.problems.length > 0) {
+        out.record("key", "failed", "unsafe_key_dir", `the key directory is not safe (${repaired.problems.join("; ")}): make each named directory yours (or root's) and not group/other-writable, then re-run setup`);
+        return stopped();
+    }
+    const ctx = {
+        harness: h, env, platform, deps: deps_,
+        ...(options.allowUnsealedKey === true ? { allowUnsealedKey: true } : {}),
+        ...(options.agentSocket !== undefined ? { agentSocket: options.agentSocket } : {}),
+        ...deps.storage,
+    };
+    // A caller that injects a whole selector gets it as a final selection (it did its own scan).
+    const prepared = deps.selectKeyStorage
+        ? { kind: "selected", harness: h, selection: await deps.selectKeyStorage(ctx) }
+        : await (deps.prepareKeyStorage ?? defaultPrepareKeyStorage)(ctx);
+    return { kind: "started", pair: { harness: h, slug, prepared, state } };
+}
+/**
+ * The rest of one pair, from its FINAL key storage (`finalizeKeyStorage`'s answer for this pair;
+ * null for a pair whose identity exists): enroll, identity, board, harness, doctor.
+ */
+export async function finishSetupPair(pair, selection) {
+    const { out, options, deps, env, cwd, scope, assets, identity, deployment, invite, identityPath, markerPath } = pair.state;
+    const h = pair.harness;
+    const slug = pair.slug;
+    const run = deps.run ?? defaultChildRunner;
     // ---- key --------------------------------------------------------------------------------
     let keyReference;
+    let keyScan;
     if (identity.kind === "present") {
         keyReference = identity.values.AGENT_BOARD_AGENT_KEY_REFERENCE;
         const slot = keyslotOf(keyReference, env);
@@ -333,27 +472,27 @@ export async function runSetup(options, deps = {}) {
         }
     }
     else {
-        // #536 as a named step, for EVERY storage: the identity file needs a private agent-board/ too,
-        // and the keychain route never reaches the key slot's own repair.
-        const repaired = repairKeyDir(env, deps.storage?.uid ?? (typeof process.getuid === "function" ? process.getuid() : -1));
-        for (const repair of repaired.repairs)
-            out.notes.push(`key: repaired ${repair}`);
-        if (repaired.problems.length > 0) {
-            out.record("key", "failed", "unsafe_key_dir", `the key directory is not safe (${repaired.problems.join("; ")}): make each named directory yours (or root's) and not group/other-writable, then re-run setup`);
+        if (selection === null) {
+            out.record("key", "failed", "scan_not_completed", "no key storage was finalized for this harness, so it is NOT enrolled: re-run setup");
             return out.report();
         }
-        const selection = await (deps.selectKeyStorage ?? defaultSelectKeyStorage)({
-            harness: h, env, platform, deps: deps_,
-            ...(options.allowUnsealedKey === true ? { allowUnsealedKey: true } : {}),
-            ...(options.agentSocket !== undefined ? { agentSocket: options.agentSocket } : {}),
-            ...deps.storage,
-        });
         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}`;
         }
@@ -389,7 +528,57 @@ export async function runSetup(options, deps = {}) {
             const root = join(identityConfigRoot(env), "agent-board");
             nodeFs.mkdirSync(dirname(identityPath), { recursive: true, mode: 0o700 });
             walkTrustedDirectory(dirname(identityPath), root);
-            await writeOwnerOnlyFile(markerPath, `${new Date().toISOString()}\n`);
+        }
+        catch (error) {
+            out.record("enroll", "failed", authoredCode(error, "identity_path_untrusted"), "the identity directory is not private to you: $XDG_CONFIG_HOME (or ~/.config) and agent-board/ beneath it must be yours, not group/world-writable");
+            return out.report();
+        }
+        // The (host, harness) enrollment lock the MCP in-chat enrollment holds for ITS whole sign-in
+        // (IF-0-ONBOARD-9), held here from before the marker until after the identity write and the
+        // marker clear. Preflight's identity and marker reads are stale by now: an in-chat enrollment
+        // may have finished (or started) since, so both are read AGAIN under the lock (phase review,
+        // codex P1: setup overwrote an identity chat enrollment had just written).
+        let lock;
+        try {
+            lock = await acquireEnrollmentLock(h, env);
+        }
+        catch (error) {
+            const code = authoredCode(error, "enroll_lock_failed");
+            out.record("enroll", "failed", code, code === "enroll_in_progress"
+                ? `another ${h} session on this host is enrolling right now (an in-chat sign-in, or another setup): finish or abandon it, then re-run setup; nothing was enrolled or written here`
+                : "setup could not take this harness's enrollment lock in its identity directory: run `agent-board doctor --harness " + h + "` and fix what it names, then re-run setup");
+            return out.report();
+        }
+        try {
+            const enrolled = await enrollUnderLock();
+            if (enrolled !== null)
+                return enrolled;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    /** The enrollment proper, with the lock held. null = continue to the board step. */
+    async function enrollUnderLock() {
+        const current = await identityState(h, env);
+        if (current.kind === "present") {
+            // Enrolled by someone else since preflight: never enroll over it, never overwrite it.
+            out.record("enroll", "already", "identity_present");
+            out.record("identity", "already", "identity_present");
+            out.notes.push(`enroll: ${h} was enrolled by another session (an in-chat enrollment) after setup started; its identity file is kept, and the key setup prepared is not used`);
+            keyScan = undefined;
+            return null;
+        }
+        if (current.kind === "unreadable") {
+            out.record("enroll", "failed", current.reason, `a ${h} identity file appeared after setup started and cannot be read safely: run \`agent-board doctor --harness ${h}\`; nothing was enrolled`);
+            return out.report();
+        }
+        if (pendingEnrollmentMarkerExists(h, env)) {
+            out.record("enroll", "failed", "enrolled_without_identity", `an enrollment of ${h} started after setup did (a pending-enrollment marker appeared), so an agent MAY exist in the Portal. Check the Portal: if no agent was created, run \`agent-board setup --harness ${h} --clear-pending\` and re-run setup; if one was, revoke it first`);
+            return out.report();
+        }
+        try {
+            await writeOwnerOnlyFile(markerPath, formatPendingEnrollmentMarker(new Date()));
         }
         catch (error) {
             out.record("enroll", "failed", authoredCode(error, "identity_path_untrusted"), "the identity directory is not private to you: $XDG_CONFIG_HOME (or ~/.config) and agent-board/ beneath it must be yours, not group/world-writable");
@@ -440,6 +629,7 @@ export async function runSetup(options, deps = {}) {
         }
         nodeFs.rmSync(markerPath, { force: true });
         out.record("identity", "done", "written");
+        return null;
     }
     // ---- board ------------------------------------------------------------------------------
     // Always the identity file just written, never ambient env: the invite is single-use.
@@ -456,17 +646,26 @@ export async function runSetup(options, deps = {}) {
     }
     else {
         try {
-            const result = await (deps.createBoardClient ?? defaultBoardClient)(fileEnv).redeemInviteLink({ p_code: invite });
+            const result = await (deps.createBoardClient ?? defaultBoardClient)(fileEnv).redeemInviteLink({ p_code: invite.code });
             if (result?.ok === false)
                 throw result;
             out.record("board", "done", "joined");
+            // IF-0-ONBOARD-2 "Board": the redeem result names the board actually joined.
+            const joined = result?.data?.[0]?.board_id;
+            if (typeof joined === "string")
+                out.notes.push(`board: joined board ${printable(joined)}`);
         }
         catch (error) {
-            out.record("board", "failed", authoredCode(error, "invite_redeem_failed"), "the invite was not redeemed: ask the board owner for a fresh invite, then `agent-board --as " + h + " rooms link-redeem` (code on stdin)");
+            const reason = redeemRefusal(error);
+            out.record("board", "failed", reason, reason === "invite_unusable"
+                ? `the board refused the invite for this agent (used up, revoked, expired, or not usable by this agent: the board does not say which): ask the board owner for a new invite, then \`agent-board --as ${h} rooms link-redeem\` (the invite on stdin)`
+                : "the invite was not redeemed: ask the board owner for a fresh invite, then `agent-board --as " + h + " rooms link-redeem` (code on stdin)");
             return out.report();
         }
     }
     // ---- harness ----------------------------------------------------------------------------
+    // The install's start: a running harness that started before it does not load what it wrote.
+    const installStartedAt = new Date();
     const installed = await installHarness({
         harness: h, scope, assets, env, cwd, keyReference: written.values.AGENT_BOARD_AGENT_KEY_REFERENCE ?? null, followSymlinks: options.followSymlinks !== false, run,
         ...deps.writer,
@@ -474,10 +673,23 @@ export async function runSetup(options, deps = {}) {
     out.record("harness", installed.status, installed.reason, installed.fix);
     if (installed.status === "failed")
         return out.report();
+    if (installed.status === "done") {
+        // IF-0-ONBOARD-3: found by EXECUTABLE (#474 launcher rules), not through runtime records: a
+        // session with no board plugin writes no record, and it is the one that most needs a restart.
+        for (const stale of listHarnessProcesses(h, { startedBefore: installStartedAt, ...deps.processes })) {
+            out.staleSessions.push({ pid: stale.pid, startedAt: stale.startedAt.toISOString(), cwd: stale.cwd });
+            out.notes.push(`harness: restart the ${h} session pid ${stale.pid} (started ${stale.startedAt.toISOString()}${stale.cwd === null ? "" : `, in ${printable(stale.cwd)}`}): it started before this install and has not loaded it`);
+        }
+    }
     // ---- 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"));
@@ -523,13 +735,25 @@ export async function runSetup(options, deps = {}) {
         out.notes.push(`next: to join a board, ask its owner for an invite link, then run \`agent-board --as ${h} rooms link-redeem\` with the code on stdin`);
     return out.report();
 }
+/**
+ * One harness: start, the key step's one scan (prepare → measure → finalize, as `setup --all` does
+ * over every pair), then the rest.
+ */
+export async function runSetup(options, deps = {}) {
+    const start = await startSetupPair(options, deps);
+    if (start.kind === "stopped")
+        return start.report;
+    const { prepared } = start.pair;
+    const selection = prepared === null ? null : finalizeKeyStorage([prepared], await measureKeyStorage([prepared], setupStorageContext(deps)))[0];
+    return finishSetupPair(start.pair, selection);
+}
 /**
  * The keyslot loader refresh (A1): `status.sh` names the recorded and the running loader version;
  * when they differ, `provision.sh --refresh-loader` (which never re-keys) points the slot at the
  * 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 +761,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,29 +780,81 @@ 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");
 }
-export function addSetupCommand(program, io, setup) {
+const collect = (value, previous = []) => [...previous, value];
+export function addSetupCommand(program, io, setup, setupAll) {
     program
         .command("setup")
-        .description("set this host up for one harness: key storage, enrollment, identity file, optional board invite, harness registration, then doctor")
+        .description("set this host up for one harness (--harness) or every harness on it (--all): key storage, enrollment, identity file, optional board invite, harness registration, then doctor")
         // Not `requiredOption`: commander's own usage exit would bypass the report (#402).
         .option("--harness <harness>", "the harness to set up (agy, claude, codex, grok, opencode, pi)")
-        .option("--slug <slug>", "the agent slug (default <short hostname>-<harness>)")
-        .option("--invite", "read a board invite code from the terminal or stdin (never argv) and redeem it after enrolling")
+        .option("--all", "set up every harness whose CLI is on PATH, with one invite read and at most one key scan")
+        .option("--slug <slug>", "the agent slug (default <short hostname>-<harness>); with --all, <harness>=<slug>, repeatable", collect)
+        .option("--invite", "read a board invite (a bare code on a terminal; the code or the whole invite message on stdin) and redeem it after enrolling; never argv")
+        .option("--invite-file <path>", "read the board invite (the code, or the whole invite message) from a file and redeem it after enrolling")
         .option("--allow-unsealed-key", "accept an unsealed 0600 key under an opt-in record on a host that cannot seal")
-        .option("--agent-socket <ref>", "use your own SSH agent (with an external-agent declaration)")
+        .option("--agent-socket <ref>", "use your own SSH agent (with an external-agent declaration); refused with --all")
         .option("--scope <scope>", "user (default) or local (this directory)")
         .option("--install-deps", "non-interactive: install the OS keychain tool with sudo -n when a Secret Service is running")
-        .option("--clear-pending", "remove this harness's pending-enrollment marker after confirming in the Portal that no agent was created; runs no step")
+        .option("--clear-pending", "remove this harness's pending-enrollment marker after confirming in the Portal that no agent was created; runs no step; refused with --all")
         .option("--no-follow-symlinks", "refuse to write through a symlinked harness config")
         .option("--json", "print the steps and exit code as JSON")
         .action(async (options) => {
+        const slugs = options.slug ?? [];
+        if (options.all === true && setupAll) {
+            process.exitCode = await setupAll({
+                ...(options.harness !== undefined ? { harness: String(options.harness) } : {}),
+                slugs,
+                invite: options.invite === true,
+                ...(options.inviteFile !== undefined ? { inviteFile: String(options.inviteFile) } : {}),
+                allowUnsealedKey: options.allowUnsealedKey === true,
+                ...(options.agentSocket !== undefined ? { agentSocket: options.agentSocket } : {}),
+                scope: options.scope,
+                installDeps: options.installDeps === true,
+                clearPending: options.clearPending === true,
+                followSymlinks: options.followSymlinks !== false,
+            }, { json: options.json === true });
+            return;
+        }
         const report = await setup({
             harness: String(options.harness ?? ""),
-            slug: options.slug,
+            // Without --all, --slug keeps its single-value form: the last one given, as before.
+            slug: slugs.at(-1),
             invite: options.invite === true,
+            ...(options.inviteFile !== undefined ? { inviteFile: String(options.inviteFile) } : {}),
             allowUnsealedKey: options.allowUnsealedKey === true,
             agentSocket: options.agentSocket,
             scope: options.scope,