@consiliency/agent-board-cli 1.10.0 → 1.11.0

package/dist/cli.d.ts

@@ -221,6 +221,86 @@ export interface DefaultEnrollmentRunnerDeps {
     };
 }
 export declare function defaultEnrollmentRunner(env?: NodeJS.ProcessEnv, deps?: DefaultEnrollmentRunnerDeps): EnrollmentCommandRunner;
+/**
+ * How each field of a `FleetOnboardingIntent` is turned from an argv string into the value
+ * that goes on the wire and into the template (Consiliency/message-board#254).
+ *
+ * This map exists because the previous shape — nine literal `.trim()` calls repeated at two
+ * call sites — is the completeness failure CLAUDE.md rule 1 targets: #254 itself enumerated
+ * six of the nine, and got one of the six wrong. The map is TOTAL over the intent's string
+ * fields by construction, so a field added to `FleetOnboardingIntent` does not compile until
+ * someone dispositions it, and both call sites read their verb from here rather than
+ * restating it.
+ *
+ * Three dispositions, because there are three real behaviours and collapsing them is what
+ * hid the defect:
+ *
+ * - `gated` — the library REFUSES a prohibited character in this value rather than
+ *   rewriting it, because the value is carried byte-exact into a template that runs on
+ *   ANOTHER machine. A bare `.trim()` here deleted an edge-placed member of the refuse
+ *   classes before `required()` could see it, so the library's raw-operand ordering (#215)
+ *   was unreachable from the CLI. The verb is the library's own, imported.
+ * - `normalized` — the value is NOT carried verbatim: it is folded, or it is pinned by
+ *   equality against a value derived from folded atoms. Trimming is right here, and
+ *   removing it would regress an ordinary trailing space into a hard failure for no
+ *   byte-exactness gain. Each one's claim is asserted positively in `cli.test.ts`, on the
+ *   intent the runner RECEIVES — `expectedAgentHandle` and `inviteCode` are copied verbatim
+ *   into the /enroll body, so "the output is clean" would not be evidence about them.
+ * - `vocabulary` — a closed set. A poisoned value cannot match a member, so it is refused
+ *   by the existing pair check rather than by a presentation class.
+ *
+ * Each entry also states what a PROHIBITED character in that field does to the /enroll
+ * request — `wire`, which is the property `cli.test.ts` measures. It is stated per field
+ * rather than as one blanket claim because the blanket claim is false: an invite code is a
+ * bearer secret the server matches, so the refuse class is not policed on it.
+ *
+ * `verbatim` means exactly that — THE REFUSE CLASS IS NOT POLICED ON THIS FIELD — and not
+ * "untouched". Edges are still trimmed here as on every field (AC-6), so a prohibited
+ * character placed at an edge is erased and only an INTERIOR one survives to the wire. The
+ * label is worth stating precisely because the looser reading ("it travels as the operator
+ * typed it") stood in this comment and in three places in the plan, and was false at the
+ * edges in all four. `cli.test.ts` asserts the arm per PLACEMENT, which is the form that
+ * cannot be read two ways.
+ *
+ * Asserting a field's real arm is what makes an exemption evidence instead of prose.
+ */
+type FleetTupleDisposition = {
+    readonly kind: "gated";
+    readonly flag: string;
+    readonly label: string;
+    readonly wire: "refused";
+} | {
+    readonly kind: "normalized";
+    readonly flag: string;
+    readonly why: string;
+    readonly wire: "clean" | "verbatim";
+    readonly normalize: (value: string) => string;
+} | {
+    readonly kind: "vocabulary";
+    readonly flag?: string;
+    readonly why: string;
+    readonly wire: "refused";
+};
+/**
+ * The string-valued keys of `T` — the operator the totality claim above rests on, and the
+ * reason it is named and exported rather than written inline.
+ *
+ * `NonNullable` is load-bearing. `-?` strips optionality from the PRODUCED property, but
+ * the conditional tests the original indexed access, and for `field?: string` that is
+ * `string | undefined`, which does not extend `string`. Written without `NonNullable` this
+ * operator answers `never` for every optional member — so an optional string field added to
+ * the intent would vanish from the disposition map, from the census, and from the wire
+ * matrix, WITHOUT a compile error. Fail-open, and invisible until someone adds such a field.
+ *
+ * Latent rather than live today (`FleetOnboardingIntent` has no optional string members),
+ * which is exactly why it is pinned by a type-level probe in `cli.test.ts` — a guard whose
+ * failure mode is silence has to be tested against a shape that would trigger it.
+ */
+export type StringFieldsOf<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends string ? K : never;
+}[keyof T];
+type FleetTupleField = StringFieldsOf<FleetOnboardingIntent>;
+export declare const FLEET_TUPLE_DISPOSITION: Readonly<Record<FleetTupleField, FleetTupleDisposition>>;
 export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner): Command;
 export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner): Promise<void>;
 export {};

package/dist/cli.js

@@ -2,7 +2,7 @@ import { Command, Option } from "commander";
 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 { 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);
@@ -71,6 +71,53 @@ class FleetPostCommitError extends FleetSafeMessageError {
  * 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 "";
@@ -197,6 +244,47 @@ async function throughFleetCommit(call) {
             : 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();
@@ -209,7 +297,7 @@ async function runHandler(io, operation, action, redactFleetFailure = false) {
         if (redactFleetFailure && !(error instanceof FleetSafeMessageError)) {
             failure.error.message = "fleet enrollment failed before completion";
         }
-        io.writeStdout(`${JSON.stringify(failure, null, 2)}\n`);
+        writeFailureEnvelope(io, failure);
         process.exitCode = 1;
     }
 }
@@ -218,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;
     }
 }
@@ -1742,6 +1830,22 @@ function buildPendingFleetTemplate(intent, publishableKeyFieldReference = DEFAUL
     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)
@@ -1761,9 +1865,59 @@ async function finalizeFleetOutcome(options, intent, result, frozenPending) {
         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);
+    // 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: fleetSafeOutput(outcome), materialization: { generation: published.generation, digest: published.digest } };
+    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 = [
@@ -1781,15 +1935,18 @@ function fleetResumeIntentFromCli(options) {
         || (options.agentRole === "reviewer" && options.repoScopeRole === "reviewer");
     if (!pair)
         throw new Error("fleet device resume allows only phase_worker/worker or reviewer/reviewer");
-    return {
+    // 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: options.boardId.trim(), machineId: options.machineId.trim(),
-        harnessKind: options.harnessKind.trim().toLowerCase(), harnessLabel: options.harnessLabel.trim(),
-        repoSlug: options.repoSlug.trim(), repoFingerprint: options.repoFingerprint.trim(),
+        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: options.expectedAgentHandle.trim(), localKeyId: options.localKeyId.trim(),
-    };
+        expectedAgentHandle: fleetTupleValue("expectedAgentHandle", options.expectedAgentHandle),
+        localKeyId: fleetTupleValue("localKeyId", options.localKeyId),
+    }));
 }
 async function enrollmentIntentFromCli(options) {
     if (!options.fleetOnboarding)
@@ -1815,20 +1972,23 @@ async function enrollmentIntentFromCli(options) {
         || (options.agentRole === "reviewer" && options.repoScopeRole === "reviewer");
     if (!pair)
         throw new Error("--fleet-onboarding allows only phase_worker/worker or reviewer/reviewer");
-    return {
+    // 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: 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(),
+        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: options.expectedAgentHandle.trim(),
-        localKeyId: options.localKeyId.trim(),
-    };
+        expectedAgentHandle: fleetTupleValue("expectedAgentHandle", options.expectedAgentHandle),
+        localKeyId: fleetTupleValue("localKeyId", options.localKeyId),
+    }));
 }
 /**
  * Every field DECLARED on `FleetOnboardingReceipt` (including the nine it inherits from
@@ -1871,7 +2031,7 @@ function fleetSafeOutput(result) {
         if (field in source)
             receipt[field] = source[field];
     }
-    return {
+    const shaped = {
         agentId: outcome.agentId,
         authUserId: outcome.authUserId,
         providerId: outcome.providerId,
@@ -1881,6 +2041,24 @@ function fleetSafeOutput(result) {
         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
@@ -1921,30 +2099,41 @@ function addEnrollCommands(program, io, enrollment) {
         .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));
+        // 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")
@@ -2041,7 +2230,12 @@ function addEnrollCommands(program, io, enrollment) {
             if (!continuation)
                 throw new Error("fleet_device_continuation_unknown");
             const resumeIntent = fleetResumeIntentFromCli(options);
-            const candidate = buildPendingFleetTemplate(resumeIntent, options.publishableKeyFieldReference);
+            // 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
@@ -2087,7 +2281,7 @@ function addEnrollCommands(program, io, enrollment) {
             const intent = await enrollmentIntentFromCli(options);
             if (intent.kind !== "fleet_onboarding")
                 throw new Error("fleet_device_intent_missing");
-            const pending = buildPendingFleetTemplate(intent, options.publishableKeyFieldReference);
+            const pending = throughPresentationGate(() => buildPendingFleetTemplate(intent, options.publishableKeyFieldReference));
             if (!options.runtimeOutput)
                 throw new Error("--fleet-onboarding requires --runtime-output");
             await prepareFleetRuntimeOutput(options.runtimeOutput);
@@ -2303,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;
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@consiliency/agent-board-client": "1.16.0",
+    "@consiliency/agent-board-client": "1.19.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0"