Task dispatch: assign a task card to an agent

Task dispatch is atrium's pattern for assigning work to an agent. It links a task card to a pane, creates a run that tracks the execution, and gives the agent the environment it needs to report progress and completion.

See Tasks & runs for the underlying data model.

Launching from the UI

Open the task detail pane (Cmd+Shift+J, or click a row in the tasks list pane) and press the Launch button at the top of the card.

The dispatch dialog asks for:

• Target pane — pick an existing empty pane or create a new one right from the dialog.
• Adapter — any installed adapter.
• Surface — an agent chat pane or a terminal pane.
• Review status — which project status to move the card to when the agent signals "ready for human review".
• Completion status — which status to move the card to when the agent signals done.
• Execution mode — either current branch (the agent works on the currently checked-out branch) or worktree (atrium creates a fresh git worktree, a sibling atrium workspace for it, and the bound agent room in one shot, so the work is isolated from your main checkout).
• Merge target — the base branch the agent is working toward; can optionally reuse an existing branch instead of creating a fresh one.
• Adapter flags — optional per-launch tuning (YOLO, CLI args, model choice if the adapter exposes one).

Press Launch and atrium:

1. Resolves the owning location and runs preflight for the project, tool, adapter, profile, credentials, and worktree.
2. Creates a new run against the card on that location.
3. Sets the card's current_primary_run_id to the new run.
4. Injects ATRIUM_TASK_ID (the task's UUID) and ATRIUM_TASK_RUN_ID (the run's UUID) into the pane's shell.
5. Sends the task title and description to the agent as the first user prompt.
6. Focuses the pane and opens its activity card in the sidebar.
7. Renames the room to include the task number and title (for example ATR-42 - Fix the auth middleware) so you can recognize task rooms at a glance.

The task detail pane now shows a live Runs timeline at the bottom with the new run at the top. Inline status, log preview, Cancel (while active), and Replay (when complete).

The run starts on the task's owning location. To use another registered box, change the card's Location before launching; atrium relocates the card and then keeps its runs and recurrence on that daemon.

Launching from the CLI

For scripting or for one-off headless use, the CLI exposes the same operation:

"$ATRIUM_CLI_PATH" task launch ATR-42 \
    --pane-id <pane-id> \
    --adapter claude-code \
    --source user:me

Qualify a remote task as ATR-42@build-box, or target the entire command with the global --location build-box flag. A remote run remains owned by that daemon through resume and recurrence.

Leave out --pane-id and atrium launches the card itself, headless:

"$ATRIUM_CLI_PATH" task launch ATR-42

A repeatable card fires the same way as task run-now. Any other card gets a background agent. atrium spawns it from the card's launch config (adapter, launch profile, execution mode) and sends it the assignment prompt. The card then moves to its in-progress status. The agent finishes the same way as a foreground launch:

• task set-in-review moves the card to review. The agent stays running in the background, so you can send it review feedback.
• task set-done completes the run, moves the card to done, and ends the agent's session. The worktree, if any, is kept.

Flags you pass override the card's launch config for that launch only.

Optional flags mirror the dialog:

• --review-status <status-id> and --completion-status <status-id>.
• --merge-target <branch> — informational; the base branch the agent is working toward.
• --execution-mode current_branch — skip worktree creation.
• --adapter-flags <json> — per-launch adapter-specific flags.

What the agent sees

Inside the pane, the agent has the usual environment plus ATRIUM_TASK_ID and ATRIUM_TASK_RUN_ID. A typical agent loop uses the canonical skill's atrium CLI commands:

# Pull the full task details
"$ATRIUM_CLI_PATH" task show "$ATRIUM_TASK_ID" --json

The agent does work and periodically posts status comments back to the task:

"$ATRIUM_CLI_PATH" task comment "$ATRIUM_TASK_ID" \
    --body "Starting work on the auth middleware" \
    --source "adapter:claude-code" \
    --kind agent-update

Comments show up live in the task detail pane's comment thread. The --kind value (discussion / instruction / agent-update) affects how the comment is rendered.

When the agent decides the work is ready for human review:

"$ATRIUM_CLI_PATH" task set-in-review

This reads $ATRIUM_TASK_RUN_ID and transitions the card to the review status you picked in the dispatch dialog. The detail pane updates immediately; the sidebar card's status flips.

When the agent wants to close the task directly:

"$ATRIUM_CLI_PATH" task set-done

Both commands accept an explicit --run-id <id> if the caller is outside the pane.

Handling interrupted runs

If a pane is closed or crashes mid-work, its run becomes interrupted.

From the UI, the tasks list pane's Interrupted filter chip isolates them. Open a run and press Resume in the run row — atrium asks for a fresh pane and adapter, then attaches a new segment to the same run.

Equivalent CLI flow:

"$ATRIUM_CLI_PATH" run list --state interrupted
"$ATRIUM_CLI_PATH" run show <run-id>
"$ATRIUM_CLI_PATH" run segments <run-id>
"$ATRIUM_CLI_PATH" run resume <run-id> --pane-id <new-pane-id>

Or cancel:

"$ATRIUM_CLI_PATH" run cancel <run-id>

The resumed run gets a fresh segment. The new pane receives the same ATRIUM_TASK_ID / ATRIUM_TASK_RUN_ID environment, so the agent can pick up without losing the link.

Multiple runs per task

A task can have many runs over its lifetime — an agent might make a first attempt, get cancelled, then come back and try again. The detail pane shows every run in chronological order, with status and inline logs. Runs are never deleted; cancelled and completed runs remain for history.