> 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_summary.md).

# Implementation Summary

**Session ID**: `phase19-session09-heroes-and-lineage` **Package**: null **Completed**: 2026-06-26 **Duration**: 2 hours

***

## Overview

Session 09 shipped the Hero/Lineage command-center surface across protocol, server, hooks, web, tests, and docs. It adds expanded hero lifecycle intent contracts, server-owned lifecycle audit handling, bounded hook metadata promotion, lineage roster derivation, and a product-facing Hero/Lineage workbench in the web Orchestration surface.

The shipped behavior keeps lifecycle commands local-first and audit-oriented. Unsupported lifecycle operations return unavailable or approved-not-executing states instead of running unsafe executors, and broad REST, WebSocket, hook, and UI payloads avoid raw prompts, transcripts, command bodies, terminal output, provider payloads, file contents, secrets, and broad absolute paths.

***

## Deliverables

### Files Created

| File                                                             | Purpose                                                                              | Lines |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----- |
| `apps/server/src/managers/heroLifecycleManager.ts`               | Hero lifecycle validation, idempotency, audit state, and unavailable handling        | 291   |
| `apps/server/tests/heroLifecycleManager.test.ts`                 | Lifecycle transition, duplicate, stale revision, unavailable, and redaction coverage | 150   |
| `apps/server/tests/commandCenterValidation.test.ts`              | Lifecycle command and lineage roster validation coverage                             | 77    |
| `apps/server/tests/missionGraph.test.ts`                         | Lineage roster, duplicate event, degraded filter, and redaction coverage             | 124   |
| `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` | Dedicated hero lifecycle and lineage roster workbench                                | 336   |
| `apps/web/tests/HeroLineageWorkbench.test.tsx`                   | Web lifecycle controls, roster filters, degraded rows, and accessibility coverage    | 150   |

### Files Modified

| File                                                           | Changes                                                                                                |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `packages/protocol/src/orchestrationCommandCenter.ts`          | Expanded lifecycle intents, states, bounded metadata, compact event entries, and parser helpers        |
| `packages/protocol/src/lineage.ts`                             | Added lineage roster rows, filters, snapshots, degraded reason labels, and bounded parser helpers      |
| `packages/protocol/src/guardedActions.ts`                      | Added lifecycle-adjacent guarded action families and kinds                                             |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`   | Added lifecycle vocabulary, parser, compact event, and blocked-payload coverage                        |
| `packages/protocol/tests/lineage.test.ts`                      | Added roster filters, degraded reason, duplicate event, and malformed ID coverage                      |
| `packages/protocol/tests/guardedActions.test.ts`               | Added lifecycle-adjacent guarded action compatibility coverage                                         |
| `apps/server/src/managers/orchestrationCommandCenter.ts`       | Delegated hero lifecycle records and compact update events to the lifecycle manager                    |
| `apps/server/src/managers/missionGraph.ts`                     | Derived deterministic, bounded, filterable lineage roster rows from mission graph state                |
| `apps/server/src/managers/executorRegistry.ts`                 | Registered lifecycle executor posture and unavailable or approved-not-executing fallbacks              |
| `apps/server/src/lib/commandCenterValidation.ts`               | Added lifecycle command and lineage roster query validation                                            |
| `apps/server/src/lib/guardedActionValidation.ts`               | Updated guarded family and kind validation maps for lifecycle-adjacent actions                         |
| `apps/server/src/routes/commandCenter.ts`                      | Added hero lifecycle command and lineage roster routes with duplicate-trigger guards                   |
| `apps/server/src/routes/event.ts`                              | Promoted safe lifecycle and subagent hook observations into command-center state                       |
| `apps/server/src/server.ts`                                    | Instantiated and injected the lifecycle manager                                                        |
| `apps/hooks/src/_lib.js`                                       | Added shared hook text sanitization helpers                                                            |
| `apps/hooks/src/factionos-hero-spawn.js`                       | Added bounded lifecycle metadata shaping for terminal, listener, process, model, and permission labels |
| `apps/hooks/src/factionos-subagent-start.js`                   | Added bounded parent, child, type, and description lineage association metadata                        |
| `apps/hooks/tests/hookRuntime.test.js`                         | Covered bounded lifecycle and subagent association hook payloads                                       |
| `apps/web/src/lib/orchestrationApi.ts`                         | Added typed lifecycle mutation and lineage roster snapshot helpers                                     |
| `apps/web/src/lib/commandCenterUi.ts`                          | Added lifecycle status, action, roster filter, tab count, and redaction helpers                        |
| `apps/web/src/lib/orchestrationUi.ts`                          | Added lifecycle-adjacent guarded action display labels                                                 |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Wired the Hero/Lineage workbench into Orchestration panes                                              |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Threaded lifecycle and lineage API callbacks into the shell                                            |
| `apps/web/src/components/orchestration/OrchestrationTabs.tsx`  | Added the Hero/Lineage tab entry                                                                       |
| `apps/web/tests/OrchestrationPanel.test.tsx`                   | Covered integrated Hero/Lineage tab behavior                                                           |
| `apps/web/tests/commandCenterStore.test.ts`                    | Covered expanded lifecycle and roster frame store behavior                                             |
| `apps/web/tests/commandCenterUi.test.ts`                       | Covered lifecycle and lineage UI helper behavior                                                       |
| `apps/web/tests/orchestrationApi.test.ts`                      | Covered lifecycle mutation and lineage roster API helpers                                              |
| `apps/server/tests/commandCenterManager.test.ts`               | Covered manager lifecycle update behavior                                                              |
| `apps/server/tests/commandCenterRoutes.test.ts`                | Covered REST and WebSocket lifecycle and lineage route behavior                                        |
| `apps/server/tests/eventIngest.test.ts`                        | Covered lifecycle and lineage event ingestion promotion                                                |
| `apps/server/tests/executorRegistry.test.ts`                   | Covered lifecycle executor registry posture                                                            |
| `docs/api/README_api.md`                                       | Documented lifecycle and lineage routes, states, and privacy boundaries                                |

***

## Technical Decisions

1. **Protocol-first lifecycle and lineage contracts**: Shared parser helpers, labels, states, and event entries keep protocol, server, hook, and web behavior aligned.
2. **Lifecycle commands remain audit-owned**: The server records validated, idempotent lifecycle intent and unavailable outcomes without launching unsafe local executors.
3. **Lineage roster is derived from manager state**: `MissionGraphManager` owns deterministic ordering, degraded classification, filters, limits, and redacted roster text.
4. **Hooks publish bounded associations only**: Hook payloads expose compact labels and lineage associations while sanitizing local paths, token-like text, prompts, transcripts, and broad runtime details.
5. **Web workbench handles every operator state explicitly**: Loading, empty, error, offline, filtered, unavailable, active, completed, degraded, and duplicate-trigger states all have test coverage.

***

## Test Results

| Metric        | Value                                                    |
| ------------- | -------------------------------------------------------- |
| Tests         | 2834                                                     |
| Passed        | 2833                                                     |
| Skipped       | 1                                                        |
| Focused suite | 4 files, 21 tests passed during code review              |
| Format        | `npm run format:check` passed; 694 files checked         |
| Lint          | `npm run lint` passed; 696 files checked                 |
| Typecheck     | `npm run typecheck` passed for all configured workspaces |
| Security      | `npm run security:secrets` passed                        |
| Coverage      | Not emitted by validation command                        |

***

## Lessons Learned

1. Lifecycle command IDs need separate handling for idempotency-keyed and non-keyed submissions so distinct commands do not collide after completion.
2. Roster degraded filters should match rows with any degraded reason, even when the raw row state is still active or completed.
3. Hook and mission graph description fields need boundary-specific redaction before they can be reused in broad lineage roster surfaces.

***

## Future Considerations

Items for future sessions:

1. Continue Phase 19 with Mission Artifacts so lifecycle and lineage context can connect to shipped mission outputs without exposing raw artifacts broadly.
2. Keep terminal, container, remote, Worker, hosted, and collaboration transfer execution behind separate threat, permission, audit, tests, and docs gates.
3. Reuse the lifecycle duplicate-trigger and unavailable-state patterns for later command-center executor families.

***

## Session Statistics

* **Tasks**: 25 completed
* **Files Created**: 13 including session artifacts and updateprd summary
* **Files Modified**: 39 tracked files including updateprd bookkeeping
* **Tests Added**: 17 focused test files covered lifecycle and lineage behavior
* **Blockers**: 0 resolved


---

# 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_summary.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.