@consiliency/agent-board-cli 1.28.0 → 1.29.1

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

@@ -147,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

@@ -24,7 +24,7 @@ import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openS
 import { dirname, isAbsolute, join } from "node:path";
 import { OS_KEYCHAIN_SERVICE, probeOsKeychainRoundTrip } from "@consiliency/agent-board-client";
 import { resolveKeyslotDir } from "./assets.js";
-import { cacheStateOf, defaultStorageRunner, measureKeyslot, progressText, scanOf, scanSourceOf, } from "./keyslot_status.js";
+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}$/;
@@ -456,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 {
@@ -482,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") {
@@ -502,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) {
@@ -511,44 +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);
-            // #552: one measurement, scanning only when no valid cache holds this key's scan, with
-            // notices before and after. Setup's onFailure is `scan`: a phase-1 exit 1 beside a measured
-            // mode still gets its scan (status.sh scans even on a contradiction).
-            const notify = ctx.notify ?? ((text) => { process.stderr.write(`${text}\n`); });
-            const notices = keyScanNotices(ctx.harness, notify);
-            const measured = await measureKeyslot({
-                dir, harness: ctx.harness, slot, env, scan: "use", onFailure: "scan", run: ctx.run, budgets: ctx.statusBudgets,
-                notify: notices,
-            });
-            if (!measured.phases.some((phase) => phase.mode !== "only") && scanSourceOf(measured.report) === "cached") {
-                notify(`key: plaintext-copy scan cached at ${String(scanOf(measured.report).scanned_at)}`);
-            }
-            const mode = measured.report?.mode;
-            if (mode === "sealed" || mode === "unsealed") {
-                const gate = scanGate(ctx.harness, measured);
-                if (gate)
-                    return { storage: "refused", status: gate.status, reason: gate.reason, fix: gate.fix, repairs };
-                return { storage: mode, reason: `keyslot_${mode}`, keyReference: line, slot, repairs, keyScan: keyStepScan(measured.report) };
-            }
-            const gate = scanGate(ctx.harness, measured);
-            // A scan that ran but whose report could not be read is a scan that did not complete.
-            const scanned = measured.phases.some((phase) => phase.mode !== "only");
-            if (gate && (gate.reason !== "scan_not_completed" || scanned))
-                return { storage: "refused", status: gate.status, reason: gate.reason, fix: gate.fix, repairs };
-            return refused("keyslot_mode_unmeasured", "provision.sh succeeded but status.sh does not measure the slot as sealed or unsealed: run the packaged status.sh --json and resolve what it reports", repairs);
+                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)
@@ -559,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;

package/dist/setup_writers.js

@@ -243,6 +243,15 @@ export function which(name, env) {
     }
     return 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 function harnessCliPath(harness, env) {
+    return which(harness, env);
+}
 function isSymlink(path) {
     try {
         return lstatSync(path).isSymbolicLink();
@@ -486,7 +495,7 @@ function packageSpecsSeen(harness, ctx) {
     return { specs, unparseable: scopes.unparseable };
 }
 async function installPackage(ctx, scopeCtx) {
-    const cli = which(ctx.harness, ctx.env);
+    const cli = harnessCliPath(ctx.harness, ctx.env);
     if (cli === null)
         return failed("harness_cli_missing", `the ${ctx.harness} CLI is not on PATH: install ${ctx.harness}, then re-run setup`);
     const version = ctx.harness === "pi" ? ctx.assets.piVersion : ctx.assets.opencodeVersion;
@@ -805,7 +814,7 @@ function materializeMarketplace(ctx, scopeCtx) {
     return { dir, rewrote: true, notes };
 }
 async function installClaude(ctx, scopeCtx) {
-    const cli = which("claude", ctx.env);
+    const cli = harnessCliPath("claude", ctx.env);
     if (cli === null)
         return failed("harness_cli_missing", "the claude CLI is not on PATH: install Claude Code, then re-run setup");
     const seen = boardEntries("claude", scopeCtx);