@cleocode/core 2026.10.1 → 2026.10.2

package/dist/resources/darwin-backend.js

@@ -0,0 +1,288 @@
+/**
+ * macOS ResourceMonitor backend.
+ *
+ * macOS has no PSI. This backend maps the kernel's own signals onto the
+ * PSI-shaped {@link ResourceSample}, so `evaluateState` and the slot scaling
+ * work unchanged:
+ *
+ *   - `kern.memorystatus_vm_pressure_level` — the kernel's memory pressure
+ *     verdict (1 normal, 2 warning, 4 critical), the signal jetsam acts on
+ *   - `kern.memorystatus_level` — free memory as a percentage of RAM, counting
+ *     reclaimable pages (unlike `os.freemem()`, which reports only the free
+ *     page list and reads near zero on a healthy Mac)
+ *   - `vm.swapusage` — swap in use (reported, not scored: macOS allocates
+ *     swapfiles on demand, so used/total sits at 80–95% on a healthy Mac)
+ *   - `vm.loadavg` + `hw.perflevel{0,1}.logicalcpu` (or `hw.ncpu`) —
+ *     run-queue length per effective core (CPU saturation)
+ *
+ * ## Sampling discipline (darwin amendment)
+ *
+ * Node has no sysctl binding, so `sample()` runs ONE `/usr/sbin/sysctl` exec
+ * (≈4 ms) for all names, and caches its output for `cacheTtlMs` (default 2 s)
+ * across every backend instance in the process. A poll loop or a burst of
+ * admissions therefore spawns at most one child per TTL. No other process or
+ * file read happens on the sample path; `sweepChildRss` (low frequency) uses
+ * `ps`.
+ *
+ * ## Mapping
+ *
+ * Memory (`globalPressure`): `some avg10` is the higher of a kernel-level score
+ * (warning 15, critical 40) and a free-memory score (`2 × (20 − free%)`,
+ * clamped at 0). `full avg10` is
+ * 15 when the kernel reports critical. With the monitor's default thresholds
+ * (hold 10 / backoff 20), a kernel warning holds and critical backs off.
+ *
+ * CPU (`cpuPressure`): effective cores are performance cores plus half the
+ * efficiency cores (a 6P+12E machine counts as 12; `hw.ncpu` when the split is
+ * unknown). With `r = load / cores`, `some = 100 × (r − 1) / r`
+ * once `r > 1`: the share of runnable work that is waiting for a core. A box
+ * running twice its cores scores 50. avg10/avg60/avg300 come from the 1/5/15
+ * minute load averages. Memory is instantaneous in all three windows.
+ *
+ * @module resources/darwin-backend
+ * @task T12981
+ * @epic T12978
+ */
+import { execFile } from 'node:child_process';
+import { totalmem } from 'node:os';
+/** The sysctl names one sample reads, in one exec. */
+export const DARWIN_SYSCTL_NAMES = [
+    'kern.memorystatus_vm_pressure_level',
+    'kern.memorystatus_level',
+    'vm.swapusage',
+    'vm.loadavg',
+    'hw.ncpu',
+    'hw.perflevel0.logicalcpu',
+    'hw.perflevel1.logicalcpu',
+];
+const MIB = 1024 * 1024;
+function parseSize(value) {
+    const m = /^([\d.]+)([KMGT])?$/.exec(value.trim());
+    if (!m?.[1])
+        return null;
+    const n = Number.parseFloat(m[1]);
+    const unit = { K: 1024, M: MIB, G: 1024 * MIB, T: 1024 * 1024 * MIB }[m[2] ?? ''] ?? 1;
+    return Number.isFinite(n) ? n * unit : null;
+}
+/**
+ * Parse `sysctl <names>` output (`name: value` per line).
+ *
+ * @example
+ * ```ts
+ * parseDarwinSysctl('kern.memorystatus_vm_pressure_level: 2\nhw.ncpu: 18\n');
+ * // → { pressureLevel: 2, ncpu: 18, freePercent: null, ... }
+ * ```
+ */
+export function parseDarwinSysctl(output) {
+    const values = new Map();
+    for (const line of output.split('\n')) {
+        const idx = line.indexOf(':');
+        if (idx <= 0)
+            continue;
+        values.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+    }
+    const int = (name) => {
+        const raw = values.get(name);
+        if (raw === undefined || !/^-?\d+$/.test(raw))
+            return null;
+        return Number.parseInt(raw, 10);
+    };
+    let swapTotalBytes = null;
+    let swapUsedBytes = null;
+    const swap = values.get('vm.swapusage');
+    if (swap) {
+        swapTotalBytes = parseSize(/total = (\S+)/.exec(swap)?.[1] ?? '');
+        swapUsedBytes = parseSize(/used = (\S+)/.exec(swap)?.[1] ?? '');
+    }
+    let loadAvg = null;
+    const load = values.get('vm.loadavg');
+    if (load) {
+        const nums = load
+            .replace(/[{}]/g, ' ')
+            .trim()
+            .split(/\s+/)
+            .map((s) => Number.parseFloat(s));
+        if (nums.length >= 3 && nums.slice(0, 3).every(Number.isFinite)) {
+            loadAvg = [nums[0], nums[1], nums[2]];
+        }
+    }
+    return {
+        pressureLevel: int('kern.memorystatus_vm_pressure_level'),
+        freePercent: int('kern.memorystatus_level'),
+        swapTotalBytes,
+        swapUsedBytes,
+        loadAvg,
+        ncpu: int('hw.ncpu'),
+        perfCores: int('hw.perflevel0.logicalcpu'),
+        efficiencyCores: int('hw.perflevel1.logicalcpu'),
+    };
+}
+function clamp(n) {
+    return Math.max(0, Math.min(100, n));
+}
+/**
+ * Memory pressure score (PSI `some`-equivalent, 0–100) from darwin signals.
+ * Returns `null` when neither the kernel level nor free% is readable.
+ */
+export function darwinMemorySome(s) {
+    if (s.pressureLevel === null && s.freePercent === null)
+        return null;
+    const levelScore = s.pressureLevel === 4 ? 40 : s.pressureLevel === 2 ? 15 : 0;
+    const freeScore = s.freePercent === null ? 0 : Math.max(0, 2 * (20 - s.freePercent));
+    return clamp(Math.max(levelScore, freeScore));
+}
+/**
+ * Cores that absorb load: performance cores plus half the efficiency cores,
+ * else `hw.ncpu`. `null` when neither is known.
+ */
+export function effectiveCores(s) {
+    if (s.perfCores !== null && s.perfCores > 0) {
+        return s.perfCores + (s.efficiencyCores ?? 0) / 2;
+    }
+    return s.ncpu;
+}
+/** CPU waiting share (0–100) for a load average on `ncpu` cores. */
+export function cpuSomeFromLoad(load, ncpu) {
+    const r = load / Math.max(1, ncpu);
+    return r <= 1 ? 0 : clamp((100 * (r - 1)) / r);
+}
+function line(avg10, avg60, avg300) {
+    return { avg10, avg60, avg300, totalUs: 0 };
+}
+/** Build the memory and CPU PSI-equivalents from parsed signals. */
+export function darwinPressure(s) {
+    const some = darwinMemorySome(s);
+    const memory = some === null
+        ? null
+        : {
+            some: line(some, some, some),
+            full: s.pressureLevel === 4 ? line(15, 15, 15) : line(0, 0, 0),
+        };
+    let cpu = null;
+    const cores = effectiveCores(s);
+    if (s.loadAvg && cores) {
+        const [l1, l5, l15] = s.loadAvg;
+        cpu = {
+            some: line(cpuSomeFromLoad(l1, cores), cpuSomeFromLoad(l5, cores), cpuSomeFromLoad(l15, cores)),
+            full: null,
+        };
+    }
+    return { memory, cpu };
+}
+const defaultSysctl = (names) => new Promise((resolve, reject) => {
+    execFile('/usr/sbin/sysctl', [...names], { timeout: 2000 }, (err, stdout) => {
+        // sysctl exits non-zero when ONE name is unknown but still prints the
+        // others; keep whatever it printed.
+        if (stdout)
+            resolve(stdout);
+        else
+            reject(err ?? new Error('sysctl produced no output'));
+    });
+});
+const defaultPsRss = (pids) => new Promise((resolve) => {
+    execFile('/bin/ps', ['-o', 'pid=,rss=', '-p', pids.join(',')], { timeout: 2000 }, (_err, stdout) => resolve(stdout ?? ''));
+});
+const defaultStat = async (path) => {
+    const { stat } = await import('node:fs/promises');
+    try {
+        return { size: (await stat(path)).size };
+    }
+    catch {
+        return null;
+    }
+};
+/** Process-wide cache of the default sysctl read. */
+let sharedRead = null;
+/** Reset the process-wide sysctl cache (tests). @internal */
+export function resetDarwinSysctlCache() {
+    sharedRead = null;
+}
+/**
+ * macOS implementation of {@link ResourceBackend}.
+ *
+ * `pressureAvailable` is `true` when the kernel memory signals were readable,
+ * so `evaluateState` uses the PSI path rather than degraded mode.
+ */
+export class DarwinResourceBackend {
+    walPaths;
+    cacheTtlMs;
+    sysctlFn;
+    psRssFn;
+    statFileFn;
+    totalMemBytes;
+    now;
+    local = null;
+    constructor(opts = {}) {
+        this.walPaths = opts.walPaths ?? [];
+        this.cacheTtlMs = opts.cacheTtlMs ?? 2000;
+        this.sysctlFn = opts.sysctlFn ?? null;
+        this.psRssFn = opts.psRssFn ?? defaultPsRss;
+        this.statFileFn = opts.statFileFn ?? defaultStat;
+        this.totalMemBytes = opts.totalMemBytes ?? totalmem();
+        this.now = opts.now ?? Date.now;
+    }
+    /** At most one sysctl exec per TTL; on failure the sample is degraded. */
+    async sample() {
+        const sampledAtMs = this.now();
+        let signals = null;
+        try {
+            signals = parseDarwinSysctl(await this.readSysctl(sampledAtMs));
+        }
+        catch {
+            signals = null;
+        }
+        const { memory, cpu } = signals ? darwinPressure(signals) : { memory: null, cpu: null };
+        const memAvailableBytes = signals?.freePercent != null
+            ? Math.round((signals.freePercent / 100) * this.totalMemBytes)
+            : null;
+        const walObservations = [];
+        for (const walPath of this.walPaths) {
+            const info = await this.statFileFn(walPath);
+            walObservations.push({ walPath, sizeBytes: info?.size ?? null });
+        }
+        return {
+            sampledAtMs,
+            pressureAvailable: memory !== null,
+            memAvailableBytes,
+            globalPressure: memory,
+            slicePressure: null,
+            cpuPressure: cpu,
+            walObservations,
+        };
+    }
+    /** RSS via one `ps` exec (no PSS on macOS: `pssBytes` mirrors RSS). */
+    async sweepChildRss(pids) {
+        const sampledAtMs = this.now();
+        const wanted = pids.filter((p) => Number.isInteger(p) && p > 0);
+        if (wanted.length === 0)
+            return { sampledAtMs, entries: [] };
+        const entries = [];
+        for (const row of (await this.psRssFn(wanted)).split('\n')) {
+            const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(row);
+            if (!m?.[1] || !m[2])
+                continue;
+            const rssBytes = Number.parseInt(m[2], 10) * 1024;
+            entries.push({ pid: Number.parseInt(m[1], 10), rssBytes, pssBytes: rssBytes });
+        }
+        return { sampledAtMs, entries };
+    }
+    readSysctl(at) {
+        const fresh = (c) => c !== null && at - c.at < this.cacheTtlMs && at >= c.at;
+        if (this.sysctlFn) {
+            if (!fresh(this.local))
+                this.local = { at, output: this.sysctlFn(DARWIN_SYSCTL_NAMES) };
+            return this.local.output;
+        }
+        if (!fresh(sharedRead)) {
+            const output = defaultSysctl(DARWIN_SYSCTL_NAMES);
+            // A failed read must not be cached for the whole TTL.
+            output.catch(() => {
+                if (sharedRead?.output === output)
+                    sharedRead = null;
+            });
+            sharedRead = { at, output };
+        }
+        return sharedRead.output;
+    }
+}
+//# sourceMappingURL=darwin-backend.js.map

package/dist/resources/darwin-backend.js.map

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

package/dist/resources/governor.d.ts

@@ -20,11 +20,16 @@
  * `interactive-cli` is NEVER gated; `full-build` is pinned to one machine-wide
  * slot regardless of pressure.
  *
+ * A local slot whose holder process is provably gone is reaped at once instead
+ * of waiting out the 10 min stale timeout (T12963), as the tool semaphore does
+ * for its slots (gh#1222).
+ *
  * @task T11999
+ * @task T12963
  * @epic T11992
  * @adr resource-governor-never-oom-architecture §3.4
  */
-import { type AdmissionResult, type GovernorMode, type ResourceClass } from '@cleocode/contracts';
+import { type AdmissionResult, type GovernorMode, type ResourceClass, type ResourceGrant } from '@cleocode/contracts';
 import type { ResourceSample } from './backend.js';
 import { ResourceMonitor } from './monitor.js';
 /**
@@ -86,6 +91,38 @@ export declare function computeClassBudget(cls: ResourceClass, sample: ResourceS
  * and PIDs — exactly like the tool semaphore.
  */
 export declare function governorSlotDir(cls: ResourceClass): string;
+export { SLOT_LOCK_STALE_MS, SLOT_LOCK_UPDATE_MS } from './slot-holder.js';
+/** An ungated grant (no slot held, `slot: -1`): `off` mode, `interactive-cli`, a nested run, fail-open. */
+export declare function passThroughGrant(cls: ResourceClass): ResourceGrant;
+/** Why the governor could not keep its state: the errno code and the path, when known. */
+export interface GovernorIoError {
+    readonly code: string;
+    readonly path: string | null;
+}
+/**
+ * The code and path of an error that means "the governor cannot keep state 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.
+ */
+export declare function governorIoError(err: unknown): GovernorIoError | null;
+/**
+ * Run an admission, failing OPEN when the governor cannot write its state
+ * ({@link governorIoError}): the work proceeds ungated with a
+ * {@link passThroughGrant}, and `ungoverned` says why. A sandboxed or
+ * read-only CLEO home must never turn into a deferral that never clears.
+ * Any other error is a bug and propagates.
+ *
+ * @example
+ * ```ts
+ * const { admission, ungoverned } = await admitFailOpen('agent-session', () =>
+ *   governor.tryAcquire('agent-session'),
+ * );
+ * ```
+ */
+export declare function admitFailOpen(cls: ResourceClass, acquire: () => Promise<AdmissionResult>): Promise<{
+    readonly admission: AdmissionResult;
+    readonly ungoverned: GovernorIoError | null;
+}>;
 /** Options for {@link ResourceGovernor.acquire}. */
 export interface AcquireOptions extends BudgetOptions {
     /**
@@ -117,6 +154,12 @@ export declare class ResourceGovernor {
      * Acquire one slot of `cls`. Returns a {@link ResourceGrant} on success or a
      * {@link ResourceDeferral} on denial. Never throws for admission control;
      * only genuinely unexpected I/O errors propagate.
+     *
+     * Only a held lock (`ELOCKED`) counts as a busy slot. Any other lock error
+     * (EACCES from a sandbox that can't write the slot dir, EROFS, ENOSPC…) is
+     * thrown once a pass found no free slot, never read as "busy": a slot that
+     * can never be taken would otherwise defer every caller until it times out
+     * (#1777 round 8, R8-1). Callers fail open with {@link admitFailOpen}.
      */
     acquire(cls: ResourceClass, opts?: AcquireOptions): Promise<AdmissionResult>;
     /**

package/dist/resources/governor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/resources/governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAoB/C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAKlD;AAgBD;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAMD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,aAAkB,GACvB,MAAM,CA8CR;AAUD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAE1D;AA6CD,oDAAoD;AACpD,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgFtF;;;;;;;OAOG;YACW,oBAAoB;IAkClC,8DAA8D;IACxD,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIzF;;;OAGG;IACG,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAWhF;AAqCD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAIxD;AAED,uCAAuC;AACvC,eAAO,MAAM,QAAQ,kBAAyB,CAAC"}
+{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/resources/governor.ts"],"names":[],"mappings":"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"}

package/dist/resources/governor.js

@@ -20,7 +20,12 @@
  * `interactive-cli` is NEVER gated; `full-build` is pinned to one machine-wide
  * slot regardless of pressure.
  *
+ * A local slot whose holder process is provably gone is reaped at once instead
+ * of waiting out the 10 min stale timeout (T12963), as the tool semaphore does
+ * for its slots (gh#1222).
+ *
  * @task T11999
+ * @task T12963
  * @epic T11992
  * @adr resource-governor-never-oom-architecture §3.4
  */
@@ -28,10 +33,11 @@ import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { availableParallelism, totalmem } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_RESOURCE_RETRY_AFTER_MS, } from '@cleocode/contracts';
-import lockfile from 'proper-lockfile';
 import { getLogger } from '../logger.js';
 import { getCleoHome } from '../paths.js';
-import { ResourceMonitor } from './monitor.js';
+import { pressureScore, ResourceMonitor } from './monitor.js';
+import { parentRunJob } from './run-admission.js';
+import { _resetSlotHolderStateForTest, describeSlotHolders, lockSlot } from './slot-holder.js';
 import { resolveSupervisorSocketPath, sendResourceAdmit, sendResourceRelease, } from './supervisor-admit.js';
 let _log = null;
 function log() {
@@ -77,12 +83,13 @@ function logSupervisorDegradeOnce(reason) {
 export function _resetGovernorStateForTest() {
     _cachedMode = null;
     _supervisorDegradeLogged = false;
+    _resetSlotHolderStateForTest();
 }
 const MB = 1024 * 1024;
 /** Extract `some avg10` (0–100) from a sample; 0 when unavailable. */
 function someAvg10(sample) {
-    const some = sample.globalPressure?.some ?? sample.slicePressure?.some;
-    return some?.avg10 ?? 0;
+    // T12981: memory or CPU, whichever is worse (CPU rescaled to this scale).
+    return pressureScore(sample);
 }
 /**
  * Compute the slot budget for a class given a point-sample.
@@ -173,11 +180,14 @@ function ensureSlotFiles(dir, count) {
     }
     return paths;
 }
-const STALE_MS = 600_000;
+// The slot timing constants live with the slot locks (T12963); re-exported
+// for existing importers.
+export { SLOT_LOCK_STALE_MS, SLOT_LOCK_UPDATE_MS } from './slot-holder.js';
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-function passThroughGrant(cls) {
+/** An ungated grant (no slot held, `slot: -1`): `off` mode, `interactive-cli`, a nested run, fail-open. */
+export function passThroughGrant(cls) {
     return {
         deferred: false,
         class: cls,
@@ -189,6 +199,54 @@ function passThroughGrant(cls) {
 function deferral(cls, reason, retryAfterMs) {
     return { deferred: true, class: cls, retryAfterMs, reason };
 }
+/** Filesystem errors meaning the governor's state can't be written here. */
+const GOVERNOR_IO_CODES = new Set([
+    'EACCES',
+    'EPERM',
+    'EROFS',
+    'ENOSPC',
+    'EDQUOT',
+    'ENOTDIR',
+    'ELOOP',
+]);
+/**
+ * The code and path of an error that means "the governor cannot keep state 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.
+ */
+export function governorIoError(err) {
+    const e = err;
+    if (!e || typeof e !== 'object' || typeof e.code !== 'string')
+        return null;
+    if (!GOVERNOR_IO_CODES.has(e.code))
+        return null;
+    return { code: e.code, path: typeof e.path === 'string' ? e.path : null };
+}
+/**
+ * Run an admission, failing OPEN when the governor cannot write its state
+ * ({@link governorIoError}): the work proceeds ungated with a
+ * {@link passThroughGrant}, and `ungoverned` says why. A sandboxed or
+ * read-only CLEO home must never turn into a deferral that never clears.
+ * Any other error is a bug and propagates.
+ *
+ * @example
+ * ```ts
+ * const { admission, ungoverned } = await admitFailOpen('agent-session', () =>
+ *   governor.tryAcquire('agent-session'),
+ * );
+ * ```
+ */
+export async function admitFailOpen(cls, acquire) {
+    try {
+        return { admission: await acquire(), ungoverned: null };
+    }
+    catch (err) {
+        const io = governorIoError(err);
+        if (io === null)
+            throw err;
+        return { admission: passThroughGrant(cls), ungoverned: io };
+    }
+}
 let _supervisorHolderSeq = 0;
 /**
  * A process-unique holder id for a supervisor `resource_admit`, so each acquire
@@ -209,6 +267,12 @@ export class ResourceGovernor {
      * Acquire one slot of `cls`. Returns a {@link ResourceGrant} on success or a
      * {@link ResourceDeferral} on denial. Never throws for admission control;
      * only genuinely unexpected I/O errors propagate.
+     *
+     * Only a held lock (`ELOCKED`) counts as a busy slot. Any other lock error
+     * (EACCES from a sandbox that can't write the slot dir, EROFS, ENOSPC…) is
+     * thrown once a pass found no free slot, never read as "busy": a slot that
+     * can never be taken would otherwise defer every caller until it times out
+     * (#1777 round 8, R8-1). Callers fail open with {@link admitFailOpen}.
      */
     async acquire(cls, opts = {}) {
         // Ungated fast paths: off mode + interactive-cli are pure pass-through.
@@ -216,6 +280,15 @@ export class ResourceGovernor {
         if (mode === 'off' || cls === 'interactive-cli') {
             return passThroughGrant(cls);
         }
+        // Inside a running `cleo run` job (e.g. `cleo run -- cleo verify`), the
+        // job's slot already covers this process tree: waiting for another slot
+        // of a budget-1 class would wait on ourselves (#1777 round 3, M-2). The
+        // env var only says "look"; parentRunJob's group + start-time check is
+        // what decides, so setting it by hand grants nothing.
+        // Only a parent holding THIS class covers it (#1777 round 4, MED-1).
+        if (process.env.CLEO_RUN_CLASS !== undefined && parentRunJob({ pid: process.pid, cls })) {
+            return passThroughGrant(cls);
+        }
         const sample = opts.sample ?? (await (opts.monitor ?? new ResourceMonitor()).sample());
         const budget = computeClassBudget(cls, sample, opts);
         if (!Number.isFinite(budget))
@@ -242,45 +315,32 @@ export class ResourceGovernor {
         do {
             // Re-shuffle each pass so concurrent acquirers don't collide on slot 0.
             const order = shuffledIndices(slots.length);
+            let lockError = null;
             for (const idx of order) {
                 const path = slots[idx];
                 if (!path)
                     continue;
                 try {
-                    const release = await lockfile.lock(path, {
-                        retries: 0,
-                        stale: STALE_MS,
-                        realpath: false,
-                    });
-                    let released = false;
-                    return {
-                        deferred: false,
-                        class: cls,
-                        slot: idx,
-                        acquiredAtMs: Date.now(),
-                        release: async () => {
-                            if (released)
-                                return;
-                            released = true;
-                            try {
-                                await release();
-                            }
-                            catch {
-                                // Already released (e.g. stale recovery) — post-condition holds.
-                            }
-                        },
-                    };
+                    // T12963: a busy slot whose holder is provably dead is reaped here.
+                    const release = await lockSlot(path, cls);
+                    if (release) {
+                        return { deferred: false, class: cls, slot: idx, acquiredAtMs: Date.now(), release };
+                    }
                 }
-                catch {
-                    // slot busy — try next
+                catch (err) {
+                    // Anything but a held lock is not "busy" (#1777 round 8, R8-1).
+                    lockError ??= { err };
                 }
             }
+            if (lockError !== null)
+                throw lockError.err;
             if (!blocking)
                 break;
             await sleep(pollMs);
         } while (Date.now() - startedAt < timeoutMs);
         return deferral(cls, `class '${cls}' is at capacity (${budget} slot(s)); ` +
-            (blocking ? `timed out after ${timeoutMs}ms` : 'no slot free'), Math.min(pollMs * 4, DEFAULT_RESOURCE_RETRY_AFTER_MS));
+            (blocking ? `timed out after ${timeoutMs}ms` : 'no slot free') +
+            describeSlotHolders(slots), Math.min(pollMs * 4, DEFAULT_RESOURCE_RETRY_AFTER_MS));
     }
     /**
      * Route an admission through the supervisor's central `resource_admit` verb.
@@ -355,7 +415,8 @@ function shuffledIndices(n) {
 /**
  * Count how many of `budget` slots are currently held, by probing each with a
  * non-blocking lock. A successful probe-lock is released immediately — it never
- * holds the slot, so it cannot starve a real acquirer.
+ * holds the slot, so it cannot starve a real acquirer. A slot held by a dead
+ * process is reaped, not counted (T12963).
  */
 async function countHeldSlots(cls, budget) {
     const dir = governorSlotDir(cls);
@@ -365,11 +426,14 @@ async function countHeldSlots(cls, budget) {
     let held = 0;
     for (const path of slots) {
         try {
-            const release = await lockfile.lock(path, { retries: 0, stale: STALE_MS, realpath: false });
-            await release();
+            const release = await lockSlot(path, cls);
+            if (release)
+                await release();
+            else
+                held++;
         }
         catch {
-            held++;
+            // Only a held lock is a holder; an unwritable slot dir is not (R8-1).
         }
     }
     return held;