@edgehero/pi-dispatch 5.2.0 → 5.2.1

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

package/src/service-env.mjs

@@ -237,7 +237,8 @@ export function readDeploymentEnv({ dir, fs, uid = process.geteuid?.(), names =
 /**
  * The `.env` of the deployment in `dir`, read the way doctor reads it (a regular file only, as bytes, one read) and
  * resolved for `keys` (`resolveServiceEnv`). For a caller that has no file of its own in hand (the admin panel).
- * Returns the resolution plus `path`, `unreadable` (a reason, when something is at the path and could not be read) and
+ * Returns the resolution plus `path`, `absent` (true when nothing is at the path: issue #845's console tells a file that
+ * went away from one that never was), `unreadable` (a reason, when something is at the path and could not be read) and
  * `untrusted` (`envFileTrust`'s reason); in either case nothing was taken from it. `shellRunsLine` is the line a sourcing shell does
  * not read as an assignment, whatever keys were asked for: it can set any of them without spelling one (`. ./more.env`, `eval`), so
  * `hazardSkipped`, which needs the key spelled, says nothing of it. Only for that loader: systemd ignores such a line and the cmd wrapper
@@ -245,11 +246,11 @@ export function readDeploymentEnv({ dir, fs, uid = process.geteuid?.(), names =
  */
 export function deploymentServiceEnv({ env, dir, keys, platform = process.platform, fs, uid = process.geteuid?.() }) {
 	// Issue #471 (gate rounds 1 and 2): one descriptor, and nothing taken from a file another account can change.
-	const { path, bytes, unreadable, untrusted } = readDeploymentEnv({ dir, fs, uid });
+	const { path, bytes, absent, unreadable, untrusted } = readDeploymentEnv({ dir, fs, uid });
 	const raw = untrusted ? null : bytes;
 	const file = raw === null ? null : serviceEnvFileOf(raw, path, serviceEnvLoader(platform));
 	const shellRunsLine = file?.loader === "shell" && file.hazard !== null && file.hazard.shape !== "shell-crlf-comment" ? file.hazard.line : null;
-	return { ...resolveServiceEnv({ env, file, keys }), path, unreadable, untrusted, hazard: file?.hazard ?? null, shellRunsLine };
+	return { ...resolveServiceEnv({ env, file, keys }), path, absent, unreadable, untrusted, hazard: file?.hazard ?? null, shellRunsLine };
 }
 
 /**

package/src/size-suggest.mjs

@@ -39,6 +39,12 @@
  *   4. otherwise it fits.
  *   A FACT (no call) rides along when runs at the limit were also under real memory pressure (`memFullUsec` above 1%
  *   of the wall time): information, never an instruction.
+ *   An `oom-killed` raise also says what CPU count the killed runs' tools counted at least (issue #865, `oomCeiling`,
+ *   worded as `memoryCeiling`): on a venue whose `--cpus` is the host ceiling (`CEILING_VENUES`), the fewest whole CPUs
+ *   a run's ceiling gives `os.availableParallelism()` (`seenCpusOf`), from its record's `capacity`, when that is more
+ *   than its size in whole CPUs (`PI_JOB_SIZE_CPUS`). A tool that starts a worker per CPU it sees starts one per such CPU inside the size's memory,
+ *   so a smaller pool may be a cheaper fix than a larger size. Information beside the raise, which is the same either
+ *   way.
  *   A size is rounded UP to a step: 256m up to 2g, 512m up to 8g, then 1g.
  * CPUs: fewer than `SUGGEST_MIN_SAMPLES` runs is not enough runs; the p95 cores used (CPU time over wall time) below
  * 0.4x the current cpus lowers to 1.25x that p95, never below 1.25x the window's largest cores used, nor 0.25;
@@ -59,7 +65,7 @@
  * land on the side the rule says, on every host.
  */
 
-import { JOB_CPUS_CEILING_CENTI, JOB_CPUS_FLOOR_CENTI, JOB_MEMORY_CEILING_MIB, JOB_MEMORY_FLOOR_MIB, formatCpus, formatMemory, recordedJobSize } from "./job-size.mjs";
+import { HOST_CPUS_MAX, JOB_CPUS_CEILING_CENTI, JOB_CPUS_FLOOR_CENTI, JOB_MEMORY_CEILING_MIB, JOB_MEMORY_FLOOR_MIB, cpuCeilingCenti, formatCpus, formatMemory, recordedJobSize, wholeCpusOf } from "./job-size.mjs";
 
 /** How far back a suggestion reads: 30 days. */
 export const SUGGEST_WINDOW_DAYS = 30;
@@ -93,6 +99,18 @@ export const MEMORY_HELD = Object.freeze(["cap", "largest", "no-cap"]);
 export const MEMORY_CAP_MISSING = Object.freeze(["unread", "none-holds", "off"]);
 /** The facts a suggestion may carry with no call: memory `pressure`, CPU `ceiling`. */
 export const SIZE_FACTS = Object.freeze(["pressure", "ceiling"]);
+/**
+ * Issue #865: the venues whose job containers get the host's CPU ceiling as `--cpus`, the same for every job
+ * (job-size.mjs `containerSizing`, on the docker and podman builders alike), so a job's tools count at least the ceiling
+ * (`seenCpusOf`) and never its size. OpenShell's venues are not here: their `--cpu` is the job's size itself
+ * (backend-openshell.mjs `sizeArgs`), so on cgroup v2 a tool there reads the size rounded down from one CPU up, and
+ * under one CPU (0.25 to 0.99) the gateway's whole runtime, whose CPU count the record does not hold (its
+ * `capacity.cpus` is this host's runtime's, and the gateway may be another machine). That last case is a residual,
+ * named in `DES-JOB-SIZE-IN-THE-ENV`, not a clause said on a guess. Restated, since this module imports nothing heavy, and held
+ * to backends.mjs by a test: every venue is in this list or in `OPENSHELL_BACKENDS`, so a new venue fails it until
+ * someone says which it is.
+ */
+export const CEILING_VENUES = Object.freeze(["local", "podman"]);
 
 const MIB = 1024 * 1024;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -117,9 +135,60 @@ function rank(sorted, pct) {
 
 const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
 
+/**
+ * Issue #865: the whole CPUs a run's tools read through `os.availableParallelism()`, as its record gives it, or null. The
+ * `--cpus` ceiling comes from the record's `capacity` (`cpus`, the runtime's CPU count, and `cpuCenti`, the host's CPU
+ * budget, each judged again here) through the worker's own `cpuCeilingCenti`, on a venue in `CEILING_VENUES` only, and
+ * becomes a count by `seenCpusOf`. Null for any other venue, a record with no readable `capacity` (every record before
+ * issue #599, and every refusal before a slot), a capacity that names neither, and a ceiling under one CPU on a record
+ * whose runtime count is not known.
+ * The record holds what the host offered at admission, not the argv itself, so this is the ceiling the worker computes
+ * from those facts. Where the budget's read of the runtime gave no CPU count, the record holds the worker's own count
+ * instead (index.mjs `capacityNow`), which on Docker Desktop is the Mac's and not the VM's, so the value is then an
+ * estimate of what the tools read. Accepted, rather than a record field for the argv's own `--cpus`: the clause is
+ * information beside a raise that does not depend on it, and that read failing while a job still ran is rare.
+ */
+function seenOf(record) {
+	if (!CEILING_VENUES.includes(record.backend)) return null;
+	const c = record.capacity;
+	if (c === null || typeof c !== "object" || Array.isArray(c)) return null;
+	const cpus = Number.isSafeInteger(c.cpus) && c.cpus >= 1 && c.cpus <= HOST_CPUS_MAX ? c.cpus : null;
+	const budget = Number.isSafeInteger(c.cpuCenti) && c.cpuCenti >= 1 && c.cpuCenti <= HOST_CPUS_MAX * 100 ? c.cpuCenti : null;
+	const ceilingCenti = cpuCeilingCenti(cpus, budget);
+	return ceilingCenti === null ? null : seenCpusOf(ceilingCenti, cpus);
+}
+
+/**
+ * Issue #865: the libuv the rule in `seenCpusOf` was read at, the one the job image's Node bundles (the Node
+ * image/Dockerfile notes its base resolves to). The next minor release, 1.52.0, changed it
+ * (`uv__get_cgroupv2_constrained_cpu` answers 1 for a quota under one CPU, where this release answers 0 and the caller
+ * skips it), so the image job compares the built image's `process.versions.uv` and `process.versions.node` with this
+ * and with that note (.github/scripts/libuv-pin-check.mjs, in "the job image holds its contract") and fails on any
+ * other, saying to read the rule again at the new libuv before moving this.
+ */
+export const SEEN_CPUS_LIBUV = "1.51.0";
+
+/**
+ * Issue #865: the fewest whole CPUs a tool counts through `os.availableParallelism()` in a container with a `--cpus`
+ * ceiling in hundredths, or null, where `runtimeCpus` is the runtime's own count (the container's affinity mask holds all
+ * of it, so `nproc` reads it). A LOWER BOUND, since what libuv reads depends on the host's cgroup version, which the
+ * record does not hold. Read at libuv `SEEN_CPUS_LIBUV`: on cgroup v2, `uv__get_constrained_cpu` (src/unix/linux.c)
+ * sets the quota to `cpu.max`'s limit over its period in INTEGER division, and `uv_available_parallelism`
+ * (src/unix/core.c) takes it only `if (quota > 0 && quota < rc)`, where `rc` is the affinity count: a ceiling of 2.5
+ * reads as 2 (ROUNDED DOWN, where `PI_JOB_SIZE_CPUS` rounds the size up), and one under one CPU gives a quota of 0,
+ * which is skipped, so the tool reads the WHOLE runtime. On cgroup v1, `uv__cgroup1_find_cpu_controller` turns
+ * `N:cpu,cpuacct:/path` into a `/sys/fs/cgroup/cpuacct:/path` that does not exist, so the read fails and the tool reads
+ * the whole runtime at any ceiling. So a tool counts at least the ceiling rounded down, and under one CPU the whole
+ * runtime: null when the record does not say how many that is.
+ */
+function seenCpusOf(ceilingCenti, runtimeCpus) {
+	if (ceilingCenti >= 100) return Math.floor(ceilingCenti / 100);
+	return Number.isSafeInteger(runtimeCpus) && runtimeCpus >= 1 ? runtimeCpus : null;
+}
+
 /**
  * One record as a suggestion reads it, or null when it is not evidence: `{ at, size, memPeak, oom, wallUsec, cpuUsec,
- * throttledUsec, memFullUsec }`. `memPeak` (bytes, clamped to the record's own limit) is null when absent or not a
+ * throttledUsec, memFullUsec, seenCpus }`. `memPeak` (bytes, clamped to the record's own limit) is null when absent or not a
  * count; `wallUsec` is null unless the span is readable; `cpuUsec` is null unless it can be read with a wall time (CPU
  * time clamped to the CPU ceiling over the wall), and `throttledUsec` likewise on its own (clamped to the wall): cgroup v2
  * writes `throttled_usec` in `cpu.stat` only where the cpu controller is enabled, so a run without it is still a CPU
@@ -145,7 +214,7 @@ function evidenceOf(record, project, nowMs) {
 	// unclamped: it is only ever compared (exactly, in BigInt) with 1% of the wall, and a stall past the wall is above it
 	const memFullUsec = wallUsec !== null && isCount(r.memFullUsec) ? r.memFullUsec : null;
 	if (memPeak === null && cpu.cpuUsec === null) return null;
-	return { at, size, memPeak, oom: record.reason === "oom-killed", wallUsec, ...cpu, memFullUsec };
+	return { at, size, memPeak, oom: record.reason === "oom-killed", wallUsec, ...cpu, memFullUsec, seenCpus: seenOf(record) };
 }
 
 /** a x b > c x d, exactly. */
@@ -164,6 +233,25 @@ function heldToCap(wanted, current, cap) {
 	return { suggested: wanted, held: null };
 }
 
+/**
+ * Issue #865: what CPU count the killed runs' tools counted at least, against their size, or null: over the
+ * `oom-killed` runs that decide a raise (the same ones `ooms` counts), those where the fewest CPUs their tools could
+ * count (`seenOf`) is more than their size rounded up, which is what `PI_JOB_SIZE_CPUS` tells them. At or below it nothing can be said:
+ * a pool sized from the variable may be the pool the ceiling gave. `{ runs, seenCpus, seenMaxCpus, sizeCenti,
+ * sizeVaries }`: how many such runs, the fewest and the most CPUs their tools counted at least (equal when every run
+ * gives the same bound), and the smallest CPU size among them and whether their sizes differ. Either can vary alone
+ * (one host's ceiling under projects of several sizes, or one size across hosts), and the words say a range for that
+ * one only.
+ */
+function oomCeilingOf(relevant) {
+	const over = relevant.filter((e) => e.oom && e.seenCpus !== null && e.seenCpus > wholeCpusOf(e.size.cpuCenti));
+	if (over.length === 0) return null;
+	const seen = over.map((e) => e.seenCpus);
+	const sizes = over.map((e) => e.size.cpuCenti);
+	const sizeCenti = Math.min(...sizes);
+	return { runs: over.length, seenCpus: Math.min(...seen), seenMaxCpus: Math.max(...seen), sizeCenti, sizeVaries: sizes.some((n) => n !== sizeCenti) };
+}
+
 function suggestMemory(runs, current, cap) {
 	const measured = runs.filter((e) => e.memPeak !== null);
 	const relevant = measured.filter((e) => e.size.memMiB >= current);
@@ -176,7 +264,7 @@ function suggestMemory(runs, current, cap) {
 	// at the limit (90% of it or more: peak x 10 >= limit x 9) AND stalled for memory more than 1% of the wall.
 	const pressured = relevant.filter((e) => !productAbove(e.size.memMiB * MIB, 9, e.memPeak, 10) && e.memFullUsec !== null && productAbove(e.memFullUsec, 100, e.wallUsec, 1)).length;
 	// `smaller`: the measured runs below the current size, which a chart draws and this verdict does not count.
-	const evidence = { samples, smaller: measured.length - samples, p95MiB: p95 === null ? null : Math.ceil(p95 / MIB), maxPeakMiB: maxPeak === null ? null : Math.ceil(maxPeak / MIB), ooms, largestOomMiB: largestOom, pressured };
+	const evidence = { samples, smaller: measured.length - samples, p95MiB: p95 === null ? null : Math.ceil(p95 / MIB), maxPeakMiB: maxPeak === null ? null : Math.ceil(maxPeak / MIB), ooms, largestOomMiB: largestOom, pressured, oomCeiling: oomCeilingOf(relevant) };
 	const fact = pressured > 0 ? "pressure" : null;
 	const out = (reason, suggested, more = {}) => ({ current, suggested: suggested === null || suggested === current ? null : suggested, reason, evidence, fact, held: null, wanted: null, ...more });
 	if (ooms > 0) {
@@ -419,12 +507,33 @@ export function notEnoughRunsText(dim, sizeText) {
 	return `not enough runs at ${sizeText(dim.current)} (${samples}${smaller})`;
 }
 
+/**
+ * Issue #865: the CPU count the killed runs' tools counted at least, in words, or "" when the evidence carries none
+ * (`oomCeilingOf`): `size per-CPU worker pools from PI_JOB_SIZE_CPUS: the killed run's tools counted at least 15 CPUs
+ * at a size of 2 CPUs`. "At least", since the count is a lower bound (`seenCpusOf`). A word of its own
+ * (`memoryCeiling`), not part of the OOM words: every surface prints it AFTER the suggestion, a held raise and a refusal
+ * (doctor ahead of its two facts; the console's card as the last of the suggestion's notes, before the card's advisory
+ * note, with the call's block below the notes; the panel and the confirm after their facts), so where a surface cuts a
+ * line (doctor publishes a label at most `DOCTOR_LABEL_MAX` long) the facts go first, then this, never the call, a held
+ * raise or a refusal. Short for the same cap, and the variable first, so a cut keeps the pointer as long as it can. A
+ * pointer, never a call: the raise is the same either way.
+ */
+function oomCeilingWords(me) {
+	const o = me?.oomCeiling;
+	if (o === null || typeof o !== "object" || !Number.isSafeInteger(o.runs) || o.runs < 1 || !Number.isSafeInteger(o.seenCpus)) return "";
+	const ooms = Number.isSafeInteger(me.ooms) && me.ooms >= o.runs ? me.ooms : o.runs;
+	const whose = ooms === 1 ? "the killed run's tools" : o.runs === ooms ? "the killed runs' tools" : `the tools of ${o.runs} of the ${ooms} killed runs`;
+	const seen = `${o.seenCpus}${Number.isSafeInteger(o.seenMaxCpus) && o.seenMaxCpus > o.seenCpus ? ` to ${o.seenMaxCpus}` : ""} CPUs`;
+	const size = o.sizeVaries === true ? `sizes from ${cpusText(o.sizeCenti)}` : `a size of ${cpusText(o.sizeCenti)}`;
+	return `size per-CPU worker pools from PI_JOB_SIZE_CPUS: ${whose} counted at least ${seen} at ${size}`;
+}
+
 /**
  * The evidence of a suggestion in words, for doctor, the panel and the insights page alike: `{ memory, cpu, memoryHeld,
- * memoryFact, cpuFact }`, each a short clause (empty when it does not apply), such as `2 runs ended oom-killed (the
- * largest size killed 4g)` or `p95 peak 2560m, largest 3g, over 24 runs`. Ids and numbers only. A fact is worded as
- * information and a held raise as what the host offers: none of them is an instruction, and none advises growing a
- * host's budget.
+ * memoryFact, cpuFact, memoryCeiling }`, each a short clause (empty when it does not apply), such as `2 runs ended
+ * oom-killed (the largest size killed 4g)` or `p95 peak 2560m, largest 3g, over 24 runs`. Ids and numbers only. A fact
+ * is worded as information and a held raise as what the host offers, and `memoryCeiling` (issue #865) points to a
+ * variable: none of them is a call, and none advises growing a host's budget.
  */
 export function suggestionEvidence(suggestion) {
 	const m = suggestion?.memory ?? {};
@@ -457,5 +566,6 @@ export function suggestionEvidence(suggestion) {
 		memoryHeld: heldWords[m.held] ?? "",
 		memoryFact: m.fact === "pressure" ? `${me.pressured} of ${plural(me.samples, "run")} reached the memory limit while stalled for memory more than 1% of their time` : "",
 		cpuFact: c.fact === "ceiling" ? `the median run was held back ${ce.throttledPct}% of its time by this host's CPU ceiling (its CPU budget, shared by every job), which a job's cpus do not change` : "",
+		memoryCeiling: m.reason === "oom-killed" ? oomCeilingWords(me) : "",
 	};
 }

package/src/touch-outbox.mjs

@@ -54,6 +54,11 @@ export async function trackTouchAction({ store, outbox = null, event, act, succe
 	const writer = outbox ?? { begin: (e) => store.begin(e), applied: (intent) => store.write(intent.event), abort: (intent) => store.abort(intent.event) };
 	const intent = await writer.begin(event);
 	let result;
+	// Aborted on any throw, also one whose answer was lost (`valkeyMayStillRun`, issue #867): a cancel's removal that then
+	// lands is a stop not counted, so the stops count can be one short (the rate is unaffected, since stops never enter
+	// its denominator). REJECTED: keeping the intent pending as unknown. Nothing resolves it (a rerun finds no job, the CLI
+	// has no outbox, `repair()` only begins it again), so the store reads `touch-actions-unresolved` with its coverage reset
+	// to now, the Zero touch page reads unavailable, and every later tracked action renews its 30-day TTL.
 	try { result = await act(); } catch (error) { await writer.abort(intent); throw error; }
 	if (!succeeded(result)) { await writer.abort(intent); return result; }
 	const tracked = await writer.applied(intent);