> 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-session01-baseline-and-port-invariants/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase40-session01-baseline-and-port-invariants` **Started**: 2026-07-02 20:12 **Last Updated**: 2026-07-02 21:03

***

## Session Progress

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

***

### Task T020 - Validate ASCII, LF, whitespace, and final worktree status for session artifacts

**Started**: 2026-07-02 21:01 **Completed**: 2026-07-02 21:03 **Duration**: 2 minutes

**Notes**:

* Session artifact ASCII check passed with no non-ASCII matches.
* Session artifact LF/no-CR check passed with no carriage-return matches.
* Tracked diff whitespace check passed.
* Untracked session artifact whitespace check passed.
* Final worktree status remains limited to the pre-existing `.spec_system/state.json` tracked modification and untracked active session artifact directory.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T020 final artifact check outcomes.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` - Updated final test status and implementation status.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T020 complete and completed the checklist after evidence was recorded.

**Verification**:

* Command/check: `rg --pcre2 -n "[^\\x00-\\x7F]" .spec_system/specs/phase40-session01-baseline-and-port-invariants`
  * Result: PASS - no non-ASCII characters in session artifacts.
  * Evidence: Command produced no output.
* Command/check: `rg -n $'\\r' .spec_system/specs/phase40-session01-baseline-and-port-invariants`
  * Result: PASS - no CRLF/carriage-return matches in session artifacts.
  * Evidence: Command produced no output.
* Command/check: `git diff --check`
  * Result: PASS - tracked diff whitespace check passed.
  * Evidence: Command produced no output and exit code 0.
* Command/check: `git diff --no-index --check /dev/null <each session artifact>`
  * Result: PASS - untracked artifact whitespace check passed.
  * Evidence: Wrapper output reported `untracked_artifact_whitespace=pass`.
* Command/check: `git status --short`
  * Result: PASS - final worktree status captured.
  * Evidence: Output listed `M .spec_system/state.json` and `?? .spec_system/specs/phase40-session01-baseline-and-port-invariants/`.
* UI product-surface check: PASS - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T019 - Run TypeScript baseline gates

**Started**: 2026-07-02 20:59 **Completed**: 2026-07-02 21:00 **Duration**: 1 minute

**Notes**:

* Ran the app TypeScript gate.
* Ran the scripts TypeScript gate.
* Both gates passed.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T019 typecheck outcomes.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` - Updated T019 test status.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T019 complete after evidence was recorded.

**Verification**:

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

***

### Task T018 - Run focused voice, control-plane, sanitizer, scanner, and Intelligence baseline tests

**Started**: 2026-07-02 20:57 **Completed**: 2026-07-02 20:58 **Duration**: 1 minute

**Notes**:

* Ran the focused voice/control-plane/sanitizer/scanner/Intelligence test slot.
* All selected test files passed.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T018 test outcome.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` - Updated T018 test status.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T018 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 scripts/lib/__tests__/local-control-plane-guard.test.ts scripts/lib/__tests__/sanitize.test.ts scripts/lib/__tests__/hermes-scanner.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`
  * Result: PASS - focused voice/control-plane/sanitizer/scanner/Intelligence tests passed.
  * Evidence: Vitest reported 7 test files passed and 63 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T017 - Run focused Hermes bridge, admin hook, chat, and read-only page baseline tests

**Started**: 2026-07-02 20:54 **Completed**: 2026-07-02 20:56 **Duration**: 2 minutes

**Notes**:

* Ran the focused Hermes bridge/admin/chat/read-only test slot.
* All selected test files passed.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T017 test outcome.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` - Updated T017 test status.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T017 complete after evidence was recorded.

**Verification**:

* Command/check: `bunx vitest run scripts/lib/__tests__/hermes-admin-bridge.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/hooks/__tests__/use-hermes-admin.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`
  * Result: PASS - focused Hermes baseline tests passed.
  * Evidence: Vitest reported 5 test files passed and 190 tests passed.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T016 - Create concise implementation summary with audit results, invariant links, classification counts, and handoff notes

**Started**: 2026-07-02 20:52 **Completed**: 2026-07-02 20:53 **Duration**: 1 minute

**Notes**:

* Created `IMPLEMENTATION_SUMMARY.md` with scope result, baseline evidence, key references, classification counts, highest-value handoff items, test status slots, and next handoff.
* Summary references the stable invariant, decision, owner mapping, and classification sections in `implementation-notes.md`.
* Test status remains "Not run yet" because T017 through T020 own those exact checks.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/IMPLEMENTATION_SUMMARY.md` - Created concise Session 01 handoff summary.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T016 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T016 complete after evidence was recorded.

**Verification**:

* Command/check: Manual summary review against implementation notes.
  * Result: PASS - summary includes audit results, invariant/decision/classification references, classification counts, and handoff notes.
  * Evidence: `IMPLEMENTATION_SUMMARY.md` contains `Scope Result`, `Baseline Evidence`, `Key References`, `Classification Counts`, `Highest-Value Handoff Items`, `Test Status`, and `Next Handoff`.
* Command/check: Manual no-production-change check.
  * Result: PASS - summary creation affected only session artifacts.
  * Evidence: New file path is under `.spec_system/specs/phase40-session01-baseline-and-port-invariants/`.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T015 - Confirm baseline audit changed no production source, route UI, Vite middleware, package metadata, graph artifact, or product/API doc

**Started**: 2026-07-02 20:50 **Completed**: 2026-07-02 20:52 **Duration**: 2 minutes

**Notes**:

* Confirmed no tracked production source, route-visible UI, Vite middleware, package metadata, graph artifact, or product/API doc diff was introduced by this baseline audit.
* Current tracked diff is limited to pre-existing `.spec_system/state.json` session pointer/history changes.
* Active session artifacts are untracked under `.spec_system/specs/phase40-session01-baseline-and-port-invariants/`.
* The baseline audit scope remains limited to spec-system session artifacts.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T015 diff boundary evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T015 complete after evidence was recorded.

**Verification**:

* Command/check: `git diff --name-status`
  * Result: PASS - tracked diff contains no production source/doc/API/package/graph files.
  * Evidence: Output listed only `M .spec_system/state.json`.
* Command/check: `git status --short`
  * Result: PASS - full worktree status captured.
  * Evidence: Output listed `M .spec_system/state.json` and `?? .spec_system/specs/phase40-session01-baseline-and-port-invariants/`.
* Command/check: `git diff -- src/routes/agents.hermes.tsx vite.config.ts package.json docs/api/README_api.md src/data/graphs/ scripts/lib/hermes-dev-bridge.ts scripts/lib/hermes-admin-bridge.ts src/components/hermes src/hooks src/lib/hermes-types.ts src/lib/hermes-admin-types.ts`
  * Result: PASS - no production/source/API/package/graph diff.
  * Evidence: Command produced no output.
* Command/check: `git ls-files --others --exclude-standard .spec_system/specs/phase40-session01-baseline-and-port-invariants`
  * Result: PASS - active session artifacts identified.
  * Evidence: Output listed `implementation-notes.md`, `spec.md`, and `tasks.md` as untracked session artifacts.
* UI product-surface check: PASS - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T009 - Audit media, public demo, graph, package identity, docs naming, and local control-plane guard boundaries

**Started**: 2026-07-02 20:30 **Completed**: 2026-07-02 20:32 **Duration**: 2 minutes

**Notes**:

* `docs/media-policy.md` keeps the non-logo committed asset cap at 200 KB for `src/assets/`, with AI Rogue music exceptions and reviewed logo/public-asset guidance.
* Existing `src/assets/hermes-art/` assets are under the configured size gate; `bash scripts/check-asset-sizes.sh` passed with total `src/assets/` size at 15M.
* Upstream `ministry-hero.webp` is 385932 bytes and must not be committed as-is under current media policy; Session 10 should replace or redesign it under the cap.
* Current graph seed files are `src/data/graphs/ai-os.json` and `src/data/graphs/index.json`; both are tracked by git.
* `.gitignore` ignores generated `graphify-out/` but does not ignore tracked AI OS seed graph files. The upstream `src/data/graphs/claude-os.json` ignore should not be copied unless a new local-only graph artifact is introduced and documented.
* `package.json` identity remains `ai-os`, private, version `0.5.103`; upstream package metadata removal is a non-port candidate.
* `docs/api/README_api.md` names current local API behavior and correctly documents Hermes dev/admin bridges as Vite `configureServer` surfaces, loopback-only, with token-gated sensitive reads and admin-gated writes.
* Public demo copy in `src/lib/public-demo.ts` keeps hosted/demo surfaces read-only, fixture-backed, and unavailable for local bridge writes or local machine reads.
* `scripts/lib/local-control-plane-guard.ts` requires loopback remote address and exact local Host header, rejects unsafe Host characters, supports localhost/127.0.0.1/::1, and validates ports.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T009 media/demo/graph/package/docs/control-plane audit.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T009 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,240p' docs/media-policy.md`
  * Result: PASS - media policy reviewed.
  * Evidence: Output showed 200 KB non-logo cap, 900 KB AI Rogue music cap, logo/public asset guidance, format requirements, and asset-size script enforcement.
* Command/check: `find src/assets/hermes-art -maxdepth 2 -type f -printf '%p %s\n' | sort`
  * Result: PASS - Hermes media inventory captured.
  * Evidence: Output listed existing Hermes assets and file sizes under the configured gate.
* Command/check: `bash scripts/check-asset-sizes.sh`
  * Result: PASS - current committed assets satisfy size checker.
  * Evidence: Output reported `OK: All assets within configured size limits (total: 15M)`.
* Command/check: `find src/data/graphs -maxdepth 2 -type f -printf '%p %s\n' | sort && git ls-files src/data/graphs`
  * Result: PASS - graph seed ownership reviewed.
  * Evidence: Output listed `src/data/graphs/ai-os.json` and `src/data/graphs/index.json`, both tracked.
* Command/check: `sed -n '1,260p' scripts/lib/local-control-plane-guard.ts`
  * Result: PASS - loopback and Host-header guard reviewed.
  * Evidence: Output showed loopback remote allowlist, exact local Host parsing, unsafe character rejection, port validation, and combined request guard.
* Command/check: `sed -n '329,475p' docs/api/README_api.md`
  * Result: PASS - Hermes API docs boundary reviewed.
  * Evidence: Output documented Hermes read/admin bridges as local Vite middleware, not public product APIs, with loopback/token/admin gates.
* Command/check: `sed -n '1,190p' src/lib/public-demo.ts`
  * Result: PASS - public demo boundary reviewed.
  * Evidence: Output showed hosted demo copy that disables local agent reads, writes, local graph services, source setup writes, Trend Finder runs, and protected local assets.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T008 - Audit voice and Intelligence ownership while preserving environment-backed provider configuration

**Started**: 2026-07-02 20:27 **Completed**: 2026-07-02 20:29 **Duration**: 2 minutes

**Notes**:

* `scripts/lib/voice-launch-bridge.ts` owns `/__start_voice`; it is POST-only, loopback-gated, same-run-token gated, rejects any non-empty browser provider config body, reads `OPENAI_API_KEY` and `OPENAI_BASE_URL` from environment, and passes the same-run token to the broker as `AI_OS_VOICE_TOKEN`.
* `scripts/lib/voice-broker.ts` owns `/api/health` and `/api/session`; it allows only OpenAI default or loopback base URLs, requires local Host/Origin, requires the same-run token, and mints Realtime sessions with provider credentials held server-side.
* The browser voice hook `src/hooks/use-hermes-intelligence-voice.ts` starts the launch bridge with an empty JSON body, checks health, requests `/api/session` with only `voice` and `mode`, then opens WebRTC with the returned ephemeral session value.
* `src/components/hermes/intelligence/intelligence-portal.tsx` owns the Hermes Intelligence UI, visualizer choice, text prompt path, Start voice/Stop controls, recovery copy, and transcript/activity rendering.
* The Intelligence portal persists only `ai-os-hermes-intelligence-design` in localStorage for visual mode preference; no API key or provider config is persisted in browser storage.
* Current AI OS already implements the privacy-preserving voice ownership model. The upstream browser-key persistence change should be treated as outcome parity only: no unnecessary reprompt when environment-backed broker config exists.
* Tests cover body-provider-config rejection, missing environment key, env-only spawn, no key material in argv, already-running broker reuse, broker method/token/origin/Host checks, browser provider config rejection, session minting without key in request body, hook startup/token/session flow, and demo-mode disabling.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T008 voice and Intelligence ownership audit.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T008 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,280p' scripts/lib/voice-launch-bridge.ts`
  * Result: PASS - launch bridge ownership reviewed.
  * Evidence: Output showed request body cap, provider-config body rejection, env-backed child env creation, token env, health polling, and spawn setup.
* Command/check: `sed -n '280,420p' scripts/lib/voice-launch-bridge.ts`
  * Result: PASS - launch bridge gate and start flow reviewed.
  * Evidence: Output showed POST-only handling, loopback/token checks, existing broker health reuse, environment key/base URL reads, spawn, timeout, and health response.
* Command/check: `sed -n '1,260p' scripts/lib/voice-broker.ts`
  * Result: PASS - broker request and provider boundaries reviewed.
  * Evidence: Output showed base URL allowlist, health payload, CORS/Host/Origin gates, session token requirement, and session request schema.
* Command/check: `sed -n '1,300p' src/hooks/use-hermes-intelligence-voice.ts`
  * Result: PASS - browser hook ownership reviewed.
  * Evidence: Output showed `VOICE_START_URL`, `VOICE_SESSION_URL`, token header, error mapping, empty start-bridge body, and session request body containing only voice/mode.
* Command/check: `sed -n '1,520p' src/components/hermes/intelligence/intelligence-portal.tsx`
  * Result: PASS - Intelligence portal ownership reviewed.
  * Evidence: Output showed visual design localStorage preference, voice controller wiring, Start voice/Stop controls, text prompt path, transcript, and activity rendering.
* Command/check: `sed -n '220,310p' scripts/lib/__tests__/voice-launch-bridge.test.ts && sed -n '122,220p' scripts/lib/__tests__/voice-broker.test.ts`
  * Result: PASS - voice privacy and broker coverage reviewed.
  * Evidence: Tests assert browser provider config is rejected, missing environment key blocks spawn, env-only config is passed to child env, key/base URL are absent from argv, sessions use env-only credentials, and browser provider config is rejected at the broker.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T007 - Audit chat UI, composer, message list, thread sidebar, read-only page wiring, and hook payload ownership

**Started**: 2026-07-02 20:24 **Completed**: 2026-07-02 20:26 **Duration**: 2 minutes

**Notes**:

* `HermesReadOnlyPage` owns demo/live selection, selected chat session id, Intelligence portal open state, `useHermes`, `useHermesAdmin`, and demo data substitution before passing props into `HermesChatTab`.
* `HermesChatTab` owns write-gate translation, local prompt/attachment state, selected-session resets, local message state, graph grounding prompt composition, and calls into `admin.chat.sendPrompt`.
* `ChatComposer` owns textarea, image upload, drag/drop/paste handling, write-gate copy, send/cancel/reset buttons, and upload errors.
* `ChatMessageList` owns selected-session message rendering, local sent messages, streaming assistant output, generic typing dots, and thread-detail state copy.
* `ChatThreadSidebar` owns recent-thread sorting/selection, new-chat reset action, and compact thread metadata.
* Current chat UI has an Intelligence launcher and graph/image grounding, but does not yet include upstream model selector, configured-provider filtering, context meter, command menu, compact action, reply copy buttons, or elapsed "thinking" timer.
* `HermesChatSendOptions` currently contains only `toolsets`, `yolo`, and `graph`; there are no model/provider override fields.
* `use-hermes-admin.ts` owns `chatPayloadOptions`, which validates only `toolsets`, `yolo`, and `graph` before posting to `/__hermes_chat`.
* Tests already cover write-gate states, Intelligence launcher focus return, new chat selection, prompt send, graph grounding, image upload prompt prefix, selected-thread send behavior, provider errors, cancel/reset behavior, and upload failures.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T007 chat UI ownership audit.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T007 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,260p' src/components/hermes/chat/hermes-chat-tab.tsx`
  * Result: PASS - chat tab ownership reviewed.
  * Evidence: Output showed write-gate handling, local message state, prompt composition, attachment handling, Intelligence launcher, and send flow.
* Command/check: `sed -n '1,260p' src/components/hermes/chat/chat-composer.tsx`
  * Result: PASS - composer ownership reviewed.
  * Evidence: Output showed textarea, image uploads, write-gate copy, supported image types, and send/cancel/reset controls.
* Command/check: `sed -n '1,240p' src/components/hermes/chat/chat-message-list.tsx`
  * Result: PASS - message list ownership reviewed.
  * Evidence: Output showed thread/local/stream message merge, typing state, state copy, and bubble rendering.
* Command/check: `sed -n '1,240p' src/components/hermes/chat/chat-thread-sidebar.tsx`
  * Result: PASS - thread sidebar ownership reviewed.
  * Evidence: Output showed recent-thread sorting, selection, new chat control, and session metadata display.
* Command/check: `sed -n '1,120p' src/components/hermes/chat/chat-types.ts && rg -n "HermesChatTab|chat|admin|sendPrompt|sessionDetail|toolsets|graph|yolo|models|Voice|Intelligence" src/components/hermes/hermes-read-only-page.tsx src/components/hermes/chat src/hooks/use-hermes-admin.ts src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx`
  * Result: PASS - type and payload ownership reviewed.
  * Evidence: Output showed `HermesChatSendOptions` fields, `chatPayloadOptions`, read-only page wiring, and chat test coverage.
* Command/check: `sed -n '140,320p' src/components/hermes/hermes-read-only-page.tsx`
  * Result: PASS - page-level chat wiring reviewed.
  * Evidence: Output showed demo/live mode, token handoff, admin hook, selected chat session, and Intelligence portal state.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T006 - Audit admin Hermes chat, write-gate, timeout, redaction, and admin type boundaries

**Started**: 2026-07-02 20:21 **Completed**: 2026-07-02 20:23 **Duration**: 2 minutes

**Notes**:

* Admin bridge endpoints are registered in `scripts/lib/hermes-admin-bridge.ts`, including admin status, chat, image upload, mission writes, Pantheon sync/persona writes, document writes, and Obsidian write.
* Admin write preflight requires method match, loopback, `X-Claude-OS-Token`, and `HERMES_DASHBOARD_ADMIN=1` for privileged routes.
* `/__hermes_admin_status` is GET-only, loopback-only, and reports that admin is dev-only, production unavailable, token-required, and gated by `HERMES_DASHBOARD_ADMIN`.
* Current chat payload validation accepts prompt, optional session id, `toolsets`, `yolo`, and `graph`; model/provider overrides are not implemented yet.
* Current chat spawn uses argv arrays with `shell` undefined, strips inherited Python env values, writes SSE `chunk`, `done`, and `error` events, and kills the child on client close or timeout.
* Current chat timeout is a single session timeout (`chatTimeoutMs` or default), not the upstream two-stage pre-output and post-output watchdog. No heartbeat is emitted yet.
* Current stderr handling buffers stderr for final error classification only; upstream-style sanitized `info` diagnostic events are not exposed yet.
* Redaction currently uses local `SECRET_PATTERN` plus shared `sanitize()` through `sanitizeCommandOutput`; Phase 40 should consolidate broader bridge/output redaction in `scripts/lib/sanitize.ts`.
* `src/lib/hermes-admin-types.ts` currently parses only chat `chunk`, `done`, and `error` events; command endpoint and MoA save response types are absent and should be added with their bridge endpoints.
* Existing tests cover admin status, disabled admin gate, non-loopback/invalid-token rejection, hostile Host handling through the shared local guard, argv-only chat spawn, graph/yolo arg combinations, spawn errors, provider-auth failure classification, and redaction of secret-shaped stderr.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T006 admin bridge audit.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T006 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "__hermes|chat|admin|token|method|loopback|timeout|AbortController|sanitize|SECRET|redact|stream|SSE|event|write|POST|persona|image|mission|document|obsidian|pantheon" scripts/lib/hermes-admin-bridge.ts`
  * Result: PASS - admin endpoint and guard inventory captured.
  * Evidence: Output showed endpoint registration, preflight gates, timeout handling, chat streaming, writes, and sanitizer usage.
* Command/check: `sed -n '540,760p' scripts/lib/hermes-admin-bridge.ts`
  * Result: PASS - chat option parsing and redaction helpers reviewed.
  * Evidence: Output showed `readChatToolsets`, strict boolean handling, confirmation helpers, and `sanitizeCommandOutput`.
* Command/check: `sed -n '1200,1568p' scripts/lib/hermes-admin-bridge.ts`
  * Result: PASS - mission store and chat execution path reviewed.
  * Evidence: Output showed JSON store writes, admin status, chat preflight, argv construction, SSE headers, timeout, stdout chunks, stderr buffer, and close/error handling.
* Command/check: `sed -n '631,654p' src/lib/hermes-admin-types.ts`
  * Result: PASS - chat event parser boundary reviewed.
  * Evidence: Parser accepts `chunk`, `done`, and `error` only.
* Command/check: `sed -n '700,1045p' scripts/lib/__tests__/hermes-admin-bridge.test.ts`
  * Result: PASS - admin bridge chat and redaction coverage reviewed.
  * Evidence: Tests cover invalid chat options, argv-only spawn, graph/yolo combinations, wrapper resolution, Windows command resolution, spawn failures, stderr redaction, and provider-auth classification.
* Command/check: `sed -n '544,675p' src/hooks/__tests__/use-hermes-admin.test.tsx`
  * Result: PASS - admin hook chat parser coverage reviewed.
  * Evidence: Tests parse `chunk`, `done`, and `error` streams and transcript output.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T005 - Audit public Hermes read bridge, model body, connection, Pantheon, documents, and provider readiness boundaries

**Started**: 2026-07-02 20:18 **Completed**: 2026-07-02 20:20 **Duration**: 2 minutes

**Notes**:

* Public bridge endpoints are registered in `scripts/lib/hermes-dev-bridge.ts`:
  * Non-sensitive reads: `/__hermes_status`, `/__hermes_models`, `/__hermes_connections`, `/__hermes_pantheon_templates`, `/__hermes_missions`, and `/__hermes_documents`.
  * Token-gated sensitive reads: `/__hermes_skills`, `/__hermes_sessions`, `/__hermes_session`, `/__hermes_memory`, `/__hermes_pantheon`, and `/__hermes_profiles`.
* All public bridge requests are GET-only and loopback-gated; sensitive endpoints also require `X-Claude-OS-Token` to match the same-run refresh token.
* Current `/__hermes_models` returns the AI OS body shape only: `ok`, `configuredDefault`, and `catalog`. It does not yet expose upstream-compatible `default`, `mixtures`, or `configured` fields.
* `src/lib/hermes-types.ts` currently requires `ok: true` and `configuredDefault` in `parseHermesModelsResponse`, so upstream no-`ok` model bodies are not yet accepted.
* `scripts/lib/hermes-provider-readiness.ts` already includes `MINIMAX_API_KEY` and `NVIDIA_API_KEY`, but later provider-readiness work must add upstream alias handling such as `googlegemini`, `xai`, `xai-oauth`, and `GEMINI_API_KEY`/`GOOGLEAI_API_KEY` coverage without breaking current `google`/`gemini` compatibility.
* Connections read from Hermes config, `.env`, `auth.json`, gateway tokens, generic service key names, and memory directory presence; values are summarized as connection metadata and tests assert credential values are not leaked.
* Documents reads resolve against a configured documents directory, reject unsafe names, skip symlink escapes, provide trash/file subpaths through the same route, and sanitize `documentsDir`.
* Pantheon persona reads parse YAML/frontmatter from token-gated local persona files and return summarized persona metadata only.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T005 public bridge audit.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T005 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "__hermes|models|connections|pantheon|documents|profiles|sessions|memory|token|read|write|method|refreshToken|isLoopback|host|public|demo" scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - bridge endpoint and gate inventory captured.
  * Evidence: Output listed the endpoint table, sensitive flags, read handlers, GET enforcement, loopback rejection, and token validation.
* Command/check: `sed -n '1,240p' scripts/lib/hermes-provider-readiness.ts`
  * Result: PASS - provider readiness mapping reviewed.
  * Evidence: Output showed OAuth providers, key map, labels, normalization, env parsing, and readiness classification.
* Command/check: `sed -n '1230,1560p' scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - models, sessions, memory, Pantheon, and connections readers reviewed.
  * Evidence: Output showed `readHermesModels`, `readHermesPantheon`, and `readHermesConnections` behavior.
* Command/check: `sed -n '1620,1778p' scripts/lib/hermes-dev-bridge.ts`
  * Result: PASS - missions/documents reads and common request gate reviewed.
  * Evidence: Output showed confined document reads, trash/file subpaths, GET-only handling, loopback gate, and token gate.
* Command/check: `rg -n "HermesModels|parseHermesModels|configuredDefault|models|catalog|provider|connection|documents|pantheon" src/lib/hermes-types.ts src/hooks/use-hermes.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx`
  * Result: PASS - client parser/hook ownership reviewed.
  * Evidence: Output showed models query ownership, parser requirement for `ok` and `configuredDefault`, and tests for models/connections/documents/Pantheon flows.
* Command/check: `rg -n "models|connections|pantheon|documents|method_not_allowed|loopback_required|invalid_token|provider readiness|provider" scripts/lib/__tests__/hermes-dev-bridge.test.ts`
  * Result: PASS - public bridge coverage reviewed.
  * Evidence: Output showed tests for endpoint registration, GET/loopback/token rejection, model reads, connection sanitization, provider readiness, and document confinement.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T004 - Inventory current split Hermes architecture and route registration owners

**Started**: 2026-07-02 20:16 **Completed**: 2026-07-02 20:17 **Duration**: 1 minute

**Notes**:

* `src/routes/agents.hermes.tsx` is a 16-line TanStack route shell that imports and renders `HermesReadOnlyPage`; it is not a monolithic feature owner.
* `src/routeTree.gen.ts` registers `/agents/hermes` from the route file.
* `vite.config.ts` imports and registers `registerHermesDevBridge` and `registerHermesAdminBridge` with shared `REFRESH_TOKEN`, `isLoopback`, bridge env, and dev logger.
* Component ownership is split under `src/components/hermes/`, including chat, Pantheon, documents, missions, Mnemosyne, Intelligence, admin panel, and page primitives.
* Hook ownership is split across `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, and `src/hooks/use-hermes-intelligence-voice.ts`.
* Shared client contracts live in `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts`, `src/lib/hermes-demo-data.ts`, and related Hermes/graph helpers.
* Bridge implementation owners are `scripts/lib/hermes-dev-bridge.ts` for public/read paths and `scripts/lib/hermes-admin-bridge.ts` for admin/write paths.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T004 owner inventory.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T004 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,220p' src/routes/agents.hermes.tsx`
  * Result: PASS - route shell ownership verified.
  * Evidence: File imports `HermesReadOnlyPage`, defines `createFileRoute("/agents/hermes")`, and sets metadata plus `component: HermesReadOnlyPage`.
* Command/check: `find src/components/hermes -maxdepth 3 -type f | sort`
  * Result: PASS - component inventory captured.
  * Evidence: Output listed chat components/tests, read-only page, admin panel, Pantheon, mission, document, Mnemosyne, Intelligence, and primitive owners.
* Command/check: `find src/hooks -maxdepth 2 -type f | sort | rg 'hermes|voice|intelligence'`
  * Result: PASS - hook inventory captured.
  * Evidence: Output listed Hermes public/admin/voice hooks and tests.
* Command/check: `find src/lib -maxdepth 2 -type f | sort | rg 'hermes|voice|sanitize|graph'`
  * Result: PASS - shared client contract inventory captured.
  * Evidence: Output listed Hermes type/parser/test files, demo data, Intelligence events, mission helpers, graph helpers, and synthetic voice helpers.
* Command/check: `rg -n "hermes|__hermes|Hermes|ai-os|routeTree|TanStack|server|configureServer|middleware" vite.config.ts src/routes/agents.hermes.tsx src/routeTree.gen.ts`
  * Result: PASS - route and middleware registration owners verified.
  * Evidence: Output showed route tree registration and Vite bridge registration lines for dev/admin bridges.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T003 - Review upstream patch stat, name-status, changelog, and folded source references

**Started**: 2026-07-02 20:14 **Completed**: 2026-07-02 20:15 **Duration**: 1 minute

**Notes**:

* Upstream evidence files were reviewed from the folded source record:
  * Patch: 11514 lines.
  * Stat: 26 lines.
  * Name-status: 25 lines.
* Name-status summary: 16 added files and 9 modified files.
* Patch stat summary: 25 files changed with 3516 insertions and 70 deletions.
* Largest upstream source changes are `src/routes/agents.hermes.tsx` with 2927 changed lines and `vite.config.ts` with 424 changed lines; these are semantic source evidence only and must not be copied into AI OS wholesale.
* Upstream added 15 provider logo SVGs and `src/assets/ministry-hero.webp`; the hero is 385932 bytes in the upstream stat and must be handled under AI OS media policy later.
* Upstream changelog themes:
  * V2.9: Ministry of Experts, MoA config save, model intelligence, and voice no-reprompt outcome.
  * V2.10: chat model selector, context meter, command menu, compact flow, copy button, and Voice label.
  * V2.10.1: configured-provider filtering, subscription provider labels, Claude Sonnet 5, command output redaction, update confirmation, timeout correctness, and compact carry-over isolation.
* Folded Phase 40 source references reviewed: second-pass findings, third-pass corrections, upstream change inventory, current AI OS mapping, and port rules.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T003 upstream evidence summary.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T003 complete after evidence was recorded.

**Verification**:

* Command/check: `wc -l <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.patch <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.stat.txt <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.name-status.txt`
  * Result: PASS - upstream evidence size captured.
  * Evidence: Output reported 11514 patch lines, 26 stat lines, 25 name-status lines, and 11565 total lines.
* Command/check: `sed -n '1,220p' <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.stat.txt`
  * Result: PASS - upstream patch stat reviewed.
  * Evidence: Output reported 25 files changed, 3516 insertions, 70 deletions, route-heavy Hermes changes, Vite middleware changes, model data changes, logos, and a 385932-byte hero asset.
* Command/check: `sed -n '1,260p' <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.name-status.txt`
  * Result: PASS - upstream name-status reviewed.
  * Evidence: Output listed 16 added files and 9 modified files.
* Command/check: `sed -n '1,180p' <upstream-checkout>/CHANGELOG.md`
  * Result: PASS - release themes reviewed.
  * Evidence: V2.9, V2.10, and V2.10.1 sections were inspected.
* Command/check: `sed -n '300,430p' .spec_system/PRD/phase_40/PRD_phase_40.md`
  * Result: PASS - folded source findings and port rules reviewed.
  * Evidence: Second-pass findings, third-pass corrections, upstream inventory, AI OS mapping, and port rules were present.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T002 - Capture package, runtime, lockfile, and command baseline

**Started**: 2026-07-02 20:13 **Completed**: 2026-07-02 20:13 **Duration**: 1 minute

**Notes**:

* Package metadata remains owned by AI OS: `package.json` has `name` `ai-os`, version `0.5.103`, and private package identity.
* `.bun-version` pins Bun `1.3.14`.
* Runtime `bun --version` returned `1.3.14`, matching the repo pin.
* `bun.lock` exists and has 1982 lines with root workspace `name` `ai-os`.
* Dependency metadata was inspected only; no install, lockfile, package, or runtime metadata changes were made.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Recorded T002 package/runtime baseline.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T002 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,220p' package.json`
  * Result: PASS - package metadata captured.
  * Evidence: `name` is `ai-os`, version is `0.5.103`, and scripts include the expected Bun/Vite/TypeScript/Vitest command baseline.
* Command/check: `sed -n '1,40p' .bun-version && bun --version`
  * Result: PASS - repo pin and runtime match.
  * Evidence: Both commands returned `1.3.14`.
* Command/check: `wc -l bun.lock && sed -n '1,40p' bun.lock`
  * Result: PASS - lockfile exists and root workspace metadata matches package identity.
  * Evidence: `bun.lock` has 1982 lines and root workspace `name` is `ai-os`.
* Command/check: `git diff -- package.json bun.lock .bun-version`
  * Result: PASS - dependency metadata unchanged.
  * Evidence: Command produced no diff.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

## Session Start

**Environment verified**:

* [x] Analyzer state loaded with current session `phase40-session01-baseline-and-port-invariants`
* [x] Prerequisites confirmed by `.spec_system/scripts/check-prereqs.sh --json --env`
* [x] Directory structure ready
* [x] BQC not loaded: this session creates audit artifacts only, not application code

***

## Baseline Audit Notes

### Upstream Evidence Summary

| Evidence               | Result                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Upstream checkout      | Local upstream checkout exists; path redacted in this artifact                                                           |
| Upstream patch         | 11514 lines                                                                                                              |
| Upstream stat          | 25 files changed, 3516 insertions, 70 deletions                                                                          |
| Upstream name-status   | 16 added files, 9 modified files                                                                                         |
| Largest source changes | Upstream `src/routes/agents.hermes.tsx` and `vite.config.ts`                                                             |
| Changelog scope        | V2.9 Ministry/voice, V2.10 chat composer, V2.10.1 model picker/redaction hardening                                       |
| Non-copy inputs        | Upstream monolithic route, Vite middleware, `.gitignore` graph ignore, package metadata removal, oversized Ministry hero |

### Local Command Baseline

| Command or file                         | Baseline                                                                                             |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `git rev-parse HEAD`                    | `c7c58c3eb36b976ee05ae1e82837b194a88fbe99`                                                           |
| Session base commit                     | `c7c58c3eb36b976ee05ae1e82837b194a88fbe99`                                                           |
| Pre-implementation `git status --short` | Dirty spec-system state: modified `.spec_system/state.json`, untracked active session spec directory |
| `package.json`                          | `name` `ai-os`, version `0.5.103`, private package                                                   |
| `.bun-version`                          | `1.3.14`                                                                                             |
| `bun --version`                         | `1.3.14`                                                                                             |
| `bun.lock`                              | Present, 1982 lines, root workspace `ai-os`                                                          |
| Asset size gate                         | `bash scripts/check-asset-sizes.sh` passed                                                           |

### Focused Hermes Baseline Test Slots

| Slot | Command                                                                                                                                                                                                                                                                                                                                                                                         | Result                    |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| T017 | `bunx vitest run scripts/lib/__tests__/hermes-admin-bridge.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/hooks/__tests__/use-hermes-admin.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx src/components/hermes/__tests__/hermes-sections.test.tsx`                                                                                                        | PASS - 5 files, 190 tests |
| T018 | `bunx vitest run scripts/lib/__tests__/voice-launch-bridge.test.ts scripts/lib/__tests__/voice-broker.test.ts scripts/lib/__tests__/local-control-plane-guard.test.ts scripts/lib/__tests__/sanitize.test.ts scripts/lib/__tests__/hermes-scanner.test.ts src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` | PASS - 7 files, 63 tests  |
| T019 | `bun run typecheck`                                                                                                                                                                                                                                                                                                                                                                             | PASS                      |
| T019 | `bun run typecheck:scripts`                                                                                                                                                                                                                                                                                                                                                                     | PASS                      |
| T020 | `git diff --check` and artifact ASCII/LF checks                                                                                                                                                                                                                                                                                                                                                 | PASS                      |

***

## Port Invariants

| ID      | Boundary             | Invariant                                                                                                                                                                                                                                 |
| ------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INV-001 | Upstream translation | Translate upstream behavior into current AI OS owners. Do not copy or replace the upstream monolithic `src/routes/agents.hermes.tsx` or upstream `vite.config.ts`.                                                                        |
| INV-002 | Route shell          | Keep `src/routes/agents.hermes.tsx` a thin TanStack route shell that delegates to Hermes components.                                                                                                                                      |
| INV-003 | Loopback             | All local bridge and admin routes that read local machine state or mutate local state must require loopback remote address checks.                                                                                                        |
| INV-004 | Host header          | Loopback checks must include exact local Host-header validation and must reject hostile Host values.                                                                                                                                      |
| INV-005 | Same-run token       | Sensitive local reads and all write/admin routes must require the per-run token from `/__token`; new Hermes write routes must use `X-Claude-OS-Token`.                                                                                    |
| INV-006 | Admin gate           | Any Hermes write, spawn, upload, delete, local file mutation, or git action remains default-off behind `HERMES_DASHBOARD_ADMIN=1` and unavailable in production builds.                                                                   |
| INV-007 | Public/demo          | Public demo and hosted pages use committed fixtures only. They must not call local bridges, fetch live provider data, run local jobs, read local machine state, or enable writes.                                                         |
| INV-008 | Chat SSE             | Chat SSE may grow beyond `chunk`/`done`/`error`, but stderr diagnostics must be sanitized and surfaced as diagnostics such as `info`, never appended as ordinary assistant reply text.                                                    |
| INV-009 | Redaction            | Browser-facing bridge output, errors, status, command output, and future MoA save output must use shared sanitization for home paths, private paths, emails, account ids, tokens, key/value secrets, and long opaque secret-like strings. |
| INV-010 | Graph                | Keep tracked AI OS seed graph files in `src/data/graphs/`. Do not copy upstream `src/data/graphs/claude-os.json` ignore behavior unless a new local-only graph artifact is introduced with docs and tests.                                |
| INV-011 | Media                | New committed non-logo assets in `src/assets/` must pass `scripts/check-asset-sizes.sh`. Do not commit upstream `ministry-hero.webp` as-is because it exceeds the current cap.                                                            |
| INV-012 | Package identity     | Preserve AI OS package/runtime identity (`ai-os`, package version, AI OS docs) unless a migration adds aliases, docs, and tests. Do not copy upstream package metadata removal.                                                           |
| INV-013 | Docs naming          | Use AI OS for the host app/platform behavior, Trend Finder only for extension behavior, and Claude OS only for upstream source or historical compatibility references.                                                                    |
| INV-014 | Voice credentials    | Voice provider credentials stay environment-backed. Do not persist browser OpenAI keys or accept browser-supplied provider config.                                                                                                        |
| INV-015 | Model data           | Treat upstream model intelligence as a 2026-06-30 snapshot unless a later session implements a verified live refresh path with source labeling.                                                                                           |

***

## Decision List

| ID      | Topic                            | Decision                                                                                                                                                                 | Rationale                                                                                    | Downstream Session  |
| ------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------- |
| DEC-001 | Stderr diagnostics               | Port sanitized stderr as chat SSE `info` diagnostics, not as assistant reply text.                                                                                       | Preserves observability without contaminating the user-visible answer stream.                | Session 04          |
| DEC-002 | Live pricing                     | Allow keyless OpenRouter pricing only in local live mode, cache/fail soft, label the source, and disable it in public/demo mode.                                         | Pricing provenance must be visible and demo-safe.                                            | Session 09          |
| DEC-003 | Connection probes                | Port only useful CLI probes with allowlisted argv arrays, no shell, no output body, short timeouts, and status-only cache. Keep TTY-unsafe MCP probing skipped.          | Reduces local hang and leakage risk while preserving useful readiness signals.               | Session 07          |
| DEC-004 | Voice key persistence            | Do not port upstream browser OpenAI key persistence. Preserve AI OS environment-backed broker behavior and verify no-reprompt parity through broker health/session flow. | Browser key storage would violate AI OS credential boundaries.                               | Session 16          |
| DEC-005 | Graph ignores                    | Do not copy upstream `src/data/graphs/claude-os.json` gitignore behavior. Keep tracked AI OS graph seeds unless a new local-only artifact is introduced.                 | AI OS owns its seed graph files and public/demo fallback.                                    | Session 17          |
| DEC-006 | Demo data                        | Public/demo routes remain fixture-backed and read-only; configured-provider summaries and live OpenRouter pricing must not run in demo mode.                             | Hosted surfaces must not read local state or imply live provider access.                     | Sessions 07, 09, 17 |
| DEC-007 | Asset handling                   | Do not commit upstream `ministry-hero.webp` as-is. Reuse/rehome provider logos only after media review and replace or redesign the hero under the cap.                   | Current hero exceeds media policy; provider marks need asset ownership review.               | Session 10          |
| DEC-008 | Package metadata                 | Do not remove AI OS package version or README identity because upstream did. Preserve `ai-os` package identity.                                                          | AI OS package metadata is not upstream Claude OS metadata.                                   | Session 17          |
| DEC-009 | Intelligence versus Voice labels | Keep the surface name `Hermes Intelligence`; use `Voice` for speech-specific controls and recovery copy only.                                                            | Current product ownership distinguishes Intelligence portal from voice transport.            | Sessions 12, 16     |
| DEC-010 | YAML writes                      | Use existing structured `js-yaml` load/dump paths for MoA config writes; do not interpolate raw YAML strings.                                                            | Prevents provider/model ids with slash, colon, quotes, or whitespace from corrupting config. | Sessions 06, 14, 15 |
| DEC-011 | Model body compatibility         | Extend AI OS model responses to tolerate both AI OS `ok/configuredDefault` and upstream `default/catalog/mixtures/configured` shapes.                                    | Keeps current clients stable while supporting upstream-derived model selector behavior.      | Sessions 02, 11     |
| DEC-012 | Sanitizer ownership              | Extend shared `scripts/lib/sanitize.ts` for bridge/output redaction rather than adding a parallel Hermes-only sanitizer.                                                 | Shared output paths need consistent redaction guarantees.                                    | Sessions 03, 05, 06 |

***

## Upstream To AI OS Owner Mapping

| ID      | Upstream change area                                          | AI OS owner files                                                                                                                                                               | Downstream session  |
| ------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| MAP-001 | `/__hermes_models` catalog/default/configured/MoA body        | `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-provider-readiness.ts`, `src/lib/hermes-types.ts`, `src/hooks/use-hermes.ts`                                            | Sessions 02, 08, 11 |
| MAP-002 | Provider aliases and readiness labels                         | `scripts/lib/hermes-provider-readiness.ts`, `scripts/lib/__tests__/hermes-dev-bridge.test.ts`, `src/lib/hermes-types.ts`                                                        | Session 02          |
| MAP-003 | Shared redaction for command/chat/MoA output                  | `scripts/lib/sanitize.ts`, `scripts/lib/hermes-admin-bridge.ts`, bridge tests, parser tests                                                                                     | Session 03          |
| MAP-004 | Chat model/provider override argv                             | `scripts/lib/hermes-admin-bridge.ts`, `src/lib/hermes-admin-types.ts`, `src/hooks/use-hermes-admin.ts`, `src/components/hermes/chat/chat-types.ts`                              | Session 04          |
| MAP-005 | Chat SSE heartbeat/watchdogs/stderr diagnostics               | `scripts/lib/hermes-admin-bridge.ts`, `src/lib/hermes-admin-types.ts`, `src/hooks/use-hermes-admin.ts`, `src/lib/hermes-intelligence-events.ts`                                 | Session 04          |
| MAP-006 | Hermes command endpoint and command menu                      | `scripts/lib/hermes-admin-bridge.ts`, `src/lib/hermes-admin-types.ts`, `src/hooks/use-hermes-admin.ts`, `src/components/hermes/chat/`                                           | Sessions 05, 13     |
| MAP-007 | MoA save endpoint and config merge                            | `scripts/lib/hermes-admin-bridge.ts`, `src/lib/hermes-admin-types.ts`, `src/hooks/use-hermes-admin.ts`                                                                          | Sessions 06, 14, 15 |
| MAP-008 | Connection probe parity                                       | `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/local-control-plane-guard.ts`, `src/lib/hermes-types.ts`, public bridge tests                                                  | Session 07          |
| MAP-009 | Catalog/context metadata and `Claude Sonnet 5`                | `scripts/lib/hermes-dev-bridge.ts`, `src/lib/hermes-types.ts`, `src/components/hermes/chat/`                                                                                    | Sessions 08, 11     |
| MAP-010 | Ministry model intelligence and live pricing                  | New Hermes-scoped data/helper under `src/lib/` or `src/components/hermes/`, Ministry components, demo guards                                                                    | Session 09          |
| MAP-011 | Provider logos and Ministry hero                              | `src/assets/`, `src/assets/hermes-art/`, `docs/media-policy.md`, asset-size script evidence                                                                                     | Session 10          |
| MAP-012 | Chat model selector and context meter UI                      | `src/components/hermes/chat/`, `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `src/lib/hermes-types.ts`                                                            | Session 11          |
| MAP-013 | Compact flow, copy replies, warning filtering, thinking state | `src/components/hermes/chat/`, `src/hooks/use-hermes-admin.ts`, `scripts/lib/hermes-admin-bridge.ts`                                                                            | Session 12          |
| MAP-014 | Ministry builder and Pantheon integration                     | `src/components/hermes/hermes-pantheon.tsx`, new `src/components/hermes/ministry/` components, `src/components/hermes/hermes-read-only-page.tsx`                                | Session 14          |
| MAP-015 | Ministry config analytics and save UX                         | Ministry components, `src/hooks/use-hermes-admin.ts`, `scripts/lib/hermes-admin-bridge.ts`                                                                                      | Session 15          |
| MAP-016 | Voice no-reprompt parity                                      | `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` | Session 16          |
| MAP-017 | Docs/API metadata/gitignore closeout                          | `docs/api/README_api.md`, `docs/media-policy.md`, `docs/`, `.gitignore`, `package.json` only if AI OS-owned behavior changes require it                                         | Session 17          |

***

## Upstream Classification Ledger

Classification counts:

| Classification                       | Count |
| ------------------------------------ | ----- |
| Direct translation into AI OS owners | 4     |
| AI OS adaptation                     | 12    |
| Intentional non-port                 | 5     |
| Already covered                      | 3     |

| ID      | Upstream change                                                                 | Classification                       | Evidence                                                                                                                | Downstream                  |
| ------- | ------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| CLS-001 | `/__hermes_models` no-`ok` body, `default`, `catalog`, `mixtures`, `configured` | AI OS adaptation                     | AI OS parser currently requires `ok` and `configuredDefault`; later work should tolerate both shapes.                   | Sessions 02, 08, 11         |
| CLS-002 | Configured-provider filtering and provider aliases                              | AI OS adaptation                     | Current readiness map needs upstream aliases while preserving AI OS `google`/`gemini` compatibility.                    | Session 02                  |
| CLS-003 | Chat model/provider argv overrides                                              | Direct translation into AI OS owners | Current admin bridge already uses argv arrays; add validated model/provider args there.                                 | Session 04                  |
| CLS-004 | Chat SSE heartbeat, two-stage watchdog, stderr `info`, env sizing               | AI OS adaptation                     | Current chat has one timeout and `chunk`/`done`/`error`; diagnostics need sanitized `info` without reply contamination. | Session 04                  |
| CLS-005 | Hermes command endpoint and command menu                                        | AI OS adaptation                     | Must become admin bridge route plus chat UI controls, not Vite monolith code.                                           | Sessions 05, 13             |
| CLS-006 | Broader command/chat/MoA redaction                                              | AI OS adaptation                     | Extend shared sanitizer instead of copying endpoint-local upstream regexes.                                             | Sessions 03, 05, 06         |
| CLS-007 | Chat model selector UI                                                          | Direct translation into AI OS owners | Behavior maps to `src/components/hermes/chat/` once public model body is extended.                                      | Session 11                  |
| CLS-008 | Context-window meter UI                                                         | Direct translation into AI OS owners | Behavior maps to chat components and model metadata.                                                                    | Sessions 08, 11             |
| CLS-009 | Reply copy, thinking state, narrowed warning filter                             | Direct translation into AI OS owners | Behavior maps to chat components and admin bridge output filtering.                                                     | Session 12                  |
| CLS-010 | Compact flow and fresh-session carry-over isolation                             | AI OS adaptation                     | Current AI OS chat/session handling needs local ownership and tests to prevent carry-over leakage.                      | Session 12                  |
| CLS-011 | Ministry builder and Pantheon integration                                       | AI OS adaptation                     | Upstream UI is monolithic; AI OS should add dedicated components under current Pantheon/page owners.                    | Session 14                  |
| CLS-012 | MoA YAML save and config merge                                                  | AI OS adaptation                     | Use existing `js-yaml` structured write paths and admin-gated save endpoint.                                            | Sessions 06, 15             |
| CLS-013 | Live OpenRouter pricing                                                         | AI OS adaptation                     | Local live only, source-labeled, fail-soft, disabled in demo.                                                           | Session 09                  |
| CLS-014 | Model intelligence data changes                                                 | AI OS adaptation                     | Use upstream snapshot as Hermes-scoped source material, not repo-wide live truth.                                       | Session 09                  |
| CLS-015 | Browser OpenAI key persistence for voice                                        | Intentional non-port                 | AI OS voice credentials stay environment-backed; parity target is broker no-reprompt behavior.                          | Session 16                  |
| CLS-016 | Connection CLI probes                                                           | AI OS adaptation                     | Port allowlisted, no-shell, status-only probes; keep TTY-unsafe MCP probing skipped.                                    | Session 07                  |
| CLS-017 | Provider logos                                                                  | AI OS adaptation                     | Rehome only needed logos after media/asset ownership review.                                                            | Session 10                  |
| CLS-018 | Upstream Ministry hero image                                                    | Intentional non-port                 | Upstream hero is 385932 bytes and exceeds AI OS non-logo asset cap.                                                     | Session 10                  |
| CLS-019 | Upstream graph `.gitignore` addition                                            | Intentional non-port                 | AI OS tracks `src/data/graphs/ai-os.json` and `index.json`.                                                             | Session 17                  |
| CLS-020 | Upstream README/package version removal                                         | Intentional non-port                 | AI OS owns package identity and current-state docs.                                                                     | Session 17                  |
| CLS-021 | Upstream monolithic route and Vite middleware ownership                         | Intentional non-port                 | Use as source evidence only; translate into split AI OS owners.                                                         | All implementation sessions |
| CLS-022 | Environment-backed voice launch and broker                                      | Already covered                      | Current launch bridge rejects browser provider config and spawns with env-only credentials.                             | Session 16 validation       |
| CLS-023 | Local control-plane loopback and Host guard                                     | Already covered                      | Shared guard checks loopback remote address plus exact local Host header.                                               | Reuse in later bridge work  |
| CLS-024 | AI OS seed graph ownership                                                      | Already covered                      | `src/data/graphs/ai-os.json` and `index.json` are tracked and demo-safe.                                                | Session 17 validation       |

***

## Task Log

### Task T001 - Verify analyzer state, Session 01 stub, Phase 40 PRD, upstream source, worktree, and base commit

**Started**: 2026-07-02 20:12 **Completed**: 2026-07-02 20:12 **Duration**: 1 minute

**Notes**:

* Analyzer reported current phase 40 and current session `phase40-session01-baseline-and-port-invariants`.
* Session stub exists at `.spec_system/PRD/phase_40/session_01_baseline_and_port_invariants.md` and scopes Session 01 to baseline evidence, invariant decisions, and upstream-change classification.
* Phase 40 PRD exists at `.spec_system/PRD/phase_40/PRD_phase_40.md` and names the local upstream checkout plus patch/stat/name-status evidence.
* Upstream source availability was confirmed locally with redacted labels:
  * `<upstream-checkout>/`
  * `<upstream-diff>/claude-os-v2.8.1_to_v2.10.1.patch`
  * `<upstream-diff>/claude-os-v2.8.1_to_v2.10.1.stat.txt`
  * `<upstream-diff>/claude-os-v2.8.1_to_v2.10.1.name-status.txt`
* `git rev-parse HEAD` returned `c7c58c3eb36b976ee05ae1e82837b194a88fbe99`, matching the session base commit.
* `git merge-base --is-ancestor c7c58c3eb36b976ee05ae1e82837b194a88fbe99 HEAD` returned status 0.
* Baseline worktree was not clean before this implementation edit: `.spec_system/state.json` was modified to point at this session, and the session spec directory was untracked.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Created session progress log and recorded T001 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T001 complete after evidence was recorded.

**Verification**:

* Command/check: `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash <apex-spec-skill>/scripts/analyze-project.sh --json; fi`
  * Result: PASS - current session resolved.
  * Evidence: Output reported current phase 40, current session `phase40-session01-baseline-and-port-invariants`, and existing `spec.md`/`tasks.md`.
* Command/check: `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/check-prereqs.sh --json --env; else bash <apex-spec-skill>/scripts/check-prereqs.sh --json --env; fi`
  * Result: PASS - environment prerequisites available.
  * Evidence: Output reported overall `pass`, `.spec_system` pass, `jq-1.7`, and `git version 2.43.0`.
* Command/check: `test -d <upstream-checkout>; test -f <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.patch; test -f <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.stat.txt; test -f <upstream-diff>/claude-os-v2.8.1_to_v2.10.1.name-status.txt`
  * Result: PASS - all named upstream sources exist.
  * Evidence: Each existence check returned status 0.
* Command/check: `git status --short`
  * Result: PASS - baseline status captured.
  * Evidence: Output showed `M .spec_system/state.json` and `?? .spec_system/specs/phase40-session01-baseline-and-port-invariants/` before implementation artifacts were added.
* Command/check: `git rev-parse HEAD && git merge-base --is-ancestor c7c58c3eb36b976ee05ae1e82837b194a88fbe99 HEAD`
  * Result: PASS - HEAD matched the session base commit and the base commit is an ancestor of HEAD.
  * Evidence: Output returned `c7c58c3eb36b976ee05ae1e82837b194a88fbe99` and merge-base status 0.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T014 - Classify upstream changes with evidence and downstream session references

**Started**: 2026-07-02 20:46 **Completed**: 2026-07-02 20:49 **Duration**: 3 minutes

**Notes**:

* Added `Upstream Classification Ledger` with `CLS-001` through `CLS-024`.
* Classification counts: 4 direct translations into AI OS owners, 12 AI OS adaptations, 5 intentional non-ports, and 3 already-covered items.
* The ledger covers all material upstream changes named in the folded Phase 40 source record.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Added classification ledger and T014 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T014 complete after evidence was recorded.

**Verification**:

* Command/check: Manual count check of `CLS-001` through `CLS-024`.
  * Result: PASS - counts match ledger rows.
  * Evidence: 24 total rows: 4 direct translation, 12 adaptation, 5 non-port, 3 already covered.
* Command/check: Manual coverage check against folded source upstream inventory.
  * Result: PASS - material upstream model, provider, chat, command, redaction, connection, Ministry, pricing, asset, voice, graph, metadata, and docs changes are classified.
  * Evidence: Ledger rows cover every material area from the Phase 40 second/third-pass findings and upstream inventory.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T013 - Map actionable upstream changes to AI OS owner files and downstream sessions

**Started**: 2026-07-02 20:43 **Completed**: 2026-07-02 20:45 **Duration**: 2 minutes

**Notes**:

* Added `Upstream To AI OS Owner Mapping` with stable `MAP-001` through `MAP-017` rows.
* Mapped each actionable upstream change area to existing AI OS owner files and the later Phase 40 session that should implement it.
* The mapping explicitly avoids assigning ownership to upstream monolithic route or Vite middleware files.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Added upstream-to-owner mapping and T013 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T013 complete after evidence was recorded.

**Verification**:

* Command/check: Manual check against `.spec_system/PRD/phase_40/PRD_phase_40.md` upstream inventory and current AI OS mapping.
  * Result: PASS - actionable areas are assigned to AI OS owner files and downstream sessions.
  * Evidence: Mapping includes models, provider readiness, redaction, chat overrides, SSE diagnostics, command endpoint, MoA save, connections, catalog/context, pricing, assets, selector, compact flow, Ministry, voice, and docs closeout.
* Command/check: Manual no-monolith-copy check.
  * Result: PASS - no row assigns implementation to upstream `src/routes/agents.hermes.tsx` or upstream `vite.config.ts`.
  * Evidence: Rows cite current AI OS files only.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T012 - Record decision list for diagnostics, pricing, probes, voice keys, graph ignores, demo data, assets, metadata, and labels

**Started**: 2026-07-02 20:40 **Completed**: 2026-07-02 20:42 **Duration**: 2 minutes

**Notes**:

* Added `Decision List` with stable `DEC-001` through `DEC-012` IDs.
* Decisions cover the requested topics plus two implementation-critical follow-ons: structured YAML writes, model body compatibility, and shared sanitizer ownership.
* Every decision includes rationale and downstream Phase 40 session reference.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Added decision ledger and T012 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T012 complete after evidence was recorded.

**Verification**:

* Command/check: Manual check of `Decision List` against folded Phase 40 findings and T003 through T009 evidence.
  * Result: PASS - all required decision topics are represented with stable IDs.
  * Evidence: Decisions include stderr `info`, live pricing, connection probes, voice key persistence, graph ignores, demo data, asset handling, package metadata, and Intelligence/Voice labels.
* Command/check: Manual downstream-session check against Phase 40 session split.
  * Result: PASS - each decision points at a relevant later session.
  * Evidence: Session references cover Sessions 02 through 17 where corresponding implementation belongs.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T011 - Record non-negotiable port invariants with stable IDs

**Started**: 2026-07-02 20:37 **Completed**: 2026-07-02 20:39 **Duration**: 2 minutes

**Notes**:

* Added `Port Invariants` with stable `INV-001` through `INV-015` IDs.
* Covered required boundaries for loopback, Host header, same-run token, admin gate, public/demo, chat SSE, graph, media, package identity, docs naming, voice credentials, model data, route shell, redaction, and upstream translation.
* These invariant IDs are intended to be cited by later Phase 40 implementation sessions.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Added stable invariant table and T011 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T011 complete after evidence was recorded.

**Verification**:

* Command/check: Manual check of `Port Invariants` against T004 through T009 evidence.
  * Result: PASS - every required invariant category from T011 is represented by a stable ID.
  * Evidence: Invariants include loopback, Host-header, same-run token, admin, public/demo, chat SSE, graph, media, package identity, and docs naming.
* Command/check: Manual ASCII check while editing.
  * Result: PASS - invariant text uses ASCII characters only.
  * Evidence: No non-ASCII punctuation was introduced in the new table.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no UI changed.

***

### Task T010 - Create baseline audit notes with upstream evidence summary, local command baseline, and focused Hermes baseline test slots

**Started**: 2026-07-02 20:33 **Completed**: 2026-07-02 20:36 **Duration**: 3 minutes

**Notes**:

* Added `Baseline Audit Notes` with upstream evidence summary, local command baseline, and focused baseline test slots.
* The test slots intentionally name the exact T017, T018, T019, and T020 checks so later task logs can fill outcomes without changing the implementation scope.
* No production source, package metadata, docs, graph data, or UI was changed.

**Files Changed**:

* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md` - Added consolidated baseline audit notes and T010 evidence.
* `.spec_system/specs/phase40-session01-baseline-and-port-invariants/tasks.md` - Marked T010 complete after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,220p' .spec_system/specs/phase40-session01-baseline-and-port-invariants/implementation-notes.md`
  * Result: PASS - baseline audit notes are present.
  * Evidence: File now contains `Upstream Evidence Summary`, `Local Command Baseline`, and `Focused Hermes Baseline Test Slots`.
* Command/check: Manual consistency check against T001 through T009 evidence in this file.
  * Result: PASS - consolidated notes match previously recorded evidence.
  * Evidence: Upstream patch/stat/name-status, package/runtime baseline, asset size gate, and git baseline are copied from completed task logs.
* UI product-surface check: N/A - no route, component, or route-visible UI changed.
* UI craft check: N/A - no 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-session01-baseline-and-port-invariants/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.