> 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/phase19-session01-mission-control-write/spec.md).

# Session Specification

**Session ID**: `phase19-session01-mission-control-write` **Phase**: 19 - Hermes Orchestration And Documents **Status**: Not Started **Created**: 2026-06-02

***

## 1. Session Overview

This session adds Mission Control as the next Hermes tab in `/agents/hermes`. The work ports the v2.3 Mission Control feature into the existing AI OS Hermes architecture instead of copying the v2.3 standalone component. The UI consumes the current `useHermes` mission query view, demo fixtures, and `useHermesAdmin` mission mutations, so read and write behavior stays routed through the Phase 16 contracts.

Mission Control is a full write/orchestration surface. It renders the active mission state, supports mission creation and optimization, lets the operator tick goals, and clears the active mission only after confirmation. The optimize operation is the highest-risk path because the bridge executes Hermes through an args-array spawn; this session verifies and relies on the already-implemented admin bridge safety tests while keeping browser output sanitized and bounded.

This is the first Phase 19 session. It is sequenced after the completed Phase 16 backend/write-safety foundation, Phase 17 shell and core writes, and Phase 18 memory/visualization work. Session 02, Documents Gallery, remains deferred.

***

## 2. Objectives

1. Add a `Mission` tab to the Hermes page with live and demo mission states.
2. Build a modular Mission Control component that handles loading, empty, error, offline, token-failure, success, and demo states explicitly.
3. Wire create, optimize, tick, and clear writes through `useHermesAdmin` with admin gating, duplicate-trigger prevention, scoped rollback, confirmation, and state reset on close.
4. Extend focused component, page mode-matrix, and browser route coverage for the Mission tab.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the Hermes architecture decision and porting guardrails.
* [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides missions read/write endpoints and spawn/path/confirmation security tests.
* [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed mission query/admin contracts and demo fixtures.
* [x] `phase17-session01-visual-system-shell-status-pill` - Provides the Hermes shell, tab framework, visual primitives, and status affordances.
* [x] `phase17-session02-chat-tab-write` - Provides the established admin write UI pattern and duplicate-trigger guard expectations.
* [x] `phase17-session03-pantheon-upgrade-write` - Provides admin-gated form, validation, and mutation feedback patterns.
* [x] `phase18-session01-memory-upgrade-write` - Provides the current Memory write surface and bounded local-path feedback patterns.
* [x] `phase18-session02-mnemosyne-constellation-readonly` - Provides the latest Hermes tab composition and mode-matrix coverage pattern.

### Required Tools/Knowledge

* React 19, TanStack Query, Radix Tabs, Tailwind CSS 4, lucide-react.
* Existing Hermes hooks in `src/hooks/use-hermes.ts` and `src/hooks/use-hermes-admin.ts`.
* Existing mission contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`.
* Existing Hermes visual primitives in `src/components/hermes/hermes-page-primitives.tsx`.
* v2.3 source anchor: `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mission-control.tsx`.

### Environment Requirements

* Bun 1.3.14 project environment.
* No live Hermes installation or admin token is required for automated tests.
* Live writes require local dev, loopback access, a successful token handshake, and `HERMES_DASHBOARD_ADMIN=1`.

***

## 4. Scope

### In Scope (MVP)

* Operator can open a `Mission` tab in `/agents/hermes` - add a tab trigger and content panel in `src/components/hermes/hermes-read-only-page.tsx`.
* Operator can inspect the active mission and mission list - render `HermesMissionsBody` with active mission summary, deadline, progress, mini-goal cards, and safe empty/error states.
* Operator can create a mission manually - use `admin.missions.createMission` with validated required fields, at least one mini-goal, admin gating, and duplicate-trigger prevention while in-flight.
* Operator can optimize a mission prompt - use `admin.missions.optimizeMission` with bounded prompt input, admin gating, mutation feedback, and existing backend spawn-safety coverage.
* Operator can tick a goal - use `admin.missions.tickGoal` with validated goal id, per-goal in-flight disabled state, confetti on successful completion, reduced-motion safety, and scoped rollback on error.
* Operator can clear the active mission - use `admin.missions.clearMission` only after explicit confirmation, with dialog/form state reset on close.
* Demo mode shows mission fixture data but keeps all write affordances disabled with an admin-mode-required or demo-mode hint.
* Tests cover live/demo rendering, admin-disabled states, form validation, duplicate-trigger prevention, rollback, confirmation, and mode-matrix tab wiring.

### Out of Scope (Deferred)

* Documents Gallery - Reason: owned by Phase 19 Session 02.
* New mission server endpoints or bridge behavior - Reason: Phase 16 Session 02 already landed the endpoint and security foundation.
* Raw v2.3 component/file parity - Reason: AI OS ports features into modular typed components rather than copying the v2.3 monolith.
* Mission state polling with raw `setInterval` or raw fetch bypasses - Reason: the component should use hook/query invalidation and existing admin mutation invalidation.
* Non-Hermes Claude Code mission route work - Reason: owned by Phase 23.

***

## 5. Technical Approach

### Architecture

Create `src/components/hermes/hermes-mission-control.tsx` as a focused tab component. It receives `missions: HermesQueryView<HermesMissionsBody>`, `admin: UseHermesAdminResult`, and `demoMode: boolean`. It derives display state locally, uses existing Hermes primitives for section structure and state badges, and routes every write through `admin.missions`.

`HermesReadOnlyPage` will expose `hermes.missions` in live mode and `HERMES_DEMO_MISSIONS` in demo mode, then add a Mission tab before Memory or near the other write-capable tabs. The page continues to own demo/live mode and the admin hook, while Mission Control owns only the mission-specific UI.

For refresh behavior, the component may use TanStack Query invalidation for `HERMES_QUERY_KEYS.missions`. It must not call the Hermes bridge directly with raw `fetch`; direct network calls remain in hooks and admin bridge utilities.

### Design Patterns

* Existing hook contract: consume `useHermes` and `useHermesAdmin` views rather than adding endpoint clients.
* Admin boundary: writes are disabled unless `admin.canUseAdmin` is true and demo mode is false.
* Stateful write safety: prevent duplicate submits while a mission mutation is pending, roll back optimistic tick state on error, and reset form/dialog state on close.
* Exhaustive states: render explicit loading, empty, error, offline, token-failure, success, and demo states.
* Bounded output: display sanitized, length-capped errors and never render raw local paths, command bodies, tokens, or private output.

### Technology Stack

* React 19 with TypeScript.
* TanStack Query invalidation through existing query keys.
* Radix Tabs plus existing local UI primitives.
* `canvas-confetti` `^1.9.4` for success feedback, with reduced-motion safety.
* Vitest, Testing Library, and Playwright for validation.

***

## 6. Deliverables

### Files to Create

| File                                                                                 | Purpose                                                                                             | Est. Lines |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-mission-control.tsx`                                   | Mission Control tab UI, state rendering, create/optimize/tick/clear controls, and mutation feedback | \~560      |
| `src/components/hermes/__tests__/hermes-mission-control.test.tsx`                    | Focused component tests for mission state, admin gating, forms, writes, rollback, and confirmation  | \~280      |
| `.spec_system/specs/phase19-session01-mission-control-write/implementation-notes.md` | Implementation evidence, source anchors, safety decisions, and validation commands                  | \~90       |

### Files to Modify

| File                                                       | Changes                                                                               | Est. Lines |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-read-only-page.tsx`          | Add Mission tab, demo mission view, icon import, and component wiring                 | \~60       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Extend page mode-matrix fixtures and assertions for Mission tab live/demo transitions | \~100      |
| `tests/e2e/hermes-agent.spec.ts`                           | Add mocked browser route coverage for the Mission tab and admin-disabled affordance   | \~60       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `Mission` appears as a Hermes tab and renders live/demo mission data.
* [ ] Loading, empty, error, offline, token-failure, success, and demo states render explicit, user-visible states.
* [ ] Create, optimize, tick, and clear writes all go through `useHermesAdmin`; no raw mission `fetch` calls are introduced in the component.
* [ ] Write controls are disabled in demo mode, without admin mode, while offline, while token-gated, and while the relevant mutation is pending.
* [ ] Clear requires explicit confirmation and resets confirmation state when dismissed.
* [ ] Tick uses scoped optimistic state with rollback on error and reduced-motion safe confetti only on successful completion.
* [ ] Optimize relies on the existing args-array spawn bridge path and focused bridge/admin tests remain passing.

### Testing Requirements

* [ ] Focused component tests cover mission rendering, form validation, admin-disabled hints, duplicate-trigger prevention, rollback, confirmation, and demo mode.
* [ ] `hermes-sections.test.tsx` covers Mission tab wiring through live and demo transitions.
* [ ] E2E coverage opens `/agents/hermes`, switches to Mission, and verifies the mocked read/admin-disabled path without horizontal overflow.
* [ ] Focused admin hook or bridge tests for mission writes are run or existing coverage is documented in implementation notes.

### Non-Functional Requirements

* [ ] No new bridge endpoint, personal-data store, third-party transfer, or production write surface is introduced.
* [ ] Browser-visible errors are redacted, bounded, and do not expose raw paths, command output, prompt bodies, tokens, or credentials.
* [ ] UI controls have platform-appropriate accessibility labels, keyboard support, and stable responsive dimensions.
* [ ] No new heavyweight dependency is added.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new global `findtrend` identifiers.
* [ ] Focused tests, typecheck, lint, and relevant browser proof pass or any unrelated pre-existing failure is documented.

***

## 8. Implementation Notes

### Key Considerations

* The v2.3 component directly fetches `/__hermes_missions` and token-fetches writes. The AI OS port must use `useHermes` and `useHermesAdmin` instead.
* `HERMES_DEMO_MISSIONS` already exists and should be wired into demo mode.
* `src/hooks/use-hermes-admin.ts` already invalidates missions after successful mutations, so the component should avoid duplicate cache ownership.
* Mission optimize is a command-exec write, but the browser component should only pass a bounded prompt to the existing admin mutation.
* Use existing mission assets already copied under `src/assets/hermes-art/` and `src/assets/claude-art/`; do not add new media unless validation proves it is required.

### Potential Challenges

* The v2.3 component is large and visually dense: port the behavior and useful visual cues, not the whole file structure.
* Optimistic goal ticks can drift from the server: roll back or revalidate after mutation failure.
* Mission creation can become an underspecified form: require title plus at least one mini-goal and keep optional fields bounded.
* Admin-disabled states can look broken if write controls simply disappear: keep controls visible, disabled, and labeled with the reason.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: Writes stay behind loopback, token checks, and explicit admin mode.
* \[P08] **Local agent privacy/readiness boundary**: Do not expose prompts, command output, raw paths, auth payloads, or workspace content.
* \[P11] **Scheduler state/log privacy boundary**: Status output should remain safe labels and bounded metadata only.
* \[P17] **One write surface per capability**: Mission writes belong in the Mission tab, not duplicated in the Admin panel.
* \[P18] **Do not collapse non-success query states into empty UI**: Loading, error, offline, and token-failure states must be explicit.
* \[P00] **Stack conventions**: Keep Bun, Vite, TanStack Start, React 19, Radix UI, and Cloudflare compatibility constraints intact.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Create, optimize, tick, and clear are write paths and need duplicate-trigger prevention while in-flight.
* Goal ticking can create misleading local state unless rollback and revalidation are explicit.
* Clear is destructive and needs confirmation plus state reset on close.
* Remote mission data can be loading, empty, error, offline, token-failure, live, or demo, and each state needs first-class UI.

***

## 9. Testing Strategy

### Unit Tests

* Test `HermesMissionControl` for active mission progress, empty state, demo state, all non-success query states, form validation, admin-disabled hints, create/optimize/tick/clear callbacks, duplicate-trigger prevention, rollback, and confirmation reset.
* Extend `hermes-sections.test.tsx` so the Mission tab is present and renders live/demo fixture data through `HermesReadOnlyPage`.

### Integration Tests

* Run focused component tests for Mission Control and Hermes sections.
* Run existing mission admin hook or bridge tests to prove create, optimize, tick, and clear safety coverage still passes.
* Run `bun run typecheck`, `bun run lint`, and any focused e2e browser proof required by the implementation.

### Manual Testing

* Visit `/agents/hermes`, open `Mission`, and verify live/setup-required/demo states.
* In a local admin-enabled environment, create a mission, optimize a prompt, tick a goal, and clear the mission after confirmation.
* Resize from desktop to mobile widths and confirm tab labels, mission cards, buttons, and forms do not overflow.

### Edge Cases

* No active mission but historical mission list exists.
* Active mission has zero mini-goals, missing optional image path, or a past deadline.
* Create form has blank title or no valid mini-goals.
* Optimize returns an error, timeout, malformed mission, or null mission.
* Tick is triggered repeatedly or fails after local optimistic state.
* Clear dialog closes without confirming, then reopens.
* Demo mode contains mission data but admin writes must remain blocked.

***

## 10. Dependencies

### External Libraries

* `canvas-confetti`: existing dependency for success feedback.
* `lucide-react`: existing dependency for tab and control icons.

### Other Sessions

* **Depends on**: Phase 16 Sessions 01-03, Phase 17 Sessions 01-03, Phase 18 Sessions 01-02.
* **Depended by**: `phase19-session02-documents-gallery-write`, `phase20-session01-connections-stats-long-tail`, and later parity closeout.

***

## Next Steps

Run the implement workflow step to begin AI-led 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/archive/sessions/phase19-session01-mission-control-write/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.