switchroom 0.14.41 → 0.14.43

package/telegram-plugin/gateway/gateway.ts

@@ -251,7 +251,7 @@ import { handleInjectCommand } from './inject-handler.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig, findConfigFile as findSwitchroomConfigFile } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
-import { resolveOutboundTopic as resolveOutboundTopicHelper, type TopicRouterConfig as _OutboundRouterConfig } from '../../src/telegram/topic-router.js'
+import { resolveOutboundTopic as resolveOutboundTopicHelper, topicForRecipient, type TopicRouterConfig as _OutboundRouterConfig } from '../../src/telegram/topic-router.js'
 import { readTurnUsages } from '../../src/agents/perf.js'
 import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
 import { nextCompactNotify, idleCompactNotifyState, type CompactNotifyState } from './compact-notify.js'
@@ -2273,14 +2273,20 @@ function postPermissionResumeMessage(opts: {
   const targets: Array<{ chatId: string; threadId: number | undefined }> =
     turn != null
       ? [{ chatId: turn.sessionChatId, threadId: turn.sessionThreadId }]
-      : loadAccess().allowFrom.map(chatId => ({
-          chatId,
-          threadId: resolveAgentOutboundTopic({
+      : (() => {
+          const sg = resolveAgentSupergroupChatId()
+          const topic = resolveAgentOutboundTopic({
             kind: 'permission',
             turnInitiated: false,
             originThreadId: undefined,
-          }),
-        }))
+          })
+          // allowFrom is normally operator DMs — attach the topic only to a
+          // recipient that owns it (the supergroup), never a DM (marko wedge).
+          return loadAccess().allowFrom.map(chatId => ({
+            chatId,
+            threadId: topicForRecipient({ recipientChatId: chatId, resolvedTopic: topic, supergroupChatId: sg }),
+          }))
+        })()
   for (const { chatId, threadId } of targets) {
     // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy); thread-aware send
     void swallowingApiCall(
@@ -4664,16 +4670,20 @@ const ipcServer: IpcServer = createIpcServer({
       turnInitiated: activeTurn != null,
       originThreadId: activeTurn?.sessionThreadId,
     })
+    const permSupergroup = resolveAgentSupergroupChatId()
     for (const chat_id of access.allowFrom) {
       // parse_mode=HTML pairs with formatPermissionCardBody (#1790)
       // so the <b>/<i> tags render as formatting.
-      // PR4b emitter sweep — opts now optionally carries
-      // message_thread_id when supergroup mode is on.
+      // The resolved topic is valid only in the agent's supergroup — attach
+      // it ONLY when this recipient IS that supergroup. allowFrom DMs get the
+      // card thread-less; attaching a topic to a DM yields 400 "message thread
+      // not found" → card never arrives → auto-deny → wedge (marko 2026-06-02).
+      const permThread = topicForRecipient({ recipientChatId: chat_id, resolvedTopic: permTopic, supergroupChatId: permSupergroup })
       // allow-raw-bot-api: permission-request keyboard fan-out; topic-aware opts
       void bot.api.sendMessage(chat_id, text, {
         parse_mode: 'HTML',
         reply_markup: keyboard,
-        ...(permTopic != null ? { message_thread_id: permTopic } : {}),
+        ...(permThread != null ? { message_thread_id: permThread } : {}),
       }).catch(e => {
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}\n`)
       })
@@ -4811,9 +4821,15 @@ const ipcServer: IpcServer = createIpcServer({
         // topic. Drive approval cards follow the originating turn
         // (operator-initiated tool call), admin alias fallback.
         const activeTurn = currentTurn
-        const driveTopic = resolveAgentOutboundTopic({
-          kind: 'hostd-approval',
-          originThreadId: activeTurn?.sessionThreadId,
+        // Attach the topic only when `operator` IS the agent's supergroup —
+        // operator DMs have no topics (marko brevo wedge, 2026-06-02).
+        const driveTopic = topicForRecipient({
+          recipientChatId: operator,
+          resolvedTopic: resolveAgentOutboundTopic({
+            kind: 'hostd-approval',
+            originThreadId: activeTurn?.sessionThreadId,
+          }),
+          supergroupChatId: resolveAgentSupergroupChatId(),
         })
         return {
           chatId: operator,
@@ -4884,9 +4900,14 @@ const ipcServer: IpcServer = createIpcServer({
         // alias fallback for background cases. Same shape as hostd /
         // drive approvals below.
         const activeTurn = currentTurn
-        const ms365Topic = resolveAgentOutboundTopic({
-          kind: 'hostd-approval',
-          originThreadId: activeTurn?.sessionThreadId,
+        // Topic valid only in the agent's supergroup — never on the operator DM.
+        const ms365Topic = topicForRecipient({
+          recipientChatId: operator,
+          resolvedTopic: resolveAgentOutboundTopic({
+            kind: 'hostd-approval',
+            originThreadId: activeTurn?.sessionThreadId,
+          }),
+          supergroupChatId: resolveAgentSupergroupChatId(),
         })
         return {
           chatId: operator,
@@ -4963,9 +4984,14 @@ const ipcServer: IpcServer = createIpcServer({
         // returns undefined for non-supergroup agents → behavior
         // unchanged.
         const activeTurn = currentTurn
-        const cfgTopic = resolveAgentOutboundTopic({
-          kind: 'hostd-approval',
-          originThreadId: activeTurn?.sessionThreadId,
+        // Topic valid only in the agent's supergroup — never on the operator DM.
+        const cfgTopic = topicForRecipient({
+          recipientChatId: operator,
+          resolvedTopic: resolveAgentOutboundTopic({
+            kind: 'hostd-approval',
+            originThreadId: activeTurn?.sessionThreadId,
+          }),
+          supergroupChatId: resolveAgentSupergroupChatId(),
         })
         return {
           chatId: operator,
@@ -5577,7 +5603,21 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
 
   assertAllowedChat(chat_id)
 
-  let threadId = resolveThreadId(chat_id, args.message_thread_id as string | undefined)
+  // Thread resolution precedence: (1) an explicit message_thread_id the
+  // model passed, else (2) THIS turn's own originating topic
+  // (turn-pinned, #1664), else (3) the chat's last-seen topic
+  // (chatThreadMap). Preferring the turn's own thread over the chat
+  // last-seen heuristic fixes synthetic turns (subagent handback/progress,
+  // cron) — whose topic the model is never told and which never write
+  // chatThreadMap — and is strictly more correct under multi-topic
+  // concurrency (a reply lands in the topic the turn came from, not
+  // whichever topic most recently received a message). DM: both are
+  // undefined → unchanged.
+  let threadId = resolveThreadId(
+    chat_id,
+    (args.message_thread_id as string | undefined) ??
+      (turn?.sessionThreadId != null ? turn.sessionThreadId : undefined),
+  )
 
   if (reply_to == null && quoteOptIn && HISTORY_ENABLED) {
     try {
@@ -6176,6 +6216,16 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
   const turn = currentTurn
   if (!args.chat_id) throw new Error('stream_reply: chat_id is required')
   if (args.text == null || args.text === '') throw new Error('stream_reply: text is required and cannot be empty')
+  // Thread precedence (matches executeReply): when the model passes no
+  // explicit message_thread_id, fall back to THIS turn's originating
+  // topic before handleStreamReply's chatThreadMap last-seen heuristic.
+  // Injecting here threads every downstream consumer consistently — the
+  // dedup key, the voice-scrub metric, the draft transport, and the send
+  // — so a streamed handback/synthetic-turn reply lands in the right
+  // supergroup topic. DM: sessionThreadId undefined → unchanged.
+  if (args.message_thread_id == null && turn?.sessionThreadId != null) {
+    args.message_thread_id = String(turn.sessionThreadId)
+  }
 
   // Outbound secret scrub (#2044): mask before the dedup key, the draft
   // stream sends, and the history record. stream_reply carries the FULL
@@ -11067,6 +11117,30 @@ function resolveAgentOutboundTopic(
   }
 }
 
+/**
+ * The agent's supergroup chat id (`channels.telegram.chat_id`) when it is in
+ * supergroup-owned mode, else undefined. A forum topic id resolved by
+ * {@link resolveAgentOutboundTopic} is valid ONLY in this chat — used by
+ * {@link topicForRecipient} to decide whether an approval/permission card sent
+ * to a given recipient (operator DMs vs the supergroup itself) may carry a
+ * `message_thread_id`. Attaching a topic to a DM is the marko brevo wedge
+ * (2026-06-02): the card fails with "message thread not found" and auto-denies.
+ */
+function resolveAgentSupergroupChatId(): string | undefined {
+  const agentName = process.env.SWITCHROOM_AGENT_NAME
+  if (!agentName) return undefined
+  try {
+    const cfg = loadSwitchroomConfig()
+    const rawAgent = cfg.agents?.[agentName]
+    if (!rawAgent) return undefined
+    const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent)
+    const tg = resolved.channels?.telegram as { chat_id?: string | number } | undefined
+    return tg?.chat_id != null ? String(tg.chat_id) : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Stamp a user-facing restart reason into the clean-shutdown marker
  * (same file the SIGTERM handler writes to and the next session greeting
@@ -18581,6 +18655,7 @@ void (async () => {
                   })
                 }
 
+                const handbackOrigin = resolveSubagentOriginChat(agentId)
                 const decision = decideSubagentHandback({
                   handbackEnvValue: process.env.SWITCHROOM_SUBAGENT_HANDBACK,
                   outcome,
@@ -18589,11 +18664,18 @@ void (async () => {
                   // turn) back to the conversation the Task was dispatched
                   // from, so the result lands where the user asked — not the
                   // agent's DM. Falls back to fleetChatId/ownerChatId.
-                  fleetChatId: resolveSubagentOriginChat(agentId)?.chatId || fleetChatId,
+                  fleetChatId: handbackOrigin?.chatId || fleetChatId,
+                  // Supergroup topic the Task was dispatched from. Plumbed
+                  // through so the handback turn (and the model's in-voice
+                  // "here's what the worker found" reply) land in the
+                  // originating topic — not the chat's last-seen topic.
+                  // Applied only when the origin chat resolved (DM fallback
+                  // is topic-less).
+                  ...(handbackOrigin?.threadId != null
+                    ? { originThreadId: handbackOrigin.threadId }
+                    : {}),
                   // Owner-chat fallback: if the parent-turn chat can't be
-                  // resolved, route to the owner chat. Every switchroom fleet
-                  // agent is DM-shaped, so allowFrom[0] is the conversation
-                  // that dispatched.
+                  // resolved, route to the owner chat.
                   ownerChatId: loadAccess().allowFrom[0] ?? '',
                   taskDescription: description,
                   resultText,
@@ -18654,7 +18736,7 @@ void (async () => {
               // suppresses stale-after-restart delivery (a 4-h-old
               // "still working (5m)" would be a lie). Sweep on handback
               // lives in the `onFinish` block just above.
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine }) => {
                 let fleetChatId = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
@@ -18694,7 +18776,15 @@ void (async () => {
                     nestingEnabled: foregroundNestingEnabled,
                     replyCalled: turn.replyCalled,
                   })) return
-                  const child = latestSummary.trim().slice(0, 120)
+                  // Prefer the tick's own display line: `progressLine` (a
+                  // friendly tool-step label) on tool ticks, else the
+                  // worker's narrative (`latestSummary`) on text ticks. This
+                  // lets a foreground sub-agent that runs tools without
+                  // emitting prose still nest its steps under the parent
+                  // feed (the foreground blindspot) — mirroring the
+                  // main-turn activity feed, which surfaces both tool labels
+                  // and prose.
+                  const child = (progressLine ?? latestSummary).trim().slice(0, 120)
                   if (child.length === 0) return
                   let narrative = turn.foregroundSubAgents.get(agentId)
                   if (narrative == null) {
@@ -18746,12 +18836,18 @@ void (async () => {
                   return
                 }
 
+                const progressOrigin = resolveSubagentOriginChat(agentId)
                 const decision = decideSubagentProgress({
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,
                   // Prefer the conversation the Task was dispatched from over
                   // the owner DM (see resolveSubagentOriginChat).
-                  fleetChatId: resolveSubagentOriginChat(agentId)?.chatId || fleetChatId,
+                  fleetChatId: progressOrigin?.chatId || fleetChatId,
+                  // Carry the dispatching topic so the progress wake lands in
+                  // it (applied only when the origin chat resolved).
+                  ...(progressOrigin?.threadId != null
+                    ? { originThreadId: progressOrigin.threadId }
+                    : {}),
                   ownerChatId: loadAccess().allowFrom[0] ?? '',
                   subagentJsonlId: agentId,
                   taskDescription: description,
@@ -18769,10 +18865,11 @@ void (async () => {
                 // model is about to compose an explicit in-voice
                 // progress line — letting the "— still working (Nm)"
                 // edit fire in parallel would double-surface the
-                // signal. Progress envelopes target the chat level
-                // (no thread id), matching how the inbound lands.
+                // signal. Key the clear on the topic the envelope lands
+                // in (origin thread) so the right lane is yielded in a
+                // supergroup; chat-level for DM-shaped agents.
                 pendingProgress.clearPending(
-                  statusKey(decision.chatId, undefined),
+                  statusKey(decision.chatId, progressOrigin?.threadId),
                   'progress',
                 )
                 process.stderr.write(

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

@@ -40,6 +40,12 @@ export interface SubagentHandbackContext {
   /** Telegram chat the work was dispatched from — the synthesized
    *  handback turn lands here so it stays with the conversation. */
   chatId: string
+  /** Supergroup topic (message_thread_id) the work was dispatched from.
+   *  Carried so the synthesized handback turn — and the model's
+   *  in-voice "here's what the worker found" reply — land in the
+   *  originating topic, not the chat's last-seen topic. Omitted for
+   *  DM-shaped chats (no topics). See `gateway.ts:resolveSubagentOriginChat`. */
+  threadId?: number
   /** Dispatch-time task description (the sub-agent's `description`). */
   taskDescription: string
   /** The worker's final result text — its last narrative emission
@@ -98,6 +104,9 @@ export function buildSubagentHandbackInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chatId,
+    // Top-level threadId → the enqueued turn's sessionThreadId, so the
+    // handback turn's live activity feed routes to the originating topic.
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts, // synthetic — no Telegram message id exists
     user: 'subagent-watcher',
     userId: 0,
@@ -106,6 +115,10 @@ export function buildSubagentHandbackInbound(opts: {
     meta: {
       source: 'subagent_handback',
       outcome: opts.ctx.outcome,
+      // meta.message_thread_id is the model-visible channel attribute
+      // (mirrors the real-inbound shape) so the model's reply targets
+      // the dispatching topic. Mirrors gateway.ts:10557.
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       ...(opts.ctx.jsonlAgentId ? { subagent_jsonl_id: opts.ctx.jsonlAgentId } : {}),
     },
   }
@@ -135,6 +148,10 @@ export interface SubagentHandbackDecisionInput {
   fleetChatId: string
   /** Owner chat fallback (access.json allowFrom[0]); '' if none. */
   ownerChatId: string
+  /** Supergroup topic the work was dispatched from (from the parent
+   *  turn). Applied ONLY when `fleetChatId` resolved (the origin chat
+   *  won) — the `ownerChatId` DM fallback has no topic. */
+  originThreadId?: number
   taskDescription: string
   resultText: string
   /** JSONL filename stem for this Claude Code spawn — forwarded into
@@ -185,9 +202,14 @@ export function decideSubagentHandback(
   if (!chatId) {
     return { deliver: false, reason: 'no-chat' }
   }
+  // Thread only when the origin chat (fleetChatId) won — the ownerChatId
+  // DM fallback is topic-less, so a stray thread id would mis-address it.
+  const threadId =
+    input.fleetChatId && input.originThreadId != null ? input.originThreadId : undefined
   const inbound = buildSubagentHandbackInbound({
     ctx: {
       chatId,
+      ...(threadId != null ? { threadId } : {}),
       taskDescription: input.taskDescription,
       resultText: input.resultText,
       outcome: input.outcome,

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

@@ -62,6 +62,10 @@ export const DEFAULT_PROGRESS_INTERVAL_MS = 5 * 60 * 1000
 export interface SubagentProgressContext {
   /** Telegram chat the work was dispatched from. */
   chatId: string
+  /** Supergroup topic (message_thread_id) the work was dispatched from,
+   *  so the progress wake-up turn and the model's reply land in the
+   *  originating topic. Omitted for DM-shaped chats. */
+  threadId?: number
   /** JSONL-derived sub-agent id (stable per Claude Code spawn). Pinned
    *  into the spool id so envelopes for the same worker dedup across
    *  buckets cleanly and survive gateway restarts. */
@@ -125,6 +129,7 @@ export function buildSubagentProgressInbound(opts: {
   return {
     type: 'inbound',
     chatId: opts.ctx.chatId,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
     messageId: ts, // synthetic — no Telegram message id exists
     user: 'subagent-watcher',
     userId: 0,
@@ -132,6 +137,7 @@ export function buildSubagentProgressInbound(opts: {
     text,
     meta: {
       source: 'subagent_progress',
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       subagent_jsonl_id: opts.ctx.subagentJsonlId,
       bucket_idx: String(opts.ctx.bucketIdx),
       expiresAt: String(expiresAt),
@@ -155,6 +161,10 @@ export interface SubagentProgressDecisionInput {
   fleetChatId: string
   /** Owner chat fallback (access.json allowFrom[0]); '' if none. */
   ownerChatId: string
+  /** Supergroup topic the work was dispatched from. Applied ONLY when
+   *  `fleetChatId` resolved (the origin chat won); the DM fallback is
+   *  topic-less. */
+  originThreadId?: number
   subagentJsonlId: string
   taskDescription: string
   latestSummary: string
@@ -240,9 +250,12 @@ export function decideSubagentProgress(
   if (input.lastBucketIdx != null && bucketIdx <= input.lastBucketIdx) {
     return { deliver: false, reason: 'bucket-already-fired' }
   }
+  const threadId =
+    input.fleetChatId && input.originThreadId != null ? input.originThreadId : undefined
   const inbound = buildSubagentProgressInbound({
     ctx: {
       chatId,
+      ...(threadId != null ? { threadId } : {}),
       subagentJsonlId: input.subagentJsonlId,
       taskDescription: input.taskDescription,
       latestSummary: input.latestSummary,

package/telegram-plugin/subagent-watcher.ts

@@ -42,6 +42,7 @@ import { basename, join } from 'path'
 import { homedir } from 'os'
 import { projectSubagentLine, sanitizeCwdToProjectName, detectErrorInTranscriptLine } from './session-tail.js'
 import { sanitiseToolArg } from './fleet-state.js'
+import { describeToolUse } from './tool-activity-summary.js'
 import { escapeHtml, truncate } from './card-format.js'
 import { bumpSubagentActivity, recordSubagentStall, recordSubagentResume, recordSubagentEnd, reapStuckRunningRows, countRunningBackgroundSubagents } from './registry/subagents-schema.js'
 import { touchTurnActiveMarker } from './gateway/turn-active-marker.js'
@@ -348,6 +349,13 @@ export interface SubagentWatcherConfig {
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Friendly display line for THIS tick. Set on `sub_agent_tool_use`
+     *  events to a `describeToolUse` label ("Reading X", "Running a
+     *  command") so a foreground sub-agent that runs tools without
+     *  emitting prose still surfaces its steps in the parent's nested
+     *  feed. Undefined on `sub_agent_text` ticks — the gateway falls back
+     *  to `latestSummary` (the narrative line), preserving prior behavior. */
+    progressLine?: string
   }) => void
   /** `Date.now` override for tests. */
   now?: () => number
@@ -645,6 +653,9 @@ export function readSubTail(
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Friendly display line for THIS tick (set on tool ticks; see the
+     *  SubagentWatcherConfig.onProgress doc). */
+    progressLine?: string
   }) => void,
 ): void {
   try {
@@ -781,6 +792,39 @@ export function readSubTail(
             name: ev.toolName,
             sanitisedArg: sanitiseToolArg(ev.toolName, ev.input ?? {}),
           }
+          // Surface a tool-step progress cue. A foreground sub-agent that
+          // runs tools WITHOUT emitting prose (e.g. a researcher reading
+          // files) previously produced no onProgress tick at all — only
+          // `sub_agent_text` fired it — so its steps never nested under the
+          // parent's activity feed (the named foreground blindspot). Fire
+          // here too, carrying a friendly `describeToolUse` label as
+          // `progressLine` so the gateway can render "Reading X" / "Running
+          // a command" the same way the main-turn feed does. `latestSummary`
+          // stays the worker's narrative result (never polluted with tool
+          // labels — the handback payload depends on it). Pure jsonl-tail →
+          // render, no model call.
+          if (onProgress != null && entry.state === 'running' && !entry.historical) {
+            const toolLine = describeToolUse(ev.toolName, ev.input ?? {})
+            if (toolLine != null && toolLine.length > 0) {
+              try {
+                onProgress({
+                  agentId: entry.agentId,
+                  description: entry.description,
+                  latestSummary: entry.lastResultText,
+                  elapsedMs: now - entry.dispatchedAt,
+                  prevBucketIdx: entry.lastProgressBucketIdx,
+                  setBucketIdx: (b: number) => {
+                    entry.lastProgressBucketIdx = b
+                  },
+                  lastTool: entry.lastTool,
+                  toolCount: entry.toolCount,
+                  progressLine: toolLine,
+                })
+              } catch (cbErr) {
+                log?.(`subagent-watcher: onProgress (tool) callback error ${entry.agentId}: ${(cbErr as Error).message}`)
+              }
+            }
+          }
         } else if (ev.kind === 'sub_agent_text') {
           // Do NOT overwrite description with narrative text — description is
           // set at dispatch time (from the parent Agent/Task tool_use input)

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

@@ -109,4 +109,36 @@ describe('decideSubagentHandback', () => {
       expect(d.inbound.text).toContain('Applied 3 migrations')
     }
   })
+
+  // Supergroup topic routing (#status-channel-routing).
+  it('threads the inbound to the origin topic when the origin (fleet) chat won', () => {
+    const d = decideSubagentHandback({ ...base, fleetChatId: '-100777', originThreadId: 42 })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('-100777')
+      expect(d.inbound.threadId).toBe(42)
+      expect(d.inbound.meta.message_thread_id).toBe('42')
+    }
+  })
+
+  it('does NOT thread when falling back to the owner DM (topic-less)', () => {
+    // fleetChatId empty → owner DM wins; a stray originThreadId must not
+    // be applied to a DM chat that has no topics.
+    const d = decideSubagentHandback({ ...base, fleetChatId: '', originThreadId: 42 })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('999')
+      expect(d.inbound.threadId).toBeUndefined()
+      expect(d.inbound.meta.message_thread_id).toBeUndefined()
+    }
+  })
+
+  it('omits thread carriers when no originThreadId is supplied (DM-shaped agent)', () => {
+    const d = decideSubagentHandback({ ...base, fleetChatId: '777' })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.inbound.threadId).toBeUndefined()
+      expect(d.inbound.meta.message_thread_id).toBeUndefined()
+    }
+  })
 })

package/telegram-plugin/tests/subagent-handback-inbound-builder.test.ts

@@ -124,4 +124,39 @@ describe('buildSubagentHandbackInbound', () => {
     })
     expect(inbound.text).toContain('(no description)')
   })
+
+  // Supergroup topic routing (#status-channel-routing). The handback turn
+  // and the model's in-voice reply must land in the topic the work was
+  // dispatched from — not the chat's last-seen topic. The carriers are the
+  // top-level threadId (→ turn.sessionThreadId, routes the activity feed)
+  // and meta.message_thread_id (the model-visible channel attribute,
+  // mirrors the real-inbound shape at gateway.ts:10557).
+  it('carries top-level threadId AND meta.message_thread_id when ctx.threadId is set', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '-1001234567890',
+        threadId: 42,
+        taskDescription: 'Research competitors',
+        resultText: 'Found 3 relevant comps.',
+        outcome: 'completed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.threadId).toBe(42)
+    expect(inbound.meta.message_thread_id).toBe('42')
+  })
+
+  it('omits both thread carriers when ctx.threadId is absent (DM-shaped chat)', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '12345',
+        taskDescription: 'x',
+        resultText: 'y',
+        outcome: 'completed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.threadId).toBeUndefined()
+    expect(inbound.meta.message_thread_id).toBeUndefined()
+  })
 })

package/telegram-plugin/tests/subagent-progress-inbound-builder.test.ts

@@ -158,6 +158,42 @@ describe('buildSubagentProgressInbound', () => {
     })
     expect(spoolId(bucket1)).not.toBe(spoolId(bucket2))
   })
+
+  // Supergroup topic routing (#status-channel-routing).
+  it('carries top-level threadId AND meta.message_thread_id when ctx.threadId is set', () => {
+    const inbound = buildSubagentProgressInbound({
+      ctx: {
+        chatId: '-100999',
+        threadId: 7,
+        subagentJsonlId: 'jsonl-abc',
+        taskDescription: 'x',
+        latestSummary: 'still going',
+        elapsedMs: 7 * 60 * 1000,
+        bucketIdx: 1,
+        progressIntervalMs: INTERVAL_MS,
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.threadId).toBe(7)
+    expect(inbound.meta.message_thread_id).toBe('7')
+  })
+
+  it('omits both thread carriers when ctx.threadId is absent (DM-shaped chat)', () => {
+    const inbound = buildSubagentProgressInbound({
+      ctx: {
+        chatId: '12345',
+        subagentJsonlId: 'jsonl-abc',
+        taskDescription: 'x',
+        latestSummary: 'y',
+        elapsedMs: 7 * 60 * 1000,
+        bucketIdx: 1,
+        progressIntervalMs: INTERVAL_MS,
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.threadId).toBeUndefined()
+    expect(inbound.meta.message_thread_id).toBeUndefined()
+  })
 })
 
 describe('isEnvFlagOn — bool env parser', () => {
@@ -266,4 +302,24 @@ describe('decideSubagentProgress', () => {
     expect(d.deliver).toBe(false)
     if (!d.deliver) expect(d.reason).toBe('missing-jsonl-id')
   })
+
+  // Supergroup topic routing (#status-channel-routing).
+  it('threads to the origin topic when the origin (fleet) chat won', () => {
+    const d = decideSubagentProgress(baseInput({ fleetChatId: '-100abc', originThreadId: 7 }))
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.inbound.threadId).toBe(7)
+      expect(d.inbound.meta.message_thread_id).toBe('7')
+    }
+  })
+
+  it('does NOT thread when falling back to the owner DM', () => {
+    const d = decideSubagentProgress(baseInput({ fleetChatId: '', originThreadId: 7 }))
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('999')
+      expect(d.inbound.threadId).toBeUndefined()
+      expect(d.inbound.meta.message_thread_id).toBeUndefined()
+    }
+  })
 })

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -373,6 +373,7 @@ describe('startSubagentWatcher', () => {
     function startWatcherSync(opts: {
       agentDir: string
       onFinish?: Parameters<typeof startSubagentWatcher>[0]['onFinish']
+      onProgress?: Parameters<typeof startSubagentWatcher>[0]['onProgress']
     }): {
       notifications: string[]
       poll: () => void
@@ -392,6 +393,7 @@ describe('startSubagentWatcher', () => {
           notifications.push(`✓ Worker done: ${info.description}`)
           opts.onFinish?.(info)
         },
+        ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
         stallThresholdMs: 60_000,
         rescanMs: 500,
         now: () => Date.now(),
@@ -477,6 +479,46 @@ describe('startSubagentWatcher', () => {
       expect(entry?.toolCount).toBe(3)
     })
 
+    it('fires onProgress with a friendly tool-step progressLine on a tool_use tick (foreground visibility)', () => {
+      // A foreground sub-agent that runs tools WITHOUT emitting prose used
+      // to fire no onProgress cue at all — only `sub_agent_text` did — so
+      // its steps never nested under the parent's activity feed (the named
+      // foreground blindspot). The tool_use branch now fires onProgress
+      // carrying a `describeToolUse` label so the gateway can render
+      // "Reading X" the same way the main-turn feed does.
+      const progress: Array<{ progressLine?: string; toolCount: number; latestSummary: string }> = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, toolCount, latestSummary }) => {
+          progress.push({ progressLine, toolCount, latestSummary })
+        },
+      })
+      // Register running, post-boot (same pattern as the onFinish test).
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Research the competitors')))
+      h.poll()
+      expect(h.watcher.getRegistry().get('deadbeef')?.state).toBe('running')
+
+      // The sub-agent reads a file — a tool_use with no accompanying prose.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'Read', id: 'r1', input: { file_path: '/x/CLAUDE.md' } }] },
+      }))
+      h.poll()
+
+      const toolTick = progress.find((p) => p.progressLine != null)
+      expect(toolTick).toBeDefined()
+      // Friendly label, matching the main-turn activity feed's renderer.
+      expect(toolTick?.progressLine).toBe('Reading CLAUDE.md')
+      // latestSummary stays the (empty) narrative result — never polluted
+      // with the tool label, so the handback payload is unaffected.
+      expect(toolTick?.latestSummary).toBe('')
+    })
+
     it('captures the full last narrative line into lastResultText (handback)', () => {
       // lastSummaryLine keeps only the first line, 120 chars — a progress
       // preview. lastResultText keeps the full last narrative emission: