> 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/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.md). # Implementation Notes **Session ID**: `phase03-session05-web-orchestration-cockpit-controls` **Package**: Cross-cutting (`apps/web`, `apps/server`, `packages/protocol`) **Started**: 2026-05-29 13:20 **Last Updated**: 2026-05-29 14:55 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 23 / 23 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ### Task T023 - Run validation and hygiene checks **Started**: 2026-05-29 14:45 **Completed**: 2026-05-29 14:55 **Duration**: 10 minutes **Notes**: * Ran focused server and web typechecks. * Ran focused server and web Vitest suites for WebSocket hydration, orchestration UI helpers, store reducers, panel behavior, cockpit shell metadata, and WebSocket privacy. * Ran Biome lint on touched TypeScript files. * Ran desktop and mobile Playwright smoke validation against the local dev stack. * Ran ASCII, LF, and patch whitespace checks. **Files Changed**: * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/tasks.md` - marked T023 complete and updated completion checklist. * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.md` - recorded validation results. * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/security-compliance.md` - updated security closeout. **Validation Commands**: * `npm --workspace apps/server run typecheck` - pass * `npm --workspace apps/web run typecheck` - pass * `npx vitest run apps/server/tests/websocket.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/orchestrationStore.test.ts apps/web/tests/OrchestrationPanel.test.tsx apps/web/tests/CockpitShell.test.tsx apps/web/tests/wsClientPrivacy.test.ts` - pass, 31 tests * `npx biome lint ...` on touched TypeScript files - pass * `git diff --check` - pass * ASCII check with `rg --pcre2 -n "[^\\x00-\\x7F]" ...` - pass * LF check with `rg -n "\\r" ...` - pass * Playwright smoke against `http://localhost:5194/` - pass **Browser Smoke Evidence**: * `test-results/session05-orchestration/desktop.png` - desktop panel reachable, 197.375 x 252 px, two filters present. * `test-results/session05-orchestration/mobile.png` - mobile panel reachable, 366 x 1128.125 px, two filters present. **BQC Fixes**: * Accessibility and platform compliance: browser smoke confirms desktop and mobile panel reachability. * Failure path completeness: validation includes loading/error/offline shell and panel tests. * Error information boundaries: focused privacy tests and server hydration tests confirm compact sensitive-field boundaries. *** ### Task T022 - Write web orchestration tests **Started**: 2026-05-29 14:32 **Completed**: 2026-05-29 14:45 **Duration**: 13 minutes **Notes**: * Added copy-helper tests for orchestration status mapping, broad redaction, missing-reference labels, and transcript-like identifier redaction. * Added store reducer tests for queue, template, mission graph, guarded-action frames, duplicate decision prevention, update reset, and hero/mission selection sync. * Added panel tests for hydrated queue/template/lineage/guarded-action rendering, reference controls, and duplicate approve prevention. * Updated shell tests for orchestration surface metadata and panel presence. * Updated WebSocket privacy tests for orchestration frame allowlist sanitization and malformed-frame rejection. **Files Changed**: * `apps/web/tests/orchestrationUi.test.ts` - copy helper and redaction tests. * `apps/web/tests/orchestrationStore.test.ts` - store reducer and selection-sync tests. * `apps/web/tests/OrchestrationPanel.test.tsx` - panel and duplicate-decision tests. * `apps/web/tests/CockpitShell.test.tsx` - orchestration shell metadata coverage. * `apps/web/tests/wsClientPrivacy.test.ts` - orchestration WebSocket privacy coverage. **BQC Fixes**: * Duplicate action prevention: component and store tests cover repeated guarded-action decisions. * State freshness on re-entry: store tests cover selection revalidation and decision reset on updates. * Error information boundaries: helper and parser tests cover sensitive-field redaction and extra-field stripping. * Accessibility and platform compliance: panel tests use accessible button names for reference and decision controls. *** ### Task T021 - Write server WebSocket hydration tests **Started**: 2026-05-29 14:25 **Completed**: 2026-05-29 14:32 **Duration**: 7 minutes **Notes**: * Updated deterministic connect hydration tests for the nine-frame sequence. * Added connect-time orchestration hydration coverage with existing queue and guarded-action state. * Asserted compact hydration frames include queue, template, mission graph, and guarded-action summaries without raw titles, paths, tokens, rationale, or preview bodies. * Updated existing WebSocket tests to drain the full hydration sequence before client-message assertions. **Files Changed**: * `apps/server/tests/websocket.test.ts` - added and updated WebSocket hydration coverage. **BQC Fixes**: * Contract alignment: tests assert connect-time frame order and protocol event types. * Error information boundaries: tests assert sensitive queue and guarded-action inputs are not echoed in WebSocket hydration. *** ### Task T020 - Update API orchestration docs **Started**: 2026-05-29 14:22 **Completed**: 2026-05-29 14:25 **Duration**: 3 minutes **Notes**: * Added WebSocket connect-time orchestration hydration frames to the API reference. * Documented compact frame boundaries for web cockpit hydration. * Updated Phase 03 planning status to include shipped Session 05 local web orchestration controls. * Preserved out-of-scope claims for subagent control actions, hidden execution, CLI recovery, hosted queues, inbound commands, War Room federation, analytics dashboards, public replay hosting, and remote execution. **Files Changed**: * `docs/api/README_api.md` - updated local WebSocket and Phase 03 orchestration planning sections. **BQC Fixes**: * Error information boundaries: API docs state compact frames exclude raw titles, proposal rationale, prompts, commands, terminal output, file contents, tokens, transcript paths, transcript contents, and broad absolute paths. *** ### Task T019 - Update web orchestration docs **Started**: 2026-05-29 14:19 **Completed**: 2026-05-29 14:22 **Duration**: 3 minutes **Notes**: * Updated the web README to describe shipped local queue, template, lineage, mission graph, and guarded-action cockpit controls. * Documented duplicate guarded-action decision prevention, expected revision use, and existing hero/mission selection synchronization. * Preserved deferred boundaries for hosted queues, War Room federation, inbound commands, analytics, public replay hosting, remote execution, handoff, fork, resume, and stop controls. **Files Changed**: * `apps/web/README_web.md` - updated Phase 03 web orchestration contract and deferred boundary wording. **BQC Fixes**: * Error information boundaries: documentation explicitly keeps sensitive orchestration payloads out of broad UI and replay-adjacent paths. *** ### Task T018 - Preserve privacy boundaries **Started**: 2026-05-29 13:50 **Completed**: 2026-05-29 14:19 **Duration**: 29 minutes **Notes**: * Orchestration WebSocket frames are allowlist-sanitized before store application and replay-buffer capture. * Broad UI copy flows through orchestration UI redaction helpers for paths, URLs, bearer tokens, secret-like values, and path-like subagent identifiers. * Replay link sharing already recursively redacts nested event strings and field names before serialization. * Export, notification, and settings flows are not extended with orchestration payload persistence or external transfer. **Files Changed**: * `apps/web/src/store/useWsClient.ts` - sanitizes orchestration frames at the WebSocket boundary. * `apps/web/src/lib/orchestrationUi.ts` - centralizes broad UI copy redaction and safe labels. * `apps/web/src/components/OrchestrationPanel.tsx` - displays helper-owned bounded copy only. **BQC Fixes**: * Error information boundaries: raw prompts, commands, terminal output, file contents, tokens, transcript paths, broad absolute paths, and extra server fields are kept out of broad orchestration UI and replay-adjacent frame capture. * Contract alignment: sanitized frames preserve protocol-owned compact event shapes. *** ### Task T017 - Synchronize orchestration references **Started**: 2026-05-29 14:15 **Completed**: 2026-05-29 14:17 **Duration**: 2 minutes **Notes**: * Added orchestration reference opening through existing `openMissionDetail` and `openHeroDetail` actions. * Queue and guarded-action reference buttons open available hero and mission references. * Lineage mission controls select lineage context and open the existing mission detail flow. * Snapshot updates revalidate selected queue, guarded-action, and lineage mission IDs. **Files Changed**: * `apps/web/src/store/useGameStore.ts` - added orchestration reference synchronization action. * `apps/web/src/components/OrchestrationPanel.tsx` - wired reference controls to store synchronization. **BQC Fixes**: * State freshness on re-entry: references are revalidated against current hero, mission, queue, graph, and action snapshots. * Contract alignment: selection sync reuses existing hero and mission store actions. *** ### Task T016 - Wire orchestration panel into cockpit shell **Started**: 2026-05-29 14:13 **Completed**: 2026-05-29 14:15 **Duration**: 2 minutes **Notes**: * Mounted `OrchestrationPanel` in the existing bottom rail between Quest Board and War Room. * Added orchestration counts to cockpit surface metadata input. * Left mission log, hero roster, battlefield, and War Room stub surfaces intact. **Files Changed**: * `apps/web/src/App.tsx` - imported and mounted the orchestration panel and passed its shell count. **BQC Fixes**: * Accessibility and platform compliance: the new panel is wrapped by existing shell surface metadata with an accessible surface label. * Contract alignment: War Room remains a separate deferred stub and is not replaced by local orchestration. *** ### Task T015 - Implement guarded-action decision controls **Started**: 2026-05-29 14:00 **Completed**: 2026-05-29 14:13 **Duration**: 13 minutes **Notes**: * Added guarded-action rows with state, family, kind, revision, result labels, and hero/mission reference controls. * Approve and reject buttons are disabled when a proposal is not pending or when a local decision is already in flight. * Decision requests include `expectedRevision` and deterministic idempotency keys. * Accepted decisions trigger a guarded-action snapshot refresh; failures clear the local in-flight guard and show bounded toast copy. **Files Changed**: * `apps/web/src/components/OrchestrationPanel.tsx` - implemented guarded-action rows and decisions. * `apps/web/src/store/useGameStore.ts` - added guarded-action in-flight decision tracking and state reset from updates/snapshots. * `apps/web/src/lib/orchestrationApi.ts` - added guarded-action decision REST helper. **BQC Fixes**: * Duplicate action prevention: store-level in-flight IDs block repeated decisions while a request is pending. * Contract alignment: decision requests send `expectedRevision` and `idempotencyKey`. * Failure path completeness: decision failures produce visible bounded toasts. * Error information boundaries: decision errors flow through sanitized API helper copy. *** ### Task T014 - Implement lineage and mission graph sections **Started**: 2026-05-29 14:00 **Completed**: 2026-05-29 14:12 **Duration**: 12 minutes **Notes**: * Added mission graph node rendering with state chips, parent labels, child counts, edge summaries, and unavailable empty state copy. * Added lineage summary copy from latest subagent update and graph counts. * Missing mission references show bounded fallback labels rather than raw IDs or paths. **Files Changed**: * `apps/web/src/components/OrchestrationPanel.tsx` - implemented lineage and graph sections. * `apps/web/src/lib/orchestrationUi.ts` - provided graph node, edge, and subagent identifier label helpers. **BQC Fixes**: * State freshness on re-entry: graph selections revalidate when graph snapshots change. * Error information boundaries: subagent identifiers with path-like or oversized values are redacted before display. * Accessibility and platform compliance: graph mission controls are native buttons with accessible labels. *** ### Task T013 - Implement queue and template sections **Started**: 2026-05-29 14:00 **Completed**: 2026-05-29 14:11 **Duration**: 11 minutes **Notes**: * Added queue and template sections with bounded six-row rendering and "showing N of M" cues. * Added allowlisted queue-state and template-role filters. * Queue rows expose state, priority, revision, rejection copy, and hero/mission reference controls. * Template rows expose role, tags, and local-only/source-owned constraints. **Files Changed**: * `apps/web/src/components/OrchestrationPanel.tsx` - implemented queue and template sections. **BQC Fixes**: * Trust boundary enforcement: filter values are selected from allowlisted option arrays. * Accessibility and platform compliance: queue rows and reference controls have accessible names and native keyboard support. * Error information boundaries: row labels flow through `orchestrationUi.ts` redaction helpers. *** ### Task T012 - Create orchestration cockpit panel shell **Started**: 2026-05-29 13:59 **Completed**: 2026-05-29 14:10 **Duration**: 11 minutes **Notes**: * Created `OrchestrationPanel` as a dense cockpit surface for local queue, templates, lineage, and guarded actions. * Added initial REST hydration for queue, template, and guarded-action snapshots. * Added visible loading, error, offline/disconnected, empty, and unavailable fallback states. **Files Changed**: * `apps/web/src/components/OrchestrationPanel.tsx` - new cockpit orchestration panel shell and state banner. **BQC Fixes**: * State freshness on re-entry: panel refreshes REST snapshots for the active local server port. * Failure path completeness: hydration failures surface bounded local copy instead of blank panels. * Accessibility and platform compliance: the panel has a labeled region, labeled controls, and keyboard-reachable buttons/selects. *** ### Task T011 - Emit compact orchestration hydration frames **Started**: 2026-05-29 13:25 **Completed**: 2026-05-29 13:59 **Duration**: 34 minutes **Notes**: * WebSocket connect now sends compact `task_queue_update`, `agent_template_update`, `mission_graph_update`, and `guarded_action_update` hydration frames after existing base snapshots. * Queue hydration includes counts and bounded event entries only. * Template hydration includes source-owned template summaries only. * Mission graph hydration uses event snapshots. * Guarded-action hydration expires stale pending proposals first, then sends counts and compact proposal summaries. **Files Changed**: * `apps/server/src/ws/handlers.ts` - emits compact orchestration hydration frames during WebSocket attach. **BQC Fixes**: * State freshness on re-entry: guarded actions expire before connect-time hydration. * Error information boundaries: hydration uses compact event payloads and excludes raw prompts, commands, file contents, terminal output, tokens, transcript paths, and broad absolute paths. * Contract alignment: hydration frames reuse existing protocol `ServerEvent` shapes. *** ### Task T010 - Wire managers into WebSocket registration **Started**: 2026-05-29 13:25 **Completed**: 2026-05-29 13:58 **Duration**: 33 minutes **Notes**: * Passed existing task queue, agent template, and mission graph managers into `registerWsHandlers`. * Preserved existing auth, CORS, Origin, rate-limit, and body-size middleware setup. **Files Changed**: * `apps/server/src/server.ts` - added orchestration managers to WebSocket handler context. **BQC Fixes**: * Contract alignment: WebSocket handler registration now receives the same runtime managers used by REST and event ingest. *** ### Task T009 - Confirm WebSocket parsing and cleanup behavior **Started**: 2026-05-29 13:50 **Completed**: 2026-05-29 13:57 **Duration**: 7 minutes **Notes**: * Preserved existing socket, reconnect timer, and close-request cleanup behavior in `useWsClient`. * Added compact allowlist sanitizers for orchestration WebSocket frames before store application and replay capture. * Malformed orchestration frames now return `null`; known orchestration frames strip broad extra fields before reaching the store. **Files Changed**: * `apps/web/src/store/useWsClient.ts` - added typed orchestration frame sanitization around existing parser and cleanup flow. **BQC Fixes**: * Resource cleanup: existing reconnect timers and sockets are still cleaned up on hook unmount. * Trust boundary enforcement: orchestration frames are shape-checked and allowlisted at the WebSocket boundary. * Error information boundaries: extra raw fields on orchestration frames are stripped before replay/store paths. *** ### Task T008 - Extend cockpit surface metadata **Started**: 2026-05-29 13:48 **Completed**: 2026-05-29 13:50 **Duration**: 2 minutes **Notes**: * Added an `orchestration` shell surface with loading, empty, offline, and disconnected copy. * Kept copy local-first and avoided hosted queue, Worker federation, analytics, inbound command, public replay, or remote execution claims. **Files Changed**: * `apps/web/src/lib/cockpitShell.ts` - added orchestration surface metadata and count support. **BQC Fixes**: * Failure path completeness: new surface has visible fallback copy for loading, empty, offline, and disconnected states. * Error information boundaries: fallback text does not expose raw local payloads or imply external transfer. *** ### Task T007 - Extend game store orchestration state and reducers **Started**: 2026-05-29 13:39 **Completed**: 2026-05-29 13:48 **Duration**: 9 minutes **Notes**: * Added store state for task queue, agent templates, latest lineage event, mission graph, guarded-action proposals, selected orchestration references, and in-flight guarded-action decisions. * Added hydration actions for REST queue, template, and guarded-action snapshots. * Added reducers for `task_queue_update`, `agent_template_update`, `subagent_lineage_update`, `mission_graph_update`, and `guarded_action_update`. * Added selection revalidation for queue entries, guarded actions, and lineage mission nodes when snapshots change. **Files Changed**: * `apps/web/src/store/useGameStore.ts` - added orchestration state, actions, reducers, and reset behavior. **BQC Fixes**: * State freshness on re-entry: selections are revalidated whenever snapshots change and reset on seed reset. * Duplicate action prevention: guarded-action decision IDs prevent repeated local decisions while in flight. * Contract alignment: reducers consume protocol-owned event shapes. * Failure path completeness: missing references clear stale selections rather than leaving broken context. *** ### Task T006 - Create orchestration UI helpers **Started**: 2026-05-29 13:31 **Completed**: 2026-05-29 13:39 **Duration**: 8 minutes **Notes**: * Added status copy and tone mapping for task queue, template, lineage, mission graph, and guarded-action protocol states. * Added view-model builders for queue entries, templates, graph nodes, and guarded actions. * Added broad text redaction, transcript/path-like identifier redaction, short-id formatting, and missing-reference labels. * Used exhaustive switch handling for protocol enum values. **Files Changed**: * `apps/web/src/lib/orchestrationUi.ts` - new UI copy, status, privacy, and view-model helper module. **BQC Fixes**: * Contract alignment: protocol enum states are mapped through exhaustive helpers. * Error information boundaries: broad labels redact paths, URLs, bearer tokens, and secret-like values. * Accessibility and platform compliance: helpers produce stable labels that components can reuse for accessible controls. *** ### Task T005 - Create orchestration REST helper **Started**: 2026-05-29 13:25 **Completed**: 2026-05-29 13:31 **Duration**: 6 minutes **Notes**: * Added local REST helpers for task queue snapshots, agent template snapshots, guarded-action snapshots, and guarded-action decisions. * Routed requests through existing local auth headers. * Added timeout-backed abort handling, bounded JSON parsing, route-id validation, and compact error mapping. * Sanitized broad error copy for paths, URLs, bearer tokens, and secret-like values. **Files Changed**: * `apps/web/src/lib/orchestrationApi.ts` - new REST helper module for local orchestration calls. **BQC Fixes**: * External dependency resilience: requests use a bounded timeout and explicit offline/timeout failure states. * Trust boundary enforcement: responses get minimal shape validation before use. * Failure path completeness: HTTP, network, timeout, malformed-response, and invalid-input cases return caller-visible results. * Error information boundaries: broad failure copy is sanitized before it reaches UI callers. *** ### Task T004 - Add WebSocket orchestration hydration context **Started**: 2026-05-29 13:24 **Completed**: 2026-05-29 13:25 **Duration**: 1 minute **Notes**: * Extended WebSocket handler context to include task queue, agent template, mission graph, and guarded-action managers. * Added compact hydration frame construction for queue counts and event entries, template summaries, mission graph event snapshots, and guarded-action proposal summaries. * Kept frames aligned with protocol event types and avoided broad raw queue titles, proposal rationale, command text, prompts, file contents, tokens, transcript paths, or absolute paths. **Files Changed**: * `apps/server/src/ws/handlers.ts` - added orchestration manager context and compact hydration frame construction. **BQC Fixes**: * State freshness on re-entry: guarded actions expire before hydration frames are generated. * Contract alignment: hydration frames use existing `ServerEvent` protocol shapes. * Error information boundaries: broad WebSocket hydration uses compact event entries and summaries only. *** ### Task T003 - Confirm web and privacy baselines **Started**: 2026-05-29 13:22 **Completed**: 2026-05-29 13:24 **Duration**: 2 minutes **Notes**: * Confirmed `apps/web/README_web.md` already documents local shell, hero/mission synchronization, permission duplicate guards, replay/export privacy, and Phase 03 orchestration boundaries. * Confirmed `apps/web/src/App.tsx` wraps regions with cockpit shell metadata and keeps War Room as a deferred stub. * Confirmed `apps/web/src/store/useGameStore.ts` owns event reduction, replay buffering, selection synchronization, duplicate permission and plan decisions, and toast feedback. * Confirmed `apps/web/src/store/useWsClient.ts` parses server frames defensively and cleans up reconnect timers plus sockets on unmount. * Confirmed `apps/web/src/lib/localAuth.ts` is the existing local auth header/token helper for REST and WebSocket clients. * Confirmed `docs/api/README_api.md` documents shipped local queue, template, lineage, mission graph, guarded-action, and WebSocket event boundaries. **Files Changed**: * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/tasks.md` - marked T003 complete and updated progress. * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.md` - recorded baseline review. *** ### Task T002 - Create implementation and security artifacts **Started**: 2026-05-29 13:20 **Completed**: 2026-05-29 13:22 **Duration**: 2 minutes **Notes**: * Created the session implementation log with progress tracking and verified environment notes. * Created the session security compliance artifact with local-first scope and pending verification sections. **Files Changed**: * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.md` - initialized session progress and task log. * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/security-compliance.md` - initialized security posture and verification placeholders. *** ### Task T001 - Verify prerequisites and owner rows **Started**: 2026-05-29 13:20 **Completed**: 2026-05-29 13:21 **Duration**: 1 minute **Notes**: * Confirmed active session from `.spec_system/state.json` and analyzer output. * Confirmed Sessions 02, 03, and 04 are listed as completed in state. * Confirmed Session 05 owner rows in the Phase 03 orchestration gap matrix route queue/template, lineage, and guarded-action web cockpit controls to this session. * Confirmed local-first exclusions remain hosted queues, War Room federation, inbound commands, analytics, public replay hosting, remote execution, Docker isolation, and hidden terminal execution. **Files Changed**: * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/tasks.md` - marked T001 complete and updated progress. * `.spec_system/specs/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.md` - recorded verification details. *** ## Task Log ### 2026-05-29 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Workspace scripts available * [x] Directory structure ready * [x] Local npm workspace tooling available through `node_modules/.bin` *** --- # 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/phase03-session05-web-orchestration-cockpit-controls/implementation-notes.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.