switchroom 0.16.46 → 0.17.0

package/telegram-plugin/tests/nested-worker-visibility-harness.test.ts

@@ -0,0 +1,329 @@
+/**
+ * Flagship harness for NESTED (depth-2+) sub-agent card visibility — the
+ * unified progress-card fix. Mirrors
+ * worker-visibility-prose-silent-harness.test.ts: it wires the REAL
+ * `startSubagentWatcher` to the REAL `createWorkerActivityFeed` on ONE
+ * virtual clock, with a REAL registry DB (bun:sqlite) and REAL files in a
+ * tempdir, and mirrors the gateway's onProgress/onFinish routing
+ * (resolveWorkerFeedDispatch + resolveSubagentOriginTurnKey).
+ *
+ * Scenario (the live incident shape): a depth-1 BACKGROUND worker —
+ * attributed to its originating turn at dispatch — spawns a nested worker
+ * AFTER the main turn has ended. The PreToolUse hook cannot attribute the
+ * nested dispatch (turn-active.json is gone) and may lose the row entirely.
+ * Pre-fix: the nested card posted, heartbeat-edited every ~6s, and stayed
+ * frozen on "starting…" forever, routed to the owner DM.
+ *
+ * Asserts the required end-state behaviour for the nested permutation:
+ *   (a) a registry row EXISTS for the nested worker (watcher-recorded from
+ *       the parent's JSONL), keyed so the child's meta.json links it,
+ *   (b) the nested card reaches LIVE TOOL ACTIVITY (real steps, climbing
+ *       tool count) — never frozen "starting…",
+ *   (c) the card routes to the ORIGINATING chat (transitive turn-key
+ *       inheritance), not the owner-DM fallback,
+ *   (d) clean finalization on turn_end (card edits to done, handle dropped),
+ *   (e) parallel-worker isolation: the depth-1 parent's own feed message is
+ *       independent of the nested child's (no cross-worker interleaving).
+ *
+ * bun:sqlite — run under Bun:
+ *   bun test telegram-plugin/tests/nested-worker-visibility-harness.test.ts
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, appendFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+import { createWorkerActivityFeed, type WorkerActivityView } from '../worker-activity-feed.js'
+import { openTurnsDbInMemory } from '../registry/turns-schema.js'
+import {
+  applySubagentsSchema,
+  getSubagent,
+  getSubagentByJsonlId,
+  resolveSubagentOriginTurnKey,
+} from '../registry/subagents-schema.js'
+import { resolveWorkerFeedDispatch } from '../gateway/worker-feed-dispatch.js'
+
+const OWNER_DM = 'owner-dm-fallback'
+const ORIGIN_CHAT = '-1001234567890'
+const ORIGIN_TURN_KEY = `${ORIGIN_CHAT}:_:1783202199395`
+
+function jline(o: object): string {
+  return JSON.stringify(o) + '\n'
+}
+function userMsg(text: string): string {
+  return jline({ type: 'user', message: { content: [{ type: 'text', text }] } })
+}
+function toolUse(id: string, name: string, input: Record<string, unknown>): string {
+  return jline({ type: 'assistant', message: { content: [{ type: 'tool_use', id, name, input }] } })
+}
+function turnEnd(): string {
+  return jline({ type: 'system', subtype: 'turn_duration', durationMs: 1234 })
+}
+
+interface FakeBot {
+  sent: Array<{ chatId: string; text: string }>
+  edits: Array<{ chatId: string; messageId: number; text: string }>
+  sendMessage: (chatId: string, text: string) => Promise<{ message_id: number }>
+  editMessageText: (chatId: string, messageId: number, text: string) => Promise<unknown>
+}
+function makeFakeBot(): FakeBot {
+  let nextId = 7000
+  const fb: FakeBot = {
+    sent: [],
+    edits: [],
+    sendMessage: async (chatId, text) => {
+      fb.sent.push({ chatId, text })
+      return { message_id: nextId++ }
+    },
+    editMessageText: async (chatId, messageId, text) => {
+      fb.edits.push({ chatId, messageId, text })
+      return {}
+    },
+  }
+  return fb
+}
+
+const flush = async (): Promise<void> => {
+  for (let i = 0; i < 6; i++) await new Promise((r) => setTimeout(r, 0))
+}
+
+let cleanupDirs: string[] = []
+let stoppers: Array<() => void> = []
+afterEach(() => {
+  for (const s of stoppers) { try { s() } catch { /* ignore */ } }
+  stoppers = []
+  for (const d of cleanupDirs) { try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ } }
+  cleanupDirs = []
+})
+
+function makeHarness() {
+  const agentDir = mkdtempSync(join(tmpdir(), 'nested-harness-'))
+  cleanupDirs.push(agentDir)
+  const subagentsDir = join(agentDir, '.claude', 'projects', 'proj', 'sess-1', 'subagents')
+  mkdirSync(subagentsDir, { recursive: true })
+
+  const db = openTurnsDbInMemory()
+  applySubagentsSchema(db)
+  // The originating turn — ENDED before the nested dispatch happens.
+  db.prepare(`
+    INSERT INTO turns (turn_key, chat_id, thread_id, started_at, ended_at, created_at, updated_at)
+    VALUES (?, ?, NULL, 500, 900, 500, 900)
+  `).run(ORIGIN_TURN_KEY, ORIGIN_CHAT)
+  // Depth-1 background worker row — stamped by the pretool hook while the
+  // main turn was live (the mechanism PRs #2085/#2075 already fixed).
+  db.prepare(`
+    INSERT INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status, jsonl_agent_id, parent_agent_id)
+    VALUES ('toolu_parent', 'sess-1', ?, 'worker', 'depth-1 orchestrator', 1, 800, 800, 'running', NULL, NULL)
+  `).run(ORIGIN_TURN_KEY)
+
+  let currentTime = 1000
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  let nextRef = 1
+  const sharedSetInterval = (fn: () => void, ms: number): unknown => {
+    const ref = nextRef++
+    intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+    return { ref }
+  }
+  const sharedClearInterval = (h: unknown): void => {
+    const { ref } = h as { ref: number }
+    const idx = intervals.findIndex((i) => i.ref === ref)
+    if (idx !== -1) intervals.splice(idx, 1)
+  }
+  const sharedSetTimeout = sharedSetInterval
+  const sharedClearTimeout = sharedClearInterval
+
+  const bot = makeFakeBot()
+  const feed = createWorkerActivityFeed({
+    bot,
+    now: () => currentTime,
+    firstPaintMinMs: 0, // paint immediately — routing/content is under test, not paint gating
+    minEditIntervalMs: 0,
+    heartbeatTickMs: 6000,
+    setInterval: sharedSetInterval,
+    clearInterval: sharedClearInterval,
+  })
+
+  const finishCalls: Array<{ agentId: string; outcome: string }> = []
+
+  // Mirror the gateway's routing: registry-derived dispatch + transitive
+  // origin resolution, worker feed for background OR nested, orphan-DM
+  // fallback otherwise.
+  const routeChat = (agentId: string): { chatId: string } => {
+    const key = resolveSubagentOriginTurnKey(db, agentId)
+    if (key == null) return { chatId: OWNER_DM }
+    const turn = db.prepare('SELECT chat_id FROM turns WHERE turn_key = ?').get(key) as { chat_id: string } | null
+    return { chatId: turn?.chat_id ?? OWNER_DM }
+  }
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    db,
+    rescanMs: 500,
+    stallThresholdMs: 60_000,
+    silentSynthesisStallThresholdMs: 300_000,
+    silentStallTerminalMs: 300_000,
+    now: () => currentTime,
+    setInterval: sharedSetInterval,
+    clearInterval: sharedClearInterval,
+    setTimeout: sharedSetTimeout,
+    clearTimeout: sharedClearTimeout,
+    onProgress: ({ agentId, description, latestSummary, elapsedMs, lastTool, toolCount, progressLine }) => {
+      const dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(db, agentId), description)
+      const isWorkerSurface = dispatch.isBackground || dispatch.isNested || !dispatch.hasRow
+      if (!isWorkerSurface) return // foreground-nest path — out of scope here
+      const { chatId } = routeChat(agentId)
+      const view: WorkerActivityView = {
+        description: dispatch.feedDescription,
+        lastTool,
+        toolCount,
+        latestSummary: progressLine != null && progressLine.length > 0 ? progressLine : latestSummary,
+        elapsedMs,
+        state: 'running',
+      }
+      void feed.update(agentId, chatId, view)
+    },
+    onFinish: ({ agentId, outcome, description, resultText, toolCount, durationMs }) => {
+      finishCalls.push({ agentId, outcome })
+      const dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(db, agentId), description)
+      void feed.finish(agentId, {
+        description: dispatch.feedDescription,
+        lastTool: null,
+        toolCount,
+        latestSummary: resultText,
+        elapsedMs: durationMs,
+        state: outcome === 'failed' ? 'failed' : 'done',
+      })
+    },
+  })
+  stoppers.push(() => watcher.stop(), () => feed.stop())
+
+  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 writeWorker = (stem: string, toolUseId: string, description: string, firstLines: string): void => {
+    writeFileSync(join(subagentsDir, `agent-${stem}.meta.json`), JSON.stringify({
+      agentType: 'general-purpose', description, toolUseId,
+    }))
+    writeFileSync(join(subagentsDir, `agent-${stem}.jsonl`), firstLines)
+  }
+  const appendWorker = (stem: string, lines: string): void => {
+    appendFileSync(join(subagentsDir, `agent-${stem}.jsonl`), lines)
+  }
+
+  return { db, bot, feed, watcher, advance, writeWorker, appendWorker, finishCalls }
+}
+
+describe('nested (depth-2+) worker — end-to-end visibility harness', () => {
+  it('records the row, shows live tool activity, routes to the origin chat, and finalizes', async () => {
+    const h = makeHarness()
+    h.advance(500) // boot scan (empty dir)
+
+    // Depth-1 parent JSONL appears (post-boot → live) and immediately
+    // dispatches a NESTED worker. The main turn ended at t=900 — there is no
+    // turn-active marker, and the hook "lost" the child row entirely (we
+    // never insert it): the exact frozen-card incident shape.
+    h.writeWorker('parent01', 'toolu_parent', 'depth-1 orchestrator',
+      userMsg('orchestrate the nested probe')
+      + toolUse('toolu_child', 'Task', {
+        description: 'nested probe', subagent_type: 'general-purpose', run_in_background: false,
+      }))
+    h.advance(500)
+    await flush()
+
+    // (a) The watcher recorded the nested dispatch from the parent's JSONL.
+    const childRow = getSubagent(h.db, 'toolu_child')
+    expect(childRow).not.toBeNull()
+    expect(childRow?.parent_agent_id).toBe('parent01')
+    expect(childRow?.parent_turn_key).toBe(ORIGIN_TURN_KEY)
+
+    // The child JSONL appears and runs REAL tools (no prose).
+    h.writeWorker('child01', 'toolu_child', 'nested probe',
+      userMsg('probe the nested structure')
+      + toolUse('t1', 'Read', { file_path: '/repo/src/index.ts' }))
+    h.advance(500)
+    await flush()
+
+    // Linked + transitively attributed.
+    expect(getSubagent(h.db, 'toolu_child')?.jsonl_agent_id).toBe('child01')
+    expect(resolveSubagentOriginTurnKey(h.db, 'child01')).toBe(ORIGIN_TURN_KEY)
+
+    // (b)+(c) The nested card painted in the ORIGINATING chat with a REAL
+    // tool step — not the owner DM, not frozen "starting…".
+    const childMsgs = [...h.bot.sent, ...h.bot.edits].filter((m) => m.text.includes('nested probe'))
+    expect(childMsgs.length).toBeGreaterThanOrEqual(1)
+    for (const m of childMsgs) expect(m.chatId).toBe(ORIGIN_CHAT)
+    const lastChild = childMsgs[childMsgs.length - 1]!
+    expect(lastChild.text).not.toContain('starting…')
+    expect(lastChild.text).toContain('index.ts')
+
+    // More tool activity → climbing tool count, still live.
+    h.appendWorker('child01', toolUse('t2', 'Bash', { command: 'ls -la /repo' }))
+    h.advance(1000)
+    await flush()
+    const afterSecondTool = [...h.bot.edits].filter((m) => m.text.includes('nested probe')).pop()
+    expect(afterSecondTool?.text).toContain('2 tools')
+
+    // (e) Parallel isolation: the parent's own card (if painted) never
+    // absorbed the child's steps, and vice versa.
+    const parentMsgs = [...h.bot.sent, ...h.bot.edits].filter((m) => m.text.includes('depth-1 orchestrator'))
+    for (const m of parentMsgs) {
+      expect(m.text).not.toContain('index.ts')
+    }
+    for (const m of [...h.bot.sent, ...h.bot.edits].filter((x) => x.text.includes('nested probe'))) {
+      expect(m.text).not.toContain('orchestrate the nested probe')
+    }
+
+    // (d) turn_end → clean finalize: the card edits to done and the feed
+    // handle is dropped (never heartbeated frozen forever).
+    h.appendWorker('child01', turnEnd())
+    h.advance(1000)
+    await flush()
+    expect(h.finishCalls.some((f) => f.agentId === 'child01')).toBe(true)
+    const finalEdit = h.bot.edits.filter((m) => m.text.includes('nested probe')).pop()
+    expect(finalEdit?.text).toContain('done')
+    expect(h.feed.messageIdOf('child01')).toBeNull()
+  })
+
+  it('links late (backfill retry) when the child JSONL appears BEFORE the parent dispatch line is read', async () => {
+    const h = makeHarness()
+    h.advance(500) // boot scan
+
+    // Child JSONL first — registration backfill finds NO row ("Phase 2 Pre
+    // hook pending", the 2-minute freeze window from the live gateway log).
+    h.writeWorker('child01', 'toolu_child', 'nested probe',
+      userMsg('probe') + toolUse('t1', 'Read', { file_path: '/repo/a.ts' }))
+    h.advance(500)
+    await flush()
+    expect(getSubagent(h.db, 'toolu_child')).toBeNull()
+
+    // Parent's dispatch line lands → watcher records the child row.
+    h.writeWorker('parent01', 'toolu_parent', 'depth-1 orchestrator',
+      userMsg('orchestrate')
+      + toolUse('toolu_child', 'Task', { description: 'nested probe', run_in_background: false }))
+    h.advance(500)
+    await flush()
+    expect(getSubagent(h.db, 'toolu_child')).not.toBeNull()
+
+    // The child's JSONL grows → the liveness-path backfill RETRY links it
+    // (registration's one-shot backfill already missed).
+    h.advance(3000) // past BACKFILL_RETRY_INTERVAL_MS
+    h.appendWorker('child01', toolUse('t2', 'Bash', { command: 'pwd' }))
+    h.advance(1000)
+    await flush()
+    const row = getSubagent(h.db, 'toolu_child')
+    expect(row?.jsonl_agent_id).toBe('child01')
+    expect(row?.parent_turn_key).toBe(ORIGIN_TURN_KEY)
+    expect(resolveSubagentOriginTurnKey(h.db, 'child01')).toBe(ORIGIN_TURN_KEY)
+  })
+})

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -95,6 +95,59 @@ describe('pending-inbound-buffer', () => {
     expect(drained.map((m) => m.meta?.source)).toEqual(['m3', 'm4', 'm5'])
   })
 
+  // #2789 A: a >cap burst mid-turn used to evict the oldest SILENTLY —
+  // the durable spool copy only replays at boot / escalates after 15 min,
+  // so within a live session the evicted message was just gone with no
+  // user-visible signal. onEvict makes the eviction non-silent so the
+  // caller can surface a coalesced "messages deferred" notice.
+  it('#2789 A: fires onEvict with the evicted message on cap eviction (not a silent drop)', () => {
+    const evicted: InboundMessage[] = []
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      onEvict: (_agent, m) => evicted.push(m),
+    })
+    // Fill to cap — no eviction yet, no notice.
+    buf.push('a', inbound('m1', 1))
+    buf.push('a', inbound('m2', 2))
+    buf.push('a', inbound('m3', 3))
+    expect(evicted).toHaveLength(0)
+    // The 4th push overflows the cap → oldest (m1) evicted → onEvict fires.
+    buf.push('a', inbound('m4', 4))
+    expect(evicted.map((m) => m.meta?.source)).toEqual(['m1'])
+    // The 5th evicts m2.
+    buf.push('a', inbound('m5', 5))
+    expect(evicted.map((m) => m.meta?.source)).toEqual(['m1', 'm2'])
+  })
+
+  it('#2789 A: a >32 burst produces one onEvict per evicted entry, never a silent drop', () => {
+    const evicted: InboundMessage[] = []
+    const buf = createPendingInboundBuffer({
+      log: () => {}, // default cap = 32
+      onEvict: (_agent, m) => evicted.push(m),
+    })
+    // 40 messages into a 32-cap buffer → exactly 8 evictions, all reported.
+    for (let i = 1; i <= 40; i++) buf.push('a', inbound(`m${i}`, i))
+    expect(buf.depth('a')).toBe(32)
+    expect(evicted).toHaveLength(8)
+    expect(evicted.map((m) => m.meta?.source)).toEqual([
+      'm1', 'm2', 'm3', 'm4', 'm5', 'm6', 'm7', 'm8',
+    ])
+  })
+
+  it('#2789 A: a throwing onEvict never breaks the push hot path', () => {
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 1,
+      log: () => {},
+      onEvict: () => {
+        throw new Error('notice failed')
+      },
+    })
+    buf.push('a', inbound('m1', 1))
+    expect(() => buf.push('a', inbound('m2', 2))).not.toThrow()
+    expect(buf.depth('a')).toBe(1)
+  })
+
   it('push returns false when eviction occurred', () => {
     const buf = createPendingInboundBuffer({ capPerAgent: 2, log: () => {} })
     expect(buf.push('a', inbound('m1'))).toBe(true)

package/telegram-plugin/tests/progress-update-redact.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+import { redact } from '../secret-detect/redact.js'
+
+/**
+ * Behavioral coverage for the progress_update outbound secret-scrub gap.
+ *
+ * progress_update was the ONLY send site in gateway.ts that did not call
+ * `redactOutboundText` — so a secret the agent echoed into a progress line
+ * reached Telegram (and history) unmasked, while reply / stream_reply /
+ * edit_message / turn_flush all redact. The fix adds
+ * `redactOutboundText(text, 'progress_update')` — and, critically, places it
+ * BEFORE the 300-char truncation the tool applies. Ordering matters: if the
+ * truncation ran first, a secret straddling the 300-char cut would be sliced
+ * into a partial token the shape detector no longer matches, leaking the
+ * visible bytes.
+ *
+ * These tests reproduce the gateway's `executeProgressUpdate` send prep — the
+ * exact `redact` engine used in production, in the same order the fix uses
+ * (redact → truncate) — and pin both the ordinary mask and the
+ * straddling-the-boundary case, plus a contrast showing the WRONG order leaks.
+ */
+
+// Build the token fixture by concatenation so the source file never contains a
+// contiguous secret-shaped literal (repo Push Protection / no-pii lint).
+const ID = '17'
+const BODY40 = 'aB3dE6fH9j'.repeat(4) // 40 base62 chars — Sanctum's Str::random(40)
+const SANCTUM = `${ID}|${BODY40}` // e.g. 17|aB3dE6fH9j…
+
+/** The production send-prep order: redact the FULL text, THEN truncate. */
+function progressSendPrep(text: string): string {
+  let out = redact(text)
+  if (out.length > 300) out = out.slice(0, 299) + '…'
+  return out
+}
+
+/** The buggy order the fix guards against: truncate first, then redact. */
+function truncateFirstThenRedact(text: string): string {
+  let out = text
+  if (out.length > 300) out = out.slice(0, 299) + '…'
+  return redact(out)
+}
+
+describe('progress_update outbound secret-scrub', () => {
+  it('masks a secret-shaped token in an ordinary (short) progress line', () => {
+    const out = progressSendPrep(`Deploying with token ${SANCTUM} now — hold tight`)
+    expect(out).not.toContain(SANCTUM)
+    expect(out).not.toContain(BODY40)
+    expect(out).toContain('[REDACTED:laravel_sanctum_token]')
+    // Surrounding prose survives.
+    expect(out).toContain('Deploying with token')
+    expect(out).toContain('hold tight')
+  })
+
+  it('masks a secret that STRADDLES the 300-char truncation boundary', () => {
+    // Pad so the token spans char 300: 286 chars of prose, a space, then the
+    // 43-char token. The 299/300 cut lands mid-token.
+    const pad = 'progress: still working on the deploy, '.repeat(8).slice(0, 286)
+    const text = `${pad} ${SANCTUM} and continuing after the token here`
+    // Sanity: the token really does straddle the cut point.
+    const cut = 299
+    expect(text.indexOf(SANCTUM)).toBeLessThan(cut)
+    expect(text.indexOf(SANCTUM) + SANCTUM.length).toBeGreaterThan(cut)
+
+    const out = progressSendPrep(text)
+    // Because redact runs on the FULL text first, the whole token is masked
+    // before any slice — no secret bytes reach the wire. (The mask MARKER
+    // itself may fall across the 300-char cut and be truncated — harmless,
+    // since it carries no secret — so assert the leading marker survives, not
+    // the full literal.)
+    expect(out).not.toContain(SANCTUM)
+    expect(out).not.toContain(BODY40)
+    expect(out).toContain('[REDACTED')
+  })
+
+  it('proves the ordering matters: truncate-FIRST would leak the straddling secret', () => {
+    // A regression fence: if someone reorders the fix so truncation precedes
+    // redaction, the cut splits the token, the shape detector misses the
+    // fragment, and partial secret bytes survive. This asserts the wrong order
+    // leaks — the exact failure the production ordering prevents.
+    const pad = 'progress: still working on the deploy, '.repeat(8).slice(0, 286)
+    const text = `${pad} ${SANCTUM} and continuing after the token here`
+
+    const wrong = truncateFirstThenRedact(text)
+    // The leading fragment of the token body (pre-cut) survives unmasked.
+    const leakedPrefix = BODY40.slice(0, 6)
+    expect(wrong).toContain(leakedPrefix)
+
+    // The correct order masks it — the fragment does NOT survive.
+    const right = progressSendPrep(text)
+    expect(right).not.toContain(leakedPrefix)
+  })
+
+  it('idempotent: a masked progress line has no secret bytes on a second pass', () => {
+    const once = progressSendPrep(`token ${SANCTUM}`)
+    const twice = progressSendPrep(once)
+    expect(twice).not.toContain(SANCTUM)
+    expect(twice).not.toContain(BODY40)
+  })
+})

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

@@ -19,6 +19,8 @@ import {
   findOrphanedTurns,
   markOrphanedWithTimeoutClassification,
   findLatestTurnIfInterrupted,
+  markTurnResumed,
+  getTurnByKey,
 } from '../registry/turns-schema.js'
 
 // Convenience: the boot reaper with no live hang marker — every open turn
@@ -506,4 +508,69 @@ describe('findLatestTurnIfInterrupted', () => {
     expect(findLatestTurnIfInterrupted(db)).toBeNull()
     db.close()
   })
+
+  // ── #2793 part A: resume is at-most-once via the `resumed_at` ledger ──
+  // Repro: without the ledger, an interrupted turn whose resume ran its
+  // side effects but never reached a clean 'stop' (process died before the
+  // follow-up turn wrote ended_at, or the resume inbound was accepted but
+  // never consumed) stays "latest + not clean" — so every subsequent boot
+  // re-mints a fresh resume and DOUBLE-EXECUTES. The ledger makes it null
+  // after the first commit.
+  it('re-fires an interrupted turn until it is stamped resumed (double-exec repro)', () => {
+    const db = openTurnsDbInMemory()
+    recordTurnStart(db, { turnKey: 'res:1', chatId: 'res' })
+    recordTurnEnd(db, { turnKey: 'res:1', endedVia: 'restart' })
+    // Boot 1: the turn is interrupted and still unresumed → it is returned
+    // (the gateway will mint a resume for it).
+    const first = findLatestTurnIfInterrupted(db)
+    expect(first).not.toBeNull()
+    expect(first!.turn_key).toBe('res:1')
+    expect(first!.resumed_at).toBeNull()
+    // Gateway durably queues the resume, then stamps the ledger.
+    markTurnResumed(db, 'res:1', 1_700_000_000_000)
+    // Boot 2 (crash happened after side effects, turn still 'restart' with
+    // no clean follow-up): the SAME turn must NOT be resumed again.
+    expect(findLatestTurnIfInterrupted(db)).toBeNull()
+    db.close()
+  })
+
+  it('does not re-fire even an OPEN (ended_at IS NULL) turn once resumed', () => {
+    const db = openTurnsDbInMemory()
+    recordTurnStart(db, { turnKey: 'res:2', chatId: 'res' })
+    // Still open (never reaped to a terminal ended_via), but already resumed
+    // once — the accept-but-never-consumed window. Must not re-fire.
+    markTurnResumed(db, 'res:2')
+    expect(findLatestTurnIfInterrupted(db)).toBeNull()
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// markTurnResumed — the at-most-once resume ledger (#2793 part A)
+// ---------------------------------------------------------------------------
+
+describe('markTurnResumed', () => {
+  it('stamps resumed_at on the target turn', () => {
+    const db = openTurnsDbInMemory()
+    recordTurnStart(db, { turnKey: 'mk:1', chatId: 'mk' })
+    recordTurnEnd(db, { turnKey: 'mk:1', endedVia: 'restart' })
+    markTurnResumed(db, 'mk:1', 1_700_000_000_000)
+    expect(getTurnByKey(db, 'mk:1')!.resumed_at).toBe(1_700_000_000_000)
+    db.close()
+  })
+
+  it('is first-write-wins: a second stamp does not overwrite the first', () => {
+    const db = openTurnsDbInMemory()
+    recordTurnStart(db, { turnKey: 'mk:2', chatId: 'mk' })
+    markTurnResumed(db, 'mk:2', 1_700_000_000_000)
+    markTurnResumed(db, 'mk:2', 1_800_000_000_000)
+    expect(getTurnByKey(db, 'mk:2')!.resumed_at).toBe(1_700_000_000_000)
+    db.close()
+  })
+
+  it('no-ops for an unknown turn_key', () => {
+    const db = openTurnsDbInMemory()
+    expect(() => markTurnResumed(db, 'nope:1')).not.toThrow()
+    db.close()
+  })
 })

package/telegram-plugin/tests/represent-guard.test.ts

@@ -37,14 +37,14 @@ describe("shouldSuppressRepresent — #2472 duplicate-represent guard", () => {
   });
 
   it("does NOT suppress the FIRST represent — genuine plain-text-no-reply still represents once", () => {
-    // First represent: lastRepresentedAt is undefined. Even though an assistant
-    // message (the original plain-text answer) exists in history, the single
-    // re-ask must still fire — the agent never called the reply tool.
-    const o = obligation({ lastRepresentedAt: undefined });
+    // First represent: lastRepresentedAt is undefined, no reply tool call was
+    // ever recorded (the genuine plain-text-no-reply case → no outbound row, so
+    // the predicate reports false). The single re-ask must still fire.
+    const o = obligation({ openedAt: 0, lastRepresentedAt: undefined });
     const suppress = shouldSuppressRepresent(o, {
       historyEnabled: true,
-      // history WOULD report an outbound exists, but the first represent ignores it
-      hasOutboundDeliveredSince: () => true,
+      // No outbound row exists for a plain-text answer → predicate is false.
+      hasOutboundDeliveredSince: () => false,
     });
     expect(suppress).toBe(false); // represent fires exactly once
   });
@@ -70,6 +70,42 @@ describe("shouldSuppressRepresent — #2472 duplicate-represent guard", () => {
     expect(suppress).toBe(false);
   });
 
+  it("#2788 Gap B — SUPPRESSES the FIRST represent when a genuine reply was delivered since openedAt", () => {
+    // The narrow false "you never answered" window: a real reply landed at
+    // t=1500 after the obligation was raised at t=1000, but its routing didn't
+    // resolve back to the origin so the ledger's close path missed it. The FIRST
+    // represent must now dedup against outbound history (cutoff = openedAt) and
+    // suppress, instead of emitting a false "you never answered".
+    const o = obligation({ openedAt: 1000, lastRepresentedAt: undefined });
+    const suppress = shouldSuppressRepresent(o, {
+      historyEnabled: true,
+      hasOutboundDeliveredSince: replyDeliveredAt(1500),
+    });
+    expect(suppress).toBe(true); // first represent deduped → no false "you never answered"
+  });
+
+  it("#2788 Gap B — first represent still fires when the only reply PREDATES openedAt", () => {
+    // A reply at t=500 answered an EARLIER turn, before this obligation was
+    // raised at t=1000. It is not evidence THIS obligation was answered → the
+    // first represent must still fire.
+    const o = obligation({ openedAt: 1000, lastRepresentedAt: undefined });
+    const suppress = shouldSuppressRepresent(o, {
+      historyEnabled: true,
+      hasOutboundDeliveredSince: replyDeliveredAt(500),
+    });
+    expect(suppress).toBe(false);
+  });
+
+  it("#2788 Gap B — first represent falls back to firing when openedAt is unknown", () => {
+    // Without an openedAt cutoff we cannot dedup safely — never suppress on doubt.
+    const o = obligation({ openedAt: undefined, lastRepresentedAt: undefined });
+    const suppress = shouldSuppressRepresent(o, {
+      historyEnabled: true,
+      hasOutboundDeliveredSince: () => true,
+    });
+    expect(suppress).toBe(false);
+  });
+
   it("never suppresses when history is unavailable (safe: re-ask rather than silently drop)", () => {
     const o = obligation({ lastRepresentedAt: 1000 });
     const suppress = shouldSuppressRepresent(o, {

package/telegram-plugin/tests/resume-inbound-builder.test.ts

@@ -37,6 +37,7 @@ function makeTurn(overrides: Partial<Turn> = {}): Turn {
     assistant_reply_preview: null,
     tool_call_count: null,
     interrupt_reason: null,
+    resumed_at: null,
     created_at: 1_000_000,
     updated_at: 1_000_000,
     ...overrides,

package/telegram-plugin/tests/session-tail.test.ts

@@ -509,7 +509,16 @@ describe('projectSubagentLine', () => {
     // rendering."
     expect(events.length).toBe(2)
     expect(events[0].kind).toBe('sub_agent_tool_use')
-    expect(events[1]).toEqual({ kind: 'sub_agent_nested_spawn', agentId: 'X' })
+    // The nested_spawn now ALSO carries the dispatch toolUseId + input so
+    // the watcher can key the nested worker's registry row
+    // (recordNestedSubagentDispatch — the depth-2+ card fix). Rendering is
+    // unchanged: still no sub_agent_tool_use for the nested Agent.
+    expect(events[1]).toEqual({
+      kind: 'sub_agent_nested_spawn',
+      agentId: 'X',
+      toolUseId: 'toolu_b',
+      input: { description: 'nested', prompt: 'nested-p' },
+    })
   })
 
   it('emits sub_agent_text + sub_agent_tool_use in source order for [text, tool_use]', () => {