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

package/dist/tasks/tool-semaphore.js

@@ -1,607 +1,181 @@
 /**
- * Cross-process global concurrency limit for evidence-tool runs (T1534 / ADR-061).
+ * Machine-wide admission for evidence-tool runs (T1534 / ADR-061, T13133).
  *
  * The cache layer ({@link runToolCached}) coalesces *identical* parallel runs
- * via a per-key file lock — when 10 sibling tasks against the same git HEAD
- * call `tool:test`, only one spawns. But orchestrator-spawned worktree
- * agents each operate on a *different* HEAD (one branch per worktree per
- * ADR-055), so their cache keys differ and the per-key lock does NOT
- * coalesce them. Without an additional bound, N worktree agents would each
- * spawn the full toolchain, multiplying CPU and resident memory by N.
- *
- * This module bounds *total* concurrent runs of a canonical tool across
- * the whole machine — independent of which project, worktree, or PID
- * issues the call. It uses a slot directory under
- * `~/.local/share/cleo/locks/tool-<canonical>/` with `slot-0.lock` …
- * `slot-(N-1).lock` files; each slot is held by `proper-lockfile` so a
- * crashed process auto-releases via the standard stale-lock recovery.
- *
- * Defaults (configurable via env):
- *
- *   | Tool           | Default                          | Binding constraint        |
- *   |----------------|----------------------------------|---------------------------|
- *   | test, build    | min(RAM/24GiB, cpus/4), min 1    | MEMORY (each run forks)   |
- *   | lint, typecheck| max(2, cpus/2)                   | CPU (single-process)      |
- *   | audit          | max(2, cpus/2)                   | network-bound, small RAM  |
- *   | security-scan  | max(2, cpus/2)                   | network-bound, small RAM  |
- *
- * On darwin `test`/`build` default to ONE slot machine-wide (T12963): macOS has
- * no PSI, so {@link pressureScaleSlots} can never shrink the budget there and
- * the RAM bound is the only guard left. Heavy runs additionally take a slot of
- * the matching {@link ResourceGovernor} class (`test` → `test-run`, `build` →
- * `scoped-build`), so evidence runs and other governed heavy work share one
- * machine-wide budget.
- *
- * T12091: `test`/`build` were `max(1, cpus/4)` — 6 slots on a 24-core box. Since
- * each `pnpm run test` is itself allowed 6 vitest forks × 4 GiB, the two bounds
- * composed to 144 GiB of permitted heap on 62 GiB of RAM. Neither layer was
- * individually violated, which is exactly why the machine froze without any
- * guard firing. Heavy tools are now bounded by the dimension that actually
- * limits them — see {@link defaultMaxConcurrent}.
- *
- * Override via `CLEO_TOOL_CONCURRENCY_<CANONICAL>` (e.g.
- * `CLEO_TOOL_CONCURRENCY_TEST=2`). Set to `0` or a negative number to
- * disable the limit for that tool — which also disables the RAM bound, so it is
- * the one setting that can still oversubscribe the machine.
+ * via a per-key file lock. Orchestrator-spawned worktree agents each operate
+ * on a *different* HEAD, so their cache keys differ and the per-key lock does
+ * not coalesce them; without a machine-wide bound, N worktree agents would
+ * each spawn the full toolchain, multiplying CPU and resident memory by N.
+ *
+ * Since T13133 that bound is the admission ledger (`resources/admission-ledger.ts`):
+ * one budget in bytes and one FIFO queue shared by every evidence run, every
+ * `cleo run` job and the vitest project probe, machine-wide. An evidence run
+ * asks for its footprint (`footprintForTool`: a heavy test/build run is
+ * charged its worker count × 6 GiB, typecheck and lint their planned heap plus
+ * 2 GiB, audit and scans 1 GiB),
+ * waits its turn, and exports the grant's `CLEO_ADMISSION` token to the tool
+ * it spawns, so a `cleo verify` or `cleo run` the tool starts rides the grant
+ * instead of waiting for the budget its own ancestor holds.
+ *
+ * What it replaced: per-tool slot directories under `<cleoHome>/locks/tool-*`,
+ * core- and RAM-derived slot counts (`defaultMaxConcurrent`), PSI slot scaling
+ * (`pressureScaleSlots`), the darwin one-slot rule (T12963) and a second,
+ * separate governor slot taken after the tool slot, the order that could
+ * deadlock against `cleo run` (T13133). Memory pressure now narrows the one
+ * budget, and the memory gate (T13127) refuses heavy work outright while
+ * memory is short; a waiting run says so on stderr with the readings.
+ *
+ * `CLEO_TOOL_CONCURRENCY_<TOOL>` no longer counts runs: `0` (or below) still
+ * bypasses admission for that tool, any other value is ignored, and either
+ * prints one deprecation line per process on stderr. `CLEO_RESOURCES_MODE=off`
+ * is the supported switch.
  *
  * @task T1534
  * @task T12091
  * @task T12963
+ * @task T13123
+ * @task T13127
+ * @task T13133
  * @adr ADR-061
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { availableParallelism, hostname, totalmem } from 'node:os';
-import { join } from 'node:path';
-import lockfile from 'proper-lockfile';
-import { getCleoHome } from '../paths.js';
-import { governor } from '../resources/governor.js';
-import { ResourceMonitor } from '../resources/monitor.js';
-import { assessSlotHolder, currentLockId, ownProcessStartedAt, reapSlotIfHolderDead, recordToolGroupsWhileHeld, SLOT_LOCK_STALE_MS, writeHolderRecord, } from '../resources/slot-holder.js';
-import { isHeavyTool } from './heavy-tool-env.js';
-// ---------------------------------------------------------------------------
-// Concurrency-limit defaults + override resolution
-// ---------------------------------------------------------------------------
-/**
- * Worst-case resident footprint of ONE `tool:test` / `tool:build` invocation,
- * in GiB.
- *
- * This is not a guess. `vitest.memory-safe.ts` permits
- * `MEMORY_SAFE_MAX_WORKERS` forks (up to 6) each capped at `FORK_HEAP_MB`
- * (4096), so a single `pnpm run test` may legitimately hold ~24 GiB before any
- * guard fires. Keep this in step with that file if either bound changes.
- *
- * @task T12091
- */
-export const HEAVY_TOOL_FOOTPRINT_GIB = 24;
-/**
- * Compute the default max-concurrency for a canonical tool.
- *
- * ## Why this is RAM-derived, not core-derived (T12091)
- *
- * This returned `floor(cpus / 4)` for `test`/`build`, which on a 24-core box is
- * **6 concurrent full test suites**. Each of those is itself allowed 6 vitest
- * forks × a 4 GiB heap cap, so the composed permission was
- *
- *     6 runs × 6 forks × 4 GiB = 144 GiB
- *
- * on a 62 GiB machine. Both layers were individually "bounded" and their
- * composition was 2.3× the hardware — which is precisely how this box froze
- * repeatedly: no single guard was violated. The per-invocation cap (T12087) and
- * this cross-invocation cap were written independently and never multiplied out.
- *
- * The dimensional error is the root of it: what limits a test run is MEMORY, and
- * core count says nothing about memory. A 24-core/16 GiB VM got the same 6 slots
- * as a 24-core/256 GiB server. So heavy tools now divide TOTAL RAM by
- * {@link HEAVY_TOOL_FOOTPRINT_GIB} and are additionally capped by cores, never
- * exceeding what the machine can actually hold.
- *
- * Reactive pressure scaling ({@link pressureScaleSlots}) is not a substitute:
- * PSI `some avg10` is a ten-second average, and a fork fleet can exhaust RAM
- * faster than that window can report it. Admission has to be right up front.
- *
- * Light tools (lint, typecheck, audit, security-scan) are single-process and
- * short, and keep the core-derived half-of-cores budget.
- *
- * ## Why darwin gets one heavy slot (T12963)
- *
- * Linux shrinks the heavy budget under memory pressure through PSI
- * ({@link pressureScaleSlots}). macOS exposes no PSI, so that reactive layer
- * never fires there, and a 64 GiB Mac would admit two full suites with nothing
- * to back them off. Concurrent agents on a laptop are the common case, so the
- * default is one heavy run at a time; `CLEO_TOOL_CONCURRENCY_TEST` /
- * `_BUILD` still raise it.
- *
- * @param canonical - the canonical tool class.
- * @param cpuCount  - logical cores available.
- * @param totalRamGib - total machine RAM in GiB; defaults to a live reading.
- * @param platform - OS platform; defaults to `process.platform`.
- * @returns the machine-wide slot count, always ≥ 1.
- *
- * @example
- * ```ts
- * // 24 cores, 62 GiB → floor(62/24) = 2 (was 6, permitting 144 GiB of heap)
- * defaultMaxConcurrent('test', 24, 62); // → 2
- * // 24 cores, 16 GiB → 1: one suite is already more than this box can hold
- * defaultMaxConcurrent('test', 24, 16); // → 1
- * // macOS: no PSI to back off with, so one heavy run at a time
- * defaultMaxConcurrent('test', 12, 64, 'darwin'); // → 1
- * ```
- *
- * @task T1534
- * @task T12091
- * @task T12963
- */
-export function defaultMaxConcurrent(canonical, cpuCount, totalRamGib = totalmem() / 1024 ** 3, platform = process.platform) {
-    const cpus = Math.max(1, cpuCount);
-    switch (canonical) {
-        case 'test':
-        case 'build': {
-            if (platform === 'darwin')
-                return 1;
-            const byRam = Math.floor(totalRamGib / HEAVY_TOOL_FOOTPRINT_GIB);
-            const byCpu = Math.floor(cpus / 4);
-            return Math.max(1, Math.min(byRam, byCpu));
-        }
-        case 'lint':
-        case 'typecheck':
-        case 'audit':
-        case 'security-scan':
-            return Math.max(2, Math.floor(cpus / 2));
-        default:
-            return 1;
-    }
+import { admissionCapacityBytes, admit, describeAdmissionIoError, footprintForTool, } from '../resources/admission-ledger.js';
+import { memoryGateReporter } from '../resources/pressure-gate.js';
+/** The default {@link AcquireSlotOptions.notice}: one stderr line. */
+function stderrNotice(line) {
+    process.stderr.write(`[cleo] ${line}\n`); // json-stream-hygiene-allowed: progress while waiting; stdout carries the envelope
 }
+/** Tools whose deprecated `CLEO_TOOL_CONCURRENCY_<TOOL>` notice was printed in this process. */
+const _deprecationNoticed = new Set();
 /**
- * Resolve the active per-tool concurrency limit, honouring the
- * `CLEO_TOOL_CONCURRENCY_<CANONICAL>` env override when set. A value of
- * `0` (or any non-positive number) disables the bound and returns
- * `Number.POSITIVE_INFINITY`, in which case {@link acquireGlobalSlot}
- * returns a no-op release.
+ * The deprecated `CLEO_TOOL_CONCURRENCY_<TOOL>` override: `bypass` for `0` or
+ * below, `ignored` for any other number, `null` when unset. Prints one
+ * deprecation line per tool per process on stderr, never on stdout.
  *
- * @task T1534
- * @task T12963
- */
-export function resolveMaxConcurrent(canonical, cpuCount, totalRamGib, platform) {
-    const envKey = `CLEO_TOOL_CONCURRENCY_${canonical.toUpperCase().replace(/-/g, '_')}`;
-    const raw = process.env[envKey];
-    if (raw !== undefined && raw !== '') {
-        const parsed = Number.parseInt(raw, 10);
-        if (Number.isFinite(parsed)) {
-            if (parsed <= 0)
-                return Number.POSITIVE_INFINITY;
-            return parsed;
-        }
-    }
-    return defaultMaxConcurrent(canonical, cpuCount ?? availableParallelism(), totalRamGib ?? totalmem() / 1024 ** 3, platform ?? process.platform);
-}
-/**
- * Whether a canonical tool's slot budget shrinks under memory pressure.
- * Only the heavy `test`/`build` classes scale; lint/typecheck/audit are light
- * and single-threaded, so they keep their static budget.
- */
-function isPressureSensitive(canonical) {
-    // Delegates rather than repeating the literal. This was the third
-    // independent definition of "heavy"; all three agreed by coincidence, and a
-    // fifth heavy tool would have needed three coordinated edits — with a missed
-    // one producing a SILENT asymmetry (a tool granted the long deadline and the
-    // worker caps but not a semaphore slot, or the reverse).
-    return isHeavyTool(canonical);
-}
-/**
- * Scale a static slot budget down under memory pressure (T12001 · choke-point
- * #6). Mirrors the governor's `test-run` budget: halve when `some avg10` exceeds
- * the hold threshold, floor to 1 when it exceeds the backoff/floor threshold.
- * Recovers automatically as pressure clears. `full-build` is not represented as
- * a canonical tool here; the dedicated `full-build` governor class (T11999)
- * pins that to one machine-wide slot.
+ * @param canonical - the canonical tool.
+ * @param notice - where the line goes.
+ * @returns what the override does now.
  *
- * @task T12001
- */
-export function pressureScaleSlots(canonical, staticMax, sample, thresholds = {}) {
-    if (!Number.isFinite(staticMax) || !isPressureSensitive(canonical))
-        return staticMax;
-    const hold = thresholds.holdSomeAvg10 ?? 10;
-    const floor = thresholds.floorSomeAvg10 ?? 25;
-    const some = sample.globalPressure?.some?.avg10 ?? sample.slicePressure?.some?.avg10 ?? 0;
-    if (some > floor)
-        return 1;
-    if (some > hold)
-        return Math.max(1, Math.floor(staticMax / 2));
-    return staticMax;
-}
-/**
- * Best-effort point-sample for slot scaling. NEVER throws — on any error (no
- * `/proc`, non-Linux, read failure) returns `null` so the caller fails open to
- * the static slot count. The PSI + meminfo reads are sub-5ms.
+ * @task T13133
  */
-async function samplePressureSafe() {
-    try {
-        return await new ResourceMonitor().sample();
-    }
-    catch {
+export function legacyConcurrencyOverride(canonical, notice = stderrNotice) {
+    const key = `CLEO_TOOL_CONCURRENCY_${canonical.toUpperCase().replace(/-/g, '_')}`;
+    const raw = process.env[key];
+    if (raw === undefined || raw === '')
         return null;
-    }
-}
-/**
- * Whether an explicit `CLEO_TOOL_CONCURRENCY_<TOOL>` override is set — when so,
- * the operator's intent is authoritative and pressure scaling is bypassed.
- */
-function hasConcurrencyOverride(canonical) {
-    const raw = process.env[`CLEO_TOOL_CONCURRENCY_${canonical.toUpperCase().replace(/-/g, '_')}`];
-    return raw !== undefined && raw !== '';
-}
-/**
- * The {@link ResourceGovernor} class a heavy tool run is admitted under, or
- * `null` for light tools. `test` and `build` are the classes the governor
- * budgets as `test-run` / `scoped-build` (T12963).
- */
-export function governorClassFor(canonical) {
-    if (canonical === 'test')
-        return 'test-run';
-    if (canonical === 'build')
-        return 'scoped-build';
-    return null;
-}
-/**
- * Take the governor slot for a heavy run that already holds its tool slot.
- * Returns the grant's release, a no-op when no admission applies, or throws
- * when the governor defers within the remaining wait budget.
- *
- * Skipped under an explicit `CLEO_TOOL_CONCURRENCY_<TOOL>` override: the
- * operator's count is authoritative, and the governor's own budget would
- * silently cap it.
- */
-async function admitThroughGovernor(canonical, opts, remainingMs) {
-    const cls = governorClassFor(canonical);
-    if (cls === null || opts.skipGovernor === true || hasConcurrencyOverride(canonical)) {
-        return NOOP_RELEASE;
-    }
-    const admission = await governor.acquire(cls, {
-        timeoutMs: Math.max(1, remainingMs),
-        ...(opts.pollMs !== undefined ? { pollMs: opts.pollMs } : {}),
-        ...(opts.cpuCount !== undefined ? { cpuCount: opts.cpuCount } : {}),
-        ...(opts.totalRamGib !== undefined ? { totalMemBytes: opts.totalRamGib * 1024 ** 3 } : {}),
-        ...(opts.pressureSample ? { sample: opts.pressureSample } : {}),
-    });
-    if (admission.deferred) {
-        // @sync-invariant none:local-only machine-wide admission timeout; no store write
-        throw new Error(`Timed out waiting for the '${cls}' resource budget for a '${canonical}' run: ` +
-            `${admission.reason}. Override with ` +
-            `CLEO_TOOL_CONCURRENCY_${canonical.toUpperCase().replace(/-/g, '_')}=<n>.`);
-    }
-    return admission.release;
-}
-// ---------------------------------------------------------------------------
-// Slot-directory layout
-// ---------------------------------------------------------------------------
-/**
- * Path to the global slot directory for a canonical tool. Sits under
- * `getCleoHome()/locks/tool-<canonical>/` so all CLEO-driven processes
- * on a machine share the same semaphore — across projects, worktrees,
- * and PIDs.
- *
- * @task T1534
- */
-export function semaphoreDir(canonical) {
-    return join(getCleoHome(), 'locks', `tool-${canonical}`);
-}
-/**
- * Path of the sidecar holder record for a slot.
- *
- * Deliberately a SIBLING of the lock rather than a file inside it:
- * `proper-lockfile` removes its lock directory with `rmdir`, which fails if we
- * have put anything inside it.
- *
- * @internal
- * @task T12113 (gh#1222)
- */
-function holderPath(slotPath) {
-    return `${slotPath}.holder.json`;
-}
-/**
- * Record who holds a slot, and keep the record listing every tool group this
- * process starts while it holds the slot (T12963). Best-effort: a failure here
- * must never fail an acquire that has already succeeded, because the slot IS
- * held at that point and throwing would leak it.
- *
- * @returns Stops recording tool groups; call it on release.
- *
- * @internal
- * @task T12113 (gh#1222)
- * @task T12963
- */
-function writeHolder(slotPath, canonical) {
-    let holder;
-    const recording = recordToolGroupsWhileHeld(slotPath, () => holder);
-    holder = {
-        pid: process.pid,
-        host: hostname(),
-        acquiredAt: new Date().toISOString(),
-        canonical,
-        slot: slotPath,
-        startedAt: ownProcessStartedAt(),
-        lockId: currentLockId(slotPath),
-        toolGroups: [...recording.groups],
-    };
-    writeHolderRecord(slotPath, holder);
-    return recording.stop;
-}
-/**
- * Read a slot's holder record. Returns `null` when absent or unparseable —
- * both mean "we cannot say who holds this", which is treated as alive.
- *
- * @internal
- * @task T12113 (gh#1222)
- */
-export function readHolder(slotPath) {
-    try {
-        const parsed = JSON.parse(readFileSync(holderPath(slotPath), 'utf-8'));
-        if (typeof parsed.pid !== 'number' || typeof parsed.host !== 'string')
-            return null;
-        return parsed;
-    }
-    catch {
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed))
         return null;
+    const effect = parsed <= 0 ? 'bypass' : 'ignored';
+    if (!_deprecationNoticed.has(key)) {
+        _deprecationNoticed.add(key);
+        notice(`${key} is deprecated: heavy runs now share one machine-wide memory budget and no ` +
+            `longer count slots (T13133). ${effect === 'bypass' ? `${key}=${raw} still bypasses admission for now;` : `${key}=${raw} is ignored;`} ` +
+            'use CLEO_RESOURCES_MODE=off to turn admission off.');
     }
+    return effect;
 }
-/**
- * Is a slot's recorded holder still running?
- *
- * Fails SAFE: an unknown holder, a holder on another host, or any error is
- * reported as ALIVE. Reaping a live holder's slot would let two heavy suites
- * run against one bound — the exact oversubscription the semaphore exists to
- * prevent — so uncertainty must never authorise a reap. A holder whose pid is
- * gone but whose tool group still has a member is ALIVE (T12963).
- *
- * @param holder - Holder record, or `null` when none could be read.
- * @param slotPath - The slot the record belongs to. With it, a record that
- *   does not describe the slot's current lock (or one written before T12963,
- *   which names no lock) is alive, and a recycled pid is dead.
- * @returns `true` when the slot must be treated as legitimately held.
- *
- * @task T12113 (gh#1222)
- * @task T12963
- */
-export function isHolderAlive(holder, slotPath) {
-    return assessSlotHolder(holder, slotPath) !== 'dead';
-}
-/**
- * Release a slot whose recorded holder is gone.
- *
- * Removes `proper-lockfile`'s lock directory directly — the same thing its own
- * stale recovery does, but decided by process liveness instead of by a 10
- * minute mtime timeout. Since T12963 the holder's tool groups must be gone
- * too, the record must describe the current lock, and the reap runs under a
- * per-slot guard ({@link reapSlotIfHolderDead}).
- *
- * @param slotPath - Slot lock file path.
- * @param staleMs - The slot's `proper-lockfile` stale threshold.
- * @returns `true` when an orphaned slot was actually reaped.
- *
- * @task T12113 (gh#1222)
- * @task T12963
- */
-export function reapSlotIfOrphaned(slotPath, staleMs = SLOT_LOCK_STALE_MS) {
-    return reapSlotIfHolderDead(slotPath, readHolder, { staleMs });
-}
-/**
- * Enumerate every slot of a canonical tool with its holder and liveness.
- *
- * Backs the operator-facing lock inspection surface requested in gh#1222 —
- * "who is holding this, and is it even alive?" — which previously required
- * reading `~/.local/share/cleo/locks/` by hand.
- *
- * @param canonical - Canonical tool name.
- * @returns One row per existing slot file.
- *
- * @task T12113 (gh#1222)
- */
-export function listSlotHolders(canonical) {
-    const dir = semaphoreDir(canonical);
-    if (!existsSync(dir))
-        return [];
-    const rows = [];
-    for (let i = 0;; i++) {
-        const slotPath = join(dir, `slot-${i}.lock`);
-        if (!existsSync(slotPath))
-            break;
-        const holder = readHolder(slotPath);
-        rows.push({
-            slot: slotPath,
-            held: existsSync(`${slotPath}.lock`),
-            holder,
-            alive: isHolderAlive(holder, slotPath),
-        });
-    }
-    return rows;
+/** Forget which deprecation notices were printed. Tests only. @internal */
+export function _resetToolSemaphoreForTest() {
+    _deprecationNoticed.clear();
 }
 /**
- * Reap every orphaned slot of a canonical tool.
- *
- * @param canonical - Canonical tool name.
- * @returns Paths of the slots actually reaped.
+ * {@link acquireGlobalSlot} gave up: the run was not admitted within its
+ * timeout. `refusal` says why (memory pressure, or the budget in use) and who
+ * holds the budget.
  *
- * @task T12113 (gh#1222)
+ * @task T13133
  */
-export function reapOrphanedSlots(canonical) {
-    const reaped = [];
-    for (const row of listSlotHolders(canonical)) {
-        if (row.held && !row.alive && reapSlotIfOrphaned(row.slot))
-            reaped.push(row.slot);
+export class AdmissionTimeoutError extends Error {
+    /** Why the run was not admitted, with the holders. */
+    refusal;
+    /**
+     * @param canonical - the tool whose run waited.
+     * @param refusal - the ledger's refusal.
+     */
+    constructor(canonical, refusal) {
+        super(`Timed out waiting for admission of a '${canonical}' run: ${refusal.reason}.` +
+            (refusal.holders.length > 0 ? ` Current holders — ${refusal.holders.join('; ')}.` : '') +
+            ' Use CI as test evidence (ci:<pr>), narrow the run, or set CLEO_RESOURCES_MODE=off to turn admission off.');
+        this.name = 'AdmissionTimeoutError';
+        this.refusal = refusal;
     }
-    return reaped;
 }
-function ensureSlotFiles(dir, count) {
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const paths = [];
-    for (let i = 0; i < count; i++) {
-        const p = join(dir, `slot-${i}.lock`);
-        if (!existsSync(p)) {
-            writeFileSync(p, '', 'utf-8');
-        }
-        paths.push(p);
-    }
-    return paths;
+function withAdmission(release, admission) {
+    return Object.assign(release, { admission });
 }
-// ---------------------------------------------------------------------------
-// Acquire / release
-// ---------------------------------------------------------------------------
-const NOOP_RELEASE = async () => {
-    /* no-op when concurrency is disabled */
-};
+const NOOP_RELEASE = withAdmission(async () => {
+    /* nothing was admitted */
+}, '');
 /**
- * Acquire one slot from the global semaphore for a canonical tool. Blocks
- * until a slot becomes free or `timeoutMs` elapses.
+ * Wait for admission of one evidence run of a canonical tool, machine-wide.
+ * Blocks until the ledger admits it or `timeoutMs` elapses.
  *
- * Implementation detail: tries each slot file in turn with `retries: 0`
- * (proper-lockfile non-blocking acquire). When all are busy, sleeps for
- * `pollMs` and retries. This avoids the thundering-herd cost of having
- * many retriers wake at the exact same moment.
+ * Re-entrant: inside an admitted run's process tree (a `cleo verify` that a
+ * `cleo run` job or another evidence run started) it is admitted at once on
+ * that grant. While it waits on memory pressure it says so through
+ * {@link AcquireSlotOptions.notice}, and after a minute it names the holders.
  *
  * @param canonical - Canonical tool name from the resolver.
  * @param opts - Acquisition options.
- * @returns A release function. Idempotent.
- * @throws When `timeoutMs` elapses without acquiring a slot.
+ * @returns A release function carrying the `CLEO_ADMISSION` token. Idempotent.
+ * @throws When `timeoutMs` elapses without admission, naming the reason and
+ *   the holders.
  *
  * @example
  * ```ts
  * const release = await acquireGlobalSlot('test');
  * try {
- *   await runTheTool();
+ *   await runTheTool({ env: { CLEO_ADMISSION: release.admission } });
  * } finally {
  *   await release();
  * }
  * ```
  *
  * @task T1534
+ * @task T13133
  */
 export async function acquireGlobalSlot(canonical, opts = {}) {
-    const max = resolveMaxConcurrent(canonical, opts.cpuCount, opts.totalRamGib, opts.platform);
-    if (!Number.isFinite(max) || max <= 0) {
+    const notice = opts.notice ?? stderrNotice;
+    if (opts.skipAdmission === true || legacyConcurrencyOverride(canonical, notice) === 'bypass') {
         return NOOP_RELEASE;
     }
-    // T12001 / choke-point #6: shrink the EFFECTIVE slot count for the heavy
-    // test/build classes under memory pressure so builds/tests can't co-schedule
-    // into an OOM. The static slot FILES are still created (stable dir across
-    // pressure swings) — only the acquirable window shrinks, and it recovers as
-    // pressure clears. An explicit CLEO_TOOL_CONCURRENCY_* override is honored
-    // verbatim, and any sampling failure fails OPEN to the static count.
-    let effectiveMax = max;
-    if (isPressureSensitive(canonical) && !hasConcurrencyOverride(canonical)) {
-        const sample = opts.pressureSample !== undefined ? opts.pressureSample : await samplePressureSafe();
-        if (sample)
-            effectiveMax = pressureScaleSlots(canonical, max, sample);
-    }
-    const dir = semaphoreDir(canonical);
-    // Create the full static slot set so the directory is stable; only the first
-    // `effectiveMax` are eligible this acquire.
-    const slots = ensureSlotFiles(dir, max);
-    const usableSlots = slots.slice(0, Math.max(1, effectiveMax));
-    const timeoutMs = opts.timeoutMs ?? 3_600_000;
-    const pollMs = opts.pollMs ?? 100;
-    const staleMs = opts.staleMs ?? 600_000;
-    const startedAt = Date.now();
-    // Randomise slot order so concurrent acquirers don't collide on slot 0.
-    // The Fisher–Yates shuffle is fine for small N.
-    const order = [...usableSlots.keys()];
-    for (let i = order.length - 1; i > 0; i--) {
-        const j = Math.floor(Math.random() * (i + 1));
-        const a = order[i];
-        const b = order[j];
-        if (a !== undefined && b !== undefined) {
-            order[i] = b;
-            order[j] = a;
-        }
+    const totalBytes = opts.totalRamGib !== undefined ? opts.totalRamGib * 1024 ** 3 : undefined;
+    const fixed = opts.pressureSample;
+    const outcome = await admit({
+        label: `tool:${canonical}`,
+        footprintBytes: opts.footprintBytes ?? footprintForTool(canonical, totalBytes, opts.heapMb),
+        // T13237: an evidence build is the project's whole build (`pnpm run
+        // build`): it takes the machine-wide full-build slot, like
+        // `cleo run --class full-build`.
+        ...(canonical === 'build' ? { exclusive: true } : {}),
+        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+        ...(opts.task !== undefined ? { task: opts.task } : {}),
+    }, {
+        wait: true,
+        timeoutMs: opts.timeoutMs ?? 3_600_000,
+        ...(opts.pollMs !== undefined ? { pollMs: opts.pollMs } : {}),
+        ...(totalBytes !== undefined ? { capacityBytes: admissionCapacityBytes(totalBytes) } : {}),
+        // A fixed sample (or none) when given; otherwise the ledger's default.
+        ...(fixed === undefined
+            ? {}
+            : {
+                sample: async () => {
+                    if (fixed === null)
+                        throw new Error('pressure disabled');
+                    return fixed;
+                },
+            }),
+        memoryPressure: memoryGateReporter(notice, `'${canonical}' run`),
+        notice,
+    });
+    if (!outcome.admitted) {
+        // @sync-invariant none:local-only machine-wide admission timeout; no store write
+        throw new AdmissionTimeoutError(canonical, outcome.refusal);
     }
-    while (Date.now() - startedAt < timeoutMs) {
-        for (const idx of order) {
-            const path = slots[idx];
-            if (!path)
-                continue;
-            let acquired = null;
-            try {
-                acquired = await lockfile.lock(path, { retries: 0, stale: staleMs, realpath: false });
-            }
-            catch {
-                // gh#1222: the slot is held — but by whom? proper-lockfile decides
-                // staleness from mtime, so a process that died without releasing
-                // holds the slot for the full staleMs (10 min) and is
-                // indistinguishable from a legitimately slow suite. Ask the holder
-                // record instead: a dead pid on this host is orphaned NOW. Fails
-                // safe — an unknown or remote holder is treated as alive.
-                if (reapSlotIfOrphaned(path, staleMs)) {
-                    try {
-                        acquired = await lockfile.lock(path, { retries: 0, stale: staleMs, realpath: false });
-                    }
-                    catch {
-                        acquired = null; // someone else won the race for the reaped slot
-                    }
-                }
-            }
-            if (acquired) {
-                const release = acquired;
-                const stopRecording = writeHolder(path, canonical);
-                const releaseSlot = async () => {
-                    stopRecording();
-                    // Record first, lock second: once the lock is gone the next holder
-                    // writes its own record, which ours must not delete (T12963).
-                    try {
-                        rmSync(holderPath(path), { force: true });
-                    }
-                    catch {
-                        /* best-effort — a stale holder record is only ever advisory */
-                    }
-                    try {
-                        await release();
-                    }
-                    catch {
-                        // proper-lockfile throws if the lock was already released
-                        // (e.g. via stale recovery). Swallow — the post-condition
-                        // is "slot is free", which is true either way.
-                    }
-                };
-                // T12963: the governor slot is taken AFTER the tool slot, so a run
-                // queued on the tool semaphore holds no governor budget while it waits.
-                let releaseGrant;
-                try {
-                    releaseGrant = await admitThroughGovernor(canonical, opts, timeoutMs - (Date.now() - startedAt));
-                }
-                catch (err) {
-                    await releaseSlot();
-                    throw err;
-                }
-                let released = false;
-                return async () => {
-                    if (released)
-                        return;
-                    released = true;
-                    await releaseGrant();
-                    await releaseSlot();
-                };
-            }
-        }
-        // All slots busy — sleep and retry.
-        await sleep(pollMs);
+    const { grant } = outcome;
+    if (grant.ungoverned) {
+        notice(`${describeAdmissionIoError(grant.ungoverned)}: running the '${canonical}' run ungoverned`);
     }
-    // gh#1222: name the holders. "Everything is busy" with no way to see WHO is
-    // what made an orphaned slot look like a broken semaphore.
-    const holders = listSlotHolders(canonical)
-        .filter((r) => r.held)
-        .map((r) => {
-        const h = r.holder;
-        if (!h)
-            return `${r.slot}: holder unknown`;
-        const groups = h.toolGroups?.length ? ` with tool group(s) ${h.toolGroups.join(',')}` : '';
-        return `${r.slot}: pid ${h.pid} on ${h.host}${groups} since ${h.acquiredAt}${r.alive ? '' : ' (DEAD)'}`;
-    });
-    throw new Error(`Timed out after ${timeoutMs}ms waiting for a free '${canonical}' tool slot ` +
-        `(max ${max} concurrent).` +
-        (holders.length > 0 ? ` Current holders — ${holders.join('; ')}.` : '') +
-        ` Override with CLEO_TOOL_CONCURRENCY_${canonical.toUpperCase().replace(/-/g, '_')}=<n>.`);
-}
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
+    return withAdmission(() => grant.release(), grant.token);
 }
 //# sourceMappingURL=tool-semaphore.js.map