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

package/dist/tasks/heavy-tool-env.d.ts

@@ -28,19 +28,51 @@
  * |---|---|---|
  * | `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 type { HeavyToolResourcePlan } from '@cleocode/contracts';
 import type { CanonicalTool } from './tool-resolver.js';
 /**
  * Heap ceiling per node process, in MiB.
@@ -56,6 +88,57 @@ export declare const GIB_PER_WORKER = 6;
 export declare const MAX_HEAVY_WORKERS = 6;
 /** Never grant fewer than this many — one worker must always be able to run. */
 export declare const MIN_HEAVY_WORKERS = 1;
+/**
+ * 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 declare function admissionReserveBytes(totalBytes: number): number;
+/**
+ * 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 declare function admissionCapacityBytes(totalBytes?: number): number;
+/**
+ * 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 declare 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 declare const PER_RUN_SHARE_ENV = "CLEO_PER_RUN_SHARE";
+/**
+ * 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 declare function perRunBudgetShare(env: NodeJS.ProcessEnv): number;
 /**
  * Workspace packages allowed to run their test/build script concurrently.
  *
@@ -64,8 +147,94 @@ export declare const MIN_HEAVY_WORKERS = 1;
  * memory-bound box does not finish at all.
  */
 export declare 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 declare 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 declare 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 declare 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 declare const HEAVY_WORKERS_ENV = "CLEO_HEAVY_WORKERS";
+/**
+ * Explicit workspace concurrency for heavy tools (`pnpm -r` packages in flight).
+ *
+ * @task T13122
+ */
+export declare 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 declare const WORKSPACE_CONCURRENCY_VARS: readonly ["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 declare function workspaceConcurrencyNames(env: NodeJS.ProcessEnv): string[];
+/**
+ * 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 declare const MAX_SEMI_SPACE_MB = 64;
 /** Environment overlay to merge into a heavy tool's spawn env. */
 export type HeavyToolEnv = Readonly<Record<string, string>>;
+/**
+ * The overlay for one heavy or memory-bound tool spawn, with the plan behind it
+ * (T13122).
+ *
+ * `resources` is `null` for a tool that is not memory-bound, whose overlay is
+ * empty.
+ */
+export interface HeavyToolSpawnPlan {
+    /** Variables to merge over the caller's environment. */
+    readonly overlay: HeavyToolEnv;
+    /** What was chosen and why; `null` when the tool is not heavy. */
+    readonly resources: HeavyToolResourcePlan | null;
+}
 /**
  * Whether a canonical tool is heavy enough to need bounding.
  *
@@ -87,19 +256,239 @@ export type HeavyToolEnv = Readonly<Record<string, string>>;
  */
 export declare function isHeavyTool(canonical: CanonicalTool): boolean;
 /**
- * Worker count this machine can hold, given {@link GIB_PER_WORKER}.
+ * 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 declare function isMemoryBoundTool(canonical: CanonicalTool): boolean;
+/**
+ * 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 declare function heavyToolWorkers(totalRamGib?: number): number;
+export declare function heavyToolWorkers(totalRamGib?: number, env?: NodeJS.ProcessEnv): number;
 /**
- * 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 declare function defaultHeavyHeapMb(totalRamGib?: number): number;
+/**
+ * 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 declare function defaultSingleProcessHeapMb(totalRamGib?: number): number;
+/**
+ * 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 declare function heavyRunBudgetMb(totalRamGib?: number, env?: NodeJS.ProcessEnv): number;
+/**
+ * `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 declare const HEAP_FLAG_NAMES: ReadonlySet<string>;
+/**
+ * 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 declare function parseHeapFlags(nodeOptions: string | undefined): ReadonlyMap<string, string>;
+/**
+ * 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 declare function inheritedHeapMb(nodeOptions: string | undefined, totalRamMb: number): number | 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 declare function withHeapCeiling(existing: string | undefined, heapMb: number): string;
+/**
+ * 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 declare function withSemiSpaceCap(existing: string | undefined): {
+    value: string | undefined;
+    clampedFrom: number | 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 declare function boundMakeflags(raw: string | undefined, workers: number): string | 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 declare function withoutNpmEnvConfigWarnings(text: string): string;
+/**
+ * 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.
@@ -107,26 +496,72 @@ export declare function heavyToolWorkers(totalRamGib?: number): number;
  */
 export declare function mergeNodeOptions(existing: string | undefined, heapMb: number): string;
 /**
- * Build the environment overlay for a heavy tool spawn.
+ * 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);
+ * // 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 declare function planHeavyToolEnv(canonical: CanonicalTool, env?: NodeJS.ProcessEnv, totalRamGib?: number, maxWorkers?: number): HeavyToolSpawnPlan;
+/**
+ * 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('lint', process.env, 62); // → {}
+ * //   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 declare function heavyToolEnv(canonical: CanonicalTool, env?: NodeJS.ProcessEnv, totalRamGib?: number): HeavyToolEnv;
 //# sourceMappingURL=heavy-tool-env.d.ts.map

package/dist/tasks/heavy-tool-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-tool-env.d.ts","sourceRoot":"","sources":["../../src/tasks/heavy-tool-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,kFAAkF;AAClF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAc5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAE7D;AA+BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,GAAE,MAA+B,GAAG,MAAM,CAGrF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,aAAa,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,WAAW,GAAE,MAA+B,GAC3C,YAAY,CAyBd"}
+{"version":3,"file":"heavy-tool-env.d.ts","sourceRoot":"","sources":["../../src/tasks/heavy-tool-env.ts"],"names":[],"mappings":"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"}