switchroom 0.13.10 → 0.13.11

package/dist/cli/switchroom.js

@@ -47314,8 +47314,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.10";
-var COMMIT_SHA = "e0fd6617";
+var VERSION = "0.13.11";
+var COMMIT_SHA = "5984798c";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.10",
+  "version": "0.13.11",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/bridge/bridge.js

@@ -23004,7 +23004,7 @@ function classifyInner(raw) {
     return "rate-limited";
   }
   if (errorType === "overloaded_error" || errorCode === "overloaded_error" || sdkCode === "overloaded_error" || message.toLowerCase().includes("overloaded_error") || message.toLowerCase().includes("overloaded")) {
-    return "quota-exhausted";
+    return "rate-limited";
   }
   if (errorType === "agent-crashed" || errorCode === "agent-crashed") {
     return "agent-crashed";
@@ -23349,6 +23349,12 @@ function projectSubagentLine(line, agentId, state) {
   }
   return [];
 }
+function extractRetryState(obj) {
+  return {
+    retryAttempt: typeof obj.retryAttempt === "number" ? obj.retryAttempt : null,
+    maxRetries: typeof obj.maxRetries === "number" ? obj.maxRetries : null
+  };
+}
 function detectErrorInTranscriptLine(line) {
   if (!line || line.length > 2 * 1024 * 1024)
     return null;
@@ -23366,7 +23372,13 @@ function detectErrorInTranscriptLine(line) {
     const errStr = typeof obj.error === "string" ? obj.error : "";
     const text = extractAssistantText(obj);
     const kind2 = status === 429 ? "quota-exhausted" : classifyClaudeError({ type: errStr, status, message: text });
-    return { kind: kind2, raw: obj, detail: text || errStr || "api error" };
+    return {
+      kind: kind2,
+      raw: obj,
+      detail: text || errStr || "api error",
+      transient: kind2 === "rate-limited",
+      terminal: true
+    };
   }
   const isErrorLine = type === "api_error" || type === "error";
   const embeddedError = typeof obj.error === "object" && obj.error != null ? obj.error : null;
@@ -23375,7 +23387,10 @@ function detectErrorInTranscriptLine(line) {
   const raw = embeddedError ?? obj;
   const kind = classifyClaudeError(embeddedError ?? obj);
   const detail = extractDetailMessage(embeddedError) ?? extractDetailMessage(obj) ?? String(type ?? "");
-  return { kind, raw, detail };
+  const transient = kind === "rate-limited";
+  const retry = extractRetryState(obj);
+  const terminal = !transient ? true : retry.retryAttempt != null && retry.maxRetries != null ? retry.retryAttempt >= retry.maxRetries : isErrorLine;
+  return { kind, raw, detail, transient, terminal };
 }
 function extractDetailMessage(obj) {
   if (!obj)
@@ -23497,7 +23512,11 @@ function startSessionTail(config2) {
           try {
             const errEvent = detectErrorInTranscriptLine(line);
             if (errEvent) {
-              onOperatorEvent(errEvent);
+              if (errEvent.terminal || !errEvent.transient) {
+                onOperatorEvent(errEvent);
+              } else {
+                log?.(`session-tail: transient overload suppressed (in-flight retry) kind=${errEvent.kind}`);
+              }
             }
           } catch (err) {
             log?.(`session-tail: onOperatorEvent threw: ${err.message}`);

package/telegram-plugin/dist/gateway/gateway.js

@@ -39632,7 +39632,8 @@ function resolveModelUnavailableFromOperatorEvent(ev) {
     return detectModelUnavailable(detail) ?? { kind: "quota_exhausted", raw: detail };
   }
   if (ev.kind === "rate-limited") {
-    return detectModelUnavailable(detail) ?? { kind: "overload", raw: detail };
+    const detected = detectModelUnavailable(detail);
+    return detected?.kind === "quota_exhausted" ? detected : null;
   }
   if (ev.kind === "unknown-5xx") {
     return detectModelUnavailable(detail) ?? { kind: "overload", raw: detail };
@@ -44782,6 +44783,31 @@ ${result}
     }
   };
 }
+function decideSubagentHandback(input) {
+  if (input.handbackEnvValue === "0") {
+    return { deliver: false, reason: "env-disabled" };
+  }
+  if (input.outcome !== "completed" && input.outcome !== "failed") {
+    return { deliver: false, reason: "outcome-not-terminal" };
+  }
+  if (!input.isBackground) {
+    return { deliver: false, reason: "foreground" };
+  }
+  const chatId = input.fleetChatId || input.ownerChatId;
+  if (!chatId) {
+    return { deliver: false, reason: "no-chat" };
+  }
+  const inbound = buildSubagentHandbackInbound({
+    ctx: {
+      chatId,
+      taskDescription: input.taskDescription,
+      resultText: input.resultText,
+      outcome: input.outcome
+    },
+    ...input.nowMs !== undefined ? { nowMs: input.nowMs } : {}
+  });
+  return { deliver: true, chatId, inbound };
+}
 
 // gateway/poll-health.ts
 var DEFAULT_LOG = (msg) => {
@@ -48001,11 +48027,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.10";
-var COMMIT_SHA = "e0fd6617";
-var COMMIT_DATE = "2026-05-22T12:01:29+10:00";
+var VERSION = "0.13.11";
+var COMMIT_SHA = "5984798c";
+var COMMIT_DATE = "2026-05-22T15:59:07+10:00";
 var LATEST_PR = null;
-var COMMITS_AHEAD_OF_TAG = 6;
+var COMMITS_AHEAD_OF_TAG = 3;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -49628,7 +49654,7 @@ function emitGatewayOperatorEvent(event) {
   let renderedText;
   let renderedKeyboard;
   if (modelUnavailable) {
-    const isAutoKind = modelUnavailable.kind === "quota_exhausted" || modelUnavailable.kind === "overload";
+    const isAutoKind = modelUnavailable.kind === "quota_exhausted";
     const willActuallyFire = isAutoKind && wouldFireFleetAutoFallback();
     process.stderr.write(`telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind} autoKind=${isAutoKind} willFire=${willActuallyFire}
 `);
@@ -57321,17 +57347,13 @@ var didOneTimeSetup = false;
                 }
               },
               onFinish: ({ agentId, outcome, description, resultText }) => {
-                if (process.env.SWITCHROOM_SUBAGENT_HANDBACK === "0")
-                  return;
-                if (outcome !== "completed" && outcome !== "failed")
-                  return;
-                let chatId = "";
+                let fleetChatId = "";
                 let isBackground = false;
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? [];
                   for (const f of fleets) {
                     if (f.fleet.has(agentId)) {
-                      chatId = f.chatId ?? "";
+                      fleetChatId = f.chatId ?? "";
                       break;
                     }
                   }
@@ -57343,24 +57365,24 @@ var didOneTimeSetup = false;
                       isBackground = row.background === 1;
                   } catch {}
                 }
-                if (!isBackground)
-                  return;
-                const handbackChatId = chatId || (loadAccess().allowFrom[0] ?? "");
-                if (!handbackChatId) {
-                  process.stderr.write(`telegram gateway: subagent-handback ${agentId} \u2014 no chat to deliver to; skipped
+                const decision = decideSubagentHandback({
+                  handbackEnvValue: process.env.SWITCHROOM_SUBAGENT_HANDBACK,
+                  outcome,
+                  isBackground,
+                  fleetChatId,
+                  ownerChatId: loadAccess().allowFrom[0] ?? "",
+                  taskDescription: description,
+                  resultText
+                });
+                if (!decision.deliver) {
+                  if (decision.reason === "no-chat") {
+                    process.stderr.write(`telegram gateway: subagent-handback ${agentId} \u2014 no chat to deliver to; skipped
 `);
+                  }
                   return;
                 }
-                const inbound = buildSubagentHandbackInbound({
-                  ctx: {
-                    chatId: String(handbackChatId),
-                    taskDescription: description,
-                    resultText,
-                    outcome
-                  }
-                });
-                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? "", inbound);
-                process.stderr.write(`telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${handbackChatId} resultChars=${resultText.length}
+                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? "", decision.inbound);
+                process.stderr.write(`telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${decision.chatId} resultChars=${resultText.length}
 `);
               }
             });

package/telegram-plugin/dist/server.js

@@ -17029,7 +17029,7 @@ function classifyInner(raw) {
     return "rate-limited";
   }
   if (errorType === "overloaded_error" || errorCode === "overloaded_error" || sdkCode === "overloaded_error" || message.toLowerCase().includes("overloaded_error") || message.toLowerCase().includes("overloaded")) {
-    return "quota-exhausted";
+    return "rate-limited";
   }
   if (errorType === "agent-crashed" || errorCode === "agent-crashed") {
     return "agent-crashed";
@@ -17387,6 +17387,12 @@ function projectSubagentLine(line, agentId, state) {
   }
   return [];
 }
+function extractRetryState(obj) {
+  return {
+    retryAttempt: typeof obj.retryAttempt === "number" ? obj.retryAttempt : null,
+    maxRetries: typeof obj.maxRetries === "number" ? obj.maxRetries : null
+  };
+}
 function detectErrorInTranscriptLine(line) {
   if (!line || line.length > 2 * 1024 * 1024)
     return null;
@@ -17404,7 +17410,13 @@ function detectErrorInTranscriptLine(line) {
     const errStr = typeof obj.error === "string" ? obj.error : "";
     const text = extractAssistantText(obj);
     const kind2 = status === 429 ? "quota-exhausted" : classifyClaudeError({ type: errStr, status, message: text });
-    return { kind: kind2, raw: obj, detail: text || errStr || "api error" };
+    return {
+      kind: kind2,
+      raw: obj,
+      detail: text || errStr || "api error",
+      transient: kind2 === "rate-limited",
+      terminal: true
+    };
   }
   const isErrorLine = type === "api_error" || type === "error";
   const embeddedError = typeof obj.error === "object" && obj.error != null ? obj.error : null;
@@ -17413,7 +17425,10 @@ function detectErrorInTranscriptLine(line) {
   const raw = embeddedError ?? obj;
   const kind = classifyClaudeError(embeddedError ?? obj);
   const detail = extractDetailMessage(embeddedError) ?? extractDetailMessage(obj) ?? String(type ?? "");
-  return { kind, raw, detail };
+  const transient = kind === "rate-limited";
+  const retry = extractRetryState(obj);
+  const terminal = !transient ? true : retry.retryAttempt != null && retry.maxRetries != null ? retry.retryAttempt >= retry.maxRetries : isErrorLine;
+  return { kind, raw, detail, transient, terminal };
 }
 function extractDetailMessage(obj) {
   if (!obj)
@@ -17535,7 +17550,11 @@ function startSessionTail(config2) {
           try {
             const errEvent = detectErrorInTranscriptLine(line);
             if (errEvent) {
-              onOperatorEvent(errEvent);
+              if (errEvent.terminal || !errEvent.transient) {
+                onOperatorEvent(errEvent);
+              } else {
+                log?.(`session-tail: transient overload suppressed (in-flight retry) kind=${errEvent.kind}`);
+              }
             }
           } catch (err) {
             log?.(`session-tail: onOperatorEvent threw: ${err.message}`);

package/telegram-plugin/gateway/gateway.ts

@@ -281,7 +281,7 @@ import {
   buildVaultSaveFailedInbound,
   buildVaultSaveDiscardedInbound,
 } from './vault-grant-inbound-builders.js'
-import { buildSubagentHandbackInbound } from './subagent-handback-inbound-builder.js'
+import { decideSubagentHandback } from './subagent-handback-inbound-builder.js'
 import { createPollHealthCheck, type PollHealthCheckHandle } from './poll-health.js'
 import type {
   ToolCallMessage,
@@ -2712,8 +2712,14 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // Card text branches on the AND. wouldFireFleetAutoFallback is a
     // pure read of the dedup state; calling fireFleetAutoFallback only
     // when both are true keeps the card honest.
-    const isAutoKind =
-      modelUnavailable.kind === 'quota_exhausted' || modelUnavailable.kind === 'overload'
+    // Only a genuine quota / usage-limit hit is addressable by fleet
+    // auto-fallback (swap to an account that still has runway). An
+    // `overload` is transient Anthropic SERVER-side capacity pressure —
+    // every account is equally affected, so failing over does nothing;
+    // it just produces a self-cancelling "probed healthy / Stale event?"
+    // loop on every 529. Overload is handled by Claude Code's own
+    // internal retry, not by switching accounts.
+    const isAutoKind = modelUnavailable.kind === 'quota_exhausted'
     const willActuallyFire = isAutoKind && wouldFireFleetAutoFallback()
     process.stderr.write(
       `telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind} autoKind=${isAutoKind} willFire=${willActuallyFire}\n`,
@@ -15063,22 +15069,24 @@ void (async () => {
               // need nothing here, and 'orphan' is a stale historical-at-
               // boot row, not a fresh completion the user is waiting on.
               onFinish: ({ agentId, outcome, description, resultText }) => {
-                if (process.env.SWITCHROOM_SUBAGENT_HANDBACK === '0') return
-                if (outcome !== 'completed' && outcome !== 'failed') return
-
-                let chatId = ''
+                // IO: resolve the fleet chat id and the background flag.
+                // The DECISION (gating + inbound build) is delegated to
+                // the pure `decideSubagentHandback` so it is unit-tested
+                // independent of the gateway — see
+                // `subagent-handback-decision.test.ts`.
+                let fleetChatId = ''
                 let isBackground = false
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
                   for (const f of fleets) {
                     if (f.fleet.has(agentId)) {
-                      chatId = f.chatId ?? ''
+                      fleetChatId = f.chatId ?? ''
                       break
                     }
                   }
                 } catch {
                   // peek failures are non-fatal — fall through to the
-                  // owner-chat fallback below.
+                  // owner-chat fallback inside decideSubagentHandback.
                 }
                 if (turnsDb != null) {
                   try {
@@ -15088,36 +15096,36 @@ void (async () => {
                     if (row != null) isBackground = row.background === 1
                   } catch { /* best-effort */ }
                 }
-                if (!isBackground) return
-
-                // chatId fallback: if the progress-driver fleet entry was
-                // already cleaned up by the time onFinish fires, route to
-                // the owner chat. Every switchroom fleet agent is
-                // DM-shaped, so allowFrom[0] is the conversation that
-                // dispatched the work.
-                const handbackChatId = chatId || (loadAccess().allowFrom[0] ?? '')
-                if (!handbackChatId) {
-                  process.stderr.write(
-                    `telegram gateway: subagent-handback ${agentId} — no chat to deliver to; skipped\n`,
-                  )
+
+                const decision = decideSubagentHandback({
+                  handbackEnvValue: process.env.SWITCHROOM_SUBAGENT_HANDBACK,
+                  outcome,
+                  isBackground,
+                  fleetChatId,
+                  // Owner-chat fallback: if the progress-driver fleet
+                  // entry was already cleaned up, route to the owner
+                  // chat. Every switchroom fleet agent is DM-shaped, so
+                  // allowFrom[0] is the conversation that dispatched.
+                  ownerChatId: loadAccess().allowFrom[0] ?? '',
+                  taskDescription: description,
+                  resultText,
+                })
+                if (!decision.deliver) {
+                  if (decision.reason === 'no-chat') {
+                    process.stderr.write(
+                      `telegram gateway: subagent-handback ${agentId} — no chat to deliver to; skipped\n`,
+                    )
+                  }
                   return
                 }
 
-                const inbound = buildSubagentHandbackInbound({
-                  ctx: {
-                    chatId: String(handbackChatId),
-                    taskDescription: description,
-                    resultText,
-                    outcome,
-                  },
-                })
                 // Deliver via pendingInboundBuffer + the idle-drain tick.
                 // The drain only releases at an idle prompt (no active
                 // turn), so the handback always lands as a clean fresh
                 // turn and never races a turn-in-flight composer (#1556).
-                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? '', inbound)
+                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? '', decision.inbound)
                 process.stderr.write(
-                  `telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${handbackChatId} resultChars=${resultText.length}\n`,
+                  `telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${decision.chatId} resultChars=${resultText.length}\n`,
                 )
               },
             })

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -101,3 +101,85 @@ export function buildSubagentHandbackInbound(opts: {
     },
   }
 }
+
+// ───────────────────────────────────────────────────────────────────────────
+// Handback decision (pure — unit-testable gate for the gateway onFinish path)
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Inputs to the handback decision. The gateway's `subagent-watcher`
+ * `onFinish` callback does the IO — resolves `isBackground` from the
+ * registry DB, `fleetChatId` from the progress-driver fleet, and
+ * `ownerChatId` from access.json — then hands the resolved values here.
+ * Keeping the *decision* pure makes the gate (which injects turns)
+ * testable without standing up a gateway.
+ */
+export interface SubagentHandbackDecisionInput {
+  /** `SWITCHROOM_SUBAGENT_HANDBACK` env var value (any non-'0' = enabled). */
+  handbackEnvValue: string | undefined
+  /** Terminal outcome the watcher reported. */
+  outcome: 'completed' | 'failed' | 'orphan'
+  /** Whether the sub-agent was a background dispatch (registry DB flag).
+   *  Foreground sub-agents hand back natively in the parent's turn. */
+  isBackground: boolean
+  /** Chat id from the progress-driver fleet entry; '' if not found. */
+  fleetChatId: string
+  /** Owner chat fallback (access.json allowFrom[0]); '' if none. */
+  ownerChatId: string
+  taskDescription: string
+  resultText: string
+  /** Deterministic clock for tests. */
+  nowMs?: number
+}
+
+/** Why a handback was NOT delivered — one of these, or `delivered`. */
+export type SubagentHandbackSkipReason =
+  | 'env-disabled'
+  | 'outcome-not-terminal'
+  | 'foreground'
+  | 'no-chat'
+
+export type SubagentHandbackDecision =
+  | { deliver: false; reason: SubagentHandbackSkipReason }
+  | { deliver: true; chatId: string; inbound: InboundMessage }
+
+/**
+ * Decide whether a finished sub-agent warrants a handback turn, and if
+ * so build the inbound. Pure: all IO is the caller's job.
+ *
+ * Gates, in order:
+ *   1. kill-switch — `SWITCHROOM_SUBAGENT_HANDBACK=0` disables entirely.
+ *   2. outcome — only `completed`/`failed` hand back; `orphan` is a
+ *      stale historical-at-boot row, not a fresh completion.
+ *   3. foreground — a foreground sub-agent already handed its result
+ *      back as the Task tool result in the parent's own turn.
+ *   4. no-chat — neither the fleet entry nor the owner chat resolved,
+ *      so there is nowhere to deliver.
+ */
+export function decideSubagentHandback(
+  input: SubagentHandbackDecisionInput,
+): SubagentHandbackDecision {
+  if (input.handbackEnvValue === '0') {
+    return { deliver: false, reason: 'env-disabled' }
+  }
+  if (input.outcome !== 'completed' && input.outcome !== 'failed') {
+    return { deliver: false, reason: 'outcome-not-terminal' }
+  }
+  if (!input.isBackground) {
+    return { deliver: false, reason: 'foreground' }
+  }
+  const chatId = input.fleetChatId || input.ownerChatId
+  if (!chatId) {
+    return { deliver: false, reason: 'no-chat' }
+  }
+  const inbound = buildSubagentHandbackInbound({
+    ctx: {
+      chatId,
+      taskDescription: input.taskDescription,
+      resultText: input.resultText,
+      outcome: input.outcome,
+    },
+    ...(input.nowMs !== undefined ? { nowMs: input.nowMs } : {}),
+  })
+  return { deliver: true, chatId, inbound }
+}

package/telegram-plugin/model-unavailable.ts

@@ -326,7 +326,17 @@ export function resolveModelUnavailableFromOperatorEvent(
     return detectModelUnavailable(detail) ?? { kind: 'quota_exhausted', raw: detail }
   }
   if (ev.kind === 'rate-limited') {
-    return detectModelUnavailable(detail) ?? { kind: 'overload', raw: detail }
+    // A rate-limited / transient overload is NOT "model unavailable" —
+    // it is retryable and Claude Code retries it internally. Escalate
+    // to the model-unavailable card ONLY if the detail carries a
+    // genuine quota signal (a 4xx that slipped past the classifier
+    // with usage-limit wording in its body). A bare overload /
+    // rate-limit returns null → the caller renders the calm
+    // `rate-limited` card, never the scary "⚠️ Model unavailable" one.
+    // Returning `{kind:'overload'}` here is what fired a false
+    // model-unavailable card on every transient 529.
+    const detected = detectModelUnavailable(detail)
+    return detected?.kind === 'quota_exhausted' ? detected : null
   }
   if (ev.kind === 'unknown-5xx') {
     return detectModelUnavailable(detail) ?? { kind: 'overload', raw: detail }

package/telegram-plugin/operator-events.fixtures.json

@@ -1,6 +1,5 @@
 {
   "_comment": "Captured error shapes per OperatorEventKind. Real API keys/IDs have been scrubbed.",
-
   "credentials-expired": [
     {
       "_source": "Anthropic API — 401 with authentication_error + expired hint",
@@ -16,7 +15,6 @@
       "message": "OAuth token expired, please re-authenticate to continue"
     }
   ],
-
   "credentials-invalid": [
     {
       "_source": "Anthropic API — 401 with invalid_api_key",
@@ -40,7 +38,6 @@
       "message": "Invalid API key"
     }
   ],
-
   "credit-exhausted": [
     {
       "_source": "Anthropic API — 402 credit_balance_too_low",
@@ -56,23 +53,7 @@
       "message": "credit balance insufficient"
     }
   ],
-
-  "quota-exhausted": [
-    {
-      "_source": "Anthropic API — 529 overloaded_error (Claude Code converts to quota-exhausted)",
-      "status": 529,
-      "error": {
-        "type": "overloaded_error",
-        "message": "Overloaded"
-      }
-    },
-    {
-      "_source": "Synthetic — set by session-tail after repeated 429 + slot exhaustion",
-      "type": "overloaded_error",
-      "message": "Service overloaded, usage limits reached"
-    }
-  ],
-
+  "quota-exhausted": [],
   "rate-limited": [
     {
       "_source": "Anthropic API — 429 rate_limit_error",
@@ -86,9 +67,21 @@
       "_source": "Top-level rate_limit_error",
       "type": "rate_limit_error",
       "message": "rate limit exceeded"
+    },
+    {
+      "_source": "Anthropic API — 529 overloaded_error (transient server capacity → rate-limited, NOT quota)",
+      "status": 529,
+      "error": {
+        "type": "overloaded_error",
+        "message": "Overloaded"
+      }
+    },
+    {
+      "_source": "Synthetic — overloaded_error from session-tail (transient → rate-limited, NOT quota)",
+      "type": "overloaded_error",
+      "message": "Service overloaded, usage limits reached"
     }
   ],
-
   "agent-crashed": [
     {
       "_source": "Synthetic — emitted by IPC bridge when Claude child exits nonzero",
@@ -101,7 +94,6 @@
       "message": "IPC socket disconnected unexpectedly"
     }
   ],
-
   "agent-restarted-unexpectedly": [
     {
       "_source": "Synthetic — emitted by gateway boot-banner diff when uptime drops unexpectedly",
@@ -114,7 +106,6 @@
       "message": "systemd unit restarted outside of operator request"
     }
   ],
-
   "unknown-4xx": [
     {
       "_source": "Novel 4xx not matching any known Anthropic error type",
@@ -142,7 +133,6 @@
       "_value": "something went wrong"
     }
   ],
-
   "unknown-5xx": [
     {
       "_source": "500 with no recognised type",

package/telegram-plugin/operator-events.ts

@@ -139,8 +139,17 @@ function classifyInner(raw: unknown): OperatorEventKind {
     message.toLowerCase().includes('overloaded_error') ||
     message.toLowerCase().includes('overloaded')
   ) {
-    // Anthropic overloaded = quota exhausted / service rate-limiting
-    return 'quota-exhausted'
+    // Anthropic "overloaded" (HTTP 529) is transient SERVER-side
+    // capacity pressure — orthogonal to account quota. It is retryable
+    // (`x-should-retry: true`) and Claude Code retries it internally.
+    // Classifying it `quota-exhausted` fired a false "Model
+    // unavailable — quota exhausted" card AND a self-cancelling fleet
+    // auto-fallback on every 529 (the active account always probes
+    // healthy — nothing is actually exhausted — so the fallback no-ops
+    // with "probed healthy / Stale event?"). It is a rate-limit-family
+    // transient; failing over to another account does nothing because
+    // every account is equally affected.
+    return 'rate-limited'
   }
 
   // Synthetic kinds (non-Anthropic — set by session-tail or IPC bridge)

package/telegram-plugin/session-tail.ts

@@ -409,9 +409,37 @@ export function projectSubagentLine(
  * Returns null when no actionable error is detected (routine lines).
  * Never throws — delegates to classifyClaudeError's own safety guarantee.
  */
+/**
+ * Extract Claude Code's retry-state annotations from a transcript line.
+ * Claude Code writes top-level `retryAttempt` / `maxRetries` on a
+ * retried API error (e.g. a 529 it is internally retrying). Used to
+ * tell an in-flight retry from an exhausted (terminal) one. Both
+ * optional — non-retried errors and older Claude Code versions omit
+ * them.
+ */
+function extractRetryState(obj: Record<string, unknown>): {
+  retryAttempt: number | null
+  maxRetries: number | null
+} {
+  return {
+    retryAttempt: typeof obj.retryAttempt === 'number' ? obj.retryAttempt : null,
+    maxRetries: typeof obj.maxRetries === 'number' ? obj.maxRetries : null,
+  }
+}
+
 export function detectErrorInTranscriptLine(
   line: string,
-): { kind: OperatorEventKind; raw: unknown; detail: string } | null {
+): {
+  kind: OperatorEventKind
+  raw: unknown
+  detail: string
+  /** True for the rate-limit / transient-overload family. */
+  transient: boolean
+  /** True when the error is final — NOT an in-flight retry. A transient
+   *  error mid-retry is `transient:true, terminal:false`; the caller
+   *  suppresses it (no operator card until the failure is terminal). */
+  terminal: boolean
+} | null {
   if (!line || line.length > 2 * 1024 * 1024) return null
   let obj: Record<string, unknown>
   try {
@@ -447,7 +475,16 @@ export function detectErrorInTranscriptLine(
       status === 429
         ? 'quota-exhausted'
         : classifyClaudeError({ type: errStr, status, message: text })
-    return { kind, raw: obj, detail: text || errStr || 'api error' }
+    // An `isApiErrorMessage` line is Claude surfacing the failure to the
+    // user — terminal by construction (Claude writes this shape only
+    // after its own internal retries are exhausted).
+    return {
+      kind,
+      raw: obj,
+      detail: text || errStr || 'api error',
+      transient: kind === 'rate-limited',
+      terminal: true,
+    }
   }
 
   // Explicit error line types from Claude Code JSONL
@@ -472,7 +509,23 @@ export function detectErrorInTranscriptLine(
     extractDetailMessage(obj) ??
     String(type ?? '')
 
-  return { kind, raw, detail }
+  // Transient = the rate-limit / overload family. For a transient,
+  // decide `terminal` from Claude Code's retry annotations: below the
+  // cap → still retrying (in-flight); at/above → exhausted. With no
+  // retry state, an explicit `type:"api_error"`/`"error"` LINE means
+  // Claude surfaced the failure (terminal); an embedded-error object
+  // with no retry state is ambiguous → treat as in-flight and suppress
+  // (the silence-poke covers a genuinely stuck turn; a false card is
+  // the bug we are fixing, a missed ambiguous card costs nothing).
+  const transient = kind === 'rate-limited'
+  const retry = extractRetryState(obj)
+  const terminal = !transient
+    ? true
+    : retry.retryAttempt != null && retry.maxRetries != null
+      ? retry.retryAttempt >= retry.maxRetries
+      : isErrorLine
+
+  return { kind, raw, detail, transient, terminal }
 }
 
 function extractDetailMessage(obj: Record<string, unknown> | null): string | null {
@@ -514,6 +567,10 @@ export interface TailOperatorEvent {
   kind: OperatorEventKind
   detail: string
   raw: unknown
+  /** True for the rate-limit / transient-overload family. */
+  transient: boolean
+  /** True when the failure is final, not an in-flight retry. */
+  terminal: boolean
 }
 
 export interface SessionTailConfig {
@@ -665,7 +722,17 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
           try {
             const errEvent = detectErrorInTranscriptLine(line)
             if (errEvent) {
-              onOperatorEvent(errEvent)
+              // Honest escalation: a transient overload Claude is still
+              // retrying (transient && !terminal) posts NO operator
+              // card — it almost always resolves on the next retry.
+              // Escalate only terminal failures + non-transient errors.
+              if (errEvent.terminal || !errEvent.transient) {
+                onOperatorEvent(errEvent)
+              } else {
+                log?.(
+                  `session-tail: transient overload suppressed (in-flight retry) kind=${errEvent.kind}`,
+                )
+              }
             }
           } catch (err) {
             log?.(`session-tail: onOperatorEvent threw: ${(err as Error).message}`)

package/telegram-plugin/tests/model-unavailable.test.ts

@@ -247,9 +247,22 @@ describe('resolveModelUnavailableFromOperatorEvent — kind-driven mapping', ()
     expect(d?.kind).toBe('quota_exhausted')
   })
 
-  it('always treats kind=rate-limited as overload', () => {
+  it('treats a bare kind=rate-limited as NOT model-unavailable (transient → calm card)', () => {
+    // A transient overload / rate-limit is retryable — Claude Code
+    // retries it internally. resolveModelUnavailableFromOperatorEvent
+    // returns null so the gateway renders the calm `rate-limited` card,
+    // never the scary "⚠️ Model unavailable" one. Returning
+    // `{kind:'overload'}` here is what fired a false card on every 529.
     const d = resolveModelUnavailableFromOperatorEvent({ kind: 'rate-limited', detail: '' })
-    expect(d?.kind).toBe('overload')
+    expect(d).toBeNull()
+  })
+
+  it('escalates a kind=rate-limited that carries a genuine quota signal', () => {
+    const d = resolveModelUnavailableFromOperatorEvent({
+      kind: 'rate-limited',
+      detail: "You've hit your limit · resets 8:50am",
+    })
+    expect(d?.kind).toBe('quota_exhausted')
   })
 
   it('always treats kind=unknown-5xx as overload', () => {

package/telegram-plugin/tests/operator-events-session-tail.test.ts

@@ -56,13 +56,64 @@ describe('detectErrorInTranscriptLine — error detection', () => {
     expect(result!.kind).toBe('credit-exhausted')
   })
 
-  it('classifies overloaded_error as quota-exhausted', () => {
+  it('classifies overloaded_error as rate-limited (transient), NOT quota-exhausted', () => {
+    // A 529 "overloaded" is transient Anthropic server-capacity
+    // pressure — orthogonal to account quota. Classifying it
+    // quota-exhausted fired a false "Model unavailable" card + a
+    // self-cancelling fleet auto-fallback on every 529.
     const line = JSON.stringify({
       type: 'api_error',
       error: { type: 'overloaded_error', message: 'Overloaded' },
     })
     const result = detectErrorInTranscriptLine(line)
-    expect(result!.kind).toBe('quota-exhausted')
+    expect(result!.kind).toBe('rate-limited')
+    expect(result!.transient).toBe(true)
+    // An explicit `type:"api_error"` line (no retry state) = Claude
+    // surfaced the failure → terminal.
+    expect(result!.terminal).toBe(true)
+  })
+
+  it('marks an in-flight 529 retry transient + NOT terminal (suppressed)', () => {
+    // Real on-disk shape: a 529 Claude Code is internally retrying,
+    // annotated with retryAttempt < maxRetries.
+    const line = JSON.stringify({
+      type: 'system',
+      subtype: 'api_error',
+      error: { status: 529, type: 'overloaded_error', message: 'Overloaded' },
+      retryAttempt: 9,
+      maxRetries: 10,
+      retryInMs: 34479,
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result!.kind).toBe('rate-limited')
+    expect(result!.transient).toBe(true)
+    // 9 < 10 — still retrying → in-flight → the caller suppresses it.
+    expect(result!.terminal).toBe(false)
+  })
+
+  it('marks an exhausted 529 retry terminal (escalates)', () => {
+    const line = JSON.stringify({
+      type: 'system',
+      subtype: 'api_error',
+      error: { status: 529, type: 'overloaded_error', message: 'Overloaded' },
+      retryAttempt: 10,
+      maxRetries: 10,
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result!.kind).toBe('rate-limited')
+    expect(result!.transient).toBe(true)
+    // retries exhausted → terminal → escalates.
+    expect(result!.terminal).toBe(true)
+  })
+
+  it('marks non-transient errors terminal (always escalate)', () => {
+    const line = JSON.stringify({
+      type: 'api_error',
+      error: { type: 'authentication_error', message: 'expired' },
+    })
+    const result = detectErrorInTranscriptLine(line)
+    expect(result!.transient).toBe(false)
+    expect(result!.terminal).toBe(true)
   })
 
   it('returns null for lines without error field', () => {

package/telegram-plugin/tests/operator-events.test.ts

@@ -57,13 +57,20 @@ describe('classifyClaudeError — credit-exhausted fixtures', () => {
   }
 })
 
-describe('classifyClaudeError — quota-exhausted fixtures', () => {
-  for (const fixture of fixtures['quota-exhausted']) {
-    it(`classifies: ${fixture._source}`, () => {
-      const input = '_value' in fixture ? fixture._value : fixture
-      expect(classifyClaudeError(input)).toBe('quota-exhausted')
-    })
-  }
+describe('classifyClaudeError — quota-exhausted', () => {
+  // classifyClaudeError is type/code/status-based and intentionally
+  // does NOT self-classify quota-exhausted: a genuine subscription
+  // usage-limit hit has no reliable Anthropic error TYPE — it is
+  // detected from the response TEXT. session-tail's `isApiErrorMessage`
+  // 429 branch + the `detectModelUnavailable` text path own quota
+  // detection. (`overloaded_error` used to be mapped here — wrongly;
+  // a 529 overload is transient server capacity, now `rate-limited`.)
+  it('no error TYPE maps to quota-exhausted (the text path owns it)', () => {
+    expect(fixtures['quota-exhausted']).toHaveLength(0)
+    expect(
+      classifyClaudeError({ type: 'overloaded_error', message: 'Overloaded' }),
+    ).not.toBe('quota-exhausted')
+  })
 })
 
 describe('classifyClaudeError — rate-limited fixtures', () => {

package/telegram-plugin/tests/subagent-handback-decision.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Regression coverage for `decideSubagentHandback` — the gate the
+ * gateway's subagent-watcher `onFinish` callback runs to decide whether
+ * a finished sub-agent gets a handback turn injected.
+ *
+ * This is the highest-risk surface of the handback feature (#1650): it
+ * injects a fresh turn. Before this suite the decision lived inline in
+ * the gateway's `onFinish` closure with no automated test — a refactor
+ * that broke the `isBackground` gate would have fired handbacks for
+ * foreground sub-agents (double messages) with nothing to catch it.
+ * The decision is now a pure function; these cases pin every gate.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { decideSubagentHandback } from '../gateway/subagent-handback-inbound-builder.js'
+
+const FIXED_NOW = 1_700_000_000_000
+
+const base = {
+  handbackEnvValue: undefined as string | undefined,
+  outcome: 'completed' as 'completed' | 'failed' | 'orphan',
+  isBackground: true,
+  fleetChatId: '777',
+  ownerChatId: '999',
+  taskDescription: 'Do the thing',
+  resultText: 'Done.',
+  nowMs: FIXED_NOW,
+}
+
+describe('decideSubagentHandback', () => {
+  it('delivers for a background completed sub-agent', () => {
+    const d = decideSubagentHandback({ ...base })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('777')
+      expect(d.inbound.meta.source).toBe('subagent_handback')
+      expect(d.inbound.chatId).toBe('777')
+    }
+  })
+
+  it('delivers for a background FAILED sub-agent', () => {
+    const d = decideSubagentHandback({ ...base, outcome: 'failed' })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) expect(d.inbound.meta.outcome).toBe('failed')
+  })
+
+  it('skips a foreground sub-agent (handed back natively in-turn)', () => {
+    const d = decideSubagentHandback({ ...base, isBackground: false })
+    expect(d).toEqual({ deliver: false, reason: 'foreground' })
+  })
+
+  it("skips an 'orphan' outcome (stale historical-at-boot row)", () => {
+    const d = decideSubagentHandback({ ...base, outcome: 'orphan' })
+    expect(d).toEqual({ deliver: false, reason: 'outcome-not-terminal' })
+  })
+
+  it('skips when the kill-switch is set (SWITCHROOM_SUBAGENT_HANDBACK=0)', () => {
+    const d = decideSubagentHandback({ ...base, handbackEnvValue: '0' })
+    expect(d).toEqual({ deliver: false, reason: 'env-disabled' })
+  })
+
+  it('treats any non-"0" env value (incl. undefined) as enabled', () => {
+    expect(decideSubagentHandback({ ...base, handbackEnvValue: undefined }).deliver).toBe(true)
+    expect(decideSubagentHandback({ ...base, handbackEnvValue: '1' }).deliver).toBe(true)
+    expect(decideSubagentHandback({ ...base, handbackEnvValue: '' }).deliver).toBe(true)
+  })
+
+  it('falls back to the owner chat when the fleet entry is gone', () => {
+    const d = decideSubagentHandback({ ...base, fleetChatId: '' })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('999')
+      expect(d.inbound.chatId).toBe('999')
+    }
+  })
+
+  it('prefers the fleet chat id over the owner chat when both are present', () => {
+    const d = decideSubagentHandback({ ...base, fleetChatId: '777', ownerChatId: '999' })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) expect(d.chatId).toBe('777')
+  })
+
+  it('skips when no chat resolves at all', () => {
+    const d = decideSubagentHandback({ ...base, fleetChatId: '', ownerChatId: '' })
+    expect(d).toEqual({ deliver: false, reason: 'no-chat' })
+  })
+
+  it('gate order: kill-switch wins over every other condition', () => {
+    // env-disabled even though it is a deliverable background completion.
+    const d = decideSubagentHandback({ ...base, handbackEnvValue: '0', isBackground: true })
+    expect(d).toEqual({ deliver: false, reason: 'env-disabled' })
+  })
+
+  it('gate order: outcome filter applies before the foreground check', () => {
+    // orphan + foreground — outcome filter is checked first.
+    const d = decideSubagentHandback({ ...base, outcome: 'orphan', isBackground: false })
+    expect(d).toEqual({ deliver: false, reason: 'outcome-not-terminal' })
+  })
+
+  it('carries the task description and result text into the inbound', () => {
+    const d = decideSubagentHandback({
+      ...base,
+      taskDescription: 'Migrate the DB',
+      resultText: 'Applied 3 migrations, 0 rows dropped.',
+    })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.inbound.text).toContain('Migrate the DB')
+      expect(d.inbound.text).toContain('Applied 3 migrations')
+    }
+  })
+})