@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/dist/claude_marketplace.js

@@ -0,0 +1,306 @@
+// message-board#549 — the per-user Claude Code marketplace directory, shared by setup (which writes
+// it) and doctor (which judges it). ONE implementation of each rule, imported by both, so the two
+// cannot disagree about where the directory is, what "the same content" means, or which chain of
+// directories is trusted.
+//
+//   claudeMarketplaceDir   `${XDG_DATA_HOME}` if absolute, else `$HOME/.local/share`, then
+//                          `/agent-board/claude-marketplace`. Claude Code 2.1.283 stores a directory
+//                          marketplace path AS GIVEN (a trailing slash stripped, symlinks NOT
+//                          resolved: measured), so setup and doctor compare paths lexically after
+//                          `resolve()` under one env.
+//   readTree / sameTree    every regular file, relative path (always `/`-separated, on every OS) →
+//                          bytes and exec bit; a symlink, device, socket or FIFO anywhere inside makes
+//                          the tree unusable. Equal = same file set, same bytes, same exec bit.
+//   resolveTrustChain      (round 4: replaces the lexical + real-path chains) walks the path as the
+//                          kernel does, from `/`, one component at a time. Every directory ENTERED:
+//                            * the marketplace directory and its `agent-board` parent: a real
+//                              directory (never a symlink), owned by this uid, not group/world-
+//                              writable;
+//                            * every other: owned by this uid or root, and not group/world-writable,
+//                              except root-owned with the sticky bit (`/tmp`), or owned by this uid and
+//                              group-writable (never world) by the user's PRIVATE group, proven from
+//                              `/etc/group` AND `/etc/passwd` (stock Ubuntu/Fedora `~/.local` is 0775
+//                              `<user>:<user>`).
+//                          A symlink component: its own owner must be this uid or root, and its target
+//                          is spliced into the remaining components, so every hop's containing
+//                          directory is entered and judged. More than 40 links: a loop, refused.
+//                          A same-uid attacker is out of scope (SETUP ruling). On win32 there is no
+//                          uid (getuid() is -1) and no POSIX mode, so only the symlink rule applies.
+//   plugin versions        `pluginVersionIn` / `compareVersions`, shared by setup (never downgrade a
+//                          TRUSTED newer directory; an untrusted one is rebuilt) and doctor (report version skew).
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import { userInfo } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+/** The manifest's key in a tree read by `readTree`: always `/`-separated. */
+export const MARKETPLACE_MANIFEST_KEY = ".claude-plugin/marketplace.json";
+/** THE per-user directory setup materialises the packaged marketplace into. User and local scope share it. */
+export function claudeMarketplaceDir(env, home) {
+    const data = env.XDG_DATA_HOME;
+    const root = data !== undefined && data.trim() !== "" && isAbsolute(data) ? data : join(home, ".local", "share");
+    return join(root, "agent-board", "claude-marketplace");
+}
+/** A declared directory path is ours when it resolves to `claudeMarketplaceDir` for this env. */
+export function isOurMarketplacePath(path, env, home) {
+    return typeof path === "string" && isAbsolute(path) && resolve(path) === resolve(claudeMarketplaceDir(env, home));
+}
+/**
+ * Every regular file under `dir`. `missing` when `dir` does not exist; `unusable` when it is not a
+ * plain tree. With `trust` (the materialised directory, never the packaged copy, which a root-owned
+ * global install legitimately owns): every directory and file under `dir` must be owned by this uid
+ * and not group/world-writable, else `untrusted` naming the first offender — a hook another uid can
+ * rewrite is a hook another uid runs as you. Skipped on win32, as elsewhere.
+ */
+export function readTree(dir, trust) {
+    let top;
+    try {
+        top = lstatSync(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "unusable" };
+    }
+    if (!top.isDirectory())
+        return { kind: "unusable" };
+    const files = new Map();
+    const judged = trust !== undefined && (trust.platform ?? process.platform) !== "win32";
+    let offender = null;
+    const untrusted = (path, stats) => {
+        if (!judged)
+            return false;
+        const owned = trust.lstat ? trust.lstat(path) : stats;
+        if (owned.uid === trust.uid && (owned.mode & 0o022) === 0)
+            return false;
+        offender = path;
+        return true;
+    };
+    const walk = (relative) => {
+        for (const name of readdirSync(relative === "" ? dir : join(dir, ...relative.split("/"))).sort()) {
+            const child = relative === "" ? name : `${relative}/${name}`;
+            const absolute = join(dir, ...child.split("/"));
+            const stats = lstatSync(absolute);
+            if ((stats.isDirectory() || stats.isFile()) && untrusted(absolute, stats))
+                return false;
+            if (stats.isDirectory()) {
+                if (!walk(child))
+                    return false;
+            }
+            else if (stats.isFile()) {
+                files.set(child, { bytes: readFileSync(absolute), executable: (stats.mode & 0o111) !== 0 });
+            }
+            else {
+                return false;
+            }
+        }
+        return true;
+    };
+    try {
+        if (walk(""))
+            return { kind: "ok", files };
+        return offender !== null ? { kind: "untrusted", path: offender } : { kind: "unusable" };
+    }
+    catch {
+        return { kind: "unusable" };
+    }
+}
+/** Same file set, same bytes, same exec bit. */
+export function sameTree(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [path, file] of a) {
+        const other = b.get(path);
+        if (!other || other.executable !== file.executable || !other.bytes.equals(file.bytes))
+            return false;
+    }
+    return true;
+}
+/** Symlinks followed before a path is refused as a loop (Linux's MAXSYMLINKS). */
+export const MAX_SYMLINK_HOPS = 40;
+const readOr = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The user's PRIVATE group (USERGROUPS_ENAB: Ubuntu, Debian, Fedora, RHEL make `~/.local` 0775 owned
+ * `<user>:<user>`). Proven only from the local files, and only when BOTH say no one else is in it:
+ *   * `/etc/group` has exactly one entry for the gid, named as the user, whose members are a subset
+ *     of {the user} (some tools list the user in their own group);
+ *   * `/etc/passwd` has exactly one account whose primary gid is that gid, and it is this user (name
+ *     AND uid) — two accounts sharing a primary gid share its write bit (round 4).
+ * The gid must also be this process's primary gid. An account or group only in NSS/LDAP, a shared
+ * group (SUSE `users`) or an unreadable file proves nothing: refused.
+ */
+export function isPrivateGroup(gid, options) {
+    const primary = options.gid ?? process.getgid?.();
+    let name = options.userName;
+    if (name === undefined) {
+        try {
+            name = userInfo().username;
+        }
+        catch {
+            return false;
+        }
+    }
+    const groupText = options.groupFile === undefined ? readOr("/etc/group") : options.groupFile;
+    const passwdText = options.passwdFile === undefined ? readOr("/etc/passwd") : options.passwdFile;
+    if (primary === undefined || gid !== primary || groupText === null || passwdText === null)
+        return false;
+    const rows = (text) => text.split("\n").map((line) => line.split(":"));
+    const groups = rows(groupText).filter((fields) => fields.length >= 4 && fields[2] !== "" && Number(fields[2]) === gid);
+    if (groups.length !== 1 || groups[0][0] !== name)
+        return false;
+    const members = groups[0][3].split(",").map((member) => member.trim()).filter(Boolean);
+    if (!members.every((member) => member === name))
+        return false;
+    const accounts = rows(passwdText).filter((fields) => fields.length >= 4 && fields[3] !== "" && Number(fields[3]) === gid);
+    return accounts.length === 1 && accounts[0][0] === name && Number(accounts[0][2]) === options.uid;
+}
+/**
+ * Round 4: ONE resolver, walking `dir` as the kernel does — from `/`, one component at a time. Every
+ * directory ENTERED is judged (the marketplace directory and its `agent-board` parent strictly; every
+ * other by the ancestor rules). A symlink component is judged by its own owner (its containing
+ * directory was judged when entered), and its `readlink` is spliced into the remaining components
+ * (absolute → from `/`, relative → from the current directory), so EVERY hop's containing
+ * directory is judged, however many hops there are. More than `MAX_SYMLINK_HOPS` links is a loop:
+ * refused. The walk stops at the first missing component: what setup will create. The marketplace
+ * directory and its parent are the last two components however the path is spliced, and neither may
+ * be a symlink. On win32 (no uid, no POSIX mode) only that symlink rule applies.
+ */
+export function resolveTrustChain(dir, options) {
+    const windows = (options.platform ?? process.platform) === "win32";
+    const lstat = options.lstat ?? ((path) => lstatSync(path));
+    const readlink = options.readlink ?? ((path) => readlinkSync(path));
+    const target = resolve(dir);
+    const visited = [];
+    const done = (problem) => ({ problem, visited });
+    if (windows) {
+        for (const path of [dirname(target), target]) {
+            try {
+                if (lstat(path).isSymbolicLink())
+                    return done({ path, cause: "symlink", tightenable: false });
+            }
+            catch {
+                break;
+            }
+        }
+        return done(null);
+    }
+    const ownedOrRoot = (stats) => stats.uid === options.uid || stats.uid === 0;
+    const judge = (path, stats, own) => {
+        const root = stats.uid === 0;
+        if (own ? stats.uid !== options.uid : !ownedOrRoot(stats))
+            return { path, cause: "foreign_owner", tightenable: false };
+        const worldWritable = (stats.mode & 0o002) !== 0;
+        const groupWritable = (stats.mode & 0o020) !== 0;
+        if (!worldWritable && !groupWritable)
+            return null;
+        if (!own && root && (stats.mode & 0o1000) !== 0)
+            return null; // /tmp
+        if (!own && !worldWritable && stats.uid === options.uid && isPrivateGroup(stats.gid, options))
+            return null;
+        return { path, cause: "writable", tightenable: own, command: `chmod ${worldWritable && groupWritable ? "go-w" : worldWritable ? "o-w" : "g-w"} ${path}` };
+    };
+    const enter = (path, role) => {
+        const stats = lstat(path);
+        if (!stats.isDirectory())
+            return { path, cause: "not_directory", tightenable: false };
+        const problem = judge(path, stats, role !== "ancestor");
+        if (problem)
+            return problem;
+        visited.push({ path, dev: stats.dev ?? -1, ino: stats.ino ?? -1, role });
+        return null;
+    };
+    const rootProblem = enter("/", "ancestor");
+    if (rootProblem)
+        return done(rootProblem);
+    let current = "/";
+    const queue = target.split("/").filter(Boolean);
+    let hops = 0;
+    while (queue.length > 0) {
+        const name = queue.shift();
+        // The tail is never spliced (a symlink there is refused), so the last two are always ours.
+        const role = queue.length === 0 ? "dir" : queue.length === 1 ? "parent" : "ancestor";
+        if (name === ".")
+            continue;
+        if (name === "..") {
+            current = dirname(current);
+            continue;
+        }
+        const path = current === "/" ? `/${name}` : `${current}/${name}`;
+        let link;
+        try {
+            link = lstat(path);
+        }
+        catch {
+            break; // missing from here down: what setup creates
+        }
+        if (link.isSymbolicLink()) {
+            if (role !== "ancestor")
+                return done({ path, cause: "symlink", tightenable: false });
+            if (!ownedOrRoot(link))
+                return done({ path, cause: "foreign_owner", tightenable: false });
+            if (++hops > MAX_SYMLINK_HOPS)
+                return done({ path, cause: "symlink_loop", tightenable: false });
+            let to;
+            try {
+                to = readlink(path);
+            }
+            catch {
+                return done({ path, cause: "not_directory", tightenable: false });
+            }
+            if (to.startsWith("/"))
+                current = "/";
+            queue.unshift(...to.split("/").filter(Boolean));
+            continue;
+        }
+        const problem = enter(path, role);
+        if (problem)
+            return done(problem);
+        current = path;
+    }
+    return done(null);
+}
+/** The first untrusted path, or null (see `resolveTrustChain`). */
+export function checkTrustChain(dir, options) {
+    return resolveTrustChain(dir, options).problem;
+}
+/** The human words for a trust problem, for a `fix`. */
+export function describeTrustProblem(problem) {
+    const words = {
+        symlink: "is a symlink",
+        not_directory: "is not a directory",
+        foreign_owner: "is owned by another user",
+        writable: "is writable by other users",
+        symlink_loop: `resolves through more than ${MAX_SYMLINK_HOPS} symlinks (a loop)`,
+    };
+    return `${problem.path} ${words[problem.cause]}${problem.command ? ` (run \`${problem.command}\`)` : ""}`;
+}
+/** The version in a marketplace tree's `plugins/agent-board/.claude-plugin/plugin.json`, or null. */
+export function pluginVersionIn(files) {
+    const file = files.get("plugins/agent-board/.claude-plugin/plugin.json");
+    if (!file)
+        return null;
+    try {
+        const version = JSON.parse(file.bytes.toString("utf8"))?.version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `x.y.z` numeric comparison (sign), or null when either side is not a plain release version. */
+export function compareVersions(a, b) {
+    const parse = (value) => (value !== null && /^\d+\.\d+\.\d+$/.test(value) ? value.split(".").map(Number) : null);
+    const x = parse(a);
+    const y = parse(b);
+    if (x === null || y === null)
+        return null;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return Math.sign(x[i] - y[i]);
+    return 0;
+}

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
-import { type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt } from "@consiliency/agent-board-client";
+import { createAgentBoardClient, type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt, resolveCredentials } from "@consiliency/agent-board-client";
 import { type DoctorOptions, type DoctorReport } from "./doctor.js";
+import { type SetupEnroller, type SetupRunner } from "./setup.js";
 import { DevicePendingEnrollmentStore } from "./enroll_runtime.js";
 type JsonObject = Record<string, unknown>;
 export interface CliIo {
@@ -208,6 +209,11 @@ export interface DefaultEnrollmentRunnerDeps {
     sessionUrl?: string;
     /** Anon apikey for the post-enroll board RPCs. Default: resolveEnrollPublishableKey(env). */
     publishableKey?: string;
+    /**
+     * SETUP: the key reference the `key` step produced, handed over directly (never an env var the
+     * user must set). Wins over `MESSAGE_BOARD_ENROLL_KEY_REFERENCE`. Default: env.
+     */
+    keyReference?: string;
     /** Clock (tests). Default: wall clock. */
     now?: () => number;
     /**
@@ -224,6 +230,11 @@ export interface DefaultEnrollmentRunnerDeps {
     };
 }
 export declare function defaultEnrollmentRunner(env?: NodeJS.ProcessEnv, deps?: DefaultEnrollmentRunnerDeps): EnrollmentCommandRunner;
+/**
+ * SETUP — the enrollment `agent-board setup` runs: this runner's device flow, built from setup's
+ * env with the `key` step's reference injected (never an env var the user must set).
+ */
+export declare const setupEnroller: SetupEnroller;
 /**
  * How each field of a `FleetOnboardingIntent` is turned from an argv string into the value
  * that goes on the wire and into the template (Consiliency/message-board#254).
@@ -306,6 +317,29 @@ type FleetTupleField = StringFieldsOf<FleetOnboardingIntent>;
 export declare const FLEET_TUPLE_DISPOSITION: Readonly<Record<FleetTupleField, FleetTupleDisposition>>;
 /** `runDoctor`'s shape; a seam so the exit-code wiring is testable without a live board. */
 export type DoctorRunner = (options: DoctorOptions) => Promise<DoctorReport>;
-export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner): Command;
-export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner): Promise<void>;
+/**
+ * SETUP IF-0-SETUP-1 — the global `--as <harness>`: which harness's identity FILE every command's
+ * credentials come from. The client is constructed before argv is parsed, so the choice is a
+ * holder the parse fills and the client's credential resolver reads at FIRST USE (see
+ * `fileAwareCredentials`). Unset, the resolver is today's env chain, unchanged.
+ */
+export interface CredentialSelection {
+    as?: string;
+}
+/**
+ * The lazy credential source. With `--as <h>`: `<h>`'s identity file through the client's trusted
+ * open, and ONLY the file — `fileIdentityEnv` strips every ambient identity and generic name, as
+ * doctor does, because `--as` is an explicit choice of the file. The runtime descriptor is ignored
+ * for the same reason. Without it: `resolveCredentials(descriptor, env)`, exactly as before.
+ */
+export declare function fileAwareCredentials(selection: CredentialSelection, env?: NodeJS.ProcessEnv): (descriptor?: Parameters<typeof resolveCredentials>[0]) => Promise<import("@consiliency/agent-board-client").ResolvedCredentials>;
+export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner, selection?: CredentialSelection, setup?: SetupRunner): Command;
+export interface RunCliOptions {
+    /** The env the default client's credential resolver reads. Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Extra options for the DEFAULT client (tests: a `dataSourceFactory`); never its resolver. */
+    clientOptions?: Omit<NonNullable<Parameters<typeof createAgentBoardClient>[0]>, "resolveCredentials">;
+    setup?: SetupRunner;
+}
+export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner, options?: RunCliOptions): Promise<void>;
 export {};

package/dist/cli.js

@@ -3,8 +3,9 @@ import { createHash, randomUUID } from "node:crypto";
 import * as nodeFs from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, assertIdentityHarness, identityFilePath, resolveHostSegment, identityConfigRoot, walkTrustedDirectory, IDENTITY_HARNESSES, CredentialResolutionError, } from "@consiliency/agent-board-client";
-import { formatDoctorReport, runDoctor } from "./doctor.js";
+import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, assertIdentityHarness, identityFilePath, resolveHostSegment, identityConfigRoot, walkTrustedDirectory, IDENTITY_HARNESSES, CredentialResolutionError, readIdentityFile, resolveCredentials, } from "@consiliency/agent-board-client";
+import { fileIdentityEnv, formatDoctorReport, runDoctor } from "./doctor.js";
+import { addSetupCommand, runSetup } from "./setup.js";
 import { identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, } from "./identity_writer.js";
 import { DevicePendingEnrollmentStore, FilePendingEnrollmentStore, FleetDeviceContinuationStore, makeBrowserOpener, prepareFleetRuntimeOutput, publishFinalizedFleetTemplate, } from "./enroll_runtime.js";
 function isRuntimeStatus(value) {
@@ -1628,11 +1629,15 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
     const boardFetch = deps.boardFetch ?? nodeFetchAdapter;
     // Post-enroll board-op wiring (raw Supabase domain): explicit /session URL + anon
     // apikey. Optional — absent preserves the ${boardUrl}/session default + no apikey.
-    const sessionUrl = deps.sessionUrl ?? resolveEnrollSessionUrl(env);
-    const publishableKey = deps.publishableKey ?? resolveEnrollPublishableKey(env);
+    // LAZY (SETUP): the runner is built before parsing, for every command, so constructing it
+    // reads nothing from env; each flow method resolves these when enrollment actually runs.
+    const sessionUrl = () => deps.sessionUrl ?? resolveEnrollSessionUrl(env);
+    const publishableKey = () => deps.publishableKey ?? resolveEnrollPublishableKey(env);
+    // SETUP: the `key` step's reference is injected, and wins over env.
+    const descriptorOf = () => resolveEnrollmentDescriptor(env, deps.keyReference === undefined ? {} : { keyReference: deps.keyReference });
     return {
         async run(input) {
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
             const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env, {
                 ...(input.intent.kind === "fleet_onboarding" ? { fleetOnboarding: input.intent } : {}),
@@ -1649,14 +1654,14 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 keystore,
                 boardFetch,
                 keystoreBackends: keystore.backends,
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 openAuthorization,
                 now: deps.now,
             });
         },
         async device(input) {
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             // Fail CLEAN and actionable when the host descriptor carries no device
             // endpoint — otherwise the shared flow throws a bare `no_device_endpoint`.
             // The endpoint is optional in resolveEnrollmentDescriptor (it is not required
@@ -1684,15 +1689,15 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 keystore,
                 boardFetch,
                 keystoreBackends: keystore.backends,
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 onDeviceAuthorization: input.onDeviceAuthorization,
                 sleep: deps.sleep,
                 now: deps.now,
             });
         },
         async deviceBegin(input) {
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             if (!descriptor.issuer.deviceAuthorizationEndpoint) {
                 throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT)");
             }
@@ -1703,8 +1708,8 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                     ...(input.intent.kind === "fleet_onboarding" ? { fleetOnboarding: input.intent } : {}),
                 }),
                 boardFetch,
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 onDeviceAuthorization: async () => { },
                 now: deps.now,
             });
@@ -1776,12 +1781,12 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 if (pending.slug !== input.expectedFleet.slug) {
                     throw new EnrollmentCommandError("fleet_device_slug_mismatch", "device enrollment agent slug does not match");
                 }
-                const currentReference = normalizeKeyReference(resolveEnrollmentDescriptor(env).keyReference);
+                const currentReference = normalizeKeyReference(descriptorOf().keyReference);
                 if (`${currentReference.resolver}:${currentReference.handle}` !== input.expectedFleet.keyReference) {
                     throw new EnrollmentCommandError("fleet_device_key_reference_mismatch", "device enrollment key reference does not match current configuration");
                 }
             }
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             if (!descriptor.issuer.deviceAuthorizationEndpoint) {
                 throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT)");
             }
@@ -1809,8 +1814,8 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 keystore,
                 boardFetch,
                 keystoreBackends: keystore.backends,
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 onDeviceAuthorization: async () => { },
                 sleep: deps.sleep,
                 now: deps.now,
@@ -1846,7 +1851,7 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
         async begin(input) {
             // Force OOB: a loopback receiver cannot bridge two separate CLI processes, so
             // the two-step path is always out-of-band paste (no redirectUri ⇒ OOB).
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             const store = deps.store ?? new FilePendingEnrollmentStore(env);
             return beginEnrollment({
                 descriptor,
@@ -1861,13 +1866,13 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 clientId: descriptor.issuer.clientId,
                 // #173 — pass the provisioning config so begin refuses a doomed raw-Supabase
                 // enrollment BEFORE the human is asked to approve anything.
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 now: deps.now,
             });
         },
         async complete(input) {
-            const descriptor = resolveEnrollmentDescriptor(env);
+            const descriptor = descriptorOf();
             const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
             const store = deps.store ?? new FilePendingEnrollmentStore(env);
             const pending = await store.get(input.enrollmentId);
@@ -1885,13 +1890,21 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 keystore,
                 boardFetch,
                 keystoreBackends: keystore.backends,
-                sessionUrl,
-                publishableKey,
+                sessionUrl: sessionUrl(),
+                publishableKey: publishableKey(),
                 now: deps.now,
             });
         },
     };
 }
+/**
+ * SETUP — the enrollment `agent-board setup` runs: this runner's device flow, built from setup's
+ * env with the `key` step's reference injected (never an env var the user must set).
+ */
+export const setupEnroller = async (input) => {
+    const runner = defaultEnrollmentRunner(input.env, { keyReference: input.keyReference });
+    return (await runner.device({ slug: input.slug, intent: input.intent, onDeviceAuthorization: input.onDeviceAuthorization }));
+};
 function intentFromOptions(options) {
     if (options.board === false) {
         return { kind: "none" };
@@ -3199,11 +3212,33 @@ function addDoctorCommand(program, io, doctor) {
         process.exitCode = report.exit;
     });
 }
-export function createProgram(client, io, enrollment = defaultEnrollmentRunner(), doctor = runDoctor) {
+/**
+ * The lazy credential source. With `--as <h>`: `<h>`'s identity file through the client's trusted
+ * open, and ONLY the file — `fileIdentityEnv` strips every ambient identity and generic name, as
+ * doctor does, because `--as` is an explicit choice of the file. The runtime descriptor is ignored
+ * for the same reason. Without it: `resolveCredentials(descriptor, env)`, exactly as before.
+ */
+export function fileAwareCredentials(selection, env = process.env) {
+    return async (descriptor) => {
+        const harness = selection.as;
+        if (harness === undefined)
+            return resolveCredentials(descriptor, env);
+        assertIdentityHarness(harness);
+        const { values } = await readIdentityFile({ harness, env });
+        return resolveCredentials(undefined, fileIdentityEnv(env, values));
+    };
+}
+export function createProgram(client, io, enrollment = defaultEnrollmentRunner(), doctor = runDoctor, selection = {}, setup) {
     const program = new Command()
         .name("agent-board")
         .description("Thin CLI surface for the agent_board RPC and canonical read contracts")
+        .option("--as <harness>", "take credentials from this harness's identity file (agy, claude, codex, grok, opencode, pi), ignoring any identity in the environment")
         .addHelpText("after", "\nAuth: user-scoped agent sessions are the default. Service-role execution is reserved for callback workers and vetted operational scripts through explicit client configuration, not the normal agent CLI path. Signing configuration is inherited from metadata-safe descriptors; raw private-key arguments are not accepted.\n");
+    // Filled at parse time, read by the client's resolver at first use.
+    program.hook("preAction", () => {
+        const chosen = program.opts().as;
+        selection.as = chosen;
+    });
     program
         .command("signing-status")
         .description("Print metadata-safe signing descriptor status; raw private-key arguments are not accepted")
@@ -3224,12 +3259,19 @@ export function createProgram(client, io, enrollment = defaultEnrollmentRunner()
     addInviteCommands(program, client, io);
     addEnrollCommands(program, io, enrollment);
     addDoctorCommand(program, io, doctor);
+    addSetupCommand(program, io, setup ?? ((options) => runSetup(options, { enroll: setupEnroller })));
     return program;
 }
 export async function runCli(argv, io = {
     writeStdout: (message) => process.stdout.write(message),
     writeStderr: (message) => process.stderr.write(message),
-}, client = createAgentBoardClient(), enrollment = defaultEnrollmentRunner(), doctor = runDoctor) {
-    const program = createProgram(client, io, enrollment, doctor);
+}, client, enrollment = defaultEnrollmentRunner(), doctor = runDoctor, options = {}) {
+    const selection = {};
+    // Built BEFORE parsing, as always; `--as` reaches it through `selection` at first use.
+    const resolved = client ?? createAgentBoardClient({
+        ...options.clientOptions,
+        resolveCredentials: fileAwareCredentials(selection, options.env ?? process.env),
+    });
+    const program = createProgram(resolved, io, enrollment, doctor, selection, options.setup);
     await program.parseAsync(argv, { from: "user" });
 }

package/dist/config_edit.d.ts

@@ -0,0 +1,37 @@
+/** What an edit found and produced. `text` equals the input when `prior` is `exact`. */
+export interface ConfigEdit {
+    prior: "absent" | "exact" | "differs";
+    text: string;
+}
+/** A refusal: the reason is an authored code, never file content. */
+export declare class ConfigEditRefused extends Error {
+    readonly reason: "config_unparseable" | "config_layout_unrecognised" | "config_not_an_object" | "config_inline_table" | "config_array_table";
+    constructor(reason: "config_unparseable" | "config_layout_unrecognised" | "config_not_an_object" | "config_inline_table" | "config_array_table");
+}
+/** A value an entry may carry: what setup writes, plus whatever a user kept in the entry. */
+export type ConfigValue = string | number | boolean | readonly ConfigValue[] | {
+    readonly [key: string]: ConfigValue;
+};
+export type ConfigEntry = {
+    readonly [key: string]: ConfigValue;
+};
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** The block setup writes for `path` (a table header plus one line per key, in the entry's order). */
+export declare function renderTomlTable(path: readonly string[], entry: ConfigEntry): string;
+/**
+ * Put `entry` at the table `path` (e.g. `["mcp_servers", "agent-board"]`) of a TOML document.
+ * Absent → appended as its own block; equal → the text unchanged; different → the table's own
+ * block(s) (its header, its sub-tables' headers, and their keys) replaced in place by the rendered
+ * block. Keys defined for it any other way (a dotted key under a parent table, an inline table)
+ * are a layout this edit does not own: refused, never appended beside.
+ */
+export declare function upsertTomlTable(text: string, path: readonly string[], entry: ConfigEntry): ConfigEdit;
+/**
+ * Put `entry` at `path` of a JSON/JSONC object document. Empty text is an empty object. Missing
+ * intermediate objects are created; an existing member is replaced in its span; a new member is
+ * inserted before its object's closing brace. `strict` also requires the input to be plain JSON,
+ * for a harness whose reader is strict (an edit never makes a file unreadable to its harness).
+ */
+export declare function upsertJsonMember(text: string, path: readonly string[], entry: ConfigEntry, options?: {
+    strict?: boolean;
+}): ConfigEdit;