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

# Session Specification

**Session ID**: `phase19-session04-campaign-workbench` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: TypeScript across `apps/server` and `apps/web`

***

## 1. Session Overview

This session turns the command-center campaign and task scaffolds from Sessions 01-03 into an operator workbench that can preview, create, mutate, and dispatch local campaign work. It builds on the existing `CommandCenterPlanCampaign`, `CommandCenterPlanTask`, legacy task queue, command-center manager, REST routes, web API helpers, store hydration, tabs, and drawer components.

It is next because the analysis script marks Phase 19 Sessions 01-03 complete and session 04 is the earliest unfinished candidate whose prerequisites are satisfied. Later attention, executor, file/git, collaboration, channel, metrics, and documentation sessions depend on campaign and queue state becoming actionable first.

The implementation stays local-first. Campaign preview and dispatch use manual or existing local inputs, bounded summaries, expected results, revisions, idempotency keys, and capability states. Model-backed decomposition and real executor-family behavior remain out of scope unless a current local provider path already exists and satisfies the existing permission, audit, redaction, and test boundaries.

***

## 2. Objectives

1. Add server-owned campaign workbench behavior for preview, create, approve, pause, resume, cancel, refine, retry failed, and dispatch transitions.
2. Bridge campaign tasks to the existing task queue without duplicating raw prompts, command bodies, absolute paths, terminal output, or artifact contents.
3. Add web workbench controls for campaigns and queue entries with stale-revision, duplicate-trigger, offline, empty, and error feedback.
4. Cover the new server routes, manager behavior, web API helpers, store state, and React workbench surfaces with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase19-session01-protocol-and-events` - Provides command-center DTOs, validators, WebSocket events, and compatibility tests.
* [x] `phase19-session02-server-backbone` - Provides `OrchestrationCommandCenterManager`, command-center REST routes, WebSocket emission, validation adapters, and server tests.
* [x] `phase19-session03-web-shell-and-store` - Provides web command-center API helpers, Zustand collections, WebSocket reducers, tabs, drawer, and shell tests.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm workspace commands from `.spec_system/CONVENTIONS.md`.
* Existing task queue contract in `packages/protocol/src/taskQueue.ts`.
* Existing command-center contract in `packages/protocol/src/orchestrationCommandCenter.ts`.
* Current server route and manager patterns in `apps/server/src/routes/commandCenter.ts`, `apps/server/src/managers/orchestrationCommandCenter.ts`, and `apps/server/src/managers/taskQueue.ts`.
* Current web API, store, and orchestration UI patterns in `apps/web/src/lib/orchestrationApi.ts`, `apps/web/src/store/useGameStore.ts`, and `apps/web/src/components/orchestration/`.

### Environment Requirements

* Local workspace dependencies installed.
* Focused tests can run with `npm test -- apps/server/tests/commandCenterManager.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterStore.test.ts apps/web/tests/OrchestrationPanel.test.tsx`.
* TypeScript checks can run with `npm --workspace apps/server run typecheck` and `npm --workspace apps/web run typecheck`.

***

## 4. Scope

### In Scope (MVP)

* Operators can preview and create local campaigns from bounded manual task input - implemented with existing command-center campaign and task DTOs.
* Operators can approve, pause, resume, cancel, refine, retry failed, and dispatch campaign plans - implemented as audited server-managed transitions with expected revision and idempotency checks.
* Operators can edit task summaries and expected results, inspect dependency and blocked-by relationships, and see verification status and revision data - implemented through scoped workbench rows and drawers.
* Operators can create queue entries from campaign tasks, update queue state, reject with reason, restore, mark unavailable, and dispatch - implemented through current task queue routes plus explicit transition support where missing.
* Broad UI rows remain summary-only while workpad, evidence, verification, and artifact details stay in scoped command-center records and later session-owned surfaces.
* Server and web tests cover accepted mutations, stale revision conflicts, duplicate triggers, task graph rendering, queue controls, and bounded product-facing failure states.

### Out Of Scope (Deferred)

* Model-backed plan decomposition - Reason: the session stub defers this if no current local provider path exists; manual task input is sufficient for MVP.
* Real executor-family implementation after dispatch - Reason: Session 06 owns executor registry behavior and Session 08+ owns concrete executor families.
* Attention queue unification and permission response files - Reason: Session 05 owns unified attention and blocking permission flows.
* Workpad/evidence raw artifact content display - Reason: Session 10 owns durable workpad, evidence, verification, and review gate detail behavior.
* Hosted, Worker, push, remote access, or external channel execution claims - Reason: later sessions own those boundaries and current PRD keeps them disabled or no-claim.

***

## 5. Technical Approach

### Architecture

Use the existing command-center contracts rather than adding a parallel protocol surface. Server work should add a focused campaign behavior layer that composes `OrchestrationCommandCenterManager` and `TaskQueueManager`, normalizes manual campaign input into `CommandCenterPlanCampaign` and `CommandCenterPlanTask`, records revisions through current manager upserts, and emits the existing `command_center_plan_update`, `command_center_task_update`, and `task_queue_update` events.

For web work, extend `orchestrationApi.ts` with campaign and queue mutation helpers, then add campaign and queue workbench components under `apps/web/src/components/orchestration/`. The workbench should reuse existing command-center store collections and in-flight mutation state, keeping rows compact and moving detailed state to drawers or scoped panels.

### Design Patterns

* Manager-owned mutation: Keeps idempotency, expected revision checks, audit timestamps, redaction, and WebSocket event emission aligned.
* Protocol-first consumption: Uses Session 01 DTOs and validators before server and web behavior.
* Pure normalization before UI mutation: Keeps malformed server payloads from blanking the cockpit.
* Bounded product rows with scoped details: Avoids exposing raw prompts, command bodies, diffs, terminal output, file contents, or broad paths in broad views.
* Duplicate-trigger prevention: Uses existing in-flight mutation key patterns on both server and web.

***

## 6. Deliverables

### Files To Create

| File                                                          | Purpose                                                                                                        | Est. Lines |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/server/src/managers/planCampaignManager.ts`             | Campaign preview, transition, dispatch, queue-bridge, and retry behavior                                       | \~260      |
| `apps/server/tests/planCampaignManager.test.ts`               | Focused manager tests for preview, transitions, idempotency, stale revisions, queue dispatch, and compensation | \~220      |
| `apps/web/src/components/orchestration/CampaignWorkbench.tsx` | Campaign preview, graph, state controls, and scoped task controls                                              | \~240      |
| `apps/web/src/components/orchestration/QueueWorkbench.tsx`    | Queue mutation controls, reject/restore/unavailable/dispatch controls, and feedback states                     | \~220      |

### Files To Modify

| File                                                           | Changes                                                                                                    | Est. Lines |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/server/src/lib/commandCenterValidation.ts`               | Add campaign preview, transition, dispatch, and queue-control validation helpers                           | \~160      |
| `apps/server/src/managers/orchestrationCommandCenter.ts`       | Add focused campaign/task helper methods only where the new manager needs existing state safely            | \~80       |
| `apps/server/src/managers/taskQueue.ts`                        | Add explicit restore and mark-unavailable transition behavior if current update semantics are insufficient | \~90       |
| `apps/server/src/routes/commandCenter.ts`                      | Add campaign workbench routes and event emission wiring                                                    | \~170      |
| `apps/server/src/server.ts`                                    | Inject the campaign workbench dependencies into command-center routes                                      | \~20       |
| `apps/server/tests/commandCenterRoutes.test.ts`                | Add route coverage for campaign preview, transitions, dispatch, stale revisions, and compact errors        | \~180      |
| `apps/web/src/lib/orchestrationApi.ts`                         | Add campaign workbench and queue mutation API helpers with refresh and error mapping                       | \~180      |
| `apps/web/src/lib/commandCenterUi.ts`                          | Add campaign graph, task dependency, state label, and action-copy helpers                                  | \~140      |
| `apps/web/src/store/useGameStore.ts`                           | Add campaign/queue mutation state handling and cleanup for accepted command-center changes                 | \~100      |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Replace generic campaign pane with workbench composition                                                   | \~80       |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire campaign and queue workbench action handlers, toasts, refresh, and duplicate-trigger guards           | \~140      |
| `apps/web/src/components/orchestration/index.ts`               | Export the new workbench components                                                                        | \~10       |
| `apps/web/tests/orchestrationApi.test.ts`                      | Cover campaign and queue API helper success, stale revision, duplicate-trigger, and offline handling       | \~180      |
| `apps/web/tests/commandCenterStore.test.ts`                    | Cover mutation state cleanup and graph-related store behavior                                              | \~120      |
| `apps/web/tests/commandCenterUi.test.ts`                       | Cover campaign graph and action-copy helpers                                                               | \~100      |
| `apps/web/tests/OrchestrationPanel.test.tsx`                   | Cover visible campaign/queue controls, failure states, accessibility, and no raw debug copy                | \~220      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Campaign preview accepts bounded manual task input and returns campaign/task previews without storing raw prompt, command, path, or artifact fields.
* [ ] Campaign create, approve, pause, resume, cancel, refine, retry failed, and dispatch transitions enforce idempotency and expected revision checks.
* [ ] Dispatch creates or links queue entries with `source: "plan"` and plan references while emitting queue and command-center updates.
* [ ] Queue controls support create-from-template, state update, reject with reason, restore, mark unavailable, and dispatch without duplicate triggers.
* [ ] Web workbench renders dependency graph, task prompts as bounded summaries/expected results, verification state, revisions, last transition, and scoped detail entry points.
* [ ] Broad rows and list views remain summary-only and product-facing.

### Testing Requirements

* [ ] Server manager tests cover idempotent preview/create/transition/dispatch and stale revision conflicts.
* [ ] Server route tests cover compact validation errors, WebSocket emissions, and dispatch queue bridging.
* [ ] Web API tests cover timeout, offline, stale revision, duplicate trigger, and refresh-after-mutation behavior.
* [ ] Store and component tests cover workbench rendering, graph rows, controls, accessibility labels, loading, empty, error, and offline states.

### Non-Functional Requirements

* [ ] Local-first privacy boundary preserved: no hosted transfer, raw prompt storage, raw command body display, absolute path leakage, or executor success claims.
* [ ] Mutations are deterministic, revisioned, and bounded to the 200-entry command-center and task queue conventions unless current code documents a stricter cap.
* [ ] Workbench controls remain keyboard and pointer accessible, with visible focus states and native buttons/inputs.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.
* [ ] `npm --workspace apps/server run typecheck` passes.
* [ ] `npm --workspace apps/web run typecheck` passes.
* [ ] Focused server and web tests pass.

***

## 8. Implementation Notes

### Working Assumptions

* Session 04 is cross-cutting: the candidate stub names `apps/server` and `apps/web`, while the analysis script reports no single active package. Planning can proceed with `Package: null` because the package targets are explicit in the stub and current code paths.
* Manual task input is the MVP campaign intake path: the session stub explicitly defers model-backed decomposition when no local provider path exists, and current code already has DTOs for bounded campaign/task summaries and expected results.
* Existing Session 01 command-center DTOs are the first implementation target: current code exposes `CommandCenterPlanCampaign`, `CommandCenterPlanTask`, and mutation routes, so planning can avoid protocol churn unless implementation proves a contract gap.

### Key Considerations

* Keep broad UI rows summary-only; raw prompt-like task content should be represented as bounded summary or expected-result text.
* Dispatch should not claim executor success. It should move campaign tasks into queue-ready or unavailable states and leave real executor behavior to later sessions.
* Route and manager failures should return compact labels and field names only.
* If a multi-record dispatch partially fails, the implementation must return bounded partial-failure details and leave enough state for retry or compensation.

### Potential Challenges

* Campaign and task state can drift from legacy task queue state: mitigate by centralizing dispatch in the server campaign manager and emitting both command-center and queue events.
* Current task queue transition names include restore and mark-unavailable but manager behavior mostly uses update/reject: mitigate by adding explicit methods or route branches with tests.
* The campaign workbench can become too dense: mitigate with grouped sections, stable button dimensions, concise rows, and scoped drawer details.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: Dispatch must not imply a file, git, terminal, Docker, remote, or hosted executor ran.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Consume the Session 01 command-center contract before adding package-specific behavior.
* \[P03-apps/server] **Local server boundary must stay conservative**: New routes need schema validation, rate-limit inheritance, compact errors, and no raw payload echo.
* \[P07] **Redaction is boundary-specific**: Campaign, queue, route, WebSocket, and UI output must each minimize sensitive developer data.
* \[P18-apps/server] **Manager-owned persistence and snapshot emission**: Keep mutation state behind one manager boundary so route responses and broadcasts align.
* \[P18-apps/web] **Pure normalization before store mutation**: Web reducers and UI helpers should normalize malformed or partial payloads before changing state.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Multi-step dispatch could partially update campaign tasks and queue entries without a recoverable retry or compensation path.
* Duplicate clicks or stale revisions could create duplicate queue entries or overwrite current campaign state.
* Workbench rows could leak prompt-like text, raw command bodies, broad paths, or implementation diagnostics into broad user-facing surfaces.

***

## 9. Testing Strategy

### Unit Tests

* `apps/server/tests/planCampaignManager.test.ts`: preview normalization, idempotent create/update, transition state machine, stale revisions, dispatch queue bridging, partial-failure/compensation, and redaction.
* `apps/web/tests/commandCenterUi.test.ts`: campaign state labels, task graph ordering, dependency summaries, action availability, and safe copy.
* `apps/web/tests/orchestrationApi.test.ts`: preview, transition, queue mutation helpers, duplicate-trigger prevention, stale revision mapping, timeout, and offline mapping.

### Integration Tests

* `apps/server/tests/commandCenterRoutes.test.ts`: route validation, compact errors, `/api` aliases, WebSocket plan/task/queue emissions, and unavailable dispatch handling.
* `apps/web/tests/commandCenterStore.test.ts`: mutation state cleanup after accepted command-center changes and selection cleanup when a mutated record disappears.
* `apps/web/tests/OrchestrationPanel.test.tsx`: visible workbench controls, graph rows, drawer links, state transitions, loading/empty/error/offline states, focus behavior, and product-surface copy.

### Runtime Verification

* Start the local server and web app only if implementation requires browser validation beyond component tests.
* Manually exercise a campaign preview, create, approve, dispatch, pause, resume, cancel, retry, and queue reject/restore/unavailable flow in the cockpit if browser validation is needed.

### Edge Cases

* Duplicate idempotency key replays original result.
* Stale expected revision returns `409 conflict` without mutation.
* Dispatch where one queue entry fails reports bounded partial failure and leaves retryable state.
* Dependency graph handles missing task ids, cycles, and completed prerequisites without crashing.
* Offline or disconnected web state leaves controls visible but disabled or safely failing with bounded copy.
* Long labels wrap without overlapping buttons or adjacent cards.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase19-session01-protocol-and-events`, `phase19-session02-server-backbone`, `phase19-session03-web-shell-and-store`
* Depended by: `phase19-session05-attention-and-permissions`, `phase19-session08-file-and-git`, `phase19-session10-mission-artifacts`, `phase19-session11-templates-and-planning-context`, `phase19-session13-collaboration-and-handoff`, `phase19-session14-channels-and-scope`, `phase19-session15-metrics-and-notifications`, `phase19-session16-ergonomics-and-documentation`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

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

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

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

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase19-session04-campaign-workbench/spec.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.