> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase19-session09-heroes-and-lineage` **Package**: cross-cutting **Started**: 2026-06-26 13:57 IDT **Last Updated**: 2026-06-26 15:18 IDT *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 25 / 25 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-06-26 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Verify sessions 01-08 validation artifacts and current hero/lineage prerequisites **Started**: 2026-06-26 13:55 IDT **Completed**: 2026-06-26 13:57 IDT **Duration**: 2 minutes **Notes**: * Verified prerequisite sessions 01 through 08 all have validation reports with `Result: PASS`. * Confirmed session 08 explicitly validates the bounded File/Git workbench and local-first no-execution boundary that this session must preserve. * Confirmed sessions 01 through 08 provide protocol, server backbone, web shell/store, attention/permissions, executor registry, diagnostics, and file/git prerequisites for this session. **Files Changed**: * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - initialized implementation notes and recorded T001 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T001 complete and added a progress summary. **Verification**: * Command/check: `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/analyze-project.sh --json; else bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/analyze-project.sh --json; fi` * Result: PASS - current session resolved. * Evidence: Current session is `phase19-session09-heroes-and-lineage`; monorepo is true; `Package: null` resolved this as cross-cutting. * Command/check: `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/check-prereqs.sh --json --env; else bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env; fi` * Result: PASS - base environment verified. * Evidence: spec system, `jq`, `git`, and npm workspace manager checks passed. * Command/check: `if [ -d ".spec_system/scripts" ]; then bash .spec_system/scripts/check-prereqs.sh --json --tools "node,npm"; else bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/check-prereqs.sh --json --tools "node,npm"; fi` * Result: PASS - required tools available. * Evidence: checker reported Node `v24.14.0` and npm `11.16.0` as pass. * Command/check: `sed -n '1,220p' .spec_system/specs/phase19-session01-protocol-and-events/validation.md` through `phase19-session08-file-and-git/validation.md` * Result: PASS - all prerequisite validation reports exist and report PASS. * Evidence: sessions 01, 02, 03, 04, 05, 06, 07, and 08 each report `Result: PASS` with no unresolved blockers. * UI product-surface check: N/A - T001 changed only spec-system implementation notes and task status. * UI craft check: N/A - no user-facing UI changed. *** ### Task T002 - Map existing lifecycle, executor, hook, and lineage gaps before implementation **Started**: 2026-06-26 13:57 IDT **Completed**: 2026-06-26 13:58 IDT **Duration**: 1 minute **Notes**: * Protocol lifecycle support currently exposes `spawn`, `pause`, `resume`, `stop`, `restart`, `assign`, and `release`; the session requires spawn, fork, handoff, resume, message, stop, dismiss, model change, permission mode change, and isolation mode change, while preserving prior aliases where practical. * `CommandCenterHeroLifecycleCommand` has compact state fields, but no server-owned lifecycle manager and no lifecycle command route is wired in `apps/server/src/routes/commandCenter.ts`. * `MissionGraphManager` tracks nodes and edges and emits `subagent_lineage_update` and `mission_graph_update`, but it does not yet expose operator roster rows, roster filters, pagination, duration fields, or display labels. * Hook payloads already include model and permission data for hero spawn and subagent association data for subagent start, but they need bounded terminal/listener/process and parent/child/type/description associations. * Web code already hydrates a generic command-center `heroes` collection and receives lifecycle WebSocket frames, but there is no typed lifecycle mutation helper, no lineage roster snapshot helper, no dedicated Hero/Lineage tab, and no roster filter UI. **Files Changed**: * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded the source gap map. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T002 complete and advanced progress. **Verification**: * Command/check: `rg -n "HeroLifecycle|hero lifecycle|lifecycle|CommandCenterHero|lineage|subagent|Roster|GuardedAction|Executor" packages/protocol/src/orchestrationCommandCenter.ts packages/protocol/src/lineage.ts packages/protocol/src/guardedActions.ts` * Result: PASS - protocol gap mapped. * Evidence: lifecycle command values and parsers exist; lineage graph types exist; roster/filter types do not yet exist. * Command/check: `rg -n "parseHeroLifecycle|saveHeroLifecycle|heroLifecycle" apps/server/src/routes/commandCenter.ts apps/server/src/server.ts apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/commandCenterManager.test.ts` * Result: PASS - missing lifecycle route confirmed. * Evidence: no matches found for route-level lifecycle command handling. * Command/check: `sed -n '1,420p' apps/server/src/managers/missionGraph.ts` * Result: PASS - mission graph implementation inspected. * Evidence: manager supports nodes, edges, duplicate events, degradation, snapshots, and event snapshots, but no operator roster method. * Command/check: `rg -n "hero|lifecycle|lineage|subagent|process|listener|terminal|permission|model" apps/hooks/src/factionos-hero-spawn.js apps/hooks/src/factionos-subagent-start.js apps/hooks/tests/hookRuntime.test.js` * Result: PASS - hook metadata gap mapped. * Evidence: hero spawn has model/permission and listener spawn evidence; subagent start has parent/subagent/type metadata but not the full bounded association surface. * Command/check: `sed -n '1,180p' apps/web/src/lib/orchestrationApi.ts`; `sed -n '1265,1465p' apps/web/src/store/useGameStore.ts`; `sed -n '1,260p' apps/web/src/components/orchestration/CommandCenterPanes.tsx` * Result: PASS - web integration gap mapped. * Evidence: generic hero lifecycle collection exists; no dedicated Hero/Lineage workbench or lineage roster collection exists. * UI product-surface check: N/A - T002 changed only spec-system implementation notes and task status. * UI craft check: N/A - no user-facing UI changed. *** ### Task T003 - Create focused lifecycle manager test fixtures for command validation, transitions, duplicates, unavailable states, and redaction **Started**: 2026-06-26 13:58 IDT **Completed**: 2026-06-26 14:04 IDT **Duration**: 6 minutes **Notes**: * Added focused Vitest coverage for lifecycle command validation, idempotency dedupe, stale revision conflict handling, unavailable execution explanations, approved-not-executing audit state, and redaction. * Added a server-owned `HeroLifecycleManager` so the test fixtures pass without leaving failing test debt. * Expanded lifecycle and guarded-action enum maps needed by the manager tests and server typecheck; these changes will receive dedicated protocol test coverage in T004 through T008. **Files Changed**: * `apps/server/tests/heroLifecycleManager.test.ts` - added focused lifecycle manager fixtures. * `apps/server/src/managers/heroLifecycleManager.ts` - added local-first lifecycle audit manager used by the fixtures. * `packages/protocol/src/orchestrationCommandCenter.ts` - expanded lifecycle/executor vocabulary and bounded lifecycle metadata fields required by the manager fixtures. * `packages/protocol/src/guardedActions.ts` - added lifecycle-adjacent guarded action kinds and families required by exhaustive maps. * `apps/server/src/lib/guardedActionValidation.ts` - updated guarded family/kind validation map for new lifecycle-adjacent kinds. * `apps/server/src/managers/executorRegistry.ts` - updated guarded-to-executor exhaustive maps for new lifecycle-adjacent kinds and families. * `apps/server/src/managers/orchestrationCommandCenter.ts` - included bounded lifecycle metadata in compact lifecycle event entries and updated executor kind family mapping. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T003 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T003 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/heroLifecycleManager.test.ts` * Result: PASS - focused lifecycle manager fixtures passed. * Evidence: 1 test file passed; 4 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0 after exhaustive maps were updated. * UI product-surface check: N/A - T003 changed protocol/server runtime and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Duplicate action prevention: added idempotency-key dedupe for lifecycle commands (`apps/server/src/managers/heroLifecycleManager.ts`). * Trust boundary enforcement: lifecycle inputs are parsed through `parseCommandCenterHeroLifecycleCommand` before storage (`apps/server/src/managers/heroLifecycleManager.ts`). * Error information boundaries: lifecycle summaries and labels are redacted with `redactSensitiveText` before parser/storage (`apps/server/src/managers/heroLifecycleManager.ts`). *** ### Task T004 - Extend command-center hero lifecycle contracts with expanded intent values and bounded metadata fields **Started**: 2026-06-26 14:04 IDT **Completed**: 2026-06-26 14:05 IDT **Duration**: 1 minute **Notes**: * Expanded command-center lifecycle intents to include fork, handoff, message, dismiss, model change, permission mode change, and isolation mode change while preserving prior pause, restart, assign, and release aliases. * Added `approved_not_executing` lifecycle state for audit-only approvals that do not run a local executor. * Added bounded lifecycle metadata fields for model, permission mode, isolation mode, worktree label, process label, terminal label, listener label, event count, approval time, and completion time. * Extended compact lifecycle event entries with the same bounded metadata needed by WebSocket consumers. **Files Changed**: * `packages/protocol/src/orchestrationCommandCenter.ts` - expanded lifecycle values, state values, lifecycle command fields, lifecycle event fields, and parser handling. * `apps/server/src/managers/orchestrationCommandCenter.ts` - emitted bounded lifecycle metadata in compact lifecycle update events. * `apps/server/src/managers/executorRegistry.ts` - carried new lifecycle-adjacent executor kinds in exhaustive maps. * `apps/server/src/lib/guardedActionValidation.ts` - carried new lifecycle-adjacent guarded kinds in exhaustive validation maps. * `apps/server/src/managers/heroLifecycleManager.ts` - consumed expanded lifecycle contract. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T004 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T004 complete and advanced progress. **Verification**: * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0. * Command/check: `rg -n "COMMAND_CENTER_HERO_LIFECYCLE_COMMAND_VALUES|approved_not_executing|modelId|message_hero|change_isolation_mode" packages/protocol/src/orchestrationCommandCenter.ts packages/protocol/src/guardedActions.ts apps/server/src/managers/orchestrationCommandCenter.ts apps/server/src/managers/executorRegistry.ts apps/server/src/lib/guardedActionValidation.ts` * Result: PASS - expanded lifecycle contract and exhaustive maps are present. * Evidence: output shows new lifecycle values, metadata fields, parser handling, event metadata, and guarded/executor maps. * UI product-surface check: N/A - T004 changed protocol/server contract code only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: updated protocol values, parser fields, event entries, and server exhaustive maps together so lifecycle enums do not drift across packages. *** ### Task T005 - Extend lineage contracts with operator roster rows, filters, snapshots, degraded explanations, bounded pagination, validated filters, and deterministic ordering **Started**: 2026-06-26 14:05 IDT **Completed**: 2026-06-26 14:07 IDT **Duration**: 2 minutes **Notes**: * Added lineage roster row, filter, counts, snapshot, validation result, and bounded limit contracts. * Added degraded reason display labels for UI and API consumers. * Added parser helpers for roster filters, rows, and snapshots with bounded IDs, text, timestamps, counts, limits, and result/state validation. **Files Changed**: * `packages/protocol/src/lineage.ts` - added lineage roster contracts, degraded reason labels, bounded parser helpers, and limit constants. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T005 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T005 complete and advanced progress. **Verification**: * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0. * Command/check: `rg -n "LineageRoster|lineageDegradedReasonLabel|LINEAGE_ROSTER" packages/protocol/src/lineage.ts` * Result: PASS - lineage roster contract and parser helpers are present. * Evidence: output shows `LineageRosterFilters`, `LineageRosterRow`, `LineageRosterSnapshot`, counts, validation result, labels, parser helpers, and bounded limits. * UI product-surface check: N/A - T005 changed protocol contracts only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: lineage rows, filters, counts, snapshots, display labels, and parser helpers now live in the shared protocol package. *** ### Task T006 - Extend guarded-action lifecycle proposal kinds for message, dismiss, model, permission, and isolation intents **Started**: 2026-06-26 14:07 IDT **Completed**: 2026-06-26 14:08 IDT **Duration**: 1 minute **Notes**: * Added guarded-action families for model, permission, and isolation lifecycle posture. * Added lifecycle-adjacent guarded-action kinds for message, dismiss, model changes, permission mode changes, and isolation mode changes. * Updated server exhaustive maps that validate guarded-action family/kind compatibility and translate guarded kinds to command-center executor kinds. * Updated existing guarded-action contract tests to assert the expanded vocabulary. **Files Changed**: * `packages/protocol/src/guardedActions.ts` - added lifecycle-adjacent families, kinds, and labels. * `packages/protocol/tests/guardedActions.test.ts` - updated vocabulary expectations for the new lifecycle-adjacent guarded actions. * `apps/server/src/lib/guardedActionValidation.ts` - updated family/kind compatibility map. * `apps/server/src/managers/executorRegistry.ts` - updated guarded-to-executor family and kind maps. * `apps/server/src/managers/orchestrationCommandCenter.ts` - updated executor kind family map for the new lifecycle-adjacent kinds. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T006 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T006 complete and advanced progress. **Verification**: * Command/check: `npm test -- packages/protocol/tests/guardedActions.test.ts` * Result: PASS - guarded-action contract fixtures passed. * Evidence: 1 test file passed; 3 tests passed. * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server exhaustive TypeScript maps passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T006 changed protocol/server contract code and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: guarded-action values, labels, validation maps, and executor translation maps now agree across protocol and server. *** ### Task T007 - Add protocol tests for lifecycle intent parsing, compatibility aliases, compact event entries, and blocked payload rejection **Started**: 2026-06-26 14:08 IDT **Completed**: 2026-06-26 14:10 IDT **Duration**: 2 minutes **Notes**: * Added protocol fixture coverage for expanded lifecycle command values and `approved_not_executing`. * Added parser coverage for bounded lifecycle metadata fields and compatibility alias `pause`. * Added compact `command_center_hero_lifecycle_update` event typing coverage with bounded metadata. * Added blocked-payload rejection coverage for lifecycle parser boundaries. **Files Changed**: * `packages/protocol/tests/orchestrationCommandCenter.test.ts` - added lifecycle vocabulary, parser, compact event, and blocked-payload tests. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T007 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T007 complete and advanced progress. **Verification**: * Command/check: `npm test -- packages/protocol/tests/orchestrationCommandCenter.test.ts` * Result: PASS - focused command-center protocol tests passed. * Evidence: 1 test file passed; 13 tests passed. * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T007 changed protocol tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: lifecycle parser and event fixtures now cover the new protocol fields and alias behavior. * Trust boundary enforcement: lifecycle tests now assert blocked payload rejection at the parser boundary. *** ### Task T008 - Add protocol tests for lineage roster filters, degraded reason labels, duplicate events, and malformed IDs **Started**: 2026-06-26 14:10 IDT **Completed**: 2026-06-26 14:12 IDT **Duration**: 2 minutes **Notes**: * Added lineage protocol fixture coverage for roster filters, rows, snapshots, bounded limits, counts, and degraded reason display labels. * Added rejection coverage for malformed roster IDs, unknown degraded reasons, and oversized snapshots. * Preserved existing graph and WebSocket privacy assertions. **Files Changed**: * `packages/protocol/tests/lineage.test.ts` - added roster filter, row, snapshot, degraded label, malformed ID, and bounded limit tests. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T008 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T008 complete and advanced progress. **Verification**: * Command/check: `npm test -- packages/protocol/tests/lineage.test.ts` * Result: PASS - focused lineage protocol tests passed. * Evidence: 1 test file passed; 6 tests passed. * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript contract checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T008 changed protocol tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: lineage roster parser fixtures now cover filters, bounded rows, snapshots, counts, degraded labels, and malformed payload rejection. *** ### Task T009 - Create hero lifecycle manager with schema-validated input, explicit error mapping, idempotency protection, state transition rules, and unavailable explanations **Started**: 2026-06-26 13:58 IDT **Completed**: 2026-06-26 14:12 IDT **Duration**: 14 minutes **Notes**: * Added `HeroLifecycleManager` with local-first audit state only; it never spawns, stops, or controls a process. * Manager input is converted to `CommandCenterHeroLifecycleCommand` and parsed through the shared protocol parser before storage. * Idempotency keys return duplicate responses, stale expected revisions return compact conflicts, and final audit states reject additional transitions. * Unsupported or unsafe lifecycle intents resolve to unavailable or approved-not-executing states with bounded explanations. **Files Changed**: * `apps/server/src/managers/heroLifecycleManager.ts` - added lifecycle manager, validation, idempotency, state rules, redaction, and unavailable explanations. * `apps/server/tests/heroLifecycleManager.test.ts` - covered manager behavior. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T009 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T009 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/heroLifecycleManager.test.ts` * Result: PASS - focused lifecycle manager tests passed. * Evidence: 1 test file passed; 4 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T009 changed server runtime and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Duplicate action prevention: lifecycle idempotency keys dedupe repeated commands. * State freshness on re-entry: stale expected revisions return compact conflicts. * Trust boundary enforcement: all stored lifecycle records pass shared protocol parsing. * Error information boundaries: lifecycle summaries and labels are redacted before storage. *** ### Task T010 - Wire hero lifecycle manager into command-center state, snapshots, counts, cleanup, and WebSocket update events **Started**: 2026-06-26 14:12 IDT **Completed**: 2026-06-26 14:15 IDT **Duration**: 3 minutes **Notes**: * Added command-center manager delegation from `submitHeroLifecycleCommand` to `HeroLifecycleManager`. * Stored validated lifecycle records in the existing `heroCommands` map so `listHeroLifecycle`, counts, and `heroLifecycleUpdateEvent` stay aligned. * Added focused manager coverage for lifecycle snapshots, counts, compact event metadata, redaction, and duplicate idempotency behavior. **Files Changed**: * `apps/server/src/managers/orchestrationCommandCenter.ts` - injected lifecycle manager dependency and added `submitHeroLifecycleCommand`. * `apps/server/tests/commandCenterManager.test.ts` - added command-center lifecycle snapshot/count/event regression. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T010 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T010 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/commandCenterManager.test.ts apps/server/tests/heroLifecycleManager.test.ts` * Result: PASS - focused lifecycle manager and command-center manager tests passed. * Evidence: 2 test files passed; 11 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T010 changed server runtime and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: lifecycle manager output now feeds existing command-center snapshots, counts, and compact WebSocket event entries. * Duplicate action prevention: command-center integration preserves lifecycle idempotency dedupe and clears no extra state. *** ### Task T011 - Extend mission graph manager to derive filtered operator roster rows with bounded pagination, active/completed duration fields, and degradation explanations **Started**: 2026-06-26 14:15 IDT **Completed**: 2026-06-26 14:18 IDT **Duration**: 3 minutes **Notes**: * Stored safe `subagentType` and `summary` metadata on mission graph nodes. * Added `roster()` derivation with parent hero, child mission, subagent id/type, description, state, duration, result, degraded reason, filtered counts, bounded limit, cursor, and deterministic updated-desc ordering. * Excluded synthetic parent-only graph nodes from operator roster rows while preserving degraded child rows. **Files Changed**: * `packages/protocol/src/lineage.ts` - added safe graph node metadata fields used by roster derivation. * `apps/server/src/managers/missionGraph.ts` - added metadata retention and filtered roster snapshot derivation. * `apps/server/tests/missionGraph.test.ts` - added roster ordering, filters, pagination, duration, duplicate, and degraded-row tests. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T011 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T011 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/missionGraph.test.ts packages/protocol/tests/lineage.test.ts` * Result: PASS - focused mission graph and lineage tests passed. * Evidence: 2 test files passed; 8 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T011 changed protocol/server runtime and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Failure path completeness: malformed and duplicate lineage events remain visible as degraded roster rows instead of disappearing. * Contract alignment: server roster rows now derive from shared protocol fields and parser-tested snapshot contracts. *** ### Task T012 - Add command-center lifecycle command and lineage roster route validation with schema-validated input and explicit error mapping **Started**: 2026-06-26 14:18 IDT **Completed**: 2026-06-26 14:21 IDT **Duration**: 3 minutes **Notes**: * Added lifecycle command body validation with blocked-payload rejection, hero id validation, lifecycle kind parsing, requester audit parsing, optional target parsing, revision/idempotency parsing, and bounded metadata parsing. * Added lineage roster query validation for parent hero, state, subagent type, cursor, and bounded limit. * Added focused validation tests for accepted and rejected lifecycle and lineage inputs. **Files Changed**: * `apps/server/src/lib/commandCenterValidation.ts` - added lifecycle command body and lineage roster query parsers. * `apps/server/tests/commandCenterValidation.test.ts` - added focused validation tests. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T012 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T012 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/commandCenterValidation.test.ts` * Result: PASS - focused command-center validation tests passed. * Evidence: 1 test file passed; 3 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T012 changed server validation and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Trust boundary enforcement: route-level lifecycle and lineage inputs now fail closed before manager execution. * Error information boundaries: validation failures return compact `invalid_request` details without raw payload echoing. *** ### Task T013 - Add hero lifecycle command routes and lineage roster snapshot routes with duplicate-trigger prevention while in-flight **Started**: 2026-06-26 14:21 IDT **Completed**: 2026-06-26 14:24 IDT **Duration**: 3 minutes **Notes**: * Added `POST /command-center/heroes/commands` for validated lifecycle command submission through the command-center manager. * Added `GET /command-center/lineage-roster` for filtered lineage roster snapshots, available at root and `/api` route mounts. * Wired `missionGraph` into the command-center router dependencies. * Added route coverage for lifecycle command creation, duplicate idempotency, WebSocket lifecycle updates, and lineage roster snapshot responses. **Files Changed**: * `apps/server/src/routes/commandCenter.ts` - added lifecycle command and lineage roster routes with validation and in-flight mutation guard. * `apps/server/src/server.ts` - passed mission graph into the command-center router. * `apps/server/tests/commandCenterRoutes.test.ts` - added lifecycle and lineage route coverage. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T013 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T013 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/commandCenterValidation.test.ts apps/server/tests/commandCenterManager.test.ts` * Result: PASS - focused command-center route, validation, and manager tests passed. * Evidence: 3 test files passed; 19 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T013 changed server routes and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Duplicate action prevention: lifecycle route uses the existing command-center in-flight mutation guard plus idempotency keys. * Failure path completeness: lineage query and lifecycle body validation return compact 400s; manager conflicts return compact 409s. * Contract alignment: route responses use command-center lifecycle mutation responses and protocol lineage roster snapshots. *** ### Task T014 - Register lifecycle executor posture for subagent, mission, handoff, model, permission, and isolation families **Started**: 2026-06-26 14:24 IDT **Completed**: 2026-06-26 14:26 IDT **Duration**: 2 minutes **Notes**: * Added non-executing registry entries for message, dismiss, model change, permission mode change, and isolation mode change. * Kept real execution unavailable: model and permission changes are approved-not-executing; isolation is policy-blocked unavailable. * Updated executor kind/family compatibility so new lifecycle kinds do not fall through to provider diagnostics. **Files Changed**: * `apps/server/src/managers/executorRegistry.ts` - added lifecycle registry entries and compatibility checks. * `apps/server/tests/executorRegistry.test.ts` - added fallback posture assertions for model and isolation lifecycle kinds. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T014 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T014 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/executorRegistry.test.ts packages/protocol/tests/guardedActions.test.ts` * Result: PASS - focused executor registry and guarded-action tests passed. * Evidence: 2 test files passed; 9 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * Command/check: `npm --workspace packages/protocol run typecheck` * Result: PASS - protocol TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T014 changed server runtime and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Contract alignment: executor registry entries, compatibility checks, guarded-action kinds, and command-center executor kinds now agree for lifecycle families. * Failure path completeness: lifecycle families return explicit non-executing fallback posture instead of generic missing capability results. *** ### Task T015 - Promote safe hook lifecycle and subagent observations into command-center lifecycle and roster state **Started**: 2026-06-26 14:26 IDT **Completed**: 2026-06-26 14:33 IDT **Duration**: 7 minutes **Notes**: * Promoted session spawn, session stop, subagent spawn, and subagent completion hook observations into command-center hero lifecycle commands. * Routed all promoted lifecycle records through the hero lifecycle manager so schema validation, redaction, idempotency, and unavailable/approved-not-executing posture stay centralized. * Added route-local safe metadata extraction for model, permission, isolation, worktree, process, terminal, listener, and event-count fields without blocking hook ingest when promotion fails. * Mapped lifecycle promotion failures to compact warning toasts while preserving best-effort hook acceptance. * Extended event-ingest tests to assert lifecycle websocket updates, command-center lifecycle state, and derived lineage roster rows from the same subagent observations. **Files Changed**: * `apps/server/src/routes/event.ts` - added lifecycle promotion helpers and wired hook observations into command-center lifecycle state. * `apps/server/tests/eventIngest.test.ts` - added command-center manager harness wiring and focused lifecycle/lineage assertions. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T015 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T015 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/eventIngest.test.ts` * Result: PASS - focused event ingest coverage passed. * Evidence: 1 test file passed; 13 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T015 changed server ingest and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Trust boundary enforcement: hook lifecycle data is normalized to compact fields and validated by the command-center lifecycle schema. * Failure path completeness: rejected lifecycle promotion produces a bounded warning event instead of silent state loss or hook ingest failure. * Contract alignment: command-center lifecycle snapshots and lineage roster state are now fed by the same safe hook observations. *** ### Task T016 - Extend hook lifecycle payload shaping with compact lifecycle and subagent associations **Started**: 2026-06-26 14:33 IDT **Completed**: 2026-06-26 14:37 IDT **Duration**: 4 minutes **Notes**: * Added compact lifecycle labels to hero spawn payloads: worktree basename label, safe terminal label, listener status label, process label, isolation mode, and event count. * Added compact Codex subagent start metadata: parent agent ID, bounded description, model, permission, isolation, worktree, terminal, listener, process, and event count fields. * Kept prompt, transcript, terminal-output, and raw path fields out of the new metadata while preserving existing hook compatibility fields. * Extended hook runtime assertions to prove the new metadata is emitted in spooled payloads under server-unavailable conditions. **Files Changed**: * `apps/hooks/src/factionos-hero-spawn.js` - added compact lifecycle metadata derivation for session start hooks. * `apps/hooks/src/factionos-subagent-start.js` - added compact subagent lifecycle metadata and bounded description fields. * `apps/hooks/tests/hookRuntime.test.js` - asserted lifecycle metadata on Codex-shaped hook payloads. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T016 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T016 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/hooks/tests/hookRuntime.test.js` * Result: PASS - hook runtime coverage passed. * Evidence: 1 test file passed; 9 tests passed. * Command/check: `npm test -- apps/hooks/tests/hookPayloads.test.js` * Result: PASS - hook payload source-shape/privacy coverage passed. * Evidence: 1 test file passed; 9 tests passed. * UI product-surface check: N/A - T016 changed hook payloads and tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Privacy boundary: new hook metadata uses safe labels and bounded descriptions instead of raw prompt, transcript, terminal output, or full path fields. * Contract alignment: hook payloads now include the metadata fields consumed by event-route lifecycle promotion. * Local-first resilience: metadata is present even when hooks spool locally because the server is unavailable. *** ### Task T017 - Add web API helpers for lifecycle mutations and lineage roster snapshots **Started**: 2026-06-26 14:37 IDT **Completed**: 2026-06-26 14:41 IDT **Duration**: 4 minutes **Notes**: * Added `fetchCommandCenterLineageRoster` with protocol-backed snapshot validation and query serialization for parent hero, state, subagent type, limit, and cursor filters. * Added `submitCommandCenterHeroLifecycleCommand` for `POST /command-center/heroes/commands` with route ID validation, typed body shaping, refresh support, and duplicate in-flight guarding. * Added lifecycle command and lineage roster API tests covering URL/query shape, request body shape, typed response parsing, and duplicate-trigger prevention. **Files Changed**: * `apps/web/src/lib/orchestrationApi.ts` - added lineage roster fetch helper and lifecycle command mutation helper. * `apps/web/tests/orchestrationApi.test.ts` - added focused API helper coverage. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T017 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T017 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/web/tests/orchestrationApi.test.ts` * Result: PASS - focused web API helper tests passed. * Evidence: 1 test file passed; 23 tests passed. * Command/check: `npm --workspace apps/web run typecheck` * Result: FAIL - pending exhaustive UI enum handling in `apps/web/src/lib/orchestrationUi.ts` for new lifecycle families/kinds. * Evidence: TypeScript errors at `orchestrationUi.ts:378` and `orchestrationUi.ts:427`; scheduled for T018. * UI product-surface check: N/A - T017 added API helpers only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Duplicate action prevention: lifecycle command submissions use the shared command-center in-flight mutation guard. * Contract alignment: roster snapshots and lifecycle mutation responses are parsed through protocol validators before reaching UI state. * Failure path completeness: invalid hero references fail locally with a compact `invalid_input` response. *** ### Task T018 - Add command-center UI helpers for lifecycle and lineage state **Started**: 2026-06-26 14:41 IDT **Completed**: 2026-06-26 14:46 IDT **Duration**: 5 minutes **Notes**: * Added typed helper views for hero lifecycle commands and lineage roster rows, including status copy, kind labels, metadata chips, safe text redaction, and timestamps. * Added lifecycle action availability helper for message, dismiss, model, permission, and isolation intents with duplicate/offline disabling. * Added lineage roster state/filter labels for the upcoming Hero/Lineage workbench. * Added a dedicated Hero/Lineage command-center tab bucket and removed hero lifecycle records from executor tab counts. * Updated orchestration guarded-action family/kind labels to cover model, permission, isolation, and new hero lifecycle actions. **Files Changed**: * `apps/web/src/lib/commandCenterUi.ts` - added Hero/Lineage helpers and tab counts. * `apps/web/src/lib/orchestrationUi.ts` - added exhaustive labels for new guarded action families and kinds. * `apps/web/tests/commandCenterUi.test.ts` - added helper coverage and updated tab count expectations. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T018 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T018 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/web/tests/commandCenterUi.test.ts` * Result: PASS - focused command-center UI helper tests passed. * Evidence: 1 test file passed; 12 tests passed. * Command/check: `npm --workspace apps/web run typecheck` * Result: PASS - web TypeScript checks passed. * Evidence: `tsc -b --noEmit` exited 0. * UI product-surface check: helper-only work; visible workbench lands in T019/T020. * UI craft check: helper labels use concise product-facing copy and safe redaction. **BQC Fixes**: * Contract alignment: UI helper switches now exhaustively cover expanded guarded-action protocol families and kinds. * Privacy boundary: lifecycle summaries, labels, and lineage descriptions pass through command-center redaction helpers. * Action-state clarity: lifecycle actions now expose consistent disabled reasons for offline and duplicate in-flight states. *** ### Task T019 - Create Hero/Lineage workbench **Started**: 2026-06-26 14:46 IDT **Completed**: 2026-06-26 14:49 IDT **Duration**: 3 minutes **Notes**: * Added a standalone `HeroLineageWorkbench` component for hero lifecycle commands and lineage roster rows. * Included controlled lineage filters, lifecycle action buttons, metric tiles, loading, empty, error, offline, filtered, active, completed, degraded, and unavailable states. * Added focusable command and mission controls with accessible labels and status pills. * Exposed `heroLifecycleActionKey` so T020 wiring can use the same in-flight mutation key shape as the component. **Files Changed**: * `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` - added Hero/Lineage workbench component. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T019 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T019 complete and advanced progress. **Verification**: * Command/check: `npm --workspace apps/web run typecheck` * Result: PASS - web TypeScript checks passed. * Evidence: `tsc -b --noEmit` exited 0. * UI product-surface check: component renders the actual Hero/Lineage operational surface instead of a placeholder or landing panel. * UI craft check: controls use stable button/select/input sizes, status pills, concise copy, and visible focus states. **BQC Fixes**: * State coverage: the workbench has explicit handling for loading, empty, error, offline, filtered, active, completed, degraded, and unavailable lifecycle states. * Accessibility: command, filter, and mission controls have accessible names and keyboard focus styling. * Duplicate action readiness: lifecycle action buttons read the shared in-flight key map and disable duplicate submissions. *** ### Task T020 - Wire Hero/Lineage workbench into Orchestration panes and shell handlers **Started**: 2026-06-26 14:49 IDT **Completed**: 2026-06-26 14:53 IDT **Duration**: 4 minutes **Notes**: * Added a dedicated Hero/Lineage command-center tab and pane case. * Threaded lineage roster snapshot, filters, loading/error state, lifecycle actions, and mission-opening handlers through `OrchestrationTabs` and `CommandCenterPanes`. * Added shell-owned lineage roster fetch state and included roster refresh in command-center refresh flows. * Wired lifecycle action buttons to `submitCommandCenterHeroLifecycleCommand` with shared in-flight mutation keys and local toast feedback. * Updated orchestration panel API mocks for lineage roster and lifecycle command helpers. **Files Changed**: * `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - added Hero/Lineage pane case and workbench props. * `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - threaded lineage and lifecycle handler props. * `apps/web/src/components/orchestration/OrchestrationShell.tsx` - added lineage roster state, hydration, filters, and lifecycle mutation handler. * `apps/web/tests/OrchestrationPanel.test.tsx` - updated API mocks/default snapshots. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T020 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T020 complete and advanced progress. **Verification**: * Command/check: `npm --workspace apps/web run typecheck` * Result: PASS - web TypeScript checks passed. * Evidence: `tsc -b --noEmit` exited 0. * Command/check: `npm test -- apps/web/tests/OrchestrationPanel.test.tsx` * Result: PASS - orchestration panel integration tests passed. * Evidence: 1 test file passed; 11 tests passed. * UI product-surface check: Hero/Lineage tab is now part of the command-center operational tabs. * UI craft check: workbench copy remains product-facing, with no shortcut/how-to explanatory text. **BQC Fixes**: * Contract alignment: shell now fetches and validates lineage roster snapshots through the web API helper before rendering. * Duplicate action prevention: lifecycle button submissions use the same mutation key visible to the component disabled state. * Failure path completeness: lineage roster fetch failures map through command-center UI error copy and render in the workbench. *** ### Task T021 - Add server route and WebSocket regression coverage **Started**: 2026-06-26 14:53 IDT **Completed**: 2026-06-26 14:55 IDT **Duration**: 2 minutes **Notes**: * Added a full command-center route regression test that posts hook lifecycle events through `/event`. * Asserted command-center hero lifecycle WebSocket updates for hero spawn and subagent fork observations. * Asserted lineage roster filtering for active reviewer rows and degraded malformed rows. * Asserted malformed subagent IDs and duplicate subagent events emit explicit degraded/duplicate lineage websocket updates. **Files Changed**: * `apps/server/tests/commandCenterRoutes.test.ts` - added lifecycle/lineage route and websocket regression coverage. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T021 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T021 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/commandCenterRoutes.test.ts` * Result: PASS - command-center route and websocket tests passed. * Evidence: 1 test file passed; 10 tests passed. * Command/check: `npm --workspace apps/server run typecheck` * Result: PASS - server TypeScript checks passed. * Evidence: `tsc --noEmit` exited 0. * UI product-surface check: N/A - T021 changed server tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Regression coverage: server now locks lifecycle command websocket broadcasts, roster filter route behavior, malformed lineage degradation, and duplicate lineage event handling together. * Failure path completeness: malformed and duplicate lineage inputs are asserted as explicit degraded websocket states. *** ### Task T022 - Add web component, store, and panel tests **Started**: 2026-06-26 14:55 IDT **Completed**: 2026-06-26 14:59 IDT **Duration**: 4 minutes **Notes**: * Added focused `HeroLineageWorkbench` component coverage for lifecycle action controls, unavailable commands, roster filters, degraded lineage rows, offline copy, and duplicate in-flight disabled state. * Extended command-center store mutation-key coverage for hero lifecycle duplicate prevention. * Extended orchestration panel integration coverage so the Hero/Lineage tab reaches the empty lifecycle fallback and fetches lineage roster state. **Files Changed**: * `apps/web/tests/HeroLineageWorkbench.test.tsx` - added focused Hero/Lineage workbench component tests. * `apps/web/tests/commandCenterStore.test.ts` - added hero lifecycle duplicate in-flight mutation-key assertions. * `apps/web/tests/OrchestrationPanel.test.tsx` - asserted Hero/Lineage panel integration and roster fetch behavior. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T022 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T022 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/web/tests/HeroLineageWorkbench.test.tsx apps/web/tests/commandCenterStore.test.ts apps/web/tests/OrchestrationPanel.test.tsx` * Result: PASS - focused web component, store, and panel tests passed. * Evidence: 3 test files passed; 19 tests passed. * Command/check: `npm --workspace apps/web run typecheck` * Result: PASS - web TypeScript checks passed. * Evidence: `tsc -b --noEmit` exited 0. * UI product-surface check: component tests cover the shipped Hero/Lineage operational surface, not placeholder copy. * UI craft check: assertions cover accessible names for action controls, filters, and mission-opening buttons. **BQC Fixes**: * Duplicate action prevention: web tests now lock lifecycle in-flight key behavior at component and store boundaries. * Failure path completeness: offline and unavailable lifecycle action states are covered with disabled controls. * Degraded-state clarity: roster filtering and degraded reason display are asserted in component tests. *** ### Task T023 - Add hook runtime tests for bounded lifecycle metadata **Started**: 2026-06-26 14:59 IDT **Completed**: 2026-06-26 15:02 IDT **Duration**: 3 minutes **Notes**: * Added hook runtime coverage for bounded terminal, listener, process, worktree, isolation, and event-count lifecycle labels. * Added subagent runtime coverage for bounded child and parent agent associations, model, permission, isolation, listener PID, process label, description, and degraded oversized ID metadata. * Kept assertions against spooled payloads so privacy-sensitive raw paths and token-like description values stay redacted during retry persistence. **Files Changed**: * `apps/hooks/tests/hookRuntime.test.js` - added lifecycle label and subagent association boundary coverage. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T023 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T023 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/hooks/tests/hookRuntime.test.js` * Result: PASS - hook runtime harness passed. * Evidence: 1 test file passed; 10 tests passed. * Command/check: `npm test -- apps/hooks/tests/hookPayloads.test.js` * Result: PASS - hook payload contract checks passed. * Evidence: 1 test file passed; 9 tests passed. * UI product-surface check: N/A - T023 changed hook runtime tests only. * UI craft check: N/A - no user-facing UI changed. **BQC Fixes**: * Privacy boundary: runtime assertions now verify raw private paths and token-like description values do not persist in spool entries. * Metadata bounds: tests lock terminal, listener, process, worktree, description, subagent type, and parent/child agent ID limits. * Degraded-state clarity: oversized subagent IDs are asserted as explicit degraded metadata. *** ### Task T024 - Update lifecycle and lineage documentation **Started**: 2026-06-26 15:02 IDT **Completed**: 2026-06-26 15:05 IDT **Duration**: 3 minutes **Notes**: * Documented `/command-center/heroes/commands` and `/command-center/lineage-roster` in the REST endpoint table. * Updated event ingest mapping for hook-promoted hero lifecycle spawn/stop and subagent fork/stop observations. * Added hook lifecycle metadata privacy boundaries for model, permission, isolation, worktree, terminal, listener, process, event count, subagent, parent, type, and description labels. * Updated WebSocket and phase closeout text for the Hero/Lineage web tab, lifecycle frames, roster filters, unavailable/offline/degraded/duplicate states, and non-execution boundaries. **Files Changed**: * `docs/api/README_api.md` - documented shipped lifecycle and lineage REST, hook, WebSocket, web, and non-execution boundaries. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T024 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T024 complete and advanced progress. **Verification**: * Command/check: `npm test -- apps/server/tests/commandCenterRoutes.test.ts apps/web/tests/HeroLineageWorkbench.test.tsx apps/hooks/tests/hookRuntime.test.js` * Result: PASS - focused documented server, web, and hook regressions passed. * Evidence: 3 test files passed; 22 tests passed. * Documentation consistency check: `rg -n "/command-center/heroes/commands|/command-center/lineage-roster|Hero/Lineage|command_center_hero_lifecycle_update|Hook lifecycle metadata" docs/api/README_api.md` * Result: PASS - updated route, web, WebSocket, and hook boundary sections are present. * UI product-surface check: documentation describes the shipped Hero/Lineage cockpit surface and avoids placeholder or future-only claims. * UI craft check: documented UI states match shipped offline, unavailable, degraded, and duplicate-action behavior. **BQC Fixes**: * Non-overclaim posture: docs state lifecycle intents are command-center state only unless future executor readiness exists. * Privacy boundary: docs now explicitly block raw prompts, transcripts, terminal output, command bodies, paths, provider payloads, tokens, and secrets for lifecycle metadata. * Route clarity: API docs separate hero lifecycle command records from raw hero terminal/session state and document roster filters. *** ### Task T025 - Run final checks **Started**: 2026-06-26 15:05 IDT **Completed**: 2026-06-26 15:07 IDT **Duration**: 2 minutes **Notes**: * Ran root formatting, lint, typecheck, full Vitest, whitespace, and changed-file ASCII/LF validation. * `npm run format:check` initially reported formatting drift in session-touched files; `npm run format` fixed 14 files, and the rerun passed. * No remaining validation blockers. **Files Changed**: * Session-touched source and test files formatted by `npm run format`. * `.spec_system/specs/phase19-session09-heroes-and-lineage/implementation-notes.md` - recorded T025 evidence. * `.spec_system/specs/phase19-session09-heroes-and-lineage/tasks.md` - marked T025 complete and checked completion checklist. **Verification**: * Command/check: `npm run format:check` * Result: PASS after formatting. * Evidence: `Checked 694 files ... No fixes applied.` * Command/check: `npm run lint` * Result: PASS. * Evidence: `Checked 696 files ... No fixes applied.` * Command/check: `npm run typecheck` * Result: PASS. * Evidence: workspace typechecks passed for adapters, server, warroom, web, protocol, and public website. * Command/check: `npm test` * Result: PASS. * Evidence: 235 test files passed, 1 skipped; 2830 tests passed, 1 skipped. * Command/check: `git diff --check` * Result: PASS. * Evidence: exited 0 with no whitespace errors. * Command/check: changed-file ASCII/LF validation script * Result: PASS. * Evidence: ASCII/LF validation passed for 42 changed files. * UI product-surface check: covered by full web test suite, including `OrchestrationPanel.test.tsx` and `HeroLineageWorkbench.test.tsx`. * UI craft check: full web suite and focused component tests passed after formatting. **BQC Fixes**: * Final verification: all root checks and changed-file encoding checks pass. * Formatting drift: resolved by repo formatter and verified with `format:check`. * Residual risk: no remaining known blockers before `creview`. --- # 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/implementation-notes.md?ask=&goal= ``` `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.