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): every session reads and moves, CI from its env [E9,E18]
Corey Olsone2197e5da205
diff --git a/src/cli.js b/src/cli.jsindex 81d83547..a7442ff7 100644--- a/src/cli.js+++ b/src/cli.js@@ -38,6 +38,7 @@ import {refuseNextIdle,} from './next-steps.js';import { reviewerStartup } from './next-steps.js';+import { environmentAgent } from './relay-environment.js';import { judgeTrunkMove } from './verdict-trunk.js';import * as gateReceipt from './gate-receipt.js';import * as itemSessions from './item-sessions.js';@@ -361,7 +362,6 @@ import {unlinkedRelayProjects,} from './relay-setup.js';import { executePersonRequests } from './relay-request-execution.js';-import { engineReceipt } from './engine.js';import {accountedFailures,landingRemote,@@ -1030,6 +1030,9 @@ export function refuseRemoteCoordinatorModel(ctx, command) {* @returns {{ id: string, lane: string, route?: string, family: string | null, model: string | null, displayName: string }}*/export function whoAmI(ctx, board) {+ // A CI or cloud session works as the agent its environment token names, on that one board [E18].+ const seat = environmentAgent(ctx.info.root, board);+ if (seat) return { id: seat.agent_id, lane: seat.agent_lane, route: seat.agent_route, family: seat.agent_family ?? null, model: seat.agent_model ?? 'unknown', displayName: displayAgentName(seat, ctx.config.agents.names) };if (ctx.info.isMain) {ctx.io.caller?.('coordinator', ctx.info.root);const registered = store.listAgents(board).find((agent) => agent.agent_id === COORDINATOR);@@ -1342,12 +1345,6 @@ export function refuseUnverifiedStack(root, board, item, commit, trunk) {}}-/** Return the durable outcome only when a recovered move exactly matches its original receipt. */-export function recordedRecovery(board, move) {- const receipt = engineReceipt(board, move.id);- return receipt?.move === JSON.stringify(move) ? receipt : null;-}-/*** How long ago an ISO time was, or how long until it, in the board's clock: 45m, 3h, 2d.*diff --git a/src/commands/resume.js b/src/commands/resume.jsindex db2aef43..e74da4f9 100644--- a/src/commands/resume.js+++ b/src/commands/resume.js@@ -88,7 +88,7 @@ import {coordinatorNext,dirtyFiles,firstLine,- ordered,+ ordered as sendOrdered,primaryCheckoutRoot,resumeReleaseNotes,reworkNext,@@ -103,6 +103,27 @@ import {worktreeLocation,} from '../cli.js';+/**+ * Resume's own moves (the approval baseline, health findings, due watches) are bookkeeping: a session that cannot+ * reach the board key (SSH, a scheduled job, a locked keychain) still reads the whole card, and the moves wait for a+ * session that can. Every read works without the key [E9].+ *+ * @param {typeof sendOrdered} send+ * @returns {typeof sendOrdered}+ */+function keylessBookkeeping(send) {+ let noted = false;+ return async (ctx, board, operation, args) => {+ try { return await send(ctx, board, operation, args); }+ catch (error) {+ if (!(error instanceof Refused) || error.code !== 'RELAY_KEY_MISSING') throw error;+ if (!noted) ctx.io.err?.('pullboard: the board key is not reachable in this session, so resume reads the local board and leaves its bookkeeping moves to a session that holds the key');+ noted = true;+ return null;+ }+ };+}+/*** `pullboard resume` (N19): one short card that puts an agent back to work after a fresh start,* a restart or a compaction, from the board rather than from a summary.@@ -113,6 +134,7 @@ import {*/export async function resumeHere(io, view) {const ctx = context(io);+ const ordered = keylessBookkeeping(sendOrdered);await withBoard(ctx, async board => {const me = whoAmI(ctx, board);// Bootstrap is an ordered move: observe health only after it, so the first legacy scan is not stale.diff --git a/src/commands/submit.js b/src/commands/submit.jsindex 0a9b111b..4d2e4cb9 100644--- a/src/commands/submit.js+++ b/src/commands/submit.js@@ -67,13 +67,13 @@ import {idArg,ordered,queuedItemLease,- recordedRecovery,refuseUnverifiedStack,reportSubmission,resourceAgent,whoAmI,withBoard,} from '../cli.js';+import { recordedRecovery } from '../recorded-recovery.js';/*** Submit: a clean tree, nothing untracked, the gate green at HEAD, then the board (V4).diff --git a/src/commands/verify.js b/src/commands/verify.jsindex 84e50e6d..177a5faa 100644--- a/src/commands/verify.js+++ b/src/commands/verify.js@@ -71,13 +71,13 @@ import {landNext,ordered,queuedItemLease,- recordedRecovery,refuseUnverifiedStack,resourceAgent,textArg,whoAmI,withBoard,} from '../cli.js';+import { recordedRecovery } from '../recorded-recovery.js';/*** Verify from this checkout (V3, V7): the submitted commit must be here, at or under HEAD, and thediff --git a/src/recorded-recovery.js b/src/recorded-recovery.jsnew file mode 100644index 00000000..cdee9360--- /dev/null+++ b/src/recorded-recovery.js@@ -0,0 +1,8 @@+/** A recovered move's durable outcome, in its own module so commands reach it without the CLI module [B26]. */+import { engineReceipt } from './engine.js';++/** Return the durable outcome only when a recovered move exactly matches its original receipt. */+export function recordedRecovery(board, move) {+ const receipt = engineReceipt(board, move.id);+ return receipt?.move === JSON.stringify(move) ? receipt : null;+}diff --git a/src/relay-environment.js b/src/relay-environment.jsnew file mode 100644index 00000000..7b9a7499--- /dev/null+++ b/src/relay-environment.js@@ -0,0 +1,76 @@+/**+ * A CI or cloud session's board, from its environment alone [E18]. A session that cannot pair holds an agent token+ * (PULLBOARD_RELAY_TOKEN) and the board key (PULLBOARD_RELAY_KEY), and optionally the relay address+ * (PULLBOARD_RELAY_URL). On its first command in a clone with no relay link, the relay names the token's board and+ * agent; the session reads that board's sealed snapshot with the key and then works as that agent. The link it saves+ * holds neither the token nor the key, so nothing secret lands on disk, and its scope is the token's one board.+ */+import {+ existsSync,+ readFileSync,+} from 'node:fs';+import { join } from 'node:path';+import { repoInfo } from './git.js';+import { Refused } from './refused.js';+import {+ DEFAULT_RELAY,+ localRecords,+ relayOrigin,+ request,+ restoreCheckpoint,+ saveLink,+} from './relay.js';+import { readBoardKey } from './relay-key.js';+import { appliedSequence } from './engine.js';+import { importBoard } from './exchange.js';++const TOKEN = /^pa_[A-Za-z0-9_-]{43}$/u;++/**+ * Link this clone to the board its environment names, once, when the environment holds both an agent token and a+ * board key and the clone has no link yet. Returns whether it linked.+ *+ * @param {string} root+ * @param {string} file - the clone's relay.json+ * @param {{ err?: (line: string) => void }} io+ * @returns {Promise<boolean>}+ */+export async function environmentLink(root, file, io) {+ const token = process.env.PULLBOARD_RELAY_TOKEN;+ if (token === undefined || process.env.PULLBOARD_RELAY_KEY === undefined || existsSync(file)) return false;+ if (!TOKEN.test(token)) throw new Refused('AUTH_REQUIRED', 'set PULLBOARD_RELAY_TOKEN to one agent token for this board, never in command arguments');+ const url = relayOrigin(process.env.PULLBOARD_RELAY_URL || DEFAULT_RELAY);+ const probe = { version: 1, board: '0'.repeat(32), url, token, sequence: 0, cursor: 0 };+ // A board token sees exactly its own board; the session then names the agent it acts as.+ const { boards } = await request(probe, '/auth/boards', {}, io);+ if (!Array.isArray(boards) || boards.length !== 1) throw new Refused('RELAY_ACTOR', 'PULLBOARD_RELAY_TOKEN must be one agent token, scoped to one board');+ const { session } = await request(probe, '/auth/session?board=' + boards[0].id, {}, io);+ if (session?.kind !== 'board' || !/^[0-9a-f]{32}$/u.test(session.board ?? '') || typeof session.agent !== 'string') {+ throw new Refused('RELAY_ACTOR', 'PULLBOARD_RELAY_TOKEN must be one agent token, scoped to one board');+ }+ const state = { version: 1, mode: 'ordered', board: session.board, url, token: null, personReauth: true, environment: { agent: session.agent },+ sequence: 0, cursor: 0, baselineAccepted: true };+ // The clone has no board of its own yet: the relay's snapshot becomes it, as a pairing would bring it.+ await restoreCheckpoint(root, state, io, readBoardKey(state.board), (board, native) => importBoard(board, native));+ state.sequence = localRecords(root, appliedSequence);+ state.cursor = localRecords(root, (board) => board.db.prepare('SELECT COALESCE(MAX(event_id), 0) AS id FROM event').get().id);+ saveLink(file, state);+ io.err?.(`pullboard: this session works on board ${state.board.slice(0, 8)} as ${session.agent}, from its environment; no key file or token is stored`);+ return true;+}++/**+ * The agent an environment session works as, when this clone's link came from its environment and the token is still+ * there, or null. Reading the link file directly keeps this a pure read with no relay contact.+ *+ * @param {string} root+ * @param {{ db: any }} board+ * @returns {object | null} the agent row+ */+export function environmentAgent(root, board) {+ if (process.env.PULLBOARD_RELAY_TOKEN === undefined) return null;+ let state;+ try { state = JSON.parse(readFileSync(join(repoInfo(root).commonDir, 'pullboard', 'relay.json'), 'utf8')); } catch { return null; }+ const agent = state?.environment?.agent;+ return typeof agent === 'string' ? board.db.prepare('SELECT * FROM agent WHERE agent_id = ?').get(agent) ?? null : null;+}diff --git a/src/relay.js b/src/relay.jsindex cd2c3b6d..65dbeeff 100644--- a/src/relay.js+++ b/src/relay.js@@ -88,6 +88,7 @@ import {unseal,} from './seal.js';import { terminalQr } from './qr.js';+import { environmentLink } from './relay-environment.js';import { locked } from './relay-lock.js';import {decideUncertainBaseline,@@ -964,14 +965,14 @@ async function ensureOrdered(root, file, state, io) {}/** Restore a compacted, authenticated native prefix before receiving any following operations. */-async function restoreCheckpoint(root, state, io, key) {+export async function restoreCheckpoint(root, state, io, key, restore = restoreRelaySnapshot) {const document = await request(state, '/api/v1/boards/' + state.board + '/state', {}, io);const snapshot = document.state;if (!snapshot || !Number.isSafeInteger(snapshot.sequence) || snapshot.sequence < 0) throw new Refused('RELAY_RESPONSE', 'the relay snapshot has no valid coverage sequence; fetch it again');const senderProblem = relaySenderProblem(null, snapshot.sender, 'snapshot');if (senderProblem) throw senderProblem;const native = await decoded(key, snapshot, state, 'snapshot', snapshot.sequence);- localRecords(root, (board) => restoreRelaySnapshot(board, native, snapshot.sequence));+ localRecords(root, (board) => restore(board, native, snapshot.sequence));}/**@@ -1259,11 +1260,11 @@ export async function relayOperation(root, operation, args, io, command, applyLo/** Catch up an opted-in replica before/after a CLI command; offline reads retain local evidence. */export async function syncRelay(root, io) {// Reuse Git discovery only within this command; still re-read the link before each retry.- let files = LINK_FILES.get(io);- if (!files) { files = new Map(); LINK_FILES.set(io, files); }+ const files = LINK_FILES.get(io) ?? LINK_FILES.set(io, new Map()).get(io);const file = files.get(root) ?? linkFile(root);files.set(root, file);- if (!existsSync(file)) return null;+ // A CI or cloud session with an agent token and a board key in its environment links itself once [E18].+ if (!existsSync(file) && !await environmentLink(root, file, io)) return null;return locked(file, async () => {const state = loadLink(file);if (!state) return null;diff --git a/test/team.test.js b/test/team.test.jsindex b917a268..03c7bdf0 100644--- a/test/team.test.js+++ b/test/team.test.js@@ -10,6 +10,13 @@ import { after, test } from 'node:test';import * as store from '../src/board.js';import { exportBoard, importBoard } from '../src/exchange.js';import { applyEngineMove, prepareEngineMove } from '../src/engine.js';+import { readdirSync } from 'node:fs';+import { lstatSync } from 'node:fs';+import { renameSync } from 'node:fs';+import { symlinkSync } from 'node:fs';+import { relayClientFixture as sessionRelay } from './relay-client-fixture.js';+import { relayFixtureChild as sessionChild } from './relay-client-fixture.js';+import { runFixtureGit as sessionGit } from './fixture-child.js';import { createE2eHelpers } from './e2e-helpers.js';import { serveApi } from '../src/api.js';import { main } from '../src/cli.js';@@ -467,3 +474,88 @@ test('an older pushed landing shows stale checked proof and a correction path ac'a later correction containing the checked composition clears the derived warning without rewriting the old landing');assert.equal(withBoard(box.repo, board => store.getItem(board, 1)).item_merged_commit, submitted);});+++/** Every file under a directory, so a test can prove no secret was written anywhere in it. */+function filesUnder(directory) {+ if (!existsSync(directory)) return [];+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? filesUnder(join(directory, entry.name)) : [join(directory, entry.name)]);+}++test('every session reads and moves: terminal, SSH, agent, job or CI [E9,E18]', { timeout: 240_000 }, async (t) => { // budget: hang ceiling for real CLI runs on three homes and a loopback relay; not a speed target.+ const box = await sessionRelay(t);+ const cli = join(import.meta.dirname, '..', 'bin', 'pullboard.js');++ // S6d: on a machine with a keychain, relay on keeps the key in the owner-only file every session can read.+ const keychainBin = join(box.root, '..', 'keychain-bin');+ mkdirSync(keychainBin, { mode: 0o700 });+ for (const name of readdirSync(box.env.PATH)) symlinkSync(join(box.env.PATH, name), join(keychainBin, name));+ const keychainLog = join(box.root, '..', 'keychain-calls.log');+ for (const name of ['security', 'secret-tool']) {+ writeFileSync(join(keychainBin, name), `#!/bin/sh\necho "$1" >> ${JSON.stringify(keychainLog)}\n[ "$1" = search ] && exit 1\nexit 0\n`, { mode: 0o755 });+ }+ const plainPath = box.env.PATH;+ box.env.PATH = keychainBin;+ assert.equal((await box.link()).code, 0, 'relay on links the board on a machine with a keychain');+ box.env.PATH = plainPath;+ const keys = join(box.env.PULLBOARD_HOME, 'relay-keys');+ assert.deepEqual(readdirSync(keys).filter((name) => name.endsWith('.key')).length, 1, 'the key sits in one owner-only file');+ assert.equal(statSyncMode(box.keyFile), 0o600, 'the key file is owner-only');+ const writes = existsSync(keychainLog) ? readFileSync(keychainLog, 'utf8').split('\n').filter((call) => ['add-generic-password', 'store'].includes(call)) : [];+ assert.deepEqual(writes, [], 'relay on never writes the key to the keychain');++ // S6b: a session that cannot read the key (SSH, a scheduled job, a locked keychain) still reads the whole board.+ assert.equal((await box.cli('add', box.lane, 'Read from any session')).code, 0);+ renameSync(keys, keys + '.parked');+ try {+ for (const command of [['list'], ['show', '1'], ['inbox'], ['whoami'], ['status'], ['resume'], ['log']]) {+ const read = await box.cli(...command);+ assert.equal(read.code, 0, `${command[0]} reads without the key: ${JSON.stringify(read.document?.error ?? null)}`);+ }+ const move = await box.cli('add', box.lane, 'Needs the key');+ assert.equal(move.document?.error?.code, 'RELAY_KEY_MISSING', 'a move without the key is refused, never sent or lost');+ } finally { renameSync(keys + '.parked', keys); }++ // S6c: a CI or cloud session, with an agent token and the board key in its environment and no key file, reads and moves.+ // The project's committed setup is what every checkout, CI's included, gets.+ sessionGit(['add', '-A'], { cwd: box.root, env: box.env });+ sessionGit(['-c', 'core.hooksPath=/dev/null', 'commit', '-q', '-m', 'chore: set up pullboard'], { cwd: box.root, env: box.env });+ const seatRoot = join(box.root, '..', 'ci-seat');+ sessionGit(['worktree', 'add', '-q', '-b', 'ci-seat', seatRoot], { cwd: box.root, env: box.env });+ const joined = await box.cliAt(seatRoot, 'join', box.lane, '--model', 'fixture-model');+ assert.equal(joined.code, 0, `the person gives CI its own seat: ${JSON.stringify(joined.document?.error ?? null)}`);+ const seat = (await box.cliAt(seatRoot, 'whoami')).document;+ assert.equal((await box.cliAt(seatRoot, 'shout', 'coordinator', 'the CI seat is ready')).code, 0, 'the seat moves once, which mints its token');+ const link = JSON.parse(readFileSync(box.linkFile, 'utf8'));+ const token = link.agentTokens?.[seat.id]?.token;+ assert.match(token ?? '', /^pa_/u, 'the seat holds its own agent token');+ const ciRoot = join(box.root, '..', 'ci-clone');+ sessionGit(['clone', '-q', box.root, ciRoot], { cwd: box.root, env: box.env });+ sessionGit(['remote', 'set-url', 'origin', '[email protected]:fixture/repository.git'], { cwd: ciRoot, env: box.env });+ const ciHome = join(box.root, '..', 'ci-home');+ mkdirSync(ciHome, { mode: 0o700 });+ const key = readFileSync(box.keyFile, 'utf8').trim();+ const ciEnv = { ...box.env, HOME: ciHome, PULLBOARD_HOME: join(ciHome, '.pullboard'), PULLBOARD_MACHINE_HOME: join(ciHome, 'machine'),+ PULLBOARD_RELAY_TOKEN: token, PULLBOARD_RELAY_KEY: key, PULLBOARD_RELAY_URL: box.origin };+ const ci = (...args) => sessionChild(ciRoot, ciEnv, [cli, ...args, '--json']);+ const status = await ci('status');+ assert.equal(status.code, 0, 'CI reads the board');+ const listed = await ci('list', '--all');+ assert.ok(listed.document.items.some((item) => (item.title ?? item.item_title) === 'Read from any session'),+ `CI reads the board’s items: ${JSON.stringify(listed.document.items?.map((item) => item.title ?? item.item_title))} ${JSON.stringify(status.document).replaceAll(token, '<token>').replaceAll(key, '<key>').slice(0, 900)}`);+ const added = await ci('add', box.lane, 'Added from CI');+ assert.equal(added.code, 0, `CI moves on the board: ${JSON.stringify(added.document?.error ?? null)}`);+ assert.equal((await box.cli('status')).code, 0);+ const items = (await box.cli('export')).document.tables.item;+ assert.ok(items.some((item) => item.item_title === 'Added from CI'), 'the CI move reaches the person’s board');+ assert.equal(filesUnder(join(ciEnv.PULLBOARD_HOME, 'relay-keys')).length, 0, 'CI keeps no key file');+ const written = [...filesUnder(join(ciRoot, '.git', 'pullboard')), ...filesUnder(ciHome)].map((file) => readFileSync(file)).map((bytes) => bytes.toString('latin1'));+ assert.equal(written.some((text) => text.includes(token) || text.includes(key)), false, 'neither the token nor the key is written to disk');+ for (const output of [status, listed, added]) {+ const shown = JSON.stringify(output.document) + (output.failure ?? '');+ assert.equal(shown.includes(token) || shown.includes(key), false, 'no output repeats a secret');+ }+});++/** A file's permission bits. */+function statSyncMode(file) { return lstatSync(file).mode & 0o777; }