switchroom 0.5.0

package/telegram-plugin/tests/turn-signal-tracker.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  reset,
+  noteSignal,
+  getLongestGap,
+  getLastSignalAt,
+  clear,
+  __resetAllForTests,
+} from '../turn-signal-tracker.js'
+
+beforeEach(() => {
+  __resetAllForTests()
+})
+
+describe('turn-signal-tracker', () => {
+  it('reset() initialises a fresh turn with zero gap', () => {
+    reset('chat:thread', 1000)
+    expect(getLongestGap('chat:thread')).toBe(0)
+    expect(getLastSignalAt('chat:thread')).toBe(1000)
+  })
+
+  it('noteSignal() updates lastSignalAt and accumulates the longest gap', () => {
+    reset('k', 1000)
+    noteSignal('k', 1500) // gap=500
+    expect(getLongestGap('k')).toBe(500)
+    expect(getLastSignalAt('k')).toBe(1500)
+
+    noteSignal('k', 1700) // gap=200, smaller
+    expect(getLongestGap('k')).toBe(500)
+    expect(getLastSignalAt('k')).toBe(1700)
+
+    noteSignal('k', 4500) // gap=2800, new max
+    expect(getLongestGap('k')).toBe(2800)
+    expect(getLastSignalAt('k')).toBe(4500)
+
+    noteSignal('k', 5000) // gap=500, smaller
+    expect(getLongestGap('k')).toBe(2800)
+  })
+
+  it('noteSignal() on an unknown key is a no-op (no state created)', () => {
+    noteSignal('untracked', 1000)
+    expect(getLongestGap('untracked')).toBe(0)
+    expect(getLastSignalAt('untracked')).toBeUndefined()
+  })
+
+  it('separate keys track independently', () => {
+    reset('chatA', 1000)
+    reset('chatB', 1000)
+    noteSignal('chatA', 5000) // gap=4000
+    noteSignal('chatB', 1500) // gap=500
+    expect(getLongestGap('chatA')).toBe(4000)
+    expect(getLongestGap('chatB')).toBe(500)
+  })
+
+  it('reset() on an existing key starts a fresh window', () => {
+    reset('k', 1000)
+    noteSignal('k', 5000) // gap=4000
+    expect(getLongestGap('k')).toBe(4000)
+
+    // New turn — counter resets even though prior gap was huge
+    reset('k', 10000)
+    noteSignal('k', 10100)
+    expect(getLongestGap('k')).toBe(100)
+  })
+
+  it('clear() removes state for a key', () => {
+    reset('k', 1000)
+    noteSignal('k', 2000)
+    clear('k')
+    expect(getLongestGap('k')).toBe(0)
+    expect(getLastSignalAt('k')).toBeUndefined()
+  })
+
+  it('clear() on an unknown key is a no-op (no error)', () => {
+    expect(() => clear('never-tracked')).not.toThrow()
+  })
+
+  it('getLongestGap() never returns negative even with out-of-order timestamps', () => {
+    // Pathological case: clocks moving backwards (NTP slew, etc).
+    reset('k', 5000)
+    noteSignal('k', 4000) // negative-ish gap
+    // Whatever the implementation does, the returned gap should still be
+    // a sensible number for downstream histogram code.
+    const gap = getLongestGap('k')
+    expect(typeof gap).toBe('number')
+    expect(Number.isFinite(gap)).toBe(true)
+  })
+
+  it('typical full-turn flow — reset, multiple signals, clear', () => {
+    const k = 'flow-test'
+    reset(k, 0)
+
+    // Simulate a turn with periodic signals + one big silent stretch
+    noteSignal(k, 200)   // gap=200
+    noteSignal(k, 700)   // gap=500
+    noteSignal(k, 1100)  // gap=400
+    // ── 3.5s of silence (model thinking) ──
+    noteSignal(k, 4600)  // gap=3500 (longest)
+    noteSignal(k, 5000)  // gap=400
+
+    expect(getLongestGap(k)).toBe(3500)
+
+    // turn_end emits the metric, then clears
+    clear(k)
+    expect(getLongestGap(k)).toBe(0)
+  })
+})

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

@@ -0,0 +1,323 @@
+/**
+ * Tests for Phase 1 of #332 — turns writer wiring.
+ *
+ * Covers the four acceptance criteria from the issue:
+ *   1. Clean turn: insert + finalize → row has ended_via='stop', non-null
+ *      ended_at, correct previews.
+ *   2. Mid-turn restart: insert without finalize, simulate gateway boot via
+ *      markOrphanedAsRestarted → row has ended_via='restart'.
+ *   3. Multiple concurrent turns same chat: each row has a unique turn_key,
+ *      no cross-contamination.
+ *   4. tool_call_count increments correctly for N tool_use events.
+ *
+ * These tests run under Bun (bun:sqlite is a Bun built-in). They are
+ * excluded from vitest.config.ts and run via `bun test` or the `test:bun`
+ * script in the root package.json.
+ */
+
+import { describe, it, expect, beforeEach } from 'bun:test'
+import {
+  openTurnsDbInMemory,
+  recordTurnStart,
+  recordTurnEnd,
+  markOrphanedAsRestarted,
+} from '../registry/turns-schema.js'
+
+// ---------------------------------------------------------------------------
+// 1. Clean turn
+// ---------------------------------------------------------------------------
+
+describe('clean turn (Phase 1 #332)', () => {
+  it('insert + finalize → ended_via=stop, non-null ended_at, correct previews', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, {
+      turnKey: 'chat1:_:1000',
+      chatId: 'chat1',
+      userPromptPreview: 'Hello, can you help me?',
+    })
+
+    // Before finalization the row is open.
+    const open = db
+      .prepare('SELECT ended_at, ended_via FROM turns WHERE turn_key = ?')
+      .get('chat1:_:1000') as Record<string, unknown>
+    expect(open['ended_at']).toBeNull()
+    expect(open['ended_via']).toBeNull()
+
+    recordTurnEnd(db, {
+      turnKey: 'chat1:_:1000',
+      endedVia: 'stop',
+      assistantReplyPreview: 'Sure! Here is what I found.',
+      toolCallCount: 3,
+    })
+
+    const row = db
+      .prepare('SELECT * FROM turns WHERE turn_key = ?')
+      .get('chat1:_:1000') as Record<string, unknown>
+
+    expect(row['ended_via']).toBe('stop')
+    expect(row['ended_at']).toBeTypeOf('number')
+    expect((row['ended_at'] as number) > 0).toBe(true)
+    expect(row['user_prompt_preview']).toBe('Hello, can you help me?')
+    expect(row['assistant_reply_preview']).toBe('Sure! Here is what I found.')
+    expect(row['tool_call_count']).toBe(3)
+
+    db.close()
+  })
+
+  it('user_prompt_preview is stored at insert time, not overwritten by recordTurnEnd', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, {
+      turnKey: 'chat1:_:1001',
+      chatId: 'chat1',
+      userPromptPreview: 'first 200 chars of the user message',
+    })
+
+    recordTurnEnd(db, {
+      turnKey: 'chat1:_:1001',
+      endedVia: 'stop',
+      assistantReplyPreview: 'bot response',
+      toolCallCount: 0,
+    })
+
+    const row = db
+      .prepare('SELECT user_prompt_preview FROM turns WHERE turn_key = ?')
+      .get('chat1:_:1001') as Record<string, unknown>
+    expect(row['user_prompt_preview']).toBe('first 200 chars of the user message')
+
+    db.close()
+  })
+
+  it('null userPromptPreview and null assistantReplyPreview are stored correctly', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chat1:_:1002', chatId: 'chat1' })
+    recordTurnEnd(db, { turnKey: 'chat1:_:1002', endedVia: 'stop', toolCallCount: 0 })
+
+    const row = db
+      .prepare('SELECT user_prompt_preview, assistant_reply_preview FROM turns WHERE turn_key = ?')
+      .get('chat1:_:1002') as Record<string, unknown>
+    expect(row['user_prompt_preview']).toBeNull()
+    expect(row['assistant_reply_preview']).toBeNull()
+
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Mid-turn restart
+// ---------------------------------------------------------------------------
+
+describe('mid-turn restart (Phase 1 #332)', () => {
+  it('insert without finalize, then markOrphanedAsRestarted → ended_via=restart', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, {
+      turnKey: 'chat2:_:2000',
+      chatId: 'chat2',
+      userPromptPreview: 'this turn was interrupted',
+    })
+
+    // Simulate gateway boot reaper (same path as the real gateway boot).
+    const swept = markOrphanedAsRestarted(db)
+    expect(swept).toBe(1)
+
+    const row = db
+      .prepare('SELECT ended_via, ended_at FROM turns WHERE turn_key = ?')
+      .get('chat2:_:2000') as Record<string, unknown>
+
+    expect(row['ended_via']).toBe('restart')
+    expect(row['ended_at']).toBeTypeOf('number')
+    expect((row['ended_at'] as number) > 0).toBe(true)
+
+    db.close()
+  })
+
+  it('clean turns are not touched by the reaper', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chat2:_:2001', chatId: 'chat2' })
+    recordTurnEnd(db, { turnKey: 'chat2:_:2001', endedVia: 'stop' })
+    recordTurnStart(db, { turnKey: 'chat2:_:2002', chatId: 'chat2' })
+
+    markOrphanedAsRestarted(db)
+
+    const clean = db
+      .prepare('SELECT ended_via FROM turns WHERE turn_key = ?')
+      .get('chat2:_:2001') as Record<string, unknown>
+    const orphan = db
+      .prepare('SELECT ended_via FROM turns WHERE turn_key = ?')
+      .get('chat2:_:2002') as Record<string, unknown>
+
+    expect(clean['ended_via']).toBe('stop')
+    expect(orphan['ended_via']).toBe('restart')
+
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. Multiple concurrent turns same chat
+// ---------------------------------------------------------------------------
+
+describe('multiple concurrent turns same chat (Phase 1 #332)', () => {
+  it('each row has a unique turn_key, values do not bleed across rows', () => {
+    const db = openTurnsDbInMemory()
+
+    const turns = [
+      { key: 'chatA:_:3000', prompt: 'first message', reply: 'first reply', tools: 1 },
+      { key: 'chatA:_:3001', prompt: 'second message', reply: 'second reply', tools: 2 },
+      { key: 'chatA:_:3002', prompt: 'third message', reply: 'third reply', tools: 5 },
+    ]
+
+    for (const t of turns) {
+      recordTurnStart(db, {
+        turnKey: t.key,
+        chatId: 'chatA',
+        userPromptPreview: t.prompt,
+      })
+      recordTurnEnd(db, {
+        turnKey: t.key,
+        endedVia: 'stop',
+        assistantReplyPreview: t.reply,
+        toolCallCount: t.tools,
+      })
+    }
+
+    const rows = db
+      .prepare('SELECT * FROM turns WHERE chat_id = ? ORDER BY started_at ASC')
+      .all('chatA') as Record<string, unknown>[]
+
+    expect(rows).toHaveLength(3)
+
+    for (let i = 0; i < turns.length; i++) {
+      const t = turns[i]!
+      const row = rows[i]!
+      expect(row['turn_key']).toBe(t.key)
+      expect(row['user_prompt_preview']).toBe(t.prompt)
+      expect(row['assistant_reply_preview']).toBe(t.reply)
+      expect(row['tool_call_count']).toBe(t.tools)
+      expect(row['ended_via']).toBe('stop')
+    }
+
+    db.close()
+  })
+
+  it('turn_keys are unique even for the same chat_id', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chatB:_:4000', chatId: 'chatB', userPromptPreview: 'a' })
+    recordTurnStart(db, { turnKey: 'chatB:_:4001', chatId: 'chatB', userPromptPreview: 'b' })
+
+    const keys = (
+      db.prepare('SELECT turn_key FROM turns WHERE chat_id = ?').all('chatB') as Record<
+        string,
+        unknown
+      >[]
+    ).map((r) => r['turn_key'])
+
+    expect(new Set(keys).size).toBe(2)
+
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. tool_call_count accuracy
+// ---------------------------------------------------------------------------
+
+describe('tool_call_count (Phase 1 #332)', () => {
+  it('records 0 when no tools were called', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chat5:_:5000', chatId: 'chat5' })
+    recordTurnEnd(db, { turnKey: 'chat5:_:5000', endedVia: 'stop', toolCallCount: 0 })
+
+    const row = db
+      .prepare('SELECT tool_call_count FROM turns WHERE turn_key = ?')
+      .get('chat5:_:5000') as Record<string, unknown>
+    expect(row['tool_call_count']).toBe(0)
+
+    db.close()
+  })
+
+  it('records the exact number of tool_use events', () => {
+    const db = openTurnsDbInMemory()
+    const N = 7
+
+    recordTurnStart(db, { turnKey: 'chat5:_:5001', chatId: 'chat5' })
+    recordTurnEnd(db, {
+      turnKey: 'chat5:_:5001',
+      endedVia: 'stop',
+      toolCallCount: N,
+    })
+
+    const row = db
+      .prepare('SELECT tool_call_count FROM turns WHERE turn_key = ?')
+      .get('chat5:_:5001') as Record<string, unknown>
+    expect(row['tool_call_count']).toBe(N)
+
+    db.close()
+  })
+
+  it('null tool_call_count when not provided to recordTurnEnd', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chat5:_:5002', chatId: 'chat5' })
+    // toolCallCount omitted — simulates the kill/SIGTERM path where count
+    // may not be written (reaper path writes null).
+    recordTurnEnd(db, { turnKey: 'chat5:_:5002', endedVia: 'restart' })
+
+    const row = db
+      .prepare('SELECT tool_call_count FROM turns WHERE turn_key = ?')
+      .get('chat5:_:5002') as Record<string, unknown>
+    expect(row['tool_call_count']).toBeNull()
+
+    db.close()
+  })
+
+  it('tool_call_count increments are independent per turn', () => {
+    const db = openTurnsDbInMemory()
+
+    recordTurnStart(db, { turnKey: 'chat5:_:5010', chatId: 'chat5' })
+    recordTurnEnd(db, { turnKey: 'chat5:_:5010', endedVia: 'stop', toolCallCount: 3 })
+
+    recordTurnStart(db, { turnKey: 'chat5:_:5011', chatId: 'chat5' })
+    recordTurnEnd(db, { turnKey: 'chat5:_:5011', endedVia: 'stop', toolCallCount: 9 })
+
+    const r1 = db
+      .prepare('SELECT tool_call_count FROM turns WHERE turn_key = ?')
+      .get('chat5:_:5010') as Record<string, unknown>
+    const r2 = db
+      .prepare('SELECT tool_call_count FROM turns WHERE turn_key = ?')
+      .get('chat5:_:5011') as Record<string, unknown>
+
+    expect(r1['tool_call_count']).toBe(3)
+    expect(r2['tool_call_count']).toBe(9)
+
+    db.close()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Schema migration: existing DB without the Phase 1 columns
+// ---------------------------------------------------------------------------
+
+describe('schema migration (Phase 1 #332)', () => {
+  it('openTurnsDbInMemory adds Phase 1 columns to the turns table', () => {
+    const db = openTurnsDbInMemory()
+
+    // If columns are missing SQLite throws "no such column"; this shows they
+    // exist and accept null/integer values correctly.
+    expect(() =>
+      db
+        .prepare(
+          'SELECT user_prompt_preview, assistant_reply_preview, tool_call_count FROM turns',
+        )
+        .all(),
+    ).not.toThrow()
+
+    db.close()
+  })
+})

package/telegram-plugin/tests/two-zone-bg-carry-full-lifecycle.test.ts

@@ -0,0 +1,131 @@
+/**
+ * PR-C2 — full lifecycle of background sub-agent carry across two
+ * consecutive parent turns.
+ *
+ *   Turn A: enqueue → spawn bg sub-agent → parent reply + turn_end
+ *           (parent done, bg still running → phase=Background on A's card).
+ *   Turn B: enqueue (carries the still-running bg member into B's fleet).
+ *           B's phase starts as Working (parent active again).
+ *   Background sub-agent emits during B → still Working.
+ *   Background sub-agent reaches sub_agent_turn_end during B → fleet
+ *           now empty of running members; B's phase resolves cleanly.
+ *
+ * fails when: a refactor drops the originatingTurnKey routing of a bg
+ * sub-agent's events back to its origin chat, OR when the bg member
+ * isn't carried into turn B's fleet on enqueue.
+ */
+import { describe, it, expect } from 'vitest'
+import { phaseFor } from '../two-zone-card.js'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('PR-C2: two-zone bg-carry full lifecycle (turn A → turn B → bg done)', () => {
+  it('phase transitions A=Background, B=Working, B-after-bg-done=Done', () => {
+    const { driver, advance, getNow, completions } = makeHarness({
+      minIntervalMs: 500,
+      coalesceMs: 400,
+      promoteAfterMs: 999_999,
+    })
+    const CHAT = 'cA'
+
+    // ── Turn A: spawn bg sub-agent, parent replies, turn_end. ──────────
+    driver.ingest(enqueue(CHAT), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg work', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg work' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, CHAT)
+
+    // After parent turn_end, the originating chatState is held in
+    // pendingCompletion because saBG is still running.
+    const fleetAfterA = driver.peekFleet(CHAT)!
+    expect(fleetAfterA.has('saBG')).toBe(true)
+    expect(fleetAfterA.get('saBG')!.status).toBe('background')
+
+    // Phase resolution for A: parentDone=true + bg running → Background.
+    {
+      const all = (driver as unknown as {
+        peekAllFleets?: () => Array<{ turnKey: string; fleet: Map<string, unknown>; state?: unknown }>
+      }).peekAllFleets?.() ?? []
+      // Find turn A — it's the one whose fleet contains saBG and whose
+      // turnKey ends in :1.
+      const a = all.find((e) => e.turnKey.endsWith(':1'))
+      expect(a).toBeDefined()
+    }
+    // Capture A's turnKey for the deferred-completion assertion below.
+    const turnKeyA = (driver as unknown as {
+      peekAllFleets?: () => Array<{ turnKey: string; fleet: Map<string, unknown> }>
+    }).peekAllFleets!().find((e) => e.fleet.has('saBG'))!.turnKey
+
+    // ── Turn B: fresh enqueue. The bg member carries forward. ─────────
+    advance(50)
+    driver.ingest(enqueue(CHAT), null)
+    const fleetB = driver.peekFleet(CHAT)!
+    // Carry: saBG should still be reachable somewhere in the driver's
+    // fleets (either on B's fresh state or A's still-pending one).
+    const allFleets = (driver as unknown as {
+      peekAllFleets?: () => Array<{ turnKey: string; fleet: Map<string, { status: string }> }>
+    }).peekAllFleets?.() ?? []
+    const sawBG = allFleets.some((f) => f.fleet.has('saBG'))
+    expect(sawBG).toBe(true)
+
+    // B parent is in flight — phaseFor should resolve to Working… because
+    // parentDone=false for B regardless of bg state.
+    const phaseB = phaseFor(
+      {
+        turnStartedAt: getNow(),
+        items: [],
+        narratives: [],
+        stage: 'run',
+        thinking: false,
+        subAgents: new Map(),
+        pendingAgentSpawns: new Map(),
+        tasks: [],
+      },
+      fleetB,
+      getNow(),
+      {},
+    )
+    expect(phaseB.label).toBe('Working…')
+
+    // ── BG sub-agent emits during B (proves routing still works). ────
+    advance(20)
+    driver.ingest(
+      {
+        kind: 'sub_agent_tool_use',
+        agentId: 'saBG',
+        toolUseId: 'bgt1',
+        toolName: 'Read',
+        input: { file_path: '/tmp/x.txt' },
+      },
+      CHAT,
+    )
+
+    // ── BG sub-agent finishes during B. ──────────────────────────────
+    advance(20)
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, CHAT)
+
+    // Turn A's pendingCompletion should now resolve (saBG no longer
+    // running). Turn B's fleet should drop its bg copy too.
+    const allAfter = (driver as unknown as {
+      peekAllFleets?: () => Array<{ turnKey: string; fleet: Map<string, { status: string }> }>
+    }).peekAllFleets?.() ?? []
+    for (const entry of allAfter) {
+      const m = entry.fleet.get('saBG')
+      if (m == null) continue
+      // Whichever turn still holds saBG, it must be terminal (done/failed/killed)
+      expect(['done', 'failed', 'killed']).toContain(m.status)
+    }
+    // Critical: A's deferred completion MUST have fired now that saBG
+    // reached sub_agent_turn_end. Without this assertion the loop above
+    // trivially passes when allAfter is empty.
+    expect(completions).toContain(turnKeyA)
+  })
+})

package/telegram-plugin/tests/two-zone-bg-detection.test.ts

@@ -0,0 +1,120 @@
+/**
+ * P2 of #662 — runInBackground detection.
+ *
+ * When the parent dispatches an Agent/Task tool with
+ * `input.run_in_background: true`, the resulting fleet member must be
+ * marked with `status: 'background'` instead of `running`. Foreground
+ * dispatches (no flag, or false) stay `running`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import type { SessionEvent } from '../session-tail.js'
+
+function harness() {
+  let now = 1000
+  const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+  let nextRef = 0
+  const driver = createProgressDriver({
+    emit: () => {},
+    minIntervalMs: 500,
+    coalesceMs: 400,
+    initialDelayMs: 0,
+    promoteAfterMs: 999_999,
+    now: () => now,
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref })
+      return { ref }
+    },
+    clearTimeout: (h) => {
+      const ref = (h as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+      return { ref }
+    },
+    clearInterval: (h) => {
+      const ref = (h as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+  })
+  return { driver, advance: (ms: number) => { now += ms } }
+}
+
+const enqueue = (chatId: string): SessionEvent => ({
+  kind: 'enqueue',
+  chatId,
+  messageId: '1',
+  threadId: null,
+  rawContent: `<channel chat_id="${chatId}">go</channel>`,
+})
+
+describe('P2: runInBackground detection', () => {
+  it('marks fleet member status=background when Agent dispatched with run_in_background:true', () => {
+    const { driver } = harness()
+    driver.ingest(enqueue('c1'), null)
+    // Parent fires Agent tool_use with run_in_background=true.
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'do bg work', description: 'bg-job', run_in_background: true },
+      },
+      'c1',
+    )
+    // sub_agent_started arrives with matching prompt.
+    driver.ingest(
+      { kind: 'sub_agent_started', agentId: 'sa1', firstPromptText: 'do bg work', subagentType: 'worker' },
+      'c1',
+    )
+
+    const m = driver.peekFleet('c1')!.get('sa1')!
+    expect(m.status).toBe('background')
+  })
+
+  it('keeps status=running when Agent dispatched without run_in_background', () => {
+    const { driver } = harness()
+    driver.ingest(enqueue('c2'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu2',
+        input: { prompt: 'do fg work', description: 'fg-job' },
+      },
+      'c2',
+    )
+    driver.ingest(
+      { kind: 'sub_agent_started', agentId: 'sa2', firstPromptText: 'do fg work' },
+      'c2',
+    )
+    const m = driver.peekFleet('c2')!.get('sa2')!
+    expect(m.status).toBe('running')
+  })
+
+  it('keeps status=running when run_in_background is explicitly false', () => {
+    const { driver } = harness()
+    driver.ingest(enqueue('c3'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu3',
+        input: { prompt: 'p', run_in_background: false },
+      },
+      'c3',
+    )
+    driver.ingest(
+      { kind: 'sub_agent_started', agentId: 'sa3', firstPromptText: 'p' },
+      'c3',
+    )
+    const m = driver.peekFleet('c3')!.get('sa3')!
+    expect(m.status).toBe('running')
+  })
+})