feat(director): talk look-ahead buffer [spec 04]

[wine-fall]

What

PR#3 of the cold-start work — spec 04 slice 2: talk look-ahead.

One next_talks(2) Brain call produces two consecutive beats. Beat 1 airs while
beat 2's synthesis runs in the background; the next talk segment then plays
from the buffer with no Brain call and no synthesis on its critical path —
the inter-segment latency (~Brain + ~TTS per gap) is gone.

• Brain.next_talks(ctx, count=2) -> list[str] (additive; next_talk /
  respond unchanged). The claude-agent-sdk query has no output schema (only
  tool-input schemas), so the beats come back as structured output via the
  harness tool seam already used for music discovery: a terminal
  emit_talk_beats tool (talk_tools.py) whose input_schema fixes the shape.
  The model calls the tool; the SDK delivers the call as a parsed mapping that
  parse_talk_beats validates — no free-text JSON to scrape. An empty batch
  (model never made the terminal call) falls back to one plain-text next_talk
  beat rather than skipping the segment into dead air.
• Look-ahead buffer in the Director: beat 2 buffered as a background synth
  task, aired next with no wait. Discarded when stale — a talkback steer
  (predates the user turn) or a song going on air (the beat was a
  consecutive-talk continuation) — and settled on shutdown.

Completes spec 04 (slice 1 = music prefetch shipped in #25; this is slice 2).

Implements specs/spec04/04-no-dead-air.md

Why

Removes the per-gap Brain+TTS wait between talk segments — the compounding half
of the cold-start work (music prefetch, #25, removed the ~45s first-song wait).

Design notes

• Beat 1 airs first, always. The look-ahead synth tasks are scheduled before
  beat 1's await, so on a concurrent backend (remote) beat 2 overlaps beat 1's
  synth, not just its playback; on a lock-serialized backend (sidecar) beat 1
  still grabs the lock first via inline execution.
• Staleness = discard. Freshness beats saving one call: an interjection or an
  intervening song both invalidate a pre-generated beat, so it's dropped and the
  next segment regenerates against current context.
• count is a call parameter (default 2), not a config knob (spec 04 §6 —
  deepen only if measurement shows a remaining gap).

Tests

• Parser: plain array, code-fence/prose tolerance, empty-item drop, cap to
  count, malformed → single beat, empty → empty.
• next_talks shape (stub returns 2 consecutive beats).
• Buffer: two segments from one next_talks(2); steer discards the buffer (next
  segment regenerates fresh); song-intervening discards it; shutdown settles it.
• Full suite: 242 passed, 12 deselected.

Peer review

codex (gpt-5.5, xhigh): 3 findings, 3 applied, 0 dismissed — (1) schedule
look-ahead synth before awaiting beat 1 (overlap synth on concurrent backends);
(2) discard the talk buffer when a song intervenes (a consecutive-talk beat is
stale post-song, and its hidden synth competed with the intro); (3) cap the
parsed batch to count (an over-producing model must not inflate the buffer).
(2) and (3) got regression tests; (1) is a concurrency-timing reorder covered
functionally by the batching test.

Verified live

One real ClaudeBrain.next_talks(count=2) smoke returned a clean JSON array of
two Chinese spoken beats (look-ahead ACTIVE, not degraded) — confirming the
real-model batch assumption the fakes can't prove. The deterministic parser /
buffer / invalidation are unit-tested; "does the model reliably emit N clean
beats" stays an eval-track concern.

Post-open re-architecture (review-driven)

The batch output originally came back as a prompt-specified JSON array parsed by
a string-munging parse_talk_batch (extract outermost [...], strip code
fences). On review that was replaced with the harness tool seam (the
codebase's sanctioned structured-output mechanism, spec 03-01): emit_talk_beats
with a typed input_schema, delivered as a parsed mapping — no text parsing.
Second codex round on that change: 2 findings, 1 applied (empty-batch →
fall back to one next_talk beat, not a skipped segment; regression-tested) +
1 resolved (the new talk_tools.py was untracked in the reviewed diff —
committing it fixes it). Verified live again: the real model calls
emit_talk_beats and returns 2 clean beats.

AI coding brief

• Original request: Speed up murmur's first cold start. This PR is the
  "brain text optimization" — one Brain call for two beats + parallel TTS +
  a look-ahead buffer, so segments after the first air with no Brain/TTS wait.
  Final slice of spec 04 (pulled forward for cold-start).
• Manual interventions: User chose JSON output (checked first whether the SDK
  supports an output schema — it doesn't, so prompt-specified JSON); count a
  call parameter with default 2, no config knob; discard-on-steer semantics.
  Earlier line-by-line review of the loop set the bar for spin/deadlock-free
  control flow, kept here.
• Retro: Checking the SDK's structured-output support up front (it has schema
  only for tool inputs, not plain-query output) settled the JSON-vs-tool question
  before any code — worth doing whenever "make the model return structured data"
  comes up. A one-line kickoff note ("SDK query has no output schema; use
  prompt-JSON or the tool pattern") would pre-answer it next time.

🤖 Generated with Claude Code