> 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/phase19-session12-terminal-and-containers/tasks.md).

# Task Checklist

**Session ID**: `phase19-session12-terminal-and-containers` **Total Tasks**: 25 **Estimated Duration**: 3-4 hours **Created**: 2026-06-26

***

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

***

## Progress Summary

| Metric          | Value            |
| --------------- | ---------------- |
| Tasks Completed | 25 / 25          |
| Completion      | 100%             |
| Last Updated    | 2026-06-26 20:06 |

***

## Setup (2 tasks)

* [x] T001 \[S1912] Verify Session 12 prerequisites, phase stub scope, completed Sessions 06, 07, 08, and 09 artifacts, and current planning assumptions (`.spec_system/PRD/phase_19/session_12_terminal_and_containers.md`)
* [x] T002 \[S1912] Verify current terminal, container, executor registry, isolation diagnostics, package dependency, and Orchestration UI surfaces before changing contracts (`apps/server/src/managers/executorRegistry.ts`, `apps/server/src/lib/isolationDiagnostics.ts`, `apps/server/package.json`, `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx`)

***

## Foundation (7 tasks)

* [x] T003 \[S1912] Extend command-center protocol contracts for terminal sessions, terminal actions, container runtime probes, isolated spawn metadata, bounded output windows, and execution attachments with types matching declared contract and exhaustive enum handling (`packages/protocol/src/orchestrationCommandCenter.ts`, `packages/protocol/src/index.ts`)
* [x] T004 \[S1912] Extend isolation contracts with terminal/container readiness, PTY/Docker/Apple Containers fallback reasons, image state, mounts, network profile, cleanup posture, and docs paths (`packages/protocol/src/isolation.ts`)
* [x] T005 \[S1912] \[P] Add protocol tests for terminal/container contract parsing, isolation readiness metadata, execution attachments, and blocked raw payload fields (`packages/protocol/tests/orchestrationCommandCenter.test.ts`, `packages/protocol/tests/isolation.test.ts`)
* [x] T006 \[S1912] Add package-managed optional PTY adapter dependency metadata while preserving fail-closed runtime behavior when the adapter is absent (`apps/server/package.json`, `package-lock.json`)
* [x] T007 \[S1912] Create the server terminal session manager with injectable PTY adapter, output caps, timeout cleanup, input, kill, restart, exit state, result attachment, and cleanup on scope exit for all acquired resources (`apps/server/src/managers/terminalSessionManager.ts`)
* [x] T008 \[S1912] Create the server container runtime manager with injectable command runner, Docker/Apple Containers probes, image/browser/auth/worktree/network readiness, cleanup posture, isolated spawn preview, and timeout handling (`apps/server/src/managers/containerRuntimeManager.ts`)
* [x] T009 \[S1912] Create terminal/container request parsers with schema-validated input, request-scoped command handling, idempotency fields, explicit error mapping, and blocked raw-field rejection (`apps/server/src/lib/terminalContainerValidation.ts`)

***

## Server Implementation (6 tasks)

* [x] T010 \[S1912] Wire terminal and container executor registry entries to manager probes and guarded execution with authorization enforced at the local executor boundary (`apps/server/src/managers/executorRegistry.ts`)
* [x] T011 \[S1912] Add terminal and container REST routes for snapshots, preview/run, input, kill, restart, probes, and isolated spawn with duplicate-trigger prevention while in-flight (`apps/server/src/routes/terminalContainers.ts`)
* [x] T012 \[S1912] Wire terminal/container managers, routes, executor registry dependencies, and shutdown disposal into server startup without adding hosted or remote transfer (`apps/server/src/server.ts`)
* [x] T013 \[S1912] Store terminal/container execution updates, capability refresh data, result attachments, and safe WebSocket snapshots in the command-center manager and routes (`apps/server/src/managers/orchestrationCommandCenter.ts`, `apps/server/src/routes/commandCenter.ts`)
* [x] T014 \[S1912] Update isolation diagnostics with terminal/container readiness and fallback metadata while keeping diagnostics read-only and compact (`apps/server/src/lib/isolationDiagnostics.ts`)
* [x] T015 \[S1912] Add server tests for PTY lifecycle, bounded output, timeout, kill/restart, container probes, isolated spawn preview/run, guarded execution, WebSocket updates, auth inheritance, and no raw echo (`apps/server/tests/terminalSessionManager.test.ts`, `apps/server/tests/containerRuntimeManager.test.ts`, `apps/server/tests/terminalContainerRoutes.test.ts`, `apps/server/tests/executorRegistry.test.ts`, `apps/server/tests/commandCenterRoutes.test.ts`, `apps/server/tests/isolationDiagnostics.test.ts`)

***

## Web Implementation (5 tasks)

* [x] T016 \[S1912] Add web API clients for terminal snapshots, terminal preview/run/input/kill/restart, container probes, isolated spawn, parser failures, and duplicate in-flight mutation keys (`apps/web/src/lib/orchestrationApi.ts`)
* [x] T017 \[S1912] Add terminal/container view models, safe labels, fallback reason copy, output-window labels, isolation row summaries, and action availability helpers (`apps/web/src/lib/terminalContainers.ts`, `apps/web/src/lib/commandCenterUi.ts`)
* [x] T018 \[S1912] Create the scoped terminal runtime drawer with bounded output, lifecycle controls, loading/empty/error/offline states, focus management, and input support (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`)
* [x] T019 \[S1912] Create the isolation capability panel for PTY, Docker, Apple Containers, image, browser deps, auth mount, worktree mount, network profile, cleanup, and fallback states (`apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`)
* [x] T020 \[S1912] Wire terminal/container state, selected terminal revalidation, isolation rows, executor family summaries, drawer selection, toasts, and offline states into Orchestration (`apps/web/src/store/useGameStore.ts`, `apps/web/src/components/orchestration/CommandCenterPanes.tsx`, `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx`, `apps/web/src/components/orchestration/OrchestrationDrawer.tsx`, `apps/web/src/components/orchestration/OrchestrationShell.tsx`)

***

## Documentation And Testing (5 tasks)

* [x] T021 \[S1912] \[P] Add web tests for API clients, store normalization, terminal drawer controls, bounded output, isolation rows, malformed payloads, offline/error states, and product-facing copy (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/commandCenterStore.test.ts`, `apps/web/tests/terminalContainers.test.ts`, `apps/web/tests/TerminalRuntimeDrawer.test.tsx`, `apps/web/tests/IsolationCapabilityPanel.test.tsx`, `apps/web/tests/ExecutorFamiliesPanel.test.tsx`, `apps/web/tests/OrchestrationPanel.test.tsx`)
* [x] T022 \[S1912] Update API, server, web, and isolation documentation with terminal/container routes, optional PTY behavior, scoped output boundary, execution gates, and remaining no-claim boundaries (`docs/api/README_api.md`, `docs/isolation-and-sandbox.md`, `apps/server/README_server.md`, `apps/web/README_web.md`)
* [x] T023 \[S1912] Run focused protocol, server, and web tests for terminal/container contracts, managers, routes, executor registry, diagnostics, API helpers, store, and components (`npm test -- orchestrationCommandCenter isolation terminalSessionManager containerRuntimeManager terminalContainerRoutes executorRegistry commandCenterRoutes isolationDiagnostics orchestrationApi commandCenterStore terminalContainers TerminalRuntimeDrawer IsolationCapabilityPanel ExecutorFamiliesPanel OrchestrationPanel`)
* [x] T024 \[S1912] Run workspace validation and ASCII/LF checks after focused tests pass (`npm run typecheck --workspaces --if-present && npm run format:check && npm run lint && npm test`, `.spec_system/specs/phase19-session12-terminal-and-containers`)
* [x] T025 \[S1912] Record implementation notes, command evidence, runtime verification results, and any remaining fail-closed unavailable states for validate/updateprd handoff (`.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md`)

***

## 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/phase19-session12-terminal-and-containers/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.