> 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_summary.md). # Implementation Summary **Session ID**: `phase20-session08-managed-agent-lifecycle-control` **Package**: null **Completed**: 2026-06-28 **Duration**: 0.8 hours *** ## Overview Session 08 added the managed-agent boundary for Hero/Lineage lifecycle controls. FactionOS can now execute stop, restart, and message actions only for manager-owned local process or PTY sessions, while hook-ingested Claude Code and Codex CLI sessions remain observed-only record-intent rows. The protocol, server, web, docs, and browser evidence now distinguish executable managed control from unsupported provider mutations and metadata-only observations. *** ## Deliverables ### Files Created | File | Purpose | Lines | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- | | `apps/server/src/managers/managedAgentSessionManager.ts` | Manager-owned process and PTY lifecycle control with ownership, cleanup, duplicate-trigger, and compact-result boundaries. | 642 | | `apps/server/tests/managedAgentSessionManager.test.ts` | Unit coverage for process stop, PTY message, restart failure, cleanup, unavailable paths, and duplicate triggers. | 269 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/spec.md` | Session scope, requirements, and implementation plan. | 248 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/tasks.md` | Completed 24-task checklist. | 88 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/implementation-notes.md` | Task-by-task implementation evidence. | 399 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/code-review.md` | Review findings and resolved fixes. | 97 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/security-compliance.md` | Security and GDPR review record. | 104 | | `.spec_system/specs/phase20-session08-managed-agent-lifecycle-control/validation.md` | Validation report with passing evidence. | 217 | ### Files Modified | File | Changes | | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Added managed lifecycle actions, readiness, supported actions, execution ids, compact results, and blocked raw-field validation. | | `packages/protocol/src/rest.ts` | Added managed lifecycle REST request typing and kept response aliases aligned. | | `apps/server/src/lib/commandCenterValidation.ts` | Added managed session id, expected revision, idempotency key, and scoped message-input validation. | | `apps/server/src/managers/heroLifecycleManager.ts` | Routed supported managed actions to execution while preserving observed-only and provider-unavailable records. | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Added async managed lifecycle submission, execution-run linkage, and compact event emission. | | `apps/server/src/routes/commandCenter.ts` | Returned managed lifecycle mutation results and compact lifecycle/execution WebSocket updates. | | `apps/server/src/server.ts` | Instantiated and disposed the managed session manager with the existing terminal manager. | | `apps/web/src/lib/orchestrationApi.ts` | Added managed lifecycle request fields and mutation-key support. | | `apps/web/src/lib/commandCenterUi.ts` | Added readiness-aware labels, availability, result copy, and safe metadata rendering. | | `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` | Rendered managed controls only for ready supported records with scoped message input and in-flight/offline states. | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Forwarded managed session id, expected revision, and message input to submit handlers. | | `apps/web/src/store/useWsClient.ts` | Sanitized managed lifecycle WebSocket fields and rejected blocked raw payloads. | | `apps/server/tests/*.test.ts`, `apps/web/tests/*.test.ts`, `packages/protocol/tests/*.test.ts` | Added focused regression coverage for managed lifecycle execution, observed-only fallback, unavailable provider actions, privacy, and UI state. | | `tests/e2e/orchestration-command-center.e2e.ts` | Added browser proof for a managed stop result in Hero/Lineage without raw payload leakage. | | `apps/server/README_server.md`, `apps/web/README_web.md`, `docs/api/README_api.md` | Documented managed lifecycle ownership, observed-only fallback, compact event boundaries, and no external or hosted control claim. | *** ## Technical Decisions 1. **Manager-owned control boundary**: Lifecycle execution requires explicit registration with `ManagedAgentSessionManager`; unowned, stale, stopped, unsupported, or wrong-hero sessions fail closed before process or PTY control. 2. **Observed sessions remain record-only**: Hook-ingested Claude Code and Codex CLI records keep audit-intent wording and do not gain managed authority unless the local manager owns the runtime. 3. **Compact execution evidence only**: Lifecycle rows, REST responses, WebSocket frames, docs, and UI metadata expose labels and ids without raw prompts, command bodies, terminal output, transcripts, broad paths, tokens, provider payloads, or raw process internals. 4. **Capability-driven UI verbs**: Hero/Lineage shows control verbs only when managed readiness and supported action fields prove the action can execute. *** ## Test Results | Metric | Value | | -------------- | --------------------------- | | Focused Vitest | 11 files, 146 passed | | Browser e2e | 6 passed | | Full Vitest | 270 files passed, 1 skipped | | Total Tests | 3077 | | Passed | 3076 | | Failed | 0 | | Skipped | 1 | | Coverage | Not collected | *** ## Lessons Learned 1. Hero lifecycle controls need a hard ownership boundary before action verbs are truthful. 2. Observed hook telemetry and managed local process control should stay separate in protocol, server, UI, docs, and tests. 3. Request-scoped message text and compact broad summaries need explicit parser, route, WebSocket, UI, and browser privacy assertions. *** ## Future Considerations Items for future sessions: 1. Session 09 should prove container dispatch as an executable family or keep it explicitly unsupported and unavailable. 2. Session 10 should reuse the same reviewable local task and no-auto-execution boundary for templates and channel intake. 3. Session 11 should re-run release privacy evidence across all completed Phase 20 executor families. *** ## Session Statistics * **Tasks**: 24 completed * **Files Created**: 8 * **Files Modified**: 27 implementation files before updateprd tracking/version edits * **Tests Added**: 38 focused protocol/server/web/browser cases across existing and new test files * **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/phase20-session08-managed-agent-lifecycle-control/implementation_summary.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.