@consiliency/agent-board-cli 1.9.0 → 1.11.0

package/dist/cli.js

@@ -1,6 +1,9 @@
 import { Command, Option } from "commander";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, 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, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, 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,288 @@ 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.
+ */
+/**
+ * A FLEET-TEMPLATE FAILURE is safe to print, and the post-commit fence cannot know that
+ * without being told (#214).
+ *
+ * The fence withholds a cause's text because a raw local failure can carry an
+ * `os_keychain[<handle>]` descriptor. The fleet-template module carries no such thing: its
+ * `fail()` composes every message from an authored `[a-z0-9_]+` code plus, in the
+ * presentation case, a field path already constrained to a plain identifier at the throw
+ * site — and it ENFORCES that shape on itself before throwing, so the guarantee is a
+ * property of the producer rather than a claim about it. Withholding these inverts the
+ * trade this whole change makes: refuse rather than rewrite is only better than a silent
+ * rewrite if the refusal is READABLE, and a failed command with no actionable reason after
+ * the server committed is the #176 shape.
+ *
+ * THE CLASS, NOT THE LINE. An earlier revision matched only `*_presentation_invalid:<path>`
+ * — the GENERIC content rule — and so redacted `invalid_receipt_key_id`, which is the
+ * refusal #214 is actually about and the one a reader would test by hand. `exact()` fires
+ * before the content sweep, so none of the legibility applied on the originating path.
+ * Matching the producer's whole vocabulary removes the category of that bug instead of
+ * adding a second special case beside the first.
+ *
+ * Trust is CHECKED at the boundary, not assumed from where the error came: same discipline
+ * as `namedCauseCode` below — a gate on the VALUE, never a cross-package `instanceof`,
+ * which is silently false when the workspace holds two copies of the client module.
+ * Anything else — an fs error, a keystore descriptor, an error from a module that is not
+ * this one — keeps the blanket redaction, which the #202 raw-cause test pins.
+ */
+// Imported, never restated: the producer enforces this shape on itself before throwing,
+// so a second copy here could only ever disagree with it — and the copy that decides
+// whether text crosses a security boundary is the one that must not drift.
+const FLEET_TEMPLATE_FAILURE = FLEET_TEMPLATE_FAILURE_MESSAGE;
+function asFleetSafeMessage(error) {
+    if (!(error instanceof Error) || !FLEET_TEMPLATE_FAILURE.test(error.message))
+        return error;
+    return new FleetSafeMessageError("fleet_onboarding_template_refused", `${error.message} — the fleet template refused this enrollment's local finalization. `
+        + "Nothing was rewritten and nothing was written to this host. A `*_presentation_invalid:<field>` "
+        + "code means the named field carries a bidi or zero-width character; report it to whoever operates the board.");
+}
+/** Run `action`, letting only a fleet-template failure cross the fence as its own message. */
+function throughPresentationGate(action) {
+    try {
+        return action();
+    }
+    catch (error) {
+        throw asFleetSafeMessage(error);
+    }
+}
+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);
+    }
+}
+/**
+ * THE LAST PASS OVER A FAILURE ENVELOPE BEFORE A HUMAN READS IT (#214).
+ *
+ * The class this whole change chased was never "receipt values" and never "server
+ * messages": it is ANYTHING THAT BECOMES OPERATOR-VISIBLE TEXT, and each review round
+ * found that class one sink wider. The field-level version of this failed twice in the
+ * same envelope — `boundServerText` cleans the server's `message`, and `error.code` is
+ * emitted beside it untouched, so a response carrying `code: "denied<RLO>allowed"` still
+ * put a bidi override in stdout.
+ *
+ * So this gate is on the ENVELOPE, at the one point where it becomes visible, rather than
+ * on the fields. That is what makes the NEXT field free instead of another round: a field
+ * added to the failure shape later is covered the day it is added, which is exactly how
+ * `code` came to be missed.
+ *
+ * REMOVE, not refuse — the same verb and the same reason as `boundServerText`: this is a
+ * diagnostic being rendered, nothing here is carried onward, and refusing to print a
+ * failure envelope would delete the operator's only information about the failure.
+ *
+ * TWO THINGS IT MUST NOT DO, both asserted rather than intended:
+ *   - It must not weaken the fleet fence. It runs on the SERIALIZED text, after the
+ *     redaction and the presentation gate have decided what the envelope says; it is a
+ *     final pass, never a replacement for either.
+ *   - It must leave `fleet_harness_template_*_presentation_invalid:<path>` intact. That
+ *     message is ASCII by construction (the path alphabet is gated at the throw site), so
+ *     the strip is a no-op on it — stripping it would undo the round that made a refusal
+ *     readable.
+ *
+ * Applied AFTER `JSON.stringify`, which is safe and deliberate: `JSON.stringify` escapes
+ * C0 controls to `\uXXXX` itself, so the only members that reach the text are the raw
+ * presentation characters, and removing those from inside string literals cannot make the
+ * document invalid — no member of the class can occur in a structural position.
+ *
+ * Own compiled instance from the shared class SOURCE (`text_safety.ts`), REMOVE verb: the
+ * same class `clean()` uses for rendered prose, because this is rendered prose.
+ */
+const OPERATOR_VISIBLE_PROHIBITED = new RegExp(`[${PROHIBITED_PRESENTATION_REMOVE_CLASS}]`, "gu");
+function writeFailureEnvelope(io, failure, indent = 2) {
+    const serialized = indent === 0 ? JSON.stringify(failure) : JSON.stringify(failure, null, indent);
+    io.writeStdout(`${serialized.replace(OPERATOR_VISIBLE_PROHIBITED, "")}\n`);
+}
+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";
+        }
+        writeFailureEnvelope(io, failure);
         process.exitCode = 1;
     }
 }
@@ -28,7 +306,7 @@ async function runJsonlHandler(io, operation, action) {
         io.writeStdout(`${JSON.stringify(await action())}\n`);
     }
     catch (error) {
-        io.writeStdout(`${JSON.stringify(toOperationFailure(operation, error))}\n`);
+        writeFailureEnvelope(io, toOperationFailure(operation, error), 0);
         process.exitCode = 1;
     }
 }
@@ -1212,6 +1490,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 +1509,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,
@@ -1261,7 +1545,9 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
             // 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);
+            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,
@@ -1280,6 +1566,157 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 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).
@@ -1306,8 +1743,11 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
         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,
@@ -1350,6 +1790,293 @@ 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;
+    // ONE gate over the whole local-finalization phase, rather than one per client call.
+    // Two consequences, both wanted: every fleet-template refusal raised anywhere in here
+    // becomes readable, and every OTHER failure in here (the fs publication error the #202
+    // test drives, a keystore descriptor, a normalizeKeyReference throw) passes through the
+    // same gate and is REJECTED by it — which makes that pre-existing test the discriminating
+    // negative pin for this gate rather than a case that never reaches it.
+    try {
+        return await finalizeFleetOutcomeInner(options, intent, result, frozenPending);
+    }
+    catch (error) {
+        throw asFleetSafeMessage(error);
+    }
+}
+async function finalizeFleetOutcomeInner(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);
+    // Hoisted rather than inlined into the call: wrapping the call in an arrow drops the
+    // object literal's contextual typing, which turns every spread field optional. The cast
+    // restates what the `!outcome.onboarding` guard above already established.
+    const receipt = { ...outcome.onboarding, agentId: outcome.agentId,
+        signingKeyId: outcome.signingKeyId, keyId: outcome.keyId, keyVersion: outcome.keyVersion,
+        agentHandle: outcome.agentHandle };
+    const finalized = finalizeFleetHarnessTemplate(pending, receipt, { keyReference: pending.keyReference, publicKey: outcome.agentPublicKey, publicKeyFingerprint: fingerprint }, resolvedPublishableKey);
+    // Shaped (and therefore content-checked) BEFORE anything is written to disk.
+    const enrollment = fleetSafeOutput(outcome);
+    const published = await publishFinalizedFleetTemplate(options.runtimeOutput, finalized);
+    return { enrollment, materialization: { generation: published.generation, digest: published.digest } };
+}
+export const FLEET_TUPLE_DISPOSITION = Object.freeze({
+    // Labels are the library's own, so an early refusal here carries the identical code the
+    // later `buildFleetHarnessTemplate` boundary would have produced. `cli.test.ts` derives
+    // that equality rather than reciting it.
+    boardId: { kind: "gated", flag: "--board-id", label: "board_id", wire: "refused" },
+    machineId: { kind: "gated", flag: "--machine-id", label: "machine_id", wire: "refused" },
+    harnessLabel: { kind: "gated", flag: "--harness-label", label: "harness_label", wire: "refused" },
+    repoSlug: { kind: "gated", flag: "--repo-slug", label: "repo_slug", wire: "refused" },
+    repoFingerprint: { kind: "gated", flag: "--repo-fingerprint", label: "repo_fingerprint", wire: "refused" },
+    // `atom()` trims AND lowercases this field, and that normalization is deliberate and
+    // pinned (fleet_onboarding.test.ts, "atom() normalizes an edge-placed U+FEFF"). Dropping
+    // the fold here is not a no-op: `buildPendingFleetTemplate` requires the expected handle
+    // to end with `-<harnessKind>`, so `--harness-kind CODEX` would stop working.
+    harnessKind: { kind: "normalized", flag: "--harness-kind", why: "atom()-gated: folded, and the folded value is what crosses", wire: "clean",
+        normalize: (value) => value.trim().toLowerCase() },
+    // Consumed by the `endsWith` suffix check and by `host = handle.slice(...)`, which goes
+    // through `atom()`; the template's handle is DERIVED, never this string. Removing the
+    // trim turns a trailing space into `fleet_onboarding_expected_handle_invalid`.
+    expectedAgentHandle: { kind: "normalized", flag: "--expected-agent-handle", why: "the template handle is derived from atoms; this string only has to agree with it", wire: "clean",
+        normalize: (value) => value.trim() },
+    // Pinned by EQUALITY against the derived `agent-board/<host>/<harness>` — strictly
+    // stronger than a class check, and the derived value is the one that crosses.
+    localKeyId: { kind: "normalized", flag: "--local-key-id", why: "equality-pinned against a derived key id", wire: "clean",
+        normalize: (value) => value.trim() },
+    // A bearer secret the server validates; carried into no template field. Its stdin ingress
+    // is already trimmed once, where a trailing newline is a stream terminator rather than a
+    // typed character.
+    inviteCode: { kind: "normalized", flag: "--invite-code", why: "server-validated bearer secret; reaches no template field", wire: "verbatim",
+        normalize: (value) => value.trim() },
+    repoScopeRole: { kind: "vocabulary", flag: "--repo-scope-role", why: "worker | reviewer, checked by the pair rule below", wire: "refused" },
+    agentRole: { kind: "vocabulary", flag: "--agent-role", why: "phase_worker | reviewer, checked by the pair rule below", wire: "refused" },
+    kind: { kind: "vocabulary", why: "a literal this file writes; never operator-supplied", wire: "refused" },
+});
+/** Apply one field's dispositioned verb. The only place an intent field is normalized. */
+function fleetTupleValue(field, value) {
+    const disposition = FLEET_TUPLE_DISPOSITION[field];
+    if (disposition.kind === "gated")
+        return normalizeFleetTupleValue(value, disposition.label);
+    if (disposition.kind === "normalized")
+        return disposition.normalize(value);
+    return value;
+}
+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");
+    // Synchronous, so the presentation gate can convert a refusal into its own message here
+    // rather than letting the blanket fleet redaction flatten it (#254).
+    return throughPresentationGate(() => ({
+        kind: "fleet_onboarding", inviteCode: "",
+        boardId: fleetTupleValue("boardId", options.boardId), machineId: fleetTupleValue("machineId", options.machineId),
+        harnessKind: fleetTupleValue("harnessKind", options.harnessKind), harnessLabel: fleetTupleValue("harnessLabel", options.harnessLabel),
+        repoSlug: fleetTupleValue("repoSlug", options.repoSlug), repoFingerprint: fleetTupleValue("repoFingerprint", options.repoFingerprint),
+        repoScopeRole: options.repoScopeRole,
+        agentRole: options.agentRole,
+        expectedAgentHandle: fleetTupleValue("expectedAgentHandle", options.expectedAgentHandle),
+        localKeyId: fleetTupleValue("localKeyId", options.localKeyId),
+    }));
+}
+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");
+    // The stdin read above is the only `await` on this path, and it is already done — so the
+    // gate wraps a purely SYNCHRONOUS construction and cannot miss a refusal that would
+    // otherwise surface as an unconverted promise rejection.
+    return throughPresentationGate(() => ({
+        kind: "fleet_onboarding",
+        inviteCode: fleetTupleValue("inviteCode", inviteCode),
+        boardId: fleetTupleValue("boardId", options.boardId),
+        machineId: fleetTupleValue("machineId", options.machineId),
+        harnessKind: fleetTupleValue("harnessKind", options.harnessKind),
+        harnessLabel: fleetTupleValue("harnessLabel", options.harnessLabel),
+        repoSlug: fleetTupleValue("repoSlug", options.repoSlug),
+        repoFingerprint: fleetTupleValue("repoFingerprint", options.repoFingerprint),
+        repoScopeRole: options.repoScopeRole,
+        agentRole: options.agentRole,
+        expectedAgentHandle: fleetTupleValue("expectedAgentHandle", options.expectedAgentHandle),
+        localKeyId: fleetTupleValue("localKeyId", options.localKeyId),
+    }));
+}
+/**
+ * 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];
+    }
+    const shaped = {
+        agentId: outcome.agentId,
+        authUserId: outcome.authUserId,
+        providerId: outcome.providerId,
+        signingKeyId: outcome.signingKeyId,
+        keyId: outcome.keyId,
+        keyVersion: outcome.keyVersion,
+        agentHandle: outcome.agentHandle,
+        onboarding: receipt,
+    };
+    // #214, second round. This allowlist bounds WHICH fields reach the operator's terminal;
+    // it never bounded their CONTENT, and `JSON.stringify` (how runHandler prints this)
+    // escapes C0 controls while passing bidi overrides and zero-width characters through
+    // verbatim. A poisoned-but-truthy id therefore printed as a different id than the one
+    // enrolled, at the moment the operator decides the enrollment is correct.
+    //
+    // The check lives HERE, in the shaping function, rather than at the fleet finalize call
+    // site, because there are TWO routes to a fleet-shaped stdout and only one of them
+    // passes through `finalizeFleetOutcome`: `enroll device --enrollment-id` returns this
+    // directly from the injected runner (#210). Placing it at the call site would have
+    // gated one route and left the other — the same one-consumer scoping error that let
+    // this sink exist. The invariant is now a property of the shaper: everything it returns
+    // is presentation-safe or nothing is returned at all.
+    //
+    // Two of these fields (`authUserId`, `providerId`) are NOT in the fleet receipt, so the
+    // client-side receipt rule cannot reach them; their construction site is `enroll.ts`.
+    throughPresentationGate(() => assertPresentationSafe(shaped, "fleet_enrollment_output"));
+    return shaped;
+}
+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")
@@ -1357,7 +2084,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")
@@ -1369,14 +2096,45 @@ 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)")
-        .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 () => {
+        // ORDER IS THE CONTRACT on this path (#254). The intent is built and the whole
+        // pending template is constructed BEFORE the filesystem is touched and before the
+        // server is asked to commit anything — which is the order `enroll device` (begin
+        // and resume) has always used, and which this path alone did not.
+        //
+        // Two claims depend on it, and neither was true before. The operator-facing
+        // refusal says nothing was written to this host: `prepareFleetRuntimeOutput`
+        // mkdirs the runtime root, so running it first made that false. And a value the
+        // template REFUSES — an interior prohibited character in the expected handle, say
+        // — was previously sent to the server and only refused afterwards, spending the
+        // bounded invite use on an enrollment this host could never finalize (#176).
+        const intent = await enrollmentIntentFromCli(options);
+        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());
+        const pending = throughPresentationGate(() => buildPendingFleetTemplate(intent, options.publishableKeyFieldReference));
+        // BOTH local prerequisites of fleet finalization, checked 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);
+        // #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);
+        // The frozen template is the one the pre-flight validated, so finalization cannot
+        // silently rebuild a different one from the same intent.
+        return afterFleetCommit(result, () => finalizeFleetOutcome(options, intent, result, pending));
+    }, Boolean(options.fleetOnboarding)));
     enroll
         .command("begin")
         .description("begin an enrollment; prints the authorization URL (no code_verifier/state)")
@@ -1428,10 +2186,11 @@ function addEnrollCommands(program, io, enrollment) {
     // 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.
-    enroll
+    const deviceCommand = enroll
         .command("device")
         .description("headless enrollment via the RFC 8628 device authorization grant (approve on any device)")
-        .requiredOption("--slug <slug>", "desired agent slug")
+        .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")
@@ -1440,25 +2199,132 @@ 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)")
-        .action((options) => runHandler(io, "agent_board.enroll_device", () => {
+        .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);
+            // Same gate as `run` (#254). A refusal raised INSIDE the template build — an
+            // interior prohibited character reaching `atom()`, say — is not a message this
+            // file wrote, so without the gate the blanket fleet redaction flattens it to
+            // "failed before completion" on this path while `run` prints the named field.
+            // Pre-commit either way; the difference is whether the operator can act on it.
+            const candidate = throughPresentationGate(() => 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 = throughPresentationGate(() => 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 enrollment.device({
-            slug: options.slug,
-            agentKind: options.agentKind,
-            intent: intentFromOptions(options),
-            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 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
@@ -1631,7 +2497,7 @@ function addRoomsCommands(program, client, io) {
             io.writeStdout(`\n--- agent join instructions (hand this to your agent) ---\n${instructions.renderedText}\n`);
         }
         catch (error) {
-            io.writeStdout(`${JSON.stringify(toOperationFailure("agent_board.create_invite_link", error), null, 2)}\n`);
+            writeFailureEnvelope(io, toOperationFailure("agent_board.create_invite_link", error));
             process.exitCode = 1;
         }
     });
@@ -1668,6 +2534,75 @@ function addRoomsCommands(program, client, io) {
         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()
         .name("agent-board")
@@ -1690,6 +2625,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;
 }