@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/dist/setup_storage.d.ts

@@ -0,0 +1,117 @@
+import { type OsKeychainProbeResult } from "@consiliency/agent-board-client";
+export type KeyStorage = "os_keychain" | "sealed" | "unsealed" | "external" | "refused";
+export interface KeyStorageSelection {
+    storage: KeyStorage;
+    /** An authored code: never a path or any other file string. */
+    reason: string;
+    /** For a refusal: what the user runs or changes. */
+    fix?: string;
+    /**
+     * The reference enrollment consumes: provision.sh's `agent_socket:` line for sealed/unsealed, the
+     * user's own `--agent-socket` for external. Absent for os_keychain: the caller names the handle.
+     */
+    keyReference?: string;
+    /** The keyslot the reference names (sealed/unsealed). */
+    slot?: string;
+    /** The #536 repairs performed, by name, in order. */
+    repairs: string[];
+}
+export interface RunOutcome {
+    /** null when the child did not exit on its own (killed, timed out, not spawned). */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type StorageRunner = (file: string, args: readonly string[], options: {
+    env: NodeJS.ProcessEnv;
+}) => Promise<RunOutcome>;
+/** The `deps` step's result, as far as a refusal needs it. */
+export interface DepsOutcome {
+    status: "done" | "already" | "skipped" | "failed" | "undetermined";
+    reason: string;
+    /** The exact install command, when `deps` did not install the keychain tool. */
+    installCommand?: string;
+}
+export interface KeyStorageContext {
+    harness: string;
+    /** Default: the harness. */
+    slot?: string;
+    /** True ONLY when the user passed `--allow-unsealed-key`. */
+    allowUnsealedKey?: boolean;
+    /** The user's `--agent-socket <ref>`. */
+    agentSocket?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** Default `process.getuid()`. */
+    uid?: number;
+    deps?: DepsOutcome;
+    probeKeychain?: () => Promise<OsKeychainProbeResult>;
+    run?: StorageRunner;
+    /** Default `resolveKeyslotDir()`. */
+    keyslotDir?: string;
+    /** Default `/etc/machine-id`. */
+    machineIdFile?: string;
+    bash?: string;
+    systemctl?: string;
+}
+export declare const SLOT_RE: RegExp;
+export declare const defaultStorageRunner: StorageRunner;
+/** The opt-in record's host comparand: sha256 of the whole machine-id file, first 16 hex (`sha256sum <`). */
+export declare function machineIdOf(file?: string): string | null;
+/** `$XDG_RUNTIME_DIR/agent-board`, where each keyslot's agent socket lives (constants.sh). */
+export declare function keyslotSocketDir(env: NodeJS.ProcessEnv): string | null;
+/** `<configRoot>/agent-board/keyslot`, the slot directory (constants.sh `keyseal_key_dir`). */
+export declare function keyslotKeyDir(env: NodeJS.ProcessEnv): string | null;
+/** `<configRoot>/agent-board/external-agent` (IF-0-KEYSEAL-6). */
+export declare function externalAgentDeclarationPath(env: NodeJS.ProcessEnv): string | null;
+/**
+ * The socket an `agent_socket:` handle signs through, resolved exactly as the client's backend does
+ * (`keystore_agent_socket.ts` `resolveSocketPath`): a non-empty `MESSAGE_BOARD_AGENT_SOCKET_PATH`
+ * overrides the handle; the handle's part before `#` otherwise, with the sentinels meaning
+ * `$SSH_AUTH_SOCK`. null when nothing names a socket.
+ */
+export declare function resolveAgentSocketPath(handle: string, env: NodeJS.ProcessEnv): string | null;
+/** Device and inode of what a path resolves to; null when it does not resolve. */
+export declare function fileIdentity(path: string): {
+    dev: number;
+    ino: number;
+} | null;
+/**
+ * Principle 4 on a directory and every directory above it: a real directory (never a symlink),
+ * owned by `uid` or root, not group/other-writable unless root-owned and sticky. One problem per line.
+ */
+export declare function untrustedAncestors(dir: string, uid: number): string[];
+export interface OwnerOnlyRecord {
+    values: Record<string, string>;
+    /** Empty only when the file opened under principle 4 and holds exactly `fields`, once each. */
+    problems: string[];
+}
+/**
+ * A `KEY=value` record opened as the keyslot scripts open the opt-in (optin.sh): no symlink, a
+ * regular file, the same inode after the open, this uid's, no group/other bit, bounded size, every
+ * ancestor trusted; then exactly the listed fields, none unknown, none repeated.
+ */
+export declare function readOwnerOnlyRecord(path: string, fields: readonly string[], uid: number, maxBytes?: number): OwnerOnlyRecord;
+export declare const OPTIN_FIELDS: readonly ["version", "machine_id", "uid", "slot", "pub_sha256", "granted_at"];
+/**
+ * The unsealed opt-in `<K>/<slot>.unsealed-optin`, field by field against this host, user, slot and
+ * pin (IF-0-KEYSEAL-6 "Opt-in record"). Empty = valid.
+ */
+export declare function unsealedOptinProblems(env: NodeJS.ProcessEnv, slot: string, uid: number, machineId: string | null): string[];
+export declare const EXTERNAL_FIELDS: readonly ["machine_id", "uid", "socket"];
+/**
+ * The external-agent declaration against the socket actually used: this machine, this user, and a
+ * canonical `socket=` (absolute, its own realpath) that is the same device and inode. Empty = valid.
+ */
+export declare function externalDeclarationProblems(env: NodeJS.ProcessEnv, socketPath: string, uid: number, machineId: string | null): string[];
+/** The #536 repair, then the full ancestor walk. Returns the repairs, or the problems. */
+export declare function repairKeyDir(env: NodeJS.ProcessEnv, uid: number): {
+    repairs: string[];
+    problems: string[];
+    root: string | null;
+};
+/**
+ * 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.
+ */
+export declare function selectKeyStorage(ctx: KeyStorageContext): Promise<KeyStorageSelection>;

package/dist/setup_storage.js

@@ -0,0 +1,447 @@
+// SETUP IF-0-SETUP-3 (cli half) — which key storage `setup` uses, following the IF-0-KEYSEAL-6 table
+// in its order:
+//
+//   1. the client's `probeOsKeychainRoundTrip()`: store, read back byte-equal, delete a throwaway;
+//   2. setup's own gate: platform linux, `systemctl --user` reachable, bash >= 4 (probe.sh cannot say
+//      "no user systemd", and bash 3.2 fails on its `declare -A`), so a host with no user systemd is
+//      never offered a key slot;
+//   3. the packaged `provision.sh`, which selects sealed or unsealed. `--allow-unsealed-key` is passed
+//      only when the user gave it; the mode is then MEASURED with `status.sh --json`, never inferred
+//      from what provision was asked;
+//   4. `external`, only with `--agent-socket <ref>` and a declaration naming that socket;
+//   5. otherwise refused, naming the fix.
+//
+// Before provision runs, the key directory's ancestors are made safe as a named step (#536): a fresh
+// user under a user-private group gets a 0775 `~/.config`, which the unsealed opt-in's principle-4
+// walk refuses. Only a directory the user owns is repaired; anything else is `unsafe_key_dir`, and
+// provision is never reached with an unsafe directory.
+//
+// Every `reason` is an authored code, never file content; the human fix is in `fix`. The same
+// module holds the owner-only KEY=value record reader that doctor's `key_storage` uses for the
+// unsealed opt-in and the external-agent declaration (IF-0-KEYSEAL-6: "checked like the opt-in").
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { probeOsKeychainRoundTrip } from "@consiliency/agent-board-client";
+import { resolveKeyslotDir } from "./assets.js";
+export const SLOT_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const REFERENCE_LINE = /^agent_socket:\/\S+#[A-Za-z0-9_-]{43}$/;
+/** States in which `systemctl --user` has a manager answering. */
+const MANAGER_REACHABLE = new Set(["initializing", "starting", "running", "degraded", "maintenance", "stopping"]);
+const RUN_TIMEOUT_MS = 180_000;
+export const defaultStorageRunner = (file, args, { env }) => new Promise((resolve) => {
+    execFile(file, [...args], { env, timeout: RUN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+        const code = error ? (typeof error.code === "number" && !error.killed ? error.code : null) : 0;
+        resolve({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+    });
+});
+const currentUid = () => (typeof process.getuid === "function" ? process.getuid() : -1);
+const configRoot = (env) => {
+    const xdg = env.XDG_CONFIG_HOME?.trim();
+    if (xdg)
+        return xdg;
+    const home = env.HOME?.trim();
+    return home ? join(home, ".config") : null;
+};
+// ---------------------------------------------------------------------------------------------
+// Shared measurements (doctor's key_storage uses these too)
+// ---------------------------------------------------------------------------------------------
+/** The opt-in record's host comparand: sha256 of the whole machine-id file, first 16 hex (`sha256sum <`). */
+export function machineIdOf(file = "/etc/machine-id") {
+    try {
+        return createHash("sha256").update(readFileSync(file)).digest("hex").slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+/** `$XDG_RUNTIME_DIR/agent-board`, where each keyslot's agent socket lives (constants.sh). */
+export function keyslotSocketDir(env) {
+    const runtime = env.XDG_RUNTIME_DIR?.trim();
+    return runtime ? join(runtime, "agent-board") : null;
+}
+/** `<configRoot>/agent-board/keyslot`, the slot directory (constants.sh `keyseal_key_dir`). */
+export function keyslotKeyDir(env) {
+    const root = configRoot(env);
+    return root ? join(root, "agent-board", "keyslot") : null;
+}
+/** `<configRoot>/agent-board/external-agent` (IF-0-KEYSEAL-6). */
+export function externalAgentDeclarationPath(env) {
+    const root = configRoot(env);
+    return root ? join(root, "agent-board", "external-agent") : null;
+}
+const SOCKET_SENTINELS = new Set(["", "default", "$ssh_auth_sock", "ssh_auth_sock"]);
+/**
+ * The socket an `agent_socket:` handle signs through, resolved exactly as the client's backend does
+ * (`keystore_agent_socket.ts` `resolveSocketPath`): a non-empty `MESSAGE_BOARD_AGENT_SOCKET_PATH`
+ * overrides the handle; the handle's part before `#` otherwise, with the sentinels meaning
+ * `$SSH_AUTH_SOCK`. null when nothing names a socket.
+ */
+export function resolveAgentSocketPath(handle, env) {
+    const override = (env.MESSAGE_BOARD_AGENT_SOCKET_PATH ?? "").trim();
+    const hash = handle.indexOf("#");
+    const spec = override !== "" ? override : (hash >= 0 ? handle.slice(0, hash) : handle).trim();
+    if (SOCKET_SENTINELS.has(spec.toLowerCase())) {
+        const sock = env.SSH_AUTH_SOCK;
+        return sock ? sock : null;
+    }
+    return spec;
+}
+/** Device and inode of what a path resolves to; null when it does not resolve. */
+export function fileIdentity(path) {
+    try {
+        const stats = statSync(realpathSync(path));
+        return { dev: stats.dev, ino: stats.ino };
+    }
+    catch {
+        return null;
+    }
+}
+const sameFile = (a, b) => a !== null && b !== null && a.dev === b.dev && a.ino === b.ino;
+/**
+ * Principle 4 on a directory and every directory above it: a real directory (never a symlink),
+ * owned by `uid` or root, not group/other-writable unless root-owned and sticky. One problem per line.
+ */
+export function untrustedAncestors(dir, uid) {
+    const problems = [];
+    if (!isAbsolute(dir))
+        return [`${dir} is not absolute`];
+    const parts = dir.split("/").filter(Boolean);
+    const paths = ["/", ...parts.map((_, index) => `/${parts.slice(0, index + 1).join("/")}`)];
+    for (const path of paths) {
+        let stats;
+        try {
+            stats = lstatSync(path);
+        }
+        catch {
+            problems.push(`ancestor ${path}: missing`);
+            break;
+        }
+        if (stats.isSymbolicLink()) {
+            problems.push(`ancestor ${path} is a symlink`);
+            continue;
+        }
+        if (!stats.isDirectory()) {
+            problems.push(`ancestor ${path} is not a directory`);
+            continue;
+        }
+        if (stats.uid !== uid && stats.uid !== 0)
+            problems.push(`ancestor ${path} is owned by uid ${stats.uid}`);
+        if ((stats.mode & 0o022) !== 0 && !((stats.mode & 0o1000) !== 0 && stats.uid === 0))
+            problems.push(`ancestor ${path} is group/other-writable`);
+    }
+    return problems;
+}
+/**
+ * A `KEY=value` record opened as the keyslot scripts open the opt-in (optin.sh): no symlink, a
+ * regular file, the same inode after the open, this uid's, no group/other bit, bounded size, every
+ * ancestor trusted; then exactly the listed fields, none unknown, none repeated.
+ */
+export function readOwnerOnlyRecord(path, fields, uid, maxBytes = 4096) {
+    const values = {};
+    const problems = untrustedAncestors(dirname(path), uid);
+    let before;
+    try {
+        before = lstatSync(path);
+    }
+    catch {
+        return { values, problems: [...problems, "missing"] };
+    }
+    if (before.isSymbolicLink())
+        return { values, problems: [...problems, "is a symlink"] };
+    if (!before.isFile())
+        return { values, problems: [...problems, "is not a regular file"] };
+    let text;
+    let fd = null;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const after = fstatSync(fd);
+        if (after.dev !== before.dev || after.ino !== before.ino)
+            return { values, problems: [...problems, "changed while it was opened"] };
+        if (after.uid !== uid)
+            problems.push(`is owned by uid ${after.uid}`);
+        if ((after.mode & 0o077) !== 0)
+            problems.push(`has mode ${(after.mode & 0o777).toString(8)}, not 0600`);
+        if (after.size > maxBytes)
+            return { values, problems: [...problems, `is over ${maxBytes} bytes`] };
+        text = readFileSync(fd, "utf8");
+    }
+    catch {
+        return { values, problems: [...problems, "unreadable"] };
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        const eq = line.indexOf("=");
+        const key = eq > 0 ? line.slice(0, eq) : line;
+        if (eq <= 0 || !fields.includes(key)) {
+            problems.push(`unknown or malformed line "${key.slice(0, 32)}"`);
+            continue;
+        }
+        if (key in values) {
+            problems.push(`duplicate ${key}`);
+            continue;
+        }
+        values[key] = line.slice(eq + 1);
+    }
+    for (const field of fields)
+        if (!(field in values))
+            problems.push(`missing ${field}`);
+    return { values, problems };
+}
+export const OPTIN_FIELDS = Object.freeze(["version", "machine_id", "uid", "slot", "pub_sha256", "granted_at"]);
+const OPTIN_GRAMMAR = {
+    version: /^1$/, machine_id: /^[0-9a-f]{16}$/, uid: /^[0-9]+$/, slot: SLOT_RE,
+    pub_sha256: /^[0-9a-f]{64}$/, granted_at: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/,
+};
+/**
+ * The unsealed opt-in `<K>/<slot>.unsealed-optin`, field by field against this host, user, slot and
+ * pin (IF-0-KEYSEAL-6 "Opt-in record"). Empty = valid.
+ */
+export function unsealedOptinProblems(env, slot, uid, machineId) {
+    const dir = keyslotKeyDir(env);
+    if (!dir)
+        return ["no config root"];
+    const { values, problems } = readOwnerOnlyRecord(join(dir, `${slot}.unsealed-optin`), OPTIN_FIELDS, uid);
+    for (const field of OPTIN_FIELDS) {
+        if (field in values && !OPTIN_GRAMMAR[field].test(values[field]))
+            problems.push(`malformed ${field}`);
+    }
+    let pinSha = null;
+    try {
+        const pub = join(dir, `${slot}.pub`);
+        if (!lstatSync(pub).isSymbolicLink())
+            pinSha = createHash("sha256").update(readFileSync(pub)).digest("hex");
+    }
+    catch {
+        pinSha = null;
+    }
+    if ("machine_id" in values && (machineId === null || values.machine_id !== machineId))
+        problems.push("machine_id is another machine's");
+    if ("uid" in values && values.uid !== String(uid))
+        problems.push("uid is another user's");
+    if ("slot" in values && values.slot !== slot)
+        problems.push("slot is another slot's");
+    if ("pub_sha256" in values && values.pub_sha256 !== pinSha)
+        problems.push("pub_sha256 does not match the pin file");
+    return problems;
+}
+export const EXTERNAL_FIELDS = Object.freeze(["machine_id", "uid", "socket"]);
+/**
+ * The external-agent declaration against the socket actually used: this machine, this user, and a
+ * canonical `socket=` (absolute, its own realpath) that is the same device and inode. Empty = valid.
+ */
+export function externalDeclarationProblems(env, socketPath, uid, machineId) {
+    const path = externalAgentDeclarationPath(env);
+    if (!path)
+        return ["no config root"];
+    const { values, problems } = readOwnerOnlyRecord(path, EXTERNAL_FIELDS, uid);
+    if ("machine_id" in values && (machineId === null || values.machine_id !== machineId))
+        problems.push("machine_id is another machine's");
+    if ("uid" in values && values.uid !== String(uid))
+        problems.push("uid is another user's");
+    if ("socket" in values) {
+        const declared = values.socket;
+        let canonical = false;
+        try {
+            canonical = isAbsolute(declared) && realpathSync(declared) === declared;
+        }
+        catch {
+            canonical = false;
+        }
+        if (!canonical)
+            problems.push("socket is not a canonical path");
+        else if (!sameFile(fileIdentity(declared), fileIdentity(socketPath)))
+            problems.push("socket is not the agent socket in use");
+    }
+    return problems;
+}
+// ---------------------------------------------------------------------------------------------
+// selectKeyStorage
+// ---------------------------------------------------------------------------------------------
+const refused = (reason, fix, repairs = []) => ({ storage: "refused", reason, fix, repairs });
+/** The #536 repair, then the full ancestor walk. Returns the repairs, or the problems. */
+export function repairKeyDir(env, uid) {
+    const repairs = [];
+    const root = configRoot(env);
+    if (!root || !isAbsolute(root))
+        return { repairs, problems: ["no absolute config root (HOME or XDG_CONFIG_HOME)"], root };
+    const boardDir = join(root, "agent-board");
+    const owned = (path) => {
+        try {
+            const stats = lstatSync(path);
+            return stats.isDirectory() && !stats.isSymbolicLink() && stats.uid === uid ? stats : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    let exists = true;
+    try {
+        lstatSync(root);
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        repairs.push("config_root_created");
+    }
+    const rootStats = owned(root);
+    if (rootStats && (rootStats.mode & 0o022) !== 0) {
+        chmodSync(root, rootStats.mode & 0o7777 & ~0o022);
+        repairs.push("config_root_group_write_removed");
+    }
+    let boardExists = true;
+    try {
+        lstatSync(boardDir);
+    }
+    catch {
+        boardExists = false;
+    }
+    if (!boardExists && rootStats) {
+        mkdirSync(boardDir, { mode: 0o700 });
+        repairs.push("agent_board_dir_created");
+    }
+    else {
+        const boardStats = owned(boardDir);
+        if (boardStats && (boardStats.mode & 0o777) !== 0o700) {
+            chmodSync(boardDir, 0o700);
+            repairs.push("agent_board_dir_0700");
+        }
+    }
+    return { repairs, problems: untrustedAncestors(boardDir, uid), root };
+}
+/** provision.sh's exit-1 refusals, by the token it prints. Anything else is `provision_failed`. */
+const PROVISION_REFUSALS = {
+    allow_unsealed_refused: "this host can seal (probe.sh: capable), so an unsealed key is never written here: re-run setup WITHOUT --allow-unsealed-key",
+    probe_error: "probe.sh could not judge this host (a user manager that is not running, no XDG_RUNTIME_DIR, or a failed round trip on systemd >= 256): run the packaged probe.sh --json and fix what it names",
+    unsafe_key_dir: "a directory above the key slot is not safe (principle 4): make every ancestor yours or root's and not group/other-writable, then re-run setup",
+    downgrade_refused: "this slot holds a sealed key, which is never turned unsealed: remove the slot's .cred and .pub first, then re-run with --allow-unsealed-key",
+    config_dir_mismatch: "XDG_CONFIG_HOME/HOME differ from the user manager's (systemctl --user show-environment): run setup from the same environment the manager has",
+    slot_busy: "another provision holds this slot's lock: wait for it and re-run setup",
+    loader_busy: "another provision holds the loader lock: wait for it and re-run setup",
+    slot_inconsistent: "the slot directory holds a state provision.sh does not name; nothing was deleted: run the packaged status.sh --json and resolve what it reports",
+    rotate_needs_capable: "this host cannot seal a new key",
+};
+function withDeps(fix, deps) {
+    return deps?.installCommand && deps.status !== "done" && deps.status !== "already"
+        ? `${fix}; or install the keychain tool (${deps.installCommand}) and re-run setup`
+        : fix;
+}
+const EXTERNAL_FIX = (path) => `declare your own agent in ${path ?? "<config root>/agent-board/external-agent"} (0600, yours): machine_id=<sha256(/etc/machine-id), first 16 hex>, uid=<your uid>, socket=<the socket's canonical path>`;
+/** Step 4: an external agent, only with --agent-socket and a declaration naming that socket. */
+function externalAgent(agentSocket, env, uid, machineIdFile, repairs) {
+    const reference = agentSocket.startsWith("agent_socket:") ? agentSocket : `agent_socket:${agentSocket}`;
+    const socket = resolveAgentSocketPath(reference.slice("agent_socket:".length), env);
+    const declaration = externalAgentDeclarationPath(env);
+    if (socket === null)
+        return refused("agent_socket_unresolved", "--agent-socket names no socket (and SSH_AUTH_SOCK is unset)", repairs);
+    const problems = externalDeclarationProblems(env, socket, uid, machineIdOf(machineIdFile));
+    if (problems.length === 0)
+        return { storage: "external", reason: "external_declared", keyReference: reference, repairs };
+    return refused(problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch", EXTERNAL_FIX(declaration), repairs);
+}
+/**
+ * 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.
+ */
+export async function selectKeyStorage(ctx) {
+    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}$");
+    // 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, []);
+    // 1. A live keychain round trip.
+    let keychain = null;
+    try {
+        keychain = await (ctx.probeKeychain ?? (() => probeOsKeychainRoundTrip({ platform })))();
+    }
+    catch {
+        keychain = null;
+    }
+    if (keychain?.ok)
+        return { 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") {
+        gate = platform === "darwin"
+            ? { reason: "macos_keychain_unavailable", fix: "the login keychain did not complete a round trip: unlock it (security unlock-keychain) in a logged-in session and re-run setup" }
+            : { reason: "platform_unsupported", fix: "setup's key storage supports Linux and macOS; on Windows run setup inside WSL, or pass --agent-socket <ref> with an external-agent declaration" };
+    }
+    else {
+        const manager = await run(ctx.systemctl ?? "/usr/bin/systemctl", ["--user", "is-system-running"], { env });
+        if (!MANAGER_REACHABLE.has(manager.stdout.trim())) {
+            gate = { reason: "no_user_systemd", fix: "no user systemd manager answers `systemctl --user`, so no key slot is offered: log in to a desktop session whose keychain unlocks, or run setup from a login session with a user manager (loginctl enable-linger $USER), or pass --agent-socket <ref>" };
+        }
+        else {
+            const bash = await run(ctx.bash ?? "/bin/bash", ["-c", "printf %s \"${BASH_VERSINFO[0]}\""], { env });
+            const major = bash.code === 0 && /^\d+$/.test(bash.stdout.trim()) ? Number(bash.stdout.trim()) : null;
+            if (major === null || major < 4)
+                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.
+    let slotRefusal = null;
+    let repairs = [];
+    if (gate === null) {
+        let dir;
+        try {
+            dir = ctx.keyslotDir ?? resolveKeyslotDir();
+        }
+        catch {
+            return 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);
+        }
+        const args = ["--harness", ctx.harness, "--slot", slot, ...(ctx.allowUnsealedKey === true ? ["--allow-unsealed-key"] : [])];
+        const provision = await run(join(dir, "provision.sh"), args, { env });
+        if (provision.code === 0) {
+            const line = provision.stdout.split("\n").map((entry) => entry.trim()).filter(Boolean).at(-1) ?? "";
+            if (!REFERENCE_LINE.test(line))
+                return refused("provision_output_unrecognised", "provision.sh exited 0 without printing an agent_socket: reference; run it by hand and report the output", repairs);
+            const status = await run(join(dir, "status.sh"), ["--harness", ctx.harness, "--slot", slot, "--json"], { env });
+            let mode = null;
+            try {
+                mode = JSON.parse(status.stdout).mode;
+            }
+            catch {
+                mode = null;
+            }
+            if (mode === "sealed" || mode === "unsealed")
+                return { storage: mode, reason: `keyslot_${mode}`, keyReference: line, slot, repairs };
+            return refused("keyslot_mode_unmeasured", "provision.sh succeeded but status.sh does not measure the slot as sealed or unsealed: run the packaged status.sh --json and resolve what it reports", repairs);
+        }
+        if (provision.code === 2) {
+            slotRefusal = /incapable_for_keyslot/.test(provision.stderr)
+                ? { reason: "incapable_for_keyslot", fix: "no key slot survives a reboot here: run `loginctl enable-linger $USER` and install openssh-client (ssh-agent, ssh-add, ssh-keygen), then re-run setup" }
+                : /capability_absent/.test(provision.stderr)
+                    ? { reason: "unsealed_needs_opt_in", fix: "this host cannot seal (systemd below 256, or no systemd-creds): re-run with --allow-unsealed-key to accept a 0600 key under an opt-in record, or use a desktop keychain" }
+                    : { reason: "provision_undetermined", fix: "provision.sh could not establish a key slot: run it by hand and read what it reports" };
+        }
+        else {
+            const token = Object.keys(PROVISION_REFUSALS).find((name) => provision.stderr.includes(name));
+            return 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);
+        }
+    }
+    // 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);
+}