@commonlyai/cli 0.1.172 → 0.1.174

package/node_modules/@commonlyai/seats/src/trace/store.js

@@ -0,0 +1,276 @@
+/**
+ * Append-only trace store on the local filesystem.
+ *
+ *   <root>/runs/<runId>.jsonl   the run record (docs/record-v1.md): one
+ *                               canonical, hash-chained entry per line
+ *   <root>/index.jsonl          one line per started run, one per settled run;
+ *                               a store convenience, not part of the format
+ *
+ * Files are 0600 and directories 0700: a trace holds agent output.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  appendEntry, hashLine, kindOfType, readRecord, traceTypeOf, validateActor, verifyRecord, BOARD_ACTOR,
+} from '../record/format.js';
+
+const RUN_ID = /^[A-Za-z0-9_-]{6,64}$/;
+const readJsonl = (path) => (existsSync(path)
+  ? readFileSync(path, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
+    try { return [JSON.parse(line)]; } catch { return []; }
+  })
+  : []);
+
+/**
+ * Known credential values never reach a line, even inside agent text. Every
+ * registered value is replaced, whatever its length: the eight-character
+ * floor in redactKnownCredentials belongs to the refusal-text reader, not to
+ * the record. `secrets` is kept longest first, so a value that contains a
+ * shorter one is replaced whole rather than in pieces.
+ */
+const scrubText = (text, secrets) => {
+  let out = text;
+  for (const value of secrets) out = out.split(value).join('[redacted]');
+  return out;
+};
+
+const scrub = (value, secrets) => {
+  if (secrets.length === 0) return value;
+  if (typeof value === 'string') return scrubText(value, secrets);
+  if (Array.isArray(value)) return value.map((item) => scrub(item, secrets));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrub(item, secrets)]));
+  }
+  return value;
+};
+
+/**
+ * Streamed agent text arrives in deltas, so a value can be split across two or
+ * more of them and match none on its own. Each stream (kind + actor) is
+ * scrubbed over a rolling window instead: the held tail is joined to the next
+ * delta, the join is scrubbed, and the longest suffix of the result that
+ * could still begin a known value is held back again. What is written is the
+ * rest.
+ *
+ * Why that is enough: an occurrence that started inside written text and ran
+ * past its end would make the written part plus the held tail a proper prefix
+ * of that value, a longer such suffix than the one held. So no value spans a
+ * written boundary, and each written piece is itself scrubbed. The tail is
+ * shorter than the longest value, and only as long as an actual prefix match.
+ */
+const STREAMED_KINDS = new Set(['agent.message_chunk', 'agent.thought_chunk']);
+// The held text is written out before these, so it stays in its own attempt
+// and is never lost at settle, whichever path (ok, failure, cancel, kill) got there.
+const FLUSH_BEFORE = new Set(['attempt.started', 'attempt.settled', 'run.settled']);
+
+const heldLength = (text, secrets) => {
+  const longest = secrets.length ? secrets[0].length : 0;
+  for (let start = Math.max(0, text.length - longest + 1); start < text.length; start += 1) {
+    const tail = text.slice(start);
+    if (secrets.some((value) => value.length > tail.length && value.startsWith(tail))) return text.length - start;
+  }
+  return 0;
+};
+
+/** What readRun has always returned, plus the envelope: `type` is the trace name. */
+const asEvent = (entry) => (entry.kind ? { ...entry, type: traceTypeOf(entry.kind) } : entry);
+
+export const createTraceStore = ({ root, now = () => new Date() } = {}) => {
+  if (!root) throw new Error('createTraceStore needs a root directory');
+  const runsDir = join(root, 'runs');
+  mkdirSync(runsDir, { recursive: true, mode: 0o700 });
+  const append = (path, value) => appendFileSync(path, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+  const indexPath = join(root, 'index.jsonl');
+
+  /**
+   * startRun({ runId?, adapter?, label?, taskId?, podId?, actor? })
+   *   → { runId, emit, redact, revokeGrant, expireGrants, openGrants, settled }
+   *
+   * `taskId` is the board's task id verbatim and needs `podId`, since task
+   * ids repeat across pods. `actor` is the run's own party, normally
+   * {type: 'agent', id: <user id>, owner: <user id>}.
+   */
+  const startRun = (meta = {}) => {
+    const runId = meta.runId || randomUUID();
+    if (!RUN_ID.test(runId)) throw new Error('runId must be 6-64 characters of [A-Za-z0-9_-]');
+    const taskId = meta.taskId || undefined;
+    const podId = meta.podId || undefined;
+    if (taskId && !podId) throw new Error('a taskId needs a podId: task ids repeat across pods');
+    const runActor = meta.actor === undefined ? null : validateActor(meta.actor);
+    const path = join(runsDir, `${runId}.jsonl`);
+    try {
+      writeFileSync(path, '', { mode: 0o600, flag: 'wx' });
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`run ${runId} already exists`);
+      throw error;
+    }
+    let last = null; // the previous line, which the next one hashes
+    let seq = 0;
+    let settled = false;
+    let broken = false;
+    const secrets = []; // longest first; see scrubText
+    const streams = new Map(); // stream key → { kind, actor, held }
+    const grants = new Map(); // open grants: grantId → { parentGrantId, binding, expiresAt }
+    const startedAt = now();
+
+    const writeLine = (kind, data, actor) => {
+      const line = appendEntry(last, {
+        runId, taskId, podId, ts: now().toISOString(), kind, data: scrub(data, secrets), actor,
+      }, { runActor });
+      try {
+        appendFileSync(path, `${line}\n`, { mode: 0o600 });
+      } catch (error) {
+        // Some bytes may have landed; a chain cannot continue past an unknown tail.
+        broken = true;
+        throw error;
+      }
+      last = line;
+      seq += 1;
+      const entry = JSON.parse(line);
+      if (kind === 'grant.issued') {
+        grants.set(entry.data.grantId, {
+          parentGrantId: entry.data.parentGrantId ?? null, binding: entry.data.binding || null, expiresAt: entry.data.expiresAt || null,
+        });
+      }
+      if (kind === 'grant.revoked') for (const id of entry.data.grantIds) grants.delete(id);
+      return asEvent(entry);
+    };
+
+    /** A streamed delta's text, less a tail that could begin a known value. */
+    const windowed = (kind, data, actor) => {
+      if (!STREAMED_KINDS.has(kind) || typeof data?.text !== 'string') return data;
+      const key = JSON.stringify([kind, actor ?? null]);
+      const joined = scrubText(`${streams.get(key)?.held ?? ''}${data.text}`, secrets);
+      const cut = joined.length - heldLength(joined, secrets);
+      if (cut < joined.length) streams.set(key, { kind, actor, held: joined.slice(cut) });
+      else streams.delete(key);
+      return { ...data, text: joined.slice(0, cut) };
+    };
+
+    const write = (kind, data, actor) => writeLine(kind, windowed(kind, data, actor), actor);
+
+    /**
+     * The stream has ended, so each held tail can no longer complete a value.
+     * A tail is held only while it is a prefix of a known value, so it is part
+     * of a credential: write the marker in its place, never the prefix.
+     */
+    const flushStreams = () => {
+      for (const [key, { kind, actor }] of streams) {
+        streams.delete(key);
+        writeLine(kind, { text: '[redacted]' }, actor);
+      }
+    };
+
+    const revoke = (grantIds, reason, actor) => (grantIds.length ? write('grant.revoked', { grantIds, reason }, actor) : null);
+
+    const emit = (type, data = {}, options = {}) => {
+      const kind = kindOfType(type);
+      if (!kind) throw new Error(`unknown trace event type: ${type}`);
+      if (settled) return null;
+      if (broken) throw new Error(`run ${runId}: the record is broken after a failed write`);
+      if (FLUSH_BEFORE.has(kind)) flushStreams();
+      const event = write(kind, data, options?.actor);
+      if (kind === 'task.done') {
+        // The board closed the task: every grant bound to it ends, in one write.
+        const bound = [...grants].filter(([, g]) => g.binding?.endsOn === 'task.done').map(([id]) => id);
+        revoke(bound, 'task.done', BOARD_ACTOR);
+      }
+      if (kind === 'run.settled') {
+        settled = true;
+        append(indexPath, {
+          runId,
+          settledAt: event.ts,
+          outcome: event.data.outcome,
+          failure: event.data.failure || null,
+          durationMs: event.data.durationMs ?? null,
+          entries: seq,
+          head: hashLine(last),
+        });
+      }
+      return event;
+    };
+
+    /** Revoke a grant and every descendant this run knows of, in one entry. */
+    const revokeGrant = (grantId, { actor } = {}) => {
+      if (settled || !grants.has(grantId)) return null;
+      const lineage = [grantId];
+      for (let i = 0; i < lineage.length; i += 1) {
+        for (const [id, g] of grants) if (g.parentGrantId === lineage[i] && !lineage.includes(id)) lineage.push(id);
+      }
+      return revoke(lineage, lineage.length > 1 ? 'cascade' : 'manual', actor);
+    };
+
+    /** Record the end of every open grant whose expiresAt has passed. */
+    const expireGrants = (at = now()) => {
+      if (settled) return null;
+      const cutoff = at.getTime();
+      return revoke([...grants].filter(([, g]) => g.expiresAt && Date.parse(g.expiresAt) <= cutoff).map(([id]) => id), 'expired');
+    };
+
+    /** Every non-empty string is scrubbed from here on, whatever its length. */
+    const redact = (values = []) => {
+      for (const value of values) if (typeof value === 'string' && value && !secrets.includes(value)) secrets.push(value);
+      secrets.sort((a, b) => b.length - a.length);
+    };
+
+    append(indexPath, {
+      runId,
+      startedAt: startedAt.toISOString(),
+      adapter: meta.adapter || null,
+      label: meta.label || null,
+      ...(taskId ? { taskId, podId } : podId ? { podId } : {}),
+      ...(runActor ? { actor: runActor } : {}),
+    });
+    return {
+      runId,
+      taskId: taskId ?? null,
+      podId: podId ?? null,
+      emit,
+      redact,
+      revokeGrant,
+      expireGrants,
+      openGrants: () => [...grants.keys()],
+      get settled() { return settled; },
+    };
+  };
+
+  const listRuns = ({ limit = 50 } = {}) => {
+    const byId = new Map();
+    for (const line of readJsonl(indexPath)) {
+      const row = byId.get(line.runId) || { runId: line.runId, outcome: 'running' };
+      Object.assign(row, line);
+      byId.set(line.runId, row);
+    }
+    return [...byId.values()].sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt))).slice(0, limit);
+  };
+
+  const runPath = (runId) => (RUN_ID.test(String(runId)) ? join(runsDir, `${runId}.jsonl`) : null);
+
+  const readRun = (runId) => {
+    const path = runPath(runId);
+    return path && existsSync(path) ? readRecord(readFileSync(path, 'utf8')).map(asEvent) : null;
+  };
+
+  /**
+   * verifyRun(runId) → { ok, errors: [{seq, reason, detail?}], entries, head, settled } | null
+   *
+   * The chain check from verifyRecord, plus the last line against the head the
+   * index recorded at settle (head_mismatch, count_mismatch). The index sits
+   * beside the record, so that check catches accidents, not an editor.
+   */
+  const verifyRun = (runId) => {
+    const path = runPath(runId);
+    if (!path || !existsSync(path)) return null;
+    const result = verifyRecord(readFileSync(path, 'utf8'));
+    const sealed = readJsonl(indexPath).filter((row) => row.runId === runId && row.head).pop();
+    if (sealed) {
+      if (sealed.entries !== result.entries) result.errors.push({ seq: sealed.entries, reason: 'count_mismatch', detail: `index ${sealed.entries}, file ${result.entries}` });
+      else if (sealed.head !== result.head) result.errors.push({ seq: sealed.entries, reason: 'head_mismatch' });
+      result.ok = result.errors.length === 0;
+    }
+    return result;
+  };
+
+  return { root, startRun, listRuns, readRun, verifyRun };
+};

package/node_modules/@commonlyai/seats/src/upstream-refusal.js

@@ -0,0 +1,362 @@
+/**
+ * TASK-096 — name a refused model route, instead of reporting the silence it
+ * causes.
+ *
+ * Measured 2026-09-22 against pi 0.84.1 with a route answering 429 (the shape
+ * that made a seat look broken for two and a half days): pi runs its own retry
+ * ladder, reports the refusal on `message_end`/`auto_retry_end` JSON events, and
+ * EXITS 0 with no assistant text. `extractReply` in the pi adapter collected only
+ * `type: "error"` events — of which this produces none — so the wrapper logged
+ * `no wrapper-post (empty output)` and the cause sat unread in the stream.
+ *
+ * Two rules govern the text that reaches a seat log:
+ *
+ *  1. KEEP-LIST, not strip-list (Vera 70876, Wren 70877). A strip-list removes
+ *     only the shapes we thought of, and a 401 can echo the key back. So a body
+ *     contributes one NAMED field or nothing at all.
+ *  2. Exact-match refusal for credentials. If the kept text contains a value
+ *     this spawn was handed, the text is dropped — a known value, not a guessed
+ *     shape (Wren 70877).
+ *
+ * Two limits follow from rule 2. They are the accepted cost of refusing guessed
+ * shapes, named here so they are not rediscovered as defects later (Vera 71082):
+ *
+ *  a. The match is exact and against THIS spawn's values only, so a credential
+ *     that arrives transformed — base64 inside a proxy error, percent-encoded in
+ *     a URL echo — does not match and the text is kept. Matching transformed
+ *     shapes instead would reintroduce the class rule 1 exists to avoid.
+ *  b. The keep-list can still surface someone ELSE's secret. A third party's key
+ *     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 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. */
+export const MAX_REFUSAL_DETAIL = 256;
+
+/**
+ * The status an adapter prefixes to its error text: `"429: {…}"` -> `429`.
+ * Null for anything that is not a 4xx/5xx, so a message that merely starts with
+ * a number ("4040 tokens over budget") is not read as a status.
+ *
+ * The separator pi uses is NOT fixed — measured 2026-09-22, the same pi 0.84.1
+ * emits `"429: {"message":…}"` for a JSON body and `"502 <html>…"` for an
+ * HTML one. Both forms are matched here; a parser that required the colon would
+ * have kept `502 <html>…` as the whole "body" and then dropped it as non-JSON,
+ * reporting the status alone with no sign that the body was never read.
+ */
+const STATUS_PREFIX = /^\s*(\d{3})(?!\d)\s*:?\s*/;
+
+export const statusFromError = (value) => {
+  const match = STATUS_PREFIX.exec(String(value ?? ''));
+  if (!match) return null;
+  const status = Number(match[1]);
+  return status >= 400 && status <= 599 ? status : null;
+};
+
+/**
+ * The body the adapter carried after its status prefix, or the whole text when
+ * there is no status to strip. `"429: {"message":"a: b"}"` -> `{"message":"a: b"}`;
+ * `"502 <html>"` -> `<html>`.
+ */
+export const bodyFromError = (value) => {
+  const text = String(value ?? '');
+  if (statusFromError(text) === null) return text.trim();
+  return text.replace(STATUS_PREFIX, '').trim();
+};
+
+/** The shortest value the refusal-text reader treats as a credential. */
+export const MIN_CREDENTIAL_LENGTH = 8;
+
+/**
+ * Replace credential values this spawn was handed with a marker.
+ *
+ * This is the exact-match half, for text that is kept for its whole shape rather
+ * than filtered to one field — an adapter's stderr tail, say, whose diagnostic
+ * value is in the lines around the secret. Values shorter than eight characters
+ * are ignored: redacting a one-character "credential" would corrupt ordinary
+ * prose, and no issued credential is that short.
+ *
+ * The floor belongs to this reader only. The trace store scrubs every value
+ * registered with it, whatever its length, and the valet refuses to grant a
+ * credential shorter than this (credential_denied), so no granted value is
+ * ever below the floor.
+ */
+export const redactKnownCredentials = (text, credentials = []) => {
+  let out = String(text ?? '');
+  for (const value of credentials) {
+    if (typeof value !== 'string' || value.length < MIN_CREDENTIAL_LENGTH) continue;
+    out = out.split(value).join('[redacted]');
+  }
+  return out;
+};
+
+/**
+ * The keep-list. Given the raw body an adapter captured, keep at most one named
+ * field of it and only when that field is a string:
+ *
+ *   `error.message` first (the OpenAI-shaped error), then a top-level `message`
+ *   (which is the shape LiteLLM's budget refusal actually uses — the motivating
+ *   case; a keep-list that kept only `error.message` would name the status and
+ *   still hide the budget line that started this row).
+ *
+ * Everything else — HTML, a non-JSON body, a JSON body with neither field, a
+ * body echoing a known credential — contributes nothing. Returns null rather
+ * than a partial guess.
+ */
+export const keptRefusalDetail = (raw, { credentials = [] } = {}) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw ?? ''));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+
+  const candidate = parsed?.error?.message ?? parsed?.message;
+  if (typeof candidate !== 'string') return null;
+
+  const text = candidate.replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+
+  const redacted = redactKnownCredentials(text, credentials);
+  // `[redacted]` appearing is the signal that the body echoed something this
+  // spawn was handed. The status is still worth keeping; the text is not.
+  if (redacted !== text) return null;
+
+  return text.length > MAX_REFUSAL_DETAIL
+    ? `${text.slice(0, MAX_REFUSAL_DETAIL - 1)}…`
+    : text;
+};
+
+/**
+ * Read a pi JSON stream and return the refusal it ended on, or null.
+ *
+ * `auto_retry_end` is the terminal word — it names the status and the body after
+ * the ladder has finished — so it wins over the per-attempt `message_end`
+ * events that precede it. A run that refused on its first attempt and never
+ * retried still reports through `message_end`.
+ */
+export const readUpstreamRefusal = (stdout, { credentials = [] } = {}) => {
+  let status = null;
+  let raw = null;
+
+  for (const line of String(stdout ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (event?.type === 'auto_retry_end' && event.success === false) {
+      const candidate = event.finalError ?? event.errorMessage;
+      const attemptStatus = statusFromError(candidate);
+      if (attemptStatus) {
+        status = attemptStatus;
+        raw = bodyFromError(candidate);
+      }
+      continue;
+    }
+
+    const message = event?.message;
+    if (
+      event?.type === 'message_end'
+      && message?.role === 'assistant'
+      && message.stopReason === 'error'
+      && status === null
+    ) {
+      const attemptStatus = statusFromError(message.errorMessage);
+      if (attemptStatus) {
+        status = attemptStatus;
+        raw = bodyFromError(message.errorMessage);
+      }
+    }
+  }
+
+  if (status === null) return null;
+  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
+ * the property the old `no wrapper-post (empty output)` line did not have.
+ */
+export const describeUpstreamRefusal = (refusal) => {
+  if (!refusal || typeof refusal.status !== 'number') return null;
+  return refusal.detail
+    ? `upstream refused ${refusal.status}: ${refusal.detail}`
+    : `upstream refused ${refusal.status}`;
+};
+
+/**
+ * The credential values this spawn was handed, for the exact-match check in
+ * `redactKnownCredentials`. `envNames` are the adapter's own provider keys; the
+ * caller supplies them because only the adapter knows which key its route uses.
+ */
+export const spawnCredentials = (ctx = {}, envNames = []) => {
+  const env = ctx.env || process.env || {};
+  return [
+    ctx.runtimeToken,
+    ...envNames.map((name) => env[name]),
+  ].filter((value) => typeof value === 'string' && value.length >= MIN_CREDENTIAL_LENGTH);
+};