> 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/tasks.md).

# Task Checklist

**Session ID**: `phase20-session08-managed-agent-lifecycle-control` **Total Tasks**: 24 **Estimated Duration**: 3.5-4 hours **Created**: 2026-06-28

***

Legend: `[x]` completed; `[ ]` pending; `[P]` parallelizable; `[SNNMM]` session ref; `TNNN` task ID.

***

## Setup (3 tasks)

* [x] T001 \[S2008] Verify current Hero/Lineage lifecycle behavior, managed-session gaps, and terminal control primitives before implementation (`apps/server/src/managers/heroLifecycleManager.ts`, `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx`, `apps/server/src/managers/terminalSessionManager.ts`)
* [x] T002 \[S2008] \[P] Add protocol acceptance coverage for managed lifecycle metadata, supported actions, execution run ids, unavailable states, and blocked raw-field rejection (`packages/protocol/tests/orchestrationCommandCenter.test.ts`)
* [x] T003 \[S2008] \[P] Add server acceptance coverage for owned process stop, PTY message, restart failure, observed-only fallback, unsupported actions, route event privacy, and duplicate-trigger prevention while in-flight (`apps/server/tests/managedAgentSessionManager.test.ts`, `apps/server/tests/heroLifecycleManager.test.ts`, `apps/server/tests/commandCenterRoutes.test.ts`)

## Progress Summary

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

***

## Foundation (5 tasks)

* [x] T004 \[S2008] Extend command-center lifecycle protocol with managed session id, provider label, readiness state, supported action list, execution run id, and compact result fields (`packages/protocol/src/orchestrationCommandCenter.ts`)
* [x] T005 \[S2008] Keep lifecycle REST aliases aligned with managed fields and add parser coverage for safe request and response shapes (`packages/protocol/src/rest.ts`, `packages/protocol/tests/orchestrationCommandCenter.test.ts`)
* [x] T006 \[S2008] Create `ManagedAgentSessionManager` with process and PTY adapters, ownership registration, cleanup on dispose, supported action checks, and compact result mapping (`apps/server/src/managers/managedAgentSessionManager.ts`)
* [x] T007 \[S2008] Wire managed lifecycle dependencies through command-center and server construction without changing observed-only ingestion behavior (`apps/server/src/managers/orchestrationCommandCenter.ts`, `apps/server/src/server.ts`)
* [x] T008 \[S2008] Extend lifecycle route validation for managed session ids, scoped message input, expected revisions, idempotency keys, and unsupported action errors with schema-validated input and explicit error mapping (`apps/server/src/lib/commandCenterValidation.ts`)

***

## Server Implementation (7 tasks)

* [x] T009 \[S2008] Implement managed stop for owned process and PTY sessions with timeout escalation, cleanup on scope exit for all acquired resources, execution run creation, and duplicate-trigger prevention while in-flight (`apps/server/src/managers/managedAgentSessionManager.ts`, `apps/server/src/managers/heroLifecycleManager.ts`)
* [x] T010 \[S2008] Implement managed restart only when a restart command or PTY restart path is configured, preserving prior session history and returning failed or unavailable state on restart failure (`apps/server/src/managers/managedAgentSessionManager.ts`, `apps/server/src/managers/heroLifecycleManager.ts`)
* [x] T011 \[S2008] Implement managed message only for running owned PTY sessions with request-scoped input, bounded stored summary, and explicit unavailable results for stopped, non-PTY, or unowned sessions (`apps/server/src/managers/managedAgentSessionManager.ts`, `apps/server/src/managers/heroLifecycleManager.ts`)
* [x] T012 \[S2008] Keep observed hook sessions record-only and return unavailable before execution for model, permission, and isolation changes (`apps/server/src/managers/heroLifecycleManager.ts`, `apps/server/src/routes/event.ts`)
* [x] T013 \[S2008] Link lifecycle command results to command-center execution runs and emit compact lifecycle plus execution update events without raw command, output, transcript, path, token, or provider payload leakage (`apps/server/src/managers/orchestrationCommandCenter.ts`, `apps/server/src/routes/commandCenter.ts`)
* [x] T014 \[S2008] Update server route tests for managed stop execution, observed-only intent, unsupported action unavailable state, stale revisions, duplicate idempotency keys, and WebSocket event privacy (`apps/server/tests/commandCenterRoutes.test.ts`)
* [x] T015 \[S2008] Update event-ingest and validation tests so hook observations remain record-only and blocked raw lifecycle input is rejected before manager mutation (`apps/server/tests/eventIngest.test.ts`, `apps/server/tests/commandCenterValidation.test.ts`)

***

## Web Implementation (5 tasks)

* [x] T016 \[S2008] Add managed lifecycle request fields and response validation to web API helpers with duplicate in-flight keys and offline/error result handling (`apps/web/src/lib/orchestrationApi.ts`)
* [x] T017 \[S2008] Normalize managed lifecycle labels, readiness, supported actions, execution run ids, unavailable copy, and safe metadata with redaction (`apps/web/src/lib/commandCenterUi.ts`)
* [x] T018 \[S2008] Render `Stop managed session`, `Restart managed session`, and `Message managed session` only for supported ready records, while observed records keep record-intent copy with platform-appropriate accessibility labels, focus management, and input support (`apps/web/src/components/orchestration/HeroLineageWorkbench.tsx`)
* [x] T019 \[S2008] Normalize managed lifecycle REST and WebSocket fields in the store without admitting blocked raw payload fields (`apps/web/src/store/useGameStore.ts`, `apps/web/src/store/useWsClient.ts`)
* [x] T020 \[S2008] Update web tests for managed versus observed labels, readiness-based controls, offline/error states, in-flight guards, store normalization, safe metadata, and redaction (`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`)

***

## Documentation And Browser Evidence (2 tasks)

* [x] T021 \[S2008] Add browser e2e coverage proving a managed stop result appears in the Hero/Lineage workbench without raw command, terminal output, transcript, broad path, token, or provider payload leakage (`tests/e2e/orchestration-command-center.e2e.ts`)
* [x] T022 \[S2008] Document managed lifecycle control, process ownership, PTY limits, unsupported provider actions, observed-only fallback, compact events, and no external-session or hosted control claim (`apps/server/README_server.md`, `apps/web/README_web.md`, `docs/api/README_api.md`)

***

## Verification (2 tasks)

* [x] T023 \[S2008] Run focused protocol, server, web, and browser checks (`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`; `npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`)
* [x] T024 \[S2008] Run workspace quality and whitespace gates (`npm --workspace packages/protocol run typecheck`; `npm --workspace apps/server run typecheck`; `npm --workspace apps/web run typecheck`; `npm run format:check`; `npm run lint`; `npm run typecheck --workspaces --if-present`; `npm test`; `git diff --check`)

***

## Completion Checklist

* [x] All tasks marked `[x]`
* [x] All tests and checks passing
* [x] All files ASCII-encoded with LF line endings
* [x] implementation-notes.md updated
* [x] Ready for `creview` to continue the implement -> creview -> validate sequence

***

## Next Steps

Run the `creview` workflow step.


---

# 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/tasks.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.