> 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-session09-container-dispatch-decision/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase20-session09-container-dispatch-decision` **Package**: null **Started**: 2026-06-28 21:20 **Last Updated**: 2026-06-28 22:05

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 23 / 23 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Task Log

### 2026-06-28 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed with `.spec_system/scripts/check-prereqs.sh --json --env` (overall pass)
* [x] Tools available with `.spec_system/scripts/check-prereqs.sh --json --tools "node,npm"` (node and npm present)
* [x] Directory structure ready for `.spec_system/specs/phase20-session09-container-dispatch-decision`
* [x] Cross-package session confirmed (`Package: null`)

**Notes**:

* `.nvmrc` pins Node 26.2.0 and npm 11.16.0. The login shell initially reported Node 24.14.0, but local `nvm` has Node 26.2.0 installed; implementation and verification commands that run project tooling will source `~/.nvm/nvm.sh` and use `.nvmrc`.
* Database checks are not applicable; `.spec_system/CONVENTIONS.md` lists database as not configured, and the session explicitly excludes database or persistence schema work.
* Behavioral Quality Checklist loaded because the session changes application code.

***

### Task T001 - Verify current container, queue, campaign, and web paths

**Started**: 2026-06-28 21:20 **Completed**: 2026-06-28 21:21 **Duration**: 1 minute

**Notes**:

* Verified `ContainerRuntimeManager` already owns direct container runtime probing, Docker image inspection, bounded `runIsolatedSpawn()`, timeout aborts, idempotency keys, in-flight protection, cleanup posture, unavailable results, and compact container attachments.
* Verified `TaskExecutionCoordinator` currently supports terminal, Git, and file queue execution paths only; no container dependency, queued run builder, dispatch method, or container queue summary exists yet.
* Verified route-level queue dispatch currently switches file -> Git -> terminal only, so a future `container` payload would incorrectly fall through without an explicit branch.
* Verified `PlanCampaignManager` stores shared `TaskQueueExecutablePayload` values and bridges campaign tasks to queue entries, but dispatch/readiness/clone behavior only recognizes file, Git, and terminal families today.
* Verified `QueueWorkbench` create modes are `tracking`, `terminal`, and `git`; it has no container create mode, image/runtime inputs, or container-specific in-flight key.

**Files Changed**:

* `.spec_system/specs/phase20-session09-container-dispatch-decision/implementation-notes.md` - recorded T001 source inspection evidence.
* `.spec_system/specs/phase20-session09-container-dispatch-decision/tasks.md` - marked T001 complete.

**Verification**:

* Command/check: `rg -n "class ContainerRuntimeManager|runIsolatedSpawn|probe|cleanup|timeout|image" apps/server/src/managers/containerRuntimeManager.ts`
  * Result: PASS - found existing runtime probe, isolated-spawn, timeout, cleanup, unavailable, and attachment behavior.
  * Evidence: inspected matched source ranges in `apps/server/src/managers/containerRuntimeManager.ts`.
* Command/check: `rg -n "class TaskExecutionCoordinator|dispatchTerminal|dispatchGit|dispatchFile|dispatch|executable|inFlight|revision|executionRun" apps/server/src/managers/taskExecutionCoordinator.ts`
  * Result: PASS - confirmed terminal/Git/file dispatch patterns and no container dispatch path.
  * Evidence: inspected constructor dependencies, dispatch methods, queued run builders, and queue summary helpers.
* Command/check: `rg -n "dispatchTerminal|dispatchGit|dispatchFile|executable.kind|queue.*dispatch|TaskExecutionCoordinator" apps/server/src/routes/orchestration.ts apps/server/src/server.ts apps/server/tests/orchestration.test.ts`
  * Result: PASS - confirmed route dispatch switch only covers file, Git, and terminal.
  * Evidence: source inspection found the route branch at `apps/server/src/routes/orchestration.ts`.
* Command/check: `rg -n "executable|dispatchQueueExecutable|executionReadinessForExecutable|TaskQueueExecutablePayload|queue" apps/server/src/managers/planCampaignManager.ts`
  * Result: PASS - confirmed campaign executable payload storage exists and family handling excludes container today.
  * Evidence: inspected queue bridge, readiness, and clone helper source ranges.
* Command/check: `rg -n "create|mode|executable|terminal|git|file|queue|dispatch|inFlight|offline|Campaign" apps/web/src/components/orchestration/QueueWorkbench.tsx`
  * Result: PASS - confirmed existing queue create UI has tracking, terminal, and Git modes only.
  * Evidence: inspected create mode state, payload construction, and action button in-flight guards.
* UI product-surface check: N/A - source inspection only; no user-facing behavior changed.
* UI craft check: N/A - source inspection only; no user-facing behavior changed.

**BQC Fixes**:

* None. T001 was verification-only.

***

### Task T002 - Add protocol acceptance coverage for container executable payloads and summaries

**Started**: 2026-06-28 21:21 **Completed**: 2026-06-28 21:27 **Duration**: 6 minutes

**Notes**:

* Added protocol acceptance tests for task-queue `container` executable payload parsing, `container_run` execution summaries, runtime metadata, cleanup posture, unavailable states, and blocked raw-field rejection.
* Updated existing queue contract tests that assert executable vocabulary and REST/event type compatibility so container support is covered consistently.

**Files Changed**:

* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - added required task-queue container executable and summary parser coverage.
* `packages/protocol/tests/taskQueue.test.ts` - added container payload/summary type and parser coverage.
* `packages/protocol/tests/orchestration.test.ts` - updated queue vocabulary and event summary coverage for compact container metadata.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts packages/protocol/tests/taskQueue.test.ts packages/protocol/tests/orchestration.test.ts`
  * Result: PASS - 3 files, 47 tests passed.
  * Evidence: Vitest reported `packages/protocol/tests/orchestrationCommandCenter.test.ts` 25 tests, `taskQueue.test.ts` 5 tests, and `orchestration.test.ts` 17 tests passed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript typecheck completed.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* UI product-surface check: N/A - protocol tests only.
* UI craft check: N/A - protocol tests only.

**BQC Fixes**:

* Contract alignment: added acceptance coverage for the new queue executable family and summary shape before server/web consumers use it.
* Error information boundaries: added blocked raw-field tests for Docker commands/output so broad queue surfaces reject unsafe data.

***

### Task T004 - Extend task queue protocol with container executable payloads and summaries

**Started**: 2026-06-28 21:21 **Completed**: 2026-06-28 21:27 **Duration**: 6 minutes

**Notes**:

* Added `container` to `TASK_QUEUE_EXECUTABLE_KIND_VALUES`, added `TaskQueueContainerExecutablePayload`, and included the container family/kind in queue execution summary types.
* Added parser support for safe optional `heroId`, `heroLabel`, `imageName`, `runtime`, `commandLabel`, `ownerId`, `idempotencyKey`, `executionRunId`, and `recoveryNote` fields.
* Added compact summary parsing for `container_run` with `containerRunId`, `runtime`, `cleanupPosture`, unavailable reason, retryability, and recovery note.
* Added explicit blocked raw-field checks for Docker/container command bodies, output, mounts, env, entrypoint, workspace paths, and image-inspect data.

**Files Changed**:

* `packages/protocol/src/taskQueue.ts` - implemented container executable and execution summary contracts.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts packages/protocol/tests/taskQueue.test.ts packages/protocol/tests/orchestration.test.ts`
  * Result: PASS - 47 focused protocol tests passed.
  * Evidence: Parser coverage accepts compact container metadata and rejects raw Docker/container fields.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript typecheck completed.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* UI product-surface check: N/A - protocol-only change.
* UI craft check: N/A - protocol-only change.

**BQC Fixes**:

* Trust boundary enforcement: container executable and summary inputs now pass through schema-like parser checks before crossing task-queue boundaries.
* Error information boundaries: raw Docker output, commands, mounts, env, and inspect payloads are rejected from broad task-queue payloads and summaries.

***

### Task T005 - Reuse command-center container runtime and cleanup parsers

**Started**: 2026-06-28 21:21 **Completed**: 2026-06-28 21:27 **Duration**: 6 minutes

**Notes**:

* Reused the existing exported `parseCommandCenterContainerRuntime()` and `parseCommandCenterCleanupPosture()` helpers from the command-center protocol module in task-queue validation.
* Did not broaden command-center attachment fields; task-queue summaries store only runtime enum, cleanup posture, ids, status, and recovery metadata.

**Files Changed**:

* `packages/protocol/src/taskQueue.ts` - imported and reused command-center runtime and cleanup parser helpers.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts packages/protocol/tests/taskQueue.test.ts packages/protocol/tests/orchestration.test.ts`
  * Result: PASS - focused protocol tests passed.
  * Evidence: Container runtime and cleanup parser coverage passed through task-queue summary cases.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript typecheck completed.
  * Evidence: Existing command-center exports resolved in `taskQueue.ts` with no type errors.
* UI product-surface check: N/A - protocol-only change.
* UI craft check: N/A - protocol-only change.

**BQC Fixes**:

* Contract alignment: reused command-center enum parsers rather than duplicating runtime/cleanup validation.

***

### Task T003 - Add server acceptance coverage for container dispatch

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Added focused coordinator coverage for container queue success, missing runtime, missing image, failed run, stale revision, duplicate in-flight prevention, campaign dispatch integration, and redaction.
* Added route-level create -> dispatch -> WebSocket evidence for compact queue and command-center execution updates.
* Added container runtime manager tests for missing image and timeout behavior without live Docker.

**Files Changed**:

* `apps/server/tests/taskExecutionCoordinator.container.test.ts` - new focused container coordinator and campaign dispatch coverage.
* `apps/server/tests/orchestration.test.ts` - route/WebSocket container queue dispatch privacy coverage.
* `apps/server/tests/containerRuntimeManager.test.ts` - missing-image and timeout coverage.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - 3 files, 24 tests passed.
  * Evidence: Vitest reported coordinator container 6 tests, orchestration routes 14 tests, and container runtime manager 4 tests passed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - server tests only.
* UI craft check: N/A - server tests only.

**BQC Fixes**:

* Duplicate action prevention: added in-flight dispatch coverage proving repeated container dispatch returns a duplicate response and starts only one run.
* Failure path completeness: added unavailable runtime/image and failed run coverage.
* Error information boundaries: route and coordinator tests assert raw Docker output, raw command text, paths, and tokens do not enter broad responses or events.

***

### Task T007 - Thread ContainerRuntimeManager into task execution coordinator construction

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Added an optional `containerRuntime` dependency to `TaskExecutionCoordinatorOptions`.
* Passed the existing server-owned `ContainerRuntimeManager` into the coordinator without changing direct terminal/container routes.

**Files Changed**:

* `apps/server/src/managers/taskExecutionCoordinator.ts` - accepted and stored the optional container runtime dependency.
* `apps/server/src/server.ts` - passed the existing `containerRuntime` manager into `TaskExecutionCoordinator`.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: coordinator construction compiled with the new dependency.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - focused server tests passed.
  * Evidence: route tests use server-provided container runtime while existing terminal/Git/file routes continue passing.
* UI product-surface check: N/A - server wiring only.
* UI craft check: N/A - server wiring only.

**BQC Fixes**:

* Contract alignment: reused the existing manager-owned runtime boundary instead of adding a side-channel Docker executor.

***

### Task T008 - Implement dispatchContainer in the coordinator

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Implemented `dispatchContainer()` with stale revision checks, queued/executing/completed execution-run transitions, queue in-progress/final transitions, duplicate in-flight protection, and compact queue summaries.
* Mapped `ContainerRuntimeManager.runIsolatedSpawn()` results to completed, unavailable, or blocked queue states with container attachments, runtime, cleanup posture, container run ids, failure codes, unavailable reasons, retryability, and recovery notes.
* Added command-center `container_run` queued run creation and safe label handling.

**Files Changed**:

* `apps/server/src/managers/taskExecutionCoordinator.ts` - added container dispatch, run result mapping, queue summary mapping, and safe container labels.
* `packages/protocol/src/orchestrationCommandCenter.ts` - extended plan-task readiness/summary types so campaign tasks can carry compact container summaries.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - focused server tests passed.
  * Evidence: success, unavailable runtime/image, failed run, stale revision, duplicate in-flight, route, and campaign coverage passed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: coordinator result mapping and protocol summary types compile.
* UI product-surface check: N/A - server-only behavior.
* UI craft check: N/A - server-only behavior.

**BQC Fixes**:

* Duplicate action prevention: dispatch lock prevents repeated queue container execution while a run is in flight.
* Failure path completeness: unavailable, failed, and setup-error outcomes produce explicit queue and execution summaries.
* Error information boundaries: queue summaries use only compact labels, ids, runtime, cleanup posture, and recovery metadata.

***

### Task T009 - Route queue container dispatch through the coordinator

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Updated the task-queue dispatch route switch so `executable.kind: "container"` calls `dispatchContainer()`.
* Preserved compact queue and command-center execution event emission through the existing coordinator update path.

**Files Changed**:

* `apps/server/src/routes/orchestration.ts` - added the container branch to queue dispatch routing.
* `apps/server/tests/orchestration.test.ts` - added route/WebSocket privacy coverage for container queue dispatch.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - focused server tests passed.
  * Evidence: route test created a container queue entry, dispatched it, and observed compact queue plus execution frames without raw Docker output.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: route switch compiled against coordinator APIs.
* UI product-surface check: N/A - API route only.
* UI craft check: N/A - API route only.

**BQC Fixes**:

* Contract alignment: route dispatch now aligns with the protocol `container` executable kind instead of falling through to terminal behavior.
* Error information boundaries: WebSocket assertions verify compact event payloads only.

***

### Task T010 - Extend campaign executable readiness and dispatch for container tasks

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Added container execution readiness labels and `container_run` kinds for campaign tasks.
* Updated campaign queue executable dispatch switching so container tasks use the shared coordinator path.
* Preserved queue/execution links, DAG outcome buckets, retryability, and compact task execution summaries.
* Extended command-center plan-task summary/readiness protocol types to allow compact container family/kind and metadata in campaign results.

**Files Changed**:

* `apps/server/src/managers/planCampaignManager.ts` - added container readiness, dispatch branch, clone handling, and redacted image-based labels.
* `packages/protocol/src/orchestrationCommandCenter.ts` - allowed compact container plan-task readiness and summary metadata.
* `apps/server/tests/taskExecutionCoordinator.container.test.ts` - covered approved campaign container dispatch through the queue bridge.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - focused server tests passed.
  * Evidence: campaign container dispatch test completed a campaign task with queue and execution links.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol TypeScript typecheck completed.
  * Evidence: command-center plan task summary/readiness container types compile.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: campaign manager compiles with container readiness and summaries.
* UI product-surface check: N/A - server/campaign state only.
* UI craft check: N/A - server/campaign state only.

**BQC Fixes**:

* Contract alignment: campaign task execution readiness, queue summaries, and command-center plan summaries now agree on container family/kind.
* Failure path completeness: unavailable/failed container queue outcomes flow into campaign blocked/failed buckets through existing DAG outcome logic.

***

### Task T011 - Harden container manager missing-image and timeout summaries

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Preserved `image_unavailable` as the fallback reason when runtime is ready but the isolated image is missing.
* Added focused tests proving missing images do not attempt `docker run`.
* Added focused timeout coverage proving bounded timeouts produce compact failed results without raw stdout/stderr.

**Files Changed**:

* `apps/server/src/managers/containerRuntimeManager.ts` - corrected isolated-spawn preview fallback reason precedence to preserve image failure.
* `apps/server/tests/containerRuntimeManager.test.ts` - added missing-image and timeout assertions.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - focused server tests passed.
  * Evidence: missing-image and timeout tests passed with fake container runners.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: container manager changes compile.
* UI product-surface check: N/A - manager behavior only.
* UI craft check: N/A - manager behavior only.

**BQC Fixes**:

* External dependency resilience: timeout path is covered without unbounded waits.
* Failure path completeness: missing image is reported distinctly from runtime unavailability and remains retryable.

***

### Task T012 - Update server tests for container queue and campaign dispatch

**Started**: 2026-06-28 21:28 **Completed**: 2026-06-28 21:38 **Duration**: 10 minutes

**Notes**:

* Added focused server tests for queue container dispatch, campaign container dispatch, unavailable runtime/image states, failure states, stale revisions, duplicate idempotency/in-flight behavior, and route event privacy.
* Tests use fake container runners and do not require live Docker.

**Files Changed**:

* `apps/server/tests/taskExecutionCoordinator.container.test.ts` - new coordinator and campaign tests.
* `apps/server/tests/orchestration.test.ts` - route and WebSocket event privacy tests.
* `apps/server/tests/containerRuntimeManager.test.ts` - runtime manager failure-path tests.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts`
  * Result: PASS - 24 focused server tests passed.
  * Evidence: all new and affected server tests passed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server TypeScript typecheck completed.
  * Evidence: test and source type usage compiles.
* UI product-surface check: N/A - server tests only.
* UI craft check: N/A - server tests only.

**BQC Fixes**:

* Duplicate action prevention, failure path completeness, external dependency resilience, contract alignment, and error information boundaries are covered by the focused server test set.

***

### Task T006 - Add web API container executable builders and validators

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Added `TaskQueueContainerCreateInput`, `containerTaskQueueExecutable()`, and `createContainerTaskQueueEntry()` so web callers can build schema-validated compact container queue payloads without raw Docker fields.
* Tightened task-queue broad response validation to reject container raw fields such as Docker commands, raw Docker output, env, mounts, volumes, entrypoint, inspect data, and workspace paths.
* Extended mutation response/link validation to tolerate compact `containerRunId` metadata.

**Files Changed**:

* `apps/web/src/lib/orchestrationApi.ts` - added container queue builders, validation, mutation-key defaulting, and raw container response blocking.
* `apps/web/tests/orchestrationApi.test.ts` - covered container queue serialization, duplicate in-flight mutation keys, compact metadata, and raw field rejection.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - 6 web test files, 85 tests passed.
  * Evidence: API tests passed container create serialization, duplicate mutation key, compact response, and blocked raw container response assertions.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - API helper only.
* UI craft check: N/A - API helper only.

**BQC Fixes**:

* Contract alignment: web API helper now validates container queue payloads with the shared protocol parser before POST.
* Duplicate action prevention: container queue create uses stable in-flight mutation keys and has explicit duplicate-trigger coverage.
* Error information boundaries: broad queue response guards now reject raw container command/output/env/mount fields.

***

### Task T013 - Add container family labels and compact result copy

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Added queue action labels and reasons for `Dispatch container` and `Retry container`.
* Updated queue execution display helpers so container queue summaries render as container, not terminal fallback copy.
* Added compact container run-history attachment display with runtime, cleanup posture, container run id, and redacted result summaries.

**Files Changed**:

* `apps/web/src/lib/commandCenterUi.ts` - added container queue action copy and compact container attachment views.
* `apps/web/src/lib/orchestrationUi.ts` - added container queue execution family labels, state descriptions, fallback summaries, and runtime/cleanup count summaries.
* `apps/web/tests/commandCenterUi.test.ts` - covered compact container run-history metadata and redaction.
* `apps/web/tests/orchestrationUi.test.ts` - covered container queue row copy, retry copy, runtime/cleanup summaries, and redaction.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - 85 focused web tests passed.
  * Evidence: command-center and orchestration UI helper assertions passed for container labels, unavailable summaries, retry copy, and redaction.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
* UI product-surface check: PASS - labels are product-facing and avoid raw Docker terminology beyond safe runtime names.
* UI craft check: PASS - compact metadata is shown as labels/count summaries rather than raw output panes.

**BQC Fixes**:

* Error information boundaries: container run history and queue row summaries display only compact runtime, cleanup, id, and bounded result labels.

***

### Task T014 - Add Container queue create mode

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Added a `Container` queue create mode with image label, runtime selector, run label, and hero label controls.
* Container create payloads carry only safe image/runtime/label metadata and a recovery note; no command body, Docker args, env, mounts, or raw output fields are exposed.
* Added invalid-image feedback and container-specific create in-flight disablement.

**Files Changed**:

* `apps/web/src/components/orchestration/QueueWorkbench.tsx` - added container create mode and safe controls.
* `apps/web/tests/QueueWorkbench.test.tsx` - added component coverage for safe container create, offline disabled state, invalid image feedback, and in-flight guard.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - focused web tests passed.
  * Evidence: `QueueWorkbench.test.tsx` passed 2 tests covering container create and unavailable/invalid states.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
* UI product-surface check: PASS - controls use accessible labels, bounded names, and no diagnostics/debug copy.
* UI craft check: PASS - controls use existing compact grid/input/select styling and disabled states.

**BQC Fixes**:

* Duplicate action prevention: create button observes `queue:create:container:draft`.
* Failure path completeness: invalid image and offline states disable create with product-facing feedback.

***

### Task T015 - Add campaign task refinement controls for container executables

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Extended campaign task refinement callback payloads from expected-result text to a structured refinement object.
* Added per-task container executable controls with safe image label, runtime selector, run label, and hero label.
* Added container-specific in-flight disablement and invalid-image feedback.
* Fixed a React event lifetime bug found by tests by capturing input values before functional state updates.

**Files Changed**:

* `apps/web/src/components/orchestration/CampaignWorkbench.tsx` - added container executable task refinement controls and callback payloads.
* `apps/web/tests/CampaignWorkbench.test.tsx` - added component coverage for compact container refinement metadata and in-flight disabled state.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - focused web tests passed after fixing the event value capture bug.
  * Evidence: `CampaignWorkbench.test.tsx` passed 2 tests covering compact container executable refinement and the container refine in-flight key.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
* UI product-surface check: PASS - refinement controls use product-facing container/runtime labels and no raw diagnostic fields.
* UI craft check: PASS - controls are grouped in a fieldset with stable compact inputs and disabled states.

**BQC Fixes**:

* Duplicate action prevention: task refine observes `campaign:refine:container:<campaignId>:<taskId>`.
* Error information boundaries: refinement payloads contain only compact container executable metadata.

***

### Task T016 - Wire container queue creation, campaign refinement, refresh, and mutation keys

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Wired container queue creation through `createContainerTaskQueueEntry()` with the `queue:create:container:draft` mutation key.
* Wired campaign task container refinement through the existing campaign refine route with the `campaign:refine:container:<campaignId>:<taskId>` mutation key.
* Updated queue dispatch selection so container queue entries call dispatch and refresh queue plus command-center diagnostics rather than falling back to tracking-only.

**Files Changed**:

* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - wired container create/refine/dispatch paths and toast copy.
* `apps/web/tests/OrchestrationPanel.test.tsx` - updated shell API mocks for the new container queue helper.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - focused web tests passed.
  * Evidence: shell integration test still passes with new API helper mock, and component/API tests cover the new mutation keys.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
* UI product-surface check: PASS - shell toasts distinguish container executable metadata updates without exposing diagnostics.
* UI craft check: PASS - existing refresh and in-flight patterns are reused.

**BQC Fixes**:

* Contract alignment: shell uses the new API helper for container queue creates and the existing refine route for campaign executable changes.
* Duplicate action prevention: create/refine/dispatch mutation keys are distinct and covered.

***

### Task T017 - Update web tests for container API and UI behavior

**Started**: 2026-06-28 21:39 **Completed**: 2026-06-28 21:54 **Duration**: 15 minutes

**Notes**:

* Added and updated focused web tests for container API serialization, queue create controls, campaign refinement controls, unavailable/retry copy, offline states, in-flight guards, safe metadata, and redaction.

**Files Changed**:

* `apps/web/tests/orchestrationApi.test.ts` - container queue API coverage.
* `apps/web/tests/commandCenterUi.test.ts` - container run-history coverage.
* `apps/web/tests/orchestrationUi.test.ts` - container queue display and action copy coverage.
* `apps/web/tests/QueueWorkbench.test.tsx` - new queue component coverage.
* `apps/web/tests/CampaignWorkbench.test.tsx` - new campaign component coverage.
* `apps/web/tests/OrchestrationPanel.test.tsx` - updated API mock coverage for shell imports.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - 6 files, 85 tests passed.
  * Evidence: all added and affected web tests passed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web TypeScript typecheck completed.
* UI product-surface check: PASS - tests assert absence of raw Docker command/output fields from created/refined payloads.
* UI craft check: PASS - tests assert accessible labels and disabled states for container controls.

**BQC Fixes**:

* Duplicate action prevention, failure path completeness, contract alignment, and error information boundaries are covered across API/helper/component tests.

***

### Task T018 - Add browser e2e proof for container queue dispatch

**Started**: 2026-06-28 21:55 **Completed**: 2026-06-28 21:59 **Duration**: 4 minutes

**Notes**:

* Extended the orchestration command-center e2e fixture with a browser create -> dispatch flow for a container queue entry.
* The fixture creates the queue row through `POST /task-queue`, refreshes it into the Queue workbench, dispatches it through `POST /task-queue/:id/dispatch`, and observes a truthful `runtime_unavailable` container result.
* The browser assertions verify compact result copy, runtime, cleanup posture, unavailable state, no terminal link, and no Docker command/output/workspace/token leakage.

**Files Changed**:

* `tests/e2e/orchestration-command-center.e2e.ts` - added the container queue create/dispatch test and fixture helpers.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`
  * Result: PASS - 7 app-desktop e2e tests passed after tightening one ambiguous locator to exact mode-button matching.
  * Evidence: new test `creates and dispatches a container queue row with compact unavailable evidence` passed.
* UI product-surface check: PASS - browser flow shows `Dispatch container`, compact unavailable evidence, and no debug copy.
* UI craft check: PASS - e2e privacy and visible-text guards passed for the container queue panel.

**BQC Fixes**:

* Failure path completeness: browser proof covers truthful unavailable container runtime state.
* Error information boundaries: browser proof asserts raw Docker command/output/workspace/token labels do not render.

***

### Task T019 - Document API, isolation, architecture, and privacy boundaries

**Started**: 2026-06-28 21:55 **Completed**: 2026-06-28 22:00 **Duration**: 5 minutes

**Notes**:

* Updated API docs for task-queue container executable creation, dispatch, compact result metadata, direct container route distinction, and denied raw Docker/container fields.
* Updated isolation docs to state that task-queue/campaign container dispatch uses the existing manager-owned isolated-spawn boundary and is not a new arbitrary Docker command surface.
* Updated architecture docs so queue/campaign controls describe the shipped bounded executable subset instead of tracking-only behavior.

**Files Changed**:

* `docs/api/README_api.md` - task queue, campaign dispatch, direct container route distinction, and privacy boundary updates.
* `docs/isolation-and-sandbox.md` - queue/campaign container dispatch boundary and audit redaction requirements.
* `docs/ARCHITECTURE.md` - command-center architecture update for bounded terminal/Git/file/container queue and campaign dispatch.

**Verification**:

* Command/check: source inspection after edits
  * Result: PASS - docs mention container queue/campaign dispatch, direct isolated-spawn distinction, compact result metadata, denied Docker operations, and privacy boundaries.
* UI product-surface check: N/A - docs only.
* UI craft check: N/A - docs only.

**BQC Fixes**:

* Contract alignment: docs now match the implemented terminal/Git/file/container task queue and campaign dispatch subset.
* Error information boundaries: docs explicitly deny raw Docker command/output/env/mount/volume/image-inspect/workspace fields in broad surfaces.

***

### Task T020 - Update server and web package docs

**Started**: 2026-06-28 21:55 **Completed**: 2026-06-28 22:00 **Duration**: 5 minutes

**Notes**:

* Updated server README route and boundary notes for container queue dispatch, campaign container tasks, unavailable states, compact metadata, and no arbitrary Docker APIs.
* Updated web README cockpit notes for container queue creation, campaign task refinement, in-flight keys, UI labels, compact result metadata, and redaction boundaries.

**Files Changed**:

* `apps/server/README_server.md` - server package docs for task queue/campaign container dispatch.
* `apps/web/README_web.md` - web package docs for container queue/campaign controls and redaction.

**Verification**:

* Command/check: source inspection after edits
  * Result: PASS - package docs include unavailable states, UI labels, redaction, and no arbitrary Docker/remote/hosted claims.
* UI product-surface check: N/A - docs only.
* UI craft check: N/A - docs only.

**BQC Fixes**:

* Contract alignment: package docs now describe the same API/UI behavior as source and tests.

***

### Task T021 - Run focused protocol, server, and web tests

**Started**: 2026-06-28 22:01 **Completed**: 2026-06-28 22:02 **Duration**: 1 minute

**Notes**:

* Ran the focused container dispatch Vitest slice across protocol, server, and web.
* Included protocol queue parser coverage and the additional web helper/shell tests added during implementation.

**Files Changed**:

* None. Verification only.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npx vitest run packages/protocol/tests/orchestrationCommandCenter.test.ts packages/protocol/tests/taskQueue.test.ts packages/protocol/tests/orchestration.test.ts apps/server/tests/taskExecutionCoordinator.container.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/containerRuntimeManager.test.ts apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterUi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/QueueWorkbench.test.tsx apps/web/tests/CampaignWorkbench.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`
  * Result: PASS - 12 files, 156 tests passed.
  * Evidence: focused parser, coordinator, route, runtime manager, API, UI helper, component, and shell tests passed.
* UI product-surface check: PASS - focused web tests cover product-facing container create/refine/dispatch copy.
* UI craft check: PASS - focused component and e2e tests cover accessible labels, disabled states, and privacy-safe visible text.

**BQC Fixes**:

* Verification-only task; no new fixes required.

***

### Task T022 - Run focused browser evidence

**Started**: 2026-06-28 22:02 **Completed**: 2026-06-28 22:03 **Duration**: 1 minute

**Notes**:

* Re-ran the focused Playwright app-desktop proof after implementation and documentation edits.

**Files Changed**:

* None. Verification only.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`
  * Result: PASS - 7 app-desktop e2e tests passed.
  * Evidence: container create -> dispatch -> compact unavailable evidence test passed with privacy guards.
* UI product-surface check: PASS - browser proof includes container queue create, dispatch, unavailable result, and product-facing labels.
* UI craft check: PASS - browser proof includes visible text fit/privacy guard coverage for the command-center panel.

**BQC Fixes**:

* Verification-only task; no new fixes required.

***

### Task T023 - Run workspace quality and whitespace gates

**Started**: 2026-06-28 22:02 **Completed**: 2026-06-28 22:05 **Duration**: 3 minutes

**Notes**:

* Ran individual protocol/server/web typechecks, workspace format check, lint, workspace typecheck, full Vitest suite, and whitespace diff check.
* The first `npm run format:check` reported two pre-final formatting differences in files touched earlier in the session; formatted those files with Biome and reran `format:check` successfully.
* Checked all touched implementation, test, docs, and spec files for non-ASCII characters with `rg`; no non-ASCII matches were found.

**Files Changed**:

* `apps/server/src/managers/taskExecutionCoordinator.ts` - Biome formatting only after the format gate reported a line-wrap difference.
* `packages/protocol/src/orchestrationCommandCenter.ts` - Biome formatting only after the format gate reported a line-wrap difference.

**Verification**:

* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol typecheck completed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server typecheck completed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web typecheck completed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm run format:check`
  * Result: PASS after targeted Biome formatting of two touched files.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm run lint`
  * Result: PASS - Biome lint checked 770 files.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm run typecheck --workspaces --if-present`
  * Result: PASS - adapters, server, warroom, web, protocol, and public-website typechecks completed.
* Command/check: `. "$HOME/.nvm/nvm.sh" && nvm use >/dev/null && npm test`
  * Result: PASS - 273 test files passed, 1 skipped; 3095 tests passed, 1 skipped.
* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors.
* Command/check: `rg -n "[^\\x00-\\x7F]" <touched files>`
  * Result: PASS - no non-ASCII matches in touched files.
* UI product-surface check: PASS - all focused and full test gates passed.
* UI craft check: PASS - format, lint, e2e privacy/text, and component gates passed.

**BQC Fixes**:

* Formatting gate compliance: applied targeted Biome formatting to touched files before rerunning final gates.

***


---

# 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-session09-container-dispatch-decision/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.