> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase40-session16-voice-parity-and-broker-respawn` **Started**: 2026-07-03 11:10 **Last Updated**: 2026-07-03 11:32

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 20 / 20 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Task Log

### 2026-07-03 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

**Checks**:

* `bash .spec_system/scripts/analyze-project.sh --json`
  * Result: PASS - Active session resolved to `phase40-session16-voice-parity-and-broker-respawn`; session directory exists with `spec.md` and `tasks.md`.
* `bash .spec_system/scripts/check-prereqs.sh --json --env`
  * Result: PASS - `.spec_system`, `jq`, and `git` available; workspace is not a monorepo.
* `bash .spec_system/scripts/check-prereqs.sh --json --tools "bun"`
  * Result: PASS - Bun 1.3.14 available.

***

## Voice Parity Audit

### Upstream Behavior

* Upstream stores a user-provided OpenAI key in browser localStorage under `hermes-openai-key`.
* Upstream reuses the saved browser key on later sessions to avoid setup reprompts.
* Upstream sends the key to `/api/session` and `/__start_voice` request bodies, optionally with a browser-supplied base URL.

### AI OS Replacement Behavior

* AI OS preserves the no-unnecessary-reprompt outcome by respawning the local broker from ignored local environment when `OPENAI_API_KEY` is configured for the Vite dev server.
* Browser code calls `/__start_voice` before showing setup/error recovery and sends no provider key or provider base URL.
* `/__start_voice` accepts an empty body and empty `{}` compatibility body, rejects any browser-supplied provider config, validates token/loopback/body bounds, reads `OPENAI_API_KEY` and optional `OPENAI_BASE_URL` from environment, and passes provider config to the child process through environment only.
* The broker mints short-lived Realtime session credentials from server-side provider config and never accepts browser provider config in `/api/session`.

### Intentional Non-Port Rationale

* Browser key persistence is an intentional non-port because Session 01 `INV-014` and `DEC-004` require voice provider credentials to stay environment-backed.
* The upstream desired user outcome is not "store a key in the browser"; it is "do not reprompt every session when a safe credential source already exists."
* AI OS satisfies that outcome through local broker health/start/session flow while preserving local control-plane, token, and provider-boundary protections.

## Session 17 Documentation Queue

* Document that AI OS voice no-reprompt parity means local broker respawn from ignored env, not browser OpenAI key persistence.
* Keep `OPENAI_API_KEY` and optional `OPENAI_BASE_URL` documented as local environment inputs only.
* State that `/__start_voice` accepts empty launches and rejects browser provider config.
* State that browser code sends only the same-run token to `/__start_voice` and `/api/session`, and only `voice`/`mode` to `/api/session`.
* Preserve Session 08 voice broker ownership and Session 09 Hermes Intelligence portal ownership caveats.
* Keep live-provider proof caveated: mocked broker/provider tests are valid for this session; do not claim a real spoken provider result without safe local credentials and redacted evidence.
* Keep public/demo docs clear that live voice and local writes are unavailable outside local admin mode.

***

## Implementation Fix Summary

* Production source changes: none required.
* Test changes: expanded bridge, hook, and portal suites to lock the shipped voice parity behavior.
* Behavior confirmed: no browser provider key/base body, empty launch compatibility, env-only broker spawn, duplicate-start prevention, health-timeout cleanup, OpenAI/loopback base policy, bridge/session failure mapping, Realtime cleanup, and product-facing portal recovery.
* BQC result so far: no production BQC fixes required; test coverage was added around trust-boundary enforcement, duplicate-action prevention, cleanup, failure paths, contract alignment, accessibility, and product-surface boundaries.

## Test Evidence Summary

* `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * PASS - 3 test files, 23 tests.
* `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts scripts/lib/__tests__/voice-broker.test.ts`
  * PASS - 2 test files, 18 tests.
* Formal session testing gates continue in T015 through T020.

***

### Task T001 - Review upstream saved-key start behavior, Session 16 scope, and Session 01 voice decisions

**Started**: 2026-07-03 11:10 **Completed**: 2026-07-03 11:12 **Duration**: 2 minutes

**Notes**:

* Upstream stores `hermes-openai-key` in browser localStorage, reuses it on later sessions, sends it to `/api/session`, and posts it to `/__start_voice` as browser-supplied provider config.
* Session 16 scope keeps the no-unnecessary-reprompt outcome but rejects the upstream storage/request-body mechanism.
* Session 01 recorded the controlling AI OS decisions: `INV-014`, `DEC-004`, `DEC-009`, `MAP-016`, `CLS-015`, and `CLS-022`.
* AI OS parity target for this session is environment-backed broker respawn from ignored local env, not browser key reuse.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded upstream comparison and Session 01 decision evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T001 complete after evidence was recorded.

**Verification**:

* Command/check: `cat .spec_system/PRD/phase_40/session_16_voice_parity_and_broker_respawn.md`
  * Result: PASS - Session 16 scope reviewed.
  * Evidence: Stub states AI OS should keep environment-backed provider configuration and should not port browser localStorage key persistence.
* Command/check: `rg -n "openaiKey|hermes-openai-key|VOICE|startCall|start_voice|api/session|localStorage" <upstream-checkout>/src/components/intelligence-portal.tsx`
  * Result: PASS - upstream saved-key flow isolated.
  * Evidence: Matches show `hermes-openai-key` localStorage reads/writes, `/api/session` body with `key`, and `/__start_voice` body with `key`/`base`.
* Command/check: `sed -n '250,520p' <upstream-checkout>/src/components/intelligence-portal.tsx`
  * Result: PASS - upstream start-call and respawn logic reviewed.
  * Evidence: Output showed saved-key reuse, `startEngine(openaiKey)`, and provider config in browser request bodies.
* Command/check: `rg -n "INV-014|DEC-004|DEC-009|MAP-016|CLS-015|CLS-022|voice|OpenAI" .spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md`
  * Result: PASS - Session 01 voice decisions found.
  * Evidence: Output identifies voice credentials as environment-backed, upstream browser key persistence as an intentional non-port, and current launch/broker behavior as already covered.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T002 - Verify current environment-backed voice startup ownership

**Started**: 2026-07-03 11:12 **Completed**: 2026-07-03 11:14 **Duration**: 2 minutes

**Notes**:

* `scripts/lib/voice-launch-bridge.ts` owns guarded `POST /__start_voice`, accepts an empty launch body, rejects non-empty browser provider config, reads `OPENAI_API_KEY`/`OPENAI_BASE_URL` from local env, spawns `bun run voice`, and passes the same-run token as `AI_OS_VOICE_TOKEN`.
* `scripts/lib/voice-broker.ts` owns `/api/health` and `/api/session`, keeps provider credentials server-side, enforces Host/Origin/token/body validation, and allowlists only OpenAI default or loopback base URLs.
* `src/hooks/use-hermes-intelligence-voice.ts` starts the bridge first, then requests a broker session with only `voice` and `mode`, opens WebRTC, maps failures, and cleans acquired runtime resources.
* `src/components/hermes/intelligence/intelligence-portal.tsx` owns the user-facing Hermes Intelligence portal, recovery copy, Start/Stop controls, typed prompts, transcript, activity rail, and visual modes.
* `docs/local-voice-setup.md` and `docs/intelligence-view.md` already document the current environment-only provider policy and the Session 08 broker / Session 09 portal ownership boundaries.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded current voice owner evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T002 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,420p' scripts/lib/voice-launch-bridge.ts`
  * Result: PASS - launch bridge reviewed.
  * Evidence: Output showed method, loopback/token, body-size/JSON/payload checks, env reads, base URL policy, spawn setup, duplicate-start guard, health polling, and timeout cleanup.
* Command/check: `sed -n '1,340p' scripts/lib/voice-broker.ts && sed -n '320,760p' scripts/lib/voice-broker.ts`
  * Result: PASS - broker reviewed.
  * Evidence: Output showed strict session schema, Host/Origin/token gates, provider timeout, safe error mapping, OpenAI/loopback base policy, and session minting without browser provider keys.
* Command/check: `sed -n '1,760p' src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - hook reviewed.
  * Evidence: Output showed `/__start_voice` call, empty-object bridge body, `/api/session` body with `voice`/`mode`, failure mapping, duplicate action prevention, and cleanup of aborts, peer, data channel, stream, and timers.
* Command/check: `sed -n '1,620p' src/components/hermes/intelligence/intelligence-portal.tsx`
  * Result: PASS - portal reviewed.
  * Evidence: Output showed Intelligence shell, voice controller wiring, recovery banner, Start/Stop controls, typed prompt form, transcript, activity, and design controls.
* Command/check: `cat docs/local-voice-setup.md && cat docs/intelligence-view.md`
  * Result: PASS - docs ownership reviewed.
  * Evidence: Docs state provider config is environment-only, `/__start_voice` starts the broker from ignored local env, browser receives only short-lived session credentials, and the portal remains `/agents/hermes?intel=1`.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T003 - Prepare focused test fixtures for voice launch, hook, and portal edge cases

**Started**: 2026-07-03 11:14 **Completed**: 2026-07-03 11:15 **Duration**: 1 minute

**Notes**:

* Made the launch bridge test helper deterministic by defaulting broker health fetches to a controlled down response unless a test overrides it.
* Added hook test helpers to parse request bodies so launch/session payload assertions can prove browser code does not send provider keys or base URLs.
* Reused portal voice/admin fixtures for recovery and active-control assertions.

**Files Changed**:

* `scripts/lib/__tests__/voice-launch-bridge.test.ts` - Added deterministic default fetch fixture for broker-down launch tests.
* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - Added request-body parsing helper for payload-shape checks.
* `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` - Reused existing voice/admin fixtures for new control and recovery cases.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T003 evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T003 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - modified voice bridge, hook, and portal suites passed.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed.
* Command/check: Manual fixture review against session edge-case list.
  * Result: PASS - fixtures cover empty launches, provider config bodies, missing key, invalid token, timeout, provider/session failure, broker-down respawn, and active controls.
  * Evidence: New helpers and fixture reuse are in the three modified test files.
* UI product-surface check: N/A - no production route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T004 - Extend launch bridge tests for empty launch, provider rejection, env-only spawn, and explicit errors

**Started**: 2026-07-03 11:14 **Completed**: 2026-07-03 11:16 **Duration**: 2 minutes

**Notes**:

* Added explicit acceptance coverage for truly empty request bodies and empty-object compatibility.
* Added schema/error coverage for invalid JSON, non-object payloads, oversized bodies, browser-supplied key/base fields, and disallowed environment base URLs.
* Preserved existing bridge coverage for env-only child spawn, no provider material in argv, already-running broker reuse, duplicate starts, spawn failure, and health-timeout child cleanup.

**Files Changed**:

* `scripts/lib/__tests__/voice-launch-bridge.test.ts` - Added launch-body, provider-config, base-policy, and deterministic broker-down test coverage.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T004 evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T004 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - modified focused suites passed.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed, including the expanded launch bridge tests.
* Command/check: Manual diff review of `scripts/lib/__tests__/voice-launch-bridge.test.ts`
  * Result: PASS - bridge coverage now asserts empty body acceptance, `{}` compatibility, `invalid_json`, `invalid_payload`, `body_too_large`, `base_not_allowed`, provider-config rejection, and no spawn on rejected input.
  * Evidence: New bridge tests fail closed before spawn for invalid/browser-supplied provider inputs and still allow empty launches to spawn with env-only config.
* UI product-surface check: N/A - no production route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: Trust boundary enforcement - Added explicit launch payload schema/error tests around the `/__start_voice` browser-to-local bridge boundary (`scripts/lib/__tests__/voice-launch-bridge.test.ts`).

***

### Task T005 - Extend voice hook tests for start payload, respawn ordering, error mapping, and cleanup

**Started**: 2026-07-03 11:14 **Completed**: 2026-07-03 11:17 **Duration**: 3 minutes

**Notes**:

* Tightened the happy-path hook test to assert `/__start_voice` receives `{}` only and `/api/session` receives only `voice` and `mode`.
* Added launch bridge failure-code cases for missing key, invalid token, health timeout, spawn failure, and start-in-flight/broker unavailable before any session credential or microphone request.
* Added broker session failure-code cases for invalid token and provider timeout.
* Added Realtime provider failure cleanup coverage after media, peer, and data channel resources are acquired.

**Files Changed**:

* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - Added payload-shape, bridge/session error mapping, broker-down ordering, and runtime cleanup coverage.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T005 evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T005 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - modified focused suites passed.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed, including expanded hook cases.
* Command/check: Manual diff review of `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - hook tests assert launch-first ordering, no browser key/base fields, distinct `missing-key`, `bad-token`, `timeout`, `spawn-failed`, `broker-unavailable`, and `provider-failed` states, and cleanup on Realtime failure.
  * Evidence: New assertions verify only `/__start_voice` is called for bridge failures and `getUserMedia` is skipped until launch/session prerequisites pass.
* UI product-surface check: N/A - no production route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: Resource cleanup - Added test coverage for stream, data channel, and peer cleanup after Realtime provider failure (`src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`).

***

### Task T006 - Extend Intelligence portal tests for recovery copy and active controls

**Started**: 2026-07-03 11:14 **Completed**: 2026-07-03 11:18 **Duration**: 4 minutes

**Notes**:

* Added a portal control test that invokes the voice controller through Start voice and Stop buttons.
* Added recovery coverage for missing same-run token and voice-controller bad-token failure copy.
* Preserved existing demo-mode gating, typed prompt submission, design switching, close cleanup, and active voice-loop start disabling coverage.
* Recovery assertions use product-facing text and explicitly check that stack/Bearer diagnostic strings are absent from the rendered portal.

**Files Changed**:

* `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` - Added Start/Stop control and recovery-copy assertions.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T006 evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T006 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - modified focused suites passed.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed, including expanded portal cases.
* Command/check: Manual diff review of `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - portal tests assert disabled Start voice in demo/missing-token/active states, usable Start/Stop controls in live-ready state, and product-facing recovery for token failures.
  * Evidence: New tests use accessible button names and visible recovery text instead of implementation-only selectors.
* UI product-surface check: PASS - test-only change confirms normal portal recovery copy is product-facing and does not expose stack or bearer diagnostics.
* UI craft check: PASS - test-only change preserves existing accessible button/form labels and active-control states.
* BQC Fixes: Accessibility and product surface discipline - Added portal assertions around accessible controls and user-facing recovery boundaries (`src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`).

***

### Task T007 - Record upstream non-port rationale, AI OS parity target, and Session 17 documentation queue

**Started**: 2026-07-03 11:18 **Completed**: 2026-07-03 11:19 **Duration**: 1 minute

**Notes**:

* Added `Voice Parity Audit` with upstream behavior, AI OS replacement behavior, and intentional non-port rationale.
* Added `Session 17 Documentation Queue` with exact docs notes that should be applied after this implementation evidence exists.
* The audit stays scoped to shipped behavior and avoids live-provider success claims.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Added parity audit and Session 17 docs queue.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T007 complete after evidence was recorded.

**Verification**:

* Command/check: Manual review of `Voice Parity Audit` against T001 through T006 evidence.
  * Result: PASS - audit records upstream saved-key behavior, AI OS env-backed replacement, no provider config in browser requests, and intentional non-port rationale.
  * Evidence: Section names `Upstream Behavior`, `AI OS Replacement Behavior`, and `Intentional Non-Port Rationale`.
* Command/check: Manual review of `Session 17 Documentation Queue` against session scope.
  * Result: PASS - queue covers env-only provider config, empty launch, browser body rejection, Session 08/09 ownership caveats, mocked evidence caveat, and public/demo limits.
  * Evidence: Seven concise documentation bullets added to implementation notes.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T008 - Audit launch-body parsing and error mapping

**Started**: 2026-07-03 11:19 **Completed**: 2026-07-03 11:20 **Duration**: 1 minute

**Notes**:

* No production change was required.
* Existing launch-body parsing reads at most 1024 bytes, accepts blank input, accepts empty object compatibility, rejects invalid JSON, rejects non-object bodies, and rejects any non-empty object before environment lookup or spawn.
* Existing bridge error codes already distinguish `invalid_json`, `invalid_payload`, `body_too_large`, `base_not_allowed`, `missing_key`, `invalid_token`, `start_in_flight`, `spawn_failed`, and `health_timeout`.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T008 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T008 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "rejectProviderConfigBody|readRequestBody|MAX_START_BODY_BYTES|Object\\.keys|missing_key|base_not_allowed|health_timeout|start_in_flight" scripts/lib/voice-launch-bridge.ts`
  * Result: PASS - launch-body and error-code ownership confirmed in production code.
  * Evidence: Matches show bounded body reads, empty-body return, non-empty object rejection, and distinct error-code branches.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - expanded tests pass against existing production bridge behavior.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: N/A - audit confirmed existing trust-boundary enforcement; no production fix required.

***

### Task T009 - Audit broker respawn, duplicate-start prevention, and timeout cleanup

**Started**: 2026-07-03 11:20 **Completed**: 2026-07-03 11:21 **Duration**: 1 minute

**Notes**:

* No production change was required.
* Existing bridge flow checks broker health before spawn and returns `already: true` when the broker is ready.
* Existing bridge flow sets `state.starting` during launch, rejects concurrent requests with `start_in_flight`, clears the flag in `finally`, and stops any tracked live child before respawn.
* Existing timeout path calls `stopLiveChild`, which kills the tracked process and clears state.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T009 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T009 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "state\\.starting|stopLiveChild|spawnVoiceBroker|pollVoiceHealth|child\\.kill|fetchVoiceHealth|already" scripts/lib/voice-launch-bridge.ts`
  * Result: PASS - respawn, duplicate-start, and cleanup branches confirmed in production code.
  * Evidence: Matches show existing health reuse, start-in-flight gate, child spawn tracking, health polling, timeout cleanup, and child kill.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - expanded bridge tests pass against existing respawn behavior.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed, including duplicate in-flight and timeout cleanup cases.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: N/A - audit confirmed existing duplicate-action prevention and cleanup; no production fix required.

***

### Task T010 - Audit provider environment handling and key/base boundaries

**Started**: 2026-07-03 11:21 **Completed**: 2026-07-03 11:22 **Duration**: 1 minute

**Notes**:

* No production change was required.
* `OPENAI_API_KEY` and `OPENAI_BASE_URL` are read from server environment in the bridge and passed to the broker child process through environment only.
* Child argv remains `["run", "voice"]`, so provider key/base values do not enter command-line arguments.
* Broker base URL policy allows default OpenAI and loopback-compatible overrides only; arbitrary remote hosts, userinfo, query strings, and fragments remain rejected.
* Browser code does not persist provider keys or provider base URLs; portal localStorage usage is limited to `ai-os-hermes-intelligence-design`.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T010 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T010 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "OPENAI_API_KEY|OPENAI_BASE_URL|resolveVoiceBaseUrl|Authorization|Bearer|spawn\\(|args|localStorage|sessionStorage" scripts/lib/voice-launch-bridge.ts scripts/lib/voice-broker.ts src/hooks/use-hermes-intelligence-voice.ts src/components/hermes/intelligence/intelligence-portal.tsx`
  * Result: PASS - provider config and browser storage boundaries inspected.
  * Evidence: Matches show provider config only in bridge/broker env handling, provider auth only inside broker provider calls, browser Realtime auth uses short-lived session value, and portal localStorage stores only design preference.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts scripts/lib/__tests__/voice-broker.test.ts`
  * Result: PASS - bridge and broker provider-policy suites passed.
  * Evidence: Vitest reported 2 test files passed and 18 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: N/A - audit confirmed existing trust-boundary and error-boundary coverage; no production fix required.

***

### Task T011 - Audit hook start flow and bridge error mapping

**Started**: 2026-07-03 11:22 **Completed**: 2026-07-03 11:23 **Duration**: 1 minute

**Notes**:

* No production change was required.
* The hook sends `POST /__start_voice` before broker health fallback, session minting, microphone access, or Realtime connection.
* The launch body remains `{}` with no provider key/base fields, while `/api/session` receives only `voice` and `mode`.
* Bridge error codes map distinctly to user-facing voice failure codes for bad token, missing token, missing key, provider failure, timeout, spawn failure, and broker unavailable.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T011 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T011 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "VOICE_START_URL|requestStartBridge|requestHealth|requestSession|failureFor|voiceError|body: JSON\\.stringify|navigator\\.mediaDevices|getUserMedia|cleanupRuntime|inFlightRef" src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - hook ordering, payload shape, failure mapping, duplicate-action gate, and cleanup owners located.
  * Evidence: Matches show `requestStartBridge` body `{}`, session body `{ voice, mode: "companion" }`, start ordering before `getUserMedia`, and `failureFor` code mapping.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - expanded hook start-flow tests pass.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: N/A - audit confirmed existing duplicate-action prevention, contract alignment, and error mapping; no production fix required.

***

### Task T012 - Audit hook runtime failure handling and cleanup

**Started**: 2026-07-03 11:23 **Completed**: 2026-07-03 11:24 **Duration**: 1 minute

**Notes**:

* No production change was required.
* Runtime cleanup aborts the active controller, closes the data channel and peer connection, stops media tracks, clears timers, and resets refs.
* Start failure handling covers disabled admin, missing token, offline browser, unavailable mic/WebRTC, missing key, provider/session failures, provider timeout, mic denial, and broker unavailable.
* Realtime failure after media acquisition is now covered by test evidence and cleans the acquired stream, data channel, and peer.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T012 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T012 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "cleanupRuntime|abortRef|dataChannelRef|peerRef|streamRef|clearTimers|mic-denied|mic-unavailable|provider-failed|offline|broker-unavailable" src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - runtime cleanup and failure-code ownership confirmed.
  * Evidence: Matches show scoped cleanup of abort, channel, peer, stream, timers, and explicit failure codes.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - expanded cleanup and failure tests pass.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed, including Realtime failure cleanup and mic/offline cases.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.
* BQC Fixes: N/A - audit confirmed existing resource cleanup and failure path completeness; no production fix required.

***

### Task T013 - Audit Intelligence portal recovery and active-control states

**Started**: 2026-07-03 11:24 **Completed**: 2026-07-03 11:25 **Duration**: 1 minute

**Notes**:

* No production change was required.
* Portal recovery uses product-facing copy for demo mode, offline, admin disabled, missing token, and voice-controller failures.
* Start voice is disabled for demo mode, admin-disabled state, busy start, and active voice loop phases.
* Stop remains available as the active-loop escape control.
* Tests now assert missing-token and bad-token recovery copy plus absence of raw stack/Bearer diagnostic strings.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T013 audit evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T013 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "recoveryFor|Start voice|Stop|voiceActive|voice\\.error|demoMode|token-failure|Ask through Intelligence|stack|Bearer" src/components/hermes/intelligence/intelligence-portal.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - portal recovery/control ownership and new assertions located.
  * Evidence: Matches show recovery decision points, Start/Stop controls, active-loop gating, and test assertions for missing token, bad token, and diagnostic absence.
* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - expanded portal tests pass.
  * Evidence: Vitest reported 3 test files passed and 23 tests passed.
* UI product-surface check: PASS - component test evidence confirms product-facing recovery copy for demo, missing-token, and bad-token states and no raw stack/Bearer text in the rendered portal.
* UI craft check: PASS - component test evidence confirms accessible button/form names and active-loop control gating.
* BQC Fixes: N/A - audit confirmed existing accessibility/product-surface boundaries; no production fix required.

***

### Task T014 - Finalize parity audit, fix summary, test evidence, and docs handoff notes

**Started**: 2026-07-03 11:25 **Completed**: 2026-07-03 11:26 **Duration**: 1 minute

**Notes**:

* Added `Implementation Fix Summary` recording that no production source changes were required.
* Added `Test Evidence Summary` for focused evidence gathered before formal testing tasks.
* Confirmed Session 17 docs handoff notes are present in `Session 17 Documentation Queue`.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Added fix summary and test evidence summary.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T014 complete after evidence was recorded.

**Verification**:

* Command/check: Manual review of implementation notes summary sections.
  * Result: PASS - parity audit, docs queue, fix summary, and test evidence summary are present and consistent with T001 through T013.
  * Evidence: File contains `Voice Parity Audit`, `Session 17 Documentation Queue`, `Implementation Fix Summary`, and `Test Evidence Summary`.
* Command/check: Manual production-source diff review.
  * Result: PASS - no production source files required changes for T008 through T013.
  * Evidence: Production owner audits found existing code satisfied expanded tests; modified runtime files are test files and session artifacts.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T015 - Run focused bridge and broker tests

**Started**: 2026-07-03 11:26 **Completed**: 2026-07-03 11:27 **Duration**: 1 minute

**Notes**:

* Ran the focused launch bridge and broker suites for launch, respawn, provider policy, token, timeout, and safe-error behavior.
* All selected tests passed.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T015 test evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T015 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts scripts/lib/__tests__/voice-broker.test.ts`
  * Result: PASS - focused bridge and broker tests passed.
  * Evidence: Vitest reported 2 test files passed and 18 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T016 - Run focused hook and Intelligence portal tests

**Started**: 2026-07-03 11:27 **Completed**: 2026-07-03 11:28 **Duration**: 1 minute

**Notes**:

* Ran the focused hook and Intelligence portal suites for start ordering, payload shape, error mapping, cleanup, recovery copy, and active controls.
* All selected tests passed.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T016 test evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T016 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused hook and Intelligence portal tests passed.
  * Evidence: Vitest reported 2 test files passed and 12 tests passed.
* UI product-surface check: PASS - portal tests verify recovery copy and control states without raw diagnostics.
* UI craft check: PASS - portal tests verify accessible button/form names and active-loop control behavior.

***

### Task T017 - Run local control-plane and sanitizer-adjacent regression tests

**Started**: 2026-07-03 11:28 **Completed**: 2026-07-03 11:29 **Duration**: 1 minute

**Notes**:

* Ran local control-plane guard and sanitizer-adjacent regression tests for route gates and safe browser-visible errors.
* All selected tests passed.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T017 test evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T017 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/local-control-plane-guard.test.ts scripts/lib/__tests__/sanitize.test.ts`
  * Result: PASS - control-plane guard and sanitizer-adjacent tests passed.
  * Evidence: Vitest reported 2 test files passed and 43 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T018 - Run TypeScript checks for app and script surfaces

**Started**: 2026-07-03 11:29 **Completed**: 2026-07-03 11:30 **Duration**: 1 minute

**Notes**:

* Ran app TypeScript check.
* Ran scripts TypeScript check.
* Both checks passed.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T018 typecheck evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T018 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript gate passed.
  * Evidence: Command ran `tsc --noEmit` and exited 0.
* Command/check: `bun run typecheck:scripts`
  * Result: PASS - scripts TypeScript gate passed.
  * Evidence: Command ran `tsc --noEmit -p tsconfig.scripts.json` and exited 0.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T019 - Run lint and diff whitespace checks

**Started**: 2026-07-03 11:30 **Completed**: 2026-07-03 11:31 **Duration**: 1 minute

**Notes**:

* `git diff --check` passed.
* `bun run lint` initially reported a Prettier line-wrap issue in the new hook test.
* Wrapped the long `json(...)` call in `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`.
* Reran lint, whitespace check, and the focused hook/portal tests successfully.

**Files Changed**:

* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - Applied Prettier-compatible line wrapping in a new test case.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T019 lint and whitespace evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T019 complete after evidence was recorded.

**Verification**:

* Command/check: `bun run lint`
  * Result: PASS - lint passed after formatting fix.
  * Evidence: Final lint run exited 0.
* Command/check: `git diff --check`
  * Result: PASS - tracked diff whitespace check passed.
  * Evidence: Command produced no output and exited 0.
* Command/check: `bunx vitest run src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused hook/portal tests still passed after formatting edit.
  * Evidence: Vitest reported 2 test files passed and 12 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***

### Task T020 - Validate ASCII/LF and scan touched session/voice files for private data

**Started**: 2026-07-03 11:31 **Completed**: 2026-07-03 11:32 **Duration**: 1 minute

**Notes**:

* Initial targeted privacy scan found one generated session-spec raw local upstream path.
* Redacted that path to `<upstream-checkout>/src/components/intelligence-portal.tsx`.
* Reran ASCII, CRLF, and targeted secret/path scans successfully.
* Reran `git diff --check` successfully after the spec redaction.

**Files Changed**:

* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/spec.md` - Redacted raw local upstream checkout path.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md` - Recorded T020 scan evidence.
* `.spec_system/specs/phase40-session16-voice-parity-and-broker-respawn/tasks.md` - Marked T020 complete and completed the checklist after evidence was recorded.

**Verification**:

* Command/check: `rg --pcre2 -n "[^\\x00-\\x7F]" <touched-session-and-voice-files>`
  * Result: PASS - no non-ASCII matches.
  * Evidence: Rerun reported no matches.
* Command/check: `rg -n $'\\r' <touched-session-and-voice-files>`
  * Result: PASS - no CRLF/carriage-return matches.
  * Evidence: Rerun reported no matches.
* Command/check: `rg -n "<secret-shaped-or-local-user-pattern>" <touched-session-and-voice-files>`
  * Result: PASS - no targeted secret-shaped strings, raw local username/path strings, bearer tokens, or long provider-key examples matched after redaction.
  * Evidence: Rerun reported `secret_matches=1`, meaning ripgrep found no matches.
* Command/check: `git diff --check`
  * Result: PASS - tracked diff whitespace check passed after the spec redaction.
  * Evidence: Command produced no output and exited 0.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no production UI changed.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session16-voice-parity-and-broker-respawn/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.