@edgehero/pi-dispatch 4.2.0 → 4.3.1

package/src/forges.mjs

@@ -37,8 +37,13 @@
  *   names that must be refused in `PI_FORWARD_ENV`, and those two lists being derived from one entry is
  *   the point: a forge added to the mint but not to the refusal set is a long-lived host token forwarded
  *   into every container, and nothing would have said so.
- * - `hostVar` is where a self-hosted instance URL lands in the container, or `null` for a forge that has
- *   no instance concept in this codebase yet.
+ * - `hostVars` are where a self-hosted instance URL lands in the container (the configured URL verbatim,
+ *   scheme included), or an empty list for a forge that has no instance concept in this codebase yet. A
+ *   LIST for the reason `tokenVars` is one: the CLI's own name is the one that matters, and a second,
+ *   forge-named copy is what scripts and skills reach for.
+ * - `receiverOnlyVars` are credentials of this forge that only the RECEIVER reads, and that must never reach a
+ *   job: refused in `PI_FORWARD_ENV`, reserved from `run.secrets`, and deleted from the container env as a
+ *   backstop (`RECEIVER_ONLY_VARS`). Empty for every forge whose author gate the job's own token can answer.
  * - `prLabelAction` is this forge's `pull_request` action meaning "a label changed", or `null` where the
  *   forge has no distinguishable one. It decides whether a rule naming that action must carry a positive
  *   selector, and the reason is independent of who is gating: a rule keyed on labels that names no labels
@@ -51,7 +56,8 @@ export const FORGES = {
 		deliveryIdName: "X-GitHub-Delivery GUID",
 		pullRequestSep: "#",
 		tokenVars: ["GITHUB_TOKEN", "GH_TOKEN"],
-		hostVar: null,
+		hostVars: [],
+		receiverOnlyVars: [],
 		prLabelAction: "labeled",
 	},
 	gitlab: {
@@ -59,7 +65,8 @@ export const FORGES = {
 		deliveryIdName: "webhook-id / Idempotency-Key",
 		pullRequestSep: "!",
 		tokenVars: ["GITLAB_TOKEN", "GL_TOKEN"],
-		hostVar: "GITLAB_HOST",
+		hostVars: ["GITLAB_HOST"],
+		receiverOnlyVars: [],
 		// A label added to a merge request arrives as a plain `update`, indistinguishable from any other
 		// edit, so there is no action for a positive-selector rule to attach to. (Separately, a GitLab label
 		// is not an approval at all -- a Guest can set one at issue creation -- which is why every gitlab
@@ -76,9 +83,23 @@ export const FORGES = {
 		// Forgejo numbers issues and pull requests from ONE per-repository sequence, exactly as GitHub does
 		// -- an issue and a PR cannot share an index. So `#` names one thing and no discriminator is needed.
 		pullRequestSep: "#",
-		// `tea` reads GITEA_SERVER_TOKEN; the unprefixed name is what the API examples and most scripts use.
-		tokenVars: ["FORGEJO_TOKEN", "GITEA_SERVER_TOKEN"],
-		hostVar: "FORGEJO_HOST",
+		// `tea` logs in from the environment ONLY through GITEA_TOKEN plus GITEA_INSTANCE_URL. Measured on the
+		// pinned tea 0.15.0 in the 4.3.0 job image against a live Forgejo 14.0.5: that pair lists issues, while
+		// GITEA_SERVER_URL + GITEA_SERVER_TOKEN (with or without GITEA_LOGIN_VIA_ENV=1), FORGEJO_HOST +
+		// GITEA_SERVER_TOKEN, and GITEA_TOKEN alone inside a clone all fail "Error: no available login". So
+		// from be1cc42e until this row changed, every `tea` command the forgejo envelope tells the agent to run
+		// failed. GITEA_SERVER_TOKEN stays: it is the default of `tea login add --token` (its --help says
+		// `[$GITEA_SERVER_TOKEN]`), so an agent that adds a login explicitly still gets the job's token, and it
+		// stays reserved. FORGEJO_TOKEN is what the API examples and most scripts use.
+		// worker/test/forges.test.mjs pins these names to the tea version image/Dockerfile installs.
+		tokenVars: ["FORGEJO_TOKEN", "GITEA_TOKEN", "GITEA_SERVER_TOKEN"],
+		// GITEA_INSTANCE_URL is tea's, and must be the full URL with its scheme (FORGEJO_URL is). FORGEJO_HOST
+		// is read by no CLI; it is kept because it has been in every forgejo job since #61 and a skill may use it.
+		hostVars: ["GITEA_INSTANCE_URL", "FORGEJO_HOST"],
+		// The author gate's own lookup token (OQ-043): Forgejo answers a lookup of another user's permission only to a
+		// repository admin, so this is a read:repository token of an account that is one, and the job's FORGEJO_TOKEN
+		// can stay a write collaborator's. A job holding it would hold an admin's token, which is the whole point lost.
+		receiverOnlyVars: ["FORGEJO_PERMISSION_TOKEN"],
 		// Forgejo names the action, so the positive-selector rule applies exactly as it does on GitHub.
 		// Note this is HYGIENE, not the gate: unlike GitHub, every forgejo trigger is additionally gated on
 		// the actor's resolved repository permission -- see filter-forgejo.mjs for why that is not
@@ -99,7 +120,8 @@ export const FORGES = {
 		pullRequestSep: "!",
 		// `az repos` reads AZURE_DEVOPS_EXT_PAT; SYSTEM_ACCESSTOKEN is what a pipeline-shaped script expects.
 		tokenVars: ["AZURE_DEVOPS_EXT_PAT", "SYSTEM_ACCESSTOKEN"],
-		hostVar: "AZURE_DEVOPS_ORG_URL",
+		hostVars: ["AZURE_DEVOPS_ORG_URL"],
+		receiverOnlyVars: [],
 		// Azure attaches no labels to a pull request at all, so there is no action to attach the rule to and
 		// a predicated PR rule could never match. The loader refuses one rather than letting it load dead.
 		prLabelAction: null,
@@ -140,14 +162,20 @@ export const MINTED_TOKEN_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[ki
  * `MINTED_TOKEN_VARS` and derived the same way, from the table rather than by hand, so a forge added
  * later cannot be missed here either.
  *
- * Separate from `MINTED_TOKEN_VARS` because `hostVar` is a separate column: the token set is
+ * Separate from `MINTED_TOKEN_VARS` because `hostVars` is a separate column: the token set is
  * `tokenVars` only, so a name like `GITLAB_HOST` is in NEITHER set until this one exists. That gap is
  * not theoretical -- `buildContainerEnv` writes this variable after the mint, so a trigger field able
  * to name it would be silently overwritten, and the job would run without the value it asked for on a
- * clean exit 0. github's row is `null` and contributes nothing, which is why the filter is here and
- * not at the call site.
+ * clean exit 0. github's row is empty and contributes nothing.
  */
-export const FORGE_HOST_VARS = new Set(FORGE_KINDS.map((kind) => FORGES[kind].hostVar).filter((name) => typeof name === "string"));
+export const FORGE_HOST_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].hostVars));
+
+/**
+ * Every credential name only the receiver reads (`receiverOnlyVars`), derived from the table like the two sets above.
+ * The worker refuses each in `PI_FORWARD_ENV`, the triggers loader refuses each in `run.secrets`, and
+ * `buildContainerEnv` deletes each last, so no path puts one in a container.
+ */
+export const RECEIVER_ONLY_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].receiverOnlyVars));
 
 /**
  * The separator between a repo label and a target number, for this forge and this target type: the

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/index.mjs

@@ -22,6 +22,7 @@ import { BUDGET_RECHECK_MS, HOST_BUDGET_TICK_MS, NEVER_FITS_RECHECK_MS, makeHost
 import { governedDollars } from "./allocation.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, afterMs, unreadableConditions, waitArmed, waitBackoffMs, waitLabel, waitProfileNames } from "./wait-for.mjs";
 import { makeWaitState } from "./wait-state.mjs";
+import { releaseSemanticWindow } from "./queue.mjs";
 
 
 export const QUEUE = "pi-jobs";
@@ -1344,6 +1345,11 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 				// mirroring the name/signal injection above. Omitted when unwired so a bare processor falls back
 				// to runJob's no-op default (a chain fault can never flip a completed outcome either way).
 				...(deps.collectChain ? { collectChain: (ctx) => deps.collectChain({ ...ctx, job }) } : {}),
+				// DES-AWAIT-INPUT-ENDS-THE-JOB: a parked run's semantic window is closed on the REAL BullMQ job, which holds the
+				// dedup id the add stored and the compare-and-delete that frees only a key it still owns (queue.mjs). Bound
+				// unconditionally, AFTER the `...deps` spread like the injections around it: whether the key may outlive a park
+				// is not a choice a wiring gets to make by omission.
+				releaseParkedWindow: () => releaseSemanticWindow(job, deps?.log),
 				// The plan collector (issue #505) the same way and for the same reason: the writer it records is the REAL job's
 				// `.id`, and the authority it checks is `.data` as queued. The pickup's `portfolio` decision rides in `ctx`.
 				...(deps.collectPlan ? { collectPlan: (ctx) => deps.collectPlan({ ...ctx, job }) } : {}),

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,16 @@ 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 () => {},
+		// () => Promise<unknown> (DES-AWAIT-INPUT-ENDS-THE-JOB): close this job's semantic dedup window once it has parked,
+		// so the answer is not swallowed against it. Takes no job: the key belongs to the REAL BullMQ job, which only the
+		// wiring holds (index.mjs binds queue.mjs's `releaseSemanticWindow` to it). Never throws. The default does nothing.
+		releaseParkedWindow = 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 +369,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 +985,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 +1517,27 @@ 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;
+				// The window closes AFTER the promotion (an answer that gets in must find the `parked` mark and the transcript)
+				// and BEFORE the comment and the marker: the marker is what routes a phrase-free reply on an issue, and the
+				// comment is what tells a pull request's author to reply, so no answer they invite can meet the old key. Every
+				// park takes this path, a resumed run that parks again included. Guarded although the seam never throws: a
+				// fault here must not cost the person the comment that says how to continue.
+				if (parked) await Promise.resolve().then(releaseParkedWindow).catch(() => {});
+				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,