> 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-session09-heroes-and-lineage/code-review.md).

# Code Review and Repair Report

**Session ID**: `phase19-session09-heroes-and-lineage` **Package**: cross-cutting **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-session09-heroes-and-lineage/code-review.md` - untracked
* `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - untracked
* `.spec_system/specs/phase19-session09-heroes-and-lineage/spec.md` - untracked
* `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - untracked
* `apps/hooks/src/_lib.js` - tracked-modified
* `apps/hooks/src/factionos-hero-spawn.js` - tracked-modified
* `apps/hooks/src/factionos-subagent-start.js` - tracked-modified
* `apps/hooks/tests/hookRuntime.test.js` - tracked-modified
* `apps/server/src/lib/commandCenterValidation.ts` - tracked-modified
* `apps/server/src/lib/guardedActionValidation.ts` - tracked-modified
* `apps/server/src/managers/executorRegistry.ts` - tracked-modified
* `apps/server/src/managers/heroLifecycleManager.ts` - untracked
* `apps/server/src/managers/missionGraph.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/server.ts` - tracked-modified
* `apps/server/tests/commandCenterManager.test.ts` - tracked-modified
* `apps/server/tests/commandCenterRoutes.test.ts` - tracked-modified
* `apps/server/tests/commandCenterValidation.test.ts` - untracked
* `apps/server/tests/eventIngest.test.ts` - tracked-modified
* `apps/server/tests/executorRegistry.test.ts` - tracked-modified
* `apps/server/tests/heroLifecycleManager.test.ts` - untracked
* `apps/server/tests/missionGraph.test.ts` - untracked
* `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - tracked-modified
* `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` - untracked
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - tracked-modified
* `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - tracked-modified
* `apps/web/src/lib/commandCenterUi.ts` - tracked-modified
* `apps/web/src/lib/orchestrationApi.ts` - tracked-modified
* `apps/web/src/lib/orchestrationUi.ts` - tracked-modified
* `apps/web/tests/HeroLineageWorkbench.test.tsx` - untracked
* `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/guardedActions.ts` - tracked-modified
* `packages/protocol/src/lineage.ts` - tracked-modified
* `packages/protocol/src/orchestrationCommandCenter.ts` - tracked-modified
* `packages/protocol/tests/guardedActions.test.ts` - tracked-modified
* `packages/protocol/tests/lineage.test.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

* None.

### High

* `apps/hooks/src/factionos-subagent-start.js:71`, `apps/hooks/src/factionos-hero-spawn.js:108`, `apps/server/src/managers/missionGraph.ts:395` - Hook and server lineage metadata paths accepted bounded-but-raw descriptive text, so live HTTP payloads and externally ingested mission graph descriptions could retain local paths or token-like values. Fix: exported `sanitizeHookText`, applied it before posting hook lifecycle metadata, and redacted server-side mission graph text before roster storage/output. Tests: `apps/hooks/tests/hookRuntime.test.js:404` and `apps/server/tests/missionGraph.test.ts:60`. Status: FIXED

### Medium

* `apps/server/src/managers/missionGraph.ts:469`, `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx:315` - Filtering for `state=degraded` only matched rows whose raw state was `degraded`, excluding active rows with a `degradedReason` that were counted and displayed as degraded. Fix: server and client degraded filters now include rows with any `degradedReason`. Tests: `apps/server/tests/missionGraph.test.ts:103` and `apps/web/tests/HeroLineageWorkbench.test.tsx:66`. Status: FIXED
* `apps/server/src/managers/heroLifecycleManager.ts:102` - Lifecycle commands without optional `idempotencyKey` derived the same command id for each `{heroId, kind}` pair, causing a later distinct command to conflict after the first reached a terminal audit state. Fix: no-key submissions now use a timestamp/sequence nonce while idempotency-keyed submissions remain stable. Test: `apps/server/tests/heroLifecycleManager.test.ts:81`. Status: FIXED

### Low

* `docs/api/README_api.md:219` - API docs described the hero lifecycle command `requester` field as optional even though server validation requires it. Fix: corrected the endpoint body table to mark `requester` required. Status: FIXED
* `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md:14`
  * The session progress summary still reported partial completion while all task sections were complete. Fix: updated the progress summary to 25 / 25 tasks and 0 hours remaining. Status: FIXED

## Assumptions and Deliberate Non-Fixes

* Hero lifecycle action intents remain command-center audit state only, with no local executor process control, matching the session spec and API docs. No process execution was added.
* Rows with a `degradedReason` should match the degraded filter even when their lifecycle state is still `active` or `completed`, because the roster counts and UI labels already classify those rows as degraded.
* No deliberate non-fixes remain.

## Behavior Changes

* The degraded lineage roster filter now returns every row classified as degraded by roster counts, including active rows with missing parent/child mission lineage.
* Repeated hero lifecycle submissions without `idempotencyKey` now create distinct audit records. Calls with the same `idempotencyKey` still dedupe.
* Hook lineage descriptions and lifecycle labels, plus server-ingested mission graph descriptions, are redacted before live exposure.
* Documentation and session notes now match implemented validation/progress.

## Verification

* Tests: `npm test -- apps/server/tests/heroLifecycleManager.test.ts apps/server/tests/missionGraph.test.ts apps/hooks/tests/hookRuntime.test.js apps/web/tests/HeroLineageWorkbench.test.tsx` - PASS - 4 files, 21 tests
* Tests: `npm test` - PASS - 235 files and 2833 tests passed; 1 file/test skipped
* Linter: `npm run lint` - PASS
* Formatter: `npm run format:check` - PASS
* Type checker: `npm run typecheck` - PASS
* Whitespace: `git diff --check` - PASS
* Encoding: ASCII/LF validation across all uncommitted files - PASS
* Final diff re-read: no remaining issues.

## Summary

1. Reviewed 44 uncommitted files across spec artifacts, protocol contracts, server managers/routes, hooks, web orchestration UI, docs, and tests.
2. Findings: 0 critical, 1 high, 2 medium, 2 low; all were fixed.
3. No deliberate non-fixes remain; assumptions are recorded above.
4. Full format, lint, typecheck, test, whitespace, and encoding checks passed.


---

# 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-session09-heroes-and-lineage/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.