Tasks

The task board tracks durable work across manual tasks, delegated work, imports, structured-session emissions, and schedule-created runs.

Statuses

Approvals can affect how a task proceeds, but approval is not a task status. Approval waits show up in the task/chat runtime while the task remains in its normal operational state.

Where Tasks Come From

• manual task creation
• agent-created tasks via platform tools
• delegation to another agent
• schedule-origin work
• GitHub issue import
• structured sessions that emit follow-up tasks

Task Shape

Tasks can carry more than a title and status:

• assigned agent
• project and goal linkage
• task dependencies (blockedBy / blocks)
• source metadata (manual, delegation, schedule, import)
• upstream results from completed dependencies
• artifacts, output files, comments, and verification summaries

Delegated Tasks

Agents with delegation enabled can create delegated tasks for other agents.

Delegated tasks:

• are assigned to the target agent
• keep origin metadata
• auto-queue when one agent creates work for another agent without explicitly choosing a status
• can be restricted to selected delegate targets
• can continue routing follow-ups back to the originating connector or session when configured

Approval Workflow

When capability policy requires approval, a running task can pause before a sensitive tool execution step.

Inline approvals can appear in the chat and task surfaces. Once approved, the normal task and session runtime resumes.

Schedule-Origin Tasks

When schedules fire, they create schedule-origin tasks.

Important behavior:

• execution targets are stored explicitly
• schedule runs do not guess from the most recently active chat
• archiving a schedule can cancel linked queued or running tasks
• cancelling an in-flight schedule task can abort its active structured session or run cleanly

Dependencies and Pool Mode

Tasks can model lightweight execution planning:

• dependency edges through blockedBy
• pool-mode claiming for eligible agents
• result propagation from completed dependencies into newly unblocked work

This keeps the task board usable both for manual operators and for agent-driven work routing.

Failed Task Retry

Failed tasks that exhausted their retry attempts can be requeued by an operator after the underlying issue is fixed.

API access:

curl -X POST http://localhost:3456/api/tasks/<taskId>/retry

POST /api/tasks/:id/retry resets attempts, clears dead-letter metadata, clears the last error and validation failure, then queues the task again. It rejects completed, queued, running, and still-blocked tasks with 409.

Handoff Packets

Handoff packets package the current task state before work moves to another operator, backend, workspace, or follow-up run.

Each packet includes:

• task owner, project, goal, and source metadata
• liveness, readiness, blockers, and recommended next actions
• workspace path, runtime links, output files, artifacts, comments, and verification summaries
• dependency status for blocked and downstream tasks
• a compact run summary and quality checks

API and CLI access:

swarmclaw tasks handoff <taskId>
swarmclaw tasks handoff-save <taskId>
swarmclaw tasks handoffs --query status=needs_attention

GET /api/tasks/:id/handoff?format=markdown returns a Markdown packet. POST /api/tasks/:id/handoff saves handoff.md and handoff.json into the task workspace, preparing the workspace first if needed.

Execution Policies

Execution policies add ordered review gates to a task. A policy can require review, approval, verification, or any combination of those stages before the task can be marked completed.

Each policy tracks:

• enabled stages and their required decision counts
• current stage status
• approve, request-changes, and reset decisions
• blocking reasons when completion is not ready

API and CLI access:

swarmclaw tasks execution-policy <taskId>
swarmclaw tasks execution-policy-decision <taskId> --data '{"action":"approve","actor":"QA"}'
swarmclaw tasks execution-policy-decision <taskId> --data '{"action":"reset","stage":"verification","note":"Rerun final checks."}'

GET /api/tasks/:id/execution-policy returns the current policy state. POST /api/tasks/:id/execution-policy records decisions or updates the policy. When a required policy stage is incomplete, PUT /api/tasks/:id rejects explicit completion with 409 and returns the blocking checks.

Atomic Checkout

Two heartbeats can fire at nearly the same instant against the same task. To prevent duplicate work, checkoutTask(taskId, runId) runs inside a SQLite IMMEDIATE transaction: only one runner transitions queued → running and stamps checkoutRunId; the other receives null back and skips. Stale checkouts left over from ungraceful exits (crash, SIGKILL, mid-turn HMR reload) are reclaimed automatically when the task is still in queued status — preventing infinite "Recovering orphaned queued task" loops.

Workflow States

Independent of the execution status lifecycle, a task can carry a customizable workflowStateId such as "Needs Review" or "Blocked on PM". See Workflow States for the registry, defaults, and CRUD API.

Billing Codes

Tag a task with billingCodes: string[] to roll cost into project-level reports. Codes flow through to usage records and aggregate via GET /api/usage/by-code. See Cost Tracking.