feat: Cancel queued and running work items #280

Parent

#276

What to build

An admin can cancel work:

• a queued item ends Cancelled immediately and never starts;
• a running item gets a cancel request. The worker's next heartbeat picks it up and cancels the handler's token, and the item ends Cancelled with the results that attempt produced, marked as partial.

Acceptance criteria

• POST /api/v1/admin/work-items/{id}/cancel (admin role only):
  • a queued item becomes Cancelled in one atomic, status-guarded update;
  • a running item gets CancelRequestedAt;
  • an already finished item returns 409;
  • an unknown id returns 404.
• The heartbeat reads CancelRequestedAt, and the executor cancels the handler when it is set. The item ends Cancelled, fenced by Attempt.
• A cancelled item's results are shown and marked partial: in the detail endpoint if it exists by then, or otherwise in the item's stored state.
• A cancel racing with a claim never loses the cancel: either the queued item is cancelled or the running item sees the request. Covered by a contract test on real PostgreSQL.
• Architecture rule: the API's only write to work items is cancel. Shown failing on a deliberate violation.
• Unit tests: the executor cancels on a cancel request, and the endpoint returns the right status codes.
• 100% mutation score outside PostgreSQL-only members, which get ADR 0005 rows.

First caller

The cancel endpoint, used on the TokenCleanup and WorkItemRetention items. The crawl and #174's sweep are the long-running items it exists for.

Design

Decided with the maintainer on 2026-10-18: cooperative cancel at the heartbeat, partial results kept on cancel. Recorded in ADR 0008 and #276's Implementation Decisions ("Execution" and "Admin API").