switchroom 0.18.31 → 0.18.33

package/telegram-plugin/subagent-watcher.ts

@@ -46,7 +46,7 @@ import { homedir } from 'os'
 import { projectSubagentLine, sanitizeCwdToProjectName, detectErrorInTranscriptLine } from './session-tail.js'
 import { sanitiseToolArg } from './fleet-state.js'
 import { clipNarrative, describeToolUse } from './tool-activity-summary.js'
-import { REPLY_TOOLS } from './narrative-dedup.js'
+import { isReplyTool } from './narrative-dedup.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from './narrative-flush.js'
 import { truncate } from './card-format.js'
 import { bumpSubagentActivity, recordSubagentStall, recordSubagentResume, recordSubagentEnd, reapStuckRunningRows, countRunningBackgroundSubagents, recordNestedSubagentDispatch, recordSubagentModel } from './registry/subagents-schema.js'
@@ -551,6 +551,31 @@ export interface SubagentWatcherConfig {
    * that the chain is bounded, not that a lost worker gets a fresh card.
    */
   onWorkerLost?: (agentId: string, description: string) => void
+  /**
+   * Issue #3373 (SendMessage-resume feed re-surface). Fires when a worker that
+   * had a GENUINE terminal completion (a real `sub_agent_turn_end`, then swept
+   * by `cleanupTerminalAgent`) is RESUMED via SendMessage — its
+   * `agent-<id>.jsonl` grows PAST the byte size recorded at terminal cleanup,
+   * and `scanSubagentsDir` re-registers it as a fresh live entry (#3315).
+   *
+   * This is DISTINCT from `onResurrect` (#3023), which reverses a FALSE finish
+   * from silent-stall synthesis and carries bounded-chain semantics. A
+   * SendMessage resume is a real, legitimately-unbounded lifecycle event (a
+   * worker may be stopped and resumed many times), so it does NOT route through
+   * the resurrection budget — it fires here every time growth-past-terminal is
+   * observed.
+   *
+   * Why it exists: the live worker-activity feed latches a terminal `finalized`
+   * gate per agentId (worker-activity-feed.ts) so a late zombie tick can't
+   * repaint a done worker. The #3315 re-registration re-arms the watcher and
+   * re-fires `onProgress`, but those cues are SWALLOWED by that latch — so a
+   * resumed long-running worker reads as silence with no card. The gateway
+   * wires this to `feed.resurrect(agentId)` (clear the latch) so the subsequent
+   * `onProgress` cue repaints a fresh live row. Deterministic: gated solely on
+   * the file growing past the recorded terminal boundary, never on model
+   * discipline. Best-effort; the callback is expected to be idempotent.
+   */
+  onResume?: (agentId: string, description: string) => void
   /**
    * Called exactly once per sub-agent when its watcher observes a terminal
    * transition (`done` or `failed`). Mirrors the existing `sub_agent_started`
@@ -846,6 +871,17 @@ const DEFAULT_REAPER_INTERVAL_MS = 15 * 60_000     // 15 minutes
  */
 const TERMINAL_CLEANUP_GRACE_MS = 30_000
 
+/**
+ * Bounded tail window (bytes) the boot-reconcile fast-path reads to decide
+ * whether a stale historical worker already reached `turn_end` before this
+ * boot (see `probeReachedTurnEndAtBoot`). Large enough to contain any realistic
+ * final line (a `turn_duration` line is ~100 bytes; an `end_turn` assistant
+ * answer line is well under this), yet a tiny fraction of the multi-MB
+ * transcripts a long-running worker accumulates — so the boot read is O(window)
+ * per record instead of O(filesize). 512 KiB.
+ */
+const BOOT_TERMINAL_PROBE_WINDOW_BYTES = 512 * 1024
+
 /**
  * Throttle for the liveness-path retry of `backfillJsonlAgentId` (see
  * WorkerEntry.lastBackfillAttemptAt). Cheap (one meta.json read + two
@@ -855,13 +891,14 @@ const BACKFILL_RETRY_INTERVAL_MS = 3000
 
 /**
  * Fix #9a: cap on `terminatedAgentIds` (the re-discovery dedup guard in
- * `cleanupTerminalAgent` / `scanSubagentsDir`). Pre-fix the Set only grew
+ * `cleanupTerminalAgent` / `scanSubagentsDir`). Pre-fix the map only grew
  * (added on every terminal cleanup, only ever cleared wholesale in
  * `stop()`), so a long-lived gateway with sustained sub-agent throughput
- * accumulated ids without bound. A `Set` preserves insertion order, so once
+ * accumulated ids without bound. A `Map` preserves insertion order, so once
  * the cap is hit the OLDEST id is evicted on each new insert (simple ring
  * buffer semantics) — recently-terminated ids (the ones actually at risk of
- * a re-discovery race) always stay covered.
+ * a re-discovery race, or of a SendMessage resume — issue #3315) always stay
+ * covered.
  */
 const TERMINATED_AGENT_IDS_CAP = 5000
 
@@ -1550,8 +1587,8 @@ export function readSubTail(
           const narrativeJustFired = resolvePendingSubNarrative(ev.toolName, ev.input)
           // NIT 3: capture a foreground sub-agent's actual reply text so the
           // turn_end path can suppress a trailing draft of it (see
-          // resolvePendingSubNarrative). Only REPLY_TOOLS carry the answer.
-          if (REPLY_TOOLS.has(ev.toolName) && typeof ev.input?.text === 'string') {
+          // resolvePendingSubNarrative). Only reply tools carry the answer.
+          if (isReplyTool(ev.toolName) && typeof ev.input?.text === 'string') {
             entry.lastReplyText = ev.input.text as string
           }
           entry.toolCount++
@@ -1861,18 +1898,26 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
   const historicalFiles = new Set<string>()
   /**
    * AgentIds that have transitioned to a terminal state and been swept
-   * out of `registry` by `cleanupTerminalAgent`. Issue #1116 (Bug B):
-   * the JSONL file outlives the registry entry — Claude Code leaves
-   * the file on disk after the sub-agent finishes. Without this guard,
-   * the next `rescanSubagentDirs` poll re-discovered the file, called
-   * `registerAgent`, the fresh entry read the terminal `turn_duration`
-   * line, and `maybySendStateTransition` fired a duplicate "Worker done"
-   * notification — looping forever every grace-window.
+   * out of `registry` by `cleanupTerminalAgent`, mapped to the JSONL byte
+   * SIZE at cleanup time. Issue #1116 (Bug B): the JSONL file outlives the
+   * registry entry — Claude Code leaves the file on disk after the sub-agent
+   * finishes. Without this guard, the next `rescanSubagentDirs` poll
+   * re-discovered the file, called `registerAgent`, the fresh entry read the
+   * terminal `turn_duration` line, and `maybySendStateTransition` fired a
+   * duplicate "Worker done" notification — looping forever every grace-window.
    *
-   * `scanSubagentsDir` consults this set and treats re-discovered
-   * terminal JSONLs as a no-op.
+   * Issue #3315 (SendMessage resume): a resumed sub-agent reuses the SAME
+   * `agent-<id>.jsonl`, appending a NEW turn to it — so the file's size grows
+   * PAST the size it had at terminal cleanup. `scanSubagentsDir` compares the
+   * live file size against this recorded terminal size: at/below it the JSONL
+   * is a static leftover and stays suppressed (#1116 Bug B); above it the
+   * worker resumed and is re-registered live (#3315) so its progress card
+   * updates again. Storing the size (not a bare membership flag) is what makes
+   * that distinction deterministic and lifecycle-driven rather than a
+   * heuristic. Map iteration order is insertion order, so the eviction ring
+   * buffer (Fix #9a) still evicts the oldest id.
    */
-  const terminatedAgentIds = new Set<string>()
+  const terminatedAgentIds = new Map<string, number>()
   /**
    * Issue #3023 (card resurrection). Per-worker record of a FALSE terminal
    * finish — a terminal state produced by silent-stall synthesis (NOT a real
@@ -1914,9 +1959,71 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
 
   let stopped = false
 
+  /**
+   * Cheap boot-terminal probe. Reads only a BOUNDED TAIL of a JSONL (not the
+   * whole multi-MB transcript) and runs the canonical `projectSubagentLine`
+   * projector over its complete lines to decide whether the worker had already
+   * reached `sub_agent_turn_end` before this boot. Used by the boot-reconcile
+   * fast-path to tell a done-at-boot worker (which still needs terminal
+   * cleanup — feed-row sweep, card collapse/unpin) apart from a running-at-boot
+   * dead prior-session worker (which needs nothing) WITHOUT the expensive full
+   * read. `done` is the only terminal boot state (`WorkerState` never flips to
+   * `'failed'` at boot — see its doc), and its signal (`system/turn_duration`
+   * or an `end_turn` assistant line) is always the tail of the file, so a
+   * bounded window catches it. Conservative on error: an unreadable/oversized
+   * final line returns `false`, so the entry falls through to the running-stale
+   * skip rather than being mis-swept.
+   */
+  function probeReachedTurnEndAtBoot(filePath: string, size: number): boolean {
+    if (size <= 0) return false
+    const start = Math.max(0, size - BOOT_TERMINAL_PROBE_WINDOW_BYTES)
+    let raw: string
+    try {
+      const len = size - start
+      const buf = Buffer.alloc(len)
+      const fd = fs.openSync(filePath, 'r')
+      try {
+        fs.readSync(fd, buf, 0, len, start)
+      } finally {
+        fs.closeSync(fd)
+      }
+      raw = buf.toString('utf-8')
+    } catch {
+      return false
+    }
+    const lines = raw.split('\n')
+    // If we started mid-file, the first fragment is a partial line — drop it
+    // (projectSubagentLine would JSON-parse-fail on it anyway, but be explicit).
+    if (start > 0) lines.shift()
+    const probeState = { hasEmittedStart: true } // suppress start events; irrelevant here
+    for (const line of lines) {
+      if (!line) continue
+      let events
+      try {
+        events = projectSubagentLine(line, 'probe', probeState)
+      } catch {
+        continue
+      }
+      for (const ev of events) {
+        if (ev.kind === 'sub_agent_turn_end') return true
+      }
+    }
+    return false
+  }
+
   // ─── Per-agent registration ─────────────────────────────────────────────
 
-  function registerAgent(filePath: string, agentId: string): void {
+  /**
+   * @param resumeFromCursor Issue #3315: when re-registering a worker whose
+   *   JSONL resumed growing after a terminal cleanup (a SendMessage resume),
+   *   start the tail cursor at the terminal byte boundary instead of 0. The
+   *   already-handed-back completed turn (its `sub_agent_turn_end` and all
+   *   prior events) is therefore never re-read — so the fresh entry stays
+   *   `running` on the NEW turn's content rather than instantly re-reading the
+   *   old terminal line and re-finalising. Omitted (⇒ 0) for every normal
+   *   registration, which reads from the start.
+   */
+  function registerAgent(filePath: string, agentId: string, resumeFromCursor?: number): void {
     if (registry.has(agentId)) return
     const n = nowFn()
     const isHistorical = historicalFiles.has(filePath)
@@ -1950,6 +2057,85 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     }
     registry.set(agentId, entry)
 
+    // Boot reconcile fast-path (perf): a historical boot entry whose file's
+    // LAST WRITE already exceeds the in-flight promotion freshness window is a
+    // provably-dead prior-session worker. The freshness gate below reaches the
+    // exact same verdict ("stale — leaving historical, no live transition to
+    // observe"), but only AFTER the full initial `readSubTail` (a whole-
+    // transcript parse plus per-record sqlite liveness/backfill round-trips).
+    // On a busy 24/7 agent, hundreds of these dead JSONLs accumulate, and doing
+    // that O(n) work synchronously at boot delayed the gateway answering
+    // Telegram by minutes after every restart — the agent looked dead. Since
+    // the age check ALONE decides "dead prior-session worker" (identical
+    // threshold `inflightPromoteMaxAgeMs`), compute it up front and short-
+    // circuit: register a minimal historical entry, skip the read, the
+    // promotion attempt, and the FSWatcher. A resume re-registration (#3315)
+    // passes isHistorical=false (historicalFiles.delete precedes it) and a
+    // genuinely fresh in-flight-at-boot worker fails the age check, so both
+    // still take the full path below.
+    if (isHistorical) {
+      let mtimeMs: number | null = null
+      let fileSize = 0
+      try {
+        const st = fs.statSync(filePath)
+        if (typeof st.size === 'number') fileSize = st.size
+        if (typeof st.mtimeMs === 'number') mtimeMs = st.mtimeMs
+      } catch {
+        /* unreadable → mtimeMs stays null → conservative full path below */
+      }
+      // Only fast-path when the mtime is KNOWN and already past the freshness
+      // window — a confidently-dead prior-session worker. A missing/unreadable
+      // mtime is NOT treated as dead here (unlike the freshness gate's
+      // Infinity-is-stale rule): we conservatively fall through to the full
+      // path so the read still happens, since the whole optimisation targets
+      // real on-disk files (which always carry an mtime) and the boot cost only
+      // bites at fleet scale where mtimes are present.
+      if (mtimeMs != null && n - mtimeMs > inflightPromoteMaxAgeMs) {
+        const fileAgeMs = n - mtimeMs
+        // The expensive boot work was the full initial `readSubTail` (whole-
+        // transcript parse + per-record sqlite liveness/backfill round-trips)
+        // done for EVERY historical `running` JSONL, including the hundreds a
+        // busy 24/7 agent hoards that were last written days-to-weeks ago. It
+        // produced nothing actionable for a worker the freshness gate was about
+        // to leave historical anyway, yet its O(filesize) disk reads (×~1177 on
+        // the incident agent) delayed the gateway answering Telegram by minutes
+        // after every restart. Replace it with a BOUNDED tail probe.
+        //
+        // The probe distinguishes the two stale-at-boot populations WITHOUT the
+        // full read, so we don't over-skip: a *done*-at-boot worker (its JSONL
+        // already reached `turn_end`) must still reach `scheduleTerminalCleanup`
+        // — otherwise its worker-feed row leaks as a ghost (card never
+        // collapsed/unpinned; #<worker-feed ghost-leak>). A *running*-at-boot
+        // dead prior-session worker (never wrote a terminal `turn_end` — the
+        // incident population) needs nothing: no read, no backfill, no watcher,
+        // no cleanup.
+        const doneAtBoot = probeReachedTurnEndAtBoot(filePath, fileSize)
+        // Park the tail cursor at the boot-time EOF either way. A historical
+        // entry whose cursor sits at EOF is a cheap no-op in the poll loop
+        // (readSubTail statSyncs, sees `size === cursor`, returns before any
+        // openSync/sqlite — the skeleton-cue path is gated on `!historical`), so
+        // no poll-loop special-casing is needed; a genuine post-boot resume that
+        // grows the file PAST this EOF is still read on the next poll. No
+        // FSWatcher: a dead prior-session worker has no live transition to
+        // observe. And a stale worker's pre-existing `turn_end` sits BEFORE the
+        // parked cursor, so it is never replayed as a spurious completion (the
+        // v0.14.23 stale-handback regression stays fixed).
+        tails.set(agentId, { cursor: fileSize, pendingPartial: '', hasEmittedStart: false, watcher: null })
+        if (doneAtBoot) {
+          // Mirror the done-at-boot branch of the full path (below), minus the
+          // whole-transcript parse: suppress a spurious completion notification
+          // and schedule the terminal cleanup so the feed row is swept.
+          entry.state = 'done'
+          entry.completionNotified = true
+          log?.(`subagent-watcher: ${agentId} done at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) — historical; scheduling terminal cleanup (bounded tail probe, no whole-transcript parse, no watcher)`)
+          scheduleTerminalCleanup(agentId)
+        } else {
+          log?.(`subagent-watcher: ${agentId} running at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) — leaving historical, skipping reconcile read (dead prior-session worker, not in-flight; no whole-transcript parse, no backfill, no watcher)`)
+        }
+        return
+      }
+    }
+
     // Backfill jsonl_agent_id linkage. The PreToolUse hook inserts the row
     // keyed on tool_use_id and doesn't know the JSONL stem yet (the JSONL
     // doesn't exist when PreToolUse fires). We bridge that gap here: read
@@ -1976,7 +2162,12 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     }
 
     const tail: SubTail = {
-      cursor: 0, // read from start to capture description
+      // Normally read from the start (to replay the full transcript); on a
+      // resume re-registration (#3315) start at the terminal boundary so only
+      // the new turn is read. A resumed cursor sits on a JSONL newline boundary
+      // (the prior turn ended with a complete `turn_end` line), so no partial
+      // line is straddled.
+      cursor: resumeFromCursor ?? 0,
       pendingPartial: '',
       hasEmittedStart: false,
       watcher: null,
@@ -2274,24 +2465,42 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       try { tail.watcher.close() } catch { /* ignore */ }
       tail.watcher = null
     }
-    tails.delete(agentId)
     const entry = registry.get(agentId)
+    // Issue #3315: snapshot the JSONL byte size at cleanup so a later
+    // SendMessage-resume — which appends a NEW turn to the SAME
+    // agent-<id>.jsonl — is detected by `scanSubagentsDir` as growth PAST this
+    // size and re-registered. The on-disk stat is the source of truth (it
+    // captures any bytes that landed during the terminal-cleanup grace window,
+    // so only genuinely post-cleanup writes trip a resume); fall back to the
+    // tail cursor, then 0, when the file is unreadable.
+    let terminalSize = tail?.cursor ?? 0
+    if (entry?.filePath) {
+      try {
+        terminalSize = fs.statSync(entry.filePath).size
+      } catch { /* keep the cursor-based fallback */ }
+    }
+    tails.delete(agentId)
     if (entry?.filePath) {
       knownFiles.delete(entry.filePath)
     }
     registry.delete(agentId)
     // Issue #1116 (Bug B): record that this agent has been fully
-    // processed so a rescan that rediscovers the still-present JSONL
-    // doesn't re-register and re-notify.
+    // processed so a rescan that rediscovers the still-present (unchanged)
+    // JSONL doesn't re-register and re-notify. The recorded value is the
+    // terminal byte size (issue #3315): `scanSubagentsDir` keeps suppressing
+    // while the file stays at/below it, and re-registers once it grows past it
+    // (a resume).
     //
-    // Fix #9a: bound the Set so it can't grow unboundedly over a long-lived
-    // gateway — evict the oldest id once the cap is hit (Set iteration
-    // order is insertion order, so `.values().next().value` is the oldest).
+    // Fix #9a: bound the Map so it can't grow unboundedly over a long-lived
+    // gateway — evict the oldest id once the cap is hit (Map iteration
+    // order is insertion order, so the first key is the oldest). A re-set of
+    // an existing key updates its value without moving it, so a re-completed
+    // (resumed-then-finished-again) agent just refreshes its terminal size.
     if (!terminatedAgentIds.has(agentId) && terminatedAgentIds.size >= terminatedAgentIdsCap) {
-      const oldest = terminatedAgentIds.values().next().value
+      const oldest = terminatedAgentIds.keys().next().value
       if (oldest != null) terminatedAgentIds.delete(oldest)
     }
-    terminatedAgentIds.add(agentId)
+    terminatedAgentIds.set(agentId, terminalSize)
     log?.(`subagent-watcher: cleaned up terminal agent ${agentId}`)
     // Authoritative terminal sweep → notify the worker-activity feed so its row
     // for this agent is removed even on the paths that never fire `onFinish`
@@ -2865,11 +3074,68 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       const filePath = join(subagentsPath, e)
       if (knownFiles.has(filePath)) continue
       const agentId = e.slice('agent-'.length, -'.jsonl'.length)
-      // Issue #1116 (Bug B): skip JSONLs whose agent already completed
-      // and was swept by cleanupTerminalAgent. Re-adding to knownFiles
-      // here would let a subsequent rescan re-register, fire a duplicate
-      // "Worker done", and loop forever every grace-window.
-      if (terminatedAgentIds.has(agentId)) continue
+      // Issue #1116 (Bug B) + issue #3315 (SendMessage resume). A rediscovered
+      // JSONL whose agent already went terminal + was swept is normally a
+      // static leftover Claude Code left on disk — re-registering it would
+      // re-read the terminal turn and re-fire a duplicate handback, looping
+      // every grace-window (#1116). BUT a SendMessage resume appends a NEW turn
+      // to the SAME agent-<id>.jsonl, growing the file PAST the size it had at
+      // terminal cleanup. That growth is the deterministic, lifecycle-driven
+      // signal (not a heuristic) that the worker resumed and must be tracked
+      // again so its progress card resumes updating. Distinguish the two by the
+      // recorded terminal size.
+      const terminalSize = terminatedAgentIds.get(agentId)
+      if (terminalSize !== undefined) {
+        // A worker whose terminal state was a FALSE finish (silent-stall
+        // synthesis) is owned by the issue-#3023 resurrection path
+        // (`checkResurrections`), which carries the bounded-chain +
+        // `onResurrect`/`onWorkerLost` semantics and re-reads from cursor 0 to
+        // rebuild the still-in-progress turn. Skipping it here avoids
+        // double-handling the same growth in one poll; this branch's concern is
+        // GENUINE terminal completions (real `turn_end`, no false-finish record)
+        // that were resumed via SendMessage (issue #3315). A false finish that
+        // has since been evicted from `falseFinishTracker` (512-cap) is no
+        // longer double-handled, so falling through to re-register it live here
+        // is correct.
+        if (falseFinishTracker.has(agentId)) continue
+        let currentSize: number
+        try {
+          currentSize = fs.statSync(filePath).size
+        } catch {
+          continue // unreadable — nothing to resume; keep suppressing
+        }
+        // At/below the terminal snapshot ⇒ static leftover file (#1116 Bug B):
+        // stay suppressed, do NOT re-register.
+        if (currentSize <= terminalSize) continue
+        // Grew past it ⇒ the worker resumed (#3315). Re-register as a fresh
+        // LIVE worker, reading only from the terminal boundary so the
+        // already-completed turn is not replayed. At-most-once per resume:
+        // dropping the id from terminatedAgentIds means the next completion
+        // re-adds it with the new (larger) terminal size, so one resume yields
+        // exactly one re-registration.
+        log?.(`subagent-watcher: agent ${agentId} resumed after terminal cleanup — JSONL grew ${terminalSize} → ${currentSize} bytes (SendMessage resume); re-registering as live so its progress card resumes (issue #3315)`)
+        terminatedAgentIds.delete(agentId)
+        historicalFiles.delete(filePath)
+        knownFiles.add(filePath)
+        // Issue #3373: the worker-activity feed latched a terminal `finalized`
+        // gate for this agentId at its genuine completion, so the `onProgress`
+        // cues the re-registration is about to re-fire would be SWALLOWED and no
+        // card would re-surface. Fire onResume FIRST (before registerAgent, whose
+        // initial read can synchronously re-emit onProgress) so the gateway clears
+        // that gate; the subsequent live cue then repaints a fresh row. Fired only
+        // on growth-past-terminal — never for a static leftover (the
+        // `currentSize <= terminalSize` continue above), so the anti-zombie latch
+        // still blocks genuinely-finished workers.
+        if (config.onResume != null) {
+          try {
+            config.onResume(agentId, registry.get(agentId)?.description ?? 'sub-agent')
+          } catch (cbErr) {
+            log?.(`subagent-watcher: onResume callback error ${agentId}: ${(cbErr as Error).message}`)
+          }
+        }
+        registerAgent(filePath, agentId, terminalSize)
+        continue
+      }
       knownFiles.add(filePath)
       // During the initial boot scan, mark every discovered file as
       // historical so stall-detection and completion notifications are

package/telegram-plugin/tests/activity-card-wiring.test.ts

@@ -20,6 +20,11 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+// #2996 P4-B: drainActivitySummary (the card-OPEN persist site) and
+// clearActivitySummary (the normal-CLOSE clear site) moved VERBATIM into
+// narrative-lane.ts (bodies indented +2 inside the factory — multi-line
+// markers below use the lane spelling).
+const laneSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'narrative-lane.ts'), 'utf-8')
 
 function between(src: string, startMarker: string, endMarker: string): string {
   const after = src.split(startMarker)[1] ?? ''
@@ -30,7 +35,7 @@ describe('activity-card durability wiring', () => {
   it('the card-OPEN path persists the durable handle (writeActivityCardRecord)', () => {
     // The open branch runs when activityMessageId transitions null → set.
     const openBranch = between(
-      gatewaySrc,
+      laneSrc,
       'if (turn.activityMessageId == null) {',
       'turn.activityLastSentRender = target',
     )
@@ -55,8 +60,8 @@ describe('activity-card durability wiring', () => {
 
   it('the normal-CLOSE path clears the durable handle, id-scoped (reap-race guard)', () => {
     const closeBody = between(
-      gatewaySrc,
-      'const id = turn.activityMessageId\n    turn.activityMessageId = null',
+      laneSrc,
+      'const id = turn.activityMessageId\n      turn.activityMessageId = null',
       'if (CLEAR_STATUS_ON_COMPLETION)',
     )
     expect(closeBody.length).toBeGreaterThan(50)

package/telegram-plugin/tests/activity-ever-opened-sticky.test.ts

@@ -32,6 +32,21 @@ const gatewaySrc = readFileSync(
   resolve(__dirname, '..', 'gateway', 'gateway.ts'),
   'utf-8',
 )
+// #2996 P4-A: one sticky-latch set site + the per-turn object-literal init live
+// in handleSessionEvent (the tool-label/answer send-success + the `enqueue`
+// turn ctor), which moved VERBATIM to stream-render.ts. The population spans
+// gateway.ts + that module.
+const streamSrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'stream-render.ts'),
+  'utf-8',
+)
+// #2996 P4-B: the drain-side set-TRUE site (drainActivitySummary) moved on
+// into narrative-lane.ts.
+const laneSrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'narrative-lane.ts'),
+  'utf-8',
+)
+const gatewayAndStreamSrc = gatewaySrc + '\n' + streamSrc + '\n' + laneSrc
 
 describe('M-2: activityEverOpened sticky-true invariant', () => {
   it('activityEverOpened = true appears only at the two feed-OPEN signal sites', () => {
@@ -39,19 +54,19 @@ describe('M-2: activityEverOpened sticky-true invariant', () => {
     // handback pre-turn ADOPTION seed (an adopted turn only edits, so it stamps
     // the flag itself). Both are set-TRUE; the sticky invariant (no reset to
     // false) is enforced by the next test.
-    const setTrueMatches = [...gatewaySrc.matchAll(/activityEverOpened\s*=\s*true/g)]
+    const setTrueMatches = [...gatewayAndStreamSrc.matchAll(/activityEverOpened\s*=\s*true/g)]
     expect(setTrueMatches).toHaveLength(2)
   })
 
   it('turn.activityEverOpened = false never appears (no standalone reset)', () => {
     // The only `false` value must be in the object literal initialiser
     // (e.g. `activityEverOpened: false`), never a standalone reassignment.
-    const resetMatches = [...gatewaySrc.matchAll(/turn\.activityEverOpened\s*=\s*false/g)]
+    const resetMatches = [...gatewayAndStreamSrc.matchAll(/turn\.activityEverOpened\s*=\s*false/g)]
     expect(resetMatches).toHaveLength(0)
   })
 
   it('activityEverOpened is initialised false in the turn object literal (per-turn reset)', () => {
     // The object literal form `activityEverOpened: false` must exist (per-turn init).
-    expect(gatewaySrc).toMatch(/activityEverOpened:\s*false/)
+    expect(gatewayAndStreamSrc).toMatch(/activityEverOpened:\s*false/)
   })
 })

package/telegram-plugin/tests/agent-button-callback-handler.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Outcome pins for the agent-emitted inline-keyboard callback family
+ * (`agent:` prefix, #271) extracted from the gateway's callback_query
+ * dispatcher (switchroom#2996 P6). Drives handleAgentButtonCallback with a
+ * mock ctx + injected deps and asserts: fall-through for non-agent data, the
+ * allowFrom gate, the ack-toast-first contract (#710), the exact InboundMessage
+ * envelope routed through the injected turn-safe delivery, the restarting
+ * notice only on bridge-offline, and the single-use keyboard strip + meta
+ * cleanup.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import {
+  handleAgentButtonCallback,
+  type AgentButtonCallbackDeps,
+} from '../gateway/agent-button-callback-handler.js'
+
+const DATA = 'agent:approve_pr'
+
+function makeCtx(over: Record<string, unknown> = {}) {
+  return {
+    from: { id: 42, username: 'ken' },
+    chat: { id: 42 },
+    callbackQuery: {
+      message: {
+        message_id: 77,
+        text: 'Deploy?',
+        reply_markup: {
+          inline_keyboard: [[{ text: 'Approve', callback_data: DATA }]],
+        },
+      },
+    },
+    answerCallbackQuery: vi.fn(async () => {}),
+    editMessageText: vi.fn(async () => {}),
+    editMessageReplyMarkup: vi.fn(async () => {}),
+    ...over,
+  } as any
+}
+
+function makeDeps(over: Partial<AgentButtonCallbackDeps> = {}) {
+  const deliverButtonTapInbound = vi.fn(async () => 'delivered')
+  const sendRestartingNotice = vi.fn()
+  const metaDelete = vi.fn()
+  const deps: AgentButtonCallbackDeps = {
+    loadAccess: () => ({ allowFrom: ['42'] }),
+    agentButtonMeta: { get: () => undefined, delete: metaDelete },
+    deliverButtonTapInbound,
+    sendRestartingNotice,
+    buttonConfirmSingleUseWarned: new Set(),
+    buttonConfirmParseModeWarned: new Set(),
+    log: vi.fn(),
+    ...over,
+  }
+  return { deps, deliverButtonTapInbound, sendRestartingNotice, metaDelete }
+}
+
+describe('handleAgentButtonCallback — routing + gates', () => {
+  it('returns false for non-agent callback data', async () => {
+    const { deps } = makeDeps()
+    const ctx = makeCtx()
+    expect(await handleAgentButtonCallback(ctx, 'perm:allow:abcde', deps)).toBe(false)
+    expect(ctx.answerCallbackQuery).not.toHaveBeenCalled()
+  })
+
+  it('gates non-allowlisted senders before any delivery', async () => {
+    const { deps, deliverButtonTapInbound } = makeDeps()
+    const ctx = makeCtx({ from: { id: 666 } })
+    expect(await handleAgentButtonCallback(ctx, DATA, deps)).toBe(true)
+    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({ text: 'Not authorized.' })
+    expect(deliverButtonTapInbound).not.toHaveBeenCalled()
+  })
+})
+
+describe('handleAgentButtonCallback — delivery envelope', () => {
+  it('acks FIRST with the default toast, then delivers the exact inbound (#710/#271)', async () => {
+    const { deps, deliverButtonTapInbound } = makeDeps()
+    const ctx = makeCtx()
+    process.env.SWITCHROOM_AGENT_NAME = 'klanker'
+    expect(await handleAgentButtonCallback(ctx, DATA, deps)).toBe(true)
+    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({ text: '✓ received' })
+    // Ack precedes delivery.
+    expect(ctx.answerCallbackQuery.mock.invocationCallOrder[0]).toBeLessThan(
+      deliverButtonTapInbound.mock.invocationCallOrder[0],
+    )
+    const [agent, msg] = deliverButtonTapInbound.mock.calls[0] as unknown as [string, any]
+    expect(agent).toBe('klanker')
+    expect(msg).toMatchObject({
+      type: 'inbound',
+      chatId: '42',
+      messageId: 77,
+      user: 'ken',
+      userId: 42,
+      text: '[user tapped button: "Approve" → approve_pr]',
+      meta: expect.objectContaining({
+        button_callback: 'true',
+        button_callback_data: 'approve_pr',
+        button_text: 'Approve',
+      }),
+    })
+  })
+
+  it('uses the stashed per-button ack_text when present', async () => {
+    // meta is keyed by the RAW payload (prefix stripped).
+    const metaMap = new Map([['approve_pr', { ack_text: 'On it!' }]])
+    const { deps } = makeDeps({
+      agentButtonMeta: { get: () => metaMap as any, delete: vi.fn() },
+    })
+    const ctx = makeCtx()
+    await handleAgentButtonCallback(ctx, DATA, deps)
+    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({ text: 'On it!' })
+  })
+
+  it('shows the restarting notice ONLY on bridge-offline', async () => {
+    const { deps, sendRestartingNotice } = makeDeps({
+      deliverButtonTapInbound: vi.fn(async () => 'buffered-bridge-offline'),
+    })
+    await handleAgentButtonCallback(makeCtx(), DATA, deps)
+    expect(sendRestartingNotice).toHaveBeenCalledWith('42', undefined)
+
+    const second = makeDeps({
+      deliverButtonTapInbound: vi.fn(async () => 'buffered-mid-turn'),
+    })
+    await handleAgentButtonCallback(makeCtx(), DATA, second.deps)
+    expect(second.sendRestartingNotice).not.toHaveBeenCalled()
+  })
+})
+
+describe('handleAgentButtonCallback — single-use strip', () => {
+  it('strips the keyboard by default (no stashed meta) after the tap', async () => {
+    const { deps } = makeDeps()
+    const ctx = makeCtx()
+    await handleAgentButtonCallback(ctx, DATA, deps)
+    expect(ctx.editMessageReplyMarkup).toHaveBeenCalledWith({
+      reply_markup: { inline_keyboard: [] },
+    })
+  })
+
+  it('preserves the keyboard when a button opts out via single_use:false', async () => {
+    const metaMap = new Map([['approve_pr', { single_use: false }]])
+    const metaDelete = vi.fn()
+    const { deps } = makeDeps({
+      agentButtonMeta: { get: () => metaMap as any, delete: metaDelete },
+    })
+    const ctx = makeCtx()
+    await handleAgentButtonCallback(ctx, DATA, deps)
+    expect(ctx.editMessageReplyMarkup).not.toHaveBeenCalled()
+    expect(metaDelete).not.toHaveBeenCalled()
+  })
+})