@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/session-cage.js

@@ -0,0 +1,1183 @@
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { runnerIdentity, systemdUserEnv } from './environment.js';
+import { log } from './log.js';
+import { DEVBRIDGE_SLICE, memoryPolicy, readMemoryFacts, readSelfCgroup, readSwapTotalBytes, SESSION_CPU_WEIGHT, SESSIONS_SLICE, SESSIONS_SWAP_SHARE, sliceCgroupPath, } from './service-unit.js';
+const execFileAsync = promisify(execFile);
+/**
+ * A cgroup of its own for every agent session — the memory ceiling that
+ * `process-priority.ts` cannot give.
+ *
+ * Stage 1a (`process-priority.ts`) orders the CPU and nothing else. Memory is
+ * the mechanism behind three of the four incidents on other people's machines:
+ * one session allocates until the machine swaps itself to a standstill, and the
+ * only thing that ever stopped it was the ceiling on the WHOLE service — which
+ * kills whichever child the kernel picks, not the one that misbehaved. This
+ * module puts each session in `devbridge-session-<id>.scope` under
+ * `devbridge-sessions.slice`, so the session that runs out of memory is the
+ * session that dies, and its neighbours never notice.
+ *
+ * Every line below is a finding of the spike of 2026-09-07 (plan
+ * `agent-sessions-host-resources.md` §5.4.1), not a preference. The ones that
+ * cost the most to learn:
+ *
+ *  - `MemorySwapMax` is BOUNDED, never unset. Without a bound there is no cage:
+ *    a process under `MemoryMax=200M` allocated 2 GB and drained the host's
+ *    entire swap (`memory.events` read `max 0, oom_kill 0`, swap 2047/2047 MB)
+ *    — the exact incident this whole plan exists to prevent, reproduced by the
+ *    supposed fix. `MemoryMax` bounds RESIDENT memory; the rest goes to swap,
+ *    and swap belongs to the machine, not to the cgroup. 0.54.0 wrote `0`;
+ *    since #387 it is a SHARE of the machine's swap (see
+ *    {@link sessionSwapMaxBytes}), because without any swap the brake below
+ *    has nothing to push pages into and stalls instead of slowing.
+ *  - `MemoryHigh` UNDER `MemoryMax`, and far under it (#387). 0.54.0 shipped
+ *    the hard line alone, at 2.5 GiB, with systemd's default `OOMPolicy=stop`:
+ *    an honest `pnpm typecheck` (seven `tsc` at ~400 MB each) went over it, the
+ *    kernel killed ONE `tsc`, and systemd then stopped the WHOLE scope — the
+ *    session died with «exited with code 143», twice in an hour, on correct
+ *    work. The owner's rule is that honest work never reaches a kill: the
+ *    honest share is where the brake starts, the wall is the machine's measured
+ *    headroom, and only a real runaway ever gets that far — and then
+ *    `OOMPolicy=continue` costs it the one process, not the session.
+ *    The spike's «60 s in, still alive at 100 MB» under `MemoryHigh` was a
+ *    runaway with NO swap to be pushed into — that is the kernel's penalty
+ *    (up to 2 s per 256 KB when nothing can be reclaimed), and it is why the
+ *    swap share above is part of the same change, not a separate one.
+ *  - no `--collect`. A scope killed by the OOM killer stays behind in `failed`,
+ *    and `systemctl --user show <unit> -p Result` is the ONLY place the cause
+ *    can be read: `Result=oom-kill`. `--collect` deletes the unit the instant it
+ *    dies and takes the reason with it. Hence the order in
+ *    {@link releaseSessionScope}: wait for the exit, read `Result`, log it, THEN
+ *    `reset-failed`.
+ *  - `--expand-environment=no`, but ONLY on systemd ≥ 254. The arguments carry
+ *    the agent's prompt, and prompts contain `$`; without this flag a future
+ *    systemd would substitute variables into the user's own words. systemd 254
+ *    is where the switch was added, and it is also where its own NEWS says
+ *    expansion «defaults to enabled for all execution types except `--scope`,
+ *    where it defaults to off … for backward compatibility reasons». So on
+ *    Ubuntu 22.04 (249), Debian 12 and RHEL 9 (252) the flag is both rejected
+ *    (`unrecognized option`, exit 1, nothing spawned) and unnecessary. Passing
+ *    it unconditionally cost those machines the cage entirely
+ *    (QA-2026-09-07 MAJOR-2).
+ *  - `--pty` is not compatible with `--scope` ("--pty/--pipe is not compatible
+ *    in timer or --scope mode."), and does not need to be: the sign-in relay's
+ *    `script -qec` runs INSIDE the scope byte for byte the same. `auth-relay.ts`
+ *    is untouched by this module.
+ *  - `CPUWeight` is set on the scope AND on `devbridge.slice`
+ *    (`service-unit.ts`). The moment sessions leave the service's own cgroup,
+ *    `nice(2)` stops protecting the daemon from its own children — nice orders
+ *    tasks WITHIN one cgroup, and across cgroups `cpu.weight` decides, which is
+ *    100 everywhere by default. A cage without that drop-in would quietly undo
+ *    stage 1a and bring back 16.08: daemon starved, four missed pongs, server
+ *    Offline, 504 on every session.
+ *
+ * Rejected in the spike: `Delegate=yes` on the service plus the runner sorting
+ * PIDs into child cgroups itself. cgroup v2's "no internal processes" rule
+ * answers `Device or resource busy` on `cgroup.subtree_control`, the way around
+ * it moves the daemon into a sub-cgroup and needs a unit change and a RESTART
+ * (which kills every live session), and the spawn-then-move order lost the race
+ * anyway — the runaway was 100–150 MB in before it ever reached the cage.
+ */
+const MIB = 1024 * 1024;
+const GIB = 1024 * MIB;
+/**
+ * The honest share of one session — where the BRAKE starts, not where it dies.
+ *
+ * Until #387 this was `MemoryMax`, the kill line. It is the same number and the
+ * same reasoning, moved one step down the ladder: above it the kernel reclaims
+ * and throttles (`MemoryHigh`), and the kill line is {@link sessionMemoryMaxBytes}.
+ *
+ * `min(2.5 GiB, service ceiling / 2)` — §3 of
+ * `docs/plans/shipped/agent-sessions-host-resources.md`. Both halves matter:
+ *
+ *  - the absolute number is sized against the measurement, not against a round
+ *    figure. The heaviest ordinary thing a session runs is a workspace
+ *    `pnpm typecheck`, measured at a 1571 MB peak; three live `claude`
+ *    processes are 512/577/646 MB. 2.5 GiB leaves ~60 % headroom over the
+ *    worst measured case, which is the margin between "kills a runaway" and
+ *    "kills the work";
+ *  - the half-of-the-service half is what keeps ONE session from being able to
+ *    fill the ceiling that covers all of them. On this machine the service
+ *    ceiling is 7680M, so half is 3.75 GiB and the absolute number wins.
+ *
+ * The service ceiling is read off systemd (`systemctl --user show
+ * devbridge-runner -p MemoryMax`) rather than recomputed here, because what
+ * protects the machine is what systemd has in force, not what the drop-in on
+ * disk says — those two have already drifted apart once (§5.5 of the plan).
+ */
+export const SESSION_MEMORY_HIGH_ABSOLUTE_BYTES = Math.round(2.5 * GIB);
+/**
+ * Processes and threads per session.
+ *
+ * An agent forks a lot (a monorepo build is hundreds of short-lived processes),
+ * so this is not a memory limit in disguise — it is the fork-bomb stop. 512 is
+ * far above anything measured on a real session and far below the 8192 the
+ * whole service gets.
+ */
+export const SESSION_TASKS_MAX = 512;
+/** Prefix of every scope this module creates. The sweeper matches on it. */
+export const SESSION_SCOPE_PREFIX = 'devbridge-session-';
+/**
+ * The FLOOR the plan's formula does not have, and the reason it needs one.
+ *
+ * `min(2.5 GiB, ceiling / 2)` is right on a big machine and wrong on a small
+ * one: at the 2 GiB ceiling `memoryPolicy` gives the smallest supported box,
+ * half is 1 GiB — BELOW the 1571 MB a workspace `pnpm typecheck` was measured
+ * at. The cage would then kill honest work on exactly the machines least able
+ * to afford a failed run, and it would look like a flaky agent rather than a
+ * limit. A containment that fires on correct work is not containment.
+ *
+ * So the floor is set above the worst measured ordinary peak, not at a round
+ * number.
+ *
+ * It is a floor and not a switch: below ~2.4 GB of RAM the containing ceiling
+ * itself drops under this number, and there the last clamp in
+ * {@link sessionMemoryMaxBytes} wins and a session is capped below the floor.
+ * That is not the cage killing honest work — the slice would have killed the
+ * same `pnpm typecheck` a moment later anyway, because it holds the same
+ * number — so removing `MemoryMax` from the scope there would buy nothing and
+ * cost the one thing it does buy: the runaway dying instead of its neighbours
+ * (QA-2026-09-07 MINOR-6, where the earlier wording promised the opposite).
+ */
+export const SESSION_MEMORY_HIGH_MIN_BYTES = 2 * GIB;
+/**
+ * The wall, when nothing on the machine can say where it should be.
+ *
+ * Every real path reads the wall off systemd (the slice, else the service) or
+ * measures it (`memoryPolicy`). This is the last resort for a machine that gave
+ * neither — twice the honest share, so that even blind the wall sits above the
+ * brake by a margin an honest build fits into, and a runaway still meets one.
+ */
+export const SESSION_MEMORY_WALL_FALLBACK_FACTOR = 2;
+/**
+ * The pool is cut into this many honest shares. Three, because that is what
+ * `maxSessions` defaults to on a dev server, so three sessions can sit at their
+ * brakes without the pool itself overflowing — and one runaway then meets its
+ * own wall (`ceiling − share`) while a neighbour on its share still fits.
+ */
+export const SESSION_SHARE_DIVISOR = 3;
+/**
+ * On a machine too small to leave a share of room, the brake is this fraction
+ * of the wall. The same 0.8 `memoryPolicy` puts between the service's own
+ * `MemoryHigh` and `MemoryMax`, for the same reason: a band, however narrow,
+ * beats a bare kill line.
+ */
+export const SESSION_BRAKE_OF_WALL = 0.8;
+/**
+ * `clamp(ceiling / 2, 2 GiB, 2.5 GiB)`, never above the ceiling itself.
+ *
+ * Three bounds, each for its own reason — see
+ * {@link SESSION_MEMORY_MAX_ABSOLUTE_BYTES} for the upper two and
+ * {@link SESSION_MEMORY_MIN_BYTES} for the lower one. The last clamp matters
+ * on a tiny machine: a per-session number ABOVE the slice's own ceiling is not
+ * a limit at all, it is a bigger number that never applies, and printing it in
+ * `doctor` would be a straight lie about what is in force.
+ *
+ * The argument is the ceiling of the cgroup that CONTAINS the session, and
+ * since 0.54.0 that is `devbridge-sessions.slice` and not the service — the
+ * caller reads the slice and falls back to the service only when systemd has
+ * nothing to say about the slice. The two are the same number by construction
+ * today; they come apart the moment a drop-in fails to apply or is edited by
+ * hand, and then «never more than the slice» has to still be true
+ * (QA-2026-09-07 MINOR-5).
+ */
+export function sessionMemoryHighBytes(containingMemoryMaxBytes) {
+    return sessionMemoryLadder(containingMemoryMaxBytes).highBytes;
+}
+/**
+ * The two numbers of the cage, computed in ONE place because each is wrong
+ * without the other (QA of #387 found both halves broken separately).
+ *
+ * ```
+ *   brake = max(containing / 3, 2 GiB)      capped by the containing ceiling
+ *   wall  = containing − brake              never at or below the brake
+ * ```
+ *
+ * **Why a third, and no upper cap.** The owner's second note on #387: «ночью
+ * машина свободна (~9 ГБ), а сессии всё равно нельзя выйти за 2.5 ГБ… граница
+ * должна смотреть на то, сколько реально свободно». A fixed 2.5 GiB was right
+ * as a KILL line and is wrong as a brake: on a big machine it throttles honest
+ * work that the machine could have absorbed. A third of the pool is the largest
+ * share that still lets three sessions sit at their brakes inside the ceiling,
+ * which is what `maxSessions` defaults to. The 2 GiB floor stays — it is sized
+ * over the 1571 MB measured peak of a workspace `pnpm typecheck`, and a dev
+ * server that cannot run one of those is not a dev server.
+ *
+ * **Why the wall is `containing − brake` and not the ceiling itself.** 0.55.0's
+ * first shape put the wall AT the slice ceiling, and that is not a per-session
+ * wall at all: the kernel charges a leaf and every ancestor, so with any
+ * neighbour the SLICE overflows first, and then the victim is chosen across the
+ * whole slice. Measured on this host (a 300 MB slice, two 250 MB scopes): the
+ * scope that crept up survived to the end, and the **neighbour holding 200 MB
+ * under its own wall was killed** — slice `max 19, oom 1, oom_kill 1`, victim
+ * `max 0, oom 0, oom_kill 1`. Leaving one honest share of room under the
+ * ceiling is what makes the runaway meet its OWN wall first while a neighbour
+ * on its share still fits.
+ *
+ * **The tiny machine.** When the ceiling is so low that `containing − brake`
+ * would land at or under the brake, there is no room for isolation at all: the
+ * wall becomes the ceiling and the BRAKE is lowered to 80 % of it, so that
+ * there is still a braking band (`memoryPolicy` uses the same 0.8 for the
+ * service). Without this, a 4 GB machine got `MemoryHigh == MemoryMax` — the
+ * 0.54.0 kill line back in place, with the card claiming a brake.
+ */
+export function sessionMemoryLadder(containingMemoryMaxBytes, measuredCeilingBytes = null) {
+    const containing = [containingMemoryMaxBytes, measuredCeilingBytes].find((value) => value !== null && Number.isFinite(value) && value > 0);
+    if (containing === undefined) {
+        // Nothing on this machine could say what contains the session. The
+        // reference share, and a wall well above it, so the ladder still exists.
+        return {
+            highBytes: SESSION_MEMORY_HIGH_ABSOLUTE_BYTES,
+            maxBytes: SESSION_MEMORY_HIGH_ABSOLUTE_BYTES * SESSION_MEMORY_WALL_FALLBACK_FACTOR,
+        };
+    }
+    const ceiling = Math.floor(containing);
+    const share = Math.max(Math.floor(ceiling / SESSION_SHARE_DIVISOR), SESSION_MEMORY_HIGH_MIN_BYTES);
+    // Never promise a session more than the cgroup that contains every session.
+    const brake = Math.max(1, Math.min(share, ceiling));
+    const wall = ceiling - brake;
+    if (wall <= brake) {
+        return {
+            highBytes: Math.max(1, Math.floor(ceiling * SESSION_BRAKE_OF_WALL)),
+            maxBytes: ceiling,
+        };
+    }
+    return { highBytes: brake, maxBytes: wall };
+}
+/**
+ * The wall — `MemoryMax` on the scope — and why it is the WHOLE containing
+ * ceiling and not a fraction of it (#387).
+ *
+ * The owner's rule: the wall is protection against a runaway, not the norm of
+ * work. Where the norm lives is {@link sessionMemoryHighBytes}; the wall has to
+ * be far enough above it that honest work never touches it, and «far» on a dev
+ * server means «what the machine can actually spare» — which is exactly the
+ * number the slice ceiling already is (`memoryPolicy`: `MemAvailable` plus what
+ * we hold, minus a reserve). Giving a session less than that is the 2.5 GiB
+ * mistake with a different number.
+ *
+ * With `OOMPolicy=continue` on the scope, reaching the wall costs a runaway its
+ * fattest process and nothing else; the neighbours are protected by the slice,
+ * which holds the same number over all of them together.
+ *
+ * `containing` is what systemd has in force on the slice (else the service);
+ * `measured` is what the policy would write there; the factor is the last
+ * resort. Never below the brake — a wall under the brake is a kill line again.
+ */
+export function sessionMemoryMaxBytes(containingMemoryMaxBytes, measuredCeilingBytes = null) {
+    return sessionMemoryLadder(containingMemoryMaxBytes, measuredCeilingBytes).maxBytes;
+}
+/**
+ * Swap one session may push into — the reason the brake slows instead of stalls.
+ *
+ * Half of what the slice may use, the same «no single session takes the
+ * collective allowance» rule as the memory share. When systemd reports no
+ * bound on the slice (the drop-in never landed, MAJOR-3 shape) the share is cut
+ * from the machine's `SwapTotal` directly, with the same fraction the slice
+ * would have had, so the per-scope line is a real bound on its own. A machine
+ * with no swap gets 0, which is exactly 0.54.0's line — and exactly right:
+ * there is nothing to share.
+ */
+export function sessionSwapMaxBytes(sliceSwapMaxBytes, hostSwapTotalBytes) {
+    if (sliceSwapMaxBytes !== null && Number.isFinite(sliceSwapMaxBytes)) {
+        return Math.max(0, Math.floor(sliceSwapMaxBytes / 2));
+    }
+    if (hostSwapTotalBytes !== null && Number.isFinite(hostSwapTotalBytes)) {
+        return Math.max(0, Math.floor((hostSwapTotalBytes * SESSIONS_SWAP_SHARE) / 2));
+    }
+    return 0;
+}
+// ─── unit names ──────────────────────────────────────────────────────
+/**
+ * Room for the id inside a unit name. systemd's own limit is 255 bytes for the
+ * whole name; the prefix, the `.scope` suffix, a restart marker and a hash all
+ * come out of the same budget, so the id is cut well short of it.
+ */
+const MAX_ID_IN_UNIT = 180;
+/**
+ * The session id as systemd will accept it.
+ *
+ * Ids are UUIDs today and arbitrary text tomorrow — they arrive from the API,
+ * and `verify` keys its cage by a run id. systemd unit names take only
+ * `[A-Za-z0-9:_.-]`, so everything else is folded to `-`. Folding is lossy, and
+ * lossy is how two different sessions end up fighting over one scope, so
+ * anything that had to be changed or cut also gets eight hex digits of the
+ * original — deterministic, so the same session always names the same unit and
+ * the sweeper can still recognise it.
+ */
+export function sanitizeCageId(id) {
+    const folded = id.replace(/[^A-Za-z0-9:_.-]/g, '-').replace(/^[.-]+/, '');
+    const cut = folded.slice(0, MAX_ID_IN_UNIT);
+    if (cut === id && cut.length > 0)
+        return cut;
+    const digest = crypto.createHash('sha256').update(id).digest('hex').slice(0, 8);
+    return `${cut || 'session'}-${digest}`;
+}
+/**
+ * The scope unit for one START of one session.
+ *
+ * `attempt` is not decoration. A scope the OOM killer took stays loaded in
+ * `failed` until something resets it, and `systemd-run --unit=` on a name that
+ * is still loaded fails outright — measured: «Unit devbridge-….scope was
+ * already loaded or has a fragment file», exit 1, nothing spawned. So a session
+ * that is restarted after an OOM (which is exactly when it IS restarted) would
+ * be unable to start at all if the name never changed.
+ * {@link releaseSessionScope} clears the failed unit and only then lets the
+ * counter fall back to 1, so the plain `devbridge-session-<id>.scope` is the
+ * normal case and the marker appears only while the old scope is still there.
+ */
+export function sessionScopeUnit(id, attempt = 1) {
+    const base = `${SESSION_SCOPE_PREFIX}${sanitizeCageId(id)}`;
+    return attempt <= 1 ? `${base}.scope` : `${base}-r${attempt}.scope`;
+}
+// ─── capability detection ────────────────────────────────────────────
+/** cgroup v2 unified, from `statfs` — the number behind `stat -fc %T`. */
+const CGROUP2_SUPER_MAGIC = 0x63677270;
+const TMPFS_MAGIC = 0x01021994;
+/** What the live probe must read back out of its own cgroup: 64 MiB, exactly. */
+const PROBE_MEMORY_MAX = 64 * MIB;
+/**
+ * The systemd release that added `--expand-environment=`.
+ *
+ * Below it `systemd-run` answers `unrecognized option` and exits 1 — the probe
+ * then reads as «the cage did not hold» on a machine whose cgroups are perfect
+ * (Ubuntu 22.04 is 249, Debian 12 and RHEL 9 are 252). See the module header for
+ * why the flag is not needed there either.
+ */
+export const EXPAND_ENVIRONMENT_MIN_SYSTEMD = 254;
+function statfsType(target) {
+    try {
+        const type = fs.statfsSync(target).type;
+        if (type === CGROUP2_SUPER_MAGIC)
+            return 'cgroup2fs';
+        if (type === TMPFS_MAGIC)
+            return 'tmpfs';
+        return `0x${type.toString(16)}`;
+    }
+    catch {
+        return null;
+    }
+}
+function onPath(name) {
+    const dirs = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
+    return dirs.some((dir) => {
+        try {
+            fs.accessSync(path.join(dir, name), fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Variables the child needs to reach the user's systemd, and nothing else.
+ *
+ * `systemd-run --user` finds the bus through `XDG_RUNTIME_DIR` (sd-bus falls
+ * back to `$XDG_RUNTIME_DIR/bus` when `DBUS_SESSION_BUS_ADDRESS` is unset), and
+ * that variable is already on both spawn allowlists — so merging this into a
+ * session's environment widens nothing. `DBUS_SESSION_BUS_ADDRESS` is passed on
+ * only when the daemon really has one of its own, never synthesised.
+ */
+export function cageEnv() {
+    const out = {};
+    const dir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+    if (dir)
+        out['XDG_RUNTIME_DIR'] = dir;
+    const bus = process.env['DBUS_SESSION_BUS_ADDRESS'];
+    if (bus)
+        out['DBUS_SESSION_BUS_ADDRESS'] = bus;
+    return out;
+}
+function userManagerCgroupControllers() {
+    const uid = runnerIdentity().uid;
+    if (uid < 0)
+        return null;
+    const file = path.join('/sys/fs/cgroup/user.slice', `user-${uid}.slice`, `user@${uid}.service`, 'cgroup.controllers');
+    try {
+        return fs.readFileSync(file, 'utf8').trim().split(/\s+/).filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The only honest check there is: build a real cage and ask it what it holds.
+ *
+ * Reading `cgroup.controllers` and `systemd-run --version` proves the parts are
+ * on the machine, not that they work: under a foreign supervisor the files look
+ * perfect and the limit is silently never applied. So the probe starts a
+ * throwaway scope with `MemoryMax=64M` whose entire job is to `cat` its own
+ * `memory.max`, and the answer has to be `67108864` on the nose.
+ *
+ * `--collect` IS right here, and only here: this scope's cause of death is of no
+ * interest, and a probe that left units behind on every daemon start would be a
+ * litter machine.
+ */
+async function runLiveProbe(options) {
+    const unit = `devbridge-cage-probe-${process.pid}`;
+    try {
+        const { stdout } = await execFileAsync('systemd-run', [
+            '--user',
+            '--scope',
+            '--quiet',
+            '--collect',
+            `--unit=${unit}`,
+            `--slice=${SESSIONS_SLICE}`,
+            // Exactly the switches `cageSpawn` will use, this one included: a probe
+            // that tests a different command line proves nothing about the real one.
+            ...(options.expandEnvironmentFlag ? ['--expand-environment=no'] : []),
+            '-p',
+            `MemoryHigh=${PROBE_MEMORY_MAX / 2}`,
+            '-p',
+            `MemoryMax=${PROBE_MEMORY_MAX}`,
+            '-p',
+            'MemorySwapMax=0',
+            // The one property an older systemd refuses for a scope — the probe is
+            // where that refusal has to surface, so the real spawn never meets it.
+            ...(options.oomPolicyFlag ? ['-p', OOM_POLICY_CONTINUE] : []),
+            '-p',
+            'TasksMax=16',
+            '-p',
+            `CPUWeight=${SESSION_CPU_WEIGHT}`,
+            '--',
+            '/bin/sh',
+            '-c',
+            'cat /sys/fs/cgroup$(cut -d: -f3 /proc/self/cgroup)/memory.max',
+        ], 
+        // Generous: the same call took 0.07–2.5 s on an idle machine and 2741 ms
+        // under load. A probe that times out costs the machine its cage, so the
+        // budget is sized for the worst measurement, not the typical one.
+        { timeout: 20_000, env: { ...process.env, ...cageEnv() } });
+        return { memoryMax: stdout.trim(), error: null };
+    }
+    catch (error) {
+        // Kept, not swallowed. «Did not run» and «ran and did not hold» are
+        // different machines and different repairs, and one sentence about
+        // `memory.max` for both sent people to fix cgroups that were fine.
+        return { memoryMax: null, error: execErrorText(error) };
+    }
+}
+/**
+ * The first line `systemd-run` complained with, short enough for a card.
+ *
+ * `stderr` before `message`: node's own message is `Command failed: systemd-run
+ * …` with the whole command line in it, while stderr is the one sentence that
+ * names the cause (`unrecognized option '--expand-environment=no'`).
+ */
+function execErrorText(error) {
+    const own = typeof error === 'object' && error !== null ? { ...error } : {};
+    const stderr = typeof own['stderr'] === 'string' ? own['stderr'] : '';
+    const text = stderr.trim() || (error instanceof Error ? error.message : String(error));
+    const first = text.split('\n').find((line) => line.trim().length > 0) ?? '';
+    return first.trim().slice(0, 200);
+}
+/**
+ * Which `systemd-run` this is. `systemd 255 (255.4-1ubuntu8.17)` → 255.
+ *
+ * The version decides one flag and nothing else, so an unreadable answer is not
+ * a refusal: it drops the flag, which is what every systemd below 254 does with
+ * `--scope` anyway.
+ */
+async function readSystemdRunVersion() {
+    try {
+        const { stdout } = await execFileAsync('systemd-run', ['--version'], { timeout: 10_000 });
+        const match = /^systemd\s+(\d+)/m.exec(stdout);
+        const major = match?.[1] ? Number(match[1]) : Number.NaN;
+        return Number.isFinite(major) ? major : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function showMemoryMax(unit) {
+    const value = await showByteCount(unit, 'MemoryMax');
+    return value !== null && value > 0 ? value : null;
+}
+/**
+ * A byte-count property as systemd has it in force. `infinity` and «no answer»
+ * are both null; 0 is kept, because for `MemorySwapMax` zero is the whole point.
+ */
+async function showByteCount(unit, property) {
+    try {
+        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', unit, '-p', property, '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const raw = stdout.trim();
+        if (!/^\d+$/.test(raw))
+            return null;
+        const value = Number(raw);
+        return Number.isSafeInteger(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The ceiling the policy would write to the slice today — the measured wall. */
+function measuredMachineCeiling() {
+    const facts = readMemoryFacts();
+    return facts ? memoryPolicy(facts).maxBytes : null;
+}
+export const defaultCageProbe = {
+    cgroupFsType: () => statfsType('/sys/fs/cgroup'),
+    systemdRunOnPath: () => onPath('systemd-run'),
+    userBusPath: () => {
+        const dir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+        if (!dir)
+            return null;
+        return fs.existsSync(path.join(dir, 'bus')) ? dir : null;
+    },
+    delegatedControllers: userManagerCgroupControllers,
+    systemdRunVersion: readSystemdRunVersion,
+    probeMemoryMax: runLiveProbe,
+    serviceMemoryMax: () => showMemoryMax('devbridge-runner'),
+    sessionsSliceMemoryMax: () => showMemoryMax(SESSIONS_SLICE),
+    sessionsSliceSwapMax: () => showByteCount(SESSIONS_SLICE, 'MemorySwapMax'),
+    hostSwapTotalBytes: readSwapTotalBytes,
+    machineCeilingBytes: measuredMachineCeiling,
+    canRenice: () => {
+        try {
+            // A no-op that still asks the kernel the question: setting our own
+            // priority to the value it already has. Allowed for every user, so a
+            // failure here means the syscall itself is refused (seccomp, a locked-down
+            // container) — which is the one case where even the fallback is a lie.
+            os.setPriority(0, os.getPriority(0));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+export async function detectSessionCage(probe = defaultCageProbe) {
+    const fallback = (reason) => ({
+        mode: probe.canRenice() ? 'nice-only' : 'none',
+        reason,
+        memoryHighBytes: null,
+        memoryMaxBytes: null,
+        swapMaxBytes: null,
+        oomContinue: false,
+        serviceMemoryMaxBytes: null,
+        sessionsSliceMemoryMaxBytes: null,
+        expandEnvironmentFlag: false,
+    });
+    const fsType = probe.cgroupFsType();
+    // Not «contains cgroup2» — exactly cgroup2fs. `tmpfs` at this path is cgroup
+    // v1 or the hybrid layout, where `systemd-run --scope` accepts every `-p` and
+    // applies none of them.
+    if (fsType !== 'cgroup2fs') {
+        return fallback(`/sys/fs/cgroup is ${fsType ?? 'unreadable'}, not cgroup2fs (cgroup v1 or hybrid)`);
+    }
+    if (!probe.systemdRunOnPath())
+        return fallback('systemd-run is not on PATH');
+    if (!probe.userBusPath()) {
+        return fallback('no user systemd bus ($XDG_RUNTIME_DIR/bus) — started outside a user session?');
+    }
+    const controllers = probe.delegatedControllers();
+    // Unreadable is NOT a refusal: the path is only right for a systemd user
+    // manager, and the live probe below is the authority in every layout. A file
+    // we can read and which says «no memory» is a different matter — that is the
+    // delegation this cage is built on, missing.
+    if (controllers && !controllers.includes('memory')) {
+        return fallback(`the user manager has no delegated memory controller (${controllers.join(' ') || 'none'})`);
+    }
+    // Decided once, here, and carried in the facts: the probe and every later
+    // spawn have to build the SAME command line, or the thing that was proved to
+    // work is not the thing that runs.
+    const systemdVersion = await probe.systemdRunVersion();
+    const expandEnvironmentFlag = systemdVersion !== null && systemdVersion >= EXPAND_ENVIRONMENT_MIN_SYSTEMD;
+    // `OOMPolicy=` on a SCOPE is newer than the cage's other switches, and which
+    // release added it is not documented well enough to gate on a number (this
+    // host, systemd 255, takes it; an older systemd answers «Unknown assignment»
+    // and spawns NOTHING at all). So the probe decides: try with it, and on a
+    // refusal that names the property try once more without — that machine keeps
+    // its cage and loses only the «one process, not the session» half (#387).
+    let oomPolicyFlag = true;
+    let probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag });
+    if (probed.error !== null && refusesOomPolicy(probed.error)) {
+        oomPolicyFlag = false;
+        probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag });
+    }
+    if (probed.error !== null) {
+        // Not «the cage did not hold» — nothing was ever caged. Blaming `memory.max`
+        // for a refused command line sent people to fix delegation that was fine.
+        return fallback(`the test cage would not start: ${probed.error}`);
+    }
+    if (probed.memoryMax !== String(PROBE_MEMORY_MAX)) {
+        return fallback(`the test cage did not hold: memory.max read back as ${probed.memoryMax ?? 'nothing'}, wanted ${PROBE_MEMORY_MAX}`);
+    }
+    const serviceMemoryMaxBytes = await probe.serviceMemoryMax();
+    const sessionsSliceMemoryMaxBytes = await probe.sessionsSliceMemoryMax();
+    const sliceSwapMaxBytes = await probe.sessionsSliceSwapMax();
+    // The slice is what actually contains the session; the service is the
+    // fallback for a systemd that would not answer about the slice at all.
+    const containing = sessionsSliceMemoryMaxBytes ?? serviceMemoryMaxBytes;
+    const ladder = sessionMemoryLadder(containing, probe.machineCeilingBytes());
+    return {
+        mode: 'scope',
+        reason: '',
+        memoryHighBytes: ladder.highBytes,
+        memoryMaxBytes: ladder.maxBytes,
+        swapMaxBytes: sessionSwapMaxBytes(sliceSwapMaxBytes, probe.hostSwapTotalBytes()),
+        oomContinue: oomPolicyFlag,
+        serviceMemoryMaxBytes,
+        sessionsSliceMemoryMaxBytes,
+        expandEnvironmentFlag,
+    };
+}
+/** The `-p` assignment itself, in one place: the probe and the spawn must agree. */
+const OOM_POLICY_CONTINUE = 'OOMPolicy=continue';
+/**
+ * Did `systemd-run` refuse the command line BECAUSE of `OOMPolicy=`?
+ *
+ * systemd's wording for a property a unit type does not take is «Unknown
+ * assignment: OOMPolicy=continue» (`bus_append_unit_property_assignment`); a
+ * refusal that does not name the property is some other machine's problem and
+ * must not be retried into a cage with a weaker policy.
+ */
+export function refusesOomPolicy(error) {
+    return /OOMPolicy/i.test(error);
+}
+/**
+ * Before the detector has run, nothing is wrapped.
+ *
+ * `nice-only` rather than `none` because stage 1a is unconditional — the renice
+ * happens at every spawn point whatever this module says. The value only ever
+ * appears where the daemon has not started (a `verify` from the command line, a
+ * test), and it means «no scope», which is the safe answer.
+ */
+const UNPROBED = {
+    mode: 'nice-only',
+    reason: 'not probed yet',
+    memoryHighBytes: null,
+    memoryMaxBytes: null,
+    swapMaxBytes: null,
+    oomContinue: false,
+    serviceMemoryMaxBytes: null,
+    sessionsSliceMemoryMaxBytes: null,
+    expandEnvironmentFlag: false,
+};
+let detected = null;
+/**
+ * Probe once, at daemon start, and remember the answer.
+ *
+ * The probe costs a process, so it is not something a spawn can afford to do:
+ * three sessions starting at once would mean three throwaway scopes before the
+ * first agent got a word out.
+ */
+export async function initSessionCage(probe = defaultCageProbe) {
+    detected = await detectSessionCage(probe);
+    if (detected.mode === 'scope') {
+        log.info('session cage: each session gets its own cgroup', {
+            slice: SESSIONS_SLICE,
+            memoryHighMB: Math.round((detected.memoryHighBytes ?? 0) / MIB),
+            memoryMaxMB: Math.round((detected.memoryMaxBytes ?? 0) / MIB),
+            swapMaxMB: Math.round((detected.swapMaxBytes ?? 0) / MIB),
+            oomPolicy: detected.oomContinue ? 'continue' : 'stop (this systemd takes none on a scope)',
+            serviceMemoryMaxMB: detected.serviceMemoryMaxBytes
+                ? Math.round(detected.serviceMemoryMaxBytes / MIB)
+                : null,
+            sessionsSliceMemoryMaxMB: detected.sessionsSliceMemoryMaxBytes
+                ? Math.round(detected.sessionsSliceMemoryMaxBytes / MIB)
+                : null,
+        });
+        if (detected.sessionsSliceMemoryMaxBytes === null) {
+            // The half of the containment the probe cannot see. Loud, because from
+            // here on the machine looks caged and one session at a time is: what is
+            // missing is the ceiling over all of them together.
+            log.warn('session cage: no collective ceiling on the sessions slice', {
+                slice: SESSIONS_SLICE,
+                why: 'the drop-in has not been applied — systemd reports MemoryMax=infinity',
+                hint: 'run `devbridge-runner doctor --fix`',
+            });
+        }
+    }
+    else {
+        // Warn, not error. A machine without the cage is the machine we had
+        // yesterday; what must never happen is that it looks like the machine we
+        // wanted and quietly is not (plan §5.4.2).
+        log.warn('session cage: not available — falling back to priority only', {
+            mode: detected.mode,
+            reason: detected.reason,
+        });
+    }
+    return detected;
+}
+/** What the last {@link initSessionCage} found; the safe default before it ran. */
+export function sessionCage() {
+    return detected ?? UNPROBED;
+}
+/**
+ * Live scope per cage id, so a restart cannot collide with a scope that the OOM
+ * killer left behind. Cleared by {@link releaseSessionScope} once the old unit
+ * is provably gone — see {@link sessionScopeUnit}.
+ */
+const attempts = new Map();
+/**
+ * The scope each caged id is CURRENTLY in, so the supervisor's memory watch can
+ * find the cgroup of a live session without the adapter having to hand it up.
+ * Set in {@link cageSpawn}, cleared in {@link releaseSessionScope}.
+ */
+const liveUnits = new Map();
+/** The scope a live caged id runs in, or null when it is not caged (or gone). */
+export function sessionScopeUnitOf(id) {
+    return liveUnits.get(id) ?? null;
+}
+/**
+ * Wrap a command in its session's cage, or hand it back untouched.
+ *
+ * Untouched is the honest answer on every machine where the cage was not proved
+ * to work: `systemd-run` would accept the flags there and apply nothing, and a
+ * session that believes it is contained when it is not is worse than one that
+ * knows it is not.
+ *
+ * Pipes, exit codes, signals and stdin EOF behave exactly as with a direct
+ * spawn, because `systemd-run --scope` execs into the SAME pid — verified in the
+ * spike, including `detached: true` + `process.kill(-pid)` in `verify.ts`
+ * (`pgid === child.pid` still holds).
+ */
+export function cageSpawn(input) {
+    const facts = sessionCage();
+    if (facts.mode !== 'scope' ||
+        facts.memoryMaxBytes === null ||
+        facts.memoryHighBytes === null ||
+        facts.swapMaxBytes === null) {
+        return { command: input.command, args: input.args, env: {}, unit: null };
+    }
+    const attempt = (attempts.get(input.id) ?? 0) + 1;
+    attempts.set(input.id, attempt);
+    const unit = sessionScopeUnit(input.id, attempt);
+    liveUnits.set(input.id, unit);
+    // A verdict nobody read belongs to the process that just ended, not to the
+    // one starting now: without this, a kill that was never surfaced would be
+    // pinned hours later on an unrelated crash of the next process (#387 QA).
+    deaths.delete(input.id);
+    oomKillsSeen.delete(input.id);
+    return {
+        command: 'systemd-run',
+        args: [
+            '--user',
+            '--scope',
+            '--quiet',
+            `--unit=${unit}`,
+            `--slice=${SESSIONS_SLICE}`,
+            // The agent's prompt travels in these arguments and prompts contain `$`.
+            // Only where systemd knows the switch — below 254 it is a hard error and
+            // `--scope` does no expansion anyway (module header, MAJOR-2).
+            ...(facts.expandEnvironmentFlag ? ['--expand-environment=no'] : []),
+            // The ladder of #387, bottom to top. The brake: past the honest share the
+            // kernel reclaims and slows this session down, and nothing dies.
+            '-p',
+            `MemoryHigh=${facts.memoryHighBytes}`,
+            // The wall: the machine's measured headroom, far above the brake. Only a
+            // runaway gets here, and with `OOMPolicy=continue` it costs one process.
+            '-p',
+            `MemoryMax=${facts.memoryMaxBytes}`,
+            // THE line. Without a bound there is no cage at all: `MemoryMax` bounds
+            // resident memory and lets the rest fall into the host's swap, which is
+            // how a 200 MB cage allocated 2 GB and took the machine's swap with it.
+            // Bounded, never unset — and since #387 a share rather than 0, because
+            // the brake above has to have somewhere to push pages (module header).
+            '-p',
+            `MemorySwapMax=${facts.swapMaxBytes}`,
+            // Only where the probe proved this systemd takes it on a scope. Without
+            // it the kernel killing ONE process stops the WHOLE scope (`OOMPolicy`
+            // defaults to `stop`) — the exact mechanism that killed honest sessions
+            // in 0.54.0, and the same lesson `service-unit.ts` learned in QA-112.
+            ...(facts.oomContinue ? ['-p', OOM_POLICY_CONTINUE] : []),
+            '-p',
+            `TasksMax=${SESSION_TASKS_MAX}`,
+            '-p',
+            `CPUWeight=${SESSION_CPU_WEIGHT}`,
+            '--',
+            input.command,
+            ...input.args,
+        ],
+        env: cageEnv(),
+        unit,
+    };
+}
+/**
+ * Did this process die in the window before `systemd-run` handed over?
+ *
+ * Starting a scope took 0.07–2.5 s in the spike, and 2741 ms on a loaded
+ * machine. A stop inside that window signals `systemd-run` itself, before the
+ * `exec`, and the parent sees `{code: null, signal: 'SIGTERM'}` with nothing on
+ * stdout at all. That is «the session never started», not «the agent died
+ * silently» — told apart here so no supervisor has to infer it from an empty
+ * buffer.
+ */
+export function killedBeforeExec(info) {
+    return info.caged && !info.sawOutput && info.code === null && info.signal === 'SIGTERM';
+}
+/**
+ * The pure half of {@link readScopeMemoryStatus}: the four files' text in, the
+ * status out. `memory.swap.current` is optional (no swap controller, cgroup v2
+ * without swap accounting); the rest are not.
+ */
+export function parseScopeMemoryStatus(files) {
+    const count = (raw) => {
+        const trimmed = raw.trim();
+        if (!/^\d+$/.test(trimmed))
+            return null;
+        const value = Number(trimmed);
+        return Number.isSafeInteger(value) ? value : null;
+    };
+    const limit = (raw) => (raw.trim() === 'max' ? null : count(raw));
+    const event = (name) => {
+        const line = files.events.split('\n').find((l) => l.startsWith(`${name} `));
+        return line ? (count(line.slice(name.length + 1)) ?? 0) : 0;
+    };
+    const currentBytes = count(files.current);
+    if (currentBytes === null)
+        return null;
+    return {
+        currentBytes,
+        highBytes: limit(files.high),
+        maxBytes: limit(files.max),
+        swapCurrentBytes: files.swapCurrent === undefined ? 0 : (count(files.swapCurrent) ?? 0),
+        highEvents: event('high'),
+        oomKills: event('oom_kill'),
+        ownLimitOom: event('oom'),
+    };
+}
+/** Where a session scope's cgroup lives, or null off a user manager. */
+function scopeCgroupDir(unit) {
+    const self = readSelfCgroup();
+    if (self === null)
+        return null;
+    const slice = sliceCgroupPath(self, SESSIONS_SLICE);
+    return slice === null ? null : path.join(slice, unit);
+}
+/**
+ * What one live session's cgroup holds and has been through. Null when the
+ * cgroup is not there (the scope ended, or this machine has no cage).
+ *
+ * Filesystem, not `systemctl show`: this runs on the supervisor's 30 s tick for
+ * every live session, and the bus is the thing that took 2.7 s under load.
+ */
+export function readScopeMemoryStatus(unit, readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    const dir = scopeCgroupDir(unit);
+    if (dir === null)
+        return null;
+    try {
+        let swapCurrent;
+        try {
+            swapCurrent = readFile(path.join(dir, 'memory.swap.current'));
+        }
+        catch {
+            swapCurrent = undefined;
+        }
+        return parseScopeMemoryStatus({
+            current: readFile(path.join(dir, 'memory.current')),
+            high: readFile(path.join(dir, 'memory.high')),
+            max: readFile(path.join(dir, 'memory.max')),
+            events: readFile(path.join(dir, 'memory.events')),
+            ...(swapCurrent === undefined ? {} : { swapCurrent }),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `oom_kill` as the watch last saw it, per id — so a kill that was already
+ * announced in the feed while the session lived is not blamed for a death that
+ * came later for another reason.
+ */
+const oomKillsSeen = new Map();
+export function markScopeOomKillsSeen(id, oomKills) {
+    oomKillsSeen.set(id, oomKills);
+}
+const deaths = new Map();
+/**
+ * Snapshot the cgroup's verdict before systemd can take it away.
+ *
+ * Exported for the test seam only (`readStatus`): the real caller passes
+ * nothing and reads the live cgroup.
+ */
+export function rememberDeath(id, unit, readStatus = readScopeMemoryStatus) {
+    const status = readStatus(unit);
+    const seen = oomKillsSeen.get(id) ?? 0;
+    oomKillsSeen.delete(id);
+    if (status === null || status.oomKills <= seen)
+        return;
+    deaths.set(id, {
+        oomKills: status.oomKills - seen,
+        maxBytes: status.maxBytes,
+        // `oom` moves only where the limit that was hit belongs. A kill with our
+        // own counter still at zero came from an ancestor — the pool.
+        ownWall: status.ownLimitOom > 0,
+    });
+}
+/**
+ * The other source of the same verdict, for the machine where the first one is
+ * already gone (#387 QA).
+ *
+ * On a systemd that takes no `OOMPolicy` on a scope, one kill stops the whole
+ * scope; systemd then removes the cgroup as soon as it is empty, and the
+ * snapshot above can find nothing at all. `Result=oom-kill` survives that —
+ * it is read a few milliseconds later from the unit, which is why
+ * {@link releaseSessionScope} is now awaited before a death is explained.
+ */
+function rememberDeathFromResult(id) {
+    if (deaths.has(id))
+        return;
+    deaths.set(id, {
+        oomKills: 1,
+        maxBytes: sessionCage().memoryMaxBytes,
+        // systemd stopped the unit for an OOM inside it; which limit was hit is not
+        // in `Result`, and «your own wall» is the claim that must not be guessed.
+        ownWall: false,
+    });
+}
+/**
+ * One sentence for the error the person reads, when the kernel had a hand in
+ * this death — or null when it had not. Consumed: a session restarted after an
+ * OOM must not carry the old sentence into its next, unrelated failure.
+ *
+ * The text that reached people in 0.54.0 was «exited with code 143» once and
+ * «terminated by signal SIGKILL» the next time, for the same cause, and neither
+ * said the word memory. This is that word.
+ */
+export function explainMemoryDeath(id) {
+    const death = deaths.get(id);
+    if (!death)
+        return null;
+    deaths.delete(id);
+    const killed = death.oomKills === 1 ? 'a process' : `${death.oomKills} processes`;
+    const wall = death.maxBytes === null ? '' : ` of ${Math.round(death.maxBytes / MIB)} MB`;
+    if (death.ownWall) {
+        return (`The session ran out of memory: it went over its own memory ceiling${wall} and the kernel killed ` +
+            `${killed} inside it. ` +
+            'Resume it and avoid re-running the command that was in flight, or give the machine more memory or swap.');
+    }
+    return (`The machine ran out of memory for agent sessions — all sessions on it share one ceiling — and the kernel killed ` +
+        `${killed} in this one. This session was not necessarily the greedy one. ` +
+        'Resume it; if it keeps happening, run fewer sessions at once or give the machine more memory or swap.');
+}
+const realSystemctl = async (args) => {
+    const { stdout, stderr } = await execFileAsync('systemctl', ['--user', ...args], {
+        timeout: 15_000,
+        env: systemdUserEnv(),
+    });
+    return { stdout, stderr };
+};
+function showValue(stdout, property) {
+    const line = stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.startsWith(`${property}=`));
+    return line ? line.slice(property.length + 1) : null;
+}
+/**
+ * Read why the scope ended, say so, and then let systemd forget it.
+ *
+ * This is the whole reason `--collect` is not passed. The order is fixed: the
+ * process has already exited, `Result` is read, the reason is logged, and only
+ * then is the unit reset — because `reset-failed` is what deletes the answer.
+ *
+ * Failure here is never fatal: a unit that could not be reset is swept at the
+ * next daemon start, and the counter in {@link cageSpawn} keeps the session
+ * startable in the meantime.
+ */
+export async function releaseSessionScope(unit, id, systemctl = realSystemctl) {
+    const running = releaseSessionScopeInner(unit, id, systemctl);
+    if (id !== undefined) {
+        releasing.set(id, running);
+        void running.finally(() => {
+            if (releasing.get(id) === running)
+                releasing.delete(id);
+        });
+    }
+    return await running;
+}
+/**
+ * Releases in flight, per cage id, so a death can be explained with BOTH
+ * sources: the cgroup snapshot (synchronous, gone the moment systemd prunes the
+ * group) and `Result=oom-kill` (authoritative, and a few milliseconds late).
+ * Without the wait, the machine that needs the sentence most — the one whose
+ * systemd stops the whole scope — was the one that never got it (#387 QA).
+ */
+const releasing = new Map();
+/**
+ * The sentence for a death, once the verdict is in. Null when the kernel had no
+ * hand in it. Waits for the release of this session's scope, but never longer
+ * than `capMs`: an answer that arrives after the person has read the error is
+ * worth nothing, and a hung `systemctl` must not hold a failing session open.
+ */
+export async function memoryDeathSentence(id, capMs = 3_000) {
+    const pending = releasing.get(id);
+    if (pending) {
+        let timer;
+        await Promise.race([
+            pending.catch(() => null),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, capMs);
+                timer.unref?.();
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+    }
+    return explainMemoryDeath(id);
+}
+async function releaseSessionScopeInner(unit, id, systemctl) {
+    if (!unit)
+        return null;
+    // Synchronously and FIRST: the cgroup's own counters are the one record of an
+    // OOM kill that survives `OOMPolicy=continue` (the unit does not fail, so
+    // `Result` says nothing), and the directory goes away the moment the scope is
+    // empty. This is what the adapter's error text is built from (#387).
+    if (id !== undefined)
+        rememberDeath(id, unit);
+    if (id !== undefined)
+        liveUnits.delete(id);
+    let result = null;
+    try {
+        const { stdout } = await systemctl(['show', unit, '-p', 'Result']);
+        result = showValue(stdout, 'Result');
+    }
+    catch {
+        // Already collected — a clean exit takes its scope with it.
+    }
+    if (result === 'oom-kill') {
+        log.warn('session cage: the kernel killed this session for going over its memory ceiling', {
+            unit,
+            memoryMaxMB: Math.round((sessionCage().memoryMaxBytes ?? 0) / MIB),
+        });
+        // The cgroup snapshot above may have found nothing: on a systemd that stops
+        // the whole scope, the group is gone by the time the process's `exit` fires.
+        if (id !== undefined)
+            rememberDeathFromResult(id);
+    }
+    let forgotten = false;
+    try {
+        await systemctl(['reset-failed', unit]);
+        forgotten = true;
+    }
+    catch {
+        // Nothing to reset is the normal case — but so is «the bus was not there»,
+        // and those two look identical from here.
+    }
+    // Only when the unit is provably gone. Clearing the counter after a FAILED
+    // `reset-failed` hands the next start of this session the same unit name,
+    // which systemd answers with «was already loaded or has a fragment file» and
+    // spawns nothing — the exact failure the counter exists to prevent
+    // (QA-2026-09-07 MINOR-11).
+    if (id !== undefined && forgotten)
+        attempts.delete(id);
+    return result;
+}
+/** Unit names of every `devbridge-session-*.scope` systemd still knows about. */
+export async function listSessionScopeUnits(systemctl = realSystemctl) {
+    let stdout;
+    try {
+        ({ stdout } = await systemctl([
+            'list-units',
+            '--all',
+            '--plain',
+            '--no-legend',
+            `${SESSION_SCOPE_PREFIX}*.scope`,
+        ]));
+    }
+    catch {
+        return [];
+    }
+    return stdout
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/)[0] ?? '')
+        .filter((unit) => unit.startsWith(SESSION_SCOPE_PREFIX) && unit.endsWith('.scope'));
+}
+/** What `doctor` prints for each caged session. */
+export async function listSessionScopes(systemctl = realSystemctl) {
+    const units = await listSessionScopeUnits(systemctl);
+    const out = [];
+    for (const unit of units) {
+        let stdout = '';
+        try {
+            ({ stdout } = await systemctl([
+                'show',
+                unit,
+                '-p',
+                'MemoryMax',
+                '-p',
+                'MemoryCurrent',
+                '-p',
+                'TasksCurrent',
+                '-p',
+                'Result',
+                '-p',
+                'ActiveState',
+            ]));
+        }
+        catch {
+            // Gone between the list and the read — report the name and nothing else.
+        }
+        const num = (property) => {
+            const value = Number(showValue(stdout, property));
+            return Number.isFinite(value) ? value : null;
+        };
+        out.push({
+            unit,
+            memoryMaxBytes: num('MemoryMax'),
+            memoryCurrentBytes: num('MemoryCurrent'),
+            tasksCurrent: num('TasksCurrent'),
+            result: showValue(stdout, 'Result'),
+            activeState: showValue(stdout, 'ActiveState'),
+        });
+    }
+    return out;
+}
+/**
+ * Stop and forget every session scope that has no session behind it.
+ *
+ * At daemon start that is all of them by definition, and it is the point: a
+ * scope outlives a killed daemon carrying the whole process tree with it, which
+ * is the shape of the 10 h 51 min `ugrep` of 16.08. Stopping the scope takes the
+ * tree, not just the process we happened to know about.
+ *
+ * `liveIds` exists so the same sweep can run later without killing work in
+ * progress; only the CURRENT scope of a live session is spared, because an
+ * earlier attempt of the same session is exactly the leftover we are here for.
+ */
+export async function sweepOrphanSessionScopes(liveIds = [], systemctl = realSystemctl) {
+    const spared = new Set();
+    for (const id of liveIds)
+        spared.add(sessionScopeUnit(id, attempts.get(id) ?? 1));
+    const removed = [];
+    for (const unit of await listSessionScopeUnits(systemctl)) {
+        if (spared.has(unit))
+            continue;
+        try {
+            await systemctl(['stop', unit]);
+        }
+        catch {
+            // A failed scope has nothing to stop; `reset-failed` below is the part
+            // that matters for it.
+        }
+        try {
+            await systemctl(['reset-failed', unit]);
+        }
+        catch {
+            // Already gone.
+        }
+        removed.push(unit);
+    }
+    if (removed.length > 0) {
+        log.warn('session cage: removed scopes left behind by a previous run', {
+            count: removed.length,
+            units: removed.slice(0, 10),
+        });
+    }
+    return removed;
+}
+/**
+ * The slice names and the CPU share — re-exported so a caller that reasons about
+ * the cage needs one import, while the values themselves stay next to the
+ * drop-in that writes them (`service-unit.ts`).
+ */
+export { SESSIONS_SLICE, DEVBRIDGE_SLICE, SESSION_CPU_WEIGHT };
+//# sourceMappingURL=session-cage.js.map