slot-claim

Every routine run, desktop or cloud, claims its Slot on the routine's Claim register (an
open issue in the routine's own repo) before it does anything else. The earliest claim wins; every
other run quits in seconds. Terms: aac-routines CONTEXT.md (Fallback Routine, Slot, Slot claim,
Claim register, Claim limit, Takeover). Design: claude-dotfiles issue 1443.

The routine's prompt supplies its values; pass them on every call as ROUTINE:

--repo <owner/name> --issue <register issue> --cron "<m h dom mon dow>" --limit <90m> --deadline <3h>

--venue local on a desktop (it names the claimant local:<computer name>), --venue cloud in a
Fallback Routine. The script prints one JSON object; its header lists every flag and exit code.

Steps

1. Claim, first thing.

   node "<skill base directory>/slot-claim.js" claim <routine> --venue local|cloud ROUTINE

   It waits about 10 seconds before answering. Keep slot and claim from the output.

   • Exit 0: you hold the slot. Go on.
   • Exit 4: you took the slot over from a stalled run. Send the output's notice to Dan with
     your push-notification tool, then go on; step 2 tells you which writes the stalled run made.
   • Exit 1 (lost, or the slot is done) or 3 (past its deadline, recorded missed): stop. Report the
     result and reason in one line and do no work.
   • Exit 2: stop and report the error. Never do the work unclaimed.

   Done when the claim exited 0 or 4, or the run has stopped.

2. Before every external write (email, Todoist change, push, file upload, page publish,
   cross-repo comment), recheck with that write's stable key:

   node "<skill base directory>/slot-claim.js" recheck <routine> <slot> --key <key> --claim <claim> --venue local|cloud ROUTINE

   A key names the write the same way on every run of the slot: email:<subject-slug>,
   todoist:<task id>, file:<name>, commit:<branch>, page:<name>. No spaces.

   • Exit 0: write. When the output says takeover: true, first look for this key's write at its
     destination (the email in Sent, the file by name, the commit on the branch) and skip it if
     it landed.
   • Exit 5: this key is already marked written. Skip the write and go on.
   • Exit 1: stop now, before the write. You lost the slot, or your claim passed its Claim limit,
     or the slot passed its deadline. Report the reason.

   Done when every write was preceded by a recheck that exited 0 or 5.

3. Right after each write, mark it:

   node "<skill base directory>/slot-claim.js" mark <routine> <slot> <key> --note "<what was written>" --claim <claim> --venue local|cloud ROUTINE

   Done when every write that landed has a marker.

4. Post done after the completion summary (triage: as soon as its status and Day Board
   publish, before Dan answers):

   node "<skill base directory>/slot-claim.js" done <routine> <slot> --claim <claim> --venue local|cloud ROUTINE

   Done when it exited 0. Exit 1 means another run holds the slot: report that, post nothing more.

Reading a register

slot-claim.js status [<routine>] --repo <owner/name> --issue <n> [--limit ..] [--deadline ..]
lists every slot with its state (done, held, expired, past-deadline, missed), holder and
write markers. Each comment's first line is plain text, so the issue itself reads as an audit log.

GitHub is reached over REST only, on the routine's own repo: no gh needed. The token is
GH_TOKEN or GITHUB_TOKEN; a cloud container's egress proxy authenticates without one.