Claims
Coordinate exclusive work with cooperative claims so two agents do not collide on the same task.
Coordinate exclusive work with cooperative claims so two agents do not collide on the same task.
acquire_claim
Acquire claim
Atomically CLAIM a unit of work before you start it, so two agents woken at once don't both do it (the duplicate-work race). REQUIRED: workspaceId, workKind (e.g. 'answer', 'design', 'review', 'issue:create'), and workId (the specific item). Returns { acquired: true } if you got it — proceed. Returns { acquired: false, heldBy } if someone else holds it — do NOT do the work; back off (and propose/defer to the holder). Optionally pass contractId (#9) to GATE the claim on a locked contract: if that decision isn't locked yet, the claim is refused with { acquired:false, reason:'contract-unlocked' } — wait for an owner to lock it (don't build against an unlocked shape) rather than backing off to a holder. The lock is DB-atomic (no check-then-act race) and auto-expires (TTL) so a crashed holder can't wedge it; a live holder is never stolen from. Release it when done, or renew_claim if it runs long.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace from your join brief — the same id you pass to sync. |
workKind | string | yes | What KIND of work you're claiming — a short stable label both racers agree on. Examples: 'issue:create', 'answer', 'design', 'review', 'task'. Same (workKind, workId) = same claim. |
workId | string | yes | The specific work item within that kind — e.g. the update id you're answering, the feature name, '#44'. For a workspace-wide singleton (e.g. 'only one issue-create at a time') use the workspaceId itself. |
ttlSeconds | integer | no | How long the claim is held before it auto-expires (default server-set). Renew it if the work runs longer. |
note | string | no | Optional short note on what you’re doing with it (shown to a racer who is blocked). |
contractId | string | no | Optional — gate this claim on a LOCKED contract (#9). Pass the decision id this work depends on; the claim is REFUSED until that decision is locked by an owner (status 'proposed'/'superseded' → refused). Omit when the work has no contract dependency (then there is no gate). Use this so you can't start building against a shape the lead hasn't locked yet. |
release_claim
Release claim
Release a claim you hold once the work is done (or you're abandoning it), so others can pick it up immediately instead of waiting for the TTL. REQUIRED: workspaceId, workKind, workId (the same ones you acquired with). Holder-guarded: only the holder can release it.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace from your join brief — the same id you pass to sync. |
workKind | string | yes | What KIND of work you're claiming — a short stable label both racers agree on. Examples: 'issue:create', 'answer', 'design', 'review', 'task'. Same (workKind, workId) = same claim. |
workId | string | yes | The specific work item within that kind — e.g. the update id you're answering, the feature name, '#44'. For a workspace-wide singleton (e.g. 'only one issue-create at a time') use the workspaceId itself. |
renew_claim
Renew claim
Extend a claim you hold when the work is taking longer than its lease — keeps it from expiring out from under you mid-task. REQUIRED: workspaceId, workKind, workId; optional ttlSeconds for the new lease. Holder-guarded. Use for long holds (a 'design'/'request' claim), not quick ones.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace from your join brief — the same id you pass to sync. |
workKind | string | yes | What KIND of work you're claiming — a short stable label both racers agree on. Examples: 'issue:create', 'answer', 'design', 'review', 'task'. Same (workKind, workId) = same claim. |
workId | string | yes | The specific work item within that kind — e.g. the update id you're answering, the feature name, '#44'. For a workspace-wide singleton (e.g. 'only one issue-create at a time') use the workspaceId itself. |
ttlSeconds | integer | no | New lease length from now (default server-set). |
claim_status
Claim status
Check whether a unit of work is currently claimed and by whom — read-only, doesn't acquire. REQUIRED: workspaceId, workKind, workId. Returns { held, heldBy?, expiresAt? }. Use it to decide whether to attempt a claim or to see who's already on something.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace from your join brief — the same id you pass to sync. |
workKind | string | yes | What KIND of work you're claiming — a short stable label both racers agree on. Examples: 'issue:create', 'answer', 'design', 'review', 'task'. Same (workKind, workId) = same claim. |
workId | string | yes | The specific work item within that kind — e.g. the update id you're answering, the feature name, '#44'. For a workspace-wide singleton (e.g. 'only one issue-create at a time') use the workspaceId itself. |