switchroom 0.14.21 → 0.14.23

package/telegram-plugin/tests/subagent-watcher-handback-gaps.test.ts

@@ -0,0 +1,293 @@
+/**
+ * Tests for the two background-worker handback gaps closed in
+ * `fix/subagent-handback-restart-and-failure`:
+ *
+ *  Gap 1 — restart survival. A background worker that is in-flight when
+ *    the gateway restarts is discovered by the boot scan and tagged
+ *    `historical`. That flag is meant to suppress replay for workers that
+ *    ALREADY finished before boot — but it was also applied to workers
+ *    still running, which then completed with outcome `orphan`, and the
+ *    handback gate drops `orphan`. Net: dispatched worker + any gateway
+ *    bounce (incl. a fleet rollout) + worker finishes = user never told.
+ *    Fix: a file still `running` at boot is promoted to a LIVE entry, so
+ *    it gets the stall-synthesis safety net and a real `completed`/`failed`
+ *    handback. A file already `done` at boot stays suppressed.
+ *
+ *  Gap 2 — failure honesty. The `failed` outcome was dead code (no caller
+ *    set it), so every dead worker was reported `completed`. Fix: a
+ *    TERMINAL error line in the worker's own transcript (model API failure
+ *    / quota exhaustion / crash — not an in-flight retry, not a routine
+ *    tool-level is_error) flips the terminal outcome to `failed` and
+ *    carries the error detail into the handback result.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+import * as fs from 'fs'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentText(text: string) {
+  return { type: 'assistant', message: { content: [{ type: 'text', text }] } }
+}
+function subAgentTurnEnd() {
+  return { type: 'system', subtype: 'turn_duration', duration_ms: 1234 }
+}
+// A terminal error line in the worker's OWN transcript — the model call
+// itself failed (here an invalid_request_error). `detectErrorInTranscriptLine`
+// classifies an explicit `type:"error"` line with a non-rate-limit kind as
+// terminal:true.
+function subAgentTerminalError(message: string) {
+  return { type: 'error', error: { type: 'invalid_request_error', message } }
+}
+// A routine mid-run tool failure (e.g. a grep that found nothing). This is a
+// `sub_agent_tool_result` with is_error — NOT a worker death. Must NOT trip
+// the failed classification.
+function subAgentToolResultError() {
+  return {
+    type: 'user',
+    message: {
+      content: [{ type: 'tool_result', tool_use_id: 'toolu_x', is_error: true, content: 'no matches found' }],
+    },
+  }
+}
+
+interface FinishCall {
+  agentId: string
+  outcome: string
+  resultText: string
+}
+
+interface Harness {
+  stallTerminalCalls: Array<{ agentId: string }>
+  finishCalls: FinishCall[]
+  logs: string[]
+  advance: (ms: number) => void
+  watcher: ReturnType<typeof startSubagentWatcher>
+  fileContents: Map<string, Buffer>
+  jsonlPath: string
+  append: (...lines: object[]) => void
+}
+
+function makeHarness(opts: {
+  agentId?: string
+  /** Lines present in the JSONL at boot (before the watcher starts). */
+  bootLines: object[]
+  stallThresholdMs?: number
+  silentStallTerminalMs?: number
+  rescanMs?: number
+}): Harness {
+  const {
+    agentId = 'gap-agent',
+    bootLines,
+    stallThresholdMs = 60_000,
+    silentStallTerminalMs = 300_000,
+    rescanMs = 500,
+  } = opts
+
+  let currentTime = 1000
+  const stallTerminalCalls: Array<{ agentId: string }> = []
+  const finishCalls: FinishCall[] = []
+  const logs: string[] = []
+
+  const agentDir = '/home/user/.switchroom/agents/myagent'
+  const sessionId = 'mock-session'
+  const projectsRoot = `${agentDir}/.claude/projects`
+  const projectDir = `${projectsRoot}/mock-cwd`
+  const sessionDir = `${projectDir}/${sessionId}`
+  const subagentsDir = `${sessionDir}/subagents`
+  const jsonlPath = `${subagentsDir}/agent-${agentId}.jsonl`
+
+  const fileContents = new Map<string, Buffer>()
+  fileContents.set(jsonlPath, Buffer.from(buildJSONL(...bootLines), 'utf-8'))
+
+  let lastOpenedPath: string | null = null
+  const mockFs = {
+    existsSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot || ps === projectDir || ps === sessionDir || ps === subagentsDir) return true
+      if (fileContents.has(ps)) return true
+      return false
+    }) as typeof fs.existsSync,
+    readdirSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot) return ['mock-cwd']
+      if (ps === projectDir) return [sessionId]
+      if (ps === sessionDir) return ['subagents']
+      if (ps === subagentsDir) return [`agent-${agentId}.jsonl`]
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) => ({ size: fileContents.get(String(p))?.length ?? 0 }) as fs.Stats) as typeof fs.statSync,
+    openSync: ((p: fs.PathLike) => {
+      lastOpenedPath = String(p)
+      return 42
+    }) as unknown as typeof fs.openSync,
+    closeSync: (() => { lastOpenedPath = null }) as typeof fs.closeSync,
+    readSync: ((
+      _fd: number,
+      buf: NodeJS.ArrayBufferView,
+      offset: number,
+      length: number,
+      position: number | null,
+    ): number => {
+      const content = lastOpenedPath != null ? fileContents.get(lastOpenedPath) : undefined
+      if (!content) return 0
+      const pos = position ?? 0
+      const src = content.slice(pos, pos + length)
+      ;(src as Buffer).copy(buf as Buffer, offset)
+      return src.length
+    }) as unknown as typeof fs.readSync,
+    watch: (() => ({ close: vi.fn() }) as unknown as fs.FSWatcher) as unknown as typeof fs.watch,
+  }
+
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  let nextRef = 1
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    stallThresholdMs,
+    silentSynthesisStallThresholdMs: stallThresholdMs,
+    silentStallTerminalMs,
+    rescanMs,
+    onStallTerminal: (id) => stallTerminalCalls.push({ agentId: id }),
+    onFinish: ({ agentId: id, outcome, resultText }) =>
+      finishCalls.push({ agentId: id, outcome, resultText }),
+    now: () => currentTime,
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = intervals.findIndex((i) => i.ref === ref)
+      if (idx !== -1) intervals.splice(idx, 1)
+    },
+    fs: mockFs,
+    log: (msg) => logs.push(msg),
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      intervals.sort((a, b) => a.fireAt - b.fireAt)
+      const next = intervals[0]
+      if (!next || next.fireAt > currentTime) break
+      next.fireAt += next.ms
+      next.fn()
+    }
+  }
+
+  const append = (...lines: object[]): void => {
+    const cur = fileContents.get(jsonlPath) ?? Buffer.alloc(0)
+    const more = buildJSONL(...lines)
+    fileContents.set(jsonlPath, Buffer.concat([cur, Buffer.from(more, 'utf-8')]))
+  }
+
+  return { stallTerminalCalls, finishCalls, logs, advance, watcher, fileContents, jsonlPath, append }
+}
+
+describe('Gap 1 — background worker in-flight across a gateway restart', () => {
+  it('an in-flight-at-boot worker that completes hands back as completed (not orphan)', () => {
+    // Boot scan finds a running worker (prompt, no turn_end yet) → tagged
+    // historical. The fix promotes it to live. When it finishes under our
+    // watch, the outcome must be `completed` so the handback delivers.
+    const h = makeHarness({ agentId: 'gap1-complete', bootLines: [subAgentUserMsg('bg task')] })
+
+    // The worker finishes after the restart.
+    h.append(subAgentText('Found the root cause in auth.ts'), subAgentTurnEnd())
+    h.advance(600) // one poll reads the new bytes
+
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].agentId).toBe('gap1-complete')
+    expect(h.finishCalls[0].outcome).toBe('completed') // pre-fix: 'orphan' → dropped
+    expect(h.finishCalls[0].resultText).toContain('root cause')
+    // The promotion is logged so the path is observable in prod.
+    expect(h.logs.some((l) => l.includes('in-flight at boot — promoting to live'))).toBe(true)
+  })
+
+  it('an in-flight-at-boot worker that dies silently is rescued by stall synthesis', () => {
+    // Pre-fix, historical entries were skipped by stall detection, so a
+    // worker that crossed a restart and then went silent sat running
+    // forever — no handback ever. After promotion it gets the safety net.
+    const h = makeHarness({
+      agentId: 'gap1-silent',
+      bootLines: [subAgentUserMsg('bg task')],
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 120_000,
+    })
+
+    h.advance(62_000) // stall threshold crossed
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    h.advance(121_000) // silent-stall terminal window elapses → synthesis
+    expect(h.stallTerminalCalls).toHaveLength(1)
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('completed')
+  })
+
+  it('a worker already DONE at boot stays suppressed (no spurious replay)', () => {
+    // The legitimate use of `historical`: a worker that finished in a prior
+    // session must NOT re-fire a handback on every restart. This is the
+    // regression guard for the fix.
+    const h = makeHarness({
+      agentId: 'gap1-stale',
+      bootLines: [subAgentUserMsg('bg task'), subAgentText('done long ago'), subAgentTurnEnd()],
+    })
+
+    h.advance(600)
+    h.advance(600_000) // well past any stall window
+    expect(h.finishCalls).toHaveLength(0)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+  })
+})
+
+describe('Gap 2 — failure honesty', () => {
+  it('a terminal error line flips the outcome to failed and carries the detail', () => {
+    const h = makeHarness({ agentId: 'gap2-failed', bootLines: [subAgentUserMsg('bg task')] })
+
+    // The worker's model call errors out, then the transcript ends.
+    h.append(subAgentTerminalError('tool input rejected by the API'), subAgentTurnEnd())
+    h.advance(600)
+
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('failed')
+    // No narrative was emitted, so the detail backfills the result slot.
+    expect(h.finishCalls[0].resultText).toContain('tool input rejected')
+  })
+
+  it('a failed worker that went silent still synthesises terminal as failed', () => {
+    const h = makeHarness({
+      agentId: 'gap2-failed-silent',
+      bootLines: [subAgentUserMsg('bg task')],
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 120_000,
+    })
+
+    // Error line, then the worker goes silent (no turn_end).
+    h.append(subAgentTerminalError('worker process crashed'))
+    h.advance(600) // read the error line
+    h.advance(62_000) // stall
+    h.advance(121_000) // synthesis
+    expect(h.stallTerminalCalls).toHaveLength(1)
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('failed')
+    expect(h.finishCalls[0].resultText).toContain('crashed')
+  })
+
+  it('a routine mid-run tool error does NOT cause a false failure', () => {
+    const h = makeHarness({ agentId: 'gap2-toolerr', bootLines: [subAgentUserMsg('bg task')] })
+
+    // A tool_result with is_error (e.g. grep found nothing) mid-run, then
+    // the worker recovers and completes normally.
+    h.append(subAgentToolResultError(), subAgentText('Completed after a retry'), subAgentTurnEnd())
+    h.advance(600)
+
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('completed') // NOT failed
+    expect(h.finishCalls[0].resultText).toContain('Completed after a retry')
+  })
+})

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -693,18 +693,21 @@ describe('startSubagentWatcher', () => {
     h.watcher.stop()
   })
 
-  it('suppresses stall notifications for historical entries', () => {
-    // Historical entries (file existed at watcher boot) must NOT fire
-    // stall notifications. The sub-agent process is long dead; the file
-    // is just left over from a prior session. With many historicals
-    // present at restart, firing stalls for each would flood the chat.
+  it('suppresses stall notifications for historical (done-at-boot) entries', () => {
+    // A worker that already FINISHED before the watcher booted (turn_end
+    // present in the file) stays historical and must NOT fire stall
+    // notifications. With months of finished session history present at
+    // restart, firing stalls for each would flood the chat. NOTE: a worker
+    // still RUNNING at boot is a different case — Gap 1 promotes it to live
+    // so it DOES get the stall safety net (it's an in-flight worker the
+    // user is still awaiting), covered in subagent-watcher-handback-gaps.
     const agentDir = '/home/user/.switchroom/agents/myagent'
     const projectsRoot = `${agentDir}/.claude/projects`
     const projectDir = `${projectsRoot}/myproject`
     const sessionDir = `${projectDir}/session-abc123`
     const subagentsDir = `${sessionDir}/subagents`
     const jsonlPath = `${subagentsDir}/agent-deadbeef.jsonl`
-    const content = buildJSONL(subAgentUserMsg('Old task'))
+    const content = buildJSONL(subAgentUserMsg('Old task'), subAgentTurnDuration())
 
     const h = makeHarness({
       agentDir,
@@ -809,12 +812,15 @@ describe('startSubagentWatcher', () => {
 
   describe('historical-vs-active filter', () => {
     /**
-     * Pre-existing JSONL files at watcher boot are tagged historical=true.
-     * Stalls and completion notifications are gated on !historical so a
-     * restart with months of session history doesn't flood the chat.
+     * Pre-existing FINISHED (done-at-boot) JSONL files are tagged
+     * historical=true. Stalls and completion notifications are gated on
+     * !historical so a restart with months of session history doesn't
+     * flood the chat. (A still-RUNNING file at boot is promoted to live by
+     * Gap 1 — see subagent-watcher-handback-gaps — so it must carry a
+     * turn_end here to stay historical.)
      */
 
-    it('pre-existing JSONL files at startup are tagged historical', () => {
+    it('pre-existing done-at-boot JSONL files are tagged historical', () => {
       const agentDir = '/home/user/.switchroom/agents/myagent'
       const projectsRoot = `${agentDir}/.claude/projects`
       const projectDir = `${projectsRoot}/myproject`
@@ -823,7 +829,7 @@ describe('startSubagentWatcher', () => {
       const jsonlA = `${subagentsDir}/agent-hist-aaaa.jsonl`
       const jsonlB = `${subagentsDir}/agent-hist-bbbb.jsonl`
 
-      const content = buildJSONL(subAgentUserMsg('Old task'))
+      const content = buildJSONL(subAgentUserMsg('Old task'), subAgentTurnDuration())
 
       const h = makeHarness({
         agentDir,
@@ -895,10 +901,12 @@ describe('startSubagentWatcher', () => {
     })
 
     it('pre-existing in-flight agent that finishes after restart fires completion', () => {
-      // Historical at boot. Then writes turn_end. Completion notification
-      // still fires for the state transition (the file was in-flight at
-      // boot, so the transition is meaningful even if the entry is tagged
-      // historical for stall-suppression purposes).
+      // Running at boot → Gap 1 promotes it to live (historical=false),
+      // because it's an in-flight worker the user is still awaiting across
+      // the restart. When it then writes turn_end, the completion
+      // notification fires for the state transition. (The deeper handback
+      // outcome — completed, not the dropped `orphan` — is covered in
+      // subagent-watcher-handback-gaps.)
       const agentDir = '/home/user/.switchroom/agents/myagent'
       const projectsRoot = `${agentDir}/.claude/projects`
       const projectDir = `${projectsRoot}/myproject`

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

@@ -4,7 +4,9 @@ import {
   appendActivityLine,
   appendActivityLabel,
   renderActivityFeed,
+  renderActivityFeedWithNested,
   MIRROR_MAX_LINES,
+  NESTED_MAX_LINES,
 } from "../tool-activity-summary.js";
 
 describe("describeToolUse — friendly per-tool rendering (draft-mirror)", () => {
@@ -143,3 +145,45 @@ describe("appendActivityLabel — precomputed label feed (tool_label path)", ()
     expect(lines.length).toBe(2);
   });
 });
+
+describe("renderActivityFeedWithNested — foreground sub-agent nesting (Model A)", () => {
+  it("with no child lines, is identical to the flat feed", () => {
+    const lines = ["Searching memory", "Delegating: review the migration"];
+    expect(renderActivityFeedWithNested(lines, [])).toBe(renderActivityFeed(lines));
+    // whitespace-only children also collapse to the flat feed
+    expect(renderActivityFeedWithNested(lines, ["  ", ""])).toBe(renderActivityFeed(lines));
+  });
+
+  it("done-styles ALL parent lines and nests the child block (newest = bold →)", () => {
+    const parent = ["Searching memory", "Delegating: review the migration"];
+    const child = ["Reading schema.ts", "Looking for foreign keys"];
+    const out = renderActivityFeedWithNested(parent, child)!;
+    // Parent is blocked at the Task tool → none of its lines is the live step.
+    expect(out).toContain("<i>✓ Searching memory</i>");
+    expect(out).toContain("<i>✓ Delegating: review the migration</i>");
+    expect(out).not.toContain("<b>→ Delegating");
+    // The live → step is the newest nested child line; earlier child = italic.
+    expect(out).toContain("   ↳ <i>Reading schema.ts</i>");
+    expect(out).toContain("   ↳ <b>→ Looking for foreign keys</b>");
+  });
+
+  it("caps the nested block to NESTED_MAX_LINES with a '↳ +N earlier…' header", () => {
+    const child = Array.from({ length: NESTED_MAX_LINES + 3 }, (_, i) => `step ${i + 1}`);
+    const out = renderActivityFeedWithNested(["Delegating: x"], child)!;
+    expect(out).toContain("   ↳ <i>+3 earlier…</i>");
+    // newest nested line is the live → step
+    expect(out).toContain(`   ↳ <b>→ step ${NESTED_MAX_LINES + 3}</b>`);
+    // the oldest (collapsed) lines are not rendered verbatim
+    expect(out).not.toContain("step 1<");
+  });
+
+  it("renders the child block even when the parent feed is empty", () => {
+    const out = renderActivityFeedWithNested([], ["Reading a.ts"]);
+    expect(out).toBe("   ↳ <b>→ Reading a.ts</b>");
+  });
+
+  it("HTML-escapes nested child text", () => {
+    const out = renderActivityFeedWithNested(["Delegating: x"], ["touch <a> & <b>"])!;
+    expect(out).toContain("   ↳ <b>→ touch &lt;a&gt; &amp; &lt;b&gt;</b>");
+  });
+});

package/telegram-plugin/tests/turns-writer.test.ts

@@ -5,7 +5,7 @@
  *   1. Clean turn: insert + finalize → row has ended_via='stop', non-null
  *      ended_at, correct previews.
  *   2. Mid-turn restart: insert without finalize, simulate gateway boot via
- *      markOrphanedAsRestarted → row has ended_via='restart'.
+ *      markOrphanedWithTimeoutClassification → row has ended_via='restart'.
  *   3. Multiple concurrent turns same chat: each row has a unique turn_key,
  *      no cross-contamination.
  *   4. tool_call_count increments correctly for N tool_use events.
@@ -20,9 +20,19 @@ import {
   openTurnsDbInMemory,
   recordTurnStart,
   recordTurnEnd,
-  markOrphanedAsRestarted,
+  markOrphanedWithTimeoutClassification,
 } from '../registry/turns-schema.js'
 
+// The boot reaper as the gateway calls it between turns (no live hang
+// marker) — every open turn is a clean 'restart' interrupt.
+function reapAsRestart(db: Parameters<typeof recordTurnEnd>[0]) {
+  return markOrphanedWithTimeoutClassification(db, {
+    markerTurnKey: null,
+    markerAgeMs: null,
+    hangThresholdMs: 300_000,
+  })
+}
+
 // ---------------------------------------------------------------------------
 // 1. Clean turn
 // ---------------------------------------------------------------------------
@@ -110,7 +120,7 @@ describe('clean turn (Phase 1 #332)', () => {
 // ---------------------------------------------------------------------------
 
 describe('mid-turn restart (Phase 1 #332)', () => {
-  it('insert without finalize, then markOrphanedAsRestarted → ended_via=restart', () => {
+  it('insert without finalize, then reaper → ended_via=restart', () => {
     const db = openTurnsDbInMemory()
 
     recordTurnStart(db, {
@@ -120,8 +130,8 @@ describe('mid-turn restart (Phase 1 #332)', () => {
     })
 
     // Simulate gateway boot reaper (same path as the real gateway boot).
-    const swept = markOrphanedAsRestarted(db)
-    expect(swept).toBe(1)
+    const swept = reapAsRestart(db)
+    expect(swept.reaped).toBe(1)
 
     const row = db
       .prepare('SELECT ended_via, ended_at FROM turns WHERE turn_key = ?')
@@ -141,7 +151,7 @@ describe('mid-turn restart (Phase 1 #332)', () => {
     recordTurnEnd(db, { turnKey: 'chat2:_:2001', endedVia: 'stop' })
     recordTurnStart(db, { turnKey: 'chat2:_:2002', chatId: 'chat2' })
 
-    markOrphanedAsRestarted(db)
+    reapAsRestart(db)
 
     const clean = db
       .prepare('SELECT ended_via FROM turns WHERE turn_key = ?')

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

@@ -216,6 +216,61 @@ export function renderActivityFeed(lines: string[]): string | null {
   return out.join("\n");
 }
 
+// ─── Foreground sub-agent nesting (Model A) ─────────────────────────────────
+//
+// A foreground sub-agent (Task/Agent with no `run_in_background`) runs INSIDE
+// the parent's turn — the parent is blocked at the Task tool until it returns.
+// Rather than a separate message, its live steps nest under the parent's own
+// activity feed: the gold-standard main-turn visibility applied one level
+// down. The parent's lines render as done (the parent handed off; it isn't
+// the active worker), and the sub-agent's recent narrative lines render as an
+// indented `↳` block with the newest as the in-progress `→` step.
+
+/** Trailing nested child lines kept visible (Telegram length + readability). */
+export const NESTED_MAX_LINES = 4;
+/** Hard cap on a single nested narrative line. */
+const NESTED_LINE_MAX = 90;
+/** Indent marker for a nested sub-agent step. */
+const NESTED_PREFIX = "   ↳ ";
+
+/**
+ * Render the parent activity feed with an active foreground sub-agent's steps
+ * nested beneath it. When `childLines` is empty this is identical to
+ * `renderActivityFeed(lines)`. Otherwise the parent's own lines are all
+ * done-styled (`✓` italic) — the live `→` step lives in the nested block —
+ * and the child block is indented, newest = bold `→`, earlier = italic, with
+ * a `↳ +N earlier…` header when it overflows. Returns ready Telegram HTML
+ * (callers must NOT re-escape) or null when there is nothing to show.
+ */
+export function renderActivityFeedWithNested(
+  lines: string[],
+  childLines: string[],
+): string | null {
+  const children = childLines.map((s) => s.trim()).filter((s) => s.length > 0);
+  if (children.length === 0) return renderActivityFeed(lines);
+
+  const out: string[] = [];
+  const shownParent = lines.slice(-MIRROR_MAX_LINES);
+  const hiddenParent = lines.length - shownParent.length;
+  if (hiddenParent > 0) out.push(`<i>✓ +${hiddenParent} earlier…</i>`);
+  for (const l of shownParent) out.push(`<i>✓ ${escapeFeedHtml(l)}</i>`);
+
+  const shownChild = children.slice(-NESTED_MAX_LINES);
+  const hiddenChild = children.length - shownChild.length;
+  if (hiddenChild > 0) out.push(`${NESTED_PREFIX}<i>+${hiddenChild} earlier…</i>`);
+  const lastChildIdx = shownChild.length - 1;
+  shownChild.forEach((l, i) => {
+    const t = l.length > NESTED_LINE_MAX ? l.slice(0, NESTED_LINE_MAX - 1) + "…" : l;
+    const esc = escapeFeedHtml(t);
+    out.push(
+      i === lastChildIdx
+        ? `${NESTED_PREFIX}<b>→ ${esc}</b>`
+        : `${NESTED_PREFIX}<i>${esc}</i>`,
+    );
+  });
+  return out.length > 0 ? out.join("\n") : null;
+}
+
 /**
  * Like appendActivityLine, but for a pre-computed label (from the
  * real-time PreToolUse sidecar / `tool_label` event) — the hook already

package/telegram-plugin/uat/driver.ts

@@ -663,8 +663,10 @@ export class Driver {
   ): Promise<{ messageIds: number[] }> {
     const c = this.requireClient();
     const replyTo = opts?.replyTo ?? opts?.messageThreadId;
+    // mtcute reads a bare string as a file_id/URL; the `file:` scheme is
+    // what forces an upload from local disk (see normalize-input-media).
     const medias = photoPaths.map((p, i) =>
-      InputMedia.photo(p, i === 0 && caption ? { caption } : undefined),
+      InputMedia.photo(`file:${p}`, i === 0 && caption ? { caption } : undefined),
     );
     const sent = await c.sendMediaGroup(
       chatId,