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(land): land on the local trunk first, opt-in, at engine 64 [C7,V4]
Corey Olsonfd91489b0ac5
diff --git a/docs/formats.md b/docs/formats.mdindex fabf5b1e..6cc01dab 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -113,7 +113,7 @@ The board file is in the repository's Git common directory at `.git/pullboard/bo| `row grammar` | `1` | `SPEC_GRAMMAR_VERSION` in `src/spec.js`; optional `<!-- pullboard-grammar N -->` line in either file (absence means the current grammar) | Both files share the version. A declared version must match; an incompatible grammar change requires a coordinated version bump and compatible files. No automatic conversion occurs. || `board schema` | `2` | `SCHEMA_VERSION` in `src/board.js`, persisted as `PRAGMA user_version` | Create missing tables and indexes, add missing columns in place with declared defaults, restore missing or changed triggers, and remove stale machine triggers without replacing rows. || `event log` | `1` | `EVENT_LOG_VERSION` in `src/board.js`, persisted in `board_meta` as `event_log_version` | Older event-log versions upgrade in place; newer versions are refused with `EVENT_LOG_VERSION`. Preserve event rows when the board schema changes. |-| `move engine` | `62` | `ENGINE_VERSION` in `src/machine.js`, carried as `engine` in every sealed executable move | Bump when a move's meaning changes, independently of the event log and sealed envelope. A newer engine is refused with `ENGINE_VERSION`, naming both versions and asking you to upgrade Pullboard. |+| `move engine` | `64` | `ENGINE_VERSION` in `src/machine.js`, carried as `engine` in every sealed executable move | Bump when a move's meaning changes, independently of the event log and sealed envelope. A newer engine is refused with `ENGINE_VERSION`, naming both versions and asking you to upgrade Pullboard. |<!-- format-versions:end -->Relay transport capability `apiVersion: 2` is independent of these versions and@@ -176,6 +176,8 @@ Engine 61 (`NATIVE_FLAKE_ENGINE`) adds `recordFlakeObservation` and typed diagnoEngine 62 (`HEALTH_CAP_ENGINE`; engine 61 is #887's) caps what one recorded health run shouts. A run sends at most ten notices one by one, resolved first; when it has more, one more notice to the coordinator says how many it held back, and every finding still records its own health event. An idle seat alone hears that it is idle. A recorded run at an older engine replays with its original notices.+Engine 64 (`LOCAL_LANDING_ENGINE`) lets a landing batch reach the state `trunk`: merged onto the local trunk after its quick guards (the static checks and submit invariants), with each item's merged receipt recorded before anything is pushed. Only a board whose `pullboard.json` sets `landing: { "publish": "separate" }` lands this way; `pullboard publish` then runs the whole suite on the exact trunk head and pushes only a green head. A batch recorded at an older engine still needs `pushed` before its receipts.+The CLI declares its engine in every relay request's `X-Pullboard-Engine` header.A linked board requires at least engine 48 after issuing any agent token or machine credential, includingrevoked or expired ones; before engine 48 these minimums were 3 and 6. The minimum survives reopening the auth database;diff --git a/src/board.js b/src/board.jsindex 31a46e2b..23b32c3d 100644--- a/src/board.js+++ b/src/board.js@@ -43,6 +43,7 @@ import {effectiveGuards,storeTriggers,} from './machine.js';+import { LOCAL_LANDING_ENGINE } from './land-engine.js';import { Refused } from './refused.js';import { refuseMaskedExit } from './check-mask.js';import {@@ -2672,6 +2673,7 @@ export function recordLandingBatch(board, { agentId, batch, revision = 0 }) {if (carriesFlakeDiagnostics(batch) && (board.executionEngineVersion ?? ENGINE_VERSION) < NATIVE_FLAKE_ENGINE) {throw new Refused('ENGINE_VERSION', `typed landing diagnostics require engine ${NATIVE_FLAKE_ENGINE}; upgrade Pullboard`);}+ if (batch?.state === 'trunk' && (board.executionEngineVersion ?? ENGINE_VERSION) < LOCAL_LANDING_ENGINE) throw new Refused('ENGINE_VERSION', `landing on the local trunk requires engine ${LOCAL_LANDING_ENGINE}; upgrade Pullboard`);const evidence = (board.executionEngineVersion ?? ENGINE_VERSION) >= SUBMISSION_PROOF_ENGINE ? invariantEvidence(batch?.invariantEvidence) : undefined;validateLandingBatch(batch, revision);if ((board.executionEngineVersion ?? ENGINE_VERSION) >= VERDICT_REVIEW_ENGINE@@ -2757,7 +2759,7 @@ export function finishLandingBatch(board, { agentId, id, tip }) {const batch = landingBatches(board).find((entry) => entry.id === id);if (!batch || batch.tip !== tip) throw new Refused('LAND_BATCH', 'the pushed tip must match its recorded batch; run pullboard land --adopt');if (batch.state === 'landed') return batch;- if (batch.state !== 'pushed') throw new Refused('LAND_NOT_PUSHED', 'record a successful push before landing receipts; run pullboard land --adopt');+ if (batch.state !== 'pushed' && !(batch.state === 'trunk' && (board.executionEngineVersion ?? ENGINE_VERSION) >= LOCAL_LANDING_ENGINE)) throw new Refused('LAND_NOT_PUSHED', 'record a successful push before landing receipts; run pullboard land --adopt');for (const entry of batch.items) {const item = itemById(board, entry.id);if (item.item_commit !== entry.commit || item.item_status !== 'verified') {diff --git a/src/config.js b/src/config.jsindex 0107ac38..6b8345db 100644--- a/src/config.js+++ b/src/config.js@@ -175,6 +175,9 @@ export function configProblems(config) {problems.push('"landingShards" is a whole number from 1 to 64: how many shards the landing gate splits its test files into');}if (typeof config.staticChecks !== 'string') problems.push('"staticChecks" is an optional project static-check command');+ if (config.landing !== undefined && (typeof config.landing !== 'object' || config.landing === null || Object.keys(config.landing).some(key => key !== 'publish') || ![undefined, 'separate'].includes(config.landing.publish))) {+ problems.push('"landing" is optional; { "publish": "separate" } lands on the local trunk and pushes only through pullboard publish');+ }if (config.positiveControl !== undefined && (typeof config.positiveControl !== 'string' || !config.positiveControl.trim())) {problems.push('"positiveControl" is a nonempty command for a known-good case the gate must pass, like "node --test test/known-good.test.js"');}diff --git a/src/engine.js b/src/engine.jsindex 2f44adab..24cd07cb 100644--- a/src/engine.js+++ b/src/engine.js@@ -52,6 +52,7 @@ import {NATIVE_FLAKE_ENGINE,carriesFlakeDiagnostics,} from './flake-engine.js';+import { LOCAL_LANDING_ENGINE } from './land-engine.js';const ITEM_ID_FIRST_ARGUMENT = new Set(['acceptCheck', 'editItem', 'escalate', 'recordAttempt', 'claim', 'release', 'submit', 'reserveReview', 'verify', 'merged', 'withdraw', 'refreeze', 'reopen', 'appendFact']);@@ -73,6 +74,9 @@ const OPERATION_ENGINE = Object.freeze({ draftSpecRow: ROW_DRAFT_ENGINE, orderMi/** Dependency edits, causes, sealed reviews, submission proofs, trunk conflicts, health observations and milestone targets retain distinct recorded engine meanings. */function minimumOperationEngine(operation, args, board) {+ // A batch landed on the local trunk before it is published (#801).+ if (operation === 'recordLandingBatch' && args[0]?.batch?.state === 'trunk'+ || operation === 'finishLandingBatch' && board && store.landingBatches(board).find(batch => batch.id === args[0]?.id)?.state === 'trunk') return LOCAL_LANDING_ENGINE;if (operation === 'recordFlakeObservation') return NATIVE_FLAKE_ENGINE;if (operation === 'recordLandingBatch' && carriesFlakeDiagnostics(args[0]?.batch)) return NATIVE_FLAKE_ENGINE;if (['proposeSentinel', 'decideSentinel', 'beginSentinelRun', 'finishSentinelRun'].includes(operation) || typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return BOARD_SENTINEL_ENGINE;diff --git a/src/land-engine.js b/src/land-engine.jsnew file mode 100644index 00000000..0018acb3--- /dev/null+++ b/src/land-engine.js@@ -0,0 +1,2 @@+/** Coordinator allocation for #801: a batch may land on the local trunk before it is published, from this engine on. */+export const LOCAL_LANDING_ENGINE = 64;diff --git a/src/land.js b/src/land.jsindex e5584278..6a3b999d 100644--- a/src/land.js+++ b/src/land.js@@ -32,6 +32,7 @@ import {import {runGate,runProfiledShell,+ runStaticChecks,withGateSlot,} from './gate.js';import { laneOf } from './lanes.js';@@ -579,6 +580,55 @@ async function publish(state) {return state.batch;}+/** Whether this project lands in two tiers: on the local trunk at once, and on the remote only through publish (#801). */+export function landsOnTrunk(config) {+ return config?.landing?.publish === 'separate';+}++/**+ * The quick guards a tier-1 landing runs on its merged tree (#801): the project's static checks and its submit+ * invariants. Each item's frozen check already ran at verify, and the whole suite runs at publish.+ */+async function quickGuards(state) {+ const root = state.batch.root;+ await runStaticChecks(root, state.config, { agent: 'coordinator', onWait: state.onWait });+ const invariants = [...new Set(state.config.submitInvariants ?? [])].sort();+ if (!invariants.length) return;+ const command = `${state.config.affectedTests} ${invariants.map(quote).join(' ')}`;+ const run = await withGateSlot(root, lease => runProfiledShell(root, command, { waitMs: lease.waitMs, gateLease: lease }),+ { agent: 'coordinator', kind: 'check', itemCheck: true, onWait: state.onWait });+ if (!run.isGreen) throw new Refused('GATE_RED', `the submit invariants are red on the merged tree: ${invariants.join(', ')}`);+}++/**+ * Tier 1 (#801): after a clean merge and its quick guards, the batch lands on the local trunk in seconds, with each+ * item's merged receipt; nothing is pushed. pullboard publish runs the whole suite on the trunk head and pushes it.+ */+async function landOnTrunk(state) {+ await save(state, { state: 'gating', tip: headCommit(state.batch.root) });+ try { await quickGuards(state); } catch (error) {+ if (!(error instanceof Refused)) throw error;+ await save(state, { state: 'blocked' });+ state.say(`nothing landed: ${error.message}`);+ return;+ }+ for (const entry of state.batch.items) {+ const item = store.getItem(state.board, entry.id);+ if (item.item_status !== 'verified' || item.item_commit !== entry.commit) throw new Refused('LAND_ITEM_MOVED', `item #${entry.id} changed after the batch merged; rebuild its landing`);+ }+ if (mainCheckout(state.root)?.commit !== state.batch.base) throw new Refused('LAND_TRUNK_MOVED', 'main moved during the landing; rebuild the batch from its new tip');+ await save(state, { state: 'trunk', proof: { tree: headTree(state.batch.root), failures: [], logPath: null } });+ await finishTrunk(state);+}++/** Record a tier-1 batch's merged receipts and move the local trunk to it; an adopted 'trunk' batch resumes here (#801). */+async function finishTrunk(state) {+ state.batch = await state.write('finishLandingBatch', [{ agentId: 'coordinator', id: state.batch.id, tip: state.batch.tip }]);+ const main = mainCheckout(state.root);+ if (main?.commit === state.batch.base && isClean(state.root) && !untracked(state.root).length) git(state.root, ['merge', '--ff-only', state.batch.tip]);+ state.say(`landed ${state.batch.items.map((entry) => `#${entry.id}`).join(', ')} at ${state.batch.tip} on the local trunk; pullboard publish pushes it once the whole suite passes`);+}+/** Build, gate, diagnose and durably land one coordinator batch; all external actions stay in its worktree. */export async function land({ root, board, config, write, say, owner, maximum = Infinity, dryRun = false, adopt = false, onWait }) {let trunk = mainCheckout(root);@@ -593,7 +643,7 @@ export async function land({ root, board, config, write, say, owner, maximum = Iconst stale = selected.blocked.find(item => item.code === 'STALE_VERDICT');if (!selected.ready.length && stale) throw staleVerdictRefusal({ item_id: stale.id }, stale);if (dryRun) {- if (selected.ready.length) requirePushTarget(root, trunk.branch);+ if (selected.ready.length && !landsOnTrunk(config)) requirePushTarget(root, trunk.branch);const conflicts = [];for (const item of selected.ready) {const merge = tryGit(root, ['merge-tree', '--write-tree', '--name-only', '-z', trunk.commit, item.item_landing_commit]);@@ -625,7 +675,7 @@ export async function land({ root, board, config, write, say, owner, maximum = Ireturn { batch: null, landed: [], conflicts: [], blocked: selected.blocked, culprits: [], flakes: [] };}if (!batch) {- requirePushTarget(root, trunk.branch);+ if (!landsOnTrunk(config)) requirePushTarget(root, trunk.branch);const id = randomUUID();const directory = join(repoInfo(root).commonDir, 'pullboard', 'landings', id);batch = { version: 1, id, base: trunk.commit, tip: trunk.commit, branch: trunk.branch, root: join(directory, 'worktree'),@@ -639,7 +689,8 @@ export async function land({ root, board, config, write, say, owner, maximum = Iconst state = { root, board, config, write, say, onWait, batch, culprits: batch.culprits ?? [], flaky: false, gates: new Map((batch.gateResults ?? []).map((result) => [result.tree, result])), diagnosed: new Map((batch.diagnostics ?? []).map((result) => [result.test, result.isGreen])) };await save(state, { owner });await returnCulprits(state);- if (state.batch.state === 'pushed' || state.batch.state === 'ready') await publish(state);+ if (state.batch.state === 'trunk') await finishTrunk(state);+ else if (state.batch.state === 'pushed' || state.batch.state === 'ready') await publish(state);else {const initialItems = (state.batch.candidates ?? state.batch.items).filter((entry) => !state.culprits.some((culprit) => culprit.id === entry.id && culprit.commit === entry.commit));@@ -648,6 +699,7 @@ export async function land({ root, board, config, write, say, owner, maximum = Iawait save(state, { ...build, conflicts: [...state.batch.conflicts, ...build.conflicts] });for (const entry of state.batch.blocked ?? []) say(`${entry.code} #${entry.id}${entry.stacked ? ` carries #${entry.stacked}` : ''}`);if (!build.items.length) await save(state, { state: 'blocked' });+ else if (landsOnTrunk(state.config)) await landOnTrunk(state);else {let gate = await gateGroup(state, 'batch');let proof = gate.isGreen ? null : waivedProof(state, gate);diff --git a/src/machine.js b/src/machine.jsindex a0243f19..b8961abd 100644--- a/src/machine.js+++ b/src/machine.js@@ -12,6 +12,7 @@import { RIGOR_NOTICE_ENGINE } from './rigor-source.js';import { HEALTH_CAP_ENGINE } from './health-receipts.js';import { NATIVE_FLAKE_ENGINE } from './flake-engine.js';+import { LOCAL_LANDING_ENGINE } from './land-engine.js';/** First writer for withdraw-and-remove milestone behavior; shipment remains engine 45. */export const WITHDRAW_MILESTONE_ENGINE = 51;@@ -33,6 +34,7 @@ export const STRONG_REJECTION_NOTICE_ENGINE = 54;export const SUBMITTED_CONFLICT_ENGINE = 60;export const ENGINE_VERSION = Math.max(+ LOCAL_LANDING_ENGINE,HEALTH_CAP_ENGINE,SUBMITTED_CONFLICT_ENGINE,NATIVE_FLAKE_ENGINE,diff --git a/src/publish.js b/src/publish.jsindex 0be72dbb..59ba47ad 100644--- a/src/publish.js+++ b/src/publish.js@@ -86,13 +86,16 @@ export async function publishTrunk({ root, board, config, say, onWait }) {let gate;try {gate = await runGate(directory, config, { trustStamp: false, landing: true, agent: 'coordinator', onWait });+ // Push from the worktree that ran the suite, so the pre-push hook reads that run's green stamp instead of rerunning it.+ if (gate.isGreen) {+ const pushed = tryGit(directory, ['push', remote, `HEAD:refs/heads/${branch}`]);+ if (pushed.status !== 0) throw new Refused('LAND_PUSH', `the landing push failed: ${pushed.stderr || pushed.stdout}; inspect the remote and hooks, then run pullboard publish again`);+ }} finally {tryGit(root, ['worktree', 'remove', '--force', directory]);if (existsSync(directory)) rmSync(directory, { recursive: true, force: true });}if (gate.isGreen) {- const pushed = tryGit(root, ['push', remote, `${head}:refs/heads/${branch}`]);- if (pushed.status !== 0) throw new Refused('LAND_PUSH', `the landing push failed: ${pushed.stderr || pushed.stdout}; inspect the remote and hooks, then run pullboard publish again`);writeFileSync(stateFile(root), JSON.stringify({ published: head }) + '\n');say(`published ${branch} at ${head.slice(0, 12)}: the whole suite passed`);return { head, published: true, red: [] };diff --git a/src/submit-invariants.js b/src/submit-invariants.jsindex f92e35c2..5a999c00 100644--- a/src/submit-invariants.js+++ b/src/submit-invariants.js@@ -126,7 +126,7 @@ export function submitInvariantLine(proposal) {/** Validate the existing canonical batch identity before its append-only snapshot is recorded. */export function validateLandingBatch(batch, revision) {if (!batch || batch.version !== 1 || typeof batch.id !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/u.test(batch.id)- || !['merging', 'gating', 'bisecting', 'flaky', 'blocked', 'ready', 'pushed', 'landed'].includes(batch.state)+ || !['merging', 'gating', 'bisecting', 'flaky', 'blocked', 'ready', 'pushed', 'trunk', 'landed'].includes(batch.state)|| !/^[a-f0-9]{40,64}$/u.test(batch.base ?? '') || !/^[a-f0-9]{40,64}$/u.test(batch.tip ?? '')|| typeof batch.root !== 'string' || !batch.root || typeof batch.branch !== 'string' || !batch.branch.startsWith('refs/heads/')|| !Array.isArray(batch.items) || batch.items.some((entry) => !Number.isSafeInteger(entry?.id) || entry.id < 1 || !/^[a-f0-9]{40,64}$/u.test(entry.commit ?? ''))diff --git a/test/land.test.js b/test/land.test.jsindex 4a5b1068..f1a1cca0 100644--- a/test/land.test.js+++ b/test/land.test.js@@ -1390,3 +1390,28 @@ test('publish pushes only a head the whole suite passed and names every red [B3,assert.equal(green.published, true);assert.equal(box.git(box.remote, 'rev-parse', 'main'), fixed, 'only the head the whole suite passed reaches the remote');});++test('an accepted item lands on the local trunk before the whole suite runs [B3,R3]', () => {+ const box = landProject();+ const path = join(box.repo, 'pullboard.json');+ const config = JSON.parse(readFileSync(path, 'utf8'));+ writeFileSync(path, JSON.stringify({ ...config, landing: { publish: 'separate' } }, null, 2));+ box.git(box.repo, 'add', 'pullboard.json');+ box.git(box.repo, 'commit', '-q', '-m', 'chore: land on the local trunk first');+ const entries = verifiedFour(box);+ const remoteBefore = box.git(box.remote, 'rev-parse', 'main');+ const start = calls(box).length;+ const result = json(box, box.repo, 'land', '--max', '4');+ assert.deepEqual(result.landed.sort((a, b) => a - b), entries.map((entry) => entry.item).sort((a, b) => a - b));+ assert.equal(result.batch.state, 'landed');+ assert.equal(box.git(box.repo, 'rev-parse', 'main'), result.batch.tip, 'the local trunk holds the landed batch');+ assert.equal(box.git(box.remote, 'rev-parse', 'main'), remoteBefore, 'tier 1 pushes nothing');+ assert.deepEqual(calls(box).slice(start), [], 'no whole-suite run before the items land');+ const merges = box.git(box.repo, 'rev-list', '--first-parent', `${result.batch.base}..${result.batch.tip}`).split('\n');+ for (const entry of entries) assert.ok(merges.includes(json(box, box.repo, 'show', String(entry.item)).item_merged_commit), `#${entry.item} has its merged receipt on the local trunk`);+ // Tier 2 then runs the whole suite once on that exact head and pushes it.+ const published = json(box, box.repo, 'publish');+ assert.equal(published.published, true);+ assert.equal(box.git(box.remote, 'rev-parse', 'main'), result.batch.tip);+ assert.equal(calls(box).length - start, 1, 'publish ran the whole suite once');+});