> 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/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase20-session08-managed-agent-lifecycle-control` **Package**: cross-cutting (`packages/protocol`, `apps/server`, `apps/web`) **Started**: 2026-06-28 19:53 **Last Updated**: 2026-06-28 20:38

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 24 / 24 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

### Tasks T023, T024 - Final verification and quality gates

**Started**: 2026-06-28 20:34 **Completed**: 2026-06-28 20:38 **Duration**: 4 minutes

**Notes**:

* T023: Ran the focused protocol/server/web Vitest suite and the app-desktop Playwright command-center e2e file after managed lifecycle implementation.
* T024: Ran package typechecks, formatting, lint, aggregate workspace typecheck, full Vitest suite, whitespace diff check, and changed-file non-ASCII scan.

**Files Changed**:

* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged final verification evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T023 and T024 complete and closed the checklist.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts apps/server/tests/managedAgentSessionManager.test.ts apps/server/tests/heroLifecycleManager.test.ts apps/server/tests/commandCenterValidation.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/eventIngest.test.ts apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/HeroLineageWorkbench.test.tsx apps/web/tests/CommandCenterPanes.test.tsx apps/web/tests/commandCenterStore.test.ts`
  * Result: PASS - Focused protocol, server, and web suites passed.
  * Evidence: `11 passed (11)`, `144 tests` passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`
  * Result: PASS - Browser command-center coverage passed after formatting.
  * Evidence: `6 passed`, including managed stop Hero/Lineage coverage.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - Protocol package typecheck passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - Server package typecheck passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - Web package typecheck passed after tightening the managed-action type guard.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run format:check`
  * Result: PASS - Biome format check passed after formatting touched files.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run lint`
  * Result: PASS - Biome lint passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run typecheck --workspaces --if-present`
  * Result: PASS - Aggregate workspace typecheck passed after formatting.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test`
  * Result: PASS - Full Vitest suite passed.
  * Evidence: `270 passed`, `1 skipped`, `3074 tests` passed and `1 skipped`.
* Command/check: `git diff --check`
  * Result: PASS - No whitespace errors.
* Command/check: `git diff --name-only | xargs -r sh -c 'LC_ALL=C rg -n "[^\x00-\x7F]" "$@"' sh`
  * Result: PASS - No non-ASCII matches in changed files.
* UI product-surface check: PASS - Managed stop appears in the Hero/Lineage e2e flow with executed state, while observed records remain audit-intent.
* UI craft check: PASS - Browser privacy guards, text fit checks, and focused UI tests passed for the managed lifecycle surface.

**BQC Fixes**:

* Contract alignment: Final focused, e2e, typecheck, and full suite gates validate protocol/server/web behavior together.
* Regression prevention: Full workspace tests and browser e2e cover both the new managed lifecycle path and adjacent command-center surfaces.
* Formatting and hygiene: Biome format/lint, workspace typecheck, diff check, and ASCII scan passed.

***

### Tasks T021, T022 - Browser evidence and lifecycle documentation

**Started**: 2026-06-28 20:27 **Completed**: 2026-06-28 20:33 **Duration**: 6 minutes

**Notes**:

* T021: Extended the command-center Playwright fixture with a ready managed Hero/Lineage lifecycle row, a managed stop mutation response, and browser assertions that the executed result appears without raw command, terminal output, transcript, broad path, token, or provider payload leakage.
* T022: Documented managed lifecycle ownership, process and PTY action limits, observed-only fallback, provider mutation unavailable states, compact event fields, and no external-session or hosted-control claim.

**Files Changed**:

* `tests/e2e/orchestration-command-center.e2e.ts` - Added managed stop fixture state, route handling, compact records, and browser privacy assertions.
* `apps/server/README_server.md` - Documented `ManagedAgentSessionManager` ownership and compact managed event boundaries.
* `apps/web/README_web.md` - Documented managed Hero/Lineage control rendering, scoped message input, disabled states, and privacy boundary.
* `docs/api/README_api.md` - Updated lifecycle command route, WebSocket event fields, and shipped behavior summary.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged e2e/docs evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T021 and T022 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`
  * Result: PASS - Browser command-center coverage passed with the managed stop scenario.
  * Evidence: `6 passed`, including `records a managed stop result in Hero/Lineage without raw lifecycle payloads`.
* UI product-surface check: PASS - The e2e scenario shows the managed stop result in the Hero/Lineage tab with correct executed state.
* UI craft check: PASS - Browser privacy guards passed and the managed result redacted token/path text while omitting raw command/output/transcript/provider payload copy.

**BQC Fixes**:

* Error information boundaries: Browser e2e verifies sensitive compact summary content is redacted before display.
* Contract alignment: Docs now match the managed server, web, REST, WebSocket, and observed-only behavior.
* Trust boundary enforcement: Documentation explicitly limits control to owned local managed sessions and rejects broader external or hosted control claims.

***

### Tasks T016, T017, T018, T019, T020 - Managed lifecycle web surface

**Started**: 2026-06-28 20:17 **Completed**: 2026-06-28 20:26 **Duration**: 9 minutes

**Notes**:

* T016: Extended web lifecycle submit helpers with managed session id, request-scoped message input, expected revision forwarding, managed-session mutation keys, and protocol response parsing.
* T017: Added UI normalization for managed labels, readiness, supported actions, execution run ids, result status, compact result summaries, and redacted metadata.
* T018: Updated the Hero/Lineage workbench to show managed stop/restart/message controls only for ready supported managed records, while observed records retain record-intent controls. Added scoped message input support.
* T019: Updated WebSocket sanitization to enum-validate and forward managed lifecycle fields while rejecting blocked raw payload keys before store mutation.
* T020: Added focused web coverage for managed REST bodies, observed versus managed labels, readiness-based controls, in-flight/offline behavior, pane integration, sanitizer redaction, and store normalization.

**Files Changed**:

* `apps/web/src/lib/orchestrationApi.ts` - Added managed lifecycle request fields and managed-aware mutation keys.
* `apps/web/src/lib/commandCenterUi.ts` - Added managed lifecycle labels, readiness copy, visible-action normalization, metadata, and redacted summaries.
* `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` - Added managed control rendering and scoped message input support.
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - Passed managed session id, expected revision, and scoped message input from the workbench submit handler.
* `apps/web/src/store/useWsClient.ts` - Sanitized managed lifecycle WebSocket fields and rejected blocked raw payload frames.
* `apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/commandCenterUi.test.ts`, `apps/web/tests/HeroLineageWorkbench.test.tsx`, `apps/web/tests/CommandCenterPanes.test.tsx`, `apps/web/tests/commandCenterStore.test.ts` - Added focused managed lifecycle web coverage.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged web implementation evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T016-T020 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/HeroLineageWorkbench.test.tsx apps/web/tests/CommandCenterPanes.test.tsx apps/web/tests/commandCenterStore.test.ts`
  * Result: PASS - Focused managed lifecycle web coverage passed.
  * Evidence: `5 passed (5)`, `74 tests` passed.
* UI product-surface check: PASS - Managed controls are shown only for ready supported records; observed records keep audit-intent controls; offline and in-flight states disable controls.
* UI craft check: PASS - Managed buttons use concise labels, scoped message input is bounded, metadata is compact and redacted, and no raw terminal output/transcript/provider payloads are rendered.

**BQC Fixes**:

* Duplicate action prevention: Managed web mutation keys include the managed session id and preserve in-flight guards.
* Error information boundaries: WebSocket sanitizer rejects blocked raw payload fields and redacts compact result summaries.
* User-visible lifecycle clarity: Executable managed controls are visually and textually distinct from record-intent audit actions.
* Contract alignment: Web request/response, WebSocket, store, and UI helpers use the shared protocol managed fields.

***

### Tasks T008, T012, T015 - Server validation and observed-hook safeguards

**Started**: 2026-06-28 20:14 **Completed**: 2026-06-28 20:16 **Duration**: 2 minutes

**Notes**:

* T008: Added route-parser coverage for managed session ids, scoped `messageInput`, idempotency keys, expected revisions, invalid managed session ids, oversized message input, and stale revision bounds.
* T012: Added lifecycle-manager coverage proving provider mutation intents (`change_model`, `change_permission_mode`, `change_isolation_mode`) return unavailable policy-blocked records without execution linkage.
* T015: Added event-ingest coverage proving hook lifecycle observations remain record-only and do not emit managed execution updates or managed lifecycle metadata.

**Files Changed**:

* `apps/server/tests/commandCenterValidation.test.ts` - Added managed lifecycle route validation and blocked raw-field coverage.
* `apps/server/tests/heroLifecycleManager.test.ts` - Added policy-blocked provider mutation coverage.
* `apps/server/tests/eventIngest.test.ts` - Added observed-hook record-only and no-execution assertions.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged validation and observed-hook evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T008, T012, and T015 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run apps/server/tests/managedAgentSessionManager.test.ts apps/server/tests/heroLifecycleManager.test.ts apps/server/tests/commandCenterValidation.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/eventIngest.test.ts`
  * Result: PASS - Focused server validation, route, manager, and ingest coverage passed.
  * Evidence: `5 passed (5)`, `46 tests` passed.
* UI product-surface check: N/A - No user-facing UI code changed in these tasks.
* UI craft check: N/A - No user-facing UI code changed in these tasks.

**BQC Fixes**:

* Trust boundary enforcement: Managed route input accepts only schema-validated ids and bounded request-scoped message text.
* Error information boundaries: Blocked raw lifecycle fields are rejected even when valid managed fields are present.
* Failure path completeness: Provider mutation requests return explicit local unavailable records before any execution run is created.
* Contract alignment: Hook observations and command-center managed execution paths remain separated.

***

### Tasks T006, T007, T009, T010, T011, T013, T014 - Managed server lifecycle implementation

**Started**: 2026-06-28 19:58 **Completed**: 2026-06-28 20:13 **Duration**: 15 minutes

**Notes**:

* T006: Created `ManagedAgentSessionManager` with explicit process/PTY registration, ownership checks, supported action checks, compact result mapping, process cleanup on dispose, PTY cleanup delegation, and duplicate in-flight guards.
* T007: Wired `ManagedAgentSessionManager` through server construction and into `OrchestrationCommandCenterManager` without changing hook observation ingestion.
* T009: Implemented managed stop for owned process and PTY sessions, including timeout-bounded process signaling, cleanup behavior, execution-run creation, and duplicate in-flight prevention.
* T010: Implemented managed restart only when process restart config or PTY restart path exists, with failed/unavailable results preserving the managed session record.
* T011: Implemented managed message only for owned running PTY sessions with request-scoped input and bounded stored summaries.
* T013: Linked managed lifecycle results to compact command-center execution runs and emitted lifecycle plus execution WebSocket updates without raw command/input/output payloads.
* T014: Updated route tests for managed stop execution, observed-only fallback, unsupported provider action unavailable state, duplicate idempotency/in-flight handling, and WebSocket event privacy.

**Files Changed**:

* `apps/server/src/managers/managedAgentSessionManager.ts` - Added managed process/PTY lifecycle manager.
* `apps/server/src/managers/heroLifecycleManager.ts` - Added managed result persistence fields and provider-action unavailable defaults.
* `apps/server/src/managers/orchestrationCommandCenter.ts` - Added async managed lifecycle submission, execution-run linkage, and compact event fields.
* `apps/server/src/routes/commandCenter.ts` - Routed hero lifecycle submissions through the async managed path and emitted execution updates.
* `apps/server/src/server.ts` - Instantiated and disposed the managed manager with the existing terminal manager.
* `apps/server/tests/managedAgentSessionManager.test.ts` - Added manager coverage for process stop, PTY message, restart failure, cleanup, and in-flight duplicate protection.
* `apps/server/tests/heroLifecycleManager.test.ts` - Added managed result persistence coverage.
* `apps/server/tests/commandCenterRoutes.test.ts` - Added route-level managed lifecycle and event privacy coverage.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged server implementation evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T006, T007, T009, T010, T011, T013, and T014 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - Server TypeScript compiled with the managed lifecycle implementation.
  * Evidence: `tsc --noEmit` exited successfully.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run apps/server/tests/managedAgentSessionManager.test.ts apps/server/tests/heroLifecycleManager.test.ts apps/server/tests/commandCenterRoutes.test.ts`
  * Result: PASS - Focused server lifecycle coverage passed.
  * Evidence: `3 passed (3)`, `27 tests` passed.
* UI product-surface check: N/A - No user-facing UI code changed in these tasks.
* UI craft check: N/A - No user-facing UI code changed in these tasks.

**BQC Fixes**:

* Resource cleanup: Manager disposal kills registered process sessions and delegates PTY cleanup.
* Duplicate action prevention: Manager and route-level in-flight guards reject duplicate lifecycle triggers.
* Trust boundary enforcement: Only explicitly registered managed sessions can be controlled; unregistered, wrong-hero, unsupported, stale, or non-running sessions return unavailable.
* Failure path completeness: Restart failure, unsupported provider actions, missing managed sessions, missing PTY support, and stopped sessions return bounded failed/unavailable results.
* Contract alignment: Lifecycle rows, execution runs, REST responses, and WebSocket events share the same protocol-managed fields.

***

### Task T005 - Align lifecycle REST aliases with managed request and response fields

**Started**: 2026-06-28 20:11 **Completed**: 2026-06-28 20:12 **Duration**: 1 minute

**Notes**:

* Added a protocol REST request interface for `/command-center/heroes/commands` that includes managed session id, expected revision, idempotency key, and request-scoped `messageInput`.
* Kept mutation/list response aliases aligned with the managed lifecycle command DTO.
* Added type-level and parser-adjacent coverage that proves request-scoped message input is not part of the stored mutation response and blocked raw lifecycle fields are rejected.

**Files Changed**:

* `packages/protocol/src/rest.ts` - Added `CommandCenterHeroLifecycleActionRestRequest`.
* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - Added managed lifecycle REST request/response coverage.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged T005 evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T005 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts`
  * Result: PASS - Protocol REST alias and parser coverage passed.
  * Evidence: `1 passed (1)`, `24 tests` passed.
* UI product-surface check: N/A - No user-facing UI code changed in this task.
* UI craft check: N/A - No user-facing UI code changed in this task.

**BQC Fixes**:

* Contract alignment: Added an explicit REST request type for managed lifecycle command submissions.
* Error information boundaries: Request-scoped message input remains outside stored mutation response objects.

***

### Task T004 - Extend command-center lifecycle protocol with managed fields

**Started**: 2026-06-28 19:55 **Completed**: 2026-06-28 20:10 **Duration**: 15 minutes

**Notes**:

* Added protocol-owned managed lifecycle action vocabulary for `stop`, `restart`, and `message`.
* Added protocol-owned managed readiness vocabulary for `observed_only`, `ready`, `running`, `stopped`, `stale`, and `unavailable`.
* Extended lifecycle command and event-entry contracts with managed session id, provider label, readiness, supported actions, execution run id, compact result status, and compact result summary.
* Extended lifecycle parsing to validate managed fields and reject unsupported supported-action entries.

**Files Changed**:

* `packages/protocol/src/orchestrationCommandCenter.ts` - Added managed lifecycle protocol constants, types, event fields, and parser validation.
* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - Added acceptance coverage for the managed protocol fields.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged T004 evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T004 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts`
  * Result: PASS - Managed protocol parsing and event-entry coverage passed.
  * Evidence: `1 passed (1)`, `23 tests` passed.
* UI product-surface check: N/A - No user-facing UI code changed in this task.
* UI craft check: N/A - No user-facing UI code changed in this task.

**BQC Fixes**:

* Contract alignment: Server and web can consume one shared managed lifecycle shape instead of duplicating readiness/action vocabularies.
* Trust boundary enforcement: Unsupported managed action values are rejected by the protocol parser.

***

### Task T003 - Add server acceptance coverage for managed lifecycle execution

**Started**: 2026-06-28 19:58 **Completed**: 2026-06-28 20:09 **Duration**: 11 minutes

**Notes**:

* Added focused manager coverage for owned process stop, missing/unowned session unavailable results, cleanup on dispose, duplicate in-flight process stop, PTY message input, and process restart failure.
* Added lifecycle-manager coverage proving managed result metadata is stored while request-scoped message input is not persisted.
* Added command-center route coverage for managed stop execution, compact lifecycle and execution WebSocket events, unsupported `change_model` unavailable state, event privacy, and duplicate in-flight route rejection.

**Files Changed**:

* `apps/server/tests/managedAgentSessionManager.test.ts` - Added manager acceptance tests for process, PTY, restart failure, cleanup, and in-flight duplicate behavior.
* `apps/server/tests/heroLifecycleManager.test.ts` - Added managed lifecycle metadata persistence coverage.
* `apps/server/tests/commandCenterRoutes.test.ts` - Added route-level managed stop, compact events, unsupported action, privacy, and duplicate in-flight coverage.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged T003 evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T003 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run apps/server/tests/managedAgentSessionManager.test.ts apps/server/tests/heroLifecycleManager.test.ts apps/server/tests/commandCenterRoutes.test.ts`
  * Result: PASS - Focused server acceptance coverage passed.
  * Evidence: `3 passed (3)`, `27 tests` passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - Server TypeScript integration compiled after manager and route wiring.
  * Evidence: `tsc --noEmit` exited successfully.
* UI product-surface check: N/A - No user-facing UI code changed in this task.
* UI craft check: N/A - No user-facing UI code changed in this task.

**BQC Fixes**:

* Duplicate action prevention: Added in-flight guards in `ManagedAgentSessionManager` and route-level duplicate coverage.
* Resource cleanup: Added manager disposal cleanup for owned process and PTY sessions.
* Trust boundary enforcement: Tests prove unregistered managed sessions return unavailable and route events expose compact safe metadata only.
* Failure path completeness: Restart failure and unsupported provider action paths now return explicit failed/unavailable states.

***

### Task T002 - Add protocol acceptance coverage for managed lifecycle metadata

**Started**: 2026-06-28 19:54 **Completed**: 2026-06-28 19:57 **Duration**: 3 minutes

**Notes**:

* Added protocol acceptance coverage for managed lifecycle readiness vocabulary, supported managed action labels, managed session id, provider label, execution run id, compact result status/summary, unavailable restart result, compact event entries, and unsupported managed-action rejection.
* Extended the protocol contract with managed lifecycle action and readiness constants/types.
* Extended `CommandCenterHeroLifecycleCommand` and compact event entries with managed session metadata, supported actions, execution linkage, and compact result fields.
* Extended `parseCommandCenterHeroLifecycleCommand` to validate managed fields and reject unsupported managed actions such as `change_model` in the supported managed-action list.

**Files Changed**:

* `packages/protocol/src/orchestrationCommandCenter.ts` - Added managed lifecycle constants, types, parser guards, DTO fields, and validation.
* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - Added managed lifecycle parser/event acceptance coverage.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Logged T002 evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T002 complete and updated progress.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts`
  * Result: PASS - Focused protocol suite passed.
  * Evidence: `1 passed (1)`, `23 tests` passed.
* UI product-surface check: N/A - No user-facing UI code changed in this task.
* UI craft check: N/A - No user-facing UI code changed in this task.

**BQC Fixes**:

* Contract alignment: Added parser validation alongside the new TypeScript fields so server/web consumers receive the same managed lifecycle shape.
* Trust boundary enforcement: Unsupported managed actions are rejected by the protocol parser before downstream execution code can treat provider-only actions as executable.

***

## Task Log

### 2026-06-28 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

**Environment notes**:

* Local `.spec_system/scripts/` was absent, so the bundled skill scripts were used.
* `analyze-project.sh --json` resolved current session `phase20-session08-managed-agent-lifecycle-control` with `Package: null`.
* `check-prereqs.sh --json --env` passed for `.spec_system`, `jq`, `git`, and npm workspace detection.
* `check-prereqs.sh --json --tools "node,npm"` found npm 11.16.0. The shell initially used Node 24.14.0 despite `.nvmrc` requiring 26.2.0; `nvm use 26.2.0` confirmed Node 26.2.0 and npm 11.16.0 are installed and available for verification commands.

***

### Task T001 - Verify current Hero/Lineage lifecycle behavior, managed-session gaps, and terminal control primitives

**Started**: 2026-06-28 19:50 **Completed**: 2026-06-28 19:53 **Duration**: 3 minutes

**Notes**:

* Confirmed `HeroLifecycleManager` currently records lifecycle intent only. `message`, `stop`, `dismiss`, `change_model`, `change_permission_mode`, `pause`, `resume`, and `release` become `approved_not_executing`; `restart`, `spawn`, `fork`, `handoff`, `assign`, and `change_isolation_mode` are unavailable or policy-blocked.
* Confirmed `HeroLineageWorkbench` currently renders record-intent verbs only and does not expose managed `stop`, `restart`, or `message` controls.
* Confirmed `TerminalSessionManager` already owns bounded PTY start, request-scoped input, kill, restart, output caps, idempotency guards, and shutdown cleanup primitives that managed-agent control can wrap.
* Confirmed protocol currently carries observed lifecycle metadata but lacks managed-session id, readiness, supported action, execution run id, and compact managed-result fields.

**Files Changed**:

* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` - Created session implementation log and recorded T001 evidence.
* `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` - Marked T001 complete.

**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: Output reported `current_session` as `phase20-session08-managed-agent-lifecycle-control`, `monorepo: true`, and `active_package: null`.
* 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 - Required spec environment is available.
  * Evidence: Output reported `overall: pass` with `.spec_system`, `jq-1.7`, `git version 2.43.0`, and `npm 11.16.0`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 && node --version && npm --version`
  * Result: PASS - Project Node/npm baseline is available.
  * Evidence: Output reported `v26.2.0` and `11.16.0`.
* Command/check: Targeted source inspection of `apps/server/src/managers/heroLifecycleManager.ts`, `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx`, `apps/server/src/managers/terminalSessionManager.ts`, `packages/protocol/src/orchestrationCommandCenter.ts`, `apps/server/src/lib/commandCenterValidation.ts`, and current focused tests.
  * Result: PASS - Existing behavior and gaps are understood before implementation.
  * Evidence: Observed-only lifecycle states, record-intent web labels, PTY kill/input/restart primitives, and missing managed fields were identified.
* UI product-surface check: N/A - No user-facing UI code changed in this task.
* UI craft check: N/A - No user-facing UI code changed in this task.

**BQC Fixes**:

* None. This task was source inspection and environment setup only.

***


---

# 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/phase20-session08-managed-agent-lifecycle-control/implementation-notes.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.