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(relay): distinguish acknowledged canary probes [H21]

Corey Olson4cc9bba99632
diff --git a/docs/api.md b/docs/api.md
index b8f2d257..a988f20e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -347,7 +347,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.
-A linked board whose baseline the relay accepted is local first by default (#1013, H21), including existing boards whose committed `pullboard.json` has no outbox setting. A coordinator can opt out with `"relay": { "outbox": false }`. With local-first enabled, ordinary authorized moves use the local board as the source of truth and the relay as a mailbox. Each is sealed into this machine's relay outbox in the order it was made, applied on this machine at once with no network call, and returns without waiting for relay or GitHub. Authority and bootstrap operations remain acknowledged exceptions: `register`/`ensureCoordinator`, `takeover`, landing-fence operations, and person requests wait for their required authority. Every move in an environment-token session also waits for relay acknowledgment: CI and other ephemeral jobs cannot retain an outbox after they exit, so local-first applies to persistent person and agent devices. One background sender per machine sends 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 ordinary move waits on GitHub. Under the test runner the sender runs inside each command instead (`PULLBOARD_RELAY_SENDER_BACKGROUND=0`).
+A linked board whose baseline the relay accepted is local first by default (#1013, H21), including existing boards whose committed `pullboard.json` has no outbox setting. A coordinator can opt out with `"relay": { "outbox": false }`. With local-first enabled, ordinary authorized moves use the local board as the source of truth and the relay as a mailbox. Each is sealed into this machine's relay outbox in the order it was made, applied on this machine at once with no network call, and returns without waiting for relay or GitHub. Authority and bootstrap operations remain acknowledged exceptions: `register`/`ensureCoordinator`, `takeover`, landing-fence operations, and person requests wait for their required authority. An explicit relay canary (`io.relayCanary`) also waits for acknowledgment, because it measures the relay rather than local execution. Every move in an environment-token session also waits for relay acknowledgment: CI and other ephemeral jobs cannot retain an outbox after they exit, so local-first applies to persistent person and agent devices. One background sender per machine sends 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 ordinary move 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 4a19b24e..45e39f04 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -196,7 +196,7 @@ Engine 67 (`GATE_RUN_ENGINE`) records gate runs and the flake quarantine they pr
The 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. It is enabled by default; committed `relay.outbox: false` opts out. Inside is gzip JSON `{version: 3, baseSequence, restored, moves, results}`: `baseSequence` is the relay sequence the queued moves sit on, and each move is `{move, refs, intent, queuedAt, after, sequences, changes}` with the prepared engine move, the relay sequence this machine had seen, the board's `sqlite_sequence` rows just before the move, and the base64 SQLite changesets of the rows it changed here. An outbox written before #1013 is version 1 or 2 and also holds `base`, the native board image at `baseSequence`, and is replayed from that image until it empties. 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 `baseSequence`, then rebuilds the board in one step: it takes the queued moves back by their inverted changesets, newest first, with the lifecycle triggers lifted in that transaction only, and puts `sqlite_sequence` back (keeping each seat's newer shout-read position); applies those records; settles each queued move whose receipt is now on the board; and makes the moves still queued again on top, capturing their rows afresh. When the moves cannot be taken back row for row, the relay's checkpoint stands in, if it is no older than `baseSequence`. 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 whose baseline the relay accepted, ordinary authorized moves queue themselves in the outbox and are made on this machine at once, with no network call. `register`/`ensureCoordinator`, `takeover`, landing-fence operations and person requests remain acknowledged authority exceptions; those may wait for relay authorization. All moves in environment-token sessions remain relay-acknowledged too: an ephemeral CI or cloud job cannot retain queued moves after it exits, so only persistent person and agent devices use local-first. `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.
+Local first (#1013, H21): on a board whose baseline the relay accepted, ordinary authorized moves queue themselves in the outbox and are made on this machine at once, with no network call. `register`/`ensureCoordinator`, `takeover`, landing-fence operations and person requests remain acknowledged authority exceptions; those may wait for relay authorization. An explicit relay canary (`io.relayCanary`) also requires acknowledgment, because it measures the relay. All moves in environment-token sessions remain relay-acknowledged too: an ephemeral CI or cloud job cannot retain queued moves after it exits, so only persistent person and agent devices use local-first. `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.