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(gate): a flake is proven by a tree's own gate receipts [C7,D1]
Corey Olson00ff5ab4b559
diff --git a/docs/formats.md b/docs/formats.mdindex aefacdd1..b27f636c 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` | `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. |+| `move engine` | `67` | `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@@ -180,6 +180,8 @@ Engine 63 (`RECURRING_JOB_ENGINE`) records recurring jobs. `declareJob` is the cEngine 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.+Engine 67 (`GATE_RUN_ENGINE`) records gate runs and the flake quarantine they prove. The gate writes a receipt for each real run of the accepted gate command on a clean, committed tree, under the common git directory at `pullboard/gate-receipts/<id>.json`: its id, kind (`gate`, `submit` or `land`), tree, head, accepted main, the command's SHA-256, its result, the committed file and name of each test that failed, the host load and the time. The writer is private to the gate and takes the result from the process it just ran; a run of any other command, or one whose checkout was dirty or moved, leaves no receipt. `recordGateRun` carries that receipt, and both a direct call and a sealed move are refused (`GATE_RUN_UNBOUND`) unless the store beside the board holds the same receipt byte for byte, so a run made up by hand is never recorded. A replayed move is applied as its origin checked it. When the coordinator's runs have found one tree both red and green for the same test, the board files one ordinary repair item for that test, with the runs as evidence, and records a `test-quarantine` event; a seat's own runs are recorded but prove nothing. Quarantine itself is the coordinator's `flakes.quarantine` setting in pullboard.json, read from accepted main and off by default: with it off, runs and the repair item are still recorded, but nothing stops blocking a landing. With it on, a quarantined test still runs and reports, but a landing treats it as covered, like a waiver naming that file and test, as long as every run that proved it is a receipt on the landing machine and its repair item is not verified or withdrawn; it then blocks again, and only a newer red-and-green proof files a new item. A different red in the same run is never covered. An older engine refuses the move with `ENGINE_VERSION`.+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 3d8f786d..a06641f0 100644--- a/src/board.js+++ b/src/board.js@@ -99,6 +99,7 @@ import {landingWaiverKind,} from './landing-exceptions.js';import { parseSpec } from './spec.js';+import { quarantineWaivers } from './quarantine.js';import { invariantEvidence } from './submit-invariants.js';import { landingBatches } from './landing-batch-history.js';import {@@ -115,6 +116,7 @@ export { acceptCheck } from './check-accept.js';export { declareJob, recordJobRun } from './recurring-jobs.js';export { proposeSentinel, decideSentinel, beginSentinelRun, finishSentinelRun } from './sentinels.js';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';@@ -2715,7 +2717,7 @@ export function recordLandingWaiver(board, { agentId, channel, id, test, until,export function landingWaivers(board) {return board.db.prepare("SELECT event_by,event_detail FROM event WHERE event_kind = 'landing_waiver' ORDER BY event_id").all().filter((row) => row.event_by === PERSON)- .map((row) => JSON.parse(row.event_detail).waiver);+ .map((row) => JSON.parse(row.event_detail).waiver).concat(quarantineWaivers(board)); // A proven flake's quarantine, when on [C7,D1].}/** Find a live person's waiver and derive its match kind without rewriting history [B3,R3,H16]. */diff --git a/src/cli.js b/src/cli.jsindex 35d95eb0..c19be53e 100644--- a/src/cli.js+++ b/src/cli.js@@ -831,6 +831,9 @@ function configHere(info) {*/export function withBoard(ctx, work) {const board = store.openBoard(ctx.file, ctx.clock, { isMain: ctx.allowSchemaUpgrade });+ // Whether a proven flake stops blocking a landing is the coordinator's setting, read from accepted main on first use.+ let quarantine;+ board.quarantineEnabled = () => quarantine ??= mainPolicy(ctx.info.root).config.flakes?.quarantine === true;const firstEvent = board.emittedEvents?.length ?? 0;/** Forward committed events before releasing either synchronous or asynchronous work. */const finish = () => {diff --git a/src/config.js b/src/config.jsindex 11663957..6147cb21 100644--- a/src/config.js+++ b/src/config.js@@ -172,8 +172,8 @@ export function configProblems(config) {if (typeof config.practice !== 'string' || !config.practice) problems.push('"practice" names the doctrine file');if (typeof config.gate !== 'string') problems.push('"gate" is a shell command, like "npm test"');if (config.flakes !== undefined && (!config.flakes || typeof config.flakes !== 'object' || Array.isArray(config.flakes)- || config.flakes.rerun !== undefined && typeof config.flakes.rerun !== 'boolean'- || Object.keys(config.flakes).some(key => key !== 'rerun'))) problems.push('"flakes" has only the optional boolean "rerun", off by default');+ || ['rerun', 'quarantine'].some(key => config.flakes[key] !== undefined && typeof config.flakes[key] !== 'boolean')+ || Object.keys(config.flakes).some(key => !['rerun', 'quarantine'].includes(key)))) problems.push('"flakes" has only the optional booleans "rerun" and "quarantine", each off by default');if (!['inside', 'beside'].includes(config.worktrees)) problems.push('"worktrees" is "inside" or "beside"');if (config.submitGate !== undefined && config.submitGate !== 'landing') {problems.push('"submitGate" is "landing" when the full suite should be deferred until landing');diff --git a/src/engine.js b/src/engine.jsindex cf13518b..7f5b4618 100644--- a/src/engine.js+++ b/src/engine.js@@ -22,6 +22,8 @@ import { CHECK_ACCEPT_ENGINE } from './check-accept.js';import { HEALTH_SENTINEL_ENGINE } from './health-receipts.js';import { BOARD_SENTINEL_ENGINE } from './sentinels.js';import { RECURRING_JOB_ENGINE } from './job-engine.js';+import { GATE_RUN_ENGINE } from './gate-run-engine.js';+import { requireBound } from './quarantine.js';import {CAUSE_ENGINE,ENGINE_VERSION,@@ -66,7 +68,7 @@ export const ENGINE_OPERATIONS = Object.freeze(['recordRowDecisions', 'applyRowDecisions', 'draftSpecRow', 'appendFact','recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'finishLandingBatch', 'acceptCheck','recordHealthFindings', 'proposeSentinel', 'decideSentinel', 'beginSentinelRun', 'finishSentinelRun',- 'recordFlakeObservation', 'declareJob', 'recordJobRun',+ 'recordFlakeObservation', 'recordGateRun', 'declareJob', 'recordJobRun',]);/** Engine version at which each ordered operation first has stable replay semantics. */@@ -82,6 +84,7 @@ function minimumOperationEngine(operation, args, board) {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;if (['declareJob', 'recordJobRun'].includes(operation)) return RECURRING_JOB_ENGINE;+ if (operation === 'recordGateRun') return GATE_RUN_ENGINE;if (operation === 'recordHealthFindings') return HEALTH_SENTINEL_ENGINE;const options = args[1];if (carriesConflict(operation, args)) return board && store.itemById(board, args[0])?.item_status === 'submitted' ? SUBMITTED_CONFLICT_ENGINE : CONFLICT_ENGINE;@@ -144,6 +147,8 @@ export function prepareEngineMove(board, operation, args, { id = randomUUID(), aif (operation === 'submit' && ENGINE_VERSION >= SUBMISSION_PROOF_ENGINE) submissionProof(args[1]?.submissionProof);const minimumEngine = minimumOperationEngine(operation, args, board);if (ENGINE_VERSION < minimumEngine) throw new Refused('ENGINE_VERSION', `${operation} requires engine version ${minimumEngine}; this pullboard uses engine ${ENGINE_VERSION}; upgrade before sending it`);+ // A gate run is sealed only as its gate's own receipt; a run made up by hand is refused before it reaches any replica.+ if (operation === 'recordGateRun') requireBound(board, args[0]?.receipt);const values = args.map((value) => value && typeof value === 'object' ? { ...value } : value);if (operation === 'release') {const problem = store.reviewReleaseNoteProblem(board, values[0], values[1], values[2]);diff --git a/src/flake-command.js b/src/flake-command.jsindex 17a89281..8bc8e923 100644--- a/src/flake-command.js+++ b/src/flake-command.js@@ -6,30 +6,34 @@ import {import { join } from 'node:path';import { CONFIG_FILE } from './config.js';import { flakeLedger } from './flakes.js';+import { flakeQuarantines } from './quarantine.js';import { Refused } from './refused.js';/** List actual flake sightings separately from unknown failures and candidate regressions. */export function flakesCommand(ctx, { first, second, rest }, withBoard) {- if (first === 'rerun' && ['on', 'off'].includes(second) && !rest.length) {+ if (['rerun', 'quarantine'].includes(first) && ['on', 'off'].includes(second) && !rest.length) {if (!ctx.info.isMain) throw new Refused('NOT_MAIN', 'only the coordinator sets this board’s diagnostic policy; ask it to run pullboard flakes rerun on or off');const file = join(ctx.info.root, CONFIG_FILE);const config = JSON.parse(readFileSync(file, 'utf8'));- config.flakes = { rerun: second === 'on' };+ config.flakes = { ...(config.flakes ?? {}), [first]: second === 'on' };writeFileSync(file, JSON.stringify(config, null, 2) + '\n');ctx.io.result?.({ flakes: config.flakes, file: CONFIG_FILE });- ctx.io.say(`paired flake diagnostics ${second}; commit ${CONFIG_FILE} to apply this board policy. The original red remains red.`);+ ctx.io.say(first === 'rerun' ? `paired flake diagnostics ${second}; commit ${CONFIG_FILE} to apply this board policy. The original red remains red.`+ : `flake quarantine ${second}; commit ${CONFIG_FILE} to apply this board policy. Runs and repair items are recorded either way; only quarantine stops a proven flake from blocking a landing.`);return 0;}- if (first || second || rest.length) throw new Refused('USAGE', 'pullboard flakes lists observations; pullboard flakes rerun on|off sets the coordinator’s opt-in policy');+ if (first || second || rest.length) throw new Refused('USAGE', 'pullboard flakes lists observations; pullboard flakes rerun|quarantine on|off sets the coordinator’s opt-in policy');return withBoard(ctx, board => {const rows = flakeLedger(board);const flakes = rows.filter(row => row.count > 0);const unclassified = rows.filter(row => row.count === 0 && row.classification === 'unclassified');const regressions = rows.filter(row => row.count === 0 && row.classification === 'possible-regression');const stable = rows.filter(row => row.count === 0 && row.classification === 'stable-red');- ctx.io.result?.({ flakes, unclassified, regressions, stable });+ const quarantined = flakeQuarantines(board).filter(entry => entry.status === 'quarantined');+ ctx.io.result?.({ flakes, unclassified, regressions, stable, quarantined });for (const row of rows) ctx.io.say(`${row.status}: ${row.file ?? '(unclassified gate)'}${row.name ? ' :: ' + row.name : ''}; count ${row.count}; first ${row.firstSeen}; last ${row.lastSeen}${row.item ? '; repair #' + row.item : ''}`);- if (!rows.length) ctx.io.say('no recorded test failures; paired diagnostics are off unless this board opts in with pullboard flakes rerun on');+ for (const entry of quarantined) ctx.io.say(`quarantined: ${entry.file} :: ${entry.name}; still runs and reports, does not block a landing until repair #${entry.item} is verified`);+ if (!rows.length && !quarantined.length) ctx.io.say('no recorded test failures; paired diagnostics are off unless this board opts in with pullboard flakes rerun on');return 0;});}diff --git a/src/gate-run-engine.js b/src/gate-run-engine.jsnew file mode 100644index 00000000..c208f00f--- /dev/null+++ b/src/gate-run-engine.js@@ -0,0 +1,2 @@+/** First engine for gate runs bound to their gate's own receipt, and the flake quarantine they prove (#813) [C7,D1]. */+export const GATE_RUN_ENGINE = 67;diff --git a/src/gate-run-receipt.js b/src/gate-run-receipt.jsnew file mode 100644index 00000000..76dbbbf9--- /dev/null+++ b/src/gate-run-receipt.js@@ -0,0 +1,121 @@+/**+ * A gate run's own receipt [C7,D1]. The gate writes one file per real run of the accepted gate command on a clean,+ * committed tree, from the exit status and output of the process it ran: its tree, the command's digest, its result,+ * the committed tests that failed, and the host load. The file sits beside the board, under the git directory, so it+ * never enters a commit. This module reads and checks receipts; nothing here writes one. Only the gate's private+ * writer in gate.js does, right after its child exits, so no caller can hand it a result to record.+ */+import { readFileSync } from 'node:fs';+import {+ dirname,+ join,+} from 'node:path';+import { tryGit } from './git.js';++/** The folder beside the board that holds gate run receipts. */+export const RECEIPT_FOLDER = 'gate-receipts';+const SHA = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;+const DIGEST = /^[a-f0-9]{64}$/u;+const ID = /^[a-f0-9-]{36}$/u;+const MOST_FAILURES = 500;++/**+ * Where this checkout's gate keeps its receipts: the common git directory's pullboard folder, the same folder that+ * holds the board, so every worktree of one repo shares one store.+ *+ * @param {string} root+ * @returns {string | null}+ */+export function receiptStore(root) {+ const common = tryGit(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);+ return common.status === 0 ? join(common.stdout.trim(), 'pullboard', RECEIPT_FOLDER) : null;+}++/**+ * The receipt store beside an open board file, or null for a board with no file (an in-memory board has no gate).+ * The board finds it from its own database file, so no caller can point it at another folder.+ *+ * @param {{ db: any }} board+ * @returns {string | null}+ */+export function boardReceiptStore(board) {+ const file = board.db.prepare('PRAGMA database_list').all().find((row) => row.name === 'main')?.file;+ return file ? join(dirname(file), RECEIPT_FOLDER) : null;+}++/** Bounded single-line text, so a receipt never carries a log or a path outside the repo. */+function line(value, limit) {+ return typeof value === 'string' && value.length > 0 && value.length <= limit && !/[\r\n\0]/u.test(value);+}++/**+ * Check and normalize a receipt's fields, in one fixed key order, or null when any field is missing or malformed. A+ * green run names no failure; a red run names the committed tests it could identify. It never throws: the gate's writer+ * must not fail a run over its receipt, and the board names its own refusal.+ *+ * @param {any} value+ * @returns {{ version: 1, id: string, kind: string, tree: string, head: string, main: string | null, command: string, green: boolean, failures: Array<{ file: string, name: string }>, load: { average: number[], cpus: number, freeMB: number }, at: string } | null}+ */+export function receiptFields(value) {+ try { return checkedFields(value); } catch { return null; }+}++/** The checks behind receiptFields; each malformed field throws, and receiptFields turns that into null. */+function checkedFields(value) {+ const bad = () => new TypeError('malformed gate receipt');+ if (!value || value.version !== 1 || !ID.test(value.id ?? '') || !['gate', 'land', 'submit'].includes(value.kind) || !SHA.test(value.tree ?? '')+ || !SHA.test(value.head ?? '') || value.main !== null && !SHA.test(value.main ?? '') || !DIGEST.test(value.command ?? '')+ || typeof value.green !== 'boolean' || !Array.isArray(value.failures) || value.failures.length > MOST_FAILURES+ || value.green && value.failures.length > 0 || !line(value.at, 40) || !Number.isFinite(Date.parse(value.at))) throw bad();+ const failures = value.failures.map((entry) => {+ const file = entry?.file, name = entry?.name;+ if (!line(file, 4096) || file.startsWith('/') || file.includes('\\') || file.split('/').some((part) => !part || part === '.' || part === '..') || !line(name, 8192)) throw bad();+ return { file, name };+ });+ const load = value.load;+ if (!load || !Array.isArray(load.average) || load.average.length !== 3 || load.average.some((number) => !Number.isFinite(number) || number < 0)+ || !Number.isSafeInteger(load.cpus) || load.cpus < 1 || !Number.isSafeInteger(load.freeMB) || load.freeMB < 0) throw bad();+ return { version: 1, id: value.id, kind: value.kind, tree: value.tree, head: value.head, main: value.main, command: value.command,+ green: value.green, failures, load: { average: [...load.average], cpus: load.cpus, freeMB: load.freeMB }, at: value.at };+}++/**+ * The exact bytes a receipt is stored as. The board compares a run's receipt with these bytes on disk, so a run that+ * changes any field no longer matches the file its gate wrote.+ *+ * @param {object} receipt+ * @returns {string | null} null for a malformed receipt+ */+export function receiptBody(receipt) {+ const fields = receiptFields(receipt);+ return fields ? `${JSON.stringify(fields)}\n` : null;+}++/**+ * Read one stored receipt by id, or null when this store holds none or holds something else under that name.+ *+ * @param {string | null} store+ * @param {string} id+ * @returns {ReturnType<typeof receiptFields>}+ */+export function readGateReceipt(store, id) {+ if (!store || !ID.test(id ?? '')) return null;+ try {+ const text = readFileSync(join(store, `${id}.json`), 'utf8');+ const receipt = receiptFields(JSON.parse(text));+ return receipt && receiptBody(receipt) === text && receipt.id === id ? receipt : null;+ } catch { return null; }+}++/**+ * True only when the store holds the gate's own receipt for this run, byte for byte. A run made up by hand has no+ * such file, and a real receipt altered in any field no longer matches it.+ *+ * @param {string | null} store+ * @param {object} receipt+ * @returns {boolean}+ */+export function receiptBinds(store, receipt) {+ const stored = readGateReceipt(store, receipt?.id);+ return stored !== null && receiptBody(stored) === receiptBody(receipt);+}diff --git a/src/gate.js b/src/gate.jsindex 66d39dfb..ead1127d 100644--- a/src/gate.js+++ b/src/gate.js@@ -8,7 +8,10 @@ import {spawn,spawnSync,} from 'node:child_process';-import { randomUUID } from 'node:crypto';+import {+ createHash,+ randomUUID,+} from 'node:crypto';import {existsSync,mkdirSync,@@ -29,18 +32,31 @@ import {} from 'node:path';import {availableParallelism,+ freemem,+ loadavg,tmpdir,} from 'node:os';import { fileURLToPath } from 'node:url';import {gitChildEnv,gitPath,+ headCommit,headTree,invalidateGitFacts,isClean,untracked,} from './git.js';import { recordGateRun } from './gate-control.js';+import {+ receiptBody,+ receiptFields,+ receiptStore,+} from './gate-run-receipt.js';+import {+ committedTest,+ tapTests,+} from './tap-tests.js';+import { mainPolicy } from './trusted-policy.js';import { secretsIn } from './hooks.js';import { Refused } from './refused.js';import { missingGate } from './gate-config.js';@@ -588,16 +604,53 @@ export async function runGate(root, config, { trustStamp = true, onWait, landingif (trustStamp && isStampedGreen(root)) return { isGreen: true, isCached: true, output: '', seconds: 0, log: '' };return await withGateSlot(root, async (lease) => {pinRunMain(lease, onFailure);- const run = fullGateRun(root, config, trustStamp, { waitMs: lease.waitMs, gateLease: lease, landing, stages, waivers });+ const run = fullGateRun(root, config, trustStamp, { waitMs: lease.waitMs, gateLease: lease, landing, stages, waivers, kind: landing ? 'land' : 'gate' });if (!run.isGreen && onFailure) await onFailure(run, { root, command: config.gate, lease });+ await recordRun(onFailure, run);return run;}, {landing, browser: true, agent, item, kind: landing ? 'landing' : 'gate', onWait,});}+/** Hand a run's receipt to its observer, which records it on the board; recording never changes the run's verdict [C7,D1]. */+async function recordRun(observer, run) {+ if (!run.receiptId || typeof observer?.recordRun !== 'function') return;+ try { await observer.recordRun(run.receiptId); } catch { /* A board that cannot take the record leaves the gate result as it was. */ }+}++/**+ * Leave the receipt of one real run of the accepted gate: its tree, the command's digest, its result, the committed+ * tests that failed and the host load, taken from the process this module just ran. It is private to this module on+ * purpose: no caller can hand it a result, so a receipt always describes an execution [C7,D1]. A run of any other+ * command, or one whose checkout was dirty or moved while it ran, proves nothing about a tree and leaves no receipt.+ *+ * @returns {string | null} the receipt id+ */+function leaveRunReceipt(root, config, run, { before, kind }) {+ try {+ if (before === null || committedTree(root) !== before || run.executionSourceUnchanged === false) return null;+ const policy = mainPolicy(root);+ const head = headCommit(root);+ const store = receiptStore(root);+ if (policy.config.gate !== config.gate || !head || !store) return null;+ const failures = new Map();+ for (const row of run.isGreen ? [] : tapTests(run.output ?? '', run.executionRoot ?? root)) {+ if (row.passed || row.skip || row.type === 'suite' || ['subtestsFailed', 'cancelledByParent', 'testAborted'].includes(row.failureType)) continue;+ if (row.file && committedTest(root, head, row.file)) failures.set(JSON.stringify([row.file, row.name]), { file: row.file, name: row.name });+ }+ const local = { average: loadavg(), cpus: availableParallelism(), freeMB: Math.floor(freemem() / 1048576) };+ const receipt = receiptFields({ version: 1, id: randomUUID(), kind, tree: before, head, main: policy.commit, command: createHash('sha256').update(config.gate).digest('hex'),+ green: run.isGreen, failures: [...failures.values()], load: Array.isArray(run.executionLoad?.average) ? run.executionLoad : local, at: new Date().toISOString() });+ if (!receipt) return null;+ mkdirSync(store, { recursive: true, mode: 0o700 });+ writeFileSync(join(store, `${receipt.id}.json`), receiptBody(receipt), { flag: 'wx', mode: 0o600 });+ return receipt.id;+ } catch { return null; }+}+/** Run a full gate while its caller owns the queue lease; only a full run may stamp its tree. */-function fullGateRun(root, config, trustStamp = false, { waitMs = 0, log = gitPath(root, LOG), gateLease, landing = false, stages = false, waivers = [] } = {}) {+function fullGateRun(root, config, trustStamp = false, { waitMs = 0, log = gitPath(root, LOG), gateLease, landing = false, stages = false, waivers = [], kind = 'gate' } = {}) {if (trustStamp && isStampedGreen(root)) return { isGreen: true, isCached: true, output: '', seconds: 0, log: '' };const before = committedTree(root);const run = runProfiledShell(root, config.gate, { waitMs, pipefail: true, profileFile: `${log}.profile.json`, gateLease, landing, stages, waivers });@@ -605,9 +658,10 @@ function fullGateRun(root, config, trustStamp = false, { waitMs = 0, log = gitPawriteFileSync(log, output);// The environment refusing a run says nothing about the gate, so only a real result is recorded (U41).if (!run.sandboxBlocked) recordGateRun(root, gateRunRecord(root, config, isGreen, gateLease));+ const receiptId = run.sandboxBlocked ? null : leaveRunReceipt(root, config, run, { before, kind });refuseSandboxBlocked(run);if (isGreen && before !== null && committedTree(root) === before) writeFileSync(gitPath(root, STAMP), `${before}\n`);- return { isGreen, isCached: false, output, seconds, log, profile, profilePath, ...(run.executionRoot ? { executionRoot: run.executionRoot } : {}),+ return { isGreen, isCached: false, output, seconds, log, profile, profilePath, receiptId, ...(run.executionRoot ? { executionRoot: run.executionRoot } : {}),// A remote run's host load and pinned main reach the flake diagnostics with it (#925)....(run.executionRunner ? { executionRunner: run.executionRunner, executionMain: run.executionMain ?? null, executionLoad: run.executionLoad ?? null } : {}), ...(stages ? { stages: run.stages } : {}) };}@@ -723,7 +777,7 @@ export async function runSubmitGate(root, config, { base, trunk, changed, check,const proofWait = check ? 0 : lease.waitMs;let proof;// The proof keeps each stage's status, so a person's waiver can only ever explain named test failures.- if (!deferFullFallback && selection.full) proof = fullGateRun(root, config, false, { waitMs: proofWait, log: proofLog, gateLease: lease, stages: true });+ if (!deferFullFallback && selection.full) proof = fullGateRun(root, config, false, { waitMs: proofWait, log: proofLog, gateLease: lease, stages: true, kind: 'submit' });else if (!proofFiles.length) proof = { isGreen: true, output: '', seconds: 0, isCached: false, log: '' };else {const command = `${config.affectedTests.trimEnd()} ${proofFiles.map(path => commandWord('./' + path)).join(' ')}`;@@ -734,6 +788,7 @@ export async function runSubmitGate(root, config, { base, trunk, changed, check,writeFileSync(log, `item check:\n${criterion.output}\n${phase}:\n${proof.output}`);if (!proof.isGreen && onFailure) await onFailure(proof, { root,command: !deferFullFallback && selection.full ? config.gate : `${config.affectedTests.trimEnd()} ${proofFiles.map(path => commandWord('./' + path)).join(' ')}`, lease });+ await recordRun(onFailure, proof);return finish(proof);}, { browser, agent, item, kind, itemCheck: true, onWait });}diff --git a/src/help.js b/src/help.jsindex 055a4d23..3410f538 100644--- a/src/help.js+++ b/src/help.js@@ -194,6 +194,7 @@ Receiptspullboard log [id] every move, in orderpullboard flakes recorded failures, their first and last sightings, counts and repair statuspullboard flakes rerun on|off coordinator: opt into one diagnostic pair per failed test; off by default+ pullboard flakes quarantine on|off coordinator: let a proven flake stop blocking landings until its repair item is verified; off by defaultcommit pullboard.json to apply; a passing diagnostic never turns the original red greenpullboard rigor failure causes that repeated: on 2 items, or 1 item at 2 commits;each with its items and whether it reads as work, product or both@@ -269,7 +270,7 @@ const HELP_EXAMPLES = {claim: 'pullboard claim 12', submit: 'pullboard submit 12', 'next --verify': 'pullboard next --verify',fact: 'pullboard fact 12 measurement "The check passes in 8 seconds"',why: 'pullboard why 12',- flakes: 'pullboard flakes', 'flakes rerun': 'pullboard flakes rerun on',+ flakes: 'pullboard flakes', 'flakes rerun': 'pullboard flakes rerun on', 'flakes quarantine': 'pullboard flakes quarantine on',verify: 'pullboard verify 12 accept --note "removed the fix; the test failed"',watch: 'pullboard watch --to web', answer: 'pullboard answer 12 "done"', pass: 'pullboard pass 12 "please decide"',status: 'pullboard status', view: 'pullboard view', digest: 'pullboard digest --out briefing.md', mcp: 'pullboard mcp', stats: 'pullboard stats --since 2026-10-08', log: 'pullboard log 12', ledger: 'pullboard ledger',diff --git a/src/land.js b/src/land.jsindex 3cca05a8..5140a842 100644--- a/src/land.js+++ b/src/land.js@@ -35,6 +35,10 @@ import {runStaticChecks,withGateSlot,} from './gate.js';+import {+ readGateReceipt,+ receiptStore,+} from './gate-run-receipt.js';import { laneOf } from './lanes.js';import { Refused } from './refused.js';import { landingFileTimes } from './submit-invariants.js';@@ -250,6 +254,14 @@ function coveredFailures(state, gate) {return gate.failures.length > 0 && gate.failures.every((failure) => failure.file && store.landingWaiverFor(state.board, failure));}+/** Record the receipt the landing gate wrote for its run, in the lane that owns its first failing test [C7,D1]. */+async function recordLandingRun(state, receiptId) {+ const receipt = readGateReceipt(receiptStore(state.batch.root), receiptId);+ if (!receipt) return;+ const owner = receipt.failures.map(failure => laneOf(state.config, failure.file)).find(lane => lane !== 'coordinator');+ await state.write('recordGateRun', [{ agentId: 'coordinator', receipt, lane: owner ?? store.getItem(state.board, state.batch.items[0].id).item_lane }]);+}+/** Run one full landing gate and retain its complete output under this batch's immutable phase path. */async function gateGroup(state, label) {const tree = headTree(state.batch.root);@@ -267,7 +279,7 @@ async function gateGroup(state, label) {const owner = observation.file ? laneOf(state.config, observation.file) : 'coordinator';const lane = owner === 'coordinator' ? store.getItem(state.board, state.batch.items[0].id).item_lane : owner;return state.write('recordFlakeObservation', [{ agentId: 'coordinator', observation, lane }]);- } }), { main: pin.main }),+ } }), { main: pin.main, recordRun: receiptId => recordLandingRun(state, receiptId) }),});copyFileSync(gate.log, logPath);if (gate.profilePath) copyFileSync(gate.profilePath, `${logPath}.profile.json`);@@ -439,6 +451,7 @@ export function liveWaiverProjection(board) {/** Name one waived failure with the person's waiver, its reason and its expiry [B3]. */export function waiverLine(failure) {const { waiver } = failure;+ if (waiver.quarantine) return `quarantined: ${failure.name} (${failure.file}) is a proven flake, reported but not blocking until repair #${waiver.quarantine.item} is verified`;return `waived: ${failure.name} (${failure.file}) by person waiver ${waiver.id} for ${waiver.kind ?? store.landingWaiverKind(waiver.test)} ${waiver.test}: ${waiver.reason}; expires ${waiver.until}`;}@@ -633,6 +646,8 @@ async function finishTrunk(state) {/** 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 }) {+ // Quarantine is read from the accepted main policy this landing runs under, never from a branch.+ board.quarantineEnabled = () => config.flakes?.quarantine === true;let trunk = mainCheckout(root);const recorded = store.landingBatches(board).findLast((batch) => batch.state === 'landed' && batch.base === trunk?.commit);if (!dryRun && recorded && isClean(root) && !untracked(root).length) {diff --git a/src/landing-exceptions.js b/src/landing-exceptions.jsindex e52170d7..93872b33 100644--- a/src/landing-exceptions.js+++ b/src/landing-exceptions.js@@ -20,6 +20,8 @@ export function landingWaiverKind(test) {* Keeping the kinds apart stops a new test named like a waived file from riding that waiver [B3,R3].*/export function landingWaiverCovers(waiver, failure) {+ // A quarantine names the test by file and name together, so it never covers a same-named test elsewhere [C7,D1].+ if (waiver.quarantine) return waiver.quarantine.file === failure.file && waiver.quarantine.name === failure.name;return (waiver.kind ?? landingWaiverKind(waiver.test)) === 'file' ? waiver.test === failure.file : waiver.test === failure.name;}diff --git a/src/native-flake-cli.js b/src/native-flake-cli.jsindex f2ad2d46..f2b40a38 100644--- a/src/native-flake-cli.js+++ b/src/native-flake-cli.js@@ -8,6 +8,10 @@ import {policyAt,} from './trusted-policy.js';import { pinRunMain } from './gate.js';+import {+ readGateReceipt,+ receiptStore,+} from './gate-run-receipt.js';import { runProfiledShell } from './gate.js';import {diagnosticUnavailable,@@ -28,6 +32,15 @@ export function observer(ctx, { kind, board, main, commit, privateCheck = false,// Diagnostics cannot block an existing check when its coordinator is detached or its observer cannot initialize.return async run => { if (!run.isGreen) diagnosticUnavailable({ run }, error); };}+ /** Record the receipt the gate just wrote for its run; the board reads the receipt itself, never a run object [C7,D1]. */+ const recordRun = async receiptId => {+ const receipt = readGateReceipt(receiptStore(ctx.info.root), receiptId);+ if (!receipt) return;+ const owners = receipt.failures.map(failure => laneOf(acceptedConfig, failure.file)).filter(owner => owner !== COORDINATOR);+ const lane = owners[0] ?? Object.keys(acceptedConfig.lanes)[0];+ const write = target => ordered(ctx, target, 'recordGateRun', [{ agentId, receipt, lane }]);+ await (board ? write(board) : withBoard(ctx, write));+ };// The pinned main rides on the observer, so a remote runner's receipt can name the main this run used (#925).return Object.assign(async (run, { root = ctx.info.root, command, lease }) => {await observeNativeFailure({ root, config: acceptedConfig, pin, run, command, lease, kind,@@ -37,7 +50,7 @@ export function observer(ctx, { kind, board, main, commit, privateCheck = false,const write = target => ordered(ctx, target, 'recordFlakeObservation', [{ agentId, observation, lane }]);return board ? write(board) : withBoard(ctx, write);} });- }, { main: pin.main });+ }, { main: pin.main, recordRun });}/** Prepare an ordinary check callback before it queues; the callback observes red under that same lease. */diff --git a/src/native-flakes.js b/src/native-flakes.jsindex 754bd6c2..d356240c 100644--- a/src/native-flakes.js+++ b/src/native-flakes.js@@ -17,14 +17,11 @@ import {readFileSync,readSync,readdirSync,- realpathSync,statSync,writeFileSync,} from 'node:fs';import {- isAbsolute,join,- relative,} from 'node:path';import {headCommit,@@ -40,6 +37,10 @@ import {} from './trusted-policy.js';import { fileURLToPath } from 'node:url';import { runProfiledShell } from './gate.js';+import {+ committedTest,+ tapTests,+} from './tap-tests.js';/** Hash immutable bytes without retaining a potentially credential-bearing command in board data. */function digest(value) { return createHash('sha256').update(value).digest('hex'); }@@ -71,35 +72,6 @@ export function flakeSource(root, { commit, main, privateCheck = false } = {}) {load: { average: loadavg(), cpus: availableParallelism(), freeMB: Math.floor(freemem() / 1048576) } };}-/** Resolve live aliases; deleted private checks already carry their physical execution root. */-function physicalPath(path) {- try { return realpathSync(path); }- catch { return path; }-}--/** Read structured Node TAP blocks only; nested selectors and cancelled parents stay unsupported. */-function tapTests(output, root) {- const rows = [];- let active;- for (const raw of output.split('\n')) {- const match = /^(\s*)(not ok|ok)\s+\d+\s+-\s+(.*)$/u.exec(raw);- if (match) {- active = { name: match[3], passed: match[2] === 'ok', indent: match[1].length, file: null, skip: /\s+#\s*(?:SKIP|TODO)\b/iu.test(match[3]), type: null, failureType: null };- rows.push(active); continue;- }- if (!active) continue;- const field = /^(\s*)(location|type|failureType):\s*(.*?)\s*$/u.exec(raw);- if (!field || field[1].length !== active.indent + 2) continue;- const value = field[3].replace(/^(['"])(.*)\1$/u, '$2');- if (field[2] === 'location') {- const path = value.replace(/:\d+(?::\d+)?$/u, '');- const file = isAbsolute(path) ? relative(physicalPath(root), physicalPath(path)) : path.replace(/^\.\//u, '');- if (file && !file.startsWith('../') && !file.includes('\\')) active.file = file;- } else active[field[2]] = value;- }- return rows;-}-/** Use only a known structured Node runner; arbitrary shell, Jest and Vitest commands are never replaced. */function nodePrefix(command, config, root, pin) {const executable = '(?:node|/[^\\s\'";|&`$]+/node)';@@ -132,13 +104,6 @@ function knownRunner(root, pin) {} catch { return false; }}-/** Confirm the file is a committed regular test at the pinned source, without reading a live substitute. */-function committedTest(root, commit, file) {- if (!file || !/\.(?:[cm]?js)$/u.test(file) || file.startsWith('/') || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part === '.')) return false;- const result = tryGit(root, ['--literal-pathspecs', 'ls-tree', '-z', commit, '--', file]);- return result.status === 0 && /^(?:100644|100755) blob [a-f0-9]+\t/u.test(result.stdout) && result.stdout.split('\0').filter(Boolean).length === 1;-}-/** Copy the whole output/profile to unique durable evidence before any diagnostic executes. */function saveReceipt(directory, id, label, run) {const file = join(directory, label + '.log');diff --git a/src/next-steps.js b/src/next-steps.jsindex 68dcb2b3..31f631cd 100644--- a/src/next-steps.js+++ b/src/next-steps.js@@ -132,6 +132,9 @@ export const NEXT_STEPS = Object.freeze({BAD_SENDER: 'use the authenticated board credential belonging to the acting person, machine or agent, then retry',BAD_SEQUENCE: 'refresh the relay head and retry the saved operation at its declared coverage sequence; keep the durable pending record',FLAKE_EVIDENCE: 'retain the original gate log, timing profile and pinned source; ask the coordinator to repair the failure-evidence recorder before recording again',+ GATE_RUN_EVIDENCE: 'run the gate again from a clean, committed checkout so the run can name its tree, its failing test ids and the host load',+ GATE_RUN_UNBOUND: 'run the gate on this machine; it stores its own receipt and records its runs itself, and a run written by hand never counts',+ GATE_RUN_CHANGED: 'keep the original gate run unchanged; record a new run with a new id instead of replacing historical evidence',FLAKE_OBSERVATION_CHANGED: 'keep the original observation unchanged; record a new gate failure with a new observation identity instead of replacing historical evidence',HEALTH_FINDINGS: 'run pullboard health to read the current findings, then run pullboard resume to capture a fresh observation',HEALTH_SCAN_STALE: 'run pullboard resume again to scan the current board before posting sentinel notices',diff --git a/src/quarantine.js b/src/quarantine.jsnew file mode 100644index 00000000..0132bfd8--- /dev/null+++ b/src/quarantine.js@@ -0,0 +1,150 @@+/**+ * Gate runs and flake quarantine [C7,D1]. Every real gate run leaves its tree, its failing test ids and the host load on+ * the board, as the receipt its gate wrote. When one tree has been both red and green for the same test, that is proof+ * of a flake: the board files one repair item for the test and quarantines it. A quarantined test still runs and still+ * reports, but a landing no longer stops on it until its repair item is verified; after that it blocks again, and a new+ * proof starts a new quarantine. Quarantine is the coordinator's opt-in; with it off, runs and items are still recorded.+ */+import {+ addItem,+ atomic,+ getItem,+ listAgents,+ logEvent,+} from './board.js';+import { GATE_RUN_ENGINE } from './gate-run-engine.js';+import {+ boardReceiptStore,+ receiptBinds,+ receiptFields,+} from './gate-run-receipt.js';+import { COORDINATOR } from './config.js';+import { flakeLedger } from './flakes.js';+import { ENGINE_VERSION } from './machine.js';+import { Refused } from './refused.js';++const FAR_FUTURE = '9999-12-31T23:59:59.999Z';++/** Quarantine is the coordinator's opt-in: the board reads it from accepted main's pullboard.json, never from a branch. */+export function quarantineOn(board) {+ try { return board.quarantineEnabled?.() === true; } catch { return false; }+}++/** The one identity of a test across runs: its committed file and its structured name. */+function testKey(file, name) { return JSON.stringify([file, name]); }++/** Every recorded gate run, oldest first, with the event that carries it and the seat that recorded it. */+export function gateRuns(board) {+ return board.db.prepare("SELECT event_id, event_by, event_detail FROM event WHERE event_kind = 'gate-run' ORDER BY event_id").all()+ .map(row => ({ eventId: row.event_id, by: row.event_by, ...JSON.parse(row.event_detail).run }));+}++/**+ * Where a test's quarantine stands. Quarantined means its repair item is still being fixed; lifted means that item was+ * verified or withdrawn, so the test blocks again, and `since` is the event after which only newer runs count as proof.+ */+export function flakeQuarantines(board) {+ const latest = new Map();+ for (const row of board.db.prepare("SELECT event_id, item_id, event_detail FROM event WHERE event_kind = 'test-quarantine' ORDER BY event_id").all()) {+ const detail = JSON.parse(row.event_detail);+ latest.set(testKey(detail.file, detail.name), { file: detail.file, name: detail.name, item: row.item_id, tree: detail.tree, runs: detail.runs, eventId: row.event_id });+ }+ return [...latest.values()].map(entry => {+ const state = getItem(board, entry.item).item_status;+ const lifted = state === 'verified' || state === 'withdrawn';+ const closing = lifted ? board.db.prepare("SELECT MAX(event_id) AS id FROM event WHERE item_id = ? AND event_kind IN ('accept','withdraw')").get(entry.item).id : null;+ return { ...entry, status: lifted ? 'lifted' : 'quarantined', since: Math.max(entry.eventId, closing ?? 0) };+ });+}++/**+ * The quarantines as landing exceptions: the same shape as a person's waiver, but naming both the file and the test, so+ * a same-named test elsewhere is never covered, and living only while the repair item is open. A quarantine waives+ * nothing here unless every run that proved it is a receipt this machine's own gate wrote: a run that reached the board+ * any other way may still file its item, but it never lifts a landing block on this machine.+ */+export function quarantineWaivers(board) {+ if (!quarantineOn(board)) return [];+ const store = boardReceiptStore(board);+ const runs = new Map(gateRuns(board).map(({ eventId, by, ...run }) => [run.id, run]));+ return flakeQuarantines(board).filter(entry => entry.status === 'quarantined' && entry.runs.every(id => runs.has(id) && receiptBinds(store, runs.get(id))))+ .map(entry => ({ id: `quarantine-${entry.item}`, test: entry.name, kind: 'name', until: FAR_FUTURE, by: 'quarantine', channel: 'board',+ reason: `flaky test, repair #${entry.item} is not verified yet`, quarantine: { file: entry.file, name: entry.name, item: entry.item } }));+}++/** The open repair item the older paired-rerun ledger already holds for this test, so one test never gets two. */+function existingRepair(board, file, name) {+ const row = flakeLedger(board).find(entry => entry.file === file && entry.name === name && entry.item !== null);+ return row && !['verified', 'withdrawn'].includes(getItem(board, row.item).item_status) ? row.item : null;+}++/**+ * The receipt a run carries, checked and normalized, or a refusal naming what a gate run needs.+ *+ * @param {any} receipt+ * @returns {NonNullable<ReturnType<typeof receiptFields>>}+ */+export function runReceipt(receipt) {+ const fields = receiptFields(receipt);+ if (!fields) throw new Refused('GATE_RUN_EVIDENCE', 'a gate run needs its receipt: id, tree, command digest, result, failing tests and host load; run the gate again from a clean checkout');+ return fields;+}++/**+ * Refuse a run that is not the gate's own receipt, byte for byte, in the store beside this board. Only the gate's+ * private writer makes that file, right after the process it ran exits, so a run written by hand has nothing to match.+ */+export function requireBound(board, receipt) {+ if (!receiptBinds(boardReceiptStore(board), runReceipt(receipt))) throw new Refused('GATE_RUN_UNBOUND', 'a run counts only as the receipt its own gate stored for it; run the gate, which records its runs itself');+}++/**+ * Append one gate run and, when it completes a proof, file the repair item and quarantine the test. A test is proven+ * flaky only by a tree the coordinator's gate ran red in one run and green in another for that same test; a rerun of a+ * different tree, a failure that never went green, or a seat's own run proves nothing and quarantines nothing.+ *+ * @param {any} board+ * @param {{ agentId: string, receipt: object, lane: string }} request+ * @returns {{ run: object, duplicate?: boolean, quarantined: {file: string, name: string, item: number}[] }}+ */+export function recordGateRun(board, { agentId, receipt, lane }) {+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < GATE_RUN_ENGINE) throw new Refused('ENGINE_VERSION', `gate runs require engine ${GATE_RUN_ENGINE}; upgrade Pullboard`);+ if (!listAgents(board).some(agent => agent.agent_id === agentId)) throw new Refused('NOT_JOINED', 'join this board before recording a gate run');+ const value = runReceipt(receipt);+ // A caller's own run must be the receipt its gate stored. A sealed move being replayed was checked where it was made+ // (prepareEngineMove), because another machine holds no copy of that receipt; quarantineWaivers checks again here.+ if (board.executionEngineVersion === undefined) requireBound(board, value);+ return atomic(board, () => {+ const existing = gateRuns(board).find(entry => entry.id === value.id);+ if (existing) {+ const { eventId, by, ...stored } = existing;+ if (JSON.stringify(stored) !== JSON.stringify(value)) throw new Refused('GATE_RUN_CHANGED', 'a run id already binds different evidence; keep the original and use a new id');+ return { run: stored, duplicate: true, quarantined: [] };+ }+ logEvent(board, agentId, 'gate-run', null, { engine: GATE_RUN_ENGINE, run: value });+ // Only the coordinator's runs prove a flake: its landing and main-checkout gates run accepted work, and no seat can+ // send a move as the coordinator. A seat's runs stay on the board as evidence of what it saw [C7,D1].+ const sameTree = gateRuns(board).filter(entry => entry.tree === value.tree && entry.by === COORDINATOR);+ const candidates = new Map();+ for (const entry of sameTree) for (const failure of entry.failures) candidates.set(testKey(failure.file, failure.name), failure);+ const known = new Map(flakeQuarantines(board).map(entry => [testKey(entry.file, entry.name), entry]));+ const filed = [];+ for (const [key, failure] of candidates) {+ const prior = known.get(key);+ if (prior?.status === 'quarantined') continue;+ const since = prior?.since ?? 0;+ const red = sameTree.filter(entry => entry.eventId > since && !entry.green && entry.failures.some(f => testKey(f.file, f.name) === key));+ const green = sameTree.filter(entry => entry.eventId > since && entry.green);+ if (!red.length || !green.length) continue;+ const evidence = [...red, ...green].sort((a, b) => a.eventId - b.eventId);+ const item = existingRepair(board, failure.file, failure.name) ?? addItem(board, { by: agentId, lane, route: 'strong',+ title: `Flaky test: ${failure.file} :: ${failure.name}`.slice(0, 240),+ criterion: `Identify and correct why ${failure.file} :: ${failure.name} fails intermittently on an unchanged tree; prove the correction without retries, and pass the gate.`,+ brief: `One tree went red and green for this test. Tree ${value.tree}. When the coordinator turns quarantine on, the test still runs and reports, but a landing no longer stops on it until this item is verified.\n\n`+ + evidence.map(entry => JSON.stringify({ run: entry.id, kind: entry.kind, at: entry.at, green: entry.green, failing: entry.failures.map(f => f.file + ' :: ' + f.name), load: entry.load })).join('\n') });+ logEvent(board, agentId, 'test-quarantine', item, { engine: GATE_RUN_ENGINE, file: failure.file, name: failure.name, tree: value.tree, runs: evidence.map(entry => entry.id) });+ filed.push({ file: failure.file, name: failure.name, item });+ }+ return { run: value, quarantined: filed };+ });+}diff --git a/src/relay-sender.js b/src/relay-sender.jsindex 15015ae3..e8a1ed2c 100644--- a/src/relay-sender.js+++ b/src/relay-sender.js@@ -10,7 +10,7 @@ export function relayMoveActor(move) {if (move.operation === 'addItem') return args[0]?.by ?? null;if (move.operation === 'shout') return args[0]?.from ?? null;if (['proposeSentinel', 'decideSentinel', 'beginSentinelRun', 'finishSentinelRun'].includes(move.operation)) return args[0]?.agentId ?? null;- if (['recordHealthFindings', 'recordFlakeObservation', 'declareJob', 'recordJobRun'].includes(move.operation)) return args[0]?.agentId ?? null;+ if (['recordHealthFindings', 'recordFlakeObservation', 'recordGateRun', 'declareJob', 'recordJobRun'].includes(move.operation)) return args[0]?.agentId ?? null;if (['holdLane', 'releaseLane'].includes(move.operation) && args[1]?.asPerson) return 'person';if (move.operation === 'release') return args[1] ?? null;if (['reserveNextReview', 'addMilestone', 'recordRowDecisions', 'applyRowDecisions', 'draftSpecRow', 'recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'finishLandingBatch'].includes(move.operation)) return args[0]?.agentId ?? null;diff --git a/src/tap-tests.js b/src/tap-tests.jsnew file mode 100644index 00000000..02e2114e--- /dev/null+++ b/src/tap-tests.js@@ -0,0 +1,48 @@+/**+ * Read which committed tests a Node TAP run names [C7,D1]. Both the flake diagnostics and the gate's own run receipt+ * use it, so a failing test has one identity everywhere: its committed file and its structured name.+ */+import {+ realpathSync,+} from 'node:fs';+import {+ isAbsolute,+ relative,+} from 'node:path';+import { tryGit } from './git.js';++/** Resolve live aliases; deleted private checks already carry their physical execution root. */+function physicalPath(path) {+ try { return realpathSync(path); }+ catch { return path; }+}++/** Read structured Node TAP blocks only; nested selectors and cancelled parents stay unsupported. */+export function tapTests(output, root) {+ const rows = [];+ let active;+ for (const raw of output.split('\n')) {+ const match = /^(\s*)(not ok|ok)\s+\d+\s+-\s+(.*)$/u.exec(raw);+ if (match) {+ active = { name: match[3], passed: match[2] === 'ok', indent: match[1].length, file: null, skip: /\s+#\s*(?:SKIP|TODO)\b/iu.test(match[3]), type: null, failureType: null };+ rows.push(active); continue;+ }+ if (!active) continue;+ const field = /^(\s*)(location|type|failureType):\s*(.*?)\s*$/u.exec(raw);+ if (!field || field[1].length !== active.indent + 2) continue;+ const value = field[3].replace(/^(['"])(.*)\1$/u, '$2');+ if (field[2] === 'location') {+ const path = value.replace(/:\d+(?::\d+)?$/u, '');+ const file = isAbsolute(path) ? relative(physicalPath(root), physicalPath(path)) : path.replace(/^\.\//u, '');+ if (file && !file.startsWith('../') && !file.includes('\\')) active.file = file;+ } else active[field[2]] = value;+ }+ return rows;+}++/** Confirm the file is a committed regular test at the pinned source, without reading a live substitute. */+export function committedTest(root, commit, file) {+ if (!file || !/\.(?:[cm]?js)$/u.test(file) || file.startsWith('/') || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part === '.')) return false;+ const result = tryGit(root, ['--literal-pathspecs', 'ls-tree', '-z', commit, '--', file]);+ return result.status === 0 && /^(?:100644|100755) blob [a-f0-9]+\t/u.test(result.stdout) && result.stdout.split('\0').filter(Boolean).length === 1;+}diff --git a/test/gate.test.js b/test/gate.test.jsindex 124aaf85..7259db62 100644--- a/test/gate.test.js+++ b/test/gate.test.js@@ -5,11 +5,23 @@import assert from 'node:assert/strict';import { runFixtureExecFile as execFileSync, runFixtureChild as spawnSync, runFixtureChild, runFixtureGit, startFixtureChild as spawn } from './fixture-child.js';import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';+import { renameSync } from 'node:fs';import { tmpdir } from 'node:os';-import { join, resolve } from 'node:path';+import { dirname, join, resolve } from 'node:path';import { after, test } from 'node:test';import { pathToFileURL } from 'node:url';+import * as store from '../src/board.js';+import { main as cli } from '../src/cli.js';import { digestOf, testConcurrency } from '../src/gate.js';+import { runGate } from '../src/gate.js';+import { liveWaiverProjection } from '../src/land.js';+import { waiverLine } from '../src/land.js';+import { waivedFailures } from '../src/land.js';+import { applyEngineMove } from '../src/engine.js';+import { prepareEngineMove } from '../src/engine.js';+import { mainPolicy } from '../src/trusted-policy.js';+import { ENGINE_VERSION } from '../src/machine.js';+import { submitFixture } from './board-submit-fixture.js';import { BROWSER_SLOT_HELD_ENV, GATE_SLOT_HELD_ENV, GATE_SLOT_POOL_ENV, GATE_SLOT_TOKEN_ENV } from '../src/resources.js';const PRIVATE_WORKER = resolve(import.meta.dirname, '../src/private-check-worker.js');@@ -580,3 +592,185 @@ test('output after the match', async () => {assert.equal(verified.error, null, 'the private verifier keeps its original shell behavior');}});++const FLAKY = { file: 'test/flaky.test.js', name: 'flaky target' };+const FLAKY_GATE = 'node --test --test-reporter=tap test/flaky.test.js';++/**+ * A real repo whose accepted gate runs one real test that reads a marker outside the tree: present, it fails; absent,+ * it passes. So one committed tree really goes red and green, the way a load-dependent test does, with nothing faked.+ * The board is the repo's own, in its git directory, and the gate runs through the real `pullboard gate`.+ */+function flakeRepo(t, policy = {}) {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'pullboard-quarantine-')));+ dirs.push(dir);+ const root = join(dir, 'repo');+ mkdirSync(join(root, 'test'), { recursive: true });+ const saved = { ...process.env };+ t.after(() => { for (const name of Object.keys(process.env)) if (!(name in saved)) delete process.env[name]; Object.assign(process.env, saved); });+ for (const name of Object.keys(process.env)) if (name.startsWith('GIT_')) delete process.env[name];+ delete process.env.PULLBOARD_RELAY_TOKEN;+ // The fixture gate is its own `node --test` run, not a child of this one.+ delete process.env.NODE_TEST_CONTEXT;+ Object.assign(process.env, { PULLBOARD_HOME: join(dir, 'home'), PULLBOARD_MACHINE_HOME: join(dir, 'machine-home'), GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',+ GIT_AUTHOR_NAME: 'Flake Test', GIT_AUTHOR_EMAIL: '[email protected]', GIT_COMMITTER_NAME: 'Flake Test', GIT_COMMITTER_EMAIL: '[email protected]' });+ const git = (...args) => runFixtureGit(args, { cwd: root });+ git('init', '-q', '-b', 'main');+ const marker = join(root, '.git', 'flaky-red');+ const commit = (comment, extra = {}) => {+ writeFileSync(join(root, 'pullboard.json'), `${JSON.stringify({ gate: FLAKY_GATE, lanes: { app: { owns: ['test/'] } }, ...policy, ...extra }, null, 2)}\n`);+ writeFileSync(join(root, FLAKY.file), `import { existsSync } from 'node:fs';\nimport { test } from 'node:test';\n// ${comment}\n`+ + `test('flaky target', () => { if (existsSync(${JSON.stringify(marker)})) throw new Error('red this time'); });\n`);+ git('add', '-A');+ git('commit', '-q', '-m', `test: ${comment}`);+ return git('rev-parse', 'HEAD^{tree}');+ };+ /**+ * Run the real gate once through the CLI, red when asked, and return what it printed. A plain gate skips a tree it+ * already passed; the landing gate never does, so the fixture clears that stamp to run the same tree again.+ */+ const gate = async (red, { landing = false, code = red ? 1 : 0 } = {}) => {+ if (red) writeFileSync(marker, 'red\n'); else rmSync(marker, { force: true });+ rmSync(join(root, '.git', 'pullboard-gate-green'), { force: true });+ let output = '';+ const io = { stdout: { isTTY: false, write: (text) => { output += text; } }, stderr: { write: (text) => { output += text; } } };+ assert.equal(await cli(landing ? ['gate', '--landing'] : ['gate'], { cwd: root, ...io }), code, output);+ return output;+ };+ const file = join(root, '.git', 'pullboard', 'board.sqlite');+ /** Open the repo's board the way a landing reads it: quarantine comes from accepted main's pullboard.json. */+ const open = () => {+ const board = store.openBoard(file);+ board.quarantineEnabled = () => mainPolicy(root).config.flakes?.quarantine === true;+ t.after(() => store.closeBoard(board));+ return board;+ };+ const receipts = join(root, '.git', 'pullboard', 'gate-receipts');+ mkdirSync(dirname(file), { recursive: true });+ const setup = store.openBoard(file);+ store.ensureCoordinator(setup, root);+ store.closeBoard(setup);+ return { root, git, commit, gate, open, receipts, marker };+}++test('the same tree red and green proves a flake and files it once [C7,D1]', async (t) => {+ const box = flakeRepo(t);+ const tree = box.commit('one');+ await box.gate(true);+ let board = box.open();+ const [red] = store.gateRuns(board);+ assert.equal(red.tree, tree, 'every run records the tree it ran on');+ assert.equal(red.green, false);+ assert.deepEqual(red.failures, [FLAKY], 'a red run names the committed test that failed');+ assert.ok(red.load.cpus >= 1 && red.load.average.length === 3 && red.load.freeMB >= 0, 'every run records the host load');+ assert.equal(red.by, 'coordinator', 'the main checkout records as the coordinator');+ assert.equal(store.listItems(board, { all: true }).length, 0, 'a red run alone proves nothing');+ await box.gate(false);+ board = box.open();+ const items = store.listItems(board, { all: true });+ assert.equal(items.length, 1, 'the same tree red and green files one item');+ assert.match(items[0].item_title, /^Flaky test: test\/flaky\.test\.js :: flaky target/u);+ const [, green] = store.gateRuns(board);+ assert.equal(green.green, true);+ assert.match(items[0].item_brief, new RegExp(red.id, 'u'), 'the red run is the evidence on the item');+ assert.match(items[0].item_brief, new RegExp(green.id, 'u'), 'and so is the green run');+ assert.match(items[0].item_brief, /"load":\{"average":/u, 'with the host load of each');+ assert.equal(store.flakeQuarantines(board).length, 1);+ await box.gate(true);+ await box.gate(false);+ board = box.open();+ assert.equal(store.gateRuns(board).length, 4, 'every run is recorded');+ assert.equal(store.listItems(board, { all: true }).length, 1, 'more red and green runs of the same test file no second item');+ box.commit('two');+ await box.gate(false);+ board = box.open();+ assert.equal(store.listItems(board, { all: true }).length, 1, 'a green run of another tree proves nothing new');+ assert.equal(waivedFailures(board, [FLAKY]), null, 'with quarantine off by default, the proven flake still blocks a landing');+ assert.deepEqual(liveWaiverProjection(board), []);+});++test('a quarantined test reports but does not block [C7,D1]', async (t) => {+ const box = flakeRepo(t, { flakes: { quarantine: true } });+ box.commit('one');+ assert.equal(waivedFailures(box.open(), [FLAKY]), null, 'a red test blocks before it is proven flaky');+ await box.gate(true);+ await box.gate(false);+ let board = box.open();+ const covered = waivedFailures(board, [FLAKY]);+ assert.equal(covered?.length, 1, 'the proven flake no longer blocks');+ const [item] = store.listItems(board, { all: true });+ assert.equal(waiverLine(covered[0]), `quarantined: flaky target (test/flaky.test.js) is a proven flake, reported but not blocking until repair #${item.item_id} is verified`, 'it still reports by name');+ assert.deepEqual(liveWaiverProjection(board), [{ kind: 'name', test: 'flaky target' }], 'the landing run keeps going past it and still reports it');+ assert.equal(waivedFailures(board, [FLAKY, { file: 'test/other.test.js', name: 'another failure' }]), null, 'a quarantine never hides a different red');+ assert.equal(waivedFailures(board, [{ file: 'test/other.test.js', name: FLAKY.name }]), null, 'the same name in another file is not covered');+ // A proof this machine's gate did not run, such as one replayed from another machine, waives nothing here.+ renameSync(box.receipts, `${box.receipts}.elsewhere`);+ assert.equal(waivedFailures(board, [FLAKY]), null, 'a quarantine waives only runs whose receipts are on the landing machine');+ renameSync(`${box.receipts}.elsewhere`, box.receipts);+ const landing = await box.gate(true, { landing: true, code: 0 });+ assert.match(landing, /^landing gate waived, not green: 1 failure\(s\)/mu, 'a landing run goes past the quarantined red without calling it green');+ assert.match(landing, /^quarantined: flaky target \(test\/flaky\.test\.js\) is a proven flake, reported but not blocking/mu, 'and still reports it');+ board = box.open();+ // The repair is built, submitted and verified by two different agents; only then does the test block again.+ const builder = store.register(board, { lane: 'app', path: join(box.root, '..', 'build'), route: 'strong' });+ const reviewer = store.register(board, { lane: 'app', path: join(box.root, '..', 'review'), route: 'strong' });+ store.claim(board, item.item_id, { agentId: builder, lane: 'app', leaseMs: 3600000, freeze: () => ({ text: 'repair', digest: 'd'.repeat(64) }) });+ submitFixture(board, item.item_id, { agentId: builder, commit: 'e'.repeat(40), tree: 'f'.repeat(40) });+ assert.equal(waivedFailures(board, [FLAKY])?.length, 1, 'a submitted repair does not lift the quarantine');+ store.verify(board, item.item_id, { agentId: reviewer, decision: 'ACCEPT', head: 'e'.repeat(40), digest: 'd'.repeat(64), policy: 'any', note: 'synthetic board-state fixture' });+ assert.equal(waivedFailures(board, [FLAKY]), null, 'the verified repair makes the test block again');+ // It fails again after its fix landed: it blocks, and only a new red-and-green proof files a new item.+ box.commit('three');+ await box.gate(true);+ board = box.open();+ assert.equal(waivedFailures(board, [FLAKY]), null, 'a failure after its fix blocks');+ assert.equal(store.listItems(board, { all: true }).length, 1);+ await box.gate(false);+ board = box.open();+ assert.equal(store.listItems(board, { all: true }).length, 2, 'a second proof after the fix files a new item');+ assert.equal(waivedFailures(board, [FLAKY])?.length, 1);+});++test('a hand-recorded run never quarantines a test [C7,D1]', async (t) => {+ const box = flakeRepo(t, { flakes: { quarantine: true } });+ const tree = box.commit('one');+ const head = box.git('rev-parse', 'HEAD');+ const board = box.open();+ const builder = store.register(board, { lane: 'app', path: join(box.root, '..', 'build'), route: 'strong' });+ const load = { average: [0, 0, 0], cpus: 1, freeMB: 100 };+ const forged = (id, green) => ({ version: 1, id, kind: 'land', tree, head, main: head, command: 'c'.repeat(64), green,+ failures: green ? [] : [FLAKY], load, at: new Date().toISOString() });+ const runs = [forged('00000000-0000-4000-8000-000000000001', false), forged('00000000-0000-4000-8000-000000000002', true)];+ for (const receipt of runs) {+ for (const agentId of ['coordinator', builder]) {+ assert.throws(() => store.recordGateRun(board, { agentId, receipt, lane: 'app' }), (error) => error.code === 'GATE_RUN_UNBOUND' || assert.fail(error), 'a run recorded by hand is refused');+ assert.throws(() => prepareEngineMove(board, 'recordGateRun', [{ agentId, receipt, lane: 'app' }], { id: `move-${receipt.id.slice(-1)}-${agentId}`, actor: agentId }),+ (error) => error.code === 'GATE_RUN_UNBOUND', 'and so is sealing it as a move');+ }+ }+ // A seat that seals its made-up runs by hand, past prepareEngineMove, is replayed as a record but proves nothing.+ for (const [sequence, receipt] of runs.entries()) {+ const move = { version: 1, engine: ENGINE_VERSION, id: `forged-${sequence}`, operation: 'recordGateRun', args: [{ agentId: builder, receipt, lane: 'app' }], actor: builder };+ applyEngineMove(board, move, { sequence: sequence + 1, at: new Date().toISOString() });+ }+ assert.equal(store.listItems(board, { all: true }).length, 0, 'no item is filed from runs a seat recorded by hand');+ assert.deepEqual(store.flakeQuarantines(board), []);+ // Running something other than the accepted gate is a real execution, but of the wrong command: it leaves no receipt.+ const fake = `printf 'TAP version 13\\nnot ok 1 - flaky target\\n ---\\n location: ${join(box.root, FLAKY.file)}:4:1\\n ...\\n1..1\\n'; exit 1`;+ const observed = [];+ const observer = Object.assign(async () => {}, { recordRun: async (id) => observed.push(id) });+ for (const _ of [1, 2]) await runGate(box.root, { ...mainPolicy(box.root).config, gate: fake }, { trustStamp: false, onFailure: observer });+ assert.deepEqual(observed, [], 'a command other than the accepted gate leaves no receipt to record');+ assert.equal(existsSync(box.receipts), false, 'and nothing in the receipt store');+ // A real receipt cannot be reused to say something else: each altered field breaks the binding.+ await box.gate(true);+ const reopened = box.open();+ const [real] = store.gateRuns(reopened);+ const { eventId, by, ...receipt } = real;+ for (const lie of [{ ...receipt, green: true, failures: [] }, { ...receipt, failures: [{ file: FLAKY.file, name: 'another test' }] }, { ...receipt, command: 'c'.repeat(64) },+ { ...receipt, id: '00000000-0000-4000-8000-000000000003' }]) {+ assert.throws(() => store.recordGateRun(reopened, { agentId: 'coordinator', receipt: lie, lane: 'app' }), (error) => ['GATE_RUN_UNBOUND', 'GATE_RUN_CHANGED'].includes(error.code));+ }+ assert.equal(store.listItems(reopened, { all: true }).length, 0, 'one real red and no green proves nothing');+ assert.equal(waivedFailures(reopened, [FLAKY]), null, 'no landing block is removed');+});diff --git a/test/relay-credential.test.js b/test/relay-credential.test.jsindex 45d3e2e4..cce3eaa8 100644--- a/test/relay-credential.test.js+++ b/test/relay-credential.test.js@@ -26,6 +26,8 @@ test('every current operation selects its native actor credential without a secoif (operation === 'reserveNextReview') args = [options];if (operation === 'recordHealthFindings') args = [{ agentId: actor, observedRevision: 0, findings: [] }];if (operation === 'recordFlakeObservation') args = [{ agentId: actor, lane: box.lane, observation: syntheticFlakeObservation('credential-fixture') }];+ if (operation === 'recordGateRun') args = [{ agentId: actor, lane: box.lane, receipt: { version: 1, id: '00000000-0000-4000-8000-00000000c0de', kind: 'gate', tree: 'b'.repeat(40), head: 'a'.repeat(40),+ 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 === 'proposeSentinel') args = [{ agentId: actor,@@ -50,11 +52,14 @@ test('every current operation selects its native actor credential without a secoif (operation === 'applyRowDecisions') args = [{ agentId: actor, events: [] }];if (operation === 'draftSpecRow') args = [{ agentId: actor, row: { id: 'G9', text: 'A credential fixture row.', gate: 'review', tier: 'must', section: 'G · Goals' } }];if (operation === 'recordRowDecisions') { args = [{ agentId: 'person', channel: 'terminal', decisions: [] }]; kind = 'person'; }+ // A gate run with no receipt from this machine's own gate is refused before it reaches transport.+ if (operation === 'recordGateRun') return { operation, args, kind, sent: false, expected: 'GATE_RUN_UNBOUND' };return { operation, args, kind, ...(kind === 'person' ? { sent: false } : {}) };});cases.push({ operation: 'recordHealthFindings', args: [{ observedRevision: 0, findings: [] }], kind: 'agent', sent: false, expected: 'RELAY_ACTOR' },{ operation: 'recordFlakeObservation', args: [{ lane: box.lane, observation: syntheticFlakeObservation('missing-actor') }], kind: 'agent', sent: false, expected: 'RELAY_ACTOR' },+ { operation: 'recordGateRun', args: [{ lane: box.lane, receipt: {} }], kind: 'agent', sent: false, expected: 'GATE_RUN_EVIDENCE' },{ operation: 'submit', args: [999999, options], kind: 'agent', sent: false, expected: 'SUBMISSION_PROOF' },{ operation: 'answerDecision', args: [999999, { ...options, asPerson: true, channel: 'terminal' }], kind: 'person', sent: false },{ operation: 'holdLane', args: [box.lane, { ...options, asPerson: true, channel: 'terminal' }], kind: 'person', sent: false },