> 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/docs/runbooks/war-room-operations.md).

# War Room Operations Runbook

This runbook covers the optional Cloudflare Worker War Room surface in `apps/warroom`. Core FactionOS local server and web workflows must continue to work without Cloudflare credentials, a Worker URL, hosted auth, hosted storage, analytics, or public replay hosting.

## Quick Status

Use the custom domain first:

```bash
curl --fail --show-error --max-time 8 https://warroom.faction-os.com/health
```

Use the workers.dev URL when isolating custom-domain or DNS issues:

```bash
curl --fail --show-error --max-time 8 \
  https://factionos-warroom.apex-web-services-llc-0d4.workers.dev/health
```

Expected compact health shape:

```json
{
  "ok": true,
  "service": "factionos-warroom",
  "time": "2026-05-30T00:00:00.000Z",
  "rateLimit": { "enabled": true, "max": 240, "windowMs": 60000 },
  "deployment": { "label": "custom-domain", "urlType": "custom-domain" }
}
```

Health output must not include Cloudflare account ids, zone ids, tokens, request headers, client IPs, request bodies, room payloads, prompt content, command output, local paths, exports, scans, media drafts, logs, or local diagnostics.

## Local Wrangler Check

Start local Worker development:

```bash
npm --workspace @factionos/warroom run dev
```

Probe local health:

```bash
curl --fail --show-error --max-time 8 http://127.0.0.1:8790/health
```

Point the web app at local Wrangler with:

```bash
VITE_FACTIONOS_WARROOM_WORKER_URL=http://127.0.0.1:8790
```

Leave `VITE_FACTIONOS_WARROOM_WORKER_URL` blank for local-only mode. Browser users can also clear the Worker URL in War Room hints.

## Deploy And Smoke

Preferred deploy path:

```bash
npm --workspace @factionos/warroom run typecheck
npm --workspace @factionos/warroom run deploy
```

The GitHub Actions workflow `.github/workflows/warroom-deploy.yml` runs a bounded health smoke check after deploy. Set the repository variable `CLOUDFLARE_WARROOM_HEALTH_URL` to override the default `https://warroom.faction-os.com/health` smoke target.

The workflow logs only service, deployment type, and app-level rate-limit enabled/disabled state. It must not print the health URL, raw response body, Cloudflare credentials, account ids, request headers, or tokens.

For Phase 08 production-hosted release smoke, run the root sanitized validator:

```bash
npm run release:hosted-smoke -- --target warroom-worker-custom --target warroom-worker-workers-dev
```

Use no-network mode when recording a credential-free no-claim summary:

```bash
npm run release:hosted-smoke -- --no-network --target warroom-worker-custom --target warroom-worker-workers-dev
```

The hosted smoke report records only target ids, safe hostnames, deployment type validity, app-level rate-limit validity, statuses, timing buckets, docs paths, and issue codes. It does not replace room/socket checks, Cloudflare dashboard review, hosted identity proof, public collaboration safety review, or trusted erasure evidence.

## Room And Socket Checks

Create rooms with the Worker API. The response includes a leader participant, `roomRevision`, and a raw authority token for the requesting browser. Treat the token as sensitive and store it only in a private shell variable while testing:

```bash
curl --fail --show-error --max-time 8 -X POST https://warroom.faction-os.com/rooms
```

Snapshot and socket checks require an existing room code, participant id, and current authority token:

```bash
curl --fail --show-error --max-time 8 \
  "https://warroom.faction-os.com/rooms/ABC234?participant=leader-id&authority=${AUTHORITY_TOKEN}"

npx wscat -c \
  "wss://warroom.faction-os.com/rooms/ABC234/socket?participant=leader-id&authority=${AUTHORITY_TOKEN}"
```

Expected setup failures are compact codes such as `expected_upgrade`, `missing_participant`, `missing_authority`, `invalid_authority`, `expired_authority`, `authority_mismatch`, `pending_approval`, or `forbidden_participant`. Do not paste raw participant payloads, request bodies, authority tokens, auth values, URLs with authority query strings, or local context into incident notes while debugging.

## Authority Failure Triage

Authority failures should stay compact and user-actionable:

* `missing_authority`: the browser does not have a current room token. Ask the user to rejoin or create the room again.
* `invalid_authority`: the token shape or stored hash check failed. Clear local War Room state and rejoin; do not copy the token into logs.
* `expired_authority`: the room authority TTL elapsed. Rejoin or recreate the room.
* `authority_mismatch`: the token belongs to a different room, participant, or role. Verify the selected room code and participant id, then rejoin.
* `stale_room_revision`: the leader acted on an old snapshot. Refresh the room state and retry the decision once.
* `replayed_authority`: the same idempotency key was reused for a different decision. Treat the retry as unsafe and start a fresh user action.
* `only_leader_can_decide`: the requester is not the room leader. Confirm the leader browser still has issued authority.

Authority proves possession of a Worker-issued token in one room only. It does not prove hosted account identity, organization membership, production audit history, public collaboration safety, or trusted erasure. Leave, reset, and authority cleanup do not erase Durable Object room data, browser hints, local logs, archives, exports, replay buffers, backups, or future hosted data.

## Rate Limit And WAF Posture

The Worker app-level limiter defaults to 240 requests per 60000 ms per connecting IP. Tune with:

* `FACTIONOS_RATE_LIMIT_ENABLED`
* `FACTIONOS_RATE_LIMIT_MAX`
* `FACTIONOS_RATE_LIMIT_WINDOW_MS`

Rate-limited responses use status `429`, `Retry-After`, `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers plus a compact `rate_limited` envelope.

Cloudflare managed/OWASP WAF and zone rate-limit rules are dashboard-managed. Follow `docs/runbooks/cloudflare-waf.md` for the current preferred rule set and manual dashboard checklist. Do not replace the existing `Leaked credential check` zone rule unless the tradeoff is explicitly approved.

## Logs And Tail

Use Wrangler tail only when operationally necessary:

```bash
npm --workspace @factionos/warroom run tail
```

Do not paste raw tail output into public issues, docs, or chat. Summarize:

* timestamp window
* route family, such as health, rooms, join, decision, or socket
* compact error code
* response status
* whether rate limiting or WAF was involved

Exclude request headers, IPs, room payloads, participant free text, prompts, command output, tokens, local paths, exports, scans, media drafts, logs, and local diagnostics.

## Rollback

Rollback path:

```bash
git checkout <known-good-ref> -- apps/warroom package.json package-lock.json
npm ci --no-audit --no-fund
npm --workspace @factionos/warroom run typecheck
npm --workspace @factionos/warroom run deploy
curl --fail --show-error --max-time 8 https://warroom.faction-os.com/health
```

Rollback when:

* health fails after deploy
* room creation, join, approval, rejection, or snapshot routes fail broadly
* socket upgrade fails for approved participants
* app-level rate limiting is misconfigured
* privacy-sensitive data appears in Worker diagnostics, web diagnostics, workflow logs, or incident notes

Rollback does not erase Durable Object room data, browser hints, local logs, archives, exports, replay buffers, or future hosted data. Trusted erasure is a later release-hardening scope.

## Worker Room-State Erasure

Phase 08 Session 04 adds a room-local Worker erasure operation for a single Durable Object room record. Use it only when the current room leader can supply room authority, the expected room revision, the exact phrase `ERASE WORKER WAR ROOM STATE`, and an idempotency key.

Operational evidence may record the room code, status, receipt id, boundary labels, counts, socket-closure count, verification status, timestamps, and docs paths. Do not record authority tokens, authority hashes, participant names, participant secrets, raw room payloads, request bodies, local paths, env values, logs, exports, replay buffers, diagnostics, or browser storage values.

This operation deletes the Worker `room` record, closes active sockets, stores a redacted receipt for duplicate confirms, and verifies room absence. It does not erase browser hints, local files, archives, exports, logs, backups, hosted identity, hosted storage, analytics, public replay, push, remote access, or workspace files. Do not describe it as full trusted unified erasure or as hosted identity validation.

## Browser Diagnostics

The web War Room panel reports disabled, invalid URL, unchecked, checking, healthy, connected, offline, timed-out, rate-limited, bad-response, and generic error states. These diagnostics are operational hints only. They do not prove hosted identity, trusted erasure, public sharing safety, hosted storage, analytics availability, or production-hosted app validation.

## Collaboration Frame Triage

Socket frame failures should stay compact:

* `invalid_socket_frame`: unknown type, unknown field, invalid enum, non-finite coordinate, bad participant id, non-persistable catch-up event, malformed JSON, or oversized catch-up envelope.
* `blocked_frame_field`: blocked key or sensitive value such as a prompt, command, terminal output, token, URL, broad path, export, replay buffer, scan payload, diagnostic, log, media draft, backup, archive, or settings value.

Do not copy raw frame bodies, catch-up entries, request URLs with authority query strings, participant free text, prompts, commands, terminal output, tokens, paths, exports, replay buffers, scans, diagnostics, logs, backups, or media drafts into tickets or incident notes. Summarize with room lifecycle state, route family, compact error code, whether the frame was rejected before persistence, and whether catch-up stayed capped at 100 safe events.

## Phase 06 Baseline

Phase 06 Session 01 keeps War Room operations scoped to optional Worker transfer. Authority, collaboration-event, cockpit UX, isolation, mobile, and validation sessions must preserve local-only fallback, local-server separation, compact diagnostics, blocked payload categories, and non-erasure wording from `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md`.

Operational notes, incidents, and release evidence must not treat leave, reset, disconnect, local diagnostics cleanup, or CLI recovery as trusted deletion. They also must not treat local or mocked browser evidence as production-hosted validation or mobile certification.

## Closeout Evidence Expectations

For Phase 06 maintenance, keep evidence local and bounded:

* Run focused protocol, Worker, web, server, CLI, and hook tests before changing room authority, socket frame allowlists, diagnostics, unsupported-route envelopes, isolation posture, or federation behavior.
* Capture app desktop/mobile browser evidence when changing visible War Room states, remote-context UI, reconnect/leave/reset behavior, or mobile collaboration controls.
* Keep health and workflow logs to service, deployment type, status, compact error code, rate-limit state, safe family labels, counts, and timestamps.
* Treat authority as room-local bearer proof only. Do not describe it as hosted identity, account membership, public collaboration safety, production audit history, or trusted erasure.
* Treat guarded actions and isolation diagnostics as non-executing until a future approved executor threat model ships source, tests, and operational docs.
* Treat local or mocked Playwright evidence as local browser evidence only. It is not production-hosted validation, mobile certification, WCAG certification, deployed Worker smoke, or Cloudflare dashboard review.
* Do not paste raw room payloads, request bodies, participant free text, prompts, commands, tokens, paths, exports, scans, media drafts, logs, or local diagnostics into issues, docs, chats, or incident notes.


---

# 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/docs/runbooks/war-room-operations.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.