> 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-session04-campaign-executable-dispatch/spec.md). # Session Specification **Session ID**: `phase20-session04-campaign-executable-dispatch` **Phase**: 20 - Orchestration Actionability Execution **Status**: Not Started **Created**: 2026-06-28 **Package**: null **Package Stack**: mixed TypeScript across `packages/protocol`, `apps/server`, and `apps/web` *** ## 1. Session Overview This session makes approved campaign tasks dispatch real terminal or Git work when those tasks carry a supported executable payload. It replaces the old campaign bridge that only created tracking queue rows with a vertical path that creates queue entries, calls `TaskExecutionCoordinator`, records execution-run evidence, and updates campaign task state from the actual result. It is next because Phase 20 Sessions 02 and 03 completed queue terminal and Git execution, including private executable storage, safe execution summaries, and coordinator-owned runtime handling. Campaign execution should reuse those shipped queue slices instead of adding a separate executor path. The session keeps campaign tasks without executable payloads truthful. Planning-only tasks stay pending, planning-only, blocked, or failed as appropriate and are not counted as dispatched or executed. Serial execution is sufficient for this session; dependency-graph campaign scheduling is left to Session 05. *** ## 2. Objectives 1. Add campaign task executable payload support for terminal and Git task inputs without exposing raw command text, Git output, diffs, or broad paths in public campaign records. 2. Route approved executable campaign task dispatch through `TaskExecutionCoordinator` and return safe execution run summaries in campaign dispatch responses. 3. Preserve truthful planning-only behavior for campaign tasks that do not have executable payloads. 4. Update web campaign labels, rows, task detail, and tests so operators can see execution readiness, queue links, execution evidence, and partial failure states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase20-session02-queue-terminal-execution` - Provides terminal executable queue payloads, private queue executable storage, terminal coordinator dispatch, safe execution summaries, and browser evidence. * [x] `phase20-session03-queue-git-execution` - Provides Git executable queue payloads, Git workbench coordinator dispatch, policy-blocked unavailable handling, and web queue evidence. ### Required Tools Or Knowledge * Node 26.2.0 and npm 11.16.0 from `.nvmrc` and `.spec_system/CONVENTIONS.md`. * Existing campaign manager, task queue manager, `TaskExecutionCoordinator`, command-center route, and campaign web workbench behavior. * Existing focused Vitest and Playwright command-center suites. ### Environment Requirements * Local repo checkout with npm workspaces installed. * No hosted credentials, provider credentials, analytics, Worker proxy, remote execution, or Docker runtime claim is required for this session. *** ## 4. Scope ### In Scope (MVP) * Operators can create or refine campaign tasks with an optional terminal or Git executable payload - Parse and store executable payloads privately while exposing safe readiness and execution summaries. * Operators can approve and dispatch a campaign - Supported terminal and Git executable tasks run through the existing queue coordinator. * Operators can inspect campaign task results - Campaign, task, queue, and execution rows link to the same safe execution evidence. * Operators can identify planning-only work - Tasks without executable payloads remain visibly planning-only and are not reported as dispatched or executed. * Operators can recover from partial failure - Failed or unavailable executable tasks set bounded task/campaign state without falsely completing the campaign. ### Out Of Scope (Deferred) * Parallel or dependency-graph campaign scheduling - Reason: Session 05 owns DAG recovery and dependency order. * File, container, channel, template, or managed-agent campaign execution - Reason: Later Phase 20 sessions own those executor families. * Hosted, remote, Worker-bridged, or trusted automatic execution - Reason: Phase 19 and Phase 20 boundaries keep these no-claim until separately threat-modeled and validated. * Broad raw execution detail in summaries, events, docs, or notifications - Reason: Sensitive command, output, diff, and path detail remains scoped local detail only. *** ## 5. Technical Approach ### Architecture Protocol remains the first package changed. Campaign task contracts should gain safe execution readiness and execution summary fields, while raw executable payloads are accepted only in request/input shapes and private server storage. Public `CommandCenterPlanTask`, compact events, and web rows should expose labels, readiness, state, execution run ids, queue ids, and compact result summaries only. Server campaign dispatch should become asynchronous because terminal and Git coordinator dispatch is async. `PlanCampaignManager` should accept or receive `TaskExecutionCoordinator`, create queue entries with executable payloads and campaign task references, call the coordinator serially for supported payloads, update task and campaign state from coordinator results, and return execution changes so routes can broadcast campaign, task, queue, and execution updates. The web should keep product-facing copy in the campaign workbench. Campaign controls should distinguish executable dispatch from planning-only tracking, graph rows should show execution readiness and evidence links, and toasts should describe executed, unavailable, partial, and planning-only outcomes without leaking raw command text, stdout, stderr, diffs, patch bodies, commit messages, or broad paths. ### Design Patterns * Protocol-first contracts: Keeps protocol, server, web, REST, WebSocket, and tests aligned before behavior changes. * Manager-owned runtime boundaries: Keeps idempotency, duplicate-trigger handling, state revisions, and bounded snapshots in managers. * Broad-summary plus scoped-detail split: Keeps raw terminal/Git detail out of campaign rows and broad events while linking to existing scoped execution evidence. * Existing coordinator reuse: Avoids a second execution path and preserves Session 02/03 timeout, unavailable, policy, and safe-summary behavior. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/tests/planCampaignExecutableDispatch.test.ts` | Focused acceptance coverage for campaign executable terminal/Git dispatch, planning-only tasks, idempotency, and partial failure. | \~260 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Add safe campaign task execution readiness/summary fields and parser support. | \~140 | | `packages/protocol/src/taskQueue.ts` | Add campaign task queue reference support and ensure queue links stay safe. | \~50 | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Cover campaign task execution summaries, blocked raw fields, and parser compatibility. | \~120 | | `packages/protocol/tests/orchestration.test.ts` | Cover task queue campaign task references and safe execution link shape. | \~80 | | `apps/server/src/lib/commandCenterValidation.ts` | Parse campaign task executable payloads with schema validation and compact errors. | \~110 | | `apps/server/src/managers/planCampaignManager.ts` | Store executable payloads privately, create executable queue rows, dispatch through the coordinator, and update campaign/task state. | \~260 | | `apps/server/src/routes/commandCenter.ts` | Make campaign dispatch async and emit execution, queue, task, and campaign updates. | \~60 | | `apps/server/src/server.ts` | Wire `PlanCampaignManager` to `TaskExecutionCoordinator`. | \~10 | | `apps/server/tests/planCampaignManager.test.ts` | Replace old tracking-only expectations where executable payloads exist. | \~120 | | `apps/server/tests/commandCenterRoutes.test.ts` | Prove REST/WebSocket campaign executable dispatch and safe events. | \~160 | | `apps/web/src/lib/orchestrationApi.ts` | Accept executable campaign task input and validate execution-aware workbench responses. | \~90 | | `apps/web/src/lib/commandCenterUi.ts` | Add execution-aware campaign row and action copy helpers. | \~110 | | `apps/web/src/components/orchestration/CampaignWorkbench.tsx` | Render executable readiness, planning-only states, queue links, and execution result summaries. | \~170 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Update campaign dispatch toasts for execution, partial failure, and planning-only outcomes. | \~40 | | `apps/web/tests/commandCenterUi.test.ts` | Cover execution-aware campaign graph and action copy. | \~80 | | `apps/web/tests/CommandCenterPanes.test.tsx` | Cover campaign product UI, duplicate prevention, links, and privacy-safe labels. | \~130 | | `apps/web/tests/orchestrationApi.test.ts` | Cover executable campaign input and response parsing. | \~90 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Update campaign dispatch toasts and workbench expectations. | \~80 | | `tests/e2e/orchestration-command-center.e2e.ts` | Add campaign executable dispatch browser proof without raw terminal/Git leakage. | \~170 | | `apps/server/README_server.md` | Document campaign executable dispatch boundary and planning-only behavior. | \~30 | | `apps/web/README_web.md` | Document campaign UI execution readiness and privacy boundary. | \~30 | | `docs/api/README_api.md` | Document updated campaign workbench response shape and evidence links. | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Campaign task create/refine accepts optional terminal or Git executable payloads through validated request shapes. * [ ] Campaign approve -> dispatch -> executable task run -> execution run -> task completed is proven for at least one terminal or Git task. * [ ] Tasks without executable payloads are not reported as dispatched or executed. * [ ] Partial failure does not falsely mark the whole campaign completed. * [ ] Campaign task, queue row, and execution run link to the same safe execution evidence. ### Testing Requirements * [ ] Protocol parser and type tests cover campaign task execution summaries, task queue references, and blocked raw fields. * [ ] Server manager and route tests cover success, planning-only, partial failure, duplicate trigger, unavailable, and safe event paths. * [ ] Web unit/component tests cover execution-aware copy, links, in-flight duplicate prevention, empty/error states, and privacy-safe rendering. * [ ] Playwright command-center desktop and mobile tests cover visible campaign dispatch evidence without raw terminal/Git leakage. ### Non-Functional Requirements * [ ] Broad campaign, queue, REST, WebSocket, docs, notifications, and row summaries do not expose raw commands, stdout, stderr, diffs, patch bodies, commit messages, tokens, secrets, provider payloads, or broad absolute paths. * [ ] Existing queue terminal and Git dispatch behavior remains compatible. * [ ] Campaign dispatch remains deterministic and serial in this session. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused protocol, server, web, Playwright, and `git diff --check` commands pass *** ## 8. Implementation Notes ### Working Assumptions * Cross-package session scope is intentional: The analyzer reports `package: null`, the session stub lists `packages/protocol`, `apps/server`, and `apps/web`, and the behavior crosses shared contracts, server dispatch, and browser UI. Planning can proceed with `Package: null` because all affected paths are repo-root-relative and the package set is explicit. * Raw executable payloads should not be stored on public campaign/task records: Sessions 02 and 03 already store queue executable payloads privately and expose safe execution summaries, and the Phase 19/20 considerations require scoped detail to stay separate from broad rows. Planning can proceed by reusing the queue/coordinator pattern. * Serial campaign execution is sufficient for this session: The session stub explicitly says serial execution is acceptable and defers dependency graph scheduling to Session 05. Planning can proceed without designing parallel scheduling. ### Conflict Resolutions * Existing campaign tests and UI copy describe campaign dispatch as tracking-only, while the Phase 20 session stub requires executable dispatch for terminal and Git payloads. The chosen interpretation is to replace tracking-only expectations only for tasks with executable payloads and preserve planning-only wording for tasks without payloads. * `docs/README_docs.md` still says no remaining phase is outlined, while `.spec_system/PRD/PRD.md`, `.spec_system/PRD/phase_20/PRD_phase_20.md`, and analyzer state show Phase 20 in progress with sessions 1-3 complete. The chosen interpretation is to treat spec-system PRD and analyzer state as authoritative for workflow planning. ### Key Considerations * \[P19] Executor claims are family-scoped: Only terminal and Git campaign task payloads may run in this session. * \[P19] Scoped detail stays separate from broad rows: Campaign rows and events must show compact evidence only. * \[P03-packages/protocol] Protocol leads cross-package work: Shared shapes change before server and web consumers. * \[P19] Command-center state is manager-owned: Idempotency, revisions, cleanup, event emission, and bounded snapshots stay in managers. ### Potential Challenges * Async route conversion can drop event emissions: Return explicit queue and execution changes from the manager and broadcast them in the route helper. * Partial failure can overstate campaign completion: Derive campaign state from per-task final states and keep failed/unavailable/planning-only tasks visible. * Raw payload leakage can enter broad surfaces through convenience cloning: Keep executable payloads in private maps/request scope and add parser/test coverage for blocked raw fields. * Duplicate dispatch can start duplicate terminal/Git work: Reuse campaign mutation locks, task queue idempotency keys, and coordinator in-flight guards. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Duplicate campaign dispatch while async terminal or Git execution is in flight. * False completion when one executable task fails, is unavailable, or when another task is planning-only. * Raw command, terminal output, Git output, diff, path, token, or secret leakage into broad campaign rows, events, docs, tests, or notifications. *** ## 9. Testing Strategy ### Unit Tests * Protocol tests for campaign task execution summary parsing, task queue campaign task references, and blocked raw fields. * Server manager tests for executable campaign dispatch success, planning-only tasks, partial failure, unavailable Git/terminal paths, and duplicate idempotency. * Web helper tests for execution-aware campaign graph rows, action labels, and safe fallback copy. ### Integration Tests * Command-center route tests for campaign create/approve/dispatch with terminal or Git payload, response execution evidence, queue linkage, WebSocket event updates, and safe public payloads. * Web component/API tests for executable task input, dispatch response parsing, campaign workbench rendering, and in-flight duplicate prevention. ### Runtime Verification * Playwright command-center desktop and mobile flow showing a campaign dispatch result and linked queue/execution evidence without broad raw payload leakage. ### Edge Cases * Campaign tasks without executable payloads remain planning-only and are not counted as dispatched or executed. * Git push remains policy-blocked/unavailable and does not run. * Terminal PTY unavailable returns unavailable evidence without marking the campaign complete. * Replayed idempotency keys do not create duplicate queue entries or execution runs. * Failed executable tasks keep campaign state partial/failed instead of completed. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase20-session02-queue-terminal-execution`, `phase20-session03-queue-git-execution` * Depended by: `phase20-session05-campaign-dag-recovery`, `phase20-session06-file-mutation-core`, later Phase 20 execution slices *** ## 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/phase20-session04-campaign-executable-dispatch/spec.md?ask=&goal= ``` `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.