@commonlyai/cli 0.1.67 → 0.1.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -39,6 +39,7 @@ import {
   formatPodFocusFrame,
   readPodFocus,
 } from '../lib/pod-focus.js';
+import { claimReleaseFor, ackResultFor } from '../lib/claim-outcome.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
@@ -1045,6 +1046,7 @@ export const performRun = ({
       // goes in a sibling field instead of being spelled into the reason.
       return {
         outcome: 'no_action',
+        refused: { reason: 'cascade-cap' },
         reason: 'cascade-cap',
         details: {
           // The id of what was dropped. `reason` and `streak` say a refusal
@@ -1139,16 +1141,19 @@ export const performRun = ({
     } finally {
       // A silent, normally completed human wake is an explicit decline, not
       // a successful answer. Tell the kernel so it can hand the message to
-      // exactly one remaining original listener. Any posted reply, refusal
-      // with a reason, or thrown spawn retains completion/legacy semantics:
-      // re-offering those would duplicate a visible response or defeat normal
-      // at-least-once redelivery after an infrastructure failure.
-      const claimOutcome = event.type === 'message.posted'
-        && event.payload?.senderIsHuman === true
-        && turnResult?.outcome === 'no_action' && !turnResult?.reason
-        ? 'declined'
-        : (turnResult ? 'completed' : undefined);
-      await claimKeeper?.release(claimOutcome);
+      // exactly one remaining original listener. A refusal — the upstream
+      // route down, or the server refusing the post — is NAMED (TASK-099): it
+      // carries its class so the kernel's record can tell "answered" from
+      // "never ran", and on a human wake the kernel hands it on exactly as it
+      // does a decline, because a failure local to THIS seat must not make a
+      // human's message disappear. A thrown spawn keeps the legacy release, so
+      // normal at-least-once redelivery still happens after an infrastructure
+      // failure. One decision point, shared with the batch path — see
+      // lib/claim-outcome.js.
+      const release = claimReleaseFor(event, turnResult);
+      await claimKeeper?.release(release.outcome, {
+        reason: release.reason, status: release.status,
+      });
     }
   };
 
@@ -1397,6 +1402,7 @@ export const performRun = ({
     if (deliveryRefusal) {
       return {
         outcome: 'no_action',
+        refused: { reason: 'delivery-refused' },
         reason: deliveryRefusal.reason,
         details: {
           mode: deliveryRefusal.mode,
@@ -1409,14 +1415,22 @@ export const performRun = ({
         },
       };
     }
-    // A refusal is not a decline. `no_action` with no reason means "the agent
-    // chose not to answer" and hands a human wake to one remaining listener;
-    // nothing about the agent's choice happened here — the model never ran — so
-    // say what did happen, and let the event close rather than fan a
-    // route-wide refusal out across the rest of the fleet.
+    // A refusal is not a decline, and it is not a close either. `no_action`
+    // with no reason means "the agent chose not to answer" and hands a human
+    // wake to one remaining listener; nothing about the agent's choice happened
+    // here — the model never ran — so the release says WHICH class of refusal
+    // it was (TASK-099). The kernel routes from there: on a human wake the
+    // message is handed to one remaining listener exactly as a decline is
+    // (this seat's upstream route being down says nothing about theirs), and on
+    // any other wake it is terminal. The free-text detail stays in the seat
+    // log and the event ack; the kernel records the class.
     if (!delivered && upstream) {
       return {
         outcome: 'no_action',
+        refused: {
+          reason: 'upstream-refused',
+          ...(Number.isInteger(upstream.status) ? { status: upstream.status } : {}),
+        },
         reason: `upstream-refused-${upstream.status}`,
         details: {
           status: upstream.status,
@@ -1461,6 +1475,7 @@ export const performRun = ({
 
   const batchAdmissionResult = (event, admission) => ({
     outcome: 'no_action',
+    refused: { reason: 'cascade-cap' },
     reason: 'cascade-cap',
     details: {
       messageId: event?.payload?.messageId || null,
@@ -1646,14 +1661,14 @@ export const performRun = ({
         .filter((entry) => entry.claimKeeper)
         .map(async (entry) => {
           // Preserve ADR-018 D6.1 per binding message: a silent human
-          // broadcast may be handed to one remaining listener, while every
-          // other completed batch item closes normally.
-          const claimOutcome = entry.event.type === 'message.posted'
-            && entry.event.payload?.senderIsHuman === true
-            && turnResult?.outcome === 'no_action' && !turnResult?.reason
-            ? 'declined'
-            : (turnResult ? 'completed' : undefined);
-          await entry.claimKeeper.release(claimOutcome);
+          // broadcast may be handed to one remaining listener, a refusal
+          // closes with its reason, and every other completed batch item
+          // closes normally. Same decision point as the single-event path.
+          // Same decision point as the single-event path.
+          const release = claimReleaseFor(entry.event, turnResult);
+          await entry.claimKeeper.release(release.outcome, {
+            reason: release.reason, status: release.status,
+          });
         }));
     }
   };
@@ -1743,7 +1758,7 @@ export const performRun = ({
             try {
               const deliveryId = event.payload?.deliveryId;
               await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
-                result: entry.result,
+                result: ackResultFor(entry.result),
                 ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
               });
             } catch (ackErr) {
@@ -1843,7 +1858,7 @@ export const performRun = ({
         try {
           const deliveryId = event.payload?.deliveryId;
           await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
-            result,
+            result: ackResultFor(result),
             ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
           });
         } catch (ackErr) {

package/src/lib/adapters/claude.js

@@ -75,6 +75,7 @@ import {
 import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
+import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 
 // See codex.js for the rationale on bumping the default + env override.
 // Keeping both adapters in lockstep so any wrapper agent runtime has the
@@ -234,7 +235,7 @@ const buildPublicClaudePolicyArgs = (mcpToolPatterns) => {
   ];
 };
 
-const runClaude = ({ cmd, args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
+const runClaude = ({ cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
   const proc = spawnImpl(cmd, args, {
     cwd,
     env,
@@ -265,8 +266,19 @@ const runClaude = ({ cmd, args, cwd, env, timeoutMs, spawnImpl = childSpawn }) =
       // at all because of this. It is not only a diagnosability problem: the
       // circuit breaker classifies from the error message, so a blank message
       // downgrades a hard quota failure to RUNTIME and its shortest backoff.
+      //
+      // TASK-103: the tail goes through the same reader pi's refusal log uses.
+      // A non-JSON tail (which this normally is — the usage-limit line above is
+      // prose) is kept whole and only exact-match redacted; a JSON body is
+      // reduced to one named field. The status, when the tail names one, is
+      // attached as `error.status` so a refusal classifies by field rather than
+      // by regex.
       const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join(' | ');
-      return reject(new Error(`claude exited with code ${code}: ${detail.slice(0, 2000)}`));
+      return reject(adapterFailure('claude', detail, {
+        credentials,
+        exitCode: code,
+        limit: 2000,
+      }));
     }
     resolve(stdout);
   });
@@ -688,6 +700,11 @@ export default {
         cwd: ctx.cwd,
         env,
         timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        // The values this spawn was handed, for the failure tail's exact-match
+        // check. Snapshot before the spawn: claude is subscription-authenticated
+        // and its provider key is not an env var here, so the seat credential is
+        // the value a tail can echo back.
+        credentials: spawnCredentials(spawnCtx),
         spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
       });
       return { text: stdout.trim(), newSessionId: sessionId };
@@ -703,7 +720,7 @@ export default {
         // session that misses the durable-state cue.
         const freshPrompt = buildPrompt(prompt, ctx.memoryLongTerm, { freshSession: true });
         const retryBase = ['-p', freshPrompt, '--output-format', 'text', '--session-id', freshId, ...modelArgs];
-        const retry = await prepareArgv(retryBase, {
+        const retryCtx = {
           ...ctx,
           mcpConfigPath: mcpConfig?.file || null,
           mcpConfigDir: mcpConfig?.dir || null,
@@ -714,13 +731,15 @@ export default {
             mcpConfig?.expansionEnv,
             mcpConfig?.credential?.path || null,
           ),
-        });
+        };
+        const retry = await prepareArgv(retryBase, retryCtx);
         const stdout = await runClaude({
           cmd: retry.cmd,
           args: retry.args,
           cwd: ctx.cwd,
           env: retry.env,
           timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+          credentials: spawnCredentials(retryCtx),
           spawnImpl: ctx._spawnImpl,
         });
         return { text: stdout.trim(), newSessionId: freshId };

package/src/lib/adapters/codex.js

@@ -60,6 +60,7 @@ import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
+import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 
 // Default timeout for a single codex spawn (exec mode).
 //
@@ -412,8 +413,21 @@ const makeEventParser = () => {
   };
 };
 
-const runCodex = ({ args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
-  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
+/**
+ * Provider keys this adapter's route can authenticate with. `env_key` in
+ * `~/.codex/config.toml` names one of them (ADR-014 — the HTTPS layer is
+ * redirected, the CLI's semantics are not), and the adapter cannot know which
+ * one this seat uses, so it snapshots whichever are present. A failure tail that
+ * echoes a key must not reach a pod (TASK-103).
+ */
+const CODEX_PROVIDER_KEY_ENVS = [
+  'LITELLM_API_KEY',
+  'LITELLM_MASTER_KEY',
+  'OPENAI_API_KEY',
+  'CODEX_API_KEY',
+];
+
+const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn }) => new Promise((resolve, reject) => {  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
   // defaults stdin to a fresh pipe. Codex 0.125.0's `exec` then blocks on
   // `Reading additional input from stdin...` because it sees an open pipe
   // and waits for input that never arrives. Interactive runs are fine because
@@ -442,11 +456,18 @@ const runCodex = ({ args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new
     if (events.turnFailedMessage) {
       // Surface the model-side failure message verbatim — the run loop posts
       // it as the agent's reply so the user sees what went wrong rather than
-      // a generic "non-zero exit" error.
-      return reject(new Error(`codex turn failed: ${events.turnFailedMessage}`));
+      // a generic "non-zero exit" error. Verbatim is about the WORDING: the
+      // tail still goes through the shared reader (TASK-103), so a message that
+      // echoed a credential this spawn was handed is redacted before it can be
+      // posted into a pod, and a status it names is attached for the circuit
+      // breaker rather than left to a regex.
+      return reject(adapterFailure('codex turn failed', events.turnFailedMessage, {
+        credentials,
+        limit: 2000,
+      }));
     }
     if (code !== 0) {
-      return reject(new Error(`codex exited with code ${code}: ${stderr.trim().slice(0, 500)}`));
+      return reject(adapterFailure('codex', stderr.trim(), { credentials, exitCode: code, limit: 500 }));
     }
     resolve({ threadId: events.threadId });
   });
@@ -554,6 +575,12 @@ export default {
         cwd: ctx.cwd,
         env: childEnv,
         timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        // The values this spawn was handed, for the failure tail's exact-match
+        // check: the seat credential and the provider key the route
+        // authenticates with. Snapshot HERE — `withholdRuntimeCredential` above
+        // already removed the token from the child copy, and after that there is
+        // nothing left to compare a tail against.
+        credentials: spawnCredentials(ctx, CODEX_PROVIDER_KEY_ENVS),
         spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
       });
 

package/src/lib/claim-outcome.js

@@ -0,0 +1,120 @@
+/**
+ * claimReleaseFor — the ONE decision about how a finished turn releases its
+ * ADR-018 attention claim.
+ *
+ * It lives here, extracted from two byte-identical copies in the run loop
+ * (single-event and batch release), for the reason a second copy is always a
+ * risk: the batch path is the one `message.posted` actually reaches, so a
+ * change applied to only one of them would pass review and do nothing.
+ *
+ * Three outcomes, and the KERNEL decides what each one does with the wake
+ * (TASK-099 ruling, corrected at 71194/71195/71210):
+ *
+ *   - `refused`   — the lease holder could not deliver. Nothing about the
+ *                   agent's CHOICE happened: the model never ran (an upstream
+ *                   429/502/401, named by TASK-096) or the server refused the
+ *                   post. On a HUMAN wake the kernel hands the message to one
+ *                   remaining listener exactly as it does for a decline — a
+ *                   per-seat budget failure must not make a human's message
+ *                   disappear — and records the refuser so the chain stays
+ *                   finite. On any other wake it is terminal. The routing is
+ *                   the kernel's: this module only names the outcome.
+ *   - `declined`  — a silent, normally completed human broadcast. The agent
+ *                   chose not to answer, so the kernel hands it to exactly one
+ *                   remaining original listener.
+ *   - `completed` — everything else that produced a result: a posted reply, or
+ *                   a skip with a reason (`no-prompt`, `claim-held`,
+ *                   `duplicate-delivery`) where nothing was refused.
+ *
+ * The refusal CLASS is an enum, not free text: `upstream-refused` (with the
+ * HTTP status), `cascade-cap`, `delivery-refused`. The kernel stores the class
+ * so refusals are countable, and rejects anything else with a 400. A producer
+ * that cannot classify itself maps to `delivery-refused` before sending — the
+ * mapping is here, in one place, rather than in each producer.
+ *
+ * A thrown turn returns no turnResult and releases with no outcome — the
+ * legacy holder-only DELETE whose at-least-once redelivery is the correct
+ * behaviour for a crashed spawn (the lid closed, the process died).
+ */
+
+/** The classes the kernel accepts. Mirrors `REFUSAL_REASONS` in agentsRuntime. */
+export const REFUSAL_REASONS = ['upstream-refused', 'cascade-cap', 'delivery-refused'];
+
+/** What an unclassifiable refusal is recorded as, rather than a fourth class. */
+export const DEFAULT_REFUSAL_REASON = 'delivery-refused';
+
+/**
+ * The range the kernel accepts for a refusal's `status` — its
+ * `MIN_UPSTREAM_STATUS` / `MAX_UPSTREAM_STATUS` in `messageClaimService`.
+ * A number outside it is not a refusal status the kernel will record: it
+ * answers 400, and the 400 fallback in `enforcement.release` re-releases as
+ * `completed` — which is terminal. So forwarding an out-of-range number does
+ * not merely lose the number, it loses the handoff: an upstream refusal on a
+ * human wake would be recorded as a clean completion. The sender's rule has to
+ * be the receiver's rule, which is why the bound lives here as well as there.
+ */
+export const MIN_UPSTREAM_STATUS = 400;
+export const MAX_UPSTREAM_STATUS = 599;
+
+/**
+ * @param {{type?: string, payload?: {senderIsHuman?: boolean}}} event
+ * @param {{refused?: {reason?: string, status?: number}|true, outcome?: string, reason?: string}|undefined} turnResult
+ * @returns {{outcome?: 'refused'|'declined'|'completed', reason?: string, status?: number}}
+ */
+export const claimReleaseFor = (event, turnResult) => {
+  if (!turnResult) return { outcome: undefined };
+  // `refused: true` is still honoured: it is what an older producer shape (and
+  // a third-party wrapper following TASK-096's docs) sends, and it means the
+  // same thing — `delivery-refused`, the class that claims the least.
+  if (turnResult.refused) {
+    const declared = typeof turnResult.refused === 'object' ? turnResult.refused : {};
+    const reason = REFUSAL_REASONS.includes(declared.reason)
+      ? declared.reason
+      : DEFAULT_REFUSAL_REASON;
+    // The status is the instance of the class, and only the upstream class has
+    // one: a cap refusal or a refused post never saw an upstream HTTP status,
+    // so sending its number would put a field on the record that cannot mean
+    // what a reader would assume. It is also bounded by what the kernel
+    // accepts — an out-of-range number keeps the class and drops only the
+    // number, so the refusal still hands off instead of falling back to
+    // `completed`.
+    const status = reason === 'upstream-refused'
+      && Number.isInteger(declared.status)
+      && declared.status >= MIN_UPSTREAM_STATUS
+      && declared.status <= MAX_UPSTREAM_STATUS
+      ? declared.status
+      : undefined;
+    return {
+      outcome: 'refused',
+      reason,
+      ...(status !== undefined ? { status } : {}),
+    };
+  }
+  if (event?.type === 'message.posted'
+      && event.payload?.senderIsHuman === true
+      && turnResult.outcome === 'no_action'
+      && !turnResult.reason) {
+    return { outcome: 'declined' };
+  }
+  return { outcome: 'completed' };
+};
+
+/**
+ * `refused` is a LOCAL release marker: the producer sets it so the claim
+ * release can name the outcome (see `claimReleaseFor`), and nothing else reads
+ * it. The event ack is a wire payload with its own readers, and the information
+ * that belongs there already reaches them as `reason` — so the marker is
+ * dropped at the ack boundary rather than widening the ack with an internal
+ * flag. Returns the result unchanged when there is no marker, so the common
+ * path never sees a rebuilt object.
+ *
+ * @param {object|undefined} turnResult
+ */
+export const ackResultFor = (turnResult) => {
+  if (!turnResult || !turnResult.refused) return turnResult;
+  // ts-eslint's `arg`/`vars` ignore pattern is `^_`, and ignoreRestSiblings is
+  // off in this repo's config — so the dropped key is renamed rather than
+  // left to trip no-unused-vars.
+  const { refused: _refused, ...rest } = turnResult;
+  return rest;
+};

package/src/lib/enforcement.js

@@ -434,7 +434,7 @@ export const createClaimKeeper = (client, {
       if (timer && typeof timer.unref === 'function') timer.unref();
     },
 
-    async release(outcome) {
+    async release(outcome, { reason, status } = {}) {
       stopRenewal();
       if (!acquired || lost) return;
       try {
@@ -442,7 +442,35 @@ export const createClaimKeeper = (client, {
         // outcome. Besides keeping old clients' DELETE shape intact, callers
         // that assert their transport arguments must not see a synthetic
         // `undefined` body. An explicit outcome is the new D6.1 contract.
-        await (outcome ? client.del(path, { outcome }) : client.del(path));
+        //
+        // `reason` and `status` ride only with a refusal (TASK-099) and only
+        // when the producer named them: the kernel stores the class as the
+        // record of why a delivery never happened, so an absent reason must
+        // stay absent rather than become the string "undefined".
+        if (!outcome) {
+          await client.del(path);
+          return;
+        }
+        const body = {
+          outcome,
+          ...(reason ? { reason } : {}),
+          ...(status !== undefined ? { status } : {}),
+        };
+        try {
+          await client.del(path, body);
+        } catch (err) {
+          // An older kernel validates the outcome against its own
+          // decline/completed enum and answers 400 — as it does for a reason
+          // it does not recognise. A CLI that ships before (or runs against a
+          // server earlier than) the third outcome must still release its
+          // lease, or the message stays claimed until it expires: one retry as
+          // `completed`, which is exactly what the old release did. Bounded to
+          // a 400 — a 500 or a timeout is not turned into a second write, and
+          // a second 400 is not retried again.
+          if (outcome !== 'refused' || err?.status !== 400) throw err;
+          log(`claim on message ${messageId}: kernel rejected the refused outcome (400) — releasing as completed`);
+          await client.del(path, { outcome: 'completed' });
+        }
       } catch {
         // Best-effort: a miss just means the lease already expired.
       }

package/src/lib/upstream-refusal.js

@@ -29,14 +29,15 @@
  *     relayed in an upstream error is not detectable here, because the one
  *     inventory this module has is the set of values it was itself handed.
  *
- * Scope: this reader is wired into the pi adapter only. codex and claude are NOT
- * silent the way pi was: the claude adapter rejects on a non-zero exit and
- * deliberately reports stdout with it, because a `-p` run writes quota
- * conditions there; the codex adapter rejects on `turnFailedMessage` even at
- * exit 0. Their gap is the opposite one — the text they raise is the raw tail,
- * unscrubbed by the rules above, and carries no HTTP status for the run loop to
- * key a refusal on. Extending this module to them is adapter work (TASK-103),
- * not a line in this comment.
+ * Scope: this reader was wired into the pi adapter only. TASK-103 extended it
+ * to codex and claude, which are NOT silent the way pi was: the claude adapter
+ * rejects on a non-zero exit and deliberately reports stdout with it, because a
+ * `-p` run writes quota conditions there; the codex adapter rejects on
+ * `turnFailedMessage` even at exit 0. Their gap was the opposite one — the text
+ * they raised was the raw tail, unscrubbed by the rules above, and carried no
+ * HTTP status for the run loop to classify on. `scrubAdapterFailure` below is
+ * the shared reader they now both go through, so the two rules cannot drift
+ * apart between three adapters.
  */
 
 /** The kept detail is truncated, ellipsis included, to this many characters. */
@@ -179,6 +180,154 @@ export const readUpstreamRefusal = (stdout, { credentials = [] } = {}) => {
   return { status, detail: keptRefusalDetail(raw, { credentials }) };
 };
 
+/**
+ * Is this text STRUCTURED upstream data — a JSON object or an array? The gate for
+ * the whole-tail fallback below, deliberately NOT `kept === null`, which is true
+ * for five different reasons (Vera 71350).
+ *
+ * An array counts, and that is a correction (Vera 71360, measured): `[{...}]` is
+ * structured data with fields this code does not know, which is exactly what rule
+ * 1 exists for, and treating it as prose shipped the whole body under exact-match
+ * alone. A JSON *string* is the opposite case and does NOT count — `"Too many
+ * requests"` is a whole-shape text with no fields to reduce, so it keeps its
+ * wording like any other prose.
+ */
+const isStructuredBody = (raw) => {
+  try {
+    const parsed = JSON.parse(String(raw ?? ''));
+    return parsed !== null && typeof parsed === 'object';
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A 3-digit number is read as a status only when the tail NAMES it as one:
+ * `status 429`, `HTTP 429`, `code: "429"` — or when it opens the tail or a ` | `
+ * segment followed by a colon, which is the shape claude's `stderr | stdout`
+ * join produces for a body that leads with its status.
+ *
+ * A bare `\b(\d{3})\b` scan is not enough, and the false positives are not
+ * hypothetical: `500 tokens`, `"max_tokens": 500` and `retry in 500 seconds`
+ * all read as 500, and `classifySpawnFailure` tests the status FIELD before the
+ * message — so a count misread as a status stands the fleet down on a refusal
+ * that never happened, which is worse than no status at all (Vera 71352).
+ */
+const STATUS_NAMED = /\b(?:status(?:_?code)?|code|http)\b\W{0,4}(\d{3})(?!\d)/gi;
+// `HTTP/1.1 429 Too Many Requests` is the most canonical refusal shape there is,
+// and the `\W{0,4}` gap above handles `HTTP 429` but cannot reach a VERSIONED
+// line: the `1` in `/1.1` is a
+// WORD character, so `HTTP` and `429` are not within four non-word characters of
+// each other. It read as `status: null` — an unclassified runtime failure on the
+// single most recognisable shape, which is the misclassification this row exists
+// to remove (Vera 71359). Its own pattern, not a looser gap: widening the gap
+// would start reading `/v1/models 500` as a status.
+const STATUS_LINE = /\bHTTP\/\d(?:\.\d)?\s+(\d{3})(?!\d)/gi;
+const STATUS_COLON = /(?:^|\|\s*)(\d{3})(?!\d)\s*:/g;
+
+/** The first 4xx/5xx one of those shapes names, or null. */
+const scanStatuses = (text, pattern) => {
+  for (const match of String(text ?? '').matchAll(pattern)) {
+    const value = Number(match[1]);
+    if (value >= 400 && value <= 599) return value;
+  }
+  return null;
+};
+
+/**
+ * Find the status AND the body boundary, because they are the same question.
+ *
+ * Anchoring the status to a ` | ` segment start is not enough on its own: the
+ * body has to be taken from just past that status too, or a mid-tail read
+ * isolates the status and then hands the WHOLE joined tail to the body rules,
+ * which no longer look like a JSON body and so fall through to "keep it all".
+ * That is the difference between dropping a credential-echoing body and shipping
+ * the part of it that exact-match cannot see.
+ *
+ * `STATUS_COLON` is the only shape that moves the boundary, because it is the
+ * same shape as the anchored prefix (`429: {body}`), just found at a segment
+ * boundary — claude's `stderr | stdout` join. A status that appears inside a
+ * body (`{"error":{"code":"429"}}`) or as prose (`HTTP 503`) names the status
+ * (`HTTP/1.1 429`) but marks no boundary, so the whole text stays the body.
+ */
+const readStatusAndBody = (text) => {
+  const raw = String(text ?? '');
+  const prefixed = statusFromError(raw);
+  if (prefixed !== null) return { status: prefixed, body: bodyFromError(raw) };
+  // Only the colon shape moves the boundary — see the note above. A status LINE
+  // names the status but its reason phrase is prose, so the body stays the whole
+  // text and the exact-match rule protects it.
+  for (const match of raw.matchAll(STATUS_COLON)) {
+    const value = Number(match[1]);
+    if (value >= 400 && value <= 599) {
+      return { status: value, body: raw.slice(match.index + match[0].length).replace(/^\s*:?\s*/, '') };
+    }
+  }
+  const named = scanStatuses(raw, STATUS_NAMED);
+  return { status: named ?? scanStatuses(raw, STATUS_LINE), body: raw };
+};
+
+/**
+ * The shared reader for an adapter's own failure tail (TASK-103).
+ *
+ * The two rules above are about a body an adapter captured, and they apply here
+ * too — but the tail is a different shape from pi's refusal, and the difference
+ * decides how each rule lands:
+ *
+ *  - The tail is often NOT structured. Claude's `-p` mode writes its terminal
+ *    condition as prose (`Claude usage limit reached. Your limit will reset at
+ *    11:40pm.`), and that line is the whole diagnostic value of reporting
+ *    stdout at all — 361 consecutive failures on 2026-08-03 carried no reason
+ *    because of it. So the keep-list applies only when the tail parses as a
+ *    body; when it does not, the text is KEPT as a whole shape and the
+ *    exact-match rule is what protects it (`redactKnownCredentials`, which
+ *    substitutes rather than drops, precisely because a whole-shape text has no
+ *    second field to fall back to).
+ *
+ *  - A body that IS structured (a JSON object or array) is reduced to one named
+ *    field, and a body whose field echoed a value this spawn was handed is
+ *    DROPPED WHOLE — the same trade rule 2 makes everywhere. The fallback to the
+ *    whole tail is gated on the SHAPE (is it structured at all), never on
+ *    "the keep-list returned null": that null has
+ *    four other causes, and one of them is the credential echo this line exists
+ *    to drop. Gating on `kept === null` would emit the whole body for that case,
+ *    which is precisely what rule 2 forbids — and exact-match cannot see a
+ *    transformed shape (limit (a) in the header), so a key that arrived
+ *    base64'd or percent-encoded would ship (Vera 71350/71351).
+ *
+ * Returns `{ status, detail }`: `status` is the 4xx/5xx the tail named, or null.
+ * The caller decides where the status goes; `classifySpawnFailure` reads it off
+ * `error.status` or out of the message text, so both a leading `429: …` prefix
+ * and an attached field classify the same way. `detail` is `''` when nothing of
+ * the body may be shown — the status is then the whole diagnostic.
+ */
+export const scrubAdapterFailure = (text, { credentials = [], limit = MAX_REFUSAL_DETAIL } = {}) => {
+  const raw = String(text ?? '').trim();
+  const { status, body } = readStatusAndBody(raw);
+  const kept = keptRefusalDetail(body, { credentials });
+  const detail = kept ?? (isStructuredBody(body) ? '' : redactKnownCredentials(body, credentials));
+  return { status, detail: detail.slice(0, limit) };
+};
+
+/**
+ * The Error an adapter raises, built from its own failure tail.
+ *
+ * `status` is attached as a field, not only written into the text: the run
+ * loop's classifier tests `error.status === 429` before it looks at the
+ * message, and a refusal that is only readable by regex is one wording away
+ * from the misclassification that cost an hour on 2026-08-18 (see
+ * spawn-retry.js). The message still names the status so a human log says the
+ * same thing as the classifier's decision.
+ */
+export const adapterFailure = (label, text, { credentials = [], exitCode = null, limit } = {}) => {
+  const { status, detail } = scrubAdapterFailure(text, { credentials, limit });
+  const code = exitCode === null ? '' : ` exited with code ${exitCode}`;
+  const named = status === null ? '' : ` (upstream ${status})`;
+  const error = new Error(`${label}${code}${named}${detail ? `: ${detail}` : ''}`);
+  if (status !== null) error.status = status;
+  return error;
+};
+
 /**
  * The seat-log clause. The status is always present; the detail only when the
  * keep-list kept one. `grep 'upstream refused'` finds every refusal, which is