@edgehero/pi-dispatch 4.1.0 → 4.3.0

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,11 +130,35 @@ 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 #625. The runner's two refusals of a job armed with run.awaitInput, each before the prompt.
+	"await-input-shadowed": "Stopped: another extension in this job registers the tool a run uses to stop and wait for an answer, so the run ended before the agent started. The operator needs to remove that extension or this trigger's run.awaitInput. Not retried.",
+	"await-input-without-session": "Stopped: this run may stop to wait for an answer but had nowhere to keep its work, so it ended before the agent started. The operator needs to run a worker and a job image of the same release. 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.",
 };
 
+// Issue #625: the one comment the COMPLETED path posts, on a run that ended awaiting-input. The agent posted its own
+// question (the tool tells it to, before it ends); this says how the run continues. Fixed and path-free, the
+// TERMINAL_COMMENTS rule, and it carries no model text: the question never crosses the exit line.
+// On an issue any reply continues it (the receiver routes it on the marker); a pull request's reply keeps the phrase,
+// since its session key needs a head branch that costs a token to read (parked.mjs).
+export const PARKED_COMMENT = "This run stopped to wait for an answer to the question above. Reply here, and the next run continues from here.";
+export const PARKED_COMMENT_PR = "This run stopped to wait for an answer to the question above. Reply in a comment that starts with this repository's pi-dispatch comment phrase, and the next run continues from here.";
+export function parkedComment(target) {
+	return target?.type === "pull_request" ? PARKED_COMMENT_PR : PARKED_COMMENT;
+}
+
 // Issue #502: the `model-unknown` refusal's comment. Names no model: the reader may be an issue author.
 export const MODEL_UNKNOWN_COMMENT = "Refused: this job names an AI model that this deployment does not know (it is in neither pi's model catalog nor the overlay models.json), so no container was started and nothing was spent. Ask the operator to check the trigger's model settings. Not run.";
 
@@ -271,6 +296,12 @@ export async function runJob(job, deps) {
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
 		promoteSession = () => null,
+		// (job) => boolean (issue #625): whether the job's session key holds a `parked` mark. Free and never throws. The
+		// default answers no, so a wiring without a store refuses every phrase-free reply rather than running one.
+		isParked = () => false,
+		// (job, on) => Promise<void> (issue #625): add or remove the forge's parked marker. Never throws; the marker is a
+		// hint for the receiver, and the sidecar decides. The default does nothing.
+		parkedLabel = async () => {},
 		// The session store's root, or null when the feature is unavailable (REQ-RESUMABLE-SESSION). Read
 		// ONLY to answer the fail-closed gate below -- nothing here opens it, and it never reaches the
 		// container env (docker-run.mjs mounts a per-job COPY, never the store).
@@ -307,6 +338,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
@@ -330,7 +365,8 @@ export async function runJob(job, deps) {
 		// runContainer({ job, token, prepared, secrets, name, signal, user, home, modelEndpoints?, size?, hostCpus?, unenforced? }) => { code, aborted, abortReason, turns, tokens, session, usage, context, exitReason }.
 		// `size` (issue #596) is `jobSize` below; `hostCpus` the runtime's CPU count off the job-user gate's own facts read.
 		// `unenforced` (issue #596) is the size flags that same read says the runtime drops, passed only when there are some.
-		// `exitReason` (issue #437) is parseExitReason's closed-set label, read only inside the exit-2 branch.
+		// `exitReason` (issue #437) is parseExitReason's closed-set label, read only inside the exit-2 branch, and in the
+		// exit-0 branch for `awaiting-input` alone (issue #625).
 		// `resources` and `exitOomKilled` (issue #596) are the exit line's cgroup block and the supervisor's OOM report.
 		// `user`/`home` are the job-user gate's answer (issue #341), null for the image's own USER.
 		// `secrets` is the resolved map from the gate above: values, already fetched, host-side. It MUST honour
@@ -491,7 +527,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 };
 			}
@@ -945,6 +981,16 @@ export async function runJob(job, deps) {
 		// purpose: only forge jobs can arm the flag today (triggers.mjs refuses it on cron, and a CLI or
 		// chained job has no trigger entry that could set it), but a gate written as an enumeration of kinds
 		// is a gate the next kind skips silently.
+		// A reply that reached this job WITHOUT the trigger phrase (issue #625) was routed only because the forge said the
+		// issue carries the parked marker, and anyone who may label an issue can set that. The truth is the key's `parked`
+		// mark beside its transcript, and it is free to read, so it is asked here, before the mint and before any spend.
+		// Without it the reply is ordinary conversation on an issue: refused, silently (no comment, since the person was
+		// talking to people), and the stale marker is cleared so the next comment is not routed here again.
+		if (job.parkedReply === true && !isParked(job)) {
+			log("refused_not_parked", { kind: job.kind ?? null });
+			await parkedLabel(job, false);
+			return { outcome: "policy", reason: "not-parked", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
 		if (job.resume === true && !sessionsDir) {
 			await comment(job, "Refused: this trigger set `run.resume` but PI_SESSIONS_DIR is unset, so there is nowhere to persist the transcript -- the job would run with no session and still report success. Set PI_SESSIONS_DIR to a private directory outside every repo, or drop `run.resume` from this trigger. Not run.");
 			// The variable NAME, never a value: there is no path to print here (its absence IS the refusal),
@@ -974,6 +1020,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 +1172,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)
@@ -1448,9 +1513,21 @@ export async function runJob(job, deps) {
 				// (CONST-RETRY-INFRA-ONLY). Same completed-only rule INT-OUTBOX-CONTRACT already uses, and
 				// it sits beside the chain collection for the same reason: both must happen before the
 				// `finally` deletes jobDir. Never throws.
-				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context }) : null;
+				// A run that asked a person a question and ended (issue #625, REQ-AWAIT-INPUT) is still a completed run: it is
+				// promoted like any other, with the key marked parked, and the one fixed comment says how it continues.
+				// exitReason is RUNNER_COMPLETED_REASONS-filtered and read only here, on code 0, so it cannot move a job
+				// between retry classes. Only a job armed with run.awaitInput may park: a line that says so on any other
+				// job is ignored, since that runner was never offered the tool.
+				const parked = exitReason === "awaiting-input" && job.awaitInput === true;
+				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context, parked }) : null;
+				if (parked) await comment(job, parkedComment(job.target));
+				// The forge marker the receiver routes a phrase-free reply on: set on a park, cleared when a run on a key that
+				// could park ends without parking. Never throws, and decides nothing: the sidecar promotion just wrote does.
+				if (parked) await parkedLabel(job, true);
+				else if (job.awaitInput === true || job.parkedReply === true) await parkedLabel(job, false);
 				return {
 					outcome: "completed",
+					...(parked ? { reason: "awaiting-input" } : {}),
 					exitCode: code,
 					turns,
 					tokens,

package/src/provider-steering.mjs

@@ -162,6 +162,7 @@ const UNREACHABLE_BY_SCAN = ["AWS_ENDPOINT_URL_BEDROCK_RUNTIME", "ALL_PROXY", "h
  */
 const PI_OWN_READS = [
 	"PI_CLEAR_ON_SHRINK",
+	"PI_CLIPBOARD_OSC52",
 	"PI_CODING_AGENT_DIR",
 	"PI_CODING_AGENT_SESSION_DIR",
 	"PI_EXPERIMENTAL",

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, awaitInput, parkedReply, 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 }),
@@ -364,6 +366,12 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// delivery, and `trigger` is what /job/event.json is built from.
 		...(instructions !== undefined && { instructions }),
 		...(resume !== undefined && { resume }),
+		// REQ-AWAIT-INPUT (issue #625): only when armed, so an unflagged job's data is byte-identical, and at JOB level
+		// for resume's reason: `trigger` is copied verbatim into /job/event.json.
+		...(awaitInput === true && { awaitInput: true }),
+		// A phrase-free reply to a parked issue (issue #625), gated by the worker on the key's `parked` mark. Never part
+		// of an id: it says how the delivery was routed, not what it is.
+		...(parkedReply === true && { parkedReply: true }),
 		// REQ-TRIGGER-SECRETS. The env variables this trigger binds and the profile whose resolver reads
 		// them. REFERENCES only: no value is ever enqueued, because a queued job is durable and a resolved
 		// credential in Redis would outlive the container it was scoped to. The worker resolves them at job

package/src/reserved-env.mjs

@@ -43,6 +43,8 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_FLOW",
 	"PI_COMMAND",
 	"PI_EXCLUDE_TOOLS",
+	"PI_AWAIT_INPUT",
+	"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,12 @@ 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 #625: whether the runner offers the tool a parked run ends on. Only beside a staged transcript: the
+			// runner refuses the flag without one (await-input-without-session), so a job whose resume degraded to no
+			// mount is not armed into that refusal.
+			awaitInput: job.awaitInput === true && prepared.session ? true : 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-history.mjs

@@ -164,12 +164,38 @@ export function parseExitTurns(text) {
  * it could not enforce before a call. The two refusals are live from the first image that knows the variables.
  * `cost-cap` is live from the image that declares `costCap`, whose runner carries the cost guard, and
  * `model-not-allowed` from the image that declares `modelPolicy`, whose runner carries the model guard.
+ *
+ * Then the runner's exit-2 refusals of a job's MCP servers (`MCP_RUNNER_REASONS`), each before the prompt. They read as
+ * `runner-policy` until they were named here, which hid an operator's fix (a server that answers 401, a command the
+ * image lacks) behind budget wording. `mcp-config-invalid` is also the pickup's FREE refusal of an overlay mcp.json it
+ * cannot read whole; that one returns `budgetReserved: false` and pages nobody, as the free `model-not-allowed` does.
+ * Live from the first image that declares `mcp`: an image built before the worker named them prints the same line.
+ */
+export const MCP_RUNNER_REASONS = Object.freeze(["mcp-unavailable", "mcp-config-invalid", "mcp-config-mismatch", "mcp-secret-missing", "mcp-command-missing", "mcp-shadowed"]);
+/**
+ * The runner's exit-2 refusals of a job armed with `run.awaitInput` (issue #625), each before the prompt: another
+ * extension registers the tool a parked run ends on (`await-input-shadowed`), or the job has no session file to park
+ * a transcript in (`await-input-without-session`, a worker regression, since the worker arms the flag only beside
+ * `run.resume` and refuses that with no store). Named for MCP_RUNNER_REASONS' reason: the operator's fix is not a budget.
+ */
+export const AWAIT_INPUT_RUNNER_REASONS = Object.freeze(["await-input-shadowed", "await-input-without-session"]);
+export const RUNNER_POLICY_REASONS = new Set(["provider-auth-refused", "cost-cap", "model-not-allowed", "cost-cap-unenforceable", "model-policy-unenforceable", ...MCP_RUNNER_REASONS, ...AWAIT_INPUT_RUNNER_REASONS]);
+
+/**
+ * The runner's reasons that ride a COMPLETED exit (`code: 0`) and that the worker acts on, closed (issue #625). One so
+ * far: `awaiting-input`, a run that asked a person a question and ended so the next run resumes with the answer. Every
+ * other exit-0 reason (`stop`, `length`, `command-completed`, `tool-terminated`) is still dropped, as before.
+ *
+ * Read for the same bounded reason RUNNER_POLICY_REASONS is: it cannot change the retry class. The processor consults it
+ * only inside its exit-0 branch, so the worst a forged line can do on a real exit 0 is mark a completed run parked: the
+ * worker then posts one fixed sentence and writes a marker beside a transcript the job already promoted.
  */
-export const RUNNER_POLICY_REASONS = new Set(["provider-auth-refused", "cost-cap", "model-not-allowed", "cost-cap-unenforceable", "model-policy-unenforceable"]);
+export const RUNNER_COMPLETED_REASONS = new Set(["awaiting-input"]);
 
 /**
  * The reason off the decisive exit line (`decisiveExitLine`), or `null`: a member of `RUNNER_POLICY_REASONS`
- * and only when that same line says `code: 2`. Read off the same line as `parseExitTurns`, and NEVER throws.
+ * and only when that same line says `code: 2`, or a member of `RUNNER_COMPLETED_REASONS` and only when it says
+ * `code: 0` (issue #625). Read off the same line as `parseExitTurns`, and NEVER throws.
  *
  * Why this may reach the outcome when its five siblings may not: it cannot change the retry class. The
  * processor consults it only inside its container-exit-2 branch, so a container that exits 1 while
@@ -182,6 +208,7 @@ export const RUNNER_POLICY_REASONS = new Set(["provider-auth-refused", "cost-cap
 export function parseExitReason(text) {
 	const parsed = decisiveExitLine(text);
 	if (parsed === null) return null;
+	if (parsed?.code === 0 && RUNNER_COMPLETED_REASONS.has(parsed?.reason)) return parsed.reason;
 	return parsed?.code === 2 && RUNNER_POLICY_REASONS.has(parsed?.reason) ? parsed.reason : null;
 }
 

package/src/schedules.mjs

@@ -182,7 +182,7 @@ function normalizeCronSchedule({ on, run }, path, existsSync, fleet) {
 	// `portfolio` (issue #505) is conditional like `command`, so an unflagged schedule grows no key, and it rides at JOB
 	// level, never inside `trigger`: `trigger` is copied verbatim into `/job/event.json`, and whether a job may send a
 	// budget plan is the worker's decision to re-check against the live file, not a fact for the agent to read.
-	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.backend !== undefined && { backend: run.backend }), ...(run.excludeTools !== undefined && { excludeTools: run.excludeTools }), ...(run.models !== undefined && { models: run.models }), ...(run.maxCostUsd !== undefined && { maxCostUsd: run.maxCostUsd }), ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), ...(run.secrets !== undefined && { secrets: run.secrets }), ...(run.secretsProfile !== undefined && { secretsProfile: run.secretsProfile }), resume: run.resume, ...(run.portfolio !== undefined && { portfolio: run.portfolio }), trigger: { id: on.id, pattern: on.pattern } };
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.backend !== undefined && { backend: run.backend }), ...(run.excludeTools !== undefined && { excludeTools: run.excludeTools }), ...(run.mcp !== undefined && { mcp: run.mcp }), ...(run.models !== undefined && { models: run.models }), ...(run.maxCostUsd !== undefined && { maxCostUsd: run.maxCostUsd }), ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), ...(run.secrets !== undefined && { secrets: run.secrets }), ...(run.secretsProfile !== undefined && { secretsProfile: run.secretsProfile }), resume: run.resume, ...(run.portfolio !== undefined && { portfolio: run.portfolio }), trigger: { id: on.id, pattern: on.pattern } };
 	// Retention only; the deterministic repeat:<id>:<millis> jobId supplies dedup, so no jobId here, and
 	// scheduler jobs are not retried (DES-CRON-VIA-BULLMQ-SCHEDULER) so no attempts/backoff.
 	const opts = { removeOnComplete: { age: 24 * 3600 }, removeOnFail: { age: 7 * 24 * 3600 } };

package/src/session-store.mjs

@@ -90,6 +90,15 @@ const CONTEXT_FILE = "context";
  * stamp existed ran on `local`, and the default is a setting that can move under it.
  */
 const VENUE_FILE = "venue";
+/**
+ * The run that wrote the transcript beside it ended `awaiting-input` (REQ-AWAIT-INPUT, issue #625): it asked a person
+ * a question and ended so that the next run on this key resumes with the answer. One line, the promotion's
+ * `now()` in milliseconds. Keyed state written where the key already is, like `resume-chain`, so it is not the
+ * index `DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED` refuses: it answers one question about this key and nothing
+ * looks it up by anything else. Written and REMOVED by promotion alone, under the promotion lock: a parked run
+ * writes it, any other completed run on the key removes it, so it never outlives the transcript it describes.
+ */
+export const PARKED_FILE = "parked";
 /**
  * What the venue stamp reads while a promotion is swapping the transcript under it. It matches no venue:
  * parentheses are outside the charset every backend name is validated against (a test pins every name this
@@ -540,7 +549,7 @@ export function makeSessionStore({
 		return st.isDirectory() ? `${st.dev}:${st.ino}` : null;
 	}
 
-	function promoteSession(session, { piVersion = null, context = null } = {}) {
+	function promoteSession(session, { piVersion = null, context = null, parked = false } = {}) {
 		// The second DI-seam backstop, and unreachable for the same reason as the `!sessionsDir` return
 		// above: sessionKeyFor is total and binary (null, or 32 hex chars), so resolveSession returns null
 		// rather than a keyless session, and processor.mjs only calls this when prepare handed it one. Kept
@@ -711,6 +720,7 @@ export function makeSessionStore({
 				// it is reporting.
 				writeSidecar(dir, RESUME_CHAIN_FILE, session.key, chainValue(session));
 				writeContextSidecar(dir, session, context);
+				writeParkedSidecar(dir, session, parked);
 			} finally {
 				fs.closeSync(fd);
 				try {
@@ -840,6 +850,20 @@ export function makeSessionStore({
 		writeSidecar(dir, CONTEXT_FILE, session.key, `${context.tokens} ${context.window}${stamp}`);
 	}
 
+	// Issue #625: `parked` is set by a run that ended awaiting-input, and cleared by every other promotion, so the
+	// marker always describes the transcript beside it. Caught like its siblings: the promotion already happened.
+	function writeParkedSidecar(dir, session, parked) {
+		if (parked === true) {
+			writeSidecar(dir, PARKED_FILE, session.key, String(now()));
+			return;
+		}
+		try {
+			fs.unlinkSync(join(dir, PARKED_FILE));
+		} catch {
+			// Absent is the desired state, so failing to remove what is not there is success.
+		}
+	}
+
 	function keyDir(key) {
 		return join(sessionsDir, key);
 	}
@@ -1289,5 +1313,24 @@ export function makeSessionStore({
 		}
 	}
 
-	return { resolveSession, promoteSession, reapSessions };
+	/**
+	 * Whether the key a job resolves to holds a `parked` mark (issue #625): the TRUTH the worker gates a phrase-free reply
+	 * on, where the forge label was only the receiver's hint. Free, read-only and never throws, so it can answer before
+	 * the mint. An issue's key is a pure function of the job (`pi/issue-<n>`); a pull request's needs its head branch,
+	 * which costs a token to read, which is why a phrase-free reply is routed on issues only and this resolves no PR.
+	 * The key's own name must `lstat` as a real directory, resolveSession's first gate, so a planted link answers no.
+	 */
+	function isParked(job) {
+		if (!sessionsDir || job?.target?.type === "pull_request") return false;
+		const key = sessionKeyFor(job);
+		if (!key) return false;
+		try {
+			if (!fs.lstatSync(keyDir(key)).isDirectory()) return false;
+		} catch {
+			return false;
+		}
+		return readSidecar(key, PARKED_FILE) !== null;
+	}
+
+	return { resolveSession, promoteSession, reapSessions, isParked };
 }

package/src/start.mjs

@@ -62,7 +62,10 @@ 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, newerRecord, RUNNER_POLICY_REASONS, sanitizeJobId, UNREADABLE_RECORD } from "./run-history.mjs";
 import { makeRunMirror, readMirroredRecord } from "./run-mirror.mjs";
@@ -1999,6 +2002,23 @@ export async function startWorker(
 		log("comment", { jobId: job?.id, text });
 	};
 
+	// Issue #625: the forge's parked marker, set on a park and cleared when it no longer applies. comment()'s shape and its
+	// rule: it NEVER throws, because the marker decides nothing (the session store's sidecar does) and a forge that refuses
+	// the label must not flip an outcome. A local job has no forge and no marker. Issues only: a pull request's reply is
+	// routed on the phrase (parked.mjs).
+	const parkedLabel = async (job, on) => {
+		const forge = forgeFor(job);
+		if (!forge?.host?.setParkedLabel || job?.target?.type !== "issue") return;
+		try {
+			const auth = forge.auth ?? (await ensureAuth(job.kind));
+			if (!auth) return;
+			const token = await auth.mintToken(job);
+			await forge.host.setParkedLabel(job, job.target, on, token);
+		} catch (err) {
+			log("parked_label_failed", { jobId: job?.id, on, reason: err?.message });
+		}
+	};
+
 	// The operator's failure hook (issue #288, INT-ON-FAILURE-HOOK-CONTRACT). Constructed ONLY when the
 	// knob is set: an unset PI_ON_FAILURE builds nothing, spawns nothing, and logs nothing -- the
 	// byte-identical guarantee. Fired from the two terminal listeners below, never from the processor:
@@ -2238,6 +2258,8 @@ export async function startWorker(
 			// Completed-only, so a policy or infra exit leaves the canonical transcript byte-identical and a
 			// retry starts from what the first attempt did (CONST-RETRY-INFRA-ONLY).
 			promoteSession: sessionStore.promoteSession,
+			isParked: sessionStore.isParked,
+			parkedLabel,
 			// The same value the store above was built from, passed explicitly so the processor's fail-closed
 			// `run.resume` gate answers from THIS config rather than from its own env default. Identical on the
 			// real path; the difference shows under an injected env, where the store would be built from the
@@ -2256,6 +2278,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,13 @@ 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 }),
+	// REQ-AWAIT-INPUT: the tool a run ends on to wait for a person. Dropped by a receiver from before #625 (which tolerates
+	// the key as unknown), the job runs without it: the agent cannot ask, and the record reads like a clean run. Only
+	// `true` arms it, and the job data carries it only then, so `false` is nothing authored.
+	Object.freeze({ key: "awaitInput", authored: (v) => v === true }),
 ]);
 
 export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {