switchroom 0.15.44 → 0.16.4

package/telegram-plugin/stream-controller.ts

@@ -16,7 +16,7 @@
  * entire server.ts top-level initialization.
  */
 
-import { createDraftStream, type DraftStreamHandle, type StreamDraftFn } from './draft-stream.js'
+import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
 import { htmlToPlainText } from './html-sanitize.js'
 
 /**
@@ -152,30 +152,15 @@ export interface StreamControllerConfig {
    */
   log?: (msg: string) => void
   /**
-   * Optional warning logger. Used for transport fallback notices.
+   * Optional warning logger. Used for fallback notices.
    */
   warn?: (msg: string) => void
-  /**
-   * Transport selector passed to createDraftStream.
-   * - "auto" (default): use draft transport for DMs only
-   * - "draft": always prefer draft (if sendMessageDraft is available)
-   * - "message": always use sendMessage/editMessageText
-   *
-   * The gateway forces "message" for forum topics (threads), since
-   * sendMessageDraft does not support threaded chats.
-   */
-  previewTransport?: 'auto' | 'message' | 'draft'
   /**
    * True when the chat is a private DM. Passed to createDraftStream so
-   * "auto" transport knows whether to activate draft.
+   * the throttle default (400 ms for DMs vs 1000 ms for groups) is applied
+   * correctly when no explicit throttleMs is set.
    */
   isPrivateChat?: boolean
-  /**
-   * sendMessageDraft callback. When provided (and transport allows it),
-   * intermediate stream updates use the draft API. On finalize(), a real
-   * sendMessage is posted for push notification and the draft is cleared.
-   */
-  sendMessageDraft?: StreamDraftFn
   /**
    * If set, the controller is initialized as if a previous send had
    * landed with this `message_id`. The first `update()` invokes
@@ -214,9 +199,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     quoteText,
     protectContent,
     replyMarkup,
-    previewTransport,
     isPrivateChat,
-    sendMessageDraft,
     initialMessageId,
   } = cfg
 
@@ -314,9 +297,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       ...(idleMs != null ? { idleMs } : {}),
       ...(log != null ? { log } : {}),
       ...(warn != null ? { warn } : {}),
-      ...(previewTransport != null ? { previewTransport } : {}),
       ...(isPrivateChat != null ? { isPrivateChat } : {}),
-      ...(sendMessageDraft != null ? { sendMessageDraft } : {}),
       ...(initialMessageId != null ? { initialMessageId } : {}),
       chatId,
     },

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

@@ -16,7 +16,7 @@
  *     wraps into an MCP content response.
  */
 
-import type { DraftStreamHandle, StreamDraftFn } from './draft-stream.js'
+import type { DraftStreamHandle } from './draft-stream.js'
 import {
   createStreamController,
   type StreamBotApi,
@@ -240,13 +240,6 @@ export interface StreamReplyDeps {
   /** Error-path stderr. */
   writeError: (line: string) => void
   throttleMs?: number
-  /**
-   * sendMessageDraft callback. When provided, stream_reply uses the draft
-   * API for intermediate updates (DM transport). On done=true, a real
-   * sendMessage fires for push notification, then the draft is cleared.
-   * Optional — omit to keep the existing sendMessage/editMessageText path.
-   */
-  sendMessageDraft?: StreamDraftFn
   /**
    * Idempotency hook for the duplicate-message class (issue #626).
    *
@@ -275,12 +268,12 @@ export interface StreamReplyDeps {
   }) => number | null | undefined
   /**
    * True when the current chat is a private DM. Passed to the stream
-   * controller so "auto" transport activates draft in DMs only.
+   * controller so the DM throttle default (400 ms) is applied instead of
+   * the group default (1000 ms) when no explicit throttleMs is set.
    */
   isPrivateChat?: boolean
   /**
-   * True when the current chat is a forum topic. Forum topics do not
-   * support sendMessageDraft — this forces message transport.
+   * True when the current chat is a forum topic.
    */
   isForumTopic?: boolean
   /**
@@ -464,14 +457,6 @@ export async function handleStreamReply(
       }
     }
 
-    // Resolve draft-transport options. Forum topics force message transport
-    // because sendMessageDraft does not support threads.
-    const isForumTopic = deps.isForumTopic === true
-    const resolvedTransport: 'auto' | 'message' | 'draft' =
-      isForumTopic || deps.sendMessageDraft == null
-        ? 'message'
-        : 'auto'
-
     // Idempotency hook (#626): if an external authority (e.g. the
     // gateway's pin manager) already knows the anchor message id for
     // this lane+turn, initialize the stream with it so the next update
@@ -504,8 +489,8 @@ export async function handleStreamReply(
       threadId,
       parseMode,
       disableLinkPreview: deps.disableLinkPreview,
-      // PR B: pass undefined when caller didn't override, so draft-stream's
-      // transport-aware default (300 ms draft / 1000 ms message) wins.
+      // Pass undefined when caller didn't override, so draft-stream's
+      // DM/group throttle defaults apply (400 ms DMs, 1000 ms groups).
       ...(deps.throttleMs != null ? { throttleMs: deps.throttleMs } : {}),
       retry: deps.retry,
       ...(replyToMessageId != null ? { replyToMessageId } : {}),
@@ -513,9 +498,7 @@ export async function handleStreamReply(
       ...(args.protect_content === true ? { protectContent: true } : {}),
       ...(args.disable_notification === true ? { disableNotification: true } : {}),
       ...(args.reply_markup != null ? { replyMarkup: args.reply_markup } : {}),
-      previewTransport: resolvedTransport,
       isPrivateChat: deps.isPrivateChat === true,
-      ...(deps.sendMessageDraft != null ? { sendMessageDraft: deps.sendMessageDraft } : {}),
       ...(initialMessageId != null ? { initialMessageId } : {}),
       onSend: (messageId, charCount) =>
         deps.logStreamingEvent({ kind: 'draft_send', chatId: chat_id, messageId, charCount }),
@@ -539,7 +522,6 @@ export async function handleStreamReply(
           || msg.startsWith('stream → edited')
           || msg.startsWith('stream → not modified')
           || msg.startsWith('stream finalized')
-          || msg.startsWith('stream → draft')
           || msg.startsWith('stream → materialized')
         ) return
         deps.writeError(`telegram channel: stream_reply ${msg}\n`)

package/telegram-plugin/streaming-metrics.ts

@@ -93,6 +93,97 @@ export type StreamingEvent =
       chatId: string
       messageId: number | undefined
     }
+  /**
+   * Emitted when maybeEarlyAckReaction fires the 👀 pre-coalesce reaction
+   * for a private-chat inbound. Lets operators see how often the fast-ack
+   * path triggers vs. the regular StatusReactionController path (#553 F2).
+   */
+  | {
+      kind: 'early_ack_reaction'
+      chatId: string
+      messageId: number
+      emoji: string
+    }
+  /**
+   * Emitted when a fresh StatusReactionController is installed for a new turn
+   * (group / non-DM path where the controller manages the whole reaction lifecycle).
+   */
+  | {
+      kind: 'status_reaction_install'
+      chatId: string
+      turnId: string
+      messageId: number
+    }
+  /**
+   * Emitted on every emoji transition inside a StatusReactionController.
+   * Lets operators trace the full queued→thinking→tool→done lifecycle and
+   * see how many state changes occur in a silent turn.
+   */
+  | {
+      kind: 'status_reaction_transition'
+      chatId: string
+      turnId: string
+      emoji: string
+    }
+  /**
+   * Emitted when StatusReactionController.finalize() / setDone() runs
+   * (controller disposed at turn_end or disconnect-flush). Terminal event.
+   */
+  | {
+      kind: 'status_reaction_dispose'
+      chatId: string
+      turnId: string
+      reason: 'done' | 'error' | 'disconnect' | 'undelivered'
+    }
+  /**
+   * Emitted when the FIRST text reply (reply or stream_reply) of a turn is
+   * sent to the user. `timeToFirstTextReplyMs` is the wall-clock delta from
+   * the inbound-received timestamp to the moment this reply tool fires.
+   * Issue #2527 instrumentation: reveals when a turn is reaction-only.
+   */
+  | {
+      kind: 'turn_reply_timing'
+      chatId: string
+      threadId: number | undefined
+      turnId: string
+      timeToFirstTextReplyMs: number
+    }
+  /**
+   * Emitted at turn_end when the turn produced ZERO text replies (only
+   * reaction-emoji transitions). This is the primary observable for the
+   * #2527 failure mode — the user sees only an emoji and the turn is done.
+   */
+  | {
+      kind: 'turn_no_reply_warn'
+      chatId: string
+      threadId: number | undefined
+      turnId: string
+      turnDurationMs: number
+      reactionCount: number
+    }
+  /**
+   * Emitted when the silence-poke framework-fallback fires and sends its
+   * "still working…" ping. Records the silence duration so operators can
+   * correlate with reaction-only turns.
+   */
+  | {
+      kind: 'silence_poke_fire'
+      chatId: string
+      threadId: number | undefined
+      silenceMs: number
+      fallbackKind: string
+    }
+  /**
+   * Emitted when the silence-poke handler short-circuits because the turn
+   * already ended cleanly during the silence window (the late-fire race).
+   */
+  | {
+      kind: 'silence_poke_skip'
+      chatId: string
+      threadId: number | undefined
+      silenceMs: number
+      skipReason: string
+    }
 
 /**
  * True iff the env gate is on. Re-read on every call so tests can toggle

package/telegram-plugin/subagent-watcher.ts

@@ -42,7 +42,8 @@ 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 { clipNarrative, describeToolUse } from './tool-activity-summary.js'
+import { REPLY_TOOLS, isDraftOfReply } from './narrative-dedup.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'
@@ -158,6 +159,27 @@ export interface WorkerEntry {
    *  failed handback's "what it reported before failing" slot when the
    *  worker left no narrative result of its own. */
   errorDetail?: string
+  /**
+   * Narrative-dedup gate state (JSONL-text-narrative primitive). A
+   * `sub_agent_text` block is held here for ONE lookahead step so the next
+   * `sub_agent_tool_use` / `sub_agent_turn_end` can decide draft-then-send
+   * (SUPPRESS — it duplicates the worker's reply) vs working-narration (SHOW
+   * — fire `onProgress({latestSummary})`). Null when nothing is pending. The
+   * pure decision lives in narrative-dedup.ts; this slot is the per-entry
+   * cursor. Mirrors the gateway's `turn.pendingNarrative`.
+   */
+  pendingNarrative?: { text: string } | null
+  /**
+   * NIT 3 (sub-agent turn_end symmetry). Most-recently-seen
+   * reply/stream_reply `input.text` for this sub-agent — the actual answer a
+   * FOREGROUND sub-agent delivered. `sub_agent_turn_end` resolves a trailing
+   * `sub_agent_text` block against THIS so a draft of the just-delivered
+   * answer is suppressed the same way main-agent step 3 does (conservative
+   * dedup). Undefined for background workers that never call a reply tool —
+   * their trailing narration still SHOWs, unchanged. Mirrors the gateway's
+   * `turn.lastReplyText`.
+   */
+  lastReplyText?: string
 }
 
 export interface SubagentWatcherConfig {
@@ -503,14 +525,20 @@ interface FsLike {
  * Backfill `jsonl_agent_id` for a sub-agent row that was inserted by the
  * PreToolUse hook (keyed on tool_use_id) but didn't yet know the JSONL stem.
  *
- * Strategy: read the `agent-<id>.meta.json` sibling Claude Code writes next
- * to each sub-agent JSONL. It carries the same `{ agentType, description }`
- * pair the parent passed to the Agent() tool. We match that pair to the
- * most-recent row in `subagents` where `jsonl_agent_id IS NULL` and link them.
+ * Strategy: read the `agent-<id>.meta.json` sibling that the Claude Code
+ * binary writes next to each sub-agent JSONL. It carries `{ agentType,
+ * description, toolUseId }` where `toolUseId` is the primary key of the
+ * `subagents` row — the same `event.tool_use_id` value the pretool hook
+ * (`subagent-tracker-pretool.mjs`) uses when it inserts the DB row. We use
+ * the direct `toolUseId` lookup first (exact PK match, race-safe); fall back
+ * to the fuzzy `(agentType, description)` match only when `toolUseId` is
+ * absent (older Claude Code versions that pre-date this field in the meta).
  *
  * Edge cases:
  *   - meta.json missing or unreadable: no-op (the row stays unlinked; liveness
  *     writes from this agent's JSONL won't land, but the system stays correct).
+ *   - `toolUseId` present but no matching row (hook crashed / race): fall
+ *     through to the fuzzy match so the link is still attempted.
  *   - Multiple in-flight rows with identical (agent_type, description): the
  *     most recently started one wins (FIFO matches dispatch order in practice).
  *   - Row already linked to a different agentId: SQL `WHERE jsonl_agent_id IS
@@ -526,7 +554,7 @@ export function backfillJsonlAgentId(
   log?: (msg: string) => void,
 ): void {
   const metaPath = jsonlPath.replace(/\.jsonl$/, '.meta.json')
-  let meta: { agentType?: string; description?: string }
+  let meta: { agentType?: string; description?: string; toolUseId?: string } | null
   try {
     const raw = readFileSync(metaPath, 'utf8')
     meta = JSON.parse(raw)
@@ -534,8 +562,8 @@ export function backfillJsonlAgentId(
     log?.(`subagent-watcher: backfill skip ${agentId} — meta.json not readable at ${metaPath}`)
     return
   }
-  if (!meta.agentType && !meta.description) {
-    log?.(`subagent-watcher: backfill skip ${agentId} — meta.json has no agentType/description`)
+  if (!meta || (!meta.agentType && !meta.description && !meta.toolUseId)) {
+    log?.(`subagent-watcher: backfill skip ${agentId} — meta.json has no agentType/description/toolUseId`)
     return
   }
 
@@ -545,27 +573,51 @@ export function backfillJsonlAgentId(
     .get(agentId)
   if (already != null) return
 
-  // Find the most-recent matching unmatched row.
-  const candidate = db
-    .prepare(`
-      SELECT id FROM subagents
-      WHERE jsonl_agent_id IS NULL
-        AND agent_type IS ?
-        AND description IS ?
-      ORDER BY started_at DESC
-      LIMIT 1
-    `)
-    .get(meta.agentType ?? null, meta.description ?? null) as { id: string } | null
-
-  if (candidate == null) {
-    log?.(`subagent-watcher: backfill no candidate for ${agentId} (type=${meta.agentType} desc=${meta.description})`)
+  // Primary path (Bug 1 fix): direct PK lookup via the toolUseId Claude Code
+  // writes to meta.json. The pretool hook inserts the row with `id =
+  // event.tool_use_id`, so this is an exact match with no ambiguity — no
+  // race, no description-collision, no fuzzy-match false-negative.
+  let candidateId: string | null = null
+  if (meta.toolUseId) {
+    const direct = db
+      .prepare('SELECT id FROM subagents WHERE id = ? AND jsonl_agent_id IS NULL LIMIT 1')
+      .get(meta.toolUseId) as { id: string } | null
+    if (direct != null) {
+      candidateId = direct.id
+      log?.(`subagent-watcher: backfill direct-key match ${agentId} → ${candidateId} (toolUseId=${meta.toolUseId})`)
+    } else {
+      log?.(`subagent-watcher: backfill direct-key miss ${agentId} toolUseId=${meta.toolUseId} — falling back to fuzzy match`)
+    }
+  }
+
+  // Fallback path: fuzzy (agentType, description) match for older Claude Code
+  // versions whose meta.json predates the toolUseId field.
+  if (candidateId == null && (meta.agentType || meta.description)) {
+    const fuzzy = db
+      .prepare(`
+        SELECT id FROM subagents
+        WHERE jsonl_agent_id IS NULL
+          AND agent_type IS ?
+          AND description IS ?
+        ORDER BY started_at DESC
+        LIMIT 1
+      `)
+      .get(meta.agentType ?? null, meta.description ?? null) as { id: string } | null
+    if (fuzzy != null) {
+      candidateId = fuzzy.id
+      log?.(`subagent-watcher: backfill fuzzy match ${agentId} → ${candidateId} (type=${meta.agentType} desc=${meta.description})`)
+    }
+  }
+
+  if (candidateId == null) {
+    log?.(`subagent-watcher: backfill no candidate for ${agentId} (toolUseId=${meta.toolUseId} type=${meta.agentType} desc=${meta.description})`)
     return
   }
 
   db
     .prepare('UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?')
-    .run(agentId, candidate.id)
-  log?.(`subagent-watcher: backfill linked ${agentId} → ${candidate.id}`)
+    .run(agentId, candidateId)
+  log?.(`subagent-watcher: backfill linked ${agentId} → ${candidateId}`)
 
   // Backfill parent_turn_key (gateway-side). The PreToolUse hook can't know
   // the gateway-minted Telegram turn_key (a chat+topic+turn key) — it only
@@ -588,7 +640,7 @@ export function backfillJsonlAgentId(
   try {
     const linkedRow = db
       .prepare('SELECT started_at, parent_turn_key FROM subagents WHERE id = ?')
-      .get(candidate.id) as { started_at: number; parent_turn_key: string | null } | null
+      .get(candidateId) as { started_at: number; parent_turn_key: string | null } | null
     if (linkedRow != null && linkedRow.parent_turn_key == null) {
       const turn = db
         .prepare(
@@ -600,12 +652,12 @@ export function backfillJsonlAgentId(
       if (turn?.turn_key != null) {
         db
           .prepare('UPDATE subagents SET parent_turn_key = ? WHERE id = ?')
-          .run(turn.turn_key, candidate.id)
-        log?.(`subagent-watcher: backfill parent_turn_key ${candidate.id} → ${turn.turn_key}`)
+          .run(turn.turn_key, candidateId)
+        log?.(`subagent-watcher: backfill parent_turn_key ${candidateId} → ${turn.turn_key}`)
       }
     }
   } catch (err) {
-    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidate.id} — ${(err as Error).message}`)
+    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidateId} — ${(err as Error).message}`)
   }
 }
 
@@ -743,6 +795,62 @@ export function readSubTail(
         if (errInfo.detail) entry.errorDetail = errInfo.detail.slice(0, SUBAGENT_RESULT_TEXT_MAX)
       }
       const events = projectSubagentLine(line, entry.agentId, startState)
+      // Narrative-dedup gate (JSONL-text-narrative primitive) — fire the
+      // narrative progress cue for a SHOWN sub_agent_text block. Identical
+      // shape to the inline #1720 onProgress below; factored out so the gate
+      // (stage-on-text, resolve-on-tool/turn_end) can replay a previously
+      // pending block exactly once. `latestSummary` carries the worker's
+      // narrative result (entry.lastResultText), never tool labels.
+      const fireNarrativeProgress = (): void => {
+        if (onProgress == null || entry.state !== 'running' || entry.historical) return
+        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,
+          })
+        } catch (cbErr) {
+          log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${(cbErr as Error).message}`)
+        }
+      }
+      // Resolve a pending sub-agent narrative against a lookahead event.
+      // SUPPRESS only when the pending block drafts a reply/stream_reply
+      // tool's text; otherwise SHOW (fire the cue). See narrative-dedup.ts §2b.
+      //
+      // Two lookahead shapes:
+      //   - sub_agent_tool_use: `toolName`/`toolInput` are the tool — suppress
+      //     a draft of THIS tool's reply text.
+      //   - sub_agent_turn_end: `toolName` is null. NIT 3 (turn_end symmetry):
+      //     a FOREGROUND sub-agent that called stream_reply/reply as its final
+      //     tool then emitted a trailing text block would, under the old
+      //     unconditional SHOW, surface a draft of the delivered answer. So at
+      //     turn_end we apply the SAME conservative dedup as main-agent step 3:
+      //     compare the trailing block against the worker's last reply text
+      //     (`entry.lastReplyText`) and suppress a draft. Background workers
+      //     never set lastReplyText, so their trailing narration still SHOWs.
+      const resolvePendingSubNarrative = (
+        toolName: string | null,
+        toolInput: Record<string, unknown> | undefined,
+      ): void => {
+        if (entry.pendingNarrative == null) return
+        const pending = entry.pendingNarrative
+        entry.pendingNarrative = null
+        if (toolName != null && REPLY_TOOLS.has(toolName)) {
+          const replyText = typeof toolInput?.text === 'string' ? (toolInput.text as string) : ''
+          if (isDraftOfReply(pending.text, replyText)) return // draft of the reply → SUPPRESS
+        } else if (toolName == null && entry.lastReplyText != null && entry.lastReplyText.length > 0) {
+          // turn_end path: suppress a trailing draft of the delivered answer.
+          if (isDraftOfReply(pending.text, entry.lastReplyText)) return
+        }
+        fireNarrativeProgress()
+      }
       for (const ev of events) {
         const idleSecBeforeBump = Math.round((now - entry.lastActivityAt) / 1000)
         entry.lastActivityAt = now
@@ -783,6 +891,17 @@ export function readSubTail(
           log?.(`subagent-watcher: stall cleared for ${entry.agentId} (activity resumed after ${idleSecBeforeBump}s — re-arming detection)`)
         }
         if (ev.kind === 'sub_agent_tool_use') {
+          // Narrative-dedup gate step 2: a sub_agent_text block was pending;
+          // this tool is the lookahead that decides it (SHOW unless it drafts
+          // a reply tool's text). Runs before the tool's own progress cue so
+          // a working preamble surfaces just ahead of its tool step.
+          resolvePendingSubNarrative(ev.toolName, ev.input)
+          // NIT 3: capture a foreground sub-agent's actual reply text so the
+          // turn_end path can suppress a trailing draft of it (see
+          // resolvePendingSubNarrative). Only REPLY_TOOLS carry the answer.
+          if (REPLY_TOOLS.has(ev.toolName) && typeof ev.input?.text === 'string') {
+            entry.lastReplyText = ev.input.text as string
+          }
           entry.toolCount++
           // P0 of #662: surface the most recent tool name + sanitised
           // arg so the driver's fleet-state shadow can render the
@@ -830,7 +949,7 @@ export function readSubTail(
           // set at dispatch time (from the parent Agent/Task tool_use input)
           // and must remain stable. Overwriting it with the sub-agent's first
           // narrative line caused a race-condition-dependent display (issue #352).
-          entry.lastSummaryLine = ev.text.split('\n')[0].trim().slice(0, 120)
+          entry.lastSummaryLine = clipNarrative(ev.text)
           // Retain the full text of the most recent narrative emission —
           // for a worker the final such line before turn_end IS its
           // result summary (the worker prompt asks it to "return a
@@ -841,29 +960,28 @@ export function readSubTail(
           // args or file content — consistent with the watcher's
           // "descriptions only" privacy posture.
           entry.lastResultText = ev.text.trim().slice(0, SUBAGENT_RESULT_TEXT_MAX)
-          // #1720: surface a progress cue for the gateway. Only fire
-          // while the entry is still running and not historical — a
-          // terminal entry's last narrative line is the handback
-          // payload, not a mid-flight progress nudge.
-          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: number) => {
-                  entry.lastProgressBucketIdx = b
-                },
-                lastTool: entry.lastTool,
-                toolCount: entry.toolCount,
-              })
-            } catch (cbErr) {
-              log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${(cbErr as Error).message}`)
-            }
+          // #1720 + JSONL-text-narrative gate step 1: stage this block for
+          // one lookahead step instead of firing the progress cue
+          // immediately. A previously-pending block had nothing reply-shaped
+          // after it (pure narration) → flush it as SHOWN now; then stage
+          // THIS block. Its eventual SHOW/SUPPRESS is decided by the next
+          // sub_agent_tool_use / sub_agent_turn_end. `lastResultText` /
+          // `lastSummaryLine` above already updated unconditionally — the
+          // handback payload is independent of the progress-cue decision.
+          if (entry.pendingNarrative != null) {
+            fireNarrativeProgress() // prior pending was pure narration → SHOW
           }
+          entry.pendingNarrative = { text: ev.text }
         } else if (ev.kind === 'sub_agent_turn_end') {
+          // Narrative-dedup gate step 3: a trailing sub_agent_text block with
+          // nothing after it. SUPPRESS only when it drafts the foreground
+          // sub-agent's delivered reply (entry.lastReplyText, set above on a
+          // REPLY_TOOL tool_use) — symmetric with main-agent step 3; otherwise
+          // SHOW. Background workers never set lastReplyText, so their trailing
+          // narration still SHOWs. The worker's result is carried separately
+          // via lastResultText/onFinish, so a SHOWN trailing cue here is purely
+          // the transient liveness beat.
+          resolvePendingSubNarrative(null, undefined)
           if (entry.state === 'running') {
             entry.state = 'done'
             // Bug 2 fix (#333): mark the DB row completed via watcher's turn_end
@@ -1456,25 +1574,53 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
         const subagentsPath = join(projectPath, sDir, 'subagents')
         if (!fs.existsSync(subagentsPath)) continue
 
-        // Watch the subagents dir for new files if not already watching
-        if (!dirWatchers.has(subagentsPath)) {
-          try {
-            const w = fs.watch(subagentsPath, (_event, filename) => {
-              if (!filename || !filename.toString().startsWith('agent-') || !filename.toString().endsWith('.jsonl')) return
-              const filePath = join(subagentsPath, filename.toString())
-              if (!knownFiles.has(filePath)) {
-                scanSubagentsDir(subagentsPath)
-              }
-            })
-            dirWatchers.set(subagentsPath, w)
-            log?.(`subagent-watcher: watching dir ${subagentsPath}`)
-          } catch (err) {
-            log?.(`subagent-watcher: dir watch failed ${subagentsPath}: ${(err as Error).message}`)
+        // Watch a single flat subagents dir and scan its agent-*.jsonl files.
+        // Reused for both the base subagents/ dir and each workflow sub-dir.
+        const watchAndScan = (dirPath: string): void => {
+          if (!dirWatchers.has(dirPath)) {
+            try {
+              const w = fs.watch(dirPath, (_event, filename) => {
+                if (!filename || !filename.toString().startsWith('agent-') || !filename.toString().endsWith('.jsonl')) return
+                const filePath = join(dirPath, filename.toString())
+                if (!knownFiles.has(filePath)) {
+                  scanSubagentsDir(dirPath)
+                }
+              })
+              dirWatchers.set(dirPath, w)
+              log?.(`subagent-watcher: watching dir ${dirPath}`)
+            } catch (err) {
+              log?.(`subagent-watcher: dir watch failed ${dirPath}: ${(err as Error).message}`)
+            }
           }
+          scanSubagentsDir(dirPath)
         }
 
-        // Scan existing files
-        scanSubagentsDir(subagentsPath)
+        // Register the base subagents dir
+        watchAndScan(subagentsPath)
+
+        // Workflow sub-agents (spawned by the Workflow tool) write to:
+        //   subagents/workflows/wf_<id>/agent-<id>.jsonl
+        // The flat readdir above misses these because it only sees the
+        // "workflows" directory entry (not matching agent-*.jsonl). Descend
+        // one level so each wf_*/ dir gets the same watch+scan treatment.
+        const workflowsPath = join(subagentsPath, 'workflows')
+        if (fs.existsSync(workflowsPath)) {
+          let wfDirs: string[]
+          try {
+            wfDirs = fs.readdirSync(workflowsPath) as string[]
+          } catch { continue }
+          for (const wfDir of wfDirs) {
+            try {
+              const wfPath = join(workflowsPath, wfDir)
+              // Only descend into actual directories. statSync succeeds on
+              // regular files too (e.g. a stray journal.jsonl or lock file
+              // sitting directly in workflows/), so check isDirectory()
+              // explicitly rather than relying on a throw that never comes.
+              if (!fs.statSync(wfPath).isDirectory()) continue
+              watchAndScan(wfPath)
+            } catch { /* skip entries we can't stat or watch */ }
+          }
+        }
       }
     }
   }