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

package/dist/resources/admission-ledger.d.ts

@@ -0,0 +1,587 @@
+/**
+ * The admission ledger: ONE machine-wide budget and ONE FIFO queue for every
+ * heavy run (T13133, epic T13121).
+ *
+ * It replaces the layers that admitted heavy work before it: the tool
+ * semaphore's per-tool slot directories, the governor's `test-run`,
+ * `scoped-build` and `full-build` slots, `cleo run`'s per-class queues and the
+ * darwin one-slot rule. Each layer bounded only what it could see, and two of
+ * them taken in opposite orders deadlocked the machine queue (T13133). Here
+ * every heavy run — a `cleo verify` evidence run, a `cleo run` job, the vitest
+ * project probe — asks one ledger for a share of one budget.
+ *
+ * ## Budget
+ *
+ * Bytes, not runs: `capacity = totalRAM − max(4 GiB, 25%)`. A run asks for its
+ * footprint ({@link footprintForTool}, {@link footprintForClass}); a run larger
+ * than the capacity is clamped to it and runs alone, so nothing waits forever
+ * on its size. Pressure scales the budget: the memory gate (`pressure-gate.ts`,
+ * T13127) refusing means nothing starts; a `hold` verdict halves the budget and
+ * a CPU-saturated `backoff` admits one run at a time (each keeps one run
+ * going when nothing else is running).
+ *
+ * ## Exclusive runs
+ *
+ * A `full-build` (`cleo run --class full-build`: a workspace-wide build,
+ * turbo/nx across every package) is EXCLUSIVE: at most one exclusive run is
+ * admitted machine-wide at a time, whatever its footprint (T13237). Bytes
+ * alone stopped guaranteeing that once T13132 charged a heavy run half the
+ * budget: two whole-workspace builds fit and ran at once, the saturation
+ * shape behind the P0 crash. Other runs still share the budget beside it.
+ *
+ * ## Queue
+ *
+ * FIFO with backfill: the oldest waiting run starts when it fits; a later run
+ * may start ahead of it while it is young, if it fits now. Once the oldest
+ * waiting run has waited {@link LEDGER_RESERVATION_MS} it holds a reservation
+ * and nothing passes it, so neither a big run nor a stream of small ones can
+ * starve the other. Any process that enters the ledger (an arrival, a waiter's
+ * periodic pass, a release) runs the scheduling pass for everyone; waiters see
+ * their admission by reading the file.
+ *
+ * ## Re-entrancy
+ *
+ * A grant exports `CLEO_ADMISSION=<id>.<nonce>` to its children. A request
+ * made inside an admitted run's process tree rides that grant (no new budget,
+ * no queue), so a `cleo verify` under `cleo run`, or a `cleo run` under an
+ * evidence run, never waits for the budget its own ancestor holds. The token
+ * only says which grant to check: the caller must descend from the holder
+ * (ancestry, or membership of a tool process group it started), with the
+ * holder's start time matching, so the env var alone grants nothing. A wrapper
+ * that scrubs the environment is caught by the same ancestry scan.
+ *
+ * ## The file
+ *
+ * `<cleoHome>/admission/ledger.json`, rewritten by tmp + rename inside a
+ * `proper-lockfile` critical section that only reads, decides and writes:
+ * pressure samples and process probes happen before it is entered, and it is
+ * never held across a spawn or a wait. An entry is dropped once its holder is
+ * provably gone: pid gone (or recycled, by start time) and every tool group it
+ * started gone; a fresh heartbeat or an unreadable probe keeps it.
+ *
+ * @module resources/admission-ledger
+ * @task T13133
+ * @epic T13121
+ */
+import type { HeavyToolResourcePlan, MemoryPressureReading, ResourceClass } from '@cleocode/contracts';
+import { admissionCapacityBytes, admissionReserveBytes } from '../tasks/heavy-tool-env.js';
+import type { CanonicalTool } from '../tasks/tool-resolver.js';
+import type { ResourceSample } from './backend.js';
+import { type MemoryGateReporter } from './pressure-gate.js';
+import { type PidProbe } from './slot-holder.js';
+/** The env var a grant exports to its children: `<id>.<nonce>`. */
+export declare const ADMISSION_ENV = "CLEO_ADMISSION";
+/** The oldest waiting run holds a reservation (no backfill passes it) after this long. */
+export declare const LEDGER_RESERVATION_MS = 120000;
+/** An admitted run refreshes its heartbeat this often. */
+export declare const LEDGER_HEARTBEAT_MS = 15000;
+/** A heartbeat older than this no longer proves its holder alive on its own. */
+export declare const LEDGER_HEARTBEAT_STALE_MS = 60000;
+/** A waiter names the holders (and any suspected cycle) after this long, then this often. */
+export declare const LEDGER_HOLDER_REPORT_MS = 60000;
+/** A crashed process's critical-section lock is taken over after this long. */
+export declare const LEDGER_CRITICAL_STALE_MS = 10000;
+/**
+ * The ledger file format this CLEO reads and writes. A file with a newer
+ * version is never rewritten by this one: admission runs ungoverned instead.
+ */
+export declare const LEDGER_VERSION = 1;
+/**
+ * An entry whose holder cannot be positively identified (pid gone, recycled,
+ * unprobeable, or no recorded start time) is dropped once its heartbeat is
+ * this old. A live holder heartbeats every {@link LEDGER_HEARTBEAT_MS}. The
+ * old slot locks had the same 10-minute takeover as a backstop.
+ */
+export declare const LEDGER_ORPHAN_MS = 600000;
+/**
+ * `CLEO_ADMISSION_PRESSURE=off`: admission ignores memory and CPU pressure
+ * and admits on the byte budget alone (a CI runner whose PSI is noisy, and
+ * the test suite, which must never depend on the host's load). An explicit
+ * sampler passed to {@link admit} is still used.
+ */
+export declare const ADMISSION_PRESSURE_ENV = "CLEO_ADMISSION_PRESSURE";
+/** One GiB in bytes. */
+export declare const GIB: number;
+/** What a light run (audit, security scan) or a config probe is charged. */
+export declare const LIGHT_FOOTPRINT_BYTES: number;
+/**
+ * Resident memory one Node process holds beyond its V8 heap ceiling, in MiB:
+ * code, native allocations, buffers (the same allowance the heavy worker count
+ * makes: {@link GIB_PER_WORKER} minus the default heap).
+ */
+export declare const PROCESS_OVERHEAD_MB: number;
+/** The machine budget and the reserve it leaves (owned by the heavy-tool plan, which sizes runs to it). */
+export { admissionCapacityBytes, admissionReserveBytes };
+/**
+ * What one heavy test or build run is charged: the worker count the heavy-tool
+ * overlay gives it (`heavyToolWorkers`) × {@link GIB_PER_WORKER}.
+ *
+ * @param totalBytes - physical RAM. @defaultValue os.totalmem()
+ * @param env - the environment (the per-run share). @defaultValue process.env
+ */
+export declare function heavyRunFootprintBytes(totalBytes?: number, env?: NodeJS.ProcessEnv): number;
+/**
+ * What an evidence run of a canonical tool is charged: a heavy test or build
+ * run its workers × {@link GIB_PER_WORKER}; a single-process memory-bound run
+ * (`typecheck`, `lint`) its heap ceiling plus {@link PROCESS_OVERHEAD_MB} (the
+ * heap the run is planned with, T13122, or the machine's default for a single
+ * process); anything else {@link LIGHT_FOOTPRINT_BYTES}.
+ *
+ * @param canonical - the canonical tool.
+ * @param totalBytes - physical RAM. @defaultValue os.totalmem()
+ * @param heapMb - the heap ceiling the run is spawned with, in MiB, when known.
+ *
+ * @example
+ * ```ts
+ * footprintForTool('test', 48 * GIB);            // 36 GiB (6 workers × 6 GiB)
+ * footprintForTool('typecheck', 48 * GIB);       // 6 GiB (4096 MiB heap + 2048 MiB)
+ * footprintForTool('typecheck', 48 * GIB, 8192); // 10 GiB
+ * ```
+ */
+export declare function footprintForTool(canonical: CanonicalTool, totalBytes?: number, heapMb?: number): number;
+/**
+ * What a planned memory-bound run is charged: every process it may start ×
+ * (its heap ceiling + {@link PROCESS_OVERHEAD_MB}), i.e. workspace packages in
+ * flight × workers × per-process cost. The plan's limits are what the child is
+ * spawned with, so the charge is enforced, not estimated (T13132).
+ *
+ * @param plan - the `resources` of `planHeavyToolEnv`.
+ *
+ * @example
+ * ```ts
+ * // 1 package × 3 workers × (4096 + 2048) MiB
+ * planFootprintBytes({ workspaceConcurrency: 1, workers: 3, heapMb: 4096 }); // 18 GiB
+ * ```
+ */
+export declare function planFootprintBytes(plan: Pick<HeavyToolResourcePlan, 'workspaceConcurrency' | 'workers' | 'heapMb'>): number;
+/** Governor classes whose admission is the ledger's. */
+export declare const LEDGER_CLASSES: ReadonlySet<ResourceClass>;
+/**
+ * Whether the ledger admits a governor class.
+ *
+ * @param cls - the governor class.
+ */
+export declare function isLedgerClass(cls: ResourceClass): boolean;
+/**
+ * What a `cleo run` job of a ledger class is charged.
+ *
+ * @param cls - the governor class.
+ * @param totalBytes - physical RAM. @defaultValue os.totalmem()
+ */
+export declare function footprintForClass(cls: ResourceClass, totalBytes?: number): number;
+/** One run in the ledger. */
+export interface LedgerEntry {
+    /** Unique id: `<pid>-<ms>-<rand>`. */
+    readonly id: string;
+    /** Secret half of the {@link ADMISSION_ENV} token. */
+    readonly nonce: string;
+    /** The holder (or waiter) process. */
+    readonly pid: number;
+    /** Host the pid belongs to. */
+    readonly host: string;
+    /** The holder's process start time, or `null` when `ps` could not say. */
+    readonly startedAt: string | null;
+    /** What is running: `tool:test`, `run:test-run`, `probe:vitest-projects`. */
+    readonly label: string;
+    /** The command line, redacted, for status and reports. */
+    readonly command: string;
+    /** Working directory, when known. */
+    readonly cwd: string | null;
+    /** Bytes requested. */
+    readonly footprintBytes: number;
+    /** `waiting` in the queue, or `admitted` and holding its share. */
+    readonly state: 'waiting' | 'admitted';
+    /** When it joined the queue (FIFO order). */
+    readonly enqueuedAtMs: number;
+    /** When it was admitted. */
+    readonly admittedAtMs: number | null;
+    /** Last proof of life. */
+    readonly heartbeatAtMs: number;
+    /** Process groups of the tools the holder started while admitted. */
+    readonly toolGroups: readonly number[];
+    /** How much of the project the run covers, when known (T13132). */
+    readonly scope?: AdmissionScope;
+    /** The CLEO task the run is evidence for, when known (T13132). */
+    readonly task?: string;
+    /**
+     * Holds the machine-wide exclusive slot: no other exclusive entry is
+     * admitted while it is (T13237). Set for the `full-build` class.
+     */
+    readonly exclusive?: boolean;
+}
+/**
+ * How much of a project a run covers, shown in status so an operator can see
+ * what holds the budget (T13132): `full` is a whole-suite run, `affected` the
+ * changed packages and their dependents, `focused` a failed-first rerun of
+ * named files, `narrowed` a command that names its test files.
+ */
+export type AdmissionScope = 'full' | 'affected' | 'focused' | 'narrowed';
+/**
+ * The ledger directory under the CLEO home.
+ *
+ * @param cleoHome - the CLEO home. @defaultValue {@link getCleoHome}
+ */
+export declare function admissionDir(cleoHome?: string): string;
+/** A ledger entry in a format this CLEO does not know: kept verbatim, charged conservatively. */
+export type ForeignEntry = Readonly<Record<string, unknown>>;
+/**
+ * Read the ledger's entries without the lock (writes are atomic renames, so a
+ * reader sees a whole file). A missing or corrupt file has no entries;
+ * entries of a format this CLEO does not know are left out (they are kept in
+ * the file and still charged).
+ *
+ * @param dir - the ledger directory. @defaultValue {@link admissionDir}
+ */
+export declare function readLedger(dir?: string): LedgerEntry[];
+/**
+ * Entries of a format this CLEO does not know (written by another CLEO
+ * version sharing the CLEO home), read without the lock.
+ *
+ * @param dir - the ledger directory. @defaultValue {@link admissionDir}
+ */
+export declare function readForeignEntries(dir?: string): ForeignEntry[];
+/**
+ * The ledger file was written by a newer CLEO: this one never rewrites it.
+ * Admission treats it like unwritable state and runs ungoverned.
+ */
+export declare class LedgerVersionError extends Error {
+    /** Error code, matched by {@link admissionIoError}. */
+    readonly code = "E_LEDGER_VERSION";
+    /** The ledger file. */
+    readonly path: string;
+    /**
+     * @param version - the version found in the file.
+     * @param path - the ledger file.
+     */
+    constructor(version: number, path: string);
+}
+/**
+ * Whether an entry's holder is still there.
+ *
+ * - 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.
+ * - 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.
+ * - 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 declare function entryLiveness(entry: LedgerEntry, nowMs: number, probe?: PidProbe): 'alive' | 'dead';
+/**
+ * How much of the budget pressure leaves: `full`; `half` (memory or CPU at
+ * hold); `one` run at a time (CPU saturated); `none` (the memory gate refuses).
+ */
+export type BudgetShare = 'full' | 'half' | 'one' | 'none';
+/**
+ * A run larger than this is heavy: more than one worker's footprint
+ * ({@link GIB_PER_WORKER}), i.e. a multi-process test or build run. CPU
+ * saturation narrows only heavy runs (T13132): a single-process typecheck or
+ * lint, a single-file test run and the config probe are one process each, and
+ * serialising them behind a whole suite only starved them.
+ */
+export declare const HEAVY_FOOTPRINT_BYTES: number;
+/**
+ * The budget share for light runs ({@link HEAVY_FOOTPRINT_BYTES} or less): the
+ * memory signal alone — `none` while the memory gate refuses, `half` at memory
+ * hold, else `full`. CPU pressure never narrows it (T13132, T13170).
+ *
+ * @param sample - a backend sample.
+ * @param gateRefuses - the memory gate's verdict for the sample.
+ */
+export declare function lightBudgetShare(sample: ResourceSample, gateRefuses: boolean): BudgetShare;
+/**
+ * The budget share for HEAVY runs (above {@link HEAVY_FOOTPRINT_BYTES}), from
+ * the memory gate's verdict and the pressure score (memory, or CPU rescaled;
+ * see `pressureScore`). Light runs use {@link lightBudgetShare}.
+ *
+ * @param sample - a backend sample.
+ * @param gateRefuses - the memory gate's verdict for the sample.
+ */
+export declare function budgetShare(sample: ResourceSample, gateRefuses: boolean): BudgetShare;
+/** Inputs to one scheduling pass. */
+export interface PassContext {
+    /** The machine-wide budget in bytes. */
+    readonly capacityBytes: number;
+    /** What pressure leaves of it for heavy runs ({@link budgetShare}). */
+    readonly share: BudgetShare;
+    /**
+     * What memory pressure leaves of it for light runs ({@link lightBudgetShare}).
+     * @defaultValue `share`
+     */
+    readonly lightShare?: BudgetShare;
+    /** The clock. */
+    readonly nowMs: number;
+    /** @defaultValue {@link LEDGER_RESERVATION_MS} */
+    readonly reservationMs?: number;
+    /** Entries of an unknown format, counted as admitted with their charge. */
+    readonly foreign?: {
+        readonly bytes: number;
+        readonly count: number;
+    };
+}
+/**
+ * One scheduling pass: admit every waiting entry the budget and the queue
+ * order allow. Pure.
+ *
+ * - FIFO by `enqueuedAtMs`. A later entry may be admitted ahead of an older
+ *   one that does not fit (backfill) until that older one has waited
+ *   `reservationMs`; from then on nothing passes it.
+ * - A footprint above the capacity is charged the capacity (it runs alone).
+ * - Heavy runs (above {@link HEAVY_FOOTPRINT_BYTES}) take `share`: `half`
+ *   halves the budget, `one` admits a single heavy run at a time (CPU
+ *   saturated). Light runs take `lightShare` (memory alone), so CPU saturation
+ *   never serialises them behind a heavy run (T13132). Either still admits the
+ *   oldest waiting entry when nothing is admitted; `none` admits nothing.
+ *
+ * @param entries - the ledger.
+ * @param ctx - capacity, pressure share and clock.
+ * @returns the ledger with admissions applied (same order).
+ *
+ * @example
+ * ```ts
+ * schedulePass(entries, { capacityBytes: 36 * GIB, share: 'full', nowMs: Date.now() });
+ * ```
+ */
+export declare function schedulePass(entries: readonly LedgerEntry[], ctx: PassContext): LedgerEntry[];
+/**
+ * Split a {@link ADMISSION_ENV} value into its id and nonce, or `null`.
+ *
+ * @param value - the env value.
+ */
+export declare function parseAdmissionToken(value: string | undefined): {
+    id: string;
+    nonce: string;
+} | null;
+/** The process facts the re-entrancy check needs (tests inject them). */
+export interface ProcessFacts {
+    /** Ancestors of a pid, nearest first, or `null` when `ps` fails. */
+    readonly ancestorsOf: (pid: number) => readonly number[] | null;
+    /** Process group of a pid, or `null`. */
+    readonly groupOf: (pid: number) => number | null;
+    /** Start time of a pid (the ledger's format), or `null`. */
+    readonly startedAt: (pid: number) => string | null;
+}
+/**
+ * The admitted entry whose process tree `pid` belongs to, or `null`.
+ *
+ * Proof is ancestry: the holder is an ancestor of `pid`, with its recorded
+ * start time matching. A holder recorded without a start time (`ps` failed)
+ * proves nothing by ancestry alone, since its pid may have been recycled into
+ * an ancestor: it also needs the token to name it (T13188). The token in `env`
+ * only narrows which entry is checked
+ * first; a missing or foreign token falls back to checking every admitted
+ * entry by ancestry, so a wrapper that scrubs the environment cannot deadlock
+ * a nested run — except under a holder recorded without a start time, which
+ * needs the token: such a nested run waits for its own parent until it times
+ * out or the entry is reaped as unidentifiable ({@link LEDGER_ORPHAN_MS}). A
+ * rare case (`ps` failed at admission), and safer than letting a recycled pid
+ * ride a dead grant.
+ *
+ * Group membership (`pid` runs in a tool process group the holder started,
+ * which covers a tool that outlived a killed holder) is accepted only for the
+ * entry the token names on this host: a process group id carries no start
+ * time, so a recycled group id alone proves nothing.
+ *
+ * @param entries - the ledger.
+ * @param pid - the requesting process.
+ * @param env - its environment.
+ * @param facts - process probes (tests inject them).
+ */
+export declare function enclosingGrant(entries: readonly LedgerEntry[], pid: number, env: NodeJS.ProcessEnv, facts?: ProcessFacts): LedgerEntry | null;
+/** The {@link ADMISSION_ENV} value of an entry. */
+export declare function admissionToken(entry: Pick<LedgerEntry, 'id' | 'nonce'>): string;
+/**
+ * ` [scope=full, task T1043]` for an entry that says what it covers, else ''.
+ *
+ * @param e - a ledger entry.
+ */
+export declare function describeScope(e: Pick<LedgerEntry, 'scope' | 'task'>): string;
+/**
+ * One line per admitted run: label, scope and task, pid, command, directory and age.
+ *
+ * @param entries - the ledger.
+ * @param nowMs - the clock.
+ */
+export declare function describeHolders(entries: readonly LedgerEntry[], nowMs: number): string[];
+/**
+ * A suspected wait cycle through a lock outside CLEO: a holder's process tree
+ * and this waiter's ancestry run the same (non-generic) program, such as a
+ * wrapper script that takes its own lock. `null` when nothing points to one.
+ *
+ * @param pid - the waiting process.
+ * @param holders - admitted entries.
+ * @param table - the process table (`pid → {ppid, command}`).
+ */
+export declare function suspectCycle(pid: number, holders: readonly LedgerEntry[], table: ReadonlyMap<number, {
+    ppid: number;
+    command: string;
+}>): string | null;
+/** What a request asks for. */
+export interface AdmissionRequest {
+    /** What is running: `tool:test`, `run:test-run`, `probe:vitest-projects`. */
+    readonly label: string;
+    /** Bytes it needs (see {@link footprintForTool}, {@link footprintForClass}). */
+    readonly footprintBytes: number;
+    /** The command line, redacted. @defaultValue this process's argv */
+    readonly command?: string;
+    /** Working directory. @defaultValue process.cwd() */
+    readonly cwd?: string | null;
+    /** How much of the project it covers, for status (T13132). */
+    readonly scope?: AdmissionScope;
+    /** The CLEO task it is evidence for, for status (T13132). */
+    readonly task?: string;
+    /** Take the machine-wide exclusive slot (T13237: a `full-build`). */
+    readonly exclusive?: boolean;
+}
+/** How to wait, and where to report. */
+export interface AdmitOptions {
+    /** Wait in the queue (`true`) or return a deferral at once. */
+    readonly wait: boolean;
+    /** Give up after this long. @defaultValue 60 min */
+    readonly timeoutMs?: number;
+    /** Re-read cadence while waiting. @defaultValue 250 ms */
+    readonly pollMs?: number;
+    /**
+     * One pressure sample; a throw counts as no signal. A sampler given here is
+     * always called: it bypasses the verdict another process wrote to the
+     * ledger in the last 2 s, which the default reuses.
+     * @defaultValue a ResourceMonitor sample, or none under `CLEO_ADMISSION_PRESSURE=off`
+     */
+    readonly sample?: () => Promise<ResourceSample>;
+    /** The machine budget in bytes. @defaultValue {@link admissionCapacityBytes} */
+    readonly capacityBytes?: number;
+    /** The requester's environment (for {@link ADMISSION_ENV}). @defaultValue process.env */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Told while the memory gate holds the run back, and when it admits. */
+    readonly memoryPressure?: MemoryGateReporter;
+    /** Where the holder report goes while waiting. */
+    readonly notice?: (line: string) => void;
+    /** The ledger directory. @defaultValue {@link admissionDir} */
+    readonly dir?: string;
+    /** Process probes for re-entrancy (tests). */
+    readonly facts?: ProcessFacts;
+    /** Pid probe for liveness (tests). */
+    readonly probe?: PidProbe;
+    /** The requesting pid (tests). @defaultValue process.pid */
+    readonly pid?: number;
+    /** Clock (tests). @defaultValue Date.now */
+    readonly now?: () => number;
+    /** Wait (tests). @defaultValue setTimeout */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** An admission: the share is held until `release`. */
+export interface AdmissionGrant {
+    /** The ledger entry, or `null` for a pass-through (nested, off, ungoverned). */
+    readonly id: string | null;
+    /** The {@link ADMISSION_ENV} value to export to children; `''` when there is none. */
+    readonly token: string;
+    /** `true` when it rides an enclosing grant. */
+    readonly nested: boolean;
+    /** Set when the ledger could not be written here: the run proceeds ungoverned. */
+    readonly ungoverned: {
+        readonly code: string;
+        readonly path: string | null;
+    } | null;
+    /** How long it waited. */
+    readonly waitedMs: number;
+    /** Bytes charged. */
+    readonly footprintBytes: number;
+    /** Give the share back. Idempotent. */
+    release(): Promise<void>;
+}
+/** A refusal: nothing was started. */
+export interface AdmissionRefusal {
+    /** Why, with the numbers. */
+    readonly reason: string;
+    /** Back-off hint. */
+    readonly retryAfterMs: number;
+    /** The memory gate's readings when it was the reason. */
+    readonly memoryPressure: MemoryPressureReading | null;
+    /** Waiting runs ahead of this one. */
+    readonly ahead: number;
+    /** One line per admitted run. */
+    readonly holders: readonly string[];
+}
+/** {@link admit}'s result. */
+export type AdmissionOutcome = {
+    readonly admitted: true;
+    readonly grant: AdmissionGrant;
+} | {
+    readonly admitted: false;
+    readonly refusal: AdmissionRefusal;
+};
+/** Why admission state cannot be written: the errno code and the path, when known. */
+export interface AdmissionIoError {
+    readonly code: string;
+    readonly path: string | null;
+}
+/**
+ * The code and path of an error that means "admission state cannot be kept
+ * here" (a sandbox that blocks writes to the CLEO home, a read-only or full
+ * disk, a broken CLEO home), or `null` for any other error, which is a bug and
+ * must not be hidden.
+ *
+ * @param err - a caught error.
+ */
+export declare function admissionIoError(err: unknown): AdmissionIoError | null;
+/**
+ * Why a run is ungoverned, in words: `admission state is not writable (EACCES
+ * /path)`, or, for a ledger a newer CLEO wrote, that this CLEO will not
+ * rewrite it. Callers append what they do about it.
+ *
+ * @param io - from {@link admissionIoError} or a grant's `ungoverned`.
+ */
+export declare function describeAdmissionIoError(io: AdmissionIoError): string;
+/**
+ * Ask the ledger for a share of the machine budget.
+ *
+ * `CLEO_RESOURCES_MODE=off` admits everything. Re-entrant: inside an admitted
+ * run's process tree it returns a pass-through grant at once. Otherwise it joins the FIFO queue; with `wait: false` it
+ * leaves again unless admitted on the spot, and with `wait: true` it waits
+ * (reporting memory-pressure waits and, after a minute, the holders and any
+ * suspected cycle) until admitted or `timeoutMs`. Never throws for admission
+ * control. An unwritable ledger, or one written by a newer CLEO, is a
+ * pass-through grant with `ungoverned` set (callers say so with
+ * {@link describeAdmissionIoError}); any other error propagates.
+ *
+ * @param req - what is asked for.
+ * @param opts - waiting and reporting.
+ *
+ * @example
+ * ```ts
+ * const out = await admit({ label: 'tool:test', footprintBytes: footprintForTool('test') }, { wait: true });
+ * if (out.admitted) {
+ *   try { await run({ env: { [ADMISSION_ENV]: out.grant.token } }); } finally { await out.grant.release(); }
+ * }
+ * ```
+ */
+export declare function admit(req: AdmissionRequest, opts: AdmitOptions): Promise<AdmissionOutcome>;
+/** Remove the ledger file (tests). @internal */
+export declare function _resetAdmissionLedgerForTest(dir?: string): void;
+/**
+ * Drop every entry whose holder is provably gone, and schedule. For
+ * `cleo doctor tool-locks --reap`; admission does this on every pass.
+ *
+ * @param opts - ledger directory, capacity and probes (tests).
+ * @returns the ids removed (entries of another CLEO version included).
+ */
+export declare function reapLedger(opts?: Pick<AdmitOptions, 'dir' | 'capacityBytes' | 'probe' | 'now' | 'sample'>): Promise<string[]>;
+/**
+ * Remove one entry by id, whatever its liveness, and schedule. For
+ * `cleo doctor tool-locks --remove <id>`, when an entry cannot be proven dead
+ * (its holder is unidentifiable) but the operator knows it is.
+ *
+ * @param id - the entry id (as `cleo doctor tool-locks` lists it).
+ * @param opts - ledger directory, capacity and probes (tests).
+ * @returns whether an entry was removed.
+ */
+export declare function removeLedgerEntry(id: string, opts?: Pick<AdmitOptions, 'dir' | 'capacityBytes' | 'now' | 'sample'>): Promise<boolean>;
+//# sourceMappingURL=admission-ledger.d.ts.map

package/dist/resources/admission-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission-ledger.d.ts","sourceRoot":"","sources":["../../src/resources/admission-ledger.ts"],"names":[],"mappings":"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"}