Coordination: work that keeps its owner

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

What it is for

A queue item is one unit of owned work: a row in the daemon's database with a destination seat, a body, a state and an append-only history of transitions. It survives the owner's turn ending, the owner compacting and the owner being replaced. A seat cannot close work without saying where it went, and handing work to another seat closes yours and opens theirs in one transaction, so nothing strands between seats. Durable does not mean automatic: a row can still need a person or a peer to notice it. What the queue guarantees is that the work stays recorded and attributable, with an owner and a history, whatever happens to the seats.

Around the queue sit three smaller surfaces. A stream is an append-only intake log for observations nobody has to act on yet. A view is a named lens over coordination state, such as what is held, what is waiting on a person, or which claimed rows have stalled. A project record turns a raw observation into a routed, typed, deduplicated row instead of a hand-made one.

The three verbs you will use first

Create a row for a seat. The destination is the seat that owns the work (help sometimes says "node" for a seat's position in the running rig). Multiline bodies go through --body-file; --mission and --slice attach the work to the work tree as tags.

rig queue create --destination dev-impl@my-rig --body-file brief.md --mission search-experience --slice 01-search-page

Claim it, then close it honestly. Claim moves pending to in-progress. Closing to done requires a closure reason from a fixed set: handed_off_to, blocked_on, denied, canceled, no-follow-on, escalation. A note without --state never changes state. Closure records delivery, not acceptance; acceptance is the next stage's verdict on its own row.

rig queue claim qitem-20260901100000-abcd1234
rig queue update qitem-20260901100000-abcd1234 --note "matching any title word, not the whole phrase"
rig queue update qitem-20260901100000-abcd1234 --state done --closure-reason no-follow-on --note "accepted, one loose end"

Hand it on. One transaction: the source row closes as handed-off and a new row opens at --to. Omit the body to carry the source body forward.

rig queue handoff qitem-20260901100000-abcd1234 --to build-checker@my-rig --note "candidate ready; keyboard path per requirement 2"

Reading the board

rig queue list defaults to active rows in your current rig, like docker ps; -a adds history and -A crosses rigs. --owned shows only the obligations assigned to you. rig queue show <id> gives a bounded preview; --full --json prints the complete item record without truncation. It is the item, not its history: the transitions are a separate read. rig queue transitions <id> is the audit trail of what happened to a row. rig view show held lists what is parked and on what; rig view show escalations lists what waits on a person; rig view show pickup derives whether a claimed row is working, stalled after claim, parked or unclaimed.

Parking on a real blocker

rig queue block <id> --on <blocker> parks a row as held with a continuation and one live wake, either a watchdog job or a timer (--wake-after 15m). A park on a human seat needs a plain-language summary and a durable evidence reference, because a person will judge it. Closing a blocked row would be a lie; sitting on it silently looks identical to a crash. rig queue resolve writes the decision onto the row and wakes the owner.

Command	What it does (from help)	Help source
rig project	Coordination L2 , agent-backed classifier with daemon-enforced lease + idempotency + reclaim	project.txt
rig project classify	Project a stream item with classification fields (idempotent on stream_item_id; requires active lease)	project.classify.txt
rig project lease-acquire	Acquire the active classifier lease for the caller	project.lease-acquire.txt
rig project lease-heartbeat	Send a heartbeat for an active classifier lease (extends TTL)	project.lease-heartbeat.txt
rig project lease-show	Show the currently-active classifier lease	project.lease-show.txt
rig project list	List project classifications with filters	project.list.txt
rig project reclaim-classifier	Operator-verb: reclaim the active classifier lease. Use --if-dead to refuse if holder is still alive.	project.reclaim-classifier.txt
rig project show	Show one project classification	project.show.txt
rig queue	Coordination L3 , owned-work queue + inbox/outbox	queue.txt
rig queue block	Park a qitem as HELD with a continuation and wake. Choose a watchdog id, timer, or live blocker.	queue.block.txt
rig queue claim	Claim a qitem (pending → in-progress); computes closure_required_at from tier	queue.claim.txt
rig queue create	Create a new qitem	queue.create.txt
rig queue fallback	Reroute a qitem to a fallback destination (e.g. unreachable seat)	queue.fallback.txt
rig queue handoff	Transactional handoff: closes source as handed-off + creates new qitem owned by --to	queue.handoff.txt
rig queue handoff-and-complete	Atomic close (state=done, closure_reason=handed_off_to) + create new qitem owned by --to. Variant of handoff that fully terminates the source qitem.	queue.handoff-and-complete.txt
rig queue inbox-absorb	Absorb a pending inbox entry into the receiver's main queue	queue.inbox-absorb.txt
rig queue inbox-deny	Deny a pending inbox entry with a recorded reason	queue.inbox-deny.txt
rig queue inbox-drop	Drop a mailbox-style entry into a destination's inbox	queue.inbox-drop.txt
rig queue inbox-pending	List pending inbox entries for a destination seat	queue.inbox-pending.txt
rig queue list	List qitems (default: active + compact + current-rig; like 'docker ps')	queue.list.txt
rig queue outbox-list	List outbox entries for a sender seat	queue.outbox-list.txt
rig queue outbox-record	Record an outbound dispatch in the sender's outbox	queue.outbox-record.txt
rig queue overdue	List in-progress qitems past their closure_required_at deadline (current rig, bounded, body-free by default)	queue.overdue.txt
rig queue resolve	Resolve a leg-1 parked qitem (state=blocked on a human seat): records the decision text durably in queue_transitions, unparks blocked -> in-progress, and nudges the owner. Non-closure.	queue.resolve.txt
rig queue show	Show one qitem and its derived waiting state (bounded preview; --full for complete body)	queue.show.txt
rig queue transitions	Show the append-only transition log for a qitem	queue.transitions.txt
rig queue unclaim	Release a claimed qitem (in-progress → pending)	queue.unclaim.txt
rig queue undelivered	List PENDING qitems whose create-path nudge FAILED (delivery never reached the destination; current rig, bounded, body-free by default)	queue.undelivered.txt
rig queue update	Append a note and/or mutate qitem state. A note without --state never changes row state. state=done REQUIRES --closure-reason (one of: handed_off_to, blocked_on, denied, canceled, no-follow-on, escalation). Closure ≠ acceptance: handed_off_to records delivery to the next stage; acceptance is the next stage's verdict on its own qitem, not this closure.	queue.update.txt
rig queue whoami	Show the caller's queue position from the daemon's perspective	queue.whoami.txt
rig stream	Coordination L1 , append-only intake stream	stream.txt
rig stream archive	Soft-archive a stream item (audit row preserved)	stream.archive.txt
rig stream emit	Append a stream item	stream.emit.txt
rig stream list	List stream items chronologically	stream.list.txt
rig stream show	Fetch one stream item by id	stream.show.txt
rig stream watch	Watch the stream (initial replay + live items)	stream.watch.txt
rig view	Coordination L5 , daemon-backed views over coordination state	view.txt
rig view list	List built-in + custom views	view.list.txt
rig view register	Register or update a custom view	view.register.txt
rig view show	Run a view (built-in or custom). Built-in views: recently-active, founder, pod-load, escalations, held, activity, pickup	view.show.txt

What it does not do

• Closing a row is not acceptance. handed_off_to records delivery; the receiver's own verdict lives on the receiver's row.
• A message (rig send) is not a row. If another seat must act, create or hand off a row.
• queue list reports up to its --limit (default 100); a board can be larger. Confirm the returned count is under the limit before claiming nothing is held.
• Tags and priority are set at create or handoff; the list view is a projection and show --full is the record.

Where it goes next

• Workflows: a declared spec that projects the next row when a step closes, so you stop relaying.
• The terminal UI: attention and pickup are these rows seen from the operator's side.
• Messaging: the informing channel that sits beside the obligating one.

Read as Markdown