> 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/phases/phase_20/session_08_managed_agent_lifecycle_control.md). # Session 08: Managed Agent Lifecycle Control **Session ID**: `phase20-session08-managed-agent-lifecycle-control` **Packages**: `packages/protocol`, `apps/server`, `apps/web` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Expose control verbs only for FactionOS-owned Claude/Codex sessions that can actually be controlled. *** ## Scope ### In Scope (MVP) * Add a managed agent session boundary with provider label, owned process or PTY id, cwd labels, readiness, supported actions, cleanup policy, and scoped IO. * Implement narrow first controls: stop, restart, and message when the managed process or PTY adapter supports them. * Keep change model, permission mode, and isolation mode unavailable unless a real provider-specific mechanism exists. * Keep hook-ingested or observed external sessions record-only. * Update Hero/Lineage UI verbs based on managed-session readiness and supported action list. ### Out of Scope * Arbitrary control of external Claude Code or Codex CLI sessions that FactionOS did not create. * Model, permission, or isolation changes without provider-specific execution mechanisms. *** ## Prerequisites * [ ] Session 01 completed and validated. * [ ] Managed session stop/restart acceptance tests defined before implementation starts. *** ## Deliverables 1. Managed session manager or equivalent adapter, hero lifecycle integration, readiness-aware UI, and tests. 2. Clear separation between observed sessions and FactionOS-owned controllable sessions. *** ## Success Criteria * [ ] A managed fixture process can be stopped and records an execution run. * [ ] Restart failure preserves prior session history and reports unavailable or failed state. * [ ] Unsupported model, permission, and isolation actions return unavailable before execution. * [ ] Observed-only sessions show record-only intent and never claim execution. * [ ] Browser e2e proves a managed stop result appears in the Hero/Lineage workbench. *** ## Folded Source Detail ### User Outcome Only managed Claude/Codex sessions that FactionOS can actually control show control verbs. Clicking a supported control performs a process or PTY action; observed-only sessions show record-only intent. ### Current Source Reality * Hook-ingested Claude Code and Codex CLI sessions are observed, not controlled. * `HeroLifecycleManager` records lifecycle commands only. * No current manager can send a prompt to an arbitrary external Claude/Codex process, change its model, change its permission mode, or dismiss it. * `apps/server` declares `tree-kill`; use it only for FactionOS-owned managed processes after a process adapter exists. ### Required Changes * Add a managed agent session boundary before claiming lifecycle control. Candidate manager: `apps/server/src/managers/managedAgentSessionManager.ts`. * A managed session must have provider label (`claude-code` or `codex-cli`), process id or PTY session id created by FactionOS, compact command line and cwd labels, readiness state, supported action list, kill/restart cleanup policy, and output/input scoping. * Supported first actions should be narrow: `stop`, `restart`, and `message` when the managed process or PTY adapter supports them. * `change_model`, `change_permission_mode`, and `change_isolation_mode` remain unavailable unless a real provider-specific mechanism is implemented. * Observed hook sessions continue to show `Record intent`, not `Stop`, `Dismiss`, `Change model`, or similar control verbs. ### Recovery Paths * Stop timeout escalates to kill and records cleanup state. * Restart failure leaves prior session history and an unavailable run. * Unsupported action returns unavailable before execution. ### Acceptance Tests From Findings * Manager test with a real spawned fixture process or injected process adapter proves stop kills an owned process and records an execution run. * Route test proves observed-only hero action records intent but does not claim executed. * Web test proves buttons switch between record-only and control verbs based on supported action readiness. * Browser e2e proves a managed session stop result appears in the Hero/Lineage workbench. --- # 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/phases/phase_20/session_08_managed_agent_lifecycle_control.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.