@edgehero/pi-dispatch 3.1.0 → 4.0.0

package/src/live-probes.mjs

@@ -28,7 +28,9 @@
  */
 
 import { READ_BACK_BY_A_LIVE_PROBE } from "./backend-conformance.mjs";
-import { containerSpec } from "./container-spec.mjs";
+import { containerSpec, memoryBytes } from "./container-spec.mjs";
+import { CGROUP_PARENT, DEFAULT_JOB_SIZE } from "./job-size.mjs";
+import { cpuMaxLine, parseCpuMaxRead } from "./cpu-reserve.mjs";
 import { ISOLATION_FLAGS, buildDockerRunArgs } from "./docker-run.mjs";
 import { DEFAULT_EGRESS_PROXY, EGRESS_PROXY_PORT, createJobNetworkWith, networkEndpoints, networkNameFor, removeNetworkOrSay } from "./egress.mjs";
 import { detachBlockedSentence, makeDetachGate } from "./netns-keeper.mjs";
@@ -112,8 +114,14 @@ export function liveFixture(root) {
 // `relabel` (issue #355) is a job's too: where a job's own mounts carry `:Z`, so do the probe's, because a probe mounted
 // the way no job is would read back a container no job gets. The fixture is doctor's own directory, so its workspace
 // is relabelled like a forge job's clone (`workspaceOwned`); its global overlay directory never is, exactly as a job's.
-function probeOptions({ image, name, fixture, user = null, relabel = false }) {
-	return { image, name, env: {}, network: "none", user, relabel: relabel === true, workspaceOwned: true, ...fixture };
+//
+// `size` and `hostCpus` (issue #596) are a job's too: the deployment's default size and the `--cpus` ceiling of this
+// runtime's own CPU count, so the probe is bounded exactly as a job without a project size is, and reads that back.
+//
+// `cgroupParent` (issue #596, phase 2) is a job's too: the jobs' parent cgroup, or null where this venue runs jobs without
+// it (`cgroupParentFor`), so the probe sits where a job sits and `cgroupParentVerdict` reads that back.
+function probeOptions({ image, name, fixture, user = null, relabel = false, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
+	return { image, name, env: {}, network: "none", user, relabel: relabel === true, workspaceOwned: true, size, hostCpus, cgroupParent, ...fixture };
 }
 
 // `buildArgs` (issue #354) is the RUNTIME's job builder, never a second one: each probe below is built by whichever
@@ -121,32 +129,32 @@ function probeOptions({ image, name, fixture, user = null, relabel = false }) {
 // The default is docker's, so every argv here is byte-for-byte what it was.
 
 /** The probe container's argv: the job builder's, detached, with `sleep <derived seconds>` as its whole program. */
-export function liveProbeRunArgs({ image, name, fixture, sleepSeconds = liveSleepSeconds(), user = null, relabel = false, buildArgs = buildDockerRunArgs }) {
-	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel }), extraFlags: ["-d", "--entrypoint", "sleep"] }), String(sleepSeconds)];
+export function liveProbeRunArgs({ image, name, fixture, sleepSeconds = liveSleepSeconds(), user = null, relabel = false, buildArgs = buildDockerRunArgs, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
+	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel, size, hostCpus, cgroupParent }), extraFlags: ["-d", "--entrypoint", "sleep"] }), String(sleepSeconds)];
 }
 
 /**
  * The pinning probe's argv: the job builder's, detached, against an image this host does not have. Detached so a
  * container that WAS created prints the ID it is removed by; with `--pull=never` in the builder none should be.
  */
-export function pinningProbeRunArgs({ name, nonce, fixture, user = null, relabel = false, buildArgs = buildDockerRunArgs }) {
-	return buildArgs({ ...probeOptions({ image: absentImageRef(nonce), name, fixture, user, relabel }), extraFlags: ["-d"] });
+export function pinningProbeRunArgs({ name, nonce, fixture, user = null, relabel = false, buildArgs = buildDockerRunArgs, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
+	return buildArgs({ ...probeOptions({ image: absentImageRef(nonce), name, fixture, user, relabel, size, hostCpus, cgroupParent }), extraFlags: ["-d"] });
 }
 
 /**
  * One ephemeral run's argv (issue #344): the job builder's, detached, running EPHEMERAL_SCRIPT with the nonce and the
  * run's number. The same NAME both times, because "a job id run twice" is the question.
  */
-export function ephemeralRunArgs({ image, name, fixture, nonce, run, user = null, relabel = false, buildArgs = buildDockerRunArgs }) {
-	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel }), extraFlags: ["-d", "--entrypoint", "sh"] }), "-c", EPHEMERAL_SCRIPT, "sh", nonce, String(run)];
+export function ephemeralRunArgs({ image, name, fixture, nonce, run, user = null, relabel = false, buildArgs = buildDockerRunArgs, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
+	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel, size, hostCpus, cgroupParent }), extraFlags: ["-d", "--entrypoint", "sh"] }), "-c", EPHEMERAL_SCRIPT, "sh", nonce, String(run)];
 }
 
 /**
  * One peer's argv (issue #344): the job builder's, detached, on its OWN job network, running PEER_SCRIPT, which answers
  * every connection with the nonce for `seconds`. Built with `network` set exactly as a job with egress armed is.
  */
-export function peerRunArgs({ image, name, fixture, network, nonce, seconds = liveSleepSeconds(), user = null, relabel = false, buildArgs = buildDockerRunArgs }) {
-	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel }), network, extraFlags: ["-d", "--entrypoint", "node"] }), "--eval", PEER_SCRIPT, nonce, String(PEER_PORT), String(seconds)];
+export function peerRunArgs({ image, name, fixture, network, nonce, seconds = liveSleepSeconds(), user = null, relabel = false, buildArgs = buildDockerRunArgs, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
+	return [...buildArgs({ ...probeOptions({ image, name, fixture, user, relabel, size, hostCpus, cgroupParent }), network, extraFlags: ["-d", "--entrypoint", "node"] }), "--eval", PEER_SCRIPT, nonce, String(PEER_PORT), String(seconds)];
 }
 
 /**
@@ -156,6 +164,9 @@ export function peerRunArgs({ image, name, fixture, network, nonce, seconds = li
 export const STATUS_SCRIPT = [
 	"cat /proc/1/status",
 	'if [ -f /sys/fs/cgroup/cgroup.controllers ]; then echo "cgroup:v2"; echo "pids.max:$(cat /sys/fs/cgroup/pids.max 2>/dev/null)"; echo "memory.max:$(cat /sys/fs/cgroup/memory.max 2>/dev/null)";',
+	// Issue #596: the swap bound (0 when --memory-swap equals --memory), the CPU weight --cpu-shares became, and the
+	// --cpus ceiling. cgroup v2 only: v1 spells all three differently, and every venue measured is v2.
+	'echo "memory.swap.max:$(cat /sys/fs/cgroup/memory.swap.max 2>/dev/null)"; echo "cpu.weight:$(cat /sys/fs/cgroup/cpu.weight 2>/dev/null)"; echo "cpu.max:$(cat /sys/fs/cgroup/cpu.max 2>/dev/null)";',
 	'else echo "cgroup:v1"; echo "pids.max:$(cat /sys/fs/cgroup/pids/pids.max 2>/dev/null)"; echo "memory.max:$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes 2>/dev/null)"; fi',
 ].join("\n");
 
@@ -246,6 +257,9 @@ export function parseStatus(output) {
 		cgroup: field("cgroup"),
 		pidsMax: field("pids.max"),
 		memoryMax: field("memory.max"),
+		swapMax: field("memory.swap.max"),
+		cpuWeight: field("cpu.weight"),
+		cpuMax: field("cpu.max"),
 	};
 }
 
@@ -257,9 +271,34 @@ export function expectedPidsLimit(flags = ISOLATION_FLAGS) {
 
 /** The memory bound in bytes, from the spec's own default (`4g`), never a literal. */
 export function expectedMemoryBytes(memory = containerSpec({ image: "i", name: "n", workspace: "/w" }).memory) {
-	const m = /^(\d+)([kmg]?)$/i.exec(String(memory));
-	if (!m) return null;
-	return Number(m[1]) * { "": 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3 }[m[2].toLowerCase()];
+	return memoryBytes(memory);
+}
+
+/**
+ * What a container of this size reads back (issue #596), from the SAME spec builder the probe's argv came from:
+ * `{ pidsLimit, memoryBytes, cpuShares, cpuMax }`, `cpuMax` being the `cpu.max` line `--cpus` writes (`<quota> 100000`,
+ * or `max 100000` with no ceiling).
+ */
+export function expectedBounds(size = DEFAULT_JOB_SIZE, hostCpus = null, cpuBudgetCenti = null, cgroupParent = CGROUP_PARENT) {
+	const spec = containerSpec({ image: "i", name: "n", workspace: "/w", size, hostCpus, cpuBudgetCenti, cgroupParent });
+	// ROUNDED (issue #596, gate round 3 of phase 1): under a CPU budget the ceiling may be fractional (`3.3`), and
+	// `3.3 * 100000` is 329999.99999999994 in floating point, while the runtime writes the integer quota 330000.
+	return { pidsLimit: expectedPidsLimit(), memoryBytes: memoryBytes(spec.memory), cpuShares: spec.cpuShares, cpuMax: spec.cpus === null ? "max 100000" : `${Math.round(Number(spec.cpus) * 100000)} 100000` };
+}
+
+/**
+ * The `cpu.weight` a `--cpu-shares` value becomes, under the two mappings measured (issue #596): runc 1.1.13 and crun
+ * 1.14 map linearly (`1 + ((shares - 2) * 9999) / 262142`, integer division: 1024 to 39, 2048 to 79), runc 1.5.1 and
+ * crun 1.27 map so 1024 is 100 (`10^((l^2 + 125l) / 612 - 7/34)` rounded up, l = log2(shares): 2048 to 174). Both
+ * reproduce every value of the lab's sweep. A weight that is neither is a runtime nobody measured, said as such.
+ */
+export function cpuWeightsFor(shares) {
+	if (!Number.isSafeInteger(shares) || shares < 2) return [];
+	if (shares >= 262144) return [10000];
+	const linear = 1 + Math.floor(((shares - 2) * 9999) / 262142);
+	const l = Math.log2(shares);
+	const curved = Math.ceil(10 ** ((l * l + 125 * l) / 612 - 7 / 34));
+	return [...new Set([linear, curved])];
 }
 
 const verdict = (property, ok, detail, extra = {}) => ({ property, ok, detail, ...extra });
@@ -273,7 +312,7 @@ const notReadBack = (property, why) => verdict(property, false, `not read back:
  * FAILURE (the bound was not applied, as on rootless docker without delegation); a bound that could not be read at
  * all is "not read back", never a pass.
  */
-export function isolationVerdict(status, { pidsLimit = expectedPidsLimit(), memoryBytes = expectedMemoryBytes() } = {}) {
+export function isolationVerdict(status, { pidsLimit = expectedPidsLimit(), memoryBytes = expectedMemoryBytes(), cpuShares = null, cpuMax = null } = {}) {
 	if (!status || status.capBnd === null || status.noNewPrivs === null) return notReadBack("isolation", "PID 1's status did not show CapBnd and NoNewPrivs");
 	const failures = [];
 	if (!/^0+$/.test(status.capBnd)) failures.push(`CapBnd ${status.capBnd} (the capability bounding set is not empty)`);
@@ -287,10 +326,30 @@ export function isolationVerdict(status, { pidsLimit = expectedPidsLimit(), memo
 		if (Number(got) !== want) failures.push(`${name} ${got}, expected ${want}`);
 		return null;
 	};
-	const unread = [bound("pids.max", status.pidsMax, pidsLimit), bound("memory.max", status.memoryMax, memoryBytes)].filter(Boolean);
+	const unread = [bound("pids.max", status.pidsMax, pidsLimit), bound("memory.max", status.memoryMax, memoryBytes)];
+	// Issue #596, read only by a caller that passes the size's bounds (`expectedBounds`). The swap bound is part of the
+	// memory bound: `--memory-swap` equal to `--memory` makes it 0, and anything else lets a job swap past its size.
+	// `cpu.max` is the host ceiling (`--cpus`), which keeps the host's reserve, so a different one is a failure too.
+	// `cpu.weight` is the job's share, whose number depends on the runtime's version: one neither measured mapping
+	// gives is said, not failed, because the ORDER between jobs is what it carries and an unknown mapping may keep it.
+	let cpuNote = "";
+	if (cpuMax !== null) {
+		const swap = status.swapMax;
+		if (swap === null || swap === undefined || swap === "") unread.push("memory.swap.max not readable");
+		else if (swap !== "0") failures.push(`memory.swap.max ${swap}, expected 0 (a job may swap beyond its memory)`);
+		const max = status.cpuMax;
+		if (max === null || max === undefined || max === "") unread.push("cpu.max not readable");
+		else if (max !== cpuMax) failures.push(`cpu.max ${max}, expected ${cpuMax}`);
+		const weight = status.cpuWeight;
+		const known = cpuWeightsFor(cpuShares);
+		if (weight === null || weight === undefined || weight === "") unread.push("cpu.weight not readable");
+		else if (!known.includes(Number(weight))) unread.push(`cpu.weight ${weight} is neither mapping measured for --cpu-shares=${cpuShares} (${known.join(" or ")})`);
+		else cpuNote = `, memory.swap.max 0, cpu.max ${cpuMax}, cpu.weight ${weight} (--cpu-shares=${cpuShares})`;
+	}
+	const missing = unread.filter(Boolean);
 	if (failures.length > 0) return verdict("isolation", false, failures.join("; "));
-	if (unread.length > 0) return notReadBack("isolation", `${unread.join(" and ")} (cgroup ${status.cgroup ?? "unknown"}); CapBnd 0 and NoNewPrivs 1 did hold`);
-	return verdict("isolation", true, `CapBnd 0, NoNewPrivs 1, pids.max ${pidsLimit}, memory.max ${memoryBytes}`);
+	if (missing.length > 0) return notReadBack("isolation", `${missing.join(" and ")} (cgroup ${status.cgroup ?? "unknown"}); CapBnd 0 and NoNewPrivs 1 did hold`);
+	return verdict("isolation", true, `CapBnd 0, NoNewPrivs 1, pids.max ${pidsLimit}, memory.max ${memoryBytes}${cpuNote}`);
 }
 
 /** NON-ROOT: all four Uid fields (real, effective, saved, filesystem) nonzero, on the process the job would be. */
@@ -612,6 +671,60 @@ export function peerTargetsOf(inspectOutput, { network, name }) {
 	return { targets: [...[...hosts].map((h) => `${h}:${PEER_PORT}`), ...addresses], addresses };
 }
 
+/**
+ * WHERE THE RUNTIME PUT A JOB-BUILT CONTAINER (issue #596, phase 2, INT-LIVE-PROBE-CONTRACT): `{ ok, warn?, detail,
+ * placed, quota }`, from `<bin> inspect --format={{.HostConfig.CgroupParent}}|{{.State.Pid}}` and this host's own files.
+ *
+ * Three readings, each as far as this host can see. The runtime's RECORD of the parent must be the one the argv named
+ * (`expected`; none where the venue runs jobs without it). The process's own cgroup (`/proc/<pid>/cgroup`, cgroup v2's
+ * `0::<path>`) must lie under `/<parent>/`, which proves the placement rather than the flag: readable for a local Linux
+ * daemon and rootless Podman, not for a daemon in a VM (Docker Desktop), where the record alone is said as such. The
+ * container cannot see any of this itself (a private cgroup namespace shows it `0::/`, measured). Then the parent's
+ * `cpu.max`, where readable, against the CPU budget (`cpuBudgetCenti`: an integer, `Infinity` for off, null not
+ * checked): a quota that is not the budget is a WARNING, "no host CPU reserve across jobs", never a failure of the
+ * placement, because on a systemd host only the operator can set it.
+ */
+export function cgroupParentVerdict({ inspected, expected = CGROUP_PARENT, cpuBudgetCenti = null, readFile = () => {
+	throw new Error("no reader");
+}, bin = "docker" }) {
+	const out = (ok, detail, extra = {}) => ({ ok, detail, placed: null, quota: undefined, ...extra });
+	if (inspected?.code !== 0) return out(false, `not read back: ${bin} inspect did not answer`, { warn: true });
+	const [recorded = "", pidText = ""] = String(inspected.stdout ?? "").trim().split("|");
+	if (expected === null) {
+		if (recorded.includes(CGROUP_PARENT)) return out(false, `the runtime recorded the parent ${recorded} for a venue that runs jobs without one`);
+		return out(true, `this venue runs jobs without the ${CGROUP_PARENT} parent (Podman's cgroup manager is not systemd), so their CPU weight is capped at 1024: the egress proxy and Valkey get a fair share of the CPU, not a reserve`, { warn: true });
+	}
+	// The bare name, or a path ending in it (a runtime may record where the slice resolved); the process's own cgroup
+	// below is the proof either way.
+	if (recorded.replace(/^\//, "") !== expected && !recorded.endsWith(`/${expected}`)) return out(false, `the runtime recorded the parent ${JSON.stringify(recorded)}, not ${expected}, so this container is outside the jobs' CPU reserve`);
+	let cgroupText = null;
+	if (/^[1-9][0-9]{0,9}$/.test(pidText)) {
+		try {
+			cgroupText = readFile(`/proc/${pidText}/cgroup`);
+		} catch {
+			cgroupText = null;
+		}
+	}
+	const path = cgroupText === null ? null : (/^0::(\/\S*)$/m.exec(String(cgroupText))?.[1] ?? null);
+	if (path === null) return out(true, `the runtime recorded the parent ${expected}; the container's own cgroup is not readable from this host (its process runs in the runtime's VM or another namespace), so the placement and the parent's quota were not read here`, { warn: true });
+	const at = path.indexOf(`/${expected}/`);
+	if (at === -1) return out(false, `the runtime recorded the parent ${expected}, but the container's cgroup is ${path}, not under it`);
+	const parentDir = `/sys/fs/cgroup${path.slice(0, at + expected.length + 1)}`;
+	let quota;
+	try {
+		quota = parseCpuMaxRead(readFile(`${parentDir}/cpu.max`));
+	} catch {
+		quota = null;
+	}
+	const placed = path.slice(0, at + expected.length + 1);
+	if (quota === null) return out(true, `the container's cgroup is under ${placed}; the parent's cpu.max is not readable here`, { warn: true, placed });
+	const shown = quota.cpuCenti === null ? "no quota" : `a quota of ${quota.cpuCenti / 100} CPUs (${cpuMaxLine(quota.cpuCenti)})`;
+	if (cpuBudgetCenti === null || cpuBudgetCenti === undefined) return out(true, `the container's cgroup is under ${placed}, which has ${shown}`, { placed, quota: quota.cpuCenti });
+	const want = cpuBudgetCenti === Infinity ? null : cpuBudgetCenti;
+	if (quota.cpuCenti === want) return out(true, `the container's cgroup is under ${placed}, which has ${want === null ? "no quota, as the CPU budget is off" : `${shown}, the host's CPU budget, so all jobs together keep the reserve`}`, { placed, quota: quota.cpuCenti });
+	return out(true, `the container's cgroup is under ${placed}, which has ${shown}, not ${want === null ? "none (the CPU budget is off)" : `the CPU budget of ${want / 100}`}: no host CPU reserve across jobs`, { warn: true, placed, quota: quota.cpuCenti });
+}
+
 /**
  * The whole sequence. Returns `{ ran, reason, verdicts, notes, swept, ranAs }`: `ran` false with a `reason` when nothing
  * was read back; the verdicts in READ_BACK_BY_A_LIVE_PROBE's order otherwise; `notes` for a teardown that failed, on
@@ -660,6 +773,14 @@ export async function runLiveProbes({
 	// Issue #452, gate round 3: the runtime as this pass already read it (`{ podman, rootless, version } | null`), for the
 	// detach gate, so doctor asks the daemon once per run. Absent, the gate reads it itself.
 	readRuntime = null,
+	// Issue #596: the size every probe container is built at (a job's default) and the runtime's CPU count for the
+	// `--cpus` ceiling; the isolation verdict reads both back.
+	size = DEFAULT_JOB_SIZE,
+	hostCpus = null,
+	// Issue #596, phase 2: the parent cgroup a job on this venue runs under (null: none, `cgroupParentFor`) and the CPU
+	// budget its quota should be (an integer in hundredths, `Infinity` for off, null or absent: not checked).
+	cgroupParent = CGROUP_PARENT,
+	cpuBudgetCenti = null,
 }) {
 	const notRun = (reason) => ({ ran: false, reason, verdicts: [], notes: [], swept: [] });
 	const notLocal = notRun(`this shell's ${bin} CLI is not observed to point at this host, so bind paths and .Mounts would describe another machine; nothing was run`);
@@ -764,7 +885,7 @@ export async function runLiveProbes({
 		}
 
 		// --- the reading container: mounts, status, writes ---
-		const reading = await start("probe container", names.probe, liveProbeRunArgs({ image, name: names.probe, fixture, sleepSeconds: liveSleepSeconds(stepTimeoutMs), user, relabel, buildArgs }));
+		const reading = await start("probe container", names.probe, liveProbeRunArgs({ image, name: names.probe, fixture, sleepSeconds: liveSleepSeconds(stepTimeoutMs), user, relabel, buildArgs, size, hostCpus, cgroupParent }));
 		const probeId = reading.entry.id;
 		if (reading.result?.code !== 0 || probeId === null) {
 			// The runtime's own words, when it printed any (issue #453, gate round 1): "did not start" alone left the operator
@@ -773,7 +894,7 @@ export async function runLiveProbes({
 			return { ran: false, reason: `the probe container did not start${said ? ` (${bin} said: ${said})` : ""}, so nothing was read back`, verdicts: [], notes, swept };
 		}
 
-		const expected = containerSpec(probeOptions({ image, name: names.probe, fixture, user, relabel })).mounts;
+		const expected = containerSpec(probeOptions({ image, name: names.probe, fixture, user, relabel, size, hostCpus, cgroupParent })).mounts;
 		const inspected = await step(["inspect", "--format={{json .Mounts}}", probeId]);
 		// Issue #345: the mount table as the container itself sees it, by a constant `cat`, for what `.Mounts` does not list.
 		const mountinfo = await step(["exec", probeId, "cat", "/proc/self/mountinfo"]);
@@ -781,8 +902,12 @@ export async function runLiveProbes({
 
 		const statusRun = await step(["exec", probeId, "sh", "-c", STATUS_SCRIPT]);
 		const status = statusRun?.code === 0 ? parseStatus(statusRun.stdout) : null;
-		const isolation = status ? isolationVerdict(status) : notReadBack("isolation", "the status probe did not run in the container");
+		const isolation = status ? isolationVerdict(status, expectedBounds(size, hostCpus, null, cgroupParent)) : notReadBack("isolation", "the status probe did not run in the container");
 		const nonRoot = status ? nonRootVerdict(status) : notReadBack("nonRoot", "the status probe did not run in the container");
+		// Issue #596, phase 2: where the runtime put the container (its record, and the process's own cgroup where this host
+		// can read it) and, where readable, the parent's quota. Its own line, not one of the declared properties.
+		const placed = await step(["inspect", "--format={{.HostConfig.CgroupParent}}|{{.State.Pid}}", probeId]);
+		const parentRead = cgroupParentVerdict({ inspected: placed, expected: cgroupParent, cpuBudgetCenti, readFile: (path) => fs.readFileSync(path, "utf8"), bin });
 
 		const written = await step(["exec", probeId, "sh", "-c", WRITE_SCRIPT, "sh", nonce]);
 		const readBack = (dir) => {
@@ -807,7 +932,7 @@ export async function runLiveProbes({
 		await release(reading.entry);
 
 		// --- the pinning container: an image this host does not have ---
-		const pinning = await start("pinning container", names.pin, pinningProbeRunArgs({ name: names.pin, nonce, fixture, user, relabel, buildArgs }));
+		const pinning = await start("pinning container", names.pin, pinningProbeRunArgs({ name: names.pin, nonce, fixture, user, relabel, buildArgs, size, hostCpus, cgroupParent }));
 		const after = await step(["image", "inspect", absentImageRef(nonce)]);
 		const stillAbsent = after?.code === 0 ? false : typeof after?.code === "number" ? true : null;
 		const imagePinning = imagePinningVerdict({ code: pinning.result?.code, output: `${pinning.result?.stdout ?? ""}${pinning.result?.stderr ?? ""}`, stillAbsent, bin });
@@ -815,7 +940,7 @@ export async function runLiveProbes({
 
 		// --- the ephemeral pair (issue #344): one name, two runs, each waited on until it is gone ---
 		const runEphemeral = async (n) => {
-			const { result, entry } = await start(`ephemeral container (run ${n})`, names.ephemeral, ephemeralRunArgs({ image, name: names.ephemeral, fixture, nonce, run: n, user, relabel, buildArgs }));
+			const { result, entry } = await start(`ephemeral container (run ${n})`, names.ephemeral, ephemeralRunArgs({ image, name: names.ephemeral, fixture, nonce, run: n, user, relabel, buildArgs, size, hostCpus, cgroupParent }));
 			const started = result?.code === 0 && entry.id !== null;
 			// A HELD NAME is the daemon refusing the create for the name, in its own words (measured: Docker "Conflict. ...
 			// is already in use", Podman "that name is already in use"). Not a listed container: after the first run was
@@ -864,7 +989,7 @@ export async function runLiveProbes({
 						} catch {
 							break;
 						}
-						const { result, entry } = await start(`${key} container`, names[key], peerRunArgs({ image, name: names[key], fixture: peerFixture, network: networkOf[key], nonce, seconds: liveSleepSeconds(stepTimeoutMs), user, relabel, buildArgs }));
+						const { result, entry } = await start(`${key} container`, names[key], peerRunArgs({ image, name: names[key], fixture: peerFixture, network: networkOf[key], nonce, seconds: liveSleepSeconds(stepTimeoutMs), user, relabel, buildArgs, size, hostCpus, cgroupParent }));
 						peers.push(entry);
 						if (result?.code !== 0 || entry.id === null) break;
 						ids[key] = entry.id;
@@ -901,7 +1026,7 @@ export async function runLiveProbes({
 		const byProperty = { isolation, ephemeral, mountSet, egress: egressVerdict(egress ?? {}), jobToJobIsolation, imagePinning, nonRoot, localFolders };
 		// The uid PID 1 actually ran as, for doctor's job-user line: the decision it was given, read back.
 		const ranAs = Array.isArray(status?.uids) && /^\d+$/.test(status.uids[1] ?? "") ? Number(status.uids[1]) : null;
-		return { ran: true, verdicts: READ_BACK_BY_A_LIVE_PROBE.map((p) => byProperty[p]), notes, swept, ranAs };
+		return { ran: true, verdicts: READ_BACK_BY_A_LIVE_PROBE.map((p) => byProperty[p]), notes, swept, ranAs, cgroupParent: parentRead };
 	} finally {
 		for (const entry of owned) await release(entry);
 		for (const entry of networks) await dropNetwork(entry);

package/src/prepare.mjs

@@ -14,6 +14,7 @@ import { buildForgejoPrompt } from "./forgejo-prompt.mjs";
 import { buildAzurePrompt } from "./azure-prompt.mjs";
 import { prepareLocalWorkspace } from "./prepare-local.mjs";
 import { copySkillTree } from "./copy-tree.mjs";
+import { recordedJobSize } from "./job-size.mjs";
 
 /**
  * The subdirectory of the per-job dir a trigger's injected skills are copied into, so they reach the
@@ -82,7 +83,7 @@ export function makePrepareWorkspace({
 	removeDir = (dir) => rmSync(dir, { recursive: true, force: true }),
 }) {
 	ensureDir(jobsDir);
-	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false } = {}) {
+	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null, jobUser = null, podmanStore = null, portfolio = false, size = null } = {}) {
 		ensureDir(jobsDir);
 		const jobDir = mkdtempSync(join(jobsDir, "job-"));
 		// Issue #524: a THROW out of anything below leaves `jobDir` to nobody. The processor tears down only what
@@ -92,7 +93,7 @@ export function makePrepareWorkspace({
 		// covers the thrown ones, in one place for every kind, rather than in each preparer that can throw.
 		// A retry makes a fresh directory, so nothing is lost by removing this one.
 		try {
-			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio });
+			return await prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size });
 		} catch (error) {
 			// GUARDED: a removal that fails (a busy mount, a permission flipped mid-job) must never replace the error
 			// that is the job's actual outcome. The directory is then left, which is what happened before this catch.
@@ -103,7 +104,7 @@ export function makePrepareWorkspace({
 		}
 	};
 
-	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio }) {
+	async function prepareInto(job, token, jobDir, { queueJobId, piVersion, jobUser, podmanStore, portfolio, size }) {
 		// The trigger's injected skills (REQ-PER-TRIGGER-SKILLS, issue #60), COPIED here rather than
 		// mounted, and copied ONCE for every job kind because this is where local and forge converge.
 		//
@@ -137,6 +138,9 @@ export function makePrepareWorkspace({
 			...(jobUser ? { jobUser: { user: jobUser.user ?? null, home: jobUser.home ?? null } } : {}),
 			// Issue #429: the podman store the run's container lived in, for a podman run only.
 			...(typeof podmanStore === "string" && podmanStore !== "" ? { podmanStore } : {}),
+			// Issue #596: the size the run's container had, so a re-opened sandbox gets the same memory and CPU weight.
+			// Rebuilt (`recordedJobSize`), and only when the processor resolved one; a direct call stamps nothing.
+			...(recordedJobSize(size) ? { size: recordedJobSize(size) } : {}),
 		};
 		if (job.kind === "local") {
 			// Harness text above, operator DATA below: the fixed pointer line names /job/event.json so a

package/src/processor.mjs

@@ -8,7 +8,7 @@ import { PROJECT_CAP_REASON } from "./scoped-limits.mjs";
 import { DEFAULT_SECRETS_PROFILE, secretsArmed } from "./secrets.mjs";
 import { RESERVED_ENV_NAMES } from "./triggers.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
-import { COST_CAP_WHYS, RUNNER_POLICY_REASONS } from "./run-history.mjs";
+import { COST_CAP_WHYS, EXIT_OOM_KILLED, RUNNER_POLICY_REASONS } from "./run-history.mjs";
 import { DEFAULT_EGRESS_PROXY } from "./egress.mjs";
 import { CAPABILITY_GATES, EXIT_AUTH_CAPABILITY } from "./image-preflight.mjs";
 import { modelListProblem, modelOnList, splitModelEntry } from "./model-ref.mjs";
@@ -83,6 +83,29 @@ export const OBSERVATION_COMMENT_UNNAMED = "the venue this job runs on did not c
  * into the queue's retry behaviour -- that is INT-RUNNER-EXIT-CODE-PROTOCOL.
  */
 
+/** The exit code of a container whose main process was SIGKILLed: a worker's stop or the kernel's OOM killer. */
+const EXIT_SIGKILL = 137;
+
+/**
+ * Issue #596: whether a run's memory peak reached the container's own limit closely enough for its OOM kill to be the
+ * job's own: `memPeak` (bytes, off the decisive exit line) at 90% of `limit` (bytes, the `--memory=` the worker passed)
+ * or more. Both must be known; anything else is false, so the 137 stays infrastructure and retries.
+ *
+ * Why the check exists: `memory.events` `oom_kill` counts a kill by ANY OOM killer, the HOST's included, and the runner
+ * tree's `oom_score_adj` of 1000 makes a job the host's first victim when the machine itself runs short. A kill of
+ * that kind says nothing about the job's size, and a retry may well pass. A cgroup OOM happens only at the limit, so its
+ * peak sits there: measured in the issue #596 lab, `memory.peak` read exactly the bound (64m, 80m) or just under it on
+ * every venue. 90% and not 100% is the margin for that "just under"; nothing in between is read as a measurement.
+ *
+ * What it cannot see (the residual): a host OOM that strikes a job which is ALREADY at 90% of its own limit, page
+ * cache included (a job that read large files counts that cache), reads as the job's own OOM. And the peak is a
+ * high-water mark over the whole run, so a job that touched 90% early and was killed by the host later reads the same.
+ */
+export function peakReachedLimit(memPeak, limit) {
+	if (!Number.isSafeInteger(memPeak) || !Number.isSafeInteger(limit) || memPeak < 0 || limit <= 0) return false;
+	return memPeak >= Math.ceil((limit * 9) / 10);
+}
+
 // The post-spend terminal comments (issue #288). Every FREE refusal above the container already comments;
 // these are the paths where money was spent and the run still ended without the agent's own status step,
 // which used to tell the issue nothing (REQ-JOB-STATUS-COMMENTS' acceptance -- "exactly one completion or
@@ -106,6 +129,9 @@ export const TERMINAL_COMMENTS = {
 	"model-not-allowed": "Stopped: the run tried to call an AI model this trigger does not allow, or to change an AI request in a way it does not allow, so the call was not made. Partial work may exist. Not retried.",
 	"cost-cap-unenforceable": "Stopped: this run has a cost limit, and the job image could not enforce it before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
 	"model-policy-unenforceable": "Stopped: this run is limited to certain AI models, and the job image could not enforce that before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
+	// 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 #502: the `model-unknown` refusal's comment. Names no model: the reader may be an issue author.
@@ -238,7 +264,8 @@ export async function runJob(job, deps) {
 		// Issue #341: which uid this job's container runs as. `(job, { capabilities, observed }) =>` `{ user, home }`
 		// (`user` null = the image's own USER), `{ refused, cause }` or `{ unavailable, reason }`. The default runs
 		// every job as the image's user, exactly as before, so a wiring that omits it changes nothing. A non-refused answer
-		// may also carry `relabel: true` (issue #355), which reaches `runContainer` beside the user it was decided with.
+		// may also carry `relabel: true` (issue #355), which reaches `runContainer` beside the user it was decided with, and
+		// `hostCpus` (issue #596), the runtime's CPU count from the same facts read, which sets the `--cpus` ceiling.
 		jobUserPreflight = async () => ({ user: null, home: null }),
 		// (session, { piVersion, context }) => { promoted, reason, bytes }. Promotes this job's transcript back into
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
@@ -300,8 +327,11 @@ export async function runJob(job, deps) {
 		mintToken,
 		isDefaultBranchProtected, // (job, token) => boolean; same reason -- the forge is the job's, not the process's
 		prepareWorkspace, // (job, token) => { workspaceDir, jobDir }  (clone+materialise+prompt)
-		// runContainer({ job, token, prepared, secrets, name, signal, user, home, modelEndpoints? }) => { code, aborted, abortReason, turns, tokens, session, usage, context, exitReason }.
+		// 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.
+		// `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
 		// `signal`: stop the container on abort, and reject/exit promptly if `signal.aborted` is already
@@ -356,6 +386,14 @@ export async function runJob(job, deps) {
 		// after prepare, before any reserve. Absent on a bare wiring, which checks nothing.
 		pickupProject = null,
 		folderProject = null,
+		// Issue #596: the job's size `{ memMiB, cpuCenti, source }`, resolved at pickup from the same limits snapshot as
+		// every other gate (index.mjs). Handed to `prepareWorkspace` (a retained run's manifest records it, so a sandbox
+		// reopens the run at its size) and to `runContainer`, never through `job.data`. null on a bare wiring: neither call
+		// then carries it, and the container gets the built-in 4g and 2.
+		jobSize = null,
+		// Issue #596, phase 2: the host's CPU budget at pickup in hundredths (`host-budget.mjs`), or null when it is off or
+		// unknown. It becomes every job's `--cpus` (capped at the runtime's count), so no job can use the reserve.
+		cpuBudgetCenti = null,
 		// Issue #503 part 7: the builtin catalog's model object for (provider, id), or null (model-catalog.mjs
 		// `builtinModel`). Read only by the zero-rated check; the default knows no builtin model, so an unwired
 		// processor judges overlay models alone and reserves for every other.
@@ -412,6 +450,8 @@ export async function runJob(job, deps) {
 	// the record says about it (INT-RUN-HISTORY-FILE-CONTRACT), null until the reservation step ran.
 	let dollarHold = null;
 	let dollars = null;
+	// Issue #596: what the container used (`resources` off its exit line), null until a container ran and reported it.
+	let resources = null;
 
 	try {
 		// The one-shot pre-spend check (issue #231), FIRST on the ladder: one file read, cheaper than
@@ -1067,7 +1107,7 @@ export async function runJob(job, deps) {
 		// `podmanStore` (issue #429) only where the venue's job user carried one: the podman store the container ran in.
 		// `portfolio` (issue #505) only for a job the gate above confirmed: prepare then writes /job/portfolio.json, after
 		// asking the live file once more. Absent otherwise, so every other job's prepare call is unchanged.
-		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}), ...(portfolio ? { portfolio: true } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
+		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}), ...(portfolio ? { portfolio: true } : {}), ...(jobSize ? { size: jobSize } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
 
 		// A determinate prepare refusal -- sha-gone (the default branch advanced past the resolved tip),
 		// or a `pi-*` materialiser cap breach (the repo's .pi/ is too large to place in /job, issue #60)
@@ -1270,12 +1310,29 @@ export async function runJob(job, deps) {
 		// then only a signed line is read (run-container.mjs, run-history.mjs `authenticExitLines`). An image that does not
 		// declare it is read as before, under the #542 trust rule below alone.
 		const exitAuth = (img.capabilities ?? []).includes(EXIT_AUTH_CAPABILITY);
-		const { code, aborted, abortReason, turns, tokens, session, usage, context, detached, exitReason, exitWhy = null, exitLineCode = null, exitAuth: exitAuthResult = null } = await runContainer({ job: containerJob, token, prepared, secrets, user: jobUser?.user ?? null, home: jobUser?.home ?? null, relabel: jobUser?.relabel === true, ...(modelEndpoints?.endpoints?.length > 0 ? { modelEndpoints } : {}), ...(exitAuth ? { exitAuth: true } : {}) });
+		const { code, aborted, abortReason, turns, tokens, session, usage, context, detached, exitReason, exitWhy = null, exitLineCode = null, exitAuth: exitAuthResult = null, exitOomKilled = false, memoryLimit = null, resources: ranResources = null } = await runContainer({ job: containerJob, token, prepared, secrets, user: jobUser?.user ?? null, home: jobUser?.home ?? null, relabel: jobUser?.relabel === true, ...(modelEndpoints?.endpoints?.length > 0 ? { modelEndpoints } : {}), ...(exitAuth ? { exitAuth: true } : {}), ...(jobSize ? { size: jobSize } : {}), ...(Number.isSafeInteger(jobUser?.hostCpus) ? { hostCpus: jobUser.hostCpus } : {}), ...(Number.isSafeInteger(cpuBudgetCenti) ? { cpuBudgetCenti } : {}), ...(Array.isArray(jobUser?.unenforced) && jobUser.unenforced.length > 0 ? { unenforced: jobUser.unenforced } : {}) });
 		containerRan = true;
+		// Issue #596: what the container used, off its exit line, rebuilt by the sink (null from a runContainer that predates
+		// the field). Every result and every throw below carries it, so a retried attempt's record says what it used too.
+		resources = ranResources ?? null;
+		// Issue #596: CONFIRMED killed for memory. The image's supervisor (image/runner/src/supervise.mjs) outlives the runner,
+		// whose process tree it gives the highest OOM score, and when the runner dies of SIGKILL with the cgroup's
+		// `oom_kill` above 0 it writes the signed line `code: 137, reason: "oom-killed"` (parseExitOomKilled). All three
+		// facts must agree: that line, verified under this run's key (an unsigned line is a tool's), and the container's
+		// own exit 137. Docker's `oom` event is not used: it fires also when only a child was killed and the job went on
+		// to exit 0, and Podman has no such event at all (both measured in the issue #596 lab). And a fourth: the line's
+		// `memPeak` at 90% of the `--memory` this container got (`memoryLimit`, from runContainer) or more, because
+		// `oom_kill` counts the HOST's OOM killer too (`peakReachedLimit`). A report below it stays infrastructure.
+		const oomReported = exitOomKilled === true && exitAuthResult === "verified" && code === EXIT_SIGKILL;
+		const oomKilled = oomReported && peakReachedLimit(resources?.memPeak ?? null, memoryLimit);
+		// Numbers only (bytes), never a path or a project: the operator's trace of a kill read as the host's. Never on a run
+		// the worker stopped itself (a timeout, a cancel, a shutdown): that 137 is the worker's own, the abort decides it
+		// below, and a line naming the host's OOM killer would send the operator after a kill that never happened.
+		if (oomReported && !oomKilled && !aborted) log("oom_report_below_limit", { jobId: job.id ?? null, memPeak: resources?.memPeak ?? null, memoryLimit });
 		// `exitAuth: "unverified"` is a run whose image signs its exit line and no signed line was found: the runner died
 		// before writing one, or a line was forged or taken off the pipe. Its tokens read as unknown and its dollars settle
 		// at the floor, the same as a container that wrote no exit line at all.
-		log("container_exit", { exitCode: code, aborted, ...(detached === true ? { detached: true } : {}), ...(exitAuthResult !== null ? { exitAuth: exitAuthResult } : {}) });
+		log("container_exit", { exitCode: code, aborted, ...(detached === true ? { detached: true } : {}), ...(exitAuthResult !== null ? { exitAuth: exitAuthResult } : {}), ...(oomKilled ? { oomKilled: true } : {}) });
 
 		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
 		// so it spent real tokens on EVERY path that reaches here -- abort, completed, policy, AND the infra
@@ -1334,14 +1391,15 @@ export async function runJob(job, deps) {
 		// mid-job). It DID start, so this is never refunded as never-started: it keeps its slot and retries as infrastructure,
 		// BEFORE the exit-code switch, where the same code would read as a free never-started exit.
 		if (detached === true) {
-			throw new InfraRetry(`the container outlived its docker run, exit ${code}`, { reason: "container-detached", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
+			throw new InfraRetry(`the container outlived its docker run, exit ${code}`, { reason: "container-detached", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars, resources });
 		}
 
 		// A WORKER-initiated stop (30-min timeout via cancelJob, graceful-shutdown docker stop, or an
 		// operator's cancel, issue #287) kills the container -> exit 143/137. That is our decision, not an
 		// infra fault: it is POLICY and must NOT retry, or a wedged job re-runs into a second PR / double
 		// spend. Keyed on the abort FLAG, not the code -- an unbidden 137 (kernel OOM) carries
-		// `aborted: false`, falls to the switch, and stays infra-retryable.
+		// `aborted: false`, and falls to the OOM branch below when the runtime confirmed it, else to the switch, where it
+		// stays infra-retryable (issue #596).
 		// WHO aborted is an exact-match on `abortReason` (the wiring maps it off `signal.reason`), and the
 		// match is deliberately closed: "job-timeout-30m", "shutdown", undefined and any future garbage all
 		// classify as worker-abort, so a pin bump that changes what rides the signal can widen nothing.
@@ -1352,7 +1410,23 @@ export async function runJob(job, deps) {
 			// Awaited bare like every determinate refusal above: the adapter never throws by contract, and
 			// the one swallowed comment in this file (the catch's) justifies itself by its position.
 			await comment(job, TERMINAL_COMMENTS[reason]);
-			return { outcome: "policy", reason, exitCode: code, turns, tokens, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}) };
+			return { outcome: "policy", reason, exitCode: code, turns, tokens, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}), ...(resources ? { resources } : {}) };
+		}
+
+		// Issue #596: a runner the kernel killed for memory, CONFIRMED (`oomKilled` above). After the abort branch, so a
+		// worker's own stop is never relabelled, and before the switch, where the same 137 is an unknown exit and retries.
+		// The same size would be killed the same way on every retry, so it is POLICY: returned, never retried, its slot
+		// kept and its dollars settled above like any other paid stop. An UNCONFIRMED 137 (an image without the supervisor,
+		// an unsigned line, a SIGKILL with no OOM kill in the cgroup, a peak short of the limit, which is how a kill by the
+		// host's OOM killer reads) falls through and retries, exactly as before.
+		//
+		// When only a CHILD was killed, the runner survives and ends on its own code, so this branch is not taken: the
+		// outcome is the runner's, and `resources.oomKills` in the record says a process was killed for memory.
+		if (oomKilled) {
+			// The project and the size go to the log and the record, never to the comment (the TERMINAL_COMMENTS rule).
+			log("oom_killed", { jobId: job.id ?? null });
+			await comment(job, TERMINAL_COMMENTS[EXIT_OOM_KILLED]);
+			return { outcome: "policy", reason: EXIT_OOM_KILLED, exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}), ...(resources ? { resources } : {}) };
 		}
 
 		switch (code) {
@@ -1394,6 +1468,7 @@ export async function runJob(job, deps) {
 					// Only when the collector returned a plan (a file, or a confirmed portfolio job with none, `plan-absent`): the
 					// record's `plan` is null otherwise, and every other result is unchanged.
 					...(plan ? { plan } : {}),
+					...(resources ? { resources } : {}),
 				};
 			}
 			case EXIT_POLICY: {
@@ -1420,7 +1495,7 @@ export async function runJob(job, deps) {
 				// `why`. parseExitWhy keeps only a member of the closed COST_CAP_WHYS off a `cost-cap` line that said code 2,
 				// and it rides only beside a `cost-cap` reason, so a forged line can at worst name the wrong rule of three.
 				const why = reason === "cost-cap" && COST_CAP_WHYS.includes(exitWhy) ? { why: exitWhy } : {};
-				return { outcome: "policy", reason, exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}), ...why };
+				return { outcome: "policy", reason, exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}), ...why, ...(resources ? { resources } : {}) };
 			}
 			case EXIT_INFRA:
 				// NO comment on any infra throw, here or in the catch: an InfraRetry may be retried and
@@ -1428,7 +1503,7 @@ export async function runJob(job, deps) {
 				// the whole infra class lives at the terminal seam -- start.mjs's failed listener, guarded on
 				// BullMQ's own finishedOn -- which also catches the stall-kill and wait-gate paths this
 				// function never sees (issue #288).
-				throw new InfraRetry(`infra failure, container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
+				throw new InfraRetry(`infra failure, container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars, resources });
 			default:
 				// THE RUNTIME NEVER HANDED CONTROL TO THE RUNNER, in whatever integers this venue spells that
 				// (issue #227). For docker it is 125 (`docker run` itself failed), 126 (the entrypoint exists
@@ -1444,9 +1519,9 @@ export async function runJob(job, deps) {
 				// and normalises to this outcome itself.
 				if (neverStarted) {
 					// No `dollars` here: the hold is still standing, and the catch refunds it whole with the job-count slots.
-					throw new InfraRetry(`the runtime could not start the container, exit ${code}`, { reason: "container-never-started", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+					throw new InfraRetry(`the runtime could not start the container, exit ${code}`, { reason: "container-never-started", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), resources });
 				}
-				throw new InfraRetry(`unknown container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
+				throw new InfraRetry(`unknown container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars, resources });
 		}
 	} catch (e) {
 		// A CONFIG-tagged throw is a determinate policy refusal wearing an exception, and issue #310 is the
@@ -1625,7 +1700,7 @@ function isNeverStartedRetry(e) {
 }
 
 export class InfraRetry extends Error {
-	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved, dollars } = {}) {
+	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved, dollars, resources } = {}) {
 		super(message, cause ? { cause } : undefined);
 		this.name = "InfraRetry";
 		this.piDispatchRetry = true;
@@ -1647,6 +1722,8 @@ export class InfraRetry extends Error {
 		// Issue #501: the dollar reservation's outcome (`dollarsRecord`), or null when no dollar window applied. Set by
 		// the processor on a throw after the reservation, so a retried attempt's record says what its window was charged.
 		this.dollars = dollars ?? null;
+		// Issue #596: what the container used, off its exit line, or null; set on a throw after a container ran.
+		this.resources = resources ?? null;
 	}
 }