@edgehero/pi-dispatch 3.1.0 → 4.0.0

package/src/sandbox.mjs

@@ -9,6 +9,8 @@ import { DEFAULT_BACKEND, PODMAN_BACKEND, UNATTRIBUTED_BACKEND, parseBackendFloo
 import { configError } from "./config.mjs";
 import { assertJobUser, CONTAINER_HOME, SHIPPED_IMAGE_UID } from "./container-spec.mjs";
 import { buildDockerRunArgs, buildPodmanRunArgs, insideDir } from "./docker-run.mjs";
+import { CGROUP_PARENT, cgroupParentFor } from "./cpu-reserve.mjs";
+import { DEFAULT_JOB_SIZE, 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";
@@ -22,7 +24,8 @@ import { isSandboxTombstone, readManifest, readRetained, sandboxDeadline, sandbo
  *
  * A SECOND container shape, deliberately not a second copy of the first. The argv comes from the run's VENUE's own
  * job builder (`buildDockerRunArgs` on `local`, `buildPodmanRunArgs` on `podman`, `SANDBOX_LAUNCHERS` below) through
- * its `extraFlags` seam, so `ISOLATION_FLAGS`, `--memory` and `--cpus` (and on podman keep-id and
+ * its `extraFlags` seam, so `ISOLATION_FLAGS` and the size flags (`--memory`, `--memory-swap`, `--cpu-shares`, `--shm-size`
+ * and the `--cpus` ceiling, at the RUN's recorded size, issue #596) (and on podman keep-id and
  * `PODMAN_PINNED_FLAGS`) reach this container BY CONSTRUCTION: a future change to the boundary cannot land on job
  * containers and miss this one, which is the whole reason for reusing the builder rather than writing a leaner argv
  * here.
@@ -154,7 +157,7 @@ function inPortRange(n) {
  * @param relabel      true where the job's own mounts carried `:Z` (issue #355), so the retained ones do again
  * @param workspaceOwned true when `workspace` is the retained clone (the worker's own), false for an operator's folder
  */
-export function buildSandboxRunArgs({ venue = DEFAULT_BACKEND, image, name, workspace, jobDir, publish = [], term, idleSeconds = 0, network = null, egressEnv: proxyEnv = {}, user = null, home = null, relabel = false, workspaceOwned = false }) {
+export function buildSandboxRunArgs({ venue = DEFAULT_BACKEND, image, name, workspace, jobDir, publish = [], term, idleSeconds = 0, network = null, egressEnv: proxyEnv = {}, user = null, home = null, relabel = false, workspaceOwned = false, size = DEFAULT_JOB_SIZE, hostCpus = null, cgroupParent = CGROUP_PARENT }) {
 	// Thrown, not defaulted to docker: a caller naming a venue this file has no launcher for is assembling a session
 	// in a runtime nobody chose, which is the one mistake the table exists to make impossible.
 	const launcher = sandboxLauncher(venue);
@@ -192,6 +195,13 @@ export function buildSandboxRunArgs({ venue = DEFAULT_BACKEND, image, name, work
 		// operator's folder, which a private label would take away from every other container.
 		relabel,
 		workspaceOwned,
+		// Issue #596: the RUN's size (its manifest's, `sandboxSizeOf`), so the shell has the memory, swap bound and CPU
+		// weight the job had, and the same `--cpus` ceiling from this CLI's own runtime read.
+		size,
+		hostCpus,
+		// Issue #596, phase 2: the jobs' parent cgroup, as a job on this venue gets it (none where Podman's cgroup manager
+		// is not systemd, `cgroupParentFor`), so a session shares the host's CPU reserve with the jobs.
+		cgroupParent,
 		// The terminal's two variables, and neither is a credential. TERM so the shell renders; TMOUT so a
 		// forgotten session closes itself. HOME beside `--user` and the proxy variables below are the rest.
 		// `buildDockerRunArgs` skips undefined, so an unset TERM or a disabled idle timeout emits nothing rather than
@@ -1029,6 +1039,9 @@ export async function openSandbox({
 	if (resolved.refused) return resolved;
 	// Admitted by `resolveSandbox`, so never null here.
 	const { bin } = sandboxLauncher(resolved.venue);
+	// Issue #596: the run's size, decided before anything is asked or created. A recorded size that is malformed refuses.
+	const size = sandboxSizeOf(resolved.manifest);
+	if (size === null) return { refused: "size-invalid", message: `the run's recorded size is malformed, so the size ${jobId} ran at is unknown; re-run the job instead` };
 
 	// `--publish` AND AN ARMED POLICY ARE OPPOSITE DIRECTIONS, and docker resolves the contradiction SILENTLY
 	// (issue #362). An armed policy puts this shell on its own `--internal` network, and a container attached
@@ -1134,6 +1147,9 @@ export async function openSandbox({
 		user: jobUser?.user ?? null,
 		home: jobUser?.home ?? null,
 		relabel: jobUser?.relabel === true,
+		size,
+		hostCpus: jobUser?.hostCpus ?? null,
+		cgroupParent: jobUser?.cgroupParent === null ? null : CGROUP_PARENT,
 		// By containment, the rule `rebaseWorkspace` already moves the retained clone by: a workspace inside the retained
 		// job dir is the worker's own clone, one outside it is the operator's folder. Not by the manifest's `kind`, so a run
 		// retained before a preparer moved its clone is still judged by where the files actually are.
@@ -1421,15 +1437,21 @@ async function decideLocalSandboxJobUser({
 	// Issue #452, gate round 5: the facts read ONCE here even where the uid needs none of them (a VM-backed platform, an
 	// endpoint on another machine), and carried beside the answer for the teardown's detach gate, which otherwise reads
 	// `docker info` again at teardown and, if that read fails, keeps the network (the Docker Desktop case).
+	// Issue #596: the CPU count rides beside it, for the session's `--cpus` ceiling.
+	let admittedCpus = null;
 	const admittedOn = async () => {
 		try {
 			const read = await readFacts();
+			admittedCpus = read?.answered ? (read.facts?.hostCpus ?? null) : null;
 			return read?.answered ? runtimeFromFacts(read) : undefined;
 		} catch {
 			return undefined;
 		}
 	};
-	if (platform === "darwin" || platform === "win32") return withRuntime({ user: null, home: null }, await admittedOn());
+	if (platform === "darwin" || platform === "win32") {
+		const runtime = await admittedOn();
+		return withRuntime({ user: null, home: null }, runtime, admittedCpus);
+	}
 	const stamp = manifest?.jobUser;
 	const read = readJobUserStamp(stamp);
 	if (read.malformed) return { ...MALFORMED_STAMP };
@@ -1467,7 +1489,8 @@ async function decideLocalSandboxJobUser({
 	if (rootful?.refusal) return { refused: PODMAN_CONF_WIDENS_JOB, message: rootfulConfRefusal(rootful.refusal) };
 	// `runtime` (issue #452, gate round 4): the facts this session was admitted on, for its teardown's detach gate.
 	const runtime = daemon?.answered ? runtimeFromFacts(daemon) : remoteRuntime;
-	if (decision.mode === "image") return withRuntime({ user: null, home: null, ...relabel }, runtime);
+	const hostCpus = daemon?.answered ? (daemon.facts?.hostCpus ?? null) : admittedCpus;
+	if (decision.mode === "image") return withRuntime({ user: null, home: null, ...relabel }, runtime, hostCpus);
 	const needsImage = identity.euid !== SHIPPED_IMAGE_UID;
 	const caps = needsImage ? await imageCapabilities(manifest?.image) : { ok: true, capabilities: [] };
 	if (needsImage && !caps?.ok) {
@@ -1478,7 +1501,7 @@ async function decideLocalSandboxJobUser({
 		return { refused: chosen.refused, message: `the retained image ${manifest?.image} does not declare anyUid, so it cannot run as the uid that owns this run's files (issue #341)` };
 	}
 	if (chosen.refused) return { refused: chosen.refused, message: `${JOB_USER_FIX[chosen.cause] ?? "the job user could not be decided"} (issue #341)` };
-	return withRuntime({ user: chosen.user, home: chosen.home, ...relabel }, runtime);
+	return withRuntime({ user: chosen.user, home: chosen.home, ...relabel }, runtime, hostCpus);
 }
 
 /**
@@ -1486,8 +1509,14 @@ async function decideLocalSandboxJobUser({
  * non-enumerable, so the answer's shape, which callers compare and print, is what it always was, while `openSandbox`'s
  * teardown hands it to the detach gate and reads the daemon nothing more.
  */
-function withRuntime(answer, runtime) {
+function withRuntime(answer, runtime, hostCpus = null, cgroupParent = CGROUP_PARENT) {
 	if (runtime !== undefined) Object.defineProperty(answer, "runtime", { value: runtime, enumerable: false });
+	// Issue #596, phase 2: whether the session runs under the jobs' parent cgroup (`cgroupParentFor`), non-enumerable for
+	// `runtime`'s reason. Set only when it is none, so every other answer is what it always was.
+	if (cgroupParent === null) Object.defineProperty(answer, "cgroupParent", { value: null, enumerable: false });
+	// Issue #596: the runtime's CPU count from the same read, for the session's `--cpus` ceiling. Non-enumerable for
+	// `runtime`'s reason: the answer's shape stays what it always was.
+	if (Number.isSafeInteger(hostCpus)) Object.defineProperty(answer, "hostCpus", { value: hostCpus, enumerable: false });
 	return answer;
 }
 
@@ -1582,7 +1611,19 @@ async function decidePodmanSandboxJobUser({
 	if (chosen.unavailable) return { refused: "job-user-unknown", message: `which uid the sandbox may run as could not be decided (${chosen.reason}); is podman answering \`podman info\` as this account?` };
 	// `relabel` on podman is `podman info`'s SELinux fact, the rule a podman job's own mounts follow (issue #355).
 	// `runtime` (issue #452, gate round 4): the same read, for the session teardown's detach gate, so it reads nothing again.
-	return withRuntime({ user: chosen.user, home: chosen.home, ...(chosen.relabel === true ? { relabel: true } : {}) }, { podman: true, rootless: info.info?.rootless ?? null, version: info.info?.version ?? null });
+	return withRuntime({ user: chosen.user, home: chosen.home, ...(chosen.relabel === true ? { relabel: true } : {}) }, { podman: true, rootless: info.info?.rootless ?? null, version: info.info?.version ?? null }, info.info?.hostCpus ?? null, cgroupParentFor({ podman: true, cgroupManager: info.info?.cgroupManager ?? null }));
+}
+
+/**
+ * The size a sandbox reopens a run at (issue #596): the size its manifest recorded, or the built-in 4g and 2 for a run
+ * retained before sizes existed (no `size` key), which is the size every such run had. A `size` key that is PRESENT
+ * and does not rebuild (`recordedJobSize`) is null, and the open refuses (`size-invalid`): the retention writes the key
+ * only with a size, so a malformed one is damage, and repairing it to 4g would open a shell at a size the run never
+ * had, larger than a small project's, without a word.
+ */
+export function sandboxSizeOf(manifest) {
+	if (!manifest || typeof manifest !== "object" || !Object.hasOwn(manifest, "size")) return DEFAULT_JOB_SIZE;
+	return recordedJobSize(manifest.size);
 }
 
 /**

package/src/scoped-limits.mjs

@@ -39,6 +39,10 @@
  * its repo or folder row, then its project's row, then the global windows (`scopedLedgers`), and its keys are built from
  * the project ROW's scope like every other row's, so a project needs no keyspace of its own.
  *
+ * Issue #596 (phase 1) adds version 3: a project row may carry its jobs' size (`memory`, `cpus`) and the host budget's
+ * two knobs (`hostShare`, `minJobs`), see `SIZE_LIMIT_FIELDS`. This module only parses them; `job-size.mjs` resolves the
+ * size at pickup, and the host budget (`host-budget.mjs`, phase 2) enforces `hostShare` and `minJobs`.
+ *
  * Custom: scoped limits validated inline per triggers.mjs/pause-windows.mjs precedent; zod not in deps
  */
 
@@ -51,6 +55,7 @@ import { splitModelEntry } from "./model-ref.mjs";
 import { formatMicros, parseUsdMicros } from "./money.mjs";
 import { parseScopeString, qualifiedScopeOf, scopeOf } from "./pause-windows.mjs";
 import { PROJECT_ID_RE, isProjectId } from "./project-id.mjs";
+import { formatCpus, formatMemory, parseCpus, parseMemory } from "./job-size.mjs";
 
 /**
  * The highest schema version this build reads. A file declaring a higher one is refused loudly. The admin writes the
@@ -66,7 +71,26 @@ import { PROJECT_ID_RE, isProjectId } from "./project-id.mjs";
  * cap, a concurrency limit and a lease that one build enforces and another silently ignores. Version 2 makes every
  * older build refuse the file loudly instead.
  */
-export const SCOPED_LIMITS_VERSION = 2;
+export const SCOPED_LIMITS_VERSION = 3;
+
+/**
+ * The four size fields of version 3 (issue #596), on a PROJECT row only, in display order:
+ *   - `memory`: the project's jobs' memory (`"512m"`, `"4g"`; `job-size.mjs` `parseMemory`), stored in its one spelling;
+ *   - `cpus`: their CPU weight (`0.5`, `2`; `parseCpus`), stored as a number;
+ *   - `hostShare`: the most of a host's job budget the project's running jobs may hold together, as a whole PERCENTAGE
+ *     from 1 to 100 (`50` is half). ENFORCED by each host's budget (`host-budget.mjs`): a job that would take the
+ *     project past it waits, and a size above it is refused there for a job on that host's own queue
+ *     (`job-size-exceeds-share`; on the shared queue it waits for a host whose share fits it);
+ *   - `minJobs`: how many of the project's jobs a host should make room for before it admits other projects' jobs, a
+ *     soft minimum. ENFORCED by the host budget's tier 1 holds (`host-budget.mjs` `rankHolds`).
+ * A version 1 or 2 file that carries one is refused naming version 3, for the version 2 reason: a 3.1.0 worker drops
+ * unknown fields, so the file would size its jobs on one build and not on another. Every released build refuses a
+ * version 3 file as newer, but only when it LOADS the file, at boot: a worker already running when the file becomes
+ * version 3 keeps its last good file on reload (`scoped_limits_reload_invalid`) and runs the project's jobs at the
+ * default size until it is upgraded and restarted. So every worker is upgraded and restarted before a size is written.
+ * A version 3 row also refuses a key it does not know, so a misspelled size field cannot drop out silently.
+ */
+export const SIZE_LIMIT_FIELDS = Object.freeze(["memory", "cpus", "hostShare", "minJobs"]);
 
 /** The four job-count limit fields a row may carry, in display order. */
 const LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
@@ -74,6 +98,9 @@ const LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
 /** The three dollar window fields (version 2), in display order. Each maps to a dollar window: day, week, month. */
 export const USD_LIMIT_FIELDS = Object.freeze(["dayUsd", "weekUsd", "monthUsd"]);
 
+/** Every key a version 3 row may carry (issue #596). Any other key refuses a version 3 file (`normalizeLimit`). */
+const V3_ROW_KEYS = new Set(["scope", ...LIMIT_FIELDS, ...USD_LIMIT_FIELDS, ...SIZE_LIMIT_FIELDS]);
+
 /**
  * The scope prefix of a per-model row (issue #502 part 6): `model:<provider>/<model>`. Reserved in BOTH versions. A
  * version 1 file naming it is refused (naming version 2) rather than read as a folder called `model:...`.
@@ -156,9 +183,10 @@ export function canonicalScope(job) {
 
 /**
  * Parse, validate, and normalize the scoped-limits file TEXT. Returns the normalized `limits` array
- * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal in a version 1 file, and
- * `{ scope, day, week, month, concurrent, dayUsd, weekUsd, monthUsd }` in a version 2 one, `null` for absent
- * fields, unknown fields dropped -- the operator-file policy). Throws `configError` (fail-loud) on any
+ * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal in a version 1 file,
+ * `{ scope, day, week, month, concurrent, dayUsd, weekUsd, monthUsd }` in a version 2 one, and that plus `memory,
+ * cpus, hostShare, minJobs` in a version 3 one, `null` for absent fields, unknown fields dropped in a version 1 or 2
+ * file -- the operator-file policy -- and refused in a version 3 one). Throws `configError` (fail-loud) on any
  * malformed entry. `path` is for error messages only -- this function touches no filesystem.
  */
 export function parseScopedLimits(text, path) {
@@ -173,7 +201,7 @@ export function parseScopedLimits(text, path) {
 	}
 	const version = parsed.version;
 	if (!Number.isInteger(version) || version < 1) {
-		throw configError(`scoped-limits file must have "version": 1 or ${SCOPED_LIMITS_VERSION} (an integer >= 1): ${path}`);
+		throw configError(`scoped-limits file must have "version": 1 to ${SCOPED_LIMITS_VERSION} (an integer >= 1): ${path}`);
 	}
 	if (version > SCOPED_LIMITS_VERSION) {
 		throw configError(`scoped-limits file written by a newer pi-dispatch (version ${version}; this build understands ${SCOPED_LIMITS_VERSION}): ${path}`);
@@ -240,10 +268,10 @@ function normalizeModelLimit(row, trimmed, at, path, version) {
 	// The runner folds model-less and overflow calls into an `other/other` usage row, so a row naming that pair
 	// could never be told apart from the fold.
 	if (`${ref.provider}/${ref.model}`.toLowerCase() === "other/other") throw configError(`${at}: model:other/other names the usage ledger's fold row, not a model: ${path}`);
-	for (const field of LIMIT_FIELDS) {
+	for (const field of [...LIMIT_FIELDS, ...SIZE_LIMIT_FIELDS]) {
 		if (row[field] !== undefined && row[field] !== null) throw configError(`${at}: a model row carries dayUsd, weekUsd and monthUsd only (${field} is refused): ${path}`);
 	}
-	const norm = { scope: `${MODEL_SCOPE_PREFIX}${ref.provider}/${ref.model}`, day: null, week: null, month: null, concurrent: null, dayUsd: null, weekUsd: null, monthUsd: null };
+	const norm = { scope: `${MODEL_SCOPE_PREFIX}${ref.provider}/${ref.model}`, day: null, week: null, month: null, concurrent: null, dayUsd: null, weekUsd: null, monthUsd: null, ...(version >= 3 ? sizeNulls() : {}) };
 	let any = false;
 	for (const field of USD_LIMIT_FIELDS) {
 		if (row[field] === undefined || row[field] === null) continue;
@@ -260,6 +288,13 @@ function normalizeLimit(row, index, path, version = SCOPED_LIMITS_VERSION) {
 		throw configError(`${at}: must be an object: ${path}`);
 	}
 	if (!isNonEmptyString(row.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+	// Version 3 refuses a key it does not know (issue #596): a misspelled `Memory`, `cpu` or `mem` beside a field that
+	// keeps the row valid was dropped, and the project's jobs ran at the default size while the file read as sized.
+	// Versions 1 and 2 keep dropping unknown keys, so a file an older build wrote and reads still loads unchanged.
+	if (version >= 3) {
+		const unknown = Object.keys(row).filter((key) => !V3_ROW_KEYS.has(key));
+		if (unknown.length > 0) throw configError(`${at}: unknown key${unknown.length === 1 ? "" : "s"} ${unknown.map((k) => JSON.stringify(k)).join(", ")} (a version 3 row carries only scope, ${[...LIMIT_FIELDS, ...USD_LIMIT_FIELDS, ...SIZE_LIMIT_FIELDS].join(", ")}; keys are case-sensitive): ${path}`);
+	}
 	const trimmed = row.scope.trim().normalize("NFC"); // the same NFC canonicalScope applies job-side
 	if (isModelScope(trimmed)) return normalizeModelLimit(row, trimmed, at, path, version);
 	// A NEAR MISS of a reserved prefix is refused, never read as a repo or folder row (PR #549's review): a
@@ -312,6 +347,9 @@ function normalizeLimit(row, index, path, version = SCOPED_LIMITS_VERSION) {
 		// read-modify-write writes back exactly what the parser accepts. `dollarCapsFor` turns them into integers.
 		// Only in a version 2 file's rows: a version 1 file reads into exactly the five-key literal it always did.
 		...(version >= 2 ? { dayUsd: null, weekUsd: null, monthUsd: null } : {}),
+		// Version 3's size fields (issue #596), the same way: only in a version 3 file's rows, null unless a project row
+		// sets them, so a version 1 or 2 file reads into exactly the literal it always did.
+		...(version >= 3 ? sizeNulls() : {}),
 	};
 	let any = false;
 	for (const field of USD_LIMIT_FIELDS) {
@@ -337,12 +375,55 @@ function normalizeLimit(row, index, path, version = SCOPED_LIMITS_VERSION) {
 		norm[field] = value;
 		any = true;
 	}
+	// Issue #596: a project row may carry a size and nothing else, so the size fields count as limiting something.
+	if (sizeFields(row, norm, { at, path, version, project: isProjectScope(trimmed) })) any = true;
 	if (!any) {
-		throw configError(`${at}: at least one of day, week, month, concurrent${version >= 2 ? ", dayUsd, weekUsd, monthUsd" : ""} is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
+		throw configError(`${at}: at least one of day, week, month, concurrent${version >= 2 ? ", dayUsd, weekUsd, monthUsd" : ""}${version >= 3 && isProjectScope(trimmed) ? ", memory, cpus, hostShare, minJobs" : ""} is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
 	}
 	return norm;
 }
 
+/** The four version 3 size fields, all null: what a version 3 row carries when it sets none. */
+function sizeNulls() {
+	return { memory: null, cpus: null, hostShare: null, minJobs: null };
+}
+
+/**
+ * Read a row's size fields into `norm` (issue #596), refusing loudly, and say whether it set any. Only a project row
+ * may carry them: a size is what one project's jobs need, and a repo or folder row is not where a job's project is
+ * decided. `minJobs` needs a size on the same row (a minimum of jobs of an unstated size reserves nothing anyone can
+ * judge) and may not exceed the row's own `concurrent` (a minimum the project can never reach). `hostShare` against
+ * `minJobs` times the size is judged where a host's budget is known (doctor warns, `hostBudgetChecks`), because a
+ * percentage of a host is an amount only on a host.
+ */
+function sizeFields(row, norm, { at, path, version, project }) {
+	const present = SIZE_LIMIT_FIELDS.filter((f) => row[f] !== undefined && row[f] !== null);
+	if (present.length === 0) return false;
+	if (!project) throw configError(`${at}: ${present.join(", ")} belong on a project row (project:<id>), because a job's size is its project's: ${path}`);
+	if (version < 3) throw configError(`${at}: ${present.join(", ")} needs "version": 3 (this file says ${version}), so a build that predates job sizes refuses the file rather than running the project's jobs at the default size: ${path}`);
+	const sized = (field, parse, store) => {
+		if (row[field] === undefined || row[field] === null) return;
+		try {
+			norm[field] = store(parse(row[field]));
+		} catch (error) {
+			throw configError(`${at}: ${field}: ${error.message}: ${path}`);
+		}
+	};
+	sized("memory", parseMemory, formatMemory);
+	sized("cpus", parseCpus, (centi) => Number(formatCpus(centi)));
+	if (row.hostShare !== undefined && row.hostShare !== null) {
+		if (!Number.isSafeInteger(row.hostShare) || row.hostShare < 1 || row.hostShare > 100) throw configError(`${at}: hostShare is a whole percentage of the host's job budget, from 1 to 100 (got ${JSON.stringify(row.hostShare)}): ${path}`);
+		norm.hostShare = row.hostShare;
+	}
+	if (row.minJobs !== undefined && row.minJobs !== null) {
+		if (!Number.isSafeInteger(row.minJobs) || row.minJobs < 1) throw configError(`${at}: minJobs must be an integer >= 1: ${path}`);
+		if (norm.memory === null && norm.cpus === null) throw configError(`${at}: minJobs needs memory or cpus on the same row, so the room it asks a host to keep has a size: ${path}`);
+		if (norm.concurrent !== null && row.minJobs > norm.concurrent) throw configError(`${at}: minJobs ${row.minJobs} is above this row's concurrent ${norm.concurrent}, a minimum the project can never reach: ${path}`);
+		norm.minJobs = row.minJobs;
+	}
+	return true;
+}
+
 /**
  * Load and validate the scoped-limits file named by `config.scopedLimitsFile`. Returns `[]` when the file
  * is unset (no scoped caps or concurrency -- a valid deployment; the folder mutex holds regardless, it is
@@ -567,12 +648,15 @@ export function dollarRowsBelowJobCap(limits, deploymentMaxCostUsd) {
 }
 
 /**
- * The lowest file version that expresses `rows` (normalized or as the admin builds them): 2 when any row carries a
- * dollar field, is a model row, is a project row (issue #499 part B) or has a forge-qualified scope (issue #498), else 1.
+ * The lowest file version that expresses `rows` (normalized or as the admin builds them): 3 when any row carries a size
+ * field (issue #596), else 2 when any row carries a dollar field, is a model row, is a project row (issue #499 part B)
+ * or has a forge-qualified scope (issue #498), else 1.
  * The admin writes this, so a file
  * with bare and folder job-count rows only stays a version 1 file that an older worker still reads.
  */
 export function scopedLimitsVersionFor(rows) {
+	// Issue #596: a size field on any row needs version 3 (the parser refuses it off a project row, and says so).
+	if ((rows ?? []).some((l) => SIZE_LIMIT_FIELDS.some((f) => l?.[f] !== null && l?.[f] !== undefined))) return 3;
 	const v2 = (rows ?? []).some((l) => {
 		const scope = typeof l?.scope === "string" ? l.scope.trim() : l?.scope;
 		return isModelScope(scope) || isProjectScope(scope) || isQualifiedScope(scope) || USD_LIMIT_FIELDS.some((f) => l?.[f] !== null && l?.[f] !== undefined);

package/src/size-records.mjs

@@ -0,0 +1,80 @@
+/**
+ * The run records a size suggestion reads (issue #596, phase 3, DES-SIZE-SUGGESTIONS), read ONCE per doctor run, panel
+ * view or insights render and handed to `suggestSize` for every project. Doctor and the admin share this reader, so the
+ * bounds below hold on every surface:
+ *
+ *   - an MTIME PREFILTER: a file the worker last wrote before the window (plus a day for skew) is not opened. A
+ *     keep-forever logs directory (`PI_LOG_RETENTION_DAYS=0`) is otherwise read whole on every render;
+ *   - a SIZE CAP per file (`SIZING_RECORD_MAX_BYTES`, 256 KiB): a larger file is skipped and COUNTED, never parsed. A
+ *     run record is a few KiB; the cap keeps a hand-placed or corrupted giant from costing a render its memory, and
+ *     the count says it happened rather than leaving a silent hole;
+ *   - only a record that carries measurements (an object `resources` and a `size`) is kept, and of those the NEWEST
+ *     `SUGGEST_WINDOW_RUNS` per project (by `endedAt`), since no suggestion reads more. The filter runs BEFORE the
+ *     cut: a run refused before its container started (a budget or policy refusal) writes a record with neither, and
+ *     cut first, fifty such refusals would crowd every measured run out of the window.
+ *
+ * Never throws: an absent directory holds no records; another unreadable one is `unreachable` (doctor reads that as
+ * none, the panel says it).
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SUGGEST_WINDOW_DAYS, SUGGEST_WINDOW_RUNS } from "./size-suggest.mjs";
+
+/** The largest run record a size suggestion parses: 256 KiB. A larger one is skipped and counted. */
+export const SIZING_RECORD_MAX_BYTES = 256 * 1024;
+/** How far back a file's mtime may lie and still be opened: the window plus a day of skew. */
+export const SIZING_MTIME_DAYS = SUGGEST_WINDOW_DAYS + 1;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * `{ records, skipped, unreachable }`: the parsed records (at most SUGGEST_WINDOW_RUNS per project, newest first by
+ * `endedAt`; a record with no string `project`, no readable `endedAt`, no object `resources` or no `size` is dropped,
+ * since no suggestion could read it), how many files were skipped for their size, and null or a reason when the
+ * directory itself could not be listed.
+ * `fs` is `{ readdirSync, statSync, readFileSync }`.
+ */
+export function readSizingRecords(logsDir, { nowMs, fs = { readdirSync, readFileSync, statSync } } = {}) {
+	const since = nowMs - SIZING_MTIME_DAYS * DAY_MS;
+	let names;
+	try {
+		names = fs.readdirSync(logsDir);
+	} catch (err) {
+		return { records: [], skipped: 0, unreachable: err?.code === "ENOENT" ? null : `logs dir unreadable (${err?.code ?? "read-error"})` };
+	}
+	const byProject = new Map();
+	let skipped = 0;
+	for (const name of names) {
+		if (typeof name !== "string" || !name.endsWith(".json")) continue;
+		try {
+			const path = join(logsDir, name);
+			const st = fs.statSync(path);
+			if (!st.isFile() || st.mtimeMs < since) continue;
+			if (st.size > SIZING_RECORD_MAX_BYTES) {
+				skipped++;
+				continue;
+			}
+			const buf = fs.readFileSync(path);
+			if (buf.length > SIZING_RECORD_MAX_BYTES) {
+				skipped++; // it grew between the stat and the read
+				continue;
+			}
+			const record = JSON.parse(buf.toString("utf8"));
+			const at = typeof record?.endedAt === "string" ? Date.parse(record.endedAt) : NaN;
+			if (typeof record?.project !== "string" || !Number.isFinite(at)) continue;
+			if (!isObject(record.resources) || !isObject(record.size)) continue; // no measurements: never counts toward the 50
+			if (!byProject.has(record.project)) byProject.set(record.project, []);
+			byProject.get(record.project).push({ at, record });
+		} catch {
+			// unparseable, or reaped between the listing and the read
+		}
+	}
+	const records = [];
+	for (const list of byProject.values()) {
+		list.sort((a, b) => b.at - a.at);
+		for (const { record } of list.slice(0, SUGGEST_WINDOW_RUNS)) records.push(record);
+	}
+	return { records, skipped, unreachable: null };
+}