Claim a ledger item before you start

One seat, one checklist item, atomically — so two sessions never open the same item.

Prompt#

Claim item 12 on LEDGER-R4 before you start, and release it if you don't finish.

What the Chair does#

Takes the shared lock named ledger:<relpath>#12 with your session as holder. No new table, no rewrite of the Markdown file.

MCP calls#

task_claim({
  "ledger":  ".workflow/LEDGER-R4-DOCS.md",
  "item":    12,
  "holder":  "<your session id>",
  "ttl_min": 60
})

When you stop without closing it:

task_release({ "ledger": ".workflow/LEDGER-R4-DOCS.md", "item": 12, "holder": "<your session id>" })

CLI equivalent, for a shell without MCP:

orch task claim .workflow/LEDGER-R4-DOCS.md 12 --holder <session> --ttl-min 60
orch task release .workflow/LEDGER-R4-DOCS.md 12 --holder <session>
orch ledger board .workflow/LEDGER-R4-DOCS.md   # prints the file with (claimed: <session>)

Expected response#

task_claim returns the lock row as JSON — name, holder, expiry. task_release returns the plain string released. The CLI prints claimed name=ledger:.workflow/LEDGER-R4-DOCS.md#12 holder=… until=….

Gotchas#

  • Any seat may claim. Unlike task_add / task_run / dispatch_worker, claiming is not fan-out, so a worker calling task_claim is not denied.
  • All three of ledger, item, holder are required, and item must be an integer — the number in - [ ] 12., not the text of the line.
  • holder is your session id from .orch/ORCH_RUNTIME.md. Invent one and the release will not match.
  • Default TTL is 15 minutes. Long items should pass ttl_min or re-claim; an expired claim is free for the next seat to take.
  • Another live session holding it fails clearly with the holder named. That is the answer, not an obstacle — pick another item or message the holder with msg_send.
  • The ledger file is never rewritten by the claim. orch ledger board shows the claims next to the items; ticking the box is still your edit.
  • Releasing with holder: "*" forces a release when a session died holding the item.