switchroom 0.19.15 → 0.19.16

package/telegram-plugin/session-tail.ts

@@ -134,7 +134,23 @@ export type SessionEvent =
   // (naive summing across lines over-counts). Null messageId → un-dedupable,
   // counted as-is. Mirrors `sub_agent_usage` but for the parent's OWN tokens.
   | { kind: 'usage'; messageId: string | null; totalTokens: number }
-  | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
+  | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string
+      /**
+       * #3519 sharpen: the claude-CLI background-task id when THIS tool_result
+       * is the launch acknowledgement of a shell moved to the background (a
+       * foreground Bash that exceeded the CLI foreground window, or an explicit
+       * run_in_background:true). Sourced PRIMARILY from the structured
+       * top-level `toolUseResult.backgroundTaskId` field (version-robust), with
+       * a regex on the `content` string as a secondary. Absent on ordinary
+       * (completed-in-foreground) tool_results. Marks the shell ALIVE. */
+      backgroundTaskId?: string }
+  /**
+   * #3519 sharpen: a claude-CLI `<task-notification>` — the proactive
+   * completion signal the CLI enqueues when a backgrounded shell finishes
+   * (`<status>completed</status>`) or errors. Marks the shell DEAD, restoring
+   * ~300s wedge recovery once the launching bash is no longer running.
+   */
+  | { kind: 'task_notification'; taskId: string; status: string }
   // `reason` is set ONLY by an internal gateway-synthesized turn_end (never by
   // the JSONL projection). `answer-ready-quiescence` (PR A) marks the positive
   // deterministic quiescence-flush signal, which — unlike the orphaned-reply
@@ -259,6 +275,60 @@ function extractToolResultErrorText(content: unknown): string {
   return ''
 }
 
+/**
+ * #3519 sharpen — ALIVE marker (primary): read the claude-CLI background-task
+ * id off the structured, sibling top-level `toolUseResult.backgroundTaskId`
+ * field of a `type:"user"` transcript line. This is the version-robust source
+ * (a named JSON field, not prose). Real shape (carrie session
+ * a6d2d33a-…, v2.1.197, line 109):
+ *   "toolUseResult":{…,"backgroundTaskId":"bxa4sv3dq"}
+ * Returns the id, or null when the line carries no backgrounded shell.
+ */
+export function parseBackgroundTaskId(obj: Record<string, unknown>): string | null {
+  const tur = obj.toolUseResult
+  if (typeof tur === 'object' && tur != null) {
+    const id = (tur as Record<string, unknown>).backgroundTaskId
+    if (typeof id === 'string' && id.length > 0) return id
+  }
+  return null
+}
+
+/**
+ * #3519 sharpen — ALIVE marker (secondary): match the launch STRING in the
+ * tool_result `content` when the structured field is absent (older CLI, or a
+ * shape change that keeps the human string). Real bytes (same line 109):
+ *   "Command running in background with ID: bxa4sv3dq. Output is being written…"
+ * DELIBERATELY the fallback, not the primary — if BOTH miss (CLI changed the
+ * string too) the caller degrades to the 900s-bounded sawBash guard. Accepts
+ * the same string|content-block shapes as extractToolResultErrorText.
+ */
+export function parseBackgroundLaunchString(content: unknown): string | null {
+  const text = typeof content === 'string'
+    ? content
+    : extractToolResultErrorText(content)
+  const m = text.match(/Command running in background with ID: (\w+)/)
+  return m != null ? m[1] : null
+}
+
+/**
+ * #3519 sharpen — DEAD marker: parse a claude-CLI `<task-notification>` block.
+ * The CLI enqueues this proactively when a backgrounded shell finishes. Real
+ * bytes (carrie session a6d2d33a-…, v2.1.197, line 175 queue-operation enqueue
+ * content, and mirrored line 180 attachment):
+ *   "<task-notification>\n<task-id>bxa4sv3dq</task-id>\n…\n<status>completed</status>\n…"
+ * Returns {taskId,status} when both tags are present, else null (so an
+ * ordinary inbound enqueue falls through to the normal user-turn path).
+ */
+export function parseTaskNotification(
+  content: string,
+): { taskId: string; status: string } | null {
+  if (!content.includes('<task-notification>')) return null
+  const idM = content.match(/<task-id>([^<]+)<\/task-id>/)
+  const stM = content.match(/<status>([^<]+)<\/status>/)
+  if (idM == null || stM == null) return null
+  return { taskId: idM[1].trim(), status: stM[1].trim() }
+}
+
 /**
  * THE single text→narrative projection primitive. Both projectTranscriptLine
  * and projectSubagentLine derive their text events through this helper so
@@ -481,6 +551,15 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     const op = obj.operation as string | undefined
     if (op === 'enqueue') {
       const content = (obj.content as string | undefined) ?? ''
+      // #3519 sharpen: a `<task-notification>` is NOT a real inbound user
+      // turn — it is the claude CLI's proactive background-shell completion
+      // signal, enqueued as a synthetic command. Project it as the DEAD
+      // marker so the liveness registry can drop the shell (restoring ~300s
+      // wedge recovery) rather than mis-reading it as a user message.
+      const notif = parseTaskNotification(content)
+      if (notif != null) {
+        return [{ kind: 'task_notification', taskId: notif.taskId, status: notif.status }]
+      }
       const { chatId, messageId, threadId } = parseChannelMeta(content)
       return [{ kind: 'enqueue', chatId, messageId, threadId, rawContent: content }]
     }
@@ -578,6 +657,11 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     const message = obj.message as Record<string, unknown> | undefined
     const content = message?.content as Array<Record<string, unknown>> | undefined
     if (!Array.isArray(content)) return []
+    // #3519 sharpen: the background-launch id is a per-LINE fact carried on
+    // the sibling top-level `toolUseResult.backgroundTaskId` (version-robust
+    // structured field), with the launch STRING as a secondary. Parsed once
+    // and attached to this line's tool_result event to mark the shell ALIVE.
+    const backgroundTaskId = parseBackgroundTaskId(obj)
     const events: SessionEvent[] = []
     for (const c of content) {
       if (c.type === 'tool_result') {
@@ -588,6 +672,9 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
           toolName: null,
           isError,
           errorText: isError ? extractToolResultErrorText(c.content) : undefined,
+          backgroundTaskId: backgroundTaskId
+            ?? parseBackgroundLaunchString(c.content)
+            ?? undefined,
         })
       }
     }

package/telegram-plugin/silence-poke.ts

@@ -93,6 +93,34 @@ export interface SilencePokeState {
    * clock — the design choice in this module's header is preserved.
    * We only enrich the fallback TEXT, not the timing. */
   inFlightTools: Map<string, { name: string; startedAt: number; label: string | null }>
+  /**
+   * #3519: true once ANY `Bash` tool_use has been observed in this turn.
+   * A foreground `Bash` that exceeds the claude-CLI foreground window is
+   * auto-moved to the background: its `tool_result` returns to the model
+   * (so `inFlightTools` empties and `isLegitimatelyWorking()`'s foreground
+   * / async-dispatch checks all go false), yet the process keeps running
+   * and the model sits silent waiting on it. That silent gap is invisible
+   * to every existing "still working" signal, so the 300s fallback fired
+   * mid-work — nulling `currentTurn`, tearing down the pinned progress
+   * card, and letting the next tool burst mint a BRAND-NEW card (the
+   * stacked-cards bug). Arming this flag on the first Bash of the turn lets
+   * the fallback defer such gaps. Turn-scoped (set here, only cleared by a
+   * fresh `startTurn`); bounded by `fallbackHardCeiling` so a genuinely
+   * wedged bash-turn still unwedges at the ceiling. Does NOT reset the
+   * silence clock — a real reply / feed edit still does that; this only
+   * gates the terminal teardown. */
+  sawBashThisTurn: boolean
+  /**
+   * #3519 sharpen: claude-CLI background shells PROVEN alive right now. A
+   * shell is added on its launch marker (structured `backgroundTaskId`, via
+   * `noteBackgroundShellAlive`) and removed when the CLI proactively reports
+   * it done (`<task-notification>` completed/failed) or the model `KillShell`s
+   * it (via `noteBackgroundShellDead`). Non-empty ⇒ a process is running, so
+   * defer the 300s teardown. Empty ⇒ nothing running, so a FINISHED bash no
+   * longer defers — restoring ~300s wedge recovery that the coarse
+   * `sawBashThisTurn` guard held to 900s. Turn-scoped (cleared by startTurn),
+   * bounded by `fallbackHardCeiling` like every other defer. */
+  aliveShells: Set<string>
 }
 
 export interface ThresholdsMs {
@@ -217,6 +245,21 @@ const state = new Map<string, SilencePokeState>()
 let timer: ReturnType<typeof setInterval> | null = null
 let activeDeps: SilencePokeDeps | null = null
 
+/**
+ * #3519 sharpen — deterministic SAFE-DEGRADATION latch (process-scoped).
+ * Flipped true the first time `noteBackgroundShellAlive` fires, i.e. the
+ * moment the session-tail marker parser resolves a real `backgroundTaskId`
+ * against the live claude CLI. Its purpose is to distinguish two look-alike
+ * states that both present as "a Bash ran but no shell is registered alive":
+ *   • CLI markers work, the bash simply FINISHED  → trust the empty alive-set,
+ *     let the 300s fallback fire (fast wedge recovery restored); and
+ *   • CLI changed its markers so the parser never matches → we CANNOT tell a
+ *     live auto-backgrounded bash from a finished one, so fall back to the
+ *     coarse 900s-bounded `sawBashThisTurn` guard (never stack, never hang).
+ * Once ANY marker has parsed, the CLI is proven compatible and the alive-set
+ * is authoritative. Never seen ⇒ stay conservative. Reset by tests only. */
+let bgMarkerParserConfirmed = false
+
 /**
  * True iff the kill switch is OFF. Re-read every call so tests can
  * toggle process.env without reloading the module.
@@ -238,9 +281,40 @@ export function startTurn(key: string, now: number): void {
     fallbackFired: false,
     floorFired: false,
     inFlightTools: new Map(),
+    sawBashThisTurn: false,
+    aliveShells: new Set(),
   })
 }
 
+/**
+ * #3519 sharpen: register a claude-CLI background shell as ALIVE for `key`.
+ * Called by the gateway when session-tail resolves a `backgroundTaskId` on a
+ * tool_result (a foreground Bash auto-moved to the background, or an explicit
+ * run_in_background:true). Flips the process-scoped parser-confirmed latch so
+ * the safe-degradation path knows the CLI markers are compatible. No-op when
+ * the key has no live turn (the launch outlived its turn — the cross-turn
+ * ambient owns that case, not the 300s teardown).
+ */
+export function noteBackgroundShellAlive(key: string, shellId: string): void {
+  bgMarkerParserConfirmed = true
+  const s = state.get(key)
+  if (s == null) return
+  s.aliveShells.add(shellId)
+}
+
+/**
+ * #3519 sharpen: mark a background shell DEAD for `key`. Called by the gateway
+ * on a `<task-notification>` (completed/failed) or a `KillShell`. Idempotent —
+ * removing an unknown id (already cleared, or launched in a prior turn) is a
+ * no-op. Once the set empties, a subsequent >300s silence is a real wedge and
+ * the fallback fires at ~300s.
+ */
+export function noteBackgroundShellDead(key: string, shellId: string): void {
+  const s = state.get(key)
+  if (s == null) return
+  s.aliveShells.delete(shellId)
+}
+
 /**
  * Record a fresh user-visible outbound message (reply or stream_reply
  * first-emit). Resets the silence clock so the 300s fallback is measured
@@ -313,6 +387,14 @@ export function noteToolStart(
   const s = state.get(key)
   if (s == null) return
   s.inFlightTools.set(toolUseId, { name, startedAt: now, label })
+  // #3519: arm the background-bash defer on the first Bash of the turn.
+  // A foreground Bash can be auto-moved to the background by the claude CLI
+  // once it crosses the foreground window; its tool_result then returns
+  // (draining inFlightTools) while the process keeps running and the model
+  // goes silent waiting on it. That gap is invisible to every other "still
+  // working" signal, so without this the 300s fallback tore down the pinned
+  // card mid-work and the next burst minted a fresh one (stacked cards).
+  if (name === 'Bash') s.sawBashThisTurn = true
 }
 
 /**
@@ -541,8 +623,13 @@ function tick(now: number): void {
       //   2. Legacy `deferFallbackWhileToolInFlight` boolean — covers only
       //      `inFlightTools.size > 0`; kept for test fixtures that set it
       //      directly without wiring the callback.
+      //   3. #3519 `sawBashThisTurn` — covers the claude-CLI-side background
+      //      bash gap the two paths above are blind to (foreground Bash moved
+      //      to background: tool_result returned, process still running, model
+      //      silent). Independent of the callback so it holds even when
+      //      `isLegitimatelyWorking()` returns false.
       //
-      // In both cases: `continue` WITHOUT setting fallbackFired so the next
+      // In all cases: `continue` WITHOUT setting fallbackFired so the next
       // tick re-checks. Once the work signal clears and the turn stays silent
       // past the base threshold, or the ceiling is crossed, the fallback fires.
       const ceiling = thresholds.fallbackHardCeiling ?? Number.POSITIVE_INFINITY
@@ -551,6 +638,30 @@ function tick(now: number): void {
         const forceDisable = process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS === '0'
         if (!forceDisable && activeDeps.isLegitimatelyWorking != null) {
           if (activeDeps.isLegitimatelyWorking(key)) continue
+          // #3519 sharpen: even when the callback reports "not working", a
+          // `Bash` earlier this turn may have been auto-moved to the CLI-side
+          // background (its tool_result returned, so every foreground /
+          // async-dispatch signal is false, yet the process is alive and the
+          // model sits silent on it) — the gap `isLegitimatelyWorking` is
+          // blind to by construction. Two-layer defer, sharp then safe:
+          //
+          //   (1) PROVEN-alive — a background shell registered from its
+          //       structured `backgroundTaskId` launch marker and not yet
+          //       reported dead (`<task-notification>` completed / KillShell).
+          //       A process is running RIGHT NOW, so defer. When it finishes,
+          //       the alive-set empties and the fallback fires at ~300s —
+          //       restoring fast wedge recovery the coarse guard held to 900s.
+          if (s.aliveShells.size > 0) continue
+          //   (2) SAFE DEGRADATION — only while the CLI markers have NEVER
+          //       parsed (`!bgMarkerParserConfirmed`): we cannot then tell a
+          //       live auto-backgrounded bash from a finished one, so fall
+          //       back to the coarse turn-scoped `sawBashThisTurn` guard —
+          //       900s-bounded by `fallbackHardCeiling` (never stacks, never
+          //       hangs). Once ANY marker has parsed, the CLI is proven
+          //       compatible, this layer switches off, and layer (1) alone
+          //       governs. Scoped to the modern callback-wired path so the
+          //       legacy defer-off / defer-bool fixtures keep their semantics.
+          if (!bgMarkerParserConfirmed && s.sawBashThisTurn) continue
         } else if (!forceDisable && activeDeps.deferFallbackWhileToolInFlight === true && s.inFlightTools.size > 0) {
           continue
         }
@@ -657,4 +768,10 @@ export function __getStateForTests(key: string): SilencePokeState | undefined {
 export function __resetAllForTests(): void {
   state.clear()
   stopTimer()
+  bgMarkerParserConfirmed = false
+}
+
+/** Test-only: peek at the process-scoped #3519 safe-degradation latch. */
+export function __bgMarkerParserConfirmedForTests(): boolean {
+  return bgMarkerParserConfirmed
 }

package/telegram-plugin/tests/background-shell-liveness.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { applyBackgroundShellLiveness } from '../gateway/background-shell-liveness.js'
+import { projectTranscriptLine, type SessionEvent } from '../session-tail.js'
+
+// #3519 sharpen — the glue that maps parsed session events to the silence-poke
+// background-shell registry. Driven by the REAL fixtures (carrie session
+// a6d2d33a-…, claude v2.1.197; see tests/fixtures/bg-shell-liveness-3519.jsonl)
+// parsed through the production projectTranscriptLine path, so the event shapes
+// here are exactly what the gateway sees at runtime.
+describe('applyBackgroundShellLiveness (real markers)', () => {
+  const FIXTURE = join(__dirname, 'fixtures', 'bg-shell-liveness-3519.jsonl')
+  const lines = readFileSync(FIXTURE, 'utf8').split('\n').filter(l => l.length > 0)
+  const aliveEv = projectTranscriptLine(lines[0]).find(e => e.kind === 'tool_result')!
+  const deadEv = projectTranscriptLine(lines[1])[0]
+  // The real shell id carried by both the ALIVE and DEAD fixture lines.
+  const REAL_ID = aliveEv.kind === 'tool_result' ? aliveEv.backgroundTaskId : undefined
+
+  function spyRegistry() {
+    const calls: Array<{ fn: 'alive' | 'dead'; key: string; id: string }> = []
+    return {
+      calls,
+      noteBackgroundShellAlive: (key: string, id: string) => calls.push({ fn: 'alive', key, id }),
+      noteBackgroundShellDead: (key: string, id: string) => calls.push({ fn: 'dead', key, id }),
+    }
+  }
+
+  it('ALIVE: a real tool_result with backgroundTaskId → noteBackgroundShellAlive', () => {
+    const r = spyRegistry()
+    applyBackgroundShellLiveness(r, 'c:0', aliveEv)
+    expect(r.calls).toEqual([{ fn: 'alive', key: 'c:0', id: REAL_ID! }])
+  })
+
+  it('DEAD: a real <task-notification> completion → noteBackgroundShellDead', () => {
+    const r = spyRegistry()
+    applyBackgroundShellLiveness(r, 'c:0', deadEv)
+    expect(r.calls).toEqual([{ fn: 'dead', key: 'c:0', id: REAL_ID! }])
+  })
+
+  it('DEAD: a KillShell tool_use → noteBackgroundShellDead by shell_id', () => {
+    const r = spyRegistry()
+    const ev: SessionEvent = { kind: 'tool_use', toolName: 'KillShell', toolUseId: 't9', input: { shell_id: REAL_ID! } }
+    applyBackgroundShellLiveness(r, 'c:0', ev)
+    expect(r.calls).toEqual([{ fn: 'dead', key: 'c:0', id: REAL_ID! }])
+  })
+
+  it('no-op: an ordinary (foreground-completed) tool_result carries no marker', () => {
+    const r = spyRegistry()
+    const ev: SessionEvent = { kind: 'tool_result', toolUseId: 't1', toolName: null }
+    applyBackgroundShellLiveness(r, 'c:0', ev)
+    expect(r.calls).toEqual([])
+  })
+
+  it('DEFENSIVE: a hypothetical non-terminal <task-notification> does NOT mark the shell dead', () => {
+    // Guards a future CLI that emits an interim (still-running) notification.
+    // The terminal-status gate must keep a live shell in the alive-set — only
+    // completed/failed/killed drop it. Built from the SAME real shell id so the
+    // scenario is a faithful "what if this id got an interim update" case.
+    const r = spyRegistry()
+    const interim: SessionEvent = { kind: 'task_notification', taskId: REAL_ID!, status: 'running' }
+    applyBackgroundShellLiveness(r, 'c:0', interim)
+    expect(r.calls).toEqual([])
+  })
+
+  it('no-op: a non-KillShell tool_use is ignored', () => {
+    const r = spyRegistry()
+    const ev: SessionEvent = { kind: 'tool_use', toolName: 'Bash', toolUseId: 't1', input: { command: 'ls' } }
+    applyBackgroundShellLiveness(r, 'c:0', ev)
+    expect(r.calls).toEqual([])
+  })
+})

package/telegram-plugin/tests/feed-survival.test.ts

@@ -191,12 +191,18 @@ describe('silence-poke — isLegitimatelyWorking callback (default-on defer)', (
     // When isLegitimatelyWorking is wired, it is consulted; the legacy flag
     // is not consulted for the new path. Verify by having callback=false and
     // inFlightTools non-empty — the fallback fires because the callback says "no".
+    // NOTE (#3519): the in-flight tool here must be a NON-Bash tool. A `Bash`
+    // arms the CLI-side background-bash defer (a foreground Bash the callback
+    // is blind to once it moves to the background), which intentionally holds
+    // the fallback back even when the callback returns false — so using Bash
+    // would exercise that new defer rather than the callback-supersedes-legacy
+    // path this test pins. `Grep` can never be a detached background process.
     const f = setupSilenceDeps({
       thresholds: { fallback: 300_000, fallbackHardCeiling: 900_000 },
       isLegitimatelyWorking: () => false,
     })
     startTurn('chat:0', 0)
-    noteToolStart('chat:0', 't1', 'Bash', 'audit', 10_000)
+    noteToolStart('chat:0', 't1', 'Grep', 'audit', 10_000)
     __tickForTests(300_000)
     // callback says false → no defer, fallback fires
     expect(f.fallbacks).toHaveLength(1)

package/telegram-plugin/tests/fixtures/bg-shell-liveness-3519.jsonl

@@ -0,0 +1,3 @@
+{"parentUuid":"69f789b8-6f8a-46cd-baf0-58fb2114b866","isSidechain":false,"promptId":"4a2992ca-82ba-49cd-bde6-c4c9ac2e67eb","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01B7T3y1t95oHDEqYKwSmqaW","type":"tool_result","content":"Command running in background with ID: bxa4sv3dq. Output is being written to: /tmp/claude-10098/-home-user--switchroom-agents-carrie/fdc3453e-36da-4480-8c69-ebbcae6b4195/tasks/bxa4sv3dq.output. You will be notified when it completes. To check interim output, use Read on that file path.","is_error":false}]},"uuid":"36ad560b-fe0c-4a1a-aab5-215de2ceab8a","timestamp":"2026-07-03T00:35:56.966Z","toolUseResult":{"stdout":"","stderr":"","interrupted":false,"isImage":false,"noOutputExpected":false,"backgroundTaskId":"bxa4sv3dq"},"sourceToolAssistantUUID":"69f789b8-6f8a-46cd-baf0-58fb2114b866","userType":"external","entrypoint":"cli","cwd":"~/.switchroom/agents/carrie","sessionId":"a6d2d33a-a8a6-40ce-81d0-cb4bd867ac89","version":"2.1.197","gitBranch":"HEAD"}
+{"type":"queue-operation","operation":"enqueue","timestamp":"2026-07-03T00:42:51.932Z","sessionId":"a6d2d33a-a8a6-40ce-81d0-cb4bd867ac89","content":"<task-notification>\n<task-id>bxa4sv3dq</task-id>\n<tool-use-id>toolu_01B7T3y1t95oHDEqYKwSmqaW</tool-use-id>\n<output-file>/tmp/claude-10098/-home-user--switchroom-agents-carrie/fdc3453e-36da-4480-8c69-ebbcae6b4195/tasks/bxa4sv3dq.output</output-file>\n<status>completed</status>\n<summary>Background command \"Search for any Buildkite product spec material on disk\" completed (exit code 0)</summary>\n</task-notification>"}
+{"parentUuid":"62dd16ed-917b-4092-861e-81437bf138fb","isSidechain":false,"attachment":{"type":"queued_command","prompt":"<task-notification>\n<task-id>bxa4sv3dq</task-id>\n<tool-use-id>toolu_01B7T3y1t95oHDEqYKwSmqaW</tool-use-id>\n<output-file>/tmp/claude-10098/-home-user--switchroom-agents-carrie/fdc3453e-36da-4480-8c69-ebbcae6b4195/tasks/bxa4sv3dq.output</output-file>\n<status>completed</status>\n<summary>Background command \"Search for any Buildkite product spec material on disk\" completed (exit code 0)</summary>\n</task-notification>","commandMode":"task-notification","timestamp":"2026-07-03T00:42:51.932Z"},"type":"attachment","uuid":"3702ef15-3c4e-4c5d-84c1-e5c2c59b038e","timestamp":"2026-07-03T00:42:51.932Z","userType":"external","entrypoint":"cli","cwd":"/share/code/product-playbook/playbook","sessionId":"a6d2d33a-a8a6-40ce-81d0-cb4bd867ac89","version":"2.1.197","gitBranch":"HEAD"}