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
fix(relay): reserve durable exclusions for person intent [H5,H17,B26]
Corey Olsonbbf89c3c3b40
diff --git a/docs/formats.md b/docs/formats.mdindex 931e0fe9..d5ba1419 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -428,6 +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 || `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/src/commands/status.js b/src/commands/status.jsindex 6979588f..cb85d37a 100644--- a/src/commands/status.js+++ b/src/commands/status.js@@ -1,3 +1,5 @@+import { existsSync } from 'node:fs';+import { relayMachineDirectory } from '../local-state.js';import { withBoardRead } from '../cli-board-read.js';/** The pullboard status command, in its own module so an item adding another command never edits these lines. */import * as store from '../board-query.js';@@ -45,12 +47,16 @@ export async function run(io, { values }) {return { me, mine, agents, presenceCounts, ruleCounts: ruleProofCounts(ctx.info.root, board, approvalState.spec), needs: approvalState.needs, specApprovalBaseline: approvalState.specApprovalBaseline, specApprovalEvidenceErrors: approvalState.specApprovalEvidenceErrors, stats: store.stats(board), reviewQueue: { ...store.reviewQueue(board), ...store.reviewQueueBreakdown(board) }, unread: store.unreadCount(board, me.id), relay: relay ? relay.relayStatus(ctx.info.root) : unlinkedRelayStatus(),submitInvariantProposals: submitInvariantProposals(store.submitInvariantEvents(board, ctx.config), ctx.config) };});+ if (!summary.relay.linked && existsSync(relayMachineDirectory())) {+ const exclusion = (await import('../relay-exclusion-state.js')).relayExclusion(ctx.info.root);+ if (exclusion) Object.assign(summary.relay, { excluded: true, exclusion });+ }summary.memoryHeld = memoryHeldRuns();if (values.json) {io.result(summary);return 0;}- if (hasRelayState) for (const line of (await import('../relay-output.js')).briefLines(summary.relay)) io.say(line);+ if (hasRelayState || summary.relay.excluded) for (const line of (await import('../relay-output.js')).briefLines(summary.relay)) io.say(line);const { items, accepted, rejected } = summary.stats;io.say(`${summary.me.displayName}: ${summary.unread} unread shouts; holding ${summary.mine.map((item) => `#${item.item_id}`).join(', ') || 'nothing'}`);io.say(`board: ${items.open} open, ${items.claimed} claimed, ${items.submitted} awaiting verification, ${items.verified} verified, ${items.withdrawn} withdrawn`);diff --git a/src/relay-exclusion-state.js b/src/relay-exclusion-state.jsnew file mode 100644index 00000000..55322076--- /dev/null+++ b/src/relay-exclusion-state.js@@ -0,0 +1,44 @@+/** Person-owned machine exclusions carry key-free native provenance [H5,H17,B26]. */+import { repoInfo } from './git.js';+import { readRelayMachine } from './relay-machine.js';+import { updateRelayMachine } from './relay-machine.js';+import { requirePersonChannel } from './person.js';++/** Read an exclusion without inferring a missing historical actor or timestamp. */+export function relayExclusion(root) {+ const project = repoInfo(root).root;+ const state = readRelayMachine();+ if (!state.excluded.includes(project)) return null;+ const detail = state.exclusionDetails?.[project];+ return { reason: detail?.reason ?? 'unknown historical exclusion', at: detail?.at ?? null,+ by: detail?.by ?? null, path: detail?.path ?? null, eventId: detail?.eventId ?? null,+ next: 'pullboard relay on' };+}++/** Successful local unlink remains available to agents; only a person can persist an opt-out. */+export function excludeRelayByPerson(root, io, record) {+ 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 = record({ path: 'relayOff', reason: 'person relay off', channel, action: 'exclude' });+ updateRelayMachine(state => {+ if (!state.excluded.includes(project)) state.excluded.push(project);+ state.exclusionDetails ??= {};+ state.exclusionDetails[project] = { reason: 'person relay off', path: 'relayOff',+ by: receipt.by, at: receipt.at, eventId: receipt.eventId };+ });+ return true;+}++/** Clear only this board's opt-out once a newly authorized link has actually finished. */+export function clearRelayExclusion(root) {+ const project = repoInfo(root).root;+ return updateRelayMachine(state => {+ const existed = state.excluded.includes(project);+ state.excluded = state.excluded.filter(entry => entry !== project);+ if (state.exclusionDetails) delete state.exclusionDetails[project];+ return existed;+ });+}diff --git a/src/relay-output.js b/src/relay-output.jsindex 96e738a1..65801228 100644--- a/src/relay-output.js+++ b/src/relay-output.js@@ -9,6 +9,7 @@ import {/** Preserve status's short relay summary, any pending-size finding and the authenticated account quota. */export function briefLines(state) {const lines = [];+ if (state.excluded) lines.push(`relay excluded: ${state.exclusion.reason}${state.exclusion.at ? ' at ' + state.exclusion.at : ' (time unknown)'}; ${state.exclusion.next}`);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));@@ -31,6 +32,7 @@ export function outboxLines(state) {/** Preserve the named relay-status link and account lines, including recovery and deleted-copy guidance. */export function detailLines(result, boardName) {const lines = [];+ if (result.excluded) lines.push(`relay excluded: ${result.exclusion.reason}${result.exclusion.at ? ' at ' + result.exclusion.at : ' (time unknown)'}; ${result.exclusion.next}`);lines.push(result.linked ? `${result.link}\nrelay: ${boardName} (board ${result.board}) is linked for GitHub ${result.login || `account ${result.account}`}; sequence ${result.sequence}; ${result.behind} pending uploads${result.recovery?.pending ? `; recovery pending for sequence ${result.recovery.skip}; retry ${result.recovery.next}` : ''}` : (result.notice || 'relay off; the local board is complete'));if (result.storage) lines.push(relayStorageLine(result.storage));return lines;diff --git a/src/relay.js b/src/relay.jsindex 8be545c3..55bb0d49 100644--- a/src/relay.js+++ b/src/relay.js@@ -1,3 +1,6 @@+import { relayExclusion } from './relay-exclusion-state.js';+import { excludeRelayByPerson } from './relay-exclusion-state.js';+import { clearRelayExclusion } from './relay-exclusion-state.js';import {cancellationOutcome,waitForDevicePoll,@@ -299,12 +302,13 @@ function deletedMoveResult(root, operation, args, command, io, applyLocally) {function forgetDeletedCopy(root, file, state, io) {const recovered = retainDeletedMove(root, state);saveDeletedLink(root, { version: 1, board: state.board, url: state.url, ...(recovered ? { recovered } : {}) });- updateRelayMachine(machine => { const project = repoInfo(root).root; if (!machine.excluded.includes(project)) machine.excluded.push(project); });+ rememberRelink(root, state.board);+ archiveRelinkOutbox(root, state);rmSync(file, { force: true });try { forgetBoardKey(state.board, state.keyStorage); } catch { /* An unavailable key store cannot block completed local opt-out. */ }if (!DELETION_NOTICES.has(io)) {DELETION_NOTICES.add(io);- io.err(`pullboard: [RELAY_BOARD_DELETED] relay copy ${state.board} was deleted; local work continues; run pullboard relay on only to link it again`);+ io.err(`pullboard: [RELAY_BOARD_DELETED] relay copy ${state.board} was deleted; local work continues; run pullboard relay on for fresh person approval to link it again`);}}@@ -452,7 +456,8 @@ function behind(root, state) {function summary(root, state, { pairing = false } = {}) {if (!state) {const deleted = deletedLink(root);- return unlinkedRelayStatus(deleted);+ const exclusion = relayExclusion(root);+ return { ...unlinkedRelayStatus(deleted), ...(exclusion ? { excluded: true, exclusion } : {}) };}if (state.unlinking) return { linked: false, board: state.board, url: state.url, link: '', sequence: state.sequence, behind: 0, cleanup: true, recovery: recoverySummary(state) };const fragment = pairing ? '&key=' + encodeBoardKey(readBoardKey(state.board)) : '';@@ -1630,6 +1635,7 @@ export async function relayOn(root, address, io, { session, credential, quiet =// The person's own sign-in sets up the coordinator's token, so no agent can mint it (#579).if (/^ps_[A-Za-z0-9_-]{43}$/u.test(signed.token ?? '')) { await ensurePersonCoordinator(file, state, signed.token, io); await syncApprovers(root, state, signed.token, io); }let result;+ let clearedExclusion = false;try {let ready = true;if (state.mode === 'ordered' && state.snapshot) {@@ -1647,7 +1653,7 @@ export async function relayOn(root, address, io, { session, credential, quiet =await flushOutbox(outboxLink(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); });+ clearedExclusion = clearRelayExclusion(root);if (reusableSession === undefined) await publishExcludedBoards({ ...signed, account, url }, io, request);}result = summary(root, state, { pairing: !quiet });@@ -1660,13 +1666,20 @@ export async function relayOn(root, address, io, { session, credential, quiet =delete state.previousBoardNotice;saveLink(file, state);}+ if (clearedExclusion) {+ result.notice = [result.notice, 'The exclusion was cleared; this board is linked again.'].filter(Boolean).join(' ');+ io.err('The exclusion was cleared; this board is linked again.');+ }return result;});}/** Unlink locally without approval, then request a separate phone-approved remote deletion if possible. */export async function relayOff(root, io) {- updateRelayMachine(machine => { const project = repoInfo(root).root; if (!machine.excluded.includes(project)) machine.excluded.push(project); });+ excludeRelayByPerson(root, io, detail => localRecords(root, board => {+ store.logEvent(board, store.PERSON, 'relay_exclusion', null, detail);+ return { by: board.lastEvent.event_by, at: board.lastEvent.event_at, eventId: board.lastEvent.event_id };+ }));const file = linkFile(root);return locked(file, async () => {const state = loadLink(file);diff --git a/test/relay-exclusion-fixture.js b/test/relay-exclusion-fixture.jsindex 39ec50b1..014f4729 100644--- a/test/relay-exclusion-fixture.js+++ b/test/relay-exclusion-fixture.js@@ -51,6 +51,9 @@ export async function relayOnClearsExclusion(t) {await box.link();assert.equal((await box.cli('relay', 'off')).code, 0);assert.equal(machine(box).excluded.includes(box.root), true, 'the person may persist an opt-out');+ const audit = (await box.cli('export')).document.tables.event.filter(row => row.event_kind === 'relay_exclusion').at(-1);+ assert.equal(audit.event_by, 'person');+ assert.equal(JSON.parse(audit.event_detail).path, 'relayOff');const status = await box.cli('status');assert.equal(status.code, 0);assert.equal(status.document.relay.excluded, true, 'normal status makes the durable opt-out visible');@@ -62,4 +65,27 @@ export async function relayOnClearsExclusion(t) {assert.match(linked.document.notice, /exclusion.*clear|clear.*exclusion/iu, 'successful explicit on names the cleared exclusion');assert.equal(machine(box).excluded.includes(box.root), false);assert.equal((await box.cli('status')).document.relay.excluded, undefined, 'a cleared exclusion is no longer reported');+ const count = (await box.cli('export')).document.tables.event.filter(row => row.event_kind === 'relay_exclusion').length;+ box.env.AI_AGENT = '1'; box.env.SSH_CONNECTION = 'fixture remote agent';+ const agentOff = await box.cli('relay', 'off');+ delete box.env.AI_AGENT; delete box.env.SSH_CONNECTION;+ assert.equal(agentOff.code, 0, 'an agent can still stop local syncing');+ assert.equal(machine(box).excluded.includes(box.root), false, 'an agent cannot persist a person opt-out');+ assert.equal((await box.cli('export')).document.tables.event.filter(row => row.event_kind === 'relay_exclusion').length, count, 'an agent cannot create person exclusion provenance');+}++/** 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');+ 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);+ assert.equal(receipt.event_by, 'person');+ assert.equal(receipt.event_kind, 'relay_exclusion');+ const detail = JSON.parse(receipt.event_detail);+ assert.equal(detail.path, 'relayOff');+ assert.equal(detail.reason, 'person relay off');+ assert.equal(detail.action, 'exclude');+ assert.equal(detail.channel, 'terminal');+ assert.ok(Number.isFinite(Date.parse(receipt.event_at)));}diff --git a/test/relay.test.js b/test/relay.test.jsindex 638dd70a..ec442343 100644--- a/test/relay.test.js+++ b/test/relay.test.js@@ -1044,7 +1044,7 @@ test('relay off forgets expired and remotely deleted boards while preserving locassert.match(off.document.notice, /Local link removed/u);assert.equal(existsSync(box.linkFile), false, 'local link metadata is forgotten');assert.equal(existsSync(box.keyFile), false, 'device-only fallback key is forgotten');- assert.deepEqual((await box.cli('export')).document.tables, localBeforeOff, 'local rows and event history survive remote deletion or expiry');+ assertPersonUnlinkHistory((await box.cli('export')).document.tables, localBeforeOff);assert.ok(JSON.parse(readFileSync(join(box.env.PULLBOARD_HOME, 'relay-machine/state.json'), 'utf8')).excluded.includes(box.root),'the local opt-out remains durable after unlink');assert.equal(box.calls.slice(callsBeforeOff).some(call => call.method === 'DELETE'), false,@@ -1069,7 +1069,7 @@ test('relay off completes local unlink when the relay is offline [H1,H7,H18]', aassert.equal(existsSync(box.keyFile), false);assert.ok(JSON.parse(readFileSync(join(box.env.PULLBOARD_HOME, 'relay-machine/state.json'), 'utf8')).excluded.includes(box.root),'the local opt-out remains durable');- assert.deepEqual((await box.cli('export')).document.tables, localBeforeOff, 'offline unlink preserves all local rows');+ assertPersonUnlinkHistory((await box.cli('export')).document.tables, localBeforeOff);assert.equal(box.calls.length, callsBeforeOff, 'offline local unlink makes no relay request');assert.equal(box.calls.some(call => call.method === 'DELETE'), false, 'offline local unlink cannot delete the remote copy');});@@ -1450,6 +1450,6 @@ test('every real CLI relay request declares its engine including sign-in, reads,});// These real-protocol cases live outside the near-cap relay fixture file.-import { deletedCopyRelinks, relayOnClearsExclusion } from './relay-exclusion-fixture.js';+import { deletedCopyRelinks, relayOnClearsExclusion, assertPersonUnlinkHistory } from './relay-exclusion-fixture.js';test('a deleted relay copy relinks rather than excluding the board [H5,H17]', deletedCopyRelinks);test('relay on clears an exclusion and names it [H5,H17,B26]', relayOnClearsExclusion);