switchroom 0.5.0

package/telegram-plugin/tests/two-zone-bg-done-when-all-terminal.test.ts

@@ -0,0 +1,114 @@
+/**
+ * P2 of #662 — completion gate: a turn with both foreground (done) and
+ * background (still running) sub-agents must NOT fire onTurnComplete
+ * until the background member also reaches a terminal state. This is
+ * the "✅ Done only when everything is actually done" invariant; the
+ * v2 renderer uses the same predicate to choose between the
+ * ⏸ Background and ✅ Done header phases.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import { hasLiveBackground } from '../fleet-state.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 completions: string[] = []
+  const driver = createProgressDriver({
+    emit: () => {},
+    minIntervalMs: 500,
+    coalesceMs: 400,
+    initialDelayMs: 0,
+    promoteAfterMs: 999_999,
+    onTurnComplete: (s) => completions.push(s.turnKey),
+    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, completions, 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: completion gates on background fleet members', () => {
+  it('hasLiveBackground reflects fleet status correctly', () => {
+    const fleet = new Map([
+      ['a', { agentId: 'a', status: 'background' as const, terminalAt: null } as never],
+      ['b', { agentId: 'b', status: 'done' as const, terminalAt: 2000 } as never],
+    ])
+    expect(hasLiveBackground(fleet as never)).toBe(true)
+    fleet.set('a', { agentId: 'a', status: 'done' as const, terminalAt: 3000 } as never)
+    expect(hasLiveBackground(fleet as never)).toBe(false)
+  })
+
+  it('foreground sub completes + background still running → no turn completion', () => {
+    const { driver, completions } = harness()
+    const CHAT = 'c1'
+    driver.ingest(enqueue(CHAT), null)
+    // Foreground Agent dispatch.
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tuFg',
+        input: { prompt: 'fg', description: 'fg-job' },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saFG', firstPromptText: 'fg' }, CHAT)
+    // Background Agent dispatch.
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tuBg',
+        input: { prompt: 'bg', description: 'bg-job', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    // Foreground completes.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saFG' }, CHAT)
+    // Parent ends.
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, CHAT)
+
+    // Background still running → no completion fired.
+    expect(completions.length).toBe(0)
+    const fleet = driver.peekFleet(CHAT)!
+    expect(fleet.get('saFG')!.status).toBe('done')
+    expect(fleet.get('saBG')!.status).toBe('background')
+
+    // Background completes → completion fires.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, CHAT)
+    expect(completions.length).toBe(1)
+  })
+})

package/telegram-plugin/tests/two-zone-bg-early-turn-end.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Regression: parent turn_end fires before bg sub-agent emits any
+ * state.subAgents entries (i.e. sub_agent_started hasn't arrived yet).
+ *
+ * Before the fix, hasAnyRunningSubAgent returned false at turn_end time
+ * (subAgents was empty) so the card was closed immediately. The fleet
+ * shadow's hasLiveBackground gate is the fix — the fleet member is
+ * created at sub_agent_started time and tagged status:'background',
+ * which keeps pendingCompletion=true even when subAgents is empty.
+ *
+ * Scenario:
+ *   1. Parent emits Agent tool_use with run_in_background:true.
+ *   2. Parent emits turn_end immediately — sub_agent_started has NOT
+ *      arrived yet, so state.subAgents is empty.
+ *   3. Card must remain alive (NOT in completions).
+ *   4. sub_agent_started arrives → fleet records the member.
+ *   5. sub_agent_turn_end arrives → deferred completion must fire.
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('two-zone-bg: parent turn_end before sub_agent_started → card survives → bg done cleans up', () => {
+  it('does not close the card prematurely; fires completion on bg sub-agent terminal', () => {
+    const { driver, completions, advance } = makeHarness({
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      promoteAfterMs: 999_999,
+    })
+    const CHAT = 'cBG_early'
+
+    // Step 1: enqueue a new parent turn.
+    driver.ingest(enqueue(CHAT), null)
+
+    // Step 2: parent emits Agent tool_use with run_in_background:true.
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu-bg-1',
+        input: { prompt: 'do bg work', run_in_background: true },
+      },
+      CHAT,
+    )
+
+    // Step 3: sub_agent_started — fleet member created as background.
+    driver.ingest(
+      {
+        kind: 'sub_agent_started',
+        agentId: 'sa-early',
+        firstPromptText: 'do bg work',
+      },
+      CHAT,
+    )
+
+    // Step 4: parent turn_end fires — sub-agent has no subAgents reducer
+    // entry yet (the sub_agent_started above only added to fleet, the
+    // reducer may not have a running entry depending on event ordering).
+    // Regardless, fleet has a live background member → card must defer.
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, CHAT)
+
+    // Card must NOT be complete yet.
+    expect(completions).toHaveLength(0)
+
+    // Step 5: bg sub-agent does some work.
+    advance(10)
+    driver.ingest(
+      {
+        kind: 'sub_agent_tool_use',
+        agentId: 'sa-early',
+        toolUseId: 'bgt-1',
+        toolName: 'Bash',
+        input: { command: 'echo hi' },
+      },
+      CHAT,
+    )
+
+    // Still not done.
+    expect(completions).toHaveLength(0)
+
+    // Step 6: bg sub-agent terminates → deferred completion must fire.
+    advance(10)
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'sa-early' }, CHAT)
+
+    // Completion must have fired exactly once.
+    expect(completions).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/two-zone-bg-survives-next-turn.test.ts

@@ -0,0 +1,211 @@
+/**
+ * P2 of #662 / fixes #64 — background sub-agent persistence across
+ * subsequent parent turns.
+ *
+ * Lifecycle under test:
+ *   - Turn A enqueue → parent dispatches Agent({run_in_background:true})
+ *     → sub_agent_started → parent reply → turn_end (would normally
+ *     finalize and dispose).
+ *   - Turn B enqueues. The original PerChatState for turn A must
+ *     survive because its fleet still has a 'background' member.
+ *   - Background sub-agent emits sub_agent_tool_use. Routing must land
+ *     the event on turn A's state (originatingTurnKey), NOT turn B's
+ *     fresh state.
+ *   - When the background sub-agent finally fires sub_agent_turn_end,
+ *     turn A's PerChatState completes and is disposed.
+ */
+
+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 completions: string[] = []
+  const driver = createProgressDriver({
+    emit: () => {},
+    minIntervalMs: 500,
+    coalesceMs: 400,
+    initialDelayMs: 0,
+    promoteAfterMs: 999_999,
+    onTurnComplete: (s) => completions.push(s.turnKey),
+    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, completions, advance: (ms: number) => { now += ms } }
+}
+
+const enqueue = (chatId: string, msgId: string): SessionEvent => ({
+  kind: 'enqueue',
+  chatId,
+  messageId: msgId,
+  threadId: null,
+  rawContent: `<channel chat_id="${chatId}">go</channel>`,
+})
+
+describe('P2 / #64: background sub-agent persists across parent turn boundaries', () => {
+  it('PerChatState for turn A survives parent turn_end while background fleet member runs', () => {
+    const { driver, completions } = harness()
+    const CHAT = 'c1'
+
+    // Turn A
+    driver.ingest(enqueue(CHAT, '1'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg work', description: 'long-bg', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest(
+      { kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg work' },
+      CHAT,
+    )
+    // Parent reply fires + delivery so turn_end takes the ✅ Done path.
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, CHAT)
+
+    // Background sub-agent is still running → onTurnComplete must NOT
+    // have fired for turn A yet. Fleet is still inspectable.
+    expect(completions.length).toBe(0)
+    const fleetA = driver.peekFleet(CHAT)!
+    expect(fleetA.has('saBG')).toBe(true)
+    expect(fleetA.get('saBG')!.status).toBe('background')
+  })
+
+  it('background sub-agent tool_use after a NEW turn arrives still updates the originating turn fleet', () => {
+    const { driver, completions, advance } = harness()
+    const CHAT = 'c1'
+
+    // Turn A spawns bg sub-agent
+    driver.ingest(enqueue(CHAT, '1'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg work', description: 'long-bg', 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)
+
+    const fleetBeforeTurnB = driver.peekFleet(CHAT)!
+    const turnAStartedAt = fleetBeforeTurnB.get('saBG')!.startedAt
+
+    // Advance the clock so the bg sub-agent's later tool_use gets a
+    // distinguishable lastActivityAt (proves routing actually mutated
+    // the originating member rather than no-oping).
+    advance(50)
+
+    // Turn B starts (and ends quickly, no sub-agents).
+    driver.ingest(enqueue(CHAT, '2'), null)
+    advance(10)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 200 }, CHAT)
+
+    // Background sub-agent emits a tool_use after parent moved on.
+    driver.ingest(
+      {
+        kind: 'sub_agent_tool_use',
+        agentId: 'saBG',
+        toolUseId: 'bgt1',
+        toolName: 'Read',
+        input: { file_path: '/tmp/x.txt' },
+      },
+      CHAT,
+    )
+
+    // The bg fleet member's lastActivityAt advanced — proving routing
+    // landed on the originating PerChatState rather than dropping the
+    // event as a "late event for ended turn".
+    // Iterate all fleets — the originating one survives even if peekFleet
+    // returns turn B's state.
+    // We discover it via a known-stable agentId.
+    // Use the test-only carry: peekFleet returns whichever chat:thread
+    // matches; but turn B may shadow it. So use the fleet from turn A
+    // by looking it up via the driver's introspection — we just call
+    // peekFleet(CHAT) and accept that it returns a fleet where saBG
+    // either lives (if A is still bound) or doesn't (if B took over).
+    // Either way the saBG entry exists somewhere; check it via the
+    // dedicated test hook.
+    const allLiveBg = driver.peekFleet(CHAT)
+    // saBG might live on turn A's fleet which is no longer the
+    // currentTurnKey; but the routing must have updated it. We rely on
+    // a debug hook to find it across all chats.
+    expect(allLiveBg).toBeDefined()
+    // Strict: we expect SOMEWHERE in the driver, saBG's lastActivityAt
+    // is now newer than turnAStartedAt.
+    // Pull via the driver's test hook (added in P2): peekAllFleets.
+    const all = (driver as unknown as { peekAllFleets?: () => Array<{ turnKey: string; fleet: Map<string, { agentId: string; lastActivityAt: number; toolCount: number }> }> })
+      .peekAllFleets?.() ?? []
+    let found: { lastActivityAt: number; toolCount: number } | undefined
+    for (const entry of all) {
+      const m = entry.fleet.get('saBG')
+      if (m != null) found = m
+    }
+    expect(found).toBeDefined()
+    expect(found!.toolCount).toBe(1)
+    expect(found!.lastActivityAt).toBeGreaterThan(turnAStartedAt)
+    // Turn B should have completed normally (no bg on it).
+    expect(completions.some((k) => k.endsWith(':2'))).toBe(true)
+    // Turn A should NOT have completed yet (bg still running).
+    expect(completions.some((k) => k.endsWith(':1'))).toBe(false)
+  })
+
+  it('completes the originating turn when the last background sub-agent reaches turn_end', () => {
+    const { driver, completions } = harness()
+    const CHAT = 'c1'
+    driver.ingest(enqueue(CHAT, '1'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, CHAT)
+    expect(completions.length).toBe(0)
+
+    // BG sub-agent eventually finishes.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, CHAT)
+    expect(completions.length).toBe(1)
+    expect(completions[0]).toMatch(/:1$/)
+  })
+})

package/telegram-plugin/tests/two-zone-card-cap.test.ts

@@ -0,0 +1,62 @@
+/**
+ * P1 of #662 — fleet zone caps at 5 visible rows; surplus collapses
+ * to "+ N more" footer. Order is most-recent-activity first.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { renderFleetZone } from '../two-zone-card.js'
+import type { FleetMember } from '../fleet-state.js'
+
+function fm(id: string, lastActivityAt: number): FleetMember {
+  return {
+    agentId: id,
+    role: 'role-' + id,
+    startedAt: 0,
+    toolCount: 1,
+    lastActivityAt,
+    lastTool: { name: 'Read', sanitisedArg: 'x.ts' },
+    status: 'running',
+    terminalAt: null,
+    errorSeen: false,
+    originatingTurnKey: 'k',
+  }
+}
+
+describe('renderFleetZone cap', () => {
+  it('returns empty string for empty fleet', () => {
+    expect(renderFleetZone(new Map(), 0)).toBe('')
+  })
+
+  it('renders all rows for fleet ≤ 5', () => {
+    const fleet = new Map([
+      ['a', fm('aaaaaa', 100)],
+      ['b', fm('bbbbbb', 200)],
+      ['c', fm('cccccc', 300)],
+    ])
+    const out = renderFleetZone(fleet, 1000)
+    expect(out).toContain('FLEET (3)')
+    expect(out).toContain('aaaaaa')
+    expect(out).toContain('bbbbbb')
+    expect(out).toContain('cccccc')
+    expect(out).not.toContain('more')
+  })
+
+  it('caps at 5 with "+ N more" footer for fleet > 5, ordered most-recent-first', () => {
+    const fleet = new Map<string, FleetMember>()
+    for (let i = 0; i < 7; i++) {
+      const id = `agent${i}xx`
+      fleet.set(id, fm(id, 100 + i))
+    }
+    const out = renderFleetZone(fleet, 1000)
+    expect(out).toContain('FLEET (7)')
+    expect(out).toContain('+ 2 more')
+    // Most-recent activity (i=6, ts=106) must appear; oldest two (i=0, i=1) must not
+    expect(out).toContain('agent6')
+    expect(out).toContain('agent2')
+    expect(out).not.toContain('agent0')
+    expect(out).not.toContain('agent1')
+    // Count visible rows by counting status glyphs at row starts
+    const rowLines = out.split('\n').filter((l) => l.startsWith('↻'))
+    expect(rowLines.length).toBe(5)
+  })
+})

package/telegram-plugin/tests/two-zone-card-fleet-row.test.ts

@@ -0,0 +1,101 @@
+/**
+ * P1 of #662 — fleet row formatting: id6 truncation, role fallback,
+ * terminal status suffix, glyph mapping.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  renderFleetRow,
+  glyphForFleetStatus,
+  formatRelativeTime,
+} from '../two-zone-card.js'
+import type { FleetMember } from '../fleet-state.js'
+
+function fm(over: Partial<FleetMember>): FleetMember {
+  return {
+    agentId: 'abcdef0123456789',
+    role: 'agent',
+    startedAt: 0,
+    toolCount: 0,
+    lastActivityAt: 1000,
+    lastTool: null,
+    status: 'running',
+    terminalAt: null,
+    errorSeen: false,
+    originatingTurnKey: 'k',
+    ...over,
+  }
+}
+
+describe('glyphForFleetStatus', () => {
+  it('maps every status to a glyph', () => {
+    expect(glyphForFleetStatus('running')).toBe('↻')
+    expect(glyphForFleetStatus('background')).toBe('⏸')
+    expect(glyphForFleetStatus('done')).toBe('✓')
+    expect(glyphForFleetStatus('failed')).toBe('✗')
+    expect(glyphForFleetStatus('stuck')).toBe('⚠')
+    expect(glyphForFleetStatus('killed')).toBe('✗')
+  })
+})
+
+describe('formatRelativeTime', () => {
+  it('seconds under 60', () => {
+    expect(formatRelativeTime(3000)).toBe('3s ago')
+  })
+  it('minutes + seconds', () => {
+    expect(formatRelativeTime(72_000)).toBe('1m12s ago')
+  })
+  it('zero', () => {
+    expect(formatRelativeTime(0)).toBe('0s ago')
+  })
+})
+
+describe('renderFleetRow', () => {
+  const NOW = 10_000
+
+  it('uses 6-char id slice', () => {
+    const out = renderFleetRow(fm({ agentId: 'abcdef0123456789' }), NOW)
+    expect(out).toContain('abcdef')
+    expect(out).not.toContain('abcdef0')
+  })
+
+  it('renders running with last tool + age', () => {
+    const out = renderFleetRow(fm({
+      lastActivityAt: NOW - 5000,
+      lastTool: { name: 'Read', sanitisedArg: 'file.ts' },
+      toolCount: 3,
+    }), NOW)
+    expect(out).toContain('Read')
+    expect(out).toContain('file.ts')
+    expect(out).toContain('5s ago')
+    expect(out).toContain('3t')
+    expect(out.startsWith('↻')).toBe(true)
+  })
+
+  it('renders terminal done with relative time', () => {
+    const out = renderFleetRow(fm({
+      status: 'done',
+      terminalAt: NOW - 12_000,
+      lastActivityAt: NOW - 12_000,
+    }), NOW)
+    expect(out).toContain('done 12s ago')
+    expect(out.startsWith('✓')).toBe(true)
+  })
+
+  it('renders failed terminal with status suffix', () => {
+    const out = renderFleetRow(fm({
+      status: 'failed',
+      terminalAt: NOW - 3000,
+      lastActivityAt: NOW - 3000,
+      errorSeen: true,
+    }), NOW)
+    expect(out).toContain('failed 3s ago')
+    expect(out.startsWith('✗')).toBe(true)
+  })
+
+  it('falls back when no lastTool yet', () => {
+    const out = renderFleetRow(fm({ lastActivityAt: NOW }), NOW)
+    expect(out).toContain('↻')
+    expect(out).toContain('agent')
+  })
+})

package/telegram-plugin/tests/two-zone-card-header-phases.test.ts

@@ -0,0 +1,68 @@
+/**
+ * P1 of #662 — phaseFor truth table.
+ *
+ * Drives the `phaseFor(state, fleet)` resolver across the 6-row spec
+ * table from `reference/status-card-design.md` plus edge cases that
+ * have historically been mis-classified (parent-stalled-fleet-active,
+ * parent-done-fg-failed-bg-running, reply-and-fleet, sub-text-only).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { phaseFor } from '../two-zone-card.js'
+import type { FleetMember } from '../fleet-state.js'
+import type { ProgressCardState } from '../progress-card.js'
+
+function fm(id: string, status: FleetMember['status'], lastActivityAt: number = 1000): FleetMember {
+  return {
+    agentId: id,
+    role: 'agent',
+    startedAt: 0,
+    toolCount: 0,
+    lastActivityAt,
+    lastTool: null,
+    status,
+    terminalAt: status === 'done' || status === 'failed' || status === 'killed' ? lastActivityAt : null,
+    errorSeen: status === 'failed',
+    originatingTurnKey: 'k',
+  }
+}
+
+function st(opts: Partial<ProgressCardState> & { stage: ProgressCardState['stage'] }): ProgressCardState {
+  return {
+    turnStartedAt: 1,
+    items: [],
+    narratives: [],
+    stage: opts.stage,
+    thinking: false,
+    subAgents: new Map(),
+    pendingAgentSpawns: new Map(),
+    tasks: [],
+    ...opts,
+  }
+}
+
+const fleetOf = (...members: FleetMember[]) => new Map(members.map((m) => [m.agentId, m]))
+
+const NOW = 100_000
+
+describe('phaseFor truth table', () => {
+  it.each([
+    // [name, state, fleet, opts, expectedLabel]
+    ['working: parent in flight, no fleet', st({ stage: 'run' }), new Map(), {}, 'Working…'],
+    ['working: parent in flight + fleet running', st({ stage: 'run' }), fleetOf(fm('a', 'running', NOW)), {}, 'Working…'],
+    ['background: parent done, bg running', st({ stage: 'done' }), fleetOf(fm('a', 'running', NOW)), { parentDone: true }, 'Background'],
+    ['background: parentDone flag + fg running', st({ stage: 'run' }), fleetOf(fm('a', 'running', NOW)), { parentDone: true }, 'Background'],
+    ['stalled: parent idle + all fleet stuck', st({ stage: 'run' }), fleetOf(fm('a', 'stuck', 0), fm('b', 'stuck', 0)), {}, 'Stalled'],
+    ['done: parent done + all fleet terminal', st({ stage: 'done' }), fleetOf(fm('a', 'done'), fm('b', 'failed')), {}, 'Done'],
+    ['done: parent done, no fleet', st({ stage: 'done' }), new Map(), {}, 'Done'],
+    ['silent: parent terminal + no reply', st({ stage: 'done' }), new Map(), { silentEnd: true }, 'Ended without reply'],
+    ['forced close: stalledClose flag wins', st({ stage: 'done' }), fleetOf(fm('a', 'done')), { stalledClose: true }, 'Forced close'],
+    // Edge cases
+    ['parent-done + fg-failed + bg-running → Background, not Done', st({ stage: 'done' }), fleetOf(fm('a', 'failed'), fm('b', 'running', NOW)), { parentDone: true }, 'Background'],
+    ['mixed terminal+stuck → not Done', st({ stage: 'run' }), fleetOf(fm('a', 'done'), fm('b', 'stuck', 0)), {}, 'Stalled'],
+    ['reply tool fired AND fleet running → Background (parentDone)', st({ stage: 'done' }), fleetOf(fm('a', 'running', NOW)), { parentDone: true }, 'Background'],
+  ])('%s', (_name, state, fleet, opts, expectedLabel) => {
+    const phase = phaseFor(state, fleet, NOW, opts as Record<string, unknown>)
+    expect(phase.label).toBe(expectedLabel)
+  })
+})