switchroom 0.18.32 → 0.19.0

package/telegram-plugin/tests/worker-feed-coalesce.test.ts

@@ -186,12 +186,20 @@ describe('coalesced worker feed — one message per chat under load', () => {
     // would shed ~ (N-1)/N of every second's cosmetic edits.
     expect(gate.stats().global.shed).toBeLessThanOrEqual(3)
 
-    // Liveness: the LAST landed edit carries EVERY worker's latest step — all
-    // rows refreshed together in the one message within one edit cycle.
+    // Liveness + bounded card (#3349): under Ken's curve every SHOWN worker
+    // keeps depth 3, so a 15-way storm cannot render every row — the 24-line
+    // body ceiling collapses the newest rows into a `+N more working…` spill.
+    // The last landed edit still carries the VISIBLE workers' latest steps
+    // (refreshed together in the one message) and a spill marker for the rest.
     const lastBody = edits[edits.length - 1].text
-    for (const id of ids) {
-      expect(lastBody).toContain(latest[id])
+    // 6 rows fit the 24-line budget (6·(1 header + 3 depth) = 24); the oldest
+    // rows (w0…w5) stay visible, the 9 newest spill.
+    for (let i = 0; i < 6; i++) {
+      expect(lastBody).toContain(latest[`w${i}`])
     }
+    expect(lastBody).toContain('more working')
+    // Still exactly ONE message — the spill is a render detail, not a new send.
+    expect(sends.length).toBe(1)
   })
 
   it('admits a critical reply mid-storm (never shed or starved by the cosmetic feed)', async () => {
@@ -722,21 +730,23 @@ describe('renderCombinedWorkerFeed (pure)', () => {
     expect(body).toContain('b first')
   })
 
-  it('degrades to ONE history line per worker at a large fan-out and stays within the body budget', () => {
+  it('holds the MIN_WORKER_DEPTH (3) floor per shown worker at a large fan-out and stays within the body budget (#3349)', () => {
+    // 6 workers each with a deep (5-line) history. Ken's curve pins depth=3 at
+    // 4+ workers, so every SHOWN worker paints its last 3 steps. 6·(1 header +
+    // 3 history) = 24 lines = MAX_COMBINED_BODY_LINES, so all 6 stay visible.
     const rows = Array.from({ length: 6 }, (_, i) =>
-      rowH(i, [`w${i} oldest`, `w${i} middle`, `w${i} newest`]),
+      rowH(i, [`w${i} s1`, `w${i} s2`, `w${i} s3`, `w${i} s4`, `w${i} s5`]),
     )
     const body = renderCombinedWorkerFeed(rows, { maxRows: 8 })!
-    // Only the newest step of each worker survives — the earlier lines are
-    // dropped by the per-worker depth clamp (floor((13-6)/6)=1).
     for (let i = 0; i < 6; i++) {
-      expect(body).toContain(current(`w${i} newest`))
-      expect(body).not.toContain(`w${i} oldest`)
-      expect(body).not.toContain(`w${i} middle`)
+      // Last 3 steps shown; the two oldest dropped by the depth-3 window.
+      expect(body).toContain(current(`w${i} s5`))
+      expect(body).toContain(struck(`w${i} s4`))
+      expect(body).toContain(struck(`w${i} s3`))
+      expect(body).not.toContain(`w${i} s1`)
+      expect(body).not.toContain(`w${i} s2`)
     }
-    // Total body lines (worker headers + history) stay within the budget: 6
-    // header lines + 6 history lines = 12 ≤ MAX_COMBINED_BODY_LINES (13). Count
-    // only the per-worker body lines (exclude the top count line + any spill).
+    // Body lines (worker headers + history) stay within the re-derived budget.
     const bodyLines = body
       .split('\n')
       .map((l) => l.trim())
@@ -744,15 +754,43 @@ describe('renderCombinedWorkerFeed (pure)', () => {
     const headerAndHistory = bodyLines.filter(
       (l) => !l.startsWith('🛠') && !l.includes('more working'),
     )
-    expect(headerAndHistory.length).toBeLessThanOrEqual(13)
+    expect(headerAndHistory.length).toBeLessThanOrEqual(24)
   })
 
-  it('exposes the deterministic depth formula (2→5, 3→3, 4→2, 6→1)', () => {
+  it('drops NEWEST (trailing) rows into the spill when the fan-out overflows the 24-line body budget, keeping per-worker depth at 3 (#3349)', () => {
+    // 8 workers × (1 header + 3 depth) = 32 > 24 → the backstop collapses the 2
+    // newest (trailing) visible rows into `+M more working…`, so 6 rows render at full
+    // depth-3 (24 lines) rather than every worker losing a step.
+    const rows = Array.from({ length: 8 }, (_, i) =>
+      rowH(i, [`w${i} s1`, `w${i} s2`, `w${i} s3`]),
+    )
+    const body = renderCombinedWorkerFeed(rows, { maxRows: 8 })!
+    expect(body).toContain('more working')
+    const bodyLines = body
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+    const headerAndHistory = bodyLines.filter(
+      (l) => !l.startsWith('🛠') && !l.includes('more working'),
+    )
+    expect(headerAndHistory.length).toBeLessThanOrEqual(24)
+    expect(body).toContain('+2 more working')
+    // The 6 kept rows render at full depth-3 (last row kept shows all 3 steps).
+    expect(body).toContain(current('w5 s3'))
+    expect(body).toContain(struck('w5 s2'))
+    expect(body).toContain(struck('w5 s1'))
+    // The 2 trailing rows spilled — none of worker 7's lines render.
+    expect(body).not.toContain('w7 s3')
+  })
+
+  it("exposes Ken's deterministic depth curve max(3, 7−w): 1→6, 2→5, 3→4, 4→3, 5+→3 (#3349)", () => {
+    expect(combinedHistoryDepth(1)).toBe(6)
     expect(combinedHistoryDepth(2)).toBe(5)
-    expect(combinedHistoryDepth(3)).toBe(3)
-    expect(combinedHistoryDepth(4)).toBe(2)
-    expect(combinedHistoryDepth(6)).toBe(1)
-    expect(combinedHistoryDepth(8)).toBe(1)
+    expect(combinedHistoryDepth(3)).toBe(4)
+    expect(combinedHistoryDepth(4)).toBe(3)
+    expect(combinedHistoryDepth(5)).toBe(3)
+    expect(combinedHistoryDepth(6)).toBe(3)
+    expect(combinedHistoryDepth(8)).toBe(3)
   })
 
   // ── Worker numbering (#3298): stable ordinal prefix at 2+ workers ──────────
@@ -798,6 +836,58 @@ describe('renderCombinedWorkerFeed (pure)', () => {
   })
 })
 
+// ── #3349: Ken's per-worker depth curve 6/5/4/3, exact rendered depth ─────────
+describe("Ken's per-worker step-trail depth curve (#3349)", () => {
+  // A worker with a DEEP history (8 lines) so the depth curve — not the buffer —
+  // is always the binding limit. Each history line is uniquely tokenised
+  // (`w{i}-s{n}`) so we can count exactly how many of a worker's steps rendered.
+  const deepRow = (i: number) => ({
+    description: `task w${i}`,
+    elapsedMs: 12_000 + i * 1000,
+    toolCount: 3,
+    ordinal: i + 1,
+    currentStep: `w${i}-s8`,
+    historyLines: Array.from({ length: 8 }, (_, n) => `w${i}-s${n + 1}`),
+  })
+  // Count how many of worker `i`'s step tokens appear in the rendered body.
+  const shownSteps = (body: string, i: number): number =>
+    (body.match(new RegExp(`w${i}-s\\d`, 'g')) ?? []).length
+
+  it.each([
+    [1, 6],
+    [2, 5],
+    [3, 4],
+    [4, 3],
+    [5, 3],
+  ])('%i worker(s) → exactly %i steps rendered per worker', (workers, expectedDepth) => {
+    const rows = Array.from({ length: workers }, (_, i) => deepRow(i))
+    const body = renderCombinedWorkerFeed(rows, { maxRows: 8 })!
+    expect(combinedHistoryDepth(workers)).toBe(expectedDepth)
+    for (let i = 0; i < workers; i++) {
+      expect(shownSteps(body, i)).toBe(expectedDepth)
+    }
+    // Newest step last (bottom-anchored → bold), oldest rendered step struck.
+    const worker0 = `**→ w0-s8**`
+    expect(body).toContain(worker0)
+  })
+
+  it('a worker with FEWER steps than the depth shows all it has, no padding', () => {
+    // 3 workers → depth 4, but this worker only has 2 steps: render both, no more.
+    const rows = [
+      { description: 'shallow', elapsedMs: 12_000, toolCount: 1, ordinal: 1,
+        currentStep: 'only-b', historyLines: ['only-a', 'only-b'] },
+      deepRow(1),
+      deepRow(2),
+    ]
+    const body = renderCombinedWorkerFeed(rows, { maxRows: 8 })!
+    expect(combinedHistoryDepth(3)).toBe(4)
+    expect(body).toContain('~~_✓ only-a_~~')
+    expect(body).toContain('**→ only-b**')
+    // Deep workers still get their full 4.
+    expect(shownSteps(body, 1)).toBe(4)
+  })
+})
+
 /**
  * Worker-feed ghost-leak (immortal/unpinned/buried card) — outcome tests.
  *

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) {
@@ -659,38 +670,65 @@ export interface CombinedWorkerRow {
 
 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:
@@ -720,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.
  */
@@ -758,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),
+  }
 }
 
 /**