@edgehero/pi-dispatch 4.0.1 → 4.2.0

package/src/start.mjs

@@ -25,6 +25,7 @@ import { builtinModel, checkModelsKnown } from "./model-catalog.mjs";
 import { capabilityTokens, serializeCaps } from "./capabilities.mjs";
 import { cronFingerprint } from "./fingerprint.mjs";
 import { makeHostRegistry } from "./host-registry.mjs";
+import { liveJobsFields, liveJobsOf } from "./live-jobs.mjs";
 import { budgetField, readUserServiceLimits } from "./host-budget.mjs";
 import { makeCpuReserve, reservePlan } from "./cpu-reserve.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
@@ -61,9 +62,12 @@ import { PODMAN_BOOT_REFUSING_CAUSES, PODMAN_INFO_TIMEOUT_MS, cachedPodmanInfo,
 import { PODMAN_RESTART_HOLD_EXPIRED, makePodmanServiceReader, onceFs, makeRootfulMemory, observeHost, observeRootfulConf, readRootfulService, rootfulConfRefusal, rootfulConfRetries, rootfulUnreadList, runtimeObservationKey } from "./runtime-observations.mjs";
 
 import { makeRunContainer } from "./run-container.mjs";
-import { resolveProviderCredential } from "./env-allowlist.mjs";
+import { piProviders, providerKeyCandidates, resolveProviderCredential } from "./env-allowlist.mjs";
+import { parseAllowlist } from "./egress-allowlist.mjs";
+import { MCP_TRANSIENT_READ_CODES, jobProviders, makeMcpCheck, providerKeyNames } from "./mcp-preflight.mjs";
+import { RESERVED_ENV_NAMES } from "./triggers.mjs";
 import { makeSecretsResolver } from "./secrets.mjs";
-import { buildRecord, EXIT_OOM_KILLED, makeFindPreviousRun, makeLogReaper, makeLogSink, makeReadRecord, makeRecordWriter, makeSettledRecord, RUNNER_POLICY_REASONS, sanitizeJobId } from "./run-history.mjs";
+import { buildRecord, EXIT_OOM_KILLED, makeFindPreviousRun, makeLogReaper, makeLogSink, makeReadRecord, makeRecordWriter, makeSettledRecord, newerRecord, RUNNER_POLICY_REASONS, sanitizeJobId, UNREADABLE_RECORD } from "./run-history.mjs";
 import { makeRunMirror, readMirroredRecord } from "./run-mirror.mjs";
 import { readOverlay, resolveSettings } from "./runtime-settings.mjs";
 import { usdFingerprint } from "./dollar-fingerprint.mjs";
@@ -1368,7 +1372,7 @@ export async function startWorker(
 	// would be bytes nothing reads. That is also what keeps a single-host deployment byte-identical, since
 	// no job then issues a single extra Valkey command.
 	const runMirror = config.workerNameDeclared ? makeRunMirrorFn({ redis, retentionDays: config.logRetentionDays, log }) : null;
-	const recordRun = ({ job, result, error, startedAt, endedAt, project, size = null }) => {
+	const recordRun = ({ job, result, error, startedAt, endedAt, project, size = null, capacity = null, earlier = null }) => {
 		// The project (issue #499) was resolved at the pickup gate and rides here as `project` (an id or null), so a live
 		// edit of projects.json mid-run cannot make the record disagree with what the job was counted against. A record
 		// path that ends BEFORE the pickup gate (the wait gate's refusals) passes none, and resolves from the live ref
@@ -1378,7 +1382,7 @@ export async function startWorker(
 		// four `recordRun` call sites byte-unchanged and `buildRecord` a pure function of its arguments.
 		// The default venue rides the same way and for the same reason (#277): it is the value the registry
 		// below is built with, so the record resolves a job's venue exactly as dispatch does.
-		const record = buildRecord({ job, result, error, startedAt, endedAt, host: config.workerName, defaultBackend: config.defaultBackend, project: projectId, size });
+		const record = buildRecord({ job, result, error, startedAt, endedAt, host: config.workerName, defaultBackend: config.defaultBackend, project: projectId, size, capacity, earlier });
 		writeRecord(record);
 		// STRICTLY AFTER the file, and deliberately not awaited. After, because a crash between the two must
 		// leave a record with no fleet row rather than a fleet row with no record -- the mirror is a VIEW,
@@ -1399,10 +1403,23 @@ export async function startWorker(
 	// The record read back, for a job the queue lost the lock of after it finished (DES-TERMINAL-COMMENTS-AND-FAILURE-HOOK,
 	// CONST-RETRY-INFRA-ONLY): this host's own file first, then the fleet's copy where a mirror is armed, because the
 	// host that meets the stalled job need not be the one that ran it. A single host has no mirror and needs none.
+	const readRecord = makeReadRecord({ logsDir: config.logsDir });
 	const settledRecord = makeSettledRecord({
-		readRecord: makeReadRecord({ logsDir: config.logsDir }),
+		readRecord,
 		readMirrored: runMirror ? (jobId) => readMirroredRecordFn(redis, sanitizeJobId(jobId)) : null,
 	});
+	// The record a retry (or a pickup after a stall) is about to replace (issue #599), read BOTH ways: this host's file and
+	// the fleet's copy where a mirror is armed. Both, because each host keeps its own file: a job that ran on A, then B,
+	// then A again finds A's stale first attempt locally while B's second is in the mirror. `newerRecord` keeps the higher
+	// attempt (a tie: the later end). Its slot interval rides the new record as `earlier`. Never rejects: unreadable or
+	// unreachable is no record from that side.
+	const previousRecord = async (jobId) => {
+		const read = readRecord(jobId);
+		const local = read === UNREADABLE_RECORD ? null : read;
+		if (!runMirror) return local;
+		const mirrored = await readMirroredRecordFn(redis, sanitizeJobId(jobId)).catch(() => null);
+		return newerRecord(local, mirrored === UNREADABLE_RECORD ? null : mirrored);
+	};
 
 	// INT-CONFIG-OVERLAY-CONTRACT: the worker reads the runtime-settings overlay at EACH job start, so this
 	// closure -- not a value frozen at boot -- is what the processor calls per job. It resolves the fourteen
@@ -1618,6 +1635,18 @@ export async function startWorker(
 		const snap = worker?.hostBudget?.snapshot?.();
 		return Number.isSafeInteger(snap?.[key]) ? String(snap[key]) : "";
 	};
+	// Issue #599, phase 2: the jobs this host runs now and its budget's orphans, oldest first, as the row's two fields
+	// (`live-jobs.mjs`). Without a budget there is no ledger, so no orphan, and the list is the in-flight map alone.
+	const liveJobsNow = () => {
+		const read = (fn) => {
+			try {
+				return fn() ?? [];
+			} catch {
+				return [];
+			}
+		};
+		return liveJobsFields(liveJobsOf({ running: read(() => worker?.runningJobs?.list?.()), budgetEntries: read(() => worker?.hostBudget?.entries?.()) }));
+	};
 	// NOT awaited, and that is load-bearing rather than an optimisation. `makeRedisClient` sets
 	// `maxRetriesPerRequest: null` -- required for BullMQ's blocking connections -- which means a command
 	// issued against an unreachable server QUEUES FOREVER instead of rejecting. Awaiting the first beat
@@ -1684,6 +1713,14 @@ export async function startWorker(
 		heldMemMiB: () => snapshotField("heldMemMiB"),
 		heldCpuCenti: () => snapshotField("heldCpuCenti"),
 		budgetRunning: () => snapshotField("running"),
+		// Issue #599, phase 2: the jobs waiting for the budget ("" without one), and the jobs this host runs now: `jobs` is
+		// JSON of at most 32 `{ id, p, m, c, at, o? }` (job id, project id or null, size integers, admission millis, 1 for an
+		// orphan), oldest first, `jobsMore` how many are not listed. Ids and integers only (live-jobs.mjs says why that
+		// meets the content rule). Each thunk builds the list again; the beat reads every thunk with no await between, so
+		// the two agree. "" before the worker exists.
+		waiters: () => snapshotField("waiters"),
+		jobs: () => (worker ? liveJobsNow().jobs : ""),
+		jobsMore: () => (worker ? liveJobsNow().jobsMore : ""),
 		budgetHolds: () => snapshotField("holds"),
 		budgetOrphans: () => snapshotField("orphans"),
 		// whether the boot listing of the job containers left from before this worker started has been read
@@ -2059,6 +2096,7 @@ export async function startWorker(
 		redis,
 		recordRun,
 		settledRecord,
+		previousRecord,
 		extraClosers,
 		// REQ-SCOPED-PAUSE-WINDOWS: the processor defers a job whose folder/repo is inside an active window.
 		// Reads the live-reloaded ref, so an operator edit takes effect on the next job without a restart.
@@ -2221,6 +2259,42 @@ export async function startWorker(
 			// injected env they were not, which is the divergence this file already calls out by name for
 			// sessionsDir. One deployment value, one place, same rule as the profiles below it.
 			resolveSecrets: makeSecretsResolverFn({ envProfiles: config.secretProfiles, roots: config.secretResolverRoots, timeoutMs: config.secretResolveTimeoutMs, forwardEnv: config.forwardEnv, hostEnv: env, log }),
+			// REQ-MCP-OPERATOR-SERVERS: the overlay's mcp.json read once per job that names a server, never at boot (an
+			// operator who re-runs import-pi must not have to restart the worker). The allowlist is the one the proxy
+			// mounts, this folder's egress-allowlist.conf on both venues (up.mjs, podman-stack.mjs), and the endpoints
+			// are the pickup's snapshot, so the check and the proxy read the same declarations.
+			checkMcp: makeMcpCheck({
+				globalPiDir: config.globalPiDir,
+				forwardEnv: config.forwardEnv,
+				hostEnv: env,
+				egress: config.egress,
+				// DES-FORGE-MCP: the GitLab a gitlab job's forge server calls, the same URL its clone and its glab use.
+				gitlabUrl: config.gitlab?.apiUrl ?? null,
+				// The credentials the job is set up to spend with (providerKeyNames). A read of the overlay models.json that
+				// may pass on a retry is thrown to the check, which retries the job; any other failure adds no overlay
+				// names, and the model gates, which ran first, refuse every job such a file breaks.
+				reserved: (job) => {
+					let overlayModels = null;
+					try {
+						overlayModels = readOverlayModels(config.globalPiDir);
+					} catch (error) {
+						if (MCP_TRANSIENT_READ_CODES.has(error?.code)) throw error;
+					}
+					const providers = jobProviders(job, { defaultProvider: config.provider, allowedModels: config.allowedModels, everyProvider: piProviders() });
+					return new Set([...RESERVED_ENV_NAMES, ...providerKeyNames({ providers, candidatesOf: providerKeyCandidates, overlayModels })]);
+				},
+				allowlist: () => {
+					try {
+						return parseAllowlist(readFileSync(join(process.cwd(), "egress-allowlist.conf"), "utf8"));
+					} catch (error) {
+						// No allowlist here: every server outside a declared endpoint is unreachable, which it is. Any other
+						// failure is the check's to classify (a transient errno is retried).
+						if (error?.code === "ENOENT") return [];
+						throw error;
+					}
+				},
+				endpoints: () => modelEndpoints.current,
+			}),
 			// #227. What PI_BACKENDS blessed, so a trigger naming an unblessed venue refuses pre-spend. The
 			// panel's picker is bounded by the same list, and this is the half that binds: the overlay is
 			// not the reviewed artifact (DES-PER-TRIGGER-SECRET-PROFILE).

package/src/triggers-file.mjs

@@ -475,6 +475,9 @@ export const AUTHORED_NARROWING_FIELDS = Object.freeze([
 	// unknown), the job would run under the deployment's wider cap, or with none, on a clean record. Any present
 	// value counts as authored; whether it is a valid amount is the loader's question, not this one.
 	Object.freeze({ key: "maxCostUsd", authored: (v) => v !== undefined && v !== null }),
+	// REQ-MCP-OPERATOR-SERVERS: the MCP servers a trigger's jobs connect. Not a widening when dropped but the same
+	// silent outcome: the job runs its flow without the servers it was written against, on a clean record.
+	Object.freeze({ key: "mcp", authored: (v) => Array.isArray(v) && v.length > 0 }),
 ]);
 
 export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {

package/src/triggers.mjs

@@ -32,6 +32,8 @@ import { imageRefProblem } from "./image-ref.mjs";
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
 import { findDuplicateKey } from "./json-duplicates.mjs";
+// The server-name rule, from the one module that parses the overlay's list (its body is import-inert).
+import { FORGE_MCP_KINDS, FORGE_MCP_SERVER_NAME, MCP_SERVER_NAME_RE } from "./mcp-config.mjs";
 import { validateModelRef } from "./model-ref.mjs";
 import { parseUsdMicros } from "./money.mjs";
 import { PROVIDER_STEERING_VARS } from "./provider-steering.mjs";
@@ -189,6 +191,29 @@ const REVIEW_ACTION = "review_submitted";
  */
 // EXPORTED for the two pinned-set bolts and for the admin, which states the vocabulary to an operator.
 export const EXCLUDABLE_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+/**
+ * The tools a job's MCP brings (REQ-MCP-OPERATOR-SERVERS, image/runner/src/mcp.mjs), excludable only by a trigger that
+ * names servers: codemode, tool_search and pi's three resource tools. One server's tools are excluded as a whole by
+ * `mcpServerToolPattern(name)`; a single tool of a server is not, since its name (pi's sanitized `mcp__<server>__<tool>`)
+ * is unknown until the server lists it, and a misspelled one would exclude nothing. That is the overlay's
+ * `toolExposure: "hidden"`, the operator's.
+ */
+export const MCP_EXCLUDABLE_TOOL_NAMES = new Set(["codemode", "tool_search", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+/**
+ * `excludeTools` without the entries that name the job's MCP tools, or undefined when nothing is left: what a job that
+ * connects no MCP server carries (a chained child, which never inherits `run.mcp`). Its runner knows none of those
+ * names, and with no MCP there is nothing for them to remove, so dropping them narrows nothing.
+ */
+export function withoutMcpExclusions(excludeTools) {
+	if (!Array.isArray(excludeTools)) return excludeTools;
+	const kept = excludeTools.filter((name) => !MCP_EXCLUDABLE_TOOL_NAMES.has(name) && !String(name).startsWith("mcp__"));
+	return kept.length > 0 ? kept : undefined;
+}
+
+/** The excludeTools entry that removes every tool of one named server: pi's namespace, `-` written as `_`. */
+export function mcpServerToolPattern(name) {
+	return `mcp__${String(name).replace(/-/g, "_")}__*`;
+}
 
 // A cron id flows into BullMQ's deterministic `repeat:<id>:<nextMillis>` jobId, so a `:` corrupts that
 // parse; the charset also excludes `:` and the dedicated check names the reason.
@@ -416,6 +441,7 @@ function normalizeCron(on, run, index, path, state) {
 	// A cron job's session narrows like any other: the field selects what the container's agent can do,
 	// which is orthogonal to what triggered it (issue #291).
 	const excludeTools = validateExcludeTools(on, run, `cron trigger "${id}"`, path);
+	const mcp = validateMcp(on, run, `cron trigger "${id}"`, path, { kind: "local" });
 	// Validated since #502; before it these three were copied untouched, so `run.provider: 7` loaded.
 	const ref = validateRunModel(on, run, `cron trigger "${id}"`, path);
 	// Issue #505: the portfolio flag. Strictly boolean, the house rule (`run.github`'s reason: a truthy string must not
@@ -430,7 +456,7 @@ function normalizeCron(on, run, index, path, state) {
 	// freeze today's default into every stored repeatable.
 	return {
 		on: { type: "cron", id, pattern },
-		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: ref.provider, model: ref.model, maxTurns: ref.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(ref.models !== undefined && { models: ref.models }), ...(ref.maxCostUsd !== undefined && { maxCostUsd: ref.maxCostUsd }), ...(portfolio !== undefined && { portfolio }) },
+		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: ref.provider, model: ref.model, maxTurns: ref.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...(ref.models !== undefined && { models: ref.models }), ...(ref.maxCostUsd !== undefined && { maxCostUsd: ref.maxCostUsd }), ...(portfolio !== undefined && { portfolio }) },
 	};
 }
 
@@ -1368,14 +1394,22 @@ function validateExcludeTools(on, run, at, path) {
 	if (!Array.isArray(excludeTools) || excludeTools.length === 0) {
 		throw configError(`${at}: run.excludeTools must be a non-empty array of tool names when present (got ${JSON.stringify(excludeTools)}) -- an empty exclusion is a field that does nothing, and accepted-and-ignored is how an operator comes to trust one that does: ${path}`);
 	}
+	// With run.mcp, the tools the job's MCP brings are known too (its shape is the next validator's to judge; here a
+	// name that is not a valid server name simply adds no pattern).
+	const known = new Set(EXCLUDABLE_TOOL_NAMES);
+	if (Array.isArray(run?.mcp) && run.mcp.length > 0) {
+		for (const name of MCP_EXCLUDABLE_TOOL_NAMES) known.add(name);
+		for (const name of run.mcp) if (typeof name === "string" && MCP_SERVER_NAME_RE.test(name)) known.add(mcpServerToolPattern(name));
+	}
 	const seen = new Set();
 	for (let i = 0; i < excludeTools.length; i++) {
 		const name = excludeTools[i];
 		if (!isNonEmptyString(name)) {
 			throw configError(`${at}: run.excludeTools[${i}] must be a non-empty string naming a pi tool (got ${JSON.stringify(name)}): ${path}`);
 		}
-		if (!EXCLUDABLE_TOOL_NAMES.has(name)) {
-			throw configError(`${at}: run.excludeTools[${i}] ${JSON.stringify(name)} is not a tool the pinned pi knows (known: ${[...EXCLUDABLE_TOOL_NAMES].join(", ")}) -- pi ignores unknown names silently, so a misspelled exclusion would exclude nothing while the file reads as though it did: ${path}`);
+		if (!known.has(name)) {
+			const mcpHint = MCP_EXCLUDABLE_TOOL_NAMES.has(name) || name.startsWith("mcp__") ? " (an MCP tool is excludable only by a trigger whose run.mcp names its server, and a server's tools only all at once, as mcp__<server>__*)" : "";
+			throw configError(`${at}: run.excludeTools[${i}] ${JSON.stringify(name)} is not a tool the pinned pi knows (known: ${[...known].join(", ")})${mcpHint} -- pi ignores unknown names silently, so a misspelled exclusion would exclude nothing while the file reads as though it did: ${path}`);
 		}
 		if (seen.has(name)) {
 			throw configError(`${at}: run.excludeTools names ${JSON.stringify(name)} twice -- the entries are a removal set, so the second can never change the answer: ${path}`);
@@ -1386,6 +1420,84 @@ function validateExcludeTools(on, run, at, path) {
 	return [...excludeTools];
 }
 
+/** The most MCP servers one trigger may name. A bound, not a budget: each one is a connection the job opens at start. */
+export const MCP_SERVERS_MAX = 8;
+
+/** The spellings of `run.mcp` a key is refused for, compared after `mcpKeySkeleton`. */
+const MCP_NEAR_MISSES = Object.freeze(["mcp", "mcps", "mcpserver", "mcpservers"]);
+
+/** An ASCII key reduced to its letters and digits, lowercased: `MCP_Servers` and `mcp-servers` both read `mcpservers`. */
+export function mcpKeySkeleton(key) {
+	return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * Whether `key` (not the field itself) is refused as a spelling of `run.mcp` rather than dropped: an ASCII key whose
+ * skeleton is one of the field's spellings, or a key that is not plain ASCII and whose plain letters are all letters
+ * of `mcpservers`. A key in another script can be drawn exactly like this one (Greek, Cyrillic, Cherokee, small
+ * capitals, fullwidth forms), which no table of lookalikes keeps up with, but any such key keeps at most the field's
+ * own letters in ASCII. An unrelated non-ASCII key (`fl\u00f6w`) keeps others and still loads, and a lookalike of
+ * another field (`m\u043edels`) is left to that field's sweep.
+ */
+export function isMcpNearMiss(key) {
+	if (key === "mcp") return false;
+	if (/^[\x20-\x7E]*$/.test(key)) return MCP_NEAR_MISSES.includes(mcpKeySkeleton(key));
+	return [...key.matchAll(/[a-z]/gi)].every(([letter]) => "mcpservers".includes(letter.toLowerCase()));
+}
+
+/**
+ * `run.mcp` -- the overlay MCP servers this trigger's jobs connect (REQ-MCP-OPERATOR-SERVERS), by name.
+ *
+ * NAMES ONLY. A server's definition is the operator's, in the overlay's `mcp.json` (INT-OVERLAY-MCP-CONFIG), so a
+ * trigger edit can choose among the servers the deployment offers and never point a credential at a new host. The
+ * loader is fs-free, so whether a name is in the overlay is checked where the file is read: at the job's pickup,
+ * before anything is spent, and by doctor. Absent means none: a job connects no MCP server unless its trigger says
+ * so. The near-miss sweep is excludeTools': a dropped `run.mcp` runs the job without the servers its flow was written
+ * against, while the file reads as though it named them.
+ *
+ * One name is not the overlay's: `forge` (DES-FORGE-MCP) is the job's own forge, through that forge's MCP server and
+ * the job's own token, and the worker writes its entry. Accepted on a github or gitlab trigger only, and refused here
+ * on the rest, since whether it can ever work is a fact about the kind: a cron job holds no forge token of its own, and
+ * forgejo and azure have no forge MCP server this repository has verified.
+ */
+function validateMcp(on, run, at, path, { kind }) {
+	for (const [label, source, exactIsLegal] of [
+		["run", run, true],
+		["on", on, false],
+	]) {
+		for (const key of Object.keys(source ?? {})) {
+			if (exactIsLegal ? isMcpNearMiss(key) : key === "mcp" || isMcpNearMiss(key)) {
+				if (!/^[\x20-\x7E]*$/.test(key)) {
+					throw configError(`${at}: ${label}.${JSON.stringify(key)} is not a field: a key outside plain ASCII with no plain letter other than run.mcp's can be drawn exactly like run.mcp, which the loader would drop while the file reads as though it named servers. Write field names in plain ASCII: ${path}`);
+				}
+				throw configError(`${at}: ${label}.${key} is not a field -- did you mean run.mcp? A list of MCP servers the loader drops runs the job without them while the file reads as though it named them, so a near miss is refused rather than dropped: ${path}`);
+			}
+		}
+	}
+	const mcp = run?.mcp;
+	if (mcp === undefined) return undefined;
+	if (!Array.isArray(mcp) || mcp.length === 0) {
+		throw configError(`${at}: run.mcp must be a non-empty array of server names from the overlay's mcp.json when present (got ${JSON.stringify(mcp)}); leave it out for none: ${path}`);
+	}
+	if (mcp.length > MCP_SERVERS_MAX) {
+		throw configError(`${at}: run.mcp names ${mcp.length} servers, more than ${MCP_SERVERS_MAX}: ${path}`);
+	}
+	const seen = new Set();
+	for (let i = 0; i < mcp.length; i++) {
+		const name = mcp[i];
+		if (typeof name !== "string" || !MCP_SERVER_NAME_RE.test(name)) {
+			throw configError(`${at}: run.mcp[${i}] must name a server of the overlay's mcp.json: lowercase letters and digits, words joined by single -, up to 32 (got ${JSON.stringify(name)}): ${path}`);
+		}
+		if (seen.has(name)) throw configError(`${at}: run.mcp names ${JSON.stringify(name)} twice: ${path}`);
+		seen.add(name);
+		if (name === FORGE_MCP_SERVER_NAME && !FORGE_MCP_KINDS.includes(kind)) {
+			const why = kind === "local" ? "a cron job holds no forge token of its own for the server to use" : `${kind} has no forge MCP server this deployment has verified yet`;
+			throw configError(`${at}: run.mcp names "forge", the job's own forge server, which a ${FORGE_MCP_KINDS.join(" or ")} trigger may name and this one may not: ${why}: ${path}`);
+		}
+	}
+	return [...mcp];
+}
+
 /**
  * `run.waitFor` -- the conditions that must all clear before this trigger's job starts (issue #230).
  *
@@ -1544,10 +1656,11 @@ function normalizeLabel(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1586,10 +1699,11 @@ function normalizeComment(on, run, index, path, state) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1655,6 +1769,7 @@ function normalizeIssue(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: {
@@ -1665,7 +1780,7 @@ function normalizeIssue(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 
@@ -1742,6 +1857,7 @@ function normalizePullRequest(on, run, index, path) {
 	const backend = validateBackend(on, run, at, path, { localWorkspace: false });
 	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	const excludeTools = validateExcludeTools(on, run, at, path);
+	const mcp = validateMcp(on, run, at, path, { kind: run.kind });
 	const ref = validateRunModel(on, run, at, path);
 	return {
 		on: {
@@ -1757,7 +1873,7 @@ function normalizePullRequest(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }), ...(backend !== undefined && { backend }), ...(excludeTools !== undefined && { excludeTools }), ...(mcp !== undefined && { mcp }), ...ref },
 	};
 }
 

package/src/wait-for.mjs

@@ -40,6 +40,13 @@ function configError(message) {
  */
 export const WAIT_CONDITION_KEYS = ["after", "profile"];
 
+/**
+ * Every reason the wait gate refuses a job with (index.mjs `refuseWait`), each before the job holds a slot. A test
+ * holds this list equal to the processor's calls; the capacity report reads it to tell such a refusal from a run on
+ * a record from before `capacity` was recorded (issue #599).
+ */
+export const WAIT_REFUSAL_REASONS = Object.freeze(["wait-superseded", "wait-unreadable", "wait-profile-unknown", "wait-after-beyond-max", "wait-expired", "wait-refused", "wait-unanswerable"]);
+
 /**
  * The ceiling on conditions per trigger. Four, on `SECRETS_MAX`'s reasoning rather than `REPLICAS_MAX`':
  * this multiplies no spend, but every `profile` condition is a subprocess evaluated before the container,

package/src/worker-name.mjs

@@ -0,0 +1,25 @@
+/**
+ * The worker name rule (issue #57), in a module with NO imports, so a pure reader (the capacity report, issue #599) can
+ * hold a record's `host` to it without loading config.mjs and its fs and os. `config.mjs` re-exports the name.
+ */
+
+/**
+ * What a worker may call itself (issue #57). The CHARACTER CLASS is `sanitizeJobId`'s
+ * (`[A-Za-z0-9._-]`), reused rather than invented so this project has one name-safe alphabet -- but that
+ * function is a REPLACER, not a validator, so the three rules around the class are NEW and are claimed
+ * as new here rather than borrowed:
+ *
+ *   - a leading alphanumeric, which is what refuses `..` and a leading `-` that reads as a flag;
+ *   - a 64-character ceiling, because the name is a Valkey key segment and a log field on every line;
+ *   - no `.json`/`.log` tail, which is not decoration. The class contains the dot, so `prod.json` is
+ *     otherwise a legal name -- and a later slice writes a per-host marker file into `PI_LOGS_DIR`,
+ *     where `<something>.json` is parsed as a run record by the admin and DELETED by the log reaper.
+ *     A name is refused here rather than escaped there, because the escape would have to be remembered
+ *     at every site that ever composes a filename from this value.
+ *
+ * The class is `:`-free, `,`-free and `#`-free, which is what lets the name be a Valkey key segment
+ * UNHASHED. That is the point of validating instead of hashing (`scopeKeyPrefix` does the opposite for
+ * a folder path, which was never chosen for key-safety and cannot be refused): the whole value of a host
+ * registry is that `HGETALL host:h:mac-mini-1` is readable by a human.
+ */
+export const WORKER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;