> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_12_terminal_and_containers.md).

# Session 12: Terminal And Containers

**Session ID**: `phase19-session12-terminal-and-containers` **Packages**: apps/server, apps/web **Status**: Complete **Estimated Tasks**: 25 **Estimated Duration**: 2-4 hours **Completed**: 2026-06-26

***

## Objective

Add terminal PTY execution and isolated runtime support as owned executor capabilities.

***

## Scope

### In Scope (MVP)

* Terminal capability probing, session count, cwd, shell, status, command preview, env handling, output caps, timeout, input, kill, restart, exit state, and result attachment
* Container and isolation diagnostics for Docker, Apple Containers, image state, browser dependencies, auth mount, worktree mount, network/port profile, provider/runtime availability, cleanup, and fallback reason
* Isolated spawn as a guarded lifecycle action when probes pass
* Scoped terminal drawer and isolation capability UI
* Tests for PTY lifecycle, bounded output, kill/restart, container probes, isolated spawn preview, and cleanup events

### Out of Scope

* Remote access tunnel creation
* Broad terminal output rendering outside scoped details

***

## Prerequisites

* [x] Sessions 06, 07, and 09 complete
* [x] Current terminal, process, container, and isolation constraints inspected

***

## Deliverables

1. Terminal session manager and guarded terminal execution wiring
2. Container runtime manager and isolation diagnostics
3. Terminal drawer and isolation capability rows
4. Tests for terminal and container lifecycle behavior

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 12: Terminal And Containers
* Implementation Targets 12 and 15 for terminal PTY capability and isolation runtime planning
* Balls-To-The-Wall Track B `terminalSessionManager` and `containerRuntimeManager` routes
* Execution Family Order items 6 and 7 for terminal and container isolation

Key EXAMPLES links:

* [Terminal guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L125-L136)
* [node-pty stack note](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L35-L44)
* [xterm.js stack note](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L100-L116)
* [Terminal events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L148-L149)
* [Dockerfile.isolated](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/Dockerfile.isolated#L1-L70)
* [Isolated heroes guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L49-L60)

***

## Success Criteria

* [x] The panel can request, approve, run, observe, kill, and record terminal commands when PTY support is ready
* [x] Isolation readiness shows fallback reasons and image/runtime state
* [x] Isolated hero spawn is gated by tested capability probes
* [x] Terminal summaries show status, exit code, duration, and owner only


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_12_terminal_and_containers.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.