@edgehero/pi-dispatch 4.0.1 → 4.2.0

package/src/mcp-preflight.mjs

@@ -0,0 +1,262 @@
+/**
+ * The pickup's MCP question (REQ-MCP-OPERATOR-SERVERS, DES-MCP-EGRESS-PREFLIGHT): can this job use the overlay MCP
+ * servers its trigger names (`run.mcp`)? Answered before anything is spent (CONST-BUDGET-BEFORE-TOKENS), from the
+ * overlay's `mcp.json` read once for the job, and the answer carries the per-job document `prepare` writes to
+ * `/job/mcp.json`, so the servers the job connects are exactly the servers this check passed.
+ *
+ * One of:
+ *   { ok: true, document }        `document` null when the job names no server
+ *   { refused, name, why }        a determinate refusal, returned (CONST-RETRY-INFRA-ONLY): `refused` is the reason
+ *   { unavailable: code }         the overlay could not be read just now, an errno that may pass: retried
+ *
+ * The refusals, in the order they are asked:
+ *   mcp-list-invalid         the job's own list is not one the loader writes (queue data from another version, or a
+ *                            hand-added job);
+ *   mcp-config-invalid       the overlay's mcp.json cannot be read whole (or there is no overlay, or no file, when the
+ *                            job names a server other than `forge`);
+ *   mcp-server-unknown       a name the file does not offer, offers disabled, or refuses (doctor names why); or
+ *                            `forge` on a job that is not a github or gitlab one;
+ *   mcp-secret-reserved      a reference to a variable this deployment writes or pi reads for the job itself (a
+ *                            credential the job spends with, `providerKeyNames`; a minted forge token; the egress or
+ *                            runner variables): a server must never be handed the job's own credentials. Asked of
+ *                            every reference before the next rule;
+ *   mcp-secret-unmapped      a reference the job will not have: not a `run.secrets` name, and not a PI_FORWARD_ENV
+ *                            name the worker's environment holds a value for;
+ *   mcp-excluded             the trigger's own run.excludeTools leaves a server no way in that it had: its tools and
+ *                            its resources reachable only through tools it removed (`mcpRouteProblem`);
+ *   mcp-egress-unreachable   with the egress policy on, a streamable HTTP server the proxy would not let the job reach,
+ *                            or the forge server's API host (api.github.com, or the configured GitLab's) unlisted;
+ *   mcp-package-runner       with the egress policy on, a package runner whose registry the allowlist does not hold.
+ *
+ * `forge` (DES-FORGE-MCP) is not read from the overlay: its entry is the worker's (`forgeMcpServer`), so a job naming
+ * only it needs no mcp.json at all, and it is exempt from the two secret rules, its one reference being the forge token
+ * the worker itself writes into the container for this job. The overlay's top-level switches still govern it when the
+ * file is there, so a file that is there and cannot be read refuses it like any other server.
+ */
+import { allowlistEntryFor, egressRefusalFor, packageRunnerHosts } from "./egress-allowlist.mjs";
+import { FORGE_MCP_KINDS, FORGE_MCP_SERVER_NAME, forgeMcpEgressUrl, forgeMcpServer, gitlabUrlProblem, jobMcpDocument, MCP_SERVER_NAME_RE, readOverlayMcp } from "./mcp-config.mjs";
+import { MCP_SERVERS_MAX, mcpServerToolPattern } from "./triggers.mjs";
+
+/**
+ * Errnos a read of the overlay may pass on a second try. Restated from model-catalog.mjs `OVERLAY_TRANSIENT_READ_CODES`
+ * rather than imported, since that module loads pi's catalog; mcp-preflight.test.mjs holds the two equal.
+ */
+export const MCP_TRANSIENT_READ_CODES = new Set(["EIO", "EAGAIN", "EMFILE", "ENFILE"]);
+
+/** A variable reference in a pi config value, `$NAME` or `${NAME}`, anywhere in the string (pi's own grammar). */
+const CONFIG_REF_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/**
+ * The credentials a job is set up to spend with, as variable names: each builtin key variable of the providers it may
+ * call (`providers`: its main provider and the ones on its model list), and every variable the overlay models.json
+ * references anywhere (a custom provider's `apiKey` in any form, its headers, a model's or an override's headers),
+ * since pi reads each of them for model calls. A builtin provider the job cannot call (its model list does not name
+ * it, `jobProviders`) is not counted: its variable is one the operator may hand a server on purpose (`HF_TOKEN` for a
+ * Hugging Face MCP server), as `run.secrets` may. A custom provider whose key is a `!command` names no variable this
+ * can see: the operator who writes both files is the one who can avoid that pairing.
+ */
+export function providerKeyNames({ providers = [], candidatesOf = () => [], overlayModels = null } = {}) {
+	const names = new Set();
+	for (const provider of providers) for (const name of candidatesOf(provider) ?? []) if (typeof name === "string") names.add(name);
+	const walk = (value) => {
+		if (typeof value === "string") for (const match of value.matchAll(CONFIG_REF_RE)) names.add(match[1] ?? match[2]);
+		else if (value !== null && typeof value === "object") Object.values(value).forEach(walk);
+	};
+	walk(overlayModels);
+	return names;
+}
+
+/**
+ * The providers a job may call: its own, and each on its model list (the trigger's, else the deployment's), which the
+ * runner's model guard holds every call to. With no list there is no guard, and the job may call any provider whose
+ * key its container holds (a pi child of its own, `--provider` and all), so every builtin provider (`everyProvider`)
+ * counts. An operator who hands a server a provider's variable on purpose (`HF_TOKEN`) gives that trigger a list.
+ */
+export function jobProviders(job, { defaultProvider = null, allowedModels = null, everyProvider = [] } = {}) {
+	const list = Array.isArray(job?.models) ? job.models : Array.isArray(allowedModels) ? allowedModels : null;
+	const listed = list === null ? everyProvider : list.map((ref) => (typeof ref === "string" ? ref.split("/")[0] : ref?.provider));
+	return [...new Set([job?.provider ?? defaultProvider, ...listed].filter((p) => typeof p === "string" && p !== ""))];
+}
+
+/**
+ * The check, bound to this deployment. `reserved(job)` is the set of variable names the job's own container holds for
+ * itself; `hostEnv` is the worker's environment, which decides whether a PI_FORWARD_ENV name reaches the job at all;
+ * `allowlist()` and `endpoints()` are read only when a server needs them, and `allowlist()` throws what its read threw.
+ * `gitlabUrl` is the worker's configured GitLab URL (null when it serves no GitLab), which a gitlab job's forge server
+ * calls.
+ */
+export function makeMcpCheck({ globalPiDir, forwardEnv = [], hostEnv = {}, egress = false, reserved = () => new Set(), allowlist = () => [], endpoints = () => [], read = readOverlayMcp, gitlabUrl = null }) {
+	return (job) => {
+		const listed = job?.mcp;
+		if (listed === undefined) return { ok: true, document: null };
+		// The loader's shape, asked again: queue data is not always the current receiver's (an older or newer service,
+		// a hand-added job, a stored repeatable), and a list that is not one must neither pass as "none" nor reach the
+		// public comment. The name is withheld from the comment when it is not a valid name.
+		if (!Array.isArray(listed) || listed.length === 0 || listed.length > MCP_SERVERS_MAX || new Set(listed).size !== listed.length || listed.some((name) => typeof name !== "string" || !MCP_SERVER_NAME_RE.test(name))) {
+			return { refused: "mcp-list-invalid", name: null, why: "the job's run.mcp is not a list of server names the loader accepts" };
+		}
+		const names = listed;
+		const overlayNames = names.filter((name) => name !== FORGE_MCP_SERVER_NAME);
+		let parsed;
+		try {
+			parsed = read(globalPiDir || "");
+		} catch (error) {
+			if (!error?.mcpConfig && MCP_TRANSIENT_READ_CODES.has(error?.code)) return { unavailable: error.code };
+			return { refused: "mcp-config-invalid", name: null, why: error?.mcpConfig ? "the overlay's mcp.json cannot be read whole" : `the overlay's mcp.json cannot be read (${error?.code ?? "unreadable"})` };
+		}
+		if (parsed === null) {
+			if (overlayNames.length > 0) return { refused: "mcp-config-invalid", name: null, why: globalPiDir ? "the overlay holds no mcp.json" : "this deployment has no overlay (PI_GLOBAL_PI_DIR)" };
+			// Only `forge`: the overlay's defaults, as an empty file reads.
+			parsed = { autoEnableCodemode: true, codemodeModels: true, servers: {}, refused: [] };
+		}
+		const refusedHere = new Map(parsed.refused.map((r) => [r.name, r.problem]));
+		let servers = parsed.servers;
+		if (overlayNames.length !== names.length) {
+			// The kind is queue data like the list: a job from elsewhere naming `forge` on a kind with no forge server (or
+			// no forge token) is refused here, never handed another forge's entry.
+			if (!FORGE_MCP_KINDS.includes(job.kind)) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: "the forge's own server is offered to a github or gitlab job only" };
+			if (job.kind === "gitlab" && (typeof gitlabUrl !== "string" || gitlabUrl === "")) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: "this worker has no GitLab URL configured" };
+			const urlProblem = job.kind === "gitlab" ? gitlabUrlProblem(gitlabUrl) : null;
+			if (urlProblem !== null) return { refused: "mcp-server-unknown", name: FORGE_MCP_SERVER_NAME, why: `GITLAB_URL cannot be handed to the forge server: ${urlProblem}` };
+			servers = { ...parsed.servers, [FORGE_MCP_SERVER_NAME]: forgeMcpServer(job.kind, { gitlabUrl }) };
+		}
+		for (const name of overlayNames) {
+			const server = Object.hasOwn(servers, name) ? servers[name] : undefined;
+			if (!server) return { refused: "mcp-server-unknown", name, why: refusedHere.has(name) ? "the overlay's mcp.json refuses it" : "the overlay's mcp.json does not offer it" };
+			if (server.enabled === false) return { refused: "mcp-server-unknown", name, why: "the overlay's mcp.json turns it off" };
+		}
+		// A forwarded name reaches the job only when the worker holds a value for it (env-allowlist.mjs buildContainerEnv).
+		const forwarded = forwardEnv.filter((ref) => typeof hostEnv[ref] === "string" && hostEnv[ref] !== "");
+		const mapped = new Set([...Object.keys(job.secrets ?? {}), ...forwarded]);
+		let own;
+		try {
+			own = reserved(job);
+		} catch (error) {
+			// The overlay models.json read inside `reserved` that may pass on a retry: without it, a custom provider's
+			// credential would drop out of the set for this one pickup.
+			if (MCP_TRANSIENT_READ_CODES.has(error?.code)) return { unavailable: error.code };
+			throw error;
+		}
+		// The forge server is exempt from both rules: its one reference is the token the worker mints for this job and
+		// writes under exactly that name, which is the reason every other server is refused it.
+		for (const name of overlayNames) {
+			for (const ref of servers[name].refs) {
+				if (own.has(ref)) return { refused: "mcp-secret-reserved", name, why: `it references ${ref}, which this deployment uses for the job's own credentials` };
+			}
+		}
+		for (const name of overlayNames) {
+			for (const ref of servers[name].refs) {
+				if (!mapped.has(ref)) return { refused: "mcp-secret-unmapped", name, why: `it references ${ref}, which the trigger does not pass (run.secrets, or a PI_FORWARD_ENV name the worker holds a value for)` };
+			}
+		}
+		const cut = mcpRouteProblem(servers, names, new Set(Array.isArray(job.excludeTools) ? job.excludeTools : []), { autoEnableCodemode: parsed.autoEnableCodemode });
+		if (cut !== null) return { refused: "mcp-excluded", name: cut.name, why: cut.why };
+		if (egress) {
+			let list = null;
+			let declared = null;
+			// The allowlist read that may pass on a retry is retried, like the overlay's; any other failure refuses, since
+			// without the list no server outside a declared endpoint can be judged reachable.
+			const readList = () => {
+				try {
+					return allowlist();
+				} catch (error) {
+					if (MCP_TRANSIENT_READ_CODES.has(error?.code)) throw Object.assign(new Error("transient"), { transient: error.code });
+					throw Object.assign(new Error("unreadable"), { unreadable: error?.code ?? "unreadable" });
+				}
+			};
+			try {
+				for (const name of names) {
+					const server = servers[name];
+					if (name === FORGE_MCP_SERVER_NAME) {
+						// Its API host, judged as a streamable HTTP server's url is: the proxy sees the same CONNECT either way.
+						list ??= readList();
+						declared ??= endpoints();
+						const refusal = egressRefusalFor(forgeMcpEgressUrl(job.kind, { gitlabUrl }), { allowlist: list, endpoints: declared });
+						if (refusal !== null) return { refused: "mcp-egress-unreachable", name, why: refusal };
+					} else if (server.transport === "http") {
+						list ??= readList();
+						declared ??= endpoints();
+						const refusal = egressRefusalFor(server.url, { allowlist: list, endpoints: declared });
+						if (refusal !== null) return { refused: "mcp-egress-unreachable", name, why: refusal };
+					} else if (server.packageRunner) {
+						list ??= readList();
+						const missing = packageRunnerHosts(server.command).filter((host) => allowlistEntryFor(list, host) === null);
+						if (missing.length > 0) return { refused: "mcp-package-runner", name, why: `it fetches its server from ${missing.join(" and ")}, which egress-allowlist.conf does not hold` };
+					}
+				}
+			} catch (error) {
+				if (error?.transient) return { unavailable: error.transient };
+				if (error?.unreadable) return { refused: "mcp-egress-unreachable", name: null, why: `egress-allowlist.conf cannot be read (${error.unreadable})` };
+				throw error;
+			}
+		}
+		return { ok: true, document: jobMcpDocument({ ...parsed, servers }, names) };
+	};
+}
+
+/**
+ * A server's exposures as pi reads them (`getMcpToolExposure`): an exact tool name first, then the patterns in order,
+ * the first that matches winning, else the server's own. So a pattern after `*` never applies, and `*` replaces the
+ * default; any exact name and any earlier pattern may still match a tool.
+ */
+function exposuresOf(server) {
+	const own = server.exposure ?? "codemode";
+	const entries = Object.entries(server.toolExposure ?? {}).filter(([key]) => !key.startsWith("dispatch_"));
+	const tools = entries.filter(([key]) => !key.includes("*")).map(([, value]) => value);
+	let base = own;
+	for (const [key, value] of entries.filter(([key]) => key.includes("*"))) {
+		if (key === "*") {
+			base = value;
+			break;
+		}
+		tools.push(value);
+	}
+	return { own, tools: [base, ...tools] };
+}
+
+/**
+ * Whether each named server keeps a way in through the tools `excluded` leaves, as pi 1.1.0 routes them: a `direct` tool
+ * needs nothing; a `codemode` or `deferred` tool is reached by whichever discovery tool is active, since codemode calls
+ * both kinds and tool_search loads both, and pi activates codemode when some server has a codemode tool (and
+ * `autoEnableCodemode` is not false) and tool_search when some server has a deferred one; the resource tools take their
+ * server's own exposure, and a `hidden` server's resources are never offered. Judged only for what the trigger's
+ * exclusions take away: a server the overlay leaves no way in is the overlay's, not this trigger's to be refused for.
+ * Returns `{ name, why }` for the first server the exclusions cut off, or null.
+ */
+export function mcpRouteProblem(servers, names, excluded, { autoEnableCodemode = true } = {}) {
+	const routes = (removed) => {
+		const all = names.map((name) => exposuresOf(servers[name]));
+		const has = (kind) => all.some(({ own, tools }) => own === kind || tools.includes(kind));
+		const discovery = (!removed.has("codemode") && autoEnableCodemode !== false && has("codemode")) || (!removed.has("tool_search") && has("deferred"));
+		const reach = (exposure) => exposure === "direct" || ((exposure === "codemode" || exposure === "deferred") && discovery);
+		const widest = ["direct", "codemode", "deferred"].find((kind) => all.some(({ own }) => own === kind)) ?? "hidden";
+		return names.map((name, i) => {
+			const { own, tools } = all[i];
+			const toolRoute = !removed.has(mcpServerToolPattern(name)) && tools.some(reach);
+			// pi registers the resource tools once, with the widest exposure among the servers that offer resources
+			// and are not hidden (syncResourceTools), and read_mcp_resource reads any of them. Whether a server lists
+			// resources is unknown until it connects, so each one that is not hidden is assumed to.
+			const resourceRoute = !removed.has("read_mcp_resource") && own !== "hidden" && reach(widest);
+			return toolRoute || resourceRoute;
+		});
+	};
+	const before = routes(new Set());
+	const after = routes(excluded);
+	const i = names.findIndex((_, k) => before[k] && !after[k]);
+	return i < 0 ? null : { name: names[i], why: "run.excludeTools removes every tool that reaches it (its own, the discovery tools that reach them, and read_mcp_resource)" };
+}
+
+/**
+ * The refusal's public sentence, per reason. Fixed text: the comment posts on the issue, and `why` can name an
+ * internal host or a variable, which belong in the worker's log, not in a thread anyone can read.
+ */
+export const MCP_REFUSAL_COMMENT = Object.freeze({
+	"mcp-list-invalid": "the list this job carries is not one the triggers file's loader writes (a service in this deployment may be at another version)",
+	"mcp-config-invalid": "this deployment's list of MCP servers (mcp.json in the overlay) cannot be used",
+	"mcp-server-unknown": "this deployment does not offer that server",
+	"mcp-secret-reserved": "that server would be handed a credential this deployment keeps for the job itself",
+	"mcp-secret-unmapped": "a credential that server needs is not passed by this trigger",
+	"mcp-excluded": "this trigger's run.excludeTools removes every way the job could reach that server",
+	"mcp-egress-unreachable": "the egress policy does not let a job reach that server",
+	"mcp-package-runner": "the egress policy does not let a job reach the registry that server is fetched from",
+});

package/src/model-endpoints.mjs

@@ -363,7 +363,12 @@ export function modelEntryOf(models, provider, modelId) {
 	return { entry, defined, override: override !== null && typeof override === "object" ? override : null };
 }
 
-function matching(baseUrl, endpoints) {
+/**
+ * The declared endpoints a URL dials: those whose host AND port `baseUrlTarget` reads from it. The one match, for a
+ * model's baseUrl here, an MCP server's url at the pickup's egress check (`egressRefusalFor`) and doctor's endpoint
+ * probes alike, so the three cannot disagree on which endpoint a URL is.
+ */
+export function endpointsAt(baseUrl, endpoints) {
 	const target = baseUrlTarget(baseUrl);
 	if (target === null || !Array.isArray(endpoints)) return [];
 	return endpoints.filter((e) => e.host === target.host && e.port === target.port);
@@ -380,7 +385,7 @@ export function endpointsForModel({ models, provider, modelId, endpoints }) {
 	if (entry === null) return [];
 	const model = modelsOf(entry).find((m) => m.id === modelId);
 	const baseUrl = typeof model?.baseUrl === "string" ? model.baseUrl : entry.baseUrl;
-	return matching(baseUrl, endpoints);
+	return endpointsAt(baseUrl, endpoints);
 }
 
 /**
@@ -391,7 +396,7 @@ export function endpointsForModel({ models, provider, modelId, endpoints }) {
 export function endpointsForProvider({ models, provider, endpoints }) {
 	const entry = providerOf(models, provider);
 	if (entry === null) return [];
-	return modelsOf(entry).map((m) => ({ modelId: m.id, endpoints: matching(typeof m.baseUrl === "string" ? m.baseUrl : entry.baseUrl, endpoints) }));
+	return modelsOf(entry).map((m) => ({ modelId: m.id, endpoints: endpointsAt(typeof m.baseUrl === "string" ? m.baseUrl : entry.baseUrl, endpoints) }));
 }
 
 /**

package/src/outbox.mjs

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { readFlowGate as realReadFlowGate } from "./flow-gate.mjs";
 import { chainedJobId } from "./job-id.mjs";
 import { enqueueLocalJob } from "./queue.mjs";
+import { withoutMcpExclusions } from "./triggers.mjs";
 
 /**
  * The outbox chain collector: the host-side reader of a completed LOCAL parent's `/outbox`, the
@@ -207,7 +208,9 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// parent would chain a child that can edit and run bash, a widening no operator wrote.
 					// Off `job.data`, never off `req` -- the request file can neither set nor drop it (explicit
 					// property reads only, above), so the agent cannot widen its child by omitting a key.
-					excludeTools: job.data?.excludeTools,
+					// Less the names of the parent's MCP tools: the child connects no server (`mcp` below), its runner knows
+					// none of them, and they would refuse it at start while removing nothing.
+					excludeTools: withoutMcpExclusions(job.data?.excludeTools),
 					// `secrets`/`secretsProfile` are deliberately ABSENT, and the two lines above are exactly why
 					// this comment exists: their reasoning reads as though it should apply here too, and it must
 					// not. An image and a skills directory are toolchain; a resolved credential is a capability.
@@ -219,6 +222,9 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// `portfolio` (issue #505) is ABSENT for the same reason, and more plainly: it is budget authority, granted
 					// to one cron trigger the operator reviewed. A child is an agent's request, so inheriting the flag would let
 					// a portfolio job queue a second plan writer of its own choosing.
+					// `mcp` (REQ-MCP-OPERATOR-SERVERS) is ABSENT for the secrets' reason: a server is reached with the
+					// credentials its trigger maps, a capability granted to the trigger the operator reviewed. A child
+					// without it connects no server, which is the narrowing direction.
 					chainDepth: childDepth,
 					parentJobId: job.id,
 					// chainedJobId deliberately does NOT take the image: the child's identity is (parent, flow, task).

package/src/prepare.mjs

@@ -1,8 +1,9 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveBackendName } from "./backend-registry.mjs";
 import { ensureJobsDir } from "./config.mjs";
+import { JOB_MCP_FILE } from "./mcp-config.mjs";
 import { resolveJobImage } from "./image-preflight.mjs";
 import { retainJobDir } from "./sandbox-store.mjs";
 import { prepareGithubWorkspace } from "./prepare-github.mjs";
@@ -15,6 +16,7 @@ import { buildAzurePrompt } from "./azure-prompt.mjs";
 import { prepareLocalWorkspace } from "./prepare-local.mjs";
 import { copySkillTree } from "./copy-tree.mjs";
 import { recordedJobSize } from "./job-size.mjs";
+import { scheduledForMillis } from "./repeat-slot.mjs";
 
 /**
  * The subdirectory of the per-job dir a trigger's injected skills are copied into, so they reach the
@@ -83,7 +85,7 @@ export function makePrepareWorkspace({
 	removeDir = (dir) => rmSync(dir, { recursive: true, force: true }),
 }) {
 	ensureDir(jobsDir);
-	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false, size = null } = {}) {
+	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false, size = null, mcp = null } = {}) {
 		ensureDir(jobsDir);
 		const jobDir = mkdtempSync(join(jobsDir, "job-"));
 		// Issue #524: a THROW out of anything below leaves `jobDir` to nobody. The processor tears down only what
@@ -93,7 +95,7 @@ export function makePrepareWorkspace({
 		// covers the thrown ones, in one place for every kind, rather than in each preparer that can throw.
 		// A retry makes a fresh directory, so nothing is lost by removing this one.
 		try {
-			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size });
+			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size, mcp });
 		} catch (error) {
 			// GUARDED: a removal that fails (a busy mount, a permission flipped mid-job) must never replace the error
 			// that is the job's actual outcome. The directory is then left, which is what happened before this catch.
@@ -104,7 +106,7 @@ export function makePrepareWorkspace({
 		}
 	};
 
-	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size }) {
+	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size, mcp }) {
 		// The trigger's injected skills (REQ-PER-TRIGGER-SKILLS, issue #60), COPIED here rather than
 		// mounted, and copied ONCE for every job kind because this is where local and forge converge.
 		//
@@ -125,6 +127,13 @@ export function makePrepareWorkspace({
 			// a host path by a later edit (the same shape packages.mjs's `dropped` record has).
 			log("trigger_skills_injected", { dirs: injected.dirs, files: injected.files, bytes: injected.bytes });
 		}
+		// The job's MCP servers (REQ-MCP-OPERATOR-SERVERS), as the processor's check passed them: written here, beside the
+		// injected skills, for their reason (no new mount, and fixed for the life of the job). References only, never a
+		// value (mcp-config.mjs `jobMcpDocument`), and read-only to the job like everything under /job.
+		if (mcp) {
+			writeFileSync(join(jobDir, JOB_MCP_FILE), `${JSON.stringify(mcp, null, 2)}\n`, { mode: 0o444 });
+			log("mcp_config_written", { servers: Object.keys(mcp.servers).length, refs: Object.values(mcp.refs).reduce((n, list) => n + list.length, 0) });
+		}
 		// What `cleanup` needs to retain this run's directory, stamped here because this is the only place
 		// that holds all of it at once. Applied to the RESULT rather than mutated in, so a preparer's
 		// `{ outcome: "policy" }` refusal -- which carries no jobDir -- is passed through untouched.
@@ -214,15 +223,6 @@ function localEventContext(job, queueJobId, findPreviousRun) {
 	return { source: "manual" };
 }
 
-/** Parse the millis out of a `repeat:<id>:<millis>` BullMQ scheduled jobId, or null. */
-function scheduledForMillis(queueJobId) {
-	if (typeof queueJobId !== "string" || !queueJobId.startsWith("repeat:")) return null;
-	const tail = queueJobId.slice(queueJobId.lastIndexOf(":") + 1);
-	if (tail === "") return null;
-	const millis = Number(tail);
-	return Number.isFinite(millis) ? millis : null;
-}
-
 /**
  * Attach the sandbox stamp to a successful prepare, and to nothing else.
  *

package/src/processor.mjs

@@ -7,6 +7,7 @@ import { unqualifiedScope } from "./pause-windows.mjs";
 import { PROJECT_CAP_REASON } from "./scoped-limits.mjs";
 import { DEFAULT_SECRETS_PROFILE, secretsArmed } from "./secrets.mjs";
 import { RESERVED_ENV_NAMES } from "./triggers.mjs";
+import { MCP_REFUSAL_COMMENT } from "./mcp-preflight.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
 import { COST_CAP_WHYS, EXIT_OOM_KILLED, RUNNER_POLICY_REASONS } from "./run-history.mjs";
 import { DEFAULT_EGRESS_PROXY } from "./egress.mjs";
@@ -129,6 +130,16 @@ export const TERMINAL_COMMENTS = {
 	"model-not-allowed": "Stopped: the run tried to call an AI model this trigger does not allow, or to change an AI request in a way it does not allow, so the call was not made. Partial work may exist. Not retried.",
 	"cost-cap-unenforceable": "Stopped: this run has a cost limit, and the job image could not enforce it before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
 	"model-policy-unenforceable": "Stopped: this run is limited to certain AI models, and the job image could not enforce that before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
+	// The runner's refusals of the job's MCP servers, each before the prompt. Never the server's name, its host or a
+	// variable: the exit line carries the name and the cause in its message, which the worker never parses (it reaches
+	// the worker's log as the container's output). Each says what the operator can check; the issue's author can act on
+	// none of it.
+	"mcp-unavailable": "Stopped: an MCP server this trigger names could not be used (it did not start, failed its handshake or refused the connection, an authentication error among them), so the run ended before the agent started. The operator needs to check that server and the job image. Not retried.",
+	"mcp-config-invalid": "Stopped: the list of MCP servers the worker wrote for this job is not one the job image accepts, so the run ended before the agent started. The operator needs to run a worker and a job image of the same release. Not retried.",
+	"mcp-config-mismatch": "Stopped: the MCP servers the worker wrote for this job are not the ones it named for it, so the run ended before the agent started. The operator needs to run a worker and a job image of the same release. Not retried.",
+	"mcp-secret-missing": "Stopped: a credential an MCP server this trigger names needs was not set inside the job, so the run ended before the agent started. The operator needs to check the secrets this trigger passes. Not retried.",
+	"mcp-command-missing": "Stopped: the job image does not have the program an MCP server this trigger names runs, so the run ended before the agent started. The operator needs to install that server in the job image or the overlay. Not retried.",
+	"mcp-shadowed": "Stopped: another extension in this job registers a tool or command that only the job's MCP servers may, so the run ended before the agent started. The operator needs to remove that extension or this trigger's MCP servers. Not retried.",
 	// Issue #596. Never the size or the project: both are operator configuration, and the reader may be an issue author
 	// who can act on neither. The worker log and the run record carry them.
 	[EXIT_OOM_KILLED]: "Stopped: the job's container ran out of memory and was stopped. Partial work may exist. Not retried, because the same size would stop the same way. The operator can raise this job's memory size.",
@@ -307,6 +318,10 @@ export async function runJob(job, deps) {
 		// would leave an INJECTED resolver running on every job, which is how a probe nobody wanted starts
 		// spawning a subprocess per delivery to learn nothing.
 		resolveSecrets = async (job) => ({ profileUnknown: job.secretsProfile ?? DEFAULT_SECRETS_PROFILE }),
+		// (job) => { ok, document } | { refused, name, why } | { unavailable: code } (REQ-MCP-OPERATOR-SERVERS,
+		// mcp-preflight.mjs). The default passes a job that names no server and refuses one that does, so a wiring that
+		// forgot the check can never run a job without the servers its trigger names.
+		checkMcp = (job) => (job?.mcp !== undefined ? { refused: "mcp-config-invalid", name: null, why: "this worker reads no MCP servers" } : { ok: true, document: null }),
 		// #227. Which backends this deployment BLESSED (PI_BACKENDS). Defaults to the one name every
 		// deployment already runs rather than to admit-everything: a wiring that says nothing blesses
 		// `local` only, so a job naming anything else is refused instead of running somewhere the operator
@@ -491,7 +506,7 @@ export async function runJob(job, deps) {
 				// Three causes, the likeliest first (PR #536's review, round 3, made the check strict): the trigger gained the
 				// field after this job was queued, a service is below the version that carries it, or one still reads an
 				// older copy of the triggers file. The first is fixed by re-running the job, so the comment says so.
-				await comment(job, `Refused: this trigger sets \`run.${skew.field}\`, but the job reached the worker without it, so it would have run without that limit. Either the trigger changed after this job was queued (re-run it), or a service in this deployment is stale: below the version that carries the field, or still reading an older copy of the triggers file and in need of a restart. Not run.`);
+				await comment(job, `Refused: this trigger sets \`run.${skew.field}\`, but the job reached the worker without it, so it would have run as though the trigger did not set it. Either the trigger changed after this job was queued (re-run it), or a service in this deployment is stale: below the version that carries the field, or still reading an older copy of the triggers file and in need of a restart. Not run.`);
 				log("refused_trigger_skew", { triggerIndex: job.trigger?.matched?.index ?? null, field: skew.field, causes: "trigger-changed-after-queue-or-stale-service" });
 				return { outcome: "policy", reason: "trigger-skew", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false };
 			}
@@ -974,6 +989,25 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: "skills-dir-missing", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
 
+		// REQ-MCP-OPERATOR-SERVERS. A trigger that named MCP servers its job cannot use would run its flow without them,
+		// or hand a server the job's own credentials, or open a connection the egress proxy refuses at its first call:
+		// each a plausible report and a clean exit. One read of the overlay's mcp.json, no credential and no network, so
+		// it sits with the free refusals before the secrets resolver (the one gate that spawns) and before anything that
+		// spends (CONST-BUDGET-BEFORE-TOKENS). Its answer carries the per-job document prepare writes, so the servers the
+		// job connects are exactly the ones this passed.
+		const mcpChecked = checkMcp(job);
+		if (mcpChecked.unavailable) {
+			throw new InfraRetry(`an overlay file the MCP check reads (mcp.json, models.json or egress-allowlist.conf) could not be read just now (${mcpChecked.unavailable})`, { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+		}
+		if (mcpChecked.refused) {
+			// The server NAME is the operator's own configuration, the same class as the image ref on the image refusal.
+			// `why` can name an internal host or a variable (never a value, a url's path or its query), so it goes to the
+			// worker's log and the public comment says only which rule refused.
+			await comment(job, `Refused: this trigger names MCP server${mcpChecked.name ? ` "${mcpChecked.name}"` : "s"} in \`run.mcp\`, and ${MCP_REFUSAL_COMMENT[mcpChecked.refused] ?? "it cannot be used"}. The job would have run without the servers its flow was written against; the worker's log says why (\`refused_mcp\`). Not run.`);
+			log("refused_mcp", { kind: job.kind ?? null, reason: mcpChecked.refused, server: mcpChecked.name ?? null, why: mcpChecked.why });
+			return { outcome: "policy", reason: mcpChecked.refused, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
 		// REQ-TRIGGER-SECRETS. A trigger that named secret references the worker cannot resolve would run its
 		// flow with those variables UNSET, get a 401 from whatever it was meant to reach, write a plausible
 		// report about why the integration is down, and exit 0.
@@ -1107,7 +1141,7 @@ export async function runJob(job, deps) {
 		// `podmanStore` (issue #429) only where the venue's job user carried one: the podman store the container ran in.
 		// `portfolio` (issue #505) only for a job the gate above confirmed: prepare then writes /job/portfolio.json, after
 		// asking the live file once more. Absent otherwise, so every other job's prepare call is unchanged.
-		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}), ...(portfolio ? { portfolio: true } : {}), ...(jobSize ? { size: jobSize } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
+		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}), ...(portfolio ? { portfolio: true } : {}), ...(jobSize ? { size: jobSize } : {}), ...(mcpChecked.document ? { mcp: mcpChecked.document } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
 
 		// A determinate prepare refusal -- sha-gone (the default branch advanced past the resolved tip),
 		// or a `pi-*` materialiser cap breach (the repo's .pi/ is too large to place in /job, issue #60)

package/src/queue.mjs

@@ -176,7 +176,7 @@ export function swallowedRunSentence(jobId, existing) {
 	return `an identical run was queued${hhmm} as ${jobId} (${existing?.state ?? "already queued or done"}); nothing new was queued.`;
 }
 
-async function addLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, models, maxCostUsd, image, backend, excludeTools, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, enqueueNonce, now = new Date() }) {
+async function addLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, models, maxCostUsd, image, backend, excludeTools, mcp, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, enqueueNonce, now = new Date() }) {
 	const minute = now.toISOString().slice(0, 16); // YYYY-MM-DDTHH:MM -- the dedup window
 	// A caller-supplied jobId (the outbox collector's retry-idempotent chainedJobId) wins; otherwise the
 	// minute-windowed localJobId is the dedup key. A command job (issue #189) fills the flow slot with
@@ -217,6 +217,7 @@ async function addLocalJob(queue, { folder, flow, task, command, provider, model
 		// same reason: `trigger` is copied verbatim into /job/event.json, and a permission boundary is the
 		// worker's business, never agent-visible input to reason about.
 		...(excludeTools !== undefined && { excludeTools }),
+		...(mcp !== undefined && { mcp }),
 		// The host directory of operator-authored skills this trigger injects (REQ-PER-TRIGGER-SKILLS).
 		// Conditional like `image`, so an unflagged job's data stays byte-identical, and at JOB level rather
 		// than inside `trigger` because a worker-host path is an execution knob, not a fact about the
@@ -310,7 +311,7 @@ export async function enqueueGitLabJob(queue, fields) {
  * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
  * has always been.
  */
-export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, models, maxCostUsd, packages, image, backend, excludeTools, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, models, maxCostUsd, packages, image, backend, excludeTools, mcp, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
 	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
 	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
 	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
@@ -351,6 +352,7 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// same reason: `trigger` is copied verbatim into /job/event.json, and a permission boundary is the
 		// worker's business, never agent-visible input to reason about.
 		...(excludeTools !== undefined && { excludeTools }),
+		...(mcp !== undefined && { mcp }),
 		// #501. The trigger's per-job dollar cap, as written. Conditional like `excludeTools`, at JOB level for its
 		// reason, and a narrowing like it: the worker runs the job under the smaller of this and the deployment cap.
 		...(maxCostUsd !== undefined && { maxCostUsd }),

package/src/repeat-slot.mjs

@@ -0,0 +1,13 @@
+/**
+ * The scheduled-for instant of a BullMQ job scheduler's job, read from the deterministic `repeat:<id>:<millis>` id it
+ * mints (DES-CRON-VIA-BULLMQ-SCHEDULER). A leaf module, so the run record and the prepare step read one parser.
+ */
+
+/** Parse the millis out of a `repeat:<id>:<millis>` BullMQ scheduled jobId, or null. */
+export function scheduledForMillis(queueJobId) {
+	if (typeof queueJobId !== "string" || !queueJobId.startsWith("repeat:")) return null;
+	const tail = queueJobId.slice(queueJobId.lastIndexOf(":") + 1);
+	if (tail === "") return null;
+	const millis = Number(tail);
+	return Number.isFinite(millis) ? millis : null;
+}

package/src/reserved-env.mjs

@@ -43,6 +43,7 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_FLOW",
 	"PI_COMMAND",
 	"PI_EXCLUDE_TOOLS",
+	"PI_MCP_SERVERS",
 	// Issues #501, #502: the per-job dollar cap (written by the worker since #501, from the trigger's and the
 	// deployment's caps) and the allowed-model list (reserved until #502 writes it). Neither can be bound through
 	// `run.secrets`: a trigger setting its own cap, or its own list, would be the policy choosing itself.

package/src/run-container.mjs

@@ -146,6 +146,8 @@ export function makeRunContainer({
 			// non-empty validated array; the guard is the same defensive shape `flow` above wears, so a
 			// hand-built job with junk in the field emits no variable rather than an empty one.
 			excludeTools: Array.isArray(job.excludeTools) && job.excludeTools.length > 0 ? job.excludeTools : undefined,
+			// REQ-MCP-OPERATOR-SERVERS: the trigger's MCP server names, off `job` like excludeTools.
+			mcpServers: Array.isArray(job.mcp) && job.mcp.length > 0 ? job.mcp : undefined,
 			// Issue #502: the effective allowed-model list, off `job` like excludeTools. index.mjs `effectiveJobOf` folds
 			// the deployment's PI_ALLOWED_MODELS in under the trigger's own, so `job.models` is already the one list.
 			allowedModels: Array.isArray(job.models) && job.models.length > 0 ? job.models : null,

package/src/run-earlier.mjs

@@ -0,0 +1,29 @@
+/**
+ * The rule for a run record's `earlier` (issue #599, INT-RUN-HISTORY-FILE-CONTRACT), in a module that imports only the
+ * worker name rule, so the record writer (run-history.mjs, which re-exports both names) and the capacity report, a pure
+ * reader, rebuild it with ONE validator.
+ */
+
+import { WORKER_NAME_RE } from "./worker-name.mjs";
+
+const recordInt = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : null);
+
+/** The most earlier attempts a record carries: the newest are kept. */
+export const EARLIER_MAX = 4;
+
+/** One earlier attempt as a record carries it, or null: a worker name, two canonical ISO instants in order, two sizes. */
+function earlierEntry(e) {
+	if (e === null || typeof e !== "object" || Array.isArray(e)) return null;
+	const instant = (v) => (typeof v === "string" && Number.isFinite(Date.parse(v)) && new Date(Date.parse(v)).toISOString() === v ? v : null);
+	const startedAt = instant(e.startedAt);
+	const endedAt = instant(e.endedAt);
+	if (typeof e.host !== "string" || !WORKER_NAME_RE.test(e.host) || startedAt === null || endedAt === null || Date.parse(endedAt) < Date.parse(startedAt)) return null;
+	return { host: e.host, startedAt, endedAt, memMiB: recordInt(e.memMiB), cpuCenti: recordInt(e.cpuCenti) };
+}
+
+/** A record's `earlier`, rebuilt: the valid entries, the newest `EARLIER_MAX` of them, or null when none is. */
+export function recordedEarlier(list) {
+	if (!Array.isArray(list)) return null;
+	const kept = list.map(earlierEntry).filter((e) => e !== null).slice(-EARLIER_MAX);
+	return kept.length > 0 ? kept : null;
+}