@edgehero/pi-dispatch 3.1.0 → 4.0.0

package/.env.example

@@ -113,6 +113,40 @@ VALKEY_URL=redis://127.0.0.1:6379
 # docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest  (or build image/Dockerfile)
 # On rootful Podman, run these and every docker command through a docker context pointed at podman.sock, with the real docker CLI (docs/podman.md)
 PI_JOB_IMAGE=pi-job:latest
+# How much memory and CPU each job container gets, unless its project's row in the scoped-limits file sets its own.
+# See docs/scoped-limits.md, and docs/sizing.md for how to choose sizes.
+# Memory is a whole number of megabytes or gigabytes (512m, 1536m, 4g), at least 512m.
+# CPUs is a number with at most two decimals (0.5, 2, 1.25), at least 0.25.
+# A bad value stops the worker at boot.
+# A job gets no swap beyond its memory where the runtime enforces swap limits (doctor warns where it does not).
+# CPUs are a weight, not a cap: under contention a job with more CPUs gets more CPU than one with fewer.
+# On an idle host one job may use every core up to the CPU budget below, whenever one is in force (with the
+# default auto budget, every core but one on a host with 4 or more; with the CPU budget off, the same).
+# Default 4g and 2.
+# PI_JOB_MEMORY=4g
+# PI_JOB_CPUS=2
+# How much memory and CPU this host's jobs may hold together: the host budget. A job starts only when its size fits
+# beside what already runs here, and a waiting job keeps its place, so a big job is not starved by a stream of small ones.
+# PI_CONCURRENCY still caps the number of jobs; whichever is reached first applies. See docs/multi-host.md,
+# and docs/sizing.md for a worked example.
+# Each budget is auto, a value, or off (no limit on that resource).
+# auto reads the container runtime: its memory and CPU count (and, on rootless Podman, the user service's own limits),
+# minus the reserve below, and never less than one job of the default size above.
+# A value is a memory amount (64g, 49152m) or a number of CPUs (12, 3.5). It is the budget itself; the reserve is not
+# taken from it. A value below one job of the default size stops the worker at boot.
+# A job's cpus count as CPU reserved for it (the runtime uses them as a weight), so they must fit the CPU budget.
+# A job too big for this host's budget, or for its project's hostShare of it, is refused before anything is spent
+# when it can run nowhere else: on this host's own queue, or on any queue without PI_WORKER_NAME (no fleet is
+# declared, so it never waits for another host). With PI_WORKER_NAME set, a job on the shared queue waits for a
+# host it fits on.
+# Default auto.
+# PI_HOST_MEMORY_BUDGET=auto
+# PI_HOST_CPU_BUDGET=auto
+# What auto leaves for the host itself (the system, the egress proxy, Valkey, the worker).
+# auto: memory 10% of the host's memory, at least 1g and at most 4g; CPUs 1 when the host has 4 or more, else 0.
+# Or a value (2g, 0.5, or 0 for none). A bad value stops the worker at boot.
+# PI_HOST_RESERVE_MEMORY=auto
+# PI_HOST_RESERVE_CPUS=auto
 # where per-job /job inputs live (default: <OS temp dir>/pi-dispatch-<your uid>/jobs, one per account, created 0700)
 # Another account's directory there, or one you set that another account owns, stops the worker at boot (exit 2), and doctor names it
 # Pin it (and PI_SANDBOX_DIR) yourself if the worker runs as a different account than your /dispatch panel or `pi-dispatch sandbox`: the default is per account

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
@@ -63,6 +63,10 @@
 		"./backends": "./src/backends.mjs",
 		"./backend-registry": "./src/backend-registry.mjs",
 		"./container-spec": "./src/container-spec.mjs",
+		"./job-size": "./src/job-size.mjs",
+		"./size-suggest": "./src/size-suggest.mjs",
+		"./size-records": "./src/size-records.mjs",
+		"./host-budget": "./src/host-budget.mjs",
 		"./backend-conformance": "./src/backend-conformance.mjs",
 		"./live-probes": "./src/live-probes.mjs",
 		"./triggers": "./src/triggers.mjs",
@@ -105,7 +109,7 @@
     "start": "node src/cli.mjs worker"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "1.0.3",
+    "@earendil-works/pi-ai": "1.0.4",
     "@octokit/auth-app": "8.2.0",
     "@octokit/rest": "22.0.1",
     "bullmq": "5.80.4",

package/src/backend-local.mjs

@@ -28,6 +28,7 @@ import { BACKENDS, DEFAULT_BACKEND, DOCKER_NEVER_STARTED_EXITS } from "./backend
 import { DEFAULT_EGRESS_PROXY, ENDPOINT_LISTED_STATES, networkEndpoints, removeNetworkOrSay } from "./egress.mjs";
 import { makeDetachGate } from "./netns-keeper.mjs";
 import { isDeterminateFsCode } from "./transient.mjs";
+import { SIZE_LABEL_CPU, SIZE_LABEL_MEM } from "./container-spec.mjs";
 
 const execDocker = promisify(execFile);
 
@@ -401,6 +402,74 @@ export function isJobNamespace(name) {
 	return typeof name === "string" && name.startsWith(JOB_NAME_PREFIX);
 }
 
+/**
+ * The states in which a job container runs nothing and never will again (gate round 1 of phase 2): Docker's
+ * `exited` and `dead`, Podman's `exited` and `stopped`. Such a container uses no memory and no CPU, yet `ps -a` lists
+ * it (an `--rm` whose removal failed), so counting it as running kept an orphan's hold until a worker restart.
+ */
+export const CONTAINER_GONE_STATES = Object.freeze(new Set(["exited", "dead", "stopped"]));
+/**
+ * The states in which a job container has not started yet: Docker's `created`, Podman's `created` and `configured`. NOT
+ * gone by itself: a `docker run` client still alive after its stop timed out may yet start it. So it is REMOVED
+ * (`rm -f`, exact name, our namespace only), and gone once the removal is answered.
+ */
+export const CONTAINER_UNSTARTED_STATES = Object.freeze(new Set(["created", "configured"]));
+
+/** `ps -a` lines of `{{.Names}}\t{{.State}}...`: `[{ name, state, rest }]`, only names in the job namespace, `rest` the later fields. */
+function psRows(stdout) {
+	return String(stdout ?? "")
+		.split("\n")
+		.map((line) => line.split("\t").map((f) => f.trim()))
+		.filter(([name, state]) => isJobNamespace(name) && typeof state === "string")
+		.map(([name, state, ...rest]) => ({ name, state: state.toLowerCase(), rest }));
+}
+
+/**
+ * Whether a job container is GONE (issue #596, phase 2): `true` when the runtime lists no container of exactly that name,
+ * or lists it in a state that runs nothing (`CONTAINER_GONE_STATES`), or lists it not yet started and removes it
+ * (`CONTAINER_UNSTARTED_STATES`); `false` when it lists one in any other state (running, paused, restarting, removing,
+ * one nothing here has measured); `null` when it could not be asked or the removal was not answered. The host budget
+ * keeps the hold of a job whose stop did not take until this says `true` (`host-budget.mjs` `sweep`), so `null` keeps
+ * it: an unanswered listing must never free room a running container may still use. `-a` with the STATE, because a
+ * stopped container is listed by `ps -a` and is gone in every sense the budget cares about, and the anchored name test,
+ * because `--filter name=` is a SUBSTRING match (the reaper's measured reason).
+ */
+export function makeContainerGone({ exec = execReaperBounded, binOf = () => "docker" } = {}) {
+	return async (name, venue) => {
+		if (typeof name !== "string" || !isJobNamespace(name)) return null;
+		const bin = binOf(venue);
+		try {
+			const { stdout } = await exec(bin, ["ps", "-a", "--filter", `name=${name}`, "--format", "{{.Names}}\t{{.State}}"]);
+			const row = psRows(stdout).find((r) => r.name === name);
+			if (!row) return true;
+			if (CONTAINER_GONE_STATES.has(row.state)) return true;
+			if (!CONTAINER_UNSTARTED_STATES.has(row.state)) return false;
+			await exec(bin, ["rm", "-f", name]);
+			return true;
+		} catch {
+			return null;
+		}
+	};
+}
+
+/**
+ * The job containers a venue still lists (gate round 1 of phase 2), for the host budget's boot seed: `ps -a`
+ * by the job namespace, each with its state and its two size labels, as `[{ name, memMiB, cpuCenti }]` (a label absent
+ * or not a positive integer is null). A container in a state that runs nothing (`CONTAINER_GONE_STATES`) is left out:
+ * it holds nothing. One not yet started is kept, so the sweep removes it before its room is given back. THROWS when
+ * the runtime does not answer: the budget then admits nothing until a listing is read, because an empty ledger beside
+ * containers nobody counted is an overcommit.
+ */
+export function makeJobContainerLister({ exec = execReaperBounded, bin = "docker" } = {}) {
+	const int = (v) => (/^[1-9][0-9]{0,8}$/.test(v ?? "") ? Number(v) : null);
+	return async () => {
+		const { stdout } = await exec(bin, ["ps", "-a", "--filter", `name=${JOB_NAME_PREFIX}`, "--format", `{{.Names}}\t{{.State}}\t{{.Label "${SIZE_LABEL_MEM}"}}\t{{.Label "${SIZE_LABEL_CPU}"}}`]);
+		return psRows(stdout)
+			.filter((r) => !CONTAINER_GONE_STATES.has(r.state))
+			.map((r) => ({ name: r.name, memMiB: int(r.rest[0]), cpuCenti: int(r.rest[1]) }));
+	};
+}
+
 /**
  * Boot-time reaper: clear stray `pi-job-*` containers a previous worker crash left behind.
  *

package/src/backend-podman.mjs

@@ -34,10 +34,11 @@ import { JOB_NAME_PREFIX, execDockerBounded, jobContainerName, makeReaper, makeS
 import { BACKENDS, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_CONF_WIDENS_JOB, PODMAN_NETWORK_HELPER_KEYS, PODMAN_WIDENING_KEYS, PODMAN_BOUNDS_DELEGATED, PODMAN_SERVICE_LOCAL, observationRefusalIsTransient, observationRefusals, unobservedFloor } from "./backends.mjs";
 import { CONTAINER_HOME, SHIPPED_IMAGE_UID } from "./container-spec.mjs";
 import { buildPodmanRunArgs } from "./docker-run.mjs";
+import { cgroupParentFor } from "./cpu-reserve.mjs";
 import { DEFAULT_EGRESS_PROXY, makeEgressPreflight } from "./egress.mjs";
 import { NETNS_KEEPER, NETNS_KEEPER_FORMAT, QUADLET_FILES, STARTED_AT_FORMAT, judgeNetnsKeeper, netnsKeeperRemedy, podmanNeedsNetnsKeeper } from "./podman-stack.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
-import { DAEMON_FACTS_TIMEOUT_MS } from "./job-user.mjs";
+import { DAEMON_FACTS_TIMEOUT_MS, JOB_USER_FACTS_MAX_AGE_MS, STALE_FACTS_CEILING_MS } from "./job-user.mjs";
 import { PODMAN_INFO_ARGS, parsePodmanInfo } from "./daemon-facts.mjs";
 
 // Moved to the leaf `daemon-facts.mjs` (issue #452, gate round 3) and re-exported, so every importer keeps its path.
@@ -106,25 +107,50 @@ export function makePodmanInfoReader({ run = (args) => execDockerBounded(args, {
 const CACHED = Symbol("podman-info-cached");
 
 /**
- * `readInfo` with its first ANSWERED result kept, and concurrent callers sharing one read. An unanswered read is never
- * kept: a Podman that timed out once must be asked again, or every later job would retry on a stale failure. Idempotent,
- * so the boot wiring can wrap a reader once and hand the same one to the bundle and to its own boot read.
+ * `readInfo` with its last ANSWERED result kept for `maxAgeMs`, and concurrent callers sharing one read. An unanswered
+ * read is never kept: a Podman that timed out once must be asked again, or every later job would retry on a stale
+ * failure. Idempotent, so the boot wiring can wrap a reader once and hand the same one to the bundle and to its own boot
+ * read (a second wrap keeps the first wrap's clock and age).
+ *
+ * The age (issue #596, gate round 2) is the job-user resolver's (`JOB_USER_FACTS_MAX_AGE_MS`), for the same reason:
+ * this read carries the host's CPU count that every job's `--cpus` ceiling is built from, and a raised or lowered count
+ * must be seen without a restart. STALE WHILE ERROR, also as there: a read past the age that does not answer keeps
+ * serving the kept answer until a read does, logging `podman_info_stale` with the failed read's reason once per run of
+ * failures, because the age exists to see a change and must not turn one slow `podman info` into a failed pickup.
+ * Podman has no `invalidate`: it accepts a `--cpus` above the host's count (4.9.3 and 5.8.1, measured), so no job
+ * refusal proves the kept count wrong.
  */
-export function cachedPodmanInfo(readInfo) {
+export function cachedPodmanInfo(readInfo, { now = Date.now, maxAgeMs = JOB_USER_FACTS_MAX_AGE_MS, log = () => {} } = {}) {
 	if (readInfo?.[CACHED]) return readInfo;
 	let kept = null;
+	let keptAt = 0;
+	let staleSaid = false;
 	let inFlight = null;
 	const cached = async () => {
-		if (kept) return kept;
+		if (kept && now() - keptAt < maxAgeMs) return kept;
 		if (inFlight) return inFlight;
 		inFlight = (async () => {
+			let read;
 			try {
-				const read = await readInfo();
-				if (read?.answered === true && read.info) kept = read;
-				return read;
+				read = await readInfo();
 			} catch {
-				return { answered: false, reason: "spawn-failed", transient: true };
+				read = { answered: false, reason: "spawn-failed", transient: true };
+			}
+			if (read?.answered === true && read.info) {
+				kept = read;
+				keptAt = now();
+				staleSaid = false;
+				return read;
+			}
+			// Not past `STALE_FACTS_CEILING_MS` (job-user.mjs says why): then the failed read is the answer, as a first one is.
+			if (kept && now() - keptAt < STALE_FACTS_CEILING_MS) {
+				if (!staleSaid) {
+					staleSaid = true;
+					log("podman_info_stale", { reason: read?.reason ?? "unanswered", ageMs: now() - keptAt });
+				}
+				return kept;
 			}
+			return read;
 		})();
 		try {
 			return await inFlight;
@@ -1081,7 +1107,7 @@ export function makePodmanBackend(opts = {}) {
 	if (reap !== undefined && typeof reap !== "function") throw new Error(`backend "${PODMAN_BACKEND}": reap must be a function (makePodmanReaper)`);
 	const spawnSeam = spawnFn ? { spawnFn } : {};
 	const execSeam = exec ? { exec } : spawnFn ? { exec: execViaSpawn(spawnFn) } : {};
-	const info = cachedPodmanInfo(readInfo);
+	const info = cachedPodmanInfo(readInfo, { log });
 
 	const runContainer = makeRunContainerFn({
 		image,
@@ -1098,7 +1124,9 @@ export function makePodmanBackend(opts = {}) {
 		forgeHosts,
 		neverStartedExits: PODMAN_NEVER_STARTED_EXITS,
 		bin: "podman",
-		buildArgs: buildPodmanRunArgs,
+		// Issue #596, phase 2: every job under the one parent cgroup (`CGROUP_PARENT`), except where Podman reports a cgroup
+		// manager other than systemd (`cgroupParentFor` says why), from the SAME `podman info` this job was admitted on.
+		buildArgs: (opts) => buildPodmanRunArgs({ ...opts, cgroupParent: cgroupParentFor({ podman: true, cgroupManager: info.peek?.()?.info?.cgroupManager ?? null }) }),
 		// Issue #452, gate round 4: the teardown's detach gate uses the `podman info` this venue admitted jobs on, never a
 		// read of its own; before any answered read it falls back to one. A refused teardown is logged with its token.
 		teardownRuntime: () => {
@@ -1145,7 +1173,10 @@ export function makePodmanBackend(opts = {}) {
 		// Issue #429: the store this job's container lives in rides beside its user, so a retained run records it and a
 		// sandbox or the retention sweep can tell another store's empty answer from "not open".
 		const store = read?.answered === true ? read.info?.graphRoot : null;
-		return chosen.user && typeof store === "string" ? { ...chosen, store } : chosen;
+		// Issue #596: the host's CPU count from the same read, for the job's `--cpus` ceiling. Absent when Podman did not say.
+		const hostCpus = read?.answered === true ? read.info?.hostCpus : null;
+		const stored = chosen.user && typeof store === "string" ? { ...chosen, store } : chosen;
+		return chosen.user && Number.isSafeInteger(hostCpus) ? { ...stored, hostCpus } : stored;
 	};
 
 	return {

package/src/config.mjs

@@ -15,6 +15,8 @@ import { SWEEP_INTERVAL_HOURS, SWEEP_INTERVAL_MAX_HOURS } from "./retention-swee
 import { parseSecretProfiles } from "./secret-profiles.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, parseWaitProfiles } from "./wait-for.mjs";
 import { imageRefProblem } from "./image-ref.mjs";
+import { jobSizeDefaults } from "./job-size.mjs";
+import { hostBudgetSettings } from "./host-budget.mjs";
 import { CONTAINER_ENV_NAMES, KEYLESS_ENV_NAME, RUNNER_ENV_NAMES } from "./reserved-env.mjs";
 import { modelListProblem } from "./model-ref.mjs";
 import { DOLLAR_ENV_NAMES, DOLLAR_WINDOW_KEYS, checkDollarInvariant, optionalUsdMicros } from "./money.mjs";
@@ -291,6 +293,34 @@ function refuseBackendShortfall(config) {
 	if (first) throw configError(first);
 }
 
+/**
+ * The deployment's default job size (issue #596): `{ memMiB, cpuCenti, memSet, cpuSet }` from `PI_JOB_MEMORY` and
+ * `PI_JOB_CPUS`, unset or empty meaning the built-in 4g and 2. A value the size parsers refuse (`job-size.mjs`) is a
+ * config error naming the key and the rule, so a typo stops the worker at boot rather than every job at its start.
+ */
+export function jobSizeFrom(env) {
+	try {
+		return jobSizeDefaults(env);
+	} catch (error) {
+		throw configError(error.message);
+	}
+}
+
+/**
+ * The host budget's four settings (issue #596, phase 2): `PI_HOST_MEMORY_BUDGET`, `PI_HOST_CPU_BUDGET` (each `auto`, a
+ * value or `off`) and `PI_HOST_RESERVE_MEMORY`, `PI_HOST_RESERVE_CPUS` (each `auto` or a value), judged against the
+ * deployment's default job size so a budget below one default job is refused here. A bad value is a config error naming
+ * the key and the rule, at boot (exit 2), never a refusal per job. ENV ONLY in this release, never the settings overlay:
+ * a budget that moved under running jobs would strand the holds taken against the old one.
+ */
+export function hostBudgetFrom(env, jobSize = jobSizeFrom(env)) {
+	try {
+		return hostBudgetSettings(env, jobSize);
+	} catch (error) {
+		throw configError(error.message);
+	}
+}
+
 /**
  * PI_JOB_IMAGE as the worker runs it (issue #471): unset or empty is pi-job:latest (`||`, so "" falls back), and any
  * other value is judged by the one image rule `run.image` is (`image-ref.mjs`). A refused value is a config error at
@@ -396,6 +426,14 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		dailyCostUsd: usdSetting(env, "PI_DAILY_COST_USD"),
 		weeklyCostUsd: usdSetting(env, "PI_WEEKLY_COST_USD"),
 		monthlyCostUsd: usdSetting(env, "PI_MONTHLY_COST_USD"),
+		// Issue #596: the deployment's default job size (`PI_JOB_MEMORY`, `PI_JOB_CPUS`; 4g and 2 when unset), refused here at
+		// boot (exit 2) naming the key, never at a job. A project row's size overrides it (INT-SCOPED-LIMITS-FILE-CONTRACT).
+		// The VALIDATION is this field's job; nothing reads its value. The pickup resolves each job's size from the same two
+		// settings (`jobSizeEnv`, start.mjs) with the same parser, so a value that got past here cannot be read otherwise.
+		jobSize: jobSizeFrom(env),
+		// Issue #596, phase 2: the host budget's settings (`hostBudgetFrom`), refused here at boot naming the key. The worker
+		// builds its one budget from them (start.mjs), and doctor reads them with the same function.
+		hostBudget: hostBudgetFrom(env),
 		jobImage: jobImageFrom(env), // || (not ??) so an empty string falls back; "" is falsy and would throw inside buildDockerRunArgs AFTER a budget slot was reserved
 		globalPiDir: resolveGlobalPiDir(env, fileExists), // REQ-GLOBAL-PI-OVERLAY: operator's ~/.pi/agent subset, :ro-mounted; null = off
 		allowGlobalExtensions: globalExtensionsEnabled(env), // REQ-GLOBAL-PI-OVERLAY: ON unless PI_GLOBAL_ALLOW_EXTENSIONS=0

package/src/container-spec.mjs

@@ -20,10 +20,13 @@
  * without reaching the argv builder. Nothing about the value changed in the move -- same fields, same
  * order, same guards -- because a byte-identical local deployment is #227's first constraint.
  *
- * It imports NOTHING, which is the property `packages.mjs` depends on when it derives the staged-packages
- * root from `CONTAINER_GLOBAL_PI_DIR` rather than re-typing the path.
+ * It imports nothing but `job-size.mjs` (issue #596), itself a leaf that imports nothing, which is the property
+ * `packages.mjs` depends on when it derives the staged-packages root from `CONTAINER_GLOBAL_PI_DIR` rather than
+ * re-typing the path.
  */
 
+import { CGROUP_PARENT, DEFAULT_JOB_SIZE, PARENTLESS_SHARES_MAX, containerSizing } from "./job-size.mjs";
+
 /**
  * Where the operator's global pi overlay lands INSIDE the container (REQ-GLOBAL-PI-OVERLAY). Exported
  * because packages.mjs derives the staged-packages root from it: the mount and that root are ONE fact on
@@ -90,6 +93,13 @@ export function assertJobUser(user) {
  */
 export const USERNS_MODES = Object.freeze(["keep-id"]);
 
+/**
+ * The two labels every job container carries (issue #596, phase 2): its memory size in MiB and its CPU size in
+ * hundredths, so `doctor` can sum what runs on this host and hold it against the host budget's ledger.
+ */
+export const SIZE_LABEL_MEM = "pi.dispatch.mem";
+export const SIZE_LABEL_CPU = "pi.dispatch.cpu";
+
 /** Throws unless `userns` is null/undefined or a member of `USERNS_MODES` (issue #354). */
 export function assertUserns(userns) {
 	if (userns === null || userns === undefined) return;
@@ -123,7 +133,19 @@ export function assertUserns(userns) {
  *                   mounted /session:rw. Per-job, like jobDir -- never the shared store.
  * @param globalPiDir host path to the operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY); mounted /opt/pi-global:ro
  * @param name       container name (for `docker stop` at the timeout)
- * @param memory     e.g. "4g"; cpus e.g. "2"
+ * @param size       the job's size, `{ memMiB, cpuCenti }` (issue #596, `job-size.mjs`); the built-in 4g and 2 when
+ *                   absent. It becomes `memory`, `memorySwap` (equal: no swap beyond memory), `cpuShares` and `shmSize`
+ *                   through ONE function, `containerSizing`, so no caller can pair a memory with another swap bound.
+ * @param hostCpus   the runtime's own CPU count (`docker info` `NCPU`, `podman info` `host.cpus`), or null. It sets
+ *                   `cpus`, the host ceiling every job shares (`hostCpuCeiling`), never the job's own size.
+ * @param cpuBudgetCenti the host's CPU budget in hundredths (`host-budget.mjs`), or null when it is off or unknown. With
+ *                   one, `cpus` is the budget capped at the runtime's count (`cpuCeilingCenti`), so no job can use the
+ *                   CPUs `auto` reserved for the host; without, the phase 1 ceiling stands.
+ * @param cgroupParent the parent cgroup the container is started under (issue #596, phase 2): `CGROUP_PARENT` (the
+ *                   default, for every container this builder makes) or null where the runtime cannot take one
+ *                   (`cgroupParentFor`). Every job shares the parent, whose quota is the host's CPU budget, so the
+ *                   reserve holds across ALL jobs; with null the job's `cpuShares` are capped at `PARENTLESS_SHARES_MAX`
+ *                   so no job outweighs the egress proxy and Valkey. Anything else is refused.
  * @param network    the per-job egress network this container joins (REQ-EGRESS-ALLOWLIST); null = the
  *                   docker default bridge, which is what every job did before that requirement existed
  * @param user       "<uid>:<gid>" the job runs as (issue #341), or null for the image's own USER. Portable: it says WHO
@@ -148,8 +170,10 @@ export function containerSpec({
 	sessionDir,
 	globalPiDir,
 	name,
-	memory = "4g",
-	cpus = "2",
+	size = DEFAULT_JOB_SIZE,
+	hostCpus = null,
+	cpuBudgetCenti = null,
+	cgroupParent = CGROUP_PARENT,
 	network = null,
 	user = null,
 	userns = null,
@@ -164,6 +188,9 @@ export function containerSpec({
 	assertCidFile(cidFile);
 	if (!name) throw new Error("docker run: container name is required");
 	if (!workspace) throw new Error("docker run: workspace mount is required");
+	// Throws on a size outside the floors and ceilings, before any field is built (issue #596).
+	const sizing = containerSizing(size, hostCpus, cpuBudgetCenti);
+	if (cgroupParent !== CGROUP_PARENT && cgroupParent !== null) throw new Error(`docker run: refusing a cgroup parent other than ${CGROUP_PARENT} or none: ${JSON.stringify(cgroupParent)}`);
 	// Booleans, strictly: a truthy string from a caller that forwarded an option bag must not re-own host directories.
 	if (typeof relabel !== "boolean") throw new Error(`docker run: relabel must be a boolean; got ${typeof relabel}`);
 	if (typeof workspaceOwned !== "boolean") throw new Error(`docker run: workspaceOwned must be a boolean; got ${typeof workspaceOwned}`);
@@ -207,8 +234,20 @@ export function containerSpec({
 	return {
 		image,
 		name,
-		memory,
-		cpus,
+		// Issue #596: the job's size. `memorySwap` equals `memory` (no swap beyond it), `cpuShares` is the job's weight,
+		// `shmSize` is min(1g, memory/2), and `cpus` is the host ceiling or null (then `--cpus` is absent).
+		memory: sizing.memory,
+		memorySwap: sizing.memorySwap,
+		cpus: sizing.cpus,
+		// Without the parent (issue #596, phase 2) a job's weight would compete with the proxy's and Valkey's directly, so it
+		// is capped at their default weight; under the parent it competes only with sibling jobs and orders them.
+		cpuShares: cgroupParent === null ? Math.min(sizing.cpuShares, PARENTLESS_SHARES_MAX) : sizing.cpuShares,
+		shmSize: sizing.shmSize,
+		cgroupParent,
+		// Issue #596, phase 2: the size the job was started at, as two labels on the container, so doctor can hold the host
+		// budget's ledger against what actually runs (`pi.dispatch.mem` in MiB, `pi.dispatch.cpu` in hundredths). Integers
+		// from the validated size, never anything a job or an operator writes as text.
+		labels: { [SIZE_LABEL_MEM]: String(size.memMiB), [SIZE_LABEL_CPU]: String(size.cpuCenti) },
 		network,
 		user,
 		// Issue #354. Always present and `null` by default (the parameter default turns an `undefined` into it, so a spec
@@ -319,3 +358,27 @@ export function copyDowngrades(spec) {
 		.map((b, i) => ({ container: b.container, was: b.readOnlyEnforcedBy, becomes: copied[i].readOnlyEnforcedBy }))
 		.filter((d) => d.was !== null && d.was !== d.becomes);
 }
+
+/**
+ * A container memory bound (`containerSpec`'s `memory`, the `--memory=` value: `4g`, `512m`, `1024k`, a plain byte
+ * count) in bytes, or null for anything else. Binary units, as Docker and Podman read them. Null is the safe answer for
+ * every caller: the live probe then reports the bound as not checked, and the OOM classification (issue #596) does not
+ * confirm a kill it cannot compare with the limit.
+ *
+ * Stricter than Docker's own parser (no fractions, no `t`), and that is safe only because every bound the worker
+ * passes is written by `formatMemory` from a size `parseMemory` accepted: `job-size.test.mjs` walks every such size
+ * through the argv and back through this function.
+ */
+export function memoryBytes(memory) {
+	const m = /^(\d{1,15})([bkmg]?)$/i.exec(String(memory ?? ""));
+	if (!m) return null;
+	const bytes = Number(m[1]) * { "": 1, b: 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3 }[m[2].toLowerCase()];
+	return Number.isSafeInteger(bytes) && bytes > 0 ? bytes : null;
+}
+
+/** The `--memory=` bound in a runtime argv, in bytes (`memoryBytes`), or null when the argv carries none. */
+export function memoryBytesOfArgs(args) {
+	if (!Array.isArray(args)) return null;
+	const flag = args.find((a) => typeof a === "string" && a.startsWith("--memory="));
+	return flag === undefined ? null : memoryBytes(flag.slice("--memory=".length));
+}