switchroom 0.19.15 → 0.19.16

package/telegram-plugin/tests/forwarded-rich-message-coalesce.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Outcome regression (#3516 follow-up): a forwarded rich (bot) message MUST
+ * coalesce through the same sliding window as `message:text`.
+ *
+ * THE BUG: PR #3516 registered `message:rich_message` but wired it with
+ * `mediaEnvelopeDeps`, whose `handleInbound` is the BARE (non-coalescing)
+ * inbound function — the same surface the cluster-A media-envelope handlers
+ * (contact/location/poll/…) use. The sibling text/photo/voice/attachment
+ * handlers all route through `handleInboundCoalesced`. Result: a forwarded
+ * bot message arriving in the same coalesce window as another inbound
+ * message did NOT fold into one turn — it bypassed the window entirely,
+ * contradicting rich-message-handler.ts's own docstring ("hands it to the
+ * normal COALESCING inbound pipeline … identical to message:text").
+ *
+ * Two guards, both anchored to the real production code:
+ *
+ *   1. WIRING (source-parse, deterministic RED/GREEN): parse gateway.ts and
+ *      assert the deps object passed to the `message:rich_message`
+ *      registration binds `handleInbound` to `handleInboundCoalesced` (the
+ *      coalescing entry point), the SAME path `message:text` takes. This
+ *      guard is RED on the pre-fix wiring (`mediaEnvelopeDeps`, bare
+ *      `handleInbound`) and GREEN after it.
+ *
+ *   2. OUTCOME (real grammy Bot + real handler + real coalescer): drive the
+ *      production `handleRichMessageMessage` and `message:text` through one
+ *      shared `createInboundCoalescer` (the exact module gateway.ts uses),
+ *      and assert a rich message + a text message in the same window flush
+ *      as ONE ordered turn — and that the bare (non-coalescing) surface the
+ *      bug used would instead emit TWO turns.
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { Bot } from 'grammy'
+import type { Update } from 'grammy/types'
+import { resetUpdateCounters } from './update-factory.js'
+import { handleRichMessageMessage } from '../gateway/rich-message-handler.js'
+import type { MediaEnvelopeDeps } from '../gateway/media-message-handlers.js'
+import {
+  createInboundCoalescer,
+  inboundCoalesceKey,
+} from '../gateway/inbound-coalesce.js'
+
+// ---------------------------------------------------------------------------
+// Guard 1 — wiring source-parse
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+/** The deps argument (arg 2) of `bot.on('message:rich_message', ctx =>
+ * handleRichMessageMessage(ctx, DEPS))` as an AST node, or null. */
+function findRichMessageDepsArg(): ts.Expression | null {
+  let found: ts.Expression | null = null
+  const visit = (node: ts.Node): void => {
+    if (found) return
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      ts.isIdentifier(node.expression.expression) &&
+      node.expression.expression.text === 'bot' &&
+      node.expression.name.text === 'on'
+    ) {
+      const arg0 = node.arguments[0]
+      const evName = arg0 && ts.isStringLiteralLike(arg0) ? arg0.text : null
+      if (evName === 'message:rich_message') {
+        // arg1 is `ctx => handleRichMessageMessage(ctx, DEPS)`
+        const arg1 = node.arguments[1]
+        if (arg1 && (ts.isArrowFunction(arg1) || ts.isFunctionExpression(arg1))) {
+          const body = arg1.body
+          const inner = !ts.isBlock(body) && ts.isCallExpression(body) ? body : undefined
+          if (inner && inner.arguments.length >= 2) found = inner.arguments[1]
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return found
+}
+
+/** Resolve the deps arg to its source text — inline object literal directly,
+ * or the initializer of the `const <name> = { … }` it names. */
+function resolveDepsText(arg: ts.Expression): string | null {
+  if (ts.isObjectLiteralExpression(arg)) return arg.getText(sourceFile)
+  if (ts.isIdentifier(arg)) {
+    let text: string | null = null
+    const visit = (node: ts.Node): void => {
+      if (text) return
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === arg.text &&
+        node.initializer
+      ) {
+        text = node.initializer.getText(sourceFile)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sourceFile)
+    return text
+  }
+  return null
+}
+
+describe('wiring: message:rich_message dispatches through the coalescing path', () => {
+  it('the rich_message registration passes deps that bind handleInbound to handleInboundCoalesced', () => {
+    const depsArg = findRichMessageDepsArg()
+    expect(depsArg, 'could not locate the message:rich_message registration deps arg').not.toBeNull()
+
+    const depsText = resolveDepsText(depsArg as ts.Expression)
+    expect(depsText, 'could not resolve the rich_message deps source text').not.toBeNull()
+
+    // The coalescing entry point — the same one message:text routes through.
+    // Pre-fix the deps was `mediaEnvelopeDeps` (bare `handleInbound,`
+    // shorthand), so this assertion is RED on the bug and GREEN with the fix.
+    expect(depsText).toContain('handleInbound: handleInboundCoalesced')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Guard 2 — outcome: real handler + real coalescer
+//
+// NOTE: Guard 2 drives its OWN `richCoalesces` boolean toggle rather than
+// importing the gateway's dispatch wiring, so it validates the coalescer
+// CONTRACT (folding/ordering into one turn vs. the pre-fix split) — it is NOT
+// a wiring regression guard. Guard 1 (the AST/source-parse over gateway.ts) is
+// the SOLE guard that regresses if the rich_message registration stops routing
+// through `handleInboundCoalesced`.
+// ---------------------------------------------------------------------------
+
+const CHAT_ID = -1004223464247
+const USER_ID = 777
+
+function makeBotInfo() {
+  return {
+    id: 999,
+    is_bot: true,
+    first_name: 'TestBot',
+    username: 'test_bot',
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+  }
+}
+
+/** Forwarded rich (bot) message, no top-level text/caption — the live shape. */
+function makeForwardedRichUpdate(update_id: number, blocks: unknown[]): Update {
+  const originUser = { id: 8500000001, is_bot: true, first_name: 'Klanker', username: 'meken_klanker_bot' }
+  return {
+    update_id,
+    message: {
+      message_id: update_id,
+      chat: { id: CHAT_ID, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: USER_ID, is_bot: false, first_name: 'Ken' },
+      date: 1784837003,
+      forward_origin: { type: 'user', date: 1784830000, sender_user: originUser },
+      forward_from: originUser,
+      forward_date: 1784830000,
+      rich_message: { blocks },
+    },
+  } as unknown as Update
+}
+
+function makeTextUpdate(update_id: number, text: string): Update {
+  return {
+    update_id,
+    message: {
+      message_id: update_id,
+      chat: { id: CHAT_ID, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: USER_ID, is_bot: false, first_name: 'Ken' },
+      date: 1784837004,
+      text,
+    },
+  } as unknown as Update
+}
+
+interface HarnessOptions {
+  /** Bind the rich handler's dispatch to the coalescing path (the fix) or to
+   * the bare non-coalescing path (the pre-fix bug). */
+  richCoalesces: boolean
+}
+
+/**
+ * Wire a real grammy Bot the way the production gateway does: message:text
+ * enqueues into a shared coalescer; message:rich_message goes through the
+ * REAL production handler with deps whose `handleInbound` is bound to either
+ * the same coalescer (fix) or a bare immediate dispatch (bug).
+ */
+function buildHarness(opts: HarnessOptions) {
+  const flushed: string[] = []
+
+  // The exact coalescer module the gateway uses. 1500ms sliding window.
+  const coalescer = createInboundCoalescer<{ text: string }>({
+    gapMs: 1500,
+    merge: entries => ({ text: entries.map(e => e.text).join('\n') }),
+    onFlush: (_key, merged) => flushed.push(merged.text),
+  })
+
+  const key = inboundCoalesceKey(String(CHAT_ID), null, String(USER_ID))
+
+  /** Coalescing dispatch — mirrors handleInboundCoalesced's enqueue step. */
+  const coalescedDispatch = async (text: string): Promise<void> => {
+    const { bypass } = coalescer.enqueue(key, { text })
+    if (bypass) flushed.push(text)
+  }
+  /** Bare dispatch — the pre-fix bug: every message is its own turn. */
+  const bareDispatch = async (text: string): Promise<void> => {
+    flushed.push(text)
+  }
+
+  const bot = new Bot('12345:TEST_TOKEN_NOT_REAL')
+  bot.botInfo = makeBotInfo()
+
+  bot.on('message:text', async ctx => {
+    await coalescedDispatch(ctx.message.text)
+  })
+
+  const richDeps: MediaEnvelopeDeps = {
+    handleInbound: async (_ctx, text) => {
+      await (opts.richCoalesces ? coalescedDispatch(text) : bareDispatch(text))
+    },
+    handleAckOnly: async () => {},
+    handleRefusal: async () => {},
+    log: () => {},
+  }
+  bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, richDeps))
+
+  return { bot, flushed }
+}
+
+const BLOCKS = [{ type: 'paragraph', text: 'forwarded body from a bot' }]
+
+describe('outcome: forwarded rich message coalesces with a sibling inbound', () => {
+  beforeEach(() => {
+    resetUpdateCounters()
+    vi.useFakeTimers()
+  })
+  afterEach(() => vi.useRealTimers())
+
+  it('rich + text in the same window flush as ONE ordered turn (the fix)', async () => {
+    const { bot, flushed } = buildHarness({ richCoalesces: true })
+
+    await bot.handleUpdate(makeForwardedRichUpdate(9001, BLOCKS))
+    // A second inbound arrives 500ms later — inside the 1500ms window.
+    vi.advanceTimersByTime(500)
+    await bot.handleUpdate(makeTextUpdate(9002, 'and my own note about it'))
+
+    // Nothing flushed yet — the window is still open.
+    expect(flushed).toEqual([])
+
+    // Window closes 1500ms after the LAST message (sliding window).
+    vi.advanceTimersByTime(1500)
+
+    // ONE turn, both bodies, rich body first (arrival order preserved).
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0]).toBe('forwarded body from a bot\nand my own note about it')
+  })
+
+  it('the pre-fix bare wiring would split them into TWO turns (bug characterization)', async () => {
+    const { bot, flushed } = buildHarness({ richCoalesces: false })
+
+    await bot.handleUpdate(makeForwardedRichUpdate(9003, BLOCKS))
+    // The rich message bypassed the window: it flushes immediately.
+    expect(flushed).toEqual(['forwarded body from a bot'])
+
+    vi.advanceTimersByTime(500)
+    await bot.handleUpdate(makeTextUpdate(9004, 'and my own note about it'))
+    vi.advanceTimersByTime(1500)
+
+    // Two separate turns — the fragmentation the fix eliminates.
+    expect(flushed).toEqual([
+      'forwarded body from a bot',
+      'and my own note about it',
+    ])
+  })
+})

package/telegram-plugin/tests/outbox-sweep-listen-button.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Regression: switchroom #3502 — the durable-outbox safety net dropped the 🔊
+ * Listen button from a net-delivered final answer.
+ *
+ * PR #3502 / commit 1a531ebb added the outbox-sweep deliverer, which sent the
+ * captured final answer via a RAW `bot.api.sendMessage` with no voice-out
+ * resolution — so any answer the net delivered lost the Listen button that the
+ * normal `sendReply` path injects. The fix threads a shared `planListenButton`
+ * decision into the sweep's chunked send (`createOutboxSend`) so a net-delivered
+ * answer is indistinguishable from a normally-delivered one.
+ *
+ * These tests assert OUTCOMES, not code paths:
+ *  - the delivered message actually carries the Listen keyboard when kokoro
+ *    on-demand voice-out is enabled;
+ *  - it does NOT when the agent supplied its own keyboard, when the TTS text is
+ *    empty, or when voice-out is not kokoro-on-demand.
+ * A test that only walked the code without asserting `reply_markup` on the sent
+ * message would not fail on the pre-fix RAW-send bug, so we assert the exact
+ * bytes handed to `sendMessage`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createOutboxSend } from '../gateway/outbox-sweep.js'
+import { makeOutboxListenMarkupResolver } from '../gateway/outbox-listen-markup.js'
+import {
+  planListenButton,
+  type ListenButtonVoiceOutPlan,
+} from '../voice-ondemand.js'
+
+const kokoroOnDemand: ListenButtonVoiceOutPlan = {
+  engine: 'kokoro',
+  speed: 1.1,
+  replyMode: 'on-demand',
+  ttsChunks: ['the spoken answer'],
+}
+
+// A passthrough retry that simply invokes the send fn once (no flood/thread
+// fallback needed for the unit under test).
+const passthroughRetry = <U>(fn: () => Promise<U>): Promise<U> => fn()
+
+function fakeBot() {
+  const calls: Array<{ chatId: string; text: string; opts: Record<string, unknown> }> = []
+  let n = 100
+  return {
+    calls,
+    api: {
+      sendMessage: async (chatId: string, text: string, opts: object) => {
+        calls.push({ chatId, text, opts: opts as Record<string, unknown> })
+        return { message_id: n++ }
+      },
+    },
+  }
+}
+
+describe('planListenButton — shared Listen-button decision', () => {
+  it('injects for kokoro on-demand with non-empty TTS and no agent keyboard', () => {
+    const plan = planListenButton({ voiceOutPlan: kokoroOnDemand, rawKeyboard: undefined })
+    expect(plan).not.toBeNull()
+    expect(plan!.replyMarkup.inline_keyboard[0]![0]!.text).toBe('🔊 Listen')
+    expect(plan!.replyMarkup.inline_keyboard[0]![0]!.callback_data).toBe(`voice:${plan!.token}`)
+    expect(plan!.payload.text).toBe('the spoken answer')
+    expect(plan!.payload.speed).toBe(1.1)
+  })
+
+  it('does NOT inject when the agent supplied its own keyboard (collision gate)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: kokoroOnDemand,
+      rawKeyboard: [[{ text: 'Approve', callback_data: 'ok' }]],
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject when the TTS text is empty (empty-TTS guard)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, ttsChunks: [''] },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject for openai on-demand (taps would dead-end on local sidecar)', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, engine: 'openai' },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('does NOT inject when reply_mode is not on-demand', () => {
+    const plan = planListenButton({
+      voiceOutPlan: { ...kokoroOnDemand, replyMode: 'voice+text' },
+      rawKeyboard: undefined,
+    })
+    expect(plan).toBeNull()
+  })
+
+  it('returns null when there is no voice-out plan', () => {
+    expect(planListenButton({ voiceOutPlan: null, rawKeyboard: undefined })).toBeNull()
+  })
+})
+
+describe('createOutboxSend — net-delivered answer carries the Listen button (#3502)', () => {
+  it('attaches the Listen keyboard as reply_markup when voice-out on-demand is enabled', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => planListenButton({ voiceOutPlan: kokoroOnDemand, rawKeyboard: undefined })!.replyMarkup,
+    })
+
+    await send('123', null, 'the final answer')
+
+    expect(bot.calls).toHaveLength(1)
+    const markup = bot.calls[0]!.opts.reply_markup as
+      | { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> }
+      | undefined
+    expect(markup).toBeDefined()
+    expect(markup!.inline_keyboard[0]![0]!.text).toBe('🔊 Listen')
+    // Guards against the pre-fix RAW send: no button would have been attached.
+  })
+
+  it('attaches the keyboard to the LAST chunk only (final visible message)', async () => {
+    const bot = fakeBot()
+    const markup = { inline_keyboard: [[{ text: '🔊 Listen', callback_data: 'voice:abcd1234' }]] }
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => markup,
+    })
+
+    // > 4000 chars → two chunks.
+    await send('123', null, 'x'.repeat(4500))
+
+    expect(bot.calls).toHaveLength(2)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    expect(bot.calls[1]!.opts.reply_markup).toEqual(markup)
+  })
+
+  it('delivers plain (no reply_markup) when the resolver returns undefined', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: () => undefined,
+    })
+
+    await send('123', 42, 'plain answer')
+
+    expect(bot.calls).toHaveLength(1)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    // thread id still threaded through
+    expect(bot.calls[0]!.opts.message_thread_id).toBe(42)
+  })
+
+  it('delivers plain when no resolver is wired at all (legacy behaviour preserved)', async () => {
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry })
+
+    await send('123', null, 'legacy answer')
+
+    expect(bot.calls).toHaveLength(1)
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+  })
+
+  it('empty text sends NOTHING and returns undefined (no empty-message retry wedge)', async () => {
+    // Telegram rejects an empty message body; a stray '' chunk would throw
+    // every sweep tick and wedge the record in a permanent retry. The send
+    // must short-circuit instead of calling sendMessage.
+    const bot = fakeBot()
+    const resolverCalls: string[] = []
+    const send = createOutboxSend({
+      getBot: () => bot,
+      retry: passthroughRetry,
+      resolveReplyMarkup: (_c, _t, text) => {
+        resolverCalls.push(text)
+        return undefined
+      },
+    })
+
+    const result = await send('123', null, '')
+
+    expect(result).toBeUndefined()
+    expect(bot.calls).toHaveLength(0)
+    // No point resolving a Listen button for a body we never send.
+    expect(resolverCalls).toEqual([])
+  })
+})
+
+describe('gateway wiring — makeOutboxListenMarkupResolver end-to-end (#3502)', () => {
+  // Pins the ACTUAL gateway resolver: the sweep must obtain the Listen keyboard
+  // AND persist the tap token when kokoro on-demand voice-out is enabled. If a
+  // future change re-severs the sweep delivery from voice-out resolution (the
+  // PR #3502 / commit 1a531ebb raw-sendMessage regression), the delivered
+  // message loses its button and these assertions go red.
+  it('a net-delivered answer carries the button and the tap token is cached', async () => {
+    const cached: Array<{ token: string; text: string }> = []
+    const enqueued: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => kokoroOnDemand,
+      cachePut: (token, payload) => cached.push({ token, text: payload.text }),
+      eagerVoiceEnabled: () => true,
+      enqueuePreSynth: (j) => enqueued.push(j.token),
+    })
+
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'the final answer the net is delivering')
+
+    const markup = bot.calls[0]!.opts.reply_markup as
+      | { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> }
+      | undefined
+    expect(markup).toBeDefined()
+    const btn = markup!.inline_keyboard[0]![0]!
+    expect(btn.text).toBe('🔊 Listen')
+    // The token on the button must be the one cached + eagerly pre-synthesized,
+    // so the tap resolves to real audio (not a dead token).
+    const token = btn.callback_data.replace('voice:', '')
+    expect(cached).toEqual([{ token, text: 'the spoken answer' }])
+    expect(enqueued).toEqual([token])
+  })
+
+  it('resolves to no button (and caches nothing) when voice-out is off', async () => {
+    const cached: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => null,
+      cachePut: (token) => cached.push(token),
+      eagerVoiceEnabled: () => true,
+      enqueuePreSynth: () => {},
+    })
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'plain answer, voice-out disabled')
+
+    expect(bot.calls[0]!.opts.reply_markup).toBeUndefined()
+    expect(cached).toEqual([])
+  })
+
+  it('skips eager pre-synth when the kill switch is off but still shows the button', async () => {
+    const enqueued: string[] = []
+    const resolve = makeOutboxListenMarkupResolver({
+      resolveVoiceOutPlan: () => kokoroOnDemand,
+      cachePut: () => {},
+      eagerVoiceEnabled: () => false,
+      enqueuePreSynth: (j) => enqueued.push(j.token),
+    })
+    const bot = fakeBot()
+    const send = createOutboxSend({ getBot: () => bot, retry: passthroughRetry, resolveReplyMarkup: resolve })
+    await send('123', null, 'answer')
+
+    expect(bot.calls[0]!.opts.reply_markup).toBeDefined()
+    expect(enqueued).toEqual([])
+  })
+})

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, afterEach } from 'vitest'
-import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync, utimesSync } from 'fs'
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync, utimesSync, readFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import {
@@ -1018,3 +1018,93 @@ describe('projectAssistantTextBlocks (shared text→narrative kernel)', () => {
     })
   })
 })
+
+// ─── #3519 sharpen: background-shell liveness markers, from REAL captured data ─
+// Fixtures are VERBATIM lines from a real agent transcript — no hand-written
+// approximations. Provenance (cited so a reviewer can independently verify;
+// this is a SURVIVING, reachable session — the earlier 1db49136 session was
+// rotated off host, so the fixture was regenerated from this one):
+//   file:  /host-home/.switchroom/agents/carrie/.claude/projects/
+//          -home-kenthompson--switchroom-agents-carrie/
+//          a6d2d33a-a8a6-40ce-81d0-cb4bd867ac89.jsonl  (claude CLI v2.1.197)
+//   line 109 → ALIVE: a FOREGROUND Bash (tool_use input has NO
+//            run_in_background) that the CLI auto-moved to the background at its
+//            ~120s foreground window (tool_result at 00:35:56Z) — the exact
+//            #3519 auto-background case. Carries BOTH the structured
+//            `toolUseResult.backgroundTaskId:"bxa4sv3dq"` and the launch string
+//            "Command running in background with ID: bxa4sv3dq. …".
+//   line 175 → DEAD: the CLI's proactive `<task-notification>` for the SAME id
+//            (`<task-id>bxa4sv3dq</task-id>`, `<status>completed</status>`),
+//            enqueued as a queue-operation.
+//   line 180 → the mirrored `type:"attachment"` copy of the same notification.
+// The three lines are copied into tests/fixtures/bg-shell-liveness-3519.jsonl
+// byte-for-byte EXCEPT the operator username, scrubbed in BOTH encodings — the
+// slash home path (`/home/<user>` → `~`) and the dashed tmp-path form
+// (`-home-<user>-` → `-home-user-`) — per repo PII policy
+// (scripts/check-no-pii-secrets.mjs). Every marker-bearing field —
+// backgroundTaskId, the launch string + id, the <task-notification> tags — is
+// untouched.
+describe('projectTranscriptLine — #3519 background-shell liveness (real fixtures)', () => {
+  const FIXTURE = join(__dirname, 'fixtures', 'bg-shell-liveness-3519.jsonl')
+  const lines = readFileSync(FIXTURE, 'utf8').split('\n').filter(l => l.length > 0)
+  const [aliveLine, deadEnqueueLine] = lines
+
+  it('ALIVE: emits backgroundTaskId from the real structured toolUseResult field', () => {
+    // The whole plumbing seam end-to-end: the raw captured bytes → the parsed
+    // tool_result event actually CARRIES backgroundTaskId, so the gateway can
+    // register the shell alive. If this field weren't in the real event, the
+    // signal would be unavailable — this proves it is.
+    const events = projectTranscriptLine(aliveLine)
+    const tr = events.find(e => e.kind === 'tool_result')
+    expect(tr).toBeDefined()
+    expect(tr).toMatchObject({
+      kind: 'tool_result',
+      toolUseId: 'toolu_01B7T3y1t95oHDEqYKwSmqaW',
+      backgroundTaskId: 'bxa4sv3dq',
+    })
+  })
+
+  it('DEAD: projects the real <task-notification> enqueue as a task_notification (completed)', () => {
+    // Proves the DEAD seam: the CLI's completion signal — which arrives as a
+    // queue-operation enqueue, NOT a tool_result — is parsed to the shell id +
+    // status the gateway drops from the alive-set. It must NOT be mis-read as
+    // an inbound user turn (no `enqueue` event).
+    const events = projectTranscriptLine(deadEnqueueLine)
+    expect(events).toEqual([
+      { kind: 'task_notification', taskId: 'bxa4sv3dq', status: 'completed' },
+    ])
+  })
+
+  it('the ALIVE and DEAD ids MATCH — a real launch pairs with its real completion', () => {
+    const alive = projectTranscriptLine(aliveLine).find(e => e.kind === 'tool_result')
+    const dead = projectTranscriptLine(deadEnqueueLine)[0]
+    expect(alive?.kind === 'tool_result' ? alive.backgroundTaskId : null)
+      .toBe(dead.kind === 'task_notification' ? dead.taskId : undefined)
+  })
+
+  it('SAFE DEGRADATION: a CLI that renamed the marker yields NO backgroundTaskId', () => {
+    // Simulate a future CLI that changed the launch shape: drop the structured
+    // field AND mutate the launch string. The parser must return NO id (so the
+    // gateway never registers a phantom-alive shell), which is what lets the
+    // silence-poke layer fall back to the 900s-bounded guard. Built by mutating
+    // the REAL line, so it stays traceable.
+    const obj = JSON.parse(aliveLine)
+    delete obj.toolUseResult.backgroundTaskId // structured field gone
+    obj.message.content[0].content =
+      'Task moved to the background (id withheld by a newer CLI).' // string changed
+    const events = projectTranscriptLine(JSON.stringify(obj))
+    const tr = events.find(e => e.kind === 'tool_result')
+    expect(tr).toBeDefined()
+    expect(tr?.kind === 'tool_result' ? tr.backgroundTaskId : 'X').toBeUndefined()
+  })
+
+  it('secondary path: the launch STRING alone still yields the id when the field is absent', () => {
+    // If a CLI keeps the human string but drops the structured field, the regex
+    // fallback still recovers the id — traceable, built from the real line.
+    const obj = JSON.parse(aliveLine)
+    delete obj.toolUseResult.backgroundTaskId
+    const events = projectTranscriptLine(JSON.stringify(obj))
+    const tr = events.find(e => e.kind === 'tool_result')
+    expect(tr?.kind === 'tool_result' ? tr.backgroundTaskId : null).toBe('bxa4sv3dq')
+  })
+})