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.

fix: enable relay outbox by default [H21]

Corey Olson3bb282f6b9ca
diff --git a/docs/api.md b/docs/api.md
index 4e020e8d..50326dbe 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.
-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`).
+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: 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/src/cli.js b/src/cli.js
index b488ab1b..81b3f664 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -566,11 +566,11 @@ export async function reserveRow(ctx, row, written) {
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.
+ * Whether the board's committed relay.outbox setting queues moves while the relay is down (#922, H21).
+ * Why: absent means enabled for existing boards; an explicit false is the shared opt-out.
*/
export function relayOutboxSetting(root) {
- try { return configFromSource(coordinatorFile(root, CONFIG_FILE).stdout).relay?.outbox === true; } catch { return false; }
+ try { return configFromSource(coordinatorFile(root, CONFIG_FILE).stdout).relay?.outbox !== false; } catch { return false; }
}
export async function ordered(ctx, board, operation, args) {
diff --git a/src/config.js b/src/config.js
index 1d9f3c87..3471eb6d 100644
--- a/src/config.js
+++ b/src/config.js
@@ -198,7 +198,7 @@ export function configProblems(config) {
if (config.relay !== undefined && (!config.relay || typeof config.relay !== 'object' || Array.isArray(config.relay)
|| config.relay.outbox !== undefined && typeof config.relay.outbox !== 'boolean'
|| config.relay.board !== undefined && (typeof config.relay.board !== 'string' || !/^[0-9a-f]{32}$/u.test(config.relay.board))
- || Object.keys(config.relay).some(key => !['outbox', 'board'].includes(key)))) problems.push('"relay" has only the optional boolean "outbox", off by default, and "board", the linked board id relay on writes');
+ || Object.keys(config.relay).some(key => !['outbox', 'board'].includes(key)))) problems.push('"relay" has only the optional boolean "outbox", on by default with false as the opt-out, and "board", the linked board id relay on writes');
if (config.approvers !== undefined && (!Array.isArray(config.approvers) || config.approvers.length > 50 || new Set(config.approvers).size !== config.approvers.length
|| config.approvers.some((login) => typeof login !== 'string' || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/u.test(login)))) problems.push('"approvers" lists the GitHub logins who act as the person on a linked board, at most fifty; leave it out for today\'s behaviour');
if (!['inside', 'beside'].includes(config.worktrees)) problems.push('"worktrees" is "inside" or "beside"');
diff --git a/src/relay-outbox.js b/src/relay-outbox.js
index 19805602..0de42796 100644
--- a/src/relay-outbox.js
+++ b/src/relay-outbox.js
@@ -305,7 +305,7 @@ export function outboxFields(state) {
...(state?.outboxRenumbered?.length ? { outboxRenumbered: structuredClone(state.outboxRenumbered) } : {}) };
}
-/** Whether this command may queue a move in the ordered outbox: the board's relay.outbox setting, off by default (#922). */
+/** Whether this command may queue a move in the ordered outbox: the board's relay.outbox setting, on unless opted out (#922,H21). */
function outboxEnabled(io) {
try { return io?.relayOutbox?.() === true; } catch { return false; }
}
diff --git a/src/settings-inventory.js b/src/settings-inventory.js
index 4f873688..0358913d 100644
--- a/src/settings-inventory.js
+++ b/src/settings-inventory.js
@@ -35,7 +35,7 @@ const MACHINE_DEFAULTS = {
};
const OPTIONAL_REPO_DEFAULTS = {
project: null, name: null, 'checks.provesNothing': 'warn', 'verify.unrelatedTrunkMoves': false, 'verify.composeAtAdmission': false,
- 'flakes.rerun': false, 'flakes.quarantine': false, 'rigor.budget': 400, 'relay.outbox': false, 'relay.board': null,
+ 'flakes.rerun': false, 'flakes.quarantine': false, 'rigor.budget': 400, 'relay.outbox': true, 'relay.board': null,
submitGate: null, submitDeferAbove: null, landingShards: 1, 'landing.publish': null, 'landing.environment': null, positiveControl: null, affectedTests: null,
'health.sentinel': true, 'testConcurrency.browser': 2, approvers: null,
};
diff --git a/test/relay-local-first-settings.test.js b/test/relay-local-first-settings.test.js
new file mode 100644
index 00000000..e6ab5a59
--- /dev/null
+++ b/test/relay-local-first-settings.test.js
@@ -0,0 +1,65 @@
+/** The relay outbox defaults on for existing boards while preserving an explicit shared opt-out [H21]. */
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { relayOutboxSetting } from '../src/cli.js';
+import { settingsInventory } from '../src/settings-inventory.js';
+import { createE2eHelpers } from './e2e-helpers.js';
+
+/** Return the effective relay.outbox row from the production settings inventory. */
+function relaySettingRow(root, env) {
+ const previous = Object.fromEntries(['PULLBOARD_HOME', 'PULLBOARD_MACHINE_HOME'].map(key => [key, process.env[key]]));
+ try {
+ process.env.PULLBOARD_HOME = env.PULLBOARD_HOME;
+ process.env.PULLBOARD_MACHINE_HOME = env.PULLBOARD_MACHINE_HOME;
+ return settingsInventory([{ root }]).settings.find(row => row.scope === 'repo' && row.key === 'relay.outbox');
+ } finally {
+ for (const [key, value] of Object.entries(previous)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+ }
+}
+
+/** Commit one coordinator choice so both production readers see the same committed configuration. */
+function commitRelayChoice(box, value) {
+ const file = join(box.repo, 'pullboard.json');
+ const config = JSON.parse(readFileSync(file, 'utf8'));
+ config.relay = { ...config.relay, outbox: value };
+ writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+ box.git(box.repo, 'add', 'pullboard.json');
+ box.git(box.repo, 'commit', '-q', '-m', 'chore: configure relay outbox');
+}
+
+test('an existing board defaults relay.outbox on, preserves explicit opt-out, and reads without rewriting config [H21]', t => {
+ const helpers = createE2eHelpers();
+ const box = helpers.project('true', undefined, { withWorktree: false });
+ t.after(() => helpers.cleanup());
+ const file = join(box.repo, 'pullboard.json');
+
+ const legacyBytes = readFileSync(file);
+ assert.equal(JSON.parse(legacyBytes).relay, undefined, 'the fixture represents an existing board without this setting');
+ assert.equal(relayOutboxSetting(box.repo), true, 'an absent setting enables the outbox on an existing board');
+ const legacyRow = relaySettingRow(box.repo, box.env);
+ assert.equal(legacyRow.key, 'relay.outbox');
+ assert.equal(legacyRow.scope, 'repo');
+ assert.match(legacyRow.board, /^[0-9a-f]{32}$/u);
+ assert.equal(legacyRow.root, box.repo);
+ assert.equal(legacyRow.value, true);
+ assert.equal(legacyRow.default, true);
+ assert.equal(legacyRow.source, file);
+ assert.equal(legacyRow.origin, 'default');
+ assert.deepEqual(readFileSync(file), legacyBytes, 'resolving the default does not rewrite the committed project file');
+
+ for (const [choice, expected] of [[true, true], [false, false]]) {
+ commitRelayChoice(box, choice);
+ const configuredBytes = readFileSync(file);
+ assert.equal(relayOutboxSetting(box.repo), expected, `an explicit ${choice} setting is honored`);
+ const row = relaySettingRow(box.repo, box.env);
+ assert.equal(row.value, expected);
+ assert.equal(row.default, true);
+ assert.equal(row.origin, 'configured');
+ assert.deepEqual(readFileSync(file), configuredBytes, 'reading the committed choice does not rewrite project config');
+ }
+});