> 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/phase25-session07-mission-archive-actions/spec.md).

# Session Specification

**Session ID**: `phase25-session07-mission-archive-actions` **Phase**: 25 - Hermes Mission Control Activation **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session makes the Mission Control archive actionable. Previous Phase 25 sessions restored preview-to-commit mission writes, versioned mission storage, safe planning prompts, multi-goal authoring, per-goal prompt copying, and the active mission execution rail. The remaining product gap is that older missions are visible in the archive but cannot be made active again.

The implementation adds an admin-gated set-active/reactivate path over the existing `missions.json` store. It should change only the active mission pointer after validating the target mission exists. It must not rebuild mission documents through the commit path, change mission schema, add archive deletion, or weaken the existing loopback, token, admin-mode, non-demo, and hook-mediated write boundary.

The user-facing result is a Mission archive where the active mission is clearly marked, inactive missions expose a safe "Set active" or "Reactivate" action, and replacing a different active mission requires explicit confirmation. All archive actions share the existing Mission Control feedback, busy, redaction, and Hermes/Claude Code presentation patterns.

***

## 2. Objectives

1. Add a dedicated admin-gated mission set-active write path that validates the target mission and preserves stored mission documents.
2. Extend typed admin contracts and the `useHermesAdmin` hook with a duplicate-safe `setActiveMission` mutation that invalidates mission reads on success.
3. Upgrade the Mission archive UI with active markers, reactivation controls, replacement confirmation, and disabled/busy states.
4. Prove pointer integrity, admin-gate rejection, malformed target handling, duplicate prevention, feedback redaction, and Hermes/Claude Code parity with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase25-session01-mission-write-contract-preview-commit` - provides the guarded mission store writer and active-pointer commit model.
* [x] `phase25-session02-mission-schema-version-legacy-compatibility` - provides normalized mission documents and legacy-safe mission reads.
* [x] `phase25-session05-full-prompt-drawer-copy-briefings` - provides archive mission cards with actionable goal details and copy behavior.
* [x] `phase25-session06-active-mission-rail-progress` - preserves the active mission execution rail and full scan grid that set-active must refresh.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* React 19, TypeScript 6, TanStack Query, Tailwind CSS 4, and local Hermes page primitives.
* Existing Hermes read and admin contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`.
* Existing mission store helpers and admin preflight in `scripts/lib/hermes-admin-bridge.ts`.
* Testing Library and Vitest conventions for hook, bridge, parser, and component tests.

### Environment Requirements

* Work from the repository root.
* No live Hermes credentials are required; tests should use temporary mission stores, mocked fetch, and existing component fixtures.
* Generated private Hermes data, `.env*`, logs, real tokens, and local mission files remain out of git.

***

## 4. Scope

### In Scope (MVP)

* Operators can reactivate an archived mission through a dedicated admin-gated set-active endpoint - validate `missionId`, require loopback, token, admin mode, non-demo UI path, and hook-mediated mutation.
* Operators can trust active pointer integrity - update only `missions.json.active`, reject missing targets, preserve every mission document, and keep atomic store writes.
* Operators can see archive state at a glance - mark the active mission and expose inactive mission actions without hiding the full archive list.
* Operators get replacement confirmation - require explicit confirmation before replacing a different active mission, with state reset on close and re-entry.
* Operators cannot duplicate writes - disable archive actions while any mission create, optimize, commit, tick, clear, or set-active write is in flight.
* Hermes and Claude Code routes stay at parity - share the same set-active contract while preserving route-specific copy and actor labels.
* Failure feedback stays bounded - invalid IDs, missing targets, closed gates, and thrown errors map to safe redacted UI messages.

### Out of Scope (Deferred)

* Bulk archive operations - Reason: Session 07 only needs one mission reactivation at a time.
* Deleting archived missions - Reason: destructive archive management is not required for Phase 25 activation and would need stronger confirmation and storage tests.
* Changing the on-disk mission file location - Reason: the existing `missions.json` store remains the compatibility contract.
* Mission document schema changes - Reason: set-active is pointer management, not mission content migration.
* Route-wide responsive/e2e parity sweep - Reason: Session 08 owns responsive and end-to-end closeout.
* Documentation and release closeout - Reason: Session 09 owns final docs and validation release work.

***

## 5. Technical Approach

### Architecture

Add a new admin request/response pair for mission set-active behavior in `src/lib/hermes-admin-types.ts`. The response should include `ok: true`, `active`, and the selected normalized mission document so the hook can parse a typed payload and tests can assert pointer integrity without reading raw JSON.

Add a dedicated bridge endpoint, proposed as `/__hermes_missions/set-active`, inside `scripts/lib/hermes-admin-bridge.ts`. The endpoint should reuse `requirePreflight`, parse a bounded JSON body, validate `missionId` against the existing mission ID pattern, optionally require a confirmation value when the store already has a different active mission, reject missing target missions, set `store.active = missionId`, and write through `writeMissionStore`.

Extend `useHermesAdmin` with a mission-scoped `setActiveMission` mutation. It should share the existing mission in-flight guard, surface parser/fetch errors through existing mutation views, and invalidate `HERMES_QUERY_KEYS.missions` only after success.

Update `HermesMissionControl` so `MissionList` becomes an actionable archive section. The parent should own target selection, confirmation text/open state, busy action state, and feedback. The archive component should stay presentational: it receives the mission list, active ID, can-edit state, busy state, and callbacks. It should not fetch, mutate, parse raw bridge payloads, or bypass parent redaction.

### Design Patterns

* Pointer-only write: set-active changes the active pointer, not mission documents.
* Boundary validation: request schema and mission IDs are validated in the bridge before any file write.
* Shared hook guard: set-active uses the same mission in-flight ref as create, optimize, commit, tick, and clear.
* Explicit confirmation: replacing an existing active mission requires a typed confirmation value and resets when the confirmation panel closes.
* Query invalidation: successful set-active refreshes mission reads rather than patching query data manually.
* Presentation parity: Hermes and Claude Code differ only through existing presentation copy.
* Bounded UI: archive titles/outcomes remain wrapped, clipped, and accessible on compact viewports.

### Technology Stack

* TypeScript 6.0.3.
* React 19.
* TanStack Query 5 through existing mission query invalidation.
* Tailwind CSS 4 and existing Hermes page primitives.
* Vitest 4.1.6 and Testing Library.

***

## 6. Deliverables

### Files to Create

| File                                                                                   | Purpose                                                                                     | Est. Lines |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase25-session07-mission-archive-actions/implementation-notes.md` | Implementation decisions, command output, manual checks, and known follow-ups.              | \~80       |
| `.spec_system/specs/phase25-session07-mission-archive-actions/security-compliance.md`  | Session security review for set-active pointer writes and unchanged admin-gated boundaries. | \~80       |

### Files to Modify

| File                                                              | Changes                                                                                                                         | Est. Lines |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-admin-bridge.ts`                              | Add set-active endpoint, request validation, target existence check, active-pointer update, and route registration.             | \~140      |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts`               | Cover route registration, success, no-op/current active, invalid IDs, missing targets, confirmation, and closed-gate rejection. | \~180      |
| `src/lib/hermes-admin-types.ts`                                   | Add set-active request/response types and parser.                                                                               | \~80       |
| `src/lib/__tests__/hermes-admin-types.test.ts`                    | Cover set-active parser success and malformed payload rejection.                                                                | \~60       |
| `src/hooks/use-hermes-admin.ts`                                   | Add set-active mutation/view/action with mission in-flight guard and mission query invalidation.                                | \~90       |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`                   | Cover set-active fetch body, duplicate prevention, invalidation, and error handling.                                            | \~120      |
| `src/components/hermes/hermes-mission-control.tsx`                | Add archive actions, confirmation state, busy gating, feedback, and Hermes/Claude Code presentation parity.                     | \~240      |
| `src/components/hermes/__tests__/hermes-mission-control.test.tsx` | Cover archive action UI, confirmation, active markers, busy/disabled states, redacted failures, and route parity.               | \~240      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Mission archive marks the currently active mission distinctly.
* [ ] Inactive archived missions expose a set-active/reactivate action when admin writes are available.
* [ ] Replacing a different active mission requires explicit confirmation.
* [ ] Closing or completing archive confirmation resets target and confirmation state.
* [ ] Set-active rejects malformed mission IDs before changing local state.
* [ ] Set-active rejects missing mission IDs without changing the current active pointer.
* [ ] Set-active preserves all mission documents and updates only the active pointer.
* [ ] Set-active invalidates mission reads only after success.
* [ ] Archive action buttons are disabled in demo, offline, token-failure, admin-disabled, and any in-flight mission write state.
* [ ] Existing create, optimize, import, commit, detail, copy, tick, clear, refresh, demo, error, offline, and token-failure behavior remains unchanged.

### Testing Requirements

* [ ] Parser tests cover set-active response success and malformed payload rejection.
* [ ] Bridge tests cover successful reactivation and pointer integrity.
* [ ] Bridge tests cover invalid ID, missing target, missing confirmation, closed admin gate, invalid token, and remote request rejection.
* [ ] Hook tests cover request body, parser use, mission query invalidation, duplicate prevention, and error surfacing.
* [ ] Component tests cover archive active markers, confirmation, set-active success, busy/disabled states, failure redaction, and Claude Code parity.

### Non-Functional Requirements

* [ ] No mission document schema field is added or changed.
* [ ] No archive delete or bulk operation is introduced.
* [ ] Admin gate strength is unchanged; writes remain loopback, token, admin mode, non-demo, and hook-mediated.
* [ ] Browser-visible archive state contains no token, auth header, local path, raw bridge error detail, or generated private mission file path.
* [ ] Mission archive remains dense, scannable, keyboard reachable, touch friendly, and consistent with the local-agent operator console.
* [ ] Archive text wraps or clips deliberately and cannot create document-level horizontal overflow.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests pass.
* [ ] `bun run typecheck` passes.
* [ ] `bun run lint` passes.

***

## 8. Implementation Notes

### Key Considerations

* A dedicated set-active endpoint is safer than reusing commit because commit currently rebuilds a mission document through `createMissionDocument`. Reactivation should preserve stored mission content and only move the active pointer.
* The bridge already normalizes mission stores on read and writes atomically. Set-active should reuse that path and avoid ad hoc file edits.
* `MissionList` should remain a presentational archive component. Keep hook calls, mutation state, redaction, and query invalidation in the parent/hook layers.
* Confirmation should be required only when replacing a different active mission. Setting the already active mission can return a successful no-op.

### Potential Challenges

* Active pointer and local UI state can diverge after clear or set-active: reset local clear, selected goal, tick overrides, and archive confirmation state after successful reactivation.
* Duplicate mission writes can overlap across create/commit/tick/clear and set-active: reuse the existing mission in-flight ref and `missionBusy` aggregation.
* Error messages from bridge or fetch failures may contain private paths or token-shaped strings: route every UI error through the existing `boundedError` helper.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: The new write path must keep loopback plus token checks, no-clobber path safety, and disabled-by- default admin mode.
* \[P17] **Reuse existing hook contracts for write surfaces**: Extend `useHermesAdmin` instead of calling fetch from Mission Control components.
* \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep the archive component focused and prop-driven so hook-layer contracts stay easy to verify.
* \[P23] **Hermes hook reuse for related agent routes**: Hermes and Claude Code should share the same Mission Control contract and differ only in presentation copy.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* A malformed or missing mission ID could change the active pointer if boundary validation is incomplete.
* A duplicate click could race with another mission write if set-active does not share the existing mission busy guard.
* Confirmation or selected-target state could linger after route/demo/mission changes and activate the wrong mission.

***

## 9. Testing Strategy

### Unit Tests

* Parser tests for set-active response shape, mission schema validation, and malformed payload rejection.
* Hook tests for endpoint path, JSON body, duplicate prevention, mission query invalidation, and error state propagation.

### Integration Tests

* Bridge tests using a temporary `missions.json` store to verify active pointer updates, document preservation, no-op behavior for the current active mission, confirmation requirements, invalid IDs, missing targets, remote rejection, invalid token rejection, and admin-disabled rejection.

### Component Tests

* Mission archive renders active markers and inactive set-active/reactivate buttons.
* Replacement confirmation opens, disables until valid, submits through the hook, resets on close/success, and preserves the existing active rail/grid behavior.
* Failure feedback is redacted and bounded.
* Claude Code route presentation shares the same behavior with route-specific labels.

### Manual Testing

* With fixture/demo mission data, inspect `/agents/hermes` Mission tab for archive layout, action placement, disabled states, and overflow at desktop and mobile widths.
* In live local admin mode, verify reactivating a temporary archived mission updates the active panel and archive marker without deleting other missions.

### Edge Cases

* No active mission and one archived mission.
* Existing active mission replaced by another archived mission.
* User clicks the already active mission action.
* Target mission disappears between confirmation open and submit.
* Admin gate closes or token fails while confirmation is open.
* Very long mission titles and outcomes in archive rows.

***

## 10. Dependencies

### External Libraries

* None. Use existing React, TanStack Query, Testing Library, Vitest, and local UI primitives.

### Internal Dependencies

* `scripts/lib/hermes-admin-bridge.ts` mission store helpers.
* `src/lib/hermes-admin-types.ts` parser helpers.
* `src/hooks/use-hermes-admin.ts` mission mutation guard.
* `src/components/hermes/hermes-mission-control.tsx` archive rendering.
* `HERMES_QUERY_KEYS.missions` for read invalidation.

### Other Sessions

* **Depends on**: `phase25-session01-mission-write-contract-preview-commit`, `phase25-session02-mission-schema-version-legacy-compatibility`, `phase25-session05-full-prompt-drawer-copy-briefings`, `phase25-session06-active-mission-rail-progress`
* **Depended by**: `phase25-session08-claude-code-parity-responsive-e2e`, `phase25-session09-documentation-validation-release`

***

## 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/phase25-session07-mission-archive-actions/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.