> 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/phase17-session07-war-room-worker-relay-and-catchup/spec.md).

# Session Specification

**Session ID**: `phase17-session07-war-room-worker-relay-and-catchup` **Phase**: 17 - Notice Board Coordination Parity **Status**: Not Started **Created**: 2026-06-05 **Package**: Cross-package (`packages/protocol`, `apps/warroom`) **Package Stack**: TypeScript shared protocol plus Cloudflare Worker Durable Object

***

## 1. Session Overview

This session restores optional War Room Worker relay support for canonical Notice Board coordination frames. Sessions 01 through 06 already established the expanded Notice Board model, server routes, WebSocket events, web store, CLI commands, and hook context access. The next step is to let room participants relay safe Notice Board messages, resolutions, and bounded catch-up through the Worker without weakening the redacted War Room boundary.

The implementation starts in `packages/protocol/src/warroom.ts` because Worker socket frames are protocol-owned. New frame contracts must be typed, bounded, validated, blocked-field aware, and exported before the Worker stores or broadcasts them. The Worker then persists a bounded Notice Board relay history, broadcasts message and resolution frames to peers other than the sender, and sends filtered `notice_board_catchup` frames to reconnecting participants.

The privacy boundary is the main constraint. Notice Board relay may carry explicit coordination notices only. It must not expose raw prompts, transcripts, terminal output, command bodies, file contents, secrets, broad absolute paths, exports, replay buffers, scans, media drafts, diagnostics, logs, backups, quarantined historical content, hosted identity claims, production auditability claims, public collaboration safety claims, or trusted erasure claims.

***

## 2. Objectives

1. Add protocol-owned Worker frame contracts for `notice_board_message`, `notice_resolved`, and `notice_board_catchup`.
2. Extend Worker socket handling to validate, persist, and sender-excluded broadcast Notice Board message and resolution frames.
3. Send reconnecting participants a bounded, filtered Notice Board catch-up frame without leaking blocked fields or stale unsafe history.
4. Add focused protocol and Worker tests for relay, resolution, catch-up, sender exclusion, bounded history, malformed frames, blocked fields, and legacy-safe filtering.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase17-session01-protocol-notice-contract-parity` - provides canonical Notice Board types, priorities, aliases, and validation helpers.
* [x] `phase17-session02-server-notice-manager-persistence-and-context` - provides canonical room-scoped Notice Board filtering and resolution expectations.
* [x] `phase17-session03-server-routes-and-websocket-parity` - provides canonical realtime event names and local compatibility expectations.
* [x] `phase17-session04-web-store-and-cockpit-notice-board` - provides web consumer expectations for `notice_board_message` and `notice_resolved`.
* [x] `phase17-session05-cli-notice-commands` - provides first-party agent command access to the local canonical board.
* [x] `phase17-session06-hook-context-and-provider-skill-parity` - provides prompt-start Notice Board context access and reminder behavior.

### Required Tools/Knowledge

* Node 26.2.0 or newer with npm workspaces.
* TypeScript protocol contracts in `packages/protocol/src`.
* Cloudflare Worker Durable Object patterns in `apps/warroom/src/index.ts`.
* Existing Worker socket validation, sender-excluded broadcast, bounded catch-up, and blocked-field tests.
* Phase 05 and Phase 06 War Room privacy and federation baselines.

### Environment Requirements

* Work from the repository root.
* Use package-relative monorepo paths from the repo root.
* Keep all generated and edited files ASCII-only with Unix LF line endings.
* Use local fake Durable Object storage and fake WebSocket helpers in tests; do not require Cloudflare credentials or a live deployed Worker.

***

## 4. Scope

### In Scope (MVP)

* Worker clients can send `notice_board_message` frames carrying canonical coordination notice payloads only - implement shared validation before persistence or broadcast.
* Worker clients can send `notice_resolved` frames carrying a notice id plus bounded safe resolution metadata where needed - update relay state and sender-excluded broadcast.
* Reconnecting Worker clients receive `notice_board_catchup` with a bounded array of safe notices derived from filtered Worker relay history.
* Worker relay frames remain typed, bounded, sender-excluded, and blocked-field validated before persistence, diagnostics, logs, catch-up, or browser consumption.
* Existing `warroom_pending_catchup` behavior for presence, cursor, focus, hero, mission, and `warroom_room_notice` frames remains intact.
* Existing safe `warroom_room_notice` behavior remains usable for current web clients and is not silently reinterpreted as a hosted identity, analytics, public replay, or auditability feature.
* Protocol and Worker tests cover relay, resolution, catch-up, sender exclusion, bounded history, malformed frames, blocked fields, legacy-safe filtering, and compact no-leak diagnostics.

### Out of Scope (Deferred)

* Local server War Room client send and ingest paths - Reason: Session 08 owns local bridge and room notice convergence.
* Web cockpit Notice Board rendering changes - Reason: Session 04 completed cockpit rendering and Session 08 owns convergence wiring.
* CLI and hook behavior - Reason: Sessions 05 and 06 completed these access paths.
* Automatic mission lifecycle posts - Reason: Session 09 owns automatic status and completion posts.
* Hosted identity, hosted storage, public replay hosting, analytics capture, public collaboration safety, production auditability, and trusted unified erasure - Reason: these remain explicit no-claims.

***

## 5. Technical Approach

### Architecture

Extend `packages/protocol/src/warroom.ts` first. The protocol layer should add Notice Board relay frame names to the Worker-safe frame vocabulary, define typed message and resolution frames, define the server catch-up frame, and validate all Notice Board payloads through existing Notice Board normalizers and the War Room blocked-field scanner. Any unsafe shape must fail closed with the existing deterministic `invalid_socket_frame` or `blocked_frame_field` envelope.

Update `apps/warroom/src/index.ts` after the protocol contracts exist. The Durable Object should continue to hydrate persisted room state defensively, filter stored history before use, and preserve sender-excluded broadcasts. For Notice Board relay frames, it should keep a bounded relay history that can produce a safe `notice_board_catchup` frame for reconnecting participants. A resolution frame should update the bounded catch-up state for the matching notice id while still broadcasting the resolution event to peers.

Keep legacy War Room event behavior stable. The existing `warroom_pending_catchup` frame remains the catch-up path for older War Room event families. The new `notice_board_catchup` frame is additive and only carries validated Notice Board notices. Worker health, error envelopes, landing HTML, deploy metadata, rate-limit metadata, and room snapshots should not expose relay payloads.

### Design Patterns

* Protocol-led cross-package change: shared frame types and validators land before Worker-specific logic.
* Fail-closed external input handling: unknown fields, malformed frames, blocked keys, unsafe notice payloads, and oversized catch-up arrays return compact protocol errors before persistence.
* Sender-excluded federation: broadcast relayed notice frames only to other connected participants.
* Bounded storage: cap Worker relay history and filter persisted history during hydrate, persist, and catch-up generation.
* Additive compatibility: preserve existing `warroom_room_notice` and `warroom_pending_catchup` behavior while adding Notice Board frames.

### Technology Stack

* TypeScript in `packages/protocol` and `apps/warroom`.
* Vitest through the root workspace test configuration.
* Cloudflare Worker Durable Object APIs and existing fake storage/WebSocket test harnesses.
* No new runtime dependencies.

***

## 6. Deliverables

### Files to Create

| File                                                 | Purpose                                                                                                           | Est. Lines |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/tests/warroomNoticeRelay.test.ts` | Focused protocol tests for Notice Board relay frame contracts, validation, bounds, and blocked fields             | \~240      |
| `apps/warroom/tests/noticeBoardRelay.test.ts`        | Focused Worker tests for message relay, resolution relay, catch-up, sender exclusion, bounds, and legacy behavior | \~420      |

### Files to Modify

| File                               | Changes                                                                                                                      | Est. Lines |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/warroom.ts` | Add Notice Board Worker frame types, validators, safe recent-event filtering, catch-up validation, and summaries             | \~260      |
| `apps/warroom/src/index.ts`        | Persist bounded Notice Board relay history, relay message/resolution frames, send catch-up, and filter unsafe stored history | \~240      |
| `apps/warroom/README_warroom.md`   | Document Notice Board relay frames, optional external-transfer boundary, catch-up behavior, and no-claim limits              | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `packages/protocol` exports Worker frame support for `notice_board_message`, `notice_resolved`, and `notice_board_catchup`.
* [ ] Worker socket parsing accepts valid Notice Board message and resolution relay frames and rejects malformed or unknown fields.
* [ ] Worker broadcasts `notice_board_message` to room peers without echoing to the sender.
* [ ] Worker broadcasts `notice_resolved` to room peers and updates bounded catch-up state for the matching notice id.
* [ ] Reconnecting Worker clients receive `notice_board_catchup` with bounded, safe Notice Board notices.
* [ ] Existing `warroom_pending_catchup` and `warroom_room_notice` behavior remains compatible for current web clients.
* [ ] Unsafe or malformed Notice Board relay frames fail closed before persistence, diagnostics, logs, catch-up, or browser consumption.

### Testing Requirements

* [ ] Protocol tests cover frame constants, type unions, parser success, parser failures, catch-up bounds, blocked fields, and safe event filtering.
* [ ] Worker tests cover message relay, resolution relay, catch-up, sender exclusion, bounded history, persisted unsafe-history filtering, malformed frames, blocked fields, and legacy `warroom_room_notice` behavior.
* [ ] Focused protocol and Worker tests run successfully.
* [ ] ASCII and LF validation passes for new session artifacts.

### Non-Functional Requirements

* [ ] Worker relay remains optional external transfer and redacted.
* [ ] Worker relay does not expose raw prompts, transcripts, terminal output, command bodies, file contents, secrets, broad absolute paths, exports, replay buffers, scans, media drafts, diagnostics, logs, backups, or quarantined historical content.
* [ ] Worker health, room snapshots, diagnostics, errors, and docs do not imply hosted identity, hosted storage, analytics, public replay, production auditability, public collaboration safety, or trusted erasure.
* [ ] Relay history is bounded deterministically and filtered before reconnect catch-up.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new runtime dependencies.

***

## 8. Implementation Notes

### Key Considerations

* `packages/protocol/src/warroom.ts` already owns safe Worker frame parsing, blocked-field detection, recent-event validation, catch-up validation, and family summaries. Keep the new Notice Board relay contracts in that module.
* `packages/protocol/src/notices.ts` already owns canonical notice aliases, type, priority, author, target, related-file, and content normalization. Reuse these helpers instead of duplicating Notice Board validation.
* `apps/warroom/src/index.ts` already sender-excludes `remote_event` frames and caps `recentEvents` to `WAR_ROOM_MAX_RECENT_EVENTS`. The Notice Board relay history should use the same bounded posture.
* Existing Worker deploy and health docs are no-claim unless an authorized environment proves live Worker validation.

### Potential Challenges

* Message versus catch-up frame ownership: keep message and resolution frames as client relay inputs, and keep `notice_board_catchup` as an additive server frame for reconnecting clients.
* Safe stored history migration: hydrate should filter persisted unsafe or obsolete records before any reconnecting participant receives catch-up.
* Resolution state in catch-up: apply resolution frames to bounded notice state so reconnecting clients do not receive stale unresolved copies for notices that the Worker saw resolved.
* Legacy compatibility: do not remove or rename existing `remote_event`, `warroom_pending_catchup`, or `warroom_room_notice` behavior.

### Relevant Considerations

* \[P03-packages/protocol] **Protocol leads cross-package work**: Notice Board Worker frame contracts must land in `packages/protocol` before Worker behavior changes.
* \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker relay can carry explicit coordination messages only and must not imply hosted identity, public collaboration safety, production auditability, certification, or full erasure.
* \[P07] **Redaction is boundary-specific**: Worker relay, catch-up, logs, diagnostics, health, errors, and docs each need explicit minimization.
* \[P03] **Stable docs are the current contract**: `EXAMPLES/` remains evidence only; current package docs and source-backed protocol contracts become the live contract.
* \[P08] **Release evidence is claim-scoped**: Local Worker tests are not live production-hosted validation or trusted erasure proof.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* External socket frames could persist unsafe payloads if validation happens after storage or broadcast.
* Reconnect catch-up could replay stale, duplicate, resolved, or unsafe notices if Worker history is not filtered and bounded.
* Sender-excluded broadcast could regress and echo a participant's own Notice Board frame back to the sender.

***

## 9. Testing Strategy

### Unit Tests

* Protocol validator tests for `notice_board_message`, `notice_resolved`, and `notice_board_catchup`.
* Protocol tests for blocked-field rejection, unknown-field rejection, notice content bounds, target bounds, catch-up length bounds, and safe recent-event filtering.

### Integration Tests

* Worker Durable Object tests using fake storage and fake WebSocket pairs for message relay, resolution relay, reconnect catch-up, sender exclusion, bounded history, persisted unsafe-history filtering, malformed socket frames, and legacy `warroom_room_notice` preservation.

### Manual Testing

* Review Worker README and protocol frame names for compatibility with Session 08 local bridge requirements.
* Inspect serialized test frames and Worker errors to confirm no raw prompts, commands, transcripts, files, secrets, absolute paths, diagnostics, logs, or tokens appear.

### Edge Cases

* Empty Notice Board relay history should not send noisy catch-up.
* Oversized or malformed Notice Board catch-up arrays should fail closed.
* Resolution for an unknown notice id should broadcast safely but not create an unsafe catch-up notice.
* Stored unsafe legacy history should be filtered before persist and before reconnect catch-up.
* Existing non-Notice War Room frames should continue to relay and catch up as before.

***

## 10. Dependencies

### External Libraries

* None. Use existing TypeScript, protocol helpers, Worker APIs, and Vitest.

### Internal Dependencies

* `packages/protocol/src/notices.ts` for canonical Notice Board types and normalization helpers.
* `packages/protocol/src/warroom.ts` for War Room socket frame validation, blocked-field scanning, safe event filtering, and error envelopes.
* `apps/warroom/src/index.ts` for Durable Object persistence, socket relay, sender exclusion, and reconnect catch-up.
* `apps/warroom/README_warroom.md` for package-level Worker boundary docs.

### Other Sessions

* **Depends on**: Sessions 01-06 in Phase 17.
* **Enables**: `phase17-session08-local-war-room-bridge-and-room-notice-convergence`.

***

## 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/phase17-session07-war-room-worker-relay-and-catchup/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.