@consiliency/agent-board-cli 1.13.0 → 1.15.0

package/dist/cli.js

@@ -34,6 +34,27 @@ class FleetSafeMessageError extends Error {
 /**
  * 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.
+ *
+ * A NOTE ON THIS CLASS'S SHAPE, left for whoever meets it next (#402).
+ *
+ * The name encodes a GLOBAL fact — "this enrollment has not committed anywhere" — while a
+ * throw site only ever knows something LOCAL: that this function, on this invocation, has
+ * not called the server yet. A helper cannot verify the claim its own class makes. That gap
+ * is not a hypothetical: it is precisely how the device-resume defect happened, where every
+ * check on the way back into a resume was locally pre-call and globally post-commit, and
+ * told operators to re-run an enrollment that had already succeeded.
+ *
+ * This was not redesigned, deliberately. The non-resume sites do happen to honour the claim
+ * — `run` and device `begin` are one-shot, so local and global coincide there — and a
+ * rename or a split would touch every call site for a property two of three paths already
+ * satisfy. What changed instead is that no MESSAGE asserts the global fact unless its
+ * caller can vouch for it: the assurance sentence is passed in by the caller, and the
+ * resume path passes one that makes no commit-status claim at all. The class keeps its
+ * name; the text stopped over-claiming.
+ *
+ * If a fourth path is ever added, the question to ask is not "is this before the server
+ * call" but "can a commit have happened on ANY earlier leg of this enrollment" — and if the
+ * answer is yes or unknown, it must not say the invite is unspent.
  */
 class FleetPreflightError extends FleetSafeMessageError {
 }
@@ -118,15 +139,30 @@ function throughPresentationGate(action) {
         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}]`;
+/**
+ * WITHDRAWN (#402). Returns "" for every input, and is kept as the single named place that
+ * decision is recorded rather than deleted into a diff nobody will read.
+ *
+ * It used to put a CAUSE's `code` into a message this CLI prints, behind a shape gate. Two
+ * successive bounds were defended here and BOTH rested on a claim about what a credential
+ * can look like: first a lowercase snake_case class (whose alphabet is a subset of
+ * base64url's, so a fleet invite code qualifies), then a 42-character cap derived from that
+ * code's invariant 43 — which covered exactly one credential and was then treated as
+ * covering the channel. The OAuth `device_code` on this same flow is constrained only to be
+ * non-empty, so a short one passes the cap.
+ *
+ * There is no third bound. A code we did not write is not printed, which is the rule the
+ * `--harness-kind`, `--local-key-id` and `--publishable-key-field-reference` echoes all
+ * reached by the same road.
+ *
+ * THE COST, stated because it is real: a post-commit or commit-unknown message no longer
+ * carries `[code <cause>]`, so an operator debugging one of those loses the one-word
+ * discriminator. Everything else in both messages is unchanged, and both still name the
+ * state and the action. Restoring it needs a bound that holds for EVERY credential able to
+ * reach here, not one derived from a single issuer.
+ */
+function namedCauseCode(_cause) {
+    return "";
 }
 function committedFactsFromOutcome(outcome) {
     return {
@@ -137,6 +173,50 @@ function committedFactsFromOutcome(outcome) {
         machineId: outcome.onboarding?.machineId ?? "",
     };
 }
+/**
+ * THE RESUME'S DEFAULT ANSWER IS "UNKNOWN", NOT "IT DID NOT HAPPEN" (#402 round 3).
+ *
+ * `runHandler`'s blanket redaction replaces an unrecognised fleet failure with "fleet
+ * enrollment failed before completion". On a ONE-SHOT command (`enroll run`, device
+ * `begin`) that sentence is true by construction: no leg preceded this one. On a device
+ * RESUME it is a claim about a MULTI-LEG flow whose earlier legs are recorded in a local
+ * file that can fail to be written or fail to be read — and measured, not reasoned:
+ *
+ *   leg 1 commits, its `store.put` fails, the operator re-runs the identical command
+ *   → "fleet enrollment failed before completion"
+ *
+ * That is the message-board#176 shape verbatim, in the case most likely to produce a
+ * duplicate agent, because a failed local write is exactly when an operator retries.
+ *
+ * The round-2 fence cannot reach it: the fence arms off a STORED outcome, and this is the
+ * path where storing it is what failed. Nor can any marker written before the commit —
+ * `store.get` itself can fail (an unsafe state directory), and then no local record is
+ * readable at all. Both variants were driven and both printed the sentence.
+ *
+ * So the resume's default is unconditional: when this CLI cannot PROVE the enrollment
+ * uncommitted, it says it does not know. The deliberate cost is that a first resume whose
+ * genuine pre-commit failure is unrecognised now also reads "unknown" — the CLI cannot
+ * distinguish that from "committed, and the record of it was lost", and inventing the
+ * distinction is what produced the lie.
+ *
+ * The DETAIL IS WITHHELD, on the `FleetPostCommitError` discipline: this converts errors
+ * the redaction was protecting the operator from, so only a fixed sentence and a
+ * shape-gated `code` cross. Anything already safe — a pre-flight refusal, the fence's own
+ * post-commit or indeterminate message — passes through untouched.
+ */
+async function throughResumeCommitUnknown(action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (error instanceof FleetSafeMessageError)
+            throw error;
+        throw new FleetSafeMessageError("fleet_device_resume_failed_commit_unknown", "this fleet device resume failed, and whether the enrollment COMMITTED is UNKNOWN: an earlier leg of this "
+            + "enrollment may have committed on the server without this host recording it. The bounded invite use may or "
+            + "may not be spent. Do NOT re-run this blindly: verify whether the agent identity now exists on the board, "
+            + `and enroll again only if it does not.${namedCauseCode(error)}`);
+    }
+}
 /**
  * Everything inside `action` runs against a COMMITTED server enrollment. Marks any
  * failure so the redaction below reports it truthfully instead of asserting it happened
@@ -184,11 +264,30 @@ function renderIds(facts) {
     // 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);
+    // THREE typed gates now, not one (Consiliency/message-board#402). `boardId` and
+    // `machineId` are OPERATOR-SUPPLIED on the indeterminate path — `localFacts` takes them
+    // from the intent, deliberately, so the message reports what the enrollment ASKED FOR —
+    // and the generic `printable` alphabet is a superset of base64url, which is what
+    // `create_invite_link` mints. A bounded invite code pasted into `--board-id` was therefore
+    // echoed here, on a path that needs no injected runner: an off-contract server answer is
+    // all it takes.
+    //
+    // The fix is the same argument the `agentId` gate already makes, extended to the two
+    // fields it fits: `boards.id` and `fleet_machines.id` are `uuid primary key`, so a
+    // non-UUID value in either is off-contract and rendering it would be rendering something
+    // the field cannot legitimately be. A type check derived from the schema, not a guess at
+    // what a credential looks like — that guess has been wrong twice on this branch.
+    //
+    // RESIDUAL, stated rather than papered over: `agentHandle` is a slug with no type to
+    // derive, so it keeps the generic gate. Reaching it with a code requires the code in BOTH
+    // `--harness-kind` and `--expected-agent-handle` (as `<host>-<code>`), because the argv
+    // census refuses a single-flag paste — the handle must end with `-<harness-kind>` — before
+    // any server call. Narrow, contrived, and real; recorded rather than closed.
     return [
         ["agentId", facts.agentId, isUuid],
         ["agentHandle", facts.agentHandle, printable],
-        ["boardId", facts.boardId, printable],
-        ["machineId", facts.machineId, printable],
+        ["boardId", facts.boardId, isUuid],
+        ["machineId", facts.machineId, isUuid],
     ].filter(([, value, ok]) => value !== "" && ok(value)).map(([key, value]) => `${key}=${value}`).join(", ");
 }
 /**
@@ -293,9 +392,17 @@ async function runHandler(io, operation, action, redactFleetFailure = false) {
     catch (error) {
         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.
+        // message; a pre-flight refusal keeps the flag the operator must set.
+        //
+        // BOTH FIELDS, not just the message (Consiliency/message-board#402). `toOperationFailure`
+        // copies any string `Error.code` onto the envelope, and this gate used to rewrite
+        // `message` alone — so a value placed in `code` reached stdout through a field the
+        // redaction never touched. That is the #214 shape exactly: a field-level gate that was
+        // one field narrower than the class it was defending. The two are rewritten together
+        // because they are one decision — whether this error's text is ours to print.
         if (redactFleetFailure && !(error instanceof FleetSafeMessageError)) {
             failure.error.message = "fleet enrollment failed before completion";
+            failure.error.code = "unknown";
         }
         writeFailureEnvelope(io, failure);
         process.exitCode = 1;
@@ -1633,8 +1740,9 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
             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 "
+                    + "runtime output and the fleet finalization. THIS command stopped before any server call and "
+                    + "spent nothing itself; whether an EARLIER leg committed cannot be told from here, 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.");
@@ -1801,23 +1909,124 @@ 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>. `
+        throw new FleetPreflightError("fleet_publishable_key_missing", 
+        // ONLY OUR OWN LITERAL. Two shape gates were tried here and BOTH rested on a false
+        // claim about what a credential can look like (Consiliency/message-board#402).
+        //
+        // The first was `normalizePublishableKeyFieldReference`'s own POSIX name rule, which a
+        // lowercase token satisfies. The second was SCREAMING_SNAKE_CASE, defended on the
+        // ground that "this system's invite codes are UUIDs" — checked against codes that
+        // happened to be at hand rather than against the ISSUER. Derived properly:
+        // `create_fleet_onboarding_invite` delegates to `create_invite_link`, whose code is
+        // `rtrim(translate(encode(gen_random_bytes(32),'base64'),'+/','-_'),'=')` — base64url
+        // over `A-Za-z0-9-_`. `[A-Z0-9_]` is a SUBSET of that alphabet, so an uppercase
+        // underscored fleet invite code is a reachable value, not a theoretical residual.
+        //
+        // No third shape gate. A value the operator supplied is not echoed, full stop, which
+        // is the same rule every other flag on this path already follows. The refusal stays
+        // actionable — it is not redacted, it names the flag and the code, and the variable
+        // name is in the fleet onboarding instructions this command was invoked from, which is
+        // where the operator got it. The DEFAULT is still named because it is this file's own
+        // literal and nothing operator-supplied reaches it.
+        (reference === DEFAULT_PUBLISHABLE_KEY_FIELD_REFERENCE
+            ? `fleet onboarding requires the publishable key in this host's environment: export ${DEFAULT_PUBLISHABLE_KEY_FIELD_REFERENCE}=<project anon/publishable key>. `
+            : "fleet onboarding requires the publishable key in this host's environment, in the variable named by this "
+                + "enrollment's --publishable-key-field-reference. That value is not echoed back: it is operator-supplied, "
+                + "and a bearer code pasted into the wrong flag would be echoed with it. Read the name from the fleet "
+                + "onboarding instructions this command was invoked from. ")
             + "The variable name was frozen at mint time by --publishable-key-field-reference.");
     }
     return value;
 }
+/**
+ * THE EXPECTED-HANDLE RULE, in one place (Consiliency/message-board#401).
+ *
+ * Stated once and consumed twice: by the argv-layer census below, which reports it
+ * ALONGSIDE the other unmet preconditions, and by `buildPendingFleetTemplate`, which is
+ * the boundary that actually depends on it (`host` is the handle minus this suffix). A
+ * second copy of the rule is the drift this repo keeps paying for, and the two copies
+ * that would exist here are the two that must agree.
+ *
+ * Returns the operator-facing sentence, or `undefined` when the rule holds.
+ */
+function expectedHandleSuffixFailure(expectedAgentHandle, harnessKind) {
+    if (expectedAgentHandle.endsWith(`-${harnessKind}`))
+        return undefined;
+    // A TEMPLATE, never the operator's own value (Consiliency/message-board#402).
+    //
+    // An earlier revision echoed `--harness-kind` through a shape gate. A shape gate is not
+    // a secrecy gate: this deployment's invite codes are UUIDs, and a UUID is lowercase
+    // hexadecimal and hyphens — it passes any plausible "looks like a harness kind" test.
+    // A bearer code pasted into the wrong flag, which is precisely the operator error this
+    // message exists to catch, would then have been printed by the diagnostic.
+    //
+    // There is no closed vocabulary of harness kinds to draw from (checked, not assumed —
+    // the column is free text), so nothing operator-supplied is echoed at all. The rule is
+    // fully actionable stated as a template plus an example this file writes.
+    return '--expected-agent-handle must end with "-" followed by your --harness-kind '
+        + '(so --harness-kind codex requires a handle like "myhost-codex"): the fleet template derives this '
+        + "host's slug from the part of the handle BEFORE that suffix, so a handle that does not carry it "
+        + "names no host. Neither value is echoed here — a bearer code pasted into the wrong flag would be "
+        + "echoed with it.";
+}
+/**
+ * THE LOCAL-KEY PIN, stated once for the two sites that check it (#401).
+ *
+ * BOTH halves are reported in one pass, and NOTHING derived from operator input is printed
+ * (#402). The earlier revision echoed the derived `localKeyId` as the value to use, which
+ * looked safe because the library composes it — but it composes it as
+ * `agent-board/<host>/<harness-kind>` from the operator's own `--expected-agent-handle` and
+ * `--harness-kind`, so a bearer code pasted into either flag came back out inside it. The
+ * rule is stated as a template instead, which is strictly more useful anyway: it tells the
+ * operator how the value is built rather than only what it is this once.
+ *
+ * The key reference is not printed for the older reason: its handle is the local key
+ * descriptor the blanket fleet redaction exists to keep out of a terminal.
+ */
+function localKeyMismatchFailure(pending, intent, ref) {
+    const mismatched = [];
+    if (pending.localKeyId !== intent.localKeyId)
+        mismatched.push("--local-key-id");
+    if (pending.keyReference !== `${ref.resolver}:${ref.handle}`)
+        mismatched.push("this host's configured keystore key reference");
+    if (!mismatched.length)
+        return undefined;
+    return `the fleet template this enrollment derives does not agree with ${mismatched.join(" and ")}. `
+        + '--local-key-id must be exactly "agent-board/<host>/<harness-kind>", where <host> is your '
+        + '--expected-agent-handle with its trailing "-<harness-kind>" removed. Neither the derived value nor '
+        + "the key reference is echoed: both are composed from operator-supplied flags, and its handle is a "
+        + "local key descriptor.";
+}
 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");
+    // #401 — every throw in this function is a FleetSafeMessageError rather than a plain
+    // `Error`, and the base class rather than `FleetPreflightError`: this function is called
+    // pre-commit by both fleet paths AND post-commit through `finalizeFleetOutcomeInner`'s
+    // `frozenPending ??` fallback, so the pre-flight class's stated contract ("the bounded
+    // invite use is not spent") would be a claim this site cannot make. The redaction
+    // exemption is `instanceof FleetSafeMessageError`, so the base class is equally exempt;
+    // post-commit, `afterFleetCommit` still rewrites the whole thing into the COMMITTED
+    // message and carries this text as its detail, which is the truthful framing.
+    const suffixFailure = expectedHandleSuffixFailure(intent.expectedAgentHandle, intent.harnessKind);
+    if (suffixFailure)
+        throw new FleetSafeMessageError("fleet_onboarding_expected_handle_invalid", suffixFailure);
     const host = intent.expectedAgentHandle.slice(0, -suffix.length);
     const deployment = resolveJoinDeployment();
-    if (!deployment.keyReference)
-        throw new Error("fleet_onboarding_key_reference_missing");
+    if (!deployment.keyReference) {
+        throw new FleetSafeMessageError("fleet_onboarding_key_reference_missing", "fleet onboarding needs this host's keystore key reference: export "
+            + "MESSAGE_BOARD_ENROLL_KEY_REFERENCE=<resolver>:<handle>. The variable NAME is named here; "
+            + "its value is a local key handle and is never printed.");
+    }
     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");
+    if (!platform) {
+        // The SUPPORTED resolvers are a closed vocabulary this file writes; the configured one
+        // is not, and it is the left half of a reference whose right half is a key handle. So
+        // the message names what is accepted and stays silent about what was found.
+        throw new FleetSafeMessageError("fleet_onboarding_unsupported_key_reference", "fleet onboarding supports only an os_keychain (desktop) or agent_socket (headless linux) key "
+            + "reference; MESSAGE_BOARD_ENROLL_KEY_REFERENCE names neither. The configured resolver is not "
+            + "printed because it is half of a local key descriptor.");
+    }
     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,
@@ -1825,8 +2034,9 @@ function buildPendingFleetTemplate(intent, publishableKeyFieldReference = DEFAUL
         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");
+    const mismatch = localKeyMismatchFailure(pending, intent, ref);
+    if (mismatch)
+        throw new FleetSafeMessageError("fleet_onboarding_local_key_mismatch", mismatch);
     return pending;
 }
 async function finalizeFleetOutcome(options, intent, result, frozenPending) {
@@ -1848,8 +2058,13 @@ async function finalizeFleetOutcome(options, intent, result, frozenPending) {
 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");
+    // Base class, not `FleetPreflightError`: this whole function runs against a COMMITTED
+    // enrollment on both fleet paths, so the pre-flight class's "the invite use is not spent"
+    // would be false here. `afterFleetCommit` rewrites it into the COMMITTED message anyway;
+    // the classification only decides whether this sentence survives as its detail.
+    if (!options.runtimeOutput) {
+        throw new FleetSafeMessageError("fleet_onboarding_runtime_output_missing", "--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
@@ -1861,8 +2076,9 @@ async function finalizeFleetOutcomeInner(options, intent, result, frozenPending)
         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 mismatch = localKeyMismatchFailure(pending, intent, ref);
+    if (mismatch)
+        throw new FleetSafeMessageError("fleet_onboarding_local_key_mismatch", 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
@@ -1919,6 +2135,67 @@ function fleetTupleValue(field, value) {
         return disposition.normalize(value);
     return value;
 }
+/** The role pair rule, stated once for the two builders and the census that reports it. */
+function fleetRolePairHolds(options) {
+    return (options.agentRole === "phase_worker" && options.repoScopeRole === "worker")
+        || (options.agentRole === "reviewer" && options.repoScopeRole === "reviewer");
+}
+/**
+ * EVERY unmet argv-layer precondition, in ONE pass (Consiliency/message-board#401).
+ *
+ * The command's input is a SINGLE-USE bounded invite. The previous shape reported the
+ * first unmet precondition and stopped, so an operator learned of `--local-key-id` only
+ * after every other flag was already right, and of the expected-handle rule only after
+ * that — each discovery costing a run made with a consumable secret in hand.
+ *
+ * WHAT THIS PASS COVERS, stated precisely because the honest scope is narrower than "all
+ * preconditions": the checks whose whole input is argv. The suffix rule is folded in from
+ * `buildPendingFleetTemplate` because it needs only two flags. The rules that need this
+ * HOST — the keystore key reference, the derived `--local-key-id` equality, the publishable
+ * key, the runtime-output directory — cannot be decided here and are still sequential;
+ * each of those now names its own rule instead, which is the other half of the fix.
+ *
+ * Normalization comes from `FLEET_TUPLE_DISPOSITION` via `fleetTupleValue`, never
+ * re-derived here: a second copy of "trim, and lowercase the harness kind" would be free
+ * to disagree with the copy that decides what actually crosses.
+ */
+function fleetArgvPreconditionFailures(required, options) {
+    const failures = [];
+    const missing = required.filter(([, value]) => !value?.trim()).map(([name]) => name);
+    if (missing.length)
+        failures.push(`missing: ${missing.join(", ")}`);
+    // Both-present guard on each derived rule: a flag that is absent is already named above,
+    // and reporting it a second time as a broken rule reads as two defects where there is one.
+    if (options.agentRole?.trim() && options.repoScopeRole?.trim() && !fleetRolePairHolds(options)) {
+        // The supplied values are not echoed: the rule is a closed vocabulary this file writes,
+        // and the operand is unbounded operator input.
+        failures.push("--agent-role/--repo-scope-role must be phase_worker/worker or reviewer/reviewer");
+    }
+    if (options.harnessKind?.trim() && options.expectedAgentHandle?.trim()) {
+        const suffix = expectedHandleSuffixFailure(fleetTupleValue("expectedAgentHandle", options.expectedAgentHandle), fleetTupleValue("harnessKind", options.harnessKind));
+        if (suffix)
+            failures.push(suffix);
+    }
+    return failures;
+}
+/**
+ * The closing sentence is the CALLER's, not this function's (Consiliency/message-board#402).
+ *
+ * A world-state assurance belongs only where it is unconditionally true. `run` and device
+ * `begin` are one-shot: reaching this refusal means no server call happened on any leg, so
+ * they say so. A device RESUME says nothing about commit status at all — it may be the
+ * second leg of an enrollment the server already committed, and the fence around it (or, if
+ * `store.put` failed and no outcome was recorded, the absence of any local evidence) is what
+ * decides that. An earlier revision shared one sentence between them, and the resume's
+ * committed envelope then carried "spent nothing itself" as the detail of a message whose
+ * framing said the invite use was spent. Both halves were literally true of their own
+ * subject and the pair was unreadable.
+ */
+function renderFleetPreconditionFailures(subject, failures, closing) {
+    return `${subject}: ${failures.length} unmet precondition${failures.length === 1 ? "" : "s"} — `
+        + failures.map((failure, index) => `(${index + 1}) ${failure}`).join(" ")
+        + ` ${closing}`;
+}
 function fleetResumeIntentFromCli(options) {
     const required = [
         ["--slug", options.slug], ["--board-id", options.boardId], ["--machine-id", options.machineId],
@@ -1928,13 +2205,12 @@ function fleetResumeIntentFromCli(options) {
         ["--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");
+    const failures = fleetArgvPreconditionFailures(required, options);
+    if (failures.length) {
+        throw new FleetPreflightError("fleet_device_resume_preconditions_unmet", 
+        // No commit-status claim: a resume can be the second leg of a committed enrollment.
+        renderFleetPreconditionFailures("fleet device resume", failures, "Fix all of the above in one edit and re-run."));
+    }
     // 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(() => ({
@@ -1951,27 +2227,37 @@ function fleetResumeIntentFromCli(options) {
 async function enrollmentIntentFromCli(options) {
     if (!options.fleetOnboarding)
         return intentFromOptions(options);
+    // Stays BEFORE the stdin read, deliberately: moving it after would drain a piped invite
+    // code on a command that is going to refuse anyway, for no diagnostic gain.
     if (options.createBoard || options.joinBoard || options.board === false) {
-        throw new Error("--fleet-onboarding cannot be combined with --create-board, --join-board, or --no-board");
+        throw new FleetPreflightError("fleet_onboarding_conflicting_intent_flags", "--fleet-onboarding cannot be combined with --create-board, --join-board, or --no-board: a fleet "
+            + "invite already names the board this enrollment joins. This command stopped before any server call and spent nothing itself.");
     }
     let inviteCode = options.inviteCode;
     if (!inviteCode)
         inviteCode = await readCodeFromStdin();
     const required = [
         ["invite code (stdin or --invite-code)", inviteCode],
+        // #402 — the flag an operator is most likely to omit, and the one that used to escape
+        // this collector entirely. `fleetResumeIntentFromCli` has always required it; the two
+        // builders are symmetric again.
+        ["--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],
+        // #401 — every fleet caller of this builder requires it (`run` finalizes into it,
+        // `device` begin refuses without it), and it was the one required flag whose absence
+        // reached the operator as a redacted `invalid_runtime_output` from the filesystem layer.
+        ["--runtime-output", options.runtimeOutput],
     ];
-    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");
+    const failures = fleetArgvPreconditionFailures(required, options);
+    if (failures.length) {
+        throw new FleetPreflightError("fleet_onboarding_preconditions_unmet", 
+        // One-shot callers only (`run`, device `begin`), so the assurance is unconditional.
+        renderFleetPreconditionFailures("--fleet-onboarding", failures, "This command stopped before any server call and spent nothing itself; fix all of the above in one edit and re-run."));
+    }
     // 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.
@@ -2087,7 +2373,14 @@ function addEnrollCommands(program, io, enrollment) {
     const runCommand = enroll
         .command("run", { isDefault: true })
         .description("one-shot enrollment over an RFC 8252 loopback receiver")
-        .requiredOption("--slug <slug>", "desired agent slug")
+        // NOT `requiredOption` (Consiliency/message-board#402). Commander enforces that one
+        // BEFORE any action runs: it prints its own usage line to the process's stderr and
+        // exits, so `--slug` never reached the one-pass collector and the operator got a usage
+        // string instead of the JSON envelope every other failure on this command produces —
+        // for the flag they are most likely to omit. The requirement is not dropped; it moved
+        // to the collector (fleet) and to an explicit guard (non-fleet), both of which answer
+        // in the envelope.
+        .option("--slug <slug>", "desired agent slug")
         .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")
@@ -2099,6 +2392,12 @@ 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 () => {
+        // The non-fleet half of what `requiredOption` used to do. The fleet half is the
+        // collector's; this arm keeps its own guard because `enrollmentIntentFromCli`
+        // returns before the collector when `--fleet-onboarding` is absent.
+        if (!options.fleetOnboarding && !options.slug?.trim()) {
+            throw new FleetPreflightError("enroll_run_slug_required", "enroll run requires --slug");
+        }
         // 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
@@ -2204,7 +2503,15 @@ function addEnrollCommands(program, io, enrollment) {
         .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)");
+                // #402 — a SAFE message rather than a plain `Error`. These two fire BEFORE the
+                // continuation is read, so they sit outside `throughResumeCommitUnknown` and were
+                // redacted to "fleet enrollment failed before completion" — an unqualified claim
+                // on a resume, where an earlier leg may have committed. Classified here instead
+                // of moved inside the wrapper, so the integrator facing them keeps the one thing
+                // that makes them actionable: the name of the method that is missing.
+                throw new FleetSafeMessageError("fleet_device_resume_runner_incomplete", "device resume is not supported by this runner (EnrollmentCommandRunner.deviceComplete is not "
+                    + "implemented). This says nothing about whether an earlier leg of this enrollment committed: "
+                    + "nothing was read from this host's continuation before the refusal.");
             }
             if (!options.fleetOnboarding) {
                 // #210, second half — shaped on the OUTCOME, not on the flag. `fleetSafeOutput`
@@ -2223,57 +2530,112 @@ function addEnrollCommands(program, io, enrollment) {
                 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)");
+                throw new FleetSafeMessageError("fleet_device_resume_runner_incomplete", "fleet device resume is not supported by this runner (EnrollmentCommandRunner.deviceDeletePending is "
+                    + "not implemented). This says nothing about whether an earlier leg of this enrollment committed: "
+                    + "nothing was read from this host's continuation before the refusal.");
             }
-            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;
+            // Starts at the STORE, not after it: `store.get` can fail on its own (an unsafe
+            // state directory), and that failure was redacted to "failed before completion"
+            // with no continuation readable — the variant no marker could ever have fenced.
+            //
+            // One wrapper covers both branches because the armed one cannot reach it:
+            // `afterFleetCommit` turns every failure under it into a `FleetPostCommitError`,
+            // which this converter passes through by class.
+            return throughResumeCommitUnknown(async () => {
+                const store = new FleetDeviceContinuationStore(defaultDevicePendingStateDir(process.env));
+                const continuation = await store.get(options.enrollmentId);
+                if (!continuation) {
+                    throw new FleetPreflightError("fleet_device_continuation_unknown", "no fleet device continuation is stored on this host for that --enrollment-id. A fleet resume needs the "
+                        + "state written by the matching `enroll device --fleet-onboarding` begin, on this same machine and user "
+                        + "account; a completed resume DELETES it. So this says nothing about whether an enrollment committed: "
+                        + "a begin that never ran here and a resume that already finished both look like this. Verify on the board "
+                        + "before enrolling again. The id itself is not echoed.");
+                }
+                // THE RESUME FENCE (Consiliency/message-board#402).
+                //
+                // A stored `outcome` is the evidence that the server ALREADY COMMITTED this
+                // enrollment: the tail below persists it, inside `afterFleetCommit`, only after
+                // `deviceComplete` returned one. Everything from here to that tail — the argv
+                // census, the template build, the continuation comparison, the runtime-output
+                // preparation — used to run outside any fence, so an operator retrying a resume
+                // after a committed-but-unfinalized leg (the realistic retry: a dropped flag, a
+                // corrected `--runtime-output`) was told the enrollment had not happened. That is
+                // the #176 shape the whole classification exists to prevent, and its cost is a
+                // second enrollment against a second invite.
+                //
+                // Reusing `afterFleetCommit` rather than composing a second truth: one function
+                // decides what a post-commit failure says. Nesting is safe — the tail's own
+                // `afterFleetCommit` produces a `FleetPostCommitError`, which this one rethrows
+                // unchanged — and `throughFleetCommit` cannot collide with it, because that runs
+                // only when `committedThisLeg`, which is exactly when this fence is NOT armed.
+                //
+                // The fence is necessary but NOT sufficient, which is why every message on this
+                // path also had its commit-status claim removed unconditionally: if leg 1 commits
+                // and the `store.put` that records it FAILS (cli.test.ts pins that case), the
+                // server has committed and no `outcome` is stored, so nothing here can arm.
+                const resumeAfterCommit = continuation.outcome;
+                const finishResume = async () => {
+                    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;
+                    // #401 — ALL differing comparisons, named together, from a closed set of literals
+                    // this file writes. Only the NAME of each comparison crosses; no operand does,
+                    // because two of the five are a key reference and a whole template.
+                    const divergent = [
+                        ["--slug", options.slug.trim() !== pending.agentSlug],
+                        ["--runtime-output", options.runtimeOutput !== continuation.runtimeOutput],
+                        ["the keystore key reference", continuation.keyReference !== pending.keyReference],
+                        ["--publishable-key-field-reference", continuation.publishableKeyFieldReference !== pending.publishableKeyFieldReference],
+                        ["the 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)",
+                            JSON.stringify(candidate) !== JSON.stringify(pending)],
+                    ].filter(([, differs]) => differs).map(([name]) => name);
+                    if (divergent.length) {
+                        throw new FleetPreflightError("fleet_device_continuation_mismatch", `this resume does not match the fleet device begin it claims to continue — ${divergent.join(", ")} `
+                            + `${divergent.length === 1 ? "differs" : "differ"} from the stored continuation. Re-run the resume with the `
+                            + "exact arguments of the begin. The continuation was kept.");
+                    }
+                    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;
+                    });
+                };
+                return resumeAfterCommit ? afterFleetCommit(resumeAfterCommit, finishResume) : finishResume();
             });
         }
-        if (!options.slug)
-            throw new Error("enroll device requires --slug when --enrollment-id is absent");
+        // Non-fleet only (#402). A fleet begin gets `--slug` from the collector below,
+        // alongside every other unmet precondition, instead of one refusal ahead of it.
+        if (!options.fleetOnboarding && !options.slug) {
+            throw new FleetPreflightError("enroll_device_slug_required", "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)");
@@ -2282,8 +2644,11 @@ function addEnrollCommands(program, io, enrollment) {
             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");
+            // Unreachable today — the argv census above now names `--runtime-output` — and kept
+            // as the boundary's own guard rather than as the operator's first notice of it.
+            if (!options.runtimeOutput) {
+                throw new FleetPreflightError("fleet_onboarding_runtime_output_missing", "--fleet-onboarding requires --runtime-output");
+            }
             await prepareFleetRuntimeOutput(options.runtimeOutput);
             // Before a human approval is spent, and before any continuation state exists
             // to clean up.
@@ -2298,7 +2663,18 @@ function addEnrollCommands(program, io, enrollment) {
                     intent, requestedScopes: csv(options.requestedScopes), requestedBoardScopes: csv(options.requestedBoardScopes) });
                 if (begun.enrollmentId !== enrollmentId)
                     throw new Error("fleet_device_enrollment_id_mismatch");
-                return begun;
+                // SHAPED, not passed through (#402). `runHandler` serializes whatever this
+                // returns, and the runner is an injection seam that received the whole intent —
+                // `inviteCode` included — so any extra property it put on its result reached
+                // stdout. The same reasoning `fleetSafeOutput` already applies to an outcome;
+                // this was the one enroll result that had no such waist.
+                return { enrollmentId: begun.enrollmentId, prompt: {
+                        userCode: begun.prompt.userCode,
+                        verificationUri: begun.prompt.verificationUri,
+                        ...(begun.prompt.verificationUriComplete === undefined ? {} : { verificationUriComplete: begun.prompt.verificationUriComplete }),
+                        ...(begun.prompt.expiresIn === undefined ? {} : { expiresIn: begun.prompt.expiresIn }),
+                        ...(begun.prompt.interval === undefined ? {} : { interval: begun.prompt.interval }),
+                    } };
             }
             catch (error) {
                 await store.delete(enrollmentId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.13.0",
+  "version": "1.15.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.24.0",
+    "@consiliency/agent-board-client": "1.25.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0"