switchroom 0.14.42 → 0.14.44

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/gateway/turn-state-purge.ts

@@ -50,6 +50,19 @@ export function purgeStaleTurnsForChat(
   chatId: string,
   keys: Iterable<string>,
   purger: (key: string) => void,
+  /**
+   * Per-sibling staleness gate. A sibling key for `chatId` is purged only when
+   * this returns true. CRITICAL for one-agent-owns-supergroup: all of an
+   * agent's forum topics share the SAME chatId, so a chatId-only match would
+   * purge a LIVE sibling topic's reaction controller + typing loop when ANOTHER
+   * topic's 300s silence-poke fires (the gymbro/klanker wedge class). The
+   * caller passes a predicate true only for siblings themselves silent ≥ the
+   * fallback threshold (their own poke would also fire) — preserving the #1556
+   * dangling-key cleanup while sparing live siblings. Defaults to always-stale
+   * for back-compat (DM / single-topic callers, where every sibling is
+   * genuinely dangling).
+   */
+  isStale: (key: string) => boolean = () => true,
 ): PurgeStaleTurnsResult {
   if (!chatId) return { purged: [] }
   const purged: string[] = []
@@ -64,6 +77,7 @@ export function purgeStaleTurnsForChat(
     if (sep < 0) continue // malformed / non-statusKey shape — skip
     const keyChat = key.slice(0, sep)
     if (keyChat !== chatId) continue
+    if (!isStale(key)) continue // live sibling topic — leave its turn state intact
     purger(key)
     purged.push(key)
   }

package/telegram-plugin/silence-poke.ts

@@ -244,6 +244,23 @@ export function endTurn(key: string): void {
   state.delete(key)
 }
 
+/**
+ * Current silence duration (ms) for a key — `now - (lastOutboundAt ??
+ * turnStartedAt)`, the same clock `tick()` uses to decide the 300s fallback —
+ * or null when no turn state exists for the key. Lets the sibling-topic purge
+ * distinguish a STALE/wedged sibling (silent ≥ the fallback threshold, so its
+ * own poke would also fire) from a LIVE one mid-turn (recent outbound, low
+ * silence), so a silence-poke on one supergroup topic doesn't purge a live
+ * sibling topic's reaction controller + typing loop. NB: this is silence, NOT
+ * turn-start age — a long but actively-narrating turn has low silence and must
+ * not be treated as stale.
+ */
+export function silenceMsForKey(key: string, now: number): number | null {
+  const s = state.get(key)
+  if (s == null) return null
+  return now - (s.lastOutboundAt ?? s.turnStartedAt)
+}
+
 /**
  * Verbatim framework-fallback text — the user-visible "still working / still
  * thinking" message the gateway sends at the 300s threshold when the model
@@ -264,8 +281,17 @@ export function formatFrameworkFallbackText(
   fallbackKind: 'working' | 'thinking',
   silenceMs: number,
   inFlightTools: ToolSnapshot[] = [],
+  blockedOnApproval = false,
 ): string {
   const minutes = Math.max(1, Math.round(silenceMs / 60_000))
+  // The turn isn't stalled — it's parked on an approval card waiting for YOUR
+  // tap (the dominant live "wedge" class is benign approval-latency, not a
+  // hang). Saying "still working…" here actively lies; name the real blocker so
+  // the operator knows the ball is in their court. Takes precedence over the
+  // in-flight-tool framing (a tool awaiting approval isn't "running").
+  if (blockedOnApproval) {
+    return `waiting for your approval — tap Approve or Deny on the card above (${minutes} min)`
+  }
   const suffix = `(no update from agent in ${minutes} min)`
   // #1292 case (a): tools in flight. Name the longest-running one
   // (entry[0] — caller pre-sorts by startedAt ascending). Avoid the

package/telegram-plugin/status-reactions.ts

@@ -144,6 +144,10 @@ export class StatusReactionController {
   private stallHardTimer: ReturnType<typeof setTimeout> | null = null
   private finished = false
   private held = false
+  // True while parked on the awaiting-approval state (🙏): the turn is blocked
+  // on the operator's tap, not stalled. Read by the silence-poke fallback so it
+  // says "waiting for your approval" instead of the dishonest "still working…".
+  private awaitingApproval = false
   private readonly debounceMs: number
   private readonly stallSoftMs: number
   private readonly stallHardMs: number
@@ -272,11 +276,21 @@ export class StatusReactionController {
 
   // ──────────────────────────────────────────────────────────────────────
 
+  /** True while the turn is parked awaiting the operator's approval tap (🙏).
+   *  The silence-poke fallback reads this to phrase its 300s message honestly
+   *  ("waiting for your approval") instead of "still working…". */
+  isAwaiting(): boolean {
+    return this.awaitingApproval && !this.finished
+  }
+
   private scheduleState(
     state: ReactionState,
     opts: { immediate?: boolean; skipStallReset?: boolean } = {},
   ): void {
     if (this.finished) return
+    // Track the awaiting-approval state for isAwaiting(). Any non-awaiting
+    // state transition (setThinking/setTool/… on verdict resume) clears it.
+    this.awaitingApproval = state === 'awaiting'
     const emoji = this.resolveEmoji(state)
     if (emoji == null) {
       if (!opts.skipStallReset) this.resetStallTimers()

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/silence-poke.test.ts

@@ -7,6 +7,7 @@ import {
   noteToolEnd,
   noteToolLabel,
   endTurn,
+  silenceMsForKey,
   silencePokeEnabled,
   formatFrameworkFallbackText,
   __tickForTests,
@@ -275,6 +276,26 @@ describe('silence-poke — #1292 tool-aware framework fallback', () => {
     ).toBe('still working… (no update from agent in 5 min)')
   })
 
+  it('blockedOnApproval names the real blocker instead of the dishonest "still working…"', () => {
+    expect(
+      formatFrameworkFallbackText('working', 305_000, [], true),
+    ).toBe('waiting for your approval — tap Approve or Deny on the card above (5 min)')
+  })
+
+  it('blockedOnApproval takes precedence over an in-flight tool (a tool awaiting approval is not "running")', () => {
+    expect(
+      formatFrameworkFallbackText('working', 305_000, [
+        { name: 'Bash', label: 'rm -rf build', durationMs: 305_000 },
+      ], true),
+    ).toBe('waiting for your approval — tap Approve or Deny on the card above (5 min)')
+  })
+
+  it('blockedOnApproval=false keeps the existing wording (default, back-compat)', () => {
+    expect(
+      formatFrameworkFallbackText('working', 305_000, [], false),
+    ).toBe('still working… (no update from agent in 5 min)')
+  })
+
   it('tool-aware wording wins over "thinking" — the actual observable beats the inferred kind', () => {
     const text = formatFrameworkFallbackText('thinking', 305_000, [
       { name: 'Grep', label: '"foo"', durationMs: 305_000 },
@@ -340,6 +361,21 @@ describe('silence-poke — #1292 tool-aware framework fallback', () => {
     expect(fx.fallbacks).toHaveLength(1)
   })
 
+  it('silenceMsForKey reports silence from last outbound (or turn start), null when unknown', () => {
+    setupDeps()
+    startTurn('k', 1_000)
+    // No outbound yet → silence measured from turnStartedAt.
+    expect(silenceMsForKey('k', 1_000 + 120_000)).toBe(120_000)
+    noteOutbound('k', 1_000 + 50_000)
+    // After an outbound → silence measured from lastOutboundAt.
+    expect(silenceMsForKey('k', 1_000 + 120_000)).toBe(70_000)
+    // Unknown key / ended turn → null (used by the sibling purge to treat a
+    // dangling key as stale).
+    expect(silenceMsForKey('never-started', 999_999)).toBeNull()
+    endTurn('k')
+    expect(silenceMsForKey('k', 999_999)).toBeNull()
+  })
+
   it('Task tool populates inFlightTools so the fallback names it as the observable', () => {
     const fx = setupDeps()
     startTurn('k', 0)

package/telegram-plugin/tests/status-reactions.test.ts

@@ -94,6 +94,22 @@ describe('StatusReactionController', () => {
     expect(calls).toEqual(['👀'])
   })
 
+  it('isAwaiting() tracks the awaiting-approval state (for the honest silence-poke copy)', async () => {
+    const { emit } = makeEmitter()
+    const ctrl = new StatusReactionController(emit)
+    expect(ctrl.isAwaiting()).toBe(false)
+    ctrl.setAwaiting()
+    expect(ctrl.isAwaiting()).toBe(true)
+    // The verdict resume (setThinking) un-parks → no longer awaiting.
+    ctrl.setThinking()
+    expect(ctrl.isAwaiting()).toBe(false)
+    // Re-park, then finish → isAwaiting is false once the turn ends.
+    ctrl.setAwaiting()
+    expect(ctrl.isAwaiting()).toBe(true)
+    ctrl.finalize()
+    expect(ctrl.isAwaiting()).toBe(false)
+  })
+
   it('setThinking is debounced by 3500ms (#1713)', async () => {
     const { emit, calls } = makeEmitter()
     const ctrl = new StatusReactionController(emit)

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:

package/telegram-plugin/tests/turn-state-purge.test.ts

@@ -106,4 +106,32 @@ describe('purgeStaleTurnsForChat', () => {
     expect(r.purged.sort()).toEqual(['123:7', '123:_'])
     expect([...map.keys()]).toEqual(['999:_']) // multi-chat safety preserved
   })
+
+  // #2 supergroup sibling-topic fix: one agent owns the supergroup, so all
+  // forum topics share the chatId. A 300s poke on topic A must NOT purge a
+  // LIVE sibling topic B's turn state — only siblings that are themselves stale.
+  it('isStale predicate spares live sibling topics (the supergroup fix)', () => {
+    const purged: string[] = []
+    const live = new Set(['-100:7']) // topic 7 is actively mid-turn
+    const r = purgeStaleTurnsForChat(
+      '-100',
+      ['-100:4', '-100:7', '999:_'],
+      (k) => purged.push(k),
+      (k) => !live.has(k), // stale iff not live
+    )
+    expect(r.purged).toEqual(['-100:4']) // only the stale topic purged
+    expect(purged).toEqual(['-100:4']) // live topic 7 + other chat untouched
+  })
+
+  it('isStale=false for every sibling purges nothing (all topics live)', () => {
+    const purged: string[] = []
+    purgeStaleTurnsForChat('-100', ['-100:4', '-100:7'], (k) => purged.push(k), () => false)
+    expect(purged).toEqual([])
+  })
+
+  it('default isStale (omitted) purges every chatId match — back-compat', () => {
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat('123', ['123:_', '123:7', '999:_'], (k) => purged.push(k))
+    expect(r.purged.sort()).toEqual(['123:7', '123:_'])
+  })
 })

package/telegram-plugin/uat/driver.ts

@@ -156,6 +156,47 @@ export class Driver {
     this.client = null;
   }
 
+  /**
+   * Populate the local peer cache with the account's dialogs so a
+   * supergroup referenced by its marked id (e.g. `-100…`) becomes
+   * resolvable. The driver runs on `MemoryStorage`, which starts EMPTY
+   * every connect — a bot username resolves on demand (server lookup),
+   * but a supergroup with no public username has no resolution path
+   * until mtcute has seen it via the dialog list (which carries the
+   * channel's `access_hash`). Call this once before sending to /
+   * observing a supergroup. Best-effort: drains up to `limit` dialogs.
+   * Requires the driver account to be a MEMBER of the supergroup — if a
+   * later `sendText` still throws "Peer … not found in local cache",
+   * the account isn't in the group.
+   */
+  async primeDialogs(limit = 200): Promise<void> {
+    const c = this.requireClient();
+    let seen = 0;
+    for await (const _dialog of c.iterDialogs({ limit })) {
+      void _dialog; // draining caches each peer's access_hash as a side effect
+      if (++seen >= limit) break;
+    }
+  }
+
+  /**
+   * True if `chatId` is resolvable (its access_hash is known) — i.e. a
+   * peer the account can address. Call after {@link primeDialogs}.
+   * Non-intrusive: sends nothing. A forum supergroup the driver account
+   * is in resolves true; a chat referenced by a wrong/foreign marked id
+   * (e.g. a BASIC group given a supergroup-style `-100…` id, or a chat
+   * the driver isn't a member of) resolves false. Used to skip supergroup
+   * scenarios cleanly when the test forum isn't wired.
+   */
+  async canResolve(chatId: number): Promise<boolean> {
+    const c = this.requireClient();
+    try {
+      await c.resolvePeer(chatId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   async sendText(
     chatId: number,
     text: string,