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(runners): measure capacity and isolate timing work [C7,Q1,O5]
Corey Olson1c7b279395f3
diff --git a/src/commands/stats.js b/src/commands/stats.jsindex 8cbf976b..b90a5959 100644--- a/src/commands/stats.js+++ b/src/commands/stats.js@@ -5,6 +5,7 @@ import {import * as store from '../board.js';import { caughtLines } from '../caught.js';import * as gateReceipt from '../gate-receipt.js';+import { readRunnerStage } from '../runner-stage-read.js';import {flowLines,flowStats,@@ -39,7 +40,10 @@ export function run(io, { values }) {try {const stats = proofStats(board, { since: values.since, now });return { stats, agents: store.listAgents(board), ...(windowMinutes === undefined ? {} : {- window: flowStats(store.events(board), null, now, stats, { windowMinutes }).window,+ window: flowStats(store.events(board), null, now, stats, { windowMinutes,+ executionCapacity: readRunnerStage(ctx.info.root, {+ from: new Date(now - windowMinutes * 60_000).toISOString(), to: new Date(now).toISOString(),+ }) }).window,}) };} finally {if (windowMinutes !== undefined) board.db.exec('RELEASE stats_window_read');@@ -55,6 +59,12 @@ export function run(io, { values }) {for (const line of barStatsLines(stats.bars)) io.say(line);for (const line of caughtLines(stats.caught)) io.say(line);for (const line of window ? flowWindowLines(window) : flowLines(stats.flow)) io.say(line);+ if (window?.executionCapacity) {+ const waits = window.executionCapacity.slotWait;+ /** Keep absent window timing visibly unmeasured in the human-readable summary. */+ const formatWait = value => value === null ? 'unmeasured' : `${(value / 1000).toFixed(2)}s`;+ io.say(`runner slot waits: fast ${formatWait(waits.fastQuarterMs)} · median ${formatWait(waits.medianMs)} · slow ${formatWait(waits.slowQuarterMs)} · worst ${formatWait(waits.worstMs)} (${waits.count} measured)`);+ }for (const line of waits.lines) io.say(line);return 0;}diff --git a/src/gate-receipt.js b/src/gate-receipt.jsindex 9a85fa64..b52c362b 100644--- a/src/gate-receipt.js+++ b/src/gate-receipt.js@@ -93,6 +93,34 @@ export function recentReceipts(root, now = Date.now()) {});}+/** Read receipts relevant to a requested half-open window without the display's last-day limit. */+export function retainedReceipts(root, { from, to }) {+ const start = Date.parse(from);+ const end = Date.parse(to);+ if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) return [];+ const file = receiptLog(root);+ if (!existsSync(file)) return [];+ return readFileSync(file, 'utf8').split('\n').flatMap((line) => {+ if (!line.trim()) return [];+ try {+ const receipt = JSON.parse(line);+ const at = Date.parse(receipt?.at);+ const admitted = Date.parse(receipt?.admittedAt);+ const finished = Date.parse(receipt?.finishedAt);+ const relevant = Number.isFinite(at) && at >= start && at < end+ || Number.isFinite(admitted) && Number.isFinite(finished) && finished > start && admitted < end;+ if (!relevant) return Number.isFinite(at) || Number.isFinite(admitted) || Number.isFinite(finished)+ ? [] : [{ at: from, malformed: true }];+ if (!Number.isFinite(receipt.waitMs) || receipt.waitMs < 0+ || !Number.isFinite(receipt.runMs) || receipt.runMs < 0) {+ // Keep the row so runnerStage marks legacy/incomplete evidence unmeasured.+ return [receipt];+ }+ return [receipt];+ } catch { return [{ at: from, malformed: true }]; }+ });+}+/** The middle value of a list of durations. */function median(values) {const sorted = [...values].sort((left, right) => left - right);diff --git a/src/gate.js b/src/gate.jsindex 1665d6d2..2d6bb36e 100644--- a/src/gate.js+++ b/src/gate.js@@ -90,6 +90,8 @@ import {timingRunner,} from './timing.js';import { landingShardProfile } from './landing-shards.js';+import { localRunnerDescriptor } from './runner-load.js';+import { sampleRunnerLoad } from './runner-load.js';import { receiptLine } from './gate-receipt.js';import { receiptOf } from './gate-receipt.js';import { recordReceipt } from './gate-receipt.js';@@ -350,7 +352,7 @@ export function runProfiledShell(root, command, { waitMs = 0, artifactDirectory,browser: gateLease.browser, pipefail, stages, waivers: landing ? waivers : [], metadata: { ...(gateLease.runMetadata ?? {}), landing, ...(timeoutMs ? { timeoutMs } : {}) } }) }: runShell(root, command, { pipefail, env: inherited, stages, timeoutMs });gateLease?.tracker?.mark('ranAt');- if (gateLease) gateLease.environment = run.environment ?? null;+ if (gateLease) { gateLease.environment = run.environment ?? null; gateLease.executionAdmission = run.executionAdmission ?? null; }const sandboxBlocked = run.isGreen ? null : run.sandboxBlocked ?? (run.executionRunner// The controller cannot realpath remote files; retain the network denial signal without treating remote paths as local paths.? sandboxBlockedOperation(root, run.output, { includeFilePaths: false })@@ -377,6 +379,7 @@ export async function runProfiledShellAsync(root, command, { waitMs = 0, gateSloconst run = await runOnRunnerAsync(root, command, { runner: gateLease.runner, source: gateLease.source,browser: gateLease.browser, metadata: { ...(gateLease.runMetadata ?? {}), landing } });gateLease.environment = run.environment ?? null;+ gateLease.executionAdmission = run.executionAdmission ?? null;gateLease.tracker?.mark('ranAt');const wallMs = Math.max(0, Date.now() - started);const profilePath = join(dirname(gitPath(root, LOG)), `pullboard-gate-${randomUUID()}.profile.json`);@@ -422,7 +425,19 @@ export async function runProfiledShellAsync(root, command, { waitMs = 0, gateSlo/** Close a gated run's receipt (#836) as its evidence is written; the slot's release records this same receipt. */function settleReceipt(lease) {if (!lease?.tracker) return undefined;- lease.receipt = { ...receiptOf(lease.tracker, { kind: lease.receiptKind, slot: lease.slot }), environment: lease.environment ?? null };+ const executor = lease.executionAdmission;+ const local = !lease.runner;+ const descriptor = local ? lease.localDescriptor ?? localRunnerDescriptor(lease.capacity ?? null, null)+ : { id: lease.runner.host, kind: 'ssh', slots: { current: executor?.slots ?? lease.runner.slots, limit: executor?.slots ?? lease.runner.slots, elastic: false },+ capabilities: { os: lease.environment?.platform ?? null, browser: lease.runner.browser > 0 } };+ const admittedAt = local ? lease.admittedAt ?? new Date(lease.tracker.marks.admittedAt ?? lease.tracker.marks.requestedAt).toISOString() : executor?.admittedAt ?? null;+ const finishedAt = local ? new Date().toISOString() : executor?.finishedAt ?? null;+ const load = local ? { start: lease.startLoad ?? sampleRunnerLoad(), end: sampleRunnerLoad() } : executor?.load ?? null;+ lease.receipt = { ...receiptOf(lease.tracker, { kind: lease.receiptKind, slot: lease.slot }), environment: lease.environment ?? null,+ runner: descriptor, admittedAt, finishedAt, timing: lease.timing === true, inherited: lease.inherited === true,+ occupiedSlots: lease.timing ? descriptor.slots.current : 1, load,+ ...(local ? lease.timingEvidence?.() ?? { exclusive: false, unfencedClients: [] }+ : { exclusive: executor?.exclusive === true, unfencedClients: executor?.unfencedClients ?? [] }) };return lease.receipt;}@@ -530,7 +545,7 @@ function hasPipeline(command) {* hold (gate.memoryFloorMB) holds short slots too, since a short run uses the same machine memory.** @param {(lease: { waitMs: number, token?: string, pool?: string, browser?: boolean, slotClass?: 'gate'|'short', release: () => void }) => any | Promise<any>} action - Work to perform while holding a slot.- * @param {{ landing?: boolean, itemCheck?: boolean, shortEligible?: boolean, diagnostic?: boolean, browser?: boolean, remote?: boolean, agent?: string, item?: string|number, kind?: string, onWait?: (state: object) => void, onReceipt?: (receipt: object) => void, readMemory?: typeof readMachineMemory }} [options] - Queue class, short-slot eligibility, remote eligibility, progress reporter, the run's receipt once its slot is released (#836) and, for tests, the machine memory reader.+ * @param {{ landing?: boolean, itemCheck?: boolean, shortEligible?: boolean, diagnostic?: boolean, browser?: boolean, remote?: boolean, timing?: boolean, agent?: string, item?: string|number, kind?: string, onWait?: (state: object) => void, onReceipt?: (receipt: object) => void, readMemory?: typeof readMachineMemory }} [options] - Queue class, short-slot eligibility, remote eligibility, progress reporter, the run's receipt once its slot is released (#836) and, for tests, the machine memory reader.* @returns {Promise<any>} The action's result after releasing its lease.*/export async function withGateSlot(root, action, options = {}) {@@ -553,21 +568,27 @@ export async function withLandingGateSlot(root, action, options = {}) {}/** One gate admission and its action; withGateSlot may call it again for a local rerun. */-async function withOneGateSlot(root, action, { landing = false, itemCheck = false, shortEligible = false, diagnostic = false, browser = false, remote = true, agent, item = '', kind = '', onWait, onReceipt, readMemory = readMachineMemory } = {}) {+async function withOneGateSlot(root, action, { landing = false, itemCheck = false, shortEligible = false, diagnostic = false, browser = false, remote = true, timing = false, agent, item = '', kind = '', onWait, onReceipt, readMemory = readMachineMemory } = {}) {const tracker = startReceipt();const receiptKind = kind || (landing ? 'landing' : 'gate');/** Hand the run its receipt tracker and slot, then record its receipt once the slot is released (#836). */- const timed = lease => Object.assign(lease, { tracker, receiptKind, slot: slotOf(lease, { browserFree: browserFreeChecksEnabled() }) });+ const timed = lease => Object.assign(lease, { tracker, receiptKind,+ ...(!lease.runner ? { startLoad: lease.startLoad ?? sampleRunnerLoad(),+ localDescriptor: localRunnerDescriptor(lease.capacity ?? null, loadMachineSettings().browserSlots > 0) } : {}),+ slot: slotOf(lease, { browserFree: browserFreeChecksEnabled() }) });const record = lease => {const receipt = lease.receipt ?? receiptOf(tracker, { kind: receiptKind, slot: lease.slot });recordReceipt(root, receipt);onReceipt?.(receipt);};- const inherited = inheritedGateSlot({ root, browser, namedFiles: shortEligible });+ const inherited = inheritedGateSlot({ root, browser, namedFiles: shortEligible, timing });if (inherited) {timed(Object.assign(inherited, { inherited: true })).tracker.mark('actionAt');try { return await action(inherited); }- finally { inherited.release(); record(inherited); }+ finally {+ try { settleReceipt(inherited); } finally { inherited.release(); }+ record(inherited);+ }}const settingsProvider = () => loadMachineSettings();const floorMB = memoryFloorMB();@@ -594,6 +615,7 @@ async function withOneGateSlot(root, action, { landing = false, itemCheck = falsitemCheck,diagnostic,browser,+ timing,allowIdleCapacityUpdate: true,remote: remote && Boolean(source),runnerProvider: () => loadMachineSettings().runners ?? [],@@ -605,7 +627,7 @@ async function withOneGateSlot(root, action, { landing = false, itemCheck = falstry {while (true) {lease.source = source;- lease.runMetadata = { landing, itemCheck, diagnostic, item: String(item), kind };+ lease.runMetadata = { landing, itemCheck, diagnostic, timing, item: String(item), kind };timed(lease).tracker.mark('actionAt');try { return await action(lease); }catch (error) {@@ -619,7 +641,7 @@ async function withOneGateSlot(root, action, { landing = false, itemCheck = fals}}} finally {- lease.release();+ try { settleReceipt(lease); } finally { lease.release(); }record(lease);}}diff --git a/src/next-steps.js b/src/next-steps.jsindex aef61082..0e6a84ba 100644--- a/src/next-steps.js+++ b/src/next-steps.js@@ -305,6 +305,7 @@ export const NEXT_STEPS = Object.freeze({RELAY_CONFIG: 'ask the relay operator to repair the named service setting and restart; retain the local board and pending upload',RELAY_PAGE_CACHE: 'close other local Pullboard commands, then restore the private relay-pages cache permissions or remove only that device cache and retry; keep the board, relay link and key',INFRA_NOTE_REQUIRED: 'run pullboard submit <id> --infra "<why>" with the reason the edit to an existing test or gate file is needed',+ TIMING_SLOT_REQUIRED: 'start the timing check outside its inherited ordinary lease and acquire the machine gate with timing true',SHORT_SLOT_FULL_SUITE: 'run the whole suite outside the short check, where it queues for an ordinary gate slot; short slots are only for runs that name their test files',GIT_GRAFTS: 'ask the coordinator to remove the git graft file: pullboard shout coordinator "please remove .git/info/grafts"',HEAD_NOT_NEW: 'commit the rework, then pullboard submit <id>',diff --git a/src/resources.js b/src/resources.jsindex 33a38370..d8ebd365 100644--- a/src/resources.js+++ b/src/resources.js@@ -129,6 +129,8 @@ function openQueue(file) {CREATE INDEX IF NOT EXISTS waiter_name_ticket ON waiter(name, ticket);`);for (const table of ['holder', 'waiter']) {const columns = db.prepare(`PRAGMA table_info(${table})`).all().map(({ name }) => name);+ if (!columns.includes('timing_aware')) db.exec(`ALTER TABLE ${table} ADD COLUMN timing_aware INTEGER NOT NULL DEFAULT 0`);+ if (!columns.includes('timing')) db.exec(`ALTER TABLE ${table} ADD COLUMN timing INTEGER NOT NULL DEFAULT 0`);if (!columns.includes('started')) db.exec(`ALTER TABLE ${table} ADD COLUMN started TEXT NOT NULL DEFAULT ''`);if (!columns.includes('landing')) db.exec(`ALTER TABLE ${table} ADD COLUMN landing INTEGER NOT NULL DEFAULT 0`);if (!columns.includes('item_check')) db.exec(`ALTER TABLE ${table} ADD COLUMN item_check INTEGER NOT NULL DEFAULT 0`);@@ -142,6 +144,22 @@ function openQueue(file) {if (table === 'waiter' && !columns.includes('remote')) db.exec('ALTER TABLE waiter ADD COLUMN remote INTEGER NOT NULL DEFAULT 0');if (table === 'waiter' && !columns.includes('short_eligible')) db.exec('ALTER TABLE waiter ADD COLUMN short_eligible INTEGER NOT NULL DEFAULT 0');}+ // Older clients insert the default zero. A database trigger witnesses even short legacy+ // arrivals between the timing owner's polls; no old client has to understand the new flag.+ db.exec(`CREATE TABLE IF NOT EXISTS timing_client_observation (+ id INTEGER PRIMARY KEY AUTOINCREMENT, agent TEXT NOT NULL, pid INTEGER NOT NULL, started TEXT NOT NULL);+ CREATE TRIGGER IF NOT EXISTS timing_unaware_holder AFTER INSERT ON holder+ WHEN NEW.name = 'gate' AND NEW.timing_aware = 0 BEGIN+ INSERT INTO timing_client_observation(agent,pid,started) VALUES (NEW.agent,NEW.pid,NEW.started);+ END;+ CREATE TRIGGER IF NOT EXISTS timing_unaware_waiter AFTER INSERT ON waiter+ WHEN NEW.name = 'gate' AND NEW.timing_aware = 0 BEGIN+ INSERT INTO timing_client_observation(agent,pid,started) VALUES (NEW.agent,NEW.pid,NEW.started);+ END;`);+ // No live timing admission can need observations once its holder and waiter rows are gone.+ db.exec(`DELETE FROM timing_client_observation+ WHERE NOT EXISTS (SELECT 1 FROM holder WHERE timing = 1)+ AND NOT EXISTS (SELECT 1 FROM waiter WHERE timing = 1)`);// Marks a waiter whose process admits by class; an older pullboard leaves it 0.if (!db.prepare('PRAGMA table_info(waiter)').all().some(({ name }) => name === 'classed')) {db.exec('ALTER TABLE waiter ADD COLUMN classed INTEGER NOT NULL DEFAULT 0');@@ -324,18 +342,18 @@ function queueOrder(scope) {/** Read the complete resource line with the metadata every admission view orders identically. */function queuedWaiters(db, name) {- return db.prepare('SELECT ticket, pid, agent, repo, since, landing, item_check AS itemCheck, diagnostic, browser, remote, item, kind, lease_until AS leaseUntil, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible AS shortEligible FROM waiter WHERE name = ?').all(name);+ return db.prepare('SELECT ticket, pid, agent, repo, since, landing, item_check AS itemCheck, diagnostic, browser, remote, item, kind, lease_until AS leaseUntil, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible AS shortEligible, timing FROM waiter WHERE name = ?').all(name);}/** Current holders and the waiting line in admission order, each waiter naming its class (aged only while class order is on). */function snapshot(db, name, order = ARRIVAL_ORDER, now = Date.now()) {/** Preserve older public entries while naming diagnostics as a distinct queue class. */- const project = ({ diagnostic, browser, remote, runner, item, kind, leaseUntil, shortSlot, shortEligible, ...entry }) => ({ ...entry, landing: entry.landing === 1,+ const project = ({ diagnostic, browser, remote, runner, item, kind, leaseUntil, shortSlot, shortEligible, timing, ...entry }) => ({ ...entry, landing: entry.landing === 1,itemCheck: entry.itemCheck === 1 && diagnostic !== 1, ...(diagnostic === 1 ? { diagnostic: true } : {}),...(['gate', 'browser'].includes(name) && shortSlot === 1 ? { slot: 'short' } : {}),...(['gate', 'browser'].includes(name) && shortSlot === 0 ? { slot: 'gate' } : {}),...(['gate', 'browser'].includes(name) && shortEligible === 1 ? { requestedSlot: 'short-eligible' } : {}),- ...(browser === 1 ? { browser: true } : {}), ...(remote === 1 ? { remote: true } : {}),+ ...(timing === 1 ? { timing: true } : {}), ...(browser === 1 ? { browser: true } : {}), ...(remote === 1 ? { remote: true } : {}),...(runner ? { runner } : {}), ...(item ? { item } : {}), ...(kind ? { kind } : {}), ...(leaseUntil ? { leaseUntil } : {}) });// Browser is an additional capability on a gate lease, not a second partially held row.const where = name === 'browser' ? 'name = ? AND browser = 1' : 'name = ?';@@ -343,7 +361,7 @@ function snapshot(db, name, order = ARRIVAL_ORDER, now = Date.now()) {const runnerHost = name.startsWith('runner:') ? name.slice('runner:'.length) : '';const holderWhere = runnerHost ? 'name = ?' : where;const holderValues = [sourceName];- const holders = db.prepare(`SELECT agent, repo, since, landing, item_check AS itemCheck, diagnostic, browser, runner, item, kind, lease_until AS leaseUntil, short_slot AS shortSlot FROM holder WHERE ${holderWhere} ORDER BY since, token`).all(...holderValues).map(project);+ const holders = db.prepare(`SELECT agent, repo, since, landing, item_check AS itemCheck, diagnostic, browser, runner, item, kind, lease_until AS leaseUntil, short_slot AS shortSlot, timing FROM holder WHERE ${holderWhere} ORDER BY since, token`).all(...holderValues).map(project);const queued = queuedWaiters(db, sourceName);const ageMs = order.reviewsFirst ? order.ageMs : Infinity;const line = orderedWaiters(queued, now, order)@@ -439,7 +457,7 @@ function validatedRunners(value) {*/function gateAdmission(db, ticket, capacity, shortCapacity, runners, 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 FROM holder WHERE name = 'gate'").all();+ 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;const localShortUsed = holders.filter(holder => holder.shortSlot === 1).length;const localBrowsers = holders.filter(holder => holder.browser === 1).length;@@ -447,9 +465,10 @@ function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARRconst usage = new Map(runners.map(runner => {// The reserved namespace is authoritative even for an older generic holder that// predates the name guard and has no runner column value.- const remoteHolders = db.prepare('SELECT browser FROM holder WHERE name = ?').all(runnerResourceName(runner.host));+ const remoteHolders = db.prepare('SELECT browser, timing FROM holder WHERE name = ?').all(runnerResourceName(runner.host));return [runner.host, {slots: remoteHolders.length,+ timing: remoteHolders.some(holder => holder.timing === 1),browsers: remoteHolders.filter(holder => holder.browser === 1).length,}];}));@@ -460,14 +479,16 @@ 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 (localUsed < capacity && (waiter.browser !== 1 || localBrowsers < browserCapacity)) {+ 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 => {if (unavailable.has(runner.host) || (waiter.browser === 1 && runner.browser < 1)) return false;const used = usage.get(runner.host);- return used.slots < runner.slots && (waiter.browser !== 1 || used.browsers < runner.browser);+ return !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.@@ -475,7 +496,8 @@ function gateAdmission(db, ticket, capacity, shortCapacity, runners, order = ARRif (compatible.length) return { ...compatible[0], shortSlot: false };}const earlierLanding = waiters.some(other => other.landing === 1 && other.ticket < waiter.ticket);- if (waiter.shortEligible === 1 && !earlierLanding && localShortUsed < shortCapacity+ if (waiter.timing !== 1 && !holders.some(holder => holder.timing === 1)+ && waiter.shortEligible === 1 && !earlierLanding && localShortUsed < shortCapacity&& (waiter.browser !== 1 || localBrowsers < browserCapacity)) {return { host: '', slots: shortCapacity, browser: waiter.browser === 1 ? 1 : 0, shortSlot: true };}@@ -509,7 +531,7 @@ export function runnerResourceStatus(runners) {visible.set(row.host, { ...JSON.parse(row.runner), draining: true });}return [...visible.values()].flatMap(runner => {- const holders = db.prepare('SELECT agent, repo, since, browser, item, kind, runner FROM holder WHERE name = ? ORDER BY since, token')+ const holders = db.prepare('SELECT agent, repo, since, browser, item, kind, runner, timing FROM holder WHERE name = ? ORDER BY since, token').all(runnerResourceName(runner.host));if (runner.draining && !holders.length) return [];const unavailable = db.prepare('SELECT since, detail FROM runner_unavailable WHERE host = ?').get(runner.host);@@ -694,7 +716,7 @@ function pause(ms) { return new Promise((resolvePromise) => setTimeout(resolvePr/*** Join the queue in its admission class (landing, review, submit, other), aging up over time; FIFO by ticket within a class.*- * @param {{ name: string, capacity: number, capacityProvider?: () => number, shortCapacityProvider?: () => number, browserCapacityProvider?: () => number, scope?: 'machine'|'repo'|'board', root?: string, agent?: string, repo?: string, landing?: boolean, itemCheck?: boolean, shortEligible?: boolean, diagnostic?: boolean, browser?: boolean, remote?: boolean, runnerProvider?: () => Array<{host:string,slots:number,browser:number}>, item?: string, kind?: string, onWait?: (state: object) => any | Promise<any>, allowIdleCapacityUpdate?: boolean, memory?: () => Promise<{ checked: boolean, held: boolean, line: string, warning?: string }>, _resume?: object }} options - Resource identity, queue class, short-slot eligibility, optional remote executor pool and memory check. An awaited wait callback may return {leaseUntil} and then receives a final {admitted:true} callback before work starts.+ * @param {{ name: string, capacity: number, capacityProvider?: () => number, shortCapacityProvider?: () => number, browserCapacityProvider?: () => number, scope?: 'machine'|'repo'|'board', root?: string, agent?: string, repo?: string, landing?: boolean, itemCheck?: boolean, shortEligible?: boolean, diagnostic?: boolean, browser?: boolean, remote?: boolean, timing?: boolean, runnerProvider?: () => Array<{host:string,slots:number,browser:number}>, item?: string, kind?: string, onWait?: (state: object) => any | Promise<any>, allowIdleCapacityUpdate?: boolean, memory?: () => Promise<{ checked: boolean, held: boolean, line: string, warning?: string }>, _resume?: object }} options - Resource identity, queue class, short-slot eligibility, optional remote executor pool and memory check. An awaited wait callback may return {leaseUntil} and then receives a final {admitted:true} callback before work starts.* memory, when given, is read before each admission: a held verdict keeps the whole queue* waiting in place, local, remote and short slots alike, and an unchecked one is passed to onWait once* so the caller can warn.@@ -708,6 +730,7 @@ export async function takeResource(options) {const landing = options.landing === true;const itemCheck = options.itemCheck === true;const shortEligible = options.shortEligible === true;+ const timing = options.timing === true;const diagnostic = options.diagnostic === true;const browser = options.browser === true;const remote = options.remote === true;@@ -719,6 +742,8 @@ export async function takeResource(options) {// withGateSlot supplies a once-captured board rank; raw resource clients may leave it unknown.const boardKey = typeof options.releaseContext?.board === 'string' ? options.releaseContext.board : '';const releaseRank = Number.isSafeInteger(options.releaseContext?.rank) && options.releaseContext.rank >= 0 ? options.releaseContext.rank : Number.MAX_SAFE_INTEGER;+ if (timing && (name !== 'gate' || scope !== 'machine')) throw new Refused('BAD_RESOURCE_METADATA', 'timing admission requires the machine gate; request name gate with scope machine and timing true');+ if (options.timing !== undefined && typeof options.timing !== 'boolean') throw new Refused('BAD_RESOURCE_METADATA', 'timing must be an explicit boolean');if (browser && name !== 'gate') throw new Refused('BAD_BROWSER_RESOURCE', 'browser capacity can only be acquired together with the machine gate; request name "gate" with browser: true');if ((remote || runnerProvider !== undefined) && name !== 'gate') throw new Refused('BAD_REMOTE_RESOURCE', 'remote executors can only be acquired together with the machine gate');if (runnerProvider !== undefined && typeof runnerProvider !== 'function') throw new Refused('BAD_RUNNER_POOL', 'runnerProvider must be a function returning configured runners');@@ -733,6 +758,18 @@ export async function takeResource(options) {let pool;try { pool = canonicalResourceFile(file); }catch (error) { db.close(); throw error; }+ const awarenessCursor = db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM timing_client_observation').get().id;+ const unfenced = new Map();+ /** Preserve every observed unfenced client throughout this admission and execution. */+ const timingEvidence = () => {+ if (!timing) return { exclusive: false, unfencedClients: [] };+ const observations = db.prepare(`SELECT agent,pid,started FROM timing_client_observation WHERE id > ?+ UNION SELECT agent,pid,started FROM holder WHERE name = 'gate' AND timing_aware = 0+ UNION SELECT agent,pid,started FROM waiter WHERE name = 'gate' AND timing_aware = 0`).all(awarenessCursor);+ for (const client of observations) unfenced.set(`${client.pid}:${client.started}:${client.agent}`, { ...client });+ return { exclusive: unfenced.size === 0, unfencedClients: [...unfenced.values()] };+ };+ timingEvidence();const resume = options._resume;const token = resume?.token ?? randomUUID();const requestedAt = resume?.requestedAt ?? Date.now();@@ -792,7 +829,7 @@ export async function takeResource(options) {if (!resume) {// Remote eligibility is metadata on this same ticket; the kind and flags decide the// admission class, and the ticket keeps arrival order within it.- const inserted = db.prepare('INSERT INTO waiter(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(queueOrder(scope)), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible));+ const inserted = db.prepare('INSERT INTO waiter(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible, timing, timing_aware) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(queueOrder(scope)), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible), Number(timing), 1);initialTicket = Number(inserted.lastInsertRowid);}}));@@ -814,11 +851,11 @@ export async function takeResource(options) {const waiter = db.prepare('SELECT ticket FROM waiter WHERE token = ?').get(token);if (!waiter) {if (resume && initialTicket) {- db.prepare('INSERT OR IGNORE INTO waiter(ticket, token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(initialTicket, token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(order), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible));+ db.prepare('INSERT OR IGNORE INTO waiter(ticket, token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible, timing, timing_aware) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(initialTicket, token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(order), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible), Number(timing), 1);return { acquired: false, state: { ...snapshot(db, name, order), position: waiterPosition(db, name, initialTicket, { order, shortCapacity: options.shortCapacityProvider?.() ?? 0 }), rejoined: true } };}queuedAt = new Date().toISOString();- const rejoined = db.prepare('INSERT INTO waiter(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(order), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible));+ const rejoined = db.prepare('INSERT INTO waiter(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible, timing, timing_aware) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote), classedMarker(order), 1, boardKey, releaseRank, resume?.queueTicket ?? null, Number(shortEligible), Number(timing), 1);initialTicket = Number(rejoined.lastInsertRowid);return { acquired: false, state: { ...snapshot(db, name, order), position: waiterPosition(db, name, initialTicket, { order, shortCapacity: options.shortCapacityProvider?.() ?? 0 }), rejoined: true } };}@@ -837,8 +874,8 @@ export async function takeResource(options) {db.prepare('DELETE FROM waiter WHERE token = ?').run(token);const acquiredAt = new Date().toISOString();const holderName = executor.host ? runnerResourceName(executor.host) : name;- db.prepare('INSERT INTO holder(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, runner, short_slot) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, holderName, pid, started, agent, repo, acquiredAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, executor.host, Number(executor.shortSlot === true));- return { acquired: true, state: { ...spot, position: 0 }, ticket: waiter.ticket, queueTicket, runner: executor.host ? executor : undefined, shortSlot: executor.shortSlot === true };+ db.prepare('INSERT INTO holder(token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, runner, short_slot, timing, timing_aware) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(token, holderName, pid, started, agent, repo, acquiredAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, executor.host, Number(executor.shortSlot === true), Number(timing), 1);+ return { acquired: true, state: { ...spot, position: 0 }, ticket: waiter.ticket, queueTicket, runner: executor.host ? executor : undefined, shortSlot: executor.shortSlot === true, capacity: limit, admittedAt: acquiredAt };}return { acquired: false, state: { ...spot, position: reportPosition } };}));@@ -921,8 +958,8 @@ export async function takeResource(options) {requeueOpportunity = requeueTicket;}db.prepare('DELETE FROM holder WHERE token = ?').run(token);- db.prepare('INSERT INTO waiter(ticket, token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')- .run(requeueTicket, token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote && !local), marker, 1, boardKey, releaseRank, requeueOpportunity, Number(shortEligible));+ db.prepare('INSERT INTO waiter(ticket, token, name, pid, started, agent, repo, since, heartbeat, landing, item_check, diagnostic, browser, item, kind, remote, classed, release_aware, board_key, release_rank, queue_ticket, short_eligible, timing, timing_aware) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')+ .run(requeueTicket, token, name, pid, started, agent, repo, queuedAt, Date.now(), Number(landing), Number(itemCheck || diagnostic), Number(diagnostic), Number(browser), item, kind, Number(remote && !local), marker, 1, boardKey, releaseRank, requeueOpportunity, Number(shortEligible), Number(timing), 1);});} catch (error) {transferred = false;@@ -933,8 +970,8 @@ export async function takeResource(options) {return takeResource({ ...options, ...(local ? { remote: false } : {}), _resume: { token, ticket: requeueTicket ?? acquired.ticket, queueTicket: requeueOpportunity,queuedAt, requestedAt, priorWaitMs: acquiredWaitMs, waitStartedAt: Date.now() } });};- return { name, scope, token, pool, browser, slotClass: acquired.shortSlot ? 'short' : 'gate', ...(acquired.runner ? { runner: acquired.runner } : {}),- waitMs: acquiredWaitMs, release, renew,+ return { name, scope, token, pool, browser, timing, admittedAt: acquired.admittedAt, capacity: acquired.capacity, slotClass: acquired.shortSlot ? 'short' : 'gate', ...(acquired.runner ? { runner: acquired.runner } : {}),+ waitMs: acquiredWaitMs, release, renew, timingEvidence,...(acquired.runner ? { requeueRunner } : {}) };}await keepItemLease(acquired.state, 'waiter');@@ -951,7 +988,7 @@ export async function takeResource(options) {* The live holder row says whether the lease is a short slot; only a run that names its test files* (namedFiles) may reuse one, so a whole suite started under a short check queues for a real slot.*/-export function inheritedGateSlot({ root = process.cwd(), browser = false, namedFiles = false } = {}) {+export function inheritedGateSlot({ root = process.cwd(), browser = false, namedFiles = false, timing = false } = {}) {// Taken by the first guard in this process, so nothing it starts (a test body) can write the receipt.const refusalFile = process.env[BROWSER_REFUSAL_FILE_ENV] ?? '';delete process.env[BROWSER_REFUSAL_FILE_ENV];@@ -967,9 +1004,10 @@ export function inheritedGateSlot({ root = process.cwd(), browser = false, namedconst db = open(pool, true);let holder;try {- holder = update(db, () => db.prepare("SELECT browser, short_slot AS shortSlot FROM holder WHERE name = 'gate' AND token = ?").get(token));+ holder = update(db, () => db.prepare("SELECT browser, short_slot AS shortSlot, timing, timing_aware AS timingAware FROM holder WHERE name = 'gate' AND token = ?").get(token));} finally { db.close(); }if (!holder) throw new Refused('GATE_SLOT_LEASE_LOST', 'the inherited gate lease is missing or expired; remove stale gate markers or let the parent reacquire the gate slot');+ if (timing && (holder.timing !== 1 || holder.timingAware !== 1)) throw new Refused('TIMING_SLOT_REQUIRED', 'the inherited ordinary lease is not exclusive; start the timing check outside it and acquire timing true');const slotClass = holder.shortSlot === 1 ? 'short' : 'gate';if (slotClass === 'short' && !namedFiles) throw new Refused('SHORT_SLOT_FULL_SUITE', 'a run that does not name its test files cannot reuse a short gate slot; start it outside the short check so it queues for an ordinary slot');const expectedBrowserMarker = holder.browser === 1 ? '1' : '';@@ -977,7 +1015,7 @@ export function inheritedGateSlot({ root = process.cwd(), browser = false, namedif (browser && holder.browser !== 1 && refusalFile) writeFileSync(refusalFile, '{"code":"BROWSER_SLOT_REQUIRED"}\n', { mode: 0o600 });if (browser && holder.browser !== 1) throw new Refused('BROWSER_SLOT_REQUIRED', 'the inherited gate lease does not hold the browser slot; release it and reacquire gate with browser: true before launching Chrome');return {- name: 'gate', scope: 'machine', token, pool, browser: holder.browser === 1, slotClass, waitMs: 0,+ name: 'gate', scope: 'machine', token, pool, browser: holder.browser === 1, timing: holder.timing === 1, slotClass, waitMs: 0,release() {}, renew() {},};}diff --git a/src/runner-load.js b/src/runner-load.jsnew file mode 100644index 00000000..c4a83d4d--- /dev/null+++ b/src/runner-load.js@@ -0,0 +1,17 @@+/** Actual executor samples shared by local gate and registered worker receipts [C7]. */+import { availableParallelism } from 'node:os';+import { freemem } from 'node:os';+import { hostname } from 'node:os';+import { loadavg } from 'node:os';+import { platform } from 'node:os';++/** Sample this executing machine now, never the controller on behalf of a remote run. */+export function sampleRunnerLoad() {+ return { at: new Date().toISOString(), average: loadavg(), cpus: availableParallelism(), freeMB: Math.floor(freemem() / 1048576) };+}++/** Describe actual local admission capacity; unreported capabilities stay unknown. */+export function localRunnerDescriptor(slots, browser) {+ return { id: `local:${hostname()}`, kind: 'local', slots: { current: slots, limit: slots, elastic: false },+ capabilities: { os: platform(), browser } };+}diff --git a/src/runner-stage-read.js b/src/runner-stage-read.jsnew file mode 100644index 00000000..c103ec80--- /dev/null+++ b/src/runner-stage-read.js@@ -0,0 +1,54 @@+/** Read a privacy-safe runner capacity snapshot for one explicit stats window [C7,O5]. */+import { retainedReceipts } from './gate-receipt.js';+import { localRunnerDescriptor } from './runner-load.js';+import {+ listResources,+ runnerResourceStatus,+} from './resources.js';+import { loadMachineSettings } from './settings.js';+import { runnerStage } from './runner-stage.js';++const PLATFORMS = new Set(['aix', 'android', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos', 'win32']);++/** Return a platform only when an actual structured executor receipt reports a recognized OS. */+function reportedPlatform(receipts, id) {+ return receipts.filter(receipt => receipt.runner?.id === id)+ .sort((left, right) => Date.parse(right.finishedAt) - Date.parse(left.finishedAt))+ .map(receipt => receipt.runner?.capabilities?.os)+ .find(platform => typeof platform === 'string' && PLATFORMS.has(platform)) ?? null;+}++/** Build current descriptors from validated settings and the live admission databases. */+function currentRunners(settings, receipts) {+ const machineResources = listResources({ scope: 'machine' });+ const gate = machineResources.find(resource => resource.name === 'gate');+ const browserPool = machineResources.find(resource => resource.name === 'browser');+ const localCapacity = gate?.capacity ?? settings.gateSlots;+ const browserCapacity = browserPool?.capacity ?? settings.browserSlots;+ const local = localRunnerDescriptor(localCapacity, browserCapacity > 0);+ const gateHolders = gate?.holders ?? [];+ local.active = gateHolders.some(holder => holder.timing) ? localCapacity+ : gateHolders.filter(holder => holder.slot !== 'short').length;+ local.browserSlots = browserCapacity;+ local.browserActive = gateHolders.filter(holder => holder.browser).length;+ const remotes = runnerResourceStatus(settings.runners ?? []).map(runner => ({+ id: runner.host,+ kind: runner.kind ?? 'ssh',+ slots: { current: runner.slots, limit: runner.slots, elastic: false },+ capabilities: { os: reportedPlatform(receipts, runner.host), browser: runner.browser > 0 },+ active: runner.holders.some(holder => holder.timing === 1) ? runner.slots : runner.inUse,+ browserSlots: runner.browser,+ browserActive: runner.browserInUse,+ ...(runner.unavailable ? { unavailable: true } : {}),+ ...(runner.draining ? { draining: true } : {}),+ }));+ return [local, ...remotes];+}++/** Read retained physical-run receipts and live capacity for exactly `[from,to)`. */+export function readRunnerStage(root, { from, to }) {+ const receipts = retainedReceipts(root, { from, to });+ const settings = loadMachineSettings();+ const runners = currentRunners(settings, receipts);+ return runnerStage(runners, receipts, { from, to });+}diff --git a/src/runner-stage.js b/src/runner-stage.jsnew file mode 100644index 00000000..81251c3a--- /dev/null+++ b/src/runner-stage.js@@ -0,0 +1,265 @@+/** Windowed runner capacity observations and an advisory placement plan [C7,O5]. */+import { Refused } from './refused.js';++const KINDS = new Set(['local', 'ssh', 'ci', 'elastic']);+const INVALID_NEXT = 'return runner rows with unique IDs, nonnegative current slots within limit, and reported capabilities';++/** Refuse malformed runner-stage input with a safe correction path. */+function invalid(message) {+ throw new Refused('BAD_RUNNER_POOL', message, INVALID_NEXT);+}++/** Return whether a value is a plain record-shaped input. */+function record(value) {+ return value !== null && typeof value === 'object' && !Array.isArray(value);+}++/** Validate a count that must be an exact nonnegative safe integer. */+function nonnegativeInteger(value) {+ return Number.isSafeInteger(value) && value >= 0;+}++/** Validate and copy the public runner descriptor, including optional runtime unavailability. */+function normalizedRunner(value, { stage = false } = {}) {+ if (!record(value) || typeof value.id !== 'string' || !value.id.trim() || !KINDS.has(value.kind)+ || !record(value.slots) || !nonnegativeInteger(value.slots.current) || !nonnegativeInteger(value.slots.limit)+ || value.slots.current > value.slots.limit || typeof value.slots.elastic !== 'boolean'+ || !record(value.capabilities)) {+ invalid('runner rows need an ID, supported kind, valid slot bounds and a capabilities object');+ }+ const os = value.capabilities.os ?? null;+ const browser = value.capabilities.browser ?? null;+ if (!(typeof os === 'string' && os.trim() || os === null)+ || !(typeof browser === 'boolean' || browser === null)) {+ invalid('runner OS and browser capability must be reported values or null when unknown');+ }+ for (const key of ['unavailable', 'draining']) {+ if (value[key] !== undefined && typeof value[key] !== 'boolean') invalid(`runner ${key} state must be true or false`);+ }+ if (value.browserSlots !== undefined && (!nonnegativeInteger(value.browserSlots) || value.browserSlots > value.slots.current+ || !nonnegativeInteger(value.browserActive) || value.browserActive > value.browserSlots)) {+ invalid('runner browser slots must be within current capacity and browser use must fit those slots');+ }+ if (value.browserSlots === undefined && value.browserActive !== undefined) invalid('runner browser use requires a reported browser-slot capacity');+ if (!nonnegativeInteger(value.active) || value.active > value.slots.current) {+ invalid('runner active slots must be a nonnegative count no greater than current capacity');+ }+ if (stage && (!(value.busyShare === null || Number.isFinite(value.busyShare) && value.busyShare >= 0 && value.busyShare <= 1)+ || !(value.runsServed === null || nonnegativeInteger(value.runsServed)))) {+ invalid('runner stage rows need a bounded busy share or null, and a served count or null');+ }+ const normalized = {+ id: value.id,+ kind: value.kind,+ slots: { current: value.slots.current, limit: value.slots.limit, elastic: value.slots.elastic },+ capabilities: { os, browser },+ };+ normalized.active = value.active;+ if (value.browserSlots !== undefined) Object.assign(normalized, { browserSlots: value.browserSlots, browserActive: value.browserActive });+ if (value.unavailable === true || value.draining === true) {+ normalized.unavailable = value.unavailable === true;+ normalized.draining = value.draining === true;+ }+ if (stage) Object.assign(normalized, { busyShare: value.busyShare, runsServed: value.runsServed });+ return normalized;+}++/** Validate one recorded peer that a timing receipt says was not fenced out. */+function validUnfencedClient(client) {+ return typeof client === 'string' && Boolean(client.trim())+ || record(client) && typeof client.agent === 'string' && Boolean(client.agent.trim())+ && Number.isSafeInteger(client.pid) && client.pid > 0 && timestamp(client.started) !== null;+}++/** Parse an ISO timestamp without treating invalid input as a boundary. */+function timestamp(value) {+ if (typeof value !== 'string') return null;+ const at = Date.parse(value);+ return Number.isFinite(at) ? at : null;+}++/** Select the nearest-rank quartile from an already sorted numeric array. */+function quartile(sorted, fraction) {+ if (!sorted.length) return null;+ return sorted[Math.max(0, Math.ceil(sorted.length * fraction) - 1)];+}++/** Return the arithmetic median of a sorted numeric array. */+function median(sorted) {+ if (!sorted.length) return null;+ const middle = Math.floor(sorted.length / 2);+ return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;+}++/**+ * Summarize known runner executions over a half-open time window. Old, partial or capacity-mismatched receipts+ * remain unmeasured instead of being converted into an idle share.+ * @param {object[]} runners Current registered runner descriptors.+ * @param {object[]} receipts Retained execution receipts.+ * @param {{from:string,to:string}} window The measured interval, `[from,to)`.+ */+export function runnerStage(runners, receipts, window = {}) {+ if (!Array.isArray(runners) || !Array.isArray(receipts) || !record(window)) invalid('runner, receipt and window inputs must be valid objects or arrays');+ const { from, to } = window;+ const start = timestamp(from);+ const end = timestamp(to);+ if (start === null || end === null || end <= start) invalid('the runner stage window needs valid increasing timestamps');++ const descriptors = runners.map(runner => normalizedRunner(runner));+ const byId = new Map();+ for (const runner of descriptors) {+ if (byId.has(runner.id)) invalid('runner IDs must be unique');+ byId.set(runner.id, { runner, slotMs: 0, unknownShare: runner.slots.current === 0,+ unknownRuns: false, runsServed: 0 });+ }+ const waits = [];+ for (const receipt of receipts) {+ if (!record(receipt) || receipt.inherited === true || receipt.slot?.kind === 'inherited') continue;+ const legacyAt = timestamp(receipt.at);+ const legacyIntervalRelevant = timestamp(receipt.admittedAt) !== null && timestamp(receipt.finishedAt) !== null+ && timestamp(receipt.finishedAt) > start && timestamp(receipt.admittedAt) < end;+ const legacyInWindow = (legacyAt !== null && legacyAt >= start && legacyAt < end || legacyIntervalRelevant)+ && (!receipt.runner || !record(receipt.runner) || typeof receipt.runner.id !== 'string'+ || legacyAt !== null && legacyAt >= start && legacyAt < end+ && (timestamp(receipt.admittedAt) === null || timestamp(receipt.finishedAt) === null));+ if (legacyInWindow) {+ for (const entry of byId.values()) {+ entry.unknownShare = true;+ entry.unknownRuns = true;+ }+ }+ const finished = timestamp(receipt.finishedAt);+ const completion = finished ?? (legacyInWindow ? legacyAt : null);+ if (completion !== null && completion >= start && completion < end+ && Number.isFinite(receipt.waitMs) && receipt.waitMs >= 0) waits.push(receipt.waitMs);+ if (!record(receipt.runner) || typeof receipt.runner.id !== 'string') continue;+ const entry = byId.get(receipt.runner.id);+ if (!entry) continue;++ const admitted = timestamp(receipt.admittedAt);+ if (finished !== null && finished >= start && finished < end) {+ entry.runsServed += 1;+ }+ if ((finished !== null && finished < start) || (admitted !== null && admitted >= end)) continue;+ // A matching receipt without both boundaries could overlap the window, so its share is unknown.+ if (admitted === null || finished === null || finished < admitted) {+ entry.unknownShare = true;+ entry.unknownRuns = true;+ continue;+ }+ const overlap = Math.min(finished, end) - Math.max(admitted, start);+ if (overlap <= 0) continue;++ const receiptSlots = record(receipt.runner.slots) ? receipt.runner.slots.current : null;+ if (!nonnegativeInteger(receiptSlots) || receiptSlots !== entry.runner.slots.current+ || receipt.timing !== undefined && typeof receipt.timing !== 'boolean') {+ entry.unknownShare = true;+ continue;+ }+ if (receipt.occupiedSlots !== undefined && (!Number.isSafeInteger(receipt.occupiedSlots)+ || receipt.occupiedSlots < 1 || receipt.occupiedSlots > receiptSlots)) {+ entry.unknownShare = true;+ continue;+ }+ if (receipt.exclusive !== undefined && typeof receipt.exclusive !== 'boolean'+ || receipt.unfencedClients !== undefined && (!Array.isArray(receipt.unfencedClients)+ || receipt.unfencedClients.some(client => !validUnfencedClient(client)))) {+ entry.unknownShare = true;+ continue;+ }+ if (receipt.timing === true && (receipt.exclusive === false || receipt.unfencedClients?.length)) {+ entry.unknownShare = true;+ continue;+ }+ const occupied = receipt.timing === true ? receiptSlots : receipt.occupiedSlots ?? 1;+ entry.slotMs += overlap * occupied;+ }++ const staged = descriptors.map(runner => {+ const entry = byId.get(runner.id);+ const capacityMs = (end - start) * runner.slots.current;+ const busyShare = entry.unknownShare || capacityMs === 0 || entry.slotMs > capacityMs+ ? null : entry.slotMs / capacityMs;+ return { ...runner, busyShare, runsServed: entry.unknownRuns ? null : entry.runsServed };+ });+ waits.sort((left, right) => left - right);+ return { runners: staged,+ slotWait: { fastQuarterMs: quartile(waits, 0.25), medianMs: median(waits),+ slowQuarterMs: quartile(waits, 0.75), worstMs: waits.length ? waits.at(-1) : null, count: waits.length } };+}++/** Compare requested capabilities; false browser means no browser requirement. */+function capabilityMatch(runner, requested) {+ let unknown = false;+ for (const key of ['os', 'browser']) {+ if (requested[key] === undefined || requested[key] === null) continue;+ if (key === 'browser' && requested[key] === false) continue;+ const actual = runner.capabilities[key];+ if (actual === null) unknown = true;+ else if (actual !== requested[key]) return 'no';+ }+ return unknown ? 'unknown' : 'yes';+}++/** Prefer known-compatible, fixed and less-busy available candidates deterministically. */+function candidateOrder(left, right) {+ return Number(left.match !== 'yes') - Number(right.match !== 'yes')+ || Number(left.runner.slots.elastic) - Number(right.runner.slots.elastic)+ || Number(left.runner.busyShare === null) - Number(right.runner.busyShare === null)+ || (left.runner.busyShare ?? Infinity) - (right.runner.busyShare ?? Infinity)+ || left.runner.id.localeCompare(right.runner.id);+}++/**+ * Return a read-only placement suggestion. It never changes runner capacity or starts a run.+ * @param {{runners:object[],slotWait:object}} stage A value returned by {@link runnerStage}.+ * @param {{capabilities?:{os?:string|null,browser?:boolean|null},slotWaitTargetMs?:number}} request+ */+export function placeRunner(stage, request = {}) {+ if (!record(request)) invalid('runner placement request must be an object');+ const { capabilities = {}, slotWaitTargetMs = 0 } = request;+ if (!record(stage) || !Array.isArray(stage.runners) || !record(stage.slotWait)+ || !(stage.slotWait.medianMs === null || Number.isFinite(stage.slotWait.medianMs) && stage.slotWait.medianMs >= 0)) {+ invalid('runner placement needs a runner stage with a measured or unknown median wait');+ }+ if (!record(capabilities) || !(capabilities.os === undefined || capabilities.os === null+ || typeof capabilities.os === 'string' && capabilities.os.trim())+ || !(capabilities.browser === undefined || capabilities.browser === null || typeof capabilities.browser === 'boolean')+ || !Number.isFinite(slotWaitTargetMs) || slotWaitTargetMs < 0) {+ invalid('placement capabilities must be reported values or null and the wait target nonnegative');+ }++ const rows = stage.runners.map(runner => normalizedRunner(runner, { stage: true }));+ if (new Set(rows.map(runner => runner.id)).size !== rows.length) invalid('runner IDs must be unique');+ const candidates = rows.map(runner => ({ runner, match: capabilityMatch(runner, capabilities) }))+ .filter(candidate => candidate.match !== 'no');+ const available = candidates.filter(({ runner }) => {+ if (runner.unavailable || runner.draining || runner.active >= runner.slots.current) return false;+ if (capabilities.browser !== true) return true;+ if (runner.browserSlots !== undefined) return runner.browserActive < runner.browserSlots;+ return runner.active === 0;+ }).sort(candidateOrder);+ if (available.length) {+ const best = available[0];+ if (best.match === 'yes') return { action: 'run', runnerId: best.runner.id };+ return { action: 'wait' };+ }+ if (!candidates.length) return { action: 'incompatible' };++ const fixed = candidates.filter(({ runner }) => !runner.slots.elastic && !runner.unavailable && !runner.draining);+ const elastic = candidates.filter(({ runner, match }) => runner.slots.elastic && match === 'yes' && !runner.unavailable && !runner.draining);+ const fixedBusy = fixed.length > 0 && fixed.every(({ runner }) => runner.active >= runner.slots.current);+ const highWait = stage.slotWait.medianMs !== null && stage.slotWait.medianMs > slotWaitTargetMs;+ if (fixedBusy && highWait) {+ const expandable = elastic.filter(({ runner }) => runner.slots.current < runner.slots.limit)+ .sort(candidateOrder)[0];+ if (expandable) return { action: 'scale', runnerId: expandable.runner.id, slots: 1 };+ const possibleElastic = candidates.filter(({ runner, match }) => runner.slots.elastic && match === 'yes'+ && !runner.unavailable && !runner.draining);+ if (elastic.length && possibleElastic.length+ && possibleElastic.every(({ runner }) => runner.slots.current >= runner.slots.limit)) {+ return { action: 'request' };+ }+ }+ return { action: 'wait' };+}diff --git a/src/runner-worker.js b/src/runner-worker.jsindex de922387..c07740fd 100644--- a/src/runner-worker.js+++ b/src/runner-worker.js@@ -21,6 +21,7 @@ import {} from 'node:fs';import { availableParallelism } from 'node:os';import { executionEnvironment } from './execution-environment.js';+import { sampleRunnerLoad } from './runner-load.js';import { freemem } from 'node:os';import { loadavg } from 'node:os';import { userInfo } from 'node:os';@@ -169,6 +170,7 @@ async function readSpec() {|| typeof value.pipefail !== 'boolean' || !Number.isSafeInteger(value.slots) || value.slots < 1|| !Number.isSafeInteger(value.browser) || value.browser < 0|| typeof value.browserRequired !== 'boolean'+ || (value.timing !== undefined && typeof value.timing !== 'boolean')|| (value.browserByLaunch !== undefined && typeof value.browserByLaunch !== 'boolean')|| !value.runtime || typeof value.runtime !== 'object' || !value.runtime.files || typeof value.runtime.files !== 'object'|| typeof value.runtime.sha256 !== 'string') throw new Error('invalid work specification');@@ -200,7 +202,7 @@ async function readSpec() {tagNames.add(tag.name);if (tag.chain.length ? tag.chain[0] !== tag.object : tag.object !== tag.peeledCommit) throw new Error('invalid tag manifest');}- const runtimeNames = ['runner-custody.js', 'resources.js', 'git.js', 'machine-home.js', 'refused.js', 'process-census.js', 'queue-settings.js', 'queue-order.js', 'sandbox-denial.js', 'gate-stages.js', 'child-journal-preload.js', 'execution-environment.js'];+ const runtimeNames = ['runner-custody.js', 'resources.js', 'git.js', 'machine-home.js', 'refused.js', 'process-census.js', 'queue-settings.js', 'queue-order.js', 'sandbox-denial.js', 'gate-stages.js', 'child-journal-preload.js', 'execution-environment.js', 'runner-load.js'];if (Object.keys(value.runtime.files).length !== runtimeNames.length|| runtimeNames.some(name => typeof value.runtime.files[name] !== 'string')) throw new Error('invalid work specification');if (createHash('sha256').update(JSON.stringify(value.runtime.files)).digest('hex') !== value.runtime.sha256) throw new Error('invalid trusted runtime');@@ -746,7 +748,7 @@ async function runCommand(spec, root, env, sink, tracker) {async function receipt(spec, fields, sink) {await flushStdout();const body = { id: spec.id, commit: spec.commit, tree: spec.tree, code: fields.code, signal: fields.signal,- environment: executionEnvironment(),+ environment: executionEnvironment(), timing: spec.timing === true, executionAdmission: fields.executionAdmission ?? null,runtimeSha256: spec.runtime.sha256, toolingSha256: spec.tooling.sha256, root: fields.root ?? '', outputSha256: sink.hash.digest('hex'), wallMs: Math.max(0, Date.now() - sink.wallStart),// The execution host's load and the pinned main this run used, so a paired rerun here can be judged (#925).main: typeof spec.main === 'string' ? spec.main : null, load: { average: loadavg(), cpus: availableParallelism(), freeMB: Math.floor(freemem() / 1048576) },@@ -832,11 +834,13 @@ async function main() {name: 'gate', capacity: gateCapacity, scope: 'machine', root: runnerRoot,repo: runnerRoot, agent: `pullboard-ssh-${spec.id}`,landing: spec.landing === true, itemCheck: spec.itemCheck === true,- diagnostic: spec.diagnostic === true, browser: spec.browserRequired,+ diagnostic: spec.diagnostic === true, browser: spec.browserRequired, timing: spec.timing === true,browserCapacityProvider: () => browserCapacity,item: spec.item ?? '', kind: spec.kind ?? 'remote-command',onWait: () => assertTransportLive(),}, machineHomePath);+ const startLoad = sampleRunnerLoad();+ lease.executionAdmission = { admittedAt: lease.admittedAt, slots: gateCapacity, load: { start: startLoad, end: null } };const canonicalMachineHome = machineHomePath;tracker = createDescendantTracker(runDirectory, {tick: reportCleanupTimeout, timedOut: () => cleanupTimedOut,@@ -872,7 +876,12 @@ async function main() {}if (lease) {cleanupStage = 'lease release';- await releaseDrainedLease(lease);+ try {+ if (lease.executionAdmission) {+ const endLoad = sampleRunnerLoad();+ final.executionAdmission = { ...lease.executionAdmission, ...lease.timingEvidence(), finishedAt: endLoad.at, load: { ...lease.executionAdmission.load, end: endLoad } };+ }+ } finally { await releaseDrainedLease(lease); }}cleanupStage = 'job files';if (runDirectory && !cleanupTimedOut) { try { rmSync(runDirectory, { recursive: true, force: true }); } catch {} }diff --git a/src/runners.js b/src/runners.jsindex 728c526a..8cb3cd26 100644--- a/src/runners.js+++ b/src/runners.js@@ -1,4 +1,5 @@/** Exact committed source and bounded, credential-free SSH execution for machine runners [C7]. */+export { placeRunner, runnerStage } from './runner-stage.js';import {spawn,spawnSync,@@ -68,7 +69,7 @@ const MAX_BLOB_BYTES = 8 * 1024 ** 2;const MAX_HISTORY_TAGS = 1_024;const MAX_TAG_CHAIN = 8;const TOOL_ROOT = fileURLToPath(new URL('../', import.meta.url));-const RUNTIME_NAMES = ['runner-custody.js', 'resources.js', 'git.js', 'machine-home.js', 'refused.js', 'process-census.js', 'queue-settings.js', 'queue-order.js', 'sandbox-denial.js', 'gate-stages.js', 'child-journal-preload.js', 'execution-environment.js'];+const RUNTIME_NAMES = ['runner-custody.js', 'resources.js', 'git.js', 'machine-home.js', 'refused.js', 'process-census.js', 'queue-settings.js', 'queue-order.js', 'sandbox-denial.js', 'gate-stages.js', 'child-journal-preload.js', 'execution-environment.js', 'runner-load.js'];/** Validate an SSH destination as one argument, never a command or an SSH option. */export function validateRunner(value) {@@ -495,7 +496,7 @@ function requestFor(root, command, { runner, source, browser = false, byLaunch,// The classification this controller used, so the runner never reclassifies by its own settings (#1043).browserByLaunch: byLaunch ?? carriedBrowserByLaunch() ?? readMachineSettingsFile()?.gate?.browserByLaunch === true,...(stages ? { stageMarker: `PULLBOARD_STAGE_${randomUUID().replaceAll('-', '')}` } : {}), waivers: projection,- itemCheck: metadata.itemCheck === true, diagnostic: metadata.diagnostic === true,+ itemCheck: metadata.itemCheck === true, diagnostic: metadata.diagnostic === true, timing: metadata.timing === true,item: String(metadata.item ?? ''), kind: String(metadata.kind ?? ''), ...(runner.root ? { root: runner.root } : {}),...(typeof metadata.main === 'string' && /^[0-9a-f]{40,64}$/u.test(metadata.main) ? { main: metadata.main } : {}) };const encodedSpec = Buffer.from(JSON.stringify(spec));@@ -553,6 +554,8 @@ function resultFrom(request, result) {const text = staged?.output ?? output.toString('utf8');if (receipt.environment !== undefined && environmentProblem(receipt.environment)) throw new RunnerDropped(request.runner.host);if (receipt.browserRefused !== undefined && (receipt.browserRefused !== true || receipt.code === 0 || request.spec.browserRequired)) throw new RunnerDropped(request.runner.host);+ const admission = remoteAdmission(receipt.executionAdmission);+ if (request.spec.timing === true && (receipt.timing !== true || !admission)) throw new RunnerDropped(request.runner.host);// Only the lease guard's own receipt counts; text a test prints is never a refusal (#1043).if (receipt.browserRefused === true) {const refused = new Refused('RUNNER_BROWSER_SLOT_REQUIRED', `runner ${request.runner.host} refused this run's lease for want of a browser slot (BROWSER_SLOT_REQUIRED)`);@@ -565,7 +568,27 @@ function resultFrom(request, result) {seconds: Math.round(receipt.wallMs / 1000), exitCode: receipt.code,executionRunner: request.runner.host, executionRoot: receipt.root, remoteWallMs: receipt.wallMs,executionSource: { commit: receipt.commit, tree: receipt.tree, tooling: request.spec.tooling },- executionMain: request.spec.main && receipt.main === request.spec.main ? receipt.main : null, executionLoad: remoteLoad(receipt.load) };+ executionMain: request.spec.main && receipt.main === request.spec.main ? receipt.main : null, executionLoad: remoteLoad(receipt.load), executionAdmission: admission };+}++/** Validate executor-sampled admission intervals and both load timestamps before trusting timing isolation. */+function remoteAdmission(value) {+ if (!value || !Number.isSafeInteger(value.slots) || value.slots < 1) return null;+ const admitted = Date.parse(value.admittedAt);+ const finished = Date.parse(value.finishedAt);+ const startAt = Date.parse(value.load?.start?.at);+ const endAt = Date.parse(value.load?.end?.at);+ const start = remoteLoad(value.load?.start);+ const end = remoteLoad(value.load?.end);+ if (![admitted, finished, startAt, endAt].every(Number.isFinite) || finished < admitted+ || startAt < admitted || endAt < startAt || finished !== endAt || !start || !end) return null;+ if (typeof value.exclusive !== 'boolean' || !Array.isArray(value.unfencedClients)+ || value.unfencedClients.some(client => !client || typeof client.agent !== 'string'+ || !Number.isSafeInteger(client.pid) || client.pid < 1 || typeof client.started !== 'string')+ || value.exclusive && value.unfencedClients.length > 0) return null;+ return { slots: value.slots, admittedAt: value.admittedAt, finishedAt: value.finishedAt,+ exclusive: value.exclusive, unfencedClients: value.unfencedClients,+ load: { start: { at: value.load.start.at, ...start }, end: { at: value.load.end.at, ...end } } };}/** The execution host's load from a receipt, or null when any part of it is missing or malformed (#925). */diff --git a/src/stats-flow.js b/src/stats-flow.jsindex 6103062c..c98baf15 100644--- a/src/stats-flow.js+++ b/src/stats-flow.js@@ -208,7 +208,7 @@ export function prepareFlowHistory(history, { window = false } = {}) {}/** Project current queues and time windows from compiled facts without mutating the cached snapshot. */-export function projectFlowStats(prepared, boundary, now, counts, { windowMinutes } = {}) {+export function projectFlowStats(prepared, boundary, now, counts, { windowMinutes, executionCapacity } = {}) {const selected = at => !boundary || at >= Date.parse(boundary);const daily = new Map();for (const event of prepared.dailyEvents) {@@ -248,7 +248,11 @@ export function projectFlowStats(prepared, boundary, now, counts, { windowMinute} : { stage: null, share: null, completedItems, fullyMeasuredCycles: 0, totalCycleMinutes: 0, lowConfidence: completedItems > 0,message: completedItems ? `not enough measured flow to name a bottleneck (${completedItems} items completed since ${boundary ?? 'the beginning'}, none with every stage measured)` :`not enough flow to name a bottleneck (0 items completed since ${boundary ?? 'the beginning'})`, recommendation: null };- return { ...(windowMinutes === undefined ? {} : { window: projectFlowWindow(prepared, windowMinutes, now) }), asOf: new Date(now).toISOString(), stages, queues: queueData.queues, unreviewed: queueData.unreviewed, daily: [...daily.values()].sort((a, b) => a.date.localeCompare(b.date)),+ const window = windowMinutes === undefined ? undefined : {+ ...projectFlowWindow(prepared, windowMinutes, now),+ ...(executionCapacity ? { executionCapacity } : {}),+ };+ return { ...(window === undefined ? {} : { window }), asOf: new Date(now).toISOString(), stages, queues: queueData.queues, unreviewed: queueData.unreviewed, daily: [...daily.values()].sort((a, b) => a.date.localeCompare(b.date)),submitsPerMerged: completedItems ? counts.submissions / completedItems : 0, activeAgents, bottleneck };}diff --git a/test/runner-capacity-fixture.js b/test/runner-capacity-fixture.jsindex 618a6f09..49cb57f6 100644--- a/test/runner-capacity-fixture.js+++ b/test/runner-capacity-fixture.js@@ -133,3 +133,56 @@ const timer=setInterval(()=>{ if (fs.existsSync(${JSON.stringify(release)})) cleelse process.env.PULLBOARD_MACHINE_HOME = previousMachineHome;}}++/** A registered worker enforces timing admission and returns its own sampled load, not the controller's. */+export async function runnerTimingReceipt(t, { cli, git, runThroughGate, gateResult }) {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'pullboard-runner-timing-')));+ t.after(() => rmSync(dir, { recursive: true, force: true }));+ const home = join(dir, 'home');+ const machineHome = join(home, '.pullboard');+ const remoteHome = join(dir, 'worker-home');+ const remoteMachineHome = join(remoteHome, '.pullboard');+ const repo = join(dir, 'repo');+ const worker = join(dir, 'second-machine');+ const bin = join(dir, 'bin');+ const requests = join(dir, 'requests.jsonl');+ for (const folder of [home, machineHome, remoteHome, remoteMachineHome, repo, worker, bin]) mkdirSync(folder, { recursive: true });+ writeFileSync(join(machineHome, 'settings.json'), JSON.stringify({ gateSlots: 1 }));+ const env = { ...process.env, HOME: home, PULLBOARD_HOME: home, PULLBOARD_MACHINE_HOME: machineHome,+ PATH: `${bin}:${process.env.PATH}`, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',+ GIT_AUTHOR_NAME: 'Timing Fixture', GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'Timing Fixture', GIT_COMMITTER_EMAIL: '[email protected]' };+ git(repo, env, 'init', '-q', '-b', 'main');+ writeFileSync(join(repo, 'pullboard.json'), JSON.stringify({ gate: 'true' }));+ git(repo, env, 'add', 'pullboard.json');+ git(repo, env, 'commit', '-q', '-m', 'test: prepare timing worker');+ installSshStandIn({ bin, worker, home: remoteHome, machineHome: remoteMachineHome, requests });+ const added = cli(repo, env, 'runner', 'add', HOST, '--slots', '2', '--browser', '0', '--json');+ assert.equal(added.status, 0, added.context);+ const previous = process.env.PULLBOARD_MACHINE_HOME;+ process.env.PULLBOARD_MACHINE_HOME = machineHome;+ let local;+ try {+ local = await takeResource({ name: 'gate', capacity: 1, scope: 'machine', root: repo, agent: 'timing-controller-holder' });+ const result = await runThroughGate(repo, env, 'node -e "console.log(\'actual timing worker\')"',+ { timing: true, browser: false, requests, item: 'timing-receipt' });+ assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);+ const actual = gateResult(result.stdout);+ assert.equal(actual.runner, HOST);+ const receipt = actual.profile.receipt;+ assert.equal(receipt.runner.id, HOST);+ assert.equal(receipt.runner.kind, 'ssh');+ assert.equal(receipt.runner.slots.current, 2);+ assert.equal(receipt.timing, true);+ assert.equal(receipt.exclusive, true);+ assert.deepEqual(receipt.unfencedClients, []);+ assert.ok(Date.parse(receipt.load.start.at) >= Date.parse(receipt.admittedAt));+ assert.equal(receipt.load.end.at, receipt.finishedAt);+ assert.ok(receipt.load.start.average.every(Number.isFinite));+ assert.ok(receipt.load.end.average.every(Number.isFinite));+ } finally {+ local?.release();+ if (previous === undefined) delete process.env.PULLBOARD_MACHINE_HOME;+ else process.env.PULLBOARD_MACHINE_HOME = previous;+ }+}diff --git a/test/runner-stage.test.js b/test/runner-stage.test.jsnew file mode 100644index 00000000..540d5092--- /dev/null+++ b/test/runner-stage.test.js@@ -0,0 +1,92 @@+/** The requested stats window reports measured runner capacity from private Git/SQLite state [C7,O5]. */+import assert from 'node:assert/strict';+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { test } from 'node:test';+import * as store from '../src/board.js';+import { main } from '../src/cli.js';+import { localRunnerDescriptor } from '../src/runner-load.js';+import { recordReceipt } from '../src/gate-receipt.js';+import * as runnerApi from '../src/runners.js';+import { runFixtureGit } from './fixture-child.js';++/** Capture the actual CLI response while supplying a deterministic observation clock. */+async function run(root, args, clock) {+ let stdout = '';+ let stderr = '';+ const code = await main(args, { cwd: root, clock,+ stdout: { isTTY: false, write: text => { stdout += text; } },+ stderr: { write: text => { stderr += text; } } });+ return { code, stdout, stderr, data: args.includes('--json') ? JSON.parse(stdout) : null };+}++test('[C7,O5] stats --window includes measured runner capacity and slot-wait quartiles from private receipts', async t => {+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'pullboard-runner-stage-')));+ const machineHome = join(root, 'machine');+ t.after(() => rmSync(root, { recursive: true, force: true }));+ runFixtureGit(['init', '-q', '-b', 'main'], { cwd: root, stdio: 'pipe' });+ writeFileSync(join(root, 'pullboard.json'), JSON.stringify({ lanes: { web: { owns: ['web/'] } } }));+ const now = Date.parse('2026-10-24T12:00:00.000Z');+ const board = store.openBoard(join(root, '.git', 'pullboard', 'board.sqlite'), { now: () => new Date(now) });+ t.after(() => store.closeBoard(board));++ const priorMachineHome = process.env.PULLBOARD_MACHINE_HOME;+ process.env.PULLBOARD_MACHINE_HOME = machineHome;+ try {+ mkdirSync(machineHome, { recursive: true });+ writeFileSync(join(machineHome, 'settings.json'), JSON.stringify({ gateSlots: 2, browserSlots: 1 }));+ const runner = { ...localRunnerDescriptor(2, true), active: 0 };+ const admittedAt = new Date(now - 10_000).toISOString();+ const finishedAt = new Date(now - 9_000).toISOString();+ recordReceipt(root, { at: finishedAt, kind: 'check', waitMs: 50, runMs: 500,+ admissionMs: 1, setupMs: 2, evidenceMs: 3, slot: { kind: 'ordinary' },+ runner, admittedAt, finishedAt, timing: false, inherited: false, occupiedSlots: 1,+ exclusive: false, unfencedClients: [] });++ const output = await run(root, ['stats', '--window', '1h', '--json'], { now: () => new Date(now) });+ assert.equal(output.code, 0, output.stderr);+ const capacity = output.data.window.executionCapacity;+ const local = capacity.runners.find(row => row.id === runner.id);+ assert.ok(local, 'the real machine resource snapshot includes the local executor');+ assert.equal(local.runsServed, 1);+ assert.ok(local.busyShare > 0 && local.busyShare < 1, 'the structured run occupies only its measured part of the requested window');+ assert.deepEqual(capacity.slotWait, { fastQuarterMs: 50, medianMs: 50, slowQuarterMs: 50, worstMs: 50, count: 1 });+ const text = await run(root, ['stats', '--window', '1h'], { now: () => new Date(now) });+ assert.equal(text.code, 0, text.stderr);+ assert.match(text.stdout, /runner slot waits: fast 0\.05s · median 0\.05s · slow 0\.05s · worst 0\.05s \(1 measured\)/u);+ } finally {+ if (priorMachineHome === undefined) delete process.env.PULLBOARD_MACHINE_HOME;+ else process.env.PULLBOARD_MACHINE_HOME = priorMachineHome;+ }+});+++test('[C7,O5] browser work waits when ordinary slots are free but browser slots are full', () => {+ const window = { from: '2026-10-24T11:00:00.000Z', to: '2026-10-24T12:00:00.000Z' };+ const stage = runnerApi.runnerStage([{+ id: 'local:test', kind: 'local', slots: { current: 2, limit: 2, elastic: false },+ capabilities: { os: 'darwin', browser: true }, active: 1, browserSlots: 1, browserActive: 1,+ }], [], window);+ assert.deepEqual(runnerApi.placeRunner(stage, { capabilities: { browser: true } }), { action: 'wait' });+ assert.deepEqual(runnerApi.placeRunner(stage, { capabilities: { browser: false } }), { action: 'run', runnerId: 'local:test' });++ const unknownBrowserUse = runnerApi.runnerStage([{+ id: 'local:unknown-browser-use', kind: 'local', slots: { current: 2, limit: 2, elastic: false },+ capabilities: { os: 'darwin', browser: true }, active: 1,+ }], [], window);+ assert.deepEqual(runnerApi.placeRunner(unknownBrowserUse, { capabilities: { browser: true } }), { action: 'wait' });+});+++test('[C7,O5] legacy receipt timestamps leave runner shares and counts unknown', () => {+ const runners = ['local:a', 'ssh:b'].map((id, index) => ({+ id, kind: index ? 'ssh' : 'local', slots: { current: 2, limit: 2, elastic: false },+ capabilities: { os: null, browser: null }, active: 0,+ }));+ const stage = runnerApi.runnerStage(runners, [{+ at: '2026-10-24T11:30:00.000Z', waitMs: 10, runMs: 20,+ }], { from: '2026-10-24T11:00:00.000Z', to: '2026-10-24T12:00:00.000Z' });+ assert.deepEqual(stage.runners.map(row => [row.busyShare, row.runsServed]), [[null, null], [null, null]]);+ assert.deepEqual(stage.slotWait, { fastQuarterMs: 10, medianMs: 10, slowQuarterMs: 10, worstMs: 10, count: 1 });+});diff --git a/test/runner-timing.test.js b/test/runner-timing.test.jsindex a01bdff2..c31054e0 100644--- a/test/runner-timing.test.js+++ b/test/runner-timing.test.js@@ -86,6 +86,8 @@ await withGateSlot(root, async lease => {finally { for (const key of ['PULLBOARD_GATE_SLOT_HELD', 'PULLBOARD_GATE_SLOT_POOL', 'PULLBOARD_GATE_SLOT_TOKEN', 'PULLBOARD_BROWSER_SLOT_HELD']) delete process.env[key]; }}, { timing: true, remote: false, onReceipt: value => { receipt = value; } });assert.equal(receipt.timing, true);+assert.equal(receipt.exclusive, true);+assert.deepEqual(receipt.unfencedClients, []);assert.equal(receipt.runner.kind, 'local');for (const sample of [receipt.load.start, receipt.load.end]) {assert.ok(Number.isFinite(Date.parse(sample.at)), 'load has an executor timestamp');@@ -97,3 +99,21 @@ assert.ok(Date.parse(receipt.load.end.at) >= Date.parse(receipt.load.start.at));assert.ok(Date.parse(receipt.finishedAt) >= Date.parse(receipt.admittedAt));`);});++test('a legacy queue client makes the timing receipt explicitly unfenced even after it exits [C7,Q1]', async t => {+ const box = fixture(t);+ await runFixture(box, `+const { takeResource: legacyTakeResource } = await import(${JSON.stringify(new URL('./fixtures/resources-pre-runners.js', import.meta.url).href)});+let receipt;+await withGateSlot(root, async lease => {+ assert.equal(lease.timingEvidence().exclusive, true);+ const legacy = await legacyTakeResource({ name: 'gate', capacity: 2, scope: 'machine', root, agent: 'legacy-unfenced-fixture' });+ try { assert.equal(listResources({ root }).find(row => row.name === 'gate').holders.length, 2); }+ finally { legacy.release(); }+ assert.equal(listResources({ root }).find(row => row.name === 'gate').holders.length, 1,+ 'the short legacy run already left before the receipt is captured');+}, { timing: true, remote: false, onReceipt: value => { receipt = value; } });+assert.equal(receipt.exclusive, false, 'a number measured beside an unfenced client cannot claim isolation');+assert.ok(receipt.unfencedClients.some(client => client.agent === 'legacy-unfenced-fixture'));+`);+});diff --git a/test/runner-tooling-fixture.js b/test/runner-tooling-fixture.jsindex 0e489bd5..b6de9171 100644--- a/test/runner-tooling-fixture.js+++ b/test/runner-tooling-fixture.js@@ -149,14 +149,14 @@ export async function awaitRoundTrip(child, closed, phasesFile, before, deadline* Run a gate command through its real lease and return the profile/result emitted by the API child.* `requests` names the stand-in's request log, whose .phases file times the round trip by phase.*/-export async function runThroughGate(repo, env, command, { browser = true, item = '663', kind = 'check', landing = false, toolingRoot = resolve(import.meta.dirname, '..'), requests, deadlines } = {}) {+export async function runThroughGate(repo, env, command, { browser = true, timing = false, item = '663', kind = 'check', landing = false, toolingRoot = resolve(import.meta.dirname, '..'), requests, deadlines } = {}) {const sourceRoot = realpathSync(toolingRoot);const gateUrl = pathToFileURL(join(committedToolingSnapshot(sourceRoot, env), 'src', 'gate.js')).href;const snapshot = TOOLING_SNAPSHOTS.get(sourceRoot);snapshot.active++;const script = `const { runProfiledShell, withGateSlot } = await import(${JSON.stringify(gateUrl)});const result = await withGateSlot(${JSON.stringify(repo)}, lease => runProfiledShell(${JSON.stringify(repo)}, ${JSON.stringify(command)}, { gateLease: lease, landing: ${landing} }),- { browser: ${browser}, item: ${JSON.stringify(item)}, kind: ${JSON.stringify(kind)}, landing: ${landing}, agent: 'runner-fixture' });+ { browser: ${browser}, timing: ${timing}, item: ${JSON.stringify(item)}, kind: ${JSON.stringify(kind)}, landing: ${landing}, agent: 'runner-fixture' });process.stdout.write(result.output);process.stdout.write('PULLBOARD_RUN_RESULT ' + JSON.stringify({ isGreen: result.isGreen, runner: result.profile.executionRunner, sandboxBlocked: result.sandboxBlocked, profile: result.profile }) + '\\n');process.exitCode = result.isGreen ? 0 : 1;diff --git a/test/runners.test.js b/test/runners.test.jsindex 3ae685c0..00b9f784 100644--- a/test/runners.test.js+++ b/test/runners.test.js@@ -25,7 +25,7 @@ import { sourceSetupFailureFixture } from './runner-source-setup-fixture.js';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 { runnerUsesRegisteredCapacity } from './runner-capacity-fixture.js';+import { runnerTimingReceipt, runnerUsesRegisteredCapacity } from './runner-capacity-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';@@ -1316,6 +1316,9 @@ test('a runner job leaves no process behind, and never signals a process it canntest('machines report busy share and a new run goes to the idle one [C7,O5]', { timeout: 30_000 }, t => runnerStageFixture(t, e2e));+test('registered timing receipt names the physical worker and actual load [C7,Q1]', { timeout: 90_000 },+ t => runnerTimingReceipt(t, { cli, git, runThroughGate, gateResult }));+test('a runner uses the capacity it was registered with [C7,O5]', { timeout: 180_000 }, t => runnerUsesRegisteredCapacity(t, { cli, git, observe, startQueueController, gateResult })); // budget: two rounds of four concurrent runner round trips.test('review655 a registered runner honors the same live person waiver at landing [B3,R3,C7]', { timeout: 120_000 }, async (t) => {