> 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-session02-hermes-bridge-status/spec.md).

# Session Specification

**Session ID**: `phase41-session02-hermes-bridge-status` **Phase**: 41 - Hermes All-Access Remediation **Status**: Complete **Created**: 2026-07-03 **Base Commit**: 570957c7d2dfcdf8568e48e0ae23a84c0ea244c3

***

## 1. Session Overview

This session converts Hermes admin bridge status and write preflight behavior from the legacy manual admin gate to the Phase 41 local all-access contract. It is next because Session 01 established `AI_OS_LOCAL_ALL_ACCESS=1` at startup, while the Hermes admin bridge and browser parser still describe and enforce readiness through `HERMES_DASHBOARD_ADMIN`.

The work keeps local defenses intact: loopback or exact local Host checks, same-run token checks, method checks, schema validation, bounded bodies, timeouts, sanitized errors, no-shell argv, and path confinement remain the security boundary for privileged Hermes routes. The legacy admin env key may remain as a compatibility alias, but its absence must not block normal local Hermes writes.

The session is limited to server status, preflight readiness, browser parser contracts, sensitive-read token reporting checks, focused fixtures, and tests. Route mode renames, hook capability language, visual component naming, and Hermes shell copy sweeps stay assigned to later Phase 41 sessions.

***

## 2. Objectives

1. Make `/__hermes_admin_status` report local write readiness by default under the Session 01 all-access startup contract.
2. Make Hermes mutating endpoints reject only real blockers such as method, loopback, token, production, explicit local access disablement, or dependency failures.
3. Update the browser status parser to distinguish local all-access readiness, legacy compatibility, and named blocked states without making `HERMES_DASHBOARD_ADMIN` the normal gate.
4. Add focused tests proving default local writes are not rejected solely because the legacy manual admin env key is absent.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase41-session01-local-access-startup-contract` - Provides the canonical startup env owner and local all-access default.

### Required Tools Or Knowledge

* Hermes admin bridge route registration and preflight behavior in `scripts/lib/hermes-admin-bridge.ts`.
* Hermes admin browser parser behavior in `src/lib/hermes-admin-types.ts`.
* Hermes sensitive-read token behavior in `scripts/lib/hermes-dev-bridge.ts`.
* Existing Vitest patterns in `scripts/lib/__tests__/` and `src/lib/__tests__/`.

### Environment Requirements

* No real `.env.local`, generated private data, credentials, bearer tokens, local logs, coverage, browser reports, or raw operator data are edited or committed.
* Tests must use fixture tokens and temporary directories only.

***

## 4. Scope

### In Scope (MVP)

* AI OS local operators can see Hermes admin status report write-ready local behavior by default - update server status readiness and compatibility fields.
* AI OS local operators can use Hermes mutating routes under normal local all-access readiness - update preflight so legacy manual env absence is not the blocker.
* Browser code can parse the new status contract safely - update parser-owned types and tests for local-ready, legacy-compatible, production, token, loopback, and disabled states.
* Maintainers can prove sensitive reads remain token-gated - inspect and adjust `scripts/lib/hermes-dev-bridge.ts` only where status or token reporting still implies manual admin setup.
* Maintainers can rely on focused tests for success, token failure, production, demo/privacy fixture status, offline or dependency-style failure states, and parser regressions.

### Out Of Scope (Deferred)

* Hermes route mode rename to `live-local` and hook capability semantics - Reason: Session 03 owns route modes and hook readiness.
* Hermes shell component names and product copy sweep - Reason: Session 07 owns visual identity cleanup.
* Hermes mutation-control UX and broader action controls - Reason: Session 08 owns mutation controls.
* Knowledge Graph, Voice, Intelligence, OpenClaw, Claude Code, local-agent, public demo, extension, docs, archive, and generated-data closeout work - Reason: Sessions 04 through 17 own those surfaces.

***

## 5. Technical Approach

### Architecture

Reuse the Session 01 local access env owner from `scripts/lib/local-access-env.ts` inside the Hermes admin bridge. The bridge should compute a single local write readiness decision from production status, canonical local all-access state, and the legacy `HERMES_DASHBOARD_ADMIN` compatibility alias. `isHermesAdminEnabled` can remain as a compatibility export during the migration, but its behavior must reflect local write readiness rather than manual env presence alone.

The status response should expose local readiness with explicit fields such as write readiness, local access mode, compatibility alias state, token requirement, dev-only status, and named blockers. Preserve a compatibility boolean for existing consumers until Session 03 moves hooks and route modes to the final names, but stop presenting `HERMES_DASHBOARD_ADMIN` as the normal write gate.

The browser parser remains the contract boundary. It should parse the expanded status response with strict types, keep malformed payloads out of hooks and UI, and keep error parsing explicit for token, loopback, production, disabled, and dependency-style failures. Server tests should cover the status route and at least representative mutating routes so the old `admin_disabled` default cannot silently return.

### Design Patterns

* Parser-owned bridge contract: Server response shape and browser parser tests move together.
* Compatibility export: Existing `isHermesAdminEnabled` and `adminEnabled` consumers remain compiling while their semantics move toward local readiness.
* Preflight as boundary owner: Method, loopback, token, and readiness checks stay centralized before write handlers run.
* Fixture-safe tests: Use temporary directories, fixture tokens, and sanitized payloads instead of real Hermes homes or credentials.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                                                                        | Est. Lines |
| ---- | -------------------------------------------------------------------------------------------------------------- | ---------- |
| None | No new production files are required; this session modifies existing bridge, parser, fixture, and test owners. | \~0        |

### Files To Modify

| File                                                | Changes                                                                                                                                                  | Est. Lines |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-admin-bridge.ts`                | Replace manual admin-gate readiness with local all-access readiness, expand status payload, preserve preflight defenses, and keep compatibility exports. | \~140      |
| `src/lib/hermes-admin-types.ts`                     | Update status body types and parser behavior for local all-access readiness, compatibility alias state, and named blockers.                              | \~90       |
| `scripts/lib/hermes-dev-bridge.ts`                  | Adjust sensitive-read token reporting only where it still implies manual admin setup; preserve token-gated reads.                                        | \~30       |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts` | Add focused server tests for default local readiness, production/disabled/token/loopback failures, and representative mutating routes.                   | \~240      |
| `src/lib/__tests__/hermes-admin-types.test.ts`      | Add parser tests for local-ready, legacy-compatible, production/blocked, and malformed status payloads.                                                  | \~100      |
| `scripts/lib/__tests__/hermes-dev-bridge.test.ts`   | Add or update sensitive-read regressions proving reads stay token-gated without manual admin setup copy.                                                 | \~50       |
| `tests/e2e/fixtures/hermes-mission-control.ts`      | Refresh Hermes admin-status fixture payloads to match the parser contract without expanding route-mode or UI-copy scope.                                 | \~35       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `/__hermes_admin_status` reports write-ready local behavior without manual `HERMES_DASHBOARD_ADMIN=1`.
* [ ] Mutating Hermes routes do not return `admin_disabled` solely because the legacy admin env key is absent when local all-access readiness is active.
* [ ] Production, explicit local access disablement, loopback failure, token failure, and dependency-style failures remain named blockers with recovery-ready error codes.
* [ ] Browser parser tests lock the expanded status contract and reject malformed status payloads.
* [ ] Sensitive Hermes reads remain token-gated and do not expose private data or raw token material.

### Testing Requirements

* [ ] Focused server tests written and passing for Hermes admin status and representative mutating route preflights.
* [ ] Focused parser tests written and passing for the new status contract.
* [ ] Focused dev bridge tests confirm sensitive read token behavior remains intact.

### Non-Functional Requirements

* [ ] No privileged route weakens loopback, Host-header, same-run token, method, body-size, schema, timeout, safe-error, redaction, no-shell argv, or path confinement controls.
* [ ] No browser-facing status or fixture exposes provider keys, bearer tokens, auth JSON, raw prompts, transcripts, raw command output, private paths, or local usernames.
* [ ] No route mode, hook capability, or visual product copy cleanup is pulled forward from later sessions except compile-safe compatibility required by the parser contract.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Primary targeted tests pass

***

## 8. Implementation Notes

### Working Assumptions

* The server status response should keep a compatibility `adminEnabled` boolean until Session 03 updates hook and route semantics: `src/hooks/use-hermes-admin.ts` currently consumes `adminEnabled`, while Session 03 owns hook readiness. Planning can proceed because the boolean can be redefined to mean local write readiness and supplemented with clearer status fields.
* Explicit `AI_OS_LOCAL_ALL_ACCESS=0` remains a named local-disablement exception when no compatibility alias reopens the route: Session 01 helper already normalizes falsey local access values, and Phase 41 allows named exceptions. Planning can proceed because normal unset local startup remains all-access by default.
* No database-layer work is needed: The PRD, conventions, and analyzer confirm this is a single-package app with no DB service, migrations, ORM, or schema artifact.

### Conflict Resolutions

* `.spec_system/PRD/PRD_UX.md` still describes older Hermes agent pages with read-only/default-off admin boundaries, while AGENTS, Phase 41 PRD, `.spec_system/CONSIDERATIONS.md`, and the Session 02 stub require all-access local readiness. The Phase 41 local all-access policy wins for this session; older UX language is a migration target for later UI/docs sessions.
* Session 01 derived legacy aliases through Vite startup for compatibility, while Session 02 requires the bridge itself to stop treating the legacy alias as the normal gate. The chosen interpretation is to preserve the alias as compatibility but make canonical local all-access readiness the default server decision.

### Key Considerations

* `src/data/live-data.json` is generated and gitignored; this session must not edit it.
* Browser-facing status and test fixtures must use safe labels and fixture tokens only.
* Keep `AI_OS_*` as the canonical host namespace and do not add new global `findtrend` identifiers.

### Potential Challenges

* Existing hook and component tests may still talk about admin gates: keep this session focused on parser and server status, and only update consumer fixtures needed for compile/test compatibility.
* Broad mutation coverage can grow beyond the 2-4 hour target: test a representative set of mutating routes that share `requirePreflight`, then rely on centralized preflight coverage for the rest.
* Production and demo/privacy states use different layers: cover production in the server bridge and demo/privacy through parser or fixture status payloads without adding hosted runtime behavior.

### Relevant Considerations

* \[P41] **Local access default migration**: Hermes must stop treating manual admin env setup as the default local write gate.
* \[P41] **Do not accept scaffolding as delivery**: The plan includes real status/preflight behavior plus focused tests, not labels alone.
* \[P38/P40] **Local control-plane gates are defense in depth**: Loopback, Host-header, token, schema, timeout, redaction, no-shell argv, and path confinement remain required.
* \[P40/P41] **Write safeguards are reusable**: The migration should reuse existing write safeguards while removing manual opt-in posture.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Access-controlled writes accidentally become broader than loopback and same-run token authorization.
* Browser parser accepts ambiguous status payloads and lets hooks treat blocked states as ready.
* Sensitive read endpoints lose token protection or leak private paths while status wording changes.

***

## 9. Testing Strategy

### Unit Tests

* Test local all-access readiness with no legacy admin env key set.
* Test explicit production and explicit local-disablement status blockers.
* Test parser handling for local-ready, legacy-compatible, blocked, and malformed status payloads.

### Integration Tests

* Test representative Hermes mutating routes through the registered middleware with method, loopback, token, and readiness permutations.
* Test sensitive Hermes reads still require a valid same-run token and public reads remain token-free where already intended.

### Runtime Verification

* Run `bun run test -- scripts/lib/__tests__/hermes-admin-bridge.test.ts src/lib/__tests__/hermes-admin-types.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts`.
* Run `bun run typecheck:scripts` if server-side type changes touch scripts.
* Run `bun run typecheck` if browser parser types or fixture payloads change.

### Edge Cases

* Unset `AI_OS_LOCAL_ALL_ACCESS` is ready in non-production local dev because Session 01 made it the default local contract.
* Explicit legacy `HERMES_DASHBOARD_ADMIN=1` remains a compatibility alias during migration.
* Invalid token, hostile Host, non-loopback socket, wrong method, oversized body, invalid payload, provider auth failure, missing setup, timeout, and unavailable Hermes dependency still fail closed.
* Demo/privacy payloads remain labeled exceptions and do not imply local all-access is unavailable.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase41-session01-local-access-startup-contract`
* Depended by: `phase41-session03-hermes-route-modes-and-hooks`, `phase41-session04-knowledge-graph-write-path`, `phase41-session05-voice-token-bootstrap`, `phase41-session08-hermes-mutation-controls`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# 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-session02-hermes-bridge-status/spec.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.