@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/dist/setup.js

@@ -0,0 +1,603 @@
+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 { bakedAssets as defaultBakedAssets, resolveKeyslotDir } from "./assets.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 { 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";
+export const SECRET_SERVICE_NAME = "org.freedesktop.secrets";
+/** `busctl --user call … NameHasOwner`: asks the BUS whether the name is owned; never calls the service. */
+export const NAME_HAS_OWNER_ARGS = Object.freeze(["--user", "call", "org.freedesktop.DBus", "/", "org.freedesktop.DBus", "NameHasOwner", "s", SECRET_SERVICE_NAME]);
+/**
+ * The keychain tool's install, one complete argv per package manager, first found wins. Each
+ * package name was re-checked against the distro's own index (throwaway containers, 2026-09-27):
+ * ubuntu 24.04 `libsecret-tools` ships ./usr/bin/secret-tool; fedora 44 `dnf repoquery
+ * --whatprovides /usr/bin/secret-tool` → libsecret; arch `pacman -F usr/bin/secret-tool` →
+ * core/libsecret; opensuse tumbleweed `zypper se --provides /usr/bin/secret-tool` → secret-tool
+ * (NOT libsecret-tools, which the plan text named).
+ */
+export const KEYCHAIN_INSTALL_ARGV = Object.freeze([
+    { manager: "apt-get", argv: Object.freeze(["apt-get", "install", "-y", "libsecret-tools"]) },
+    { manager: "dnf", argv: Object.freeze(["dnf", "install", "-y", "libsecret"]) },
+    { manager: "pacman", argv: Object.freeze(["pacman", "-S", "--needed", "--noconfirm", "libsecret"]) },
+    { manager: "zypper", argv: Object.freeze(["zypper", "--non-interactive", "install", "secret-tool"]) },
+]);
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_MAX = 63;
+/** `<short hostname>-<harness>`, lowercased to `[a-z0-9-]`. */
+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
+ * code this repository minted counts.
+ */
+const PRE_COMMIT_ENROLL_CODES = new Set(["device_code_expired", "device_token_failed", "device_poll_exhausted"]);
+/**
+ * Deployment-config refusals: every one is raised while the runner resolves its configuration,
+ * before any request, so nothing can have committed. Preflight resolves the same configuration
+ * first; this set is the backstop for a runner that resolves something preflight did not.
+ */
+const CONFIG_RESOLUTION_CODES = new Set([
+    "missing_enroll_endpoint", "missing_enrollment_field", "missing_client_identity", "missing_device_endpoint",
+    "missing_board_url", "unsupported_generation_target", "agent_socket_no_generation", "identity_incomplete", "identity_secret_value",
+]);
+/** A key reference of the right shape for preflight's descriptor check; the key step supplies the real one. */
+const PREFLIGHT_KEY_REFERENCE = "os_keychain:agent-board/preflight/check";
+/** The DB's refusal of a taken slug, surfaced by /enroll as a 403 detail (foreign text, matched only). */
+const SLUG_TAKEN_DETAIL = /already bound to a different identity/;
+async function identityState(harness, env) {
+    // Existence first, by lstat alone: a directory the key step will repair (#536: a user-owned
+    // 0755 agent-board/) must not stop a host that has NO identity yet. Only an identity that EXISTS
+    // is read through the trusted open, and refused when that open refuses.
+    try {
+        nodeFs.lstatSync(identityFilePath(harness, env));
+    }
+    catch (error) {
+        const errno = error.code;
+        if (errno === "ENOENT" || errno === "ENOTDIR")
+            return { kind: "absent" };
+    }
+    try {
+        return { kind: "present", values: (await readIdentityFile({ harness, env })).values };
+    }
+    catch (error) {
+        const code = authoredCode(error, "identity_unreadable");
+        return code === "identity_absent" ? { kind: "absent" } : { kind: "unreadable", reason: code };
+    }
+}
+const exists = (path) => {
+    try {
+        nodeFs.lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+function defaultPrompt(question, options) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        if (options.secret) {
+            const writer = rl;
+            process.stderr.write(question);
+            writer._writeToOutput = () => { };
+            rl.question("", (answer) => { rl.close(); process.stderr.write("\n"); resolve(answer); });
+        }
+        else {
+            rl.question(question, (answer) => { rl.close(); resolve(answer); });
+        }
+    });
+}
+function defaultReadStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+function renderDevicePrompt(prompt) {
+    return [
+        "",
+        "=== Approve this agent in the Portal (device authorization) ===",
+        `  1. Open:  ${prompt.verificationUri}`,
+        `  2. Enter code:  ${prompt.userCode}`,
+        ...(prompt.verificationUriComplete ? [`  (or open ${prompt.verificationUriComplete})`] : []),
+        "",
+    ].join("\n");
+}
+function defaultBoardClient(fileEnv) {
+    const client = createAgentBoardClient({ resolveCredentials: () => resolveCredentials(undefined, fileEnv) });
+    return { redeemInviteLink: (input) => client.redeemInviteLink(input) };
+}
+class Run {
+    steps = [];
+    notes = [];
+    record(step, status, reason, fix) {
+        const entry = { step, status, reason };
+        this.steps.push(entry);
+        if (fix)
+            this.notes.push(`${step}: ${fix}`);
+        return entry;
+    }
+    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 };
+    }
+}
+/** The exact command a user runs to install the keychain tool on this host, or null. */
+function installArgv(env) {
+    return KEYCHAIN_INSTALL_ARGV.find((entry) => which(entry.manager, env) !== null)?.argv ?? null;
+}
+export async function depsStep(ctx) {
+    if (ctx.platform === "darwin")
+        return { status: "already", reason: "macos_security_builtin" };
+    if (ctx.platform !== "linux")
+        return { status: "skipped", reason: "platform_unsupported" };
+    // Detection first, and it starts nothing: only a name ALREADY owned on the session bus counts.
+    const busctl = which("busctl", ctx.env);
+    const owner = busctl === null ? null : await ctx.run(busctl, NAME_HAS_OWNER_ARGS, { env: ctx.env });
+    // busctl exits 0 for `b false` too: the reply is parsed, and only exactly `b true` counts.
+    const owned = owner !== null && owner.code === 0 && owner.stdout.replace(/\n$/, "") === "b true";
+    if (!owned)
+        return { status: "skipped", reason: "no_secret_service" };
+    if (which("secret-tool", ctx.env) !== null)
+        return { status: "already", reason: "secret_tool_present" };
+    const argv = installArgv(ctx.env);
+    if (argv === null)
+        return { status: "skipped", reason: "deps_no_package_manager", fix: "install the package that provides secret-tool with your package manager, then re-run setup" };
+    const command = `sudo -- ${argv.join(" ")}`;
+    let nonInteractive = false;
+    if (ctx.interactive) {
+        const answer = (await ctx.prompt(`The OS keychain needs secret-tool. Install it now with \`${command}\`? [y/N] `, { secret: false })).trim();
+        // Default No: this answer is the approval, since cached sudo credentials may never prompt.
+        if (!/^y(es)?$/i.test(answer))
+            return { status: "skipped", reason: "deps_declined", installCommand: command, fix: `run \`${command}\`, then re-run setup` };
+    }
+    else if (ctx.installDeps) {
+        nonInteractive = true;
+    }
+    else {
+        return { status: "skipped", reason: "deps_not_installed", installCommand: command, fix: `run \`${command}\` (or re-run setup with --install-deps), then re-run setup` };
+    }
+    const sudoArgs = nonInteractive ? ["-n", "--", ...argv] : ["--", ...argv];
+    const result = await ctx.run(ctx.sudo, sudoArgs, { env: ctx.env });
+    if (result.code !== 0 || which("secret-tool", ctx.env) === null) {
+        return { status: "skipped", reason: "deps_install_failed", installCommand: command, fix: `the install failed (a package index never updated on a fresh host is common: sudo apt-get update first); run \`${command}\` yourself, then re-run setup` };
+    }
+    return { status: "done", reason: "secret_tool_installed" };
+}
+// ---------------------------------------------------------------------------------------------
+// The run
+// ---------------------------------------------------------------------------------------------
+function inviteFromText(text) {
+    return text.trim();
+}
+/** The keyslot a key reference's socket names, when it is one of `$XDG_RUNTIME_DIR/agent-board/<slot>.sock`. */
+function keyslotOf(reference, env) {
+    let handle;
+    try {
+        const normalized = normalizeKeyReference(reference);
+        if (normalized.resolver !== "agent_socket")
+            return null;
+        handle = String(normalized.handle);
+    }
+    catch {
+        return null;
+    }
+    const socket = handle.split("#")[0];
+    const dir = keyslotSocketDir(env);
+    if (!dir || dirname(socket) !== dir || !socket.endsWith(".sock"))
+        return null;
+    const slot = socket.slice(dir.length + 1, -".sock".length);
+    // Only a name the keyslot scripts accept ever reaches their argv.
+    return SLOT_RE.test(slot) ? slot : null;
+}
+export async function runSetup(options, deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const platform = deps.platform ?? process.platform;
+    const interactive = deps.interactive ?? process.stdin.isTTY === true;
+    const prompt = deps.prompt ?? defaultPrompt;
+    const run = deps.run ?? defaultChildRunner;
+    const out = new Run();
+    // ---- 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();
+    }
+    const h = harness;
+    let markerPath;
+    let identityPath;
+    try {
+        identityPath = identityFilePath(h, env);
+        markerPath = pendingMarkerPath(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();
+    }
+    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`);
+        }
+        else if (exists(markerPath)) {
+            nodeFs.unlinkSync(markerPath);
+            out.record("clear_pending", "done", "marker_removed");
+        }
+        else {
+            out.record("clear_pending", "already", "no_marker");
+        }
+        return out.report();
+    }
+    const scope = (options.scope ?? "user");
+    if (!SETUP_SCOPES.includes(scope)) {
+        out.record("preflight", "failed", "scope_invalid", "--scope is user or local");
+        return out.report();
+    }
+    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();
+    }
+    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();
+    }
+    let assets;
+    try {
+        assets = (deps.bakedAssets ?? defaultBakedAssets)();
+    }
+    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();
+    }
+    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();
+    }
+    if (identity.kind === "absent" && exists(markerPath)) {
+        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();
+    }
+    let deployment = null;
+    if (identity.kind === "absent") {
+        // The WHOLE deployment the enrollment will read — the board group (identity values and the
+        // enroll endpoint) and the issuer group — resolved here, before deps, key and the marker, so an
+        // incomplete env (an operator shell with an identity but no enroll endpoint, say) refuses
+        // while nothing has run and nothing can have been sent.
+        try {
+            deployment = resolveIdentityDeployment(env);
+            resolveEnrollEndpoint(env);
+            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();
+            }
+        }
+        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();
+        }
+    }
+    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();
+        }
+    }
+    out.record("preflight", "done", "ready");
+    // ---- deps -------------------------------------------------------------------------------
+    // With an identity the key is already stored: nothing to install, and no prompt for nothing.
+    // With --agent-socket the user named their own agent, which wins over the keychain: nothing to offer.
+    const deps_ = identity.kind === "present"
+        ? { status: "skipped", reason: "identity_present" }
+        : options.agentSocket !== undefined
+            ? { 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 --------------------------------------------------------------------------------
+    let keyReference;
+    if (identity.kind === "present") {
+        keyReference = identity.values.AGENT_BOARD_AGENT_KEY_REFERENCE;
+        const slot = keyslotOf(keyReference, env);
+        if (slot === null) {
+            out.record("key", "already", "identity_present");
+        }
+        else {
+            const loader = await refreshLoader(h, slot, env, deps);
+            out.record("key", loader.status, loader.reason, loader.fix);
+            if (loader.status === "failed")
+                return out.report();
+        }
+    }
+    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`);
+            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);
+            return out.report();
+        }
+        if (selection.storage === "os_keychain") {
+            keyReference = `os_keychain:agent-board/${resolveHostSegment(env) ?? slug}/${h}`;
+        }
+        else if (selection.keyReference) {
+            keyReference = selection.keyReference;
+        }
+        else {
+            out.record("key", "failed", "key_reference_missing", "the key storage named no reference");
+            return out.report();
+        }
+        out.record("key", "done", selection.reason);
+    }
+    // ---- enroll + identity --------------------------------------------------------------------
+    if (identity.kind === "present") {
+        out.record("enroll", "already", "identity_present");
+        out.record("identity", "already", "identity_present");
+    }
+    else {
+        // The descriptor again, now with the key step's REAL reference (preflight checked the rest of
+        // the configuration with a stand-in), still before the marker is written.
+        try {
+            const descriptor = resolveEnrollmentDescriptor(env, { keyReference });
+            if (!descriptor.issuer.deviceAuthorizationEndpoint) {
+                out.record("enroll", "failed", "missing_device_endpoint", "the deployment has no device authorization endpoint");
+                return out.report();
+            }
+        }
+        catch (error) {
+            out.record("enroll", "failed", authoredCode(error, "enrollment_descriptor_invalid"), "the enrollment deployment values are incomplete: unset the partial MESSAGE_BOARD_ENROLL_* issuer names to use the shipped defaults, or set all of them");
+            return out.report();
+        }
+        try {
+            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();
+        }
+        if (!deps.enroll) {
+            nodeFs.rmSync(markerPath, { force: true });
+            out.record("enroll", "failed", "enroll_runner_missing", "this build wires no enrollment runner into setup");
+            return out.report();
+        }
+        let outcome;
+        try {
+            outcome = await deps.enroll({
+                slug, keyReference, env,
+                intent: { kind: "none" },
+                onDeviceAuthorization: (devicePrompt) => { process.stderr.write(renderDevicePrompt(devicePrompt)); },
+            });
+        }
+        catch (error) {
+            const marker = enrollCommitMarker(error);
+            const code = authoredCode(error, "enroll_failed");
+            const status = error?.status;
+            const message = String(error?.message ?? "");
+            if (!marker && status === 403 && SLUG_TAKEN_DETAIL.test(message)) {
+                nodeFs.rmSync(markerPath, { force: true });
+                out.record("enroll", "failed", "slug_taken", `the slug ${slug} is taken by another agent: re-run with --slug <another>`);
+            }
+            else if (!marker && PRE_COMMIT_ENROLL_CODES.has(code)) {
+                nodeFs.rmSync(markerPath, { force: true });
+                out.record("enroll", "failed", code, "the device authorization was denied or expired before any agent was created: re-run setup");
+            }
+            else if (!marker && CONFIG_RESOLUTION_CODES.has(code)) {
+                nodeFs.rmSync(markerPath, { force: true });
+                out.record("enroll", "failed", code, "the enrollment configuration is incomplete, so nothing was sent: unset the partial MESSAGE_BOARD_ENROLL_* / AGENT_BOARD_* names to use the shipped defaults, or set all of them");
+            }
+            else {
+                out.record("enroll", "failed", marker?.state === "committed" ? "enroll_committed_incomplete" : "enroll_outcome_unknown", `whether the Portal created the agent is unknown. Check the Portal: if no agent exists, run \`agent-board setup --harness ${h} --clear-pending\` and re-run; if one does, revoke it first`);
+            }
+            return out.report();
+        }
+        out.record("enroll", "done", "enrolled");
+        try {
+            await writeIdentityFile(h, identityValuesFromEnrollment(outcome, deployment), env);
+        }
+        catch (error) {
+            out.record("identity", "failed", "identity_write_failed_after_commit", `the agent was enrolled (${outcome.agentHandle}) but its identity file was not written (${authoredCode(error, "unknown")}). Do NOT re-run the enrollment: revoke that agent's key in the Portal, then run setup --clear-pending and re-run`);
+            return out.report();
+        }
+        nodeFs.rmSync(markerPath, { force: true });
+        out.record("identity", "done", "written");
+    }
+    // ---- board ------------------------------------------------------------------------------
+    // Always the identity file just written, never ambient env: the invite is single-use.
+    const written = await identityState(h, env);
+    if (written.kind !== "present") {
+        out.record("board", "failed", written.kind === "unreadable" ? written.reason : "identity_absent");
+        return out.report();
+    }
+    const fileEnv = fileIdentityEnv(env, written.values);
+    let boardSkipped = false;
+    if (invite === null) {
+        boardSkipped = true;
+        out.record("board", "skipped", "no_invite");
+    }
+    else {
+        try {
+            const result = await (deps.createBoardClient ?? defaultBoardClient)(fileEnv).redeemInviteLink({ p_code: invite });
+            if (result?.ok === false)
+                throw result;
+            out.record("board", "done", "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)");
+            return out.report();
+        }
+    }
+    // ---- harness ----------------------------------------------------------------------------
+    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,
+    });
+    out.record("harness", installed.status, installed.reason, installed.fix);
+    if (installed.status === "failed")
+        return out.report();
+    // ---- doctor -----------------------------------------------------------------------------
+    let report;
+    try {
+        report = await (deps.doctor ?? runDoctor)({ harness: h, env, cwd, ...deps.doctorOptions });
+    }
+    catch (error) {
+        out.record("doctor", "undetermined", authoredCode(error, "doctor_threw"));
+        return out.report();
+    }
+    // The runtime expectation is "nothing is running": the reason alone is not enough, since a live
+    // probe or tier0 record also leaves it. Read with doctor's own reader and liveness test.
+    let liveRecords = 0;
+    try {
+        liveRecords = readSessionRecords(h, { ...(deps.doctorOptions?.trust ?? {}), env, isAlive: deps.doctorOptions?.isAlive })
+            .filter((entry) => entry.status === "live").length;
+    }
+    catch {
+        liveRecords = -1;
+    }
+    const expected = [];
+    const failures = [];
+    const unknowns = [];
+    for (const [name, check] of Object.entries(report.checks)) {
+        if (check.status === "pass")
+            continue;
+        if (name === "runtime" && check.status === "undetermined" && check.reason === "no_live_wake_producer" && liveRecords === 0) {
+            expected.push(`runtime=${check.reason}`);
+        }
+        else if (name === "board_membership" && boardSkipped && check.status === "fail" && check.reason === "no_membership") {
+            expected.push(`board_membership=${check.reason}`);
+        }
+        else if (check.status === "fail")
+            failures.push(name);
+        else
+            unknowns.push(name);
+    }
+    for (const item of expected)
+        out.notes.push(`doctor: expected ${item.replace("=", ": ")}`);
+    if (failures.length > 0)
+        out.record("doctor", "failed", `doctor_failed:${failures.join("+")}`, `run \`agent-board doctor --harness ${h}\` for each check's reason`);
+    else if (unknowns.length > 0)
+        out.record("doctor", "undetermined", `doctor_undetermined:${unknowns.join("+")}`, `run \`agent-board doctor --harness ${h}\` for each check's reason`);
+    else
+        out.record("doctor", "done", expected.length > 0 ? `expected:${expected.join(",")}` : "passed");
+    out.notes.push(`next: start ${h} in ${scope === "local" ? "this directory" : "any directory"}, then run \`agent-board doctor --harness ${h}\``);
+    if (boardSkipped)
+        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();
+}
+/**
+ * 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;
+    let dir;
+    try {
+        dir = deps.storage?.keyslotDir ?? resolveKeyslotDir();
+    }
+    catch {
+        return { status: "undetermined", reason: "keyslot_scripts_absent", fix: "the packaged keyslot scripts are missing: reinstall @consiliency/agent-board-cli" };
+    }
+    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 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 });
+    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();
+    if (after === null || after.recorded !== after.running)
+        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" };
+}
+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) {
+    program
+        .command("setup")
+        .description("set this host up for one harness: 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("--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("--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("--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 report = await setup({
+            harness: String(options.harness ?? ""),
+            slug: options.slug,
+            invite: options.invite === true,
+            allowUnsealedKey: options.allowUnsealedKey === true,
+            agentSocket: options.agentSocket,
+            scope: options.scope,
+            installDeps: options.installDeps === true,
+            clearPending: options.clearPending === true,
+            followSymlinks: options.followSymlinks !== false,
+        });
+        if (options.json) {
+            io.writeStdout(`${JSON.stringify({ steps: report.steps, exit: report.exit })}\n`);
+            if (report.notes.length > 0)
+                io.writeStderr(`${report.notes.join("\n")}\n`);
+        }
+        else {
+            io.writeStdout(`${formatSetupReport(report)}\n`);
+        }
+        process.exitCode = report.exit;
+    });
+}