> 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/phase19-session05-attention-and-permissions/code-review.md).

# Code Review and Repair Report

**Session ID**: `phase19-session05-attention-and-permissions` **Package**: null **Reviewed**: 2026-06-26 **Scope**: All uncommitted changes in the working tree **Result**: RESOLVED

## Review Surface

**Files reviewed** (all uncommitted changes):

* `.spec_system/state.json` - tracked-modified
* `.spec_system/specs/phase19-session05-attention-and-permissions/implementation-notes.md` - untracked
* `.spec_system/specs/phase19-session05-attention-and-permissions/spec.md` - untracked
* `.spec_system/specs/phase19-session05-attention-and-permissions/tasks.md` - untracked
* `apps/hooks/tests/hookPayloads.test.js` - tracked-modified
* `apps/server/README_server.md` - tracked-modified
* `apps/server/src/lib/commandCenterAttentionAdapters.ts` - untracked
* `apps/server/src/lib/commandCenterValidation.ts` - tracked-modified
* `apps/server/src/managers/orchestrationCommandCenter.ts` - tracked-modified
* `apps/server/src/routes/commandCenter.ts` - tracked-modified
* `apps/server/src/routes/event.ts` - tracked-modified
* `apps/server/src/routes/permission.ts` - tracked-modified
* `apps/server/src/server.ts` - tracked-modified
* `apps/server/src/ws/handlers.ts` - tracked-modified
* `apps/server/tests/commandCenterManager.test.ts` - tracked-modified
* `apps/server/tests/commandCenterRoutes.test.ts` - tracked-modified
* `apps/server/tests/permission.test.ts` - tracked-modified
* `apps/server/tests/websocket.test.ts` - tracked-modified validation repair
* `apps/web/README_web.md` - tracked-modified
* `apps/web/src/components/orchestration/AttentionWorkbench.tsx` - untracked
* `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - tracked-modified
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - tracked-modified
* `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - tracked-modified
* `apps/web/src/components/orchestration/index.ts` - tracked-modified
* `apps/web/src/lib/commandCenterUi.ts` - tracked-modified
* `apps/web/src/lib/orchestrationApi.ts` - tracked-modified
* `apps/web/src/store/useGameStore.ts` - tracked-modified
* `apps/web/tests/OrchestrationPanel.test.tsx` - tracked-modified
* `apps/web/tests/commandCenterStore.test.ts` - tracked-modified
* `apps/web/tests/commandCenterUi.test.ts` - tracked-modified
* `apps/web/tests/orchestrationApi.test.ts` - tracked-modified
* `docs/api/README_api.md` - tracked-modified
* `packages/protocol/src/orchestrationCommandCenter.ts` - tracked-modified
* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - tracked-modified

**Inventory commands**: `git status`, `git diff HEAD`, `git diff --cached`, `git ls-files --others --exclude-standard`

## Findings by Severity

### Critical

* No findings.

### High

* No findings.

### Medium

* `apps/server/src/lib/commandCenterAttentionAdapters.ts:26` - Legacy and hook adapters could generate command-center record ids, attention ids, dedupe keys, and idempotency keys longer than the protocol 100-character id limit. Long but accepted legacy ids could create records that failed shared parser contracts or later blocked valid decisions. | Fix: Added protocol-limit-aware safe id generation with deterministic hash truncation, routed generated adapter keys through it, and made manager-created attention ids use the same helper. Added long legacy id protocol-parser regression coverage in `apps/server/tests/permission.test.ts:106`. | Status: FIXED
* `apps/server/src/managers/orchestrationCommandCenter.ts:497` - `createPermissionRequest` trusted optional `createdAt`, `expiresAt`, and `timeoutMs` input. A malformed hook `expiresAt` could persist an invalid command-center permission or attention timestamp and break typed clients. | Fix: Added timestamp and timeout fallback validation in the manager, and updated hook-ingest route coverage to send a malformed expiration while still parsing the resulting attention record through the protocol validator in `apps/server/tests/commandCenterRoutes.test.ts:298`. | Status: FIXED
* `apps/web/src/components/orchestration/OrchestrationShell.tsx:687` - Web attention decisions generated idempotency keys from the full attention id. A valid 100-character attention id produced an over-limit idempotency key that the server rejected before recording the decision. | Fix: Added `commandCenterClientIdempotencyKey` in `apps/web/src/lib/orchestrationApi.ts:160`, used it for attention decisions, and added max-length id coverage in `apps/web/tests/orchestrationApi.test.ts:439`. | Status: FIXED

### Low

* No findings.

## Assumptions and Deliberate Non-Fixes

* `.spec_system/state.json` was left with `current_session` set to `phase19-session05-attention-and-permissions` because deterministic analysis reported that session as current and the session files are present.
* `code-review.md` is generated by this review step and was not part of the initial implementation surface.

## Behavior Changes

* Long external permission or plan ids are still accepted by compatibility routes, but generated command-center ids and keys are now bounded to the shared 100-character protocol limit with deterministic hash suffixes when truncation is needed.
* Malformed optional permission creation timestamps no longer persist into command-center records; the manager falls back to a valid local timeout window.
* Web attention decision idempotency keys are now bounded before requests are sent.
* Validation repair: WebSocket legacy approval tests now consume the paired command-center create and decision update frames before asserting the trailing legacy compatibility response. Runtime behavior was unchanged.

## Verification

* Tests: `npm test -- packages/protocol/tests/orchestrationCommandCenter.test.ts apps/server/tests/commandCenterManager.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/permission.test.ts apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/commandCenterStore.test.ts apps/web/tests/OrchestrationPanel.test.tsx apps/hooks/tests/hookPayloads.test.js` - PASS - 9 files, 76 tests.
* Linter: `npm run lint` - PASS - Biome checked 670 files with no fixes applied.
* Formatter: `npm run format:check` - PASS - Biome checked 668 files with no fixes applied.
* Type checker: `npm --workspace packages/protocol run typecheck` - PASS.
* Type checker: `npm --workspace apps/server run typecheck` - PASS.
* Type checker: `npm --workspace apps/web run typecheck` - PASS.
* Whitespace: `git diff --check` - PASS.
* Encoding: touched-file ASCII/LF scan - PASS.
* Final diff re-read: no remaining issues found.
* Validation repair: `npm test -- apps/server/tests/websocket.test.ts` - PASS - 12 tests; `npm test` - PASS - 222 files and 2732 tests passed, 1 skipped.

## Summary

1. Reviewed 34 implementation files across spec state, protocol, server, web, hooks, tests, and docs.
2. Fixed 3 medium findings: server command-center id/key bounds, permission creation timestamp validation, and web attention decision idempotency bounds.
3. No deliberate repo-fixable findings remain unfixed.
4. Focused tests, package typechecks, lint, format check, whitespace, and ASCII/LF validation all pass.
5. Reviewed the validation-time WebSocket test repair; it only aligns test expectations with the paired command-center frames plus the preserved legacy response.


---

# 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/phase19-session05-attention-and-permissions/code-review.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.