> 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/validation.md). # Validation Report **Session ID**: `phase20-session08-managed-agent-lifecycle-control` **Package**: null (cross-cutting) **Validated**: 2026-06-28 **Result**: PASS ## Validation Summary | Check | Status | Notes | | ------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | Code Review | PASS | `code-review.md` exists, scope is all uncommitted changes, and Result is `RESOLVED`; validation-fix review note added. | | Tasks Complete | PASS | 24/24 tasks complete. | | Files Exist | PASS | 30/30 deliverable and touched support files checked exist and are non-empty. | | ASCII Encoding | PASS | 35/35 changed or untracked files are ASCII/LF. | | Tests Passing | PASS | Focused Vitest 146/146, Playwright 6/6, full Vitest 3076 passed and 1 skipped. | | Database/Schema Alignment | N/A | N/A -- conventions say database is not configured and the spec excludes DB/schema work. | | Quality Gates | PASS | Format, lint, package typechecks, workspace typecheck, full tests, e2e, security secret scan, and `git diff --check` passed. | | Conventions | PASS | Node/npm versions matched conventions; Biome, TypeScript, Vitest, Playwright, and workspace gates passed. | | Security & GDPR | PASS | See `security-compliance.md`; security PASS, GDPR N/A. | | Behavioral Quality | PASS | Trust boundary, cleanup, mutation safety, failure path, and contract alignment spot-checks passed. | | UI Product Surface | PASS | Browser and component evidence passed; no normal Hero/Lineage product surface diagnostics found. | **Overall**: PASS ## Evidence Ledger | Check | Command or Inspection | Result | Evidence / Blocker | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Project state | `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` | PASS | Current session is `phase20-session08-managed-agent-lifecycle-control`; monorepo true; package null; session directory exists. | | Code review | \`rg -n '^\*\*(Result | Scope)\*\* | ^\*\*Files reviewed\*\* | | Task completion | `rg -c '^- \[[ x]\] T[0-9]+' .../tasks.md`; `rg -c '^- \[x\] T[0-9]+' .../tasks.md`; `rg -n '^- \[ \] T[0-9]+' .../tasks.md` | PASS | `total=24 completed=24`; pending search returned `none`. | | Deliverables | Shell existence/non-empty loop over the 29 spec deliverables plus `apps/web/src/components/orchestration/OrchestrationShell.tsx` support file | PASS | 30 files checked; all exist and are non-empty. | | ASCII/LF | `file $changed_files`; `LC_ALL=C rg -n '[^\x00-\x7F]' $changed_files`; CRLF grep loop over changed/untracked files | PASS | 35 changed or untracked files checked; no non-ASCII matches; no CRLF matches. | | Tests | Initial focused Vitest command | FAIL then FIXED | Initial run failed 1 test because the duplicate in-flight route test raced HTTP scheduling. Fix applied to wait for mocked kill path before duplicate request. | | Tests | `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` | PASS | 11 files passed; 146 tests passed. | | Tests | `npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts` | PASS | 6 browser tests passed, including managed stop in Hero/Lineage without raw lifecycle payload leakage. | | Tests | `npm test` | PASS | 270 files passed, 1 skipped; 3076 tests passed, 1 skipped. | | Typecheck | `npm --workspace packages/protocol run typecheck`; `npm --workspace apps/server run typecheck`; `npm --workspace apps/web run typecheck`; `npm run typecheck --workspaces --if-present` | PASS | Protocol, server, web, adapters, warroom, public website, and workspace typechecks passed. | | Format/lint | `npm run format:check`; `npm run lint`; `git diff --check` | PASS | 765 files format-checked, 767 files linted, no whitespace errors. | | Security scan | `npm run security:secrets` | PASS | Secret scan passed; 1978 tracked text files checked. | | Database/schema | \`git diff --name-only HEAD | rg '(^ | /)(migrations | | Success criteria | Spec criteria inspection plus focused/full tests and e2e | PASS | Managed process stop, restart failure, PTY message, unsupported provider actions, observed-only fallback, privacy, and quality gates have direct evidence. | | Conventions | `.spec_system/CONVENTIONS.md`, README files, Node/npm check, and package gates | PASS | Node v26.2.0 and npm 11.16.0 used; npm workspace, Biome, TypeScript, Vitest, and Playwright gates passed. | | Security/GDPR | `security-compliance.md` checklist; `npm run security:secrets`; targeted keyword/control inspections | PASS/N/A | Security PASS, GDPR N/A; no dependency or database changes. | | Behavioral quality | Targeted inspection of `managedAgentSessionManager.ts`, `commandCenterValidation.ts`, `orchestrationCommandCenter.ts`, `HeroLineageWorkbench.tsx`, and `useWsClient.ts` | PASS | Ownership checks, schema validation, preflight, timeout cleanup, in-flight guards, explicit failure states, and sanitized WebSocket/UI handling found. | | UI product surface | Playwright app-desktop e2e, HeroLineageWorkbench component test, and code inspection | PASS | Hero/Lineage shows managed controls only when supported and redacts token/path text; no debug/status/scaffolding diagnostics appear on the normal managed lifecycle surface. | ## 1. Code Review Gate ### Status: PASS **Report**: `code-review.md` **Result**: RESOLVED **Issues**: None unresolved. The report records 1 high, 1 medium, and 1 low finding from creview as fixed, plus a validation-fix review note for the duplicate-trigger test race fixed during validation. ## 2. Task Completion ### Status: PASS **Tasks**: 24/24 complete **Incomplete tasks**: None ## 3. Deliverables Verification ### Status: PASS | File | Found | Status | | ---------------------------------------------------------------- | ----- | ------ | | `apps/server/src/managers/managedAgentSessionManager.ts` | Yes | PASS | | `apps/server/tests/managedAgentSessionManager.test.ts` | Yes | PASS | | `packages/protocol/src/orchestrationCommandCenter.ts` | Yes | PASS | | `packages/protocol/src/rest.ts` | Yes | PASS | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Yes | PASS | | `apps/server/src/lib/commandCenterValidation.ts` | Yes | PASS | | `apps/server/src/managers/heroLifecycleManager.ts` | Yes | PASS | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Yes | PASS | | `apps/server/src/routes/commandCenter.ts` | Yes | PASS | | `apps/server/src/routes/event.ts` | Yes | PASS | | `apps/server/src/server.ts` | Yes | PASS | | `apps/server/tests/heroLifecycleManager.test.ts` | Yes | PASS | | `apps/server/tests/commandCenterValidation.test.ts` | Yes | PASS | | `apps/server/tests/commandCenterRoutes.test.ts` | Yes | PASS | | `apps/server/tests/eventIngest.test.ts` | Yes | PASS | | `apps/web/src/lib/orchestrationApi.ts` | Yes | PASS | | `apps/web/src/lib/commandCenterUi.ts` | Yes | PASS | | `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` | Yes | PASS | | `apps/web/src/store/useGameStore.ts` | Yes | PASS | | `apps/web/src/store/useWsClient.ts` | Yes | PASS | | `apps/web/tests/orchestrationApi.test.ts` | Yes | PASS | | `apps/web/tests/commandCenterUi.test.ts` | Yes | PASS | | `apps/web/tests/HeroLineageWorkbench.test.tsx` | Yes | PASS | | `apps/web/tests/CommandCenterPanes.test.tsx` | Yes | PASS | | `apps/web/tests/commandCenterStore.test.ts` | Yes | PASS | | `tests/e2e/orchestration-command-center.e2e.ts` | Yes | PASS | | `apps/server/README_server.md` | Yes | PASS | | `apps/web/README_web.md` | Yes | PASS | | `docs/api/README_api.md` | Yes | PASS | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Yes | PASS | **Missing deliverables**: None ## 4. ASCII Encoding Check ### Status: PASS | File Set | Encoding | Line Endings | Status | | ---------------------------------- | ------------------------------------------------------------------------------------- | ------------ | ------ | | 35 touched tracked/untracked files | ASCII text, JavaScript source ASCII text, or JSON text data with no non-ASCII matches | LF | PASS | **Encoding issues**: None ## 5. Test Results ### Status: PASS | Metric | Value | | ----------------- | ------------------------------------ | | Focused Vitest | 11 files, 146 passed | | Browser e2e | 6 passed | | Full Vitest files | 270 passed, 1 skipped | | Full Vitest tests | 3076 passed, 1 skipped | | Failed | 0 after validation fix | | Coverage | Not collected by validation commands | **Failed tests**: None remaining. Initial focused Vitest failure was fixed by making the duplicate in-flight route test wait for the mocked managed process kill path before issuing the duplicate request. ## 6. Database/Schema Alignment ### Status: N/A **Evidence**: `git diff --name-only HEAD | rg '(^|/)(migrations|migration|schema|schemas|prisma|db|database|sql)(/|\.|$)|\.(sql|prisma)$'` returned no matches. `.spec_system/CONVENTIONS.md` states `Database | not configured`; session spec Out Of Scope states database, persistence schema, or migration work is not included because command-center lifecycle state remains in-memory manager-owned local state. **Issues found**: None ## 7. Success Criteria From spec.md: **Functional requirements**: * [x] A managed fixture process can be stopped, records an executed command-center execution run, and leaves a compact lifecycle result in Hero/Lineage state. Evidence: `apps/server/tests/commandCenterRoutes.test.ts`, `apps/server/tests/managedAgentSessionManager.test.ts`, and Playwright e2e passed. * [x] Managed restart failure preserves prior session history and returns failed or unavailable state without deleting the earlier lifecycle record. Evidence: `apps/server/tests/managedAgentSessionManager.test.ts` passed. * [x] Managed message writes only to a running owned PTY session and rejects missing, stopped, or unowned sessions before execution. Evidence: `apps/server/tests/managedAgentSessionManager.test.ts` and `apps/server/tests/heroLifecycleManager.test.ts` passed. * [x] `change_model`, `change_permission_mode`, and `change_isolation_mode` return unavailable before execution with product-facing recovery copy. Evidence: `apps/server/tests/heroLifecycleManager.test.ts` and `apps/server/tests/commandCenterRoutes.test.ts` passed. * [x] Hook-ingested or observed-only Claude/Codex sessions show record-only intent and never use process-control verbs. Evidence: `apps/server/tests/eventIngest.test.ts` and web lifecycle tests passed. * [x] Broad REST responses, WebSocket events, UI rows, docs, and tests do not expose raw prompts, command bodies, terminal output, transcripts, broad absolute paths, tokens, provider payloads, or raw process internals. Evidence: protocol parser tests, route event privacy tests, web sanitizer/redaction tests, secret scan, and Playwright e2e passed. **Testing requirements**: * [x] Protocol tests cover managed lifecycle metadata, supported actions, execution run ids, unavailable states, and blocked raw-field rejection. Evidence: protocol focused test passed. * [x] Server tests cover owned process stop, PTY message, restart failure, unsupported actions, observed-only fallback, route events, execution-run linkage, and duplicate-trigger prevention. Evidence: server focused tests passed. * [x] Web tests cover managed versus observed labels, readiness-based buttons, offline/error states, in-flight guards, safe metadata, and store normalization. Evidence: web focused tests passed. * [x] Browser e2e proves a managed stop result appears in the Hero/Lineage workbench. Evidence: Playwright 6/6 passed. **Non-functional requirements**: * [x] No lifecycle action controls a process or PTY that was not created or registered by FactionOS. Evidence: manager ownership checks and unregistered-session tests passed. * [x] Managed stop, restart, and message actions are idempotent or duplicate-trigger protected while in flight. Evidence: route/manager in-flight tests passed after validation fix. * [x] Managed process cleanup runs on manager disposal and local server shutdown. Evidence: manager dispose tests and server construction/disposal inspection passed. * [x] Sensitive developer data remains local and scoped; no hosted, Worker, provider, analytics, or remote execution behavior is introduced. Evidence: no dependency/config changes, docs inspection, and privacy tests passed. * [x] Existing terminal, Git, file, queue, campaign, and observed lifecycle behavior remains compatible. Evidence: full Vitest and command-center e2e passed. **Quality gates**: * [x] All files ASCII-encoded. Evidence: changed-file ASCII scan passed. * [x] Unix LF line endings. Evidence: CRLF scan passed. * [x] Code follows project conventions. Evidence: format, lint, typecheck, and tests passed. * [x] Primary user-facing surfaces contain product-facing copy only. Evidence: Playwright and component/code inspections passed. * [x] Focused protocol, server, web, browser, root quality, and `git diff --check` commands pass. Evidence: all commands passed. ## 8. Conventions Compliance ### Status: PASS **Categories spot-checked**: naming, file structure, error handling, comments, testing, and database conventions where relevant. **Convention violations**: None. Evidence: `.spec_system/CONVENTIONS.md`, root/package README guidance, Node v26.2.0/npm 11.16.0 check, Biome format/lint, TypeScript typechecks, Vitest, Playwright, and no DB configured. ## 9. Security & GDPR Compliance ### Status: PASS **Full report**: See `security-compliance.md` in this session directory. #### Summary | Area | Status | Findings | | -------- | ------ | -------- | | Security | PASS | 0 issues | | GDPR | N/A | 0 issues | **Critical violations**: None ## 10. Behavioral Quality Spot-Check ### Status: PASS **Checklist applied**: Yes **Files spot-checked**: * `apps/server/src/managers/managedAgentSessionManager.ts` * `apps/server/src/lib/commandCenterValidation.ts` * `apps/server/src/managers/orchestrationCommandCenter.ts` * `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` * `apps/web/src/store/useWsClient.ts` **Categories spot-checked**: trust boundaries, resource cleanup, mutation safety, failure paths, and contract alignment. **Violations found**: None. Evidence: targeted inspections found schema validation and blocked-field rejection before mutation, manager-owned session registration and hero ownership checks, timeout-bounded stop and cleanup, duplicate in-flight/idempotency guards, stale revision preflight before process control, explicit failed/unavailable states, and WebSocket/UI enum sanitization before store mutation. **Fixes applied during validation**: * `apps/server/tests/commandCenterRoutes.test.ts` duplicate in-flight route test now waits for the mocked kill path to start before sending the duplicate request, removing a validation-time race while preserving the product behavior under test. ## 11. UI Product-Surface Spot-Check ### Status: PASS **Surfaces inspected**: Orchestration panel Heroes tab, Hero lifecycle region, managed stop control, managed result row, and managed message input through app-desktop Playwright, component tests, and code inspection. **Diagnostics found in primary UI**: None. The rendered managed lifecycle e2e asserts `Managed Running`, `Provider Codex CLI`, `Stop managed session`, and `Managed process stopped locally`, while asserting raw command, terminal output, transcript, broad path, token, and provider payload text are absent. **Allowed debug/admin surfaces**: Existing explicit Diagnostics surfaces only; this session did not add debug panels or runtime telemetry to normal Hero/Lineage product UI. **Fixes applied during validation**: None ## Validation Result ### PASS Session `phase20-session08-managed-agent-lifecycle-control` passes validation. Code review is resolved, all tasks are complete, deliverables exist, touched files are ASCII/LF, quality gates and tests pass, no DB/schema work applies, security passes, GDPR is N/A, behavioral quality passes, and product-surface checks pass. ### Unresolved Failures And Blockers None ## Next Steps Next command: `updateprd` --- # 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/validation.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.