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

# Session 02: Queue Terminal Execution

**Session ID**: `phase20-session02-queue-terminal-execution` **Packages**: `packages/protocol`, `apps/server`, `apps/web` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Deliver create -> dispatch -> execute -> observe -> recover for queue tasks that run terminal commands.

***

## Scope

### In Scope (MVP)

* Add the minimal protocol-owned executable task contract needed for terminal queue tasks, event redaction, and execution-run links.
* Add enough `TaskExecutionCoordinator` behavior to preview and dispatch a terminal queue entry through `TerminalSessionManager`.
* Change queue dispatch to create a command-center execution run, run the terminal command, update queue state, and emit execution and queue events.
* Preserve the old metadata-only transition only behind truthful naming such as `Start tracking`.
* Surface terminal execution state, result summary, unavailable guidance, retry, kill, and terminal-drawer links in the Command Center UI.
* Update terminal dependency diagnostics and `factionos doctor` output for normal-install readiness when required by the slice.

### Out of Scope

* Git, file, campaign DAG, container, and managed-agent execution.
* Broad display of terminal command text or output in queue rows or WebSocket summaries.

***

## Prerequisites

* [ ] Session 01 completed and validated.
* [ ] Terminal execution acceptance test defined before implementation starts.

***

## Deliverables

1. Terminal executable payload types, coordinator path, queue route behavior, UI result surface, and diagnostic updates.
2. Protocol, server, web, and browser tests for successful execution and failure recovery.

***

## Success Criteria

* [ ] A queue terminal task runs through dispatch, creates an execution run, records terminal attachment detail, completes or fails the queue row, and shows the result in the UI.
* [ ] `pty_unavailable`, timeout, running-command kill, and duplicate dispatch produce truthful states and recoverable results.
* [ ] Route tests prove both `task_queue_update` and `command_center_execution_update` events are emitted.
* [ ] Browser e2e proves the visible queue-to-terminal drawer flow.
* [ ] Focused protocol, server, web, e2e, and `git diff --check` commands for this slice pass.

***

## Folded Source Detail

### User Outcome

An operator creates a queue task with a terminal command, clicks dispatch, the command runs locally, the queue row shows the final result, and the terminal drawer shows scoped output or a truthful unavailable state.

### Current Source Map

* Queue contract: `packages/protocol/src/taskQueue.ts` has no executable payload, execution run link, approval policy, timeout, rollback metadata, or result summary.
* Queue behavior: `apps/server/src/managers/taskQueue.ts` and `apps/server/src/routes/orchestration.ts` currently transition `queued|blocked -> in_progress` and emit `task_queue_update`.
* Execution run model: `packages/protocol/src/orchestrationCommandCenter.ts` and `apps/server/src/managers/orchestrationCommandCenter.ts` already represent queued, executing, executed, failed, and unavailable runs.
* Terminal executor: `apps/server/src/managers/terminalSessionManager.ts`, `apps/server/src/routes/terminalContainers.ts`, and `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx` already support direct terminal run, kill, restart, scoped attachments, and UI detail behind PTY readiness.
* Installed baseline: `apps/server/package.json` declares `node-pty` as a normal dependency; live evidence showed `TerminalSessionManager.probe()` returning `executor_ready`, but queue and campaign still do not route to it.

### Required Changes

* Add terminal executable payload support to queue create, preview, and update requests.
* Add `POST /task-queue/:id/preview-dispatch` if the UI needs non-mutating preflight before dispatch.
* Change `POST /task-queue/:id/dispatch` to call `TaskExecutionCoordinator.dispatchQueueEntry`.
* Keep the old state-only transition only behind a renamed route or action such as `POST /task-queue/:id/start-tracking`.
* The coordinator must call `TerminalSessionManager.probe()`, create a `CommandCenterExecutionRun` with target `queue_item`, run through `TerminalSessionManager.start()` for interactive runs or `runAndWait()` for one-shot dispatch, store terminal attachment detail, update queue state, and emit both queue and execution events.
* Web queue rows must show executor family, run state, result summary, and a link to the execution run or terminal session.
* Terminal command text and output must stay in scoped detail views, not broad queue rows, WebSocket lists, exports, diagnostics, or notifications.

### Recovery Paths

* `pty_unavailable`: queue becomes `unavailable`, execution run records the unavailable reason, and UI shows repair guidance.
* Timeout: execution run and queue become failed, terminal attachment remains inspectable, and retry is enabled.
* Running command: user can kill through terminal session control.
* Duplicate dispatch: idempotent response returns the existing execution run.

### Acceptance Tests From Findings

* New `apps/server/tests/taskExecutionCoordinator.test.ts` with injected fake PTY proves create -> dispatch -> execute -> completed queue -> execution detail -> terminal attachment.
* Server route test proves `/task-queue/:id/dispatch` creates an execution run and emits both `task_queue_update` and `command_center_execution_update`.
* Failure test proves `pty_unavailable` does not leave the row stuck `in_progress`.
* Web component/store tests prove result summary and terminal link render.
* Browser e2e proves the visible Command Center flow from queue row to terminal drawer.


---

# 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_20/session_02_queue_terminal_execution.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.