switchroom 0.13.26 → 0.13.27

package/dist/cli/switchroom.js

@@ -47436,8 +47436,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.26";
-var COMMIT_SHA = "b2767bb7";
+var VERSION = "0.13.27";
+var COMMIT_SHA = "a158e029";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.26",
+  "version": "0.13.27",
   "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/active-reactions-sweep.ts

@@ -16,7 +16,7 @@
  *      any still-active reactions to 👍 before it gets SIGTERM'd.
  *
  * Both consumers call `sweepActiveReactions`, which is shaped as a
- * pure function that takes the setDone callback as an argument. That
+ * pure function that takes the finalize callback as an argument. That
  * keeps it testable in isolation — the tests pass a fake callback and
  * assert which reactions were visited and whether the sidecar was
  * cleared.
@@ -24,7 +24,7 @@
 
 import { readActiveReactions, clearActiveReactions, type ActiveReaction } from "./active-reactions.js";
 
-export type SetDoneReactionFn = (chatId: string, messageId: number) => Promise<unknown>;
+export type FinalizeReactionFn = (chatId: string, messageId: number) => Promise<unknown>;
 
 export interface SweepOptions {
   timeoutMs?: number;
@@ -45,7 +45,7 @@ export interface SweepResult {
  */
 export async function sweepActiveReactions(
   agentDir: string,
-  setDone: SetDoneReactionFn,
+  finalize: FinalizeReactionFn,
   options: SweepOptions = {},
 ): Promise<SweepResult> {
   const log = options.log ?? (() => {});
@@ -56,7 +56,7 @@ export async function sweepActiveReactions(
   log(`sweeping ${reactions.length} stale reaction(s)`);
   const attempts = reactions.map((r) =>
     Promise.resolve()
-      .then(() => setDone(r.chatId, r.messageId))
+      .then(() => finalize(r.chatId, r.messageId))
       .catch((err: unknown) => {
         const msg = err instanceof Error ? err.message : String(err);
         log(`reaction sweep failed for ${r.chatId}/${r.messageId}: ${msg}`);

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

@@ -27230,7 +27230,7 @@ var init_secretlint_source = __esm(() => {
 function escapeHtml8(s) {
   return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
 }
-function truncate3(s, n) {
+function truncate4(s, n) {
   return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
 }
 
@@ -30763,7 +30763,6 @@ var REACTION_VARIANTS = {
   web: ["\u26a1", "\uD83E\uDD14", "\uD83D\uDC4C"],
   compacting: ["\u270d", "\uD83E\uDD14", "\uD83D\uDC40"],
   done: ["\uD83D\uDC4D", "\uD83D\uDCAF", "\uD83C\uDF89"],
-  silent: ["\uD83D\uDE4A", "\uD83E\uDD14", "\uD83D\uDE10"],
   error: ["\uD83D\uDE31", "\uD83D\uDE28", "\uD83E\uDD2F"],
   stallSoft: ["\uD83E\uDD71", "\uD83D\uDE34", "\uD83E\uDD14"],
   stallHard: ["\uD83D\uDE28", "\uD83E\uDD2F", "\uD83D\uDE31"]
@@ -30796,7 +30795,7 @@ class StatusReactionController {
   constructor(emit, allowedReactions = null, config = {}) {
     this.emit = emit;
     this.allowedReactions = allowedReactions;
-    this.debounceMs = config.debounceMs ?? 700;
+    this.debounceMs = config.debounceMs ?? 3500;
     this.stallSoftMs = config.stallSoftMs ?? 30000;
     this.stallHardMs = config.stallHardMs ?? 90000;
     this.log = config.log;
@@ -30814,14 +30813,15 @@ class StatusReactionController {
   setCompacting() {
     this.scheduleState("compacting");
   }
-  setDone() {
-    this.finishWithState("done");
+  setError() {
+    this.scheduleState("error");
   }
-  setSilent() {
-    this.finishWithState("silent");
+  finalize(reason = "done") {
+    const state = reason === "error" ? "error" : "done";
+    this.finishWithState(state);
   }
-  setError() {
-    this.finishWithState("error");
+  setDone() {
+    this.finalize("done");
   }
   cancel() {
     if (this.finished)
@@ -32025,15 +32025,6 @@ async function handleStreamReply(args, state, deps) {
     await stream.finalize();
     state.activeDraftStreams.delete(sKey);
     state.activeDraftParseModes?.delete(sKey);
-    const isDefaultLaneForCompletion = args.lane == null || args.lane.length === 0;
-    if (isDefaultLaneForCompletion && stream.getMessageId() != null) {
-      try {
-        deps.endStatusReaction(chat_id, threadId, "done");
-      } catch (err) {
-        deps.writeError(`telegram channel: stream_reply: endStatusReaction hook threw: ${err}
-`);
-      }
-    }
     if (stream.getMessageId() == null) {
       throw new Error(`stream_reply finalized without sending any message (length=${rawText.length}, ` + `max=4096). Telegram's per-message limit is 4096 chars and stream_reply does not ` + `auto-chunk. Split the text or use \`reply\` (which chunks).`);
     }
@@ -41139,14 +41130,14 @@ function clearActiveReactions2(agentDir) {
 }
 
 // active-reactions-sweep.ts
-async function sweepActiveReactions(agentDir, setDone, options = {}) {
+async function sweepActiveReactions(agentDir, finalize, options = {}) {
   const log = options.log ?? (() => {});
   const timeoutMs = options.timeoutMs ?? 2000;
   const reactions = readActiveReactions2(agentDir);
   if (reactions.length === 0)
     return { swept: [], timedOut: false };
   log(`sweeping ${reactions.length} stale reaction(s)`);
-  const attempts = reactions.map((r) => Promise.resolve().then(() => setDone(r.chatId, r.messageId)).catch((err) => {
+  const attempts = reactions.map((r) => Promise.resolve().then(() => finalize(r.chatId, r.messageId)).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     log(`reaction sweep failed for ${r.chatId}/${r.messageId}: ${msg}`);
   }));
@@ -41181,7 +41172,7 @@ function flushOnAgentDisconnect(deps) {
     return false;
   }
   for (const [key, ctrl] of activeStatusReactions.entries()) {
-    ctrl.setDone();
+    ctrl.finalize("done");
     activeStatusReactions.delete(key);
     activeReactionMsgIds.delete(key);
     activeTurnStartedAt.delete(key);
@@ -41193,7 +41184,7 @@ function flushOnAgentDisconnect(deps) {
       activeTurnStartedAt.delete(k);
       activeReactionMsgIds.delete(k);
     }
-    log(`telegram gateway: disconnect-flush swept ${danglingKeys.length} dangling turn key(s) ` + `post-bridge-death (controller loop missed \u2014 setDone raced disconnect)`);
+    log(`telegram gateway: disconnect-flush swept ${danglingKeys.length} dangling turn key(s) ` + `post-bridge-death (controller loop missed \u2014 finalize raced disconnect)`);
     onDanglingTurnsSwept?.(danglingKeys);
   }
   disposeProgressDriver();
@@ -44315,6 +44306,12 @@ function createPendingInboundBuffer(opts = {}) {
 
 // gateway/inbound-spool.ts
 function spoolId(msg) {
+  if (msg.meta?.source === "subagent_handback" && typeof msg.meta?.subagent_jsonl_id === "string" && msg.meta.subagent_jsonl_id.length > 0) {
+    return `s:handback:${msg.meta.subagent_jsonl_id}`;
+  }
+  if (msg.meta?.source === "subagent_progress" && typeof msg.meta?.subagent_jsonl_id === "string" && msg.meta.subagent_jsonl_id.length > 0 && typeof msg.meta?.bucket_idx === "string" && msg.meta.bucket_idx.length > 0) {
+    return `s:progress:${msg.meta.subagent_jsonl_id}:${msg.meta.bucket_idx}`;
+  }
   if (typeof msg.messageId === "number" && msg.messageId > 0) {
     return `m:${msg.chatId}:${msg.messageId}`;
   }
@@ -44437,7 +44434,31 @@ function createInboundSpool(opts) {
       maybeCompact();
     },
     liveEntries() {
-      return [...live.values()].map((e) => ({ agent: e.agent, msg: e.msg }));
+      const cutoff = now();
+      const out = [];
+      for (const e of live.values()) {
+        const expRaw = e.msg.meta?.expiresAt;
+        if (typeof expRaw === "string" && expRaw.length > 0) {
+          const exp = Number(expRaw);
+          if (Number.isFinite(exp) && exp <= cutoff)
+            continue;
+        }
+        out.push({ agent: e.agent, msg: e.msg });
+      }
+      return out;
+    },
+    dropMatching(predicate) {
+      let n = 0;
+      for (const [id, _e] of [...live.entries()]) {
+        if (!predicate(id))
+          continue;
+        live.delete(id);
+        appendRecord({ t: "ack", id });
+        n++;
+      }
+      if (n > 0)
+        maybeCompact();
+      return n;
     },
     sweepEscalations(onEscalate) {
       const cutoff = now() - escalateAfterMs;
@@ -45082,7 +45103,8 @@ ${result}
     text,
     meta: {
       source: "subagent_handback",
-      outcome: opts.ctx.outcome
+      outcome: opts.ctx.outcome,
+      ...opts.ctx.jsonlAgentId ? { subagent_jsonl_id: opts.ctx.jsonlAgentId } : {}
     }
   };
 }
@@ -45105,13 +45127,110 @@ function decideSubagentHandback(input) {
       chatId,
       taskDescription: input.taskDescription,
       resultText: input.resultText,
-      outcome: input.outcome
+      outcome: input.outcome,
+      ...input.jsonlAgentId ? { jsonlAgentId: input.jsonlAgentId } : {}
     },
     ...input.nowMs !== undefined ? { nowMs: input.nowMs } : {}
   });
   return { deliver: true, chatId, inbound };
 }
 
+// gateway/subagent-progress-inbound-builder.ts
+var PROGRESS_RESULT_MAX = 800;
+var PROGRESS_DESC_MAX = 200;
+var DEFAULT_PROGRESS_INTERVAL_MS = 5 * 60 * 1000;
+function truncate3(s, max) {
+  const t = s.trim();
+  return t.length > max ? t.slice(0, max) + "\u2026" : t;
+}
+function formatElapsed(ms) {
+  const totalMin = Math.floor(ms / 60000);
+  if (totalMin < 60)
+    return `${Math.max(1, totalMin)}m`;
+  const h = Math.floor(totalMin / 60);
+  const m = totalMin % 60;
+  return m === 0 ? `${h}h` : `${h}h${m}m`;
+}
+function buildSubagentProgressInbound(opts) {
+  const ts = opts.nowMs ?? Date.now();
+  const desc = truncate3(opts.ctx.taskDescription, PROGRESS_DESC_MAX) || "(no description)";
+  const summary = truncate3(opts.ctx.latestSummary, PROGRESS_RESULT_MAX);
+  const elapsed = formatElapsed(opts.ctx.elapsedMs);
+  const expiresAt = ts + 2 * opts.ctx.progressIntervalMs;
+  const text = `\uD83D\uDD04 A background worker you dispatched is still running.
+
+` + `Task: ${desc}
+` + `Elapsed: ${elapsed}
+
+` + (summary ? `Latest activity:
+${summary}
+
+` : `(no narrative line yet \u2014 worker has been tool-only)
+
+`) + `This is beat 3 \u2014 mid-flight progress. Surface ONE short line to ` + `the user in your own voice about what the worker is up to. Do ` + `NOT paste this raw, do NOT repeat the elapsed time verbatim, do ` + `NOT promise completion. The handback (beat 4) will come ` + `separately when the worker finishes.`;
+  return {
+    type: "inbound",
+    chatId: opts.ctx.chatId,
+    messageId: ts,
+    user: "subagent-watcher",
+    userId: 0,
+    ts,
+    text,
+    meta: {
+      source: "subagent_progress",
+      subagent_jsonl_id: opts.ctx.subagentJsonlId,
+      bucket_idx: String(opts.ctx.bucketIdx),
+      expiresAt: String(expiresAt),
+      elapsed_ms: String(opts.ctx.elapsedMs)
+    }
+  };
+}
+function isEnvFlagOn(value) {
+  if (value == null)
+    return false;
+  const v = value.trim().toLowerCase();
+  if (v === "")
+    return false;
+  if (v === "0" || v === "false" || v === "no" || v === "off")
+    return false;
+  return true;
+}
+function decideSubagentProgress(input) {
+  if (isEnvFlagOn(input.disableEnvValue)) {
+    return { deliver: false, reason: "env-disabled" };
+  }
+  if (!input.isBackground) {
+    return { deliver: false, reason: "foreground" };
+  }
+  const chatId = input.fleetChatId || input.ownerChatId;
+  if (!chatId) {
+    return { deliver: false, reason: "no-chat" };
+  }
+  if (!input.subagentJsonlId) {
+    return { deliver: false, reason: "missing-jsonl-id" };
+  }
+  const bucketIdx = Math.floor(input.elapsedMs / input.progressIntervalMs);
+  if (bucketIdx < 1) {
+    return { deliver: false, reason: "first-bucket-suppressed" };
+  }
+  if (input.lastBucketIdx != null && bucketIdx <= input.lastBucketIdx) {
+    return { deliver: false, reason: "bucket-already-fired" };
+  }
+  const inbound = buildSubagentProgressInbound({
+    ctx: {
+      chatId,
+      subagentJsonlId: input.subagentJsonlId,
+      taskDescription: input.taskDescription,
+      latestSummary: input.latestSummary,
+      elapsedMs: input.elapsedMs,
+      bucketIdx,
+      progressIntervalMs: input.progressIntervalMs
+    },
+    ...input.nowMs !== undefined ? { nowMs: input.nowMs } : {}
+  });
+  return { deliver: true, chatId, bucketIdx, inbound };
+}
+
 // gateway/poll-health.ts
 var DEFAULT_LOG = (msg) => {
   process.stderr.write(msg.endsWith(`
@@ -46733,7 +46852,7 @@ function backfillJsonlAgentId(db2, jsonlPath, agentId, log) {
   db2.prepare("UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?").run(agentId, candidate.id);
   log?.(`subagent-watcher: backfill linked ${agentId} \u2192 ${candidate.id}`);
 }
-function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, parentStateDir, onUnstall, onFileVanished) {
+function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, parentStateDir, onUnstall, onFileVanished, onProgress) {
   try {
     const stat = fs2.statSync(entry.filePath);
     if (stat.size < tail.cursor) {
@@ -46815,6 +46934,22 @@ function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, paren
           entry.lastSummaryLine = ev.text.split(`
 `)[0].trim().slice(0, 120);
           entry.lastResultText = ev.text.trim().slice(0, SUBAGENT_RESULT_TEXT_MAX);
+          if (onProgress != null && entry.state === "running" && !entry.historical) {
+            try {
+              onProgress({
+                agentId: entry.agentId,
+                description: entry.description,
+                latestSummary: entry.lastResultText,
+                elapsedMs: now - entry.dispatchedAt,
+                prevBucketIdx: entry.lastProgressBucketIdx,
+                setBucketIdx: (b) => {
+                  entry.lastProgressBucketIdx = b;
+                }
+              });
+            } catch (cbErr) {
+              log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${cbErr.message}`);
+            }
+          }
         } else if (ev.kind === "sub_agent_turn_end") {
           if (entry.state === "running") {
             entry.state = "done";
@@ -46913,6 +47048,7 @@ function startSubagentWatcher(config) {
       stallTerminalSynthesised: false,
       lastSummaryLine: "",
       lastResultText: "",
+      lastProgressBucketIdx: null,
       lastTool: null,
       historical: isHistorical
     };
@@ -46933,7 +47069,7 @@ function startSubagentWatcher(config) {
     tails.set(agentId, tail);
     readSubTail(entry, tail, n, (desc) => {
       log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`);
-    }, fs2, log, db2, parentStateDir, config.onUnstall);
+    }, fs2, log, db2, parentStateDir, config.onUnstall, undefined, config.onProgress);
     if (isHistorical && entry.state === "done") {
       entry.completionNotified = true;
       scheduleTerminalCleanup(agentId);
@@ -46950,7 +47086,7 @@ function startSubagentWatcher(config) {
           return;
         readSubTail(entry2, t, nowFn(), (desc) => {
           log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`);
-        }, fs2, log, db2, parentStateDir, config.onUnstall, cleanupTerminalAgent);
+        }, fs2, log, db2, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress);
         maybySendStateTransition(agentId);
       });
     } catch (err) {
@@ -47044,7 +47180,7 @@ function startSubagentWatcher(config) {
       if (idleMs >= threshold) {
         entry.stallNotified = true;
         entry.stalledAt = n;
-        const desc = escapeHtml8(truncate3(entry.description, 80));
+        const desc = escapeHtml8(truncate4(entry.description, 80));
         const idleSec = Math.floor(idleMs / 1000);
         log?.(`subagent-watcher: stall detected for ${entry.agentId} (idle ${idleSec}s): ${desc}`);
         if (db2 != null) {
@@ -47196,7 +47332,7 @@ function startSubagentWatcher(config) {
         continue;
       readSubTail(entry, tail, n, (desc) => {
         log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`);
-      }, fs2, log, db2, parentStateDir, config.onUnstall, cleanupTerminalAgent);
+      }, fs2, log, db2, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress);
       maybySendStateTransition(agentId);
     }
     checkStalls();
@@ -48006,7 +48142,7 @@ function summarizeToolForTitle(toolName, inputPreview) {
     }
     case "Bash": {
       const command = readString(input, "command");
-      return command ? `${toolName}: ${truncate4(command, COMMAND_TITLE_MAX)}` : toolName;
+      return command ? `${toolName}: ${truncate5(command, COMMAND_TITLE_MAX)}` : toolName;
     }
     case "Read":
     case "Edit":
@@ -48014,17 +48150,17 @@ function summarizeToolForTitle(toolName, inputPreview) {
     case "MultiEdit":
     case "NotebookEdit": {
       const filePath = readString(input, "file_path") ?? readString(input, "notebook_path");
-      return filePath ? `${toolName}: ${truncate4(basename5(filePath), PATH_TITLE_MAX)}` : toolName;
+      return filePath ? `${toolName}: ${truncate5(basename5(filePath), PATH_TITLE_MAX)}` : toolName;
     }
     case "Glob":
     case "Grep": {
       const pattern = readString(input, "pattern");
-      return pattern ? `${toolName}: ${truncate4(pattern, COMMAND_TITLE_MAX)}` : toolName;
+      return pattern ? `${toolName}: ${truncate5(pattern, COMMAND_TITLE_MAX)}` : toolName;
     }
     case "WebFetch":
     case "WebSearch": {
       const query2 = readString(input, "url") ?? readString(input, "query");
-      return query2 ? `${toolName}: ${truncate4(query2, COMMAND_TITLE_MAX)}` : toolName;
+      return query2 ? `${toolName}: ${truncate5(query2, COMMAND_TITLE_MAX)}` : toolName;
     }
     default:
       return toolName;
@@ -48057,7 +48193,7 @@ function skillBasenameFromPath(input) {
   const basename6 = lastSlash >= 0 ? trimmed.slice(lastSlash + 1) : trimmed;
   return basename6.length > 0 ? basename6 : null;
 }
-function truncate4(text, max) {
+function truncate5(text, max) {
   const collapsed = text.replace(/\s+/g, " ").trim();
   if (collapsed.length <= max)
     return collapsed;
@@ -48328,10 +48464,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.26";
-var COMMIT_SHA = "b2767bb7";
-var COMMIT_DATE = "2026-05-24T07:35:41Z";
-var LATEST_PR = 1723;
+var VERSION = "0.13.27";
+var COMMIT_SHA = "a158e029";
+var COMMIT_DATE = "2026-05-24T09:47:16Z";
+var LATEST_PR = 1727;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -49362,6 +49498,9 @@ function maybeProactiveCompact() {
       resolveCompactCard("superseded", occupancy);
     }
     postCompactCard(occupancy, cap);
+    for (const ctrl of activeStatusReactions.values()) {
+      ctrl.setCompacting();
+    }
   }
   if (!decision.fire)
     return;
@@ -49435,15 +49574,12 @@ async function resolveCompactCard(kind, occNow) {
 `);
   }
 }
-function endStatusReaction(chatId, threadId, outcome) {
+function finalizeStatusReaction(chatId, threadId, reason = "done") {
   const key = statusKey(chatId, threadId);
   const ctrl = activeStatusReactions.get(key);
   if (!ctrl)
     return;
-  if (outcome === "done")
-    ctrl.setDone();
-  else
-    ctrl.setError();
+  ctrl.finalize(reason);
   purgeReactionTracking(key);
 }
 function resolveThreadId(chat_id, explicit) {
@@ -51188,12 +51324,6 @@ ${url}`;
       progressDriver?.recordOutboundDelivered(chat_id, threadId != null ? String(threadId) : undefined);
     } catch {}
     noteSignal(statusKey(chat_id, threadId), Date.now());
-    try {
-      endStatusReaction(chat_id, threadId, "done");
-    } catch (err) {
-      process.stderr.write(`telegram gateway: reply: endStatusReaction hook threw: ${err}
-`);
-    }
     if (turn != null && isFinalAnswerReply({ text: rawText, disableNotification })) {
       turn.finalAnswerDelivered = true;
     }
@@ -51284,7 +51414,6 @@ async function executeStreamReply(args) {
     disableLinkPreview: access.disableLinkPreview !== false,
     defaultFormat: access.parseMode ?? "html",
     logStreamingEvent,
-    endStatusReaction,
     isPrivateChat: streamIsPrivate,
     isForumTopic: streamIsForumTopic,
     ...sendMessageDraftFn != null ? { sendMessageDraft: sendMessageDraftFn } : {},
@@ -52274,11 +52403,8 @@ function handleSessionEvent(ev) {
           verb: "context-exhaust-warning",
           ...threadId != null ? { threadId } : {}
         });
+        finalizeStatusReaction(chatId, threadId, "error");
         const ceKey = statusKey(chatId, threadId);
-        const ctrl = activeStatusReactions.get(ceKey);
-        if (ctrl)
-          ctrl.setError();
-        purgeReactionTracking(ceKey);
         endTurn(ceKey);
         noteTurnEnd(ceKey);
         if (turn.answerStream != null) {
@@ -52380,9 +52506,7 @@ function handleSessionEvent(ev) {
           }
         }
         unpinProgressCardForChat?.(chatId, threadId);
-        if (ctrl)
-          ctrl.setDone();
-        purgeReactionTracking(statusKey(chatId, threadId));
+        finalizeStatusReaction(chatId, threadId, "done");
         {
           const sKey = streamKey3(chatId, threadId);
           const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0;
@@ -52537,7 +52661,7 @@ function handleSessionEvent(ev) {
             }
             outboundDedup.record(backstopChatId, backstopThreadId, capturedText, Date.now(), currentTurn?.registryKey ?? null);
             if (backstopCtrl)
-              backstopCtrl.setDone();
+              backstopCtrl.finalize("done");
             if (backstopCardTurnKey != null) {
               completeProgressCardTurn?.({
                 chatId: backstopChatId,
@@ -52551,16 +52675,14 @@ function handleSessionEvent(ev) {
             process.stderr.write(`telegram gateway: turn-flush send failed: ${err.message}
 `);
             if (backstopCtrl)
-              backstopCtrl.setError();
+              backstopCtrl.finalize("error");
           } finally {
             purgeReactionTracking(statusKey(backstopChatId, backstopThreadId));
           }
         })();
         return;
       }
-      if (ctrl)
-        ctrl.setDone();
-      purgeReactionTracking(statusKey(chatId, threadId));
+      finalizeStatusReaction(chatId, threadId, "done");
       {
         const sKey = streamKey3(chatId, threadId);
         const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0;
@@ -57918,7 +58040,8 @@ var didOneTimeSetup = false;
                   fleetChatId,
                   ownerChatId: loadAccess().allowFrom[0] ?? "",
                   taskDescription: description,
-                  resultText
+                  resultText,
+                  jsonlAgentId: agentId
                 });
                 if (!decision.deliver) {
                   if (decision.reason === "no-chat") {
@@ -57927,8 +58050,60 @@ var didOneTimeSetup = false;
                   }
                   return;
                 }
+                try {
+                  const progressPrefix = `s:progress:${agentId}:`;
+                  const dropped = inboundSpool?.dropMatching((id) => id.startsWith(progressPrefix)) ?? 0;
+                  if (dropped > 0) {
+                    process.stderr.write(`telegram gateway: subagent-handback ${agentId} swept ${dropped} live progress envelope(s) from spool
+`);
+                  }
+                } catch (err) {
+                  process.stderr.write(`telegram gateway: subagent-handback ${agentId} progress-sweep error: ${err.message}
+`);
+                }
                 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}
+`);
+              },
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx }) => {
+                let fleetChatId = "";
+                let isBackground = false;
+                try {
+                  const fleets = progressDriver?.peekAllFleets() ?? [];
+                  for (const f of fleets) {
+                    if (f.fleet.has(agentId)) {
+                      fleetChatId = f.chatId ?? "";
+                      break;
+                    }
+                  }
+                } catch {}
+                if (turnsDb != null) {
+                  try {
+                    const row = turnsDb.prepare("SELECT background FROM subagents WHERE jsonl_agent_id = ?").get(agentId);
+                    if (row != null)
+                      isBackground = row.background === 1;
+                  } catch {}
+                }
+                if (!isBackground)
+                  return;
+                const decision = decideSubagentProgress({
+                  disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
+                  isBackground,
+                  fleetChatId,
+                  ownerChatId: loadAccess().allowFrom[0] ?? "",
+                  subagentJsonlId: agentId,
+                  taskDescription: description,
+                  latestSummary,
+                  elapsedMs,
+                  progressIntervalMs: DEFAULT_PROGRESS_INTERVAL_MS,
+                  lastBucketIdx: prevBucketIdx
+                });
+                if (!decision.deliver)
+                  return;
+                setBucketIdx(decision.bucketIdx);
+                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? "", decision.inbound);
+                clearPending(statusKey(decision.chatId, undefined), "progress");
+                process.stderr.write(`telegram gateway: subagent-progress queued agent=${agentId} bucket=${decision.bucketIdx} elapsed_ms=${elapsedMs} chat=${decision.chatId}
 `);
               }
             });

package/telegram-plugin/docs/waiting-ux-spec.md

@@ -1,7 +1,23 @@
 # Waiting-for-reply UX — v2 spec (three-class contract)
 
 Tracks: [#545](https://github.com/mekenthompson/switchroom/issues/545),
-[#553](https://github.com/mekenthompson/switchroom/issues/553) (PR series)
+[#553](https://github.com/mekenthompson/switchroom/issues/553) (PR series),
+[#1713](https://github.com/switchroom/switchroom/issues/1713)
+(reflective status-reaction restoration)
+
+> **#1713 note — defect restoration, not feature change.** The Class B
+> contract below ("Ladder progresses through 🤔 / tool-glyphs … **Must
+> NOT collapse straight to 👍**") already documents the correct
+> reflective behaviour. The implementation had regressed: plain `reply`
+> and `stream_reply done=true` were firing the terminal 👍 mid-turn,
+> collapsing the ladder. #1713 restores the documented contract — the
+> **`turn_end` IPC event (Stop hook) is the sole terminal trigger**.
+> Mid-turn replies (ack OR final-answer) are non-events for the
+> reaction. Working states (🤔 / ✍ / 👨‍💻 / ⚡ / 🗜) are bidirectional
+> and may re-enter any number of times within a turn. 🔥 (5xx) is also
+> non-terminal: recovery to a working state is allowed; only
+> `finalize()` ends the controller. Controller debounce is 3500ms by
+> default (#1713 spec: 3-5s) to coalesce rapid state flips.
 
 This document codifies the user-perceived contract for what happens
 between "I sent a Telegram message" and "the agent's reply is locked