> 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/phase05-session06-deployment-environment-and-diagnostics/spec.md). # Session Specification **Session ID**: `phase05-session06-deployment-environment-and-diagnostics` **Phase**: 05 - War Room Worker Integration **Status**: Complete **Created**: 2026-05-30 **Package**: Cross-package (`apps/warroom`, `apps/web`, docs) **Package Stack**: TypeScript, React 18, Vite, Zustand, Vitest, Cloudflare Workers, Durable Objects, GitHub Actions *** ## 1. Session Overview This session makes the optional War Room Worker integration operable after the room lifecycle, approval, presence, reconnect, catch-up, and redacted federation paths shipped in Sessions 03-05. The work adds clear Worker URL configuration, health diagnostics, deployment checks, and operator guidance so users can distinguish disabled, misconfigured, unreachable, rate-limited, and connected states without making Cloudflare mandatory. The runtime boundary remains local-first. Core server and web workflows must continue to run with no Cloudflare credentials, no Worker URL, no hosted auth, no hosted storage, no analytics, and no public replay hosting. Browser-visible diagnostics may report compact Worker health, rate-limit, and configuration state, but they must not expose account ids, raw secrets, request bodies, prompt content, paths, tokens, command output, replay buffers, exports, scan payloads, media drafts, or local diagnostics. The session also updates stable deployment, environment, API, architecture, privacy, release, package README, workflow, and runbook docs so the shipped Phase 05 behavior is no longer described as a stub or future-only surface. Session 07 will later validate Phase 05 end to end; this session focuses on operability, configuration, diagnostics, and documentation readiness. *** ## 2. Objectives 1. Add browser-safe Worker URL default configuration and health diagnostics while preserving local-only fallback when no Worker URL is configured. 2. Expose Worker health, rate-limit, room API, and socket upgrade failure states through bounded web UI copy and focused tests. 3. Add Worker health metadata and deployment smoke checks without leaking Cloudflare account identifiers, secrets, request bodies, or sensitive payloads. 4. Update stable docs and runbooks so deployment, rollback, rate-limit, WAF, local Wrangler, custom-domain, and privacy boundaries match current source. *** ## 3. Prerequisites ### Required Sessions * [x] `phase05-session03-web-room-lifecycle-and-state-store` - Provides the web room lifecycle store, Worker URL hints, and local-only fallback. * [x] `phase05-session04-join-approval-presence-and-reconnect-ux` - Provides approval, presence, reconnect, catch-up, leave, and unavailable states. * [x] `phase05-session05-federation-event-redaction-and-cockpit-integration` - Provides redacted federation, remote context, sender exclusion, and privacy adjacency tests. ### Required Tools/Knowledge * Worker health and room routes in `apps/warroom/src/index.ts`. * Web War Room client, identity hints, store, and panel behavior in `apps/web`. * Deployment docs, environment inventory, workflow docs, and runbooks under `docs/` and `.github/workflows/`. * Vitest tests for Worker, web client, store, and panel behavior. ### Environment Requirements * Node 20+ and npm workspace install are available. * Cloudflare credentials are not required for local tests. * Real Wrangler dev remains opt-in through `FACTIONOS_RUN_WRANGLER_DEV=1`. * No database or schema migration is in scope. *** ## 4. Scope ### In Scope (MVP) * Operators can configure a browser-safe default Worker URL, local Wrangler dev URL, custom-domain URL, or local-only disabled state with clear validation. * Browser users can run a bounded Worker health diagnostic and see disabled, misconfigured, unreachable, timed out, rate-limited, healthy, connected, and socket-failed states without blank panels. * Worker health responses expose compact service, timestamp, and rate-limit metadata without account ids, secrets, request bodies, stack traces, or raw payloads. * Deployment workflow and docs identify the Worker custom domain, workers.dev URL, local dev URL, health probes, rollback path, app-level rate limits, and current WAF posture. * Stable docs and package READMEs remove stale stub wording and state that War Room federation is optional, redacted, allowlisted, and locally degradable. * Tests cover URL defaults, health diagnostics, unavailable and rate-limited states, store cleanup, UI copy, Worker health metadata, and docs-linked commands where practical. ### Out of Scope (Deferred) * Requiring Cloudflare credentials for core local development - *Reason: core local workflows remain credential-free and local-first.* * Adding hosted auth, hosted storage, analytics, public replay hosting, inbound commands, real executors, or shared hosted queues - *Reason: later phases own those threat models and consent models.* * Replacing or provisioning Cloudflare dashboard WAF/rate-limit rules - *Reason: account-level WAF changes require explicit operator approval and may depend on plan entitlement.* * Phase 05 end-to-end browser evidence and security closeout - *Reason: Session 07 owns final validation and documentation closeout.* * Unified erasure for Worker room data, browser hints, logs, archives, exports, replay buffers, backups, or future hosted data - *Reason: Phase 08 owns trusted erasure.* *** ## 5. Technical Approach ### Architecture Keep `apps/warroom` as the only room relay. Extend the Worker health response with compact metadata that can be safely shown in the browser and docs: service name, server time, rate-limit enabled flag, max/window values, and deployment-safe labels. The health endpoint must not include Cloudflare account ids, zone ids, tokens, request headers, client IPs, request bodies, or room payloads. In `apps/web`, add a small diagnostics helper that normalizes Worker URLs, derives local Wrangler, custom-domain, workers.dev, and disabled-state labels, and maps health results to user-facing diagnostics. The War Room client should reuse existing timeout and safe error mapping. The Zustand store owns health diagnostic state so duplicate checks are ignored while in flight and stale diagnostics reset when the Worker URL changes, room context resets, or storage hydrates. The War Room panel renders diagnostics as an operational section beside the existing lifecycle and federation summaries. The UI must show loading, empty, healthy, rate-limited, timeout, offline, and invalid URL states using text and accessible status regions rather than color alone. It must not imply that a healthy Worker is hosted identity, trusted erasure, analytics, or public sharing. Documentation updates should be source-backed. `docs/environments.md` records new browser-safe Worker variables. `docs/deployment.md`, `docs/api/README_api.md`, `docs/ARCHITECTURE.md`, `docs/privacy-and-security.md`, and `docs/release.md` describe shipped behavior and current limits. `docs/runbooks/war-room-operations.md` captures local and deployed checks. Package README files and workflow docs point to the same commands and boundaries. ### Design Patterns * Local-first configuration: Empty or invalid Worker URL degrades to local-only or bounded invalid-input states. * Fail-closed diagnostics: Health checks report compact statuses and never echo raw response bodies, headers, account ids, secrets, or stack traces. * Store-owned lifecycle: Health diagnostics clear on Worker URL changes, hydration, leave, reset, and disconnect where stale context would mislead. * Existing timeout boundaries: Reuse client timeout and failure mapping rather than adding long-running browser requests. * Documentation as contract: Stable docs must describe current behavior, not planned Session 01 stub language. ### Technology Stack * TypeScript 5.9.3 in `apps/warroom` and `apps/web`. * Cloudflare Worker, Durable Objects, Wrangler, and GitHub Actions. * React 18, Vite, Tailwind, and Zustand in `apps/web`. * Vitest 4.1.7, Testing Library, happy-dom, and in-process Worker tests. * npm workspaces and Biome. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/warRoomDiagnostics.ts` | Pure diagnostic derivation for Worker URL source, health status, safe copy, and operator hints. | \~180 | | `apps/web/tests/warRoomDiagnostics.test.ts` | Focused tests for URL defaults, health-state mapping, rate-limit copy, and sensitive-data absence. | \~180 | | `docs/runbooks/war-room-operations.md` | Operator runbook for local Wrangler, deployed health checks, rate limits, rollback, and privacy boundaries. | \~160 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------- | | `apps/warroom/src/index.ts` | Add compact health metadata and preserve safe error behavior. | \~60 | | `apps/warroom/tests/warroom.test.ts` | Cover health metadata, no sensitive details, and rate-limit metadata. | \~80 | | `apps/web/src/lib/warRoomClient.ts` | Parse enriched health responses and preserve timeout/rate-limit failure mapping. | \~80 | | `apps/web/src/lib/warRoomIdentity.ts` | Load browser-safe default Worker URL before localStorage overrides. | \~80 | | `apps/web/src/store/useWarRoomStore.ts` | Add health diagnostic state/action, duplicate guards, and reset behavior. | \~140 | | `apps/web/src/components/WarRoomPanel.tsx` | Render diagnostic controls and visible failure states. | \~150 | | `apps/web/tests/warRoomClient.test.ts` | Cover enriched health parsing and safe failure copy. | \~80 | | `apps/web/tests/warRoomStore.test.ts` | Cover diagnostic action, in-flight guard, reset, and Worker URL change cleanup. | \~120 | | `apps/web/tests/WarRoomPanel.test.tsx` | Cover diagnostic UI copy, accessible status, and sensitive-data absence. | \~120 | | `.env.local.example` | Document browser-safe Worker URL default and operational health URL variables. | \~30 | | `.github/workflows/warroom-deploy.yml` | Add a bounded post-deploy health smoke check without secret echoing. | \~35 | | `.github/workflows/README_workflows.md` | Document the War Room deploy health smoke behavior. | \~25 | | `docs/environments.md` | Align Worker and browser-safe environment variables with current source. | \~50 | | `docs/deployment.md` | Update deploy, validation, WAF, rate-limit, and rollback guidance. | \~80 | | `docs/api/README_api.md` | Update War Room API reference for current room, reject, socket, health, and federation behavior. | \~80 | | `docs/ARCHITECTURE.md` | Update architecture and current gaps for shipped optional Worker federation. | \~70 | | `docs/privacy-and-security.md` | Update external transfer and controls for shipped redacted Worker federation. | \~70 | | `docs/release.md` | Add War Room diagnostic and deploy checks to release readiness notes. | \~45 | | `docs/runbooks/incident-response.md` | Link the War Room operations runbook and update stale stub wording. | \~40 | | `apps/web/README_web.md` | Document diagnostics UI and browser-safe default Worker URL behavior. | \~45 | | `apps/warroom/README_warroom.md` | Document enriched health metadata, deploy checks, and operational commands. | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Empty Worker URL keeps the web panel in local-only mode without blocking local cockpit use. * [ ] Browser-safe default Worker URL configuration is loaded, normalized, and overridable by local room hints. * [ ] Users can manually run a Worker health diagnostic and see healthy, invalid URL, offline, timeout, rate-limited, and bad-response outcomes. * [ ] Worker health responses expose only compact service, time, and rate-limit metadata. * [ ] Deployment workflow or docs provide a bounded health check after Worker deploy without printing secrets. ### Testing Requirements * [ ] Worker tests cover health metadata and sensitive-detail absence. * [ ] Web client and diagnostic helper tests cover URL normalization, health parsing, failure mapping, and rate-limit copy. * [ ] Store and panel tests cover diagnostic in-flight guards, resets, visible states, and accessibility. * [ ] Docs-linked commands are reviewed or covered by focused tests where practical. ### Non-Functional Requirements * [ ] Core local workflows do not require Cloudflare credentials, Worker URL, hosted auth, hosted storage, analytics, or public replay hosting. * [ ] Diagnostic output does not expose account ids, secrets, raw request bodies, prompt content, command output, paths, tokens, exports, scans, media drafts, logs, or local diagnostics. * [ ] UI copy does not claim hosted identity, production-hosted validation, public sharing safety, or trusted erasure. * [ ] WAF and rate-limit docs distinguish app-level controls from dashboard controls that require operator approval. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Focused Worker and web tests pass * [ ] Relevant package typechecks pass *** ## 8. Implementation Notes ### Key Considerations * Do not put Cloudflare account ids, zone ids, or token values into browser code or tracked docs. * Keep `CLOUDFLARE_*` operational variables server/operator-only unless they are explicitly safe URLs. Browser-facing defaults should use `VITE_` names. * Health diagnostics are advisory. A healthy Worker does not prove hosted auth, trusted erasure, production validation, or public sharing safety. * Local Wrangler dev remains opt-in in tests. Do not make `npm test` spawn real Wrangler by default. * Update stale docs that still say the web War Room panel is a stub. ### Potential Challenges * Browser default URL can look like mandatory Cloudflare configuration: Mitigate by treating an empty value as first-class local-only mode. * Health response can grow into an information leak: Mitigate by returning only service, time, and rate-limit metadata. * Docs can drift across many files: Mitigate by using one runbook as the operational anchor and linking stable docs to it. * Post-deploy health checks can break deploys on transient Cloudflare issues: Mitigate with bounded curl timeouts and clear failure output. * Rate-limit and WAF posture can be misunderstood: Mitigate by separating app-level Worker rate limits from Cloudflare dashboard WAF rules. ### Relevant Considerations * \[P03-apps/warroom+apps/web] **War Room federation is still separate**: This session keeps the Worker optional while making the shipped web integration operable. * \[P03] **Redaction is boundary-specific**: Health diagnostics, deployment docs, browser copy, logs, and runbooks need explicit minimization. * \[P00] **Hosted services are optional**: Core local workflows must still work without Cloudflare, hosted accounts, hosted storage, analytics, or public client tokens. * \[P03] **Local-first boundary is architectural**: Worker diagnostics must degrade cleanly when remote relay configuration is absent or unavailable. * \[P02-apps/web] **Responsive and accessibility debt**: Diagnostics need readable text states, accessible status regions, focus-safe controls, and mobile-friendly layout. * \[P03] **Unified erasure still missing**: Runbooks and UI copy must not imply trusted deletion of Worker room data, browser hints, logs, exports, replay buffers, backups, or future hosted records. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Worker health diagnostics leak account details, tokens, raw payloads, stack traces, local paths, or sensitive transfer context. * The web panel presents Cloudflare configuration as mandatory or treats a healthy Worker as hosted identity, trusted erasure, or public sharing safety. * Diagnostic state becomes stale after Worker URL changes, room leave/reset, reconnect, hydration, or storage failure. *** ## 9. Testing Strategy ### Unit Tests * Diagnostic helper tests for URL source labels, disabled/local-only states, custom-domain and local Wrangler labels, rate-limit copy, health states, and sensitive string blocking. * Web client tests for enriched health response parsing, timeout, offline, bad-response, HTTP error, and rate-limit mapping. * Store tests for health diagnostic action, duplicate in-flight guard, Worker URL change cleanup, hydrate/reset cleanup, and safe failure state. ### Integration Tests * Worker in-process tests for `/health` metadata and no sensitive fields. * War Room panel tests for diagnostic rendering, button states, accessible status regions, healthy/rate-limited/unavailable copy, and no stale stub claims. * Workflow smoke behavior reviewed through YAML and docs-linked commands. ### Manual Testing * Start the web app with no Worker URL and confirm local-only mode stays usable. * Set a local Wrangler Worker URL, run health diagnostics, then stop Wrangler and confirm bounded unavailable copy. * Use the deployed custom-domain health URL from docs and confirm health copy shows compact service and rate-limit status only. * Trigger a mocked 429 response and confirm retry-after copy is visible without raw response payloads. ### Edge Cases * Empty, malformed, too-long, credential-bearing, or unsupported-protocol Worker URL. * Worker health endpoint times out, returns non-JSON, returns malformed JSON, or is rate-limited. * Worker URL changes while a health check is in flight. * Browser storage is unavailable or contains stale Worker hints. * User is connected to a room while diagnostics report health failure. * Deploy smoke health check fails after `wrangler deploy`. *** ## 10. Dependencies ### External Libraries * No new external libraries are planned. * Existing workspace dependencies: React 18, Zustand, Vite, Vitest, Testing Library, happy-dom, Wrangler, and Cloudflare Worker types. ### Other Sessions * **Depends on**: `phase05-session03-web-room-lifecycle-and-state-store`, `phase05-session04-join-approval-presence-and-reconnect-ux`, `phase05-session05-federation-event-redaction-and-cockpit-integration` * **Depended by**: `phase05-session07-war-room-validation-and-documentation-closeout`, Phase 06 collaboration, isolation, and mobile work *** ## 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase05-session06-deployment-environment-and-diagnostics/spec.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.