> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase19-session03-web-shell-and-store/spec.md).

# Session Specification

**Session ID**: `phase19-session03-web-shell-and-store` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: apps/web **Package Stack**: TypeScript

***

## 1. Session Overview

This session restructures the web orchestration surface in `apps/web` around the Phase 19 command-center contracts now provided by `packages/protocol` and the server command-center scaffold from Session 02. It keeps the existing compact queue, template, lineage, and guarded-action panel usable while adding the API, store, WebSocket, tab, and drawer foundations for the broader command center.

The session is next because Sessions 01 and 02 are complete and later Phase 19 work depends on web clients being able to hydrate command-center snapshots, reduce `command_center_*` events, and render explicit capability states. The implementation must preserve the current Orchestration entry point instead of creating a separate route or landing page.

The web work remains a shell/store foundation. It should show empty, loading, stale revision, unavailable, observe-only, proposal-only, and executor-ready states, but it must not implement deep campaign workbench behavior, blocking permission round trips, executor dispatch, file/git execution, channel intake, or federation workflows owned by later sessions.

***

## 2. Objectives

1. Extend `orchestrationApi` with typed command-center snapshot, capability, mutation, and refresh helpers for the scaffolded `/api/command-center/*` routes.
2. Add normalized Zustand slices and WebSocket reducers for every Session 01 command-center event family emitted by the Session 02 server backbone.
3. Split the current Orchestration surface into a shell, header, tabs, drawer, legacy compact sections, and command-center overview panes while preserving current queue, template, lineage, and guarded-action behavior.
4. Add focused tests for API validation, store hydration/reducers, WebSocket sanitization, component preservation, and command-center empty/unavailable/capability states.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase19-session01-protocol-and-events` - Provides command-center DTOs, REST aliases, compact WebSocket events, capability states, and parser helpers in `packages/protocol`.
* [x] `phase19-session02-server-backbone` - Provides scaffolded command-center managers, `/api/command-center/*` routes, WebSocket hydration, diagnostics counts, and capability envelopes in `apps/server`.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0 workspace commands.
* Current web Orchestration files: `apps/web/src/lib/orchestrationApi.ts`, `apps/web/src/lib/orchestrationUi.ts`, `apps/web/src/store/useGameStore.ts`, `apps/web/src/store/useWsClient.ts`, and `apps/web/src/components/OrchestrationPanel.tsx`.
* Current web tests: `apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/orchestrationStore.test.ts`, `apps/web/tests/orchestrationUi.test.ts`, `apps/web/tests/OrchestrationPanel.test.tsx`, and `apps/web/tests/wsClientPrivacy.test.ts`.
* Protocol command-center types from `packages/protocol/src/orchestrationCommandCenter.ts`, `packages/protocol/src/events.ts`, and `packages/protocol/src/rest.ts`.

### Environment Requirements

* Run from the repository root with dependencies installed.
* No hosted credentials, provider credentials, Cloudflare access, real executors, Docker runtime, terminal PTY runtime, channel webhook secrets, or browser automation is required for this session.

***

## 4. Scope

### In Scope (MVP)

* Web clients can fetch command-center capabilities and snapshots - add typed API methods for plans, tasks, attention, executors, hero lifecycle, executions, permissions, file intents, workpads, evidence, verification, review gates, handoffs, diagnostics, channels, usage, and notification readiness.
* Web clients can call scaffold mutation helpers safely - add generic helpers for existing Session 02 mutation routes with duplicate-trigger protection, expected revision handling, idempotency keys, stale revision mapping, and refresh-on-mutation hooks.
* The Zustand store owns normalized command-center slices - add pure normalizers before store mutation, generatedAt fields, counts, capability envelopes, stale/error state, selected tab/drawer ids, and reset behavior.
* WebSocket input is sanitized before state mutation - parse `command_center_*` frames with schema-shaped checks, compact field preservation, explicit malformed-frame rejection, and broad sensitive text redaction.
* The Orchestration panel is split into focused components - preserve compact queue/templates/lineage/guarded-action rows while adding product-facing command-center tabs and a detail drawer for empty, unavailable, observe-only, proposal-only, and executor-ready states.
* Component and store tests cover current panel preservation plus new snapshot hydration, event reducers, stale revision handling, unavailable states, and malformed WebSocket frame behavior.

### Out Of Scope (Deferred)

* Deep campaign creation, task graph editing, dispatch, pause, resume, retry, refine, or verification flows - Reason: Session 04 owns the campaign workbench.
* Blocking permission request response-file round trips and unified attention decisions - Reason: Session 05 owns attention and permissions.
* Executor registry behavior, execution dispatch, file/git/terminal/container execution, or result persistence - Reason: Sessions 06, 08, and 12 own concrete executor behavior.
* War Room, Notice Board, remote-access, channel/webhook intake, push, hosted identity, or hosted notification behavior - Reason: Sessions 13 through 15 own those integrations and claim boundaries.
* Playwright coverage for mutating flows - Reason: the Session 03 stub explicitly excludes deep mutating-flow Playwright coverage.

***

## 5. Technical Approach

### Architecture

Extend `apps/web/src/lib/orchestrationApi.ts` with command-center request helpers that reuse the existing local-server URL resolution, auth headers, timeout handling, HTTP error mapping, and response validation. Add narrow validators for `CommandCenterListRestResponse<T>`, capability responses, mutation responses, and capability-refresh responses so bad scaffold responses are surfaced as readable local orchestration failures instead of entering state.

Create `apps/web/src/lib/commandCenterUi.ts` for command-center pure normalizers and view helpers. This module should convert protocol/server payloads into bounded, display-ready records, capability summaries, status copy, and tab counts before Zustand mutates. Broad UI labels must redact raw prompts, command bodies, terminal output, diffs, file contents, provider payloads, tokens, broad absolute paths, URLs, and secrets.

Extend `useGameStore` with command-center slices for capabilities, plans/tasks, attention, executors/executions, hero lifecycle, permissions, file intents, workpad/evidence, verification/review gates, handoffs, diagnostics, channels, usage/notification readiness, active tab, selected item, loading/error/stale state, and in-flight mutation keys. Add hydrators for route snapshots and reducers for `command_center_plan_update`, `command_center_task_update`, `command_center_attention_update`, `command_center_executor_update`, `command_center_hero_lifecycle_update`, `command_center_execution_update`, `command_center_permission_update`, `command_center_file_intent_update`, `command_center_workpad_update`, `command_center_evidence_update`, `command_center_verification_update`, `command_center_handoff_update`, `command_center_diagnostic_update`, `command_center_channel_command_update`, and `command_center_usage_update`.

Split `apps/web/src/components/OrchestrationPanel.tsx` by creating `apps/web/src/components/orchestration/` components. Keep `OrchestrationPanel` as the mounted entry point for the cockpit. Move current compact rows into a legacy/current-state section, add header capability summaries, add tab controls, and add a drawer with scoped product-facing details for plans, attention, executors, diagnostics, and metrics. Empty and unavailable panes should be first-class UI states, not debug output.

### Design Patterns

* Pure normalization before store mutation: follows Quest Board and Notice Board lessons so malformed frames cannot blank the cockpit.
* Existing API request wrapper: preserves local auth, timeout, URL resolution, redacted errors, and loopback behavior.
* Capability-first rendering: follows Phase 19 semantics by showing unavailable, observe-only, proposal-only, and executor-ready states without claiming execution.
* Product surface tabs and drawers: keeps the cockpit operational and scan-friendly while avoiding a disconnected command-center route.
* Focused component extraction: reduces `OrchestrationPanel.tsx` size without changing the public app composition.

***

## 6. Deliverables

### Files To Create

| File                                                                  | Purpose                                                                                                                   | Est. Lines |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/web/src/lib/commandCenterUi.ts`                                 | Pure command-center normalizers, status copy, capability summaries, safe labels, tab count helpers, and redaction helpers | \~420      |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx`        | Mounted orchestration shell layout that composes header, compact rows, tabs, panes, and drawer                            | \~220      |
| `apps/web/src/components/orchestration/OrchestrationHeader.tsx`       | Header counts, capability summary, stale/offline labels, refresh action, and accessible details trigger                   | \~160      |
| `apps/web/src/components/orchestration/OrchestrationTabs.tsx`         | Accessible tablist and tab panels for overview, attention, campaigns, executors, diagnostics, federation, and metrics     | \~220      |
| `apps/web/src/components/orchestration/OrchestrationDrawer.tsx`       | Scoped detail drawer for command-center records with empty, unavailable, stale, and capability states                     | \~220      |
| `apps/web/src/components/orchestration/OrchestrationCurrentState.tsx` | Extracted compact queue, templates, lineage, and guarded-action sections from the current panel                           | \~360      |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx`        | Overview panes for plans/tasks, attention, executors, workpad/evidence, diagnostics/channels, and usage metrics           | \~360      |
| `apps/web/tests/commandCenterUi.test.ts`                              | Unit tests for normalizers, copy, redaction, safe labels, and tab counts                                                  | \~180      |
| `apps/web/tests/commandCenterStore.test.ts`                           | Store hydration and WebSocket reducer tests for command-center slices                                                     | \~360      |

### Files To Modify

| File                                             | Changes                                                                                                                   | Est. Lines    |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `apps/web/src/lib/orchestrationApi.ts`           | Add command-center snapshot, capability, mutation, refresh, validator, stale revision, and response helpers               | \~360         |
| `apps/web/src/lib/orchestrationUi.ts`            | Keep legacy helper exports stable and share safe text/copy helpers where useful                                           | \~80          |
| `apps/web/src/store/useGameStore.ts`             | Add command-center slices, hydrators, reducers, selection state, in-flight mutation keys, and reset behavior              | \~620         |
| `apps/web/src/store/useWsClient.ts`              | Sanitize `command_center_*` frames before `applyEvent` with explicit malformed-frame rejection                            | \~300         |
| `apps/web/src/components/OrchestrationPanel.tsx` | Preserve public entry point while delegating shell, current-state sections, tabs, panes, and drawer to focused components | \~260 changed |
| `apps/web/tests/orchestrationApi.test.ts`        | Cover command-center URLs, validators, stale revision mapping, redaction, and mutation refresh behavior                   | \~180         |
| `apps/web/tests/orchestrationStore.test.ts`      | Preserve existing queue/template/lineage/guarded-action reducer coverage while coexisting with new slices                 | \~120         |
| `apps/web/tests/OrchestrationPanel.test.tsx`     | Preserve current compact panel assertions and add command-center empty/unavailable/capability state coverage              | \~240         |
| `apps/web/tests/wsClientPrivacy.test.ts`         | Cover command-center WebSocket sanitization, malformed rejection, and sensitive-field redaction                           | \~180         |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Existing queue, template, lineage, and guarded-action compact display behavior remains visible and component-tested.
* [ ] Command-center capability and snapshot helpers fetch every Session 02 route through the existing local-server API wrapper.
* [ ] Command-center slices hydrate from route snapshots and reduce every `command_center_*` WebSocket event family from Session 01.
* [ ] Mutation helper calls prevent duplicate triggers while in-flight, map stale revision conflicts to readable UI state, and refresh the affected slice after accepted scaffold mutations.
* [ ] Orchestration tabs and drawer render empty, loading, stale, unavailable, observe-only, proposal-only, and executor-ready states without crashing.
* [ ] Broad Orchestration rows and event reducers do not expose raw prompts, command bodies, diffs, terminal output, file contents, transcript text, provider payloads, tokens, secrets, broad absolute paths, replay buffers, exports, or hosted account data.

### Testing Requirements

* [ ] Unit tests written and passing for command-center API helpers, UI normalizers, store hydrators, WebSocket sanitizers, and component states.
* [ ] `npm --workspace apps/web run typecheck` passes.
* [ ] Focused Vitest targets pass for `apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/commandCenterUi.test.ts`, `apps/web/tests/commandCenterStore.test.ts`, `apps/web/tests/orchestrationStore.test.ts`, `apps/web/tests/OrchestrationPanel.test.tsx`, and `apps/web/tests/wsClientPrivacy.test.ts`.

### Non-Functional Requirements

* [ ] The Orchestration surface stays dense, product-facing, keyboard-accessible, screen-reader labeled, and responsive without text overlap.
* [ ] Command-center state updates are deterministic, bounded, and sorted where the source route does not guarantee ordering.
* [ ] WebSocket malformed frames are ignored safely instead of clearing existing state.
* [ ] No new runtime dependency, hosted transfer path, localStorage persistence, database, or executor behavior is added.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Primary user-facing surfaces contain product-facing copy only

***

## 8. Implementation Notes

### Working Assumptions

* The selected package context is `apps/web`: the candidate stub declares `apps/web`, the first two Phase 19 prerequisites are complete, and later command-center sessions depend on web shell/store readiness. Planning can proceed without user arbitration because no earlier unfinished Phase 19 session is executable.
* Command-center API paths should use the current server scaffold namespace `/api/command-center/*`: Session 02 implemented those routes in `apps/server/src/routes/commandCenter.ts`, and historical `EXAMPLES/` route names remain evidence only.
* "Metrics" in the Session 03 stub maps to the server's `usage` and `notification-readiness` snapshots: Session 02 exposes `/command-center/usage` and `/command-center/notification-readiness`, and the protocol event is `command_center_usage_update`.
* The existing `OrchestrationPanel` remains the user-facing entry point: the Phase 19 PRD explicitly says the current panel remains the entry point and new work should not create a separate landing page or disconnected command center.

### Conflict Resolutions

* The Phase 19 study names federation as a future tab area, while Session 13 owns War Room, Notice Board, remote-access, handoff, and federation integrations. This session should include only a shell-level federation tab or capability placeholder with unavailable/deferred copy; it should not add Worker or Notice Board behavior.
* The Session 03 stub asks for mutation helpers, while deep mutating flows are deferred. This session resolves that by adding generic typed scaffold mutation helpers, in-flight guards, stale revision handling, and refresh-on-mutation plumbing, but no deep approval, dispatch, executor, or channel workflows.
* The UX PRD requires user-facing product surfaces rather than debug surfaces. Diagnostics and unavailable states should be rendered as operator capability posture and recovery guidance, with raw payloads and internal frame dumps kept out of the UI.

### Key Considerations

* `EXAMPLES/` is evidence only and must not be imported, copied, transformed, or shipped.
* The local-first trust boundary remains active: no hosted identity, remote execution, push delivery, or external transfer claim is added.
* Current queue, template, lineage, and guarded-action rows are compatibility-critical and should stay tested before and after component extraction.

### Potential Challenges

* Component extraction could accidentally change current panel semantics: Mitigate by moving behavior behind existing tests first, then adding command-center tabs.
* Store breadth could become hard to reason about: Mitigate with typed slice factories and pure normalizers in `commandCenterUi.ts`.
* Event breadth could let malformed frames mutate state: Mitigate with explicit WebSocket sanitizers and tests that reject malformed records without clearing existing state.
* Unavailable/executor-ready copy could overclaim execution: Mitigate with capability-state labels and no execution buttons until later sessions add real behavior.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: This session renders capability state and scaffolded records but ships no real file, git, terminal, remote, or container execution.
* \[P07] **Redaction is boundary-specific**: API errors, WebSocket frames, store normalizers, row labels, detail drawers, and diagnostics need separate minimization.
* \[P18-apps/web] **Pure normalization before store mutation**: Command-center payloads must be normalized before Zustand updates.
* \[P18-apps/web] **Pointer and keyboard actions should share store methods**: Refresh and scaffold mutation controls should use shared store helpers for duplicate prevention and feedback.
* \[P03] **Stable docs are the current contract**: Use active README and docs/api files as current truth; archived PRDs and `EXAMPLES/` are traceability evidence only.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Malformed or oversized command-center frames clearing existing cockpit state or leaking raw developer payloads.
* Duplicate scaffold mutation triggers creating repeated route calls or stale local state.
* Component extraction breaking keyboard, focus, accessible labels, or current compact panel behavior.

***

## 9. Testing Strategy

### Unit Tests

* Test command-center API helper URL resolution, response validators, stale revision mapping, HTTP error redaction, and refresh-on-mutation dispatch in `apps/web/tests/orchestrationApi.test.ts`.
* Test command-center normalizers, state copy, capability labels, tab counts, safe IDs, and redaction in `apps/web/tests/commandCenterUi.test.ts`.
* Test store hydrators and reducers for every `command_center_*` event family in `apps/web/tests/commandCenterStore.test.ts`.

### Integration Tests

* Test `OrchestrationPanel` still renders current queue, templates, lineage fallback, guarded actions, reference openers, duplicate guarded-action decisions, and detail popup behavior in `apps/web/tests/OrchestrationPanel.test.tsx`.
* Test the new shell tabs and drawer render empty, loading, stale, unavailable, observe-only, proposal-only, and executor-ready states using mocked command-center snapshots.
* Test `parseServerEventFrame` sanitizes valid command-center frames and rejects malformed or sensitive raw-field frames in `apps/web/tests/wsClientPrivacy.test.ts`.

### Runtime Verification

* Run `npm --workspace apps/web run typecheck`.
* Run focused Vitest targets for command-center API, UI, store, WebSocket, and Orchestration panel tests.
* Run `git diff --check -- apps/web .spec_system/specs/phase19-session03-web-shell-and-store`.

### Edge Cases

* Empty snapshots, missing capability envelopes, malformed counts, unknown event states, stale expected revisions, duplicate idempotency keys, offline local server, request timeouts, unavailable command-center routes, observe-only executors, proposal-only executors, executor-ready capabilities without execution controls, oversized labels, absolute paths, URL-like strings, Windows paths, bearer tokens, raw command fields, raw terminal output fields, and remounting the detail drawer after selection changes.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase19-session01-protocol-and-events`, `phase19-session02-server-backbone`
* Depended by: `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session07-provider-diagnostics`, and later Phase 19 web sessions that consume command-center API/store/tabs/drawers.

***

## 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase19-session03-web-shell-and-store/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.