@edgehero/pi-dispatch 5.1.0 → 5.2.1

package/src/github-app-setup.mjs

@@ -49,6 +49,11 @@ const API_ROOT = "https://api.github.com";
 const USER_AGENT = "pi-dispatch-setup-github";
 // The repo homepage, shown on the App's about page — informational, not a trust anchor.
 const HOMEPAGE = "https://github.com/edgehero/pi-dispatch";
+// The webhook URL of an App made with --no-webhook (issue #874). GitHub requires one even for an inactive hook. A
+// `.invalid` name (RFC 6761) never resolves, so nothing GitHub sends there reaches any host: not the ping an inactive
+// hook still got at creation (in the measurement that `buildManifest`'s comment cites), and not an event if someone
+// ticks Active later without changing the URL. A real host would get both, and a domain can change owner.
+export const NO_WEBHOOK_URL = "https://no-webhook.invalid/";
 // GitHub app names are GLOBALLY unique and capped at 34 characters.
 const NAME_MAX = 34;
 
@@ -363,7 +368,11 @@ function printSummary(say, summary, { noWebhook }) {
 	say("\nNext:\n");
 	if (noWebhook) {
 		say("  the App was created with its webhook INACTIVE (--no-webhook) — the polling-ready shape.\n");
-		say("  Polling delivery is a follow-up; until it lands, forge triggers for this App will not fire on their own.\n");
+		say("  start the poller so events reach the queue: `pi-dispatch-receiver poll`. Under GITHUB_AUTH_SOURCE=app it\n");
+		say("  watches the repositories of the installation GITHUB_APP_INSTALLATION_ID names; POLL_REPOS names a list of\n");
+		say("  your own instead. See docs/polling.md.\n");
+		say(`  the App's webhook URL is a placeholder, ${NO_WEBHOOK_URL}, which nothing can receive. Moving to webhooks\n`);
+		say("  later takes a webhook secret and an order of steps: docs/polling.md, \"Moving to webhooks later\".\n");
 	} else {
 		say("  start the receiver so deliveries have somewhere to land: `pi-dispatch-receiver`\n");
 		say("  (or, where the folder holds deploy/docker-compose.yml, its receiver profile), reachable at the --webhook-url you gave GitHub.\n");
@@ -402,8 +411,12 @@ export function sanitizeAppName(raw) {
  * The manifest GitHub converts into the App — the narrowest shape this system needs
  * (SECURITY.md's auth-source ladder): write on exactly the three surfaces jobs touch, metadata read
  * because the API requires it, private, and only the event families the triggers file can name.
- * `hook_attributes` carries the receiver URL, or `active: false` under --no-webhook — the
- * no-public-URL shape the polling transport will consume.
+ * `hook_attributes` carries the receiver URL, or under --no-webhook an INACTIVE hook at `NO_WEBHOOK_URL`. GitHub
+ * refuses a manifest whose `hook_attributes` has no `url`, inactive or not ("url" wasn't supplied, issue #874), and one
+ * that leaves `hook_attributes` out while it subscribes events ("Hook url cannot be blank"). What it accepts was
+ * measured against github.com on 2026-11-09 by another project's throwaway Apps: a `.invalid` URL with
+ * `active: false` was accepted, only `localhost` and `127.0.0.1` were refused as not reachable over the public
+ * Internet, and the App with the inactive hook recorded one delivery, its creation's ping, and no event after it.
  *
  * `pull_request_review` (issue #66) is subscribed for every new App, armed trigger or not. That is the
  * posture `pull_request` already has for a label-only deployment: an unsubscribed event cannot be turned
@@ -415,7 +428,7 @@ export function buildManifest({ name, redirectUrl, webhookUrl }) {
 		name,
 		url: HOMEPAGE,
 		redirect_url: redirectUrl,
-		hook_attributes: webhookUrl ? { url: webhookUrl } : { active: false },
+		hook_attributes: webhookUrl ? { url: webhookUrl } : { url: NO_WEBHOOK_URL, active: false },
 		public: false,
 		default_permissions: { contents: "write", pull_requests: "write", issues: "write", metadata: "read" },
 		default_events: ["issues", "issue_comment", "pull_request", "pull_request_review"],

package/src/host-loads.mjs

@@ -14,9 +14,11 @@
  * charset, on the way in AND on the way out, since another host wrote what a reader parses. An overlay extension's first
  * path segment and whether it is a file or a folder; a skill's folder name; a server's name, transport, where it is
  * (`mcpServerWhere`: a url's host and port, or a command's base name, never a header, an argument or a value), exposure,
- * whether it is on, and the variable NAMES it references; a package's name and version; a trigger's position, flow name and
- * the tier it resolved in. No path, no value and no tool name: what a server or an extension offers is known only once it
- * runs, and the run's own record says that. These are the same facts the viewer's Connections page shows; a model's
+ * whether it is on, and the variable NAMES it references; a package's name and version; a trigger's position, flow name,
+ * the tier it resolved in and a short hex digest of the trigger fields that answer was judged from (`flowBasisOf`). No path,
+ * no value and no tool name: what a server or an extension offers is known only once it runs, and the run's own record says
+ * that. The digest holds a path (`run.folder`, `run.skillsDir`) only as a hash cut to 8 hex digits, which names nothing a
+ * reader can read back. These are the same facts the viewer's Connections page shows; a model's
  * projection (`modelConnections`) carries counts in place of `where` and the key names, and one of these rows gets the
  * same treatment when a tool reads it.
  *
@@ -27,6 +29,7 @@
  * folders on the host and runs nothing: a frontmatter `name:` rename is invisible, and what a run really loaded is its
  * own record's `loaded`. Where a read cannot say, it says so (`unread`), never an empty list that reads as none.
  */
+import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { DOCTOR_HOSTS, DOCTOR_HOSTS_MAX, DOCTOR_RESULTS_TTL_MS } from "./doctor-results.mjs";
@@ -73,6 +76,52 @@ const KEY_NAME_RE = /^[A-Z_][A-Z0-9_]{0,63}$/;
 const WHERE_RE = /^[A-Za-z0-9._:[\]-]{1,255}$/;
 const INDEX_MAX = 1_000_000;
 
+/**
+ * The trigger fields `flowTierOf` reads, by the names its first argument gives them (issue #869). A flow row's `basis` is a
+ * digest of exactly these, so a test holds this list to that argument's own names: a field `flowTierOf` came to read that
+ * this list left out would let an edit to it keep the console answering for the file as it was.
+ */
+export const FLOW_INPUT_FIELDS = Object.freeze(["flow", "folder", "skillsDir", "packages", "excludeExtensions"]);
+/**
+ * How long a basis is, in hex digits: 32 bits. A collision costs one stale answer read as current, which is what every edit
+ * cost before the basis, and the triggers file has no author but the operator, so nobody gains by aiming for one. Per edit the
+ * odds are one in about four billion. REJECTED: a longer digest, which a flow row carries 128 times over in a record that already
+ * trims its flow rows at its worst (`FIT_ORDER`), so each digit would put a trigger's answer out of the record on such a host.
+ */
+export const FLOW_BASIS_HEX = 8;
+const FLOW_BASIS_RE = new RegExp(`^[0-9a-f]{${FLOW_BASIS_HEX}}$`);
+
+/**
+ * What `flowTierOf` is asked of a trigger as the loader parsed it (`parseTriggers`' entry): doctor's flow lines and its published
+ * rows ask it this, and nothing else does. A field that is not there reads as `flowTierOf`'s own default. A disarmed one-shot is
+ * the loader's sentinel, whose `run` is empty, so it names no flow and doctor publishes no row for it.
+ */
+export function flowInputOf(trigger) {
+	const run = isObject(trigger?.run) ? trigger.run : {};
+	return {
+		flow: typeof run.flow === "string" ? run.flow : null,
+		folder: typeof run.folder === "string" ? run.folder : null,
+		skillsDir: typeof run.skillsDir === "string" ? run.skillsDir : null,
+		packages: run.packages !== false,
+		excludeExtensions: Array.isArray(run.excludeExtensions) ? run.excludeExtensions.filter((name) => typeof name === "string") : [],
+	};
+}
+
+/**
+ * The basis of a flow row (issue #869): a digest of what `flowTierOf` was asked of this trigger, from the trigger as the loader
+ * parsed it. Doctor writes it beside each answer, and the console computes it from its own parse of the file it reads, through
+ * this one function, so the two cannot compute it two ways. Where they differ, the answer was judged for another version of the file.
+ * `flowTierOf` only asks whether a name is in `excludeExtensions`, so the list's order and a repeat change nothing here either.
+ * REJECTED: leaving the list out under `"packages": false`, where `flowTierOf` does not look at it. An edit there would then keep
+ * the answer, at the price of a copy of `flowTierOf`'s branches here that would have to move with them, and the cost of not doing
+ * it is an answer read as unknown until doctor runs on the file as it is, the safe direction.
+ */
+export function flowBasisOf(trigger) {
+	const input = flowInputOf(trigger);
+	const canonical = FLOW_INPUT_FIELDS.map((field) => (field === "excludeExtensions" ? [...new Set(input[field])].sort() : input[field]));
+	return createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, FLOW_BASIS_HEX);
+}
+
 /** A first path segment: the shape a run's record holds, less the two a folder listing never returns and a path could. */
 const extensionOf = (row) => (isObject(row) && typeof row.name === "string" && EXTENSION_NAME_RE.test(row.name) && row.name !== "." && row.name !== ".." && LOADS_EXTENSION_KINDS.includes(row.kind) ? { name: row.name, kind: row.kind } : null);
 const skillOf = (name) => (typeof name === "string" && SKILL_NAME_RE.test(name) ? name : null);
@@ -83,7 +132,10 @@ const flowOf = (row) => {
 	if (flow === null && row.flow !== null) return null;
 	const pkg = row.package === null ? null : isPackageName(row.package) ? row.package : undefined;
 	if (pkg === undefined || (pkg !== null && row.tier !== "package")) return null;
-	return { trigger: row.trigger, flow, tier: row.tier, package: pkg, repo: row.repo };
+	// Absent is a row from a release before issue #869, which a reader answers from as it did. Any other shape is refused, never
+	// read as absent: that would put a row of unknown basis back on the older rule, which answers whatever the file now says.
+	if (row.basis !== undefined && (typeof row.basis !== "string" || !FLOW_BASIS_RE.test(row.basis))) return null;
+	return { trigger: row.trigger, flow, tier: row.tier, package: pkg, repo: row.repo, ...(row.basis === undefined ? {} : { basis: row.basis }) };
 };
 /** One server's row, or null, with how many of its keys its cap left out. */
 const serverOf = (row) => {
@@ -346,6 +398,8 @@ export function hostsAgree(rows) {
  *   resolved, checked, unknown   the words of doctor's own line, which name folders and so are never published
  *
  * `repoFlowAtHead(folder, flow)` answers `present`, `absent` or anything else for not known. `staged` is `readStagedSkills`.
+ * The first argument is `flowInputOf`'s, and its names are `FLOW_INPUT_FIELDS`: a new one goes in both, or a flow row's basis
+ * would not change when it does (`worker/test/host-loads.test.mjs` reads them off this signature).
  */
 export async function flowTierOf({ flow, folder = null, skillsDir = null, packages = true, excludeExtensions = [] }, { repoFlowAtHead, fileExists, overlay = null, staged = { skills: [], unenumerable: [] } }) {
 	let tier = null;

package/src/job-size.mjs

@@ -106,6 +106,33 @@ export function codemodeWorkersOf(memMiB) {
 	return Math.max(1, Math.floor(memMiB / (2 * CODEMODE_WORKER_HEAP_MIB)));
 }
 
+/**
+ * Issue #865: a size's CPUs as a whole count, rounded UP (`1.5` is 2, `0.25` is 1), for a tool's `-j` or worker flag,
+ * which takes no fraction. Up, not down, so no size reads as 0 and a size between two counts gets the larger one: it is
+ * a pool size under a CPU WEIGHT, and the job may already use idle cores beyond its size (the `--cpus` ceiling above).
+ */
+export function wholeCpusOf(cpuCenti) {
+	return Math.ceil(cpuCenti / 100);
+}
+
+/**
+ * Issue #865: the job's size as its own processes can read it, `{ PI_JOB_SIZE_CPUS, PI_JOB_SIZE_MEMORY_MIB }`, both
+ * decimal strings. A job's CPU size is a weight that nothing inside the container can see: `os.availableParallelism()`
+ * reads the cgroup's `cpu.max`, which is the host ceiling (`--cpus`, the same for every job), and `nproc` reads the
+ * affinity mask, which is the whole runtime. So a tool that starts one worker per CPU it sees (jest and vitest by
+ * default) starts one per CEILING CPU, all inside the size's memory, which is the hard bound. These two values are what
+ * a flow, an image or the agent's commands size such a pool from instead.
+ *
+ * INFORMATION, NOT A BOUND: the size is resolved at pickup and enforced by the container's flags; nothing reads these
+ * back. One function, so the job's closed env map (`env-allowlist.mjs`) and the operator's sandbox shell
+ * (`sandbox.mjs`) cannot spell them two ways. Not `PI_JOB_CPUS` and `PI_JOB_MEMORY`: those name the DEPLOYMENT's default
+ * size in `.env`, and a project row can give a job another one.
+ */
+export function jobSizeEnv(size) {
+	assertJobSize(size);
+	return { PI_JOB_SIZE_CPUS: String(wholeCpusOf(size.cpuCenti)), PI_JOB_SIZE_MEMORY_MIB: String(size.memMiB) };
+}
+
 /** The scope prefix of a project row, as `scoped-limits.mjs` spells it (`PROJECT_SCOPE_PREFIX`; a test holds them equal). */
 const PROJECT_ROW_PREFIX = "project:";
 

package/src/json-duplicates.mjs

@@ -22,7 +22,8 @@
  * FIRST, IT RUNS ONLY ON TEXT `JSON.parse` HAS ALREADY ACCEPTED. Every caller parses first and scans
  * second. So the scanner never has to decide whether malformed input is malformed, never has to recover
  * from anything, and every branch it does not have is a branch that cannot be wrong. Feeding it text that
- * did not parse is a caller error, not an input case: the result is unspecified rather than a refusal.
+ * did not parse is a caller error, not an input case: the result is unspecified rather than a refusal, and
+ * since issue #868 it can be a `SyntaxError`, thrown when a key with an escape is decoded.
  *
  * SECOND, IT IS CHECKED AGAINST A GENERATOR THAT KNOWS THE ANSWER. `worker/test/json-duplicates.test.mjs`
  * builds thousands of documents with adversarial key characters -- quotes, backslashes, newlines, braces,
@@ -33,14 +34,19 @@
  * a key written plainly and the same key written with a `u00`-style escape are ONE key to `JSON.parse`,
  * and a byte comparison sees two.
  *
+ * SINCE ISSUE #868 NO KEY IS DECODED BY HAND. A key with no backslash is a slice of the text, and a key
+ * with one is handed to `JSON.parse` as its own string literal, so the decoder is the same code whose
+ * reading of the file the check defends. The hand-written decoder before it appended one character at a
+ * time, which took about 30 bytes of heap per character of a key: a 4MB key cost 123MB, and a 16MB key
+ * ended a process with a 256MB heap while it read its own configuration. That decoder agreed with
+ * `JSON.parse` on every escape, so no verdict moves. What is still written by hand about a string is
+ * where it ends, the one rule the value skip has always relied on, and the generator above checks it.
+ *
  * IMPORT-FREE, like `reserved-env.mjs` and `provider-key.mjs` beside it: `triggers.mjs` is the shared
  * validator, the receiver loads it and `admin/build.mjs` inlines it into the published console, so
  * anything it reaches has to be as cheap as a list of strings.
  */
 
-/** The escape characters JSON defines, other than `\u`. */
-const SIMPLE_ESCAPES = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
-
 /**
  * The first duplicate key in `text`, as `{ key, at }`, or `null` when there is none.
  *
@@ -73,54 +79,53 @@ export function findDuplicateKey(text) {
 	};
 
 	/**
-	 * Walk past the string starting at `s[i] === '"'` WITHOUT building it.
+	 * Walk past the string starting at `s[i] === '"'` WITHOUT building it, and say whether it held an escape.
+	 *
+	 * Building a string here one character at a time (`out += ch`) costs about 30 bytes of heap per source
+	 * character, because each append is a new rope node that lives until the string is flattened. A value's
+	 * text is discarded, so it is never built: a single 64MB value cost 2GB of garbage that way, and a
+	 * trigger's `run.task` and `run.instructions` are free text. A key is taken from the text by `readKey`
+	 * with the end this finds (issue #868). A worker that dies at boot reading its own configuration is a
+	 * worse failure than anything this file refuses.
 	 *
-	 * Value position only, and it is not a micro-optimisation: `readString` accumulates about 32 bytes of
-	 * heap per source character, so a single 64MB string value cost 2GB of garbage to decode a value this
-	 * function then discards. A trigger's `run.task` and `run.instructions` are free text, and a worker
-	 * that dies at boot reading its own configuration is a worse failure than anything this file refuses.
+	 * Character codes, as `skipWhitespace` reads them, because comparing numbers measured a little faster
+	 * than comparing one-character strings on an ordinary triggers file. Either is correct.
 	 */
 	const skipString = () => {
 		i++; // the opening quote
+		let escaped = false;
 		while (i < n) {
-			const ch = s[i];
-			if (ch === '"') {
+			const c = s.charCodeAt(i);
+			if (c === 0x22) {
 				i++;
-				return;
+				return escaped;
 			}
 			// An escape consumes its own next character, which is what stops `\"` ending the string. The
 			// `\uXXXX` digits need no special case here: none of them is a quote or a backslash.
-			i += ch === "\\" ? 2 : 1;
-		}
-	};
-
-	/** Read the string starting at `s[i] === '"'` and return its DECODED value. Keys only. */
-	const readString = () => {
-		i++; // the opening quote
-		let out = "";
-		while (i < n) {
-			const ch = s[i];
-			if (ch === '"') {
-				i++;
-				return out;
-			}
-			if (ch === "\\") {
-				const esc = s[i + 1];
+			if (c === 0x5c) {
+				escaped = true;
 				i += 2;
-				if (esc === "u") {
-					// A lone surrogate is preserved as itself, which is what JSON.parse does too, so a pair
-					// written as two escapes still compares equal to the same pair written literally.
-					out += String.fromCharCode(Number.parseInt(s.slice(i, i + 4), 16));
-					i += 4;
-				} else {
-					out += SIMPLE_ESCAPES[esc] ?? esc;
-				}
-				continue;
+			} else {
+				i++;
 			}
-			out += ch;
-			i++;
 		}
-		return out; // unreachable on text that parsed
+		return escaped; // unreachable on text that parsed
+	};
+
+	/**
+	 * Read the key starting at `s[i] === '"'` and return its DECODED value.
+	 *
+	 * A key with no backslash is its own text, so it is a slice, which V8 keeps as a view of `s` rather than
+	 * a copy from 13 characters up. A key with one is decoded by `JSON.parse` of its literal, quotes
+	 * included. That literal is valid on its own because the whole text already parsed and `skipString`
+	 * ends a string where the parse did. Decoding every key with `JSON.parse` would give the same answers;
+	 * the slice is there because nearly every key has no escape and a slice copies nothing.
+	 * `json-duplicates.test.mjs` holds every `\u` code unit, in both cases of hex, and every simple escape
+	 * against the key `JSON.parse` makes, and the hand-written decoder this replaced passed it too.
+	 */
+	const readKey = () => {
+		const start = i;
+		return skipString() ? JSON.parse(s.slice(start, i)) : s.slice(start + 1, i - 1);
 	};
 
 	// True when the next string is a KEY rather than a value: just after `{`, or after a `,` inside one.
@@ -177,8 +182,14 @@ export function findDuplicateKey(text) {
 		if (ch === '"') {
 			const top = stack[stack.length - 1];
 			if (expectKey && top && top.keys !== null) {
-				const key = readString();
-				if (top.keys.has(key)) return { key, at: [...path, key].join(".") };
+				const key = readKey();
+				// The key is copied on the way out, once: a slice is a view that keeps the whole text alive for as long
+				// as a caller holds the answer, and `secret-bundles.mjs` keeps `key` past the call while its text is a
+				// resolver's output, which holds secret values. JSON's own round trip keeps a lone surrogate as itself.
+				if (top.keys.has(key)) {
+					const own = JSON.parse(JSON.stringify(key));
+					return { key: own, at: [...path, own].join(".") };
+				}
 				top.keys.add(key);
 				path.push(key);
 				top.named = true;

package/src/mcp-preflight.mjs

@@ -158,7 +158,7 @@ export function makeMcpCheck({ globalPiDir, forwardEnv = [], hostEnv = {}, egres
 		// writes under exactly that name, which is the reason every other server is refused it.
 		for (const name of overlayNames) {
 			for (const ref of servers[name].refs) {
-				if (own.has(ref)) return { refused: "mcp-secret-reserved", name, why: `it references ${ref}, which this deployment uses for the job's own credentials` };
+				if (own.has(ref)) return { refused: "mcp-secret-reserved", name, why: `it references ${ref}, which this deployment uses for the job's own credentials or settings` };
 			}
 		}
 		for (const name of overlayNames) {
@@ -276,7 +276,7 @@ export const MCP_REFUSAL_COMMENT = Object.freeze({
 	"mcp-list-invalid": "the list this job carries is not one the triggers file's loader writes (a service in this deployment may be at another version)",
 	"mcp-config-invalid": "this deployment's list of MCP servers (mcp.json in the overlay) cannot be used",
 	"mcp-server-unknown": "this deployment does not offer that server",
-	"mcp-secret-reserved": "that server would be handed a credential this deployment keeps for the job itself",
+	"mcp-secret-reserved": "that server would be handed a variable this deployment keeps for the job itself",
 	"mcp-secret-unmapped": "a credential that server needs is not passed by this trigger",
 	"mcp-excluded": "this trigger's run.excludeTools removes every way the job could reach that server",
 	"mcp-egress-unreachable": "the egress policy does not let a job reach that server",

package/src/pause-windows.mjs

@@ -83,8 +83,13 @@ export function pauseWindowsVersionRefusal(doc, { supported = PAUSE_WINDOWS_VERS
 export function heldPauseWindows(text, path) {
 	if ((text ?? "").trim() === "") return { doc: null, windows: [] };
 	const { value, problem } = heldDocument(text, "windows");
-	const refused = problem ?? (findDuplicateKey(text) ? "has a key written twice" : null);
-	if (refused) return { doc: value ?? null, problem: `the pause-windows file ${path} ${refused}, so its windows cannot be kept` };
+	// Whenever the text parsed, a problem with its shape included (`"windows": {}`), as the loader judges the duplicate first.
+	const doubled = value !== undefined && findDuplicateKey(text) !== null;
+	const refused = doubled ? "has a key written twice" : problem ?? null;
+	// A key written twice hands back no document (issue #846): the callers ask the document whether a newer release wrote
+	// it before they read `problem`, and `{"version":1,"version":2}` would send the operator to upgrade to a release that
+	// refuses the file too. Broken, never newer, as the loader reads it and as the triggers writer does.
+	if (refused) return { doc: doubled ? null : value ?? null, problem: `the pause-windows file ${path} ${refused}, so its windows cannot be kept` };
 	return { doc: value, windows: Array.isArray(value.windows) ? value.windows : [] };
 }
 
@@ -158,7 +163,7 @@ function validateTz(tz, at, path) {
  * (unknown fields dropped; `fromMin`/`toMin` precomputed). Throws `configError` (fail-loud) on any malformed
  * entry. `path` is for messages only.
  *
- * The file's `version` is judged FIRST, before the windows (issue #761): a newer file's windows may use a shape this
+ * The file's `version` is judged right after the duplicate-key check (issue #846) and before the windows (issue #761): a newer file's windows may use a shape this
  * build would call malformed, and the true message is "upgrade". A newer file throws a configError with
  * `.newer === true` (the worker defers jobs rather than misread a pause); a broken `version`, or a window using a field
  * or a value that needs a higher version than the file declares, throws the ordinary configError. `supported`, `table`
@@ -171,6 +176,17 @@ export function parsePauseWindows(text, path, { supported = PAUSE_WINDOWS_VERSIO
 	} catch (error) {
 		throw configError(`pause-windows file is not valid JSON: ${path} (${error.message})`);
 	}
+	// Issue #846: a key written twice is REFUSED, after the parse and before anything else, as the triggers loader refuses
+	// one (`triggers.mjs`, issue #313). `JSON.parse` keeps the LAST value, so `{"windows":[...],"windows":[]}` loaded no
+	// window while a person reading the file sees two, and a reload swapped a live list down to none with nothing said:
+	// quiet hours stopped applying, which costs money in exactly the hours someone believes are paused. Refused, the boot
+	// does not start and a reload keeps the last good windows and logs why (`reloadPauseWindows`). The writers have
+	// refused such a file since #841 (`heldPauseWindows`), so only a hand edit makes one. BEFORE the version, the triggers
+	// loader's order: a doubled `version` is broken, never newer, and a newer release refuses the duplicate as well.
+	const duplicate = findDuplicateKey(text);
+	if (duplicate) {
+		throw configError(`pause-windows file has a duplicate key ${JSON.stringify(duplicate.key)} at ${duplicate.at}: JSON keeps the LAST value, so the file a person reads and the file that applies are not the same: ${path}`);
+	}
 	const problem = pauseWindowsVersionRefusal(parsed, { supported });
 	if (problem) {
 		const error = configError(`${problem.message}: ${path}`);

package/src/reason-catalog.mjs

@@ -274,7 +274,7 @@ const ROWS = [
 	["mcp-config-invalid", "Refused: the list of MCP servers could not be used: the overlay `mcp.json` before the job started, or the list the worker wrote for the job inside its container. Not run.", "Fix the overlay `mcp.json` (`pi-dispatch doctor` checks it), and run a worker and a job image of the same release."],
 	["mcp-server-unknown", mcpRefusalComment("mcp-server-unknown", null), "Declare the server in the overlay `mcp.json`, or fix the name in `run.mcp`."],
 	["mcp-secret-unmapped", mcpRefusalComment("mcp-secret-unmapped", null), "Pass the credential the server needs in the trigger's `run.secrets`."],
-	["mcp-secret-reserved", mcpRefusalComment("mcp-secret-reserved", null), "Give the server's credential a variable of its own."],
+	["mcp-secret-reserved", mcpRefusalComment("mcp-secret-reserved", null), "Give the server a variable of its own, not one the job keeps."],
 	["mcp-excluded", mcpRefusalComment("mcp-excluded", null), "Remove the server from `run.mcp`, or keep a tool that reaches it out of `run.excludeTools`."],
 	["mcp-egress-unreachable", mcpRefusalComment("mcp-egress-unreachable", null), "Add the server's host to the egress allowlist, or drop the server from `run.mcp`."],
 	["mcp-package-runner", mcpRefusalComment("mcp-package-runner", null), "Allow the package registry in the egress allowlist, or install the server in the job image."],

package/src/redact-secrets.mjs

@@ -135,6 +135,10 @@ export function makeRedactor({ values = [], extraPatterns = [] } = {}) {
 export const NON_SECRET_ENV_KEYS = new Set([
 	// Issue #693: a memory-derived concurrency count, never a credential; keep it in the structural venue env.
 	"PI_CODEMODE_MAX_WORKERS",
+	// Issue #865: the job's size, two integers, never a secret. Listed, or OpenShell would put each in the job's credential
+	// provider and the agent would read a placeholder where a tool's worker count needs the number.
+	"PI_JOB_SIZE_CPUS",
+	"PI_JOB_SIZE_MEMORY_MIB",
 	"PI_PROVIDER",
 	"PI_MODEL",
 	"PI_FORK_ENTRY",

package/src/reserved-env.mjs

@@ -37,6 +37,10 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_RUNNER_OBSERVABLE",
 	// Issue #693: derived from the resolved job memory, never chosen by a trigger or forwarded host value.
 	"PI_CODEMODE_MAX_WORKERS",
+	// Issue #865: the job's size as the job reads it (job-size.mjs `jobSizeEnv`). A trigger binding one through
+	// run.secrets, or a forwarded host value, would tell the job's tools a size the container was not given.
+	"PI_JOB_SIZE_CPUS",
+	"PI_JOB_SIZE_MEMORY_MIB",
 	"PI_PROVIDER",
 	"PI_MODEL",
 	"PI_FORK_ENTRY",

package/src/sandbox-cli.mjs

@@ -61,7 +61,9 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 
 	if (values.deployment) {
 		const { sandboxDeploymentEnv } = await import("./sandbox-deployment.mjs");
-		const loaded = await (deps.deploymentEnv ?? sandboxDeploymentEnv)({ dir: values.deployment, env, expectedHost: values["expected-host"] });
+		// Only `--new` reads the preparation's settings (#863), so only `--new` loads and compares them: an opener's open or
+		// attach must not refuse over a shell's PI_JOB_MEMORY it would never read.
+		const loaded = await (deps.deploymentEnv ?? sandboxDeploymentEnv)({ dir: values.deployment, env, expectedHost: values["expected-host"], preparing: values.new !== undefined });
 		if (loaded.refused) return fail(err, loaded.message);
 		// Readers and runtime helpers use their process's environment. Re-exec in the clean environment so none
 		// can accidentally consult the SSH shell's DOCKER_HOST, egress or rootless store (#771).
@@ -209,9 +211,13 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 	return result.code ?? 0;
 }
 
-function runDeploymentSandbox(argv, env, dir) {
+// The child runs IN the deployment folder, as the service does (its unit's WorkingDirectory), and that is load-bearing
+// (#863): a relative PI_PROJECTS_FILE, PI_SCOPED_LIMITS_FILE or PI_TRIGGERS_FILE, and an unset PI_TRIGGERS_FILE's
+// `triggers.json`, then name the files the deployment's worker reads. Resolving them here instead would be a second
+// rule for the same paths, which drifts.
+export function runDeploymentSandbox(argv, env, dir, { spawnFn = spawn } = {}) {
 	return new Promise((resolve) => {
-		const child = spawn(process.execPath, [fileURLToPath(new URL("./cli.mjs", import.meta.url)), "sandbox", ...argv], { env, ...(dir ? { cwd: dir } : {}), stdio: "inherit" });
+		const child = spawnFn(process.execPath, [fileURLToPath(new URL("./cli.mjs", import.meta.url)), "sandbox", ...argv], { env, ...(dir ? { cwd: dir } : {}), stdio: "inherit" });
 		child.once("error", () => resolve(1));
 		child.once("exit", (code) => resolve(code ?? 1));
 	});

package/src/sandbox-deployment.mjs

@@ -1,4 +1,7 @@
-/** An explicit deployment handoff is stronger than a generic deployment pointer: it loads sandbox authority only. */
+/**
+ * An explicit deployment handoff is stronger than a generic deployment pointer: it loads sandbox authority only, plus,
+ * for `--new` alone, what a sandbox's preparation reads. It never loads a forge credential.
+ */
 import * as nodeFs from "node:fs";
 import { isAbsolute, join, win32 } from "node:path";
 import { homedir } from "node:os";
@@ -10,15 +13,38 @@ export const SANDBOX_DEPLOYMENT_KEYS = Object.freeze([
 	"PI_BACKENDS", "PI_BACKEND_FLOOR", "PI_EGRESS", "PI_EGRESS_PROXY", "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_CONFIG", "DOCKER_TLS_VERIFY", "DOCKER_CERT_PATH",
 	"VALKEY_URL", "VALKEY_PASSWORD", "PI_VALKEY_SHARED", "PATH", "XDG_DATA_HOME", "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "CONTAINERS_STORAGE_CONF", "CONTAINERS_CONF", "CONTAINERS_CONF_OVERRIDE", "CONTAINERS_REGISTRIES_CONF", "CONTAINER_HOST", "CONTAINER_CONNECTION",
 ]);
+
+/**
+ * Issue #863: what `--new` reads to plan a preparation (`planSandboxPreparation`) beyond the list above. Without them a
+ * sandbox prepared through `--deployment` got no project, the default size and the default image, so its plan was not
+ * the one the deployment's own worker and the console's preview make. A relative file path names a file in the
+ * deployment folder, because the re-exec runs there as the service does (`runDeploymentSandbox`).
+ *
+ * A LIST OF ITS OWN, read only when preparing. Opening, attaching and `--list` never read these, and folding them into
+ * the list above made every opener command refuse over a shell's `PI_JOB_MEMORY` or a `.env` line such as
+ * `PI_PROJECTS_FILE=$HOME/p.json` that only the service's shell can expand. When preparing they get the same strict rule
+ * as the rest, named: a value the shell sets that the deployment does not, or sets otherwise, refuses, and so does a line
+ * that cannot be read as the service reads it. Letting the deployment's value win quietly would prepare with a setting
+ * the person did not see.
+ *
+ * The forge's credential and address are left out on purpose (#771): with none, a GitHub trigger clones with this
+ * account's own `gh` login, and a trigger on another forge cannot be prepared this way (the console's preparation runs
+ * in the worker, with its credential). sandbox-deployment-plan.test.mjs records the plan's inputs from the real preparer,
+ * and fails on a new one until it is carried in one of these lists or named there with its reason.
+ */
+export const SANDBOX_PREPARATION_KEYS = Object.freeze(["PI_TRIGGERS_FILE", "PI_PROJECTS_FILE", "PI_SCOPED_LIMITS_FILE", "PI_JOB_IMAGE", "PI_JOB_MEMORY", "PI_JOB_CPUS"]);
 const OS_KEYS = Object.freeze(["HOME", "USERPROFILE", "SystemRoot", "WINDIR", "TEMP", "TMP", "TMPDIR", "TERM", "LANG", "LC_ALL", "PATH"]);
-export function sandboxDeploymentEnv({ dir, env = process.env, expectedHost = null, fs = nodeFs, platform = process.platform, uid = process.geteuid?.(), home = homedir(), read = deploymentServiceEnv } = {}) {
+export function sandboxDeploymentEnv({ dir, env = process.env, expectedHost = null, preparing = false, fs = nodeFs, platform = process.platform, uid = process.geteuid?.(), home = homedir(), read = deploymentServiceEnv } = {}) {
 	const refuse = (message) => ({ refused: "sandbox-deployment", message });
 	if (typeof dir !== "string" || !isAbsolute(dir) || /[\x00-\x1f\x7f]/.test(dir)) return refuse("--deployment must name an absolute deployment directory");
 	// One descriptor-backed read. Ambient values are compared afterwards, never used as defaults for authority.
-	const resolved = read({ dir, env: {}, keys: SANDBOX_DEPLOYMENT_KEYS, platform, fs, uid });
+	const resolved = read({ dir, env: {}, keys: preparing ? [...SANDBOX_DEPLOYMENT_KEYS, ...SANDBOX_PREPARATION_KEYS] : SANDBOX_DEPLOYMENT_KEYS, platform, fs, uid });
 	if (resolved.unreadable || resolved.untrusted || resolved.hazard) return refuse("the deployment .env cannot be trusted or read as its service reads it; run pi-dispatch doctor");
 	if (!resolved.path || (resolved.fromFile && Object.keys(resolved.fromFile).length === 0 && resolved.env && !fs.existsSync(resolved.path))) return refuse("the deployment .env is missing; point --deployment at the installed deployment");
-	if (resolved.unread?.length || resolved.hazardSkipped?.length) return refuse("a sandbox setting cannot be read the way the deployment service reads it; run pi-dispatch doctor");
+	const unread = [...(resolved.unread ?? []).map((u) => u.key), ...(resolved.hazardSkipped ?? [])];
+	if (unread.some((key) => SANDBOX_DEPLOYMENT_KEYS.includes(key))) return refuse("a sandbox setting cannot be read the way the deployment service reads it; run pi-dispatch doctor");
+	const unreadPlan = unread.find((key) => SANDBOX_PREPARATION_KEYS.includes(key));
+	if (unreadPlan) return refuse(`the deployment's ${unreadPlan} line cannot be read the way its service reads it; run pi-dispatch doctor before preparing`);
 	const clean = { ...resolved.env };
 	for (const key of SANDBOX_DEPLOYMENT_KEYS) {
 		if (typeof env[key] !== "string") continue;
@@ -38,11 +64,18 @@ export function sandboxDeploymentEnv({ dir, env = process.env, expectedHost = nu
 		if (key === "XDG_CONFIG_HOME" && env[key] === join(home, ".config")) { clean[key] = env[key]; continue; }
 		return refuse(`the shell sets sandbox authority absent from the deployment: ${key}; unset that variable before opening`);
 	}
+	if (preparing) {
+		for (const key of SANDBOX_PREPARATION_KEYS) {
+			if (typeof env[key] !== "string") continue;
+			if (typeof clean[key] !== "string") return refuse(`the shell sets ${key}, which the deployment's .env does not set; unset that variable before preparing`);
+			if (clean[key] !== env[key]) return refuse(`the shell disagrees with the deployment for ${key}; unset that variable before preparing`);
+		}
+	}
 	const result = {};
 	for (const key of OS_KEYS) if (typeof env[key] === "string") result[key] = env[key];
 	// env-internal HOME: compare the launching account's home to the OS identity before opening a rootless store.
 	if (platform !== "win32" && env.HOME && env.HOME !== home) return refuse("HOME is not this account's home; open the sandbox as the worker's account");
-	for (const key of SANDBOX_DEPLOYMENT_KEYS) if (typeof clean[key] === "string") result[key] = clean[key];
+	for (const key of preparing ? [...SANDBOX_DEPLOYMENT_KEYS, ...SANDBOX_PREPARATION_KEYS] : SANDBOX_DEPLOYMENT_KEYS) if (typeof clean[key] === "string") result[key] = clean[key];
 	if (typeof result.PATH === "string" && (/[\x00-\x1f\x7f]/.test(result.PATH) || result.PATH.split(platform === "win32" ? ";" : ":").some((part) => !part || !(platform === "win32" ? win32.isAbsolute(part) : isAbsolute(part))))) return refuse("the sandbox runtime PATH must contain only absolute tool directories; correct PATH in the deployment .env");
 	try {
 		if (expectedHost !== null && workerName(result) !== expectedHost) return refuse("the deployment worker name does not match the opener host; check Fleet and the local opener configuration");

package/src/sandbox-prepare.mjs

@@ -21,6 +21,13 @@ const PREPARATION_LOCK_MAX_BYTES = 16 * 1024;
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 const refused = (reason, message) => ({ refused: reason, message });
 const configRefusal = () => refused("sandbox-config-invalid", "the host's sandbox configuration could not be read; run pi-dispatch doctor on that host");
+/**
+ * What a preparation needs set to clone from each forge whose address is configuration (#863), as `config.mjs` reads
+ * them (`loadGitLabAuth`, `loadForgejoAuth`, `loadAzureAuth`: no block at all without the token). GitHub's address is
+ * fixed. Named in the refusal so it says what to set, in words true both in a worker serving the console and in a
+ * terminal; sandbox-prepare.test.mjs holds each name to `loadConfig`.
+ */
+export const SANDBOX_FORGE_SETTINGS = Object.freeze({ gitlab: "GitLab (GITLAB_TOKEN, and GITLAB_URL when it is not gitlab.com)", forgejo: "Forgejo (FORGEJO_TOKEN and FORGEJO_URL)", azure: "Azure DevOps (AZURE_TOKEN and AZURE_ORG_URL)" });
 
 export function sandboxTriggerDigest(text, index) {
 	const rows = JSON.parse(text)?.triggers;
@@ -123,11 +130,18 @@ export function createSandboxPreparer({ env = process.env, config = loadConfig(e
 		catch (error) { if (error?.piDispatchConfig || error?.code === "ENOENT") return configRefusal(); throw new Error("sandbox preparation configuration read failed", { cause: error }); }
 		if (planned.refused) return planned;
 		const { plan } = planned;
+		// A forge's settings are configuration, so a preparation without usable ones is a determinate refusal, said here
+		// before any directory, lock, credential or clone. Inside the directories' catch below it read as infrastructure: the
+		// CLI said "try again" and the control queue retried a request that can never succeed (#863,
+		// CONST-RETRY-INFRA-ONLY). The plan has already refused a malformed repository (`sandbox-repo-invalid`, from the same
+		// `sandboxRepoProblem` this calls), so what is left to throw is the forge's settings: no block at all (its token is
+		// unset, whatever its URL says), or an address that is not a plain http(s) URL.
+		let remote;
+		try { remote = sandboxRemoteUrl(plan.kind, plan.repo, config); }
+		catch { return refused("sandbox-forge-unconfigured", `this preparation has no usable settings for ${SANDBOX_FORGE_SETTINGS[plan.kind] ?? "the trigger's forge"}, so it cannot clone the repository`); }
 		const id = request.id ?? newSandboxId();
 		const fingerprint = hash(JSON.stringify({ plan, by: request.by ?? null }));
-		let remote;
 		try {
-			remote = sandboxRemoteUrl(plan.kind, plan.repo, config);
 			ensureDir(config.sandboxDir, { env });
 			fs.mkdirSync(config.sandboxDir, { recursive: true, mode: 0o700 });
 			ensureDir(config.sandboxDir, { env });

package/src/sandbox.mjs

@@ -10,7 +10,7 @@ import { configError } from "./config.mjs";
 import { assertJobUser, CONTAINER_HOME, SHIPPED_IMAGE_UID } from "./container-spec.mjs";
 import { insideDir } from "./docker-run.mjs";
 import { CGROUP_PARENT, cgroupParentFor } from "./cpu-reserve.mjs";
-import { DEFAULT_JOB_SIZE, recordedJobSize } from "./job-size.mjs";
+import { DEFAULT_JOB_SIZE, jobSizeEnv, recordedJobSize } from "./job-size.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
 import { decideJobUser, JOB_USER_FIX, makeDaemonFactsReader, relabelsPrivateMounts, resolveImageUser, socketFacts } from "./job-user.mjs";
 import { DEFAULT_EGRESS_PROXY, NETWORK_SUFFIX, createJobNetwork, egressArmed, egressEnv, egressProxyName, networkEndpoints, networkExists, networkNameFor, removeJobNetwork, removeNetworkOrSay } from "./egress.mjs";
@@ -43,7 +43,8 @@ export { SANDBOX_LAUNCHERS, SANDBOX_OPEN_GRACE_MS, sandboxLauncher, sandboxSyncR
  *     (env-allowlist.mjs) and throws outright when no provider credential resolves, so a credential-free
  *     container cannot be produced from it. The env here is two variables about the terminal, plus the four
  *     proxy variables when an egress policy is armed, plus `HOME=/home/pi` beside `--user` when the run had a job
- *     user (issue #341).
+ *     user (issue #341), plus the size the manifest records (`PI_JOB_SIZE_CPUS`, `PI_JOB_SIZE_MEMORY_MIB`, issue #865):
+ *     the run's, or for a prepared sandbox the size its trigger's jobs get.
  *   - No `/outbox`, no `/session`, no `/opt/pi-global`. The agent is not running; there is nothing to
  *     chain, no transcript to continue and no overlay to layer.
  *
@@ -177,9 +178,15 @@ export function buildSandboxRunArgs({ venue = DEFAULT_BACKEND, image, name, work
 			TMOUT: idleSeconds > 0 ? String(idleSeconds) : undefined,
 			// Beside `--user` only (issue #341). Not a credential either.
 			HOME: user !== null ? home : undefined,
+			// Issue #865: the size this shell is built at (`size`: the manifest's, the run's own or, for a prepared
+			// sandbox, its trigger's), by the job env's own function (`jobSizeEnv`), so a flow command copied in here
+			// (`jest --maxWorkers=$PI_JOB_SIZE_CPUS`) sizes its pool as a job of that size would instead of expanding to
+			// nothing. A run retained before this release never had the variables; its shell gets them for its recorded
+			// size all the same. Two integers, not a credential.
+			...jobSizeEnv(size),
 			// Still NO CREDENTIALS, and that clause is untouched: a proxy URL is not a credential, and
 			// buildContainerEnv is still not reused here. The env is two variables about the terminal, HOME
-			// beside `--user`, and, when a policy is armed, four about the network.
+			// beside `--user`, two about the run's size and, when a policy is armed, four about the network.
 			...proxyEnv,
 		},
 		// Ahead of the env and the mounts, and well ahead of the image, which the builder keeps as