@edgehero/pi-dispatch 4.2.0 → 4.3.0

package/.env.example

@@ -33,15 +33,16 @@ ANTHROPIC_API_KEY=
 
 # --- Which provider/model to run by default (override per job with --provider / --model) ---
 PI_PROVIDER=anthropic
-# A DATED model id is deterministic; a floating alias (e.g. claude-sonnet-4-5) can change cost.
-PI_MODEL=claude-sonnet-4-5-20250929
+# Name an exact model version (claude-sonnet-5-5, or a dated id such as claude-sonnet-4-5-20250929); an alias
+# that moves to a newer model can change cost.
+PI_MODEL=claude-sonnet-5-5
 # optional: the only models a job may call, comma-separated provider/model (at most 16). A trigger's own
 # run.models replaces this list for its jobs. The default model must be on it, or every job that uses the
 # default is refused before it spends. Env only: the settings overlay cannot set or widen it.
 # Unset = any model. Needs a job image that declares the modelPolicy capability.
 # No spaces, not even after a comma: a shell that sources this file cuts the value at the first space
 # and leaves it unset, so jobs would run with no list (the worker refuses a spaced value at boot).
-# PI_ALLOWED_MODELS=anthropic/claude-sonnet-4-5-20250929,anthropic/claude-haiku-4-5-20251001
+# PI_ALLOWED_MODELS=anthropic/claude-sonnet-5-5,anthropic/claude-haiku-5-5
 
 # --- Spend + concurrency guards (money bounds; all have conservative defaults) ---
 # per-job turn cap -- pi has none of its own, so the harness imposes one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "type": "module",
   "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
@@ -55,6 +55,7 @@
     "./git-dirty": "./src/git-dirty.mjs",
     "./queue": "./src/queue.mjs",
     "./capabilities": "./src/capabilities.mjs",
+    "./parked": "./src/parked.mjs",
     "./connection": "./src/connection.mjs",
     "./valkey-auth": "./src/valkey-auth.mjs",
     "./job-id": "./src/job-id.mjs",
@@ -114,7 +115,7 @@
     "start": "node src/cli.mjs worker"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-ai": "1.2.0",
     "@octokit/auth-app": "8.2.0",
     "@octokit/rest": "22.0.1",
     "bullmq": "5.80.4",

package/src/azure-host.mjs

@@ -22,6 +22,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";
@@ -201,7 +202,33 @@ export function makeAzureHost({ orgUrl, fetchFn = fetch } = {}) {
 		return { headRef: stripRefsHeads(pr?.sourceRefName), headRepo: sameRepo ? job?.repo : null };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * Add or remove the parked marker on a work item, as a TAG (issue #625, parked.mjs): Azure work items have
+	 * tags, not labels, and the receiver reads `System.Tags` into the same `[{ name }]` shape. A tags field is written
+	 * whole, so this reads it, edits the one tag and writes the result; Azure creates a tag the project lacks. 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 { project } = scopeOf(ref);
+		const path = `/${encodeURIComponent(project)}/_apis/wit/workitems/${encodeURIComponent(target?.number)}`;
+		const item = await get(`${path}?fields=System.Tags&api-version=${API_VERSION}`, token);
+		const tags = String(item?.fields?.["System.Tags"] ?? "").split(";").map((tag) => tag.trim()).filter((tag) => tag !== "" && tag !== PARKED_LABEL);
+		const value = (on ? [...tags, PARKED_LABEL] : tags).join("; ");
+		let res;
+		try {
+			res = await fetchFn(`${root}${path}?api-version=${API_VERSION}`, {
+				method: "PATCH",
+				headers: { Authorization: authHeader(token), "content-type": "application/json-patch+json" },
+				body: JSON.stringify([{ op: "add", path: "/fields/System.Tags", value }]),
+				redirect: "error",
+			});
+		} catch (err) {
+			throw new InfraRetry(`azure-host: PATCH ${path} failed (${fetchFailureReason(err)})`);
+		}
+		if (!res.ok) throw new InfraRetry(`azure-host: PATCH ${path} returned ${res.status}`);
+	}
+
+	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };
 }
 
 /**

package/src/azure-prompt.mjs

@@ -68,6 +68,31 @@ function prReplicaLines(replica, replicas) {
 	];
 }
 
+/**
+ * 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 a work item 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 work item 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 work item 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 active pull request from it (\`az repos pr list --source-branch ${branch} --status active\`):`,
+		`if one exists your push updates it, so do not create another; only if none exists, run \`az repos pr create --source-branch ${branch}\`.`,
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "pull request" : "work item";
@@ -81,9 +106,7 @@ function buildResumedPrompt(flow, target, comment, instructions) {
 		`\`az repos pr show --id ${n}\` (or \`az boards work-item show --id ${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/config.mjs

@@ -31,7 +31,7 @@ import { DOLLAR_ENV_NAMES, DOLLAR_WINDOW_KEYS, checkDollarInvariant, optionalUsd
  */
 export const DEFAULT_VALKEY_URL = "redis://127.0.0.1:6379";
 /** The model a job runs on when nothing names one (`PI_MODEL` unset): one copy, for `loadConfig` and doctor. */
-export const DEFAULT_MODEL = "claude-sonnet-4-5-20250929";
+export const DEFAULT_MODEL = "claude-sonnet-5-5";
 /** The provider a job runs on when nothing names one (`PI_PROVIDER` unset). */
 export const DEFAULT_PROVIDER = "anthropic";
 
@@ -394,7 +394,7 @@ export function globalExtensionsEnabled(env) {
  * spend caps above, the per-job token scoping, or the admin-extension recursion block.
  */
 export function loadConfig(env = process.env, { fileExists = existsSync } = {}) {
-	const model = env.PI_MODEL ?? DEFAULT_MODEL; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
+	const model = env.PI_MODEL ?? DEFAULT_MODEL; // an exact model version, not a moving alias; deterministic per CONST-PI-VERSION-PINNED
 	// #227. Hoisted above the object because `defaultBackend` INDEXES `backends`, and a property cannot read
 	// a sibling of the literal it is in. (Calling the parser twice would be harmless -- `egressEnabled` is
 	// called twice a few properties down for the same reason -- so this is about the index, not the throw.)

package/src/env-allowlist.mjs

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

package/src/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

@@ -215,6 +215,16 @@ export const CAPABILITY_GATES = Object.freeze([
 		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/model-catalog.mjs

@@ -125,6 +125,8 @@ export function overlayProviderProblem(config, providerId) {
 		if (!api) return "no-api";
 		const baseUrl = def.baseUrl ?? config.baseUrl ?? defaults?.baseUrl;
 		if (!baseUrl) return "no-baseUrl";
+		// pi 1.2.0's schema refuses both first (a token count must be above zero), so a file reaching here holds none; kept
+		// because provider-composer.js still checks them, and the mirror follows that file, not the schema in front of it.
 		if (def.contextWindow !== undefined && def.contextWindow <= 0) return "contextWindow";
 		if (def.maxTokens !== undefined && def.maxTokens <= 0) return "maxTokens";
 		const composed = { id: def.id, api, baseUrl };

package/src/models-json.mjs

@@ -121,8 +121,13 @@ const T = {
 const opt = (check) => [check, true];
 const req = (check) => [check, false];
 
-// The schema, transcribed from model-config.js at the pin (1.0.3; worker/test/models-json.test.mjs holds the file's
-// content hash), in its order.
+// The schema, transcribed at the pin (1.2.0; worker/test/models-json.test.mjs holds each file's content hash). Since
+// 1.2.0 model-config.js builds it from two pi-ai modules, `providers/model-schema.js` (cost, prompt cache, input
+// limits, thinking map, modalities) and `providers/compat-schema.js` (compat), so all three are pinned.
+//
+// The change that matters in 1.2.0: `compat` was a UNION of three object schemas that each admit extra keys, so a value
+// one api's schema refused passed through another (`supportsStore: "x"` loaded). It is now ONE object, the superset of
+// five apis' properties, so every known compat key is type-checked wherever `compat` appears.
 const PercentileCutoffs = T.obj({ p50: opt(T.num()), p75: opt(T.num()), p90: opt(T.num()), p99: opt(T.num()) });
 const numOrStr = T.union(T.num(), T.str());
 const OpenRouterRouting = T.obj({
@@ -141,70 +146,76 @@ const OpenRouterRouting = T.obj({
 	preferred_max_latency: opt(T.union(T.num(), PercentileCutoffs)),
 });
 const VercelGatewayRouting = T.obj({ only: opt(T.arr(T.str())), order: opt(T.arr(T.str())) });
+// model-schema.js: `Partial(Record(Enum(levels), String | Null))`, which checks the seven level keys and admits others.
 const ThinkingValue = T.union(T.str(), T.nul());
 const ThinkingLevelMap = T.obj({ off: opt(ThinkingValue), minimal: opt(ThinkingValue), low: opt(ThinkingValue), medium: opt(ThinkingValue), high: opt(ThinkingValue), xhigh: opt(ThinkingValue), max: opt(ThinkingValue) });
 // pi 1.0.2 (issue #587): a model's sampling parameters, and the same per thinking level, merged per call over them.
 const SamplingParams = T.rec(T.unknown());
 const SamplingParamsByThinkingLevel = T.obj({ off: opt(SamplingParams), minimal: opt(SamplingParams), low: opt(SamplingParams), medium: opt(SamplingParams), high: opt(SamplingParams), xhigh: opt(SamplingParams), max: opt(SamplingParams) });
-const KwargScalar = T.union(T.str(), T.num(), T.bool(), T.nul());
-const KwargVariable = T.obj({ $var: req(T.union(T.lit("thinking.enabled"), T.lit("thinking.effort"))), omitWhenOff: opt(T.bool()) });
-const Kwarg = T.union(KwargScalar, KwargVariable);
+const KwargValue = T.union(T.str(), T.num(), T.bool(), T.nul(), T.obj({ $var: req(T.union(T.lit("thinking.enabled"), T.lit("thinking.effort"), T.lit("thinking.budget"))), omitWhenOff: opt(T.bool()) }));
 const affinity = T.union(T.lit("openai"), T.lit("openai-nosession"), T.lit("openrouter"));
-const OpenAICompletionsCompat = T.obj({
-	supportsStore: opt(T.bool()),
-	supportsDeveloperRole: opt(T.bool()),
-	supportsReasoningEffort: opt(T.bool()),
-	supportsUsageInStreaming: opt(T.bool()),
-	supportsFinishReason: opt(T.bool()),
-	maxTokensField: opt(T.union(T.lit("max_completion_tokens"), T.lit("max_tokens"))),
-	requiresToolResultName: opt(T.bool()),
-	requiresAssistantAfterToolResult: opt(T.bool()),
-	requiresThinkingAsText: opt(T.bool()),
-	requiresReasoningContentOnAssistantMessages: opt(T.bool()),
-	thinkingFormat: opt(T.union(...["openai", "openrouter", "together", "baseten", "deepseek", "zai", "qwen", "chat-template", "qwen-chat-template", "string-thinking", "ant-ling"].map((x) => T.lit(x)))),
-	chatTemplateKwargs: opt(T.rec(Kwarg)),
-	chatTemplateArgs: opt(T.rec(Kwarg)),
-	cacheControlFormat: opt(T.lit("anthropic")),
-	openRouterRouting: opt(OpenRouterRouting),
-	vercelGatewayRouting: opt(VercelGatewayRouting),
-	supportsOpenAIGrammarTools: opt(T.bool()),
-	supportsStrictMode: opt(T.bool()),
-	sendSessionAffinityHeaders: opt(T.bool()),
-	sessionAffinityFormat: opt(affinity),
-	supportsLongCacheRetention: opt(T.bool()),
-	vllmPriority: opt(T.num()),
-});
-const OpenAIResponsesCompat = T.obj({
-	supportsDeveloperRole: opt(T.bool()),
-	sessionAffinityFormat: opt(affinity),
-	supportsLongCacheRetention: opt(T.bool()),
-	supportsStrictMode: opt(T.bool()),
-	supportsOpenAIGrammarTools: opt(T.bool()),
-	supportsMaxOutputTokens: opt(T.bool()),
-});
 const costRates = { input: req(T.num()), output: req(T.num()), cacheRead: req(T.num()), cacheWrite: req(T.num()) };
 const ModelCostTier = T.obj({ inputTokensAbove: req(T.num()), ...costRates });
 const ModelCost = T.obj({ ...costRates, tiers: opt(T.arr(ModelCostTier)) });
+// `Partial(Record(Enum(["short", "long"]), Number > 0))`, like the thinking map.
 const ModelPromptCache = T.obj({ short: opt(T.num({ exclusiveMinimum: 0 })), long: opt(T.num({ exclusiveMinimum: 0 })) });
 const posInt = T.int({ minimum: 1 });
 const ImageResize = T.obj({ maxWidth: opt(posInt), maxHeight: opt(posInt), maxBytes: opt(posInt), jpegQuality: opt(T.int({ minimum: 1, maximum: 100 })) });
 const ModelInputLimits = T.obj({ maxRequestBytes: opt(posInt), images: opt(T.obj({ resize: opt(ImageResize), maxPerMessage: opt(posInt), maxPerRequest: opt(posInt) })) });
-const AnthropicMessagesCompat = T.obj({
-	supportsEagerToolInputStreaming: opt(T.bool()),
-	supportsLongCacheRetention: opt(T.bool()),
-	sendSessionAffinityHeaders: opt(T.bool()),
-	supportsCacheControlOnTools: opt(T.bool()),
-	supportsTemperature: opt(T.bool()),
-	forceAdaptiveThinking: opt(T.bool()),
-	allowEmptySignature: opt(T.bool()),
-	supportsStrictTools: opt(T.bool()),
-	supportsMidConvoEffort: opt(T.bool()),
+// compat-schema.js's ProviderCompatSchema: the merged properties of the OpenAI completions, OpenAI responses, Anthropic
+// messages, Bedrock and Mistral schemas. A key two of them share takes pi's generic override, which for every shared
+// key here is the same type as each api's own (a boolean, or the three-way affinity format), so the superset is exact.
+const bool = opt(T.bool());
+const ProviderCompat = T.obj({
+	// OpenAI completions
+	supportsStore: bool,
+	supportsDeveloperRole: bool,
+	supportsReasoningEffort: bool,
+	supportsUsageInStreaming: bool,
+	supportsFinishReason: bool,
+	maxTokensField: opt(T.union(T.lit("max_completion_tokens"), T.lit("max_tokens"))),
+	requiresToolResultName: bool,
+	requiresAssistantAfterToolResult: bool,
+	requiresThinkingAsText: bool,
+	requiresReasoningContentOnAssistantMessages: bool,
+	thinkingFormat: opt(T.union(...["openai", "openrouter", "deepseek", "together", "baseten", "zai", "qwen", "chat-template", "qwen-chat-template", "string-thinking", "ant-ling"].map((x) => T.lit(x)))),
+	chatTemplateKwargs: opt(T.rec(KwargValue)),
+	chatTemplateArgs: opt(T.rec(KwargValue)),
+	openRouterRouting: opt(OpenRouterRouting),
+	vercelGatewayRouting: opt(VercelGatewayRouting),
+	zaiToolStream: bool,
+	thinkingTokenBudgetField: opt(T.union(T.lit("thinking_token_budget"), T.lit("thinking_budget"), T.lit("thinking_budget_tokens"))),
+	supportsThinkingTokenBudget: bool,
+	supportsOpenAIGrammarTools: bool,
+	supportsMidConvoSystemMessages: bool,
+	supportsMidConvoToolAdditions: bool,
+	supportsStrictMode: bool,
+	cacheControlFormat: opt(T.lit("anthropic")),
+	sendSessionAffinityHeaders: bool,
+	sessionAffinityFormat: opt(affinity),
+	supportsLongCacheRetention: bool,
+	vllmPriority: opt(T.num()),
+	// OpenAI responses
+	supportsAdditionalTools: bool,
+	supportsToolSearch: bool,
+	supportsExplicitPromptCacheMode: bool,
+	supportsMaxOutputTokens: bool,
+	// Anthropic messages
+	supportsEagerToolInputStreaming: bool,
+	supportsCacheControlOnTools: bool,
+	supportsTemperature: bool,
+	forceAdaptiveThinking: bool,
+	allowEmptySignature: bool,
+	supportsStrictTools: bool,
+	supportsMidConvoEffort: bool,
+	supportsMidConvoToolChanges: bool,
 	allowedFallbackModels: opt(T.arr(T.obj({ provider: req(T.str({ minLength: 1 })), model: req(T.str({ minLength: 1 })), cost: req(ModelCost) }), { maxItems: 3 })),
 });
-const ProviderCompat = T.union(OpenAICompletionsCompat, OpenAIResponsesCompat, AnthropicMessagesCompat);
 const nonEmpty = T.str({ minLength: 1 });
 const inputKinds = T.arr(T.union(T.lit("text"), T.lit("image")));
 const headers = T.rec(T.str());
+// 1.2.0: a token count must be above zero, where any number passed before.
+const tokenCount = T.num({ exclusiveMinimum: 0 });
 const ModelDefinition = T.obj({
 	id: req(nonEmpty),
 	name: opt(nonEmpty),
@@ -216,8 +227,8 @@ const ModelDefinition = T.obj({
 	inputLimits: opt(ModelInputLimits),
 	cost: opt(ModelCost),
 	promptCache: opt(ModelPromptCache),
-	contextWindow: opt(T.num()),
-	maxTokens: opt(T.num()),
+	contextWindow: opt(tokenCount),
+	maxTokens: opt(tokenCount),
 	samplingParams: opt(SamplingParams),
 	samplingParamsByThinkingLevel: opt(SamplingParamsByThinkingLevel),
 	headers: opt(headers),
@@ -231,8 +242,8 @@ const ModelOverride = T.obj({
 	inputLimits: opt(ModelInputLimits),
 	cost: opt(T.obj({ input: opt(T.num()), output: opt(T.num()), cacheRead: opt(T.num()), cacheWrite: opt(T.num()), tiers: opt(T.arr(ModelCostTier)) })),
 	promptCache: opt(ModelPromptCache),
-	contextWindow: opt(T.num()),
-	maxTokens: opt(T.num()),
+	contextWindow: opt(tokenCount),
+	maxTokens: opt(tokenCount),
 	samplingParams: opt(SamplingParams),
 	samplingParamsByThinkingLevel: opt(SamplingParamsByThinkingLevel),
 	headers: opt(headers),
@@ -250,7 +261,8 @@ const ProviderConfig = T.obj({
 	models: opt(T.arr(ModelDefinition)),
 	modelOverrides: opt(T.rec(ModelOverride)),
 });
-const ModelsConfig = T.obj({ providers: req(T.rec(ProviderConfig)) });
+// 1.2.0: a `$schema` key (the published https://pi.dev/schemas/models.schema.json) is declared, as a string.
+const ModelsConfig = T.obj({ $schema: opt(T.str()), providers: req(T.rec(ProviderConfig)) });
 
 /**
  * Parse overlay `models.json` TEXT as pi does. `{ value }` when pi would load it, else `{ error }` with a fixed

package/src/parked.mjs

@@ -0,0 +1,18 @@
+/**
+ * REQ-AWAIT-INPUT, the reply half (issue #625): the forge marker on an issue whose last run is waiting for an answer.
+ *
+ * Imported by both services, like capabilities.mjs, because the receiver routes on it and the worker writes it: two
+ * spellings of one label would be two places for one to drift while every test stayed green.
+ *
+ * THE LABEL IS A HINT, THE SIDECAR IS THE TRUTH. The receiver cannot read the session store (on a fleet it may not
+ * even run beside one), so a label the forge already sends in every comment payload is what lets it route a reply
+ * that carries no trigger phrase. Anyone who may label an issue can set it, so it decides nothing on its own: the
+ * worker refuses such a reply before any spend unless the key's `parked` sidecar exists (`not-parked`). And it
+ * widens WHICH comments start a job, never WHO may: the comment trigger's author gate still runs first.
+ */
+export const PARKED_LABEL = "pi-awaiting-input";
+
+/** Whether a subset's `[{ name }]` label list (or Azure's tag list, the same shape) carries the marker. */
+export function hasParkedLabel(labels) {
+	return Array.isArray(labels) && labels.some((label) => label?.name === PARKED_LABEL);
+}

package/src/processor.mjs

@@ -140,11 +140,25 @@ export const TERMINAL_COMMENTS = {
 	"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.";
 
@@ -282,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).
@@ -345,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
@@ -960,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),
@@ -1482,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

@@ -311,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, mcp, 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`
@@ -366,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,7 @@ 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

package/src/run-container.mjs

@@ -148,6 +148,10 @@ export function makeRunContainer({
 			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

@@ -172,11 +172,30 @@ export function parseExitTurns(text) {
  * 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"]);
-export const RUNNER_POLICY_REASONS = new Set(["provider-auth-refused", "cost-cap", "model-not-allowed", "cost-cap-unenforceable", "model-policy-unenforceable", ...MCP_RUNNER_REASONS]);
+/**
+ * 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_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
@@ -189,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/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

@@ -2002,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:
@@ -2241,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

package/src/triggers-file.mjs

@@ -478,6 +478,10 @@ export const AUTHORED_NARROWING_FIELDS = Object.freeze([
 	// 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 }) {

package/src/triggers.mjs

@@ -425,6 +425,9 @@ function normalizeCron(on, run, index, path, state) {
 	// `false` or absent. Both must keep reaching the job payload unchanged -- an operator who wrote down
 	// today's default must not get a `data` that disagrees with the file they reviewed.
 	const resume = validateResumeFlag(run, `cron trigger "${id}"`, path);
+	// Called for its refusal only (issue #625): `true` needs run.resume, which cron refuses, so the returned `run`
+	// grows no `awaitInput` key, exactly as it grows no `replicas` one.
+	validateAwaitInputFlag(run, `cron trigger "${id}"`, path);
 	// Called and DISCARDED: on a cron trigger this can only refuse, and the refusal is the point. The
 	// returned `run` below deliberately grows no `replicas` key -- a cron entry can never carry one.
 	validateReplicas(run, `cron trigger "${id}"`, path);
@@ -557,6 +560,28 @@ function validateResumeFlag(run, at, path) {
 	return run.resume;
 }
 
+/**
+ * Validate the per-trigger `run.awaitInput` flag (REQ-AWAIT-INPUT, issue #625): whether the job is offered the tool
+ * that ends a run to wait for a person's answer. Strictly boolean, validateResumeFlag's rule and for its reason: a
+ * truthy `"false"` would arm what the operator meant to leave off.
+ *
+ * `true` needs `run.resume: true` beside it, and that one rule carries every other refusal: a parked run is only
+ * worth anything if the next run resumes its transcript, and `run.resume` is already refused on cron and beside
+ * `run.command`, `run.replicas` and `run.secrets`, each for a reason that holds here too. So this adds no list of
+ * its own, which is one place fewer for the two to disagree.
+ *
+ * Returns the flag, undefined when absent, so an unflagged trigger normalizes byte-identically to today's.
+ */
+function validateAwaitInputFlag(run, at, path) {
+	if (run.awaitInput !== undefined && typeof run.awaitInput !== "boolean") {
+		throw configError(`${at}: run.awaitInput must be true or false when present: ${path}`);
+	}
+	if (run.awaitInput === true && run.resume !== true) {
+		throw configError(`${at}: run.awaitInput needs run.resume: true beside it -- a run that stops to wait for an answer is continued by the next run on the same issue or pull request, and only run.resume keeps the transcript it would continue from: ${path}`);
+	}
+	return run.awaitInput;
+}
+
 /**
  * Validate the per-trigger `run.image` reference, shared by all four normalizers. It selects the Docker image
  * this trigger's job containers run in, overriding the deployment-wide `PI_JOB_IMAGE` for this trigger only;
@@ -1649,6 +1674,7 @@ function normalizeLabel(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	const repository = validateRepository(run, "label", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1660,7 +1686,7 @@ function normalizeLabel(on, run, index, path) {
 	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 }), ...(mcp !== undefined && { mcp }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(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 },
 	};
 }
 
@@ -1692,6 +1718,7 @@ function normalizeComment(on, run, index, path, state) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	const repository = validateRepository(run, "comment", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1703,7 +1730,7 @@ function normalizeComment(on, run, index, path, state) {
 	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 }), ...(mcp !== undefined && { mcp }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(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 },
 	};
 }
 
@@ -1762,6 +1789,7 @@ function normalizeIssue(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	validateRepository(run, "issue", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1780,7 +1808,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 }), ...(mcp !== undefined && { mcp }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(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 },
 	};
 }
 
@@ -1850,6 +1878,7 @@ function normalizePullRequest(on, run, index, path) {
 	const skillsDir = validateSkillsDir(run, at, path);
 	const instructions = validateInstructions(run, at, path);
 	const resume = validateResumeFlag(run, at, path);
+	const awaitInput = validateAwaitInputFlag(run, at, path);
 	validateRepository(run, "pull_request", at, path);
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
@@ -1873,7 +1902,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 }), ...(mcp !== undefined && { mcp }), ...ref },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(awaitInput !== undefined && { awaitInput }), ...(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 },
 	};
 }