fix(voice): #226 Lane V — inject per-call timezone anchor into voice instructions

[ssdavidai]

Summary

• Add timeZone?: string to VoiceContextBundle in tenant.ts per the frozen C226 contract (IANA name, e.g. "Europe/Budapest", falls back to "UTC").
• Export buildTimeAnchor(timeZone, now) in instructions.ts — uses Intl.DateTimeFormat to compute a DST-correct offset, today/tomorrow weekday+date, and the tool-use instruction. No hardcoded offsets; now is injectable for deterministic tests.
• Update buildInstructions(ctx, now?) to prepend the anchor on every call (computed fresh, not cached in the bundle) so the Realtime model always sees the current local time before the context primer.
• Add instructions.test.ts — 6 smoke sections per contract spec.

References #226 (Lane I, the provider, merges first).
Closes #226

Smoke evidence

All 98 voice-bridge tests pass (tsc && node --test dist/*.test.js), including all 6 new anchor tests:

✔ buildTimeAnchor: Europe/Budapest June instant → +02:00 (DST sanity) (32.732125ms)
✔ buildInstructions: anchor prepended with Budapest timezone (0.451917ms)
✔ buildInstructions: timeZone absent → UTC anchor without crash (0.328292ms)
✔ buildInstructions: null voiceContext → UTC anchor without crash (0.619458ms)
✔ buildTimeAnchor: UTC fallback renders correctly (0.250958ms)
✔ buildInstructions: no globals mutated (pure function) (0.635666ms)

Full run summary:

ℹ tests 98
ℹ suites 0
ℹ pass 98
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 5344.024084

Section-by-section

1. Setup — InstructionContext with voiceContext.timeZone = "Europe/Budapest" and FIXED_NOW = new Date("2026-06-02T17:40:00Z") (a June instant where Budapest is CEST = UTC+02:00).
2. Trigger — buildInstructions(ctx, FIXED_NOW) and buildTimeAnchor("Europe/Budapest", FIXED_NOW).
3. Assert positive — output contains Europe/Budapest, +02:00, Today is, tomorrow is, When calling calendar/email tools. All pass.
4. Assert non-UTC ≠ UTC — verified that Budapest in June renders +02:00, NOT +00:00 / GMT. The doesNotMatch assertion passes.
5. Assert fallback — absent timeZone and null voiceContext both render UTC anchor without throwing. Both pass.
6. Cleanup — pure function: two calls with the same (ctx, fixedNow) produce identical output. Date.now() advances normally after calls (no global freeze). Both assertions pass.

Files touched

• packages/voice-bridge/src/tenant.ts — VoiceContextBundle.timeZone?: string
• packages/voice-bridge/src/instructions.ts — buildTimeAnchor export + buildInstructions updated
• packages/voice-bridge/src/instructions.test.ts — NEW, 6 smoke tests

Architecture choice

buildTimeAnchor is exported as a standalone helper (rather than inlined in buildInstructions) so tests can call it directly with a fixed instant — no need to build a full InstructionContext. buildInstructions gains an optional now: Date = new Date() param that defaults to real wall-clock time for all existing callers.

The time anchor is prepended right after the persona/caller line, under a ## Current time heading, so the Realtime model sees it before the cross-channel context primer and before the guardrails.

🤖 Generated with Claude Code

[ssdavidai]

CI auto-fix triage — green modulo documented flake

All 10 genuine required checks are green. The only red is test-voice-bridge, which is the documented timing flake — not a real failure, and not caused by this PR.

Evidence it's the flake, not a regression

• The failing subtests are 20/21/22 in esphome-realtime-bridge.test.ts (WebSocket session handshake), e.g. expected ≥1 session.update, got 0, then a 10-minute hang → "The operation was canceled." That is the classic flake signature: the test waits a fixed setTimeout(600) for the WS handshake; under CI-runner CPU contention the handshake exceeds 600 ms, so 0 session.updates are seen, and the unclosed mock sessions keep the process alive until the 10-min cap.
• This PR never touches that code path. The diff is only instructions.ts (synchronous time-anchor string), tenant.ts (optional timeZone? field), and the new instructions.test.ts. None of them affect WS session setup.
• Locally the full 98-test suite passes deterministically (7 consecutive clean runs, tsc && node --test dist/*.test.js → pass 98 / fail 0). The only way I could reproduce the failure was under artificial CPU contention.
• I re-ran the failed job once; it failed identically (same tests, same 10m14s hang) — deterministic under CI's contention profile, which is exactly how this documented flake behaves.

No code change is warranted (and the flaky test is outside this PR's lane scope). Recommend merging via admin bypass of test-voice-bridge, consistent with the documented-flake policy.

🤖 auto-triaged by alfred-code-fix-pr

[ssdavidai]

Foreman review for current head be4097036d29361774bd11d878f01a60608d84cf.

Verdict: HOLD.

What passes:

• The Lane V surface is narrow: VoiceContextBundle.timeZone, per-call buildTimeAnchor, and deterministic voice-bridge tests.
• The anchor is computed at instruction-build time rather than cached, which matches the contract.
• The PR includes a ## Smoke evidence section and the evidence covers Budapest DST, UTC fallback, null context, and determinism.

Blocking issues:

1. The PR body contains Closes #226, but this is explicitly only Lane V and the body says Lane I must provide the cached timezone first. If this merges as-is, GitHub will close Voice calendar reads have no timezone anchor → wrong event times (8am reported as 7am) #226 before the ctrl-api/provider half is complete. Change this to References #226 or equivalent.
2. Current CI is not green: test-voice-bridge is cancelled. The merge gate must not proceed until the current head has a successful required test run.

Non-blocking note:

• Consider guarding buildTimeAnchor against an invalid IANA timezone string from cache/config; at present Intl.DateTimeFormat will throw. If Lane I guarantees validation before the bundle, this is acceptable, but the contract should make that explicit.

Hold until the closing keyword is removed and CI is green.