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(land): fence admitted speculative worktrees [B3,V4,Q1,Q3]

Corey Olson2ccadff33751
diff --git a/src/cli.js b/src/cli.js
index 0bbf19fd..bb00f7ee 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -976,8 +976,9 @@ async function bindCheckoutSession(io, positionals, values) {
let agent = info.isMain ? COORDINATOR : null;
if (!info.isMain) {
const ctx = context(io);
+ const ownsLandingRoot = command === 'hook' ? (await import('./landing-candidates.js')).landingBatchOwnsRoot : () => false;
agent = withBoard(ctx, (board) => store.agentAt(board, info.root)?.agent_id
- ?? (command === 'hook' && store.landingBatches(board).some((batch) => batch.root === info.root && !['landed', 'blocked'].includes(batch.state)) ? COORDINATOR : null));
+ ?? (command === 'hook' && store.landingBatches(board).some((batch) => ownsLandingRoot(batch, info.root)) ? COORDINATOR : null));
if (!agent && command !== 'join') throw withBoard(ctx, (board) => seatCheckout.unjoinedRefusal(info, store.listAgents(board)));
}
if (['shout', 'fact'].includes(command) && localSessionMatches(info, { agent: agent ?? 'unjoined agent', digest })) {
diff --git a/src/commands/hook.js b/src/commands/hook.js
index dd1edc68..3b1c0863 100644
--- a/src/commands/hook.js
+++ b/src/commands/hook.js
@@ -1,5 +1,6 @@
/** The pullboard hook command, in its own module so an item adding another command never edits these lines. */
import * as store from '../board.js';
+import { landingBatchOwnsRoot } from '../landing-candidates.js';
import {
hookRead,
readStdin,
@@ -67,7 +68,7 @@ export async function hookCommand(io, { first, second }) {
if (first === 'pre-commit' || first === 'pre-merge-commit') {
applyFixers(info.root, ctx.config.fix).forEach((note) => io.err(`pullboard pre-commit: ${note}`));
const agent = info.isMain ? null : hookRead(ctx, (board) => store.agentAt(board, info.root));
- const landing = hookRead(ctx, (board) => store.landingBatches(board).some((batch) => batch.root === info.root && !['landed', 'blocked'].includes(batch.state)));
+ const landing = hookRead(ctx, (board) => store.landingBatches(board).some((batch) => landingBatchOwnsRoot(batch, info.root)));
if (landing) io.caller('coordinator', info.root);
else if (agent) io.caller('seat', info.root);
problems = preCommitProblems({ root: info.root, isMain: info.isMain || landing, config: ctx.config, agent, boardFile: ctx.file, preMergeHook: first === 'pre-merge-commit', onNotice: (message) => io.err(`pullboard pre-commit: warning: ${message}`) });
diff --git a/src/land.js b/src/land.js
index 2fd7eeda..07631cb9 100644
--- a/src/land.js
+++ b/src/land.js
@@ -54,6 +54,7 @@ import {
} from './landing-lease.js';
import { runLandingWorker } from './landing-worker.js';
import { runLandingCandidateWorker } from './landing-candidates.js';
+import { inheritedGateSlot } from './resources.js';
import { Refused } from './refused.js';
import { requireLandingHost } from './landing-host.js';
import {
@@ -1111,6 +1112,13 @@ function cadenceDeferral(board, config, branch, say) {
return { batch: null, landed: [], conflicts: [], blocked: [], culprits: [], flakes: [], deferredUntil };
}
+/** Require a separate admitted slot for every speculative gate, without holding a parent gate open. */
+function requireParallelGateAdmission(root, config) {
+ if (config.landing?.parallel === true && inheritedGateSlot({ root, namedFiles: true })) {
+ throw new Refused('LAND_PARALLEL_NESTED_GATE', 'parallel landing needs separately admitted gate slots; run pullboard land outside the current gate command');
+ }
+}
+
/** Build, gate, diagnose and durably land one coordinator batch; all external actions stay in its worktree. */
export async function land(options) {
if (options.dryRun) return runLandingBatch(options);
@@ -1118,6 +1126,7 @@ export async function land(options) {
const trunk = mainCheckout(options.root);
const branch = trunk?.branch;
if (!branch) throw new Refused('LAND_TRUNK', 'landing needs the coordinator’s primary branch; return its checkout to the trunk');
+ if (trunk.commit) requireParallelGateAdmission(options.root, policyAt(options.root, trunk.commit).config);
if (trunk.commit && !options.adopt) {
requireConfirmedLanding(options.board);
const deferred = cadenceDeferral(options.board, policyAt(options.root, trunk.commit).config, branch, options.say);
@@ -1191,6 +1200,7 @@ export async function runLandingBatch({ root, board, config, write, say, owner,
if (!trunk?.commit) throw new Refused('LAND_TRUNK', 'landing needs the coordinator’s primary branch; return its checkout to the trunk');
// Pin accepted policy after any recorded-landed repair, never before admission or from candidate files.
config ??= policyAt(root, trunk.commit).config;
+ if (!dryRun) requireParallelGateAdmission(root, config);
board.quarantineEnabled = () => config.flakes?.quarantine === true;
const environment = dryRun ? null : requireLandingHost(store.boardId(board), config);
const testDefects = heldTestDefects(root, board, trunk);
diff --git a/src/landing-candidates.js b/src/landing-candidates.js
index ea81393a..01e6a7dc 100644
--- a/src/landing-candidates.js
+++ b/src/landing-candidates.js
@@ -9,6 +9,13 @@ import { Refused } from './refused.js';
const FILE = fileURLToPath(import.meta.url);
+/** Recognize only the exact worktrees registered by an active canonical landing batch. */
+export function landingBatchOwnsRoot(batch, root) {
+ if (['landed', 'blocked'].includes(batch.state)) return false;
+ return batch.root === root || (batch.parallelCandidates ?? []).some(candidate => candidate.snapshot?.root === root
+ && candidate.snapshot.base === batch.base && candidate.snapshot.branch === batch.branch);
+}
+
/** Run one exact prefix in the existing guardian's process group, never publishing it. */
export async function runLandingCandidateWorker(options, { write, checkLease, say, onWait, onStart }) {
const child = spawn(process.execPath, [FILE, 'candidate'], {
diff --git a/test/land-parallel-fixture.js b/test/land-parallel-fixture.js
index 3c7b243a..9d35a359 100644
--- a/test/land-parallel-fixture.js
+++ b/test/land-parallel-fixture.js
@@ -1,9 +1,10 @@
/** Prove concurrent landing gates against actual private Git, SQLite and gate subprocesses [B3,V4]. */
import assert from 'node:assert/strict';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
-import { runFixtureChild } from './fixture-child.js';
+import { runFixtureChild, startFixtureChild } from './fixture-child.js';
+import * as store from '../src/board.js';
import { GATE_SLOT_HELD_ENV, GATE_SLOT_POOL_ENV, GATE_SLOT_TOKEN_ENV, BROWSER_SLOT_HELD_ENV } from '../src/resources.js';
/** Read append-only subprocess markers; each completed line is one independently observed transition. */
@@ -103,3 +104,152 @@ export function assertParallelLanding({ landProject, itemWorktree, submitItem, a
} else assert.equal(maximum, 1, 'the default serial behavior remains serial');
}
}
+
+/** Configure only the private project's accepted trunk before creating its submitted items. */
+function parallelCliProject(landProject) {
+ const box = landProject();
+ mkdirSync(box.env.PULLBOARD_MACHINE_HOME, { recursive: true });
+ // Capacity belongs only to this sandbox's independent machine home, never the user's pool.
+ writeFileSync(join(box.env.PULLBOARD_MACHINE_HOME, 'settings.json'), JSON.stringify({ gateSlots: 2, browserSlots: 2 }));
+ const path = join(box.repo, 'pullboard.json');
+ const config = JSON.parse(readFileSync(path, 'utf8'));
+ config.landing = { ...config.landing, parallel: true };
+ writeFileSync(path, JSON.stringify(config, null, 2));
+ box.git(box.repo, 'add', 'pullboard.json');
+ box.git(box.repo, 'commit', '-q', '-m', 'chore: configure private parallel landing');
+ return box;
+}
+
+/** Observe a real CLI landing without replacing its configuration, lease or guardian callbacks. */
+function startParallelCli(box, BIN) {
+ const env = { ...box.env };
+ for (const key of [GATE_SLOT_HELD_ENV, GATE_SLOT_POOL_ENV, GATE_SLOT_TOKEN_ENV, BROWSER_SLOT_HELD_ENV]) delete env[key];
+ const child = startFixtureChild(process.execPath, [BIN, 'land', '--json'], {
+ cwd: box.repo, env, stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '';
+ let stderr = '';
+ child.stdout.setEncoding('utf8').on('data', part => { stdout += part; });
+ child.stderr.setEncoding('utf8').on('data', part => { stderr += part; });
+ const closed = new Promise(resolveClose => {
+ child.once('error', error => resolveClose({ error }));
+ child.once('close', (code, signal) => resolveClose({ code, signal, stdout, stderr }));
+ });
+ return { child, closed };
+}
+
+/** Exercise real CLI opt-in and authority loss on separate private, normally verified projects. */
+export async function assertParallelCliLease({ landProject, itemWorktree, submitItem, acceptItem, onBoard, waitFor, BIN }) {
+ for (const loseLease of [false, true]) {
+ const box = parallelCliProject(landProject);
+ const entries = [1, 2].map(number => itemWorktree(box, number));
+ for (const entry of entries) submitItem(box, entry);
+ for (const entry of entries) acceptItem(box, entry);
+ const localBefore = box.git(box.repo, 'rev-parse', 'main');
+ const remoteBefore = box.git(box.remote, 'rev-parse', 'main');
+ writeFileSync(box.hold, 'armed');
+ const running = startParallelCli(box, BIN);
+ let terminal;
+ let held;
+ let batch;
+ try {
+ await waitFor(() => existsSync(box.entered), 'the parallel CLI entered its real gate');
+ ({ held, batch } = onBoard(box, board => ({ held: store.landingLeaseState(board).holder,
+ batch: store.landingBatches(board).at(-1) })));
+ assert.ok(held && Number.isSafeInteger(held.guardianPid) && held.guardianPid > 0, 'the real guardian is bound to an actual lease');
+ assert.equal(held.branch, batch.branch);
+ assert.ok(Number.isSafeInteger(held.generation) && held.generation > 0);
+ assert.equal(batch.parallelCandidates.length, 2, 'the CLI parsed the committed opt-in and dispatched both prefixes');
+ assert.equal(new Set(batch.parallelCandidates.map(candidate => candidate.snapshot.root)).size, 2);
+ if (loseLease) {
+ // This private fixture owns the observed invocation. Release its actual public grant;
+ // no SQL, invented token, elapsed-clock override, takeover identity or signal is used.
+ onBoard(box, board => store.landingLeaseMove(board, { agentId: 'coordinator', action: 'release',
+ token: held.token, generation: held.generation, branch: held.branch, pid: held.pid }));
+ assert.equal(onBoard(box, board => store.landingLeaseState(board).holder), null);
+ }
+ } finally {
+ // Always release the cooperative gate. Any authority-loss cancellation is the product
+ // guardian's own fenced shutdown; this test never signals an arbitrary process/group.
+ writeFileSync(box.release, 'release');
+ terminal = await running.closed;
+ }
+ assert.equal(terminal.error, undefined);
+ assert.equal(terminal.signal, null, terminal.stderr);
+ const result = JSON.parse(terminal.stdout);
+ const snapshot = onBoard(box, board => ({ holder: store.landingLeaseState(board).holder,
+ batch: store.landingBatches(board).find(row => row.id === batch.id), events: store.events(board),
+ statuses: entries.map(entry => store.getItem(board, entry.item).item_status) }));
+ assert.equal(snapshot.holder, null, 'the CLI leaves no live landing grant');
+ if (loseLease) {
+ assert.notEqual(terminal.code, 0, terminal.stderr);
+ assert.equal(result.error?.code, 'LAND_LEASE_LOST', terminal.stdout);
+ assert.equal(box.git(box.repo, 'rev-parse', 'main'), localBefore);
+ assert.equal(box.git(box.remote, 'rev-parse', 'main'), remoteBefore);
+ assert.equal(snapshot.events.filter(event => event.event_kind === 'main-moved').length, 0);
+ assert.deepEqual(snapshot.batch.culprits ?? [], [], 'authority loss attributes no item failure');
+ assert.deepEqual(snapshot.statuses, ['verified', 'verified']);
+ } else {
+ assert.equal(terminal.code, 0, terminal.stderr);
+ assert.deepEqual(result.landed, entries.map(entry => entry.item));
+ assert.equal(box.git(box.repo, 'rev-parse', 'main'), result.batch.tip);
+ assert.equal(box.git(box.remote, 'rev-parse', 'main'), result.batch.tip);
+ assert.equal(snapshot.events.filter(event => event.event_kind === 'main-moved').length, 1);
+ assert.equal(snapshot.batch.state, 'landed');
+ }
+ }
+}
+
+/** Prove nested parallel refusal under a real private live gate grant through both public entries. */
+export function assertParallelNestedGate({ landProject, itemWorktree, submitItem, acceptItem, onBoard, BIN }) {
+ const box = parallelCliProject(landProject);
+ const entry = itemWorktree(box, 1);
+ submitItem(box, entry);
+ acceptItem(box, entry);
+ const before = { main: box.git(box.repo, 'rev-parse', 'main'), remote: box.git(box.remote, 'rev-parse', 'main'),
+ calls: readFileSync(box.calls, 'utf8'), batches: onBoard(box, board => store.landingBatches(board)),
+ paths: existsSync(join(box.repo, '.git', 'pullboard', 'landings'))
+ ? readdirSync(join(box.repo, '.git', 'pullboard', 'landings'), { recursive: true }).sort() : null };
+ /** Resolve the running installed source for a real private controller child. */
+ const url = name => pathToFileURL(join(import.meta.dirname, '../src', name)).href;
+ const direct = [
+ `import * as store from ${JSON.stringify(url('board.js'))};`,
+ `import { runLandingBatch } from ${JSON.stringify(url('land.js'))};`,
+ "import { join } from 'node:path';",
+ 'const root = process.argv[1]; const board = store.openBoard(join(root, ".git", "pullboard", "board.sqlite"));',
+ 'try { await runLandingBatch({ root, board, owner: "private-nested-api", write: async (operation, args) => store[operation](board, ...args), say: () => {} }); console.log(JSON.stringify({ code: null })); }',
+ 'catch (error) { console.log(JSON.stringify({ code: error.code, message: error.message })); } finally { store.closeBoard(board); }',
+ ].join('\n');
+ const controller = [
+ "import assert from 'node:assert/strict';",
+ `import { withGateSlot } from ${JSON.stringify(url('gate.js'))};`,
+ `import { gateSlotEnvironment, holdsLease } from ${JSON.stringify(url('resources.js'))};`,
+ `import { runFixtureChild } from ${JSON.stringify(pathToFileURL(join(import.meta.dirname, 'fixture-child.js')).href)};`,
+ 'const [root, bin] = process.argv.slice(1); let owned;',
+ 'await withGateSlot(root, async lease => { owned = lease; const env = { ...process.env, ...gateSlotEnvironment(lease) };',
+ 'assert.equal(holdsLease(lease), true);',
+ 'const cli = runFixtureChild(process.execPath, [bin, "land", "--json"], { cwd: root, env, encoding: "utf8" });',
+ 'assert.notEqual(cli.status, 0); assert.equal(JSON.parse(cli.stdout).error?.code, "LAND_PARALLEL_NESTED_GATE");',
+ 'assert.equal(holdsLease(lease), true, "the CLI refusal cannot release its caller grant");',
+ `const api = runFixtureChild(process.execPath, ["--input-type=module", "-e", ${JSON.stringify(direct)}, root], { cwd: root, env, encoding: "utf8" });`,
+ 'assert.equal(api.status, 0, api.stderr); assert.equal(JSON.parse(api.stdout).code, "LAND_PARALLEL_NESTED_GATE");',
+ 'assert.equal(holdsLease(lease), true, "the API refusal cannot release its caller grant");',
+ '}, { browser: false, remote: false, agent: "coordinator", kind: "check" });',
+ 'assert.equal(holdsLease(owned), false, "only the actual owner releases the grant when its action ends");',
+ 'console.log(JSON.stringify({ cli: "LAND_PARALLEL_NESTED_GATE", api: "LAND_PARALLEL_NESTED_GATE", ownerReleased: true }));',
+ ].join('\n');
+ const env = { ...box.env };
+ for (const key of [GATE_SLOT_HELD_ENV, GATE_SLOT_POOL_ENV, GATE_SLOT_TOKEN_ENV, BROWSER_SLOT_HELD_ENV]) delete env[key];
+ const result = runFixtureChild(process.execPath, ['--input-type=module', '-e', controller, box.repo, BIN], {
+ cwd: box.repo, env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, `${result.failure ?? result.stderr}\n${result.stdout}`);
+ assert.deepEqual(JSON.parse(result.stdout), { cli: 'LAND_PARALLEL_NESTED_GATE', api: 'LAND_PARALLEL_NESTED_GATE', ownerReleased: true });
+ assert.equal(box.git(box.repo, 'rev-parse', 'main'), before.main);
+ assert.equal(box.git(box.remote, 'rev-parse', 'main'), before.remote);
+ assert.equal(readFileSync(box.calls, 'utf8'), before.calls, 'neither entry launches a candidate gate');
+ assert.deepEqual(onBoard(box, board => store.landingBatches(board)), before.batches, 'no new candidate batch is persisted');
+ const paths = existsSync(join(box.repo, '.git', 'pullboard', 'landings'))
+ ? readdirSync(join(box.repo, '.git', 'pullboard', 'landings'), { recursive: true }).sort() : null;
+ assert.deepEqual(paths, before.paths, 'neither entry creates candidate paths');
+}
diff --git a/test/land.test.js b/test/land.test.js
index d42d24ba..657fee0d 100644
--- a/test/land.test.js
+++ b/test/land.test.js
@@ -16,7 +16,7 @@ import { assertLandingDoctrineCounts } from './land-doctrine-fixture.js';
import { onBoard, events, calls } from './land-board-fixture.js';
import { landingTimeoutFixture } from './landing-timeout-fixture.js';
-import { assertParallelLanding } from './land-parallel-fixture.js';
+import { assertParallelLanding, assertParallelCliLease, assertParallelNestedGate } from './land-parallel-fixture.js';
const e2e = createE2eHelpers();
after(e2e.cleanup);
const { sandbox, project, commitFile, waitFor, BIN } = e2e;
@@ -1492,3 +1492,9 @@ test('a landing gate past its timeout stops cleanly [E27,E29]', () => landingTim
test('landing tests candidate batches in parallel and lands the longest green prefix [B3,V4]', { timeout: 180_000 }, // budget: two real three-item private landings and bounded overlap barriers; no speed threshold.
() => assertParallelLanding({ landProject, itemWorktree, submitItem, acceptItem, json }));
+
+test('parallel CLI landing retains its lease and fences lost authority [B3,V4,Q1,Q3]', { timeout: 180_000 }, // budget: two private CLI landings with cooperative gate barriers; hang ceiling only, no speed threshold.
+async () => assertParallelCliLease({ landProject, itemWorktree, submitItem, acceptItem, onBoard, waitFor, BIN }));
+
+test('parallel landing refuses a live inherited gate before scheduling [B3,V4,Q1,Q3]', { timeout: 90_000 }, // budget: private verified item plus two immediate guarded entries; hang ceiling only.
+() => assertParallelNestedGate({ landProject, itemWorktree, submitItem, acceptItem, onBoard, BIN }));