Agent Execution

Applies to: Dispatch v1.0.0, last verified 2026-04-05

Overview

This page explains how Dispatch spawns CLI agents from the dashboard and how the execution pipeline works end to end.

Dispatch can spawn CLI agents directly from the dashboard. Click the Run button on a TODO or BLOCKED epic phase, and Dispatch launches the assigned agent’s CLI process with the phase context as its prompt.

The executor is additive: it feeds the existing observation pipeline. A spawned agent creates session files (JSONL, logs) just like a manually-started agent. The file watcher and multi-session poller pick up the new session automatically.

Spawn-per-command model

Each spawn request creates a fresh CLI process. Sending a command to a running agent does not use PTY injection or IPC. It means spawning a new process with --resume <sessionId> and the new prompt via stdin. The CLI handles session continuity.

Supported providers

Provider	Binary	Spawnable	Notes
Claude Code	claude	Yes	Full streaming support, session resume
Codex	codex	Yes	JSON output mode, session resume
Gemini	gemini	Yes	Session resume
Copilot	gh	No	MCP-only integration. No CLI spawn interface.

The Run button

The Run button appears on epic phase rows when all of these conditions are met:

• The phase status is TODO or BLOCKED
• The phase has a persona field
• The persona maps to an installed agent
• The agent’s tool supports spawning (not Copilot)

Click the Run button to start the spawn. The button shows inline status feedback:

1. Spawning: spawn request sent to the server
2. Running: CLI process is active, streaming output
3. Done: process exited successfully
4. Error: process failed (error shown inline)

The phase card auto-updates when the spawned agent writes DONE to plan.md. The existing file watcher detects the change without any polling.

Adapter architecture

Each provider has a dedicated adapter implementing a common interface. The adapter handles process lifecycle (spawn, parse stdout, timeout, kill). It does not handle prompt sanitization. That is the caller’s responsibility (see Security).

Prompt assembly

The server assembles the prompt before calling the adapter:

1. Trusted prefix: the agent’s persona instructions (from its .md definition)
2. Sandboxed context: epic description and phase title, wrapped in delimited XML to prevent prompt injection
3. Sandboxed custom prompt: if provided via the API request body
4. Trusted footer: instruction to mark the phase DONE when work is complete

All user/task/blackboard content is sandboxed (wrapped in XML tags with closing-tag patterns stripped) before being included in the prompt. See Security: G2.

Session resume and retry

Dispatch stores the lastSessionId from each successful spawn in the agent’s tool config. On the next spawn for the same agent and tool:

1. If the stored session is less than 30 days old, the adapter spawns with --resume <sessionId>
2. If the CLI reports “unknown session” (expired or invalid), Dispatch retries once with a fresh session
3. On success, the new session ID overwrites the stored one

Sessions older than 30 days are pre-emptively discarded to avoid a round-trip failure.

SSE streaming

When the dashboard requests SSE streaming, the server streams chunks back as SSE events:

• sessionId: fires as soon as the CLI init event is parsed (fast feedback)
• text: assistant output as it arrives
• cost: token cost on completion
• error: if the process fails
• run_complete: final event with the full result

Without SSE, the endpoint returns a buffered JSON response after the process exits.

Active runs

In-flight runs are tracked in an in-memory map. This map is intentionally lost on server restart. The JSONL files survive restarts, and the observation layer rebuilds state from them.

Cancellation

Cancelling a run sends SIGTERM to the spawned process followed by SIGKILL after a short grace period. A well-behaved process should flush buffers in this window.