@consiliency/agent-board-cli 1.8.0 → 1.10.0

package/dist/cli.js

@@ -1,6 +1,9 @@
 import { Command, Option } from "commander";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, runEnrollment, resolveEnrollmentDescriptor, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, nodeFetchAdapter, buildEnrollKeystore, } from "@consiliency/agent-board-client";
-import { FilePendingEnrollmentStore, makeBrowserOpener } from "./enroll_runtime.js";
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeKeyReference, enrollCommitMarker, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, } from "@consiliency/agent-board-client";
+import { DevicePendingEnrollmentStore, FilePendingEnrollmentStore, FleetDeviceContinuationStore, makeBrowserOpener, prepareFleetRuntimeOutput, publishFinalizedFleetTemplate, } from "./enroll_runtime.js";
 function isRuntimeStatus(value) {
     return Boolean(value && typeof value === "object" && "runtime" in value);
 }
@@ -13,13 +16,200 @@ function parseJson(value) {
 function numberOption(flags, description) {
     return new Option(flags, description).argParser((value) => Number(value));
 }
-async function runHandler(io, operation, action) {
+/**
+ * A fleet failure whose message this CLI CONSTRUCTED and therefore knows to be free of
+ * bearer codes, key material and local key handles. The blanket fleet redaction below
+ * exists because a raw error can carry an `os_keychain[<handle>]` descriptor; it must
+ * not also flatten the messages we wrote ourselves, or an actionable pre-flight refusal
+ * reaches the operator as an unactionable "failed before completion".
+ */
+class FleetSafeMessageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "FleetSafeMessageError";
+    }
+}
+/**
+ * Raised BEFORE any server call — the enrollment has not committed and the bounded
+ * invite use is not spent. The message names the environment variable, never its value.
+ */
+class FleetPreflightError extends FleetSafeMessageError {
+}
+/**
+ * Raised AFTER the server committed the enrollment: identity, signing key, harness
+ * registration, repo scope, fleet binding and membership exist and the bounded invite
+ * use is SPENT. Reporting such a failure as "before completion" is the
+ * Consiliency/message-board#176 shape — it tells the operator to retry an enrollment
+ * that already happened, against an invite that may have no uses left.
+ *
+ * The detail is withheld unless the cause is itself a message we constructed: a raw
+ * post-commit error can carry a local key descriptor, which is exactly what the
+ * blanket redaction is for.
+ */
+class FleetPostCommitError extends FleetSafeMessageError {
+    constructor(committedFacts, cause) {
+        // Only the ids that survived. Region-1 facts are deliberately sparse — that region
+        // renders what this process KNEW rather than what the response echoed — so a fixed
+        // four-field list would print `agentId=,` and read as data while carrying none.
+        const committed = renderIds(committedFacts) || "(the receipt carried no id we could verify)";
+        const detail = cause instanceof FleetSafeMessageError
+            ? cause.message
+            : `detail withheld (a raw local failure can carry key descriptors)${namedCauseCode(cause)}`;
+        super("fleet_onboarding_committed_local_finalization_failed", "fleet enrollment COMMITTED on the server; only local finalization failed. "
+            + "Do NOT treat this as a failed enrollment and do NOT re-run it — the bounded invite use is spent. "
+            + `Committed: ${committed}. Local finalization failure: ${detail}`);
+        this.cause = cause;
+    }
+}
+/**
+ * Name WHICH check failed without letting the cause's free text across the boundary.
+ * The enrollment codes are a closed vocabulary we author (`fleet_onboarding_contract_
+ * mismatch` et al.), so an operator facing a rollout skew learns something actionable;
+ * the shape gate is what keeps it from becoming a message channel. It is a gate on the
+ * VALUE, not an `instanceof EnrollError`: a cross-package `instanceof` is silently
+ * false when the workspace holds two copies of the client module.
+ */
+function namedCauseCode(cause) {
+    if (!cause || typeof cause !== "object")
+        return "";
+    const code = cause.code;
+    // Lower-case snake_case only: our own codes match, and a key descriptor
+    // (`os_keychain[handle]`), a path, or an upper-case OS errno does not.
+    if (typeof code !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(code))
+        return "";
+    return ` [code ${code}]`;
+}
+function committedFactsFromOutcome(outcome) {
+    return {
+        agentId: outcome.agentId,
+        agentHandle: outcome.agentHandle,
+        keyId: outcome.keyId,
+        boardId: outcome.onboarding?.boardId ?? "",
+        machineId: outcome.onboarding?.machineId ?? "",
+    };
+}
+/**
+ * Everything inside `action` runs against a COMMITTED server enrollment. Marks any
+ * failure so the redaction below reports it truthfully instead of asserting it happened
+ * before completion.
+ */
+async function afterFleetCommit(outcome, action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        throw error instanceof FleetPostCommitError ? error : new FleetPostCommitError(committedFactsFromOutcome(outcome), error);
+    }
+}
+/**
+ * Render only the ids that are actually present. An all-empty list (`agentId=,
+ * agentHandle=,`) is the shape both messages exist to avoid printing: it reads as
+ * evidence while carrying none.
+ */
+function renderIds(facts) {
+    // Gated HERE, at the single render point, rather than at each producer. There are two
+    // producers of these facts — the client's marker (already normalized) and
+    // `committedFactsFromOutcome` below (straight from the outcome, never normalized) —
+    // and the type carries a stated invariant that a non-id-shaped value is not rendered.
+    // A per-producer gate makes that invariant a thing each new producer must remember;
+    // gating the render makes it hold for producers that do not exist yet. Without it a
+    // poisoned `agent_id` in an otherwise contract-valid receipt reaches stdout verbatim,
+    // newlines and all.
+    const printable = (value) => /^[A-Za-z0-9._:@/+=-]{1,128}$/.test(value);
+    // `agentId` gets a TYPED gate, not the generic one, and the asymmetry is deliberate.
+    //
+    // Of the four fields, three are already tied to something this process sent: the
+    // receipt check requires `board_id`/`machine_id`/`agent_handle` to EQUAL the
+    // authorized tuple, so a contract-valid receipt cannot carry a surprise there — the
+    // validation does what region 1 achieves by construction. `agent_id` is the one field
+    // the contract constrains only as non-empty, so it is the one place a receipt can
+    // carry an arbitrary server-chosen string into an operator's terminal, including a
+    // value we ourselves sent (the invite code) echoed back.
+    //
+    // The schema declares it: `agents.id uuid primary key`. So a non-UUID `agent_id` is
+    // off-contract, and rendering it as an agent id would be rendering something this
+    // field cannot legitimately be. This is a type check derived from the contract, not a
+    // guess at what "looks like an id".
+    //
+    // Residual, stated rather than implied: an on-path attacker who can forge a
+    // contract-valid receipt can also supply a well-formed UUID. No client-side check
+    // closes that; it needs a signature over the response.
+    const isUuid = (value) => /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(value);
+    return [
+        ["agentId", facts.agentId, isUuid],
+        ["agentHandle", facts.agentHandle, printable],
+        ["boardId", facts.boardId, printable],
+        ["machineId", facts.machineId, printable],
+    ].filter(([, value, ok]) => value !== "" && ok(value)).map(([key, value]) => `${key}=${value}`).join(", ");
+}
+/**
+ * Raised when the server's answer was OFF-CONTRACT, so whether it committed is unknown.
+ * This is the third state, and it exists because both of the other two would be a lie:
+ * "COMMITTED" tells the operator not to retry an enrollment that may never have
+ * happened and to write off an invite use that may be unspent, and "failed before
+ * completion" is the #176 shape. The operator is told what to verify instead of what to
+ * assume. As with the post-commit error, the cause's free text is withheld.
+ */
+class FleetIndeterminateError extends FleetSafeMessageError {
+    constructor(marker, cause) {
+        // Only the ids that actually survived. An all-empty list (`agentId=, agentHandle=`)
+        // is the shape this state exists to stop printing — it reads as data while carrying
+        // none, and on the off-contract path there is frequently nothing to show.
+        const rendered = renderIds(marker.facts);
+        const observed = rendered
+            ? ` What this enrollment asked for, to verify against: ${rendered}.`
+            : " Nothing about this enrollment could be corroborated, so there is no id here to verify against.";
+        super("fleet_onboarding_commit_indeterminate", 
+        // Covers both shapes: an off-contract status (201/202/204), and a 200 that carried
+        // no /enroll identity at all — a proxy or maintenance page the origin never saw.
+        `fleet enrollment status is UNKNOWN: the server answered HTTP ${marker.status ?? "(unknown)"} without a usable /enroll receipt. `
+            + "The enrollment MAY or MAY NOT have committed, and the bounded invite use may or may not be spent. "
+            + "Do NOT re-run it blindly: verify first whether the agent identity now exists on the board, and enroll again only if it does not."
+            + observed);
+        this.cause = cause;
+    }
+}
+/**
+ * The enrollment call ITSELF (Consiliency/message-board#202). `afterFleetCommit` can only
+ * fence what follows the runner, but the runner commits INSIDE its own call: the /enroll
+ * POST returns 200 and the contract checks, receipt check and pending-store cleanup all
+ * run after it. Such a failure surfaced out of the runner, missed the fence entirely, and
+ * was flattened into "failed before completion" — telling the operator to re-run an
+ * enrollment that already happened, against an invite whose bounded use is spent.
+ *
+ * The client marks those errors at the 200-response boundary, where the truth is known;
+ * this converts the marker into the CLI's own truthful message. Errors with no marker are
+ * genuinely pre-commit and keep the blanket redaction. `runHandler` is unchanged — it
+ * still exempts exactly `FleetSafeMessageError` and nothing else.
+ */
+async function throughFleetCommit(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        const marker = enrollCommitMarker(error);
+        if (!marker)
+            throw error;
+        throw marker.state === "indeterminate"
+            ? new FleetIndeterminateError(marker, error)
+            : new FleetPostCommitError(marker.facts, error);
+    }
+}
+async function runHandler(io, operation, action, redactFleetFailure = false) {
     try {
         const result = await action();
         io.writeStdout(`${JSON.stringify(result, null, 2)}\n`);
     }
     catch (error) {
-        io.writeStdout(`${JSON.stringify(toOperationFailure(operation, error), null, 2)}\n`);
+        const failure = toOperationFailure(operation, error);
+        // Redact only what we did not write. A post-commit failure keeps its truthful
+        // message; a pre-flight refusal keeps the variable name the operator must set.
+        if (redactFleetFailure && !(error instanceof FleetSafeMessageError)) {
+            failure.error.message = "fleet enrollment failed before completion";
+        }
+        io.writeStdout(`${JSON.stringify(failure, null, 2)}\n`);
         process.exitCode = 1;
     }
 }
@@ -1212,6 +1402,10 @@ const processWriter = {
     writeStdout: (message) => process.stdout.write(message),
     writeStderr: (message) => process.stderr.write(message),
 };
+function defaultDevicePendingStateDir(env) {
+    const configured = env.XDG_STATE_HOME?.trim();
+    return join(configured || join(homedir(), ".local", "state"), "agent-board", "pending-device-enroll");
+}
 // The default runner drives the live enrollment flow: `run` = one-shot loopback +
 // browser opener; `begin`/`complete` = headless OOB two-step bridged by a
 // file-backed store (loopback cannot span two CLI processes). Every seam is
@@ -1227,7 +1421,9 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
         async run(input) {
             const descriptor = resolveEnrollmentDescriptor(env);
             const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
-            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env);
+            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env, {
+                ...(input.intent.kind === "fleet_onboarding" ? { fleetOnboarding: input.intent } : {}),
+            });
             const openAuthorization = deps.openAuthorization ?? makeBrowserOpener(deps.io ?? processWriter);
             return runEnrollment(descriptor, input.intent, {
                 slug: input.slug,
@@ -1246,6 +1442,193 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 now: deps.now,
             });
         },
+        async device(input) {
+            const descriptor = resolveEnrollmentDescriptor(env);
+            // 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
+            // for the auth-code paths), so a headless operator must set it explicitly.
+            if (!descriptor.issuer.deviceAuthorizationEndpoint) {
+                throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT, e.g. https://portal.consiliency.io/api/oauth/device_authorization)");
+            }
+            // Post-token deps are reconstructed EXACTLY as `run` does (rule #1): keystore,
+            // keystoreBackends, boardFetch, enrollEndpoint, sessionUrl, publishableKey. A
+            // dropped sessionUrl/publishableKey breaks the post-enroll board op on a raw-
+            // Supabase board — pinned by the device analogue of the `run` e2e (drop either
+            // and the sessionUrl-override / anon-apikey assertion fails).
+            const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
+            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env, {
+                ...(input.intent.kind === "fleet_onboarding" ? { fleetOnboarding: input.intent } : {}),
+            });
+            return runDeviceEnrollment(descriptor, input.intent, {
+                slug: input.slug,
+                agentKind: input.agentKind,
+                requestedScopes: input.requestedScopes,
+                requestedBoardScopes: input.requestedBoardScopes,
+            }, {
+                fetch,
+                enrollEndpoint,
+                keystore,
+                boardFetch,
+                keystoreBackends: keystore.backends,
+                sessionUrl,
+                publishableKey,
+                onDeviceAuthorization: input.onDeviceAuthorization,
+                sleep: deps.sleep,
+                now: deps.now,
+            });
+        },
+        async deviceBegin(input) {
+            const descriptor = resolveEnrollmentDescriptor(env);
+            if (!descriptor.issuer.deviceAuthorizationEndpoint) {
+                throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT)");
+            }
+            const continuation = await beginDeviceEnrollment(descriptor, input.intent, {
+                fetch,
+                enrollEndpoint: deps.enrollEndpoint ?? resolveEnrollEndpoint(env),
+                keystore: deps.keystore ?? buildEnrollKeystore(descriptor, env, {
+                    ...(input.intent.kind === "fleet_onboarding" ? { fleetOnboarding: input.intent } : {}),
+                }),
+                boardFetch,
+                sessionUrl,
+                publishableKey,
+                onDeviceAuthorization: async () => { },
+                now: deps.now,
+            });
+            const enrollmentId = input.enrollmentId ?? `enr-${randomUUID()}`;
+            const store = deps.deviceStore ?? new DevicePendingEnrollmentStore(defaultDevicePendingStateDir(env));
+            await store.put({
+                flow: "device_code",
+                enrollmentId,
+                deviceCode: continuation.deviceCode,
+                interval: continuation.prompt.interval,
+                expiresAt: continuation.expiresAt,
+                expiresIn: continuation.prompt.expiresIn,
+                userCode: continuation.prompt.userCode,
+                verificationUri: continuation.prompt.verificationUri,
+                verificationUriComplete: continuation.prompt.verificationUriComplete,
+                intent: input.intent,
+                slug: input.slug,
+                agentKind: input.agentKind,
+                requestedScopes: input.requestedScopes,
+                requestedBoardScopes: input.requestedBoardScopes,
+            });
+            return { enrollmentId, prompt: continuation.prompt };
+        },
+        async deviceComplete(input) {
+            const store = deps.deviceStore ?? new DevicePendingEnrollmentStore(defaultDevicePendingStateDir(env));
+            const pending = await store.get(input.enrollmentId);
+            if (!pending) {
+                throw new EnrollmentCommandError("unknown_device_enrollment", "device enrollment is unknown");
+            }
+            // Consiliency/message-board#210 — the READ door for the DEVICE store, symmetric with
+            // `completeEnrollment`'s (enroll_command.ts). Keyed on the intent READ FROM THE
+            // STORE, never on the caller's flag: `enroll device --enrollment-id <id>` without
+            // --fleet-onboarding passes no `expectedFleet`, and every fleet check below is gated
+            // on it, so a fleet pending would be handed to completeDeviceEnrollment and
+            // COMMITTED with no publishable-key pre-flight, no runtime output, no finalization
+            // and no post-commit fence — and then deleted below, destroying the correct resume's
+            // own state.
+            //
+            // The pending is deliberately NOT deleted: the operator's recovery is to re-run the
+            // same resume WITH the flag, and that needs this record. Deleting here would make
+            // the refusal as destructive as the bug.
+            //
+            // This is the missing direction of a biconditional: `expectedFleet` present against
+            // a non-fleet pending already throws below. Fleet-ness of the PENDING decides; the
+            // flag must agree with it in both directions.
+            //
+            // Placement is load-bearing three ways: AFTER the `!pending` throw (an unknown id
+            // keeps `unknown_device_enrollment`), BEFORE the descriptor/keystore/endpoint work
+            // below (no local side effects), and BEFORE any network call (the device
+            // authorization is not spent).
+            if (pending.intent.kind === "fleet_onboarding" && !input.expectedFleet) {
+                throw new FleetPreflightError("fleet_device_resume_requires_fleet_flag", "this pending device enrollment is a fleet onboarding and cannot be resumed without "
+                    + "--fleet-onboarding: that flag is what performs the publishable-key pre-flight, the "
+                    + "runtime output and the fleet finalization. Nothing was committed and the pending "
+                    + "was kept. Re-run the same resume with --fleet-onboarding, the same bounded tuple "
+                    + "(--board-id/--machine-id/--harness-kind/--harness-label/--repo-slug/"
+                    + "--repo-fingerprint/--repo-scope-role/--agent-role/--expected-agent-handle/"
+                    + "--local-key-id), --slug and --runtime-output.");
+            }
+            if (input.expectedFleet) {
+                if (pending.intent.kind !== "fleet_onboarding") {
+                    throw new EnrollmentCommandError("fleet_device_intent_mismatch", "device enrollment is not a fleet enrollment");
+                }
+                const { inviteCode: _inviteCode, ...storedIntent } = pending.intent;
+                if (JSON.stringify(storedIntent) !== JSON.stringify(input.expectedFleet.intent)) {
+                    throw new EnrollmentCommandError("fleet_device_intent_mismatch", "device enrollment fleet bounds do not match");
+                }
+                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);
+                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);
+            if (!descriptor.issuer.deviceAuthorizationEndpoint) {
+                throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT)");
+            }
+            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env, {
+                ...(pending.intent.kind === "fleet_onboarding" ? { fleetOnboarding: pending.intent } : {}),
+            });
+            const result = await completeDeviceEnrollment(descriptor, pending.intent, {
+                slug: pending.slug,
+                agentKind: pending.agentKind,
+                requestedScopes: pending.requestedScopes,
+                requestedBoardScopes: pending.requestedBoardScopes,
+            }, {
+                deviceCode: pending.deviceCode,
+                expiresAt: pending.expiresAt,
+                prompt: {
+                    userCode: pending.userCode,
+                    verificationUri: pending.verificationUri,
+                    verificationUriComplete: pending.verificationUriComplete,
+                    expiresIn: pending.expiresIn,
+                    interval: pending.interval,
+                },
+            }, {
+                fetch,
+                enrollEndpoint: deps.enrollEndpoint ?? resolveEnrollEndpoint(env),
+                keystore,
+                boardFetch,
+                keystoreBackends: keystore.backends,
+                sessionUrl,
+                publishableKey,
+                onDeviceAuthorization: async () => { },
+                sleep: deps.sleep,
+                now: deps.now,
+            });
+            // POST-COMMIT and unmarked: `completeDeviceEnrollment` above has returned, so the
+            // enrollment is committed and this delete is local cleanup on top of it.
+            //
+            // An earlier version of this comment said the fleet path DOES reach here, via the
+            // resume that omits `--fleet-onboarding`. That premise died with
+            // Consiliency/message-board#210: the guard at the top of this method refuses a fleet
+            // pending whose caller passed no `expectedFleet`, before any network call, and the
+            // CLI's fleet resume passes `deletePending: false`. Neither CLI branch arrives here
+            // with a fleet enrollment.
+            //
+            // What remains is a DIRECT runner caller that supplies a fleet-guarded
+            // `expectedFleet` and lets `deletePending` default — a caller that has by
+            // construction already done the fleet pre-flight, and that is inside the CLI's fence
+            // only if it is the CLI.
+            //
+            // Marker decision, recorded rather than omitted: NO #202 marker here.
+            // `markEnrollCommitted`/`throughFleetCommit` exist to turn an error raised inside a
+            // committed call into a truthful post-commit message for a caller that HAS a fence.
+            // On the only path that still reaches this line there is no such fence to feed, so a
+            // marker would imply one that does not exist.
+            if (input.deletePending !== false)
+                await store.delete(input.enrollmentId);
+            return result;
+        },
+        async deviceDeletePending(input) {
+            const store = deps.deviceStore ?? new DevicePendingEnrollmentStore(defaultDevicePendingStateDir(env));
+            await store.delete(input.enrollmentId);
+        },
         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).
@@ -1259,13 +1642,24 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 requestedScopes: input.requestedScopes,
                 requestedBoardScopes: input.requestedBoardScopes,
                 redirectMode: "oob",
-            }, store, { fetch, clientId: descriptor.issuer.clientId, now: deps.now });
+            }, store, {
+                fetch,
+                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,
+                now: deps.now,
+            });
         },
         async complete(input) {
             const descriptor = resolveEnrollmentDescriptor(env);
             const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
-            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env);
             const store = deps.store ?? new FilePendingEnrollmentStore(env);
+            const pending = await store.get(input.enrollmentId);
+            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env, {
+                ...(pending?.intent.kind === "fleet_onboarding" ? { fleetOnboarding: pending.intent } : {}),
+            });
             return completeEnrollment({
                 enrollmentId: input.enrollmentId,
                 code: input.code,
@@ -1285,6 +1679,9 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
     };
 }
 function intentFromOptions(options) {
+    if (options.board === false) {
+        return { kind: "none" };
+    }
     if (options.joinBoard) {
         return { kind: "join_board", boardId: options.joinBoard };
     }
@@ -1305,6 +1702,203 @@ function csv(value) {
             .filter(Boolean)
         : undefined;
 }
+const DEFAULT_PUBLISHABLE_KEY_FIELD_REFERENCE = "MESSAGE_BOARD_ENROLL_PUBLISHABLE_KEY";
+/**
+ * Resolve the publishable key fleet finalization REQUIRES from this host's environment.
+ * The pre-flight (before any server call) and the post-commit finalization both go
+ * through this one function, so they cannot drift about which variable is read or what
+ * counts as present — the drift is what made a missing variable a post-commit failure.
+ */
+function resolveFleetPublishableKey(publishableKeyFieldReference) {
+    const reference = normalizePublishableKeyFieldReference(publishableKeyFieldReference ?? DEFAULT_PUBLISHABLE_KEY_FIELD_REFERENCE);
+    const value = process.env[reference]?.trim() ?? "";
+    if (!value) {
+        throw new FleetPreflightError("fleet_publishable_key_missing", `fleet onboarding requires the publishable key in this host's environment: export ${reference}=<project anon/publishable key>. `
+            + "The variable name was frozen at mint time by --publishable-key-field-reference.");
+    }
+    return value;
+}
+function buildPendingFleetTemplate(intent, publishableKeyFieldReference = DEFAULT_PUBLISHABLE_KEY_FIELD_REFERENCE) {
+    const suffix = `-${intent.harnessKind}`;
+    if (!intent.expectedAgentHandle.endsWith(suffix))
+        throw new Error("fleet_onboarding_expected_handle_invalid");
+    const host = intent.expectedAgentHandle.slice(0, -suffix.length);
+    const deployment = resolveJoinDeployment();
+    if (!deployment.keyReference)
+        throw new Error("fleet_onboarding_key_reference_missing");
+    const ref = normalizeKeyReference(deployment.keyReference);
+    const platform = ref.resolver === "os_keychain" ? "desktop" : ref.resolver === "agent_socket" ? "headless_linux" : null;
+    if (!platform)
+        throw new Error("fleet_onboarding_unsupported_key_reference");
+    const separator = ref.handle.lastIndexOf("#");
+    const pending = buildFleetHarnessTemplate({ host, harnessKind: intent.harnessKind, harnessLabel: intent.harnessLabel, platform,
+        boardId: intent.boardId, machineId: intent.machineId, repoSlug: intent.repoSlug, repoFingerprint: intent.repoFingerprint,
+        repoScopeRole: intent.repoScopeRole, agentRole: intent.agentRole, boardUrl: deployment.boardUrl, sessionUrl: deployment.sessionUrl ?? deployment.boardUrl,
+        publishableKeyFieldReference,
+        ...(platform === "headless_linux" ? { agentSocketPath: ref.handle.slice(0, separator), publicKeySelector: separator > 0 ? ref.handle.slice(separator + 1) : "" } : {}),
+    });
+    if (pending.localKeyId !== intent.localKeyId || pending.keyReference !== `${ref.resolver}:${ref.handle}`)
+        throw new Error("fleet_onboarding_local_key_mismatch");
+    return pending;
+}
+async function finalizeFleetOutcome(options, intent, result, frozenPending) {
+    if (intent.kind !== "fleet_onboarding")
+        return result;
+    if (!options.runtimeOutput)
+        throw new Error("--fleet-onboarding requires --runtime-output");
+    const outcome = result;
+    // LIVE, unlike its same-named twin in enroll_command.ts (message-board#212). That one
+    // sits after an `enrollAgent` call whose return shape the same function controls, so
+    // nothing can produce the state it tests. This one consumes whatever the INJECTED
+    // `EnrollmentCommandRunner` returned — a seam any `runCli` caller supplies — so a
+    // runner that resolves a fleet enrollment without its receipt reaches here. Verified by
+    // probe, not by reading. Do not delete it alongside the other one.
+    if (!outcome.onboarding)
+        throw new Error("fleet_onboarding_receipt_missing");
+    const ref = normalizeKeyReference(outcome.keyReference);
+    const pending = frozenPending ?? buildPendingFleetTemplate(intent, options.publishableKeyFieldReference);
+    if (pending.localKeyId !== intent.localKeyId || pending.keyReference !== `${ref.resolver}:${ref.handle}`)
+        throw new Error("fleet_onboarding_local_key_mismatch");
+    const fingerprint = ref.publicKeyFingerprint ?? `sha256:${createHash("sha256").update(Buffer.from(outcome.agentPublicKey, "base64url")).digest("base64url")}`;
+    const resolvedPublishableKey = resolveFleetPublishableKey(pending.publishableKeyFieldReference);
+    const finalized = finalizeFleetHarnessTemplate(pending, { ...outcome.onboarding, agentId: outcome.agentId, signingKeyId: outcome.signingKeyId, keyId: outcome.keyId, keyVersion: outcome.keyVersion, agentHandle: outcome.agentHandle }, { keyReference: pending.keyReference, publicKey: outcome.agentPublicKey, publicKeyFingerprint: fingerprint }, resolvedPublishableKey);
+    const published = await publishFinalizedFleetTemplate(options.runtimeOutput, finalized);
+    return { enrollment: fleetSafeOutput(outcome), materialization: { generation: published.generation, digest: published.digest } };
+}
+function fleetResumeIntentFromCli(options) {
+    const required = [
+        ["--slug", options.slug], ["--board-id", options.boardId], ["--machine-id", options.machineId],
+        ["--harness-kind", options.harnessKind], ["--harness-label", options.harnessLabel],
+        ["--repo-slug", options.repoSlug], ["--repo-fingerprint", options.repoFingerprint],
+        ["--repo-scope-role", options.repoScopeRole], ["--agent-role", options.agentRole],
+        ["--expected-agent-handle", options.expectedAgentHandle], ["--local-key-id", options.localKeyId],
+        ["--runtime-output", options.runtimeOutput],
+    ];
+    const missing = required.filter(([, value]) => !value?.trim()).map(([name]) => name);
+    if (missing.length)
+        throw new Error(`fleet device resume is missing: ${missing.join(", ")}`);
+    const pair = (options.agentRole === "phase_worker" && options.repoScopeRole === "worker")
+        || (options.agentRole === "reviewer" && options.repoScopeRole === "reviewer");
+    if (!pair)
+        throw new Error("fleet device resume allows only phase_worker/worker or reviewer/reviewer");
+    return {
+        kind: "fleet_onboarding", inviteCode: "",
+        boardId: options.boardId.trim(), machineId: options.machineId.trim(),
+        harnessKind: options.harnessKind.trim().toLowerCase(), harnessLabel: options.harnessLabel.trim(),
+        repoSlug: options.repoSlug.trim(), repoFingerprint: options.repoFingerprint.trim(),
+        repoScopeRole: options.repoScopeRole,
+        agentRole: options.agentRole,
+        expectedAgentHandle: options.expectedAgentHandle.trim(), localKeyId: options.localKeyId.trim(),
+    };
+}
+async function enrollmentIntentFromCli(options) {
+    if (!options.fleetOnboarding)
+        return intentFromOptions(options);
+    if (options.createBoard || options.joinBoard || options.board === false) {
+        throw new Error("--fleet-onboarding cannot be combined with --create-board, --join-board, or --no-board");
+    }
+    let inviteCode = options.inviteCode;
+    if (!inviteCode)
+        inviteCode = await readCodeFromStdin();
+    const required = [
+        ["invite code (stdin or --invite-code)", inviteCode],
+        ["--board-id", options.boardId], ["--machine-id", options.machineId],
+        ["--harness-kind", options.harnessKind], ["--harness-label", options.harnessLabel],
+        ["--repo-slug", options.repoSlug], ["--repo-fingerprint", options.repoFingerprint],
+        ["--repo-scope-role", options.repoScopeRole], ["--agent-role", options.agentRole],
+        ["--expected-agent-handle", options.expectedAgentHandle], ["--local-key-id", options.localKeyId],
+    ];
+    const missing = required.filter(([, value]) => !value?.trim()).map(([name]) => name);
+    if (missing.length)
+        throw new Error(`--fleet-onboarding is missing: ${missing.join(", ")}`);
+    const pair = (options.agentRole === "phase_worker" && options.repoScopeRole === "worker")
+        || (options.agentRole === "reviewer" && options.repoScopeRole === "reviewer");
+    if (!pair)
+        throw new Error("--fleet-onboarding allows only phase_worker/worker or reviewer/reviewer");
+    return {
+        kind: "fleet_onboarding",
+        inviteCode: inviteCode.trim(),
+        boardId: options.boardId.trim(),
+        machineId: options.machineId.trim(),
+        harnessKind: options.harnessKind.trim().toLowerCase(),
+        harnessLabel: options.harnessLabel.trim(),
+        repoSlug: options.repoSlug.trim(),
+        repoFingerprint: options.repoFingerprint.trim(),
+        repoScopeRole: options.repoScopeRole,
+        agentRole: options.agentRole,
+        expectedAgentHandle: options.expectedAgentHandle.trim(),
+        localKeyId: options.localKeyId.trim(),
+    };
+}
+/**
+ * Every field DECLARED on `FleetOnboardingReceipt` (including the nine it inherits from
+ * `FleetOnboardingBounds`) except `publicKeyFingerprint`, which is deliberately withheld.
+ *
+ * Consiliency/message-board#224 — this list exists because the receipt used to be rebuilt
+ * as `const { publicKeyFingerprint: _f, ...receipt } = outcome.onboarding`, a DENYLIST OF
+ * ONE: every undeclared property spread straight to stdout. The outcome being shaped here
+ * arrives from an INJECTED `EnrollmentCommandRunner`, so it is not a value this code
+ * produced, and `FleetOnboardingIntent` extends the same bounds while adding `inviteCode`
+ * — an intent-shaped receipt therefore leaked the bounded BEARER SECRET. An allowlist
+ * cannot leak a field nobody listed; a denylist can only stop what someone anticipated.
+ *
+ * Kept honest by `enroll_commit_sites.test.ts`, which derives the declared field set from
+ * `enrollment_types.ts` and fails if this list and the type disagree in EITHER direction —
+ * so a field added to the receipt cannot be silently dropped here, which is the regression
+ * an allowlist invites.
+ */
+const FLEET_RECEIPT_FIELDS = [
+    "boardId", "machineId", "harnessKind", "harnessLabel", "repoSlug", "repoFingerprint",
+    "repoScopeRole", "agentRole", "expectedAgentHandle",
+    "contractVersion", "harnessRegistrationId", "repoScopeId", "fleetMachineAgentId",
+    "bindingSigningKeyId", "membershipRole", "membershipState",
+    "identityDisposition", "membershipDisposition", "harnessDisposition",
+    "repoScopeDisposition", "bindingDisposition",
+];
+/** The field withheld from output even though the type declares it. */
+const FLEET_RECEIPT_WITHHELD = "publicKeyFingerprint";
+function fleetSafeOutput(result) {
+    if (!result || typeof result !== "object")
+        return result;
+    const outcome = result;
+    if (!outcome.onboarding)
+        return result;
+    const source = outcome.onboarding;
+    const receipt = {};
+    // Copy BY NAME. A property absent from the source stays absent rather than becoming
+    // an explicit `undefined`, so a partial receipt shapes to a partial receipt.
+    for (const field of FLEET_RECEIPT_FIELDS) {
+        if (field in source)
+            receipt[field] = source[field];
+    }
+    return {
+        agentId: outcome.agentId,
+        authUserId: outcome.authUserId,
+        providerId: outcome.providerId,
+        signingKeyId: outcome.signingKeyId,
+        keyId: outcome.keyId,
+        keyVersion: outcome.keyVersion,
+        agentHandle: outcome.agentHandle,
+        onboarding: receipt,
+    };
+}
+function addFleetOptions(command) {
+    return command
+        .option("--fleet-onboarding", "atomically enroll and bind the creator-authorized fleet tuple")
+        .option("--invite-code <code>", "fleet bearer code escape hatch (WARNING: argv and shell history expose it; prefer stdin)")
+        .option("--board-id <id>", "bounded board id")
+        .option("--machine-id <id>", "bounded fleet machine id")
+        .option("--harness-kind <kind>", "bounded harness kind")
+        .option("--harness-label <label>", "bounded harness label")
+        .option("--repo-slug <slug>", "bounded repo slug")
+        .option("--repo-fingerprint <fingerprint>", "bounded repo fingerprint")
+        .option("--repo-scope-role <role>", "worker or reviewer")
+        .option("--agent-role <role>", "phase_worker or reviewer")
+        .option("--expected-agent-handle <handle>", "exact server handle authorized by the creator")
+        .option("--local-key-id <id>", "deterministic descriptor-only local key id")
+        .option("--publishable-key-field-reference <ref>", "publishable-key environment field frozen into fleet finalization")
+        .option("--runtime-output <path>", "required fleet runtime generation destination");
+}
 function addEnrollCommands(program, io, enrollment) {
     const enroll = program
         .command("enroll")
@@ -1312,7 +1906,7 @@ function addEnrollCommands(program, io, enrollment) {
     // One-shot loopback flow. It is a DEFAULT subcommand (isDefault) so bare
     // `enroll ...` runs it, while keeping its options off the parent — otherwise a
     // parent-level --slug shadows the begin/complete subcommands' own --slug.
-    enroll
+    const runCommand = enroll
         .command("run", { isDefault: true })
         .description("one-shot enrollment over an RFC 8252 loopback receiver")
         .requiredOption("--slug <slug>", "desired agent slug")
@@ -1324,13 +1918,34 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
-        .action((options) => runHandler(io, "agent_board.enroll", () => enrollment.run({
-        slug: options.slug,
-        agentKind: options.agentKind,
-        intent: intentFromOptions(options),
-        requestedScopes: csv(options.requestedScopes),
-        requestedBoardScopes: csv(options.requestedBoardScopes),
-    })));
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)");
+    addFleetOptions(runCommand)
+        .action((options) => runHandler(io, "agent_board.enroll", async () => {
+        if (options.fleetOnboarding) {
+            // BOTH local prerequisites of fleet finalization are checked here, before the
+            // server is asked to commit anything. The publishable key used to be read only
+            // inside finalizeFleetOutcome, after `enrollment.run` had already created the
+            // identity and spent the bounded invite use (message-board#176).
+            await prepareFleetRuntimeOutput(options.runtimeOutput ?? "");
+            resolveFleetPublishableKey(options.publishableKeyFieldReference);
+        }
+        return enrollmentIntentFromCli(options).then(async (intent) => {
+            const call = () => enrollment.run({
+                slug: options.slug,
+                agentKind: options.agentKind,
+                intent,
+                requestedScopes: csv(options.requestedScopes),
+                requestedBoardScopes: csv(options.requestedBoardScopes),
+            });
+            if (intent.kind !== "fleet_onboarding")
+                return finalizeFleetOutcome(options, intent, await call());
+            // #202 — the runner commits inside this call, so the fence must start here,
+            // not after it. Fleet-only: the post-commit message is about a fleet
+            // enrollment, and a non-fleet failure is not redacted in the first place.
+            const result = await throughFleetCommit(call);
+            return afterFleetCommit(result, () => finalizeFleetOutcome(options, intent, result));
+        });
+    }, Boolean(options.fleetOnboarding)));
     enroll
         .command("begin")
         .description("begin an enrollment; prints the authorization URL (no code_verifier/state)")
@@ -1343,6 +1958,7 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
         // A6: `begin` is ALWAYS out-of-band (a loopback receiver cannot bridge the two
         // separate begin/complete CLI processes), so this flag is a vestigial no-op kept
         // only for backward compatibility. Use `enroll run` for the loopback flow.
@@ -1376,6 +1992,169 @@ function addEnrollCommands(program, io, enrollment) {
             slug: options.slug,
         }));
     });
+    // RFC 8628 device authorization — the correct flow for a HEADLESS host. `run`'s
+    // loopback receiver binds the SERVER's localhost (useless when the human's browser
+    // is elsewhere) and `begin`/`complete`'s OOB redirect is not registered for the
+    // Portal client; the device grant prints a user_code + URL the human approves on
+    // ANY device, then polls to completion. Same options as `run` where they apply.
+    const deviceCommand = enroll
+        .command("device")
+        .description("headless enrollment via the RFC 8628 device authorization grant (approve on any device)")
+        .option("--slug <slug>", "desired agent slug (required unless resuming a non-fleet enrollment)")
+        .option("--enrollment-id <id>", "resume the device authorization returned by a prior fleet begin")
+        .option("--agent-kind <kind>", "agent kind (default 'agent')")
+        .option("--create-board <slug>", "create-board intent slug")
+        .option("--board-name <name>", "board name for create-board")
+        .option("--board-description <description>", "board description")
+        .option("--visibility <visibility>", "board visibility")
+        .option("--join-board <boardId>", "join-board intent board id")
+        .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
+        .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)");
+    addFleetOptions(deviceCommand)
+        .action((options) => runHandler(io, "agent_board.enroll_device", async () => {
+        if (options.enrollmentId) {
+            if (!enrollment.deviceComplete) {
+                throw new Error("device resume is not supported by this runner (EnrollmentCommandRunner.deviceComplete is not implemented)");
+            }
+            if (!options.fleetOnboarding) {
+                // #210, second half — shaped on the OUTCOME, not on the flag. `fleetSafeOutput`
+                // is a no-op for a non-fleet outcome by construction (it returns `result`
+                // unchanged when `onboarding` is absent), so this costs the supported non-fleet
+                // resume nothing. It closes the leak because this is the ONE enroll path whose
+                // result reaches `runHandler` without passing through `finalizeFleetOutcome`:
+                // a fleet outcome arriving here — from the INJECTED `EnrollmentCommandRunner`
+                // seam, which this file already treats as a reachable population — printed
+                // `keyReference` and `agentPublicKey` verbatim.
+                //
+                // `runHandler`'s `redactFleetFailure` argument below stays
+                // `Boolean(options.fleetOnboarding)`. Do NOT make it outcome-keyed to match:
+                // it governs FAILURE text, and turning it on here would blank the guard's
+                // refusal message into "fleet enrollment failed before completion".
+                return fleetSafeOutput(await enrollment.deviceComplete({ enrollmentId: options.enrollmentId }));
+            }
+            if (!enrollment.deviceDeletePending) {
+                throw new Error("fleet device resume is not supported by this runner (EnrollmentCommandRunner.deviceDeletePending is not implemented)");
+            }
+            const store = new FleetDeviceContinuationStore(defaultDevicePendingStateDir(process.env));
+            const continuation = await store.get(options.enrollmentId);
+            if (!continuation)
+                throw new Error("fleet_device_continuation_unknown");
+            const resumeIntent = fleetResumeIntentFromCli(options);
+            const candidate = buildPendingFleetTemplate(resumeIntent, options.publishableKeyFieldReference);
+            const pending = continuation.pendingTemplate;
+            if (options.slug.trim() !== pending.agentSlug || options.runtimeOutput !== continuation.runtimeOutput
+                || continuation.keyReference !== pending.keyReference
+                || continuation.publishableKeyFieldReference !== pending.publishableKeyFieldReference
+                || JSON.stringify(candidate) !== JSON.stringify(pending)) {
+                throw new Error("fleet_device_continuation_mismatch");
+            }
+            await prepareFleetRuntimeOutput(options.runtimeOutput);
+            const expectedIntent = { kind: "fleet_onboarding", ...pending.enrollment };
+            let outcome = continuation.outcome;
+            const committedThisLeg = !outcome;
+            if (committedThisLeg) {
+                // Nothing has committed yet on this leg — check the second local
+                // prerequisite before spending the device authorization.
+                resolveFleetPublishableKey(pending.publishableKeyFieldReference);
+                // #202 — same boundary as `run`: deviceComplete commits inside the call.
+                outcome = await throughFleetCommit(() => enrollment.deviceComplete({
+                    enrollmentId: options.enrollmentId,
+                    expectedFleet: { intent: expectedIntent, keyReference: pending.keyReference, slug: pending.agentSlug },
+                    deletePending: false,
+                }));
+            }
+            return afterFleetCommit(outcome, async () => {
+                // The write that MAKES this recoverable is itself post-commit: mkdir,
+                // O_EXCL create, write, fsync and rename can each fail. Outside the fence
+                // its failure read as "failed before completion", and because the outcome
+                // was never persisted a retry would re-enter deviceComplete against a
+                // device authorization that is already consumed.
+                if (committedThisLeg)
+                    await store.put({ ...continuation, outcome: outcome });
+                const result = await finalizeFleetOutcome(options, { ...expectedIntent, inviteCode: "" }, outcome, pending);
+                await enrollment.deviceDeletePending({ enrollmentId: options.enrollmentId });
+                await store.delete(options.enrollmentId);
+                return result;
+            });
+        }
+        if (!options.slug)
+            throw new Error("enroll device requires --slug when --enrollment-id is absent");
+        if (options.fleetOnboarding) {
+            if (!enrollment.deviceBegin) {
+                throw new Error("fleet device begin is not supported by this runner (EnrollmentCommandRunner.deviceBegin is not implemented)");
+            }
+            const intent = await enrollmentIntentFromCli(options);
+            if (intent.kind !== "fleet_onboarding")
+                throw new Error("fleet_device_intent_missing");
+            const pending = buildPendingFleetTemplate(intent, options.publishableKeyFieldReference);
+            if (!options.runtimeOutput)
+                throw new Error("--fleet-onboarding requires --runtime-output");
+            await prepareFleetRuntimeOutput(options.runtimeOutput);
+            // Before a human approval is spent, and before any continuation state exists
+            // to clean up.
+            resolveFleetPublishableKey(pending.publishableKeyFieldReference);
+            const enrollmentId = `enr-${randomUUID()}`;
+            const store = new FleetDeviceContinuationStore(defaultDevicePendingStateDir(process.env));
+            await store.put({ version: "fleet_device_continuation.v1", enrollmentId,
+                runtimeOutput: options.runtimeOutput, publishableKeyFieldReference: pending.publishableKeyFieldReference,
+                keyReference: pending.keyReference, pendingTemplate: pending });
+            try {
+                const begun = await enrollment.deviceBegin({ enrollmentId, slug: options.slug, agentKind: options.agentKind,
+                    intent, requestedScopes: csv(options.requestedScopes), requestedBoardScopes: csv(options.requestedBoardScopes) });
+                if (begun.enrollmentId !== enrollmentId)
+                    throw new Error("fleet_device_enrollment_id_mismatch");
+                return begun;
+            }
+            catch (error) {
+                await store.delete(enrollmentId);
+                throw error;
+            }
+        }
+        // `device` is an OPTIONAL member of EnrollmentCommandRunner (added after the
+        // interface shipped). The default runner always provides it; a custom runner
+        // that predates it gets a clean error instead of a `undefined is not a function`.
+        if (!enrollment.device) {
+            throw new Error("device-authorization enrollment is not supported by this runner (EnrollmentCommandRunner.device is not implemented)");
+        }
+        return enrollmentIntentFromCli(options).then(async (intent) => {
+            const result = await enrollment.device({
+                slug: options.slug,
+                agentKind: options.agentKind,
+                intent,
+                requestedScopes: csv(options.requestedScopes),
+                requestedBoardScopes: csv(options.requestedBoardScopes),
+                // Print the human-facing prompt PROMINENTLY to stderr (stdout is reserved
+                // for the final JSON outcome). The device_code secret is never surfaced.
+                onDeviceAuthorization: (prompt) => io.writeStderr(renderDevicePrompt(prompt)),
+            });
+            return result;
+        });
+    }, Boolean(options.fleetOnboarding)));
+}
+/**
+ * Render the human-facing device-authorization prompt. Written to be pasted to a
+ * human: the user_code and verification URI are the two things they act on. Never
+ * carries the device_code (the shared flow does not expose it here).
+ */
+function renderDevicePrompt(prompt) {
+    const lines = [
+        "",
+        "=== Approve this agent on any device (RFC 8628 device authorization) ===",
+        `  1. Open:  ${prompt.verificationUri}`,
+        `  2. Enter code:  ${prompt.userCode}`,
+    ];
+    if (prompt.verificationUriComplete) {
+        lines.push(`  (or open this pre-filled link directly:  ${prompt.verificationUriComplete})`);
+    }
+    if (prompt.expiresIn) {
+        lines.push(`  This code expires in ${prompt.expiresIn} seconds. Waiting for approval...`);
+    }
+    else {
+        lines.push("  Waiting for approval...");
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
 }
 /** Read a single-line auth code from a piped stdin (A5). Returns undefined on a TTY. */
 async function readCodeFromStdin() {
@@ -1533,6 +2312,102 @@ function addRoomsCommands(program, client, io) {
         .description("Revoke an invite link by code")
         .requiredOption("--code <code>")
         .action((o) => runHandler(io, "agent_board.revoke_invite_link", () => client.revokeInviteLink({ p_code: o.code })));
+    // Joiner-side redeem: an already-enrolled agent redeems an invite AS ITSELF from
+    // its OWN env-resolved credentials (the same resolution every other CLI command
+    // uses) — the clean path for a host whose MCP session carries a different/shared
+    // identity, without hand-rolling an SDK script. The code is a BEARER SECRET.
+    //
+    // A5 (mirrors `enroll complete`, cli.ts): PREFER stdin. A bearer code on argv leaks
+    // via /proc/<pid>/cmdline and the shell's history file, so `--code` is optional and
+    // documented as leaky; when it is absent and stdin is piped, the code is read from
+    // stdin (e.g. a quoted heredoc — the form the rendered join instructions emit, which
+    // keeps the code out of any executable shell string). The command never writes the
+    // code to a log, and neither the success result nor the failure object echoes it.
+    rooms
+        .command("link-redeem")
+        .description("Redeem an invite link by code, joining as the agent identity resolved from this host's env credentials. The code is a BEARER SECRET — prefer piping it on stdin.")
+        .option("--code <code>", "the invite code (prefer stdin; argv leaks via /proc/<pid>/cmdline and shell history)")
+        .action(async (o) => {
+        let code = o.code;
+        if (!code) {
+            code = await readCodeFromStdin();
+        }
+        if (!code) {
+            io.writeStderr("link-redeem needs an invite code: pipe it on stdin (e.g. `agent-board rooms link-redeem <<'MB_INVITE_CODE'` ... `MB_INVITE_CODE`) or pass --code (which leaks the bearer code via /proc and shell history).\n");
+            process.exitCode = 1;
+            return;
+        }
+        return runHandler(io, "agent_board.redeem_invite_link", () => client.redeemInviteLink({ p_code: code }));
+    });
+}
+function addInviteCommands(program, client, io) {
+    const invite = program.command("invite").description("create bounded fleet onboarding invites");
+    invite
+        .command("create-fleet")
+        .description("create a member-only invite with immutable machine/harness/repo/role/handle bounds")
+        .requiredOption("--board-id <id>")
+        .requiredOption("--machine-id <id>")
+        .requiredOption("--harness-kind <kind>")
+        .requiredOption("--harness-label <label>")
+        .requiredOption("--repo-slug <slug>")
+        .requiredOption("--repo-fingerprint <fingerprint>")
+        .requiredOption("--repo-scope-role <role>", "worker or reviewer")
+        .requiredOption("--agent-role <role>", "phase_worker or reviewer")
+        .requiredOption("--expected-agent-handle <handle>")
+        .addOption(numberOption("--max-uses <n>", "maximum atomic onboardings (default 1)"))
+        .option("--expires <iso>")
+        .option("--created-by-agent-id <id>")
+        .option("--with-instructions", "render the bounded atomic onboarding instructions")
+        .option("--host <slug>", "normalized host slug (required with --with-instructions)")
+        .option("--platform <platform>", "desktop or headless_linux (required with --with-instructions)")
+        .option("--publishable-key-field-reference <ref>", "public key field reference (required with --with-instructions)")
+        .action((o) => runHandler(io, "agent_board.create_fleet_onboarding_invite", async () => {
+        if (!client.createFleetOnboardingInvite) {
+            throw new Error("this client does not support bounded fleet onboarding invites");
+        }
+        const pair = (o.agentRole === "phase_worker" && o.repoScopeRole === "worker")
+            || (o.agentRole === "reviewer" && o.repoScopeRole === "reviewer");
+        if (!pair)
+            throw new Error("fleet invite allows only phase_worker/worker or reviewer/reviewer");
+        let instructionTemplate;
+        let instructionDeployment;
+        if (o.withInstructions) {
+            if (!o.host || !o.platform || !o.publishableKeyFieldReference)
+                throw new Error("--with-instructions requires --host, --platform, and --publishable-key-field-reference");
+            if (o.platform !== "desktop" && o.platform !== "headless_linux")
+                throw new Error("--platform must be desktop or headless_linux");
+            instructionDeployment = resolveJoinDeployment();
+            instructionTemplate = buildFleetHarnessTemplate({ host: o.host, harnessKind: o.harnessKind, harnessLabel: o.harnessLabel,
+                platform: o.platform, boardId: o.boardId, machineId: o.machineId, repoSlug: o.repoSlug, repoFingerprint: o.repoFingerprint,
+                repoScopeRole: o.repoScopeRole, agentRole: o.agentRole, boardUrl: instructionDeployment.boardUrl,
+                sessionUrl: instructionDeployment.sessionUrl ?? instructionDeployment.boardUrl,
+                publishableKeyFieldReference: o.publishableKeyFieldReference,
+                ...(o.platform === "headless_linux" ? { agentSocketPath: process.env.SSH_AUTH_SOCK, publicKeySelector: process.env.AGENT_BOARD_PUBLIC_KEY_SELECTOR } : {}),
+            });
+            const instructionBounds = ["boardId", "machineId", "harnessKind", "harnessLabel", "repoSlug", "repoFingerprint", "repoScopeRole", "agentRole", "expectedAgentHandle"];
+            if (instructionBounds.some((field) => instructionTemplate.enrollment[field] !== o[field])) {
+                throw new Error("fleet instruction options do not match the normalized bounded template");
+            }
+        }
+        const result = await client.createFleetOnboardingInvite({
+            boardId: o.boardId,
+            machineId: o.machineId,
+            harnessKind: o.harnessKind,
+            harnessLabel: o.harnessLabel,
+            repoSlug: o.repoSlug,
+            repoFingerprint: o.repoFingerprint,
+            repoScopeRole: o.repoScopeRole,
+            agentRole: o.agentRole,
+            expectedAgentHandle: o.expectedAgentHandle,
+            maxUses: o.maxUses,
+            expiresAt: o.expires,
+            createdByAgentId: o.createdByAgentId,
+        });
+        if (!o.withInstructions)
+            return result;
+        const branded = result.data;
+        return { result, instructions: buildAgentJoinInstructions({ invite: branded, deployment: { ...instructionDeployment, fleetHarnessTemplate: instructionTemplate, fleetOnboardingInvite: branded } }) };
+    }));
 }
 export function createProgram(client, io, enrollment = defaultEnrollmentRunner()) {
     const program = new Command()
@@ -1556,6 +2431,7 @@ export function createProgram(client, io, enrollment = defaultEnrollmentRunner()
     addWriteCommands(program, client, io);
     addReadCommands(program, client, io);
     addRoomsCommands(program, client, io);
+    addInviteCommands(program, client, io);
     addEnrollCommands(program, io, enrollment);
     return program;
 }