@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.2

package/src/plugin/fleet-target.mjs

@@ -34,6 +34,12 @@
  *   GET  /api/w2m/target?session_id=…   the fleet and this session's selection, as one snapshot
  *   POST /api/w2m/target                { session_id, machine_id|null } → the same snapshot
  *
+ * A refusal is `{ok: false, error, reason_code, detail}` with a `{@link TARGET_REFUSAL}` code and a
+ * `detail` that says what would change it; a `PUT`/`DELETE`/`PATCH` is a `405` rather than a write
+ * (only exactly `GET` and `POST` are answered), a machine the relay does not list is a `409` exactly
+ * like one it lists as offline, and `session_id` is capped at {@link MAX_SESSION_ID_LENGTH} characters
+ * on both verbs because the store keys on the whole string.
+ *
  * Plain `Response.json`, no Typert descriptor: this package is dependency-free, and a generated
  * strict Remote contribution is neither reachable from plain JavaScript nor worth a codec for one
  * object. Nothing else in the protocol changes — no new relay endpoint, no new tool parameter, no
@@ -76,6 +82,49 @@ export const NO_SESSION = '(no-session)';
 /** Session buckets retained before the oldest is evicted; a browse session cannot grow this. */
 export const MAX_SELECTIONS = 512;
 
+/**
+ * Longest `session_id` this route accepts, in characters (UTF-16 code units).
+ *
+ * `MAX_SELECTIONS` bounds how many buckets exist; it says nothing about how large one key is, and the
+ * store keeps the whole string. A caller that sends a 200,000-character id therefore allocates as much
+ * as it likes per request and gets it echoed back in the snapshot — the count cap bounds the *number*
+ * of sessions, never the *bytes*. 200 is a bound with room to spare: a DSH session id is a UUID (36
+ * characters), and 200 leaves room for a ULID, a path-shaped id or a test's own naming without
+ * inviting an unbounded key.
+ */
+export const MAX_SESSION_ID_LENGTH = 200;
+
+/**
+ * The `/api/w2m/target` route's refusals, in the house `{reason_code, detail}` shape.
+ *
+ * Deliberately a map of its own rather than a widening of `tools.mjs`'s `REFUSAL_CODE`: those codes name
+ * refusals on the *dispatch* path (which the eight tools report), while these name refusals at the
+ * route the browser calls, and `fleet-target.mjs` is imported *by* `tools.mjs` — importing back would
+ * be a cycle. `reason_code` is the greppable, stable identifier and `detail` says what would change it.
+ */
+export const TARGET_REFUSAL = Object.freeze({
+  /** A verb this route does not answer. Only exactly `GET` and `POST` are read or written. */
+  METHOD_NOT_ALLOWED: 'TARGET_METHOD_NOT_ALLOWED',
+  /** `GET` carried no `session_id`, so there is no session to answer for. */
+  SESSION_ID_REQUIRED: 'TARGET_SESSION_ID_REQUIRED',
+  /** `session_id` is longer than {@link MAX_SESSION_ID_LENGTH}. */
+  SESSION_ID_TOO_LONG: 'TARGET_SESSION_ID_TOO_LONG',
+  /** A `POST` body that could not be parsed as JSON at all. */
+  BODY_NOT_JSON: 'TARGET_BODY_NOT_JSON',
+  /** A `POST` body that is not a JSON object. */
+  BODY_NOT_AN_OBJECT: 'TARGET_BODY_NOT_AN_OBJECT',
+  /** `machine_id` was neither a string nor null. */
+  MACHINE_ID_NOT_A_STRING: 'TARGET_MACHINE_ID_NOT_A_STRING',
+  /** `machine_name` was neither a string nor null. */
+  MACHINE_NAME_NOT_A_STRING: 'TARGET_MACHINE_NAME_NOT_A_STRING',
+  /** The named machine is not one the relay lists at all. */
+  MACHINE_UNKNOWN: 'TARGET_MACHINE_UNKNOWN',
+  /** The named machine exists, and the relay does not call it online. */
+  MACHINE_OFFLINE: 'TARGET_MACHINE_OFFLINE',
+  /** The fleet could not be read, so no selection could be checked against it. */
+  FLEET_UNAVAILABLE: 'TARGET_FLEET_UNAVAILABLE',
+});
+
 /** How long the fleet roster may be reused by the control before it is asked for again. */
 export const FLEET_CACHE_MS = 10_000;
 
@@ -415,25 +464,55 @@ export function buildUiState(deps) {
 /**
  * Parse the JSON body of a selection write, refusing anything outside the declared shape.
  *
+ * Every refusal is a *value with a name*: `reason_code` is stable and greppable, and `detail` says what
+ * would have to change for the same request to be accepted. The route turns both into the response body
+ * verbatim, so the browser can show the reason without re-deriving it.
+ *
  * @param {unknown} body
- * @returns {{ok: true, value: {session_id: string, machine_id: string|null, machine_name: string|null}}|{ok: false, error: string}}
+ * @returns {{ok: true, value: {session_id: string, machine_id: string|null, machine_name: string|null}}
+ *   |{ok: false, error: string, reason_code: string, detail: string}}
  */
 export function parseSelectionWrite(body) {
+  const refuse = (error, reason_code, detail) => ({ ok: false, error, reason_code, detail });
   if (body === null || typeof body !== 'object' || Array.isArray(body)) {
-    return { ok: false, error: 'body must be a JSON object' };
+    return refuse(
+      'body must be a JSON object',
+      TARGET_REFUSAL.BODY_NOT_AN_OBJECT,
+      'send `{"session_id": "<id>", "machine_id": "<id>|null"}`',
+    );
   }
   const record = /** @type {Record<string, unknown>} */ (body);
   const sessionId = record.session_id;
   if (typeof sessionId !== 'string' || sessionId === '') {
-    return { ok: false, error: '`session_id` must be a non-empty string' };
+    return refuse(
+      '`session_id` must be a non-empty string',
+      TARGET_REFUSAL.SESSION_ID_REQUIRED,
+      'send the id of the session this selection belongs to',
+    );
+  }
+  if (sessionId.length > MAX_SESSION_ID_LENGTH) {
+    return refuse(
+      `\`session_id\` must be at most ${MAX_SESSION_ID_LENGTH} characters, got ${sessionId.length}`,
+      TARGET_REFUSAL.SESSION_ID_TOO_LONG,
+      `send the id the host gave this session (a UUID is 36 characters); anything longer than `
+        + `${MAX_SESSION_ID_LENGTH} characters is not a session id`,
+    );
   }
   const machineId = record.machine_id;
   if (machineId !== null && machineId !== undefined && typeof machineId !== 'string') {
-    return { ok: false, error: '`machine_id` must be a string or null' };
+    return refuse(
+      '`machine_id` must be a string or null',
+      TARGET_REFUSAL.MACHINE_ID_NOT_A_STRING,
+      'send a `machine_id` from the roster this route reports, or null to clear the selection',
+    );
   }
   const machineName = record.machine_name;
   if (machineName !== null && machineName !== undefined && typeof machineName !== 'string') {
-    return { ok: false, error: '`machine_name` must be a string or null' };
+    return refuse(
+      '`machine_name` must be a string or null',
+      TARGET_REFUSAL.MACHINE_NAME_NOT_A_STRING,
+      'send the machine\'s display name as a string, or leave it out and the relay\'s name is used',
+    );
   }
   return {
     ok: true,
@@ -603,11 +682,51 @@ function mountTargetRoutes(connection, deps, status, logger) {
     fetch: async (request) => {
       const url = new URL(request.url);
       const noStore = { 'cache-control': 'no-store' };
+      /**
+       * One refusal shape for the whole route: `{ok:false, error, reason_code, detail}`.
+       *
+       * @param {number} status
+       * @param {string} reasonCode A {@link TARGET_REFUSAL} value.
+       * @param {string} error What happened, in the host's own words (the control prints this).
+       * @param {string} detail What would change it.
+       * @returns {Response}
+       */
+      const refuse = (status, reasonCode, error, detail) =>
+        Response.json({ ok: false, error, reason_code: reasonCode, detail }, { status, headers: noStore });
+
+      // Defence in depth, and the one place it is cheap. The registration above declares
+      // `methods: ['GET', 'POST']`, so the host should never route a `PUT`/`DELETE`/`PATCH` here at all
+      // — but the handler used to treat *anything* that was not a GET as a write, which means a
+      // registration mistake, a host that forwards other verbs, or a future `methods` change would
+      // silently turn `DELETE /api/w2m/target` into "clear this selection". A route that writes must
+      // say which verbs write; everything else is refused by name rather than guessed at.
+      if (request.method !== 'GET' && request.method !== 'POST') {
+        return refuse(
+          405,
+          TARGET_REFUSAL.METHOD_NOT_ALLOWED,
+          `${request.method} is not a method this route answers`,
+          'GET reads the fleet and this session\'s selection and POST writes one; any other verb is refused '
+            + 'rather than treated as a write',
+        );
+      }
 
       if (request.method === 'GET') {
         const sessionId = url.searchParams.get('session_id');
         if (typeof sessionId !== 'string' || sessionId === '') {
-          return Response.json({ ok: false, error: '`session_id` query parameter is required' }, { status: 400 });
+          return refuse(
+            400,
+            TARGET_REFUSAL.SESSION_ID_REQUIRED,
+            '`session_id` query parameter is required',
+            'add `?session_id=<the session the control belongs to>`',
+          );
+        }
+        if (sessionId.length > MAX_SESSION_ID_LENGTH) {
+          return refuse(
+            400,
+            TARGET_REFUSAL.SESSION_ID_TOO_LONG,
+            `\`session_id\` must be at most ${MAX_SESSION_ID_LENGTH} characters, got ${sessionId.length}`,
+            `send the id the host gave this session (a UUID is 36 characters)`,
+          );
         }
         try {
           return Response.json(await snapshot(sessionId, request.signal), { headers: noStore });
@@ -623,10 +742,17 @@ function mountTargetRoutes(connection, deps, status, logger) {
       try {
         body = await request.json();
       } catch {
-        return Response.json({ ok: false, error: 'body is not JSON' }, { status: 400 });
+        return refuse(
+          400,
+          TARGET_REFUSAL.BODY_NOT_JSON,
+          'body is not JSON',
+          'send `{"session_id": "<id>", "machine_id": "<id>|null"}` as a JSON object',
+        );
       }
       const parsed = parseSelectionWrite(body);
-      if (!parsed.ok) return Response.json({ ok: false, error: parsed.error }, { status: 400 });
+      if (!parsed.ok) {
+        return refuse(400, parsed.reason_code, parsed.error, parsed.detail);
+      }
       const { session_id: sessionId, machine_id: machineId, machine_name: machineName } = parsed.value;
 
       if (machineId === null) {
@@ -642,16 +768,35 @@ function mountTargetRoutes(connection, deps, status, logger) {
       const cfg = deps.cfg();
       const fleet = await fleetFor(request.signal);
       if (fleet.ok !== true) {
-        return Response.json(
-          { ok: false, error: `the fleet could not be read, so no target was changed: ${fleet.error ?? 'unknown cause'}` },
-          { status: 503 },
+        return refuse(
+          503,
+          TARGET_REFUSAL.FLEET_UNAVAILABLE,
+          `the fleet could not be read, so no target was changed: ${fleet.error ?? 'unknown cause'}`,
+          'bring the relay back (or fix `rabbitUrl`) and choose again; nothing was selected in the meantime',
         );
       }
       const machine = fleet.machines.find((entry) => entry.machine_id === machineId) ?? null;
-      if (machine !== null && machine.online !== true) {
-        return Response.json(
-          { ok: false, error: `${machine.name ?? machineId} is listed as ${machine.state}, so it cannot be selected` },
-          { status: 409 },
+      // A machine the relay does not list *at all* is refused in exactly the same breath as one it lists
+      // as offline. The comment above always claimed this and the code did not do it: `machine === null`
+      // fell through to `store.set`, so `{"machine_id":"NOT-A-MACHINE"}` was accepted with a 200 and a
+      // selection the fleet could never honour. Dispatch re-validates, which is what bounded the impact
+      // — but a control whose whole promise is "you cannot select what the fleet cannot run" has to
+      // refuse the id it has never heard of too.
+      if (machine === null) {
+        return refuse(
+          409,
+          TARGET_REFUSAL.MACHINE_UNKNOWN,
+          `${machineId} is not a machine this relay lists`,
+          'pick a machine from the roster this route reports; if it has just paired, reload the list and '
+            + 'choose it again',
+        );
+      }
+      if (machine.online !== true) {
+        return refuse(
+          409,
+          TARGET_REFUSAL.MACHINE_OFFLINE,
+          `${machine.name ?? machineId} is listed as ${machine.state}, so it cannot be selected`,
+          'the machine must be online: wait for its next heartbeat, or select another machine',
         );
       }
       deps.store.set(sessionId, {

package/src/plugin/tools.mjs

@@ -177,7 +177,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '0.5.9';
+const PLUGIN_VERSION = '0.6.2';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -1810,9 +1810,15 @@ async function initP2P(ctx, cfg, runtime, block) {
    * Registered *here*, after the node exists, rather than in `createP2PRuntime` — an effect that owns
    * nothing is a disposer that releases nothing, and `relay` mode and a machine with no identity must
    * leave the host's effect list exactly as they found it. A host that provides no `ctx.effect` (an
-   * older Cordis, or a bare test context) still gets a working node: the socket is `unref()`ed, so it
-   * cannot keep the process alive, and refusing to start the direct path because the host cannot track
-   * a disposer would break the release's own default.
+   * older Cordis, or a bare test context) still gets a working node: the node itself is asked not to
+   * hold the process open (`node.unref()`, below), so it cannot keep the process alive, and refusing
+   * to start the direct path because the host cannot track a disposer would break the release's own
+   * default.
+   *
+   * v0.5.10: `node.unref()` is a real call, not a description. Until it was added this comment
+   * claimed an `unref()` that existed nowhere in the plugin or the node — the socket went on holding
+   * the event loop, so a host without `ctx.effect` that started a node never exited (found by an
+   * independent verifier against the `w2m_status` test's bare context).
    */
   if (typeof ctx?.effect === 'function') {
     ctx.effect(() => () => {
@@ -1824,6 +1830,11 @@ async function initP2P(ctx, cfg, runtime, block) {
         runtime.events.last_error = error instanceof Error ? error.message : String(error);
       });
     });
+  } else {
+    // No disposer will ever be called by the host, so the node must not be the reason the process
+    // stays up. Called before `start()`: the node remembers it and unrefs the socket it binds, which
+    // is the only ordering that leaves no window where the loop is held open.
+    runtime.node?.unref?.();
   }
 
   // eslint-disable-next-line require-atomic-updates -- single-entry: `ensureStarted` assigns `starting` before this runs
@@ -2700,27 +2711,6 @@ async function resolveTreeFingerprint(projectDir, timeoutMs) {
 // Command policy
 // ---------------------------------------------------------------------------------------------
 
-/**
- * The comparable form of an **executable token**: basename, lower case, no `.exe`/`.cmd`/`.bat`/`.com`.
- *
- * Applied to `argv[0]` and to the first token of an entry, never to the arguments after it --
- * `--reporter=TAP` and `--reporter=tap` are different arguments, and collapsing them would authorise
- * something nobody wrote.
- *
- * This is the plugin's long-documented tolerance (`allowedCommands: ['Node.exe']` accepts
- * `C:\Program Files\nodejs\node.exe`), and it is deliberately platform-independent: the old check
- * normalised the separator itself rather than asking `path`, which is what makes the documented
- * entry work the same on a POSIX dispatcher. Everything *after* the executable token is compared
- * verbatim by the shared matcher, which is where the prefix rule lives.
- *
- * @param {string} value
- * @returns {string}
- */
-function normalizeExecToken(value) {
-  const base = path.basename(String(value).trim().replace(/\\/g, '/')).toLowerCase();
-  return base.replace(/\.(exe|cmd|bat|com)$/, '');
-}
-
 /**
  * Check one argv against the configured allow-list, with the **same rule the agent applies**.
  *
@@ -2736,6 +2726,15 @@ function normalizeExecToken(value) {
  * documented config `['node --test','git status --porcelain']` refused `['git','rev-parse','HEAD']`
  * -- stricter than the gate, which is the direction that silently loses work.
  *
+ * The argv is handed over **verbatim**, including `argv[0]`. It used to be reduced to a basename
+ * first, and that was the plugin half of a defect: the matcher decides executable identity by
+ * resolving a path, and a pre-flight that strips the path can only ever compare names, so it would
+ * wave `E:\Temp\evil\node.exe` through while the agent refused it. Passing the argv through
+ * unchanged is what keeps the two ends one rule. What the shared matcher then resolves, it resolves
+ * against **this** process's environment — the dispatcher's PATH — which is a real limit of a
+ * pre-flight (the executing machine's PATH is the one that will decide), and the reason the refusal
+ * that matters is the agent's own.
+ *
  * A refusal names itself: `reason_code` is the matcher's own code (so the two ends cannot report one
  * refusal under two spellings) and `detail` says what would change it. The two ways this control
  * refuses are kept apart — a command outside the list and a list that cannot be parsed have
@@ -2766,15 +2765,14 @@ function checkAllowedCommand(allowedCommands, argv) {
   }
   // Prefixes "as written": the configured entries, whitespace-normalised, in a stable order.
   const allowed = prefixes.map((prefix) => prefix.join(' ')).sort();
-  const entries = prefixes.map((prefix) => [normalizeExecToken(prefix[0]), ...prefix.slice(1)]);
-  const command = [normalizeExecToken(argv[0]), ...argv.slice(1)];
-  const match = matchAllowedCommand(command, entries);
+  const match = matchAllowedCommand(argv, prefixes);
   if (match.allowed) return null;
   return {
     allowed,
     // The shared matcher's code, not a second copy of it: `COMMAND_NOT_ALLOWED` is the literal the
     // agent writes into its own envelope, so a machine's refusal and this pre-flight's refusal read
-    // the same to whoever has to act on them.
+    // the same to whoever has to act on them. The matcher's three newer codes travel the same way
+    // for the same reason.
     reason_code: match.reason_code ?? REFUSAL_CODE.COMMAND_NOT_ALLOWED,
     message: `\`${argv.join(' ')}\` is not in this plugin's allowedCommands (${allowed.join(', ')})`,
     detail:

package/src/relay/persistence.mjs

@@ -36,6 +36,15 @@ export class Persistence {
     this._now = now;
     /** @type {{file:string, message:string, line?:number}[]} */
     this.warnings = [];
+    /**
+     * Durability state (v0.6.2): whether the ledger is actually being written.
+     *
+     * `appendFailures` is cumulative and never reset, so "how much was lost" stays answerable after a
+     * disk fills and is freed again. `degradedSinceMs` is the live condition.
+     */
+    this.appendFailures = 0;
+    this.lastAppendError = null;
+    this.degradedSinceMs = null;
     this.devicesCorrupt = false;
     this.devicesMissing = true;
     this.revivedDevices = 0;
@@ -50,8 +59,61 @@ export class Persistence {
   get operatorTokenFile() { return this.enabled ? path.join(this.dir, OPERATOR_TOKEN_FILE) : null; }
 
   warn(file, message, extra = {}) {
-    this.warnings.push({ file, message, ...extra });
-    return this.warnings[this.warnings.length - 1];
+    // Deduplicated (v0.6.2). A full disk fails *every* append, and appending an identical entry each
+    // time buried the signal in its own repetition: this fleet's relay reached 22 byte-identical
+    // "ENOSPC" warnings and no way to ask "is this relay still recording?" without counting them. One
+    // entry that counts is what an operator can act on.
+    const existing = this.warnings.find((entry) => entry.file === file && entry.message === message);
+    if (existing !== undefined) {
+      existing.count = (existing.count ?? 1) + 1;
+      existing.last_at = rfc3339(this._now());
+      return existing;
+    }
+    const entry = { file, message, count: 1, ...extra };
+    this.warnings.push(entry);
+    return entry;
+  }
+
+  /**
+   * One ledger append failed: the relay is still serving, but it is no longer recording (v0.6.2).
+   *
+   * This is a first-class state rather than a log line because the ledger *is* the relay's durability
+   * story. Every machine's result, every lease, everything a later question would be answered from —
+   * none of it survives a restart once appends stop landing. A relay in this state accepts work
+   * exactly as before, which is precisely why it has to say so out loud.
+   *
+   * @param {string} message
+   * @returns {false}
+   */
+  noteAppendFailure(message) {
+    this.appendFailures += 1;
+    this.lastAppendError = message;
+    if (this.degradedSinceMs === null) this.degradedSinceMs = this._now();
+    this.warn(LEDGER_FILE, `append failed: ${message}`);
+    return false;
+  }
+
+  /**
+   * The ledger is being written again.
+   *
+   * The history is kept — `append_failures` is not reset — because "how much was lost" is the first
+   * question after a disk fills, and a counter that silently returns to zero cannot answer it.
+   *
+   * @returns {true}
+   */
+  noteAppendSuccess() {
+    if (this.degradedSinceMs !== null) {
+      const forMs = Math.max(0, this._now() - this.degradedSinceMs);
+      this.degradedSinceMs = null;
+      this.lastAppendError = null;
+      this.warn(LEDGER_FILE, `append recovered after ${this.appendFailures} failure(s) over ${forMs}ms`);
+    }
+    return true;
+  }
+
+  /** Is the relay serving without recording? @returns {boolean} */
+  get degraded() {
+    return this.degradedSinceMs !== null;
   }
 
   ensureDir() {
@@ -199,6 +261,14 @@ export class Persistence {
       devices_missing: this.devicesMissing,
       ledger_lines_read: this.ledgerLinesRead,
       ledger_lines_skipped: this.ledgerLinesSkipped,
+      /**
+       * v0.6.2. `degraded: true` means the relay is answering requests while failing to record them,
+       * which is the one relay failure that looks exactly like health from the outside.
+       */
+      degraded: this.degraded,
+      degraded_since: this.degradedSinceMs === null ? null : rfc3339(this.degradedSinceMs),
+      last_append_error: this.lastAppendError,
+      append_failures: this.appendFailures,
       warnings: this.warnings.map((w) => ({ ...w })),
     };
   }

package/src/relay/server.mjs

@@ -36,6 +36,32 @@ export const DEFAULT_PAIR_RATE_LIMIT_PER_MINUTE = 5; // v0.1.2 §6
 export const RATE_LIMIT_WINDOW_MS = 60_000;
 export const DEFAULT_STATE_DIR = path.join(os.homedir(), '.w2m');
 
+/**
+ * The environment variable that opts in to printing the operator token on a start that did not
+ * generate it (MEDIUM-6 of the v0.5.9 review).
+ *
+ * The value is printed **once, on the start that generated it**, because that is the only moment at
+ * which it exists nowhere else yet; every other start has `<state>/operator-token.txt` to read it
+ * from, and a relay's stdout ends up in journald, a container log or a CI transcript — where a
+ * credential that authorises dispatching to the whole fleet does not belong. `W2M_PRINT_OPERATOR_TOKEN=1`
+ * (or `printOperatorToken: true`, which is the same switch for an embedder) restores the old
+ * behaviour for an operator who genuinely needs it in the log, and says so in the banner when it does.
+ */
+export const PRINT_OPERATOR_TOKEN_ENV = 'W2M_PRINT_OPERATOR_TOKEN';
+
+/**
+ * Resolve that opt-in, so the relay and the CLI agree on one answer.
+ *
+ * @param {object} [options] Relay options; `printOperatorToken: true` is the programmatic spelling.
+ * @returns {'option'|'env'|null} Why printing was asked for, or null.
+ */
+export function printOperatorTokenOptIn(options = {}) {
+  if (options.printOperatorToken === true) return 'option';
+  const raw = process.env[PRINT_OPERATOR_TOKEN_ENV];
+  if (raw === '1' || raw === 'true') return 'env';
+  return null;
+}
+
 /* ------------------------------------------------------------------ */
 /* helpers                                                             */
 /* ------------------------------------------------------------------ */
@@ -459,11 +485,19 @@ export class RelayServer {
     const wantsRequired = options.operatorTokenRequired !== false;
     const explicit = options.operatorToken;
     const persisted = this.persistence.enabled ? this.persistence.readOperatorToken() : null;
+    /**
+     * Why the token may be printed, when it may be: `'generated'` is the one start whose token exists
+     * nowhere else until this process writes it, and `'option'`/`'env'` are the documented opt-ins.
+     * @type {'generated'|'option'|'env'|null}
+     */
+    this.operatorTokenPrintReason = printOperatorTokenOptIn(options);
 
     if (!wantsRequired || explicit === '') {
       this.operatorToken = null;
       this.operatorTokenRequired = false;
       this.operatorTokenSource = 'disabled';
+      this.operatorTokenPrintable = false;
+      this.operatorTokenPrintReason = null;
       return;
     }
     this.operatorTokenRequired = true;
@@ -471,18 +505,22 @@ export class RelayServer {
       this.operatorToken = explicit;
       this.operatorTokenSource = 'option';
       this.persistence.writeOperatorToken(explicit);
-      return;
-    }
-    if (persisted) {
+    } else if (persisted) {
       // §5.1 + §7: keep the token stable across restarts, otherwise every restart
       // would silently invalidate the plugin's configured operatorToken.
       this.operatorToken = persisted;
       this.operatorTokenSource = 'restored';
-      return;
+    } else {
+      this.operatorToken = randomBytes(32).toString('hex');
+      this.operatorTokenSource = 'generated';
+      this.persistence.writeOperatorToken(this.operatorToken);
     }
-    this.operatorToken = randomBytes(32).toString('hex');
-    this.operatorTokenSource = 'generated';
-    this.persistence.writeOperatorToken(this.operatorToken);
+    // MEDIUM-6: the material is printed only by the start that generated it, or when the operator has
+    // explicitly asked for it. "The posture, never the material" still holds everywhere else.
+    if (this.operatorTokenSource === 'generated') {
+      this.operatorTokenPrintReason = this.operatorTokenPrintReason ?? 'generated';
+    }
+    this.operatorTokenPrintable = this.operatorTokenPrintReason !== null;
   }
 
   _buildStartupMessages() {
@@ -517,10 +555,30 @@ export class RelayServer {
       m.push(`[w2m-rabbit] !! ${w.file}: ${w.message}`);
     }
     if (this.operatorTokenRequired) {
-      m.push(`[w2m-rabbit] operator token (${this.operatorTokenSource}) - required for POST /v1/task:`);
-      m.push(`[w2m-rabbit]   ${this.operatorToken}`);
-      if (this.persistence.operatorTokenFile) {
-        m.push(`[w2m-rabbit]   stored at ${this.persistence.operatorTokenFile} (0600)`);
+      // MEDIUM-6: the token is material, not posture, so it is printed as rarely as it can be — on the
+      // start that generated it (`operatorTokenSource === 'generated'`) or when `printOperatorToken` /
+      // `W2M_PRINT_OPERATOR_TOKEN=1` asked for it — and once, never twice. Where it is stored is said in
+      // every case, including the case where there is nowhere to store it.
+      //
+      // DELIBERATE, do not "fix": on that one start the CLI prints the value a second time, in its own
+      // stdout banner. Two sinks for one start is not a leak — the defect was printing it on *every*
+      // start, restored ones included — and the box is the documented first-start handoff a human reads
+      // (docs/DEPLOY.md §2.4, test/crossnetwork.test.mjs). Collapsing the pair would trade a documented
+      // behaviour for one saved line on one start.
+      const tokenFile = this.persistence.operatorTokenFile ?? null;
+      const stored = tokenFile === null
+        ? 'persistence is off, so this token exists only in this process and cannot be read back later'
+        : `stored at ${tokenFile} (0600)`;
+      if (this.operatorTokenPrintable) {
+        m.push(`[w2m-rabbit] operator token (${this.operatorTokenSource}) - required for POST /v1/task:`);
+        m.push(`[w2m-rabbit]   ${this.operatorToken}`);
+        m.push(`[w2m-rabbit]   printed once because ${this.operatorTokenPrintReason === 'generated'
+          ? 'this start generated it' : `${this.operatorTokenPrintReason} asked for it (${PRINT_OPERATOR_TOKEN_ENV})`}`
+          + ` - and ${stored}`);
+      } else {
+        m.push(`[w2m-rabbit] operator token (${this.operatorTokenSource}) - required for POST /v1/task, NOT printed`);
+        m.push(`[w2m-rabbit]   read it from ${tokenFile ?? '<state>/operator-token.txt'} - ${stored}`);
+        m.push(`[w2m-rabbit]   set ${PRINT_OPERATOR_TOKEN_ENV}=1 to print it on this start as well`);
       }
     } else {
       m.push('[w2m-rabbit] !! WARNING: OPERATOR TOKEN DISABLED (--operator-token "") - '
@@ -562,6 +620,11 @@ export class RelayServer {
           basePath: this.basePath,
           operatorToken: this.operatorToken,
           operatorTokenRequired: this.operatorTokenRequired,
+          // The CLI prints its own banner, so it has to reach the same conclusion this class did rather
+          // than re-deriving one from the token's presence (MEDIUM-6).
+          operatorTokenSource: this.operatorTokenSource,
+          operatorTokenPrintable: this.operatorTokenPrintable === true,
+          operatorTokenPrintReason: this.operatorTokenPrintReason ?? null,
           scheme: this.scheme,
         });
       });
@@ -839,6 +902,16 @@ export class RelayServer {
       // so this drops to 0 by itself when nobody is refreshing.
       ...this.peers.stats(),
       ok: true,
+      /**
+       * v0.6.2: hoisted out of `persistence` so it cannot be missed by a reader that only looks at
+       * the top level. `degraded: true` means this relay is answering requests while failing to record
+       * them -- the one relay failure that presents as health. `ok` deliberately stays true: the relay
+       * still serves the fleet, and flipping it would turn a recording problem into an outage.
+       */
+      degraded: this.persistence.enabled && this.persistence.degraded,
+      degraded_reason: this.persistence.degraded
+        ? `ledger appends are failing (${this.persistence.lastAppendError ?? 'unknown error'}); results are served but not durably recorded`
+        : null,
       protocol_version: PROTOCOL_VERSION,
       rabbit_time: this.state.nowIso(),
       uptime_ms: this.state.nowMs() - this._startedAtMs,

package/src/relay/state.mjs

@@ -470,9 +470,16 @@ export class RabbitState {
   _ledger(entry) {
     if (this._restoring || !this._persist) return false;
     try {
-      return this._persist.append(entry);
+      const appended = this._persist.append(entry);
+      // v0.6.2: a successful append is what clears a degraded relay, so the outcome has to be
+      // reported back rather than assumed -- otherwise the state could only ever be entered.
+      if (appended) this._persist.noteAppendSuccess?.();
+      return appended;
     } catch (err) {
-      this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
+      // Recorded as a state, not merely as a line: this is the one relay failure that keeps serving,
+      // and so the one that is invisible from every other angle (v0.6.2).
+      if (typeof this._persist.noteAppendFailure === 'function') this._persist.noteAppendFailure(err.message);
+      else this._persist.warn?.('ledger.jsonl', `append failed: ${err.message}`);
       return false;
     }
   }