> 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/specs/phase41-session06-intelligence-action-access/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase41-session06-intelligence-action-access` **Started**: 2026-07-03 23:45 **Last Updated**: 2026-07-03 23:59

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 16 / 16   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

***

### Task T015 - Run Focused Automated Checks

**Started**: 2026-07-03 23:57 **Completed**: 2026-07-03 23:58 **Duration**: 1 minute

**Notes**:

* Ran the required focused hook and portal Vitest command.
* Ran the changed route-level Playwright smoke with the repo-supported existing-server mode because port `5189` was already occupied.
* The first smoke run found an over-broad page-level `admin mode` absence assertion; scoped the assertion to the Intelligence dialog and reran successfully.

**Files Changed**:

* `tests/e2e/hermes-intelligence.spec.ts` - scoped old-copy absence assertion to the Intelligence dialog.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded final check evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T015 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused hook and portal suites passed.
  * Evidence: 2 test files passed; 18 tests passed.
* Command/check: `PLAYWRIGHT_REUSE_EXISTING_SERVER=true bunx playwright test tests/e2e/hermes-intelligence.spec.ts --project=chromium`
  * Result: PASS - changed route-level smoke passed.
  * Evidence: 2 Playwright tests passed.
* UI product-surface check: PASS - e2e verifies the Intelligence dialog shows local-readiness recovery and no old admin-mode copy.
* UI craft check: PASS - browser smoke confirms dialog opens and controls remain usable/disabled as expected.

**BQC Fixes**:

* Product surface discipline: e2e absence assertion is scoped to the affected Intelligence dialog instead of unrelated Hermes page content.

***

### Task T016 - Validate ASCII, LF, And Session Notes

**Started**: 2026-07-03 23:58 **Completed**: 2026-07-03 23:59 **Duration**: 1 minute

**Notes**:

* Formatted touched TypeScript, TSX, and e2e files with Prettier.
* Re-ran focused hook and portal tests after formatting.
* Verified changed source, test, spec, task, and implementation-note files are ASCII-only with LF endings.
* Updated the task checklist and completion checklist after evidence was recorded.

**Files Changed**:

* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - added final hygiene evidence and final progress.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T016 and completion checklist complete.

**Verification**:

* Command/check: `bunx prettier --write src/hooks/use-hermes-intelligence-voice.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/intelligence-types.ts src/components/hermes/intelligence/intelligence-portal.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - touched source/test files formatted.
  * Evidence: Prettier completed; only hook and hook test needed formatting changes.
* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused tests still pass after formatting.
  * Evidence: 2 test files passed; 18 tests passed.
* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors in the diff.
  * Evidence: Command exited 0 with no output.
* Command/check: `bun run typecheck`
  * Result: PASS - app TypeScript project typechecked after the failure-code union change.
  * Evidence: `tsc --noEmit` exited 0.
* Command/check: `LC_ALL=C rg -n "[^ -~\t]" [session source/test/spec/task/note files]`
  * Result: PASS - no non-ASCII matches.
  * Evidence: `rg` exited 1 with no output, which means no matches were found.
* Command/check: `rg -n $'\r' [session source/test/spec/task/note files]`
  * Result: PASS - no CRLF matches.
  * Evidence: `rg` exited 1 with no output, which means no carriage returns were found.
* UI product-surface check: N/A - final hygiene gate only.
* UI craft check: N/A - final hygiene gate only.

**BQC Fixes**:

* N/A - final hygiene gate only.

***

### Task T011 - Update Route-Level Intelligence Smoke Expectation

**Started**: 2026-07-03 23:54 **Completed**: 2026-07-03 23:55 **Duration**: 1 minute

**Notes**:

* Updated the direct Intelligence smoke test name and assertions to expect local-readiness recovery copy.
* Added an e2e absence assertion for old `admin mode` copy.

**Files Changed**:

* `tests/e2e/hermes-intelligence.spec.ts` - replaced legacy manual admin recovery expectation with local-readiness expectation.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T011 complete.

**Verification**:

* Command/check: `rg -n "admin-disabled|Hermes admin mode is disabled|Local Hermes actions are not ready|admin mode" tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - old admin-disabled assertion is gone and new local-readiness assertions are present.
  * Evidence: Output shows `Local Hermes actions are not ready` and `admin mode` absence assertion only.
* Command/check: `sed -n '52,82p' tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - smoke now names local readiness recovery and keeps Start Voice disabled in blocked mode.
  * Evidence: The direct route test asserts heading, local readiness recovery, absence of admin-mode copy, and disabled Start Voice.
* UI product-surface check: PASS - route smoke now guards against the old manual admin setup copy.
* UI craft check: N/A - expectation-only e2e change.

**BQC Fixes**:

* Product surface discipline: route smoke now catches regression to manual admin setup copy.

***

### Task T012 - Confirm No Private Data Or Secret Material

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

**Notes**:

* Confirmed changed files do not include generated private data such as `src/data/live-data.json`.
* Scanned Intelligence hook, portal, focused tests, and e2e smoke for private paths, usernames, bearer literals, provider keys, raw provider payload language, and auth JSON.
* Existing runtime provider-session Authorization header remains code behavior, not a committed token value; portal tests assert `Bearer` is not rendered.

**Files Changed**:

* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded privacy scan evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T012 complete.

**Verification**:

* Command/check: `git diff --name-only`
  * Result: PASS - changed source/test/spec files do not include generated private runtime data.
  * Evidence: Diff contains spec state/session files, Intelligence source/tests, and e2e smoke only; no `src/data/live-data.json`.
* Command/check: `rg -n "(/home/[A-Za-z0-9._-]+|Bearer|Authorization|OPENAI_API_KEY|sk-[A-Za-z0-9]|xox[baprs]-|eyJ[A-Za-z0-9_-]|provider payload|raw provider|auth JSON|transcript file|local username)" src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx tests/e2e/hermes-intelligence.spec.ts src/hooks/use-hermes-intelligence-voice.ts src/components/hermes/intelligence/intelligence-portal.tsx src/components/hermes/intelligence/intelligence-types.ts`
  * Result: PASS - no committed secret value, private path, local username, auth JSON, or raw provider payload was introduced.
  * Evidence: Matches are the existing runtime `Authorization: Bearer ${session.value}` header, existing safe `OPENAI_API_KEY` setup copy, and tests asserting `Bearer` is absent from rendered UI.
* UI product-surface check: PASS - recovery text stays product-facing and does not expose tokens, keys, paths, command output, or raw payloads.
* UI craft check: N/A - privacy scan only.

**BQC Fixes**:

* Error information boundaries: fixture and recovery text scan confirms no secret-shaped or private local data exposure was added.

***

### Task T013 - Add Hook Regression Matrix

**Started**: 2026-07-03 23:55 **Completed**: 2026-07-03 23:56 **Duration**: 1 minute

**Notes**:

* Hook tests now cover local voice start success, same-run token headers, launch rejected token, missing token config, missing provider key, broker unavailable, provider timeout/failure, microphone denial, offline state, cleanup, and duplicate prevention.
* Added new regressions for demo/privacy and local-readiness gates, duplicate launch while in flight, Ask Hermes readiness preflight, Ask Hermes rollback, and active unmount cleanup.

**Files Changed**:

* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - expanded hook regression matrix.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T013 complete.

**Verification**:

* Command/check: `rg -n "starts broker|missing_key|invalid_token|broker-unavailable|provider-failed|mic-denied|offline|duplicate|cleans active voice resources|demo-gated|local-readiness|missing-token" src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - required hook regression scenarios are present.
  * Evidence: Output includes local success, missing/rejected token, provider-key, broker, provider, mic, offline, cleanup, and duplicate cases.
* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - expanded hook suite passes.
  * Evidence: 1 test file passed; 11 tests passed.
* UI product-surface check: N/A - hook test task only.
* UI craft check: N/A - no rendered UI changed for this task.

**BQC Fixes**:

* Duplicate action prevention, resource cleanup, failure path completeness, and contract alignment are now covered by the hook regression suite.

***

### Task T014 - Add Portal Regression Matrix

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

**Notes**:

* Portal tests now assert local-ready controls, typed transcript rendering, demo/privacy gating, missing-token recovery, voice dependency recovery, disabled controls, and absence of manual admin setup copy.
* Added a local all-access disabled fixture to verify real blocker copy without legacy admin language.

**Files Changed**:

* `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` - expanded portal regression coverage.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T014 complete.

**Verification**:

* Command/check: `rg -n "Local live|Hermes answered|demo or privacy|Local token is missing|local voice broker|Start voice|Ask through Intelligence|admin mode|adminStatusLocalAccessDisabled" src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - required portal regression assertions are present.
  * Evidence: Output includes local-ready controls, transcript, demo/privacy, token, broker, disabled controls, and admin-copy absence assertions.
* Command/check: `bun run test src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - portal suite passes.
  * Evidence: 1 test file passed; 7 tests passed.
* UI product-surface check: PASS - portal tests assert product-facing local-readiness copy and absence of manual admin setup copy.
* UI craft check: PASS - tests preserve existing interaction flow and visualizer mode behavior.

**BQC Fixes**:

* Product surface discipline and failure path completeness are now pinned by portal tests.

### Checkpoint 3 - Before Final Verification Tasks

* Session tests/build commands: hook suite passed with 11 tests; portal suite passed with 7 tests.
* Scope re-read: only focused automated checks and final file hygiene remain; no database, generated data, or docs update is in scope.
* Next task: T015 focused automated checks for hook, portal, and changed e2e smoke.

***

### Task T007 - Start Voice Gating And Duplicate Prevention

**Started**: 2026-07-03 23:50 **Completed**: 2026-07-03 23:52 **Duration**: 2 minutes

**Notes**:

* Start Voice now fails demo/privacy and local-readiness states with named recovery codes.
* Start Voice already blocks active voice resources; added regression coverage for duplicate calls while broker launch is still in flight.
* Readiness/token loss cleans up runtime resources and resets active busy state.

**Files Changed**:

* `src/hooks/use-hermes-intelligence-voice.ts` - updated Start Voice preflight and readiness-change cleanup.
* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - added in-flight duplicate Start Voice regression.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T007 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - hook tests cover Start Voice success, cleanup, named failures, and duplicate launch prevention.
  * Evidence: 1 test file passed; 9 tests passed.
* Command/check: Targeted inspection of `start()` in `src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - duplicate, resource-present, demo/privacy, local-readiness, missing-token, offline, media, broker, provider, and timeout branches are explicit.
  * Evidence: `inFlightRef`, resource refs, `voiceError("demo-gated")`, `voiceError("local-readiness")`, token/offline checks, and health recovery mapping are all present.
* UI product-surface check: N/A - hook behavior only; portal UI checks are covered by T005/T014.
* UI craft check: N/A - no rendered UI changed for this task.

**BQC Fixes**:

* Duplicate action prevention: in-flight Start Voice calls now have explicit regression coverage.
* State freshness on re-entry: readiness/token loss performs runtime cleanup and resets busy/level state.

***

### Task T008 - Typed Ask Hermes Gating And Error Rollback

**Started**: 2026-07-03 23:52 **Completed**: 2026-07-03 23:53 **Duration**: 1 minute

**Notes**:

* Added typed Ask Hermes preflight gates for demo/privacy, local readiness, missing token, and offline state.
* Preserved duplicate Ask Hermes prevention through `askInFlightRef`.
* Rolled back the staged operator transcript row when the chat bridge returns `null` or throws before a stream starts.

**Files Changed**:

* `src/hooks/use-hermes-intelligence-voice.ts` - added Ask Hermes preflight and scoped rollback logic.
* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - added readiness-gate and rollback regressions.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T008 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - typed Ask Hermes success, duplicate prevention, readiness preflight, and rollback tests pass.
  * Evidence: 1 test file passed; 10 tests passed.
* Command/check: Targeted inspection of `askHermes()` in `src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - empty prompts, duplicate in-flight calls, demo/privacy, local readiness, missing token, offline, null bridge result, aborted streams, failed streams, and thrown errors have explicit outcomes.
  * Evidence: `askInFlightRef`, `voiceError("demo-gated")`, `voiceError("local-readiness")`, `voiceError("missing-token")`, `voiceError("offline")`, and transcript rollback are present.
* UI product-surface check: N/A - hook behavior only; portal surface tests follow in T014.
* UI craft check: N/A - no rendered UI changed for this task.

**BQC Fixes**:

* Duplicate action prevention: typed Ask Hermes duplicate calls remain guarded while a request is in flight.
* Failure path completeness: local readiness failures and bridge non-start errors now leave visible error state instead of stale thinking state.

***

### Task T009 - Remove Manual Admin Setup Copy From Portal

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

**Notes**:

* Replaced portal status/recovery language with product-facing local live, demo/privacy, token, offline, and local-readiness copy.
* Updated Start Voice and Ask Hermes disabled states to use the portal readiness projection.
* Updated route smoke expectation to assert old `admin mode` copy is absent.

**Files Changed**:

* `src/components/hermes/intelligence/intelligence-portal.tsx` - removed normal local manual admin setup recovery language.
* `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` - asserted absence of manual admin copy in portal scenarios.
* `tests/e2e/hermes-intelligence.spec.ts` - updated route smoke recovery expectation.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T009 complete.

**Verification**:

* Command/check: `rg -n "admin mode|admin-disabled|Enable local Hermes admin|Live gated|Demo gated|Hermes admin" src/components/hermes/intelligence/intelligence-portal.tsx tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - no legacy portal copy remains; the only match is the e2e absence assertion.
  * Evidence: Output only shows `expect(page.getByText(/admin mode/i)).toHaveCount(0)`.
* Command/check: `bun run test src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - portal tests pass with new recovery copy.
  * Evidence: 1 test file passed; 7 tests passed.
* UI product-surface check: PASS - normal portal recovery now names local live/dependency states and excludes debug/runtime/scaffold/admin setup language.
* UI craft check: PASS - existing visual hierarchy and controls were preserved.

**BQC Fixes**:

* Product surface discipline: normal local Intelligence no longer tells operators to enable manual admin mode.

***

### Task T010 - Preserve Voice Resource Cleanup

**Started**: 2026-07-03 23:53 **Completed**: 2026-07-03 23:54 **Duration**: 1 minute

**Notes**:

* Preserved cleanup of abort controller, data channel, peer connection, media tracks, and timers through the shared runtime cleanup helper.
* Added active-unmount regression coverage alongside existing stop and provider-failure cleanup tests.
* Readiness/token loss also routes through cleanup to avoid stale active resources.

**Files Changed**:

* `src/hooks/use-hermes-intelligence-voice.ts` - preserved cleanup helper and added readiness-change cleanup.
* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - added active unmount cleanup regression.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T010 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - cleanup, failure, and duplicate tests pass.
  * Evidence: 1 test file passed; 11 tests passed.
* Command/check: Targeted inspection of `cleanupRuntime()` and hook lifecycle effects in `src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - aborts active request, closes data channel and peer, stops media tracks, clears timers, runs on stop/reset/unmount/fail/readiness loss.
  * Evidence: `cleanupRuntime()` is called from `fail()`, `stop()`, `reset()`, unmount effect, and readiness/token-loss effect.
* UI product-surface check: N/A - hook lifecycle behavior only.
* UI craft check: N/A - no rendered UI changed for this task.

**BQC Fixes**:

* Resource cleanup: active voice resources now have explicit stop, provider-failure, and unmount regression coverage.

### Checkpoint 2 - After Runtime Implementation Tasks

* Session tests/build commands: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` passed with 1 file and 11 tests.
* Scope re-read: remaining work is route smoke expectation, private-data/copy scan, expanded hook and portal regressions, focused checks, and final file hygiene.
* Next task: T011 route-level Intelligence smoke expectation update.

***

## Task Log

### 2026-07-03 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed by `.spec_system/scripts/check-prereqs.sh --json --env`
* [x] Tools available: `jq-1.7`, `git version 2.43.0`
* [x] Directory structure ready for `phase41-session06-intelligence-action-access`
* [x] Database not required for this session

***

### Task T001 - Verify Prior Artifacts And Current Baselines

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

**Notes**:

* Confirmed Session 03 moved local Hermes readiness to `live-local` and `writeReady`-derived `canUseAdmin`.
* Confirmed Session 05 completed automatic voice token bootstrap while preserving same-run request-token enforcement.
* Read current Intelligence hook, portal, type contract, focused tests, and e2e smoke before editing.

**Files Changed**:

* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded baseline evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T001 complete.

**Verification**:

* Command/check: `rg -n "writeReady|canUseAdmin|live-local|same-run token|voice|bootstrap|token" .spec_system/specs/phase41-session03-hermes-route-modes-and-hooks .spec_system/specs/phase41-session05-voice-token-bootstrap`
  * Result: PASS - prior-session artifacts expose the required readiness and token behavior.
  * Evidence: Session 03 notes show `useHermesAdmin()` now gates write capability on parsed `writeReady`; Session 05 notes show token bootstrap and request enforcement completed.
* Command/check: `sed -n '1,620p' src/hooks/use-hermes-intelligence-voice.ts` and `sed -n '1,540p' src/components/hermes/intelligence/intelligence-portal.tsx`
  * Result: PASS - current hook and portal baselines inspected.
  * Evidence: Hook owns voice cleanup, duplicate guards, token/broker/provider mapping, and Ask Hermes transcript flow; portal consumes `admin.canUseAdmin` and renders typed/voice controls.
* UI product-surface check: N/A - inspection only; no product UI changed.
* UI craft check: N/A - inspection only; no product UI changed.

**BQC Fixes**:

* N/A - inspection task only.

***

### Task T003 - Rename Intelligence Voice Failure Codes

**Started**: 2026-07-03 23:46 **Completed**: 2026-07-03 23:49 **Duration**: 3 minutes

**Notes**:

* Replaced the Intelligence-facing `admin-disabled` failure code with explicit `demo-gated` and `local-readiness` codes.
* Kept existing named token, broker, provider, microphone, timeout, offline, and aborted-stream codes intact.

**Files Changed**:

* `src/components/hermes/intelligence/intelligence-types.ts` - updated `IntelligenceVoiceFailureCode`.
* `src/hooks/use-hermes-intelligence-voice.ts` - updated consumer cases to use the new codes.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T003 complete.

**Verification**:

* Command/check: `rg -n "admin-disabled|demo-gated|local-readiness" src/components/hermes/intelligence/intelligence-types.ts src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - old type/hook code is absent; new explicit codes are present.
  * Evidence: `demo-gated` and `local-readiness` match in type and hook; `admin-disabled` has no match in those files.
* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - hook suite still passes after type/consumer rename.
  * Evidence: 1 test file passed; 6 tests passed.
* UI product-surface check: N/A - type/hook contract only; portal UI copy task follows.
* UI craft check: N/A - no rendered UI changed for this task.

**BQC Fixes**:

* Contract alignment: failure-code union and hook consumers now use the same explicit readiness codes.

***

### Task T004 - Refactor Voice Error Construction And Recovery Mapping

**Started**: 2026-07-03 23:46 **Completed**: 2026-07-03 23:49 **Duration**: 3 minutes

**Notes**:

* Added product-specific `demo-gated` and `local-readiness` error copy.
* Added health recovery mapping for token, provider-key, broker, provider, timeout, and spawn failures.
* Added typed Ask Hermes preflight checks for demo/privacy mode, local readiness, missing token, and offline state before adding transcript rows or crossing the bridge.

**Files Changed**:

* `src/hooks/use-hermes-intelligence-voice.ts` - updated `voiceError()`, health recovery mapping, Start Voice gating, Ask Hermes gating, and readiness-change cleanup.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T004 complete.

**Verification**:

* Command/check: `rg -n "failureFromRecovery|demo-gated|local-readiness|missing-token|provider-failed|stream-aborted" src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - explicit recovery codes and mapper are present in the hook.
  * Evidence: Output shows mapper, new codes, and existing token/provider/aborted cases.
* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`
  * Result: PASS - existing hook behavior remains green after recovery refactor.
  * Evidence: 1 test file passed; 6 tests passed.
* UI product-surface check: N/A - hook copy feeds portal recovery but no rendered surface was inspected for this task.
* UI craft check: N/A - hook behavior only.

**BQC Fixes**:

* Failure path completeness: typed Ask Hermes now has visible preflight failures for readiness, token, demo/privacy, and offline blockers.
* State freshness on re-entry: readiness/token loss cleans up active runtime resources and resets busy/level state.

***

### Task T005 - Refactor Portal Readiness And Recovery Helpers

**Started**: 2026-07-03 23:49 **Completed**: 2026-07-03 23:50 **Duration**: 1 minute

**Notes**:

* Added a portal-local readiness projection over `admin.canUseAdmin`, token presence, demo/privacy mode, offline state, and status data.
* Disabled Start Voice and typed Ask Hermes from the projection, not manual admin setup state.
* Updated status and recovery copy to product-facing live/local/dependency language.

**Files Changed**:

* `src/components/hermes/intelligence/intelligence-portal.tsx` - added readiness helper and wired controls/recovery panel/status chip to it.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T005 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused hook and portal suites passed.
  * Evidence: 2 test files passed; 15 tests passed.
* Command/check: `rg -n "Hermes admin mode is disabled|Enable local Hermes admin|admin-disabled" src/components/hermes/intelligence src/hooks/use-hermes-intelligence-voice.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - legacy manual admin setup copy/code is absent from scoped Intelligence files.
  * Evidence: `rg` exited 1 with no matches.
* UI product-surface check: PASS - portal copy uses demo/privacy, offline, token, local readiness, and voice dependency recovery language; no debug/runtime/scaffold copy added.
* UI craft check: PASS - existing portal layout and controls were preserved while control disabled states were narrowed to the readiness projection.

**BQC Fixes**:

* Product surface discipline: normal local Intelligence recovery no longer surfaces manual admin setup language.
* Failure path completeness: portal now names demo/privacy, offline, token, status, production-preview, and local-readiness blockers.

***

### Task T006 - Update Intelligence Test Fixtures

**Started**: 2026-07-03 23:49 **Completed**: 2026-07-03 23:50 **Duration**: 1 minute

**Notes**:

* Added hook fixture coverage for demo/privacy and local-readiness gates before broker or media access.
* Added portal fixture coverage for local ready mode, local all-access disabled mode, token recovery, and voice broker recovery.
* Updated the route smoke fixture expectation away from manual admin setup copy.

**Files Changed**:

* `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` - added readiness gate tests for Start Voice and typed Ask Hermes.
* `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` - added local all-access disabled fixture and new portal recovery expectations.
* `tests/e2e/hermes-intelligence.spec.ts` - updated recovery smoke expectation to local readiness copy.
* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T006 complete.

**Verification**:

* Command/check: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - updated hook and portal fixtures compile and pass.
  * Evidence: 2 test files passed; 15 tests passed.
* Command/check: `rg -n "demo-gated|local-readiness|adminStatusLocalAccessDisabled|Local Hermes actions are not ready|Local live" src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - fixtures now model the new local readiness and recovery states.
  * Evidence: Matches found in hook tests, portal tests, and route smoke.
* UI product-surface check: PASS - tests assert absence of `admin mode` copy on the normal Intelligence portal surface.
* UI craft check: PASS - no layout or visual-system fixture changes were required.

**BQC Fixes**:

* Contract alignment: tests now pin the new readiness codes and portal copy.

### Checkpoint 1 - After Foundation Tasks

* Session tests/build commands: `bun run test src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` passed with 2 files and 15 tests.
* Scope re-read: objectives still require local all-access typed Ask Hermes and Start Voice readiness, named blocker recovery, cleanup, duplicate prevention, and focused hook/portal tests.
* Next task: T007 Start Voice gating and duplicate-trigger verification.

***

### Task T002 - Identify Legacy Intelligence Copy And Assertions

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

**Notes**:

* Found `admin-disabled` in the Intelligence voice failure union and start gating.
* Found portal recovery copy that still tells local users to enable Hermes admin mode.
* Found e2e smoke coverage expecting the old admin-disabled recovery copy.

**Files Changed**:

* `.spec_system/specs/phase41-session06-intelligence-action-access/implementation-notes.md` - recorded legacy-copy scan.
* `.spec_system/specs/phase41-session06-intelligence-action-access/tasks.md` - marked T002 complete.

**Verification**:

* Command/check: `rg -n "admin-disabled|admin disabled|admin setup|local admin|enable local Hermes admin|token|broker|provider|demo|privacy|offline" src/hooks/use-hermes-intelligence-voice.ts src/components/hermes/intelligence/intelligence-portal.tsx src/components/hermes/intelligence/intelligence-types.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - all legacy Intelligence readiness language and relevant recovery tests were identified.
  * Evidence: Matches found in `intelligence-types.ts`, `use-hermes-intelligence-voice.ts`, `intelligence-portal.tsx`, the hook/portal tests, and the route smoke.
* Command/check: `sed -n '1,460p' src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`, `sed -n '1,380p' src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`, and `sed -n '1,120p' tests/e2e/hermes-intelligence.spec.ts`
  * Result: PASS - test assumptions reviewed before implementation.
  * Evidence: Existing tests cover token/broker/provider/mic/offline paths, but route smoke still expects `Hermes admin mode is disabled`.
* UI product-surface check: N/A - inspection only; no product UI changed.
* UI craft check: N/A - inspection only; no product UI changed.

**BQC Fixes**:

* N/A - inspection task only.

***


---

# 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/specs/phase41-session06-intelligence-action-access/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.