> 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-session01-local-access-startup-contract/spec.md). # Session Specification **Session ID**: `phase41-session01-local-access-startup-contract` **Phase**: 41 - Hermes All-Access Remediation **Status**: Complete **Created**: 2026-07-03 **Base Commit**: 1885d7131bb733ca2fce998061a4f1efa4e92123 *** ## 1. Session Overview This session makes the normal AI OS local startup path establish the canonical `AI_OS_LOCAL_ALL_ACCESS=1` contract before Vite middleware registers Hermes, OpenClaw, voice, Dream, and other local control-plane routes. It is first because every later Phase 41 session depends on a shared startup posture instead of per-surface manual admin opt-ins. The implementation keeps loopback, Host-header, same-run token, schema, timeout, safe-error, redaction, no-shell argv, and path confinement controls as automatic local defenses. Legacy `HERMES_DASHBOARD_ADMIN` and `OPENCLAW_DASHBOARD_ADMIN` remain compatibility aliases, but normal local startup must not require operators to set them manually. The session is limited to startup contracts, Vite bridge env resolution, startup-facing copy, the committed local env template, and focused regression tests. Route mode renames, bridge status response rewrites, and visual copy sweeps remain in later Phase 41 sessions. *** ## 2. Objectives 1. Make `AI_OS_LOCAL_ALL_ACCESS=1` the default normal local startup contract for `bun run dev`. 2. Pass the same local all-access contract through `scripts/dev.sh` and `scripts/cleandev.sh` tmux launches. 3. Resolve Hermes and OpenClaw legacy admin aliases from the all-access contract before middleware evaluates write readiness. 4. Replace startup-facing recovery copy that tells normal local operators to set manual admin env keys. *** ## 3. Prerequisites ### Required Sessions * [x] Phase 40 completed - Provides the current Hermes, OpenClaw, voice, Dream, middleware, and validation baseline. * [x] `phase41-session01-local-access-startup-contract` stub exists - Provides this session's scope, dependencies, and acceptance checks. ### Required Tools Or Knowledge * Bun 1.3.14 and Vite 8 local dev startup behavior from `package.json` and `vite.config.ts`. * Existing shell launch behavior in `scripts/dev.sh` and `scripts/cleandev.sh`. * Local control-plane safety model: loopback, Host-header, same-run token, schema validation, timeout, redaction, no-shell argv, and path confinement. ### Environment Requirements * No real `.env.local`, private generated data, credentials, bearer tokens, or local runtime logs are edited or committed. * Tests must avoid starting long-lived dev servers or tmux sessions unless explicitly isolated. *** ## 4. Scope ### In Scope (MVP) * AI OS local operators can run `bun run dev` and receive all-access startup readiness by default - Update the package script and Vite env resolution. * AI OS local operators can run `scripts/dev.sh` and `scripts/cleandev.sh` with the same startup contract - Export and pass `AI_OS_LOCAL_ALL_ACCESS=1` into tmux-managed Vite processes. * Hermes and OpenClaw bridges can keep legacy admin aliases during migration - Derive legacy alias values from `AI_OS_LOCAL_ALL_ACCESS=1` when unset. * Clean-dev runtime hints report actual missing dependencies, token failures, offline states, or recovery actions - Remove normal-local guidance to set `HERMES_DASHBOARD_ADMIN=1`. * The committed local env template documents `AI_OS_LOCAL_ALL_ACCESS=1` as the normal local contract - Keep legacy admin keys clearly labeled as compatibility aliases. * Focused startup regressions prove `bun run dev`, `scripts/dev.sh`, and `scripts/cleandev.sh` establish the contract - Add tests near script behavior. ### Out Of Scope (Deferred) * Hermes bridge status response rename and parser contract changes - Reason: Session 02 owns `/__hermes_admin_status` and browser parser semantics. * Hermes route mode, hook, and `live-local` rename work - Reason: Session 03 owns route and hook semantics. * Knowledge Graph, Voice, Intelligence, OpenClaw action execution, Claude Code execution, and local-agent capability completion - Reason: Sessions 04 through 11 own those implementation surfaces. * Broad user/developer documentation sweep - Reason: Session 15 owns active docs and runbooks after code behavior is implemented. *** ## 5. Technical Approach ### Architecture Introduce a small, testable local access env owner under `scripts/lib/` that normalizes `AI_OS_LOCAL_ALL_ACCESS` and derives transitional legacy aliases for Vite bridge registration. `vite.config.ts` will read shell, `.env.local`, and `.env` values as it does today, then apply the local access defaults before passing env objects into Hermes and OpenClaw bridge registration. Shell startup remains thin. `scripts/dev.sh` and `scripts/cleandev.sh` should export `AI_OS_LOCAL_ALL_ACCESS=1` when unset and pass it into tmux explicitly with the same pattern already used for `PATH`, enabled extensions, and Dream activation. Clean-dev runtime hints should check local readiness regardless of legacy env files and report real failure dimensions without exposing local paths beyond existing safe labels. ### Design Patterns * Local-first env helper: Keeps canonical env normalization testable without importing `vite.config.ts` and triggering dev-server side effects. * Compatibility alias mapping: Lets existing Phase 40 bridge internals remain functional while later sessions remove manual admin semantics from status and parser contracts. * Static startup regression tests: Proves package and shell launch contracts without starting tmux or leaving a dev server running. * Existing script conventions: Reuse `trim_whitespace`, truthy parsing, `tmux_args`, and Bun/Vitest test placement already present in the repo. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/lib/local-access-env.ts` | Canonical local all-access env normalization and legacy alias resolution helper. | \~90 | | `scripts/lib/__tests__/local-access-startup.test.ts` | Focused regressions for package, Vite, `scripts/dev.sh`, and `scripts/cleandev.sh` startup contract behavior. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Default `bun run dev` to `AI_OS_LOCAL_ALL_ACCESS=1` before seed data and Vite start. | \~1 | | `vite.config.ts` | Apply local all-access env defaults before Hermes and OpenClaw bridge env objects are evaluated. | \~30 | | `scripts/dev.sh` | Export `AI_OS_LOCAL_ALL_ACCESS=1` when unset and pass it into the tmux Vite server. | \~12 | | `scripts/cleandev.sh` | Export and pass the all-access contract into tmux; update Hermes runtime hint failures to name real dependency, token, or readiness blockers. | \~40 | | `.env.local.example` | Document `AI_OS_LOCAL_ALL_ACCESS=1` as the normal local contract and mark legacy admin keys as compatibility aliases. | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `bun run dev` establishes `AI_OS_LOCAL_ALL_ACCESS=1` for seed and Vite startup when the operator has not set it. * [ ] `scripts/dev.sh` starts tmux with `AI_OS_LOCAL_ALL_ACCESS=1` and does not require `HERMES_DASHBOARD_ADMIN` or `OPENCLAW_DASHBOARD_ADMIN`. * [ ] `scripts/cleandev.sh` starts tmux with `AI_OS_LOCAL_ALL_ACCESS=1` in default and configured launch profiles. * [ ] Vite Hermes and OpenClaw bridge env objects receive write-ready compatibility aliases when `AI_OS_LOCAL_ALL_ACCESS=1` is active and legacy aliases are unset. * [ ] Clean-dev runtime hint output no longer tells normal local operators to set `HERMES_DASHBOARD_ADMIN=1`. ### Testing Requirements * [ ] Unit tests written and passing for local access env normalization and legacy alias resolution. * [ ] Static startup tests prove `package.json`, `scripts/dev.sh`, `scripts/cleandev.sh`, and `vite.config.ts` carry the contract. * [ ] Focused regression command passes for `scripts/lib/__tests__/local-access-startup.test.ts`. ### Non-Functional Requirements * [ ] Existing loopback, Host-header, same-run token, schema, timeout, safe-error, redaction, no-shell argv, and path confinement controls remain documented in code and unweakened. * [ ] No `.env.local`, generated private data, logs, coverage, browser reports, or local runtime artifacts are modified or committed. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions *** ## 8. Implementation Notes ### Working Assumptions * Session 01 should derive legacy admin alias values from `AI_OS_LOCAL_ALL_ACCESS=1` for Vite bridge registration: The current Hermes and OpenClaw bridge internals still check `HERMES_DASHBOARD_ADMIN` and `OPENCLAW_DASHBOARD_ADMIN`, and Sessions 02 and 09 own replacing those internal contracts. Planning can proceed because this preserves write-ready startup behavior now without expanding Session 01 into bridge parser rewrites. * Static startup tests are acceptable for shell launch regressions: Starting tmux and Vite inside unit tests would leave long-lived local processes and require host-dependent ports. Planning can proceed because tests can assert the exact package and shell contracts plus pure helper behavior, while implementation can keep manual runtime smoke optional. ### Conflict Resolutions * Phase 41 PRD minimum implementation direction lists route, hook, UI, Knowledge Graph, Voice, OpenClaw, Claude Code, and docs work together, while the Session 01 stub explicitly limits this session to startup contract work. The session stub and dependency graph win for this run because `plansession` must create one 2-4 hour session and later stubs own those surfaces. * Historical docs still describe manual admin gates, while AGENTS, Phase 41 PRD, and current considerations define all-access as the local default. The current Phase 41 policy wins for startup planning; broad docs remain deferred to Session 15 except for `.env.local.example` and startup-facing script output. ### Key Considerations * `src/data/live-data.json` is generated and gitignored; this session must not edit it. * Browser-facing output and startup hints must use safe labels and avoid raw home-directory paths, prompts, auth JSON, tokens, and local usernames. * `AI_OS_LOCAL_ALL_ACCESS` is the canonical new global identifier; do not add new `findtrend` identifiers. ### Potential Challenges * Existing bridge tests may still encode legacy admin-gate semantics: Keep Session 01 focused on startup env delivery and add tests that prove Vite provides compatibility values; leave server response semantics for Session 02 and OpenClaw execution semantics for Session 09. * Shell parsing can drift from TypeScript helper behavior: Keep the shell default simple, `AI_OS_LOCAL_ALL_ACCESS=${AI_OS_LOCAL_ALL_ACCESS:-1}`, and test for the literal export and tmux propagation. ### Relevant Considerations * \[P41] **Local access default migration**: Startup must default to full local read/write/edit access and treat legacy manual gates as migration compatibility only. * \[P41] **Do not accept scaffolding as delivery**: The plan includes concrete startup behavior and 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 stay in place. * \[P40/P41] **Write safeguards are reusable**: Compatibility mapping must preserve existing token and structured write safeguards while removing manual admin opt-in as the normal local posture. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Startup env drift between `bun run dev`, `scripts/dev.sh`, `scripts/cleandev.sh`, and Vite bridge registration. * Legacy alias compatibility accidentally weakening production, hosted demo, token, loopback, or dependency failure handling. * Clean-dev hints hiding real startup failures behind old manual admin setup guidance. *** ## 9. Testing Strategy ### Unit Tests * Test local access helper defaults unset env to `AI_OS_LOCAL_ALL_ACCESS=1`. * Test legacy Hermes and OpenClaw alias resolution derives compatibility values only from the canonical all-access contract when aliases are unset. * Test explicit legacy alias values remain accepted for compatibility during the migration. ### Integration Tests * Add static startup contract tests that read `package.json`, `scripts/dev.sh`, `scripts/cleandev.sh`, and `vite.config.ts` and assert the all-access contract is present in launch paths. * Update any focused script tests only if they directly assert the old manual admin startup posture. ### Runtime Verification * Run `bun run test -- scripts/lib/__tests__/local-access-startup.test.ts`. * Run `bun run typecheck:scripts` if helper types touch script TypeScript compilation. ### Edge Cases * Existing operator-set legacy aliases still work as compatibility aliases. * `NODE_ENV=production`, public demo/privacy modes, token failures, loopback failures, missing dependencies, and offline services remain named blockers in later bridge layers. * Clean-dev `--configured`, `--validate-only`, and default restart modes do not diverge in local access env setup. *** ## 10. Dependencies ### Other Sessions * Depends on: Phase 40 completion and Phase 41 PRD/session stubs. * Depended by: `phase41-session02-hermes-bridge-status`, `phase41-session09-openclaw-action-execution`, `phase41-session10-claude-code-execution`, `phase41-session12-public-demo-setup-and-dream-modes`, `phase41-session13-extension-and-compliance-boundaries`, and later Phase 41 closeout sessions. *** ## Next Steps Run the `creview` workflow step. --- # 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-session01-local-access-startup-contract/spec.md?ask=&goal= ``` `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.