@consiliency/agent-board-cli 1.16.0 → 1.19.0

package/dist/cli.d.ts

@@ -79,6 +79,7 @@ interface ClientLike {
     agentDashboard(input: JsonObject): Promise<unknown>;
     agentInbox(input: JsonObject): Promise<unknown>;
     agentInboxCounts(input: JsonObject): Promise<unknown>;
+    wakeRecovery(input: JsonObject): Promise<unknown>;
     boardDirectory(input: JsonObject): Promise<unknown>;
     boardMemberships(input: JsonObject): Promise<unknown>;
     boardFeed(input: JsonObject): Promise<unknown>;

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, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, 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, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, } 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);
@@ -29,6 +29,7 @@ class FleetSafeMessageError extends Error {
         super(message);
         this.code = code;
         this.name = "FleetSafeMessageError";
+        markAuthoredCode(this);
     }
 }
 /**
@@ -70,17 +71,21 @@ class FleetPreflightError extends FleetSafeMessageError {
  * blanket redaction is for.
  */
 class FleetPostCommitError extends FleetSafeMessageError {
-    constructor(committedFacts, cause) {
+    constructor(committedFacts, origin, 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 committed = renderIds(committedFacts, origin)
+            || (origin === "receipt"
+                ? "(the receipt carried no id we could verify)"
+                : "(this enrollment named nothing to verify against)");
         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}`);
+            + `${origin === "receipt" ? "Committed" : "Verify against the values you passed as"}: ${committed}. `
+            + `Local finalization failure: ${detail}`);
         this.cause = cause;
     }
 }
@@ -140,29 +145,34 @@ function throughPresentationGate(action) {
     }
 }
 /**
- * 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.
+ * The one-word cause discriminator, restored on a PROVENANCE gate (#403) after #402
+ * withdrew it. #402's two shape gates both rested on a claim about what a credential can
+ * look like (a snake_case alphabet, then a 42-character cap) and a fleet invite code or a
+ * short OAuth `device_code` fits either. There is no third shape bound, so this gate asks
+ * a different question: did WE write this value?
  *
- * 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.
+ * Property (plan §2.1): returns ` [code <cause.code>]` iff `cause.code` is a string equal
+ * to a member of AUTHORED_CAUSE_CODES — the set derived by
+ * `scripts/derive-authored-cause-codes.mjs` from every literal this repository assigns to
+ * an error `code` — AND the instance carries the authored value-bound brand for that exact
+ * value (`codeProvenance(cause) === "authored"`, see code_provenance.ts). Both halves are
+ * needed: the set alone would print a server body that happens to equal a member; the
+ * brand alone would print a value the brand was never bound to. A foreign value therefore
+ * reaches the operator only if it is already a published member of the set (it carries no
+ * foreign byte) AND arrived through an instance that was branded authored for it (R6-1:
+ * an equal-value overwrite of an authored code is one bit of equality, not a leak).
  *
- * 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.
+ * Every other input returns "": a non-object, a non-string `code`, a non-member, an
+ * unbranded instance, a `"foreign"`-branded instance, or an instance whose `code` was
+ * written after it was branded.
  */
-function namedCauseCode(_cause) {
-    return "";
+function namedCauseCode(cause) {
+    if (cause === null || typeof cause !== "object")
+        return "";
+    const { code } = cause;
+    if (typeof code !== "string" || !AUTHORED_CAUSE_CODES.has(code))
+        return "";
+    return codeProvenance(cause) === "authored" ? ` [code ${code}]` : "";
 }
 function committedFactsFromOutcome(outcome) {
     return {
@@ -227,7 +237,7 @@ async function afterFleetCommit(outcome, action) {
         return await action();
     }
     catch (error) {
-        throw error instanceof FleetPostCommitError ? error : new FleetPostCommitError(committedFactsFromOutcome(outcome), error);
+        throw error instanceof FleetPostCommitError ? error : new FleetPostCommitError(committedFactsFromOutcome(outcome), "receipt", error);
     }
 }
 /**
@@ -235,60 +245,42 @@ async function afterFleetCommit(outcome, action) {
  * 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);
-    // 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.
+function renderIds(facts, origin) {
+    // FACTS ARE RENDERED BY WHERE THEY CAME FROM, NEVER BY WHAT THEY LOOK LIKE
+    // (Consiliency/message-board#404).
     //
-    // 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.
+    // This function used to hold three shape gates — a permissive `printable` alphabet and
+    // a UUID test — and both were the wrong instrument twice over. A shape gate on the
+    // INTENT arm bounds an echo of the operator's own argument instead of removing it: the
+    // alphabet is a superset of base64url, so a bounded invite code pasted into `--board-id`
+    // passed it, and `<host>-<code>` passed the handle's. A shape gate on the RECEIPT arm is
+    // a second, weaker copy of the `exact` check the value already passed, and it HID a
+    // legitimate id whose shape the schema does not actually pin.
     //
-    // 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, isUuid],
-        ["machineId", facts.machineId, isUuid],
-    ].filter(([, value, ok]) => value !== "" && ok(value)).map(([key, value]) => `${key}=${value}`).join(", ");
+    // So there is no predicate here at all, and none can be reintroduced without failing
+    // B1a (a value hidden on the intent arm whatever its shape) or B2 (a value shown on the
+    // receipt arm whatever its shape).
+    const present = [
+        ["agentId", facts.agentId],
+        ["agentHandle", facts.agentHandle],
+        ["boardId", facts.boardId],
+        ["machineId", facts.machineId],
+    ].filter(([, value]) => value !== "");
+    if (origin === "receipt") {
+        // The server's own answer, after `exact` required it to equal the authorized tuple —
+        // the same strings the success path prints in full.
+        return present.map(([key, value]) => `${key}=${value}`).join(", ");
+    }
+    // The operator's own arguments. The value is theirs already; what the message has to
+    // carry is WHICH enrollment and WHAT to verify against, and the flag names carry that.
+    // `agentId` and `keyId` are `""` on this arm by construction (`enroll.ts` localFacts),
+    // so they contribute nothing and are not in the map.
+    const FLAG_OF_INTENT_FACT = {
+        agentHandle: "--expected-agent-handle",
+        boardId: "--board-id",
+        machineId: "--machine-id",
+    };
+    return present.map(([key]) => FLAG_OF_INTENT_FACT[key]).filter((flag) => flag !== undefined).join(", ");
 }
 /**
  * Raised when the server's answer was OFF-CONTRACT, so whether it committed is unknown.
@@ -303,9 +295,11 @@ class FleetIndeterminateError extends FleetSafeMessageError {
         // 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 rendered = renderIds(marker.facts, marker.origin);
         const observed = rendered
-            ? ` What this enrollment asked for, to verify against: ${rendered}.`
+            ? (marker.origin === "receipt"
+                ? ` Ids from the server's answer, to verify against: ${rendered}.`
+                : ` Verify against the values you passed as: ${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
@@ -340,7 +334,7 @@ async function throughFleetCommit(call) {
             throw error;
         throw marker.state === "indeterminate"
             ? new FleetIndeterminateError(marker, error)
-            : new FleetPostCommitError(marker.facts, error);
+            : new FleetPostCommitError(marker.facts, marker.origin, error);
     }
 }
 /**
@@ -1512,6 +1506,27 @@ function addReadCommands(program, client, io) {
         recipientAgentId: options.recipientAgentId,
         limit: options.limit,
     })));
+    // WAKETIER0 (plans/WAKE-MULTIHARNESS-ROADMAP.md Phase 1). The terminal binding of
+    // the universal baseline. `wake-recovery` is the primary name and `agent-wake-recovery`
+    // the view-shaped alias, matching `agent-inbox`/`inbox` in the other direction: the
+    // join text an agent is handed spells the short form, so that is the one that must
+    // not drift.
+    //
+    // NO `--recipient-agent-id` OPTION, and its absence is the property (see the MCP
+    // registration): the view self-scopes to current_agent_id() in SQL, so a
+    // caller-supplied recipient could only ever contradict the session. Offering the
+    // flag would invite an operator to "check another agent's" recovery set and get
+    // their own rows back, silently.
+    program
+        .command("wake-recovery")
+        .alias("agent-wake-recovery")
+        .description("your OWN unhandled inbox items (Tier 0: a per-turn check, not a wake)")
+        .option("--board-id <boardId>")
+        .addOption(numberOption("--limit <limit>", "row limit"))
+        .action((options) => runHandler(io, "agent_board.v_agent_wake_recovery", () => client.wakeRecovery({
+        boardId: options.boardId,
+        limit: options.limit,
+    })));
     program
         .command("board-directory")
         .option("--board-id <boardId>")
@@ -2395,7 +2410,7 @@ function addEnrollCommands(program, io, enrollment) {
         // 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()) {
+        if (!options.fleetOnboarding && !String(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
@@ -2587,7 +2602,7 @@ function addEnrollCommands(program, io, enrollment) {
                     // 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],
+                        ["--slug", String(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],

package/dist/enroll_runtime.d.ts

@@ -1,8 +1,9 @@
 import type { EnrollmentOutcome, FinalizedFleetHarnessTemplate, PendingFleetHarnessTemplate } from "@consiliency/agent-board-client";
+import { type AuthoredCauseCode } from "@consiliency/agent-board-client";
 import { type EnrollmentIntent, type PendingEnrollment, type PendingEnrollmentStore } from "@consiliency/agent-board-client";
 export declare class EnrollRuntimeError extends Error {
     code: string;
-    constructor(code: string, message: string);
+    constructor(code: AuthoredCauseCode, message: string);
 }
 /** Versioned, non-secret continuation for an interrupted fleet device flow. */
 export interface FleetDeviceContinuation {

package/dist/enroll_runtime.js

@@ -8,7 +8,7 @@ import { constants as FS } from "node:fs";
 import * as fs from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { validateFinalizedFleetHarnessTemplate } from "@consiliency/agent-board-client";
+import { validateFinalizedFleetHarnessTemplate, markAuthoredCode } from "@consiliency/agent-board-client";
 import { resolveEnrollmentDescriptor, } from "@consiliency/agent-board-client";
 export class EnrollRuntimeError extends Error {
     code;
@@ -16,6 +16,7 @@ export class EnrollRuntimeError extends Error {
         super(message);
         this.name = "EnrollRuntimeError";
         this.code = code;
+        markAuthoredCode(this);
     }
 }
 export class FleetDeviceContinuationStore {

package/package.json

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