> 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/phases/phase_05/prd_phase_05.md). # PRD Phase 05: War Room Worker Integration **Status**: Complete **Sessions**: 7 **Estimated Duration**: 7-14 days **Progress**: 7/7 sessions validated (100%); Phase 05 complete and archived *** ## Overview Phase 05 wires the existing optional Cloudflare Worker and Durable Object War Room backend into the web cockpit without making core local FactionOS workflows depend on Cloudflare. It owns source-backed federation requirements, participant trust, Worker/client contracts, room creation and join flows, leader approval, presence, reconnect, bounded catch-up, sender-excluded broadcasts, and visible fallback behavior when the Worker is unavailable. This phase must preserve the local-first posture established by Phases 01-04. War Room federation may transfer only compact, redacted collaboration state to the Worker after shared schemas and payload allowlists exist. It must not transfer file contents, full prompts, command bodies, terminal output, transcripts, secret values, broad absolute paths, local archives, replay buffers, exports, media drafts, or scan payloads. This phase does not introduce hosted auth, hosted storage, analytics, public replay hosting, inbound chat commands, real action executors, Docker isolation, remote command execution, media promotion, mobile certification, or unified erasure. Those surfaces remain later-phase work unless a future PRD explicitly changes scope. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | -------------------------------------------------- | -------- | ---------- | ---------- | | 01 | War Room Requirements and Trust Baseline | Complete | \~14-18 | 2026-05-29 | | 02 | Worker API Hardening and Client Contract | Complete | \~16-22 | 2026-05-29 | | 03 | Web Room Lifecycle and State Store | Complete | \~16-24 | 2026-05-30 | | 04 | Join Approval Presence and Reconnect UX | Complete | \~16-24 | 2026-05-30 | | 05 | Federation Event Redaction and Cockpit Integration | Complete | \~16-24 | 2026-05-30 | | 06 | Deployment Environment and Diagnostics | Complete | \~14-20 | 2026-05-30 | | 07 | War Room Validation and Documentation Closeout | Complete | \~12-18 | 2026-05-30 | *** ## Completed Sessions * Session 01: War Room Requirements and Trust Baseline - completed on 2026-05-29. * Session 02: Worker API Hardening and Client Contract - completed on 2026-05-29. * Session 03: Web Room Lifecycle and State Store - completed on 2026-05-30. * Session 04: Join Approval, Presence, and Reconnect UX - completed on 2026-05-30. * Session 05: Federation Event Redaction and Cockpit Integration - completed on 2026-05-30. * Session 06: Deployment Environment and Diagnostics - completed on 2026-05-30. * Session 07: War Room Validation and Documentation Closeout - validation and `updateprd` completed on 2026-05-30. *** ## Session 01 Baseline Artifacts Session 01 creates the Phase 05 contract artifacts that later implementation sessions must consume: * `war_room_requirements_trust_baseline.md` defines source-backed Worker, web-stub, local-server, protocol, lifecycle, participant trust, authority, spoofing, local-first, and Worker boundary requirements. * `war_room_payload_redaction_baseline.md` defines allowed Worker transfer fields, non-transferable data categories, catch-up minimization, and replay/export/log adjacency rules. * `war_room_requirement_routing_matrix.md` assigns Worker hardening, web lifecycle, approval UX, redacted federation, deployment diagnostics, validation, and later-phase deferrals to owner sessions. The baseline records the initial Phase 05 state before Sessions 02-07: Worker backend shipped, web panel disabled, local server `/warroom` stubbed, and protocol contracts typed but incomplete for hardened federation. Sessions 02-07 now provide the implemented optional Worker lifecycle, diagnostics, approval, presence, reconnect, bounded catch-up, redacted federation, browser evidence, security closeout, and documentation closeout evidence. *** ## Session 07 Closeout Evidence Session 07 recorded Phase 05 closeout evidence in `.spec_system/specs/phase05-session07-war-room-validation-and-documentation-closeout/`. The implementation and final closeout steps ran and recorded: * Focused Worker, protocol, and web War Room tests: 14 files passed, 146 tests passed. * Browser evidence: app desktop/mobile Playwright evidence for disabled, diagnostics, join, pending, create, approved, connected, reconnecting, unavailable, and redacted remote-context states. * Repository quality: formatting, linting, workspace typecheck, full Vitest, workspace build, secret scan, whitespace, and ASCII/LF checks. * Security/privacy review: Worker transfer inventory, redacted allowlist posture, browser diagnostic boundaries, catch-up filtering, replay/export adjacency, and deferred erasure boundaries. Formal spec workflow validation and `updateprd` are complete; this PRD now serves as the archived Phase 05 record. *** ## Upcoming Sessions No Phase 05 implementation sessions remain. The next workflow step is `audit`. *** ## Session Output Contract | Session | Primary output | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Source-backed War Room requirements, trust model, payload redaction rules, and session routing matrix. | | 02 | Worker REST/WebSocket schema hardening, shared client contracts, error envelopes, participant authority, rejection/leave contract decisions, and focused Worker tests. | | 03 | Web War Room client, Zustand state, room create/join/connect/disconnect controls, local-only fallback, and Worker-unavailable states. | | 04 | Leader approval, pending/rejected participant handling, member/observer policy, presence, reconnect, catch-up, leave behavior, duplicate-action guards, and accessible UX tests. | | 05 | Redacted federation event allowlist, sender-excluded cockpit updates, ghost participant UI, catch-up filtering, replay/export/log adjacency, and blocked-payload tests. | | 06 | Worker URL configuration, deployment and health diagnostics, rate-limit/WAF posture, environment docs, and operational runbook updates. | | 07 | End-to-end Worker/web validation evidence, security/privacy review, stable docs, and phase handoff updates. | *** ## Next Workflow Step `validate` *** ## Objectives 1. Reconcile the Worker backend, initial disabled web panel, protocol contracts, server stub, deployment docs, and security posture into one source-backed Phase 05 scope. 2. Define participant identity, room trust, join approval, authorization, unavailable states, reconnect, and catch-up behavior before broad UI wiring. 3. Harden the Worker REST and WebSocket contract with typed schemas, bounded payloads, deterministic errors, rate-limit behavior, and sender-excluded broadcasts. 4. Replace the disabled web War Room stub with local-first room lifecycle controls for create, join, approve, connect, reconnect, disconnect, and leave flows. 5. Federate only compact redacted cockpit state and make all sensitive prompts, paths, commands, transcripts, exports, media, and scan data non-transferable by default. 6. Add deployment, environment, health, and diagnostics guidance so Worker federation is operable but optional. 7. Validate Worker, web, protocol, docs, security, and browser behavior with focused tests and retained evidence. *** ## Prerequisites * Phase 04 completed. * `apps/warroom` Worker backend, tests, Wrangler config, deployment docs, and ADR are available. * `apps/web/src/components/WarRoomPanel.tsx` remains a clear disabled stub until Phase 05 implementation replaces it. * `packages/protocol/src/warroom.ts` and War Room event shapes remain the shared contract starting point. * The local server `/warroom` route stays a compatibility/status stub and must not become the room relay. * Cloudflare credentials are optional for local core workflows; tests must provide a local, mocked, or documented Worker path. *** ## Technical Considerations ### Architecture Protocol contracts lead cross-package War Room work. Shared participant, room, event, error, and redaction shapes should start in `packages/protocol`, then flow into `apps/warroom` and `apps/web`. The Worker remains the only room relay. The local server must keep `/warroom` as a status stub and should not proxy room traffic unless a future PRD adds a separate threat model. The web cockpit owns browser state, room lifecycle controls, visible fallback states, and participant overlays. It should treat Worker federation as optional external transfer, recover cleanly when the Worker is unreachable, and preserve the local cockpit without a room. ### Technologies * TypeScript contracts in `packages/protocol` * Cloudflare Worker, Durable Objects, WebSocket, Wrangler, and Worker tests in `apps/warroom` * React 18, Vite, TypeScript, Tailwind, Zustand, and browser WebSocket/fetch APIs in `apps/web` * Optional localStorage for bounded client identity and Worker URL hints * Vitest, Testing Library, Playwright, Biome, npm workspace scripts, and deployment health checks ### Risks * External transfer privacy: federation payloads could leak prompts, paths, commands, transcripts, exports, scan data, media drafts, or secrets without strict allowlists. * Participant trust spoofing: room identity, leader approval, and pending participant handling need deterministic authorization and clear UI states. * Worker outage drift: room create, join, socket, reconnect, and catch-up flows must degrade without breaking local cockpit use. * Catch-up replay leakage: recent-event buffers must stay bounded, redacted, and safe for reconnecting participants. * CORS and rate-limit drift: Worker browser access, origins, rate limits, and errors must be documented and tested. * Scope bleed: hosted auth, hosted persistence, analytics, inbound commands, remote execution, and release erasure stay out of Phase 05. ### Relevant Considerations * \[P05-apps/warroom+apps/web] **War Room federation is optional and redacted**: Phase 05 shipped Worker lifecycle, participant trust basics, reconnect, catch-up, sender-exclusion, diagnostics, and redacted federation while leaving stronger hosted identity to later phases. * \[P03] **Redaction is boundary-specific**: Worker payloads, room catch-up, browser overlays, replay, export, logs, and diagnostics need explicit minimization. * \[P03-apps/server] **Local server boundary must stay conservative**: keep loopback defaults, auth, Origin, CORS, validation, rate limits, and explicit Worker separation. * \[P00] **Hosted services are optional**: core local workflows must work without Cloudflare, hosted accounts, hosted storage, analytics, or public client tokens. * \[P03-packages/protocol] **Protocol leads cross-package work**: shared room and event contracts should be updated before Worker or web code depends on them. * \[P02-apps/web] **Responsive and accessibility debt**: War Room controls need mobile, focus return, dialog semantics, reduced motion, contrast, and browser validation. * \[P03] **Unified erasure still missing**: Phase 05 must avoid claiming trusted deletion for room identity, browser hints, local state, logs, or future hosted data. * \[P04] **Asset provenance gate remains active**: War Room UI and demos must not promote conditional media, generated drafts, or quarantined historical intake. *** ## Success Criteria Phase complete when: * [x] All 7 sessions implemented. * [x] Source-backed War Room requirements and trust boundaries are documented before implementation. * [x] Worker REST and WebSocket contracts are typed, schema-validated, bounded, rate-limited, and covered by focused tests. * [x] Web cockpit supports create, join, approval, presence, connect, reconnect, catch-up, disconnect, and Worker-unavailable states without blank panels. * [x] Federation payloads use explicit redaction allowlists and never include prompts, file contents, commands, transcripts, secrets, broad paths, exports, media drafts, or scan payloads. * [x] Sender-excluded broadcasts, participant overlays, and catch-up behavior are validated in Worker and browser tests. * [x] Deployment, environment, health, privacy, API, architecture, package README, and release docs describe shipped Phase 05 behavior and remaining deferred surfaces. * [x] Phase 06-08 handoff keeps collaboration, isolation, hosted services, analytics, mobile certification, unified erasure, and release decommission work deferred. *** ## Dependencies ### Depends On * Phase 04: Media Catalog and Audio/Visual Pipeline ### Enables * Phase 06: Collaboration, Isolation, and Mobile * Phase 07: Hosted Services and Analytics Guardrails * Phase 08: Release Hardening and Legacy Decommission --- # 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/phases/phase_05/prd_phase_05.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.