> 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/spec.md). # Session Specification **Session ID**: `phase19-session09-heroes-and-lineage` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed TypeScript/JavaScript *** ## 1. Session Overview This session adds the missing hero lifecycle control surface and turns the existing subagent mission graph into an operator roster. Sessions 01 through 08 already provide the command-center protocol scaffold, server backbone, web store, attention and permission state, executor registry, diagnostics, and bounded File/Git workbench. The next executable gap is lifecycle intent and lineage visibility. The work expands hero lifecycle contracts for spawn, fork, handoff, resume, message, stop, dismiss, model change, permission mode change, and isolation mode change intents. Server behavior remains local-first and bounded: commands are validated, audited, idempotent, and explicit about unavailable or approved-not-executing outcomes when no safe local executor exists. The lineage work deepens the current mission graph into active and completed subagent rows with parent hero, child mission, subagent type, description, state, timing, and degraded reason filters. Raw prompts, transcripts, command bodies, terminal output, file contents, broad paths, and provider payloads stay out of broad REST, WebSocket, hook, and web surfaces. *** ## 2. Objectives 1. Add protocol-first hero lifecycle intent contracts and compact WebSocket entries for the command-center hero surface. 2. Add server-owned lifecycle command handling with idempotency, state transition validation, permission/audit fields, and unavailable explanations. 3. Add lineage operator roster rows and filters derived from existing mission graph, hero, mission, and hook metadata. 4. Add a web Hero/Lineage workbench with lifecycle controls, roster filters, loading/empty/error/offline states, and product-facing copy only. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session01-protocol-and-events` - provides command-center shared contracts. * [x] `phase19-session02-server-backbone` - provides server command-center manager, routes, and WebSocket hydration. * [x] `phase19-session03-web-shell-and-store` - provides command-center web store, API helpers, and panels. * [x] `phase19-session05-attention-and-permissions` - provides audited decision state and duplicate-decision guards. * [x] `phase19-session06-executor-registry` - provides registry-gated execution posture and bounded run history. * [x] `phase19-session07-provider-diagnostics` - provides provider readiness and setup diagnostics used by lifecycle availability. * [x] `phase19-session08-file-and-git` - provides bounded executor-ready precedent and in-flight mutation patterns. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 workspace commands from `.spec_system/CONVENTIONS.md`. * Existing hook/listener and mission lineage implementation in `apps/hooks`, `apps/server/src/routes/event.ts`, and `apps/server/src/managers/missionGraph.ts`. * Existing command-center route, store, WebSocket, and panel patterns. ### Environment Requirements * No hosted credentials, provider API keys, Worker credentials, container runtime, or analytics configuration are required. * Unsupported lifecycle operations must return explicit unavailable or approved-not-executing state instead of invoking external tools. *** ## 4. Scope ### In Scope (MVP) * Operators can record lifecycle intents for spawn, fork, handoff, resume, message, stop, dismiss, model change, permission mode change, and isolation mode change with duplicate-trigger prevention while in-flight. * Operators can see provider, model, permission mode, worktree, process ID label, terminal/listener association, lifecycle state, unavailable reason, and bounded event tracking where current hooks or server state provide it. * Operators can inspect active and completed subagent roster rows with parent hero, child mission, subagent type, bounded description, state, timing, and degraded reason. * Operators can filter the lineage roster by parent hero, state, and subagent type with deterministic ordering and bounded result counts. * Tests cover command validation, state transitions, malformed lineage events, duplicate lineage events, unavailable lifecycle commands, and degradation explanations. ### Out Of Scope (Deferred) * Raw prompt, transcript, provider payload, command body, terminal output, or file-content rendering - Reason: these belong only in separately scoped detail surfaces with explicit redaction. * Container-isolated spawn - Reason: the session stub defers container isolated spawn until runtime capability exists. * Terminal command execution - Reason: Session 12 owns terminal and container capability. * Hosted queues, inbound chat commands, Worker execution, remote access, and collaboration transfer - Reason: later sessions own these route families and external-transfer boundaries. * Autonomous process control beyond explicit local audit state - Reason: lifecycle controls must not imply unsafe local process execution without a scoped executor threat model. *** ## 5. Technical Approach ### Architecture Start in `packages/protocol` because command-center lifecycle and lineage contracts are shared across server, hooks, and web. Expand `orchestrationCommandCenter.ts` for lifecycle intent values and metadata, and extend `lineage.ts` with compact roster rows, filters, snapshots, and parser helpers. Preserve existing hero lifecycle values as compatibility aliases when practical so previous scaffold fixtures do not hard-fail. Add a server-owned `HeroLifecycleManager` that validates lifecycle requests, normalizes hero associations from the roster and hook metadata, applies state-transition rules, records audit details, and maps unsupported commands to bounded unavailable results. The existing `OrchestrationCommandCenterManager` should delegate hero command state to that manager and continue emitting `command_center_hero_lifecycle_update` frames. Derive the lineage operator roster from `MissionGraphManager` plus existing hero and mission state. Roster derivation should be deterministic, filterable, bounded, and privacy-safe. Web code should consume typed API helpers and Zustand hydration, then render a dedicated Hero/Lineage workbench inside the Orchestration command-center tabs. ### Design Patterns * Protocol-first shared vocabulary: prevents lifecycle and lineage drift across packages. * Manager-owned state and snapshots: keeps validation, idempotency, ordering, and broadcasts aligned. * Explicit unavailable states: prevents lifecycle UI from implying unsupported local execution. * Pure web normalization before store mutation: malformed frames cannot blank the cockpit. * Product-surface copy only: diagnostics and raw technical detail stay in tests, docs, and scoped local details. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/managers/heroLifecycleManager.ts` | Hero lifecycle command state, validation, idempotency, availability, and audit summaries | \~300 | | `apps/server/tests/heroLifecycleManager.test.ts` | Lifecycle validation, state transition, duplicate, unavailable, and redaction coverage | \~240 | | `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` | Dedicated hero lifecycle and lineage roster workbench | \~320 | | `apps/web/tests/HeroLineageWorkbench.test.tsx` | Web rendering, filters, controls, accessibility, and redaction coverage | \~260 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Expand hero lifecycle intent vocabulary, metadata fields, parser helpers, and compact event entries | \~180 | | `packages/protocol/src/lineage.ts` | Add lineage roster row, filter, snapshot, and degradation display contracts | \~150 | | `packages/protocol/src/guardedActions.ts` | Add lifecycle-adjacent proposal kinds for message, dismiss, model, permission, and isolation intents | \~80 | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Contract fixtures for lifecycle intent parsing and event entries | \~130 | | `packages/protocol/tests/lineage.test.ts` | Roster/filter/snapshot fixtures and degradation reason coverage | \~120 | | `packages/protocol/tests/guardedActions.test.ts` | Lifecycle-adjacent guarded action compatibility coverage | \~90 | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Delegate hero lifecycle records to the lifecycle manager and emit compact updates | \~150 | | `apps/server/src/managers/missionGraph.ts` | Derive filtered lineage operator roster rows from graph nodes and edges | \~160 | | `apps/server/src/managers/executorRegistry.ts` | Register lifecycle family posture and unavailable/approved-not-executing explanations | \~100 | | `apps/server/src/lib/commandCenterValidation.ts` | Add lifecycle command and lineage roster query validation | \~130 | | `apps/server/src/routes/commandCenter.ts` | Add lifecycle command routes and lineage roster snapshot routes with in-flight guards | \~180 | | `apps/server/src/routes/event.ts` | Promote safe hook lifecycle and subagent observations into lifecycle/roster state | \~110 | | `apps/server/src/server.ts` | Instantiate and inject lifecycle manager dependencies | \~35 | | `apps/hooks/src/factionos-hero-spawn.js` | Include bounded terminal/listener/process association metadata where available | \~45 | | `apps/hooks/src/factionos-subagent-start.js` | Include bounded parent/child lineage association metadata where available | \~35 | | `apps/hooks/tests/hookRuntime.test.js` | Validate bounded lifecycle and subagent association payloads | \~100 | | `apps/web/src/lib/orchestrationApi.ts` | Add typed lifecycle mutation and lineage roster API helpers with in-flight guards | \~150 | | `apps/web/src/lib/commandCenterUi.ts` | Add hero lifecycle copy, roster filters, tab counts, and redaction helpers | \~150 | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Wire the Hero/Lineage workbench into Orchestration panes | \~70 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire lifecycle and lineage handlers into the shell | \~90 | | `apps/web/src/store/useGameStore.ts` | Normalize lifecycle and roster updates without unsafe payloads | \~90 | | `apps/server/tests/commandCenterRoutes.test.ts` | Route and WebSocket lifecycle/lineage regression coverage | \~180 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Integrated Orchestration panel coverage for Hero/Lineage tab behavior | \~140 | | `apps/web/tests/commandCenterStore.test.ts` | Store reducer coverage for expanded lifecycle and roster frames | \~80 | | `docs/api/README_api.md` | Document lifecycle and lineage routes, states, and privacy boundaries | \~90 | | `docs/api/event-api-hook-contracts.md` | Document hook lifecycle and lineage event behavior | \~80 | | `apps/server/README_server.md` | Update server command-center ownership and no-execution boundary notes | \~60 | | `apps/web/README_web.md` | Update Hero/Lineage workbench UX and product-surface rules | \~70 | | `apps/hooks/README_hooks.md` | Update bounded lifecycle and subagent association payload notes | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Lifecycle commands validate supported intent kinds, hero references, expected revisions, idempotency keys, and bounded metadata. * [ ] Unsupported lifecycle commands return unavailable or approved-not-executing explanations without running unsafe executors. * [ ] Hero lifecycle rows show provider, model, permission mode, worktree label, terminal/listener/process association, state, and event history where safe metadata exists. * [ ] Lineage roster rows show parent hero, child mission, subagent type, bounded description, active/completed state, duration, result, and degraded reason. * [ ] Roster filters by parent hero, state, and subagent type are deterministic and bounded. ### Testing Requirements * [ ] Protocol tests cover lifecycle intent vocabulary, compatibility aliases, lifecycle metadata parsing, and lineage roster contracts. * [ ] Server tests cover lifecycle validation, state transitions, stale revisions, duplicate triggers, malformed lineage events, duplicate lineage events, route errors, and WebSocket updates. * [ ] Hook tests cover bounded lifecycle and subagent association payloads without prompts, transcripts, or broad paths. * [ ] Web tests cover loading, empty, error, offline, filtered, degraded, unavailable, active, completed, and duplicate-trigger states. ### Non-Functional Requirements * [ ] Broad REST, WebSocket, hook, and web payloads never expose raw prompts, command bodies, transcripts, terminal output, file contents, provider payloads, secrets, or broad absolute paths. * [ ] Lifecycle mutations use explicit validation, authorization-adjacent audit fields, idempotency, and deterministic error mapping. * [ ] UI controls have accessible names, focus behavior, keyboard support, and duplicate-trigger prevention while in flight. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused package checks plus root format, lint, typecheck, and tests pass or failures are recorded with exact residual risk *** ## 8. Implementation Notes ### Working Assumptions * `Package: null` is correct because the selected stub names `apps/server`, `apps/web`, and `apps/hooks`, while `.spec_system/CONVENTIONS.md` requires protocol-first shared contract changes for WebSocket, REST, and domain types. Planning can proceed because the cross-package scope is exactly the session boundary. * Lifecycle commands are command-center intents and audit state, not broad real process or container execution. The PRD requires permission, audit, redaction, unavailable states, and tests before execution claims, and the session stub explicitly defers container-isolated spawn. * The lineage roster should derive from current mission graph and hook metadata instead of raw transcripts or prompts. Existing contracts already emit `subagent_lineage_update` and `mission_graph_update` frames with compact IDs, states, summaries, and degraded reasons. ### Conflict Resolutions * Existing `CommandCenterHeroLifecycleCommandKind` values are narrower than the session stub. The chosen interpretation is to expand the protocol to the stub's lifecycle intents while preserving existing scaffold values as compatibility aliases where practical, because the PRD and session stub are the current scope and protocol-first work is an active convention. * Existing executor registry entries for subagent, mission, and handoff are unavailable or proposal-only. The chosen interpretation is to keep real execution unavailable unless a safe local capability already exists, because sessions 06 and 08 establish registry-gated execution and the current stub does not add terminal/container capability. ### Key Considerations * `EXAMPLES/` links in the stub are evidence only; shipped behavior must live in protocol, server, hooks, web, tests, and docs. * Lifecycle availability should use provider diagnostics and executor registry posture without implying cloud provider calls or hosted identity. * The web surface should use compact labels and avoid visible debug copy. ### Potential Challenges * Lifecycle command semantics can become too broad: keep each intent as a bounded state mutation with explicit unavailable reasons unless a scoped executor is proven. * Lineage rows may have missing parent or child IDs: preserve degraded rows with clear reason labels instead of dropping them. * Hook metadata varies by provider: normalize only allowlisted fields and keep absent values visible as unavailable or unknown states. ### Relevant Considerations * \[P07] **Redaction is boundary-specific**: Apply redaction to lifecycle, lineage, hook, WebSocket, and UI payloads separately. * \[P03-packages/protocol] **Protocol leads cross-package work**: Update shared lifecycle and lineage contracts before server, hook, and web consumers. * \[P03] **Stable docs are the current contract**: Update API, server, web, and hooks docs alongside behavior. * \[P03] **Do not log raw CLI args or local paths**: Lifecycle association logging must use bounded labels and redacted paths only. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Lifecycle controls could imply unsupported execution unless unavailable and approved-not-executing states are explicit. * Lineage rows could disappear or mislead when parent, child, or subagent IDs are missing or malformed. * UI actions could duplicate lifecycle mutations without in-flight and idempotency guards. *** ## 9. Testing Strategy ### Unit Tests * Protocol parser and enum tests for lifecycle intent values, aliases, metadata fields, lineage roster rows, filters, and degraded reasons. * Server manager tests for lifecycle validation, transition rules, duplicate idempotency keys, stale revisions, unavailable states, and redaction. * Web helper tests for lifecycle status copy, roster filter labels, and blocked payload handling. ### Integration Tests * Server route tests for lifecycle command creation/decision, lineage roster snapshots, malformed filters, duplicate triggers, and compact WebSocket updates. * Hook runtime tests for bounded session start and subagent association metadata. * Orchestration panel tests for Hero/Lineage tab rendering, filters, controls, and offline/error behavior. ### Runtime Verification * Start local server and web app, hydrate command-center snapshots, submit a lifecycle command, and verify the web panel updates without raw payloads. * Post bounded subagent spawn and complete events to `/event`, verify lineage roster rows and degraded explanations, then filter by hero, state, and type. ### Edge Cases * Duplicate lifecycle command idempotency key. * Stale lifecycle expected revision. * Missing hero or child mission reference. * Malformed, missing, oversized, or duplicate subagent IDs. * Unsupported model, permission mode, isolation mode, or lifecycle intent. * Disconnected browser or unavailable local server. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase19-session01-protocol-and-events`, `phase19-session02-server-backbone`, `phase19-session03-web-shell-and-store`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session07-provider-diagnostics`, `phase19-session08-file-and-git` * Depended by: `phase19-session10-mission-artifacts`, `phase19-session11-templates-and-planning-context`, `phase19-session13-collaboration-and-handoff`, `phase19-session16-ergonomics-and-documentation` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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/spec.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.