switchroom 0.18.31 → 0.18.33

package/telegram-plugin/tests/worker-feed-resume-guard.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Issue #3373 follow-up (PR #3376 adversarial review) — guards for the
+ * SendMessage-resume → feed re-surface seam.
+ *
+ * The #3376 fix has three links: the watcher fires `onResume` on jsonl growth
+ * past a genuine terminal (pinned by subagent-watcher-resume-reregister.test.ts),
+ * the gateway's `onResume` handler delegates to `handleWorkerResume`, and
+ * `handleWorkerResume` calls `feed.resurrect(agentId)` to clear the terminal
+ * `finalized` latch. The review found the middle + last links untested: deleting
+ * the gateway handler (or gutting its body) left every test green. This file
+ * closes both:
+ *
+ *   1. UNIT — `handleWorkerResume` calls `feed.resurrect` with the agentId,
+ *      never throws when resurrect throws or the feed is absent, and always
+ *      emits the re-surface audit line.
+ *   2. SOURCE SCAN (mirrors permission-verdict-resume-guard.test.ts) — the
+ *      gateway wires an `onResume:` callback into the watcher config AND that
+ *      callback delegates to `handleWorkerResume`. Deleting the handler, or
+ *      replacing the delegation with a no-op body, reds this suite.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { handleWorkerResume } from '../gateway/worker-feed-dispatch.js'
+
+describe('handleWorkerResume (issue #3373 seam unit)', () => {
+  it('calls feed.resurrect with the agentId and logs the re-surface line', () => {
+    const calls: string[] = []
+    const logs: string[] = []
+    handleWorkerResume({ resurrect: (id) => calls.push(id) }, 'w1', (m) => logs.push(m))
+    expect(calls).toEqual(['w1'])
+    expect(logs.some((l) => l.includes('w1') && l.includes('RE-SURFACED'))).toBe(true)
+  })
+
+  it('a throwing resurrect is logged, never propagated (watcher poll loop safety)', () => {
+    const logs: string[] = []
+    expect(() =>
+      handleWorkerResume(
+        { resurrect: () => { throw new Error('boom') } },
+        'w2',
+        (m) => logs.push(m),
+      ),
+    ).not.toThrow()
+    expect(logs.some((l) => l.includes('boom') && l.includes('w2'))).toBe(true)
+    // The audit line still lands after the failure.
+    expect(logs.some((l) => l.includes('RE-SURFACED'))).toBe(true)
+  })
+
+  it('a null/undefined feed (feed disabled) is a safe no-op that still audits', () => {
+    const logs: string[] = []
+    expect(() => handleWorkerResume(null, 'w3', (m) => logs.push(m))).not.toThrow()
+    expect(logs.some((l) => l.includes('w3') && l.includes('RE-SURFACED'))).toBe(true)
+  })
+})
+
+describe('gateway onResume wiring (issue #3373 source-scan guard)', () => {
+  const __dirname = dirname(fileURLToPath(import.meta.url))
+  const GATEWAY_SRC = readFileSync(
+    resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+    'utf8',
+  )
+
+  it('the watcher config carries an onResume callback', () => {
+    expect(/\bonResume:\s*\(/.test(GATEWAY_SRC)).toBe(true)
+  })
+
+  it('the onResume callback delegates to handleWorkerResume (not an inline no-op)', () => {
+    // Match the `onResume: (…) => { … }` callback body and require the
+    // delegation call inside it. A gutted handler (empty body / dropped
+    // resurrect) fails here even though tsc stays green.
+    const m = GATEWAY_SRC.match(/\bonResume:\s*\([^)]*\)\s*=>\s*\{([\s\S]*?)\n\s{14}\},/)
+    expect(m, 'onResume callback not found in gateway.ts').not.toBeNull()
+    expect(m![1]).toMatch(/\bhandleWorkerResume\s*\(/)
+    expect(m![1]).toMatch(/\bworkerActivityFeed\b/)
+  })
+
+  it('handleWorkerResume is imported from worker-feed-dispatch (the tested seam)', () => {
+    expect(
+      /import\s*\{[^}]*\bhandleWorkerResume\b[^}]*\}\s*from\s*'\.\/worker-feed-dispatch\.js'/.test(
+        GATEWAY_SRC,
+      ),
+    ).toBe(true)
+  })
+})

package/telegram-plugin/tool-activity-summary.ts

@@ -86,6 +86,7 @@ export function describeToolUse(
 import {
   STATUS_CARD_CHAR_BUDGET,
   STATUS_ROLLING_LINES,
+  WORKER_HISTORY_MAX,
   STATUS_LINE_MAX,
   NESTED_PREFIX,
 } from './status-no-truncate.js'
@@ -286,7 +287,8 @@ function escapeStepLine(raw: string): string {
 
 /**
  * Shared step-feed emitter. Appends `✓`/`→` bullet lines to `out` for the
- * given ALREADY-ESCAPED step strings, windowing to STATUS_ROLLING_LINES and
+ * given ALREADY-ESCAPED step strings, windowing to `window` (default
+ * STATUS_ROLLING_LINES; the worker surfaces pass a deeper window) and
  * prepending a `+N earlier…` header when the feed overflows the window (on
  * BOTH surfaces now). The worker feed imports this directly.
  *
@@ -301,9 +303,10 @@ export function renderStepFeed(
   steps: string[],
   allDone: boolean,
   liveSuffix = '',
+  window: number = STATUS_ROLLING_LINES,
 ): void {
   if (steps.length === 0) return
-  const shown = steps.slice(-STATUS_ROLLING_LINES)
+  const shown = steps.slice(-Math.max(1, window))
   const hidden = steps.length - shown.length
   if (hidden > 0) out.push(`_✓ +${hidden} earlier…_`)
   const lastIdx = shown.length - 1
@@ -351,6 +354,13 @@ export interface StatusCardOpts {
   stepCount?: number
   /** Optional terminal result block (worker recap), already-cleaned text + emoji. */
   result?: { emoji: string; text: string }
+  /**
+   * How many trailing step/child lines the rolling window shows. Defaults to
+   * STATUS_ROLLING_LINES (the 🤖 agent card). The 🛠 single-worker card passes
+   * a deeper window (`workerHistoryDepth(1)` = 6) so a lone worker can show its
+   * full recent trail — see WORKER_HISTORY_MAX.
+   */
+  historyWindow?: number
 }
 
 /**
@@ -364,6 +374,7 @@ export interface StatusCardOpts {
  */
 export function renderStatusCard(opts: StatusCardOpts): string | null {
   const { header, final = false, liveSuffix = '', stepCount, result } = opts
+  const window = Math.max(1, opts.historyWindow ?? STATUS_ROLLING_LINES)
   const rawSteps = opts.steps.filter((s) => s != null)
   const rawChildren = (opts.childSteps ?? []).map((s) => s.trim()).filter((s) => s.length > 0)
   const hasChildren = rawChildren.length > 0
@@ -393,12 +404,12 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
 
   if (hasChildren) {
     // Parent lines all render done — the live → step lives in the nested block.
-    const shownParent = steps.slice(-STATUS_ROLLING_LINES)
+    const shownParent = steps.slice(-window)
     const hiddenParent = steps.length - shownParent.length
     if (hiddenParent > 0) out.push(`_✓ +${hiddenParent} earlier…_`)
     for (const s of shownParent) out.push(`~~_✓ ${s}_~~`)
     // Child block.
-    const shownChild = children.slice(-STATUS_ROLLING_LINES)
+    const shownChild = children.slice(-window)
     const hiddenChild = children.length - shownChild.length
     if (hiddenChild > 0) out.push(`${NESTED_PREFIX}_+${hiddenChild} earlier…_`)
     const lastChildIdx = shownChild.length - 1
@@ -410,7 +421,7 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
       )
     })
   } else {
-    renderStepFeed(out, steps, final, liveSuffix)
+    renderStepFeed(out, steps, final, liveSuffix, window)
   }
 
   if (final && stepCount != null && stepCount > 0) {
@@ -646,54 +657,96 @@ export interface CombinedWorkerRow {
   /** Running total tokens for this worker — rendered as `· {N} tok` on the row
    *  header. Omitted (0/undefined) → no token segment. */
   totalTokens?: number
+  /**
+   * Stable per-card ordinal (1-based), assigned when the worker joins its feed
+   * group and KEPT for the card's lifetime — survivors keep their numbers when
+   * an earlier worker finishes (the card may show `2.`/`3.` with no `1.`; the
+   * `N running` chrome carries the count). Rendered as a `{ordinal}. ` prefix
+   * inside the bold header when the card has 2+ rows. Omitted → unnumbered
+   * (back-compat for direct callers).
+   */
+  ordinal?: number
 }
 
 export interface CombinedWorkerFeedOpts {
   /** Max worker rows rendered before the `+M more working…` spill line.
-   *  The overflow is ordered oldest-hidden-first (the newest/most-recently
-   *  active workers stay visible). */
+   *  Rows are kept head-first (`rows.slice(0, visibleCount)`): the earliest
+   *  supplied (oldest dispatch-order) workers stay visible and the
+   *  newest/trailing rows spill. */
   maxRows: number
 }
 
+/** Each visible worker costs one header line before any history. */
+const PER_WORKER_HEADER_COST = 1
+
+/**
+ * Floor of the per-worker depth curve — every SHOWN worker renders at least
+ * this many recent steps, no matter how large the fan-out (Ken's "4+ → 3 each").
+ */
+const MIN_WORKER_DEPTH = 3
+
+/**
+ * Design fan-out: the largest concurrent-worker count whose full Ken curve is
+ * allowed to render before the total-line backstop starts collapsing the
+ * NEWEST (trailing) rows into `+M more working…`. Chosen at 6 — beyond six live workers a
+ * per-worker trail is no longer a glanceable card, so extra rows spill rather
+ * than every shown worker losing depth. Every worker that IS shown keeps its
+ * full curve depth; the ceiling trims row COUNT, never per-worker depth.
+ */
+const DESIGN_FANOUT = 6
+
 /**
  * Total per-worker BODY line budget for the combined feed — the sum, across all
  * visible workers, of (one header line + that worker's history lines). The top
  * `🛠 Workers · N running` line and the `+M more working…` spill are OUTSIDE
- * this budget (fixed chrome). 13 is chosen so the card stays a compact glance,
- * not a wall: at 2 workers it yields the full 5-line history each (2·1 header +
- * 2·5 history = 12 ≤ 13), and it degrades to a single history line each by ~6
- * workers — matching the pre-adaptive one-line-per-worker floor while never
- * letting a 2–3 worker fan-out lose its narrative trail.
+ * this budget (fixed chrome).
+ *
+ * Re-derived (#3349) to fit Ken's per-worker curve `max(3, 7 − w)` rather than
+ * to DRIVE the depth: at the flat tail (w ≥ 4, depth = MIN_WORKER_DEPTH) each
+ * worker costs `PER_WORKER_HEADER_COST + MIN_WORKER_DEPTH` = 4 lines, so a
+ * DESIGN_FANOUT of 6 fully-rendered workers needs 6 × 4 = 24 lines. That fully
+ * fits every fan-out through 6 workers (w1=7, w2=12, w3=15, w4=16, w5=20,
+ * w6=24); a 7th/8th concurrent worker overflows and the backstop drops the
+ * newest (trailing) visible rows to the spill — bounding the card at 24 body lines so a
+ * big swarm never explodes it. The per-worker curve wins on DEPTH; this ceiling
+ * wins on ROW COUNT.
  */
-const MAX_COMBINED_BODY_LINES = 13
-/** Each visible worker costs one header line before any history. */
-const PER_WORKER_HEADER_COST = 1
+const MAX_COMBINED_BODY_LINES = DESIGN_FANOUT * (PER_WORKER_HEADER_COST + MIN_WORKER_DEPTH)
 
 /**
  * Deterministic per-worker history depth for `w` visible workers:
- *   clamp( floor( (BUDGET − headerCost·w) / w ), 1, STATUS_ROLLING_LINES )
- * So 2 workers → 5 lines each, 3 → 3, 4 → 2, ≥6 → 1 (today's single-line floor
- * is the graceful-degradation floor, never below it). Pure function of the
- * visible worker count — no model input, consistent with deterministic controls.
+ *   clamp( max(MIN_WORKER_DEPTH, 7 − w), 1, WORKER_HISTORY_MAX )
+ * So 1 worker → 6, 2 → 5, 3 → 4, 4 → 3, ≥4 → 3 (Ken's 6/5/4/3 curve, #3349).
+ * Pure function of the visible worker count — no model input, consistent with
+ * deterministic controls. Replaces the former budget-driven divide (which
+ * yielded 5/5/3/2/… and could never reach 6 for a lone worker).
  */
 export function combinedHistoryDepth(w: number): number {
   if (w <= 0) return 1
-  const raw = Math.floor((MAX_COMBINED_BODY_LINES - PER_WORKER_HEADER_COST * w) / w)
-  return Math.max(1, Math.min(STATUS_ROLLING_LINES, raw))
+  return Math.min(WORKER_HISTORY_MAX, Math.max(MIN_WORKER_DEPTH, 7 - w))
 }
 
+/** Alias for readability at the single-worker call site — same curve. */
+export const workerHistoryDepth = combinedHistoryDepth
+
 /**
  * Render N≥1 live workers into ONE combined feed body (ready Telegram
  * markdown; callers send verbatim — do NOT re-escape). Layout:
  *
  *   🛠 **Workers** · _N running_
- *   **{desc1}** _· {elapsed} · {n} tools_
+ *   **1. {desc1}** _· {elapsed} · {n} tools_
  *   ~~_✓ {earlier step}_~~
  *   **→ {newest step}**
- *   **{desc2}** _· {elapsed} · {n} tools_
+ *   **2. {desc2}** _· {elapsed} · {n} tools_
  *   **→ {newest step}**
  *   _+M more working…_
  *
+ * NUMBERING (#3298): when the card tracks 2+ rows AND a row carries `ordinal`,
+ * its header gets a stable `{ordinal}. ` prefix. Ordinals are assigned by the
+ * caller at dispatch and kept for the card's life — after an earlier worker
+ * finishes the survivors keep their numbers (`2.`, `3.` with no `1.`). A lone
+ * row, or rows without ordinals, render unnumbered.
+ *
  * ADAPTIVE DENSITY: each visible worker renders its last-K narrative lines as a
  * `✓`/`→` trail (prior steps struck, newest bold in-progress) — the single-
  * worker card's idiom — where K = `combinedHistoryDepth(visibleCount)` splits a
@@ -705,7 +758,7 @@ export function combinedHistoryDepth(w: number): number {
  * Pure. Rows are rendered in the order supplied (the manager passes them
  * dispatch-order, oldest first). `maxRows` caps the visible rows; the hidden
  * remainder collapses to a single `+M more working…` line. A total-budget
- * backstop drops the OLDEST visible rows one at a time (growing the spill)
+ * backstop drops the NEWEST (trailing) visible rows one at a time (growing the spill)
  * until the body fits STATUS_CARD_CHAR_BUDGET, so a burst of long descriptions
  * can never overflow the wire limit. Returns null only when `rows` is empty.
  */
@@ -716,6 +769,11 @@ export function renderCombinedWorkerFeed(
   if (rows.length === 0) return null
   const maxRows = Math.max(1, Math.floor(opts.maxRows))
 
+  // Number the workers only when the CARD tracks 2+ (a lone worker stays
+  // unnumbered). Uses the total row count, not the visible count, so ordinals
+  // don't appear/vanish as the overflow backstop shrinks the visible set.
+  const numbered = rows.length >= 2
+
   const rowHeader = (r: CombinedWorkerRow): string => {
     const desc = escapeMarkdown(
       truncate(stripMarkdown(r.description).replace(/\s+/g, ' ').trim() || 'background task', COMBINED_ROW_DESC_MAX),
@@ -724,7 +782,11 @@ export function renderCombinedWorkerFeed(
     const tokPart = tokenSegment(r.totalTokens)
     const modelLabel = formatModelLabel(r.model)
     const modelPart = modelLabel != null ? ` · ${escapeMarkdown(modelLabel)}` : ''
-    return `**${desc}** _· ${formatFeedElapsed(r.elapsedMs)} · ${r.toolCount} ${toolWord}${tokPart}${modelPart}_`
+    // Stable ordinal prefix INSIDE the bold span, before the already-escaped
+    // description — no new escaping surface, and the gateway md→HTML conversion
+    // has no ordered-list auto-formatting on bolded text.
+    const num = numbered && r.ordinal != null ? `${r.ordinal}. ` : ''
+    return `**${num}${desc}** _· ${formatFeedElapsed(r.elapsedMs)} · ${r.toolCount} ${toolWord}${tokPart}${modelPart}_`
   }
 
   // Raw (unescaped) history for a worker, oldest→newest, empty lines stripped.
@@ -734,37 +796,47 @@ export function renderCombinedWorkerFeed(
     return src.filter((s) => s != null && stripMarkdown(s).replace(/\s+/g, ' ').trim().length > 0)
   }
 
-  const compose = (visibleCount: number): string => {
+  const compose = (visibleCount: number): { body: string; bodyLines: number } => {
     const shown = rows.slice(0, visibleCount)
     const hidden = rows.length - shown.length
-    // Adaptive depth: split the fixed body-line budget across the VISIBLE
-    // workers so the card stays bounded regardless of fan-out.
+    // Per-worker depth follows Ken's deterministic curve max(3, 7−w) (#3349):
+    // the curve drives DEPTH; the total-line budget below drives ROW COUNT.
     const depth = combinedHistoryDepth(shown.length)
-    const out: string[] = [`🛠 **Workers** · _${rows.length} running_`]
+    const chrome: string[] = [`🛠 **Workers** · _${rows.length} running_`]
+    const bodyOut: string[] = []
     for (const r of shown) {
-      out.push(rowHeader(r))
+      bodyOut.push(rowHeader(r))
       const hist = rowHistory(r)
       if (hist.length === 0) {
-        out.push('→ _starting…_')
+        bodyOut.push('→ _starting…_')
         continue
       }
       // Paint the last-K history lines with the SAME `✓`/`→` idiom as the
       // single-worker card: escape each raw line through the shared per-line
       // pipeline (escapeStepLine), then renderStepFeed strikes the prior steps
-      // and bolds the newest in-progress step.
+      // and bolds the newest in-progress step. The window equals the depth so a
+      // per-worker `+N earlier…` marker never appears inside the combined feed.
       const esc = hist.slice(-depth).map(escapeStepLine)
-      renderStepFeed(out, esc, false)
+      renderStepFeed(bodyOut, esc, false, '', depth)
     }
+    const out = [...chrome, ...bodyOut]
     if (hidden > 0) out.push(`_+${hidden} more working…_`)
-    return stackCardLines(out)
+    return { body: stackCardLines(out), bodyLines: bodyOut.length }
   }
 
-  // Cap to maxRows first, then shrink further only if the char budget demands.
+  // Cap to maxRows first, then shrink the visible set while EITHER the total
+  // body-line budget (#3349: bounds a big swarm without stealing depth from the
+  // shown workers) OR the wire char budget is exceeded. Newest (trailing) rows
+  // collapse into the `+M more working…` spill (`rows.slice(0, visibleCount)`
+  // keeps the head of the list).
   let visible = Math.min(rows.length, maxRows)
-  let body = compose(visible)
-  while (body.length > STATUS_CARD_CHAR_BUDGET && visible > 1) {
+  let { body, bodyLines } = compose(visible)
+  while (
+    (bodyLines > MAX_COMBINED_BODY_LINES || body.length > STATUS_CARD_CHAR_BUDGET) &&
+    visible > 1
+  ) {
     visible -= 1
-    body = compose(visible)
+    ;({ body, bodyLines } = compose(visible))
   }
   return body
 }

package/telegram-plugin/turn-flush-safety.ts

@@ -155,28 +155,80 @@ export const FLUSH_SUBSTANTIVE_MIN_CHARS = 200
  * `[verboseNarration(250), realAnswer(150)]` a reversed length scan returns the
  * 250-char narration and DROPS the 150-char real answer. Instead we take the
  * last non-empty block as the answer and strip only the EARLIER blocks — and
- * only when they look like intent-narration (short, or the classic "Let me…" /
- * "I'll…" openers). If the earlier blocks are themselves substantial (a genuine
- * multi-paragraph answer written as several blocks) we keep the whole thing
- * joined, so we never truncate a real long answer down to its last paragraph.
+ * only when they look like intent-narration. If the earlier blocks are
+ * themselves substantial (a genuine multi-paragraph answer written as several
+ * blocks) we keep the whole thing joined, so we never truncate a real long
+ * answer down to its last paragraph.
+ *
+ * #3237 — the STRUCTURAL discriminator. The opener heuristic below
+ * (`isNarrationBlock`) cannot tell a narration preamble ("Let me pull the
+ * numbers…" followed by a separate reply) from a real answer paragraph that
+ * merely OPENS with "Let me explain…": both match the same regex, and length
+ * cannot separate them (the observed narration was itself ≥200 chars). The one
+ * signal that DOES separate them is structural — did a `tool_use` follow this
+ * block in the model's actual message? A narration preamble is drafted, then
+ * the model ACTS (a tool call follows it); a terminal answer paragraph is not
+ * followed by any tool call. That per-block flag (`lastInMessage`) is computed
+ * upstream by `projectAssistantTextBlocks` (session-tail.ts) and, when the
+ * caller plumbs it through as `followedByToolUse`, we consult STRUCTURE, but
+ * asymmetrically:
+ *   - present-and-FALSE (no tool_use followed) is purely additive — it can only
+ *     RESCUE a block the opener regex would have mis-stripped (a terminal answer
+ *     opening "Let me explain…"); it never drops a block the heuristic kept.
+ *   - present-and-TRUE (a tool_use followed) is NOT taken as narration on its
+ *     own: a substantial real-content paragraph can precede a tool call, so the
+ *     strip is GATED by the substance check (narration only if it also matches
+ *     the opener/trailer heuristic OR falls below the substantive floor). This
+ *     is deliberately not "strictly additive" over the opener-only strip — it
+ *     both rescues real content the old flag-alone path would have dropped and
+ *     stays truncation-free.
+ * Where the structural flag is ABSENT for a block (legacy `string[]` caller, or
+ * the accumulator lost provenance) we fall back to the opener/trailer heuristic
+ * for that block.
+ *
+ * `followedByToolUse` is a parallel array aligned to `blocks` (index `i` ⇒
+ * `blocks[i]`); it is zipped BEFORE the empty-block filter so alignment holds
+ * even if the caller passes empty/whitespace blocks. `undefined` at an index
+ * (or a missing/short array) means "no reliable structural signal for this
+ * block" → opener-heuristic fallback.
  *
  * `blocks` are already trimmed/non-empty candidates (silent markers removed by
  * the caller's guards). Returns the chosen delivery text.
  */
-export function selectFlushDeliveryText(blocks: string[]): string {
+export function selectFlushDeliveryText(
+  blocks: string[],
+  followedByToolUse?: ReadonlyArray<boolean | undefined>,
+): string {
   const candidates = blocks
-    .map(b => b.trim())
-    .filter(b => b.length > 0)
+    .map((b, i) => ({ text: b.trim(), followedByToolUse: followedByToolUse?.[i] }))
+    .filter(c => c.text.length > 0)
   if (candidates.length === 0) return ''
-  if (candidates.length === 1) return candidates[0]
-  const answer = candidates[candidates.length - 1]
+  if (candidates.length === 1) return candidates[0].text
+  const answer = candidates[candidates.length - 1].text
   const preceding = candidates.slice(0, -1)
   // Deliver only the terminal answer when every earlier block is
-  // intent-narration (a short block, or a "Let me…/I'll…/I'm going to…" opener).
+  // intent-narration. Per block:
+  //   - structural flag TRUE ⇒ a tool_use followed this block, but that alone
+  //     is NOT sufficient to drop it: a substantial real-content paragraph can
+  //     legitimately precede a tool call (the model writes a real answer, then
+  //     calls a memory/verify tool, then a short wrap-up). So gate the
+  //     structural strip with the substantive floor — narration only if the
+  //     block ALSO looks like narration OR is below the substantive floor.
+  //   - structural flag FALSE ⇒ present-and-false definitively overrides the
+  //     opener regex: no tool_use followed, so it is a terminal-style block,
+  //     never narration (#3237).
+  //   - structural flag ABSENT ⇒ fall back to the opener/trailer heuristic.
   // Otherwise the earlier blocks carry real content — keep the full joined text
-  // so a legitimate multi-block answer is never truncated to its last paragraph.
-  const allNarration = preceding.every(isNarrationBlock)
-  return allNarration ? answer : candidates.join('\n\n')
+  // so a legitimate multi-block answer is never truncated to its last
+  // paragraph (#3237).
+  const allNarration = preceding.every(c =>
+    c.followedByToolUse === true
+      ? isNarrationBlock(c.text) || c.text.trim().length < FLUSH_SUBSTANTIVE_MIN_CHARS
+      : c.followedByToolUse === false
+        ? false
+        : isNarrationBlock(c.text),
+  )
+  return allNarration ? answer : candidates.map(c => c.text).join('\n\n')
 }
 
 /**
@@ -244,6 +296,17 @@ export interface FlushDecisionInput {
    * is false — once the model has called reply / stream_reply the turn is
    * served and trailing terminal text is dropped (see `decideTurnFlush`). */
   capturedText: string[]
+  /** Optional per-block structural provenance, aligned to `capturedText`
+   * (index `i` describes `capturedText[i]`). `true` ⇒ a `tool_use` followed
+   * this text block in its assistant message (the draft-then-send narration
+   * signal — the negation of `projectAssistantTextBlocks`' `lastInMessage`).
+   * Consumed by `selectFlushDeliveryText` to separate a narration preamble from
+   * a real answer paragraph that merely opens with a narration phrase (#3237).
+   * When absent (legacy caller / lost provenance) the strip falls back to the
+   * opener/trailer heuristic. Present-and-false is additive (only rescues a
+   * mis-stripped terminal answer); present-and-true is gated by the substantive
+   * floor rather than trusted alone. */
+  capturedBlockMeta?: boolean[]
   /** Feature flag — defaults to true. Pass `false` to force skip everywhere. */
   flushEnabled?: boolean
 }
@@ -316,7 +379,10 @@ export function decideTurnFlush(input: FlushDecisionInput): FlushDecision {
   // blob (see `selectFlushDeliveryText`). The silent-marker / empty guards above
   // still run on the full `joined` string so a partly-silent turn is classified
   // correctly; only the DELIVERED text is narrowed to the answer.
-  return { kind: 'flush', text: selectFlushDeliveryText(input.capturedText) }
+  return {
+    kind: 'flush',
+    text: selectFlushDeliveryText(input.capturedText, input.capturedBlockMeta),
+  }
 }
 
 /**

package/telegram-plugin/uat/restart-capability.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared restart-capability probe + loud-skip announcer for the
+ * restart/resume UAT scenarios.
+ *
+ * These scenarios (`jtbd-deliberate-restart-resumes-dm`,
+ * `jtbd-interrupted-turn-resumes-dm`, `jtbd-always-on-after-restart-dm`)
+ * can only exercise a REAL restart when the runner has NOPASSWD `sudo` and
+ * the `switchroom` CLI on PATH. On a sandboxed runner that lacks those,
+ * `vitest`'s `describe.skip` marks them skipped — but a bare skip reads as
+ * a plain green in a summarised board, which is exactly how the v0.18.32
+ * UAT canary over-claimed "#3315 restart/resume validated" when in fact
+ * these three self-skipped (#3334 item d).
+ *
+ * The durable fix has two parts. Part 2 (a runner that can actually
+ * restart) is infrastructure and is tracked separately. Part 1 — this file
+ * — makes the skip LOUD and unmistakable: a single-source-of-truth probe
+ * plus a banner printed to stderr at collection time, so a green that is
+ * really a skip can never be silently indistinguishable from a green that
+ * ran live.
+ */
+
+import { execSync } from "node:child_process";
+
+/**
+ * True only when the runner can drive a real agent restart: NOPASSWD
+ * `sudo` is available (the scenarios shell out to
+ * `sudo -n switchroom agent restart …`). A sandboxed CI runner returns
+ * false, which routes the scenario to `describe.skip`.
+ */
+export function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Print a loud, unmissable banner to stderr when a restart/resume scenario
+ * is about to self-skip because the runner cannot exercise a real restart.
+ * Call this at module-collection time (top level of the scenario file) so
+ * the banner lands in CI stdout/stderr regardless of the reporter's
+ * skip-count rendering.
+ *
+ * The banner deliberately spells out that a GREEN here is a SKIP, not live
+ * proof — the exact confusion #3334 item d flags as "the dangerous one".
+ */
+export function announceRestartSkip(scenarioTitle: string): void {
+  console.warn(
+    "\n" +
+      "════════════════════════════════════════════════════════════════════\n" +
+      "  ⚠️  UAT SKIPPED — NOT LIVE-VALIDATED (restart capability absent)\n" +
+      `      scenario: ${scenarioTitle}\n` +
+      "      reason:   this runner has no NOPASSWD sudo + switchroom CLI, so\n" +
+      "                it cannot exercise a real agent restart. The scenario\n" +
+      "                self-skips. Its GREEN is a SKIP, not live proof.\n" +
+      "      see:      #3334 item (d) / #3315 — restart/resume assurance from\n" +
+      "                this run rests on the unit/vitest layer, not this UAT.\n" +
+      "════════════════════════════════════════════════════════════════════\n",
+  );
+}
+
+/**
+ * Convenience: probe capability once and, when absent, emit the loud-skip
+ * banner. Returns the capability boolean so the caller can gate
+ * `describe` vs `describe.skip`:
+ *
+ *   const sudoOk = restartCapableOrAnnounceSkip(TITLE);
+ *   (sudoOk ? describe : describe.skip)(TITLE, () => { … });
+ */
+export function restartCapableOrAnnounceSkip(scenarioTitle: string): boolean {
+  const ok = canShellSudo();
+  if (!ok) announceRestartSkip(scenarioTitle);
+  return ok;
+}

package/telegram-plugin/uat/scenarios/bg-sub-agent-dispatch-dm.test.ts

@@ -89,7 +89,17 @@ const BG_DISPATCH_PROMPT =
   `brief reply saying you've kicked off the background worker so I can ` +
   `watch the progress feed.`;
 
-const WORKER_RUNNING_RE = /running\s*·/i;
+// Single-worker RUNNING headers show NO literal "running" — they render
+// `<elapsed> · <n> tools[ · <tok> tok][ · <model>]`
+// (`tool-activity-summary.ts` renderActivityHeader, running branch); the
+// word "running" only appears on the MULTI-worker combined header
+// (`🛠 Workers · N running`). The old `/running\s*·/i` oracle matched only
+// by accident when the multi-worker header happened to render (failed live
+// 2026-07-18, ci-uat run 29634400115, against a healthy in-flight card).
+// In-flight signal = either header shape's live metric, paired with the
+// `not.toMatch(WORKER_DONE_RE)` terminal exclusion below — a skeleton that
+// paints only `🛠 Worker · <name>` with no metric line still fails.
+const WORKER_RUNNING_RE = /\brunning\b|·\s*\d+\s+tools?\b/i;
 const WORKER_DONE_RE = /finished\s*·\s*(completed|failed)/i;
 
 describe("uat: background sub-agent visibility (#709/#776/#782/#788)", () => {
@@ -117,9 +127,9 @@ describe("uat: background sub-agent visibility (#709/#776/#782/#788)", () => {
         expect(feed.messageId).toBeGreaterThan(0);
         expect(feed.text).toMatch(WORKER_FEED_RE);
 
-        // AC-2 step 1: feed body MUST show "running ·" (the in-flight
-        // status), NOT the terminal "finished ·" — the worker hasn't
-        // completed yet.
+        // AC-2 step 1: feed body MUST show an in-flight signal (live
+        // metric line, or multi-worker "N running"), NOT the terminal
+        // "finished ·" — the worker hasn't completed yet.
         expect(feed.text).toMatch(WORKER_RUNNING_RE);
         expect(feed.text).not.toMatch(WORKER_DONE_RE);
 

package/telegram-plugin/uat/scenarios/bridge-flap-resilience-dm.test.ts

@@ -123,8 +123,18 @@ describe("uat: bridge-flap resilience — agent stays responsive, gateway does n
             `overall deadline hit before DM ${i} — earlier turns were too slow`,
           ).toBeGreaterThan(0);
 
+          // Skip empty-text observations: the Bot API cannot send an
+          // empty text message (Telegram rejects it), so an empty-text
+          // fromBot observation is by construction a SERVICE message —
+          // e.g. the `[pinned_message]` event from the progress-card pin.
+          // One of those latched here as "the reply" on 2026-07-18
+          // (ci-uat run 29634400115: pinChatMessage 06:54:36.420Z → rx
+          // [pinned_message] 06:54:37.012Z, exactly at the DM-2 failure).
+          // A genuinely eaten turn_end still fails loudly: no non-empty
+          // reply arrives and this expectMessage times out.
           const reply = await sc.expectMessage(
-            (m: ObservedMessage) => m.fromBot && !m.edited,
+            (m: ObservedMessage) =>
+              m.fromBot && !m.edited && m.text.length > 0,
             { from: "bot", timeout: remaining },
           );
           expect(