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: add runner-first gate scheduling [C7]
Corey Olson3502a4a8527a
diff --git a/src/commands/settings.js b/src/commands/settings.jsindex 938f1dbd..170faac7 100644--- a/src/commands/settings.js+++ b/src/commands/settings.js@@ -15,6 +15,7 @@ import {setBrowserSlots,setGateShortSlots,setGateSlots,+ setGateRunnersFirst,setLandingPool,} from '../settings.js';import {@@ -41,7 +42,8 @@ export function settingsCommand(io, { first, second, rest, values }) {// The result names the queue order in effect, defaults included; the file keeps only what was set.const offerAtInit = relayOfferEnabled();const shortSlots = gateShortSlots();- io.result?.({ settings: { ...settings, gate: { ...settings.gate, queue: { ...settings.gate?.queue, ...queue }, shortSlots }, relay: { ...settings.relay, offerAtInit } }, memoryFloorMB: memoryFloorMB() });+ const runnersFirst = settings.gate?.runnersFirst === true;+ io.result?.({ settings: { ...settings, gate: { ...settings.gate, queue: { ...settings.gate?.queue, ...queue }, shortSlots, runnersFirst }, relay: { ...settings.relay, offerAtInit } }, memoryFloorMB: memoryFloorMB() });io.say(`gateSlots: ${settings.gateSlots}`);io.say(`browserSlots: ${settings.browserSlots}`);io.say(`gate.queue.reviewsFirst: ${queue.reviewsFirst}${queue.reviewsFirst ? '' : ' (landings first, then arrival order)'}`);@@ -51,10 +53,18 @@ export function settingsCommand(io, { first, second, rest, values }) {io.say(`view.background: ${settings.view?.background !== false}${settings.view?.background === false ? ' (init and resume leave the view to you)' : ' (init and resume keep pullboard view running for pullboard.dev)'}`);io.say(`relay.offerAtInit: ${offerAtInit}${offerAtInit ? ' (init asks once to share your boards with your phone)' : ' (init stays quiet about sharing)'}`);io.say(`gate.shortSlots: ${shortSlots}${shortSlots ? '' : ' (off; runs that name their test files wait for a gate slot)'}`);+ io.say(`gate.runnersFirst: ${runnersFirst} (registered runners are preferred before local slots when on)`);return 0;}if (!SETTING_FORMS.includes(first) || !second || rest.length) {- throw new Refused('USAGE', 'pullboard settings gateSlots <n> | browserSlots <n> | gate.shortSlots <n>');+ throw new Refused('USAGE', 'pullboard settings gateSlots <n> | browserSlots <n> | gate.shortSlots <n> | gate.runnersFirst on|off');+ }+ if (first === 'gate.runnersFirst') {+ if (!['on', 'off'].includes(second)) throw new Refused('BAD_MACHINE_SETTINGS', 'gate.runnersFirst must be on or off; run pullboard settings gate.runnersFirst on|off');+ const settings = setGateRunnersFirst(second === 'on');+ io.result?.({ settings });+ io.say(`gate.runnersFirst set to ${second}`);+ return 0;}if (first === 'gate.shortSlots') {if (!/^(?:0|[1-9]\d*)$/u.test(second) || !Number.isSafeInteger(Number(second))) {@@ -65,9 +75,9 @@ export function settingsCommand(io, { first, second, rest, values }) {io.say(`gate.shortSlots set to ${settings.gate.shortSlots}`);return 0;}- if (!/^[1-9]\d*$/u.test(second) || !Number.isSafeInteger(Number(second))) {- if (first === 'gateSlots') throw new Refused('USAGE', 'pullboard settings gateSlots <positive integer>');- throw new Refused(first === 'browserSlots' ? 'BAD_BROWSER_SLOTS' : 'BAD_GATE_SLOTS', `${first} must be a positive integer; run pullboard settings ${first} <n>`);+ if (!/^(?:0|[1-9]\d*)$/u.test(second) || !Number.isSafeInteger(Number(second))) {+ if (first === 'gateSlots') throw new Refused('USAGE', 'pullboard settings gateSlots <n>');+ throw new Refused('BAD_BROWSER_SLOTS', 'browserSlots must be a whole number, 0 or more; 0 requires a registered runner');}const settings = first === 'browserSlots' ? setBrowserSlots(Number(second)) : setGateSlots(Number(second));io.result?.({ settings });diff --git a/src/gate.js b/src/gate.jsindex b8d80a37..dcfb9be3 100644--- a/src/gate.js+++ b/src/gate.js@@ -74,6 +74,7 @@ import {} from './resources.js';import {browserFreeChecksEnabled,+ gateRunnersFirstEnabled,gateQueueSettings,gateShortSlots,loadMachineSettings,@@ -438,6 +439,7 @@ async function withOneGateSlot(root, action, { landing = false, itemCheck = falsallowIdleCapacityUpdate: true,remote: remote && Boolean(source),runnerProvider: () => loadMachineSettings().runners ?? [],+ runnersFirstProvider: gateRunnersFirstEnabled,releaseContext,memory: floorMB === null ? undefined : memoryAdmission({ floorBytes: () => (memoryFloorMB() ?? floorMB) * 1024 ** 2, read: readMemory }),onWait,diff --git a/src/help.js b/src/help.jsindex 6d4cb548..61fe3db6 100644--- a/src/help.js+++ b/src/help.js@@ -33,13 +33,14 @@ Set uppullboard settings line [<name> <value> --reason "why" --window <json>] read or record board controller inputs; all off by defaultvalue is on, off, or a number within the setting rangenames: order, reviewsFirst, wipPerReviewer (1.5-3), barReady, bar.check, takeoverMinutes (15-60), collisionFreeBatch, landingBatchSize (1-8), landingCadenceMinutes (5-30)- pullboard settings [gateSlots <n> | browserSlots <n>] view or set machine capacity (gate default 2; browser default 1)+ pullboard settings [gateSlots <n> | browserSlots <n> | gate.runnersFirst on|off] view or set machine gate policy and capacity (gate default 2; browser default 1)browser-free check slots are opt-in: gate.browserFreeChecks in ~/.pullboard/settings.json (default false)a test file takes a browser slot only if it launches Chrome: gate.browserByLaunch (default false)reviews-first queue order is opt-in: gate.queue.reviewsFirst (default false), gate.queue.agingMinutes (default 30)release priority is opt-in: gate.queue.currentReleaseFirst (default false), within each board's otherwise-tied positionsmemory hold is opt-in: gate.memoryFloorMB in ~/.pullboard/settings.json holds the queue under that many MB free or critical pressure (default off)short slots for runs that name their test files are opt-in: pullboard settings gate.shortSlots <n> (default 0)+ runner-first dispatch is opt-in: pullboard settings gate.runnersFirst on|off (default off)pullboard runner add <ssh-host> --slots <n> --browser <n> [--node <remote-path>] [--root <remote-path>]register SSH test capacity; no runner sign-in; root defaults to ~/.pullboard-runnerpullboard runner list each runner's registered slots and browsers, which it runs at@@ -466,7 +467,7 @@ function overviewHelp(groups, firstRun = false) {}/** The settings forms settingsCommand dispatches with a value; each gets its own help, from this list (N2). */-export const SETTING_FORMS = Object.freeze(['gateSlots', 'browserSlots', 'gate.shortSlots', 'landing.pool']);+export const SETTING_FORMS = Object.freeze(['gateSlots', 'browserSlots', 'gate.shortSlots', 'gate.runnersFirst', 'landing.pool']);/** Help for each settings form the printed usage did not already name, so each form is covered (N2). */function settingFormHelp(commands) {diff --git a/src/resources.js b/src/resources.jsindex b859e916..cf10982e 100644--- a/src/resources.js+++ b/src/resources.js@@ -125,6 +125,7 @@ function openQueue(file) {CREATE INDEX IF NOT EXISTS holder_name ON holder(name);CREATE TABLE IF NOT EXISTS waiter (ticket INTEGER PRIMARY KEY AUTOINCREMENT, token TEXT UNIQUE NOT NULL, name TEXT NOT NULL, pid INTEGER NOT NULL, started TEXT NOT NULL DEFAULT '', agent TEXT NOT NULL, repo TEXT NOT NULL, since TEXT NOT NULL, heartbeat INTEGER NOT NULL, landing INTEGER NOT NULL DEFAULT 0, item_check INTEGER NOT NULL DEFAULT 0, browser INTEGER NOT NULL DEFAULT 0, item TEXT NOT NULL DEFAULT '', kind TEXT NOT NULL DEFAULT '', remote INTEGER NOT NULL DEFAULT 0, short_eligible INTEGER NOT NULL DEFAULT 0);CREATE TABLE IF NOT EXISTS runner_unavailable (host TEXT PRIMARY KEY, since TEXT NOT NULL, detail TEXT NOT NULL DEFAULT '');+ CREATE TABLE IF NOT EXISTS runner_rotation (pool TEXT PRIMARY KEY, next_host TEXT NOT NULL DEFAULT '');CREATE TABLE IF NOT EXISTS runner_gui (host TEXT PRIMARY KEY, gui INTEGER, observed_at TEXT NOT NULL);CREATE TABLE IF NOT EXISTS runner_draining (host TEXT PRIMARY KEY, runner TEXT NOT NULL);CREATE INDEX IF NOT EXISTS waiter_name_ticket ON waiter(name, ticket);`);@@ -457,7 +458,7 @@ function validatedRunners(value) {* @param {number} [now] - The clock reading to age against.* @returns {{host:string,slots:number,browser:number}|null}*/-function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARRIVAL_ORDER, now = Date.now()) {+function gateAdmission(db, ticket, capacity, shortCapacity, runners, runnersFirst = false, order = ARRIVAL_ORDER, now = Date.now()) {const waiters = orderedWaiters(queuedWaiters(db, 'gate'), now, order);const holders = db.prepare("SELECT pid, landing, browser, short_slot AS shortSlot, timing FROM holder WHERE name = 'gate'").all();const localUsed = holders.filter(holder => holder.shortSlot !== 1).length;@@ -481,12 +482,13 @@ function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARR/** Find a currently free compatible slot without reserving it for later queue entries. */function available(waiter) {if (blockedByLanding(waiter)) return null;- if (!holders.some(holder => holder.timing === 1) && (waiter.timing !== 1 || holders.length === 0)- && localUsed < capacity && (waiter.browser !== 1 || localBrowsers < browserCapacity)) {- return { host: '', slots: capacity, browser: waiter.browser === 1 ? 1 : 0, shortSlot: false };- }- if (waiter.remote === 1) {- const compatible = runners.filter(runner => {+ /** Pick an eligible runner in durable round-robin order when the machine opts in. */+ function runnerSlot() {+ if (waiter.remote !== 1) return null;+ const cursor = runnersFirst ? db.prepare("SELECT next_host FROM runner_rotation WHERE pool = 'gate'").get()?.next_host : '';+ const start = Math.max(0, runners.findIndex(runner => runner.host === cursor));+ const ordered = runnersFirst ? [...runners.slice(start), ...runners.slice(0, start)] : runners;+ const compatible = ordered.filter(runner => {const observed = db.prepare('SELECT gui FROM runner_gui WHERE host = ?').get(runner.host);const gui = observed ? observed.gui === 1 : runner.gui === true;if (unavailable.has(runner.host) || (waiter.browser === 1 && runner.browser < 1) || (waiter.gui === 1 && !gui)) return false;@@ -494,13 +496,30 @@ function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARRreturn !used.timing && (waiter.timing !== 1 || used.slots === 0)&& used.slots < runner.slots && (waiter.browser !== 1 || used.browsers < runner.browser);});- // A landing spreads its active shards before filling another slot on the same runner.- // Choose under this transaction's holder snapshot, so concurrent acquisitions cannot tie on stale use.- if (waiter.landing === 1) compatible.sort((left, right) => usage.get(left.host).slots - usage.get(right.host).slots);- if (compatible.length) {- const observed = db.prepare('SELECT gui FROM runner_gui WHERE host = ?').get(compatible[0].host);- return { ...compatible[0], ...(observed ? { gui: observed.gui === null ? null : observed.gui === 1 } : {}), shortSlot: false };+ // Existing landing balancing stays intact when the opt-in rotation is off.+ if (!runnersFirst && waiter.landing === 1) compatible.sort((left, right) => usage.get(left.host).slots - usage.get(right.host).slots);+ if (!compatible.length) return null;+ const selected = compatible[0];+ const observed = db.prepare('SELECT gui FROM runner_gui WHERE host = ?').get(selected.host);+ return { ...selected, ...(observed ? { gui: observed.gui === null ? null : observed.gui === 1 } : {}), shortSlot: false };+ }+ /** The local slot follows runner admission only while runner-first is enabled. */+ function localSlot() {+ if (!holders.some(holder => holder.timing === 1) && (waiter.timing !== 1 || holders.length === 0)+ && localUsed < capacity && (waiter.browser !== 1 || localBrowsers < browserCapacity)) {+ return { host: '', slots: capacity, browser: waiter.browser === 1 ? 1 : 0, shortSlot: false };}+ return null;+ }+ const remote = runnerSlot();+ if (runnersFirst) {+ if (remote) return remote;+ const local = localSlot();+ if (local) return local;+ } else {+ const local = localSlot();+ if (local) return local;+ if (remote) return remote;}const earlierLanding = waiters.some(other => other.landing === 1 && other.ticket < waiter.ticket);if (waiter.timing !== 1 && !holders.some(holder => holder.timing === 1)@@ -522,7 +541,15 @@ function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARR}for (const waiter of waiters) {const executor = available(waiter);- if (executor) return waiter.ticket === ticket ? executor : null;+ if (executor) {+ if (waiter.ticket !== ticket) return null;+ if (runnersFirst && executor.host) {+ const selected = runners.findIndex(runner => runner.host === executor.host);+ const nextHost = runners[(selected + 1) % runners.length]?.host ?? '';+ db.prepare("INSERT INTO runner_rotation(pool, next_host) VALUES ('gate', ?) ON CONFLICT(pool) DO UPDATE SET next_host = excluded.next_host").run(nextHost);+ }+ return executor;+ }}return null;}@@ -743,7 +770,7 @@ export async function takeResource(options) {const { name, capacity, scope = 'machine', root = process.cwd(), allowIdleCapacityUpdate = false } = options;if (typeof name !== 'string' || !name.trim() || name.trim() !== name) throw new Refused('BAD_RESOURCE_NAME', 'resource name must be nonempty trimmed text');if (name.startsWith('runner:')) throw new Refused('RESERVED_RUNNER_RESOURCE', 'runner resource rows are managed by the machine gate; request name "gate"');- if (!Number.isSafeInteger(capacity) || capacity < 1) throw new Refused('BAD_RESOURCE_CAPACITY', 'resource capacity must be a positive integer');+ if (!Number.isSafeInteger(capacity) || capacity < (name === 'gate' && scope === 'machine' ? 0 : 1)) throw new Refused('BAD_RESOURCE_CAPACITY', 'resource capacity must be positive; only the machine gate accepts 0 with a registered runner');const landing = options.landing === true;const itemCheck = options.itemCheck === true;const shortEligible = options.shortEligible === true;@@ -755,6 +782,8 @@ export async function takeResource(options) {// This synchronous provider is used inside the admission transaction; callers must// limit it to a bounded local configuration read, never Git, process inspection or network work.const runnerProvider = options.runnerProvider;+ const runnersFirstProvider = options.runnersFirstProvider;+ if (runnersFirstProvider !== undefined && typeof runnersFirstProvider !== 'function') throw new Refused('BAD_RUNNER_POOL', 'runnersFirstProvider must return the machine runner-first setting');const item = options.item ?? '';const kind = options.kind ?? '';// withGateSlot supplies a once-captured board rank; raw resource clients may leave it unknown.@@ -817,7 +846,10 @@ export async function takeResource(options) {await retryLockedSlotDatabase(file, () => update(db, () => {const currentCapacity = options.capacityProvider?.() ?? capacity;const currentShortCapacity = options.shortCapacityProvider?.() ?? 0;- if (!Number.isSafeInteger(currentCapacity) || currentCapacity < 1) throw new Refused('BAD_RESOURCE_CAPACITY', 'resource capacity must be a positive integer');+ const configuredRunners = runnerProvider ? validatedRunners(runnerProvider()) : [];+ if (!Number.isSafeInteger(currentCapacity) || currentCapacity < (name === 'gate' && scope === 'machine' && configuredRunners.length ? 0 : 1)) {+ throw new Refused('BAD_RESOURCE_CAPACITY', `resource capacity must be positive${name === 'gate' && scope === 'machine' ? ', or 0 with a registered runner' : ''}`);+ }if (!Number.isSafeInteger(currentShortCapacity) || currentShortCapacity < 0) throw new Refused('BAD_SHORT_SLOTS', 'gate.shortSlots must be a whole number, 0 or more; run pullboard settings gate.shortSlots <n>');const row = db.prepare('SELECT capacity FROM resource WHERE name = ?').get(name);if (row && row.capacity !== currentCapacity) {@@ -831,7 +863,7 @@ export async function takeResource(options) {db.prepare('INSERT INTO resource(name, capacity) VALUES (?, ?) ON CONFLICT(name) DO NOTHING').run(name, currentCapacity);if (name === 'gate' && scope === 'machine' && browser) {const browserCapacity = options.browserCapacityProvider?.() ?? 1;- if (!Number.isSafeInteger(browserCapacity) || browserCapacity < 1 || browserCapacity > currentCapacity) {+ if (!Number.isSafeInteger(browserCapacity) || browserCapacity < (runnerProvider && validatedRunners(runnerProvider()).length ? 0 : 1) || browserCapacity > currentCapacity) {throw new Refused('BAD_BROWSER_SLOTS', `browser capacity must be a positive integer no greater than gate capacity (${currentCapacity}); run pullboard settings browserSlots <n>`);}const browserResource = db.prepare("SELECT capacity FROM resource WHERE name = 'browser'").get();@@ -866,6 +898,7 @@ export async function takeResource(options) {// after taking the same SQLite write lock used by updateRunnerSettings so an// older pre-lock snapshot cannot overwrite a newer configured capacity.const runners = runnerProvider ? validatedRunners(runnerProvider()) : [];+ const runnersFirst = runnersFirstProvider?.() === true;const waiter = db.prepare('SELECT ticket FROM waiter WHERE token = ?').get(token);if (!waiter) {if (resume && initialTicket) {@@ -885,7 +918,7 @@ export async function takeResource(options) {// A machine short of memory holds the whole line in place; recovery admits it in order.if (memory?.held) return { acquired: false, state: { ...spot, position: reportPosition, memory } };const executor = name === 'gate'- ? gateAdmission(db, waiter.ticket, limit, options.shortCapacityProvider?.() ?? 0, runners, order, now)+ ? gateAdmission(db, waiter.ticket, limit, options.shortCapacityProvider?.() ?? 0, runners, runnersFirst, order, now): (waiterPosition(db, name, waiter.ticket, { eligibleOnly: true, order, now }) === 1 && spot.holders.length < limit ? { host: '' } : null);if (executor) {const queueTicket = consumeOpportunity(db, name, waiter.ticket, order, now);@@ -1049,10 +1082,10 @@ export function holdsLease({ name, scope = 'repo', root = process.cwd(), token }}/** Raise live capacity atomically; a decrease waits for an empty queue without evicting holders. */-export function setResourceCapacity({ name, capacity, scope = 'machine', root = process.cwd(), persist = () => {} }) {+export function setResourceCapacity({ name, capacity, scope = 'machine', root = process.cwd(), allowZero = false, persist = () => {} }) {if (typeof name !== 'string' || !name.trim() || name.trim() !== name) throw new Refused('BAD_RESOURCE_NAME', 'resource name must be nonempty trimmed text');if (name.startsWith('runner:')) throw new Refused('RESERVED_RUNNER_RESOURCE', 'runner resource rows are managed by the machine gate; use runner settings');- if (!Number.isSafeInteger(capacity) || capacity < 1) throw new Refused('BAD_RESOURCE_CAPACITY', 'resource capacity must be a positive integer');+ if (!Number.isSafeInteger(capacity) || capacity < (allowZero && scope === 'machine' && ['gate', 'browser'].includes(name) ? 0 : 1)) throw new Refused('BAD_RESOURCE_CAPACITY', 'resource capacity must be a positive integer');const db = open(databaseFile(scope, root), scope === 'machine');try {return update(db, () => {diff --git a/src/settings-inventory.js b/src/settings-inventory.jsindex 8cc0ec9a..ab759a1c 100644--- a/src/settings-inventory.js+++ b/src/settings-inventory.js@@ -30,7 +30,7 @@ import { environmentProblem } from './execution-environment.js';const MACHINE_DEFAULTS = {gateSlots: 2, browserSlots: 1, 'gate.shortSlots': 0,'gate.queue.reviewsFirst': false, 'gate.queue.currentReleaseFirst': false, 'gate.queue.agingMinutes': 30,- 'gate.memoryFloorMB': null, 'gate.browserFreeChecks': false, 'gate.browserByLaunch': false,+ 'gate.memoryFloorMB': null, 'gate.browserFreeChecks': false, 'gate.browserByLaunch': false, 'gate.runnersFirst': false,'health.sentinel': true, 'view.background': true, 'relay.offerAtInit': true, runners: [], 'landing.pools': [],};const OPTIONAL_REPO_DEFAULTS = {diff --git a/src/settings.js b/src/settings.jsindex 29df44d5..a30f147c 100644--- a/src/settings.js+++ b/src/settings.js@@ -44,6 +44,9 @@ export function loadMachineSettings() {if (value.gate?.browserFreeChecks !== undefined && typeof value.gate.browserFreeChecks !== 'boolean') {throw new Refused('BAD_MACHINE_SETTINGS', `gate.browserFreeChecks in ${file} must be true or false`);}+ if (value.gate?.runnersFirst !== undefined && typeof value.gate.runnersFirst !== 'boolean') {+ throw new Refused('BAD_MACHINE_SETTINGS', `gate.runnersFirst in ${file} must be true or false`);+ }if (value.gate?.browserByLaunch !== undefined && typeof value.gate.browserByLaunch !== 'boolean') {throw new Refused('BAD_MACHINE_SETTINGS', `gate.browserByLaunch in ${file} must be true or false`);}@@ -58,18 +61,6 @@ export function loadMachineSettings() {if (value.gate?.memoryFloorMB !== undefined && (!Number.isSafeInteger(value.gate.memoryFloorMB) || value.gate.memoryFloorMB < 0)) {throw new Refused('BAD_MACHINE_SETTINGS', `gate.memoryFloorMB in ${file} must be a whole number of megabytes, 0 or more; fix it before running Pullboard`);}- const gateSlots = value.gateSlots ?? DEFAULT_GATE_SLOTS;- if (!Number.isSafeInteger(gateSlots) || gateSlots < 1) {- throw new Refused('BAD_GATE_SLOTS', `gateSlots in ${file} must be a positive integer; run pullboard settings gateSlots <n>`);- }- const browserSlots = value.browserSlots ?? DEFAULT_BROWSER_SLOTS;- if (!Number.isSafeInteger(browserSlots) || browserSlots < 1 || browserSlots > gateSlots) {- throw new Refused('BAD_BROWSER_SLOTS', `browserSlots in ${file} must be a positive integer no greater than gateSlots (${gateSlots}); run pullboard settings browserSlots <n>`);- }- const shortSlots = value.gate?.shortSlots;- if (shortSlots !== undefined && (!Number.isSafeInteger(shortSlots) || shortSlots < 0)) {- throw new Refused('BAD_SHORT_SLOTS', `gate.shortSlots in ${file} must be a whole number, 0 or more; run pullboard settings gate.shortSlots <n>`);- }const runners = value.runners ?? [];if (!Array.isArray(runners)) throw new Refused('BAD_MACHINE_SETTINGS', 'runners must be an array; use pullboard runner add <ssh-host> --slots <n> --browser <n>');const seen = new Set();@@ -78,6 +69,18 @@ export function loadMachineSettings() {if (seen.has(runner.host)) throw new Refused('BAD_MACHINE_SETTINGS', 'runner hosts must be unique; remove the duplicate machine setting');seen.add(runner.host);}+ const gateSlots = value.gateSlots ?? DEFAULT_GATE_SLOTS;+ if (!Number.isSafeInteger(gateSlots) || gateSlots < 0 || gateSlots === 0 && runners.length === 0) {+ throw new Refused('BAD_GATE_SLOTS', `gateSlots in ${file} must be positive, or 0 with a registered runner; run pullboard runner add <ssh-host> --slots <n> --browser <n>`);+ }+ const browserSlots = value.browserSlots ?? DEFAULT_BROWSER_SLOTS;+ if (!Number.isSafeInteger(browserSlots) || browserSlots < 0 || browserSlots > gateSlots || browserSlots === 0 && runners.length === 0) {+ throw new Refused('BAD_BROWSER_SLOTS', `browserSlots in ${file} must be positive and no greater than gateSlots (${gateSlots}), or 0 with a registered runner; run pullboard settings browserSlots <n>`);+ }+ const shortSlots = value.gate?.shortSlots;+ if (shortSlots !== undefined && (!Number.isSafeInteger(shortSlots) || shortSlots < 0)) {+ throw new Refused('BAD_SHORT_SLOTS', `gate.shortSlots in ${file} must be a whole number, 0 or more; run pullboard settings gate.shortSlots <n>`);+ }return { ...value, gateSlots, browserSlots, ...(runners.length ? { runners } : {}) };}@@ -86,6 +89,11 @@ export function browserFreeChecksEnabled() {return loadMachineSettings().gate?.browserFreeChecks === true;}+/** Runner-first admission is machine-wide and remains off unless explicitly enabled. */+export function gateRunnersFirstEnabled() {+ return loadMachineSettings().gate?.runnersFirst === true;+}+/*** Classifying a test file as browser-bound only when it reaches a real Chrome launch is opt-in per* machine; off, any path to the Chrome fixture or an unfollowed process starter takes a browser slot.@@ -154,10 +162,11 @@ export function setLandingPool(board, enabled) {/** Raise machine gate capacity immediately; decreases require an empty durable queue. */export function setGateSlots(capacity) {- if (!Number.isSafeInteger(capacity) || capacity < 1) throw new Refused('BAD_GATE_SLOTS', 'gateSlots must be a positive integer; run pullboard settings gateSlots <n>');+ if (!Number.isSafeInteger(capacity) || capacity < 0) throw new Refused('BAD_GATE_SLOTS', 'gateSlots must be a whole number, 0 or more; 0 requires a registered runner');let next;- setResourceCapacity({ name: 'gate', capacity, scope: 'machine', persist: () => {+ setResourceCapacity({ name: 'gate', capacity, scope: 'machine', allowZero: capacity === 0, persist: () => {const current = loadMachineSettings();+ if (capacity === 0 && !current.runners?.length) throw new Refused('BAD_GATE_SLOTS', 'gateSlots 0 requires a registered runner; run pullboard runner add <ssh-host> --slots <n> --browser <n>');if (capacity < current.browserSlots) throw new Refused('BAD_GATE_SLOTS', `gateSlots cannot be lower than browserSlots (${current.browserSlots}); first run pullboard settings browserSlots <n>`);next = { ...current, gateSlots: capacity };writeMachineSettings(next);@@ -192,10 +201,11 @@ export function setGateShortSlots(count) {/** Raise machine browser capacity immediately; decreases require an empty browser queue. */export function setBrowserSlots(capacity) {- if (!Number.isSafeInteger(capacity) || capacity < 1) throw new Refused('BAD_BROWSER_SLOTS', 'browserSlots must be a positive integer; run pullboard settings browserSlots <n>');+ if (!Number.isSafeInteger(capacity) || capacity < 0) throw new Refused('BAD_BROWSER_SLOTS', 'browserSlots must be a whole number, 0 or more; 0 requires a registered runner');let next;- setResourceCapacity({ name: 'browser', capacity, scope: 'machine', persist: () => {+ setResourceCapacity({ name: 'browser', capacity, scope: 'machine', allowZero: capacity === 0, persist: () => {const current = loadMachineSettings();+ if (capacity === 0 && !current.runners?.length) throw new Refused('BAD_BROWSER_SLOTS', 'browserSlots 0 requires a registered runner; run pullboard runner add <ssh-host> --slots <n> --browser <n>');if (capacity > current.gateSlots) throw new Refused('BAD_BROWSER_SLOTS', `browserSlots cannot exceed gateSlots (${current.gateSlots}); run pullboard settings gateSlots <n> first`);next = { ...current, browserSlots: capacity };writeMachineSettings(next);@@ -203,6 +213,19 @@ export function setBrowserSlots(capacity) {return next;}+/** Set the machine-wide runner-first gate policy while preserving other gate settings. */+export function setGateRunnersFirst(enabled) {+ if (typeof enabled !== 'boolean') throw new Refused('BAD_MACHINE_SETTINGS', 'gate.runnersFirst must be true or false; run pullboard settings gate.runnersFirst on|off');+ let next;+ const current = loadMachineSettings();+ setResourceCapacity({ name: 'gate', capacity: current.gateSlots, scope: 'machine', allowZero: current.gateSlots === 0, persist: () => {+ const latest = loadMachineSettings();+ next = { ...latest, gate: { ...latest.gate, runnersFirst: enabled } };+ writeMachineSettings(next);+ } });+ return next;+}+/** Register plain SSH capacity without storing credentials, and serialize updates with active dispatches. */export function addRunner(value) {const runner = validateRunner(value);@@ -221,13 +244,17 @@ export function addRunner(value) {export function removeRunner(host) {return updateRunnerSettings(host, () => {const current = readMachineSettingsFile(machineSettingsFile()) ?? {};- const runners = loadMachineSettings().runners ?? [];+ const currentSettings = loadMachineSettings();+ const runners = currentSettings.runners ?? [];const index = runners.findIndex(runner => runner.host === host);if (index < 0) {const registered = runners.map(runner => runner.host);throw new Refused('RUNNER_NOT_REGISTERED', `runner ${host} is not registered`,registered.length ? `registered runners: ${registered.join(', ')}` : 'run pullboard runner add <ssh-host> --slots <n> --browser <n> first');}+ if (runners.length === 1 && (currentSettings.gateSlots === 0 || currentSettings.browserSlots === 0)) {+ throw new Refused('RUNNER_REQUIRED_FOR_ZERO_CAPACITY', 'this is the last registered runner and a local gate capacity is 0; restore positive gateSlots and browserSlots before removing it');+ }const [runner] = runners.splice(index, 1);writeMachineSettings({ ...current, runners });return runner;diff --git a/test/cli-help.test.js b/test/cli-help.test.jsindex 9c83ded2..c26c69df 100644--- a/test/cli-help.test.js+++ b/test/cli-help.test.js@@ -253,11 +253,11 @@ test('help covers every dispatched subcommand [N2]', () => {test('the settings forms the CLI dispatches have help and reach their own refusal [N2]', () => {// The expected forms are written out here, not read from the parser: each one must have help, and// each must reach its own value check in settingsCommand, which proves the dispatcher knows it (#824).- assert.deepEqual([...helpDeclaration.SETTING_FORMS], ['gateSlots', 'browserSlots', 'gate.shortSlots', 'landing.pool']);+ assert.deepEqual([...helpDeclaration.SETTING_FORMS], ['gateSlots', 'browserSlots', 'gate.shortSlots', 'gate.runnersFirst', 'landing.pool']);const folder = mkdtempSync(join(tmpdir(), 'pullboard-settings-'));sandboxes.push(folder);runFixtureGit(['init', '-q'], { cwd: folder });- const refusals = { gateSlots: '[USAGE]', browserSlots: '[BAD_BROWSER_SLOTS]', 'gate.shortSlots': '[BAD_SHORT_SLOTS]', 'landing.pool': '[USAGE]' };+ const refusals = { gateSlots: '[USAGE]', browserSlots: '[BAD_BROWSER_SLOTS]', 'gate.shortSlots': '[BAD_SHORT_SLOTS]', 'gate.runnersFirst': '[BAD_MACHINE_SETTINGS]', 'landing.pool': '[USAGE]' };for (const [form, code] of Object.entries(refusals)) {const help = run('help', 'settings', form);assert.equal(help.status, 0, `help settings ${form} exits 0: ${help.stderr}`);diff --git a/test/runner-first-fixture.js b/test/runner-first-fixture.jsnew file mode 100644index 00000000..bbe574ca--- /dev/null+++ b/test/runner-first-fixture.js@@ -0,0 +1,155 @@+/** Exercise runner-first placement, zero local pools, and public submit/landing gate paths [C7]. */+import assert from 'node:assert/strict';+import { mkdirSync, readFileSync } from 'node:fs';+import { join, resolve } from 'node:path';+import { pathToFileURL } from 'node:url';+import { runFixtureChild } from './fixture-child.js';+import { HOST, installSshStandIn } from './runner-ssh-fixture.js';++/** Ask the real private machine queue for one gate lease from a fresh process. */+function runPrivateGateLease(box, behavior = '') {+ const gateUrl = pathToFileURL(resolve(import.meta.dirname, '../src/gate.js')).href;+ const runnersUrl = pathToFileURL(resolve(import.meta.dirname, '../src/runners.js')).href;+ const source = `import { withGateSlot } from ${JSON.stringify(gateUrl)};+import { RunnerDropped } from ${JSON.stringify(runnersUrl)};+const root = ${JSON.stringify(box.repo)};+let remoteAttempts = 0;+const result = await withGateSlot(root, async lease => {+ ${behavior}+ return lease.runner?.host ?? 'local';+}, { remote: true, kind: 'runner-first-cursor-test' });+process.stdout.write(result + '\\n');+`;+ return runFixtureChild(process.execPath, ['--input-type=module', '-e', source], { cwd: box.repo, env: box.env, encoding: 'utf8' });+}++/** Run the complete frozen runner-first policy scenario, including public submit and landing gate. */+export async function runnerFirstPolicyCase(e2e) {+ const box = e2e.privateCheckSubmission({ check: 'true' });+ const settingsFile = join(box.env.PULLBOARD_MACHINE_HOME, 'settings.json');+ mkdirSync(box.env.PULLBOARD_MACHINE_HOME, { recursive: true });+ const hosts = ['a51', 'a52', 'a53'];+ for (const host of hosts) {+ const added = box.run(box.repo, 'runner', 'add', host, '--slots', '1', '--browser', '1');+ assert.equal(added.code, 0, `${host} is registered: ${added.err}`);+ }+ const first = box.run(box.repo, 'settings', 'gate.runnersFirst', 'on');+ assert.equal(first.code, 0, first.err);+ const browserZero = box.run(box.repo, 'settings', 'browserSlots', '0');+ assert.equal(browserZero.code, 0, `registered runners allow browserSlots 0: ${browserZero.err}`);+ const gateZero = box.run(box.repo, 'settings', 'gateSlots', '0');+ assert.equal(gateZero.code, 0, `registered runners allow gateSlots 0: ${gateZero.err}`);+ const effective = JSON.parse(box.run(box.repo, 'settings', '--json').out).settings;+ assert.equal(effective.gate.runnersFirst, true);+ assert.equal(effective.gateSlots, 0);+ assert.equal(effective.browserSlots, 0);+ assert.deepEqual([1, 2, 3, 4, 5, 6].map(() => {+ const result = runPrivateGateLease(box);+ assert.equal(result.status, 0, result.context);+ return result.stdout.trim();+ }), ['a51', 'a52', 'a53', 'a51', 'a52', 'a53'], 'the durable cursor rotates across fresh process requests');++ const priorHome = process.env.PULLBOARD_HOME;+ const priorMachineHome = process.env.PULLBOARD_MACHINE_HOME;+ process.env.PULLBOARD_HOME = box.env.PULLBOARD_HOME;+ process.env.PULLBOARD_MACHINE_HOME = box.env.PULLBOARD_MACHINE_HOME;+ let releaseHeld;+ let heldRun;+ try {+ const { withGateSlot } = await import(pathToFileURL(resolve(import.meta.dirname, '../src/gate.js')).href);+ let announce;+ const admitted = new Promise(resolvePromise => { announce = resolvePromise; });+ heldRun = withGateSlot(box.repo, async lease => {+ announce(lease.runner?.host ?? 'local');+ await new Promise(resolvePromise => { releaseHeld = resolvePromise; });+ return lease.runner?.host ?? 'local';+ }, { remote: true, agent: 'runner-first-full-control', kind: 'runner-first-cursor-test' });+ assert.equal(await admitted, 'a51', 'the first live runner lease occupies the next runner');+ assert.deepEqual([runPrivateGateLease(box), runPrivateGateLease(box)].map(result => {+ assert.equal(result.status, 0, result.context);+ return result.stdout.trim();+ }), ['a52', 'a53'], 'the cursor advances past the occupied host before returning to it');+ const skipped = runPrivateGateLease(box);+ assert.equal(skipped.status, 0, skipped.context);+ assert.equal(skipped.stdout.trim(), 'a52', 'a full next runner is skipped');+ } finally {+ releaseHeld?.();+ if (heldRun) await heldRun;+ if (priorHome === undefined) delete process.env.PULLBOARD_HOME;+ else process.env.PULLBOARD_HOME = priorHome;+ if (priorMachineHome === undefined) delete process.env.PULLBOARD_MACHINE_HOME;+ else process.env.PULLBOARD_MACHINE_HOME = priorMachineHome;+ }++ const unreachable = runPrivateGateLease(box, `if (lease.runner?.host === 'a53') throw new RunnerDropped('a53');`);+ assert.equal(unreachable.status, 0, unreachable.context);+ assert.equal(unreachable.stdout.trim(), 'a51', 'an unreachable next runner is marked unavailable and skipped on its original queue request');++ const fallbackCapacity = box.run(box.repo, 'settings', 'gateSlots', '1');+ assert.equal(fallbackCapacity.code, 0, fallbackCapacity.err);+ const fallbackBrowser = box.run(box.repo, 'settings', 'browserSlots', '1');+ assert.equal(fallbackBrowser.code, 0, fallbackBrowser.err);+ const fallback = runPrivateGateLease(box, `if (lease.runner && remoteAttempts++ < 2) throw new RunnerDropped(lease.runner.host);`);+ assert.equal(fallback.status, 0, fallback.context);+ assert.equal(fallback.stdout.trim(), 'local', 'after registered runners refuse, runner-first uses the available local slot');++ const noRunner = e2e.privateCheckSubmission({ check: 'true' });+ const refusedGate = noRunner.run(noRunner.repo, 'settings', 'gateSlots', '0');+ assert.notEqual(refusedGate.code, 0);+ assert.match(refusedGate.err, /BAD_GATE_SLOTS/u);+ assert.match(refusedGate.err, /registered runner/u);+ const refusedBrowser = noRunner.run(noRunner.repo, 'settings', 'browserSlots', '0');+ assert.notEqual(refusedBrowser.code, 0);+ assert.match(refusedBrowser.err, /BAD_BROWSER_SLOTS/u);+ assert.match(refusedBrowser.err, /registered runner/u);+ assert.ok(readFileSync(settingsFile, 'utf8').includes('runnersFirst'), 'the opted-in policy is persisted only in the private fixture');++ // Public submit and landing-gate entry exercise the real worker transport. This does not claim+ // the coordinator-only `pullboard land` orchestration itself ran here.+ const integrated = e2e.project('true');+ const runner = HOST;+ const runnerBin = join(integrated.dir, 'submit-land-bin');+ const worker = join(integrated.dir, 'submit-land-worker');+ const remoteHome = join(integrated.dir, 'submit-land-home');+ const remoteMachineHome = join(remoteHome, '.pullboard');+ const requests = join(integrated.dir, 'submit-land-ssh-requests.jsonl');+ for (const folder of [runnerBin, worker, remoteHome, remoteMachineHome]) mkdirSync(folder, { recursive: true });+ integrated.env.PATH = `${runnerBin}:${integrated.env.PATH}`;+ installSshStandIn({ bin: runnerBin, worker, home: remoteHome, machineHome: remoteMachineHome, requests });+ const registered = integrated.run(integrated.repo, 'runner', 'add', runner, '--slots', '1', '--browser', '1');+ assert.equal(registered.code, 0, registered.err);+ for (const [key, value] of [['gate.runnersFirst', 'on'], ['browserSlots', '0'], ['gateSlots', '0']]) {+ const setting = integrated.run(integrated.repo, 'settings', key, value);+ assert.equal(setting.code, 0, `${key} ${value}: ${setting.err}`);+ }+ const added = integrated.run(integrated.repo, 'add', 'web', 'Runner-first public submit', '--specs', 'G1',+ '--criterion', 'the runner executes the submitted gate', '--check', 'true', '--json');+ assert.equal(added.code, 0, added.err);+ const id = JSON.parse(added.out).item.item_id;+ assert.equal(integrated.run(integrated.web, 'claim', String(id)).code, 0);+ const built = e2e.commitFile(integrated, integrated.web, 'web/runner-first.txt', 'submitted on runner\n', 'feat(web): add runner-first fixture [G1]');+ assert.equal(built.status, 0, built.stderr);+ const submittedCommit = integrated.git(integrated.web, 'rev-parse', 'HEAD');+ const submitted = integrated.run(integrated.web, 'submit', String(id), '--json');+ assert.equal(submitted.code, 0, `${submitted.out}\n${submitted.err}`);+ const submittedDocument = JSON.parse(submitted.out);+ const submitGateProfile = JSON.parse(readFileSync(submittedDocument.gate.check.profilePath, 'utf8'));+ const submitProofProfile = JSON.parse(readFileSync(submittedDocument.gate.proofProfilePath, 'utf8'));+ assert.equal(submitGateProfile.executionRunner, runner, 'public submit executes on the registered runner');+ assert.equal(submitGateProfile.executionSource?.commit, submittedCommit, 'the worker receipt binds the submitted check');+ assert.equal(submitGateProfile.receipt?.runner?.id, runner, 'the submit check records the actual runner admission receipt');+ assert.equal(submitProofProfile.executionSource?.commit, submittedCommit, 'the worker receipt binds the submitted proof');+ assert.equal(submitProofProfile.receipt?.runner?.id, runner, 'the submit proof records the actual runner admission receipt');++ const landingGate = integrated.run(integrated.repo, 'gate', '--landing', '--json');+ assert.equal(landingGate.code, 0, `${landingGate.out}\n${landingGate.err}`);+ const landingProfile = JSON.parse(readFileSync(join(integrated.repo, '.git', 'pullboard-gate.log.profile.json'), 'utf8'));+ assert.equal(landingProfile.executionRunner, runner, 'the public landing gate uses the registered runner');+ assert.equal(landingProfile.executionSource?.commit, integrated.git(integrated.repo, 'rev-parse', 'HEAD'),+ 'the landing-gate worker receipt binds the exact main source it checked');+ assert.equal(landingProfile.receipt?.runner?.id, runner, 'the landing gate records the actual runner admission receipt');+ const requestsMade = readFileSync(requests, 'utf8').trim().split(/\r?\n/u).filter(Boolean).map(line => JSON.parse(line));+ assert.equal(requestsMade.length, 3, 'the two submit stages and landing gate each make one actual SSH worker request');+ assert.deepEqual(requestsMade.map(entry => entry.host), [runner, runner, runner]);+ assert.ok(requestsMade.every(entry => entry.workerStarted && !entry.remoteHasSecret), 'every request executes the worker and keeps fixture secrets local');+}diff --git a/test/runners.test.js b/test/runners.test.jsindex 00b9f784..01849e96 100644--- a/test/runners.test.js+++ b/test/runners.test.js@@ -26,6 +26,7 @@ import { runnerSourceRefusalCases } from './runner-source-refusal-fixture.js';import { writeCacheProbe, writeProbe } from './runner-probe-fixture.js';import { browserFreeRunnerCheck, browserRefusalTextStaysRed } from './runner-browser-free-fixture.js';import { runnerTimingReceipt, runnerUsesRegisteredCapacity } from './runner-capacity-fixture.js';+import { runnerFirstPolicyCase } from './runner-first-fixture.js';import { removingBusyRunnerDrains, runnerRemoveKeepsSettings } from './runner-drain-fixture.js';import { awaitRoundTrip, cleanupToolingSnapshots, cli, committedToolingSnapshot, fixtureResultContext, gateResult, git, phaseCounts, ROUND_TRIP_DEADLINES, runThroughGate, startToolingCli, TOOLING_SNAPSHOTS } from './runner-tooling-fixture.js';import { runnerStageFixture } from './runner-stage-fixture.js';@@ -1292,6 +1293,9 @@ syncBuiltinESMExports();\n`);}});+test('a machine with runners can run no tests itself [C7]', { timeout: 90_000 }, // budget: covers fixture setup plus three real runner transports and cleanup; not an execution-time target.+ () => runnerFirstPolicyCase(e2e));+const parentDeathTools = { cli, git, installSshStandIn, observe, startQueueController, waitForMarker, processIsAlive, shellQuote, HOST };test('a queued run executes on a registered runner and its result comes back [C7] (parent death drains a detached worker descendant before releasing its lease)',{ timeout: 90_000 }, t => parentDeathDrainFixture(t, parentDeathTools)); // budget: fixture ceiling covers declared30-second remote cleanup plus startup, transport and final cleanup.diff --git a/test/settings-api-fixture.js b/test/settings-api-fixture.jsindex 39dd9b73..b6e7e3e4 100644--- a/test/settings-api-fixture.js+++ b/test/settings-api-fixture.js@@ -55,7 +55,7 @@ export async function proveSettingsApi() {const canary = ['fixture', 'credential', 'never-return-this'].join('-');const config = { ...defaults(), verify: { ...defaults().verify, composeAtAdmission: true }, gate: 'node --test', health: { sentinel: false }, testConcurrency: { files: 3, browser: 1 }, claim: { reopenFirstRefusalMinutes: 30 }, lanes: { app: { owns: ['app/'], specs: ['O5'], ignoredSecret: canary } } };writeFileSync(join(repo, 'pullboard.json'), JSON.stringify(config));- writeFileSync(join(home, 'settings.json'), JSON.stringify({ gateSlots: 3, browserSlots: 2, gate: { queue: { reviewsFirst: true }, shortSlots: 1 }, relay: { offerAtInit: false }, unknown: { token: canary } }));+ writeFileSync(join(home, 'settings.json'), JSON.stringify({ gateSlots: 3, browserSlots: 2, gate: { queue: { reviewsFirst: true }, shortSlots: 1, runnersFirst: true }, relay: { offerAtInit: false }, unknown: { token: canary } }));mkdirSync(join(home, 'relay-machine'));writeFileSync(join(home, 'relay-machine', 'state.json'), JSON.stringify({ v: 1, autoLink: true, session: { token: canary, account: 'fixture', url: 'https://relay.example.invalid' }, approvals: [{ sealed: canary }], devices: [], excluded: [] }));writeFileSync(join(privateDir, 'relay.json'), JSON.stringify({ version: 1, board: id, url: 'https://relay.example.invalid', token: canary, agentTokens: { fixture: { token: canary } }, snapshot: canary }));@@ -107,6 +107,8 @@ export async function proveSettingsApi() {assert.equal(find('machine', 'gateSlots').default, 2);assert.equal(find('machine', 'gateSlots').source, join(home, 'settings.json'));assert.equal(find('machine', 'gate.queue.reviewsFirst').value, true);+ assert.equal(find('machine', 'gate.runnersFirst').value, true);+ assert.equal(find('machine', 'gate.runnersFirst').default, false);assert.equal(find('machine', 'gate.queue.agingMinutes').value, 30);assert.equal(find('machine', 'resources.custom.capacity').value, 4);assert.equal(find('repo', 'claim.reopenFirstRefusalMinutes').value, 30);