@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/session-cage.js

@@ -0,0 +1,755 @@
+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, SESSION_CPU_WEIGHT, SESSIONS_SLICE } 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=0` is what MAKES the cage. Without it there is none. 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.
+ *  - no `MemoryHigh`. With `MemoryHigh` under `MemoryMax` the kernel throttles
+ *    allocations with delays instead of killing: 60 seconds in, the runaway had
+ *    100 MB and was still alive — a session that hangs rather than dies, which
+ *    is the worse of the two. With `MemoryMax` + `MemorySwapMax=0` alone it was
+ *    exit 137 in 380 ms and `Result=oom-kill`.
+ *  - 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;
+/**
+ * What one session may hold. **Proposal Р3 of the plan, awaiting the owner.**
+ *
+ * `min(2.5 GiB, service ceiling / 2)` — §3 of
+ * `docs/plans/active/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_MAX_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_MIN_BYTES = 2 * GIB;
+/**
+ * `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 sessionMemoryMaxBytes(containingMemoryMaxBytes) {
+    if (containingMemoryMaxBytes === null || !Number.isFinite(containingMemoryMaxBytes)) {
+        return SESSION_MEMORY_MAX_ABSOLUTE_BYTES;
+    }
+    const half = Math.floor(containingMemoryMaxBytes / 2);
+    const clamped = Math.min(SESSION_MEMORY_MAX_ABSOLUTE_BYTES, Math.max(SESSION_MEMORY_MIN_BYTES, half));
+    // Never promise a session more than the cgroup that contains every session.
+    return Math.max(1, Math.min(clamped, Math.floor(containingMemoryMaxBytes)));
+}
+// ─── 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',
+            `MemoryMax=${PROBE_MEMORY_MAX}`,
+            '-p',
+            'MemorySwapMax=0',
+            '-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) {
+    try {
+        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', unit, '-p', 'MemoryMax', '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const value = Number(stdout.trim());
+        return Number.isFinite(value) && value > 0 ? value : null;
+    }
+    catch {
+        return 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),
+    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,
+        memoryMaxBytes: null,
+        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;
+    const probed = await probe.probeMemoryMax({ expandEnvironmentFlag });
+    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();
+    return {
+        mode: 'scope',
+        reason: '',
+        // 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.
+        memoryMaxBytes: sessionMemoryMaxBytes(sessionsSliceMemoryMaxBytes ?? serviceMemoryMaxBytes),
+        serviceMemoryMaxBytes,
+        sessionsSliceMemoryMaxBytes,
+        expandEnvironmentFlag,
+    };
+}
+/**
+ * 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',
+    memoryMaxBytes: null,
+    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,
+            memoryMaxMB: Math.round((detected.memoryMaxBytes ?? 0) / MIB),
+            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();
+/**
+ * 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) {
+        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);
+    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'] : []),
+            '-p',
+            `MemoryMax=${facts.memoryMaxBytes}`,
+            // THE line. Without it 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.
+            // Never remove, never make conditional.
+            '-p',
+            'MemorySwapMax=0',
+            '-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';
+}
+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) {
+    if (!unit)
+        return null;
+    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),
+        });
+    }
+    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