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): an env session never overwrites another link [E18]
Corey Olson02b571f23447
diff --git a/docs/api.md b/docs/api.mdindex b10539f2..5b9265b2 100644--- a/docs/api.md+++ b/docs/api.md@@ -522,7 +522,7 @@ upgrade guidance; it never returns an older or partial image.Every session on a paired machine reads the board: a terminal, SSH, an agent, a scheduled job or CI. `relay on` keeps the board key only in the owner-only file `relay-keys/<board>.key` under the pullboard home, even where a keychain exists. A session that cannot read that file still reads the local board with every read command, `resume` included: resume reports once that the key is not reachable and leaves its own bookkeeping moves to a session that holds it. A move in such a session is refused with `RELAY_KEY_MISSING` and nothing is sent.-A CI or cloud session that cannot pair sets `PULLBOARD_RELAY_TOKEN` to one agent token, `PULLBOARD_RELAY_KEY` to the board key and, for a relay other than app.pullboard.dev, `PULLBOARD_RELAY_URL`. In a clone with no relay link, its first command asks the relay for the token's one board, reads that board's sealed snapshot with the key and writes the local board, plus a `relay.json` marked `environment` that names the token's agent and holds neither the token nor the key. Every later command reads and moves as that agent, on that one board; a token for any other board is refused (`TOKEN_BOARD`).+A CI or cloud session that cannot pair sets `PULLBOARD_RELAY_TOKEN` to one agent token, `PULLBOARD_RELAY_KEY` to the board key and, for a relay other than app.pullboard.dev, `PULLBOARD_RELAY_URL`. In a clone with no relay link, its first command asks the relay for the token's one board, reads that board's sealed snapshot with the key and writes the local board, plus a `relay.json` marked `environment` that names the token's agent and holds neither the token nor the key. Every later command reads and moves as that agent, on that one board; a token for any other board is refused (`TOKEN_BOARD`). A clone already linked to another board keeps its `relay.json`: the environment never overwrites it, reads go on with a `RELAY_LINKED` notice, and moves are refused.## Sealed person requestsdiff --git a/src/relay-environment.js b/src/relay-environment.jsindex 7b9a7499..c2c2ba2c 100644--- a/src/relay-environment.js+++ b/src/relay-environment.js@@ -25,10 +25,23 @@ import { appliedSequence } from './engine.js';import { importBoard } from './exchange.js';const TOKEN = /^pa_[A-Za-z0-9_-]{43}$/u;+/** Link files this process has already matched to the environment's board, so each command asks the relay once. */+const CHECKED = new Set();++/**+ * The board an existing link file names, or null when it cannot be read.+ *+ * @param {string} file+ * @returns {string | null}+ */+function linkedBoard(file) {+ try { return JSON.parse(readFileSync(file, 'utf8'))?.board ?? null; } catch { return null; }+}/*** 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.+ * board key and the clone has no link yet. Returns whether it linked. A clone already linked keeps its link, and one+ * linked to a board other than the token's is refused, so the environment never overwrites another board's link.** @param {string} root* @param {string} file - the clone's relay.json@@ -37,12 +50,24 @@ const TOKEN = /^pa_[A-Za-z0-9_-]{43}$/u;*/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 === undefined || process.env.PULLBOARD_RELAY_KEY === undefined || CHECKED.has(file)) return false;+ const linked = existsSync(file);+ if (linked && !TOKEN.test(token)) 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);+ const { boards } = linked ? await request(probe, '/auth/boards', {}, io).catch(() => ({})) : await request(probe, '/auth/boards', {}, io);+ if (linked) {+ // An existing link stays as it is; one for another board is never overwritten by the environment. An offline relay+ // leaves the check to the next command, so reads keep working.+ if (Array.isArray(boards) && boards.length === 1 && boards[0].id !== linkedBoard(file)) {+ const [here, there] = [linkedBoard(file), boards[0].id].map((board) => String(board).slice(0, 8));+ throw new Refused('RELAY_LINKED', `this clone is linked to board ${here}, but PULLBOARD_RELAY_TOKEN belongs to board ${there}; unset it here, or use a fresh clone`);+ }+ if (Array.isArray(boards)) CHECKED.add(file);+ return false;+ }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') {diff --git a/src/relay.js b/src/relay.jsindex 65dbeeff..77ed0bf0 100644--- a/src/relay.js+++ b/src/relay.js@@ -1264,7 +1264,7 @@ export async function syncRelay(root, io) {const file = files.get(root) ?? linkFile(root);files.set(root, file);// 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;+ if (!await environmentLink(root, file, io) && !existsSync(file)) 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 03c7bdf0..4e66163c 100644--- a/test/team.test.js+++ b/test/team.test.js@@ -555,6 +555,19 @@ test('every session reads and moves: terminal, SSH, agent, job or CI [E9,E18]',const shown = JSON.stringify(output.document) + (output.failure ?? '');assert.equal(shown.includes(token) || shown.includes(key), false, 'no output repeats a secret');}+ // A clone already linked to another board keeps its link: the environment never overwrites it.+ const otherLink = join(ciRoot, '.git', 'pullboard', 'relay.json');+ const elsewhere = JSON.stringify({ ...JSON.parse(readFileSync(otherLink, 'utf8')), board: 'f'.repeat(32) });+ writeFileSync(otherLink, elsewhere, { mode: 0o600 });+ const warned = await ci('status');+ assert.match(JSON.stringify(warned.document?.diagnostics ?? []), /RELAY_LINKED/u, 'the environment names the link to another board and the read goes on');+ const refused = await ci('add', box.lane, 'Added across boards');+ assert.notEqual(refused.code, 0, 'a session on another board’s link does not move');+ for (const output of [warned, refused]) {+ const shown = JSON.stringify(output.document) + (output.failure ?? '');+ assert.equal(shown.includes(token) || shown.includes(key), false, 'the refusal repeats no secret');+ }+ assert.equal(readFileSync(otherLink, 'utf8'), elsewhere, 'the other board’s link is left as it was');});/** A file's permission bits. */