> 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/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase18-session03-suggestion-routes-and-websocket-parity` **Package**: apps/server **Started**: 2026-06-10 00:09 **Last Updated**: 2026-06-10 00:20

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 22 / 22   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

***

### Task T022 - Validate ASCII encoding and Unix LF line endings

**Started**: 2026-06-10 00:19 **Completed**: 2026-06-10 00:20 **Duration**: 1 minute

**Notes**:

* `git diff --check` passed.
* ASCII and CRLF checks passed for touched server files and session artifacts.

**Files Changed**:

* `.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/tasks.md` - marked the final task and completion checklist.
* `.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.md` - logged final validation.

***

### Task T004 - Create suggestion broadcast helper

**Started**: 2026-06-10 00:11 **Completed**: 2026-06-10 00:13 **Duration**: 2 minutes

**Notes**:

* Added a server-local helper that builds `suggestion_update` hydrate frames and emits mutation snapshots through `SuggestionManager.emitUpdate`.
* Added deterministic grouped `idle_suggestion` compatibility frames from active idle suggestions only.

**Files Changed**:

* `apps/server/src/lib/suggestionBroadcast.ts` - new canonical and compatibility broadcast helpers.

**BQC Fixes**:

* Contract alignment: helper emits only active protocol event shapes and does not expose raw store files or provider payloads.

***

### Task T005 - Create suggestion REST router and validation helpers

**Started**: 2026-06-10 00:13 **Completed**: 2026-06-10 00:14 **Duration**: 1 minute

**Notes**:

* Added route-local safe ID validation, optional JSON body validation, compact `invalid_request` responses, and manager validation error mapping.
* Added per-route in-flight mutation guards returning compact `409 conflict` envelopes.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - new router, validation helpers, error mapping, and mutation guard.

**BQC Fixes**:

* Trust boundary enforcement: route params and optional body IDs validate through protocol safe identifier helpers.
* Duplicate action prevention: accept, suggestion dismiss, and issue dismiss have in-flight locks.

***

### Task T006 - Extend WebSocket context and hydrate helper

**Started**: 2026-06-10 00:14 **Completed**: 2026-06-10 00:14 **Duration**: 1 minute

**Notes**:

* Extended the WebSocket handler context with `SuggestionManager`.
* Added connect-time `suggestion_update` hydration using the helper, including empty manager state.

**Files Changed**:

* `apps/server/src/ws/handlers.ts` - suggestion manager context and hydrate frame.

**BQC Fixes**:

* State freshness on re-entry: every new WebSocket connection receives current manager state.

***

### Task T007 - Mount suggestion router under root and /api

**Started**: 2026-06-10 00:14 **Completed**: 2026-06-10 00:14 **Duration**: 1 minute

**Notes**:

* Mounted the suggestion router inside the existing local route chain so it inherits auth, CORS, rate limiting, and JSON body limits under both root and `/api` prefixes.
* Passed the manager into WebSocket registration.

**Files Changed**:

* `apps/server/src/server.ts` - router mount and WebSocket context wiring.

**BQC Fixes**:

* Trust boundary enforcement: no parallel middleware boundary was introduced.

***

### Task T008 - Refine unsupported-route classification

**Started**: 2026-06-10 00:14 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Removed the blanket `/suggestions` planned prefix.
* Added explicit planned classification for `/suggestions/analyze`, `/suggestions/scan`, and `/suggestions/project-scan` under root and `/api`.

**Files Changed**:

* `apps/server/src/lib/unsupportedRoutes.ts` - narrowed suggestion unsupported classification.

***

### Task T009 - Implement suggestion summary route

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Added `GET /suggestions/summary` returning `{ summary }` from `SuggestionManager.getSummary`.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - summary route.

***

### Task T010 - Implement suggestion dismiss route

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Added `POST /suggestions/:suggestionId/dismiss` with path/body ID validation, in-flight protection, manager mutation, and post-mutation broadcast.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - suggestion dismiss route.

**BQC Fixes**:

* Duplicate action prevention: per-suggestion in-flight lock protects concurrent duplicate dismissals.

***

### Task T011 - Implement issue dismiss route

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Added `POST /issues/:issueId/dismiss` with path/body ID validation, in-flight protection, manager mutation, and post-mutation broadcast.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - issue dismiss route.

**BQC Fixes**:

* Duplicate action prevention: per-issue in-flight lock protects concurrent duplicate dismissals.

***

### Task T012 - Implement accept parsing and manager transition

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Added accept path/body parsing with optional matching `suggestionId` and optional target `heroId`.
* Missing suggestions return `404 not_found` without rollback work because no mutation occurs when the manager returns `undefined`.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - accept route validation and manager transition.

**BQC Fixes**:

* Failure path completeness: missing suggestions return a compact caller-visible `404`.

***

### Task T013 - Implement internal-hero accept branch

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:15 **Duration**: 1 minute

**Notes**:

* Resolves the requested or suggestion-owned hero through `HeroRoster`.
* Returns `send_prompt` with the historical `/internal-heroes/{heroId}/prompt` endpoint and does not execute commands.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - `send_prompt` accept branch.

***

### Task T014 - Implement fallback prompt\_sent branch

**Started**: 2026-06-10 00:15 **Completed**: 2026-06-10 00:16 **Duration**: 1 minute

**Notes**:

* Added the `prompt_sent` response branch when no internal hero resolves.
* Emits a bounded `mission_event` compatibility intent with `kind: "user_prompt"` because the active server-event union does not include a first-class `user_prompt` event.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - fallback accept branch and compatibility intent emission.

**BQC Fixes**:

* Contract alignment: used an existing protocol event shape rather than inventing a server-only event discriminator.

***

### Task T015 - Wire all mutations through shared broadcast helper

**Started**: 2026-06-10 00:16 **Completed**: 2026-06-10 00:16 **Duration**: 1 minute

**Notes**:

* Accept, suggestion dismiss, and issue dismiss all call the same helper after manager mutation.
* The helper emits `suggestion_update` first and compatibility frames from the resulting active idle suggestions.

**Files Changed**:

* `apps/server/src/routes/suggestions.ts` - mutation broadcast calls.
* `apps/server/src/lib/suggestionBroadcast.ts` - shared broadcast behavior.

***

### Task T016 - Add WebSocket suggestion\_update hydrate

**Started**: 2026-06-10 00:16 **Completed**: 2026-06-10 00:16 **Duration**: 1 minute

**Notes**:

* Added deterministic hydrate order: `suggestion_update` follows `notice_board_hydrate` and precedes scroll/achievement frames.
* Did not add any client-to-server suggestion WebSocket messages.

**Files Changed**:

* `apps/server/src/ws/handlers.ts` - hydrate frame.
* `apps/server/tests/websocket.test.ts` - existing hydration expectations updated to drain 11 frames.

***

### Task T017 - Update server README

**Started**: 2026-06-10 00:16 **Completed**: 2026-06-10 00:16 **Duration**: 1 minute

**Notes**:

* Documented shipped summary, accept, suggestion dismiss, and issue dismiss routes.
* Replaced Session 02 no-route wording with Session 03 runtime behavior while keeping scan/analyze/project-scan routes planned.

**Files Changed**:

* `apps/server/README_server.md` - route table and Quest Board notes.

***

### Task T018 - Update unsupported-route tests

**Started**: 2026-06-10 00:16 **Completed**: 2026-06-10 00:16 **Duration**: 1 minute

**Notes**:

* Added regression coverage for still-planned suggestion engine routes under root and `/api`.

**Files Changed**:

* `apps/server/tests/unsupportedRoutes.test.ts` - planned suggestion engine route cases.

***

### Task T019 - Add suggestion route integration tests

**Started**: 2026-06-10 00:16 **Completed**: 2026-06-10 00:17 **Duration**: 1 minute

**Notes**:

* Added tests for `send_prompt`, `prompt_sent`, summary, suggestion dismiss, issue dismiss, `/api` prefix behavior, validation errors, and missing accept records.

**Files Changed**:

* `apps/server/tests/suggestionRoutes.test.ts` - new focused route integration suite.

***

### Task T020 - Add suggestion WebSocket tests

**Started**: 2026-06-10 00:17 **Completed**: 2026-06-10 00:17 **Duration**: 1 minute

**Notes**:

* Added tests for `suggestion_update` hydrate, mutation snapshots, `idle_suggestion` compatibility frames, dismissed item absence, and fallback prompt compatibility intent.

**Files Changed**:

* `apps/server/tests/suggestionWebsocket.test.ts` - new focused WebSocket integration suite.

***

### Task T021 - Run focused tests and server typecheck

**Started**: 2026-06-10 00:17 **Completed**: 2026-06-10 00:18 **Duration**: 1 minute

**Notes**:

* `PATH="$HOME/.nvm/versions/node/v26.2.0/bin:$PATH" npx vitest run apps/server/tests/suggestionRoutes.test.ts apps/server/tests/suggestionWebsocket.test.ts apps/server/tests/unsupportedRoutes.test.ts apps/server/tests/websocket.test.ts` passed.
* `PATH="$HOME/.nvm/versions/node/v26.2.0/bin:$PATH" npm --workspace apps/server run typecheck` passed.

**Files Changed**:

* `apps/server/package.json` - no changes required; existing typecheck script passed.

***

### Task T003 - Verify current WebSocket hydration order and tests

**Started**: 2026-06-10 00:10 **Completed**: 2026-06-10 00:11 **Duration**: 1 minute

**Notes**:

* Verified hydration currently sends connected, roster, mission, notice-board, scroll, achievement, task queue, agent template, mission graph, and guarded action frames.
* Identified strict `readFrames(socket, 10)` expectations that must drain one additional `suggestion_update` hydrate frame.

**Files Changed**:

* `.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.md` - logged WebSocket prerequisite verification.

***

### Task T002 - Verify SuggestionManager route prerequisites

**Started**: 2026-06-10 00:09 **Completed**: 2026-06-10 00:10 **Duration**: 1 minute

**Notes**:

* Confirmed `SuggestionManager` exposes `acceptSuggestion`, `dismissSuggestion`, `dismissIssue`, `getSummary`, `getCurrentState`, and `emitUpdate`.
* Confirmed manager validation uses protocol safe identifiers and throws `SuggestionManagerValidationError` for compact route error mapping.

**Files Changed**:

* `.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.md` - logged manager prerequisite verification.

***

## Task Log

### 2026-06-10 - Session Start

**Environment verified**:

* [x] Deterministic project state confirmed
* [x] `apps/server` package prerequisites confirmed
* [x] Node 26.2.0 available at `~/.nvm/versions/node/v26.2.0/bin/node`
* [x] Directory structure ready

***

### Task T001 - Verify Session 01/02 artifacts, route conventions, and server notes

**Started**: 2026-06-10 00:07 **Completed**: 2026-06-10 00:09 **Duration**: 2 minutes

**Notes**:

* Verified the active session metadata, Phase 18 session notes, server README Quest Board notes, and current REST route conventions.
* Confirmed Session 03 must replace the Session 02 unsupported-route wording for shipped suggestion routes while keeping scan/analyze/project-scan routes deferred.

**Files Changed**:

* `.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.md` - started the session log.

***


---

# 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/phase18-session03-suggestion-routes-and-websocket-parity/implementation-notes.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.