> 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_17/session_03_server_routes_and_websocket_parity.md).

# Session 03: Server Routes And WebSocket Parity

**Session ID**: `phase17-session03-server-routes-and-websocket-parity` **Packages**: apps/server, packages/protocol **Status**: Completed **Validated**: 2026-06-05 **Estimated Tasks**: \~18-25 **Estimated Duration**: 2-4 hours

***

## Objective

Restore canonical Notice Board REST routes and WebSocket events while preserving current compatibility paths.

***

## Scope

### In Scope (MVP)

* Add canonical routes:
  * `GET /notice-board`
  * `GET /notice-board/context`
  * `POST /notice-board`
  * `POST /notice-board/:id/resolve`
* Keep compatibility routes:
  * `GET /notices`
  * `POST /notice`
* Ensure `GET /notice-board` accepts `type`, `since`, `forSession`, `limit`, `offset`, `includeResolved`, `roomCode`, and `debug=1`.
* Return `{ messages, total }` from canonical list routes.
* Return `{ notices }` from compatibility `/notices`.
* Return `{ context }` from context route.
* Validate `type` and `content` as required for canonical posts.
* Enforce recovered type validation.
* Cap `content` at 2000 characters.
* Normalize `authorName`, `authorSessionId`, `authorType`, `authorAvatarUrl`, `priority`, `tags`, `targetSessionIds`, `parentMessageId`, and `relatedFiles`.
* Sanitize `relatedFiles` to safe repository- or worktree-relative paths inside current project boundaries.
* Store posts in the active War Room code when connected or the local standalone room id when not connected.
* Emit `notice_board_message` on canonical and compatibility posts.
* Add `POST /notice-board/:id/resolve` with active-room resolution, `notice_resolved` emission, and `{ success: true }` response.
* Update WebSocket hydration to send active-room notices.
* Update WebSocket `post_notice` handling to accept expanded notice input while preserving current `body`, `severity`, and `targets` behavior.
* Emit and handle `notice_board_hydrate`, `notice_board_message`, and `notice_resolved` event shapes with compatibility keys where needed.
* Add server route and WebSocket tests proving real-mode post, hydrate, and resolve behavior without mock mode.

### Out of Scope

* Web UI rendering.
* CLI command implementation.
* Hook context implementation.
* Worker relay implementation.
* Automatic mission lifecycle posts.

***

## Prerequisites

* [ ] Session 01 protocol contracts completed.
* [ ] Session 02 manager behavior completed.
* [ ] Current server auth, CORS, and request validation helpers reviewed.

***

## Deliverables

1. Canonical Notice Board route family.
2. Compatibility `/notice` and `/notices` adapters.
3. Expanded WebSocket hydrate, post, and resolve behavior.
4. Safe related-file normalization.
5. Focused server route and WebSocket tests.

***

## Task Expansion Guidance

When expanded with `plansession`, keep the checklist to 18-25 tasks covering:

* Route placement audit.
* Active room id helper.
* Query validation.
* Canonical list route.
* Compatibility list route.
* Context route.
* Canonical post body validation.
* Compatibility post adapter.
* Author metadata normalization.
* Tags and target normalization.
* Related-file sanitizer.
* Resolve route.
* Broadcaster event updates.
* WebSocket hydrate update.
* WebSocket `post_notice` compatibility.
* WebSocket resolve path if needed.
* Debug provenance response shape.
* Route tests.
* WebSocket tests.
* Real-mode no-mock test.

***

## Success Criteria

* [ ] `POST /notice-board` stores a notice and emits `notice_board_message`.
* [ ] `GET /notice-board/context?sessionId=<id>` returns relevant context only.
* [ ] `POST /notice-board/:id/resolve` emits `notice_resolved`.
* [ ] `/notice`, `/notices`, and `post_notice` compatibility paths still work.
* [ ] Unsafe related files are rejected or dropped before storage.
* [ ] Server tests prove the board works with `FACTIONOS_MOCK=false`.


---

# 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_17/session_03_server_routes_and_websocket_parity.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.