> 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-session02-queue-terminal-execution/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase20-session02-queue-terminal-execution` **Package**: null **Started**: 2026-06-28 10:56 **Last Updated**: 2026-06-28 11:55

***

## Session Progress

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

***

### Task T001 - Define terminal execution acceptance fixture and fake PTY behavior

**Started**: 2026-06-28 10:56 **Completed**: 2026-06-28 10:58 **Duration**: 2 minutes

**Notes**:

* Added the initial coordinator acceptance test file with reusable fake PTY adapter/process modes for success, unavailable, timeout, kill, and duplicate idempotency behavior.
* Verified the fake timeout path models the manager-owned timeout completion instead of resolving early from a process exit event.

**Files Changed**:

* `apps/server/tests/taskExecutionCoordinator.test.ts` - Added fake PTY fixtures and initial acceptance tests for terminal runtime behavior needed by queue dispatch.

**Verification**:

* Command/check: `npx vitest run apps/server/tests/taskExecutionCoordinator.test.ts`
  * Result: PASS - The focused fixture tests passed.
  * Evidence: Vitest reported 1 test file passed and 2 tests passed.
* UI product-surface check: N/A - Server test fixture only; no user-facing UI changed.
* UI craft check: N/A - Server test fixture only; no rendered UI changed.

**BQC Fixes**:

* Duplicate action prevention: Fixture covers duplicate terminal idempotency-key reuse so coordinator tests can assert one terminal run per queue dispatch key (`apps/server/tests/taskExecutionCoordinator.test.ts`).
* External dependency resilience: Fixture covers PTY unavailable and timeout paths without depending on native `node-pty` (`apps/server/tests/taskExecutionCoordinator.test.ts`).

***

### Task T002 - Verify Session 01 evidence and current terminal route behavior

**Started**: 2026-06-28 10:58 **Completed**: 2026-06-28 10:59 **Duration**: 1 minute

**Notes**:

* Verified Phase 20 Session 01 validation report records a PASS result, 18/18 tasks complete, full test pass evidence, and product-surface checks for truthful tracking copy.
* Inspected current direct terminal routes and confirmed scoped terminal preview/run/input/kill/restart behavior already records compact command-center execution metadata.

**Files Changed**:

* `.spec_system/specs/phase20-session02-queue-terminal-execution/implementation-notes.md` - Recorded setup verification evidence.
* `.spec_system/specs/phase20-session02-queue-terminal-execution/tasks.md` - Marked T002 complete after evidence was recorded.

**Verification**:

* Command/check: `rg -n "Tasks Complete|Full tests|UI Product Surface" .spec_system/specs/phase20-session01-truthful-capability-baseline/validation.md`
  * Result: PASS - Session 01 validation evidence is present.
  * Evidence: Report shows tasks complete PASS, full tests PASS with 2983/2983 passed and 1 skipped, and UI product-surface PASS.
* Command/check: `sed -n '1,320p' apps/server/src/routes/terminalContainers.ts`
  * Result: PASS - Direct terminal routes use `TerminalSessionManager`, save command-center execution records, emit execution updates, and keep raw command scoped to route/session handling.
  * Evidence: Route code provides snapshot, session detail, preview, run, input, kill, and restart endpoints with bounded session/execution responses.
* Command/check: `npx vitest run apps/server/tests/terminalContainerRoutes.test.ts`
  * Result: PASS - Direct terminal/container route baseline tests passed.
  * Evidence: Vitest reported 1 test file passed and 3 tests passed.
* UI product-surface check: N/A - Evidence/read-only setup task; no user-facing UI changed.
* UI craft check: N/A - Evidence/read-only setup task; no rendered UI changed.

***

### Task T003 - Add terminal executable queue protocol contract

**Started**: 2026-06-28 10:59 **Completed**: 2026-06-28 11:02 **Duration**: 3 minutes

**Notes**:

* Added protocol-owned terminal executable payload types, safe queue execution summary fields, dispatch/control request types, and mutation execution links.
* Added parser helpers for scoped executable payloads and safe execution summaries. The parsers allow request-scoped `commandText` only inside the executable payload and reject raw output or broad payload fields.

**Files Changed**:

* `packages/protocol/src/taskQueue.ts` - Added terminal executable queue payloads, safe execution summaries, response links, and validation helpers.

**Verification**:

* Command/check: `npm --workspace @factionos/protocol run typecheck`
  * Result: PASS - Protocol package compiled with the new shared queue types.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* UI product-surface check: N/A - Shared protocol contract only; no user-facing UI changed.
* UI craft check: N/A - Shared protocol contract only; no rendered UI changed.

**BQC Fixes**:

* Trust boundary enforcement: Added parser helpers that reject blocked raw fields such as `stdout`, `terminalOutput`, `token`, and `prompt` from executable and summary payloads while allowing scoped terminal command input only where the route explicitly accepts it (`packages/protocol/src/taskQueue.ts`).
* Contract alignment: Queue entries, event entries, create/update requests, dispatch requests, and mutation responses now share one safe execution summary/link contract (`packages/protocol/src/taskQueue.ts`).

***

### Task T004 - Extend protocol tests for executable queue payloads and safe events

**Started**: 2026-06-28 11:02 **Completed**: 2026-06-28 11:04 **Duration**: 2 minutes

**Notes**:

* Added protocol tests for terminal executable queue payload parsing, safe execution summaries on compact queue update events, and queue-targeted command-center execution runs.
* Added raw field rejection checks for broad terminal output fields in executable and execution summary payloads.

**Files Changed**:

* `packages/protocol/tests/orchestration.test.ts` - Added executable queue contract, safe event, queue-targeted execution run, and privacy tests.

**Verification**:

* Command/check: `npx vitest run packages/protocol/tests/orchestration.test.ts`
  * Result: PASS - Focused protocol orchestration contract tests passed.
  * Evidence: Vitest reported 1 test file passed and 13 tests passed.
* UI product-surface check: N/A - Protocol tests only; no user-facing UI changed.
* UI craft check: N/A - Protocol tests only; no rendered UI changed.

**BQC Fixes**:

* Contract alignment: Protocol tests now assert queue create/dispatch/mutation response typing, event execution summary shape, and queue-targeted command-center execution runs (`packages/protocol/tests/orchestration.test.ts`).
* Error information boundaries: Tests assert raw output strings are not copied into validation details when blocked raw fields are rejected (`packages/protocol/tests/orchestration.test.ts`).

***

### Task T005 - Add task-queue terminal executable validators

**Started**: 2026-06-28 11:05 **Completed**: 2026-06-28 11:07 **Duration**: 2 minutes

**Notes**:

* Extended task-queue create and update validators to accept the protocol-owned executable payload.
* Added task-queue preview and dispatch body validators with compact validation errors for malformed executable payloads and blocked raw fields.

**Files Changed**:

* `apps/server/src/lib/orchestrationValidation.ts` - Added executable payload parsing for create/update/preview/dispatch task-queue inputs.

**Verification**:

* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled with the new task-queue validator types.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server request validation only; no user-facing UI changed.
* UI craft check: N/A - Server request validation only; no rendered UI changed.

**BQC Fixes**:

* Trust boundary enforcement: Terminal executable payloads now cross task-queue route boundaries through a protocol parser instead of unchecked object fields (`apps/server/src/lib/orchestrationValidation.ts`).
* Error information boundaries: Invalid executable bodies return compact field-level validation details without echoing raw command output content (`apps/server/src/lib/orchestrationValidation.ts`).

***

### Task T006 - Add private executable storage and safe queue execution summaries

**Started**: 2026-06-28 11:07 **Completed**: 2026-06-28 11:11 **Duration**: 4 minutes

**Notes**:

* Added private executable payload storage keyed by queue entry id; raw terminal commands are no longer part of public queue entries or event entries.
* Added safe execution summary creation, cloning, event exposure, and execution link responses for queue execution updates.
* Added `recordExecution` so the coordinator can move queue rows through execution state changes with revision, stale update, and idempotency-key protection.

**Files Changed**:

* `apps/server/src/managers/taskQueue.ts` - Added private executable payload accessors, safe execution summary storage, event summaries, and execution update mutation support.

**Verification**:

* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled with the new queue manager storage and mutation methods.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server manager storage only; no user-facing UI changed.
* UI craft check: N/A - Server manager storage only; no rendered UI changed.

**BQC Fixes**:

* Error information boundaries: Raw executable payloads are stored in a private manager map and are not cloned into public `TaskQueueEntry` or `TaskQueueEventEntry` values (`apps/server/src/managers/taskQueue.ts`).
* Duplicate action prevention: Execution updates use queue mutation locks and idempotency-key tracking to return duplicate responses instead of racing duplicate state changes (`apps/server/src/managers/taskQueue.ts`).
* Contract alignment: Queue event entries now expose cloned safe execution summaries that match the protocol contract (`apps/server/src/managers/taskQueue.ts`).

***

### Task T007 - Create TaskExecutionCoordinator for terminal queue dispatch

**Started**: 2026-06-28 11:11 **Completed**: 2026-06-28 11:14 **Duration**: 3 minutes

**Notes**:

* Added `TaskExecutionCoordinator` as the server-owned boundary between task queue entries, terminal sessions, and command-center execution runs.
* Coordinator rejects metadata-only dispatches, probes PTY readiness, records queue-targeted command-center executions, dispatches terminal commands with terminal idempotency keys, records safe queue execution summaries, and reuses in-flight runs for duplicate triggers.
* Extended the focused coordinator test file from the T001 fixture into runtime coordinator coverage.

**Files Changed**:

* `apps/server/src/managers/taskExecutionCoordinator.ts` - Added terminal queue dispatch coordinator and safe mapping helpers.
* `apps/server/tests/taskExecutionCoordinator.test.ts` - Added coordinator success, unavailable, timeout, and duplicate in-flight dispatch tests.

**Verification**:

* Command/check: `npx vitest run apps/server/tests/taskExecutionCoordinator.test.ts`
  * Result: PASS - Focused coordinator tests passed.
  * Evidence: Vitest reported 1 test file passed and 5 tests passed.
* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled with the new coordinator and tests.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server coordinator and tests only; no user-facing UI changed.
* UI craft check: N/A - Server coordinator and tests only; no rendered UI changed.

**BQC Fixes**:

* Duplicate action prevention: In-flight dispatches are tracked by queue entry and return duplicate responses without spawning another terminal session (`apps/server/src/managers/taskExecutionCoordinator.ts`).
* Failure path completeness: PTY unavailable, timeout, killed/failed, and missing executable payload paths return explicit queue and execution states (`apps/server/src/managers/taskExecutionCoordinator.ts`).
* Error information boundaries: Coordinator responses expose safe command labels, execution links, and attachment metadata without raw command text or terminal output (`apps/server/src/managers/taskExecutionCoordinator.ts`, `apps/server/tests/taskExecutionCoordinator.test.ts`).

***

### Task T008 - Wire task-queue dispatch routes through the coordinator

**Started**: 2026-06-28 11:14 **Completed**: 2026-06-28 11:17 **Duration**: 3 minutes

**Notes**:

* Changed `/task-queue/:id/dispatch` to parse terminal dispatch inputs and call `TaskExecutionCoordinator`.
* Added `/task-queue/:id/start-tracking` for the previous metadata-only queue transition so non-executable queue rows keep truthful tracking behavior.
* Added route helpers to emit all queue and command-center execution changes returned by the coordinator without exposing internal change arrays in the REST response.

**Files Changed**:

* `apps/server/src/routes/orchestration.ts` - Routed terminal dispatch through the coordinator, added start-tracking, and emitted queue plus execution updates.

**Verification**:

* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled after route wiring and server injection were both present.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server route wiring only; no rendered UI changed.
* UI craft check: N/A - Server route wiring only; no rendered UI changed.

**BQC Fixes**:

* Contract alignment: Terminal dispatch now uses task-queue-specific dispatch validation and coordinator responses, while metadata-only tracking has a truthful route name (`apps/server/src/routes/orchestration.ts`).
* Failure path completeness: Missing executable payloads now fail through coordinator conflict responses instead of silently becoming metadata-only execution claims (`apps/server/src/routes/orchestration.ts`).

***

### Task T009 - Inject task execution coordinator from server runtime

**Started**: 2026-06-28 11:16 **Completed**: 2026-06-28 11:17 **Duration**: 1 minute

**Notes**:

* Instantiated `TaskExecutionCoordinator` in server startup with the existing task queue, command-center manager, and terminal session manager.
* Passed the coordinator and command-center manager into the orchestration router so dispatch routes can emit compact execution events.

**Files Changed**:

* `apps/server/src/server.ts` - Created and injected the task execution coordinator into orchestration routes.

**Verification**:

* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled with coordinator runtime injection.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server runtime wiring only; no rendered UI changed.
* UI craft check: N/A - Server runtime wiring only; no rendered UI changed.

**BQC Fixes**:

* Contract alignment: Server startup now wires the same terminal/session/queue/command-center instances used by direct terminal routes into queue terminal dispatch (`apps/server/src/server.ts`).

***

### Task T010 - Update server route and diagnostics tests

**Started**: 2026-06-28 11:17 **Completed**: 2026-06-28 11:20 **Duration**: 3 minutes

**Notes**:

* Added fake PTY route tests for terminal queue create/dispatch success, unavailable PTY dispatch, malformed executable validation, start-tracking compatibility, privacy, and dual queue/execution WebSocket frames.
* Added compact terminal queue execution diagnostics counters for ready, completed, unavailable, degraded, and linked terminal-session states.
* Added diagnostics tests for ready and unavailable terminal queue dispatch results without raw command/output leakage.

**Files Changed**:

* `apps/server/tests/orchestration.test.ts` - Added terminal queue dispatch route, WebSocket event, start-tracking, unavailable, and validation privacy coverage.
* `apps/server/src/lib/orchestrationDiagnostics.ts` - Added compact terminal queue execution counters.
* `apps/server/tests/orchestrationDiagnostics.test.ts` - Added terminal queue diagnostics coverage for ready and unavailable dispatch results.

**Verification**:

* Command/check: `npx vitest run apps/server/tests/orchestration.test.ts apps/server/tests/orchestrationDiagnostics.test.ts apps/server/tests/taskExecutionCoordinator.test.ts`
  * Result: PASS - Focused server route, diagnostics, and coordinator suites passed.
  * Evidence: Vitest reported 3 test files passed and 19 tests passed.
* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled after route and diagnostics test changes.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - Server tests and diagnostics only; no rendered UI changed.
* UI craft check: N/A - Server tests and diagnostics only; no rendered UI changed.

**BQC Fixes**:

* Failure path completeness: Route tests now cover missing executable, unavailable PTY, and invalid raw executable payload failures (`apps/server/tests/orchestration.test.ts`).
* Contract alignment: Diagnostics and route tests assert terminal queue execution summaries, command-center execution runs, and WebSocket frames agree on safe execution state (`apps/server/tests/orchestration.test.ts`, `apps/server/tests/orchestrationDiagnostics.test.ts`).
* Error information boundaries: Route and diagnostics tests assert raw command text and terminal output do not appear in broad responses, events, or diagnostics (`apps/server/tests/orchestration.test.ts`, `apps/server/tests/orchestrationDiagnostics.test.ts`).

***

### Task T011 - Add terminal executable queue API helpers and parsers

**Started**: 2026-06-28 11:20 **Completed**: 2026-06-28 11:23 **Duration**: 3 minutes

**Notes**:

* Extended web task-queue create/update/control inputs to carry protocol-owned executable payloads.
* Added `startTrackingTaskQueueEntry` for metadata-only queue rows while keeping `dispatchTaskQueueEntry` for executable terminal rows.
* Tightened queue snapshot and mutation response guards so broad queue responses reject raw terminal command/output fields and validate safe execution summaries.

**Files Changed**:

* `apps/web/src/lib/orchestrationApi.ts` - Added executable payload request fields, start-tracking helper, response execution-link parsing, and broad-response privacy guards.

**Verification**:

* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled with the new queue API helpers and guards.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - API helper layer only; no rendered UI changed.
* UI craft check: N/A - API helper layer only; no rendered UI changed.

**BQC Fixes**:

* Contract alignment: Web queue create/update/dispatch helpers now share the protocol executable payload and execution summary contracts (`apps/web/src/lib/orchestrationApi.ts`).
* Error information boundaries: Broad queue response guards reject `commandText`, `terminalOutput`, `stdout`, and `stderr` fields before hydrating app state (`apps/web/src/lib/orchestrationApi.ts`).

***

### Task T012 - Add safe queue terminal view models and action labels

**Started**: 2026-06-28 11:23 **Completed**: 2026-06-28 11:26 **Duration**: 3 minutes

**Notes**:

* Added safe queue execution view models with command label, execution state, redacted result summary, retryability, execution-run link, and terminal-session link metadata.
* Updated command-center queue action availability so terminal executable rows use dispatch/retry execution verbs, while metadata-only rows keep truthful start-tracking copy.

**Files Changed**:

* `apps/web/src/lib/orchestrationUi.ts` - Added `QueueExecutionView` and safe queue execution view-model builders.
* `apps/web/src/lib/commandCenterUi.ts` - Added entry-aware terminal dispatch/retry labels and metadata-only start-tracking labels.

**Verification**:

* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled with the new queue view models and action labels.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: PASS - Code inspection confirms normal queue actions show product-facing "Dispatch terminal", "Retry terminal", or "Start tracking" labels, with no debug/runtime scaffolding copy.
* UI craft check: PASS - View-model copy uses compact status labels and bounded summaries appropriate for the existing dense Command Center UI.

**BQC Fixes**:

* Product surface discipline: Metadata-only queue rows no longer share execution wording with terminal executable rows (`apps/web/src/lib/commandCenterUi.ts`).
* Error information boundaries: Queue execution view models redact command labels and result summaries and expose only safe execution/terminal ids (`apps/web/src/lib/orchestrationUi.ts`).

***

### Task T013 - Update queue UI and pane wiring for terminal task creation and links

**Started**: 2026-06-28 11:26 **Completed**: 2026-06-28 11:29 **Duration**: 3 minutes

**Notes**:

* Added terminal-mode queue creation controls with command and label inputs that send the protocol executable payload only when terminal mode is selected.
* Rendered safe queue execution summaries with status, result summary, execution-run link, and terminal-session link controls.
* Wired command-center panes and tabs so execution links open execution details, terminal links select the terminal session and open the terminal drawer, and metadata-only queue dispatches use start-tracking instead of terminal dispatch.

**Files Changed**:

* `apps/web/src/components/orchestration/QueueWorkbench.tsx` - Added terminal queue creation controls, execution summary display, and safe execution/terminal link buttons.
* `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - Routed queue execution links to execution detail selection and terminal session open callbacks.
* `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - Passed terminal-session open callbacks through the tab panel boundary.
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - Split terminal dispatch from metadata-only start-tracking and added linked terminal drawer opening.

**Verification**:

* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled with terminal queue creation, dispatch branching, and link wiring.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: PASS - Queue UI uses product-facing "Terminal", "Dispatch terminal", "Retry terminal", "Start tracking", "Run", and "Terminal" controls without exposing raw command output.
* UI craft check: PASS - Execution summaries render as compact row-level panels outside the row select button, preserving valid button nesting, focus behavior, and dense Command Center layout.

**BQC Fixes**:

* Duplicate action prevention: Terminal queue dispatch and metadata start-tracking now use distinct in-flight mutation keys so buttons disable independently (`apps/web/src/components/orchestration/OrchestrationShell.tsx`).
* Product surface discipline: Metadata-only queue rows keep "Start tracking" behavior while terminal rows use terminal dispatch/retry behavior (`apps/web/src/components/orchestration/OrchestrationShell.tsx`, `apps/web/src/components/orchestration/QueueWorkbench.tsx`).
* Contract alignment: Queue create requests now pass the shared executable payload from the UI through the existing web API helper (`apps/web/src/components/orchestration/QueueWorkbench.tsx`).

***

### Task T014 - Update store reconciliation for queue and execution WebSocket events

**Started**: 2026-06-28 11:29 **Completed**: 2026-06-28 11:33 **Duration**: 4 minutes

**Notes**:

* Added store helpers that clear command-center in-flight mutation keys by execution run id, queue target id, terminal session id, and terminal-run prefix when safe execution events arrive.
* Reconciled queue-targeted terminal execution events into existing queue rows with safe execution summaries, preserving existing command labels and avoiding raw command/output fields.
* Added terminal selection cleanup during execution-event reconciliation so stale selected terminal sessions are revalidated against the current terminal session list.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - Added queue/execution WebSocket reconciliation helpers, safe queue execution enrichment from command-center execution events, linked mutation-key cleanup, and terminal selection cleanup.

**Verification**:

* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled with the new store reconciliation helpers.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - Store reconciliation only; no rendered UI changed in this task.
* UI craft check: N/A - Store reconciliation only; no rendered UI changed in this task.

**BQC Fixes**:

* Duplicate action prevention: Queue-targeted execution events now clear linked queue dispatch/start-tracking keys and terminal-session action keys instead of relying only on queue events (`apps/web/src/store/useGameStore.ts`).
* Contract alignment: Queue rows are enriched from command-center execution events using only safe execution summary fields (`apps/web/src/store/useGameStore.ts`).

***

### Task T015 - Add web terminal queue tests

**Started**: 2026-06-28 11:33 **Completed**: 2026-06-28 11:39 **Duration**: 6 minutes

**Notes**:

* Added API tests for terminal executable create serialization, terminal dispatch route selection, metadata-only start-tracking route selection, safe execution link parsing, and broad raw-field rejection.
* Added queue view-model tests for terminal execution state, retryability, links, and redaction of path/secret-like text.
* Added integrated Command Center pane tests for terminal queue creation controls, retry dispatch copy, execution detail links, and terminal drawer links.
* Added terminal drawer output scoping tests for linked selected sessions.
* Added store event reconciliation tests for queue-targeted terminal execution events, linked in-flight cleanup, and stale terminal selection repair.

**Files Changed**:

* `apps/web/tests/orchestrationApi.test.ts` - Added terminal queue API create/dispatch/start-tracking/privacy coverage.
* `apps/web/tests/orchestrationUi.test.ts` - Added safe terminal queue execution view-model coverage.
* `apps/web/tests/CommandCenterPanes.test.tsx` - Added integrated terminal queue UI coverage and pane callback defaults.
* `apps/web/tests/TerminalRuntimeDrawer.test.tsx` - Added linked selected terminal-session output scoping coverage.
* `apps/web/tests/commandCenterStore.test.ts` - Added queue-targeted execution event reconciliation and mutation cleanup coverage.

**Verification**:

* Command/check: `npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/CommandCenterPanes.test.tsx apps/web/tests/TerminalRuntimeDrawer.test.tsx apps/web/tests/commandCenterStore.test.ts`
  * Result: PASS - Focused web terminal queue tests passed.
  * Evidence: Vitest reported 5 test files passed and 60 tests passed.
* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled after the web source and test changes.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: PASS - Tests assert terminal queue controls use product-facing copy and avoid raw command/output fields in broad rendered surfaces.
* UI craft check: PASS - Tests exercise accessible labels for terminal mode, execution links, retry actions, and linked terminal-session drawer selection.

**BQC Fixes**:

* Error information boundaries: Tests assert broad queue API responses reject raw terminal output fields and rendered surfaces do not expose `stdout`, `commandText`, or raw terminal output (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/CommandCenterPanes.test.tsx`).
* Duplicate action prevention: Store tests assert queue dispatch/start-tracking, execution, terminal input, and terminal run keys clear from linked execution events (`apps/web/tests/commandCenterStore.test.ts`).
* Contract alignment: API, UI, pane, drawer, and store tests now exercise the same safe terminal execution summary/link contract (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/orchestrationUi.test.ts`, `apps/web/tests/CommandCenterPanes.test.tsx`, `apps/web/tests/TerminalRuntimeDrawer.test.tsx`, `apps/web/tests/commandCenterStore.test.ts`).

***

### Task T016 - Add compact CLI terminal queue diagnostics

**Started**: 2026-06-28 11:39 **Completed**: 2026-06-28 11:42 **Duration**: 3 minutes

**Notes**:

* Added compact CLI preservation of `commandCenter.terminalQueue` readiness/result counters from orchestration diagnostics.
* Added terminal queue status to the one-line server diagnostics summary while keeping older/omitted server payloads compatible through empty defaults.
* Extended CLI diagnostics tests to assert terminal queue counters are preserved and raw command/output fields are dropped.

**Files Changed**:

* `apps/cli/src/lib/orchestrationDiagnostics.js` - Added compact command-center terminal queue diagnostics and summary text.
* `apps/cli/tests/orchestrationDiagnostics.test.js` - Added terminal queue diagnostics fixture, summary assertion, and privacy checks.

**Verification**:

* Command/check: `npx vitest run apps/cli/tests/orchestrationDiagnostics.test.js`
  * Result: PASS - Focused CLI diagnostics tests passed.
  * Evidence: Vitest reported 1 test file passed and 6 tests passed.
* UI product-surface check: N/A - CLI diagnostics only; no rendered UI changed.
* UI craft check: N/A - CLI diagnostics only; no rendered UI changed.

**BQC Fixes**:

* Error information boundaries: CLI diagnostics tests assert `commandText` and `terminalOutput` are not preserved in compact results (`apps/cli/tests/orchestrationDiagnostics.test.js`).
* Product surface discipline: CLI summary reports compact terminal queue readiness as `terminal queue <status>` without command text or output details (`apps/cli/src/lib/orchestrationDiagnostics.js`).

***

### Task T017 - Add browser e2e queue-to-terminal drawer coverage

**Started**: 2026-06-28 11:42 **Completed**: 2026-06-28 11:47 **Duration**: 5 minutes

**Notes**:

* Added a Playwright flow that dispatches a mocked terminal queue row from the Command Center campaigns tab, verifies the row updates to executed, opens the linked terminal drawer, and checks the scoped terminal output.
* Extended the command-center e2e API fixture with a terminal queue row, terminal dispatch mutation response, command-center execution run, and dispatch-aware terminal snapshot.
* Ran the new flow on desktop and mobile projects to cover the dense queue row and terminal drawer layouts.

**Files Changed**:

* `tests/e2e/orchestration-command-center.e2e.ts` - Added visible queue-to-terminal dispatch e2e and fixture helpers for terminal queue, execution run, and linked terminal session.

**Verification**:

* Command/check: `npx playwright test tests/e2e/orchestration-command-center.e2e.ts --project=app-desktop -g "dispatches a terminal queue row"`
  * Result: PASS - Desktop browser queue-to-terminal flow passed.
  * Evidence: Playwright reported 1 test passed for `app-desktop`.
* Command/check: `npx playwright test tests/e2e/orchestration-command-center.e2e.ts --project=app-mobile -g "dispatches a terminal queue row"`
  * Result: PASS - Mobile browser queue-to-terminal flow passed.
  * Evidence: Playwright reported 1 test passed for `app-mobile`.
* UI product-surface check: PASS - Browser guards and explicit assertions verify the flow avoids `commandText`, `stdout`, and unsafe broad text while showing product-facing terminal queue copy.
* UI craft check: PASS - The e2e verifies the queue row is visible, the terminal action is reachable, the completed row state is visible, and the linked terminal drawer renders on desktop and mobile.

**BQC Fixes**:

* Product surface discipline: Browser coverage now proves the visible queue-to-terminal path uses user-facing copy and scoped drawer output instead of raw broad command/output fields (`tests/e2e/orchestration-command-center.e2e.ts`).
* Contract alignment: The e2e fixture exercises the same queue mutation response, execution run link, and terminal snapshot link expected from the server implementation (`tests/e2e/orchestration-command-center.e2e.ts`).

***

### Task T018 - Update docs and run final focused checks

**Started**: 2026-06-28 11:47 **Completed**: 2026-06-28 11:55 **Duration**: 8 minutes

**Notes**:

* Updated concise API docs, detailed event/API contract docs, web cockpit docs, and CLI diagnostics docs for terminal executable queue dispatch, metadata-only start-tracking, safe event summaries, terminal drawer links, and compact terminal queue diagnostics.
* Ran final focused protocol, server, web, CLI, and browser checks plus `git diff --check` and ASCII/LF validation.
* A parallel desktop/mobile e2e attempt produced a shared-port startup race before the desktop test ran; the desktop e2e was rerun sequentially and passed. The mobile e2e from the same final attempt passed.

**Files Changed**:

* `docs/api/README_api.md` - Documented terminal executable queue create/update/dispatch, start-tracking, safe WebSocket summaries, diagnostics counters, and Phase 03 closeout wording.
* `docs/api/event-api-hook-contracts.md` - Documented terminal queue route/event contracts, execution-update pairing, and diagnostics posture.
* `apps/web/README_web.md` - Documented terminal executable queue UI behavior, retry, drawer links, and store reconciliation expectations.
* `apps/cli/README_cli.md` - Documented compact terminal queue diagnostics counters and privacy limits.
* `.spec_system/specs/phase20-session02-queue-terminal-execution/tasks.md` - Marked T018 and completion checklist complete.
* `.spec_system/specs/phase20-session02-queue-terminal-execution/implementation-notes.md` - Recorded final verification evidence.

**Verification**:

* Command/check: `npm --workspace @factionos/protocol run typecheck`
  * Result: PASS - Protocol TypeScript compiled.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* Command/check: `npm --workspace @factionos/server run typecheck`
  * Result: PASS - Server TypeScript compiled.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `npm --workspace @factionos/web run typecheck`
  * Result: PASS - Web TypeScript compiled.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: `npx vitest run packages/protocol/tests/orchestration.test.ts`
  * Result: PASS - Focused protocol tests passed.
  * Evidence: Vitest reported 1 test file passed and 13 tests passed.
* Command/check: `npx vitest run apps/server/tests/orchestration.test.ts apps/server/tests/orchestrationDiagnostics.test.ts apps/server/tests/taskExecutionCoordinator.test.ts`
  * Result: PASS - Focused server route, diagnostics, and coordinator tests passed.
  * Evidence: Vitest reported 3 test files passed and 19 tests passed.
* Command/check: `npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/CommandCenterPanes.test.tsx apps/web/tests/TerminalRuntimeDrawer.test.tsx apps/web/tests/commandCenterStore.test.ts`
  * Result: PASS - Focused web terminal queue tests passed.
  * Evidence: Vitest reported 5 test files passed and 60 tests passed.
* Command/check: `npx vitest run apps/cli/tests/orchestrationDiagnostics.test.js`
  * Result: PASS - Focused CLI diagnostics tests passed.
  * Evidence: Vitest reported 1 test file passed and 6 tests passed.
* Command/check: `npx playwright test tests/e2e/orchestration-command-center.e2e.ts --project=app-mobile -g "dispatches a terminal queue row"`
  * Result: PASS - Mobile browser queue-to-terminal flow passed.
  * Evidence: Playwright reported 1 test passed for `app-mobile`.
* Command/check: `npx playwright test tests/e2e/orchestration-command-center.e2e.ts --project=app-desktop -g "dispatches a terminal queue row"`
  * Result: PASS - Desktop browser queue-to-terminal flow passed after rerunning sequentially.
  * Evidence: Playwright reported 1 test passed for `app-desktop`.
* Command/check: `git diff --check`
  * Result: PASS - No whitespace errors.
  * Evidence: Command exited 0 with no output.
* Command/check: ASCII/LF validation over changed `.ts`, `.tsx`, `.js`, and `.md` files
  * Result: PASS - No CRLF or non-ASCII bytes found.
  * Evidence: Perl CRLF and non-ASCII scans exited 0 with no output.
* UI product-surface check: PASS - Docs, web tests, and browser e2e assert broad surfaces use safe terminal queue summaries, product-facing dispatch/retry/start-tracking copy, and no raw command/output leakage.
* UI craft check: PASS - Browser e2e passed desktop and mobile for visible queue dispatch, completed row state, and linked terminal drawer flow.

**BQC Fixes**:

* Error information boundaries: Final docs and checks preserve the rule that command text and terminal output stay out of broad rows, WebSocket snapshots, diagnostics, exports, replay, and docs examples (`docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`, `apps/cli/README_cli.md`, `apps/web/README_web.md`).
* Contract alignment: API docs, event docs, web docs, CLI docs, focused tests, and e2e now describe and verify one terminal queue execution contract (`docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`, `tests/e2e/orchestration-command-center.e2e.ts`).

***

## Task Log

### 2026-06-28 - Session Start

**Environment verified**:

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

**Verification**:

* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/analyze-project.sh --json`
  * Result: PASS - Current session resolved to `phase20-session02-queue-terminal-execution`; session directory exists with `spec.md` and `tasks.md`.
  * Evidence: Analyzer reported monorepo `true`, `Package: null`, and Phase 20 Session 02 as the current unfinished session.
* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env`
  * Result: PASS - Spec system, `jq`, `git`, and npm workspace manager are available.
  * Evidence: Prerequisite checker returned `"overall": "pass"` with no issues.

***


---

# 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-session02-queue-terminal-execution/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.