@intentic/constants 1.311.0 → 1.313.0

package/README.md

@@ -8,7 +8,7 @@ flowchart LR
     c -->|"index: browser-safe values"| web["Web app · public site"]
     c -->|"index"| daemon["Daemon · platform api · CLIs"]
     c -->|"./node: repoRoot"| scripts["Scripts, configs,<br/>dev servers"]
-    c -->|"plain .mjs tables"| gates["_tools/checks · push gate<br/>daemon's own checks"]
+    c -->|"plain .mjs tables"| gates["_tools/checks · verify scripts<br/>daemon's own checks"]
 ```
 
 - The index has no Node imports, so the web app and the public site bundle the same values the daemon reads.
@@ -17,8 +17,18 @@ flowchart LR
 - `./node` holds `repoRoot` and `packageRoot`, which find the monorepo by walking up to `pnpm-workspace.yaml`
   instead of counting `../..`. The `paths` check refuses counted roots.
 - The `.mjs` modules (`control-bytes`, `contract-shrink`, `assertion-measure`, `mirror-roots`, `test-suites`,
-  `vocabulary`, `ci-infra-steps`) are plain JavaScript with `.d.mts` types, so the checks and the push gate import
-  them by path before any install or build, and the daemon applies the same rule from the same file.
+  `vocabulary`, `ci-infra-steps`, `memory-room`, `allow`, `heavy-rules`) are plain JavaScript with `.d.mts` types, so
+  the checks and the verify scripts import them by path before any install or build, and the daemon applies the same
+  rule from the same file.
+- `heavy-rules.cjs` is the one heavy-command table (which programs queue, their pools, max-holds and deadlines, and
+  the owner's overrides merged on top); `heavy-hook.cjs` (a `node --require` preload) and `heavy-exec.cjs` (behind the
+  sandbox's wrappers for native programs) judge a program by what it is as it starts. CommonJS, so the hook loads
+  on any Node an agent's project pins.
+- `memory-room` is the one formula for whether the sandbox has room (limit, used, free, stall, and what each workload
+  class costs). The daemon's resource budget judges by it, and it is also the `memory-room` command `queue-run` asks:
+  it asks the daemon's room socket, and applies the formula itself where no daemon answers.
+- `./allow` reads the two exception forms every check and guard suite honours: the site pragma
+  `// allow(<check>): <reason>` and the commit trailer `Allow: <check> — <reason>`.
 - `WORKSPACE_ROOT` and `HISTORY_ROOT` are defaults only: a running daemon reads its real roots from config.
 
 ## Key files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/constants",
-  "version": "1.311.0",
+  "version": "1.313.0",
   "description": "Shared constants for the intentic packages, ports, paths, and image references the daemon, CLIs and desktop app all agree on",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,16 @@
     "src/mirror-roots.mjs",
     "src/mirror-roots.d.mts",
     "src/ci-infra-steps.mjs",
-    "src/ci-infra-steps.d.mts"
+    "src/ci-infra-steps.d.mts",
+    "src/memory-room.mjs",
+    "src/memory-room.d.mts",
+    "src/allow.mjs",
+    "src/allow.d.mts",
+    "src/heavy/heavy-rules.cjs",
+    "src/heavy/heavy-rules.d.cts",
+    "src/heavy/heavy-turn.cjs",
+    "src/heavy/heavy-hook.cjs",
+    "src/heavy/heavy-exec.cjs"
   ],
   "exports": {
     ".": {
@@ -64,13 +73,27 @@
     "./test-suites": {
       "types": "./src/test-suites.d.mts",
       "default": "./src/test-suites.mjs"
-    }
+    },
+    "./memory-room": {
+      "types": "./src/memory-room.d.mts",
+      "default": "./src/memory-room.mjs"
+    },
+    "./allow": {
+      "types": "./src/allow.d.mts",
+      "default": "./src/allow.mjs"
+    },
+    "./heavy-rules": {
+      "types": "./src/heavy/heavy-rules.d.cts",
+      "default": "./src/heavy/heavy-rules.cjs"
+    },
+    "./heavy-hook": "./src/heavy/heavy-hook.cjs",
+    "./heavy-exec": "./src/heavy/heavy-exec.cjs"
   },
   "devDependencies": {
     "@intentic/testing": "0.0.0",
     "@intentic/tsconfig": "0.0.0",
-    "@types/bun": "1.4.0",
-    "@types/node": "24.13.2",
+    "@types/bun": "1.4.2",
+    "@types/node": "24.13.6",
     "@typescript/native-preview": "7.0.0-dev.20260707.2"
   },
   "scripts": {

package/src/allow.d.mts

@@ -0,0 +1,8 @@
+// Types for allow.mjs: the site pragma and commit trailer that excuse a check's finding.
+export function pragmaReason(text: string, check: string): string | undefined;
+export function allowedAt(lines: readonly string[], line: number, check: string): boolean;
+export interface AllowTrailer {
+    readonly check: string;
+    readonly reason: string;
+}
+export function allowTrailers(text: string): AllowTrailer[];

package/src/allow.mjs

@@ -0,0 +1,42 @@
+// THE TWO WAYS TO SAY A CHECK'S FINDING IS RIGHT HERE, read the same way by every check and suite that honours them.
+//
+// - A SITE PRAGMA, `// allow(<check>): <reason>`, for one place in the code: on the flagged line, or anywhere in the
+//   comment block directly above it. It lives on the declaration it excuses, so a rename carries it and a deletion
+//   takes it away, which a list of names kept somewhere else cannot do.
+// - A COMMIT TRAILER, `Allow: <check> — <reason>`, for a change: what the range adds to that check is accepted, with the
+//   reason in the history. `—`, `–`, `-` or `:` may separate the two.
+//
+// A reason is required in both: an exception nobody can explain is a finding nobody fixed.
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+// Comment openers the pragma may follow: a line comment, a block comment or one of its continuation lines.
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
+
+/** The reason a pragma for `check` in `text` gives, or undefined when `text` holds none with a reason. */
+export const pragmaReason = (text, check) => {
+    const found = new RegExp(String.raw`(?:\/\/|\/\*|\*)\s*allow\(${escape(check)}\):\s*(\S[^\n]*?)\s*(?:\*\/)?\s*$`, "m").exec(text);
+    return found?.[1];
+};
+
+/**
+ * Whether the site on 1-based `line` of `lines` carries a pragma for `check`: on the line itself, or in the comment block
+ * that ends on the line above it.
+ */
+export const allowedAt = (lines, line, check) => {
+    const says = (text) => pragmaReason(text, check) !== undefined;
+    if (says(lines[line - 1] ?? "")) {
+        return true;
+    }
+    for (let at = line - 2; at >= 0 && COMMENT_LINE.test(lines[at]); at--) {
+        if (says(lines[at])) {
+            return true;
+        }
+    }
+    return false;
+};
+
+const TRAILER = /^Allow:[ \t]*([\w./-]+?)[ \t]*(?:—|–|:|-{1,2})[ \t]*(\S.*?)[ \t]*$/gm;
+
+/** Every `Allow: <check> — <reason>` line in a commit message or a trailer listing, in order. */
+export const allowTrailers = (text) => [...text.matchAll(TRAILER)].map(([, check, reason]) => ({ check, reason }));

package/src/assertion-measure.mjs

@@ -1,6 +1,6 @@
 // Three numbers per test file (exact matchers, loose matchers, asserted-text characters) that flag a weaker second
-// version; shared by the push gate and the daemon's turn-ending check so both agree. Regex over source, not an AST,
-// since the push gate runs before install.
+// version; read through assertion-ratchet.mjs by the push check and the check after each land, so
+// both agree. Regex over source, not an AST, since the push check runs before install.
 
 // Asserted text that shrinks past this fraction of what it was, with no test removed, is a narrowing.
 export const NARROWING = 0.75;

package/src/heavy/heavy-exec.cjs

@@ -0,0 +1,44 @@
+// The other half of heavy-hook.cjs, for programs that are not node scripts (pnpm's own binary, bun, cargo): a thin
+// wrapper of that name, first on the agent's PATH (_sandbox/sandbox/bin/heavy-shims), runs
+// `node heavy-exec.cjs <wrapper dir> <program> <args…>`. The program is the one its wrapper stands for, its arguments
+// are the ones it was given; heavy-turn.cjs judges them, and then this process becomes the real program, found on the
+// PATH past the wrappers.
+"use strict";
+
+const { accessSync, constants } = require("node:fs");
+const { delimiter, join, resolve } = require("node:path");
+const { takeTurn } = require("./heavy-turn.cjs");
+
+const [shims = "", program = "", ...args] = process.argv.slice(2);
+
+// The real program: the first executable of that name on the PATH that is not a wrapper. The PATH it runs with keeps the
+// wrappers, so a program it starts in turn (a package script's `bun test`) is judged the same way.
+const pathEntries = (process.env.PATH ?? "").split(delimiter).filter((entry) => entry !== "" && resolve(entry) !== resolve(shims));
+const real = pathEntries
+    .map((entry) => join(entry, program))
+    .find((candidate) => {
+        try {
+            accessSync(candidate, constants.X_OK);
+            return true;
+        } catch {
+            // allow(silent-catch): absent or not executable is exactly "not this one"
+            return false;
+        }
+    });
+
+if (real === undefined) {
+    process.stderr.write(`${program}: command not found\n`);
+    process.exit(127);
+}
+try {
+    takeTurn({ program, args, command: [real, ...args] });
+} catch {
+    // allow(silent-catch): a table that does not parse runs the program as if unjudged
+}
+// `real` passed the executable check above, so this execve does not fail the way that aborts a process.
+if (typeof process.execve === "function") {
+    process.execve(real, [program, ...args], process.env);
+}
+const { spawnSync } = require("node:child_process");
+const run = spawnSync(real, args, { stdio: "inherit", env: process.env, argv0: program });
+process.exit(run.status ?? 1);

package/src/heavy/heavy-hook.cjs

@@ -0,0 +1,61 @@
+// Loaded into every node program an agent's command starts (`NODE_OPTIONS=--require …/heavy-hook.cjs`, set by the
+// daemon, _sandbox/sandbox/src/agent/tools/agent-terminals.ts), so the heavy-command queue follows the program that
+// actually runs — `vitest` under `pnpm test`, `tsc` under a `make` target, `turbo` under an npm script — and not the words
+// an agent typed. The program is the script node was asked to run, named as its package publishes it (`vitest`, `tsc`,
+// `npx`); heavy-turn.cjs decides the rest. Nothing here may be why a program did not run.
+"use strict";
+
+const { readFileSync, realpathSync } = require("node:fs");
+const { basename, dirname, join, resolve } = require("node:path");
+
+// The command a script is published as: the `bin` entry of its nearest package.json that names this very file, else its
+// own file name without its extension.
+const programOf = (script) => {
+    let real = script;
+    try {
+        real = realpathSync(script);
+    } catch {
+        // allow(silent-catch): a script path that does not resolve is named by what it says
+    }
+    let dir = dirname(real);
+    for (let depth = 0; depth < 6; depth += 1) {
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        } catch {
+            // allow(silent-catch): a directory without a package.json (or with a broken one) names nothing; look further up
+            manifest = undefined;
+        }
+        if (manifest !== undefined) {
+            const name = typeof manifest.name === "string" ? manifest.name.split("/").pop() : undefined;
+            const bins = typeof manifest.bin === "string" ? { [name ?? ""]: manifest.bin } : (manifest.bin ?? {});
+            const named = Object.entries(bins).find(([, path]) => typeof path === "string" && resolve(dir, path) === real)?.[0];
+            if (named !== undefined && named !== "") {
+                return named;
+            }
+            break;
+        }
+        const up = dirname(dir);
+        if (up === dir) {
+            break;
+        }
+        dir = up;
+    }
+    return basename(real).replace(/\.[cm]?[jt]s$/u, "");
+};
+
+try {
+    const script = process.argv[1];
+    if (process.env.INTENTIC_HEAVY !== undefined && script !== undefined && script !== "") {
+        const { takeTurn } = require("./heavy-turn.cjs");
+        takeTurn({
+            program: programOf(script),
+            args: process.argv.slice(2),
+            command: [process.execPath, ...process.execArgv, ...process.argv.slice(1)],
+        });
+    }
+} catch {
+    // allow(silent-catch): a table that does not parse or a program that cannot be named runs as if unjudged
+}
+
+module.exports = { programOf };

package/src/heavy/heavy-rules.cjs

@@ -0,0 +1,195 @@
+// Which programs are heavy enough to take turns, and how the queue treats them: the one table the daemon
+// (_sandbox/sandbox/src/platform/resources/heavy-commands.ts), the program hook that queues a heavy program as it starts
+// (heavy-hook.cjs, heavy-exec.cjs), queue-run's callers and the repository's own scripts (_tools/scripts/lib/
+// heavy-slot.mjs) all read. CommonJS with no dependencies, so it loads under `node --require` in any project, on any
+// Node an agent's project pins, and ES modules import it by name.
+//
+// A rule's `pattern` is matched against the program that actually runs and its arguments, `<program> <args…>` (`pnpm
+// --filter web test`, `vitest run`, `tsc -b`), never against the shell line an agent typed: quotes, heredocs, globs and
+// assignments are gone by then, and a line that only mentions a program never starts it. First match wins; an `exempt`
+// rule stops the search for what it matches.
+"use strict";
+
+// What queue-run exits with when it ran nothing because the wait was up and the rule said `skip`: EX_TEMPFAIL, so a
+// caller records "not measured", never "failed".
+const QUEUE_SKIPPED_EXIT_CODE = 75;
+
+// Characters of an invocation a rule's regex runs against; bounds backtracking, since node has no regex timeout.
+const MATCH_LIMIT = 4096;
+
+// The shipped rules and settings. Every rule is something measured pinning a sandbox, not merely slow.
+const SHIPPED_HEAVY_COMMANDS = Object.freeze({
+    // How many matching programs may run at once across the sandbox; two fits twice the peak of one bounded run.
+    limit: 2,
+    defaultPool: "heavy",
+    // How long a program waits for a slot before running anyway, so a stuck queue cannot turn into a dead sandbox.
+    waitSeconds: 900,
+    // How long a matching program also waits for memory (memory-room.mjs), before its slot.
+    memoryGateSeconds: 120,
+    // How long a program may HOLD a slot before it is killed. Generous on purpose: this ends a hang, it does not cap
+    // honest work, and a build still running after half an hour on a sandbox is already the anomaly. 0 switches it off.
+    maxHoldSeconds: 1800,
+    // For a rule that says nothing: for a person's command the queue must never be the reason it did not run.
+    onDeadline: "run",
+    rules: Object.freeze([
+        // A watch, a server or a language server is meant to outlive its command, so it can neither take turns nor be
+        // killed for holding a slot: queueing one holds the slot until somebody stops it. `-w` is NOT here: `pnpm -w
+        // test` is a workspace-root fan-out, the heaviest command there is.
+        {
+            id: "long-lived",
+            pattern: "--watch|--lsp\\b|\\bnodemon\\b|\\b(pnpm|npm|yarn|bun)\\s+(run\\s+)?(dev|serve|start)\\b",
+            exempt: true,
+        },
+        // A repo-wide verification, one at a time in the same pool: two of them are the most expensive thing that can
+        // happen to a sandbox at once (measured: 24.9 GiB against a 16 GiB cap), and the second is usually the same
+        // work over the same tree, which turbo's cache makes nearly free once the first is done. Never two at once,
+        // not even after the wait: a verification that did not run costs a check the next land repeats.
+        { id: "repo-verify", pattern: "\\b(pnpm|npm|yarn|bun)\\s+(run\\s+)?verify(:\\S+)?\\b", limit: 1, onDeadline: "skip" },
+        // A program's name joined to `.` or `-` is another word (`check-tsc`), not the program.
+        { id: "vitest", pattern: "(?<![-.])\\b(vitest|jest)\\b(?![-.])" },
+        { id: "typechecker", pattern: "(?<![-.])\\b(tsc|tsgo|vue-tsc)\\b(?![-.])" },
+        { id: "turbo-fanout", pattern: "\\bturbo\\b.*\\brun\\b.*\\b(build|test|typecheck|check)\\b" },
+        { id: "package-script", pattern: "\\b(pnpm|npm|yarn|bun)\\b.*\\b(test|typecheck|verify|check|build)\\b" },
+        { id: "cargo", pattern: "^cargo\\s+(\\+\\S+\\s+)?(build|test|check|clippy|bench|doc)\\b" },
+    ]),
+});
+
+// Every rule an earlier release shipped, as it shipped it (matched against the agent's shell line then). A stored rule
+// equal to one of these was seeded, not chosen, so converting a stored file drops it and the current rule takes over.
+const EARLIER_SHIPPED_RULES = Object.freeze([
+    {
+        id: "read-only",
+        pattern: "^\\s*(grep|rg|iq|ag|cat|bat|head|tail|less|ls|find|fd|wc|which|echo|git\\s+(log|status|diff|show|blame))\\b",
+        exempt: true,
+    },
+    { id: "long-lived", pattern: "--watch|\\bnodemon\\b|\\b(pnpm|npm|yarn|bun)\\s+(run\\s+)?(dev|serve|start)\\b", exempt: true },
+    { id: "repo-verify", pattern: "\\b(pnpm|npm|yarn|bun)\\s+(run\\s+)?verify(:\\S+)?\\b", limit: 1 },
+    { id: "repo-verify", pattern: "\\b(pnpm|npm|yarn|bun)\\s+(run\\s+)?verify(:\\S+)?\\b", limit: 1, onDeadline: "skip" },
+    { id: "vitest", pattern: "\\bvitest\\b" },
+    { id: "vitest", pattern: "(?<![-.])\\bvitest\\b(?![-.])" },
+    { id: "typechecker", pattern: "\\b(tsc|tsgo|vue-tsc)\\b" },
+    { id: "typechecker", pattern: "(?<![-.])\\b(tsc|tsgo|vue-tsc)\\b(?![-.])" },
+    { id: "turbo-fanout", pattern: "\\bturbo\\b[^&|;]*\\brun\\b[^&|;]*\\b(build|test|typecheck|check)\\b" },
+    { id: "package-script", pattern: "\\b(pnpm|npm|yarn|bun)\\b[^&|;]*\\b(test|typecheck|verify|check|build)\\b" },
+]);
+
+const SETTING_KEYS = Object.freeze(["limit", "defaultPool", "waitSeconds", "memoryGateSeconds", "maxHoldSeconds", "onDeadline"]);
+const RULE_KEYS = Object.freeze(["id", "pattern", "pool", "limit", "maxHoldSeconds", "exempt", "onDeadline"]);
+
+// Two rules are the same when every field either names is equal; key order and absent-versus-undefined do not count.
+const sameRule = (left, right) => RULE_KEYS.every((key) => left[key] === right[key]);
+
+// The rules and settings in force: the shipped table with the owner's overrides on top. A setting the overrides name
+// replaces the shipped one; an edit naming a shipped rule's id changes the fields it names, or removes that rule
+// (`disabled`); an edit naming any other id, with a pattern, is the owner's own rule, and the owner's own rules are
+// matched before the shipped ones. `queue: false` stops queueing without touching how heavy programs are ranked.
+const mergeHeavyRules = (overrides = {}) => {
+    const settings = Object.fromEntries(SETTING_KEYS.map((key) => [key, overrides[key] ?? SHIPPED_HEAVY_COMMANDS[key]]));
+    const edits = Array.isArray(overrides.ruleEdits) ? overrides.ruleEdits : [];
+    const shippedIds = new Set(SHIPPED_HEAVY_COMMANDS.rules.map((rule) => rule.id));
+    const editOf = new Map(edits.filter((edit) => shippedIds.has(edit.id)).map((edit) => [edit.id, edit]));
+    const own = edits.filter((edit) => !shippedIds.has(edit.id) && edit.disabled !== true && typeof edit.pattern === "string");
+    const shipped = SHIPPED_HEAVY_COMMANDS.rules.flatMap((rule) => {
+        const edit = editOf.get(rule.id);
+        if (edit === undefined) {
+            return [rule];
+        }
+        if (edit.disabled === true) {
+            return [];
+        }
+        const { disabled: _disabled, ...fields } = edit;
+        return [{ ...rule, ...fields }];
+    });
+    return { ...settings, queue: overrides.queue !== false, rules: [...own.map(({ disabled: _disabled, ...rule }) => rule), ...shipped] };
+};
+
+// A stored file of the earlier shape (every setting and the whole rule list) as overrides: only what differs from what
+// was shipped. A rule equal to a rule some release shipped goes, so the current one takes its place; an empty list was
+// how the queue was switched off.
+const overridesOf = (full) => {
+    const overrides = {};
+    for (const key of SETTING_KEYS) {
+        if (full[key] !== undefined && full[key] !== SHIPPED_HEAVY_COMMANDS[key]) {
+            overrides[key] = full[key];
+        }
+    }
+    const rules = Array.isArray(full.rules) ? full.rules : [];
+    if (Array.isArray(full.rules) && rules.length === 0) {
+        overrides.queue = false;
+    }
+    const shipped = [...SHIPPED_HEAVY_COMMANDS.rules, ...EARLIER_SHIPPED_RULES];
+    const edits = rules.filter((rule) => !shipped.some((known) => sameRule(rule, known)));
+    if (edits.length > 0) {
+        overrides.ruleEdits = edits.map((rule) => Object.fromEntries(RULE_KEYS.filter((key) => rule[key] !== undefined).map((key) => [key, rule[key]])));
+    }
+    return overrides;
+};
+
+const compileRule = (rule, report) => {
+    try {
+        return { rule, regex: new RegExp(rule.pattern, "i") };
+    } catch (error) {
+        report?.(`${rule.id}: ${error instanceof Error ? error.message : "bad pattern"}`);
+        return undefined;
+    }
+};
+
+// The rule a program's invocation falls under, with what the queue does with it; undefined for one that is not heavy.
+const matchInvocation = (invocation, config, report) => {
+    const text = invocation.slice(0, MATCH_LIMIT);
+    for (const rule of config.rules) {
+        const compiled = compileRule(rule, report);
+        if (compiled === undefined || !compiled.regex.test(text)) {
+            continue;
+        }
+        if (rule.exempt === true) {
+            return undefined;
+        }
+        return {
+            id: rule.id,
+            pool: rule.pool ?? config.defaultPool,
+            limit: rule.limit ?? config.limit,
+            maxHold: rule.maxHoldSeconds ?? config.maxHoldSeconds,
+            onDeadline: rule.onDeadline ?? config.onDeadline,
+        };
+    }
+    return undefined;
+};
+
+// queue-run's flags for a match (bin/queue-run), before its `--`.
+const queueArgs = (match, config) => [
+    "--pool",
+    match.pool,
+    "--limit",
+    String(match.limit),
+    "--wait",
+    String(config.waitSeconds),
+    "--memory-gate",
+    String(config.memoryGateSeconds),
+    "--max-hold",
+    String(match.maxHold),
+    "--on-deadline",
+    match.onDeadline,
+    "--label",
+    match.id,
+];
+
+// When a slot held this long is worth a line in the log: half of what its own rule lets it hold, never for a rule that
+// lets it hold forever.
+const holdWarnSeconds = (maxHold) => (maxHold > 0 ? maxHold / 2 : undefined);
+
+// The rule a pool's holder ran under, by the label queue-run names it with, as the merged table has it.
+const ruleById = (config, id) => config.rules.find((rule) => rule.id === id);
+
+module.exports = {
+    QUEUE_SKIPPED_EXIT_CODE,
+    MATCH_LIMIT,
+    SHIPPED_HEAVY_COMMANDS,
+    EARLIER_SHIPPED_RULES,
+    mergeHeavyRules,
+    overridesOf,
+    matchInvocation,
+    queueArgs,
+    holdWarnSeconds,
+    ruleById,
+};

package/src/heavy/heavy-rules.d.cts

@@ -0,0 +1,71 @@
+// Types for heavy-rules.cjs, the one heavy-command table the daemon, the program hook and the scripts read.
+export type OnDeadline = "run" | "skip";
+
+export interface HeavyCommandRule {
+    readonly id: string;
+    // JS regex source, case-insensitive, matched against `<program> <args…>` of the program that runs.
+    readonly pattern: string;
+    readonly pool?: string | undefined;
+    readonly limit?: number | undefined;
+    readonly maxHoldSeconds?: number | undefined;
+    readonly exempt?: boolean | undefined;
+    readonly onDeadline?: OnDeadline | undefined;
+}
+
+// An owner's change to the table: a shipped rule's id changes the fields it names, or removes it (`disabled`); any other
+// id, with a pattern, is the owner's own rule.
+export interface HeavyCommandRuleEdit {
+    readonly id: string;
+    readonly pattern?: string | undefined;
+    readonly pool?: string | undefined;
+    readonly limit?: number | undefined;
+    readonly maxHoldSeconds?: number | undefined;
+    readonly exempt?: boolean | undefined;
+    readonly onDeadline?: OnDeadline | undefined;
+    readonly disabled?: boolean | undefined;
+}
+
+export interface HeavyCommandSettings {
+    readonly limit: number;
+    readonly defaultPool: string;
+    readonly waitSeconds: number;
+    readonly memoryGateSeconds: number;
+    readonly maxHoldSeconds: number;
+    readonly onDeadline: OnDeadline;
+}
+
+export interface HeavyCommandOverrides {
+    readonly limit?: number | undefined;
+    readonly defaultPool?: string | undefined;
+    readonly waitSeconds?: number | undefined;
+    readonly memoryGateSeconds?: number | undefined;
+    readonly maxHoldSeconds?: number | undefined;
+    readonly onDeadline?: OnDeadline | undefined;
+    readonly queue?: boolean | undefined;
+    readonly ruleEdits?: readonly HeavyCommandRuleEdit[] | undefined;
+}
+
+export interface HeavyCommands extends HeavyCommandSettings {
+    // False stops queueing; heavy programs keep their class either way.
+    readonly queue: boolean;
+    readonly rules: readonly HeavyCommandRule[];
+}
+
+export interface HeavyMatch {
+    readonly id: string;
+    readonly pool: string;
+    readonly limit: number;
+    readonly maxHold: number;
+    readonly onDeadline: OnDeadline;
+}
+
+export const QUEUE_SKIPPED_EXIT_CODE: 75;
+export const MATCH_LIMIT: number;
+export const SHIPPED_HEAVY_COMMANDS: HeavyCommandSettings & { readonly rules: readonly HeavyCommandRule[] };
+export const EARLIER_SHIPPED_RULES: readonly HeavyCommandRule[];
+export function mergeHeavyRules(overrides?: HeavyCommandOverrides): HeavyCommands;
+export function overridesOf(full: Partial<HeavyCommandSettings> & { readonly rules?: readonly HeavyCommandRule[] | undefined }): HeavyCommandOverrides;
+export function matchInvocation(invocation: string, config: HeavyCommands, report?: (detail: string) => void): HeavyMatch | undefined;
+export function queueArgs(match: HeavyMatch, config: HeavyCommandSettings): string[];
+export function holdWarnSeconds(maxHold: number): number | undefined;
+export function ruleById(config: HeavyCommands, id: string): HeavyCommandRule | undefined;

package/src/heavy/heavy-turn.cjs

@@ -0,0 +1,113 @@
+// What a heavy program does as it starts, shared by the two ways one is caught: heavy-hook.cjs, loaded into every node
+// program an agent's command starts, and heavy-exec.cjs, which the thin wrappers for native programs (pnpm, bun, cargo)
+// run. Both know the program for a fact, and its arguments as it received them; heavy-rules.cjs says whether it is heavy.
+//
+// A heavy program is put in the toolchain class (its rank for the OOM killer, its CPU and IO priority) right away,
+// whether or not anything queues it, then replaces itself with the same run behind queue-run (a slot, and memory first),
+// or behind offload-run when the owner sends that kind of work to a runner. Everything it starts inherits both, and
+// nothing below it is judged again: INTENTIC_HEAVY_HELD and queue-run's INTENTIC_QUEUE_SLOT say it is already covered.
+//
+// The daemon hands the table in INTENTIC_HEAVY, as JSON: { rules (heavy-rules.cjs mergeHeavyRules), queue, queueRun,
+// offloadRun, offload: { <rule id>: <runner> }, klass: { oomScoreAdj, nice, lowIo } }. Every failure here is a program
+// that runs as if nothing had looked at it.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { accessSync, constants, readFileSync, writeFileSync } = require("node:fs");
+const { getPriority, setPriority } = require("node:os");
+const { matchInvocation, queueArgs } = require("./heavy-rules.cjs");
+
+// The spec the daemon handed down, or undefined when this program is not under it or is already covered.
+const pendingSpec = (env = process.env) => {
+    const raw = env.INTENTIC_HEAVY;
+    if (raw === undefined || raw === "" || env.INTENTIC_HEAVY_HELD !== undefined || env.INTENTIC_QUEUE_SLOT !== undefined) {
+        return undefined;
+    }
+    return JSON.parse(raw);
+};
+
+// The class applied to this very process, raised only: descendants inherit all three at fork.
+const applyClass = (klass) => {
+    if (klass === undefined || process.platform !== "linux") {
+        return;
+    }
+    try {
+        const current = Number(readFileSync("/proc/self/oom_score_adj", "utf8").trim());
+        if (Number.isFinite(current) && current < klass.oomScoreAdj) {
+            writeFileSync("/proc/self/oom_score_adj", String(klass.oomScoreAdj));
+        }
+    } catch {
+        // allow(silent-catch): procfs hidden by a hardened runtime; the kernel then weighs size alone
+    }
+    try {
+        if (getPriority() < klass.nice) {
+            setPriority(klass.nice);
+        }
+    } catch {
+        // allow(silent-catch): a priority this process may not set leaves it where it was
+    }
+    if (klass.lowIo) {
+        spawnSync("ionice", ["-c", "2", "-n", "7", "-p", String(process.pid)], { stdio: "ignore" });
+    }
+};
+
+// POSIX single-quoting, as offload-run's --here prefix is read by a shell.
+const quote = (word) => (/^[\w@%+=:,./-]+$/u.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`);
+
+// Programs every runner has on its PATH; anything else is a project's own, run there from its node_modules.
+const ON_EVERY_PATH = new Set(["node", "npm", "npx", "pnpm", "yarn", "bun", "cargo"]);
+const remoteArgv = (program, args) => (ON_EVERY_PATH.has(program) ? [program, ...args] : ["npx", "--no-install", program, ...args]);
+
+// Whether `path` can be exec'd; checked first because a failed execve aborts the process rather than throwing.
+const runnable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    } catch {
+        // allow(silent-catch): absent or not executable is exactly "cannot run it"
+        return false;
+    }
+};
+
+// This process becomes `argv`: the same pid, so the class and every signal aimed at it still land. A Node too old to
+// replace itself runs it as a child and leaves with its code, the way heavy-slot.mjs does. Returns only when `argv[0]`
+// cannot be run at all, for the caller to run the program in place.
+const become = (argv, env) => {
+    if (!runnable(argv[0])) {
+        return;
+    }
+    if (typeof process.execve === "function") {
+        process.execve(argv[0], argv, env);
+    }
+    const run = spawnSync(argv[0], argv.slice(1), { stdio: "inherit", env });
+    process.exit(run.status ?? (run.signal === null ? 1 : 128));
+};
+
+/**
+ * Judges one program as it starts. Returns false for one that is not heavy (or not under the daemon's table), true for
+ * one that was classed and runs in place; a queued or offloaded one does not return.
+ */
+const takeTurn = ({ program, args, command, env = process.env }) => {
+    const spec = pendingSpec(env);
+    if (spec === undefined) {
+        return false;
+    }
+    const match = matchInvocation([program, ...args].join(" "), spec.rules);
+    if (match === undefined) {
+        return false;
+    }
+    env.INTENTIC_HEAVY_HELD = match.id;
+    applyClass(spec.klass);
+    const queue = spec.queue === true && typeof spec.queueRun === "string" && runnable(spec.queueRun) ? [spec.queueRun, ...queueArgs(match, spec.rules), "--"] : [];
+    const runner = spec.offload?.[match.id];
+    if (runner !== undefined && typeof spec.offloadRun === "string") {
+        const here = queue.length === 0 ? "" : `${queue.map(quote).join(" ")} `;
+        become([spec.offloadRun, "--to", runner, "--label", match.id, "--here", here, "--", ...remoteArgv(program, args)], env);
+    }
+    if (queue.length > 0) {
+        become([...queue, ...command], env);
+    }
+    return true;
+};
+
+module.exports = { takeTurn, pendingSpec, remoteArgv };

package/src/memory-room.d.mts

@@ -0,0 +1,68 @@
+// Types for memory-room.mjs, the one room formula the daemon's ResourceBudget and the scripts share.
+export type RoomWorkload = "agentRuntime" | "service" | "panel" | "install" | "command" | "toolchain";
+
+export const COST_BYTES: Readonly<Record<RoomWorkload, number>>;
+export const PERSON_RESERVE_BYTES: number;
+export const TEST_PROCESS_BYTES: Readonly<{ fanOutWorker: number; standaloneWorker: number; typecheck: number; ceiling: number }>;
+export const STALL_PERCENT: number;
+export const RESERVATION_MS: number;
+export const ROOM_SOCKET: string;
+export const READING_FILES: readonly string[];
+
+export interface MemoryReading {
+    // memory.high, else memory.max, else the machine's memory; undefined where nothing bounds it.
+    readonly limitBytes: number | undefined;
+    // Working set plus swap; undefined where nothing measures it.
+    readonly usedBytes: number | undefined;
+    // The swapped part of `usedBytes`; 0 when swap is off or unaccounted.
+    readonly swapBytes: number;
+    // The machine's MemAvailable, which free memory never exceeds; absent where the machine does not say.
+    readonly availableBytes?: number | undefined;
+    // Memory PSI `full avg10`, in percent; 0 when healthy or unreported.
+    readonly stallPercent: number;
+    // memory.events `oom_kill`, cumulative; undefined without a cgroup.
+    readonly oomKills: number | undefined;
+}
+
+export interface ShortMemory {
+    readonly limitBytes: number;
+    readonly residentBytes: number;
+    readonly swapBytes: number;
+}
+
+export type RoomVerdict = "run" | "wait" | "refuse";
+
+export interface RoomJudgement {
+    readonly verdict: RoomVerdict;
+    readonly needBytes: number;
+    readonly freeBytes: number | undefined;
+    readonly reservedBytes: number;
+    // Why the sandbox is short; absent on `run`.
+    readonly diagnosis?: string;
+    // The reading a byte shortfall was decided on; absent on a stall, whose ceiling is not what is wrong.
+    readonly memory?: ShortMemory;
+}
+
+export interface RoomAnswer extends RoomJudgement {
+    readonly waitedMs: number;
+    readonly source: "daemon" | "formula";
+}
+
+export function readingFrom(read: (path: string) => string | undefined): MemoryReading;
+export function readReadingSync(): MemoryReading;
+export function needBytes(workload: RoomWorkload, attended: boolean): number;
+export function judge(reading: MemoryReading, request: { readonly workload: RoomWorkload; readonly attended: boolean; readonly reservedBytes?: number }): RoomJudgement;
+export function freeBytesOf(reading: MemoryReading): number | undefined;
+export function askRoom(options?: {
+    readonly workload?: RoomWorkload;
+    readonly waitSeconds?: number;
+    readonly label?: string;
+    readonly socketPath?: string;
+    readonly intervalMs?: number;
+    readonly read?: () => MemoryReading;
+}): Promise<RoomAnswer>;
+export function askFree(options?: { readonly socketPath?: string; readonly read?: () => MemoryReading }): Promise<{
+    readonly freeBytes: number | undefined;
+    readonly source: "daemon" | "formula";
+}>;
+export function askFreeSync(options?: { readonly socketPath?: string }): number | undefined;

package/src/memory-room.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// Whether this sandbox has room for more work, by one formula: the daemon's ResourceBudget
+// (_sandbox/sandbox/src/platform/resources/resource-budget.ts) judges every turn, child and heavy command with it and
+// serves the verdict on a local socket, and the scripts that run where no daemon answers (CI, a plain checkout, a
+// daemon restarting) apply the same functions to the same files. Plain JavaScript with no dependencies, so a script
+// imports it by path before any install, and `memory-room` runs it as a command.
+//
+//   limit  memory.high (where the kernel starts throttling the whole cgroup), else memory.max, else the machine's
+//          memory, never more than the machine's
+//   used   the working set (memory.current less the inactive file cache the kernel reclaims first) plus what was
+//          pushed to swap; at a root cgroup, which has no memory.current, the machine's own used memory and swap
+//   free   limit − used, and never more than the machine itself has available (MemAvailable): a sandbox on a
+//          shared machine cannot take memory the machine does not have, whatever its own limit says
+//   stall  memory PSI `full avg10`: the share of the last ten seconds in which everything waited on memory
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { request } from "node:http";
+import { pathToFileURL } from "node:url";
+
+const GIB = 1024 ** 3;
+const MIB = 1024 ** 2;
+
+// What starting one more of each workload class takes out of the sandbox (keys: WorkloadClass in workload-class.ts).
+// A reservation holds it for RESERVATION_MS, until the reading shows what the work grew into; a runner fits its memory
+// divided by an agent's cost.
+export const COST_BYTES = Object.freeze({
+    // A runtime, its MCP servers and the first commands it runs.
+    agentRuntime: GIB,
+    service: 512 * MIB,
+    panel: 512 * MIB,
+    install: GIB,
+    command: 256 * MIB,
+    // A build, test or typecheck a heavy-command rule matched; the queue's slots bound how many run at once.
+    toolchain: GIB,
+});
+
+// What one test or typecheck process holds at its peak, for the scripts that size a fan-out to the free memory
+// (_tools/scripts/verify/test-workers.mjs) and the ceiling that stops a runaway one (_tools/scripts/lib/memory-ceiling.mjs).
+export const TEST_PROCESS_BYTES = Object.freeze({
+    // One bun worker's share in a turbo fan-out: two of the four concurrent tasks are the heavy packages, so between the
+    // web worker's 3 GiB and the rest.
+    fanOutWorker: 1.5 * GIB,
+    // One bun worker on the web package at its peak (measured 2026-09-25: 2.4 to 3.2 GiB over the web suite), the size a
+    // lone `suites` run sizes to.
+    standaloneWorker: 3 * GIB,
+    // One typecheck task: most packages' tsgo or vue-tsc settle under 1 GiB, the web package's vue-tsc may take its 4 GiB
+    // heap, and at most one of those runs among the others.
+    typecheck: 2 * GIB,
+    // Past this one process is a leak, not a suite: twice the largest worker measured. On 2026-09-25 a single bun process
+    // reached 14.7 GiB resident plus 31 GiB of swap, twice in one day, and stalled every conversation on the sandbox.
+    ceiling: 6 * GIB,
+});
+
+// Work nobody is waiting on must leave room for a person's turn on top of its own cost, so it loses every tie.
+export const PERSON_RESERVE_BYTES = COST_BYTES.agentRuntime;
+// Percent of full avg10 at which the sandbox counts as grinding, whatever its byte count says.
+export const STALL_PERCENT = 20;
+export const RESERVATION_MS = 90_000;
+// Where the daemon answers `GET /room`; never the daemon's own socket, which the front relays to the internet.
+export const ROOM_SOCKET = process.env.INTENTIC_ROOM_SOCKET ?? "/run/intentic/room.sock";
+
+const CGROUP = "/sys/fs/cgroup";
+// Every file the reading is made of, for a caller that reads them itself (the daemon, asynchronously).
+export const READING_FILES = Object.freeze([
+    `${CGROUP}/memory.high`,
+    `${CGROUP}/memory.max`,
+    `${CGROUP}/memory.current`,
+    `${CGROUP}/memory.stat`,
+    `${CGROUP}/memory.swap.current`,
+    `${CGROUP}/memory.pressure`,
+    `${CGROUP}/memory.events`,
+    "/proc/meminfo",
+    "/proc/pressure/memory",
+]);
+
+const numeric = (text) => {
+    const trimmed = text?.trim() ?? "";
+    return /^\d+$/u.test(trimmed) ? Number(trimmed) : undefined;
+};
+
+// `key value` lines, and meminfo's `Key:   value kB`.
+const keyed = (text) =>
+    Object.fromEntries(
+        (text ?? "")
+            .split("\n")
+            .map((line) => line.trim().replace(/\s+kB$/u, "").split(/\s+/u))
+            .filter((parts) => parts.length === 2 && Number.isFinite(Number(parts[1])))
+            .map(([key, value]) => [key.replace(/:$/u, ""), Number(value)]),
+    );
+
+const fullAvg10 = (text) => {
+    const line = (text ?? "").split("\n").find((entry) => entry.startsWith("full"));
+    const value = line?.match(/avg10=([0-9.]+)/u)?.[1];
+    return value === undefined ? undefined : Number(value);
+};
+
+const kib = (fields, key) => (fields[key] === undefined ? undefined : fields[key] * 1024);
+
+/** The reading, from a reader that answers each of READING_FILES with its text or undefined. */
+export const readingFrom = (read) => {
+    const meminfo = keyed(read("/proc/meminfo"));
+    const machine = kib(meminfo, "MemTotal");
+    const bound = Math.min(
+        numeric(read(`${CGROUP}/memory.high`)) ?? Number.POSITIVE_INFINITY,
+        numeric(read(`${CGROUP}/memory.max`)) ?? Number.POSITIVE_INFINITY,
+        machine ?? Number.POSITIVE_INFINITY,
+    );
+    const current = numeric(read(`${CGROUP}/memory.current`));
+    let usedBytes;
+    let swapBytes = 0;
+    if (current !== undefined) {
+        // Unaccounted swap (swapaccount off) is none, never unknown: it must not blank a measurable ceiling.
+        swapBytes = numeric(read(`${CGROUP}/memory.swap.current`)) ?? 0;
+        usedBytes = Math.max(0, current - (keyed(read(`${CGROUP}/memory.stat`)).inactive_file ?? 0)) + swapBytes;
+    } else if (machine !== undefined && kib(meminfo, "MemAvailable") !== undefined) {
+        swapBytes = Math.max(0, (kib(meminfo, "SwapTotal") ?? 0) - (kib(meminfo, "SwapFree") ?? 0));
+        usedBytes = Math.max(0, machine - (kib(meminfo, "MemAvailable") ?? 0)) + swapBytes;
+    }
+    return {
+        limitBytes: Number.isFinite(bound) ? bound : undefined,
+        usedBytes,
+        swapBytes,
+        availableBytes: kib(meminfo, "MemAvailable"),
+        stallPercent: fullAvg10(read(`${CGROUP}/memory.pressure`)) ?? fullAvg10(read("/proc/pressure/memory")) ?? 0,
+        oomKills: keyed(read(`${CGROUP}/memory.events`)).oom_kill,
+    };
+};
+
+const readSync = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    } catch {
+        // allow(silent-catch): a file this kernel or platform does not have is the absent reading every caller handles
+        return undefined;
+    }
+};
+
+export const readReadingSync = () => readingFrom(readSync);
+
+const gib = (bytes) => `${(bytes / GIB).toFixed(1)} GiB`;
+
+/** What starting one more of `workload` needs free: its own cost, plus a person's turn when nobody is waiting on it. */
+export const needBytes = (workload, attended) => (COST_BYTES[workload] ?? COST_BYTES.agentRuntime) + (attended ? 0 : PERSON_RESERVE_BYTES);
+
+/**
+ * The verdict for one more of `workload`: `run`, or, when the sandbox is short, `refuse` for work a person is waiting
+ * on (they are told, and decide) and `wait` for work nobody is (it is held until there is room). `reservedBytes` is what
+ * other admissions still hold off the reading. An unmeasurable sandbox has no opinion, and runs.
+ */
+export const judge = (reading, { workload, attended, reservedBytes = 0 }) => {
+    const need = needBytes(workload, attended);
+    const { limitBytes, usedBytes, swapBytes, stallPercent, availableBytes } = reading;
+    const unreserved = freeBytesOf(reading);
+    if (limitBytes === undefined || usedBytes === undefined || unreserved === undefined) {
+        return { verdict: "run", needBytes: need, freeBytes: undefined, reservedBytes };
+    }
+    const freeBytes = Math.max(0, unreserved - reservedBytes);
+    const shortOf = (diagnosis, memory) => ({
+        verdict: attended ? "refuse" : "wait",
+        needBytes: need,
+        freeBytes,
+        reservedBytes,
+        diagnosis,
+        ...(memory === undefined ? {} : { memory }),
+    });
+    // PSI is the sandbox's own only under a cgroup; at the root it is the machine's, and still the one there is.
+    if (stallPercent >= STALL_PERCENT) {
+        return shortOf(`The sandbox is short of memory: for ${Math.round(stallPercent)}% of the last ten seconds, everything in it was waiting on memory`);
+    }
+    if (freeBytes >= need) {
+        return { verdict: "run", needBytes: need, freeBytes, reservedBytes };
+    }
+    // The machine, not the sandbox's own limit, is what ran out: saying "9 of 16 GiB used" would read as a wrong refusal.
+    if (availableBytes !== undefined && availableBytes < limitBytes - usedBytes) {
+        const held = reservedBytes > 0 ? `, and ${gib(reservedBytes)} held for work that just started` : "";
+        return shortOf(`Sandbox memory is low: the machine it runs on has ${gib(availableBytes)} available${held}`);
+    }
+    // Resident and swapped are named apart once paging starts: the limit bounds resident pages only, so their sum can
+    // exceed it, and "19.2 GiB of 16.0 GiB used" reads as a bug.
+    const used =
+        swapBytes > 0
+            ? `${gib(usedBytes - swapBytes)} resident + ${gib(swapBytes)} swapped, against ${gib(limitBytes)}`
+            : `${gib(usedBytes)} of ${gib(limitBytes)} used`;
+    // Named, or a sandbox reading 3 GiB free would seem to refuse work that needs 2.
+    const held = reservedBytes > 0 ? `, and ${gib(reservedBytes)} held for work that just started` : "";
+    return shortOf(`Sandbox memory is low: ${used}${held}`, { limitBytes, residentBytes: usedBytes - swapBytes, swapBytes });
+};
+
+/** Free memory as the formula counts it, or undefined where nothing bounds or measures it. */
+export const freeBytesOf = (reading) =>
+    reading.limitBytes === undefined || reading.usedBytes === undefined
+        ? undefined
+        : Math.max(0, Math.min(reading.limitBytes - reading.usedBytes, reading.availableBytes ?? Number.POSITIVE_INFINITY));
+
+// ---- asking the daemon, with the formula itself as the fallback ----
+
+const askSocket = (workload, waitSeconds, label, socketPath) =>
+    new Promise((resolve) => {
+        const query = new URLSearchParams({ class: workload, wait: String(waitSeconds), label });
+        const asked = request({ socketPath, path: `/room?${query}`, method: "GET", timeout: (waitSeconds + 15) * 1000 }, (response) => {
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => (body += chunk));
+            response.on("end", () => {
+                try {
+                    resolve(response.statusCode === 200 ? JSON.parse(body) : undefined);
+                } catch {
+                    // allow(silent-catch): an answer that does not parse is no answer; the formula below decides instead
+                    resolve(undefined);
+                }
+            });
+        });
+        // No socket (CI, a plain checkout), a daemon restarting, a hung answer: the formula below decides instead.
+        asked.on("error", () => resolve(undefined));
+        asked.on("timeout", () => asked.destroy());
+        asked.end();
+    });
+
+const askSnapshot = (socketPath) =>
+    new Promise((resolve) => {
+        const asked = request({ socketPath, path: "/snapshot", method: "GET", timeout: 3_000 }, (response) => {
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => (body += chunk));
+            response.on("end", () => {
+                try {
+                    resolve(response.statusCode === 200 ? JSON.parse(body) : undefined);
+                } catch {
+                    // allow(silent-catch): an answer that does not parse is no answer; the formula below decides instead
+                    resolve(undefined);
+                }
+            });
+        });
+        asked.on("error", () => resolve(undefined));
+        asked.on("timeout", () => asked.destroy());
+        asked.end();
+    });
+
+/**
+ * Free memory as the daemon counts it (the reading less what work it admitted still holds), for a caller that sizes
+ * itself rather than asking to start; where no daemon answers, the formula's own free memory.
+ */
+export const askFree = async ({ socketPath = ROOM_SOCKET, read = readReadingSync } = {}) => {
+    const snapshot = await askSnapshot(socketPath);
+    return snapshot === undefined ? { freeBytes: freeBytesOf(read()), source: "formula" } : { freeBytes: snapshot.freeBytes, source: "daemon" };
+};
+
+// The same, for a caller that cannot wait on a promise (a script's default argument): this module run as a command.
+export const askFreeSync = ({ socketPath = ROOM_SOCKET } = {}) => {
+    if (existsSync(socketPath)) {
+        const run = spawnSync(process.execPath, [import.meta.filename, "--free", "--socket", socketPath], { encoding: "utf8", timeout: 5_000 });
+        try {
+            const answer = JSON.parse(run.stdout);
+            if (typeof answer.freeBytes === "number") {
+                return answer.freeBytes;
+            }
+        } catch {
+            // allow(silent-catch): a daemon that did not answer leaves the formula to decide, below
+        }
+    }
+    return freeBytesOf(readReadingSync());
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * The daemon's verdict for one more of `workload`, waiting up to `waitSeconds` for room; where no daemon answers, the
+ * same formula over the same files, polled every `intervalMs`. Never throws: every failure is an answer of `run`.
+ */
+export const askRoom = async ({ workload = "toolchain", waitSeconds = 0, label = "command", socketPath = ROOM_SOCKET, intervalMs = 5_000, read = readReadingSync } = {}) => {
+    const answered = await askSocket(workload, waitSeconds, label, socketPath);
+    if (answered !== undefined) {
+        return { ...answered, source: "daemon" };
+    }
+    const startedAt = Date.now();
+    let verdict = judge(read(), { workload, attended: false });
+    while (verdict.verdict !== "run" && Date.now() - startedAt < waitSeconds * 1000) {
+        await sleep(intervalMs);
+        verdict = judge(read(), { workload, attended: false });
+    }
+    return { ...verdict, waitedMs: Date.now() - startedAt, source: "formula" };
+};
+
+// `memory-room --class toolchain --wait 120 --label NAME` holds a command until there is room, printing why it waited,
+// and always exits 0: a gate that cannot read the sandbox must not be the reason a command did not run. `--json` prints
+// the answer instead; `--free` prints the free memory as the daemon counts it, for a caller that sizes itself to it.
+const main = async (args) => {
+    const option = (name, fallback) => {
+        const at = args.indexOf(`--${name}`);
+        return at === -1 ? fallback : (args[at + 1] ?? fallback);
+    };
+    if (args.includes("--free")) {
+        process.stdout.write(`${JSON.stringify(await askFree({ socketPath: option("socket", ROOM_SOCKET) }))}\n`);
+        return;
+    }
+    const waitSeconds = Math.max(0, Number(option("wait", "0")) || 0);
+    const label = option("label", "command");
+    const answer = await askRoom({ workload: option("class", "toolchain"), waitSeconds, label, intervalMs: Math.max(50, Number(option("interval-ms", "5000")) || 5000) });
+    if (args.includes("--json")) {
+        process.stdout.write(`${JSON.stringify(answer)}\n`);
+        return;
+    }
+    const free = answer.freeBytes === undefined ? "?" : gib(answer.freeBytes);
+    if (answer.waitedMs > 0) {
+        process.stderr.write(
+            answer.verdict === "run"
+                ? `[memory-room] ${label}: waited ${Math.round(answer.waitedMs / 1000)}s for memory, ${free} free — starting.\n`
+                : `[memory-room] ${label}: still short of memory after ${Math.round(answer.waitedMs / 1000)}s (${free} free) — starting anyway.\n`,
+        );
+    }
+};
+
+const invokedAs = process.argv[1] === undefined ? undefined : (() => {
+    try {
+        return pathToFileURL(realpathSync(process.argv[1])).href;
+    } catch {
+        // allow(silent-catch): an argv[1] that is not a file is not this module being run as a command
+        return undefined;
+    }
+})();
+if (invokedAs === import.meta.url) {
+    await main(process.argv.slice(2)).catch((error) => process.stderr.write(`[memory-room] skipped: ${error instanceof Error ? error.message : String(error)}\n`));
+    process.exit(0);
+}