Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(core): local-first moves, the sender and windowed access [H21,H8]

Corey Olson6c828be6555f
diff --git a/docs/api.md b/docs/api.md
index 75b701f6..8d4b7c35 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -342,7 +342,7 @@ Only the coordinator sets or edits an item's `--check`. `pullboard check [id]` p
`relay on`, `relay`, and `relay off` share the relay result shape. Successful `pullboard relay recover --skip N` returns that same shape with optional `skipped: N` naming the explicitly refused sequence and `adopted: true` when it adopts a different authenticated person checkpoint that proves the same blocked refusal. Every relay result includes `recovery: { pending, skip, next }`; when a saved recovery is pending, `next` is the exact retry command. The `behind` count remains the number of pending uploads and does not include recovery. `status` includes this relay object alongside the local board summary. Human status and relay output show the recovery sequence and retry command when one is saved. The local `agent_last_shout_id` inbox read cursor is metadata: recovery ignores only that field in its guarded digest and preserves the greater valid cursor for matching agents. Other native changes remain protected; if a semantic local write changes while recovery is pending, the CLI preserves it and refuses automatic restoration. Exporting alone does not unblock that conflict; this prototype has no merge or discard command, so the person must reconcile the export and remote checkpoint before continuing. Successful results may include `diagnostics` for a relay refusal or inactivity notice; a local move still succeeds when its upload must wait. Device sign-in instructions are written immediately to stderr, including with `--json`, so the person can sign in before the command returns.
-With `"relay": { "outbox": true }` in the committed `pullboard.json` (off by default), a board move on a link whose baseline the relay accepted no longer fails while the relay is unavailable. The move is sealed into this machine's relay outbox in the order it was made, made on this machine at once, and the command exits 0. The relay result then carries `outbox: [{id, operation, item, actor, queuedAt}]`, counted in `behind`, and `pullboard show <id> --json` carries `relayPending` for the item's queued moves. The next command that reaches the relay replays the outbox first, in order: a move the relay already holds from a lost reply is not sent twice, and a move refused at replay, because another machine's move came first, is kept in `outboxRefusals: [{move, queuedAt, code, message, earlier: [{sequence, move}]}]` with the moves the relay ordered before it. While queued moves wait, `RELAY_OUTBOX_PENDING` refuses to apply other machines' moves underneath them.
+With `"relay": { "outbox": true }` in the committed `pullboard.json` (off by default), a linked board whose baseline the relay accepted is local first (#1013, H21): the local board is the source of truth and the relay is a mailbox. Every move except a registration, a takeover, a person's request and landing authority is sealed into this machine's relay outbox in the order it was made, made on this machine at once with no network call, and the command exits 0 whatever the relay or GitHub does. No command syncs or takes the relay lock before or after it runs; one background sender per machine sends the queued moves and pulls other machines' moves, for every local-first board on it. The relay result carries `outbox: [{id, operation, item, actor, queuedAt}]`, counted in `behind`, and `pullboard show <id> --json` carries `relayPending` for the item's queued moves. The sender sends the outbox in order: a move the relay already holds from a lost reply is not sent twice, and a move refused at replay, because another machine's move came first, is kept in `outboxRefusals: [{move, queuedAt, code, message, earlier: [{sequence, move}]}]` with the moves the relay ordered before it; its line names the winner (`won by sequence <n> <move>`), and the next command in the worktree of the agent that made the move prints it once. Other machines' moves are applied underneath the queued ones, which are then made again on top. The relay asks GitHub about a sign-in's access to a board once in each ten-minute window, for reads and writes alike, so lost access takes effect within ten minutes and no write waits on GitHub. Under the test runner the sender runs inside each command instead (`PULLBOARD_RELAY_SENDER_BACKGROUND=0`).
`relay on --all [--url <address>]` returns `{version, linked: [{project, root, board}], failed: [{project, root, reason}], paired, autoLink: true}`. Its status is nonzero when a project failed; successful links remain available. With no paired phone, the command prints one tappable pairing link and QR, then waits in the foreground up to ten minutes. Interruption or expiration leaves completed links intact and exits zero when no link failed. Every explicit invocation signs in afresh; no person session is retained on the Mac. Later project registrations publish one sealed phone-link proposal and keep working locally until its single approval tap. `doctor` and `resume` name the waiting project and its expiry; expiration requires an explicit fresh sign-in rather than silently asking again. `relay off` excludes that project from automatic linking; explicit `relay on` clears the exclusion.
diff --git a/docs/formats.md b/docs/formats.md
index 84e362fc..64e5d715 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -194,7 +194,9 @@ Engine 66 (`REOPEN_FIRST_REFUSAL_ENGINE`) holds a reopened item for its builder.
Engine 67 (`GATE_RUN_ENGINE`) records gate runs and the flake quarantine they prove. The gate writes a receipt for each real run of the accepted gate command on a clean, committed tree, under the common git directory at `pullboard/gate-receipts/<id>.json`: its id, kind (`gate`, `submit` or `land`), tree, head, accepted main, the command's SHA-256, its result, the committed file and name of each test that failed, the host load and the time. The writer is private to the gate and takes the result from the process it just ran; a run of any other command, or one whose checkout was dirty or moved, leaves no receipt. The coordinator's gate runs, from the main checkout and the landing, go on the board as `recordGateRun`; a seat's run keeps only its receipt. `recordGateRun` carries that receipt, and both a direct call and a sealed move are refused (`GATE_RUN_UNBOUND`) unless the store beside the board holds the same receipt byte for byte, so a run made up by hand is never recorded. A replayed move is applied as its origin checked it. When the coordinator's runs have found one tree both red and green for the same test, the board files one ordinary repair item for that test, with the runs as evidence, and records a `test-quarantine` event; a run any other seat recorded proves nothing. Quarantine itself is the coordinator's `flakes.quarantine` setting in pullboard.json, read from accepted main and off by default: with it off, runs and the repair item are still recorded, but nothing stops blocking a landing. With it on, a quarantined test still runs and reports, but a landing treats it as covered, like a waiver naming that file and test, as long as every run that proved it is a receipt on the landing machine and its repair item is not verified or withdrawn; it then blocks again, and only a newer red-and-green proof files a new item. A different red in the same run is never covered. An older engine refuses the move with `ENGINE_VERSION`.
-The relay outbox (#922, opt in with `relay.outbox`) lives beside `relay.json` as `relay-outbox.sealed`, mode 0600, sealed with the board key under the `outbox` seal kind at sequence 0. Inside is gzip JSON `{version: 1, base, baseSequence, restored, moves}`: `base` is the native board image as the relay last ordered it, at `baseSequence`, and each move is `{move, intent, queuedAt, after}` with the prepared engine move and the relay sequence this machine had seen. `relay.json` keeps only a key-free `outbox` summary and the last twenty `outboxRefusals`. A replay restores `base` (keeping each seat's newer shout-read position), catches up, then sends each move at the next sequence; if the relay fails part way, the board is sealed again as the relay has now ordered it and the remaining moves are applied on top. The outbox adds no engine version: every move still replays through the relay's order.
+The relay outbox (#922, opt in with `relay.outbox`) lives beside `relay.json` as `relay-outbox.sealed`, mode 0600, sealed with the board key under the `outbox` seal kind at sequence 0. Inside is gzip JSON `{version: 1, base, baseSequence, restored, moves}`: `base` is the native board image as the relay last ordered it, at `baseSequence`, and each move is `{move, intent, queuedAt, after}` with the prepared engine move and the relay sequence this machine had seen. Its key-free summary, the list `pullboard status` shows, is `relay-outbox.summary.json` beside it, and `relay-outbox.generation` counts every move ever queued there; `relay.json` keeps the last twenty `outboxRefusals` and `outboxRenumbered`, never the summary. A replay reads every record the relay ordered after `base` (or the relay's checkpoint when it compacted them), then rebuilds the board in one step: it restores `base` (keeping each seat's newer shout-read position), applies those records, settles each queued move whose receipt is now on the board, seals the result as the new `base`, and applies the moves still queued on top. Only then does it send the moves still queued, each at the next sequence, and read again. The outbox adds no engine version: every move still replays through the relay's order.
+
+Local first (#1013, H21): on a board with `relay.outbox` on whose baseline the relay accepted, every move except a registration, a takeover, a person's request and landing authority queues itself in the outbox and is made on this machine at once, with no network call. `relay-outbox.guard.sqlite`, beside the link, is held in an exclusive SQLite transaction while a move queues and while a replay rebuilds the board, never across a network call. A refusal found at replay is also left for the worktree of the agent that made the move, as one JSON string per line in `relay-conflicts/<digest>.txt` (the first 32 hex of the SHA-256 of the worktree path), which that worktree's next command prints and removes. One background sender per machine does the relay's work, under `relay-sender/` in the machine's pullboard home: `sender.pid` is its claim (refreshed while it runs), `sender.starting` marks one being started, `sender.log` is its short log, and `boards/<digest>.json` is `{root, file, due}` for each board a command nudged, named by the first 32 hex of the SHA-256 of the link file's path.
Engine 69 (`REVIEW_SKIP_ENGINE`) lets `reserveNextReview` carry `skipIds`: the submitted items the reviewer's own agent session built, which `pullboard next --verify` never offers it. A move with a non-empty `skipIds` needs engine 69, so an older reader refuses it instead of reserving a different item; moves without `skipIds`, and every move recorded before engine 69, replay as before.