Module work_queue 

Muxqueue HTTP surface — slice 2 of docs/reports/REPORT_UNIVERSAL_AGENT_WORK_QUEUE_2026_09_01.md.

POST /agentmux/work — enqueue POST /agentmux/work/claim — claim the next eligible item POST /agentmux/work/:id/heartbeat — extend a lease POST /agentmux/work/:id/complete — finish POST /agentmux/work/:id/release — give back GET /agentmux/work — list DELETE /agentmux/work/:id — cancel

Auth-gated by the same middleware as the cron and reactive routes.

Store choice: every handler uses state.identity_store — the always-global store — NOT state.shared_store, which is what the cron handlers next door still use. That difference is deliberate, not an inconsistency to tidy up later: a per-channel queue would only ever mean “any agent in this channel can pick it up”. Cron’s own placement is a known unmigrated case (SPEC_IDENTITY_STORE_SPLIT_2026_08_17.md step 1b).

Structs

CancelRequest 🔒

ClaimRequest 🔒

EnqueueRequest 🔒

HolderRequest 🔒

ListQuery 🔒

Constants

DEFAULT_LEASE_MS 🔒

Default lease granted by a claim, and the window a heartbeat extends by. Deliberately short relative to a long agent turn: a claimant is expected to heartbeat, and a crashed one should return to the pool in about a minute rather than blocking the item for an hour.

Functions

claimer_uid 🔒

An Unattributed claimer’s UID: carried, else its block’s row, else "" (name path only). An attributed claim uses its Caller’s UID instead — see handle_work_claim.

count_holder_match 🔒

Count a holder check that matched by name — the row or the caller had no UID. Each is a holder that M5, which drops the name path, would refuse.

err 🔒

handle_work_cancel 🔒

The body is OPTIONAL (reagent P1 on PR #2902). The sibling DELETE route in the same router — DELETE /agentmux/cron/:id — takes no body at all, so a caller following that adjacent, established convention would otherwise get a 400/415 from axum’s Json extractor rather than the intended “cancel with an empty reason”. CancelRequest::reason is already #[serde(default)]; making the whole body optional is what actually lets that default be reached.

handle_work_claim 🔒

handle_work_complete 🔒

handle_work_enqueue 🔒

handle_work_heartbeat 🔒

handle_work_list 🔒

handle_work_release 🔒

Returns the item’s RESULTING state alongside ok (Codex P2 on PR #2902). A release on the item’s final allowed attempt parks it as failed rather than reopening it, so a bare {ok:true} would let the caller report “handed back to the queue” for an item nobody can ever claim again.

holder_result 🔒

Shared shape for the three holder-only transitions. No match from the store means the caller is not the current holder OR its fence is stale — both are CONFLICT, not NOT_FOUND: the row usually still exists, it just moved on without this caller.

holder_uid 🔒

The caller’s UID for a holder check (identity M4c-2, spec §6.5.9): the token’s, or "" when Unattributed — the store then matches by name.

publish_changed 🔒