switchroom 0.13.10 → 0.13.12

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.12";
+var COMMIT_SHA = "18363dfb";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.10",
+  "version": "0.13.12",
   "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 };
@@ -40592,28 +40593,12 @@ function isSilentFlushMarker2(text) {
   }
   return SILENT_MARKERS2.has(trimmed.toUpperCase());
 }
-var REPLY_CALLED_TAIL_MIN_CHARS = 40;
 function decideTurnFlush(input) {
   const flushEnabled = input.flushEnabled !== false;
   if (!flushEnabled)
     return { kind: "skip", reason: "flag-disabled" };
-  if (input.replyCalled) {
-    const tailIdx = input.capturedTextLenAtLastReply ?? input.capturedText.length;
-    const tail = input.capturedText.slice(tailIdx).join(`
-`).trim();
-    const minChars = input.replyCalledTailMinChars ?? REPLY_CALLED_TAIL_MIN_CHARS;
-    if (tail.length === 0) {
-      return { kind: "skip", reason: "reply-called" };
-    }
-    if (tail.length < minChars) {
-      return { kind: "skip", reason: "reply-called-no-new-text" };
-    }
-    if (input.chatId == null)
-      return { kind: "skip", reason: "no-inbound-chat" };
-    if (isSilentFlushMarker2(tail))
-      return { kind: "skip", reason: "silent-marker" };
-    return { kind: "flush", text: tail };
-  }
+  if (input.replyCalled)
+    return { kind: "skip", reason: "reply-called" };
   if (input.chatId == null)
     return { kind: "skip", reason: "no-inbound-chat" };
   const joined = input.capturedText.join(`
@@ -44782,6 +44767,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) => {
@@ -46628,14 +46638,6 @@ function startSubagentWatcher(config) {
       return;
     if (entry.state === "done" && !entry.completionNotified) {
       entry.completionNotified = true;
-      const desc = escapeHtml8(truncate3(entry.description, 80));
-      const summary = entry.lastSummaryLine ? ` \u2014 ${escapeHtml8(truncate3(entry.lastSummaryLine, 120))}` : "";
-      const tools = entry.toolCount > 0 ? ` (${entry.toolCount} tools)` : "";
-      try {
-        config.sendNotification(`\u2713 Worker done: ${desc}${tools}${summary}`);
-      } catch (err) {
-        log?.(`subagent-watcher: completion notification error: ${err.message}`);
-      }
       if (config.onFinish) {
         try {
           config.onFinish({
@@ -48001,11 +48003,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.12";
+var COMMIT_SHA = "18363dfb";
+var COMMIT_DATE = "2026-05-22T19:32:19+10:00";
 var LATEST_PR = null;
-var COMMITS_AHEAD_OF_TAG = 6;
+var COMMITS_AHEAD_OF_TAG = 5;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -49628,7 +49630,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}
 `);
@@ -51568,7 +51570,6 @@ function handleSessionEvent(ev) {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           capturedText: [],
-          capturedTextLenAtLastReply: 0,
           orphanedReplyTimeoutId: null,
           registryKey: null,
           lastAssistantMsgId: null,
@@ -51633,7 +51634,6 @@ function handleSessionEvent(ev) {
       const name = ev.toolName;
       if (isTelegramReplyTool(name)) {
         turn.replyCalled = true;
-        turn.capturedTextLenAtLastReply = turn.capturedText.length;
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId);
           turn.orphanedReplyTimeoutId = null;
@@ -51796,13 +51796,8 @@ function handleSessionEvent(ev) {
         chatId: turn.sessionChatId,
         replyCalled: turn.replyCalled,
         capturedText: turn.capturedText,
-        capturedTextLenAtLastReply: turn.capturedTextLenAtLastReply,
         flushEnabled: TURN_FLUSH_SAFETY_ENABLED
       });
-      if (flushDecision.kind === "flush" && turn.replyCalled) {
-        process.stderr.write(`telegram gateway: WARN post-reply-tail flush (#1291) \u2014 model emitted ${flushDecision.text.length} chars after a prior reply call without a follow-up reply tool chat=${chatId} turnStartedAt=${turn.startedAt}
-`);
-      }
       if (flushDecision.kind === "skip" && flushDecision.reason !== "reply-called") {
         process.stderr.write(`telegram gateway: turn-flush skipped \u2014 reason=${flushDecision.reason}
 `);
@@ -57282,20 +57277,6 @@ var didOneTimeSetup = false;
               agentCwd: watcherAgentDir,
               db: turnsDb,
               parentStateDir: STATE_DIR,
-              sendNotification: (text) => {
-                const ownerChatId = loadAccess().allowFrom[0];
-                if (!ownerChatId)
-                  return;
-                swallowingApiCall(() => lockedBot.api.sendMessage(ownerChatId, text, {
-                  parse_mode: "HTML",
-                  link_preview_options: { is_disabled: true },
-                  ...TOPIC_ID != null ? { message_thread_id: TOPIC_ID } : {}
-                }), {
-                  chat_id: ownerChatId,
-                  verb: "subagent-watcher-notification",
-                  ...TOPIC_ID != null ? { threadId: TOPIC_ID } : {}
-                });
-              },
               log: (msg) => process.stderr.write(`telegram gateway: ${msg}
 `),
               onStall: (agentId, idleMs, description) => {
@@ -57321,17 +57302,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 +57320,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,
@@ -1192,14 +1192,6 @@ type CurrentTurn = {
   gatewayReceiveAt: number
   replyCalled: boolean
   capturedText: string[]
-  // #1291: snapshot of capturedText.length at the moment of the most
-  // recent reply / stream_reply tool call. Used by decideTurnFlush to
-  // isolate the post-reply tail (e.g. a soft-commit reply followed by
-  // the real substantive answer in terminal text only) and flush it as
-  // a follow-up message. Pre-#1291 the existence of ANY reply call
-  // suppressed flush entirely — that lost long terminal-only answers
-  // after a "let me check" interim reply.
-  capturedTextLenAtLastReply: number
   orphanedReplyTimeoutId: ReturnType<typeof setTimeout> | null
   registryKey: string | null
   // Last assistant outbound message id for the current turn — populated
@@ -2712,8 +2704,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`,
@@ -5700,7 +5698,6 @@ function handleSessionEvent(ev: SessionEvent): void {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           capturedText: [],
-          capturedTextLenAtLastReply: 0,
           orphanedReplyTimeoutId: null,
           registryKey: null,
           lastAssistantMsgId: null,
@@ -5801,12 +5798,6 @@ function handleSessionEvent(ev: SessionEvent): void {
       // placeholder-heartbeat label, which has been retired.
       if (isTelegramReplyTool(name)) {
         turn.replyCalled = true
-        // #1291: pin the captured-text index at the moment of this reply
-        // tool call. Anything pushed into capturedText after this point
-        // is the post-reply tail (e.g. the substantive answer composed
-        // in terminal text after a soft-commit "on it, back in a few").
-        // decideTurnFlush slices from this index to flush the tail.
-        turn.capturedTextLenAtLastReply = turn.capturedText.length
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId)
           turn.orphanedReplyTimeoutId = null
@@ -6066,20 +6057,8 @@ function handleSessionEvent(ev: SessionEvent): void {
         chatId: turn.sessionChatId,
         replyCalled: turn.replyCalled,
         capturedText: turn.capturedText,
-        capturedTextLenAtLastReply: turn.capturedTextLenAtLastReply,
         flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
       })
-      // #1291: when the model emitted a soft-commit reply followed by a
-      // substantive terminal-only answer, decideTurnFlush returns
-      // kind:'flush' with the post-reply tail. Log WARN so this case is
-      // auditable — the model SHOULD have called reply for the tail, but
-      // didn't, and the framework is covering for it.
-      if (flushDecision.kind === 'flush' && turn.replyCalled) {
-        process.stderr.write(
-          `telegram gateway: WARN post-reply-tail flush (#1291) — model emitted ${flushDecision.text.length} chars after a prior reply call without a follow-up reply tool` +
-          ` chat=${chatId} turnStartedAt=${turn.startedAt}\n`,
-        )
-      }
       if (flushDecision.kind === 'skip' && flushDecision.reason !== 'reply-called') {
         process.stderr.write(
           `telegram gateway: turn-flush skipped — reason=${flushDecision.reason}\n`,
@@ -14977,26 +14956,11 @@ void (async () => {
               // inside the sub-agent. Belt-and-braces with PR #557's
               // multi-signal progress gate.
               parentStateDir: STATE_DIR,
-              sendNotification: (text: string) => {
-                const ownerChatId = loadAccess().allowFrom[0]
-                if (!ownerChatId) return
-                // #1075: thread-id-bearing — route through swallowingApiCall
-                // so a deleted TOPIC_ID forum thread doesn't crash the
-                // gateway. Notifications are best-effort.
-                void swallowingApiCall(
-                  () =>
-                    lockedBot.api.sendMessage(ownerChatId, text, {
-                      parse_mode: 'HTML',
-                      link_preview_options: { is_disabled: true },
-                      ...(TOPIC_ID != null ? { message_thread_id: TOPIC_ID } : {}),
-                    }),
-                  {
-                    chat_id: ownerChatId,
-                    verb: 'subagent-watcher-notification',
-                    ...(TOPIC_ID != null ? { threadId: TOPIC_ID } : {}),
-                  },
-                )
-              },
+              // No user-facing notification callback: the card-era
+              // "✓ Worker done" message was retired with the progress
+              // card (#1122). Sub-agent completion reaches the user as
+              // the model's own beat-4 handback reply; the watcher's
+              // role here is registry liveness + the `onFinish` cue.
               log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
               // Option C (#393): route stall detections into the progress-card
               // driver so the pinned card re-renders with a ⚠️ indicator even
@@ -15063,22 +15027,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 +15054,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 }
+}