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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(relay): a move waits in an outbox while the relay is down [B26,H16]
Corey Olson34f8510c5bcf
diff --git a/docs/api.md b/docs/api.mdindex 672fb25b..7f8c1259 100644--- a/docs/api.md+++ b/docs/api.md@@ -313,6 +313,8 @@ 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.+`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.`relay devices` returns `{version, devices: [{deviceId, pairedHere, label, createdAt, seen, revoked, boards}], computers: [{machine, host, created, seen, boards}]}` without a private key or credential. `devices` are the phones that read this computer's linked boards; `computers` are the other computers that joined one of them with `relay join`. Only the computer that paired a phone keeps its `label` and `createdAt`; a phone paired on another computer has `pairedHere: false`, null `label` and `createdAt`, and prints as paired on another computer with the end of its id. `seen` is the last relay contact in epoch milliseconds, or null when unknown, `revoked` is the relay's revocation status, and `boards` names the linked boards each one can read. The text output names each one with its paired date, last seen and boards. `--verbose` adds ids in the text and, for phones paired here, the key `fingerprint` in both text and JSON. `relay revoke <deviceId>` returns `{version, deviceId, revoked: true, notice}` after removing the local recipient and deleting its remote wraps. Native revocation never asks the target device to approve its own removal. Another paired phone can approve it with a short-lived, single-use, RAM-only grant for that exact target. With no other paired approver or no linked publishing board, the person completes a fresh GitHub device-code sign-in on the computer instead. The authenticated account and relay origin must match the saved enrollment; the fresh session stays in memory and is revoked after the action. Agent terminals are refused before any sign-in or network request. A failed or interrupted approval or sign-in needs an explicit retry. Revocation stops future wrapping and refuses the removed browser’s enrolled session with `DEVICE_REVOKED` (HTTP 403), including snapshot/event reads and auth-session, board-list and token-list reads. That same principal boundary refuses its machine or agent credential issuance, so the removed session cannot mint another reader. The public board-free shell still loads to clear local browser data; it grants no person actions. Its next connected page clears the locally held board keys, private device key and board request cache and shows that it was removed; reload retains the refusal. The relay stores only public session ids tied to the enrollment, never an extra bearer credential. A fresh GitHub sign-in remains eligible for recovery; it does not resurrect the revoked device. An offline copy cannot be remotely erased and board key rotation remains separate (#346).diff --git a/docs/formats.md b/docs/formats.mdindex aefacdd1..c152a7fa 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -180,6 +180,8 @@ Engine 63 (`RECURRING_JOB_ENGINE`) records recurring jobs. `declareJob` is the cEngine 64 (`LOCAL_LANDING_ENGINE`) lets a landing batch reach the state `trunk`: merged onto the local trunk after its quick guards (the static checks and submit invariants), with each item's merged receipt recorded before anything is pushed. Only a board whose `pullboard.json` sets `landing: { "publish": "separate" }` lands this way; `pullboard publish` then runs the whole suite on the exact trunk head and pushes only a green head. A batch recorded at an older engine still needs `pushed` before its receipts.+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 CLI declares its engine in every relay request's `X-Pullboard-Engine` header.A linked board requires at least engine 48 after issuing any agent token or machine credential, includingrevoked or expired ones; before engine 48 these minimums were 3 and 6. The minimum survives reopening the auth database;diff --git a/src/cli.js b/src/cli.jsindex 35d95eb0..8ad6c31a 100644--- a/src/cli.js+++ b/src/cli.js@@ -59,6 +59,7 @@ import {COORDINATOR,DOCTRINE_FILE,LEGACY_DOCTRINE_FILE,+ configFromSource,loadConfig,} from './config.js';import { displayAgentName } from './agent-names.js';@@ -864,7 +865,16 @@ export async function reserveRow(ctx, row, written) {/** Note the session behind a claim or submit (#921): its ledger must be writable before the move, and record after it. */async function withItemSession(info, operation, args, move) { const noted = operation === 'claim' || operation === 'submit'; if (noted) itemSessions.requireLedger(info); const result = await move(); if (noted) itemSessions.recordItemSession(info, args[0], operation); return result; }+/**+ * Whether the board's committed relay.outbox setting queues moves while the relay is down (#922).+ * Why: it is read from the trunk's pullboard.json, so every machine on the board follows the same committed choice.+ */+function relayOutboxSetting(root) {+ try { return configFromSource(coordinatorFile(root, CONFIG_FILE).stdout).relay?.outbox === true; } catch { return false; }+}+export async function ordered(ctx, board, operation, args) {+ ctx.io.relayOutbox ??= () => relayOutboxSetting(ctx.info.root);// Every engine-27 registration records the seat that made it: the coordinator from the main// checkout, the joined agent from its worktree, or `machine` for a join no seat made (#579).if (operation === 'register' && args[0] && args[0].createdBy === undefined) {@@ -2314,6 +2324,7 @@ async function runMain(argv, streams) {/** A network refusal preserves offline reads; linked mutation dispatch requires an acknowledgement. */const retry = async () => {try {+ io.relayOutbox ??= () => relayOutboxSetting(io.cwd);await syncRelay(io.cwd, io);await retryCheckBaselines(io.cwd, io);}diff --git a/src/commands/show.js b/src/commands/show.jsindex c83e18be..08b77dce 100644--- a/src/commands/show.js+++ b/src/commands/show.js@@ -28,6 +28,7 @@ import {sayBrief,withBoard,} from '../cli.js';+import { relayStatus } from '../relay.js';/** Run `pullboard show` and return its exit code. */export function run(io, { first, values }) {@@ -43,8 +44,10 @@ export function run(io, { first, values }) {agents: store.listAgents(board), mainMerge: mainMergeFor(board, id), infra: infraNotes.infraNoteOf(store.events(board, { itemId: id })),}));const agentName = (id) => displayAgentName(agents.find((agent) => agent.agent_id === id) ?? { agent_id: id }, ctx.config.agents.names);+ // #922: moves on this item made while the relay was down wait in this machine's relay outbox until it answers.+ const relayPending = (relayStatus(ctx.info.root).outbox ?? []).filter((move) => move.item === id);if (values.json) {- io.result({ ...item, verdicts, thread });+ io.result({ ...item, verdicts, thread, ...(relayPending.length ? { relayPending } : {}) });return 0;}io.say(itemLine(item, agentName, Boolean(mainMerge)));@@ -53,6 +56,7 @@ export function run(io, { first, values }) {if (item.item_check) io.say(`check: ${item.item_check}`);sayCheckBaseline(io, item);sayBrief(io, item.item_brief);+ for (const move of relayPending) io.say(`pending in the relay outbox: ${move.operation}${move.actor ? ` by ${move.actor}` : ''} (made ${move.queuedAt}); it goes up in order when the relay answers`);for (const { item: other, shared } of related) {io.say(`related: #${other.item_id} ${other.item_title}: ${shared.slice(0, 4).join(', ')}${shared.length > 4 ? ', ...' : ''} (git log -p -1 ${other.item_commit.slice(0, 12)} -- ${shared[0]})`);}diff --git a/src/config.js b/src/config.jsindex 11663957..7465250c 100644--- a/src/config.js+++ b/src/config.js@@ -174,6 +174,9 @@ export function configProblems(config) {if (config.flakes !== undefined && (!config.flakes || typeof config.flakes !== 'object' || Array.isArray(config.flakes)|| config.flakes.rerun !== undefined && typeof config.flakes.rerun !== 'boolean'|| Object.keys(config.flakes).some(key => key !== 'rerun'))) problems.push('"flakes" has only the optional boolean "rerun", off by default');+ if (config.relay !== undefined && (!config.relay || typeof config.relay !== 'object' || Array.isArray(config.relay)+ || config.relay.outbox !== undefined && typeof config.relay.outbox !== 'boolean'+ || Object.keys(config.relay).some(key => key !== 'outbox'))) problems.push('"relay" has only the optional boolean "outbox", off by default');if (!['inside', 'beside'].includes(config.worktrees)) problems.push('"worktrees" is "inside" or "beside"');if (config.submitGate !== undefined && config.submitGate !== 'landing') {problems.push('"submitGate" is "landing" when the full suite should be deferred until landing');diff --git a/src/engine.js b/src/engine.jsindex cf13518b..4d4588ee 100644--- a/src/engine.js+++ b/src/engine.js@@ -187,7 +187,7 @@ function validateMove(move) {}/** Restore only the frozen criterion callback; no receiver runs another machine's Git or shell. */-function executableArgs(move, board) {+export function executableArgs(move, board) {const args = structuredClone(move.args);if (move.operation === 'appendFact') {if (!args[1] || typeof args[1] !== 'object' || Array.isArray(args[1])) throw new Refused('RELAY_MOVE', 'a fact needs its typed arguments; use the current Pullboard engine');diff --git a/src/next-steps.js b/src/next-steps.jsindex f34f68f5..783e2485 100644--- a/src/next-steps.js+++ b/src/next-steps.js@@ -449,6 +449,8 @@ export const NEXT_STEPS = Object.freeze({RELAY_BASELINE_UNCERTAIN: 'run the command again when the relay answers; it first checks whether the relay kept the board upload',RELAY_BOARD_DELETED: 'keep working locally, or run pullboard relay on to link the board again',RELAY_BUSY: 'run the command again after the other worktree finishes sending',+ RELAY_OUTBOX: 'keep the relay-outbox.sealed file and the board as they are, then ask for help before relinking',+ RELAY_OUTBOX_PENDING: 'run pullboard status once the relay answers; it sends the queued moves in order first',RELAY_CURSOR: 'fetch a consistent snapshot: pullboard relay',RELAY_DIVERGED: 'run pullboard relay off, then pullboard relay on to link again from this machine',RELAY_KEYCHAIN: 'unlock the system keychain, then run the command again',diff --git a/src/relay-outbox.js b/src/relay-outbox.jsnew file mode 100644index 00000000..b5d61955--- /dev/null+++ b/src/relay-outbox.js@@ -0,0 +1,123 @@+/**+ * The ordered outbox (#922): board moves made on an accepted relay link while the relay is unavailable, sealed on+ * this machine with the board as the relay last ordered it, until they replay in relay order.+ */+import { randomUUID } from 'node:crypto';+import {+ existsSync,+ mkdirSync,+ readFileSync,+ renameSync,+ rmSync,+ writeFileSync,+} from 'node:fs';+import {+ dirname,+ join,+} from 'node:path';+import {+ gunzipSync,+ gzipSync,+} from 'node:zlib';+import {+ seal,+ unseal,+} from './seal.js';+import { Refused } from './refused.js';++/** How many replay refusals the link keeps for pullboard status; older ones stay in the relay's own receipts. */+const KEPT_REFUSALS = 20;++/** The sealed outbox beside a link file. */+export function outboxFile(linkFile) {+ return join(dirname(linkFile), 'relay-outbox.sealed');+}++/** Whether a link holds moves the relay has not ordered yet, while the local board still shows them applied. */+export function outboxAhead(state) {+ return Boolean(state?.outbox?.moves?.length) && state.outbox.restored !== true;+}++/**+ * Read and open the sealed outbox, or null when there is none.+ * Why: the board image and the queued moves are as private as the relay's own sealed records, so they stay sealed at rest.+ */+export async function readOutbox(file, key, boardId) {+ if (!existsSync(file)) return null;+ const plain = await unseal(key, readFileSync(file), { boardId, kind: 'outbox', sequence: 0 });+ const document = JSON.parse(gunzipSync(plain).toString('utf8'));+ if (document?.version !== 1 || !Array.isArray(document.moves) || !document.base || !Number.isSafeInteger(document.baseSequence)) {+ throw new Refused('RELAY_OUTBOX', 'the relay outbox on this machine is unreadable; keep it, and ask for help before relinking this board');+ }+ return document;+}++/** Seal and atomically replace the outbox, readable only by this user. */+export async function writeOutbox(file, key, boardId, document) {+ const sealed = await seal(key, gzipSync(Buffer.from(JSON.stringify(document))), { boardId, kind: 'outbox', sequence: 0 });+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 });+ const temporary = file + '.' + randomUUID() + '.tmp';+ try {+ writeFileSync(temporary, Buffer.from(sealed), { flag: 'wx', mode: 0o600 });+ renameSync(temporary, file);+ } finally { rmSync(temporary, { force: true }); }+}++/** Remove the outbox once every move in it has been ordered. */+export function removeOutbox(file) {+ rmSync(file, { force: true });+}++/** The item a move acts on, when its first argument names one. */+function moveItem(move) {+ return Number.isSafeInteger(move?.args?.[0]) ? move.args[0] : null;+}++/** Name a move for people: its operation, its item and who made it. */+export function describeMove(move) {+ const item = moveItem(move);+ return `${move.operation}${item === null ? '' : ` #${item}`}${move.actor ? ` by ${move.actor}` : ''}`;+}++/** The key-free line pullboard status keeps for one queued move. */+export function outboxEntrySummary(entry) {+ return { id: entry.move.id, operation: entry.move.operation, item: moveItem(entry.move), actor: entry.move.actor ?? null, queuedAt: entry.queuedAt };+}++/**+ * The moves the relay ordered after a queued move was made and before it replayed, on the same item when any are,+ * so a refusal at replay names what came first.+ * Why: a refused replay that named only itself would leave the person to guess which other machine's move won.+ */+export function earlierMoves(board, entry, sequence) {+ const rows = board.db.prepare("SELECT meta_value FROM board_meta WHERE meta_key LIKE 'relay_receipt_%'").all();+ const between = [];+ for (const { meta_value: value } of rows) {+ let receipt;+ try { receipt = JSON.parse(value); } catch { continue; }+ if (!(receipt.sequence > entry.after && receipt.sequence < sequence)) continue;+ let move;+ try { move = JSON.parse(receipt.move); } catch { continue; }+ if (move.id === entry.move.id) continue;+ between.push({ sequence: receipt.sequence, move });+ }+ const item = moveItem(entry.move);+ const same = item === null ? [] : between.filter(({ move }) => moveItem(move) === item);+ return (same.length ? same : between).sort((a, b) => a.sequence - b.sequence).slice(-3)+ .map(({ sequence: at, move }) => ({ sequence: at, move: describeMove(move) }));+}++/** Keep one replay refusal on the link for pullboard status, newest last, and return its line. */+export function keepRefusal(state, entry, refusal, earlier) {+ const kept = { move: describeMove(entry.move), queuedAt: entry.queuedAt, code: refusal.code, message: refusal.message, earlier };+ state.outboxRefusals = [...(state.outboxRefusals ?? []), kept].slice(-KEPT_REFUSALS);+ return refusalLine(kept);+}++/** Say what a refused replay was and which ordered moves came first. */+export function refusalLine(kept) {+ const first = kept.earlier.length+ ? `; moves the relay ordered first: ${kept.earlier.map(({ sequence, move }) => `sequence ${sequence} ${move}`).join(', ')}`+ : '; no other move reached the relay first';+ return `[RELAY_OUTBOX_REFUSED] the queued move ${kept.move} (made ${kept.queuedAt}) was refused when it replayed: [${kept.code}] ${kept.message}${first}`;+}diff --git a/src/relay-output.js b/src/relay-output.jsindex 75b591d0..f029ac90 100644--- a/src/relay-output.js+++ b/src/relay-output.js@@ -1,6 +1,10 @@/** Relay text output stays separate from CLI dispatch and encrypted transport [H15,H17]. */import { formatSnapshotLimit } from './relay.js';import { relayStorageLine } from './relay-storage.js';+import {+ describeMove,+ refusalLine,+} from './relay-outbox.js';/** Preserve status's short relay summary, any pending-size finding and the authenticated account quota. */export function briefLines(state) {@@ -8,6 +12,18 @@ export function briefLines(state) {if (state.linked) lines.push(`relay: sequence ${state.sequence}; ${state.behind} pending uploads${state.recovery?.pending ? `; recovery pending for sequence ${state.recovery.skip}; retry ${state.recovery.next}` : ''}`);if (state.oversizedSnapshot && !state.refusedCheckpoint) lines.push(formatSnapshotLimit(state.oversizedSnapshot));if (state.storage) lines.push(relayStorageLine(state.storage));+ lines.push(...outboxLines(state));+ return lines;+}++/** Name each move waiting in the relay outbox and each one refused when it replayed (#922). */+export function outboxLines(state) {+ const lines = [];+ if (state.outbox?.length) {+ lines.push(`relay outbox: ${state.outbox.length} ${state.outbox.length === 1 ? 'move waits' : 'moves wait'} for the relay, sent in this order when it answers:`);+ for (const move of state.outbox) lines.push(` ${describeMove({ operation: move.operation, args: [move.item], actor: move.actor })} (made ${move.queuedAt}): pending`);+ }+ for (const refused of state.outboxRefusals ?? []) lines.push(refusalLine(refused));return lines;}diff --git a/src/relay.js b/src/relay.jsindex b707f6d2..da382c6a 100644--- a/src/relay.js+++ b/src/relay.js@@ -43,6 +43,7 @@ import {applyRelayMove,checkpointSequence,engineReceipt,+ executableArgs,prepareEngineMove,refuseRelayMove,requireSupportedEngine,@@ -93,6 +94,16 @@ import {baselineNotAccepted,transientRelayFailure,} from './relay-move-fallback.js';+import {+ earlierMoves,+ keepRefusal,+ outboxAhead,+ outboxEntrySummary,+ outboxFile,+ readOutbox,+ removeOutbox,+ writeOutbox,+} from './relay-outbox.js';import { Refused } from './refused.js';import { refusalFromReceipt } from './recorded-refusal.js';import { relaySenderProblem } from './relay-sender.js';@@ -130,6 +141,7 @@ export const DEFAULT_RELAY = 'https://app.pullboard.dev';const LINK_FILES = new WeakMap();const STATE_FILES = new WeakMap();const MOVE_FALLBACK_NOTICES = new WeakSet();+const OUTBOX_NOTICES = new WeakSet();const KEY_WARNED_COMMANDS = new WeakSet();const BASELINE_ATTEMPTS = new WeakMap();const BASELINE_NOTICES = new WeakSet();@@ -441,6 +453,12 @@ function recoverySummary(state) {return { pending: skip > 0, skip, next: skip > 0 ? `pullboard relay recover --skip ${skip}` : '' };}+/** The queued moves and replay refusals pullboard status shows, when there are any (#922). */+function outboxFields(state) {+ return { ...(state?.outbox?.moves?.length ? { outbox: structuredClone(state.outbox.moves) } : {}),+ ...(state?.outboxRefusals?.length ? { outboxRefusals: structuredClone(state.outboxRefusals) } : {}) };+}+/** Expose key-free link status; only an explicit link operation includes its pairing carrier. */function summary(root, state, { pairing = false } = {}) {if (!state) {@@ -453,8 +471,10 @@ function summary(root, state, { pairing = false } = {}) {const oversizedSnapshot = snapshotSize(state);return { linked: true, board: state.board, url: state.url, account: state.account ?? '', login: state.login ?? '',link: 'https://app.pullboard.dev/#board=' + state.board + fragment,- sequence: state.sequence, behind: (state.baselinePause ? behind(root, state) : state.mode === 'ordered' ? Number(Boolean(state.pending)) : behind(root, state)) + Number(Boolean(state.snapshot || state.checkpoint)),+ sequence: state.sequence, behind: (state.baselinePause ? behind(root, state) : state.mode === 'ordered' ? Number(Boolean(state.pending)) : behind(root, state)) + Number(Boolean(state.snapshot || state.checkpoint))+ + (state.outbox?.moves?.length ?? 0),recovery: recoverySummary(state),+ ...outboxFields(state),...(relayStorage(state.storage) ? { storage: relayStorage(state.storage) } : {}),...(oversizedSnapshot ? { oversizedSnapshot } : {}),...(state.baselinePause ? { pausedUpload: structuredClone(state.baselinePause) } : {}),@@ -998,6 +1018,8 @@ function reportRecoveredReply(record, io) {/** Apply a validated relay prefix with durable, transaction-bound receipts on this replica. */async function catchUp(root, file, state, io) {+ // Queued moves sit on top of this board until the outbox replays; another machine's moves must not land under them.+ if (outboxAhead(state)) throw new Refused('RELAY_OUTBOX_PENDING', 'this machine holds moves the relay has not ordered yet; run pullboard status to send them first');const key = readBoardKey(state.board);const after = localRecords(root, appliedSequence);let remote;@@ -1160,6 +1182,169 @@ function keepMoveForLaterBaseline(file, state, error, io) {io.err(`pullboard: [${safePauseCode(error)}] the move is saved on this machine; ${error.transportFailure ? `the relay did not answer (${error.transportFailure})` : safePauseMessage(error)}; it goes up inside the board baseline on a later command once the relay answers`);}+/** Whether this command may queue a move in the ordered outbox: the board's relay.outbox setting, off by default (#922). */+function outboxEnabled(io) {+ try { return io?.relayOutbox?.() === true; } catch { return false; }+}++/**+ * Whether a failure on an accepted link may queue the move instead of refusing it (#922): the relay said nothing+ * definite, and the move needs no relay answer to exist (a registration mints its token there; a person's request+ * is the phone's to send).+ */+function outboxQueueable(state, error, operation, io) {+ return state.mode === 'ordered' && state.baselineAccepted === true && !state.baselineConflict && !io?.personRequest+ && !['register', 'ensureCoordinator'].includes(operation) && transientRelayFailure(error) && outboxEnabled(io);+}++/** The board's relay-applied sequence, read from an exported image. */+function exportedSequence(native) {+ return Number(native.tables.board_meta.find((row) => row.meta_key === 'relay_applied_sequence')?.meta_value ?? 0);+}++/** Keep the key-free outbox summary on the link, or drop it once the outbox is empty. */+function saveOutboxSummary(file, state, outbox) {+ if (outbox?.moves.length) state.outbox = { restored: outbox.restored, moves: outbox.moves.map(outboxEntrySummary) };+ else delete state.outbox;+ saveLink(file, state);+}++/**+ * Queue a move the relay could not take on an accepted link, then make it on this machine (#922).+ * The first queued move seals the board as the relay last ordered it; the move is written before it is applied,+ * so a crash between the two leaves it queued and the replay starts from that image anyway. A move this board+ * refuses is refused now and never queued.+ */+async function queueMove(root, file, state, io, { operation, args, command, move, error, applyLocally }) {+ const key = readBoardKey(state.board);+ const where = outboxFile(file);+ const outbox = await readOutbox(where, key, state.board) ?? (() => {+ const base = localRecords(root, (board) => exportBoard(board));+ return { version: 1, base, baseSequence: exportedSequence(base), restored: false, moves: [] };+ })();+ if (!move) {+ const sent = withSeatName(root, operation, args);+ move = localRecords(root, (board) => prepareEngineMove(board, operation, sent));+ move.actor = relayMoveActor(move) ?? credentialActor(move);+ }+ // `after` is the relay sequence this machine had seen: a refusal at replay names the moves ordered since.+ const entry = { move, intent: operationIntent(operation, args), queuedAt: new Date().toISOString(), after: state.sequence,+ ...(command ? { command, commandIntent: operationIntent('cli:' + command.cliOperation, command) } : {}) };+ outbox.moves.push(entry);+ await writeOutbox(where, key, state.board, outbox);+ if (state.pending?.move?.id === move.id) delete state.pending;+ saveOutboxSummary(file, state, outbox);+ let result;+ try { result = await applyLocally(); }+ catch (refusal) {+ outbox.moves.pop();+ if (outbox.moves.length) await writeOutbox(where, key, state.board, outbox);+ else removeOutbox(where);+ saveOutboxSummary(file, state, outbox);+ throw refusal;+ }+ if (!OUTBOX_NOTICES.has(io)) {+ OUTBOX_NOTICES.add(io);+ io.err(`pullboard: [${safePauseCode(error)}] ${error.transportFailure ? `the relay did not answer (${error.transportFailure})` : safePauseMessage(error)}; the move is saved on this machine and waits in the relay outbox (${outbox.moves.length} pending); it goes up in order when the relay answers, and pullboard status lists it`);+ }+ return result;+}++/**+ * Put the queued moves back on top of the board after a replay stopped part way (#922): seal the board as the relay+ * has now ordered it, then apply each remaining move here again, so this machine keeps showing them.+ */+async function rebaseOutbox(root, file, state, outbox, key) {+ outbox.base = localRecords(root, (board) => exportBoard(board));+ outbox.baseSequence = exportedSequence(outbox.base);+ outbox.restored = false;+ await writeOutbox(outboxFile(file), key, state.board, outbox);+ saveOutboxSummary(file, state, outbox);+ for (const entry of outbox.moves) {+ localRecords(root, (board) => {+ try { store.atomic(board, () => store[entry.move.operation](board, ...executableArgs(entry.move, board))); }+ catch (error) { if (!(error instanceof Refused)) throw error; }+ });+ }+}++/**+ * Replay the ordered outbox before this machine applies or sends anything else (#922). The board goes back to the+ * image the relay last ordered, catches up with every other machine's moves, then sends each queued move in order:+ * a move the relay already holds from a lost reply is not sent twice, and a move refused at replay is reported with+ * the moves ordered before it. A relay that fails again part way puts the rest back on top and throws its failure.+ */+async function flushOutbox(root, file, state, io) {+ const where = outboxFile(file);+ if (!state.outbox && !existsSync(where)) return;+ const key = readBoardKey(state.board);+ const outbox = await readOutbox(where, key, state.board);+ if (!outbox?.moves.length) {+ removeOutbox(where);+ saveOutboxSummary(file, state, null);+ return;+ }+ try {+ if (!outbox.restored) {+ // Probe first: a relay that is still down leaves this machine's board exactly as its person last saw it.+ try { await request(state, '/api/v1/boards/' + state.board + '/events?after=' + outbox.baseSequence, {}, io); }+ catch (error) { if (error.code !== 'SNAPSHOT_REQUIRED') throw error; }+ localRecords(root, (board) => {+ const cursors = board.db.prepare('SELECT agent_id, agent_last_shout_id FROM agent').all();+ restoreRelaySnapshot(board, outbox.base, outbox.baseSequence);+ // Reading shouts is this machine's own progress; the restore keeps the newer read position.+ const keep = board.db.prepare('UPDATE agent SET agent_last_shout_id = ? WHERE agent_id = ? AND (agent_last_shout_id IS NULL OR agent_last_shout_id < ?)');+ for (const row of cursors) if (Number.isSafeInteger(row.agent_last_shout_id)) keep.run(row.agent_last_shout_id, row.agent_id, row.agent_last_shout_id);+ });+ state.sequence = outbox.baseSequence;+ outbox.restored = true;+ await writeOutbox(where, key, state.board, outbox);+ saveOutboxSummary(file, state, outbox);+ }+ await catchUp(root, file, state, io);+ while (outbox.moves.length) {+ const entry = outbox.moves[0];+ const receiptOf = () => localRecords(root, (board) => engineReceipt(board, entry.move.id));+ let receipt = receiptOf();+ let sequence = receipt?.sequence;+ if (!receipt) {+ await actorTransport(root, file, state, credentialActor(entry.move), io);+ sequence = state.sequence + 1;+ const sealed = await sealedRecord(key, entry.move, state, 'move', sequence);+ const registration = seatReceipt(entry.move, sequence, sealed);+ state.pending = { move: entry.move, intent: entry.intent, ...(entry.command ? { command: entry.command, commandIntent: entry.commandIntent } : {}),+ sequence, sealed, ...(registration ? { registration } : {}) };+ saveLink(file, state);+ let failure;+ try { await sendPending(root, file, state, io); } catch (error) { failure = error; }+ if (failure && !receiptOf()) {+ if (!['RELAY_UNAVAILABLE', 'RELAY_RESPONSE'].includes(failure.code)) throw failure;+ try { await catchUp(root, file, state, io); } catch { throw failure; }+ }+ receipt = receiptOf();+ if (!receipt) throw failure ?? new Refused('RELAY_RESPONSE', 'the relay acknowledged a queued move without its replay receipt; run pullboard status to retry the outbox');+ sequence = receipt.sequence;+ }+ if (state.pending?.move?.id === entry.move.id) delete state.pending;+ if (state.recovered?.move?.id === entry.move.id) delete state.recovered;+ if (receipt.outcome.error) {+ const earlier = localRecords(root, (board) => earlierMoves(board, entry, sequence));+ io.err(`pullboard: ${keepRefusal(state, entry, receipt.outcome.error, earlier)}`);+ }+ outbox.moves.shift();+ if (outbox.moves.length) await writeOutbox(where, key, state.board, outbox);+ else removeOutbox(where);+ saveOutboxSummary(file, state, outbox);+ }+ } catch (error) {+ if (outbox.restored && outbox.moves.length) {+ if (state.pending && outbox.moves.some((entry) => entry.move.id === state.pending.move?.id)) delete state.pending;+ await rebaseOutbox(root, file, state, outbox, key);+ }+ throw error;+ }+}+/** Send one board operation before executing it locally, and report its canonical engine result. */export async function relayOperation(root, operation, args, io, command, applyLocally) {const file = linkFile(root);@@ -1181,8 +1366,10 @@ export async function relayOperation(root, operation, args, io, command, applyLomoves.add(state.board);try {let ordered;+ const queue = (error, move) => queueMove(root, file, state, io, { operation, args, command, move, error, applyLocally: applyPausedMoveLocally });try { ordered = await ensureOrdered(root, file, state, io); }catch (error) {+ if (outboxQueueable(state, error, operation, io)) return await queue(error);// #341: a baseline the relay has not accepted never blocks a move; the move rides in the later baseline.if (!baselineNotAccepted(state) || !transientRelayFailure(error)) throw error;keepMoveForLaterBaseline(file, state, error, io);@@ -1192,7 +1379,14 @@ export async function relayOperation(root, operation, args, io, command, applyLoif (state.baselinePause) reportBaselinePause(state, io);return applyPausedMoveLocally();}- await catchUp(root, file, state, io);+ try {+ // #922: moves queued while the relay was down go up first, in the order they were made.+ await flushOutbox(root, file, state, io);+ await catchUp(root, file, state, io);+ } catch (error) {+ if (outboxQueueable(state, error, operation, io)) return await queue(error);+ throw error;+ }if (state.pending) {delete state.pending;saveLink(file, state);@@ -1208,28 +1402,34 @@ export async function relayOperation(root, operation, args, io, command, applyLoreturn previousReceipt.outcome.result;}let move = recoveredMove(root, state, operation, args, command);- if (!move) {- const sent = withSeatName(root, operation, args);- move = localRecords(root, (board) => prepareEngineMove(board, operation, sent, io.personRequestMoveId ? { id: io.personRequestMoveId } : {}));- if (io.personRequest) move.personRequest = structuredClone(io.personRequest);- const problem = move.personRequest && localRecords(root, board => requestMoveProblem(board, move, { checkExecutorLease: false }));- if (problem) throw problem;- move.actor = relayMoveActor(move) ?? credentialActor(move);- await actorTransport(root, file, state, credentialActor(move), io);- const sequence = state.sequence + 1;- const sealed = await sealedRecord(readBoardKey(state.board), move, state, 'move', sequence);- const registration = seatReceipt(move, sequence, sealed);- state.pending = { move, intent: operationIntent(operation, args),- ...(command ? { command, commandIntent: operationIntent('cli:' + command.cliOperation, command) } : {}), sequence,- sealed, ...(registration ? { registration } : {}) };- saveLink(file, state);- try { await sendPending(root, file, state, io); }- catch (error) {- if (!['RELAY_UNAVAILABLE', 'RELAY_RESPONSE'].includes(error.code)) throw error;- // A lost acknowledgement can be recovered now without asking the caller to retry side effects.- try { await catchUp(root, file, state, io); } catch { throw rememberLostReply(file, state, move.id, error); }- if (!localRecords(root, (board) => engineReceipt(board, move.id))) throw rememberLostReply(file, state, move.id, error);+ try {+ if (!move) {+ const sent = withSeatName(root, operation, args);+ move = localRecords(root, (board) => prepareEngineMove(board, operation, sent, io.personRequestMoveId ? { id: io.personRequestMoveId } : {}));+ if (io.personRequest) move.personRequest = structuredClone(io.personRequest);+ const problem = move.personRequest && localRecords(root, board => requestMoveProblem(board, move, { checkExecutorLease: false }));+ if (problem) throw problem;+ move.actor = relayMoveActor(move) ?? credentialActor(move);+ await actorTransport(root, file, state, credentialActor(move), io);+ const sequence = state.sequence + 1;+ const sealed = await sealedRecord(readBoardKey(state.board), move, state, 'move', sequence);+ const registration = seatReceipt(move, sequence, sealed);+ state.pending = { move, intent: operationIntent(operation, args),+ ...(command ? { command, commandIntent: operationIntent('cli:' + command.cliOperation, command) } : {}), sequence,+ sealed, ...(registration ? { registration } : {}) };+ saveLink(file, state);+ try { await sendPending(root, file, state, io); }+ catch (error) {+ if (!['RELAY_UNAVAILABLE', 'RELAY_RESPONSE'].includes(error.code)) throw error;+ // A lost acknowledgement can be recovered now without asking the caller to retry side effects.+ try { await catchUp(root, file, state, io); } catch { throw rememberLostReply(file, state, move.id, error); }+ if (!localRecords(root, (board) => engineReceipt(board, move.id))) throw rememberLostReply(file, state, move.id, error);+ }}+ } catch (error) {+ // #922: on an accepted link, a relay that stays down queues the move; a lost reply's copy is matched at replay.+ if (move && !localRecords(root, (board) => engineReceipt(board, move.id)) && outboxQueueable(state, error, operation, io)) return await queue(error, move);+ throw error;}const receipt = localRecords(root, (board) => engineReceipt(board, move.id));if (!receipt) throw new Refused('RELAY_RESPONSE', 'the acknowledged operation has no replay receipt; fetch a consistent relay snapshot');@@ -1273,6 +1473,7 @@ export async function syncRelay(root, io) {try {if (state.recovery) throw new Refused('RELAY_RECOVERY_PENDING', `a relay recovery for sequence ${state.recovery.skip} is pending; retry pullboard relay recover --skip ${state.recovery.skip} before syncing`);if (!await ensureOrdered(root, file, state, io)) return summary(root, state);+ await flushOutbox(root, file, state, io);await catchUp(root, file, state, io);if (state.pending) {// The complete prefix did not acknowledge this interrupted send. It must not run later.@@ -1294,10 +1495,10 @@ export async function syncRelay(root, io) {}} else if (error.code === 'AUTH_REQUIRED') {if (!orderedMoveCommand(io)) reportExpiredSignIn(state, io);- } else if (!(orderedMoveCommand(io) && baselineNotAccepted(state) && transientRelayFailure(error))) io.err(`pullboard: ${error.message}; run pullboard status to see pending uploads`);+ } else if (!(orderedMoveCommand(io) && (baselineNotAccepted(state) || outboxQueueable(state, error, null, io)) && transientRelayFailure(error))) io.err(`pullboard: ${error.message}; run pullboard status to see pending uploads`);return { linked: true, board: state.board, url: state.url, sequence: state.sequence,- behind: (state.mode === 'ordered' ? Number(Boolean(state.pending)) : behind(root, state)) + Number(Boolean(state.snapshot || state.checkpoint)),- recovery: recoverySummary(state) };+ behind: (state.mode === 'ordered' ? Number(Boolean(state.pending)) : behind(root, state)) + Number(Boolean(state.snapshot || state.checkpoint)) + (state.outbox?.moves?.length ?? 0),+ recovery: recoverySummary(state), ...outboxFields(state) };}}, io);}@@ -1665,6 +1866,7 @@ export async function relayOn(root, address, io, { session, credential, quiet =if (ready) ready = await ensureOrdered(root, file, state, io);if (ready) {rmSync(deletedLinkFile(root), { force: true });+ await flushOutbox(root, file, state, io);await catchUp(root, file, state, io);await deliverDeviceWraps(root, io);updateRelayMachine(machine => { machine.excluded = machine.excluded.filter(entry => entry !== repoInfo(root).root); });diff --git a/src/seal.js b/src/seal.jsindex f528f759..ce909d2f 100644--- a/src/seal.js+++ b/src/seal.js@@ -39,9 +39,9 @@ function keyBytes(value) {/** Canonical, domain-separated associated data binds the header and public position. */function associatedData(binding, version = SEAL_VERSION) {if (!binding || typeof binding.boardId !== 'string' || !binding.boardId.length ||- binding.boardId.length > 256 || !['snapshot', 'move', 'request'].includes(binding.kind) ||+ binding.boardId.length > 256 || !['snapshot', 'move', 'request', 'outbox'].includes(binding.kind) ||!Number.isSafeInteger(binding.sequence) || binding.sequence < 0 || !Number.isInteger(version) || version < 0 || version > 255) {- throw new Refused('SEAL_BINDING', 'Supply the board id, snapshot/move/request kind and nonnegative safe sequence.');+ throw new Refused('SEAL_BINDING', 'Supply the board id, snapshot/move/request/outbox kind and nonnegative safe sequence.');}return new TextEncoder().encode(JSON.stringify(['pullboard-sealed', version, binding.boardId, binding.sequence, binding.kind,diff --git a/test/relay-outbox.test.js b/test/relay-outbox.test.jsnew file mode 100644index 00000000..19dab651--- /dev/null+++ b/test/relay-outbox.test.js@@ -0,0 +1,71 @@+import assert from 'node:assert/strict';+import { readFileSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import test from 'node:test';+import { fileURLToPath } from 'node:url';+import { runFixtureGit } from './fixture-child.js';+import { relayClientFixture } from './relay-client-fixture.js';++/** Turn the board's committed relay.outbox setting on, as its coordinator would. */+function enableOutbox(box) {+ const file = join(box.root, 'pullboard.json');+ const config = JSON.parse(readFileSync(file, 'utf8'));+ writeFileSync(file, JSON.stringify({ ...config, relay: { outbox: true } }, null, 2) + '\n');+ // The board's own commit hook runs pullboard, so this private PATH gets the CLI under test.+ const cliPath = fileURLToPath(new URL('../bin/pullboard.js', import.meta.url));+ writeFileSync(join(box.env.PATH, 'pullboard'), `#!/bin/sh\nexec node "${cliPath}" "$@"\n`, { mode: 0o700 });+ runFixtureGit(['add', 'pullboard.json'], { cwd: box.root, env: box.env });+ runFixtureGit(['commit', '-q', '-m', 'chore(config): queue relay moves while the relay is down'], { cwd: box.root, env: box.env });+}++/** The shout texts a board export holds, in board order. */+function shoutTexts(exported) {+ return exported.tables.shout.map((row) => row.shout_text);+}++test('a move on an accepted relay link waits in the ordered outbox while the relay is down, and replays in order [B26,H16,H17]', async (t) => {+ const box = await relayClientFixture(t);+ enableOutbox(box);+ await box.link();+ const contested = (await box.cli('add', box.lane, 'Contested while the relay is down')).document.item.item_id;+ const printed = await box.cli('relay', 'pair');+ const other = await box.otherDeviceJoin(printed.document.code);+ assert.equal(JSON.parse(readFileSync(box.linkFile, 'utf8')).baselineAccepted, true, 'the relay accepted this board before the outage');++ await box.stopRelay();+ const first = await box.cli('shout', 'all', 'queued first while the relay is down');+ assert.equal(first.code, 0, JSON.stringify(first.document));+ const withdrawn = await box.cli('withdraw', String(contested), 'queued withdraw from this machine');+ assert.equal(withdrawn.code, 0, withdrawn.failure);+ const last = await box.cli('shout', 'all', 'queued last while the relay is down');+ assert.equal(last.code, 0, last.failure);++ const waiting = await box.cli('status');+ assert.deepEqual(waiting.document.relay.outbox.map((move) => [move.operation, move.item]), [['shout', null], ['withdraw', contested], ['shout', null]],+ 'pullboard status lists the queued moves in the order they were made');+ const shown = await box.cli('show', String(contested));+ assert.deepEqual(shown.document.relayPending.map((move) => move.operation), ['withdraw'], 'the item shows its move as pending');+ const local = await box.cli('export');+ assert.ok(shoutTexts(local.document).includes('queued last while the relay is down'), 'this machine keeps working on its queued moves');++ await box.restartRelay();+ const raced = await other.cli('withdraw', String(contested), 'the other machine withdrew it first');+ assert.equal(raced.code, 0, raced.failure);++ const replayed = await box.cli('status');+ assert.equal(replayed.code, 0, replayed.failure);+ assert.equal(replayed.document.relay.outbox, undefined, 'the outbox is empty once it replays');+ const [refused] = replayed.document.relay.outboxRefusals;+ assert.equal(replayed.document.relay.outboxRefusals.length, 1, 'only the conflicting move is refused');+ assert.match(refused.move, new RegExp(`^withdraw #${contested}`), 'the refusal names the queued move');+ assert.ok(refused.earlier.some((earlier) => earlier.move.startsWith(`withdraw #${contested}`)), 'the refusal names the move another machine made first');++ const there = await other.cli('export');+ const here = await box.cli('export');+ const sent = shoutTexts(there.document).filter((text) => /while the relay is down/u.test(text));+ assert.deepEqual(sent, ['queued first while the relay is down', 'queued last while the relay is down'], 'the other machine receives the queued moves in order');+ assert.deepEqual(shoutTexts(here.document), shoutTexts(there.document), 'both machines hold the same shouts in the same order');+ const item = (exported) => exported.tables.item.find((row) => row.item_id === contested);+ assert.deepEqual(item(here.document), item(there.document), 'both machines agree on the contested item');+ assert.equal(item(there.document).item_status, 'withdrawn');+});