@edgehero/pi-dispatch 4.0.1 → 4.2.0

package/src/egress-allowlist.mjs

@@ -0,0 +1,81 @@
+/**
+ * The egress allowlist as the proxy reads it, and whether a URL a job dials gets through (docs/egress.md). Squid
+ * matches `egress-allowlist.conf` as a `dstdomain` file (deploy/egress-proxy.conf, `acl allowed dstdomain -n`): each
+ * line, trimmed and with a `#` comment removed, is ONE entry, and an entry with a leading dot admits that domain and
+ * every name under it. A line with two words is one entry that matches nothing (measured on the pinned squid: both
+ * names refused), so it admits nothing here either. A job's runner sends every request as a CONNECT
+ * (image/runner/src/env-proxy.mjs, `proxyTunnel: true`), and the proxy allows a CONNECT to an allowlisted name on port
+ * 443 only, never to a host that resolves to this machine (`to_host_local`), and to a declared model endpoint on
+ * exactly its host and port (`model-endpoints.conf`).
+ *
+ * The proxy stays the enforcement. This is the same reading done before anything is spent, so a job whose server the
+ * policy cannot serve is refused with a reason instead of failing at its first call. It is a necessary condition, not
+ * a sufficient one: a NAME that resolves to this machine is refused by the proxy and not here, since this reads no DNS.
+ */
+import { isIP } from "node:net";
+import { basename } from "node:path";
+import { isProxyLocalHost } from "./backends.mjs";
+import { baseUrlTarget, endpointsAt } from "./model-endpoints.mjs";
+
+/** The entries of an allowlist's text, lowercased, in order: one per line, a line with inner whitespace skipped. */
+export function parseAllowlist(text) {
+	const entries = [];
+	for (const raw of String(text ?? "").split(/\r?\n/)) {
+		// A comment starts at a `#` that opens the line or follows whitespace; one inside a word is part of the word,
+		// which then matches no host.
+		const line = raw.replace(/(^|\s)#.*$/, "").trim();
+		if (line === "" || /\s/.test(line)) continue;
+		entries.push(line.toLowerCase());
+	}
+	return entries;
+}
+
+/** The first entry that admits `host`, or null: the name itself, or a leading-dot entry for it or a name above it. */
+export function allowlistEntryFor(entries, host) {
+	const name = String(host).toLowerCase();
+	for (const entry of entries) {
+		if (entry.startsWith(".") ? name === entry.slice(1) || name.endsWith(entry) : name === entry) return entry;
+	}
+	return null;
+}
+
+/** Whether `host` (as `baseUrlTarget` gives it) is an address squid's `to_host_local` refuses, or `localhost`. */
+function hostIsLocal(host) {
+	const bare = host.startsWith("[") ? host.slice(1, -1) : host;
+	const kind = isIP(bare) === 4 ? "ipv4" : isIP(bare) === 6 ? "ipv6" : "name";
+	if (isProxyLocalHost(kind, bare)) return true;
+	if (kind === "ipv4") return bare.startsWith("169.254.");
+	if (kind === "ipv6") return /^fe[89ab][0-9a-f]:/i.test(bare);
+	return false;
+}
+
+/**
+ * Why a job's CONNECT to `url` would be refused by the proxy, or null when it gets through: a declared endpoint's
+ * exact host and port, or an allowlisted name on port 443, over https, that is not this machine. Both schemes go as
+ * a CONNECT, so the proxy itself does not tell them apart.
+ */
+export function egressRefusalFor(url, { allowlist = [], endpoints = [] } = {}) {
+	const target = baseUrlTarget(url);
+	if (target === null) return "it is not an http or https URL";
+	if (endpointsAt(url, endpoints).length > 0) return null;
+	const entry = allowlistEntryFor(allowlist, target.host);
+	if (entry !== null && hostIsLocal(target.host)) return `${target.host} is the proxy's own machine, which it never opens; a server on this machine is declared in model-endpoints.json under host.docker.internal or host.containers.internal`;
+	// The proxy tunnels to 443 whatever speaks inside, so an `http://` url on 443 is plain HTTP to what is almost always
+	// a TLS port, carrying the server's headers in clear inside the tunnel: refused, with the fix.
+	if (entry !== null && target.port === 443 && new URL(url).protocol !== "https:") return `the egress proxy opens ${target.host} on port 443 for TLS, and this url is http://; use https://`;
+	if (entry !== null && target.port === 443) return null;
+	if (entry !== null) return `the egress proxy opens ${target.host} on port 443 only, and this is port ${target.port}; declare ${target.host}:${target.port} in model-endpoints.json to open exactly that port`;
+	return `${target.host} is not in egress-allowlist.conf${target.port === 443 ? "" : ", and port " + target.port + " opens only as a declared endpoint in model-endpoints.json"}`;
+}
+
+/**
+ * Every host a package runner fetches from at start, by name, since the proxy matches names: uv and pipx take the
+ * index from pypi.org and the files from files.pythonhosted.org, yarn's default registry is its own name, and the npm
+ * family reads registry.npmjs.org.
+ */
+export function packageRunnerHosts(command) {
+	const runner = basename(String(command));
+	if (["uv", "uvx", "pipx"].includes(runner)) return ["pypi.org", "files.pythonhosted.org"];
+	if (runner === "yarn") return ["registry.yarnpkg.com"];
+	return ["registry.npmjs.org"];
+}

package/src/env-allowlist.mjs

@@ -367,7 +367,7 @@ function resolveEnvName(provider) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], mcpServers = [], allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a policy refusal that refunds any reserve
@@ -429,6 +429,10 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// second-validator rule directly above). Absent means the full pinned default set, never an empty
 		// string, for PI_PACKAGES' reason.
 		PI_EXCLUDE_TOOLS: excludeTools.length > 0 ? excludeTools.join(",") : undefined,
+		// The trigger's run.mcp (REQ-MCP-OPERATOR-SERVERS): the overlay servers the job's session connects, so the
+		// runner can hold `/job/mcp.json` to the names the worker meant. Comma-safe for excludeTools' reason (the loader
+		// admits only lowercase letters, digits and `-`). Absent means none, never an empty string.
+		PI_MCP_SERVERS: mcpServers.length > 0 ? mcpServers.join(",") : undefined,
 		// The job's EFFECTIVE allowed-model list (issue #502): its trigger's `run.models`, else the deployment's
 		// PI_ALLOWED_MODELS. Comma-joined `provider/model` entries, which the runner splits at each entry's first `/`
 		// (image/runner/src/config.mjs). Comma is safe because both list parsers refuse an entry carrying one. NULL is

package/src/host-budget.mjs

@@ -484,6 +484,9 @@ export function makeHostBudget({ settings, jobDefault = { memMiB: 4096, cpuCenti
 		return Number.isSafeInteger(limit) && limit >= 0 ? limit : null;
 	};
 
+	// The runtime's own CPU count from the last facts read (`docker info` NCPU, `podman info` host.cpus), or null: what a
+	// run record names as the host's CPUs (issue #599), never the worker's own count, which on Docker Desktop is the Mac's.
+	let hostCpus = null;
 	const refresh = async () => {
 		let facts = {};
 		try {
@@ -493,6 +496,7 @@ export function makeHostBudget({ settings, jobDefault = { memMiB: 4096, cpuCenti
 		}
 		const next = computeHostBudget(settings, facts, jobDefault);
 		budget = { memMiB: next.memMiB, cpuCenti: next.cpuCenti };
+		hostCpus = Number.isSafeInteger(facts.hostCpus) && facts.hostCpus >= 1 ? facts.hostCpus : null;
 		detail = next.detail;
 		for (const entry of ledger.values()) {
 			if (entry.guess) Object.assign(entry, pessimisticSize([], entry.guess, budget));
@@ -618,6 +622,8 @@ export function makeHostBudget({ settings, jobDefault = { memMiB: 4096, cpuCenti
 		refresh,
 		/** The budget in force: `{ memMiB, cpuCenti }`, each an integer, `Infinity` (off) or null (unknown). */
 		current: () => ({ ...budget }),
+		/** The runtime's CPU count from the last facts read, or null when no venue answered. */
+		hostCpus: () => hostCpus,
 		detail: () => detail,
 		/** null when `size` can start here some day, else `host` or `share` (`neverFits`). */
 		neverFits: (size, project, limits = scopedLimits()) => neverFits(size, budget, project ? rulesOf(limits).shareOf(project) : null),

package/src/host-registry.mjs

@@ -29,8 +29,14 @@
  * from the reader rather than the writer -- the panel is where an operator screenshots, and doctor
  * prints these rows. A value that must be carried but cannot satisfy the rule is HASHED before it gets
  * here (`scopeKeyPrefix`'s idiom), never abbreviated.
+ *
+ * `jobs` (issue #599, phase 2) is the one field that carries a list: JSON of the jobs this host runs now, ids and
+ * integers only, built and read back by `live-jobs.mjs`, whose header argues each field against this rule. The reader
+ * below parses it through that module's allowlist, so a row's `jobs` is an array (or null), never the raw string.
  */
 
+import { parseJobsMore, parseLiveJobs } from "./live-jobs.mjs";
+
 /** The index. A SET cannot expire its members, so the leak is handled by the reader, as `wait:held` does. */
 export const HOST_SET = "host:live";
 
@@ -270,7 +276,7 @@ export function makeHostRegistry({ redis, name, now = () => Date.now(), ttlMs =
  * one treats them alike: "there are no other hosts" and "I could not find out" differ, and a panel that
  * renders the second as the first tells an operator their fleet is gone when Valkey merely blinked.
  */
-export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs = REGISTRY_OP_TIMEOUT_MS } = {}) {
+export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs = REGISTRY_OP_TIMEOUT_MS, prune = true } = {}) {
 	let names;
 	try {
 		names = await bounded(redis.smembers(HOST_SET), timeoutMs);
@@ -285,12 +291,24 @@ export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs =
 		try {
 			const row = await bounded(redis.hgetall(hostKey(member)), timeoutMs);
 			if (!row || Object.keys(row).length === 0) {
-				await bounded(redis.srem(HOST_SET, member), timeoutMs).catch(() => {});
+				// `prune: false` for a reader that promises to write nothing (the capacity report, issue #599): the stale member
+				// is skipped the same, and left for the next pruning reader.
+				if (prune) await bounded(redis.srem(HOST_SET, member), timeoutMs).catch(() => {});
 				continue;
 			}
 			const beatAt = typeof row.beatAt === "string" && row.beatAt.trim() !== "" ? Number(row.beatAt) : NaN;
+			// The running jobs through the allowlist (issue #599, phase 2): an array, or null where the row publishes none (a
+			// worker from before the field) or none that parses. A listed entry that does not read is a running job not
+			// counted, so it joins `jobsMore` rather than vanishing.
+			const live = parseLiveJobs(row.jobs);
+			const more = parseJobsMore(row.jobsMore);
 			hosts.push({
 				...row,
+				jobs: live.jobs,
+				jobsMore: live.jobs === null ? more : (more ?? 0) + live.dropped,
+				// A row that HAS a `jobs` value that is not a list: how many it runs is unknown, which a reader must say
+				// rather than read as a worker from before the field.
+				jobsUnreadable: live.jobs === null && typeof row.jobs === "string" && row.jobs !== "",
 				name: row.name || member,
 				// Derived rather than stored, so the panel can say "stale 2m" about a row that still lives.
 				// A row whose clock is AHEAD of ours reads as 0 rather than negative: the difference is the

package/src/image-preflight.mjs

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { imageRefProblem } from "./image-ref.mjs";
+import { FORGE_MCP_SERVER_NAME } from "./mcp-config.mjs";
 
 /**
  * Which image a job runs in, and whether it is on this host.
@@ -44,7 +45,9 @@ export function resolveJobImage(job, defaultImage) {
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
  *   { <gate.result>, declared } -- present, but does not declare a capability this job needs, one key per
  *                            CAPABILITY_GATES row (replicaUnsupported, commandUnsupported,
- *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported) => POLICY
+ *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported, mcpUnsupported,
+ *                            forgeMcpUnsupported)
+ *                            => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
  * so the failure path disambiguates POSITIVELY with `docker info` rather than by matching docker's stderr.
@@ -191,6 +194,27 @@ export const CAPABILITY_GATES = Object.freeze([
 		event: "refused_image_cost_cap_unsupported",
 		comment: (image, declared) => `Refused: the job image "${image}" does not declare cost-cap support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore the per-job dollar cap and run this job with no cap at all. Rebuild the image from a version that has this feature. Not run.`,
 	}),
+	// REQ-MCP-OPERATOR-SERVERS: a runner that predates run.mcp reads no /job/mcp.json, so the job would run without
+	// the servers its flow was written against and record a clean exit while the file reads as though it named them.
+	Object.freeze({
+		token: "mcp",
+		needed: (job) => Array.isArray(job?.mcp) && job.mcp.length > 0,
+		result: "mcpUnsupported",
+		reason: "job-image-mcp-unsupported",
+		event: "refused_image_mcp_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare MCP support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would not connect the servers \`run.mcp\` names. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// DES-FORGE-MCP: `forge` in run.mcp starts a server the IMAGE carries (github-mcp-server, mcp-gitlab), not one the
+	// overlay names. An image with `mcp` and without them would pass every gate, reserve the budget, and refuse at the
+	// container's start as mcp-command-missing; this row says so before anything is spent.
+	Object.freeze({
+		token: "forgeMcp",
+		needed: (job) => Array.isArray(job?.mcp) && job.mcp.includes(FORGE_MCP_SERVER_NAME),
+		result: "forgeMcpUnsupported",
+		reason: "job-image-forge-mcp-unsupported",
+		event: "refused_image_forge_mcp_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare the forge's own MCP server (\`dev.pi-dispatch.capabilities\` ${declared}), so it does not carry the server \`run.mcp\` names as \`forge\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
 ]);
 
 /**

package/src/import-pi.mjs

@@ -7,7 +7,8 @@
  * `auth.json` / env and reaches the container through the env allowlist, never a mounted file. So this
  * command copies only the safe subset and REFUSES a `models.json` that embeds a literal key.
  *
- * Copied:   models.json (definitions only, sanitized), skills/, APPEND_SYSTEM.md, and extensions/ (verbatim;
+ * Copied:   models.json (definitions only, sanitized), skills/, APPEND_SYSTEM.md, mcp.json (rewritten to the
+ *           servers a job may connect, references only; `--no-mcp` leaves it out), and extensions/ (verbatim;
  *           the admin extension is hard-blocked, and one the operator disabled in `pi config` is left behind).
  *           Extensions come along BY DEFAULT -- staging is the vetting step, and an overlay missing the
  *           operator's own extensions is not the setup they asked for -- with `--no-extensions` as the escape
@@ -19,17 +20,19 @@
  *           setup and staged at the exact version their host runs (issue #102); `pi-packages.json` becomes
  *           the override-and-addition layer rather than the only road in, and `--no-host-packages` restores
  *           the declared-only behaviour exactly.
- * Never:    auth.json, settings.json, sessions/, themes/, prompts/, tools/. Discovery READS settings.json to
- *           learn what pi has installed and what the operator turned off; reading is not copying, and no part
- *           of that file reaches the overlay.
+ * Never:    auth.json, settings.json, sessions/, themes/, prompts/, tools/, mcp-auth.json (pi's MCP sign-ins).
+ *           Discovery READS settings.json to learn what pi has installed and what the operator turned off;
+ *           reading is not copying, and no part of that file reaches the overlay.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, lstatSync, statSync, copyFileSync, renameSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, lstatSync, statSync, copyFileSync, renameSync, rmSync, unlinkSync } from "node:fs";
 import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { FROM_HOST, PACKAGES_SUBDIR, RESOURCE_DIRS, STAGE_MANIFEST, mergeHostPackages, parsePackagesFile } from "./packages.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
 import { ENTRY_NAME_RE, copyDirContents, copySkillTree } from "./copy-tree.mjs";
+import { MCP_CONFIG_FILE_NAME, MCP_CONFIG_MAX_BYTES, mcpServerWhere, overlayMcpText, parseOverlayMcp } from "./mcp-config.mjs";
 
 /**
  * A valid skill/extension entry name. Defined in copy-tree.mjs, which is the module that enforces it,
@@ -46,7 +49,7 @@ export const ADMIN_RE = /pi-dispatch|dispatch-admin/i;
  * silently means "third-party code you did not expect runs in every job container". A typo must not be able
  * to widen what loads.
  */
-const BOOL_FLAGS = new Set(["--no-extensions", "--with-extensions", "--with-packages", "--host-packages", "--no-host-packages"]);
+const BOOL_FLAGS = new Set(["--no-extensions", "--with-extensions", "--with-packages", "--host-packages", "--no-host-packages", "--no-mcp"]);
 const VALUE_FLAGS = new Set(["--from", "--to", "--packages-file"]);
 
 const execFileAsync = promisify(execFile);
@@ -98,7 +101,7 @@ export async function runImportPi(argv = [], deps = {}) {
 		out = (s) => process.stdout.write(s),
 		// lstatSync rides along for the shared copier, whose symlink guard is the whole point of it: the
 		// walker this dir's copies used to go through guarded with statSync, which FOLLOWS links.
-		fs = { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, lstatSync, statSync, copyFileSync, renameSync, rmSync },
+		fs = { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, lstatSync, statSync, copyFileSync, renameSync, rmSync, unlinkSync },
 		exec = defaultExec,
 		// Injected like `fs`/`exec`/`out` so the win32 npm branch below is reachable from a test on any host;
 		// it is the branch that was dead on arrival precisely because nothing could exercise it here.
@@ -181,6 +184,13 @@ export async function runImportPi(argv = [], deps = {}) {
 		results.push(["APPEND_SYSTEM.md", "global persona (layers under each repo's persona)"]);
 	}
 
+	// mcp.json -- the MCP servers jobs may connect (REQ-MCP-OPERATOR-SERVERS). REWRITTEN, never copied: only the servers
+	// a job may connect are written, each in pi's shape with every header and env value a reference, so a host entry
+	// with a literal value, an OAuth sign-in or a key this deployment does not take never reaches the overlay. Each one
+	// left behind is named with why. The overlay's file follows the host's (`stageMcp`), since a job would otherwise
+	// keep connecting servers the operator no longer offers.
+	results.push(...stageMcp({ fs, from, to, skip: argv.includes("--no-mcp") }));
+
 	// extensions/ -- the sharp edge, and copied BY DEFAULT: the operator staged this overlay to be their own
 	// setup, and one they have to arm twice more is not that. The admin extension stays hard-blocked (it can
 	// enqueue paid jobs from inside a container: a recursion vector, not part of this relaxation).
@@ -268,11 +278,106 @@ export async function runImportPi(argv = [], deps = {}) {
 	// A note-less row is a list item under the row above it (the extension names), so it prints bare rather
 	// than padded out to a column that has nothing to hold.
 	for (const [name, note] of results) out(note ? `  ${name.padEnd(18)} ${note}\n` : `  ${name}\n`);
-	out(`\n  (auth.json, settings.json, sessions/ are never copied — your credential stays in env/auth.json.)\n`);
+	out(`\n  (auth.json, settings.json, sessions/ and mcp-auth.json are never copied: your credential stays in env/auth.json.)\n`);
 	out(nextSteps(to, withExtensions, withPackages, withHostPackages && hostPi.packages.length > 0));
 	return 0;
 }
 
+/**
+ * Stage the host's `mcp.json` into the overlay, rewritten to the servers a job may connect. Returns the result rows.
+ * The overlay's file follows the host's: it is replaced by each import, and removed when the host has none, when
+ * `--no-mcp` is passed, or when the host offers no server a job may connect, so a hand-written overlay file is
+ * replaced too (docs/mcp.md says so). One exception keeps what is there: a host file that cannot be read whole (not
+ * JSON, a duplicate key, too large) changes nothing, since the operator is mid-edit and the last good list stands.
+ * The overlay's file is never followed if it is a link: a new file is renamed over it, so a link back to the host's
+ * own file cannot make this command rewrite it.
+ */
+function stageMcp({ fs, from, to, skip }) {
+	const src = join(from, MCP_CONFIG_FILE_NAME);
+	const dst = join(to, MCP_CONFIG_FILE_NAME);
+	const rows = [];
+	const existing = () => {
+		try {
+			return fs.lstatSync(dst);
+		} catch {
+			return null;
+		}
+	};
+	const removeOld = (why) => {
+		const entry = existing();
+		if (entry === null) return true;
+		if (entry.isDirectory()) {
+			rows.push([`${MCP_CONFIG_FILE_NAME} (overlay)`, `WARN: ${dst} is a folder; remove it by hand`]);
+			return false;
+		}
+		// unlink, not rmSync: `force` skips a dangling link, which the write would then follow.
+		fs.unlinkSync(dst);
+		rows.push([`${MCP_CONFIG_FILE_NAME} (overlay)`, `removed (${why})`]);
+		return true;
+	};
+	if (skip) {
+		if (fs.existsSync(src)) rows.push([MCP_CONFIG_FILE_NAME, "skipped -- --no-mcp was passed (jobs are offered no MCP server)"]);
+		removeOld("--no-mcp");
+		return rows;
+	}
+	if (!fs.existsSync(src)) {
+		removeOld(`no ${MCP_CONFIG_FILE_NAME} in your pi setup`);
+		return rows;
+	}
+	let parsed;
+	try {
+		// statSync follows a link, so a link to a regular file is read and one to a pipe or device is not: a FIFO would
+		// block this read forever, and /dev/zero would never end.
+		const stat = fs.statSync(src);
+		if (!stat.isFile()) throw Object.assign(new Error(`${src}: is not a regular file`), { mcpConfig: true });
+		if (stat.size > MCP_CONFIG_MAX_BYTES) throw Object.assign(new Error(`${src}: is larger than ${MCP_CONFIG_MAX_BYTES} bytes`), { mcpConfig: true });
+		parsed = parseOverlayMcp(String(fs.readFileSync(src, "utf8")), src);
+	} catch (error) {
+		const kept = existing() === null ? "" : "; the overlay's file is kept as it was";
+		rows.push([MCP_CONFIG_FILE_NAME, `SKIPPED -- ${error?.mcpConfig ? error.message : `${src}: cannot be read (${error?.code ?? "unreadable"})`}${kept}`]);
+		return rows;
+	}
+	const names = Object.keys(parsed.servers);
+	if (names.length > 0) {
+		// Replaced, never written through: a link or an earlier file goes first, and a folder stops the write.
+		const entry = existing();
+		if (entry?.isDirectory()) {
+			rows.push([MCP_CONFIG_FILE_NAME, `WARN: ${dst} is a folder; remove it by hand, then re-run`]);
+		} else {
+			// A new file renamed over the old: the rename replaces a link rather than its target, and a write that fails
+			// leaves the last good list in place.
+			// A name no earlier run left, opened only if it does not exist (`wx`), so it is never a link to follow; removed
+			// again if the write or the rename fails, since every job mounts this folder.
+			const tmp = `${dst}.${randomBytes(6).toString("hex")}.tmp`;
+			try {
+				fs.writeFileSync(tmp, overlayMcpText(parsed), { flag: "wx", mode: 0o644 });
+				fs.renameSync(tmp, dst);
+			} catch (error) {
+				try {
+					fs.unlinkSync(tmp);
+				} catch {
+					// Never written.
+				}
+				throw error;
+			}
+			rows.push([MCP_CONFIG_FILE_NAME, `${names.length} MCP server${names.length === 1 ? "" : "s"} offered to jobs`]);
+			for (const name of names) {
+				const server = parsed.servers[name];
+				const runner = server.packageRunner ? ", fetches its server from a registry at start" : "";
+				rows.push([`  - ${name} (${server.transport}, ${mcpServerWhere(server)}${runner})`, ""]);
+			}
+		}
+	} else {
+		rows.push([MCP_CONFIG_FILE_NAME, "no MCP server a job may connect"]);
+		removeOld("nothing to offer");
+	}
+	if (parsed.refused.length > 0) {
+		rows.push([`${MCP_CONFIG_FILE_NAME} (left)`, `${parsed.refused.length} server${parsed.refused.length === 1 ? "" : "s"} not staged`]);
+		for (const { name, problem } of parsed.refused) rows.push([`  - ${JSON.stringify(name)}: ${problem}`, ""]);
+	}
+	return rows;
+}
+
 /**
  * Copy `<src>/<name>/**` for each valid, non-symlink child dir. Returns the count copied.
  *

package/src/index.mjs

@@ -1,3 +1,4 @@
+import { availableParallelism } from "node:os";
 import { DelayedError, UnrecoverableError, Worker } from "bullmq";
 import { assertJudgedConnection, onValkeyError } from "./connection.mjs";
 import { jobContainerName } from "./backend-local.mjs";
@@ -7,7 +8,7 @@ import { CANCEL_ACK_TTL_MS, cancelAckKey, cancelReqKey } from "./cancel-state.mj
 import { InfraRetry, NETNS_KEEPER_CRASH_LOOP, NETNS_KEEPER_NOT_HOLDING, TERMINAL_COMMENTS, runJob } from "./processor.mjs";
 import { NETNS_KEEPER_YOUNG_HOLD_MAX_MS, netnsKeeperCrashLoopSentence, netnsKeeperLoopAgainSentence } from "./netns-keeper.mjs";
 import { PODMAN_RESTART_HOLD_EXPIRED, PODMAN_RESTART_HOLD_MAX_MS, PODMAN_RESTART_HOLD_RECHECK_MS } from "./runtime-observations.mjs";
-import { targetFor } from "./run-history.mjs";
+import { earlierFrom, targetFor } from "./run-history.mjs";
 import { isPerMachineHost } from "./backends.mjs";
 import { hash16 } from "./fleet-lease.mjs";
 import { endpointsForModel } from "./model-endpoints.mjs";
@@ -190,7 +191,43 @@ export function effectiveJobOf(data, settings, allowedModels = null, log = () =>
 	};
 }
 
-export function makeProcessor({ cancelJob, stopContainer, containerName = (job) => jobContainerName(job.id), redis, getSettings, hostBudget = null, abortGraceMs = ABORT_GRACE_MS, applyConcurrency = () => {}, pauseUntil = () => null, scopedLimits = () => [], projects = () => [], jobSizeEnv = {}, allocation = null, inFlight = makeInFlight(), hostBound = null, checkLease = null, scopeLease = null, endpointSlots = makeInFlight(), endpointLease = null, modelEndpoints = null, overlayModels = () => null, endpointSetFor = mainModelEndpoints, deps, recordRun = () => {}, settledRecord = null, timeoutMs = JOB_TIMEOUT_MS, cancelPollMs = 2_000, cancelStopBoundMs = CANCEL_STOP_BOUND_MS, hostName = "", multiHost = false, now = () => Date.now(), waitState = makeWaitState({ redis, now }), afterMaxMs = () => WAIT_AFTER_MAX_DEFAULT_MS, checkSlots = makeInFlight(), checkSlotCount = () => 1, checkTimeoutMs = () => 10_000, concurrencyNow = () => 3, intervalMs = () => WAIT_INTERVAL_FLOOR_MS * 2, maxWaitMs = () => 24 * 3600 * 1000, maxChecks = () => 96, maxFaults = () => 5, random = Math.random }) {
+/**
+ * The jobs this host runs right now (issue #599, phase 2): one entry per PICKUP that holds a slot, `{ id, project, memMiB,
+ * cpuCenti, at }`, `at` its admission instant in millis (the record's `startedAt`). The registry beat publishes it
+ * (`jobs`, live-jobs.mjs), and the capacity report counts each as busy until its record exists.
+ *
+ * It works WITHOUT a host budget, which is why it is not the budget's ledger: the ledger exists only when a budget is
+ * set. Keyed by a per-pickup number, not the job id, so a second pickup of the same id (a stalled job handed back while
+ * the first still runs here) can never remove the first's entry. Process memory, `makeInFlight`'s reason: it counts
+ * this process's own pickups, and a restart that loses it has no pickup left to count.
+ *
+ * An entry is added where the job is admitted (`startedAt`, `capacity`) and removed only by `releaseAllHolds`, the one
+ * release every exit goes through, so it cannot outlive its pickup. An ORPHAN (the container's stop did not take) is
+ * removed like any other exit: the processor is done with it, and only the host budget keeps watching its container,
+ * so the beat flags orphans from the budget's ledger alone. Without a budget nothing watches such a container, and the
+ * list says only what this process still runs.
+ */
+export function makeRunningJobs() {
+	const entries = new Map();
+	let next = 0;
+	return {
+		/** Adds one pickup's entry; returns its key. Total: it never throws, so the admission block may call it. */
+		add(entry) {
+			next += 1;
+			entries.set(next, { ...entry });
+			return next;
+		},
+		/** Removes one pickup's entry; true only the first time. */
+		remove(key) {
+			return entries.delete(key);
+		},
+		/** Copies, never the live map. */
+		list: () => [...entries.values()].map((e) => ({ ...e })),
+		size: () => entries.size,
+	};
+}
+
+export function makeProcessor({ cancelJob, stopContainer, containerName = (job) => jobContainerName(job.id), redis, getSettings, hostBudget = null, abortGraceMs = ABORT_GRACE_MS, applyConcurrency = () => {}, pauseUntil = () => null, scopedLimits = () => [], projects = () => [], jobSizeEnv = {}, allocation = null, inFlight = makeInFlight(), hostBound = null, checkLease = null, scopeLease = null, endpointSlots = makeInFlight(), endpointLease = null, modelEndpoints = null, overlayModels = () => null, endpointSetFor = mainModelEndpoints, deps, recordRun = () => {}, settledRecord = null, previousRecord = null, timeoutMs = JOB_TIMEOUT_MS, cancelPollMs = 2_000, cancelStopBoundMs = CANCEL_STOP_BOUND_MS, hostName = "", multiHost = false, now = () => Date.now(), waitState = makeWaitState({ redis, now }), afterMaxMs = () => WAIT_AFTER_MAX_DEFAULT_MS, checkSlots = makeInFlight(), checkSlotCount = () => 1, checkTimeoutMs = () => 10_000, concurrencyNow = () => 3, intervalMs = () => WAIT_INTERVAL_FLOOR_MS * 2, maxWaitMs = () => 24 * 3600 * 1000, maxChecks = () => 96, maxFaults = () => 5, random = Math.random, cpus = availableParallelism, runningJobs = makeRunningJobs() }) {
 	// The lost-lock gate's rejection lines, said ONCE per job id, stall count and attempt. The gate runs before every
 	// deferral (pause window, wait, scope or endpoint busy), and BullMQ never resets a job's stall count, so a stalled
 	// scheduled job whose record is refused meets the gate again on every deferred pickup: a 30-minute scope-busy hold
@@ -233,6 +270,19 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 			}
 		}
 
+		// THE EARLIER ATTEMPTS' SLOT TIME (issue #599): a retry, or a pickup after a stall, writes its record over the one
+		// before it (one file and one mirror key per job id), so that record is read NOW, before anything here can replace
+		// it, and its slot interval (with the ones it carried) rides every record this pickup writes (`earlier`). Only on
+		// such a pickup, so a first attempt reads nothing; bounded by the reader, and a fault reads as none.
+		let earlier = null;
+		if (typeof previousRecord === "function" && ((Number.isInteger(job.attemptsMade) && job.attemptsMade > 0) || Number(job.stalledCounter) > 0)) {
+			try {
+				earlier = earlierFrom(await previousRecord(job.id));
+			} catch {
+				earlier = null;
+			}
+		}
+
 		// Scoped pause windows (REQ-SCOPED-PAUSE-WINDOWS): if this job's folder/repo is inside an active pause
 		// window, DEFER it to the window end via BullMQ's delayed set -- the job keeps its identity/dedup and
 		// auto-resumes when re-picked. This is FIRST, before the kill timer, the settings read, and the budget
@@ -302,7 +352,7 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 					const result = { outcome: "policy", reason, exitCode: null, turns: null, tokens: null, budgetReserved: false, hostBudget: { memMiB: budgetNow.memMiB, cpuCenti: budgetNow.cpuCenti, hostShare: share } };
 					// Above the wait gate, so through the recorder's own arguments rather than the bound one below it: the
 					// same pickup project and size, by hand once.
-					recordRun({ job, result, startedAt: at, endedAt: new Date().toISOString(), project, size });
+					recordRun({ job, result, startedAt: at, endedAt: new Date().toISOString(), project, size, earlier });
 					return result;
 				}
 				deps?.log?.("job_size_never_fits_here_deferred", { jobId: job.id, project, misfit, delayMs: NEVER_FITS_RECHECK_MS, ...sizeFields });
@@ -344,7 +394,7 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 				// resolver path or a vault topology -- `secret-profile-unknown` sets that rule.
 				if (sentence && deps?.comment) await Promise.resolve(deps.comment(job.data, sentence)).catch(() => {});
 				const result = { outcome: "policy", reason, exitCode: null, turns: null, tokens: null, budgetReserved: false };
-				recordRun({ job, result, startedAt: at, endedAt: new Date().toISOString() });
+				recordRun({ job, result, startedAt: at, endedAt: new Date().toISOString(), earlier });
 				return result;
 			};
 
@@ -673,6 +723,8 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 		// guard) still frees every local slot before it rethrows; the fleet halves are release-if-mine and awaited where
 		// the caller can. Draining, so a second call releases nothing: the in-process map's release is not idempotent.
 		let budgetHeld = false;
+		// This pickup's entry in the running jobs (issue #599, phase 2), null until it is admitted below.
+		let runningKey = null;
 		let stopDidNotTake = false;
 		let name;
 		let venue;
@@ -692,6 +744,11 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 			return Promise.all(taken.map((hold) => hold.fleet?.release?.()));
 		};
 		const releaseAllHolds = ({ orphan = false } = {}) => {
+			// The running-jobs entry first (issue #599, phase 2): this pickup no longer runs the job, orphan or not.
+			if (runningKey !== null) {
+				runningJobs.remove(runningKey);
+				runningKey = null;
+			}
 			const endpointsReleased = releaseEndpointHolds();
 			const scopesReleased = releaseScopeHolds();
 			if (hostHeld) {
@@ -718,11 +775,31 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 			hostHeld = true;
 		}
 
+		// The host's capacity as the record carries it (issue #599). Read when the job is admitted, not here: the slot count,
+		// the budget and the runtime's CPU count are live, and the value a run is judged against is the one it started under.
+		const capacityNow = () => {
+			const read = (fn) => {
+				try {
+					return fn();
+				} catch {
+					return null;
+				}
+			};
+			const budget = hostBudget ? read(() => hostBudget.current()) : null;
+			// The CPUs are the RUNTIME's count where its facts were read (the budget's own read), the worker's only when
+			// they were not: on Docker Desktop the worker sees the Mac's cores while every job runs in the VM's.
+			const runtimeCpus = hostBudget ? read(() => hostBudget.hostCpus?.()) : null;
+			return { slots: read(concurrencyNow), memMiB: budget?.memMiB ?? null, cpuCenti: budget?.cpuCenti ?? null, cpus: Number.isSafeInteger(runtimeCpus) && runtimeCpus >= 1 ? runtimeCpus : read(cpus) };
+		};
 		// THE ONE RECORDER BELOW THE GATE, bound once, so the pickup project is a property of the path and not of each call
 		// site: every record from here on goes through it, and none can drop the field and fall back to the live ref in
 		// start.mjs, which would disagree with the pickup value exactly when projects.json was edited mid-run. A bolt in
 		// project-pickup.test.mjs refuses a bare `recordRun(` call below this line.
-		const recordAfterGate = (args) => recordRun({ ...args, project, size });
+		//
+		// `capacity` (issue #599) rides the same binding, and is null until the job is admitted below (where `startedAt` is
+		// set): every record of a refusal before that point says, by its null, that the job never held a slot.
+		let capacity = null;
+		const recordAfterGate = (args) => recordRun({ ...args, project, size, capacity, earlier });
 
 		// The MATCHED ROW's scope keys both the in-process slot and the fleet lease (issue #498), the same string
 		// `budgetCapsFor` hashes below and the boot sweeper hashes from the file: a qualified `github:acme/web` row holds
@@ -984,6 +1061,14 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 			// exception, and it is named: the registry's refusal of an unheld venue is caught at the call, and
 			// anything else it throws propagates to the catch below, which releases what was acquired.
 			startedAt = new Date().toISOString();
+			// What this host offered as the job took its slot (issue #599, INT-RUN-HISTORY-FILE-CONTRACT): the live slot
+			// count, the host budget (null without one; `recordedCapacity` writes its `Infinity` as "off") and the CPUs the OS
+			// reports. Each read guarded: this block must not throw (above), and a fact that cannot be read is unknown, never
+			// a reason to fail a job that is about to run.
+			capacity = capacityNow();
+			// This host runs the job from here on (issue #599, phase 2): its entry, at the same instant as `startedAt`, given
+			// back by `releaseAllHolds` on every exit. `add` is total, so this block still cannot throw.
+			runningKey = runningJobs.add({ id: job.id, project, memMiB: size.memMiB, cpuCenti: size.cpuCenti, at: Date.parse(startedAt) });
 			// The producer of the name both boot reapers sweep by substring. Built from the shared prefix
 			// rather than typed here, so a rename cannot land in the producer and not in the sweeps (#227).
 			// From the VENUE that will build the container, not from the local adapter reached for directly:
@@ -1517,7 +1602,7 @@ export function keeperHoldState(job, at) {
 	return { at, since, startedMs };
 }
 
-export function createWorker({ connection, name, stopContainer, containerName, hostQueue = null, checkLease = null, scopeLease = null, checkTimeoutMs, concurrency, getSettings, redis, deps, recordRun, settledRecord = null, limiter, pauseUntil, scopedLimits, projects, jobSizeEnv = {}, allocation = null, inFlight = makeInFlight(), waitState, afterMaxMs, checkSlots = makeInFlight(), checkSlotCount, concurrencyNow, intervalMs, maxWaitMs, maxChecks, maxFaults, hostSlots = makeInFlight(), endpointSlots = makeInFlight(), endpointLease = null, modelEndpoints = null, overlayModels, extraClosers = [], hostBudget: hostBudgetOptions = null }) {
+export function createWorker({ connection, name, stopContainer, containerName, hostQueue = null, checkLease = null, scopeLease = null, checkTimeoutMs, concurrency, getSettings, redis, deps, recordRun, settledRecord = null, previousRecord = null, limiter, pauseUntil, scopedLimits, projects, jobSizeEnv = {}, allocation = null, inFlight = makeInFlight(), waitState, afterMaxMs, checkSlots = makeInFlight(), checkSlotCount, concurrencyNow, intervalMs, maxWaitMs, maxChecks, maxFaults, hostSlots = makeInFlight(), endpointSlots = makeInFlight(), endpointLease = null, modelEndpoints = null, overlayModels, extraClosers = [], hostBudget: hostBudgetOptions = null, runningJobs = makeRunningJobs() }) {
 	// One Worker per queue name (issue #57). A host-affine job -- one whose folder, secret resolver or wait
 	// check lives on THIS machine -- is enqueued to `pi-jobs@<name>` rather than filtered for at pickup,
 	// because BullMQ has no selective pop and the put-it-back alternative does not work: promotion out of
@@ -1626,6 +1711,10 @@ export function createWorker({ connection, name, stopContainer, containerName, h
 			// The run-record lookup a stalled job is checked against before it can run again (see the processor's
 			// first gate). `null` in a bare wiring, which keeps today's behaviour: the job runs.
 			settledRecord,
+			previousRecord,
+			// Issue #599, phase 2: SHARED across both workers for the host slot's reason: the registry row lists what this
+			// HOST runs, and two maps would each list half.
+			runningJobs,
 		});
 
 		// Issue #464: only a connection `parseConnection` built, which judges and pins the Valkey it dials.
@@ -1652,6 +1741,8 @@ export function createWorker({ connection, name, stopContainer, containerName, h
 	primary.hostWorker = workers[1] ?? null;
 	// Issue #596, phase 2: the host budget, for the registry beat's thunks (start.mjs) and doctor-facing snapshots.
 	primary.hostBudget = hostBudget;
+	// Issue #599, phase 2: the jobs this host runs now, for the registry beat's `jobs` thunk (start.mjs).
+	primary.runningJobs = runningJobs;
 
 	const stop = async () => {
 		// Abort active jobs (=> docker stop via onAbort), then close. Without the cancel,

package/src/job-size.mjs

@@ -54,6 +54,16 @@ export const JOB_MEMORY_CEILING_MIB = 1024 * 1024;
 export const JOB_CPUS_FLOOR_CENTI = 25;
 /** The largest CPU size: 256, as hundredths, because round(256 x 1024) is 262144, the top of `--cpu-shares`. */
 export const JOB_CPUS_CEILING_CENTI = 256 * 100;
+/**
+ * The most a host can have, as a run record's `capacity` may say it (issue #599, phase 4's review): a value past these is
+ * not a host but a fault or a forgery, so the writer records it as unknown and the capacity report counts a record that
+ * says it as unreadable, rather than judging a week against "1 of 1000000000 slots". The CPUs and the memory are the
+ * ceilings the runtime facts are read to (daemon-facts.mjs `cpuCount`, `memoryMiB`); the slots are as many of the
+ * smallest jobs (`JOB_CPUS_FLOOR_CENTI`) as those CPUs hold.
+ */
+export const HOST_CPUS_MAX = 4096;
+export const HOST_MEMORY_MAX_MIB = 64 * 1024 * 1024;
+export const HOST_SLOTS_MAX = (HOST_CPUS_MAX * 100) / JOB_CPUS_FLOOR_CENTI;
 /** The valid range of `--cpu-shares` on cgroup v2 (runc and crun clamp to it; 2 is the kernel's cgroup v1 minimum). */
 export const CPU_SHARES_MIN = 2;
 export const CPU_SHARES_MAX = 262144;
@@ -119,6 +129,12 @@ export function parseCpus(value) {
 	return centi;
 }
 
+/**
+ * The two never-fits refusals (index.mjs `SIZE_REFUSAL_COMMENTS`, issue #596), both decided before the job holds a slot.
+ * Here, beside the size they judge, so a leaf can read them; a test holds them equal to the processor's.
+ */
+export const SIZE_REFUSAL_REASONS = Object.freeze(["job-size-exceeds-host", "job-size-exceeds-share"]);
+
 /**
  * The one spelling of a memory size: `<n>g` when it is whole gigabytes, else `<n>m`. Every `--memory`, `--memory-swap`
  * and stored row is written by this function, and `container-spec.mjs`'s `memoryBytes` reads every value it can write