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(relay): serialize opt-out and preserve its native audit [H5,H17]

Corey Olsonb43b64dba62b
diff --git a/docs/formats.md b/docs/formats.md
index d5ba1419..08641090 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -428,7 +428,7 @@ The `event` table is a SQLite schema object governed by `SCHEMA_VERSION`; its ap
| `edit` | editor | `brief`, `route`, `criterion`, `check`, `unfrozen`, optional `after`, optional `pendingRefreeze`, engine-19 `reason`, `barCorrection` |
| `escalate` | builder | `from`, `to`, `note`, `attempt` |
| `attempt` | reporting agent | `n`, `seconds`, `result` |
-| `relay_exclusion` | person | `action` (`exclude`, the durable opt-out intent), `path` (`relayOff`), `reason`, `channel`; event time and actor identify the request before machine settings persist it |
+| `relay_exclusion` | person | `action` (exclude, the durable opt-out intent), `path` (relayOff), `reason`, `channel`; event time and actor identify the request before machine settings persist it |
| `board_members` | coordinator | `document` (exact version-1 body with board, repository, revision and complete members, approving login and SSH signature; native moves and checkpoints carry it sealed) |
| `fact` | author | `id`, `kind`, `text`, `ref`, `supersedes`, engine-20 `implies`, `decision`, `supersededBy`, engine-30 `cause`, `neverAgain`, `channel` |
| `claim` | builder | `leaseUntil`, `digest` |
diff --git a/docs/formats.test.js b/docs/formats.test.js
index 7f847014..08f16615 100644
--- a/docs/formats.test.js
+++ b/docs/formats.test.js
@@ -1,3 +1,4 @@
+import { recordRelayExclusionIntent } from '../src/relay-exclusion-state.js';
/** @pullboard-test-input source-tree */
/** Keep the format guide aligned with parser behavior, live SQLite schema and static export [A5,A10]. */
import assert from 'node:assert/strict';
@@ -447,6 +448,7 @@ function recordEventContract() {
beginSentinelRun(board, { agentId: coordinator, name: watch.name, digest: watch.digest, run: 'format-run' });
finishSentinelRun(board, { agentId: coordinator, name: watch.name, digest: watch.digest, run: 'format-run',
result: { green: false, code: 1, timedOut: false, durationMs: 0, output: 'synthetic format receipt' } });
+ recordRelayExclusionIntent(board, 'view'); // Synthetic person format fixture, not a real settings opt-out.
const rows = events(board).map((row) => ({ ...row, detail: JSON.parse(row.event_detail) }));
closeBoard(board);
return { rows, actors: { [coordinator]: 'coordinator', [builder]: 'builder', [returnedBuilder]: 'builder', [reviewer]: 'reviewer', [PERSON]: 'person', board: 'board', rigor: 'rigor' } };
diff --git a/src/relay-exclusion-state.js b/src/relay-exclusion-state.js
index ec7fede2..4cec76d9 100644
--- a/src/relay-exclusion-state.js
+++ b/src/relay-exclusion-state.js
@@ -1,3 +1,5 @@
+import { logEvent } from './board-event-log.js';
+import { PERSON } from './board-query.js';
/** Person-owned machine exclusions carry key-free native provenance [H5,H17,B26]. */
import { repoInfo } from './git.js';
import { readRelayMachine } from './relay-machine.js';
@@ -16,16 +18,13 @@ export function relayExclusion(root) {
}
/** Successful local unlink remains available to agents; only a person can persist an opt-out. */
-export function excludeRelayByPerson(root, io, { localRecords, store }) {
+export function excludeRelayByPerson(root, io, { localRecords }) {
let channel;
try { channel = requirePersonChannel(io.personChannel); }
catch (error) { if (error.code === 'B26_PERSON_CHANNEL') return false; throw error; }
const project = repoInfo(root).root;
// Record the intent first: a storage failure can leave a truthful request, never an unattributed exclusion.
- const receipt = localRecords(root, board => {
- store.logEvent(board, store.PERSON, 'relay_exclusion', null, { path: 'relayOff', reason: 'person relay off', channel, action: 'exclude' });
- return { by: board.lastEvent.event_by, at: board.lastEvent.event_at, eventId: board.lastEvent.event_id };
- });
+ const receipt = localRecords(root, board => recordRelayExclusionIntent(board, channel));
updateRelayMachine(state => {
if (!state.excluded.includes(project)) state.excluded.push(project);
state.exclusionDetails ??= {};
@@ -52,3 +51,17 @@ export function reportClearedExclusion(result, io) {
result.notice = [result.notice, notice].filter(Boolean).join(' ');
io.err(notice);
}
+
+/** Record the person request before settings persistence, so every durable opt-out cites its native intent. */
+export function recordRelayExclusionIntent(board, channel) {
+ requirePersonChannel(channel);
+ logEvent(board, PERSON, 'relay_exclusion', null, { path: 'relayOff', reason: 'person relay off', channel, action: 'exclude' });
+ return { by: board.lastEvent.event_by, at: board.lastEvent.event_at, eventId: board.lastEvent.event_id };
+}
+
+/** A pending authorized upload does not hide an exclusion which has not yet been cleared. */
+export function withRelayExclusion(root, result) {
+ if (result.excluded) return result;
+ const exclusion = relayExclusion(root);
+ return { ...result, ...(exclusion ? { excluded: true, exclusion } : {}) };
+}
diff --git a/src/relay.js b/src/relay.js
index 0aab05ce..9c1d64f4 100644
--- a/src/relay.js
+++ b/src/relay.js
@@ -1,3 +1,4 @@
+import { withRelayExclusion } from './relay-exclusion-state.js';
import { relinkReplacement } from './relay-relink.js';
import { relayExclusion } from './relay-exclusion-state.js';
import { excludeRelayByPerson } from './relay-exclusion-state.js';
@@ -1497,7 +1498,7 @@ export async function relayRecover(root, skip, io) {
}
/** Read the local link and lag without opening a network connection or revealing its relay token. */
-export function relayStatus(root) { return summary(root, loadLink(linkFile(root))); }
+export function relayStatus(root) { return withRelayExclusion(root, summary(root, loadLink(linkFile(root)))); }
/** Cancel one device ticket without the already-aborted caller signal. */
async function cancelDeviceFlow(url, ticket, io) {
@@ -1676,9 +1677,9 @@ export async function relayOn(root, address, io, { session, credential, quiet =
/** Unlink locally without approval, then request a separate phone-approved remote deletion if possible. */
export async function relayOff(root, io) {
- excludeRelayByPerson(root, io, { localRecords, store });
const file = linkFile(root);
return locked(file, async () => {
+ excludeRelayByPerson(root, io, { localRecords });
const state = loadLink(file);
if (!state) { await publishOffExclusions(null, io, { loadLink, linkFile, request: relayDeviceRequest }); return summary(root, null); }
let joined = [];
diff --git a/test/relay-exclusion-fixture.js b/test/relay-exclusion-fixture.js
index 067bb83b..d815734e 100644
--- a/test/relay-exclusion-fixture.js
+++ b/test/relay-exclusion-fixture.js
@@ -76,6 +76,12 @@ export async function relayOnClearsExclusion(t) {
assert.equal(status.document.relay.exclusion.reason, 'person relay off');
assert.ok(Number.isFinite(Date.parse(status.document.relay.exclusion.at)), 'new exclusions retain their actual time');
assert.match(status.document.relay.exclusion.next, /pullboard relay on/u);
+ box.refuseSnapshotWrites(true);
+ const pending = await box.cli('relay', 'on', '--url', box.origin);
+ assert.equal(pending.code, 0, 'a refused checkpoint retains a retryable authorized link');
+ assert.equal(machine(box).excluded.includes(box.root), true, 'a pending upload cannot prematurely clear the opt-out');
+ assert.equal((await box.cli('status')).document.relay.excluded, true, 'pending-link status still exposes the uncleared exclusion');
+ box.refuseSnapshotWrites(false);
const linked = await box.cli('relay', 'on', '--url', box.origin);
assert.equal(linked.code, 0);
assert.match(linked.document.notice, /exclusion.*clear|clear.*exclusion/iu, 'successful explicit on names the cleared exclusion');
@@ -92,7 +98,9 @@ export async function relayOnClearsExclusion(t) {
/** Person opt-out appends exactly one attributed native intent and preserves every prior row. */
export function assertPersonUnlinkHistory(after, before) {
- assert.deepEqual({ ...after, event: before.event }, before, 'unlink preserves all non-event native tables');
+ const sequences = before.sqlite_sequence.map(row => row.name === 'event' ? { ...row, seq: row.seq + 1 } : row);
+ assert.deepEqual(after.sqlite_sequence, sequences, 'only the event allocation advances, by exactly one audit');
+ assert.deepEqual({ ...after, event: before.event, sqlite_sequence: before.sqlite_sequence }, before, 'unlink preserves every other native table and sequence');
assert.deepEqual(after.event.slice(0, before.event.length), before.event, 'unlink preserves the exact previous event prefix');
assert.equal(after.event.length, before.event.length + 1, 'person unlink adds exactly its audit intent');
const receipt = after.event.at(-1);
diff --git a/test/relay.test.js b/test/relay.test.js
index ec442343..035f8396 100644
--- a/test/relay.test.js
+++ b/test/relay.test.js
@@ -1427,7 +1427,7 @@ test('plain relay off explains the retained relay copy without printing credenti
assert.equal(existsSync(box.linkFile), false, 'plain local off removes the device link');
assert.equal(existsSync(box.keyFile), false, 'plain local off forgets the device key');
assert.ok(JSON.parse(readFileSync(join(box.env.PULLBOARD_HOME, 'relay-machine/state.json'), 'utf8')).excluded.includes(box.root));
- assert.deepEqual((await box.cli('export')).document.tables, localBeforeOff, 'plain local off preserves native rows');
+ assertPersonUnlinkHistory((await box.cli('export')).document.tables, localBeforeOff);
assert.equal(box.calls.slice(callsBeforeOff).some(call => call.method === 'DELETE'), false,
'plain local off never deletes the remote copy without phone approval');
});