tumwater 0.4.1 → 0.4.2

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.4.1**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
+**v0.4.2**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
 which files tumwater bugs from tumwater's own event log, and `feedback`, which files them as GitHub
 issues on znation/tumwater, are opt-in (`roles.selfcheck.enabled`, `roles.feedback.enabled`).
 
@@ -75,11 +75,9 @@ and `tumwater pause`, `resume`, `wake`, and `stop` control the roles. `tumwater
 so pair it with `--token <secret>`.
 
 `tumwater prompt --attach <image>` gives a role an image to read at its next run. When a role's
-model cannot read images, the command refuses the attachment up front (naming the fix) unless
-the role reroutes a blind read to a vision model, in which case it says where the message will
-run; `tumwater doctor` probes each claimed image-input model once (cached 7 days, `--reprobe` to
-force) and the dashboards and `tumwater role <id>` say which roles read images and where a blind
-run reroutes.
+model cannot read images, the command refuses the attachment up front (naming the fix); the
+dashboards and `tumwater role <id>` say which roles read images. Nothing reroutes a blind read
+to another tier — a run that reads an image its model cannot see fails with `lastError`.
 
 Every command, flag, and TUI key is in [docs/cli.md](docs/cli.md); `tumwater help` prints the
 same list, and `tumwater completion bash|zsh|fish` prints shell completion. Settings live in

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "defe3e5dd243a9eb3c844751752328d88f5ad674",
-  "builtAt": 1792989016668,
+  "sha": "115515a5f5134c37c2bf8fa9dfb0edf620dd94b6",
+  "builtAt": 1793081614993,
   "root": "/home/runner/work/tumwater/tumwater"
 }

package/dist/src/agent/backend-traits.js

@@ -95,3 +95,17 @@ export function backendDefaultLabel(backend) {
  * for one cannot go missing from the other (opencode classifies the same failure from message
  * text, not a status code, so it is not in the set). */
 export const SERVER_TRANSIENT_STATUS = new Set([500, 502, 503, 504, 529]);
+/** Classify a failure message's prose into the transient-backend failure it names, when the
+ * wire carries no structured signal: a dropped connection or a timeout, read from the message
+ * text by claude's and opencode's stream translators, which both fall back to prose for the
+ * statuses their native events leave to the message (claude's classifyResult and opencode's
+ * classifyError end with this same connection/then-timeout tail). The single home of the
+ * connection/timeout vocabulary, so the two backends' tail regexes cannot drift. undefined
+ * when the text names neither. */
+export function transientProseKind(text) {
+    if (/connection|econn|refused|reset|terminated/i.test(text))
+        return { kind: "transientBackend", backendKind: "connection" };
+    if (/timed out|timeout/i.test(text))
+        return { kind: "transientBackend", backendKind: "timeout" };
+    return undefined;
+}

package/dist/src/agent/claude/claude-stream.js

@@ -15,9 +15,9 @@
  * `agent_unknown_event` warning after the run. `cost_unknown` is recorded the same way when a
  * run produced no authoritative `run_cost`. */
 import { joinParts } from "../../text/text.js";
-import { secondsUntil } from "../../text/datetime.js";
-import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
-import { SERVER_TRANSIENT_STATUS } from "../backend-traits.js";
+import { secondsUntilUnixStamp } from "../../text/datetime.js";
+import { canonicalUsageBlock, isJsonObject, nonNegativeNumber, objectOrEmpty, optionalString, parseJsonObject } from "../../files/json-object.js";
+import { SERVER_TRANSIENT_STATUS, transientProseKind } from "../backend-traits.js";
 /** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
  * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
  * lower-cased so a future tool still reads as a name rather than as `undefined`. */
@@ -32,9 +32,6 @@ const TOOL_NAMES = {
 };
 /** claude's HTTP status classes that mean a permanent configuration error. */
 const CONFIG_STATUS = new Set([400, 401, 403, 404]);
-function str(value) {
-    return typeof value === "string" ? value : undefined;
-}
 /** claude's usage block → pi's canonical usage block, with `cost.total` 0 because the run's
  * authoritative cost rides the final `run_cost` event (a split-block message repeats its usage
  * on every event, so summing per event would double-count — the fold takes it once). The
@@ -49,15 +46,15 @@ function canonicalUsage(usage) {
 function canonicalBlock(block) {
     switch (block.type) {
         case "text":
-            return { type: "text", text: str(block.text) ?? "" };
+            return { type: "text", text: optionalString(block.text) ?? "" };
         case "thinking":
-            return { type: "thinking", thinking: str(block.thinking) ?? str(block.text) ?? "" };
+            return { type: "thinking", thinking: optionalString(block.thinking) ?? optionalString(block.text) ?? "" };
         case "tool_use": {
             const input = objectOrEmpty(block.input);
             const args = { ...input };
             if (typeof input.file_path === "string")
                 args.path = input.file_path;
-            const name = str(block.name) ?? "";
+            const name = optionalString(block.name) ?? "";
             // Own-property test, not a bare index: a tool name like `constructor`, `toString`, or
             // `__proto__` would otherwise inherit a function (or Object.prototype) from the table's
             // prototype chain and bypass the lower-cased fallback — JSON.stringify then drops the
@@ -65,7 +62,7 @@ function canonicalBlock(block) {
             // applies to EFFORT_BY_THINKING.
             return {
                 type: "toolCall",
-                id: str(block.id) ?? "",
+                id: optionalString(block.id) ?? "",
                 name: Object.hasOwn(TOOL_NAMES, name) ? (TOOL_NAMES[name]) : name.toLowerCase(),
                 arguments: args,
             };
@@ -81,12 +78,12 @@ function canonicalBlock(block) {
  * provider classification applies. `status` is `api_error_status`, which is null on the
  * not-logged-in result, so the text checks carry that case. */
 function classifyResult(result) {
-    const terminal = str(result.terminal_reason);
+    const terminal = optionalString(result.terminal_reason);
     if (terminal === "aborted_tools")
         return {};
     if (terminal === "error_max_budget_usd")
         return { kind: "budgetCapped" };
-    const text = joinParts([str(result.result), str(result.error)], " ");
+    const text = joinParts([optionalString(result.result), optionalString(result.error)], " ");
     if (/error_max_budget_usd/i.test(text))
         return { kind: "budgetCapped" };
     const status = nonNegativeNumber(result.api_error_status, undefined);
@@ -109,10 +106,9 @@ function classifyResult(result) {
         return { kind: "transientRateLimit" };
     if (/overloaded|internal server error|bad gateway|service unavailable|gateway timeout|\b5\d\d\b/i.test(text))
         return { kind: "transientBackend", backendKind: "server" };
-    if (/connection|econn|refused|reset|terminated/i.test(text))
-        return { kind: "transientBackend", backendKind: "connection" };
-    if (/timed out|timeout/i.test(text))
-        return { kind: "transientBackend", backendKind: "timeout" };
+    const prose = transientProseKind(text);
+    if (prose)
+        return prose;
     if (/\b(400|401|403|404)\b/i.test(text))
         return { kind: "configError" };
     return {};
@@ -169,14 +165,14 @@ export function claudeTranslator(opts = {}) {
         warnings.add(kind);
     };
     const handleSystem = (event) => {
-        const subtype = str(event.subtype);
+        const subtype = optionalString(event.subtype);
         if (subtype === "init") {
             const out = [];
-            const cwd = str(event.cwd);
-            const id = str(event.session_id);
+            const cwd = optionalString(event.cwd);
+            const id = optionalString(event.session_id);
             out.push(JSON.stringify({ type: "session", ...(cwd !== undefined ? { cwd } : {}), ...(id !== undefined ? { id } : {}) }));
             out.push(JSON.stringify({ type: "agent_start" }));
-            const billing = billingOf(str(event.apiKeySource), opts.thirdPartyProvider === true);
+            const billing = billingOf(optionalString(event.apiKeySource), opts.thirdPartyProvider === true);
             if (billing)
                 out.push(JSON.stringify({ type: "billing", billing }));
             return out;
@@ -185,7 +181,7 @@ export function claudeTranslator(opts = {}) {
             const attempt = nonNegativeNumber(event.attempt, undefined);
             const maxAttempts = nonNegativeNumber(event.max_retries, undefined);
             const status = nonNegativeNumber(event.error_status, undefined);
-            const error = str(event.error) ?? "";
+            const error = optionalString(event.error) ?? "";
             const errorMessage = joinParts([status !== undefined ? `status ${status}` : "", error], ": ");
             return [
                 JSON.stringify({
@@ -207,7 +203,7 @@ export function claudeTranslator(opts = {}) {
     const handleAssistant = (event) => {
         sawActivity = true;
         const message = objectOrEmpty(event.message);
-        const id = str(message.id) ?? `anon-${anonymous++}`;
+        const id = optionalString(message.id) ?? `anon-${anonymous++}`;
         // A new id flushes the open message; a continuing one flushes nothing. Either way the
         // fresh or open pending then folds this event's content, usage, and stop reason the
         // same way — that shared fold is why both branches live on one path.
@@ -230,7 +226,7 @@ export function claudeTranslator(opts = {}) {
         // Usage repeats on every event of the same message; the last read wins and is counted
         // once because the fold emits one message_end per id.
         pending.usage = canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined);
-        const stopReason = str(message.stop_reason);
+        const stopReason = optionalString(message.stop_reason);
         if (stopReason !== undefined)
             pending.stopReason = stopReason;
         return out;
@@ -244,7 +240,7 @@ export function claudeTranslator(opts = {}) {
                 continue;
             out.push(JSON.stringify({
                 type: "tool_execution_end",
-                toolCallId: str(raw.tool_use_id) ?? "",
+                toolCallId: optionalString(raw.tool_use_id) ?? "",
                 isError: raw.is_error === true,
             }));
         }
@@ -252,8 +248,8 @@ export function claudeTranslator(opts = {}) {
     };
     const handleRateLimitEvent = (event) => {
         const info = objectOrEmpty(event.rate_limit_info);
-        const rateLimitType = str(info.rateLimitType);
-        const status = str(info.status);
+        const rateLimitType = optionalString(info.rateLimitType);
+        const status = optionalString(info.status);
         // claude 2.1.295 reports every window's utilization and reset under `unifiedWindows`,
         // keyed by window type, and only the binding window's status at the top level.
         const windows = [];
@@ -281,14 +277,14 @@ export function claudeTranslator(opts = {}) {
         const utilization = nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
         if (utilization !== undefined)
             out.utilization = utilization;
-        const overageStatus = str(info.overageStatus);
+        const overageStatus = optionalString(info.overageStatus);
         if (overageStatus !== undefined)
             out.overageStatus = overageStatus;
         if (info.isUsingOverage === true)
             out.isUsingOverage = true;
         if (status === "rejected" && resetsAt !== undefined) {
-            // resetsAt is a unix-seconds stamp; secondsUntil folds it (×1000) to whole seconds.
-            out.retryAfterSeconds = secondsUntil(resetsAt * 1000, Date.now());
+            // resetsAt is a unix-seconds stamp; secondsUntilUnixStamp folds it to whole seconds.
+            out.retryAfterSeconds = secondsUntilUnixStamp(resetsAt, Date.now());
         }
         return [JSON.stringify(out), ...windows];
     };
@@ -315,7 +311,7 @@ export function claudeTranslator(opts = {}) {
                 content: [],
                 stopReason: "error",
             };
-            const errorMessage = str(event.result) ?? str(event.error);
+            const errorMessage = optionalString(event.result) ?? optionalString(event.error);
             if (errorMessage !== undefined)
                 message.errorMessage = errorMessage;
             // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
@@ -334,7 +330,7 @@ export function claudeTranslator(opts = {}) {
         if (!parsed)
             return []; // Non-JSON noise on stdout; ignore, as pi's parser does.
         const event = parsed;
-        const type = str(event.type);
+        const type = optionalString(event.type);
         switch (type) {
             case "system": return handleSystem(event);
             case "assistant": return handleAssistant(event);

package/dist/src/agent/codex/codex-rollout.js

@@ -13,11 +13,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { walkFiles } from "../../files/files.js";
-import { isJsonObject, nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
+import { isJsonObject, nonNegativeNumber, objectOrEmpty, optionalString, parseJsonObject } from "../../files/json-object.js";
 import { windowTypeName } from "./codex-stream.js";
-function str(value) {
-    return typeof value === "string" ? value : undefined;
-}
 function finite(value) {
     return nonNegativeNumber(value, undefined);
 }
@@ -32,15 +29,11 @@ function windowStatus(windowType, rateLimitReachedType, usedPercent) {
         return "allowed_warning";
     return "allowed";
 }
-/** Read the records of ONE turn out of a rollout's text. A rollout is one file per thread that
- * appends a new `task_started` block per run, so the adapter's `afterRun` read (which knows
- * only the thread id that names the file, never a turn id) reads the LAST block — everything
- * after the last `task_started`. `sinceTurnStart` (optional) selects a specific turn's block
- * instead, which pins per-turn isolation: the thread total hides a resume's own figures
- * (finding 4). `requestedModel` is the `-m` tumwater passed; a turn whose `turn_context.model`
- * differs reports the switch. */
-export function rolloutLines(text, opts) {
-    const { sinceTurnStart, requestedModel } = opts;
+/** Scan ONE turn's records out of a rollout's text, tracking `task_started` blocks and
+ * collecting the read turn's `turn_context.model`, `token_usage_record` usage, `token_count`
+ * rate limits and `plan_type`. `rolloutLines` decides emptiness from `sawTurn`/`lastUsage`;
+ * this scanner never decides it. */
+function scanTurnRecords(text, sinceTurnStart) {
     let currentTurn;
     let sawTurn = false;
     let lastUsage;
@@ -57,9 +50,9 @@ export function rolloutLines(text, opts) {
         // `task_started`, `task_complete` and `token_count` come wrapped in an `event_msg` whose
         // `payload.type` discriminates; `turn_context` and `token_usage_record` name themselves in
         // the outer `type`. Read either.
-        const ptype = str(parsed.type) === "event_msg" ? str(payload.type) : str(parsed.type);
+        const ptype = optionalString(parsed.type) === "event_msg" ? optionalString(payload.type) : optionalString(parsed.type);
         if (ptype === "task_started") {
-            currentTurn = str(payload.turn_id);
+            currentTurn = optionalString(payload.turn_id);
             // Each new task_started begins a fresh turn (a resume appends a second run to the same
             // file), so the collectors restart at the block we are reading. With no turn id (the
             // adapter's read) every task_started restarts them and the last block wins; with one,
@@ -78,7 +71,7 @@ export function rolloutLines(text, opts) {
         switch (ptype) {
             case "turn_context":
                 if (model === undefined)
-                    model = str(payload.model);
+                    model = optionalString(payload.model);
                 break;
             case "token_usage_record": {
                 const turnUsage = objectOrEmpty(payload.turn_token_usage);
@@ -90,7 +83,7 @@ export function rolloutLines(text, opts) {
             case "token_count": {
                 const rateLimits = objectOrEmpty(payload.rate_limits);
                 lastRateLimits = rateLimits;
-                const plan = str(rateLimits.plan_type);
+                const plan = optionalString(rateLimits.plan_type);
                 if (plan !== undefined)
                     planType = plan;
                 break;
@@ -99,12 +92,15 @@ export function rolloutLines(text, opts) {
                 break;
         }
     }
-    // No matching task_started, or the turn's usage record is missing or malformed (a truncated
-    // or torn file): there is no reading. (currentTurn will have moved on to a later run's
-    // task_started in a resume-shared file; sawTurn — not currentTurn — is the real signal.)
-    if (!sawTurn || !isJsonObject(lastUsage)) {
-        return { lines: [] };
-    }
+    return { sawTurn, lastUsage, lastRateLimits, model, planType };
+}
+/** Assemble the reading's canonical `run_usage`, `billing` and up-to-two `rate_limit` lines
+ * (in that order), plus the `switchedTo` model comparison, from scanned records. */
+function buildRolloutLines(records, requestedModel) {
+    // `rolloutLines` guarantees `lastUsage` is a Json object before calling (its presence check
+    // stays there, so this builder never reads `sawTurn`); narrow the shared interface here.
+    const lastUsage = records.lastUsage;
+    const { lastRateLimits, model, planType } = records;
     const lines = [];
     const input = finite(lastUsage.input_tokens) ?? 0;
     const cacheRead = finite(lastUsage.cached_input_tokens) ?? 0;
@@ -124,7 +120,7 @@ export function rolloutLines(text, opts) {
     // rollout has a token_usage_record but no token_count, so it yields run_usage with no
     // rate_limit (finding 23).
     if (lastRateLimits !== undefined) {
-        const reached = str(lastRateLimits.rate_limit_reached_type);
+        const reached = optionalString(lastRateLimits.rate_limit_reached_type);
         for (const key of ["primary", "secondary"]) {
             const windowRaw = lastRateLimits[key];
             if (!isJsonObject(windowRaw))
@@ -146,6 +142,24 @@ export function rolloutLines(text, opts) {
     const switchedTo = model !== undefined && requestedModel !== undefined && model !== requestedModel ? model : undefined;
     return { lines, ...(switchedTo !== undefined ? { switchedTo } : {}) };
 }
+/** Read the records of ONE turn out of a rollout's text. A rollout is one file per thread that
+ * appends a new `task_started` block per run, so the adapter's `afterRun` read (which knows
+ * only the thread id that names the file, never a turn id) reads the LAST block — everything
+ * after the last `task_started`. `sinceTurnStart` (optional) selects a specific turn's block
+ * instead, which pins per-turn isolation: the thread total hides a resume's own figures
+ * (finding 4). `requestedModel` is the `-m` tumwater passed; a turn whose `turn_context.model`
+ * differs reports the switch. */
+export function rolloutLines(text, opts) {
+    const { sinceTurnStart, requestedModel } = opts;
+    const records = scanTurnRecords(text, sinceTurnStart);
+    // No matching task_started, or the turn's usage record is missing or malformed (a truncated
+    // or torn file): there is no reading. (currentTurn will have moved on to a later run's
+    // task_started in a resume-shared file; sawTurn — not currentTurn — is the real signal.)
+    if (!records.sawTurn || !isJsonObject(records.lastUsage)) {
+        return { lines: [] };
+    }
+    return buildRolloutLines(records, requestedModel);
+}
 /** Locate the rollout file of `$CODEX_HOME` that names the session `id`: the first
  * `sessions/…/rollout-*-<id>.jsonl` under `home`, or null. It takes no start date and does no
  * date math — the id match alone decides (finding 5: Codex's rollout name carries local time,

package/dist/src/agent/codex/codex-stream.js

@@ -15,7 +15,7 @@
  */
 import { nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
 import { boundText, outputLimits } from "../../pi-extension/bounded-output.js";
-import { secondsUntil } from "../../text/datetime.js";
+import { secondsUntilUnixStamp } from "../../text/datetime.js";
 import { SERVER_TRANSIENT_STATUS } from "../backend-traits.js";
 /** How codex wraps every shell command — the prefix to strip (with its quoting) so the
  * canonical `bash` call carries the model's own command, which suite-rerun detection matches. */
@@ -43,31 +43,31 @@ export function windowTypeName(windowMinutes) {
         return "seven_day";
     return `${windowMinutes}_minute`;
 }
-/** One codex `error` item's distinct message → a run warning; repeated identical messages are
- * warned once (finding 11). */
-/** How a `turn.failed` error message classifies into the canonical `tumwaterKind` (and, for a
- * transient backend, its kind), trusted by `PiStreamParser` before its text regexes. The inner
- * `message` is a JSON string carrying `status` and `error.type` / `error.code` (finding 11).
- * Returns the canonical lines to emit beside the closing `message_end`: a rejected rate-limit
- * reading when the error names a used-up window. */
-function classifyTurnFailed(parsed) {
-    const kind = {};
+/** Read the `turn.failed` inner JSON's four deciding fields. The inner `message` is a JSON
+ * string carrying `status` and `error.type` / `error.code` (finding 11). */
+function readTurnFailedFields(parsed) {
     const error = objectOrEmpty(parsed.error);
-    const code = typeof error.code === "string" ? error.code : undefined;
-    const errType = typeof error.type === "string" ? error.type : undefined;
-    const message = typeof error.message === "string" ? error.message : typeof parsed.message === "string" ? parsed.message : undefined;
-    kind.errorMessage = message;
-    const status = nonNegativeNumber(parsed.status, undefined);
+    return {
+        code: typeof error.code === "string" ? error.code : undefined,
+        errType: typeof error.type === "string" ? error.type : undefined,
+        message: typeof error.message === "string" ? error.message : typeof parsed.message === "string" ? parsed.message : undefined,
+        status: nonNegativeNumber(parsed.status, undefined),
+    };
+}
+/** Owns the context-window arm: a `context_window_exceeded` code, or a 400 whose message names
+ * the context window, classifies as `contextExceeded`. */
+function isContextExceeded({ code, errType, message, status }) {
     // The context-window signal is tested BEFORE the generic 400 `invalid_request_error`
     // branch (as claude's classifyResult tests "prompt is too long" before CONFIG_STATUS): a
     // `context_window_exceeded` code, or a 400 whose message names the context window, is
     // `contextExceeded`, never `configError`.
     const namesContextWindow = (t) => t !== undefined &&
         /context window|context length|too long|exceeds? (the )?(model'?s )?context|prompt is too long/i.test(t);
-    if (code === "context_window_exceeded" || (status === 400 && errType === "invalid_request_error" && namesContextWindow(message))) {
-        kind.kind = "contextExceeded";
-        return kind;
-    }
+    return code === "context_window_exceeded" || (status === 400 && errType === "invalid_request_error" && namesContextWindow(message));
+}
+/** Owns the transient rate-limit arm: a `usage_limit_reached` / `rate_limit_exceeded` code or a
+ * 429 returns the rejected reading naming the used-up window, else undefined. */
+function rateLimitReading(parsed, { code, status }) {
     if (code === "usage_limit_reached" || code === "rate_limit_exceeded" || status === 429) {
         // Which window the account hit, from the error's own `rate_limit_reached_type` (else the
         // five-hour window, the one Plus exhausts first). The rejected reading's wait comes from
@@ -75,42 +75,75 @@ function classifyTurnFailed(parsed) {
         const minutes = nonNegativeNumber(parsed.rate_limit_reached_type, undefined);
         const named = typeof parsed.rate_limit_reached_type === "string" ? parsed.rate_limit_reached_type : undefined;
         const resetsAt = nonNegativeNumber(parsed.resets_at, undefined);
-        // secondsUntil folds the unix-seconds resets stamp (×1000 to epoch-ms), clamped at 0.
-        const retryAfter = resetsAt === undefined ? undefined : secondsUntil(resetsAt * 1000, Date.now());
-        kind.kind = "transientRateLimit";
-        kind.rateLimit = {
+        return {
             type: "rate_limit",
             rateLimitType: typeof named === "string" && /_minute$|_hour$|_day$/.test(named)
                 ? named
                 : windowTypeName(minutes ?? 300),
             status: "rejected",
             utilization: 1,
-            ...(resetsAt !== undefined ? { resetsAt } : {}),
-            ...(retryAfter !== undefined ? { retryAfterSeconds: retryAfter } : {}),
+            // secondsUntilUnixStamp folds the unix-seconds resets stamp to epoch-ms, clamped at 0.
+            ...(resetsAt === undefined
+                ? {}
+                : { resetsAt, retryAfterSeconds: secondsUntilUnixStamp(resetsAt, Date.now()) }),
         };
-        return kind;
     }
-    if (code === "usage_not_included") {
-        kind.kind = "configError";
+    return undefined;
+}
+/** Owns the used-up-account arm: `usage_not_included` is a permanent config error, never a
+ * transient retry. */
+function isUsageNotIncluded({ code }) {
+    return code === "usage_not_included";
+}
+/** Owns the server-status arm: any `SERVER_TRANSIENT_STATUS` is a transient backend. */
+function isTransientServer({ status }) {
+    return status !== undefined && SERVER_TRANSIENT_STATUS.has(status);
+}
+/** Owns the permanent-login arms: a reused/invalidated refresh token, a 401, and a 400
+ * `invalid_request_error` are permanent config errors. */
+function isPermanentLogin({ message, status, errType }) {
+    // A refresh-token failure and an absent/invalid login are permanent config errors, which
+    // the doctor names with the login command (design §5).
+    if (/refresh_token_reused|invalidated refresh token/i.test(message ?? ""))
+        return true;
+    if (status === 401)
+        return true;
+    if (status === 400 && errType === "invalid_request_error") {
+        // A 400 `invalid_request_error` names the model as unsupported on a ChatGPT account.
+        return true;
+    }
+    return false;
+}
+/** How a `turn.failed` error message classifies into the canonical `tumwaterKind` (and, for a
+ * transient backend, its kind), trusted by `PiStreamParser` before its text regexes. The inner
+ * `message` is a JSON string carrying `status` and `error.type` / `error.code` (finding 11).
+ * Returns the canonical lines to emit beside the closing `message_end`: a rejected rate-limit
+ * reading when the error names a used-up window. The body is an ordered composition; each arm
+ * lives in its named helper: `readTurnFailedFields` (the field reads), `isContextExceeded`,
+ * `rateLimitReading`, `isUsageNotIncluded`, `isTransientServer` and `isPermanentLogin`. */
+function classifyTurnFailed(parsed) {
+    const fields = readTurnFailedFields(parsed);
+    const kind = { errorMessage: fields.message };
+    if (isContextExceeded(fields)) {
+        kind.kind = "contextExceeded";
         return kind;
     }
-    if (status !== undefined && SERVER_TRANSIENT_STATUS.has(status)) {
-        kind.kind = "transientBackend";
-        kind.backendKind = "server";
+    const rateLimit = rateLimitReading(parsed, fields);
+    if (rateLimit !== undefined) {
+        kind.kind = "transientRateLimit";
+        kind.rateLimit = rateLimit;
         return kind;
     }
-    // A refresh-token failure and an absent/invalid login are permanent config errors, which
-    // the doctor names with the login command (design §5).
-    if (/refresh_token_reused|invalidated refresh token/i.test(message ?? "")) {
+    if (isUsageNotIncluded(fields)) {
         kind.kind = "configError";
         return kind;
     }
-    if (status === 401) {
-        kind.kind = "configError";
+    if (isTransientServer(fields)) {
+        kind.kind = "transientBackend";
+        kind.backendKind = "server";
         return kind;
     }
-    if (status === 400 && errType === "invalid_request_error") {
-        // A 400 `invalid_request_error` names the model as unsupported on a ChatGPT account.
+    if (isPermanentLogin(fields)) {
         kind.kind = "configError";
         return kind;
     }