@edgehero/pi-dispatch 4.1.0 → 4.3.0

package/src/forgejo-host.mjs

@@ -21,6 +21,7 @@
  */
 
 import { configError } from "./config.mjs";
+import { PARKED_LABEL } from "./parked.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
 import { matchesBranch } from "./gitlab-host.mjs";
@@ -153,7 +154,38 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 		return { headRef: pr?.head?.ref, headRepo: pr?.head?.repo?.full_name };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * Add or remove the parked marker on an issue (issue #625, parked.mjs). Forgejo adds and removes a
+	 * label by NAME (its IssueLabelsOption and the `{identifier}` path take a name or an id), but only one the repository
+	 * already has, so adding first creates the repository label; a label that already exists answers 409 or 422 there. The caller treats any throw as fail-open:
+	 * the session store's sidecar, not this label, decides whether a reply resumes anything.
+	 */
+	async function setParkedLabel(ref, target, on, token) {
+		const [owner, name] = splitRepo(ref);
+		const send = async (method, path, body, accept = []) => {
+			let res;
+			try {
+				res = await fetchFn(`${root}${path}`, {
+					method,
+					headers: { Authorization: `token ${token}`, "content-type": "application/json" },
+					...(body !== undefined && { body: JSON.stringify(body) }),
+					redirect: "error",
+				});
+			} catch (err) {
+				throw new InfraRetry(`forgejo-host: ${method} ${path} failed (${fetchFailureReason(err)})`);
+			}
+			if (!res.ok && !accept.includes(res.status)) throw new InfraRetry(`forgejo-host: ${method} ${path} returned ${res.status}`);
+		};
+		const issue = `/repos/${owner}/${name}/issues/${encodeURIComponent(target?.number)}/labels`;
+		if (on) {
+			await send("POST", `/repos/${owner}/${name}/labels`, { name: PARKED_LABEL, color: "#fbca04", description: "pi-dispatch: the last run is waiting for an answer" }, [409, 422]);
+			await send("POST", issue, { labels: [PARKED_LABEL] });
+			return;
+		}
+		await send("DELETE", `${issue}/${encodeURIComponent(PARKED_LABEL)}`, undefined, [404]);
+	}
+
+	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };
 }
 
 /**

package/src/forgejo-prompt.mjs

@@ -74,6 +74,31 @@ function prReplicaLines(replica, replicas) {
  * toward the full envelope, and a bare "address the feedback" over a cold session is an agent with no idea
  * what it was asked to do. `tea`, never `gh`: this envelope's whole reason for existing.
  */
+/**
+ * What a resumed run is told to do with the activity (issue #624). On a pull request the branch and the pull
+ * request exist, so the words are the ones this envelope always had. On an issue neither is certain: the
+ * previous run may have opened nothing (it concluded there was nothing to change, or it stopped to ask), and
+ * "push to the same branch ... do not open a second" would leave the work on a branch nobody reviews while the
+ * human who asked waits on the issue for a reply. So the issue form names the issue branch, checks for its pull
+ * request first, and replies where the activity came from. No replica argument: run.resume refuses replicas.
+ */
+function resumedActionLines(target, n) {
+	if (target?.type === "pull_request") {
+		return [
+			"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
+			"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
+			"not. Do not open a second pull request -- your push updates the existing one.",
+		];
+	}
+	const branch = issueBranch(n);
+	return [
+		"Address the activity quoted below, then reply on the issue saying what you did or why you could not.",
+		`If it asks for changes, commit them to \`${branch}\` and publish with \`git push --force-with-lease\` to that`,
+		`branch only. Check first for an open pull request from it (\`tea pr list --state open\`, look for \`${branch}\`):`,
+		`if one exists your push updates it, so do not open a second; only if none exists, run \`tea pr create --head ${branch}\`.`,
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "pull request" : "issue";
@@ -86,9 +111,7 @@ function buildResumedPrompt(flow, target, comment, instructions) {
 		`If you do not recognise this ${noun}, treat this as a fresh start: read it with \`tea pr ${n}\``,
 		`(or \`tea issue ${n}\`) before doing anything, then follow the "${flow}" skill from the top.`,
 		"",
-		"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
-		"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
-		"not. Do not open a second pull request -- your push updates the existing one.",
+		...resumedActionLines(target, n),
 		"",
 		// Above the never-merge paragraph, so the harness has the last word before the data region.
 		...(instructionBlock(instructions) ? [instructionBlock(instructions), ""] : []),

package/src/github-host.mjs

@@ -26,6 +26,7 @@
 import { Octokit } from "@octokit/rest";
 import { configError } from "./config.mjs";
 import { octokitLogOptions } from "./octokit-log.mjs";
+import { PARKED_LABEL } from "./parked.mjs";
 import { InfraRetry } from "./processor.mjs";
 
 /**
@@ -134,7 +135,26 @@ export function makeGitHubHost({ log, octokitFor = (token) => new Octokit({ auth
 		return { headRef: data?.head?.ref, headRepo: data?.head?.repo?.full_name };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * Add or remove the parked marker on an issue (issue #625, parked.mjs). GitHub creates a label the repository lacks
+	 * when it is added, so there is nothing to create first. Removing a label the issue does not carry is a 404, which is
+	 * the state asked for. The caller treats any throw as fail-open: the session store's sidecar, not this label, decides.
+	 */
+	async function setParkedLabel(repo, target, on, token) {
+		const [owner, name] = splitRepo(repo);
+		const octokit = octokitFor(token);
+		if (on) {
+			await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/labels", { owner, repo: name, issue_number: target?.number, labels: [PARKED_LABEL] });
+			return;
+		}
+		try {
+			await octokit.request("DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}", { owner, repo: name, issue_number: target?.number, name: PARKED_LABEL });
+		} catch (error) {
+			if (error?.status !== 404) throw error;
+		}
+	}
+
+	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };
 }
 
 /**

package/src/github-prompt.mjs

@@ -155,6 +155,31 @@ function prReplicaLines(replica, replicas) {
  * The safety paragraph is repeated verbatim rather than assumed inherited. It is cheap, and the whole
  * premise of a long-lived transcript is that early turns get compacted away.
  */
+/**
+ * What a resumed run is told to do with the activity (issue #624). On a pull request the branch and the pull
+ * request exist, so the words are the ones this envelope always had. On an issue neither is certain: the
+ * previous run may have opened nothing (it concluded there was nothing to change, or it stopped to ask), and
+ * "push to the same branch ... do not open a second" would leave the work on a branch nobody reviews while the
+ * human who asked waits on the issue for a reply. So the issue form names the issue branch, checks for its pull
+ * request first, and replies where the activity came from. No replica argument: run.resume refuses replicas.
+ */
+function resumedActionLines(target, n) {
+	if (target?.type === "pull_request") {
+		return [
+			"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
+			"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
+			"not. Do not open a second pull request -- your push updates the existing one.",
+		];
+	}
+	const branch = issueBranch(n);
+	return [
+		"Address the activity quoted below, then reply on the issue saying what you did or why you could not.",
+		`If it asks for changes, commit them to \`${branch}\` and publish with \`git push --force-with-lease\` to that`,
+		`branch only. Check first for an open pull request from it (\`gh pr list --head ${branch} --state open\`):`,
+		"if one exists your push updates it, so do not open a second; only if none exists, run `gh pr create`.",
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, review, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "pull request" : "issue";
@@ -168,9 +193,7 @@ function buildResumedPrompt(flow, target, comment, review, instructions) {
 		`and \`gh pr diff ${n}\` (or \`gh issue view ${n}\`) before doing anything, then follow the`,
 		`"${flow}" skill from the top.`,
 		"",
-		"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
-		"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
-		"not. Do not open a second pull request -- your push updates the existing one.",
+		...resumedActionLines(target, n),
 		"",
 		// The operator block sits HERE and not after: later text reads as more specific, and the harness's
 		// non-negotiables must be the last thing before the data region rather than something an operator

package/src/gitlab-host.mjs

@@ -24,6 +24,7 @@
  */
 
 import { configError } from "./config.mjs";
+import { PARKED_LABEL } from "./parked.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
 import { isDeterminateFetchFailure } from "./transient.mjs";
@@ -164,7 +165,29 @@ export function makeGitLabHost({ apiUrl = "https://gitlab.com", fetchFn = fetch
 		return { headRef: mr?.source_branch, headRepo: sameProject ? job?.repo : null };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * Add or remove the parked marker on an issue (issue #625, parked.mjs). `add_labels` creates a
+	 * project label the project lacks, and `remove_labels` of one the issue does not carry changes nothing. The caller treats any throw as fail-open:
+	 * the session store's sidecar, not this label, decides whether a reply resumes anything.
+	 */
+	async function setParkedLabel(projectRef, target, on, token) {
+		const id = projectId(projectRef);
+		const path = `/projects/${id}/issues/${encodeURIComponent(target?.number)}`;
+		let res;
+		try {
+			res = await fetchFn(`${root}${path}`, {
+				method: "PUT",
+				headers: { "PRIVATE-TOKEN": token, "content-type": "application/json" },
+				body: JSON.stringify(on ? { add_labels: PARKED_LABEL } : { remove_labels: PARKED_LABEL }),
+				redirect: "error",
+			});
+		} catch (err) {
+			throw new InfraRetry(`gitlab-host: PUT ${path} failed (${fetchFailureReason(err)})`);
+		}
+		if (!res.ok) throw new InfraRetry(`gitlab-host: PUT ${path} returned ${res.status}`);
+	}
+
+	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };
 }
 
 /**

package/src/gitlab-prompt.mjs

@@ -76,6 +76,31 @@ function mrReplicaLines(replica, replicas) {
  * toward the full envelope, and a bare "address the feedback" over a cold session is an agent with no
  * idea what it was asked to do. `glab`, never `gh`: this envelope's whole reason for existing.
  */
+/**
+ * What a resumed run is told to do with the activity (issue #624). On a merge request the branch and the pull
+ * request exist, so the words are the ones this envelope always had. On an issue neither is certain: the
+ * previous run may have opened nothing (it concluded there was nothing to change, or it stopped to ask), and
+ * "push to the same branch ... do not open a second" would leave the work on a branch nobody reviews while the
+ * human who asked waits on the issue for a reply. So the issue form names the issue branch, checks for its pull
+ * request first, and replies where the activity came from. No replica argument: run.resume refuses replicas.
+ */
+function resumedActionLines(target, n) {
+	if (target?.type === "pull_request") {
+		return [
+			"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
+			"`git push --force-with-lease`, and reply on the merge request saying what you did or why you could",
+			"not. Do not open a second merge request -- your push updates the existing one.",
+		];
+	}
+	const branch = issueBranch(n);
+	return [
+		"Address the activity quoted below, then reply on the issue saying what you did or why you could not.",
+		`If it asks for changes, commit them to \`${branch}\` and publish with \`git push --force-with-lease\` to that`,
+		`branch only. Check first for an open merge request from it (\`glab mr list --source-branch ${branch}\`):`,
+		"if one exists your push updates it, so do not open a second; only if none exists, run `glab mr create`.",
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "merge request" : "issue";
@@ -89,9 +114,7 @@ function buildResumedPrompt(flow, target, comment, instructions) {
 		`and \`glab mr diff ${n}\` (or \`glab issue view ${n}\`) before doing anything, then follow the`,
 		`"${flow}" skill from the top.`,
 		"",
-		"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
-		"`git push --force-with-lease`, and reply on the merge request saying what you did or why you could",
-		"not. Do not open a second merge request -- your push updates the existing one.",
+		...resumedActionLines(target, n),
 		"",
 		// Above the never-merge paragraph, so the harness has the last word before the data region.
 		...(instructionBlock(instructions) ? [instructionBlock(instructions), ""] : []),

package/src/host-pi.mjs

@@ -72,11 +72,14 @@ export const PINNED_PI_NEEDLES = {
 		"const path = `${BUILTIN_PATH_PREFIX}${name}`;",
 	],
 	"dist/core/source-info.js": ['export const BUILTIN_PATH_PREFIX = "builtin:";'],
-	"dist/core/settings-manager.d.ts": [
-		"export type PackageSource = string | {",
-		"    autoload?: boolean;",
-		"    packages?: PackageSource[];",
-		"    extensions?: string[];",
+	// The settings shape parseHostSettings reads. Since pi 1.2.0 it is a TypeBox schema in settings-schema (the same
+	// union: a string, or an object with `source` and an optional `autoload`), and pi still loads the file without
+	// validating it, which is why the parse here stays lenient.
+	"dist/core/settings-schema.d.ts": [
+		"declare const PackageSourceSchema: Type.TUnion<[Type.TString, Type.TObject<{",
+		"    autoload: Type.TOptional<Type.TBoolean>;",
+		"    packages: Type.TOptional<Type.TArray<Type.TUnion<[Type.TString, Type.TObject<{",
+		"    extensions: Type.TOptional<Type.TArray<Type.TString>>;",
 	],
 };
 

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,37 @@ 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.`,
+	}),
+	// Issue #625: a runner that predates run.awaitInput reads no PI_AWAIT_INPUT, so the agent is never offered the tool a
+	// parked run ends on: it guesses or gives up, and the run ends without the question the trigger was armed for.
+	Object.freeze({
+		token: "awaitInput",
+		needed: (job) => job?.awaitInput === true,
+		result: "awaitInputUnsupported",
+		reason: "job-image-await-input-unsupported",
+		event: "refused_image_await_input_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for stopping to wait for an answer (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.awaitInput\`. 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.
  *