ROADMAP-10 — P1 — Background runs, cancellation endpoint and RunStatus.CANCELED #102

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M15-T03 · Priority: P1 · Effort: large (design note first)

Problem

POST /runs executes the whole agent loop inside the HTTP request (up to RUN_TIMEOUT_S=60s+). Clients sit blind, LBs and proxies may cut the connection (see ROADMAP-01), long runs occupy a worker. A short design note in docs/ should be approved before implementation so the in-request mode stays the default.

This issue fixes three review findings in one design: synchronous-only execution, no cancellation endpoint, and the missing CANCELED status.

Evidence

• agentkit/api/routes.py:59 — in-request execution
• agentkit/core/types.py:6–16 — no CANCELED in RunStatus
• cancellation handling itself (BaseException path) is ROADMAP-01 — this issue is the API/lifecycle layer on top

Acceptance criteria (after design note)

• background: true mode returns run_id immediately (queued/pending), agent runs in a tracked asyncio task
• RunStatus.CANCELED added; POST /runs/{run_id}:cancel transitions a live run cooperatively
• Stale running rows detectable via updated_at heartbeat; documented sweep/reaper transitions them to failed
• Sync mode unchanged and still tested

Suggested branch / commit

feat/async-run-lifecycle · feat(api): background runs with cooperative cancellation