@cleocode/core 2026.10.25 → 2026.10.26

package/dist/resources/admission-ledger.js

@@ -74,12 +74,12 @@ import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getLogger } from '../logger.js';
 import { getCleoHome } from '../paths.js';
-import { admissionCapacityBytes, admissionReserveBytes, defaultSingleProcessHeapMb, GIB_PER_WORKER, HEAVY_TOOL_HEAP_MB, heavyToolWorkers, isHeavyTool, isMemoryBoundTool, planHeavyToolEnv, vitestWorkerCeiling, } from '../tasks/heavy-tool-env.js';
-import { gitHookPath, HOOK_PEAK_MARGIN, hookFootprintKey, readHookPeak } from './hook-footprint.js';
+import { admissionCapacityBytes, admissionReserveBytes, defaultSingleProcessHeapMb, GIB_PER_WORKER, HEAVY_TOOL_HEAP_MB, heavyToolWorkers, isHeavyTool, isMemoryBoundTool, planHeavyToolEnv, projectSettingOverrides, vitestWorkerCeiling, } from '../tasks/heavy-tool-env.js';
+import { gitHookPath, HOOK_MIN_RUNS, HOOK_PEAK_MARGIN, hookFootprintKey, readHookPeak, scriptFootprint, } from './hook-footprint.js';
 import { pressureScore, ResourceMonitor } from './monitor.js';
 import { checkMemoryGate, MEMORY_GATE_RETRY_AFTER_MS, } from './pressure-gate.js';
 import { processAncestors, processGroupOf, processGroupsOf } from './run-admission.js';
-import { canonicalForClass, gitHookFor, lightCommandReason, namedTestFileCount, runFootprint, } from './run-class.js';
+import { canonicalForClass, gitHookFor, heavyScriptReason, lightCommandReason, namedTestFileCount, nodeScriptOf, runFootprint, } from './run-class.js';
 import { ownProcessStartedAt, systemPidProbe } from './slot-holder.js';
 import { followToolGroups, isProbeableId } from './tool-groups.js';
 import { memoryPressureCause, TOP_MEMORY_COUNT, TOP_MEMORY_FAILED_REUSE_MS, TOP_MEMORY_REUSE_MS, topMemoryConsumers, } from './top-memory.js';
@@ -244,7 +244,10 @@ function scopedBuildWorkers(totalRamGib, env) {
  * A formatter on named files is charged {@link LIGHT_FOOTPRINT_BYTES} with no
  * heap plan. A single Node linter on files, or a one-project `tsc -p`, is
  * charged one process. A scoped build of a command that runs no heavy tool
- * (`node x.mjs`, a hook-free `git push`) is charged light (T13452). Anything
+ * (`node x.mjs`, a hook-free `git push`) is charged light (T13452), unless
+ * the script hosts a heavy tool: its path names a heavy job or it loads a
+ * compiler or test runner (T14050). Such a script, like a hook, is charged its
+ * measured peak once measured, and the class plan until then. Anything
  * else gets the class's heavy-run plan, with a named-file test run capped at
  * one worker per file (T13132) and a scoped build at half a heavy run's
  * workers (T13759). A test run is also capped at the project's own vitest
@@ -259,6 +262,8 @@ function scopedBuildWorkers(totalRamGib, env) {
  * @param hookPeak - a hook's measured peak. @defaultValue reads the hook footprint store
  * @param cwd - the directory the command runs in, read for the project's vitest
  *   limit (T14033). @defaultValue process.cwd()
+ * @param scriptPeak - a `node` script's key, loaded heavy tool and measured
+ *   peak (T14050). @defaultValue reads the script and the footprint store
  *
  * @example
  * ```ts
@@ -269,18 +274,37 @@ export function planRunFootprint(cls, argv, env = process.env, totalRamGib = tot
 hookPeak = (hook, globals) => {
     const key = hookFootprintKey(process.cwd(), hook, globals, env); // CWD-OK: as above
     return key === null ? null : { key, peakBytes: readHookPeak(key, admissionDir()) };
-}, cwd = process.cwd()) {
+}, cwd = process.cwd(), // CWD-OK: cleo run runs the command in its own cwd
+scriptPeak = (script) => {
+    const found = scriptFootprint(cwd, script);
+    return found === null ? null : { ...found, peakBytes: readHookPeak(found.key, admissionDir()) };
+}) {
     let scope = cls === 'full-build' ? null : runFootprint(argv);
+    const sized = cls === 'scoped-build' && scope?.size === 'class';
+    // T14050: a node script that hosts a heavy tool (its path names one, or it
+    // loads a compiler or test runner in-process) is never light.
+    const script = sized ? nodeScriptOf(argv) : null;
+    const scripted = script !== null ? scriptPeak(script) : null;
+    const host = script === null
+        ? null
+        : (heavyScriptReason(script) ??
+            (scripted?.heavyTool ? `it loads ${scripted.heavyTool}` : null));
     // T13452: a scoped build of a command that runs no heavy tool (`node x.mjs`,
     // `ls`) is charged light. An explicit test run keeps its class plan.
-    const light = cls === 'scoped-build' && scope?.size === 'class' ? lightCommandReason(argv) : null;
+    const light = sized && host === null ? lightCommandReason(argv) : null;
     if (light !== null)
         scope = { size: 'light', reason: light };
+    else if (host !== null)
+        scope = { size: 'class', reason: `node ${script} hosts a heavy tool (${host})` };
     // T13452: a hooked git push/commit keeps the class plan, because whatever
     // the hook runs (tests, a build) rides this admission.
     const probe = scope?.size === 'light' ? gitHookFor(argv) : null;
     const hook = probe?.hooks.find((h) => hookInstalled(h, probe.globals));
-    const measured = hook !== undefined && probe !== null ? hookPeak(hook, probe.globals) : null;
+    const measured = hook !== undefined && probe !== null
+        ? hookPeak(hook, probe.globals)
+        : host !== null
+            ? scripted
+            : null;
     if (hook !== undefined) {
         scope = { size: 'class', reason: `runs the ${hook} hook` };
     }
@@ -297,7 +321,7 @@ hookPeak = (hook, globals) => {
         const { overlay, resources } = planHeavyToolEnv('typecheck', env, totalRamGib);
         return {
             overlay,
-            resources,
+            resources: withProjectOverrides(resources, overlay, cwd),
             ...(resources !== null ? { footprintBytes: planFootprintBytes(resources) } : {}),
             footprintReason: scope.reason,
             namedFiles: null,
@@ -326,15 +350,39 @@ hookPeak = (hook, globals) => {
         : planned;
     return {
         overlay,
-        resources,
+        resources: withProjectOverrides(resources, overlay, cwd),
         ...(charged !== undefined ? { footprintBytes: charged } : {}),
         footprintReason: peak !== null && charged !== planned
             ? `${reason}, measured peak ${gib(peak)} + ${Math.round((HOOK_PEAK_MARGIN - 1) * 100)}%`
-            : reason,
+            : measured !== null && peak === null && host !== null
+                ? `${reason}; charged the plan until ${HOOK_MIN_RUNS} runs are measured`
+                : reason,
         namedFiles,
         ...(measured !== null ? { hookKey: measured.key } : {}),
     };
 }
+/**
+ * The charge `cleo run` prints before admission (T14050): the bytes asked of
+ * the ledger and how they were derived.
+ *
+ * @param cls - the resolved class.
+ * @param plan - from {@link planRunFootprint}.
+ *
+ * @example
+ * ```ts
+ * describeCharge('scoped-build', plan); // '1.0 GiB: biome check on 2 named paths'
+ * ```
+ */
+export function describeCharge(cls, plan) {
+    return `${gib(plan.footprintBytes ?? footprintForClass(cls))}: ${plan.footprintReason}`;
+}
+/** A plan with the project-file settings its overlay overrides (T14038). */
+function withProjectOverrides(resources, overlay, cwd) {
+    if (resources === null)
+        return null;
+    const projectOverrides = projectSettingOverrides(cwd, overlay);
+    return projectOverrides.length > 0 ? { ...resources, projectOverrides } : resources;
+}
 /** Governor classes whose admission is the ledger's. */
 export const LEDGER_CLASSES = new Set([
     'test-run',
@@ -643,49 +691,80 @@ async function withLedger(dir, fn, signal, strictRead = false) {
         }
     }
 }
-// ---------------------------------------------------------------------------
-// Liveness
-// ---------------------------------------------------------------------------
 /**
- * Whether an entry's holder is still there.
+ * Whether an entry's holder is still there, and why.
  *
  * - A pid that is provably gone (or recycled: alive with another start time,
- *   once the heartbeat is stale) is dead as soon as every tool group it
- *   started is gone too; a detached tool outlives a SIGKILLed cleo.
+ *   once the heartbeat is stale) is dead as soon as its recorded child and
+ *   every tool group it started are gone too; a detached tool outlives a
+ *   SIGKILLed cleo, and so does a foreground child (T13046).
  * - A fresh heartbeat, or a live pid whose start time matches the recorded
  *   one, is alive.
  * - A holder that cannot be identified (the probe fails, or no start time was
  *   recorded or can be read) is alive until its heartbeat is
- *   {@link LEDGER_ORPHAN_MS} old, and so is a gone holder whose tool group id
- *   still runs (a group id carries no start time, so it may be recycled).
- *   Past that bound both are dead: nothing holds the budget forever.
+ *   {@link LEDGER_ORPHAN_MS} old, and so is a gone holder whose child or tool
+ *   group id still runs (a group id carries no start time, so it may be
+ *   recycled). Past that bound both are dead: nothing holds the budget forever.
  * - An entry of another host is judged by its heartbeat alone.
  *
  * @param entry - the ledger entry.
  * @param nowMs - the clock.
  * @param probe - pid probe (tests inject one).
  */
-export function entryLiveness(entry, nowMs, probe = systemPidProbe) {
+export function entryVerdict(entry, nowMs, probe = systemPidProbe) {
+    const alive = (reason) => ({ state: 'alive', reason });
+    const dead = (reason) => ({ state: 'dead', reason });
     const age = nowMs - entry.heartbeatAtMs;
-    if (entry.host !== hostname())
-        return age < LEDGER_HEARTBEAT_STALE_MS ? 'alive' : 'dead';
+    if (entry.host !== hostname()) {
+        return age < LEDGER_HEARTBEAT_STALE_MS
+            ? alive(`other-host:${entry.host}`)
+            : dead(`other-host-stale:${entry.host}`);
+    }
     const orphaned = age >= LEDGER_ORPHAN_MS;
-    const goneUnlessGroups = () => orphaned || entry.toolGroups.every((g) => isProbeableId(g) && probe.groupLiveness(g) === 'gone')
-        ? 'dead'
-        : 'alive';
+    /** What the holder left running: its child, then its tool groups. */
+    const survivor = () => {
+        const child = entry.child;
+        if (child !== undefined && isProbeableId(child.pid) && probe.liveness(child.pid) !== 'gone') {
+            const started = child.startedAt === null ? null : probe.startedAt(child.pid);
+            if (started === null || started === child.startedAt)
+                return `child-alive:${child.pid}`;
+        }
+        for (const g of entry.toolGroups) {
+            const state = isProbeableId(g) ? probe.groupLiveness(g) : 'unknown';
+            if (state !== 'gone')
+                return `group-${state}:${g}`;
+        }
+        return null;
+    };
+    const goneUnlessSurvivor = (reason) => {
+        if (orphaned)
+            return dead('orphaned');
+        const left = survivor();
+        return left === null ? dead(reason) : alive(left);
+    };
     const pid = probe.liveness(entry.pid);
     if (pid === 'gone')
-        return goneUnlessGroups();
+        return goneUnlessSurvivor('pid-gone');
     if (age < LEDGER_HEARTBEAT_STALE_MS)
-        return 'alive';
+        return alive(pid === 'alive' ? 'pid-alive' : 'heartbeat-fresh');
     if (pid === 'alive' && entry.startedAt !== null) {
         const startedAt = probe.startedAt(entry.pid);
         if (startedAt === entry.startedAt)
-            return 'alive';
+            return alive('pid-alive');
         if (startedAt !== null)
-            return goneUnlessGroups(); // a recycled pid
+            return goneUnlessSurvivor('pid-recycled');
     }
-    return orphaned ? 'dead' : 'alive';
+    return orphaned ? dead('orphaned') : alive('unidentifiable');
+}
+/**
+ * Whether an entry's holder is still there: {@link entryVerdict}'s state.
+ *
+ * @param entry - the ledger entry.
+ * @param nowMs - the clock.
+ * @param probe - pid probe (tests inject one).
+ */
+export function entryLiveness(entry, nowMs, probe = systemPidProbe) {
+    return entryVerdict(entry, nowMs, probe).state;
 }
 /**
  * The budget an entry of an unknown format is charged: its numeric
@@ -1208,15 +1287,26 @@ export function describeScope(e) {
     return parts.length > 0 ? ` [${parts.join(', ')}]` : '';
 }
 /**
- * One line per admitted run: label, scope and task, pid, command, directory and age.
+ * One line per admitted run: label, scope and task, pid and host, command,
+ * directory, charge and age, then its heartbeat age, child, tool groups and
+ * liveness verdict with the reason (T14066), so a waiter can tell a stale
+ * holder from a real one.
  *
  * @param entries - the ledger.
  * @param nowMs - the clock.
+ * @param probe - pid probe for the verdict (tests inject one).
  */
-export function describeHolders(entries, nowMs) {
+export function describeHolders(entries, nowMs, probe = systemPidProbe) {
     return entries
         .filter((e) => e.state === 'admitted')
-        .map((e) => `${e.label}${describeScope(e)} pid ${e.pid} (${e.command})${e.cwd ? ` in ${e.cwd}` : ''}, ${gib(e.footprintBytes)}${e.footprintReason ? ` (${e.footprintReason})` : ''}, for ${age(nowMs - (e.admittedAtMs ?? e.enqueuedAtMs))}`);
+        .map((e) => {
+        const verdict = entryVerdict(e, nowMs, probe);
+        const child = e.child !== undefined ? `, child ${e.child.pid}` : '';
+        const groups = e.toolGroups.length > 0 ? `, groups ${e.toolGroups.join(',')}` : '';
+        return (`${e.label}${describeScope(e)} pid ${e.pid} on ${e.host} (${e.command})${e.cwd ? ` in ${e.cwd}` : ''}, ` +
+            `${gib(e.footprintBytes)}${e.footprintReason ? ` (${e.footprintReason})` : ''}, for ${age(nowMs - (e.admittedAtMs ?? e.enqueuedAtMs))}; ` +
+            `heartbeat ${age(nowMs - e.heartbeatAtMs)} ago${child}${groups}, ${verdict.state} (${verdict.reason})`);
+    });
 }
 /** Commands too generic to name a lock-taking wrapper. */
 const GENERIC_PROGRAMS = new Set([
@@ -1632,6 +1722,12 @@ async function admitInner(req, opts) {
         const { share, lightShare, reading, sampled } = await sampleShare(opts, before.pressure, nowMs, before.entries);
         lastReading = reading;
         checkQueue();
+        try {
+            opts.onPass?.();
+        }
+        catch {
+            // Best effort: the orphan bound still frees what this could not.
+        }
         const dead = findDead(before, now(), probe);
         return withLedger(dir, (doc) => {
             checkQueue();
@@ -1679,7 +1775,7 @@ async function admitInner(req, opts) {
             retryAfterMs: reading !== null ? MEMORY_GATE_RETRY_AFTER_MS : 2_000,
             memoryPressure: reading,
             ahead,
-            holders: describeLoad(doc, nowMs),
+            holders: describeLoad(doc, nowMs, probe),
         };
     };
     const attempt = async () => {
@@ -1712,7 +1808,7 @@ async function admitInner(req, opts) {
             }
             if (now() - lastReportAt >= LEDGER_HOLDER_REPORT_MS && opts.notice) {
                 lastReportAt = now();
-                opts.notice(holderReport(first.doc, entry, pid, now() - t0, capacityBytes, now(), timeoutMs));
+                opts.notice(holderReport(first.doc, entry, pid, now() - t0, capacityBytes, now(), timeoutMs, probe));
             }
             const remaining = timeoutMs - (now() - t0);
             if (remaining <= 0)
@@ -1791,8 +1887,8 @@ function budgetLoad(doc, capacityBytes) {
     };
 }
 /** {@link describeHolders}, plus a line for entries of another CLEO version. */
-function describeLoad(doc, nowMs) {
-    const lines = describeHolders(doc.entries, nowMs);
+function describeLoad(doc, nowMs, probe) {
+    const lines = describeHolders(doc.entries, nowMs, probe);
     if (doc.foreign.length > 0) {
         lines.push(`${doc.foreign.length} entr${doc.foreign.length === 1 ? 'y' : 'ies'} of another CLEO version`);
     }
@@ -1803,13 +1899,13 @@ function describeLoad(doc, nowMs) {
  * budget, it names the cause (the host's largest memory users, CLEO or not)
  * and when the wait gives up (T13914).
  */
-function holderReport(doc, mine, pid, waitedMs, capacityBytes, nowMs, timeoutMs) {
+function holderReport(doc, mine, pid, waitedMs, capacityBytes, nowMs, timeoutMs, probe) {
     const holders = doc.entries.filter((e) => e.state === 'admitted');
     const used = budgetLoad(doc, capacityBytes).bytes;
     const ahead = waitingAhead(doc.entries, mine, nowMs);
     const lines = [
         `still waiting after ${age(waitedMs)} for the machine budget (${gib(used)} of ${budgetPhrase(mine, ledgerBudget(doc.pressure, capacityBytes))} in use, ` +
-            `queue position ${ahead + 1}${mine.priority === 'urgent' ? ' (urgent)' : ''}, ${ahead} waiting ahead). Holders: ${describeLoad(doc, nowMs).join('; ') || 'none'}.`,
+            `queue position ${ahead + 1}${mine.priority === 'urgent' ? ' (urgent)' : ''}, ${ahead} waiting ahead). Holders: ${describeLoad(doc, nowMs, probe).join(' | ') || 'none'}.`,
     ];
     const reading = doc.pressure?.reading ?? null;
     if (reading !== null) {
@@ -1906,6 +2002,9 @@ function holdGrant(entry, dir, waitedMs, opts) {
         ungoverned: null,
         waitedMs,
         footprintBytes: entry.footprintBytes,
+        recordChild: (child) => {
+            void update((e) => ({ ...e, child }));
+        },
         release: async () => {
             if (released)
                 return;