@cleocode/core 2026.10.3 → 2026.10.5-rc.ci.672

package/dist/tasks/heavy-tool-env.js

@@ -28,18 +28,49 @@
  * |---|---|---|
  * | `NODE_OPTIONS=--max-old-space-size=N` | Heap ceiling for EVERY node process in the tree, inherited | node docs; appended, never clobbered |
  * | `VITEST_MAX_WORKERS=N` | `if (process.env.VITEST_MAX_WORKERS) resolved.maxWorkers = parseInt(...)` — overrides the resolved config, so it binds projects that set their own | read out of vitest 4.1.4 `dist/chunks/coverage.*.js` |
- * | `npm_config_workspace_concurrency=N` | Bounds `pnpm -r` fan-out across workspace packages | `npm_config_workspace_concurrency=1 pnpm config get workspace-concurrency` → `1` |
+ * | `npm_config_workspace_concurrency=N` / `pnpm_config_workspace_concurrency=N` | Bounds `pnpm -r` fan-out across workspace packages (pnpm 10 reads the first, pnpm 11+ the second) | `npm_config_workspace_concurrency=1 pnpm config get workspace-concurrency` → `1` on pnpm 10.30; `pnpm_config_…` → `1` on pnpm 12.6 (T13122) |
  *
  * Together these bound the product the semaphore could not see:
  * `packages in flight × workers per run × heap per worker`.
  *
- * Applied ONLY to `test` / `build`. Capping `lint` or `typecheck` would
- * serialise cheap single-process work for no benefit.
+ * The worker levers apply ONLY to `test` / `build`, the tools that fork.
+ * `typecheck` and `lint` are single processes, but not cheap ones: one
+ * TypeScript program on a large monorepo holds 2–5 GB (a live `tsc --noEmit`
+ * held 4.7 GB on 2026-10-03), so since T13123 they get the heap ceiling and the
+ * workspace-concurrency bound too ({@link isMemoryBoundTool}), and no worker
+ * variables, which nothing they run reads.
  *
- * A project that genuinely wants more can set any of these itself — an existing
- * value is always respected, because a deliberate setting beats our default.
+ * ## An inherited value can tighten the plan, never loosen it (T13122)
+ *
+ * The overlay is merged over the CALLER's environment: whatever the shell
+ * profile, the agent harness or a parent process exported. Until T13122 an
+ * inherited value always won, on the theory that "a deliberate setting beats our
+ * default". A shell profile is not a per-project decision: on 2026-10-03 a
+ * `~/.zprofile` export of `NODE_OPTIONS=--max-old-space-size=8192` reached a
+ * `cleo verify --evidence tool:test`, and the run got 6 workers × 8 GiB = all of
+ * a 48 GiB Mac, because the worker count was sized for a 4 GiB heap it was not
+ * getting.
+ *
+ * So the run has a heap budget — the default worker count times the default heap
+ * ({@link heavyRunBudgetMb}) — and the overlay is planned against it
+ * ({@link planHeavyToolEnv}):
+ *
+ *   - an inherited `NODE_OPTIONS` heap that fits the budget is kept, and the
+ *     worker count shrinks so `workers × heap` still fits; one above the budget
+ *     is clamped to it;
+ *   - an inherited worker count or workspace concurrency at or below the plan
+ *     is kept; one above it is clamped;
+ *   - only an explicit CLEO override asks for more: `CLEO_HEAVY_HEAP_MB`,
+ *     `CLEO_HEAVY_WORKERS`, `CLEO_HEAVY_WORKSPACE_CONCURRENCY`.
+ *
+ * A project that wants more for its own suite still sets it in its own script
+ * (`"test": "NODE_OPTIONS=… vitest run"`) or config: that runs below the
+ * overlay and is untouched by it. The plan, and every value it clamped, is
+ * reported by `cleo verify` and `cleo run`.
  *
  * @task T12096
+ * @task T13122
+ * @task T13123
  */
 import { totalmem } from 'node:os';
 /**
@@ -56,6 +87,85 @@ export const GIB_PER_WORKER = 6;
 export const MAX_HEAVY_WORKERS = 6;
 /** Never grant fewer than this many — one worker must always be able to run. */
 export const MIN_HEAVY_WORKERS = 1;
+const GIB_BYTES = 1024 ** 3;
+/**
+ * RAM the admission ledger never hands out: the OS, resident apps, VMs and
+ * agent CLIs — `max(4 GiB, 25%)`.
+ *
+ * @param totalBytes - physical RAM in bytes.
+ * @task T13133
+ */
+export function admissionReserveBytes(totalBytes) {
+    return Math.max(4 * GIB_BYTES, totalBytes * 0.25);
+}
+/**
+ * The machine-wide budget the admission ledger shares between heavy runs, in
+ * bytes (at least 1 GiB): total RAM minus {@link admissionReserveBytes}.
+ *
+ * @param totalBytes - physical RAM. @defaultValue os.totalmem()
+ *
+ * @example
+ * ```ts
+ * admissionCapacityBytes(48 * 1024 ** 3); // 36 GiB
+ * ```
+ *
+ * @task T13133
+ */
+export function admissionCapacityBytes(totalBytes = totalmem()) {
+    return Math.max(GIB_BYTES, totalBytes - admissionReserveBytes(totalBytes));
+}
+/**
+ * Share of the admission budget one heavy run plans its workers for (T13132).
+ * A whole-suite run sized to the entire budget left nothing for anyone else:
+ * on a 48 GiB Mac it planned 6 workers × 6 GiB = all 36 GiB, and 49 single-file
+ * runs queued behind it for 17 minutes. Planning for half keeps the other half
+ * open, at the cost of a slower whole-suite run.
+ */
+export const PER_RUN_BUDGET_SHARE = 0.5;
+/** Overrides the per-run share: a number in `(0, 1]` (e.g. `1` on a dedicated box). */
+export const PER_RUN_SHARE_ENV = 'CLEO_PER_RUN_SHARE';
+/**
+ * Variables a hosted CI runner sets, each with the value that marks it. A bare
+ * `CI` is not trusted: agent harnesses and devcontainers export it locally.
+ */
+const CI_RUNNER_MARKERS = [
+    ['GITHUB_ACTIONS', 'true'],
+    ['GITLAB_CI', null],
+    ['BUILDKITE', 'true'],
+    ['CIRCLECI', 'true'],
+    ['TF_BUILD', 'True'],
+];
+/**
+ * Share of the admission budget one heavy run plans for:
+ * `CLEO_PER_RUN_SHARE` when it is a number in `(0, 1]`; the whole budget on a
+ * hosted CI runner (GitHub Actions, GitLab CI, Buildkite, CircleCI, Azure
+ * Pipelines), which is single-tenant, so CI keeps its parallelism (2 workers on
+ * a 16 GiB GitHub runner, as before T13132); else {@link PER_RUN_BUDGET_SHARE}.
+ * Fixed per environment, so the worker count in the tool cache key is stable.
+ *
+ * @param env - the environment.
+ *
+ * @example
+ * ```ts
+ * perRunBudgetShare({});                          // 0.5
+ * perRunBudgetShare({ GITHUB_ACTIONS: 'true' });  // 1
+ * perRunBudgetShare({ CI: '1' });                 // 0.5 (a bare CI is not trusted)
+ * perRunBudgetShare({ CLEO_PER_RUN_SHARE: '1' }); // 1
+ * ```
+ */
+export function perRunBudgetShare(env) {
+    const raw = env[PER_RUN_SHARE_ENV]?.trim();
+    if (raw !== undefined && raw !== '') {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0 && n <= 1)
+            return n;
+    }
+    const onRunner = CI_RUNNER_MARKERS.some(([name, value]) => {
+        const v = env[name];
+        return v !== undefined && v !== '' && (value === null || v === value);
+    });
+    return onRunner ? 1 : PER_RUN_BUDGET_SHARE;
+}
 /**
  * Workspace packages allowed to run their test/build script concurrently.
  *
@@ -64,6 +174,87 @@ export const MIN_HEAVY_WORKERS = 1;
  * memory-bound box does not finish at all.
  */
 export const WORKSPACE_CONCURRENCY = 1;
+/**
+ * The default heap never drops below this, in MiB, however small the machine —
+ * one worker must be able to run a real suite.
+ *
+ * @task T13122
+ */
+export const MIN_HEAVY_HEAP_MB = 1024;
+/**
+ * Fraction of total RAM the DEFAULT heap may reach. {@link HEAVY_TOOL_HEAP_MB}
+ * on an 8 GiB laptop is half the machine; on a 4 GiB box it would be all of it,
+ * which is no ceiling at all. Machines of 8 GiB and up are unaffected.
+ *
+ * @task T13122
+ */
+export const HEAVY_HEAP_RAM_FRACTION = 0.5;
+/**
+ * Explicit heap ceiling for heavy tools, in MiB. The only way to ask for a heap
+ * above the run's budget: unlike an inherited `NODE_OPTIONS`, it is never
+ * clamped.
+ *
+ * @task T13122
+ */
+export const HEAVY_HEAP_ENV = 'CLEO_HEAVY_HEAP_MB';
+/**
+ * Explicit worker count for heavy tools. Replaces the planned count for every
+ * runner variable, even when that puts the run over its budget.
+ *
+ * @task T13122
+ */
+export const HEAVY_WORKERS_ENV = 'CLEO_HEAVY_WORKERS';
+/**
+ * Explicit workspace concurrency for heavy tools (`pnpm -r` packages in flight).
+ *
+ * @task T13122
+ */
+export const HEAVY_WORKSPACE_CONCURRENCY_ENV = 'CLEO_HEAVY_WORKSPACE_CONCURRENCY';
+/**
+ * The two spellings of pnpm's `workspace-concurrency` in the environment. pnpm
+ * 10 reads only `npm_config_workspace_concurrency`; pnpm 11+ reads only
+ * `pnpm_config_workspace_concurrency` (measured: pnpm 10.30.0 and 12.6.0 each
+ * report `undefined` for the other spelling). Setting one bounded `pnpm -r`
+ * fan-out on one pnpm major and silently nothing on the other, so the overlay
+ * sets both — for every launcher, because an `npm test` script that runs
+ * `pnpm -r` still reads them. Both are read case-insensitively, and an
+ * uppercase spelling outranks the lowercase one, so an inherited
+ * `NPM_CONFIG_WORKSPACE_CONCURRENCY` is planned and overlaid as well
+ * ({@link workspaceConcurrencyNames}).
+ *
+ * @task T13122
+ */
+export const WORKSPACE_CONCURRENCY_VARS = [
+    'npm_config_workspace_concurrency',
+    'pnpm_config_workspace_concurrency',
+];
+/**
+ * Every environment name that sets pnpm's workspace concurrency in `env`: the
+ * two canonical spellings, plus any case or dash variant of them present (pnpm
+ * reads these case-insensitively, uppercase first, and `workspace-concurrency`
+ * with a dash as readily).
+ *
+ * @param env - The caller's environment.
+ * @returns The names to plan and overlay, canonical first.
+ * @task T13122
+ */
+export function workspaceConcurrencyNames(env) {
+    const canonical = [...WORKSPACE_CONCURRENCY_VARS];
+    const wanted = new Set(canonical);
+    const variants = Object.keys(env).filter((name) => !wanted.has(name) && wanted.has(name.toLowerCase().replace(/-/g, '_')));
+    return [...canonical, ...variants.sort()];
+}
+/**
+ * V8 young-generation (semi-space) ceiling a plan allows, in MiB: Node 24's own
+ * default on a 64-bit host. `heap_size_limit` is old space plus three
+ * semi-spaces (measured on Node 24: `--max-old-space-size=4096` with
+ * `--max-semi-space-size=4096` reports 16384 MiB), so an inherited large
+ * semi-space would multiply the planned heap without touching the old-space
+ * flag; above this it is clamped.
+ *
+ * @task T13122
+ */
+export const MAX_SEMI_SPACE_MB = 64;
 /**
  * Canonical tools treated as HEAVY — the ones that fork.
  *
@@ -97,6 +288,35 @@ const HEAVY_TOOLS = new Set(['test', 'build']);
 export function isHeavyTool(canonical) {
     return HEAVY_TOOLS.has(canonical);
 }
+/**
+ * Canonical tools whose memory must be bounded: the heavy ones, plus the
+ * single-process tools that build a whole TypeScript program (T13123).
+ */
+const MEMORY_BOUND_TOOLS = new Set(['test', 'build', 'typecheck', 'lint']);
+/**
+ * Whether a canonical tool's memory is bounded: a heap ceiling and workspace
+ * concurrency in its spawn env, and a RAM-derived machine-wide slot count that
+ * shrinks under pressure.
+ *
+ * A superset of {@link isHeavyTool}. `typecheck` and `lint` were treated as
+ * cheap (`max(2, cpus/2)` slots, no ceiling) until T13123: nine concurrent
+ * `tsc` runs of 2–5 GB each on an 18-core box is most of 48 GB. `audit` and
+ * `security-scan` stay unbounded — they are network-bound and small.
+ *
+ * @param canonical - the tool in question.
+ * @returns `true` for `test`, `build`, `typecheck` and `lint`.
+ *
+ * @example
+ * ```ts
+ * isMemoryBoundTool('typecheck'); // true
+ * isMemoryBoundTool('audit');     // false
+ * ```
+ *
+ * @task T13123
+ */
+export function isMemoryBoundTool(canonical) {
+    return MEMORY_BOUND_TOOLS.has(canonical);
+}
 /**
  * Per-runner worker-count variables, keyed by the env var each runner reads.
  *
@@ -126,22 +346,369 @@ const WORKER_COUNT_VARS = [
     'PYTEST_XDIST_AUTO_NUM_WORKERS',
 ];
 /**
- * Worker count this machine can hold, given {@link GIB_PER_WORKER}.
+ * Default worker count one heavy run plans for, given {@link GIB_PER_WORKER}:
+ * {@link perRunBudgetShare} of the admission budget
+ * ({@link admissionCapacityBytes}) — half on a shared machine, so a
+ * whole-suite run never takes the budget other runs need (T13132), the whole
+ * budget on a single-tenant CI runner. Fixed per machine and environment, so
+ * the worker count — part of the tool cache key (T12989) — is stable.
+ *
+ * The planned count ({@link planHeavyToolEnv}) never exceeds this: a small
+ * inherited heap does not buy extra workers, because each worker also costs
+ * memory outside its heap.
  *
  * @param totalRamGib - total RAM in GiB; defaults to a live reading.
+ * @param env - the environment ({@link perRunBudgetShare}). @defaultValue process.env
  * @returns a value in `[MIN_HEAVY_WORKERS, MAX_HEAVY_WORKERS]`.
+ *
+ * @example
+ * ```ts
+ * heavyToolWorkers(48, {});            // 3 (half of the 36 GiB budget)
+ * heavyToolWorkers(16, {});            // 1
+ * heavyToolWorkers(16, { GITHUB_ACTIONS: 'true' }); // 2 (the whole 12 GiB budget)
+ * ```
  */
-export function heavyToolWorkers(totalRamGib = totalmem() / 1024 ** 3) {
-    const byRam = Math.floor(totalRamGib / GIB_PER_WORKER);
+export function heavyToolWorkers(totalRamGib = totalmem() / 1024 ** 3, env = process.env) {
+    const capacityGib = admissionCapacityBytes(Math.max(0, totalRamGib) * GIB_BYTES) / GIB_BYTES;
+    const byRam = Math.floor((capacityGib * perRunBudgetShare(env)) / GIB_PER_WORKER);
     return Math.min(MAX_HEAVY_WORKERS, Math.max(MIN_HEAVY_WORKERS, byRam));
 }
 /**
- * Append `--max-old-space-size` to an existing `NODE_OPTIONS`, or create it.
+ * Default heap ceiling per Node process, in MiB: {@link HEAVY_TOOL_HEAP_MB},
+ * lowered to {@link HEAVY_HEAP_RAM_FRACTION} of RAM on a machine under 8 GiB
+ * (never below {@link MIN_HEAVY_HEAP_MB}).
  *
- * Never clobbers: a project may legitimately set `--experimental-*` flags there,
- * and dropping them would break the very command we are trying to run. An
- * existing `--max-old-space-size` is left alone — an explicit choice outranks
- * our default.
+ * @param totalRamGib - total RAM in GiB; defaults to a live reading.
+ * @returns the default heap in MiB.
+ *
+ * @example
+ * ```ts
+ * defaultHeavyHeapMb(64); // → 4096
+ * defaultHeavyHeapMb(4);  // → 2048
+ * ```
+ *
+ * @task T13122
+ */
+export function defaultHeavyHeapMb(totalRamGib = totalmem() / 1024 ** 3) {
+    const byRam = Math.floor(totalRamGib * 1024 * HEAVY_HEAP_RAM_FRACTION);
+    return Math.min(HEAVY_TOOL_HEAP_MB, Math.max(MIN_HEAVY_HEAP_MB, byRam));
+}
+/**
+ * Default heap ceiling for a single-process tool (`typecheck`, `lint`), in MiB:
+ * {@link defaultHeavyHeapMb}, but never above a quarter of RAM — V8's own
+ * default old space on a machine under 16 GiB (measured 4288 MiB with no flags
+ * on a 64 GiB host, the capped default) — so the plan never RAISES a `tsc`'s
+ * ceiling on a small machine (review of #1810). Never below
+ * {@link MIN_HEAVY_HEAP_MB}.
+ *
+ * @param totalRamGib - total RAM in GiB; defaults to a live reading.
+ * @returns the default heap in MiB.
+ *
+ * @example
+ * ```ts
+ * defaultSingleProcessHeapMb(64); // → 4096
+ * defaultSingleProcessHeapMb(8);  // → 2048
+ * ```
+ *
+ * @task T13123
+ */
+export function defaultSingleProcessHeapMb(totalRamGib = totalmem() / 1024 ** 3) {
+    const quarter = Math.max(MIN_HEAVY_HEAP_MB, Math.floor((totalRamGib * 1024) / 4));
+    return Math.min(defaultHeavyHeapMb(totalRamGib), quarter);
+}
+/**
+ * Heap budget for one heavy run, in MiB: the default worker count times the
+ * default heap. `workspace concurrency × workers × heap` must fit in it.
+ *
+ * Since T13132 the worker count is half the admission budget's worth
+ * ({@link heavyToolWorkers}); an inherited heap is planned against the budget
+ * instead of multiplying it (T13122).
+ *
+ * @param totalRamGib - total RAM in GiB; defaults to a live reading.
+ * @param env - the environment ({@link perRunBudgetShare}). @defaultValue process.env
+ * @returns the budget in MiB.
+ *
+ * @example
+ * ```ts
+ * heavyRunBudgetMb(64, {}); // → 16384 (4 workers × 4096)
+ * heavyRunBudgetMb(16, {}); // → 4096  (1 worker  × 4096)
+ * ```
+ *
+ * @task T13122
+ * @task T13132
+ */
+export function heavyRunBudgetMb(totalRamGib = totalmem() / 1024 ** 3, env = process.env) {
+    return heavyToolWorkers(totalRamGib, env) * defaultHeavyHeapMb(totalRamGib);
+}
+/**
+ * `NODE_OPTIONS` flags that set a V8 heap limit. `max-old-space-size` and its
+ * percentage form decide the old-space ceiling; `max-semi-space-size` sizes the
+ * young generation, three of which count toward the limit, and is capped at
+ * {@link MAX_SEMI_SPACE_MB}.
+ *
+ * @task T12989
+ * @task T13122
+ */
+export const HEAP_FLAG_NAMES = new Set([
+    'max-old-space-size',
+    'max-old-space-size-percentage',
+    'max-semi-space-size',
+]);
+/** The two flags that set the old-space ceiling, which a plan replaces. */
+const OLD_SPACE_FLAGS = new Set([
+    'max-old-space-size',
+    'max-old-space-size-percentage',
+]);
+/** The young-generation flag, capped at {@link MAX_SEMI_SPACE_MB}. */
+const SEMI_SPACE_FLAG = new Set(['max-semi-space-size']);
+function spannedWords(text) {
+    return [...text.matchAll(/\S+/g)].map((m) => ({
+        text: m[0],
+        start: m.index,
+        end: m.index + m[0].length,
+    }));
+}
+/**
+ * Remove the heap flags named in `names` from a `NODE_OPTIONS` value, cutting
+ * their spans (and the whitespace before each) out of the original string, so
+ * every other byte — quoted paths with runs of spaces included — is kept.
+ */
+function cutHeapFlags(text, names) {
+    const words = spannedWords(text);
+    const tokens = words.map((w) => w.text);
+    let out = '';
+    let cursor = 0;
+    for (let i = 0; i < words.length; i++) {
+        const flag = heapTokenAt(tokens, i);
+        if (flag === null || !names.has(flag.name))
+            continue;
+        const first = words[i];
+        const last = words[i + flag.width - 1];
+        if (first === undefined || last === undefined)
+            continue;
+        // Drop the whitespace before the flag along with it.
+        let from = first.start;
+        while (from > cursor && /\s/.test(text[from - 1] ?? ''))
+            from--;
+        out += text.slice(cursor, from);
+        cursor = last.end;
+        i += flag.width - 1;
+    }
+    return (out + text.slice(cursor)).trim();
+}
+function heapTokenAt(tokens, i) {
+    const token = tokens[i] ?? '';
+    if (!token.startsWith('--'))
+        return null;
+    const eq = token.indexOf('=');
+    const name = (eq === -1 ? token.slice(2) : token.slice(2, eq)).replace(/_/g, '-');
+    if (!HEAP_FLAG_NAMES.has(name))
+        return null;
+    const next = tokens[i + 1];
+    if (eq === -1 && next !== undefined && /^\d+(\.\d+)?$/.test(next)) {
+        return { name, value: next, width: 2 };
+    }
+    return { name, value: eq === -1 ? '' : token.slice(eq + 1), width: 1 };
+}
+/**
+ * The V8 heap flags a `NODE_OPTIONS` value sets, by name, with the value in
+ * effect.
+ *
+ * V8 reads flags left to right and a later value replaces an earlier one, so
+ * the LAST occurrence of each flag is the effective one. Underscores in a flag
+ * name read as dashes, as they do to V8, and the space-separated spelling
+ * (`--max-old-space-size 4096`) is read too.
+ *
+ * @param nodeOptions - A `NODE_OPTIONS` value, if any.
+ * @returns flag name → effective value, in first-seen order.
+ *
+ * @task T12989
+ * @task T13122
+ */
+export function parseHeapFlags(nodeOptions) {
+    const tokens = (nodeOptions ?? '').trim().split(/\s+/).filter(Boolean);
+    const values = new Map();
+    for (let i = 0; i < tokens.length; i++) {
+        const flag = heapTokenAt(tokens, i);
+        if (flag === null)
+            continue;
+        values.set(flag.name, flag.value);
+        i += flag.width - 1;
+    }
+    return values;
+}
+/**
+ * The old-space heap ceiling a `NODE_OPTIONS` value asks for, in MiB, or
+ * `null` when it sets none (or sets one Node could not use).
+ *
+ * `--max-old-space-size-percentage` wins over `--max-old-space-size` whatever
+ * their order (measured on Node 24.21: `=10` beside `=2048` gave a 6745 MiB
+ * limit on a 64 GiB machine either way round), and resolves against total RAM.
+ *
+ * @param nodeOptions - A `NODE_OPTIONS` value, if any.
+ * @param totalRamMb - Total RAM in MiB, for the percentage form.
+ * @returns the requested heap in MiB, or `null`.
+ *
+ * @example
+ * ```ts
+ * inheritedHeapMb('--max-old-space-size=8192', 65536);          // → 8192
+ * inheritedHeapMb('--max-old-space-size-percentage=25', 65536); // → 16384
+ * inheritedHeapMb('--enable-source-maps', 65536);               // → null
+ * ```
+ *
+ * @task T13122
+ */
+export function inheritedHeapMb(nodeOptions, totalRamMb) {
+    const flags = parseHeapFlags(nodeOptions);
+    const pct = Number(flags.get('max-old-space-size-percentage') ?? Number.NaN);
+    if (Number.isFinite(pct) && pct > 0 && pct <= 100) {
+        return Math.floor((totalRamMb * pct) / 100);
+    }
+    const mb = Number(flags.get('max-old-space-size') ?? Number.NaN);
+    return Number.isFinite(mb) && mb >= 1 ? Math.floor(mb) : null;
+}
+/**
+ * Set the old-space heap ceiling in a `NODE_OPTIONS` value: every existing
+ * `--max-old-space-size` and `--max-old-space-size-percentage` is cut out and
+ * one `--max-old-space-size=<heapMb>` appended. Every other byte survives — a
+ * project may rely on `--experimental-*` or a quoted `--require` path there.
+ *
+ * Removing the percentage form is required, not tidiness: it outranks the size
+ * form whatever the order, so leaving it would silently undo the ceiling.
+ *
+ * @param existing - current `NODE_OPTIONS`, if any.
+ * @param heapMb - ceiling to apply.
+ * @returns the rewritten value.
+ *
+ * @example
+ * ```ts
+ * withHeapCeiling('--enable-source-maps --max-old-space-size=8192', 4096);
+ * // → '--enable-source-maps --max-old-space-size=4096'
+ * ```
+ *
+ * @task T13122
+ */
+export function withHeapCeiling(existing, heapMb) {
+    const rest = cutHeapFlags(existing ?? '', OLD_SPACE_FLAGS);
+    const flag = `--max-old-space-size=${heapMb}`;
+    return rest.length > 0 ? `${rest} ${flag}` : flag;
+}
+/**
+ * Cap the semi-space (young generation) flag of a `NODE_OPTIONS` value at
+ * {@link MAX_SEMI_SPACE_MB}: a larger `--max-semi-space-size` is cut out and the
+ * cap appended. A value at or under the cap is left alone.
+ *
+ * @param existing - `NODE_OPTIONS`, if any.
+ * @returns The value to use, and the inherited semi-space it clamped (or `null`).
+ *
+ * @example
+ * ```ts
+ * withSemiSpaceCap('--max-semi-space-size=4096'); // → { value: '--max-semi-space-size=64', clampedFrom: 4096 }
+ * ```
+ *
+ * @task T13122
+ */
+export function withSemiSpaceCap(existing) {
+    const raw = parseHeapFlags(existing).get('max-semi-space-size');
+    const semi = Number(raw ?? Number.NaN);
+    if (raw === undefined || (Number.isFinite(semi) && semi <= MAX_SEMI_SPACE_MB)) {
+        return { value: existing, clampedFrom: null };
+    }
+    const rest = cutHeapFlags(existing ?? '', SEMI_SPACE_FLAG);
+    const flag = `--max-semi-space-size=${MAX_SEMI_SPACE_MB}`;
+    return {
+        value: rest.length > 0 ? `${rest} ${flag}` : flag,
+        clampedFrom: Number.isFinite(semi) ? semi : null,
+    };
+}
+/**
+ * Bound an inherited `MAKEFLAGS` to `workers` jobs.
+ *
+ * Absent: `-j<workers>` (GNU make sizes a bare `-j` off nproc). Carrying a
+ * jobserver (`--jobserver-auth=` / `--jobserver-fds=`): kept, since inside a
+ * `make` recipe the parent's jobserver already bounds the jobs. Otherwise any
+ * `-j`, `-jN`, `--jobs[=N]`, a short cluster ending in j (`-sj18`) or make's
+ * dash-less first word (`j18`) above `workers` (a bare one is unlimited) is
+ * replaced by `-j<workers>`, keeping every other flag — a profile-wide
+ * `export MAKEFLAGS=-j18` no longer outruns the plan.
+ *
+ * @param raw - The inherited `MAKEFLAGS`.
+ * @param workers - The planned worker count.
+ * @returns The value to set, or `null` to keep the inherited one.
+ * @task T13122
+ */
+export function boundMakeflags(raw, workers) {
+    if (raw === undefined || raw.trim() === '')
+        return `-j${workers}`;
+    const words = raw.trim().split(/\s+/);
+    if (words.some((w) => /^--jobserver-(auth|fds)=/.test(w)))
+        return null;
+    const kept = [];
+    let over = false;
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i] ?? '';
+        const long = /^--jobs(?:=(\d*))?$/.exec(word);
+        // A short-flag cluster ending in j (`-j18`, `-sj18`, `-kj`), or make's own
+        // dash-less letter form as the first word (`j18`, `kj`). Only make's
+        // argument-less short flags may precede the j: in `-Ij18` the `j18` is
+        // -I's directory, and splitting it would hand -I the `-j` (review of #1824).
+        const short = long === null ? /^(-?)([BbdehikLnpqrRsStvw]*)j(\d*)$/.exec(word) : null;
+        const isShort = short !== null && (short[1] === '-' || i === 0);
+        if (long === null && !isShort) {
+            kept.push(word);
+            continue;
+        }
+        let count = long !== null ? (long[1] ?? '') : (short?.[3] ?? '');
+        const takesNext = long !== null ? long[1] === undefined : count === '';
+        const next = words[i + 1];
+        if (count === '' && takesNext && next !== undefined && /^\d+$/.test(next)) {
+            count = next;
+            i++;
+        }
+        // The cluster's other letters (`s`, `k`) are flags of their own: keep them.
+        if (isShort && short?.[2])
+            kept.push(`-${short[2]}`);
+        if (count === '' || Number(count) > workers)
+            over = true;
+        else
+            kept.push(`-j${count}`);
+    }
+    return over ? [...kept.filter((w) => !/^-j\d+$/.test(w)), `-j${workers}`].join(' ') : null;
+}
+/**
+ * Remove npm's `Unknown env config` warnings from captured output.
+ *
+ * npm warns once per run for every `npm_config_*` variable it does not know,
+ * including `npm_config_workspace_concurrency`, which the overlay sets for the
+ * `pnpm -r` an `npm test` script may run. The warning would otherwise sit in
+ * the stderr tail CLEO quotes when a tool fails and push the real error out of
+ * it; the variable itself stays, because dropping it for npm unbounded those
+ * child `pnpm -r` runs (review of #1808).
+ *
+ * @param text - Captured stderr.
+ * @returns The text without those warning lines.
+ * @task T13122
+ */
+export function withoutNpmEnvConfigWarnings(text) {
+    if (!text.includes('Unknown env config'))
+        return text;
+    return text
+        .split('\n')
+        .filter(
+    // A coloured npm (FORCE_COLOR, color=always) prefixes ANSI codes.
+    (line) => !/^npm (warn|WARN) Unknown env config\b/.test(line.replace(ANSI_SGR, '')))
+        .join('\n');
+}
+/** ANSI select-graphic-rendition escapes (colours), stripped before matching npm's warning. */
+const ANSI_SGR = /\u001b\[[0-9;]*m/g;
+/**
+ * Append `--max-old-space-size` to an existing `NODE_OPTIONS`, or create it,
+ * leaving an existing `--max-old-space-size` alone.
+ *
+ * @deprecated Since T13122 the heavy-tool overlay plans the heap against the
+ *   run's budget instead of letting any inherited value win; use
+ *   {@link planHeavyToolEnv} (or {@link withHeapCeiling} to set a ceiling).
+ *   Kept for SDK consumers.
  *
  * @param existing - current `NODE_OPTIONS`, if any.
  * @param heapMb - ceiling to apply.
@@ -154,50 +721,259 @@ export function mergeNodeOptions(existing, heapMb) {
     const flag = `--max-old-space-size=${heapMb}`;
     return current.length > 0 ? `${current} ${flag}` : flag;
 }
+/** A strictly positive base-10 integer, or `null` (`'50%'`, `'0'`, `'-1'`, `'4x'` are all `null`). */
+function positiveInt(raw) {
+    const text = (raw ?? '').trim();
+    if (!/^\d+$/.test(text))
+        return null;
+    const n = Number.parseInt(text, 10);
+    return n > 0 ? n : null;
+}
+/** An explicit `CLEO_HEAVY_*` override, or `null`; an unusable value is noted and ignored. */
+function readOverride(env, name, ignored) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    const n = positiveInt(raw);
+    if (n === null)
+        ignored.push(`${name}=${JSON.stringify(raw)} (not a positive integer)`);
+    return n;
+}
+/** The heap flags of a `NODE_OPTIONS` value as one readable string, e.g. `--max-old-space-size=8192`. */
+function heapFlagsText(nodeOptions) {
+    return [...parseHeapFlags(nodeOptions)]
+        .filter(([name]) => OLD_SPACE_FLAGS.has(name))
+        .map(([name, value]) => `--${name}=${value}`)
+        .join(' ');
+}
+function chooseHeap(env, override, maxHeapMb, totalRamMb, defaultHeapMb) {
+    const inherited = inheritedHeapMb(env.NODE_OPTIONS, totalRamMb);
+    if (override !== null)
+        return { heapMb: override, source: 'override', inherited };
+    // The default heap never shrinks to fit an explicit workspace concurrency: a
+    // run asked for that way is reported over budget instead (`overBudget`).
+    if (inherited === null)
+        return { heapMb: defaultHeapMb, source: 'default', inherited };
+    if (inherited <= maxHeapMb)
+        return { heapMb: inherited, source: 'inherited', inherited };
+    return { heapMb: maxHeapMb, source: 'clamped', inherited };
+}
+/** One worker-count variable: keep an inherited value within the plan, else overlay the plan. */
+function planCount(name, raw, planned, forced, overlay, clamped, kept) {
+    const inherited = positiveInt(raw);
+    if (!forced && inherited !== null && inherited <= planned) {
+        kept.push(`${name}=${inherited}`);
+        return;
+    }
+    overlay[name] = String(planned);
+    if (!forced && raw !== undefined && raw !== '') {
+        clamped.push({ name, from: raw, to: String(planned) });
+    }
+}
+/** A tool that runs as one process: nothing to size. */
+const SINGLE_PROCESS = {
+    workers: 1,
+    source: 'plan',
+    reason: 'one process, no worker pool',
+};
 /**
- * Build the environment overlay for a heavy tool spawn.
+ * The worker count of a forking tool — `CLEO_HEAVY_WORKERS`, else as many as
+ * fit (`fit`, the budget over packages × heap), never above the default — written
+ * to every runner variable and to `MAKEFLAGS`.
+ */
+function planWorkers(env, fit, defaultWorkers, ledger) {
+    const override = readOverride(env, HEAVY_WORKERS_ENV, ledger.ignored);
+    const workers = override ?? Math.max(MIN_HEAVY_WORKERS, Math.min(defaultWorkers, Math.floor(fit)));
+    for (const key of WORKER_COUNT_VARS) {
+        planCount(key, env[key], workers, override !== null, ledger.overlay, ledger.clamped, ledger.kept);
+    }
+    // GNU make sizes `-j` off nproc when told `-j` with no argument; an explicit
+    // job count bounds a Makefile-driven test/build target too.
+    const makeflags = boundMakeflags(env.MAKEFLAGS, workers);
+    if (makeflags !== null) {
+        ledger.overlay.MAKEFLAGS = makeflags;
+        if (env.MAKEFLAGS && env.MAKEFLAGS.trim() !== '' && override === null) {
+            ledger.clamped.push({ name: 'MAKEFLAGS', from: env.MAKEFLAGS, to: makeflags });
+        }
+    }
+    if (override !== null)
+        return { workers, source: 'override', reason: HEAVY_WORKERS_ENV };
+    return {
+        workers,
+        source: 'plan',
+        reason: workers < defaultWorkers
+            ? `fewer than the default ${defaultWorkers} so the run fits its budget`
+            : 'default for this RAM',
+    };
+}
+function heapReason(choice) {
+    switch (choice.source) {
+        case 'override':
+            return HEAVY_HEAP_ENV;
+        case 'inherited':
+            return 'inherited NODE_OPTIONS';
+        case 'clamped':
+            return `inherited NODE_OPTIONS asked for ${choice.inherited} MiB, more than the budget allows`;
+        default:
+            return 'CLEO default';
+    }
+}
+/**
+ * Plan a heavy or memory-bound tool spawn: the environment overlay, and the
+ * resource plan behind it (T13122, T13123).
+ *
+ * The heap is chosen first — `CLEO_HEAVY_HEAP_MB`, else the inherited
+ * `NODE_OPTIONS` heap when it fits the budget (clamped to it otherwise), else
+ * {@link defaultHeavyHeapMb}. The worker count then derives from the heap
+ * actually in effect, `⌊budget / (packages × heap)⌋`, never above
+ * {@link heavyToolWorkers}, so `packages × workers × heap` stays within
+ * {@link heavyRunBudgetMb}. Inherited worker counts and workspace concurrency
+ * are kept at or below the plan and clamped above it; `CLEO_HEAVY_WORKERS` and
+ * `CLEO_HEAVY_WORKSPACE_CONCURRENCY` override.
  *
- * Returns an empty object for non-heavy tools, so the caller can merge
- * unconditionally.
+ * A single-process memory-bound tool (`typecheck`, `lint`) gets the same heap
+ * ceiling and workspace concurrency, and no worker variables: its plan is one
+ * process (T13123).
  *
  * @param canonical - the canonical tool about to be spawned.
  * @param env - the environment the child would otherwise inherit.
  * @param totalRamGib - total RAM in GiB; injectable for deterministic tests.
- * @returns variables to overlay; existing deliberate values are preserved.
+ * @param maxWorkers - at most this many workers (a run that names its test
+ *   files needs no more than one per file, T13132). @defaultValue no limit
+ * @returns the overlay and plan; an empty overlay and `null` plan for a tool
+ *          that is not memory-bound (`audit`, `security-scan`).
  *
  * @example
  * ```ts
- * const overlay = heavyToolEnv('test', process.env, 62);
- * // { NODE_OPTIONS: '--max-old-space-size=4096',
- * //   VITEST_MAX_WORKERS: '6',
- * //   npm_config_workspace_concurrency: '1' }
- * heavyToolEnv('lint', process.env, 62); // → {}
+ * // A shell profile exported an 8 GiB heap on a 64 GiB machine:
+ * const { overlay, resources } = planHeavyToolEnv(
+ *   'test', { NODE_OPTIONS: '--max-old-space-size=8192' }, 64);
+ * overlay.VITEST_MAX_WORKERS; // → '2' (2 × 8192 = the 16384 MiB budget)
+ * resources?.heapSource;      // → 'inherited'
  * ```
  *
  * @task T12096
+ * @task T13122
+ * @task T13123
+ * @task T13132
  */
-export function heavyToolEnv(canonical, env = process.env, totalRamGib = totalmem() / 1024 ** 3) {
-    if (!isHeavyTool(canonical))
-        return {};
-    const overlay = {
-        NODE_OPTIONS: mergeNodeOptions(env.NODE_OPTIONS, HEAVY_TOOL_HEAP_MB),
-    };
-    // Respect a deliberate setting; supply one otherwise. An existing value
-    // always wins — a project that asked for more has outranked our default
-    // since T12096, and that contract is unchanged.
-    const workers = String(heavyToolWorkers(totalRamGib));
-    for (const key of WORKER_COUNT_VARS) {
-        if (!env[key])
-            overlay[key] = workers;
+export function planHeavyToolEnv(canonical, env = process.env, totalRamGib = totalmem() / 1024 ** 3, maxWorkers) {
+    if (!isMemoryBoundTool(canonical))
+        return { overlay: {}, resources: null };
+    const totalRamMb = Math.floor(totalRamGib * 1024);
+    const defaultWorkers = Math.min(heavyToolWorkers(totalRamGib, env), Math.max(MIN_HEAVY_WORKERS, Math.floor(maxWorkers ?? Number.POSITIVE_INFINITY)));
+    // A single process starts from Node's own default ceiling on its machine; a
+    // forking tool from the heavy default. Both share the heavy run's budget.
+    const defaultHeapMb = isHeavyTool(canonical)
+        ? defaultHeavyHeapMb(totalRamGib)
+        : defaultSingleProcessHeapMb(totalRamGib);
+    const budgetMb = defaultWorkers * defaultHeavyHeapMb(totalRamGib);
+    const overlay = {};
+    const clamped = [];
+    const kept = [];
+    const ignored = [];
+    // Packages in flight first: the heap ceiling an inherited value may keep is
+    // the budget shared between them.
+    const packagesOverride = readOverride(env, HEAVY_WORKSPACE_CONCURRENCY_ENV, ignored);
+    const packages = packagesOverride ?? WORKSPACE_CONCURRENCY;
+    const packageNames = workspaceConcurrencyNames(env);
+    for (const name of packageNames) {
+        planCount(name, env[name], packages, packagesOverride !== null, overlay, clamped, kept);
     }
-    if (!env.npm_config_workspace_concurrency) {
-        overlay.npm_config_workspace_concurrency = String(WORKSPACE_CONCURRENCY);
+    // What the child gets: the overlay's value, or the inherited one it kept —
+    // the largest across every spelling, since which one pnpm reads depends on
+    // its version and the case.
+    const packagesInFlight = Math.max(...packageNames.map((name) => positiveInt(overlay[name] ?? env[name]) ?? packages));
+    const heap = chooseHeap(env, readOverride(env, HEAVY_HEAP_ENV, ignored), Math.max(1, Math.floor(budgetMb / packagesInFlight)), totalRamMb, defaultHeapMb);
+    // Young generation first: three semi-spaces count toward the heap limit.
+    const semi = withSemiSpaceCap(env.NODE_OPTIONS);
+    if (semi.clampedFrom !== null) {
+        clamped.push({
+            name: 'NODE_OPTIONS',
+            from: `--max-semi-space-size=${semi.clampedFrom}`,
+            to: `--max-semi-space-size=${MAX_SEMI_SPACE_MB}`,
+        });
     }
-    // GNU make sizes `-j` off nproc when told `-j` with no argument; an explicit
-    // job count here bounds a Makefile-driven test/build target too.
-    if (!env.MAKEFLAGS) {
-        overlay.MAKEFLAGS = `-j${workers}`;
+    overlay.NODE_OPTIONS = withHeapCeiling(semi.value, heap.heapMb);
+    if (heap.source === 'clamped') {
+        clamped.push({
+            name: 'NODE_OPTIONS',
+            from: heapFlagsText(env.NODE_OPTIONS),
+            to: `--max-old-space-size=${heap.heapMb}`,
+        });
+    }
+    // A single-process tool (typecheck, lint) has no worker pool to size.
+    const pool = isHeavyTool(canonical)
+        ? planWorkers(env, budgetMb / (packagesInFlight * heap.heapMb), defaultWorkers, {
+            overlay,
+            clamped,
+            kept,
+            ignored,
+        })
+        : SINGLE_PROCESS;
+    const { workers } = pool;
+    const product = packagesInFlight * workers * heap.heapMb;
+    const overBudget = product > budgetMb;
+    const parts = [
+        `heap ${heap.heapMb} MiB (${heapReason(heap)}) × ${workers} worker(s) (${pool.reason}) × ` +
+            `${packagesInFlight} workspace package(s) at once = ${product} MiB of a ${budgetMb} MiB budget ` +
+            `(${Math.round(totalRamMb / 1024)} GiB RAM)`,
+    ];
+    if (clamped.length > 0) {
+        parts.push(`clamped ${clamped.map((c) => `${c.name} ${c.from} → ${c.to}`).join(', ')}; ` +
+            `set ${HEAVY_HEAP_ENV}, ${HEAVY_WORKERS_ENV} or ${HEAVY_WORKSPACE_CONCURRENCY_ENV} to ask for more`);
     }
-    return overlay;
+    if (overBudget)
+        parts.push('OVER budget by an explicit CLEO_HEAVY_* override');
+    if (ignored.length > 0)
+        parts.push(`ignored ${ignored.join(', ')}`);
+    return {
+        overlay,
+        resources: {
+            heapMb: heap.heapMb,
+            heapSource: heap.source,
+            inheritedHeapMb: heap.inherited,
+            workers,
+            workersSource: pool.source,
+            workspaceConcurrency: packagesInFlight,
+            budgetMb,
+            totalRamMb,
+            clamped,
+            kept,
+            overBudget,
+            summary: parts.join('; '),
+        },
+    };
+}
+/**
+ * Build the environment overlay for a heavy or memory-bound tool spawn: the
+ * `overlay` of {@link planHeavyToolEnv}.
+ *
+ * Returns an empty object for a tool that is not memory-bound, so the caller
+ * can merge unconditionally.
+ *
+ * @param canonical - the canonical tool about to be spawned.
+ * @param env - the environment the child would otherwise inherit.
+ * @param totalRamGib - total RAM in GiB; injectable for deterministic tests.
+ * @returns variables to overlay; inherited values within the plan are kept.
+ *
+ * @example
+ * ```ts
+ * const overlay = heavyToolEnv('test', {}, 62);
+ * // { NODE_OPTIONS: '--max-old-space-size=4096',
+ * //   VITEST_MAX_WORKERS: '6',
+ * //   npm_config_workspace_concurrency: '1', … }
+ * heavyToolEnv('typecheck', {}, 62);
+ * // { NODE_OPTIONS: '--max-old-space-size=4096',
+ * //   npm_config_workspace_concurrency: '1', pnpm_config_workspace_concurrency: '1' }
+ * heavyToolEnv('audit', process.env, 62); // → {}
+ * ```
+ *
+ * @task T12096
+ * @task T13122
+ * @task T13123
+ */
+export function heavyToolEnv(canonical, env = process.env, totalRamGib = totalmem() / 1024 ** 3) {
+    return planHeavyToolEnv(canonical, env, totalRamGib).overlay;
 }
 //# sourceMappingURL=heavy-tool-env.js.map