feat(director): the brain gets the clock to the minute and the song's real progress [spec 04]

[Eis4TY]

What

The speaking brain was missing two pieces of ground truth, and invented both:

• The clock. The scene bucket is a mood, not a schedule — late-night spans 23:00–04:59, so a model reading only the cue could not tell 01:00 (hours to dawn) from 04:00. Every prompt that speaks aloud (the two self-initiated builders, the reply, the steer task) now renders Local time: Monday 2026-08-31, 01:23. beside the scene cue.
• What is actually on air. The model cannot hear the engine, so it re-narrated its own announcements as the air — a song "finished" because the host said it would. The Director now stamps compose-time facts on the pack (ctx.air), derived from the same startedAt+durationS arithmetic the spec-10 progress rail runs on, and the prompt renders them as a facts block: On air now: Song — Artist (2:10 of 4:05 played, about 1:55 left). A music session between tracks says no track is on air; a talk-only session renders no block at all.

Where

• src/contracts.ts — ContextPack.now + ContextPack.air (both optional, additive; absent renders nothing).
• src/prompts.ts — formatClock / formatProgress (pure, pinned with injected clock values, the scene_for pattern) + the clockLine / programFacts renderers, threaded into all four speaking builders. Prompt text stays centralized here (DESIGN §0).
• src/director.ts — context() samples the clock once per compose; airFacts() derives the on-air state from the segment stamp (clamped to the track's length).
• Specs: specs/spec04/04-no-dead-air.md §2 / §3.4 amendments / §5 criteria 13–14; specs/spec01/01-core-loop.md §2.1 pack docstring.

Evidence

• Test-first: each step landed red before its implementation (test/prompts.test.ts clock + progress + facts states; test/director-music.test.ts mid-song / between-tracks / talk-only pack assertions; test/director-steer.test.ts the steer context clock).
• Gates in the worktree: pnpm run typecheck ✅, pnpm run lint ✅, pre-commit run --all-files ✅ (all four hooks), pnpm test 984 passed / 6 failed — the 6 are pre-existing machine-local failures in test/config.test.ts / test/app.test.ts (they read this machine's real ~/.murmur/voice.json through the NO_ENV homedir fallback; identical on the stashed clean baseline, unrelated to this change).

---

中文摘要

本次给模型的提示词补充了两项"现场事实",目标是让 AI 基于事实判断情境,而不是靠模糊提示脑补:

1. 精确到分钟的本地时间。此前提示词只有"上午 / 下午 / 深夜"这类粗粒度时段,而深夜桶覆盖 23:00–04:59,AI 无法区分凌晨一点和凌晨四点,常在午夜说出"快天亮了"这类错判。现在每条开口提示(自主播报、听众回复、steer 任务)都会在场景提示旁附带精确时间,例如 Local time: Monday 2026-08-31, 01:23.

2. 当前在播歌曲及播放进度。AI 听不到音频引擎,只能凭自己先前说过的话"回忆"在播什么,于是歌还没播完就被它宣告结束。现在 Director 在组合上下文时,把在播曲目、已播时长与总时长作为事实块注入提示,例如 On air now: Song — Artist (2:10 of 4:05 played, about 1:55 left).;两首歌之间会明确说明当前没有歌曲在播(避免 AI 凭空续播已结束的歌),纯谈话会话则不注入该块。

[wine-fall]

Thanks for the diagnosis! it was right, and it landed the same day from two directions.

The clock half of this PR is now on main via #191, with you as commit author (squash commit eccdcc0 carries Co-authored-by to your account). The music-grounding half had already landed in #165 with a wider state model (playing / quiet / picking / pick-failed) plus anti-fabrication rules.

The on-air progress numbers were left out on purpose: self-initiated beats are composed two deep ahead of air (spec 04 §3.3), so a countdown stamped at compose time is already false when spoken, and cuts against #165's rule to say nothing that turns false when the music changes. Progress on the immediate reply path alone would be accurate — a separate, smaller change if wanted.

Closing in favour of #191.

[Eis4TY]

Okay, I understand your point. There definitely needs to be a better system for tracking playback progress.