switchroom 0.16.46 → 0.17.0

package/telegram-plugin/slot-banner-driver.ts

@@ -72,6 +72,23 @@ export interface RefreshBannerArgs {
   /** Optional API-failure observer. Phase identifies which Bot API
    *  call failed so the caller can log meaningfully. Default: silent. */
   onError?: (phase: 'pin' | 'edit' | 'unpin', err: unknown) => void;
+  /** Optional durable-persistence hooks so an orphaned banner pin is
+   *  recoverable across a gateway crash. The gateway wires these to the
+   *  shared status-pin store (a distinct `banner:` pinKey), mirroring the
+   *  status-pin store's persist-BEFORE-pin ordering. All hooks are
+   *  best-effort — the driver guards each call so a throwing hook can never
+   *  break banner pinning (persistence is cosmetic-recovery, never load-bearing
+   *  for the live pin). Omit entirely to disable persistence (unit tests). */
+  persist?: {
+    /** Record a PENDING pin: the banner message was sent but the pin API call
+     *  has not yet confirmed. Called AFTER sendMessage, BEFORE pinChatMessage,
+     *  so a crash in that window leaves a recoverable record on disk. */
+    pending?: (chatId: string, messageId: number) => void;
+    /** Rewrite the record as confirmed once the pin lands. */
+    confirm?: (chatId: string, messageId: number) => void;
+    /** Drop the persisted record (banner unpinned, cleared, or pin failed). */
+    clear?: () => void;
+  };
 }
 
 /**
@@ -95,6 +112,17 @@ export async function refreshBanner(
     args.defaultSlot,
   );
 
+  // Persistence hooks are cosmetic-recovery; a throwing hook must never break
+  // live banner pinning. Guard every call.
+  const safePersist = (fn: (() => void) | undefined) => {
+    if (!fn) return;
+    try {
+      fn();
+    } catch {
+      /* best-effort — persistence failures degrade to in-memory-only */
+    }
+  };
+
   if (action.kind === 'noop') return args.prevState;
 
   if (action.kind === 'unpin') {
@@ -105,7 +133,10 @@ export async function refreshBanner(
     }
     // Even if unpin failed, drop our claim — the message may have been
     // unpinned out-of-band (operator did it manually) and re-pinning
-    // would be more confusing than surfacing it again later.
+    // would be more confusing than surfacing it again later. Drop the
+    // persisted record too (unpin-then-clear mirrors the status-pin store:
+    // a crash between unpin and clear just re-unpins next boot, idempotent).
+    safePersist(args.persist?.clear);
     return null;
   }
 
@@ -122,15 +153,24 @@ export async function refreshBanner(
       args.onError?.('pin', err);
       return args.prevState;
     }
+    // Persist INTENT (pending) BEFORE the pin API call: a crash between the pin
+    // landing and its confirm rewrite leaves a pending record that boot cleanup
+    // unpins next boot — closing the persist-after-pin leak.
+    safePersist(() => args.persist?.pending?.(String(args.ownerChatId), sent.message_id));
     try {
       await args.bot.api.pinChatMessage(args.ownerChatId, sent.message_id, {
         disable_notification: true,
       });
     } catch (err) {
       args.onError?.('pin', err);
-      // sendMessage succeeded but pin failed — don't claim the message.
+      // sendMessage succeeded but pin failed — don't claim the message, and
+      // drop the pending record so we don't leave a phantom claim for a pin
+      // that never landed.
+      safePersist(args.persist?.clear);
       return args.prevState;
     }
+    // Pin confirmed — rewrite the record without the pending flag.
+    safePersist(() => args.persist?.confirm?.(String(args.ownerChatId), sent.message_id));
     return { messageId: sent.message_id, slot: action.slot };
   }
 

package/telegram-plugin/status-query-telemetry.ts

@@ -0,0 +1,100 @@
+/**
+ * Truthful `status-query` telemetry — issue #109 (truthful-telemetry PR).
+ *
+ * When the user has to ask "status?" mid-turn, the gateway logs a snapshot of
+ * what is ACTUALLY in flight so the frequency of surface failures can be
+ * counted. This module is the pure decision at the heart of that log line.
+ *
+ * History / why this is pure: the snapshot used to be read from the pinned
+ * progress card via `progressDriver.peek(...)`. That card was retired
+ * (#1122/#1126) and `progressDriver` is now permanently `null`, so the old
+ * peek ALWAYS reported idle/zero regardless of live background work — a lying
+ * diagnostic that actively misled debugging. The gateway now reads the LIVE
+ * surfaces (running-background-worker DB count, the `🛠 Worker` activity-feed
+ * size, the cross-turn pending-async-dispatch flag, and whether a turn is
+ * active) and passes them here. A live background worker ⇒ non-idle.
+ *
+ * A `ux-failure` is emitted ONLY when `idle` is true — every surface is
+ * genuinely zero AND no turn is active, i.e. the user asked "status?" and
+ * there really was nothing in flight for the surfaces to have shown.
+ */
+
+export interface StatusQuerySurfaces {
+  /** A turn is currently active for this chat key (`activeTurnStartedAt`). */
+  turnActive: boolean
+  /**
+   * Age of the active turn in whole seconds, or `-1` when no turn is active
+   * (numeric sentinel so structured-log parsers avoid string branches).
+   */
+  turnAgeS: number
+  /** Background sub-agent workers currently `running` (registry DB count). */
+  runningWorkers: number
+  /** Workers tracked by the edit-in-place `🛠 Worker` activity feed. */
+  workerFeedSize: number
+  /** Cross-turn pending-async dispatch for this chat key: 1 if pending, else 0. */
+  pendingAsync: number
+}
+
+export type StatusQueryStage = 'idle' | 'turn-active' | 'background-work'
+
+export interface StatusQueryTelemetry {
+  stage: StatusQueryStage
+  /**
+   * True only when NOTHING is live on any surface. Gates the `ux-failure`
+   * emission: a live turn or a live background worker means the surfaces DID
+   * have something to show, so the "status?" is not a clean surface failure.
+   */
+  idle: boolean
+}
+
+/**
+ * Derive the truthful stage + idle verdict from the live surfaces. Pure and
+ * total so it can be unit-tested without standing up the gateway.
+ */
+export function deriveStatusQueryTelemetry(s: StatusQuerySurfaces): StatusQueryTelemetry {
+  const idle =
+    !s.turnActive &&
+    s.runningWorkers <= 0 &&
+    s.workerFeedSize <= 0 &&
+    s.pendingAsync <= 0
+  const stage: StatusQueryStage = idle
+    ? 'idle'
+    : s.turnActive
+      ? 'turn-active'
+      : 'background-work'
+  return { stage, idle }
+}
+
+/**
+ * Render the primary structured log line (grep anchor: "status-query").
+ * Kept here so the field layout is single-sourced with the derive logic and
+ * covered by the same test.
+ */
+export function formatStatusQueryLine(
+  agentName: string,
+  chatId: string,
+  thread: string,
+  s: StatusQuerySurfaces,
+  t: StatusQueryTelemetry,
+): string {
+  return (
+    `telegram gateway: status-query agent=${agentName} chat_id=${chatId} thread=${thread} ` +
+    `stage=${t.stage} turn_age_s=${s.turnAgeS} running_workers=${s.runningWorkers} ` +
+    `worker_feed=${s.workerFeedSize} pending_async=${s.pendingAsync}\n`
+  )
+}
+
+/**
+ * Render the `ux-failure` line (grep anchor: "ux-failure: status-query"). Only
+ * call this when `t.idle` is true.
+ */
+export function formatStatusQueryUxFailureLine(
+  agentName: string,
+  chatId: string,
+  thread: string,
+): string {
+  return (
+    `telegram gateway: ux-failure: status-query agent=${agentName} chat_id=${chatId} thread=${thread} ` +
+    `stage=idle turn_age_s=-1 running_workers=0 worker_feed=0 pending_async=0\n`
+  )
+}

package/telegram-plugin/stream-reply-handler.ts

@@ -216,25 +216,24 @@ export interface StreamReplyDeps {
     sameAsLast: boolean
   }) => void
   /**
-   * Optional: progress-card driver completion hook. Wired by the gateway
-   * to `progressDriver.forceCompleteTurn(...)`. Invoked after a
-   * `stream_reply(done=true)` on the default (unnamed) lane finalizes,
-   * so the final-answer delivery acts as an authoritative turn-complete
-   * signal equal to session-tail `turn_end`. Skipped when args.lane is
-   * 'progress' (that's the driver's own emit — calling this would cause
-   * re-entry). Safe to leave unset for callers that don't use the driver.
+   * Optional: turn-complete hook. Historically wired by the gateway to
+   * `progressDriver.forceCompleteTurn(...)` so a `stream_reply(done=true)` on
+   * the default (unnamed) lane acted as an authoritative turn-complete signal
+   * equal to session-tail `turn_end`. The pinned progress card was retired
+   * (#1122/#1126) and `progressDriver` is permanently null, so the gateway now
+   * passes a no-op wrapper for this dep — the hook is inert until a future
+   * consumer re-attaches it. Skipped when args.lane is 'progress'. Safe to
+   * leave unset.
    */
   forceCompleteTurn?: (chatId: string, threadId: number | undefined) => void
   /**
-   * Optional: progress-card driver delivery counter hook. Wired by the
-   * gateway to `progressDriver.recordOutboundDelivered(...)`. Called
-   * BEFORE `forceCompleteTurn` so the driver's per-turn outbound counter
-   * is non-zero when the terminal render fires. Without this ordering
-   * guarantee, `forceCompleteTurn` flushes the card while
-   * `outboundDeliveredCount === 0` → ⚠️ false positive (issue #310).
-   * Only called on the default (unnamed) lane when `done=true` and the
-   * stream produced a non-null messageId. Safe to leave unset for callers
-   * that don't use the driver.
+   * Optional: outbound-delivery counter hook. Historically wired to
+   * `progressDriver.recordOutboundDelivered(...)`, called BEFORE
+   * `forceCompleteTurn` so the driver's per-turn outbound counter was non-zero
+   * when the terminal render fired (issue #310). With the progress card retired
+   * (#1122/#1126, null driver) the gateway passes a no-op wrapper — inert until
+   * re-attached. Only called on the default (unnamed) lane when `done=true` and
+   * the stream produced a non-null messageId. Safe to leave unset.
    */
   recordOutboundDelivered?: (chatId: string, threadId: number | undefined) => void
   /** Whether to persist outbound history. */

package/telegram-plugin/subagent-watcher.ts

@@ -48,7 +48,7 @@ import { sanitiseToolArg } from './fleet-state.js'
 import { clipNarrative, describeToolUse } from './tool-activity-summary.js'
 import { REPLY_TOOLS, isDraftOfReply } from './narrative-dedup.js'
 import { truncate } from './card-format.js'
-import { bumpSubagentActivity, recordSubagentStall, recordSubagentResume, recordSubagentEnd, reapStuckRunningRows, countRunningBackgroundSubagents } from './registry/subagents-schema.js'
+import { bumpSubagentActivity, recordSubagentStall, recordSubagentResume, recordSubagentEnd, reapStuckRunningRows, countRunningBackgroundSubagents, recordNestedSubagentDispatch } from './registry/subagents-schema.js'
 import { touchTurnActiveMarker } from './gateway/turn-active-marker.js'
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -183,6 +183,16 @@ export interface WorkerEntry {
    * `turn.lastReplyText`.
    */
   lastReplyText?: string
+  /**
+   * Wall-clock ms of the most recent RETRY of `backfillJsonlAgentId` from the
+   * liveness path (readSubTail's "row not in DB yet" branch). The one-shot
+   * backfill at registration loses the race for a NESTED worker: its row is
+   * written by recordNestedSubagentDispatch only when the watcher reads the
+   * PARENT worker's dispatch line, which can land after the child's own
+   * registration. Retrying (throttled) closes the "liveness skip … Phase 2
+   * Pre hook pending" window that froze nested cards on "starting…".
+   */
+  lastBackfillAttemptAt?: number
 }
 
 export interface SubagentWatcherConfig {
@@ -293,37 +303,47 @@ export interface SubagentWatcherConfig {
   /**
    * Option C: callback fired when a stall is detected for a running sub-agent.
    * Called with the sub-agent's agentId, idle ms, and description string.
-   * Wired to `progressDriver.onSubAgentStall` in gateway.ts so the progress
-   * card re-renders with a visible ⚠️ stall indicator even when the bridge
-   * has disconnected. The `stallNotified` flag prevents duplicate calls for
-   * the same sub-agent across subsequent poll ticks.
+   * The `stallNotified` flag prevents duplicate calls for the same sub-agent
+   * across subsequent poll ticks.
+   *
+   * NOTE: this used to be wired in gateway.ts to `progressDriver.onSubAgentStall`
+   * so the pinned progress card could render a ⚠️ stall badge. That card was
+   * retired (#1122/#1126) and the gateway wiring was removed (the dead no-op
+   * falsely implied a stall renders a visual badge). The callback is retained
+   * as an unwired hook — PR 2 will re-wire it to repaint the live `🛠 Worker`
+   * activity feed on stall. Currently no gateway consumer is attached.
    */
   onStall?: (agentId: string, idleMs: number, description: string) => void
   /**
    * Symmetric to `onStall`: fires when a previously-stalled sub-agent's
    * JSONL grows again (text emission, tool use, turn_end — anything that
-   * moves last_activity_at). Wired to `progressDriver.onSubAgentUnstall`
-   * in gateway.ts so the pinned card clears the ⚠ Stalled badge as soon
-   * as activity resumes, instead of waiting on the next render tick.
+   * moves last_activity_at).
    *
    * Each stall→resume cycle fires exactly once: the watcher resets
    * `entry.stallNotified` on resume, so a sub-agent that stalls again
    * later in the same lifetime is detected (and reported) again.
+   *
+   * NOTE: formerly wired to `progressDriver.onSubAgentUnstall` (retired card,
+   * #1122/#1126) — the gateway wiring was removed with `onStall`. Retained as
+   * an unwired hook for PR 2's live-feed repaint.
    */
   onUnstall?: (agentId: string, description: string) => void
   /**
    * RFC §Bug 6: fires when the watcher synthesises a terminal transition
    * for a stalled sub-agent (no explicit `sub_agent_turn_end` line in
    * the JSONL after `silentStallTerminalMs` past the stall notification).
-   * Wired in gateway.ts to push a synthetic
-   * `{kind:'sub_agent_turn_end', agentId}` event into the progress
-   * driver so the pinned card can release its deferred-completion gate
-   * for the background dispatch.
    *
    * Idempotent: each sub-agent triggers this at most once per lifetime
-   * (guarded by `entry.stallTerminalSynthesised`). Fires *before* the
-   * existing `onFinish` callback so the driver-side state mutation
-   * lands first; the audit-log surface then sees a consistent fleet.
+   * (guarded by `entry.stallTerminalSynthesised`).
+   *
+   * NOTE: formerly wired in gateway.ts to push a synthetic
+   * `{kind:'sub_agent_turn_end', agentId}` into the progress driver so the
+   * pinned card could release its deferred-completion gate. The card is retired
+   * (#1122/#1126) and that dead wiring was removed. The completion path does
+   * NOT depend on this callback: the silent-stall synthesis loop in
+   * `checkStalls()` writes the terminal registry-DB row itself
+   * (`recordSubagentEnd`) and fires `maybySendStateTransition` → `onFinish`
+   * (the handback) regardless. Retained as an unwired hook.
    */
   onStallTerminal?: (agentId: string, description: string) => void
   /**
@@ -439,6 +459,28 @@ const DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS = 300_000
  */
 const DEFAULT_SILENT_STALL_TERMINAL_MS = 300_000
 
+/**
+ * Tools that legitimately run for minutes with ZERO intervening JSONL
+ * writes: the worker emits ONE `sub_agent_tool_use` line when the command
+ * starts, then nothing until it returns. `Bash` (a build, `npm test`, a long
+ * curl, a git clone) is the canonical case. A worker whose last observed tool
+ * is one of these is NOT stalled just because the JSONL went quiet — the
+ * 60s active-loop threshold misfires on exactly this population, producing the
+ * false "stall detected (idle 60s)" the operator hit while a background worker
+ * was mid-`Bash`. Pass-1 stall detection widens the idle threshold for these
+ * to the same silent-synthesis window used for not-yet-started workers, so a
+ * long command is given room before it counts as stalled. The pass-2 terminal
+ * synthesis is unchanged — it still releases the deferred-completion gate the
+ * fixed window after a stall IS eventually flagged.
+ */
+const LONG_RUNNING_TOOLS: ReadonlySet<string> = new Set(['Bash'])
+
+/** True when the tool named legitimately runs quiet for minutes (see
+ *  LONG_RUNNING_TOOLS). Null/undefined tool name → false. */
+function isLongRunningTool(name: string | null | undefined): boolean {
+  return name != null && LONG_RUNNING_TOOLS.has(name)
+}
+
 /**
  * Freshness window for the boot-scan "in-flight at boot → promote to
  * live" path. A worker file still in `running` state at boot is only
@@ -505,6 +547,13 @@ const DEFAULT_REAPER_INTERVAL_MS = 15 * 60_000     // 15 minutes
  */
 const TERMINAL_CLEANUP_GRACE_MS = 30_000
 
+/**
+ * Throttle for the liveness-path retry of `backfillJsonlAgentId` (see
+ * WorkerEntry.lastBackfillAttemptAt). Cheap (one meta.json read + two
+ * indexed lookups) but no reason to run it on every 1s poll tick.
+ */
+const BACKFILL_RETRY_INTERVAL_MS = 3000
+
 // ─── JSONL tail per sub-agent ─────────────────────────────────────────────
 
 interface SubTail {
@@ -642,21 +691,52 @@ export function backfillJsonlAgentId(
   // throws out of the watcher poll loop.
   try {
     const linkedRow = db
-      .prepare('SELECT started_at, parent_turn_key FROM subagents WHERE id = ?')
-      .get(candidateId) as { started_at: number; parent_turn_key: string | null } | null
+      .prepare('SELECT started_at, parent_turn_key, parent_agent_id FROM subagents WHERE id = ?')
+      .get(candidateId) as { started_at: number; parent_turn_key: string | null; parent_agent_id?: string | null } | null
     if (linkedRow != null && linkedRow.parent_turn_key == null) {
-      const turn = db
-        .prepare(
-          `SELECT turn_key FROM turns
-           WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
-           ORDER BY started_at DESC LIMIT 1`,
-        )
-        .get(linkedRow.started_at, linkedRow.started_at) as { turn_key: string } | null
-      if (turn?.turn_key != null) {
+      // Nested-parent inheritance FIRST: a depth-2+ worker's dispatching
+      // context is another sub-agent, not a gateway turn — its origin is its
+      // ancestor chain's turn key (stamped on the depth-1 row while the main
+      // turn was still active). The time-window match below can never be
+      // right for it (the turn had typically ended before the nested dispatch
+      // happened, and overlapping windows mis-attribute).
+      let resolvedKey: string | null = null
+      if (linkedRow.parent_agent_id != null && linkedRow.parent_agent_id.length > 0) {
+        const seen = new Set<string>([agentId])
+        let cursor: string | null = linkedRow.parent_agent_id
+        for (let hop = 0; hop < 5 && cursor != null && !seen.has(cursor); hop++) {
+          seen.add(cursor)
+          const parentRow = db
+            .prepare('SELECT parent_turn_key, parent_agent_id FROM subagents WHERE jsonl_agent_id = ? LIMIT 1')
+            .get(cursor) as { parent_turn_key: string | null; parent_agent_id?: string | null } | null
+          if (parentRow == null) break
+          if (parentRow.parent_turn_key != null && parentRow.parent_turn_key.length > 0) {
+            resolvedKey = parentRow.parent_turn_key
+            break
+          }
+          cursor = parentRow.parent_agent_id ?? null
+        }
+        if (resolvedKey != null) {
+          log?.(`subagent-watcher: backfill parent_turn_key ${candidateId} → ${resolvedKey} (inherited via nested-parent chain)`)
+        }
+      }
+      if (resolvedKey == null) {
+        const turn = db
+          .prepare(
+            `SELECT turn_key FROM turns
+             WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
+             ORDER BY started_at DESC LIMIT 1`,
+          )
+          .get(linkedRow.started_at, linkedRow.started_at) as { turn_key: string } | null
+        if (turn?.turn_key != null) {
+          resolvedKey = turn.turn_key
+          log?.(`subagent-watcher: backfill parent_turn_key ${candidateId} → ${resolvedKey}`)
+        }
+      }
+      if (resolvedKey != null) {
         db
           .prepare('UPDATE subagents SET parent_turn_key = ? WHERE id = ?')
-          .run(turn.turn_key, candidateId)
-        log?.(`subagent-watcher: backfill parent_turn_key ${candidateId} → ${turn.turn_key}`)
+          .run(resolvedKey, candidateId)
       }
     }
   } catch (err) {
@@ -751,6 +831,22 @@ export function readSubTail(
           .get(entry.agentId) as { id: string; background: number } | null
         if (existing == null) {
           log?.(`subagent-watcher: liveness skip ${entry.agentId} — row not in DB yet (Phase 2 Pre hook pending)`)
+          // Retry the jsonl link (throttled). Registration's one-shot backfill
+          // loses the race for a NESTED worker whose row is only written when
+          // the watcher reads the PARENT's dispatch line — without this retry
+          // the row never links, the worker is misclassified foreground, and
+          // its card freezes on "starting…" forever (the depth-2+ freeze).
+          if (
+            entry.lastBackfillAttemptAt == null ||
+            now - entry.lastBackfillAttemptAt >= BACKFILL_RETRY_INTERVAL_MS
+          ) {
+            entry.lastBackfillAttemptAt = now
+            try {
+              backfillJsonlAgentId(db, entry.filePath, entry.agentId, log)
+            } catch (bfErr) {
+              log?.(`subagent-watcher: backfill retry error ${entry.agentId}: ${(bfErr as Error).message}`)
+            }
+          }
         } else {
           bumpSubagentActivity(db, { id: existing.id, ts: now })
           isForeground = existing.background === 0
@@ -947,6 +1043,36 @@ export function readSubTail(
               }
             }
           }
+        } else if (ev.kind === 'sub_agent_nested_spawn') {
+          // Nested (depth-2+) dispatch keying: this worker just dispatched a
+          // sub-agent of its own. The PreToolUse hook can't attribute it (the
+          // main turn's turn-active.json marker is long gone for a background
+          // worker, and under concurrent nested dispatch the hook's write can
+          // be lost entirely) — but WE are reading the authoritative dispatch
+          // line right now. Record/repair the child's registry row: ensure it
+          // exists (keyed on the dispatch tool_use_id, which the child's
+          // meta.json `toolUseId` links against), stamp `parent_agent_id` =
+          // this worker's jsonl stem, and inherit `parent_turn_key`
+          // transitively so origin-chat routing works at any depth. Rendering
+          // is unchanged (design §5.5 "no recursion in rendering") — this is
+          // registry keying only. Fire-and-forget: a DB hiccup must never
+          // break the tail loop.
+          if (db != null && ev.toolUseId != null && ev.toolUseId.length > 0) {
+            try {
+              const nestedInput = (ev.input ?? {}) as Record<string, unknown>
+              recordNestedSubagentDispatch(db, {
+                toolUseId: ev.toolUseId,
+                parentJsonlAgentId: entry.agentId,
+                agentType: typeof nestedInput.subagent_type === 'string' ? nestedInput.subagent_type : null,
+                description: typeof nestedInput.description === 'string' ? nestedInput.description : null,
+                background: nestedInput.run_in_background === true,
+                now,
+              })
+              log?.(`subagent-watcher: nested dispatch recorded parent=${entry.agentId} toolUseId=${ev.toolUseId}`)
+            } catch (dbErr) {
+              log?.(`subagent-watcher: nested dispatch record error ${entry.agentId}: ${(dbErr 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)
@@ -1260,6 +1386,23 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             log?.(`subagent-watcher: backfill error for ${agentId}: ${(err as Error).message}`)
           }
         }
+        // Historical/onProgress gate-ordering fix: the initial read above ran
+        // while `entry.historical` was still TRUE, so every onProgress cue it
+        // would have fired was suppressed by the `!entry.historical` guard —
+        // and the tail cursor is now at EOF, so for a quiet worker no later
+        // tick ever re-fires them. The card painted as a bare stub and froze
+        // on "starting…" forever. Re-read from the start now that the entry
+        // is live: the replayed events rebuild toolCount/lastTool/narrative
+        // AND fire onProgress so the worker's card reaches real activity.
+        entry.toolCount = 0
+        entry.lastTool = null
+        entry.pendingNarrative = null
+        tail.cursor = 0
+        tail.pendingPartial = ''
+        tail.hasEmittedStart = false
+        readSubTail(entry, tail, n, (desc) => {
+          log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
+        }, fs, log, db, parentStateDir, config.onUnstall, undefined, config.onProgress)
       }
     }
 
@@ -1436,9 +1579,18 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       // tool_use. Once tools have started, switch to the tighter loop
       // threshold — frequent JSONL writes mean 60s of silence is a
       // strong signal the sub-agent is genuinely stuck.
-      const threshold = entry.toolCount === 0
-        ? silentSynthesisStallThresholdMs
-        : stallThresholdMs
+      // A worker that hasn't fired any tools yet is mid-silent-synthesis; a
+      // worker whose LAST tool is a known long-runner (e.g. `Bash`) is mid-
+      // command — both legitimately go quiet in the JSONL for minutes, so both
+      // use the wider silent-synthesis window instead of the tight 60s active-
+      // loop threshold. Without the long-runner arm a background worker running
+      // a long `Bash`/`npm test` was falsely flagged "stall detected (idle
+      // 60s)" while genuinely alive. Pass-2 terminal synthesis (below) is
+      // unaffected: it still fires the fixed window after a stall IS flagged.
+      const threshold =
+        entry.toolCount === 0 || isLongRunningTool(entry.lastTool?.name)
+          ? silentSynthesisStallThresholdMs
+          : stallThresholdMs
       if (idleMs >= threshold) {
         entry.stallNotified = true
         entry.stalledAt = n

package/telegram-plugin/tests/buffer-gate-broadened.test.ts

@@ -126,22 +126,16 @@ describe('buffer-gate release decoupled from final-answer classification', () =>
     expect(releaseIdx).toBeGreaterThan(gateBlockClose)
   })
 
-  it('executeStreamReply calls releaseTurnBufferGate before its final return', () => {
-    const post =
-      gatewaySrc.split('async function executeStreamReply')[1]
-        ?.split('\nasync function ')[0] ?? ''
-    expect(post).toMatch(/releaseTurnBufferGate\(statusKey\(/)
-  })
-
-  it('the helper is invoked from executeReply / executeStreamReply only — not from new mid-turn paths', () => {
+  it('the helper is invoked from executeReply only — not from new mid-turn paths', () => {
     // Sanity: nothing else should call releaseTurnBufferGate. The
     // helper is narrow on purpose. If future code adds new
     // callsites that aren't reply-finalize, the steer-vs-queue
     // semantics could drift.
     const callMatches = gatewaySrc.match(/releaseTurnBufferGate\(/g) ?? []
-    // Definition + 2 callsites (executeReply, executeStreamReply) = 3.
+    // Definition + 1 callsite (executeReply) = 2. (The retired
+    // stream_reply tool's callsite was removed with executeStreamReply.)
     // If this count grows the test catches it; reviewer must justify
     // any new callsite.
-    expect(callMatches.length).toBe(3)
+    expect(callMatches.length).toBe(2)
   })
 })