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

# Implementation Notes

**Session ID**: `phase19-session12-terminal-and-containers` **Package**: null **Started**: 2026-06-26 18:48 **Last Updated**: 2026-06-26 20:06

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 25 / 25   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

## Task Log

### 2026-06-26 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available
* [x] Directory structure ready

***

### Task T001 - Verify Session 12 prerequisites and scope

**Started**: 2026-06-26 18:46 **Completed**: 2026-06-26 18:48 **Duration**: 2 minutes

**Notes**:

* Confirmed active session from `.spec_system/state.json` through the local spec-system analyzer.
* Confirmed Session 12 is cross-package with `Package: null` in the generated spec, while the phase stub names `apps/server` and `apps/web` as primary package surfaces.
* Confirmed Sessions 06, 07, 08, and 09 are complete in deterministic analyzer output before proceeding with terminal/container implementation.
* Confirmed optional Docker and Apple Containers probes are runtime posture checks, not development prerequisites.

**Files Changed**:

* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - created implementation progress log and recorded setup evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `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`
  * Result: PASS - analyzer returned `current_session: phase19-session12-terminal-and-containers`, `current_session_dir_exists: true`, `monorepo: true`, and Session 06 through Session 09 in `completed_sessions`.
  * Evidence: output also listed Session 12 as the first incomplete Phase 19 candidate with package `null`.
* Command/check: `sed -n '1,220p' .spec_system/PRD/phase_19/session_12_terminal_and_containers.md`
  * Result: PASS - phase stub names terminal PTY execution, container/isolation diagnostics, isolated spawn gating, scoped terminal drawer, and tests as in scope.
  * Evidence: out-of-scope entries remain remote access tunnel creation and broad terminal output rendering.
* UI product-surface check: N/A - setup verification changed no user-facing surface.
* UI craft check: N/A - setup verification changed no user-facing surface.

***

### Task T002 - Verify current terminal and container surfaces

**Started**: 2026-06-26 18:48 **Completed**: 2026-06-26 18:51 **Duration**: 3 minutes

**Notes**:

* Confirmed `executorRegistry.ts` currently registers terminal and container default entries as unavailable placeholders, while file and Git entries are executor-ready.
* Confirmed `isolationDiagnostics.ts` emits default isolation executor capabilities without runtime terminal/container probe metadata.
* Confirmed `apps/server/package.json` has no package-managed PTY adapter dependency before this session.
* Confirmed `ExecutorFamiliesPanel.tsx` renders executor family readiness and recent safe run summaries, but no scoped terminal drawer or isolation capability panel exists yet.
* Confirmed guarded-action approval already creates command-center execution runs through `executorRegistry`, which is the correct boundary for terminal/container guarded execution.

**Files Changed**:

* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded baseline inspection evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `sed -n '1,260p' apps/server/src/managers/executorRegistry.ts` and `sed -n '241,980p' apps/server/src/managers/executorRegistry.ts`
  * Result: PASS - inspected default terminal/container placeholder entries, probe/execute boundary, cleanup behavior, and guarded family/kind mapping.
  * Evidence: terminal default entry was unavailable with `not_implemented`; container default entry was unavailable with `policy_blocked`.
* Command/check: `sed -n '1,260p' apps/server/src/lib/isolationDiagnostics.ts`
  * Result: PASS - inspected current read-only default isolation snapshot builder.
  * Evidence: diagnostics call `buildDefaultIsolationExecutorCapabilities()` and do not yet include manager probe metadata.
* Command/check: `sed -n '1,220p' apps/server/package.json`
  * Result: PASS - inspected server package dependencies and optional dependencies.
  * Evidence: no `node-pty` optional dependency exists before implementation.
* Command/check: `sed -n '1,260p' apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx`
  * Result: PASS - inspected current executor family UI surface.
  * Evidence: family cards show readiness, requirements, refresh, and recent runs without scoped terminal output.
* Command/check: `sed -n '1,360p' apps/server/src/routes/guardedActions.ts`
  * Result: PASS - inspected guarded-action approval execution flow.
  * Evidence: approved actions evaluate executor capability, create queued command-center execution runs, mark executing, execute through registry, complete runs, and emit updates.
* UI product-surface check: N/A - setup verification changed no user-facing surface.
* UI craft check: N/A - setup verification changed no user-facing surface.

***

### Task T003 - Extend command-center protocol contracts

**Started**: 2026-06-26 18:51 **Completed**: 2026-06-26 19:04 **Duration**: 13 minutes

**Notes**:

* Added terminal session state, terminal action, container runtime, runtime readiness, mount readiness, network profile, cleanup posture, bounded output window, terminal probe/session/preview, container probe, isolated spawn preview, and safe execution attachment contracts.
* Extended command-center unavailable reasons with terminal/container-specific fail-closed reasons.
* Extended execution runs and execution WebSocket event entries with safe terminal/container attachments that exclude command bodies and terminal output.
* Added parsers and enum guards for the new contracts, including raw-field rejection on terminal/container protocol records.

**Files Changed**:

* `packages/protocol/src/orchestrationCommandCenter.ts` - added terminal/container DTOs, enums, guards, parsers, and execution attachment support.
* `packages/protocol/src/index.ts` - verified existing wildcard export already publishes updated command-center contracts.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* Command/check: targeted inspection of `packages/protocol/src/orchestrationCommandCenter.ts`
  * Result: PASS - new DTO parsers reject blocked raw field names and add only safe execution attachment metadata to broad records.
  * Evidence: `parseCommandCenterTerminalProbe`, `parseCommandCenterTerminalSession`, `parseCommandCenterContainerProbeSnapshot`, `parseCommandCenterIsolatedSpawnPreview`, and `parseCommandCenterExecutionAttachment` call `rejectCommandCenterBlockedPayloadFields`.
* UI product-surface check: N/A - shared protocol contracts changed no rendered UI.
* UI craft check: N/A - shared protocol contracts changed no rendered UI.

**BQC Fixes**:

* Contract alignment: added parser/guard coverage with execution-run attachment parsing so server and web cannot silently drift from the declared terminal/container shapes (`packages/protocol/src/orchestrationCommandCenter.ts`).

***

### Task T004 - Extend isolation contracts

**Started**: 2026-06-26 19:04 **Completed**: 2026-06-26 19:07 **Duration**: 3 minutes

**Notes**:

* Added isolation readiness contracts for PTY, Docker, Apple Containers, image state, browser dependencies, auth/worktree mounts, network profile, cleanup posture, and fallback reasons.
* Kept default isolation posture conservative by reporting terminal and container families unavailable until manager probes prove readiness.
* Added runtime, mount, network, and cleanup guard helpers for exhaustive isolation metadata handling.

**Files Changed**:

* `packages/protocol/src/isolation.ts` - added terminal/container readiness metadata, vocabulary, default fail-closed metadata, and guard helpers.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript compilation completed with no errors after isolation contract changes.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* Command/check: targeted inspection of `packages/protocol/src/isolation.ts`
  * Result: PASS - default terminal readiness reports `pty_unavailable`; default container readiness reports runtime/image/browser/mount/network fallback metadata without raw paths or output.
  * Evidence: `defaultRuntimeReadinessForExecutor` adds terminal/container metadata only for relevant executor families.
* UI product-surface check: N/A - shared isolation contracts changed no rendered UI.
* UI craft check: N/A - shared isolation contracts changed no rendered UI.

**BQC Fixes**:

* Contract alignment: added shared isolation readiness enums and default metadata so server diagnostics and web rows can consume one declared contract (`packages/protocol/src/isolation.ts`).

***

### Task T005 - Add protocol tests

**Started**: 2026-06-26 19:07 **Completed**: 2026-06-26 19:12 **Duration**: 5 minutes

**Notes**:

* Added command-center parser tests for terminal probes, terminal sessions, bounded output windows, safe execution attachments, container probes, isolated spawn previews, and blocked raw-field rejection.
* Updated isolation tests for PTY/runtime/image/browser/mount/network/cleanup readiness metadata and guard helpers.
* Confirmed the supported focused Vitest invocation passes.

**Files Changed**:

* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - added terminal/container parser and raw-field rejection coverage.
* `packages/protocol/tests/isolation.test.ts` - updated isolation readiness vocabulary and default metadata coverage.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm test -- orchestrationCommandCenter isolation --runInBand`
  * Result: FAIL - Vitest rejected unsupported option `--runInBand`.
  * Evidence: command exited 1 before test execution with `CACError: Unknown option --runInBand`.
* Command/check: `npm test -- orchestrationCommandCenter isolation`
  * Result: PASS - focused protocol/isolation tests passed.
  * Evidence: 3 files passed, 22 tests passed, including `packages/protocol/tests/orchestrationCommandCenter.test.ts`, `packages/protocol/tests/isolation.test.ts`, and matching `apps/server/tests/isolationDiagnostics.test.ts`.
* UI product-surface check: N/A - protocol tests changed no rendered UI.
* UI craft check: N/A - protocol tests changed no rendered UI.

**BQC Fixes**:

* Trust boundary enforcement: added tests proving terminal/container protocol parsers reject blocked raw fields such as `stdout`, `terminalOutput`, `rawLog`, and `command` (`packages/protocol/tests/orchestrationCommandCenter.test.ts`).
* Contract alignment: added parser fixtures for shared terminal/container DTOs consumed by server and web layers (`packages/protocol/tests/orchestrationCommandCenter.test.ts`, `packages/protocol/tests/isolation.test.ts`).

***

### Task T006 - Add optional PTY adapter dependency metadata

**Started**: 2026-06-26 19:12 **Completed**: 2026-06-26 19:16 **Duration**: 4 minutes

**Notes**:

* Added `node-pty` as an optional dependency of `@factionos/server` so native PTY support is package-managed but not required for installation or runtime readiness.
* Updated the workspace lockfile with `node-pty@1.1.0` and its optional `node-addon-api` dependency metadata.
* Kept runtime fail-closed behavior for the next manager task; this task only establishes package metadata.

**Files Changed**:

* `apps/server/package.json` - added optional `node-pty` dependency.
* `package-lock.json` - recorded optional PTY dependency metadata.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm view node-pty version`
  * Result: PASS - npm registry returned `1.1.0`.
  * Evidence: selected `^1.1.0` for optional dependency metadata.
* Command/check: `npm install node-pty@^1.1.0 --workspace apps/server --save-optional --package-lock-only`
  * Result: PASS with environment warnings - lockfile-only dependency update completed and npm audit reported 0 vulnerabilities.
  * Evidence: npm exited 0; warnings noted current shell Node `v24.14.0` is below repo engine `>=26.2.0` and `node-pty` install scripts are not currently listed in root allow-scripts.
* Command/check: `rg -n "node-pty|optionalDependencies" apps/server/package.json package-lock.json | head -40`
  * Result: PASS - package and lockfile contain `node-pty` optional dependency entries.
  * Evidence: `apps/server/package.json` lists `"node-pty": "^1.1.0"` under `optionalDependencies`; `package-lock.json` includes `node_modules/node-pty`.
* UI product-surface check: N/A - package metadata changed no rendered UI.
* UI craft check: N/A - package metadata changed no rendered UI.

**BQC Fixes**:

* External dependency resilience: kept `node-pty` optional so missing native PTY support can be reported as unavailable by the runtime manager instead of breaking server startup (`apps/server/package.json`).

***

### Task T007 - Create terminal session manager

**Started**: 2026-06-26 19:16 **Completed**: 2026-06-26 19:29 **Duration**: 13 minutes

**Notes**:

* Created a server-owned `TerminalSessionManager` with injectable PTY adapter support and dynamic optional `node-pty` loading.
* Added PTY probing, safe command labels, bounded scoped output windows, timeout cleanup, stdin forwarding, kill, restart, execution attachment metadata, idempotency handling, and shutdown disposal.
* Kept raw command text private to manager state for execution/restart only; public session records expose command labels and scoped output windows.

**Files Changed**:

* `apps/server/src/managers/terminalSessionManager.ts` - new PTY lifecycle manager with fail-closed probing and cleanup behavior.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/managers/terminalSessionManager.ts`
  * Result: PASS - manager exposes injectable adapter boundary, dynamic optional PTY loading, timeout kill path, kill/restart/input methods, output caps, and `dispose()`.
  * Evidence: public sessions store `commandLabel`, `cwdLabel`, `shellLabel`, bounded `output`, status metadata, and optional execution attachment ids; raw `commandText` stays private in `TerminalRecord`.
* UI product-surface check: N/A - server manager changed no rendered UI.
* UI craft check: N/A - server manager changed no rendered UI.

**BQC Fixes**:

* Resource cleanup: added timer clearing, process kill on timeout/operator kill/restart/shutdown, and completion resolution in the terminal lifecycle manager (`apps/server/src/managers/terminalSessionManager.ts`).
* Duplicate action prevention: added session and input idempotency maps for terminal start/input operations (`apps/server/src/managers/terminalSessionManager.ts`).
* External dependency resilience: dynamic optional `node-pty` loading returns `pty_unavailable` instead of throwing during server startup (`apps/server/src/managers/terminalSessionManager.ts`).

***

### Task T008 - Create container runtime manager

**Started**: 2026-06-26 19:29 **Completed**: 2026-06-26 19:42 **Duration**: 13 minutes

**Notes**:

* Created a server-owned `ContainerRuntimeManager` with injectable bounded command runner support.
* Added Docker and Apple Containers version probes, Docker image inspection, browser dependency posture, auth/worktree mount labels, loopback-only network posture, cleanup posture, isolated spawn preview, bounded Docker run execution, timeout handling, and idempotency.
* Kept probe responses and execution results label-based; raw command output is not returned in broad records.

**Files Changed**:

* `apps/server/src/managers/containerRuntimeManager.ts` - new container runtime probe and isolated spawn manager.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/managers/containerRuntimeManager.ts`
  * Result: PASS - manager exposes injectable command runner, Docker/Apple probes, image/browser/mount/network/cleanup posture, isolated spawn preview/run, timeout cancellation, and duplicate-trigger protection.
  * Evidence: public probe results use labels and fallback reasons; execution attachments include container run ids, runtime, cleanup posture, and fallback reason only.
* UI product-surface check: N/A - server manager changed no rendered UI.
* UI craft check: N/A - server manager changed no rendered UI.

**BQC Fixes**:

* External dependency resilience: Docker and Apple Containers absence resolves to structured unavailable/failed probe states instead of startup failure (`apps/server/src/managers/containerRuntimeManager.ts`).
* Duplicate action prevention: isolated spawn runs use in-flight locks and idempotency result replay (`apps/server/src/managers/containerRuntimeManager.ts`).
* Error information boundaries: probe and run summaries return safe labels/fallback reasons, not raw command output or absolute paths (`apps/server/src/managers/containerRuntimeManager.ts`).

***

### Task T009 - Create terminal/container request parsers

**Started**: 2026-06-26 19:42 **Completed**: 2026-06-26 19:49 **Duration**: 7 minutes

**Notes**:

* Added route parsers for terminal command preview/run, terminal input, terminal control actions, container probes, and isolated spawn preview/run.
* Allowed request-scoped `commandText` and `inputText` while rejecting broad raw payload fields such as `command`, `stdout`, `stderr`, `terminalOutput`, and `rawLog`.
* Added safe route id, idempotency, timeout, runtime, image label, hero id, and hero label validation.

**Files Changed**:

* `apps/server/src/lib/terminalContainerValidation.ts` - new terminal/container route validation module.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/lib/terminalContainerValidation.ts`
  * Result: PASS - parsers call `rejectCommandCenterBlockedPayloadFields`, bound request-scoped text lengths, validate safe ids, and restrict container runtimes to `docker` or `apple_containers`.
  * Evidence: invalid raw-field payloads map to compact `invalid_request` responses before reaching managers.
* UI product-surface check: N/A - server validation changed no rendered UI.
* UI craft check: N/A - server validation changed no rendered UI.

**BQC Fixes**:

* Trust boundary enforcement: added explicit validation for every terminal/container route body and route id (`apps/server/src/lib/terminalContainerValidation.ts`).
* Error information boundaries: validation returns compact field errors and does not echo command text, input text, image details, or raw payload content (`apps/server/src/lib/terminalContainerValidation.ts`).

***

### Task T010 - Wire terminal and container executor registry entries

**Started**: 2026-06-26 19:49 **Completed**: 2026-06-26 20:01 **Duration**: 12 minutes

**Notes**:

* Replaced terminal/container placeholder executor entries with manager-backed entries.
* Added terminal PTY and container runtime probe integration for capability refresh.
* Added guarded execution integration that returns safe execution attachments for terminal/container runs and stays unavailable when required runtime/request-scoped data is missing.
* Preserved local authorization boundary by keeping execution behind the existing guarded-action approval route and executor registry evaluation flow.

**Files Changed**:

* `apps/server/src/managers/executorRegistry.ts` - added terminal/container manager dependencies, probe entries, execute entries, and attachment propagation.
* `apps/server/src/managers/orchestrationCommandCenter.ts` - persisted safe execution attachments on command-center execution runs and WebSocket event entries.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors after registry and command-center changes.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/managers/executorRegistry.ts`
  * Result: PASS - terminal/container entries probe managers, require guarded approval, map ready/unavailable/failed states, and attach safe metadata without broad output.
  * Evidence: terminal entry returns `missing_reference` when no request-scoped command text is present; container entry runs through `ContainerRuntimeManager` after probes pass.
* Command/check: targeted inspection of `apps/server/src/managers/orchestrationCommandCenter.ts`
  * Result: PASS - execution run creation, completion, and event snapshots preserve optional `attachment` metadata.
  * Evidence: event entries clone attachments and do not include raw command bodies or terminal output.
* UI product-surface check: N/A - server registry changed no rendered UI.
* UI craft check: N/A - server registry changed no rendered UI.

**BQC Fixes**:

* Trust boundary enforcement: terminal/container executor execution remains behind guarded-action approval and capability evaluation (`apps/server/src/routes/guardedActions.ts`, `apps/server/src/managers/executorRegistry.ts`).
* Contract alignment: executor run results now carry the protocol-defined safe attachment shape into command-center storage and WebSocket snapshots (`apps/server/src/managers/executorRegistry.ts`, `apps/server/src/managers/orchestrationCommandCenter.ts`).

***

### Task T011 - Add terminal and container REST routes

**Started**: 2026-06-26 20:01 **Completed**: 2026-06-26 20:11 **Duration**: 10 minutes

**Notes**:

* Added scoped terminal snapshot, session detail, preview, run, input, kill, and restart routes.
* Added container probe, isolated spawn preview, and isolated spawn run routes.
* Added duplicate-trigger prevention through route-level in-flight locks.
* Added command-center execution records for direct terminal/container route runs using safe attachment metadata.

**Files Changed**:

* `apps/server/src/routes/terminalContainers.ts` - new local REST route module for terminal and container capabilities.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/routes/terminalContainers.ts`
  * Result: PASS - routes parse request bodies, enforce route locks, call managers, save safe execution records, and emit command-center execution updates.
  * Evidence: preview responses expose labels only; terminal output remains scoped to terminal session responses; command-center execution records receive attachments without raw command text.
* UI product-surface check: N/A - server routes changed no rendered UI.
* UI craft check: N/A - server routes changed no rendered UI.

**BQC Fixes**:

* Duplicate action prevention: added per-route in-flight keys for terminal run/input/kill/restart, container probes, isolated spawn preview, and isolated spawn run (`apps/server/src/routes/terminalContainers.ts`).
* Failure path completeness: route manager failures return compact status-specific JSON instead of falling through or throwing (`apps/server/src/routes/terminalContainers.ts`).

***

### Task T012 - Wire managers, routes, registry dependencies, and shutdown disposal

**Started**: 2026-06-26 20:11 **Completed**: 2026-06-26 20:15 **Duration**: 4 minutes

**Notes**:

* Instantiated terminal and container managers in server startup.
* Passed the managers into the default executor registry so capability probes and guarded executions use the same runtime instances as REST routes.
* Mounted terminal/container routes under both root local API and `/api` prefixes through the existing auth, CORS, rate-limit, and JSON middleware stack.
* Added terminal resource disposal to server shutdown.

**Files Changed**:

* `apps/server/src/server.ts` - wired terminal/container managers, routes, executor registry dependencies, and shutdown disposal.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/server.ts`
  * Result: PASS - terminal/container routes are mounted after command-center routes under inherited local middleware and terminal sessions are disposed during shutdown.
  * Evidence: default executor registry receives `gitWorkbench`, `terminalSessions`, and `containerRuntime`.
* UI product-surface check: N/A - server startup wiring changed no rendered UI.
* UI craft check: N/A - server startup wiring changed no rendered UI.

**BQC Fixes**:

* Resource cleanup: server shutdown now disposes terminal sessions before command-center disposal (`apps/server/src/server.ts`).
* Contract alignment: REST routes and executor registry share the same terminal/container manager instances (`apps/server/src/server.ts`).

***

### Task T013 - Store terminal/container execution updates and safe snapshots

**Started**: 2026-06-26 20:15 **Completed**: 2026-06-26 20:20 **Duration**: 5 minutes

**Notes**:

* Stored terminal/container execution attachment metadata on command-center execution runs created through guarded execution and direct terminal/container routes.
* Preserved safe WebSocket snapshots by including attachment metadata only, not raw command bodies or terminal output.
* Added a top-level safe `attachment` field to execution detail route responses for terminal/container consumers.
* Capability refresh data flows through the existing executor probe endpoints because the default registry now probes terminal/container managers.

**Files Changed**:

* `apps/server/src/managers/orchestrationCommandCenter.ts` - persisted safe execution attachments and included them in execution event entries.
* `apps/server/src/routes/commandCenter.ts` - exposed safe attachment metadata on execution detail responses.
* `apps/server/src/routes/terminalContainers.ts` - created direct terminal/container execution records with safe attachments.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/managers/orchestrationCommandCenter.ts`
  * Result: PASS - run creation, completion, and event snapshots preserve optional `attachment`.
  * Evidence: execution events clone safe attachment metadata and do not include output lines.
* Command/check: targeted inspection of `apps/server/src/routes/commandCenter.ts`
  * Result: PASS - execution detail route returns `item`, safe `attachment`, and `generatedAt`.
  * Evidence: raw command and terminal output remain absent from command-center detail payloads.
* UI product-surface check: N/A - server command-center storage changed no rendered UI.
* UI craft check: N/A - server command-center storage changed no rendered UI.

**BQC Fixes**:

* Contract alignment: execution attachments now flow from protocol to registry results, manager storage, REST detail responses, and WebSocket event snapshots (`packages/protocol/src/orchestrationCommandCenter.ts`, `apps/server/src/managers/orchestrationCommandCenter.ts`, `apps/server/src/routes/commandCenter.ts`).
* Error information boundaries: broad execution snapshots carry only safe attachment metadata and result summaries (`apps/server/src/managers/orchestrationCommandCenter.ts`).

***

### Task T014 - Update isolation diagnostics

**Started**: 2026-06-26 20:20 **Completed**: 2026-06-26 20:30 **Duration**: 10 minutes

**Notes**:

* Extended isolation diagnostics to merge optional terminal and container runtime probe metadata into executor capability rows.
* Updated the diagnostics route to gather terminal/container probes read-only before building the snapshot.
* Preserved compact labels and fallback reasons; diagnostics do not execute terminal commands or container actions.

**Files Changed**:

* `packages/protocol/src/isolation.ts` - made `unavailableReason` optional for ready executor capabilities.
* `apps/server/src/lib/isolationDiagnostics.ts` - mapped terminal/container probes into isolation executor readiness metadata.
* `apps/server/src/routes/diagnostics.ts` - added read-only terminal/container probe collection for isolation diagnostics.
* `apps/server/src/server.ts` - passed terminal/container managers into diagnostics routes.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* Command/check: `npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript compilation completed with no errors.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: targeted inspection of `apps/server/src/lib/isolationDiagnostics.ts` and `apps/server/src/routes/diagnostics.ts`
  * Result: PASS - diagnostics merge probe metadata and remain read-only.
  * Evidence: route calls `probe()` only; no terminal command, input, kill, restart, or isolated spawn route is invoked from diagnostics.
* UI product-surface check: N/A - server diagnostics changed no rendered UI.
* UI craft check: N/A - server diagnostics changed no rendered UI.

**BQC Fixes**:

* Failure path completeness: missing or unavailable terminal/container probes resolve to structured fallback metadata in diagnostics (`apps/server/src/lib/isolationDiagnostics.ts`).
* Error information boundaries: diagnostics emit labels, readiness states, and fallback reasons only, not command bodies, output, or paths (`apps/server/src/lib/isolationDiagnostics.ts`).

***

### Task T015 - Add server tests for terminal/container runtime paths

**Started**: 2026-06-26 19:19 **Completed**: 2026-06-26 19:21 **Duration**: 2 minutes

**Notes**:

* Added and verified focused server coverage for the PTY lifecycle, bounded output, kill/idempotency behavior, container runtime probes, isolated spawn run results, terminal/container REST routes, executor registry integration, and isolation diagnostics.
* Made diagnostics route tests deterministic by injecting an unavailable container runtime probe instead of relying on host Docker state.
* Fixed terminal output truncation state so once a bounded output window trims content, the public `truncated` flag remains true.

**Files Changed**:

* `apps/server/tests/terminalSessionManager.test.ts` - PTY lifecycle, bounded output, safe attachment, kill, and idempotent replay coverage.
* `apps/server/tests/containerRuntimeManager.test.ts` - unavailable and ready container runtime probe/run coverage.
* `apps/server/tests/terminalContainerRoutes.test.ts` - terminal/container REST route coverage with safe command-center attachments.
* `apps/server/tests/executorRegistry.test.ts` - manager-backed terminal/container executor entry coverage.
* `apps/server/tests/isolationDiagnostics.test.ts` - deterministic terminal/container diagnostics metadata coverage.
* `apps/server/src/managers/terminalSessionManager.ts` - preserved truncation state after bounded output trimming.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm test -- terminalSessionManager containerRuntimeManager terminalContainerRoutes executorRegistry commandCenterRoutes isolationDiagnostics`
  * Result: PASS - 6 test files and 27 tests passed.
  * Evidence: Vitest completed `terminalSessionManager`, `containerRuntimeManager`, `terminalContainerRoutes`, `executorRegistry`, `commandCenterRoutes`, and `isolationDiagnostics` with exit code 0.
* Command/check: targeted inspection of test assertions for raw data leakage.
  * Result: PASS - tests assert command-center responses and attachments do not include raw secret command payloads.
  * Evidence: terminal route and manager tests use secret-bearing commands and assert serialized public payloads omit the secret value.
* UI product-surface check: N/A - server tests and server manager bug fix changed no rendered UI.
* UI craft check: N/A - server tests and server manager bug fix changed no rendered UI.

**BQC Fixes**:

* Failure path completeness: diagnostics tests now inject unavailable container probes so host runtime availability cannot flip expected unavailable posture (`apps/server/tests/isolationDiagnostics.test.ts`).
* Error information boundaries: focused route and manager tests assert safe attachments and no raw command echo (`apps/server/tests/terminalContainerRoutes.test.ts`, `apps/server/tests/terminalSessionManager.test.ts`).
* Output boundary correctness: terminal bounded output now tracks truncation as durable state after trimming (`apps/server/src/managers/terminalSessionManager.ts`).

***

### Task T016 - Add web API clients for terminal and container routes

**Started**: 2026-06-26 19:21 **Completed**: 2026-06-26 19:26 **Duration**: 5 minutes

**Notes**:

* Added terminal API client helpers for snapshot, session detail, preview, run, input, kill, and restart routes.
* Added container API client helpers for probe, isolated spawn preview, and isolated spawn run routes.
* Added strict response validators backed by shared protocol parsers for terminal probes, terminal sessions, terminal previews, container probes, isolated spawn previews, execution runs, and safe execution attachments.
* Updated command-center execution detail response typing and validation to include optional safe attachment metadata.

**Files Changed**:

* `apps/web/src/lib/orchestrationApi.ts` - added terminal/container request inputs, response DTOs, request helpers, body builders, duplicate mutation keys, and validators.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript project compilation completed with no errors.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: targeted inspection of `apps/web/src/lib/orchestrationApi.ts`
  * Result: PASS - new functions use existing local API URL resolution, auth headers, timeout handling, HTTP error mapping, and duplicate in-flight mutation guard.
  * Evidence: preview/run/input/kill/restart/probe/spawn mutations call `requestCommandCenterMutation`; GET snapshot/detail/probe calls use `requestJson`.
* UI product-surface check: N/A - API client changes changed no rendered UI.
* UI craft check: N/A - API client changes changed no rendered UI.

**BQC Fixes**:

* Contract alignment: web response validators now parse terminal/container DTOs through shared protocol parsers before state can consume them (`apps/web/src/lib/orchestrationApi.ts`).
* Error information boundaries: execution-detail validation accepts only safe attachment metadata and rejects blocked raw payload fields through protocol parsers (`apps/web/src/lib/orchestrationApi.ts`).
* Duplicate action prevention: terminal/container mutating calls use scoped mutation keys with existing in-flight guard (`apps/web/src/lib/orchestrationApi.ts`).

***

### Task T017 - Add terminal/container view models and action helpers

**Started**: 2026-06-26 19:26 **Completed**: 2026-06-26 19:30 **Duration**: 4 minutes

**Notes**:

* Added shared command-center UI copy helpers for runtime readiness, mount readiness, network profiles, cleanup posture, and terminal/container fallback reasons.
* Added terminal probe, terminal session, bounded output, isolated spawn preview, and isolation capability row view models.
* Added terminal and container action availability helpers for connected, in-flight, selected session, running-session, preview, probe, and ready-runtime states.

**Files Changed**:

* `apps/web/src/lib/commandCenterUi.ts` - added shared terminal/container status and fallback copy helpers.
* `apps/web/src/lib/terminalContainers.ts` - added pure terminal/container view-model builders and action availability helpers.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript project compilation completed with no errors.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: targeted inspection of `apps/web/src/lib/terminalContainers.ts`
  * Result: PASS - helpers sanitize labels, summarize bounded output, surface fallback reasons, and avoid raw command text storage in view models.
  * Evidence: terminal session views use `commandLabel`, scoped output windows, redacted labels, and metadata-only runtime rows.
* UI product-surface check: N/A - pure helper changes changed no rendered UI.
* UI craft check: N/A - pure helper changes changed no rendered UI.

**BQC Fixes**:

* Product clarity: terminal/container copy now maps each readiness and fallback state to user-facing labels and descriptions (`apps/web/src/lib/commandCenterUi.ts`).
* Error information boundaries: view-model builders apply existing command-center label redaction to terminal output lines and runtime labels (`apps/web/src/lib/terminalContainers.ts`).
* Action-state completeness: terminal/container controls now have deterministic disabled reasons for offline, in-flight, unselected, non-running, and runtime-not-ready states (`apps/web/src/lib/terminalContainers.ts`).

***

### Task T018 - Create scoped terminal runtime drawer

**Started**: 2026-06-26 19:30 **Completed**: 2026-06-26 19:33 **Duration**: 3 minutes

**Notes**:

* Added a right-side terminal runtime drawer with focus-on-open, Escape close, backdrop close, command draft, input draft, session selection, bounded output display, and lifecycle controls.
* Rendered loading, empty, error, offline, selected-session, and no-output states without blank panels.
* Wired button disabled states through terminal action availability helpers and surfaced disabled reasons through button titles.

**Files Changed**:

* `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx` - added terminal runtime drawer UI.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript project compilation completed with no errors.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: targeted inspection of `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`
  * Result: PASS - drawer handles focus, Escape, backdrop close, scoped output, input, run, stop, restart, refresh, loading, empty, error, and offline states.
  * Evidence: component uses portal drawer pattern, local draft state, `StatusPill`, `EmptyState`, and terminal action availability helpers.
* UI product-surface check: PASS - drawer is the first screen of the terminal workflow, not a landing or explanatory surface.
* UI craft check: PASS - controls have stable sizing, visible disabled states, bounded output scroll area, and no nested page-section cards outside the drawer context.

**BQC Fixes**:

* Accessibility: drawer focuses the close control on open and closes on Escape (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`).
* Action-state completeness: run/input/stop/restart controls use deterministic disabled states and reason titles (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`).
* Output boundary: terminal output renders from scoped bounded output windows only (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`).

***

### Task T019 - Create isolation capability panel

**Started**: 2026-06-26 19:33 **Completed**: 2026-06-26 19:34 **Duration**: 1 minute

**Notes**:

* Added an isolation runtime panel for terminal PTY, Docker, Apple Containers, image, browser dependencies, auth mount, worktree mount, network profile, cleanup, provider runtime, and fallback states.
* Added probe, isolated preview, and isolated run buttons with offline and duplicate in-flight disabled states.
* Added isolated spawn preview rendering with requirements and safe runtime metadata.

**Files Changed**:

* `apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx` - added isolation capability panel UI.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript project compilation completed with no errors.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: targeted inspection of `apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`
  * Result: PASS - panel renders readiness rows, fallback labels, preview requirements, and action disabled states.
  * Evidence: component uses `buildIsolationCapabilityRows`, `buildIsolatedSpawnPreviewView`, and `containerRuntimeActionAvailability`.
* UI product-surface check: PASS - panel exposes actual local runtime readiness rather than marketing copy.
* UI craft check: PASS - rows use compact repeated cards with status pills, bounded metadata chips, and no one-note palette additions.

**BQC Fixes**:

* Product clarity: all terminal/container isolation subchecks have visible row labels, status, summaries, and fallback chips (`apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`).
* Action-state completeness: probe/preview/run controls use connected and in-flight guards with reason titles (`apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`).
* Error information boundaries: panel renders safe labels and requirements only, using helper redaction before display (`apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`, `apps/web/src/lib/terminalContainers.ts`).

***

### Task T020 - Wire terminal/container state into Orchestration

**Started**: 2026-06-26 19:34 **Completed**: 2026-06-26 19:42 **Duration**: 8 minutes

**Notes**:

* Added terminal and container runtime substate to the command-center store, including selected terminal session revalidation after snapshot refreshes.
* Hydrated terminal snapshots and container probes during command-center load while keeping runtime-specific errors separate from broader command-center errors.
* Wired terminal run/input/kill/restart and container probe/isolated preview/isolated run handlers through existing in-flight mutation keys and toast reporting.
* Added the isolation capability panel to the Executors tab and exposed the terminal runtime drawer from the executor family panel.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added terminal/container runtime state, hydrate actions, selection cleanup, and loading/error actions.
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - added runtime hydration, handlers, toasts, and terminal drawer rendering.
* `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - threaded runtime props and callbacks into panes.
* `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - rendered isolation capability rows in the Executors tab.
* `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx` - added terminal drawer control and terminal session count.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript project compilation completed with no errors.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: targeted inspection of Orchestration wiring.
  * Result: PASS - runtime snapshots hydrate store state, selected terminal sessions remain valid, and runtime actions use existing mutation/toast patterns.
  * Evidence: shell handlers call terminal/container API clients with scoped mutation keys and update store runtime substate before refreshing command-center execution records.
* UI product-surface check: PASS - Executors tab now shows isolation readiness rows and a direct terminal drawer control.
* UI craft check: PASS - terminal drawer is a drawer, isolation readiness uses repeated compact rows, and executor family layout remains dense and scannable.

**BQC Fixes**:

* State consistency: selected terminal session id is cleared or replaced when refreshed sessions no longer contain it (`apps/web/src/store/useGameStore.ts`).
* Duplicate action prevention: runtime actions use store-level in-flight keys aligned with API client mutation keys (`apps/web/src/components/orchestration/OrchestrationShell.tsx`).
* Offline states: terminal drawer and isolation panel receive connected state and render disabled controls/offline pills (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`, `apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx`).

***

### Task T021 - Add web tests for terminal/container UI and clients

**Started**: 2026-06-26 19:42 **Completed**: 2026-06-26 19:51 **Duration**: 9 minutes

**Notes**:

* Added API client tests for terminal snapshots, terminal preview/run/input, container probes, isolated spawn preview/run, malformed raw responses, safe attachments, and duplicate mutation keys.
* Added store tests for terminal snapshot hydration, selected terminal revalidation, container probe hydration, and isolated spawn preview hydration.
* Added pure helper tests for terminal output redaction, isolation row summaries, fallback labels, and action availability.
* Added component tests for the terminal drawer, isolation capability panel, executor terminal control, and integrated OrchestrationPanel terminal/container wiring.

**Files Changed**:

* `apps/web/tests/orchestrationApi.test.ts` - terminal/container API client coverage.
* `apps/web/tests/commandCenterStore.test.ts` - runtime store hydration coverage.
* `apps/web/tests/terminalContainers.test.ts` - pure helper coverage.
* `apps/web/tests/TerminalRuntimeDrawer.test.tsx` - terminal drawer coverage.
* `apps/web/tests/IsolationCapabilityPanel.test.tsx` - isolation panel coverage.
* `apps/web/tests/ExecutorFamiliesPanel.test.tsx` - updated executor family panel coverage for terminal drawer control.
* `apps/web/tests/OrchestrationPanel.test.tsx` - updated API mocks and integrated runtime wiring coverage.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm test -- orchestrationApi commandCenterStore terminalContainers TerminalRuntimeDrawer IsolationCapabilityPanel ExecutorFamiliesPanel OrchestrationPanel`
  * Result: PASS - 7 web test files and 60 tests passed.
  * Evidence: Vitest completed `orchestrationApi`, `commandCenterStore`, `terminalContainers`, `TerminalRuntimeDrawer`, `IsolationCapabilityPanel`, `ExecutorFamiliesPanel`, and `OrchestrationPanel` with exit code 0.
* Command/check: targeted inspection of new web tests.
  * Result: PASS - tests cover malformed payload rejection, no raw secret/path rendering, duplicate actions, offline states, and integrated shell callbacks.
  * Evidence: terminal output tests assert redacted secret/path content; API tests assert malformed `stdout` response is rejected as `bad_response`.
* UI product-surface check: PASS - component tests assert visible runtime controls and state copy.
* UI craft check: PASS - tests verify focus, dialog role, disabled controls, empty/loading/error/offline states, and compact readiness rows.

**BQC Fixes**:

* Regression coverage: terminal/container API, store, helper, component, and integrated shell paths now have focused tests (`apps/web/tests/*terminal*`, `apps/web/tests/IsolationCapabilityPanel.test.tsx`, `apps/web/tests/OrchestrationPanel.test.tsx`).
* Error information boundaries: tests assert raw terminal output fields are rejected and unsafe output text is redacted before display (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/terminalContainers.test.ts`, `apps/web/tests/TerminalRuntimeDrawer.test.tsx`).
* Duplicate action prevention: API and component tests exercise duplicate in-flight mutation keys and disabled action states (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/IsolationCapabilityPanel.test.tsx`).

***

### Task T022 - Update terminal/container API, server, web, and isolation documentation

**Started**: 2026-06-26 19:53 **Completed**: 2026-06-26 19:59 **Duration**: 6 minutes

**Notes**:

* Documented terminal snapshot/detail/preview/run/input/kill/restart routes and the scoped bounded output boundary.
* Documented container probe and isolated-spawn preview/run routes with Docker and Apple Containers readiness, image/browser/auth/worktree/network/provider/cleanup posture, and structured unavailable states.
* Updated server and isolation docs to describe optional `node-pty` fail-closed behavior, manager-owned runtime gates, safe execution attachments, and remaining no-claim boundaries for remote, hosted, Worker, tunnel, and broad Docker execution.
* Updated web docs to describe the Executors tab isolation capability panel, scoped terminal runtime drawer, duplicate in-flight controls, selected terminal revalidation, and drawer-only terminal output rendering.

**Files Changed**:

* `docs/api/README_api.md` - added terminal/container routes, diagnostics wording, WebSocket registry posture, safe attachment boundary, and optional PTY/container probe behavior.
* `docs/isolation-and-sandbox.md` - updated the isolation threat model for Session 12 terminal/container capabilities and remaining unavailable operation boundaries.
* `apps/server/README_server.md` - updated route summary, diagnostics behavior, executor registry readiness, Session 12 terminal/container route behavior, and Phase 06 closeout boundaries.
* `apps/web/README_web.md` - updated Command Center UX/product-surface requirements and local orchestration boundary for terminal/container controls.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `rg -n 'non-executing isolation|unavailable file/git/terminal|test or future entries|container routes remain deferred|execute terminal, git, Docker|does not run terminal|start arbitrary containers|node-pty|bounded terminal output|terminal/container readiness|isolated-spawn' docs/api/README_api.md docs/isolation-and-sandbox.md apps/server/README_server.md apps/web/README_web.md`
  * Result: PASS - scan returned only expected updated terms and no stale all-unavailable terminal/container claims.
  * Evidence: matches were limited to intentional Session 12 documentation, no-claim boundaries, and route names.
* Command/check: `git diff --check -- docs/api/README_api.md docs/isolation-and-sandbox.md apps/server/README_server.md apps/web/README_web.md`
  * Result: PASS - no whitespace errors in documentation changes.
  * Evidence: command exited 0.
* UI product-surface check: N/A - documentation changes changed no rendered UI.
* UI craft check: N/A - documentation changes changed no rendered UI.

**BQC Fixes**:

* Contract alignment: docs now match the shipped terminal/container route set, safe attachment contracts, and diagnostics posture.
* Error information boundaries: docs explicitly preserve drawer-only bounded terminal output and metadata-only broad route/WebSocket/diagnostics boundaries.
* Product surface discipline: web docs now state that terminal output appears only in the scoped drawer and that broad Executor surfaces remain metadata-only.

***

### Task T023 - Run focused terminal/container protocol, server, and web tests

**Started**: 2026-06-26 20:02 **Completed**: 2026-06-26 20:02 **Duration**: 1 minute

**Notes**:

* Ran the focused cross-package Vitest pattern set covering protocol contracts, server managers, server routes, executor registry, diagnostics, web API helpers, store, view models, drawer, isolation panel, executor families, and OrchestrationPanel integration.
* Confirmed terminal/container focused coverage passes after documentation updates and final web/server wiring.

**Files Changed**:

* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded focused test evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm test -- orchestrationCommandCenter isolation terminalSessionManager containerRuntimeManager terminalContainerRoutes executorRegistry commandCenterRoutes isolationDiagnostics orchestrationApi commandCenterStore terminalContainers TerminalRuntimeDrawer IsolationCapabilityPanel ExecutorFamiliesPanel OrchestrationPanel`
  * Result: PASS - 15 test files and 106 tests passed.
  * Evidence: Vitest completed protocol, server, and web focused suites with exit code 0.
* UI product-surface check: N/A - test command changed no rendered UI.
* UI craft check: N/A - test command changed no rendered UI.

**BQC Fixes**:

* Regression coverage: focused protocol/server/web suites passed for terminal/container contracts, lifecycle managers, guarded execution, diagnostics, API validation, store normalization, and component states.

***

### Task T024 - Run workspace validation and ASCII/LF checks

**Started**: 2026-06-26 20:03 **Completed**: 2026-06-26 20:05 **Duration**: 2 minutes

**Notes**:

* Ran the exact workspace validation command required by the task. The first pass reached `format:check` and failed on Biome formatting in new/changed implementation and test files.
* Ran `npm run format`, which formatted 717 files and fixed 15 files.
* Reran the exact workspace validation command. Typecheck, format, and lint passed; full test suite initially exposed one stale WebSocket assertion expecting the old terminal placeholder unavailable reason.
* Updated `apps/server/tests/websocket.test.ts` to expect the new terminal PTY fail-closed `pty_unavailable` reason, reran `npm test -- websocket`, then reran the full workspace validation command successfully.
* Ran repository whitespace, ASCII, and CRLF checks across changed and untracked files.

**Files Changed**:

* `apps/server/src/lib/isolationDiagnostics.ts` - Biome formatting.
* `apps/server/src/lib/terminalContainerValidation.ts` - Biome formatting.
* `apps/server/src/managers/containerRuntimeManager.ts` - Biome formatting.
* `apps/server/src/managers/executorRegistry.ts` - Biome formatting.
* `apps/server/src/managers/terminalSessionManager.ts` - Biome formatting.
* `apps/server/src/routes/terminalContainers.ts` - Biome formatting.
* `apps/server/src/server.ts` - Biome formatting.
* `apps/server/tests/isolationDiagnostics.test.ts` - Biome formatting.
* `apps/server/tests/terminalContainerRoutes.test.ts` - Biome formatting.
* `apps/server/tests/websocket.test.ts` - updated stale terminal unavailable reason expectation from `not_implemented` to `pty_unavailable`.
* `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx` - Biome formatting.
* `apps/web/src/lib/orchestrationApi.ts` - Biome formatting.
* `apps/web/src/lib/terminalContainers.ts` - Biome formatting.
* `apps/web/tests/TerminalRuntimeDrawer.test.tsx` - Biome formatting.
* `apps/web/tests/terminalContainers.test.ts` - Biome formatting.
* `packages/protocol/src/orchestrationCommandCenter.ts` - Biome formatting.
* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded validation evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status updated after evidence was recorded.

**Verification**:

* Command/check: `npm run typecheck --workspaces --if-present && npm run format:check && npm run lint && npm test`
  * Result: PASS after format and assertion repair - all workspace typechecks passed, `format:check` checked 717 files, `lint` checked 719 files, and full Vitest passed.
  * Evidence: final Vitest summary reported 245 test files passed, 1 skipped; 2879 tests passed, 1 skipped.
* Command/check: `npm run format`
  * Result: PASS - Biome formatted 717 files and fixed 15 files.
  * Evidence: command exited 0 before the final validation rerun.
* Command/check: `npm test -- websocket`
  * Result: PASS - 2 WebSocket-related test files and 16 tests passed after the stale assertion repair.
  * Evidence: Vitest completed `apps/server/tests/websocket.test.ts` and `apps/server/tests/suggestionWebsocket.test.ts` with exit code 0.
* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors.
  * Evidence: command exited 0 with no output.
* Command/check: `git ls-files -m -o --exclude-standard -z | xargs -0 grep -nI -P '[^\x00-\x7F]' || true`
  * Result: PASS - no non-ASCII characters found in changed/untracked files.
  * Evidence: command exited 0 with no output.
* Command/check: `git ls-files -m -o --exclude-standard -z | xargs -0 grep -nI $'\r' || true`
  * Result: PASS - no CRLF carriage returns found in changed/untracked files.
  * Evidence: command exited 0 with no output.
* UI product-surface check: N/A - validation and test assertion repair changed no rendered UI.
* UI craft check: N/A - validation and test assertion repair changed no rendered UI.

**BQC Fixes**:

* Regression coverage: full workspace validation now covers the new terminal/container code paths plus the broader existing suite.
* Contract alignment: WebSocket guarded-action test expectation now matches the shipped terminal PTY unavailable reason (`apps/server/tests/websocket.test.ts`).
* Formatting consistency: Biome formatting applied to new/changed implementation and test files before final validation.

***

### Task T025 - Record final implementation notes and handoff evidence

**Started**: 2026-06-26 20:05 **Completed**: 2026-06-26 20:06 **Duration**: 1 minute

**Notes**:

* Recorded the final implementation, command, validation, runtime-verification, and fail-closed state evidence for the `creview` and `validate` handoff.
* Confirmed the final change inventory spans protocol contracts/tests, server managers/routes/diagnostics/tests, web API/store/components/tests, documentation, optional PTY dependency metadata, and spec-system bookkeeping.
* Runtime verification evidence is covered by focused and full Vitest suites for missing PTY, PTY lifecycle, bounded output, kill/restart/timeout cleanup, missing container runtime, container probe fallback, isolated-spawn unavailable/preview/success paths, executor registry guarded execution, diagnostics read-only posture, web parser/store normalization, offline/error states, and scoped drawer output.
* Remaining fail-closed unavailable states for handoff: missing or failing `node-pty` returns `pty_unavailable`; absent or failed Docker/Apple Containers returns `runtime_unavailable`; unavailable image state returns `image_unavailable`; missing browser dependencies return `browser_dependency_missing`; missing auth/worktree mounts return `mount_unavailable`; blocked network posture returns `network_unavailable`; cleanup failures use `cleanup_unavailable`; remote, hosted, Worker, push, channel, webhook, and broad Docker/tunnel paths remain unavailable, separate-surface, or policy-blocked.

**Files Changed**:

* `.spec_system/specs/phase19-session12-terminal-and-containers/implementation-notes.md` - recorded final handoff evidence.
* `.spec_system/specs/phase19-session12-terminal-and-containers/tasks.md` - task status and completion checklist updated after evidence was recorded.

**Verification**:

* Command/check: `git status --short`
  * Result: PASS - final worktree contains expected protocol, server, web, docs, package-lock, and spec-system changes for this session.
  * Evidence: status listed the new Session 12 spec directory, terminal/container server files, web terminal/container files, focused tests, docs, and related modified files.
* Command/check: `git diff --stat`
  * Result: PASS - tracked diff summary reviewed.
  * Evidence: stat reported 30 tracked files changed with 4150 insertions and 134 deletions, excluding newly untracked session-created files.
* Command/check: `rg -n 'pty_unavailable|runtime_unavailable|dependency_unavailable|browser_dependency_missing|image_unavailable|mount_unavailable|network_unavailable|timeout' apps/server/tests/terminalSessionManager.test.ts apps/server/tests/containerRuntimeManager.test.ts apps/server/tests/terminalContainerRoutes.test.ts apps/server/tests/isolationDiagnostics.test.ts apps/server/tests/executorRegistry.test.ts packages/protocol/tests/isolation.test.ts packages/protocol/tests/orchestrationCommandCenter.test.ts apps/web/tests/IsolationCapabilityPanel.test.tsx apps/web/tests/TerminalRuntimeDrawer.test.tsx apps/web/tests/terminalContainers.test.ts`
  * Result: PASS - targeted runtime fallback evidence is present in protocol, server, and web tests.
  * Evidence: matches covered `pty_unavailable`, `runtime_unavailable`, `browser_dependency_missing`, `mount_unavailable`, and timeout/fallback assertions.
* Command/check: review of Task T024 validation evidence
  * Result: PASS - final validation command, format check, lint, full tests, ASCII check, CRLF check, and `git diff --check` all passed.
  * Evidence: T024 log records exact commands and final pass results.
* UI product-surface check: N/A - handoff notes changed no rendered UI.
* UI craft check: N/A - handoff notes changed no rendered UI.

**BQC Fixes**:

* Handoff completeness: final notes name the tested runtime scenarios and remaining unavailable states so `creview` and `validate` can audit the correct behavior.

***


---

# 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/implementation-notes.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.