switchroom 0.5.0 → 0.7.8

package/telegram-plugin/tests/subagent-watcher-stall-notification.test.ts

@@ -28,16 +28,19 @@ function subAgentUserMsg(promptText: string) {
 interface StallHarness {
   notifications: string[]
   stallCalls: Array<{ agentId: string; idleMs: number; description: string }>
+  unstallCalls: Array<{ agentId: string; description: string }>
   logs: string[]
   advance: (ms: number) => void
   watcher: ReturnType<typeof startSubagentWatcher>
   now: () => number
   fileContents: Map<string, Buffer>
+  jsonlPath: string
 }
 
 function makeStallHarness(opts: {
   agentDir?: string
   stallThresholdMs?: number
+  silentSynthesisStallThresholdMs?: number
   rescanMs?: number
   initialContent?: string
   agentId?: string
@@ -45,6 +48,7 @@ function makeStallHarness(opts: {
   const {
     agentDir = '/home/user/.switchroom/agents/myagent',
     stallThresholdMs = 60_000,
+    silentSynthesisStallThresholdMs,
     rescanMs = 500,
     agentId = 'test-stall-agent-01',
     initialContent,
@@ -53,6 +57,7 @@ function makeStallHarness(opts: {
   let currentTime = 1000
   const notifications: string[] = []
   const stallCalls: Array<{ agentId: string; idleMs: number; description: string }> = []
+  const unstallCalls: Array<{ agentId: string; description: string }> = []
   const logs: string[] = []
 
   // Build realistic path: <agentDir>/.claude/projects/<sanitized-cwd>/<sessionId>/subagents/
@@ -127,9 +132,16 @@ function makeStallHarness(opts: {
   const watcher = startSubagentWatcher({
     agentDir,
     stallThresholdMs,
+    // When the test doesn't explicitly distinguish the two thresholds,
+    // mirror them so existing fixtures (which have toolCount=0 and a
+    // simple "advance past 60s" model) keep working under the new
+    // adaptive logic. New tests pass an explicit value to exercise the
+    // silent-synthesis vs active-loop split.
+    silentSynthesisStallThresholdMs: silentSynthesisStallThresholdMs ?? stallThresholdMs,
     rescanMs,
     sendNotification: (text) => notifications.push(text),
     onStall: (id, idle, desc) => stallCalls.push({ agentId: id, idleMs: idle, description: desc }),
+    onUnstall: (id, desc) => unstallCalls.push({ agentId: id, description: desc }),
     now: () => currentTime,
     setInterval: (fn, ms) => {
       const ref = nextRef++
@@ -156,7 +168,7 @@ function makeStallHarness(opts: {
     }
   }
 
-  return { notifications, stallCalls, logs, advance, watcher, now: () => currentTime, fileContents }
+  return { notifications, stallCalls, unstallCalls, logs, advance, watcher, now: () => currentTime, fileContents, jsonlPath }
 }
 
 // ─── Tests ────────────────────────────────────────────────────────────────────
@@ -211,6 +223,97 @@ describe('subagent-watcher onStall callback (Option C, issue #393)', () => {
     expect(stallCalls.length).toBe(countAfterFirstStall) // still exactly 1
   })
 
+  // Test 11 (silent-synthesis): a sub-agent that hasn't fired any tools
+  // yet should NOT trip the stall detector at the active-loop threshold
+  // (60s) — it's almost certainly in long-form synthesis mode where the
+  // model is still composing its first emit. The silent-synthesis
+  // threshold (5min by default) is what gates that case. Pre-fix the
+  // single 60s threshold tripped on plan/research sub-agents that ran
+  // 2-3min legitimately, freezing the card at ⚠ until completion.
+  it('does NOT trip stall at 60s when toolCount=0 (silent synthesis adaptive threshold)', () => {
+    const agentId = 'stall-test-11'
+    const { stallCalls, advance, watcher } = makeStallHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentSynthesisStallThresholdMs: 300_000, // 5min
+      rescanMs: 500,
+    })
+    advance(500) // register
+    const entry = watcher.getRegistry().get(agentId)
+    if (entry) entry.historical = false
+    advance(120_000) // 2min idle, far past 60s but well under 5min
+    expect(stallCalls).toHaveLength(0)
+    advance(200_000) // total ~5min 20s — past silent-synthesis threshold
+    expect(stallCalls).toHaveLength(1)
+    expect(stallCalls[0].agentId).toBe(agentId)
+  })
+
+  // Test 12 (un-stall transition): once JSONL activity returns after a
+  // stall, the watcher must reset stallNotified, fire onUnstall, and
+  // re-arm so a subsequent stall detects again. Pre-fix none of those
+  // happened — the card stuck at ⚠ even when the sub-agent was clearly
+  // alive again.
+  it('fires onUnstall when activity returns after a stall and re-arms detection', () => {
+    const agentId = 'stall-test-12'
+    const { stallCalls, unstallCalls, advance, watcher, fileContents, jsonlPath } = makeStallHarness({
+      agentId,
+      // Force the active-loop threshold by giving the entry a tool right
+      // away (avoids the silent-synthesis adaptive path). We append a
+      // sub_agent_tool_use line in the initial content so toolCount > 0
+      // by the first activity bump.
+      stallThresholdMs: 60_000,
+      silentSynthesisStallThresholdMs: 60_000, // keep flat for this test
+      rescanMs: 500,
+      initialContent: buildJSONL(
+        subAgentUserMsg('background task'),
+        { type: 'assistant', message: { content: [{ type: 'tool_use', id: 'tool-A', name: 'Read', input: { path: '/x' } }] } },
+      ),
+    })
+    advance(500) // register + initial tail read (toolCount becomes 1)
+    const entry = watcher.getRegistry().get(agentId)
+    if (entry) entry.historical = false
+    advance(65_000) // cross 60s — stall fires
+    expect(stallCalls).toHaveLength(1)
+    expect(unstallCalls).toHaveLength(0)
+
+    // Append a fresh JSONL line — the sub-agent emits text, proving it's
+    // alive. The watcher should reset stallNotified, fire onUnstall, and
+    // re-arm so a *future* idle period can stall it again.
+    const existing = fileContents.get(jsonlPath) ?? Buffer.from('')
+    const resumeLine = JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'still alive' }] } }) + '\n'
+    fileContents.set(jsonlPath, Buffer.concat([existing, Buffer.from(resumeLine, 'utf-8')]))
+    advance(500) // poll picks up the new line
+
+    expect(unstallCalls).toHaveLength(1)
+    expect(unstallCalls[0].agentId).toBe(agentId)
+    // stallNotified must be re-armed: another idle window crosses
+    // threshold again and onStall fires a SECOND time.
+    advance(65_000)
+    expect(stallCalls).toHaveLength(2)
+  })
+
+  // Test 13 (un-stall + tool-loop adaptive): once tools have been used,
+  // a 60s gap correctly re-trips the stall detector. Sanity check that
+  // toolCount > 0 selects the active-loop threshold, not silent-synthesis.
+  it('uses 60s threshold once toolCount>0 (active-loop adaptive)', () => {
+    const agentId = 'stall-test-13'
+    const { stallCalls, advance, watcher } = makeStallHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentSynthesisStallThresholdMs: 600_000, // way out — 10min
+      rescanMs: 500,
+      initialContent: buildJSONL(
+        subAgentUserMsg('worker'),
+        { type: 'assistant', message: { content: [{ type: 'tool_use', id: 'tool-A', name: 'Read', input: {} }] } },
+      ),
+    })
+    advance(500) // register + tail (toolCount=1)
+    const entry = watcher.getRegistry().get(agentId)
+    if (entry) entry.historical = false
+    advance(65_000) // 65s of silence with tools active → stall
+    expect(stallCalls).toHaveLength(1)
+  })
+
   // Test 10: onStall is NOT called for sub-agents already done/failed
   it('does not call onStall for sub-agents in done/failed state', () => {
     const agentId = 'stall-test-10-done'

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -200,6 +200,11 @@ function makeHarness(opts: {
     agentDir,
     sendNotification: (text) => notifications.push(text),
     stallThresholdMs,
+    // Mirror the active-loop threshold so existing fixtures (which have
+    // toolCount=0 and use the simple "advance past N" model) keep
+    // working under the adaptive split. Tests that need the silent-
+    // synthesis vs active-loop distinction set both explicitly.
+    silentSynthesisStallThresholdMs: stallThresholdMs,
     rescanMs,
     now: () => currentTime,
     setInterval: (fn, ms) => {

package/telegram-plugin/tests/tool-label-sidecar.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, appendFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createToolLabelSidecar } from '../tool-label-sidecar.js'
+
+/**
+ * Unit tests for tool-label-sidecar.ts (#783).
+ *
+ * Uses an injected scheduler so we drive polls deterministically — no
+ * setTimeout, no flake.
+ */
+
+function makeManualScheduler() {
+  let tickFn: (() => void) | null = null
+  return {
+    setInterval: (cb: () => void, _ms: number) => {
+      tickFn = cb
+      return Symbol('handle')
+    },
+    clearInterval: (_h: unknown) => {
+      tickFn = null
+    },
+    tick: () => { if (tickFn) tickFn() },
+  }
+}
+
+describe('tool-label-sidecar', () => {
+  let stateDir: string
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'tool-label-sidecar-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+  })
+
+  it('returns undefined when sidecar file is missing', () => {
+    const sched = makeManualScheduler()
+    const s = createToolLabelSidecar({ stateDir, sessionId: 'no-such', scheduler: sched })
+    expect(s.getLabel('whatever')).toBeUndefined()
+    s.stop()
+  })
+
+  it('reads existing sidecar lines on construction', () => {
+    const sessionId = 'sess1'
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    writeFileSync(f, JSON.stringify({ ts: 1, tool_use_id: 'A', agent_id: 'g', label: 'Reading foo.ts', tool_name: 'Read' }) + '\n')
+    const sched = makeManualScheduler()
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+    expect(s.getLabel('A')).toBe('Reading foo.ts')
+    expect(s.getLabel('B')).toBeUndefined()
+    s.stop()
+  })
+
+  it('picks up appended lines on poll() (renderer reads, hook then writes)', () => {
+    const sessionId = 'sess2'
+    const sched = makeManualScheduler()
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+    expect(s.getLabel('A')).toBeUndefined()
+
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    appendFileSync(f, JSON.stringify({ ts: 1, tool_use_id: 'A', agent_id: null, label: 'Replying', tool_name: 'mcp__switchroom-telegram__reply' }) + '\n')
+    s.poll()
+    expect(s.getLabel('A')).toBe('Replying')
+    s.stop()
+  })
+
+  it('fires onLabel subscribers as new lines arrive', () => {
+    const sessionId = 'sess3'
+    const sched = makeManualScheduler()
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+    const seen: Array<[string, string]> = []
+    s.onLabel((id, label) => seen.push([id, label]))
+
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    appendFileSync(f, JSON.stringify({ ts: 1, tool_use_id: 'X', agent_id: null, label: 'Reading a.ts', tool_name: 'Read' }) + '\n')
+    s.poll()
+    expect(seen).toEqual([['X', 'Reading a.ts']])
+
+    appendFileSync(f, JSON.stringify({ ts: 2, tool_use_id: 'Y', agent_id: null, label: 'Editing b.ts', tool_name: 'Edit' }) + '\n')
+    s.poll()
+    expect(seen).toEqual([['X', 'Reading a.ts'], ['Y', 'Editing b.ts']])
+    s.stop()
+  })
+
+  it('ignores malformed JSON lines', () => {
+    const sessionId = 'sess4'
+    const sched = makeManualScheduler()
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    writeFileSync(
+      f,
+      'not-json\n' +
+      JSON.stringify({ tool_use_id: 'good', label: 'Saved memory', ts: 1, tool_name: 'mcp__hindsight__retain', agent_id: null }) + '\n' +
+      '{partial\n',
+    )
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+    expect(s.getLabel('good')).toBe('Saved memory')
+    s.stop()
+  })
+
+  it('first write wins (idempotent on duplicates)', () => {
+    const sessionId = 'sess5'
+    const sched = makeManualScheduler()
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    writeFileSync(
+      f,
+      JSON.stringify({ tool_use_id: 'A', label: 'first', ts: 1, tool_name: 'Read', agent_id: null }) + '\n' +
+      JSON.stringify({ tool_use_id: 'A', label: 'second', ts: 2, tool_name: 'Read', agent_id: null }) + '\n',
+    )
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+    expect(s.getLabel('A')).toBe('first')
+    s.stop()
+  })
+})

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

@@ -59,12 +59,14 @@ const enqueue = (chatId: string): SessionEvent => ({
 
 describe('P2: completion gates on background fleet members', () => {
   it('hasLiveBackground reflects fleet status correctly', () => {
+    // isBackgroundDispatch is the sticky flag used by hasLiveBackground —
+    // status alone is no longer the gate (fixes #757).
     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],
+      ['a', { agentId: 'a', status: 'background' as const, terminalAt: null, isBackgroundDispatch: true } as never],
+      ['b', { agentId: 'b', status: 'done' as const, terminalAt: 2000, isBackgroundDispatch: false } as never],
     ])
     expect(hasLiveBackground(fleet as never)).toBe(true)
-    fleet.set('a', { agentId: 'a', status: 'done' as const, terminalAt: 3000 } as never)
+    fleet.set('a', { agentId: 'a', status: 'done' as const, terminalAt: 3000, isBackgroundDispatch: true } as never)
     expect(hasLiveBackground(fleet as never)).toBe(false)
   })
 

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

@@ -61,6 +61,16 @@ describe('phaseFor truth table', () => {
     ['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'],
+    // Regression: pre-fix the `[].every(...)` vacuous-truth at
+    // two-zone-card.ts fleetAllStuck would mark the fleet stalled the
+    // moment the last sub-agent finished while the parent was still
+    // running. Plan agents that completed in 2-3min showed ⚠ Stalled
+    // on the pinned card until the parent itself wrapped up. Now: zero
+    // running-or-stuck members in the fleet means we fall through to
+    // the default "Working…" instead.
+    ['regression: all fleet done + parent still running → Working… (was Stalled)', st({ stage: 'run' }), fleetOf(fm('a', 'done'), fm('b', 'done')), {}, 'Working…'],
+    ['regression: lone done sub-agent + parent still running → Working…', st({ stage: 'run' }), fleetOf(fm('a', 'done')), {}, 'Working…'],
+    ['regression: failed-only fleet + parent still running → Working… (was Stalled)', st({ stage: 'run' }), fleetOf(fm('a', 'failed')), {}, 'Working…'],
   ])('%s', (_name, state, fleet, opts, expectedLabel) => {
     const phase = phaseFor(state, fleet, NOW, opts as Record<string, unknown>)
     expect(phase.label).toBe(expectedLabel)

package/telegram-plugin/tests/two-zone-snapshot-extras.test.ts

@@ -100,13 +100,16 @@ describe('PR-C2: two-zone card snapshot extras', () => {
     // 12 items, cap 8 → 4 hidden.
     expect(out).toContain('(+4 earlier)')
     // The visible bullets are the LAST 8 (slice(-8) → f4..f11).
-    expect(out).toContain('<code>f11.ts</code>')
-    expect(out).toContain('<code>f4.ts</code>')
-    // f3 (the latest hidden) must not appear as a bullet code block.
-    expect(out).not.toContain('<code>f3.ts</code>')
+    // f11 is the in-flight bullet (stage=run, last index) → ◉.
+    expect(out).toContain('◉ f11.ts')
+    expect(out).toContain('● f4.ts')
+    // f3 (the latest hidden) must not appear as a bullet.
+    expect(out).not.toContain('f3.ts')
+    // No <code> wrapping around row labels anymore.
+    expect(out).not.toContain('<code>f11.ts</code>')
   })
 
-  it('parent zone: in-flight last bullet uses ◉ <b>tool</b>; earlier use ● tool', () => {
+  it('parent zone: in-flight last bullet uses ◉ <plain>; earlier use ● <plain>', () => {
     const items = [
       { tool: 'Read', label: 'a.ts' },
       { tool: 'Read', label: 'b.ts' },
@@ -117,13 +120,16 @@ describe('PR-C2: two-zone card snapshot extras', () => {
       fleet: new Map(),
       now: NOW,
     })
-    // last item active
-    expect(out).toContain('◉ <b>Bash</b> <code>ls</code>')
-    // earlier items plain
-    expect(out).toContain('● Read <code>a.ts</code>')
-    expect(out).toContain('● Read <code>b.ts</code>')
-    // last item is NOT plain
-    expect(out).not.toContain('● Bash <code>ls</code>')
+    // last item active — plain text, no <b>, no <code>, no tool prefix
+    expect(out).toContain('◉ ls')
+    expect(out).not.toContain('◉ <b>')
+    // earlier items — plain text only, no tool prefix
+    expect(out).toContain('● a.ts')
+    expect(out).toContain('● b.ts')
+    expect(out).not.toContain('Read <code>')
+    // No <code> wrapping anywhere on parent rows.
+    expect(out).not.toContain('<code>ls</code>')
+    expect(out).not.toContain('<code>a.ts</code>')
   })
 
   it('parent zone: when stage=done all bullets render as ● (no active marker)', () => {
@@ -136,8 +142,46 @@ describe('PR-C2: two-zone card snapshot extras', () => {
       fleet: new Map(),
       now: NOW,
     })
-    expect(out).toContain('● Read <code>a.ts</code>')
-    expect(out).toContain('● Bash <code>ls</code>')
+    expect(out).toContain('● a.ts')
+    expect(out).toContain('● ls')
     expect(out).not.toContain('◉')
   })
+
+  it('parent zone: row with no label falls back to humanised tool name', () => {
+    const items = [
+      { tool: 'TodoWrite', label: '' },
+      { tool: 'Edit', label: '' },
+    ]
+    const out = renderTwoZoneCard({
+      state: st({ stage: 'run', turnStartedAt: NOW - 5000, items }),
+      fleet: new Map(),
+      now: NOW,
+    })
+    expect(out).toContain('● updating tasks')
+    expect(out).toContain('◉ editing file')
+  })
+
+  it('parent zone: row with no label on mcp tool uses mcpDisplayName', () => {
+    const items = [
+      { tool: 'mcp__switchroom-telegram__reply', label: '' },
+    ]
+    const out = renderTwoZoneCard({
+      state: st({ stage: 'run', turnStartedAt: NOW - 5000, items }),
+      fleet: new Map(),
+      now: NOW,
+    })
+    expect(out).toContain('◉ Telegram: reply')
+  })
+
+  it('parent zone: HTML in label is escaped (no raw <code> styling)', () => {
+    const items = [
+      { tool: 'Bash', label: 'echo <hi>' },
+    ]
+    const out = renderTwoZoneCard({
+      state: st({ stage: 'done', turnStartedAt: NOW - 5000, items }),
+      fleet: new Map(),
+      now: NOW,
+    })
+    expect(out).toContain('● echo &lt;hi&gt;')
+  })
 })

package/telegram-plugin/tests/welcome-text.test.ts

@@ -243,6 +243,63 @@ describe("statusPairedText", () => {
       expect(out).toContain("<b>Version</b>");
     });
   });
+
+  // Live probe block — `/status` shows EVERY probe (green and otherwise).
+  // This is the deliberate opposite of the boot card's silent-when-healthy
+  // contract: boot card = quiet ack, /status = dashboard.
+  describe("live health block", () => {
+    it("does NOT render a Health section when meta.live is undefined", () => {
+      const out = statusPairedText({ user: "@ken", meta });
+      expect(out).not.toContain("<b>Health</b>");
+    });
+
+    it("does NOT render a Health section when meta.live is empty array", () => {
+      const out = statusPairedText({ user: "@ken", meta: { ...meta, live: [] } });
+      expect(out).not.toContain("<b>Health</b>");
+    });
+
+    it("renders all probe rows including green ones", () => {
+      const live: AgentMetadata["live"] = [
+        { status: "ok",       label: "Account",   detail: "ken@x.com · Max · token 60d" },
+        { status: "ok",       label: "Broker",    detail: "reachable" },
+        { status: "degraded", label: "Skills",    detail: "1/5 dangling: foo" },
+        { status: "fail",     label: "Scheduler", detail: "sidecar not running" },
+      ];
+      const out = statusPairedText({ user: "@ken", meta: { ...meta, live } });
+      expect(out).toContain("<b>Health</b>");
+      expect(out).toContain("🟢 <b>Account</b>  ken@x.com · Max · token 60d");
+      expect(out).toContain("🟢 <b>Broker</b>  reachable");
+      expect(out).toContain("🟡 <b>Skills</b>  1/5 dangling: foo");
+      expect(out).toContain("🔴 <b>Scheduler</b>  sidecar not running");
+    });
+
+    it("renders Health section before the audit block", () => {
+      const live: AgentMetadata["live"] = [
+        { status: "ok", label: "Account", detail: "ok" },
+      ];
+      const audit = {
+        version: "v0.3.0", tools: "all", toolsDeny: null, skills: null,
+        limits: "idle 30m", channel: "switchroom", memoryBank: "x",
+      };
+      const out = statusPairedText({
+        user: "@ken",
+        meta: { ...meta, live, audit },
+      });
+      const healthIdx = out.indexOf("<b>Health</b>");
+      const versionIdx = out.indexOf("<b>Version</b>");
+      expect(healthIdx).toBeGreaterThan(-1);
+      expect(versionIdx).toBeGreaterThan(healthIdx);
+    });
+
+    it("escapes HTML in probe detail strings", () => {
+      const live: AgentMetadata["live"] = [
+        { status: "fail", label: "Skills", detail: "<script>alert(1)</script>" },
+      ];
+      const out = statusPairedText({ user: "@ken", meta: { ...meta, live } });
+      expect(out).not.toContain("<script>alert");
+      expect(out).toContain("&lt;script&gt;");
+    });
+  });
 });
 
 // Local alias for the audit shape — duplicates the AgentMetadata.audit

package/telegram-plugin/tool-label-sidecar.ts

@@ -0,0 +1,140 @@
+/**
+ * Sidecar reader for $TELEGRAM_STATE_DIR/tool-labels-${session_id}.jsonl —
+ * the per-tool-call human labels emitted by the PreToolUse hook
+ * `tool-label-pretool.mjs` (#783).
+ *
+ * Two surfaces:
+ *
+ *   getLabel(toolUseId): string | undefined
+ *     Returns the label if the sidecar has already produced one for this
+ *     tool_use. Synchronous, in-memory.
+ *
+ *   onLabel(cb): unsubscribe
+ *     Subscribes to "label arrived for this tool_use_id" notifications,
+ *     used by the renderer to re-emit a checklist row when a label
+ *     arrives AFTER the matching JSONL `tool_use` has been processed.
+ *
+ * Design notes:
+ *   - Plain stat()-poll watcher (every 250ms) — simpler than fs.watch and
+ *     robust to all the platform quirks. The hot path is two-digit ms.
+ *   - Append-only: we track a per-file byte offset and only read the new
+ *     suffix on each tick, so re-reading is cheap.
+ *   - One reader per session_id. The driver instantiates a reader when a
+ *     session JSONL is first observed; old readers are stopped when the
+ *     session is evicted from the chat-state TTL map.
+ *
+ * Pure module — no globals. Tests inject a custom directory and clock.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface ToolLabelRow {
+  ts: number
+  tool_use_id: string
+  agent_id: string | null
+  label: string
+  tool_name: string
+}
+
+export interface ToolLabelSidecar {
+  /** Synchronous label lookup. */
+  getLabel(toolUseId: string): string | undefined
+  /** Subscribe to "label arrived" notifications. */
+  onLabel(cb: (toolUseId: string, label: string) => void): () => void
+  /** Force a re-poll (tests). */
+  poll(): void
+  /** Stop polling and release resources. */
+  stop(): void
+}
+
+export interface SidecarOptions {
+  stateDir: string
+  sessionId: string
+  /** Polling interval in ms. Default 250. */
+  pollMs?: number
+  /** Inject for tests; defaults to setInterval. */
+  scheduler?: {
+    setInterval: (cb: () => void, ms: number) => unknown
+    clearInterval: (handle: unknown) => void
+  }
+}
+
+export function createToolLabelSidecar(opts: SidecarOptions): ToolLabelSidecar {
+  const path = join(opts.stateDir, `tool-labels-${opts.sessionId}.jsonl`)
+  const labels = new Map<string, string>()
+  const subscribers = new Set<(toolUseId: string, label: string) => void>()
+  let offset = 0
+  let stopped = false
+
+  const sched = opts.scheduler ?? {
+    setInterval: (cb, ms) => setInterval(cb, ms),
+    clearInterval: (h) => clearInterval(h as ReturnType<typeof setInterval>),
+  }
+
+  function ingestSuffix(text: string): void {
+    if (!text) return
+    const lines = text.split('\n')
+    for (const raw of lines) {
+      const line = raw.trim()
+      if (!line) continue
+      let row: ToolLabelRow | null = null
+      try {
+        row = JSON.parse(line) as ToolLabelRow
+      } catch {
+        continue
+      }
+      if (!row || typeof row.tool_use_id !== 'string' || typeof row.label !== 'string') continue
+      // First write wins — sidecar lines are append-only and we don't
+      // expect duplicates, but if one lands we keep the earliest.
+      if (labels.has(row.tool_use_id)) continue
+      labels.set(row.tool_use_id, row.label)
+      for (const cb of subscribers) {
+        try { cb(row.tool_use_id, row.label) } catch { /* ignore */ }
+      }
+    }
+  }
+
+  function poll(): void {
+    if (stopped) return
+    if (!existsSync(path)) return
+    let size = 0
+    try { size = statSync(path).size } catch { return }
+    if (size <= offset) {
+      // Truncation safety: if the file shrank (rotation / manual delete),
+      // reset offset so we re-read from the start.
+      if (size < offset) offset = 0
+      else return
+    }
+    let text = ''
+    try {
+      const buf = readFileSync(path)
+      text = buf.subarray(offset).toString('utf8')
+      offset = buf.length
+    } catch {
+      return
+    }
+    ingestSuffix(text)
+  }
+
+  // Initial drain, in case the file already exists when we start.
+  poll()
+  const handle = sched.setInterval(poll, opts.pollMs ?? 250) as unknown
+
+  return {
+    getLabel(toolUseId) {
+      return labels.get(toolUseId)
+    },
+    onLabel(cb) {
+      subscribers.add(cb)
+      return () => subscribers.delete(cb)
+    },
+    poll,
+    stop() {
+      if (stopped) return
+      stopped = true
+      try { sched.clearInterval(handle) } catch { /* ignore */ }
+      subscribers.clear()
+    },
+  }
+}