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): the coordinator hold follows its checkout's machine [E19]

Corey Olsonf834f93c8b0a
diff --git a/src/board.js b/src/board.js
index d1706593..3a887d6a 100644
--- a/src/board.js
+++ b/src/board.js
@@ -129,7 +129,7 @@ export { flakeLedger, recordFlakeObservation } from './flakes.js';
export { flakeQuarantines, gateRuns, recordGateRun } from './quarantine.js';
/** The seat readers live in seats.js; the board re-exports them so `store.*` callers keep one import. */
-export { agentAt, agentCreator, listAgents, nextSeatId, seatEnrolled, seatLineage, withVerifierStanding } from './seats.js';
+export { agentAt, agentCreator, coordinatorHolder, listAgents, nextSeatId, seatEnrolled, seatLineage, takeCoordinator, withVerifierStanding } from './seats.js';
export const ACCEPT_REASON = 'CRITERION_MET';
export const PERSON = 'person';
@@ -2575,7 +2575,6 @@ export function milestones(board) {
// A lane agent's drafted rows live in row-drafts.js (#878); exported here so the engine dispatches them.
export { draftSpecRow, rowDrafts } from './row-drafts.js';
-export { coordinatorHolder, takeCoordinator } from './coordinator-hold.js';
export { recordSpecApprovalBaseline, specApprovalBaseline, specApprovalBaselineExists } from './spec-approval-baseline.js';
// The roadmap's moves live in milestones.js; the board keeps exporting them so the engine replays them.
export { addMilestone, canonicalMilestoneTarget, editMilestone, editMilestoneItems, orderMilestoneItems, moveMilestone, removeMilestone, roadmap, shipMilestone } from './milestones.js';
diff --git a/src/cli.js b/src/cli.js
index f9cad9a1..916a1636 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -930,7 +930,7 @@ export async function claimOrdered(ctx, board, args) {
return await ordered(ctx, board, 'claim', args);
}
-/** Check ownership before sync or command side effects; reads and authenticated person channels keep their identity. */
+/** Check ownership before sync or command side effects; reads and authenticated person channels keep their identity. A person's takeover in a linked main checkout binds no session (#347). */
async function bindCheckoutSession(io, positionals, values) {
if (values.help || values.version || io.personChannel === 'view' || io.personRequest) return;
const [command, first] = positionals;
@@ -943,10 +943,7 @@ async function bindCheckoutSession(io, positionals, values) {
if (command === 'answer' && values.as === 'person') return;
const digest = agentSessionDigest();
if (!digest) {
- // A person's shell in a linked main checkout takes the board's coordinator; it binds no agent session (#347).
- if (command === 'takeover' && !(repoInfo(io.cwd).isMain && relayLinked(repoInfo(io.cwd).root))) {
- throw new Refused('AGENT_SESSION', 'takeover belongs to an agent session; run pullboard takeover from the agent’s shell');
- }
+ if (command === 'takeover' && !(repoInfo(io.cwd).isMain && relayLinked(repoInfo(io.cwd).root))) throw new Refused('AGENT_SESSION', 'takeover belongs to an agent session; run pullboard takeover from the agent’s shell');
return;
}
if (command === 'check') {
diff --git a/src/commands/takeover.js b/src/commands/takeover.js
index 338a3405..c080d175 100644
--- a/src/commands/takeover.js
+++ b/src/commands/takeover.js
@@ -6,7 +6,6 @@ import {
withBoard,
} from '../cli.js';
import { COORDINATOR } from '../config.js';
-import { computerLabel } from '../coordinator-hold.js';
import { relayLinked } from '../relay.js';
import { relayMachineContext } from '../relay.js';
@@ -19,8 +18,8 @@ export async function run(io) {
const ctx = context(io);
const me = withBoard(ctx, (board) => whoAmI(ctx, board));
if (ctx.info.isMain && relayLinked(ctx.info.root)) {
- const label = computerLabel(relayMachineContext(ctx.info.root)?.machine);
- const taken = await withBoard(ctx, (board) => ordered(ctx, board, 'takeCoordinator', [{ agentId: COORDINATOR, label }]));
+ const machine = relayMachineContext(ctx.info.root)?.machine;
+ const taken = await withBoard(ctx, (board) => ordered(ctx, board, 'takeCoordinator', [{ agentId: COORDINATOR, ...(typeof machine === 'string' ? { machine } : {}) }]));
io.result?.({ agent: me.id, path: ctx.info.root, coordinator: taken.holder, previous: taken.previous });
io.say(`${me.displayName} now coordinates this board from ${taken.holder}${taken.previous && taken.previous !== taken.holder ? `, taking over from ${taken.previous}` : ''}`);
return 0;
diff --git a/src/coordinator-hold.js b/src/coordinator-hold.js
index 58751610..579bd85f 100644
--- a/src/coordinator-hold.js
+++ b/src/coordinator-hold.js
@@ -1,12 +1,13 @@
/**
* One coordinator per board, held by one main checkout at a time and passed by takeover [E19].
*
- * On a linked board every main checkout's coordinator moves reach the relay under that checkout's own root
- * coordinator credential, whose lineage the relay authenticates. The board records the lineage that holds the
+ * On a linked board every main checkout's coordinator moves reach the relay under its own root coordinator
+ * credential, and each move names the checkout's relay machine id. The board records which checkout holds the
* coordinator: the first coordinator move at this engine takes it, so a board coordinated from one checkout works
- * as before. A coordinator move from any other lineage is refused, naming the holder, until that checkout runs
- * pullboard takeover. An unlinked board's main checkout is already held by one session through its checkout
- * binding, so nothing here applies to it (#347).
+ * as before, including after another person signs in there. A coordinator move from any other checkout is
+ * refused, naming the holder, until that checkout runs pullboard takeover. A move that names no machine id is
+ * told apart by its relay-authenticated credential lineage instead. An unlinked board's main checkout is already
+ * held by one session through its checkout binding, so nothing here applies to it (#347).
*/
import {
atomic,
@@ -19,42 +20,36 @@ import { credentialActor } from './relay-sender.js';
export { COORDINATOR_HOLD_ENGINE };
const HOLDER_KEY = 'coordinator_holder';
+const MACHINE = /^[A-Za-z0-9_.-]{1,128}$/u;
/** Operations a non-holding main checkout may still send: seat creation and path upkeep stay per machine. */
const UNHELD_OPERATIONS = new Set(['register', 'ensureCoordinator', 'takeCoordinator']);
/**
- * A stored or received holder name, bounded and free of control characters.
- *
- * @param {unknown} label
- * @returns {string}
- */
-export function holderLabel(label) {
- const text = typeof label === 'string' ? label.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' ').trim().slice(0, 80) : '';
- return text || 'another main checkout';
-}
-
-/**
- * The name a linked main checkout goes by in a hold: its computer, by the end of the machine id the relay gave it
- * when it was linked, as the device roster shows a computer. It carries no host name or path, since a hold is read
- * by every member of a team board.
+ * The name a linked main checkout goes by: its computer, by the end of the machine id the relay gave it when it
+ * was linked, as the device roster shows a computer. It carries no host name or path, since every member of a
+ * team board reads it.
*
* @param {unknown} machine the link's relay machine id
* @returns {string}
*/
export function computerLabel(machine) {
- return typeof machine === 'string' && /^[A-Za-z0-9_.-]{1,128}$/u.test(machine) ? `computer ${machine.slice(-8)}` : 'another main checkout';
+ return typeof machine === 'string' && MACHINE.test(machine) ? `computer ${machine.slice(-8)}` : 'another main checkout';
+}
+
+/** The identity a hold compares: the checkout's machine id when the move names one, else the credential lineage. */
+function holdKey(machine, lineage) {
+ return typeof machine === 'string' && MACHINE.test(machine) ? `machine:${machine}` : `lineage:${lineage}`;
}
/**
- * Name the sending main checkout on a coordinator move, so a hold and its refusals say which checkout holds it.
- * The name travels sealed inside the move, so only the board's members read it.
+ * Name the sending checkout on a coordinator move, by its relay machine id, so a hold follows the checkout.
*
* @param {any} move a prepared engine move
* @param {unknown} machine the sending link's relay machine id
* @returns {any} the same move
*/
export function stampCoordinatorHolder(move, machine) {
- if (credentialActor(move) === COORDINATOR) move.holder = computerLabel(machine);
+ if (credentialActor(move) === COORDINATOR && typeof machine === 'string' && MACHINE.test(machine)) move.holder = machine;
return move;
}
@@ -62,26 +57,28 @@ export function stampCoordinatorHolder(move, machine) {
* The checkout that holds this board's coordinator, or null before any linked coordinator move at this engine.
*
* @param {any} board
- * @returns {{ lineage: string, label: string, at: string } | null}
+ * @returns {{ key: string, label: string, at: string } | null}
*/
export function coordinatorHolder(board) {
const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get(HOLDER_KEY);
if (!row) return null;
try {
const value = JSON.parse(row.meta_value);
- return typeof value?.lineage === 'string' ? { lineage: value.lineage, label: holderLabel(value.label), at: String(value.at ?? '') } : null;
+ return typeof value?.key === 'string' ? { key: value.key, label: String(value.label ?? 'another main checkout'), at: String(value.at ?? '') } : null;
} catch { return null; }
}
-/** Record a holder in the caller's transaction. */
-function saveHolder(board, lineage, label, at) {
+/** Record a holder in the caller's transaction and return its name. */
+function saveHolder(board, machine, lineage, at) {
+ const label = computerLabel(machine);
board.db.prepare('INSERT INTO board_meta (meta_key, meta_value) VALUES (?, ?) ON CONFLICT(meta_key) DO UPDATE SET meta_value = excluded.meta_value')
- .run(HOLDER_KEY, JSON.stringify({ lineage, label: holderLabel(label), at }));
+ .run(HOLDER_KEY, JSON.stringify({ key: holdKey(machine, lineage), label, at }));
+ return label;
}
/**
- * Admit one relay-ordered coordinator move from the main checkout with this lineage, or refuse it by name.
- * The first such move takes the hold, so a single coordinating checkout never sees a refusal.
+ * Admit one relay-ordered coordinator move from a linked main checkout, or refuse it by name. The first such move
+ * takes the hold, so a single coordinating checkout never sees a refusal.
*
* @param {any} board
* @param {{ operation: string, engine: number, holder?: unknown }} move
@@ -91,21 +88,21 @@ function saveHolder(board, lineage, label, at) {
export function requireCoordinatorHold(board, move, lineage, at) {
if (!lineage || !(move.engine >= COORDINATOR_HOLD_ENGINE) || UNHELD_OPERATIONS.has(move.operation)) return;
const holder = coordinatorHolder(board);
- if (!holder) { saveHolder(board, lineage, move.holder, at); return; }
- if (holder.lineage === lineage) return;
+ if (!holder) { saveHolder(board, move.holder, lineage, at); return; }
+ if (holder.key === holdKey(move.holder, lineage)) return;
throw new Refused('COORDINATOR_HELD',
`this board's coordinator is held by ${holder.label}, so this main checkout cannot act as coordinator; to coordinate from here, run pullboard takeover in this main checkout`);
}
/**
- * Take this board's coordinator for the main checkout that sent the move, recording who held it before.
- * Only a relay-ordered move from a linked main checkout's own coordinator credential can take it.
+ * Take this board's coordinator for the linked main checkout that sent the move, recording who held it before.
+ * Only a relay-ordered move under a linked main checkout's own coordinator credential can take it.
*
* @param {any} board
- * @param {{ agentId: string, label: string }} options
+ * @param {{ agentId: string, machine?: string }} options
* @returns {{ holder: string, previous: string | null }}
*/
-export function takeCoordinator(board, { agentId, label }) {
+export function takeCoordinator(board, { agentId, machine }) {
if (agentId !== COORDINATOR) throw new Refused('COORDINATOR_ONLY', 'only the coordinator takes over the coordinator; run pullboard takeover in the main checkout');
const lineage = board.verifierStanding?.lineage;
if (!lineage) {
@@ -114,8 +111,7 @@ export function takeCoordinator(board, { agentId, label }) {
return atomic(board, () => {
const previous = coordinatorHolder(board);
const at = board.clock?.now?.().toISOString?.() ?? new Date().toISOString();
- saveHolder(board, lineage, label, at);
- const holder = holderLabel(label);
+ const holder = saveHolder(board, machine, lineage, at);
logEvent(board, COORDINATOR, 'coordinator-takeover', null, { holder, previous: previous?.label ?? null, engine: COORDINATOR_HOLD_ENGINE });
return { holder, previous: previous?.label ?? null };
});
diff --git a/src/relay-outbox.js b/src/relay-outbox.js
index bf8d3e2f..1f6e5df0 100644
--- a/src/relay-outbox.js
+++ b/src/relay-outbox.js
@@ -163,7 +163,7 @@ export const ITEM_SLOTS = Object.freeze({
recordRowDecisions: [], applyRowDecisions: [], draftSpecRow: [], recordSpecApprovalBaseline: [],
recordLandingBatch: [], recordLandingWaiver: [], recordLandingFlake: [], finishLandingBatch: [],
recordHealthFindings: [], decideSentinel: [], beginSentinelRun: [], finishSentinelRun: [],
- recordFlakeObservation: [], recordGateRun: [], declareJob: [], recordJobRun: [],
+ recordFlakeObservation: [], recordGateRun: [], declareJob: [], recordJobRun: [], takeCoordinator: [],
...Object.fromEntries(FIRST_ITEM.map((operation) => [operation, [[0]]])),
addItem: [[0, 'parentId'], [0, 'after', '*']],
editItem: [[0], [1, 'after', '*']],
diff --git a/src/seats.js b/src/seats.js
index 00370e9a..8a06477e 100644
--- a/src/seats.js
+++ b/src/seats.js
@@ -11,6 +11,9 @@ import {
} from './machine.js';
import { Refused } from './refused.js';
+/** The board's coordinator hold travels with its seats: one main checkout coordinates a linked board (#347). */
+export { coordinatorHolder, takeCoordinator } from './coordinator-hold.js';
+
/**
* The agent registered for a worktree path, if any.
*
diff --git a/test/relay-credential.test.js b/test/relay-credential.test.js
index d1d0ac70..baddd4d0 100644
--- a/test/relay-credential.test.js
+++ b/test/relay-credential.test.js
@@ -31,7 +31,7 @@ test('every current operation selects its native actor credential without a seco
main: 'a'.repeat(40), command: 'c'.repeat(64), green: true, failures: [], load: { average: [0, 0, 0], cpus: 1, freeMB: 100 }, at: '2026-10-20T00:00:00.000Z' } }];
if (operation === 'declareJob') args = [{ agentId: actor, name: 'credential-job', every: '10m', owner: actor }];
if (operation === 'recordJobRun') args = [{ agentId: actor, name: 'credential-job' }];
- if (operation === 'takeCoordinator') args = [{ agentId: actor, label: 'computer credential' }];
+ if (operation === 'takeCoordinator') args = [{ agentId: actor, machine: 'credential-machine' }];
if (operation === 'proposeSentinel') args = [{ agentId: actor,
row: { name: 'credential-watch', check: 'true', every: 'hourly', owner: actor } }];
if (['beginSentinelRun', 'finishSentinelRun'].includes(operation)) {