@bridge4dev/runner 0.56.0 → 0.58.1

package/dist/session-cage.js

@@ -1,13 +1,12 @@
-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 { cageAuthority, mayActOnSessionCages, mayStartScope, runSystemctl, runSystemdRun, } from './cage-authority.js';
 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);
+import { stateDir } from './paths.js';
+import { DEVBRIDGE_SLICE, memoryPolicy, readCgroupMemory, readMemoryFacts, readSelfCgroup, readSwapTotalBytes, SESSION_CPU_WEIGHT, SESSIONS_SLICE, SESSIONS_SWAP_SHARE, sliceCgroupPath, } from './service-unit.js';
 /**
  * A cgroup of its own for every agent session — the memory ceiling that
  * `process-priority.ts` cannot give.
@@ -144,6 +143,40 @@ export const SESSION_SCOPE_PREFIX = 'devbridge-session-';
  * (QA-2026-09-07 MINOR-6, where the earlier wording promised the opposite).
  */
 export const SESSION_MEMORY_HIGH_MIN_BYTES = 2 * GIB;
+/**
+ * The gap between the brake and the wall, and never less than this (#398 S2).
+ *
+ * The brake is where the kernel starts reclaiming; the wall is where it kills.
+ * With the two at the same number there is no brake at all — that is the 0.54.0
+ * kill line, and #387 is the whole story of what it costs. So every path that
+ * computes the pair keeps at least a band between them, and the band is also
+ * the step by which the stall detector may raise a brake.
+ *
+ * 256 MiB is sized against what one `tsc` of this monorepo holds (~400 MB
+ * measured) divided by the overshoot a build makes in one 5 s window: enough
+ * room for the allocation that was refused, not enough to hide a runaway.
+ *
+ * {@link sessionMemoryBandBytes} widens it on the machines where reaching the
+ * wall costs the whole session rather than one process — see there.
+ */
+export const SESSION_MEMORY_BAND_BYTES = 256 * MIB;
+/**
+ * The band on THIS machine.
+ *
+ * Where the probe found no `OOMPolicy=continue` (systemd 249 and friends), a
+ * kill inside the scope stops the whole scope: the session dies, not one
+ * process. The band there is not a nicety but the only warning the session
+ * gets, so it is a quarter of the brake and never under 512 MiB.
+ *
+ * Two of the fleet's fifteen caged machines answer `sessionOomContinue: false`
+ * (`search aigain`, `trizailab`, measured 10.09.2026), so this is not a
+ * hypothetical branch.
+ */
+export function sessionMemoryBandBytes(brakeBytes, oomContinue) {
+    if (oomContinue)
+        return SESSION_MEMORY_BAND_BYTES;
+    return Math.max(512 * MIB, Math.floor(brakeBytes * 0.25));
+}
 /**
  * The wall, when nothing on the machine can say where it should be.
  *
@@ -421,7 +454,7 @@ function userManagerCgroupControllers() {
 async function runLiveProbe(options) {
     const unit = `devbridge-cage-probe-${process.pid}`;
     try {
-        const { stdout } = await execFileAsync('systemd-run', [
+        const { stdout } = await runSystemdRun([
             '--user',
             '--scope',
             '--quiet',
@@ -431,6 +464,11 @@ async function runLiveProbe(options) {
             // 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'] : []),
+            // The guarantee (#398 S3). In the probe for the same reason `OOMPolicy`
+            // is: a `-p` an older systemd refuses makes `systemd-run` exit 1 and
+            // spawn NOTHING, so a property that has never been tried here would
+            // cost that machine every session it tries to start.
+            ...(options.memoryLowFlag ? ['-p', `MemoryLow=${PROBE_MEMORY_MAX / 4}`] : []),
             '-p',
             `MemoryHigh=${PROBE_MEMORY_MAX / 2}`,
             '-p',
@@ -485,7 +523,7 @@ function execErrorText(error) {
  */
 async function readSystemdRunVersion() {
     try {
-        const { stdout } = await execFileAsync('systemd-run', ['--version'], { timeout: 10_000 });
+        const { stdout } = await runSystemdRun(['--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;
@@ -504,7 +542,9 @@ async function showMemoryMax(unit) {
  */
 async function showByteCount(unit, property) {
     try {
-        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', unit, '-p', property, '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const { stdout } = await runSystemctl(['show', unit, '-p', property, '--value'], {
+            timeout: 10_000,
+        });
         const raw = stdout.trim();
         if (!/^\d+$/.test(raw))
             return null;
@@ -562,6 +602,7 @@ export async function detectSessionCage(probe = defaultCageProbe) {
         serviceMemoryMaxBytes: null,
         sessionsSliceMemoryMaxBytes: null,
         expandEnvironmentFlag: false,
+        memoryLowFlag: false,
     });
     const fsType = probe.cgroupFsType();
     // Not «contains cgroup2» — exactly cgroup2fs. `tmpfs` at this path is cgroup
@@ -595,10 +636,30 @@ export async function detectSessionCage(probe = defaultCageProbe) {
     // 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 });
+    /**
+     * `MemoryLow` on a SCOPE, tried the same way and for the same reason (#398 S3).
+     *
+     * The guarantee is a new `-p` on a command line that has been stable for two
+     * releases, and a `-p` an older systemd does not take makes `systemd-run` exit
+     * 1 and spawn NOTHING — which on that machine is not a missing feature, it is
+     * every session failing to start. The fleet runs systemd 249, 252 and 255, and
+     * only 255 could be tried here. So it is probed, and a refusal costs the
+     * machine its guarantees and nothing else.
+     */
+    let memoryLowFlag = true;
+    let probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag, memoryLowFlag });
     if (probed.error !== null && refusesOomPolicy(probed.error)) {
         oomPolicyFlag = false;
-        probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag });
+        probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag, memoryLowFlag });
+    }
+    if (probed.error !== null && refusesMemoryLow(probed.error)) {
+        memoryLowFlag = false;
+        probed = await probe.probeMemoryMax({ expandEnvironmentFlag, oomPolicyFlag, memoryLowFlag });
+        if (probed.error === null) {
+            log.warn('session cage: this systemd will not take MemoryLow on a scope — no guarantees here', {
+                why: 'the brake and the wall are unaffected; only MemoryLow is dropped',
+            });
+        }
     }
     if (probed.error !== null) {
         // Not «the cage did not hold» — nothing was ever caged. Blaming `memory.max`
@@ -625,6 +686,7 @@ export async function detectSessionCage(probe = defaultCageProbe) {
         serviceMemoryMaxBytes,
         sessionsSliceMemoryMaxBytes,
         expandEnvironmentFlag,
+        memoryLowFlag,
     };
 }
 /** The `-p` assignment itself, in one place: the probe and the spawn must agree. */
@@ -640,6 +702,10 @@ const OOM_POLICY_CONTINUE = 'OOMPolicy=continue';
 export function refusesOomPolicy(error) {
     return /OOMPolicy/i.test(error);
 }
+/** The same question for `MemoryLow=`, and the same wording from systemd. */
+export function refusesMemoryLow(error) {
+    return /MemoryLow/i.test(error);
+}
 /**
  * Before the detector has run, nothing is wrapped.
  *
@@ -658,6 +724,7 @@ const UNPROBED = {
     serviceMemoryMaxBytes: null,
     sessionsSliceMemoryMaxBytes: null,
     expandEnvironmentFlag: false,
+    memoryLowFlag: false,
 };
 let detected = null;
 /**
@@ -667,8 +734,31 @@ let detected = null;
  * 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);
+export async function initSessionCage(probe = defaultCageProbe, options = {}) {
+    const found = await detectSessionCage(probe);
+    /**
+     * A re-probe that comes back WORSE does not take the cage away (#398).
+     *
+     * The live probe is a `systemd-run`, and one transient failure — a busy bus,
+     * a momentary «Failed to connect» — answers `nice-only`. At daemon start that
+     * is the honest answer and the machine simply runs uncaged. On the HOURLY
+     * re-measure it is something else entirely: from that moment every new
+     * session on a perfectly good machine would start with no cage, until
+     * somebody restarted the runner. An hourly job must not be able to do that
+     * (found by the independent review of 10.09.2026).
+     *
+     * Losing the cage for real is possible — cgroups remounted, the user bus gone
+     * — and it is not silent: the line below says so, loudly, every hour, and the
+     * next daemon start settles it either way.
+     */
+    if (options.keepCageIfWorse && detected?.mode === 'scope' && found.mode !== 'scope') {
+        log.error('session cage: the re-measure lost the cage — keeping what the last probe proved', {
+            reason: found.reason,
+            hint: 'restart the runner if this machine really has no cgroups any more',
+        });
+        return detected;
+    }
+    detected = found;
     if (detected.mode === 'scope') {
         log.info('session cage: each session gets its own cgroup', {
             slice: SESSIONS_SLICE,
@@ -725,6 +815,30 @@ const liveUnits = new Map();
 export function sessionScopeUnitOf(id) {
     return liveUnits.get(id) ?? null;
 }
+/**
+ * The pid of the agent process of each live session (#403).
+ *
+ * Written by the adapters right after the spawn — `systemd-run --scope` execs
+ * into the same pid, so this IS the process inside the cage — and read by the
+ * stall mechanism, which must never choose the agent as the command to stop.
+ *
+ * The structural rule it replaces («the agent is the one process whose parent
+ * is outside the scope») is true of the agent and true of one other thing: an
+ * MCP server whose launcher exited. Under the old rule such an orphan became a
+ * root, was protected on that account, and its own children — a browser, a
+ * language server — lost the protection they had. Knowing the pid tells the two
+ * apart, and it costs one map.
+ */
+const agentPids = new Map();
+/** Remember which process is the agent of this session. */
+export function noteSessionAgentPid(id, pid) {
+    if (typeof pid === 'number' && pid > 0)
+        agentPids.set(id, pid);
+}
+/** The agent's pid for a live session, or null when nothing has said. */
+export function sessionAgentPid(id) {
+    return agentPids.get(id) ?? null;
+}
 /**
  * Wrap a command in its session's cage, or hand it back untouched.
  *
@@ -737,8 +851,30 @@ export function sessionScopeUnitOf(id) {
  * 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).
+ *
+ * Untouched is also the answer for a process that has no right to put units on
+ * this machine (#403). It is the mildest of the doors in `cage-authority.ts`:
+ * the command still runs, it simply runs uncaged, which is exactly what happens
+ * on every machine without cgroups.
  */
 export function cageSpawn(input) {
+    if (!mayStartScope(SESSION_SCOPE_PREFIX)) {
+        log.warn('session cage: this process may not create cages, the command runs uncaged', {
+            id: input.id,
+        });
+        return { command: input.command, args: input.args, env: {}, unit: null };
+    }
+    return buildCagedSpawn(input);
+}
+/**
+ * The command line itself, with no question of who is allowed to run it.
+ *
+ * Split out from {@link cageSpawn} so the shape of the line stays testable: the
+ * suite proves what `systemd-run` would be handed, and the door above proves
+ * who may hand it. One function could not do both — a test process legitimately
+ * needs the first answer and must never get the second.
+ */
+export function buildCagedSpawn(input) {
     const facts = sessionCage();
     if (facts.mode !== 'scope' ||
         facts.memoryMaxBytes === null ||
@@ -746,6 +882,20 @@ export function cageSpawn(input) {
         facts.swapMaxBytes === null) {
         return { command: input.command, args: input.args, env: {}, unit: null };
     }
+    /**
+     * The live numbers if anything can give them, the daemon-start snapshot
+     * otherwise (#398 S3, work 9).
+     *
+     * Without this a session started at 03:00 would run for its first half-minute
+     * on the formula of whenever the daemon last started, and then jump. The
+     * allocator is asked to compute as though this session already existed, so
+     * the number it is born with is the number its first tick will confirm.
+     */
+    const live = liveLadderSource?.(input.id) ?? null;
+    const highBytes = live?.highBytes ?? facts.memoryHighBytes;
+    const maxBytes = live?.maxBytes ?? facts.memoryMaxBytes;
+    const swapMaxBytes = live?.swapBytes ?? facts.swapMaxBytes;
+    const guaranteedBytes = live?.guaranteedBytes ?? null;
     const attempt = (attempts.get(input.id) ?? 0) + 1;
     attempts.set(input.id, attempt);
     const unit = sessionScopeUnit(input.id, attempt);
@@ -767,21 +917,28 @@ export function cageSpawn(input) {
             // 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 guarantee: what will not be reclaimed from this session when the
+            // slice as a whole comes under pressure (#398 S3). Only where the
+            // allocator could compute one — a number nobody stands behind is worse
+            // than none.
+            ...(guaranteedBytes === null || !facts.memoryLowFlag
+                ? []
+                : ['-p', `MemoryLow=${guaranteedBytes}`]),
             // 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}`,
+            `MemoryHigh=${highBytes}`,
             // 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}`,
+            `MemoryMax=${maxBytes}`,
             // 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}`,
+            `MemorySwapMax=${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
@@ -843,8 +1000,14 @@ export function parseScopeMemoryStatus(files) {
         ownLimitOom: event('oom'),
     };
 }
-/** Where a session scope's cgroup lives, or null off a user manager. */
-function scopeCgroupDir(unit) {
+/**
+ * Where a session scope's cgroup lives, or null off a user manager.
+ *
+ * Exported for `session-stall.ts`, which reads three more files out of the same
+ * directory (`memory.pressure`, `memory.stat`, `cgroup.procs`). One resolver,
+ * so the two modules can never disagree about which cgroup a session is in.
+ */
+export function scopeCgroupDir(unit) {
     const self = readSelfCgroup();
     if (self === null)
         return null;
@@ -882,6 +1045,223 @@ export function readScopeMemoryStatus(unit, readFile = (p) => fs.readFileSync(p,
         return null;
     }
 }
+/**
+ * What a live session holds, for the allocator (#398 S3).
+ *
+ * `readCgroupMemory` rather than a second parser: it already takes page cache
+ * out and puts `shmem` back, which is the difference between «cache we can give
+ * back» and «memory something would have to be killed for», and getting that
+ * wrong inflates every number by whatever the machine happened to have cached
+ * (measured at +19 % on this host).
+ */
+export function readScopeHold(unit) {
+    const dir = scopeCgroupDir(unit);
+    if (dir === null)
+        return null;
+    const reading = readCgroupMemory(dir);
+    if (reading === null)
+        return null;
+    return {
+        currentBytes: reading.currentBytes,
+        holdBytes: reading.unreclaimableBytes ?? reading.currentBytes,
+    };
+}
+/**
+ * The slice's own two limits, from the filesystem rather than the bus.
+ *
+ * Live on purpose. What the probe found at daemon start is a snapshot, and the
+ * pot moves: the hourly `repairResourceLimits` rewrites it from a fresh
+ * measurement, and a machine whose neighbours grew or shrank gets a different
+ * number. Reading two small files on the tick costs nothing and cannot be stale;
+ * a `systemctl show` would cost a bus call measured at 2.7 s under load.
+ */
+export function readSliceLimits(readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    /**
+     * The slice's path, from the READER's own cgroup where that works — and from
+     * the user id where it does not.
+     *
+     * `sliceCgroupPath(readSelfCgroup(), …)` answers null for anything that is
+     * not itself under the user manager: a login-session scope, a `systemd-run`
+     * scope, a bare shell. That is fine for the DAEMON, which always is, and
+     * quite wrong for `doctor` — which the installer runs through `setpriv`,
+     * keeping the installer's own cgroup. The result was that a freshly and
+     * correctly installed machine reported «collective brake MISSING» on its very
+     * first acceptance run. Found by the independent review of 10.09.2026.
+     */
+    const dir = sessionsSliceCgroupDir();
+    if (dir === null)
+        return null;
+    const limit = (name) => {
+        try {
+            const raw = readFile(path.join(dir, name)).trim();
+            if (raw === 'max' || !/^\d+$/.test(raw))
+                return null;
+            const value = Number(raw);
+            return Number.isSafeInteger(value) ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const potBytes = limit('memory.max');
+    const collectiveBrakeBytes = limit('memory.high');
+    // `memory.low` reads `0` when nothing protects the slice, and `limit()` turns
+    // only `max` into null — so zero survives, which is the whole point here.
+    const guaranteeBytes = limit('memory.low');
+    if (potBytes === null && collectiveBrakeBytes === null)
+        return null;
+    return { potBytes, collectiveBrakeBytes, guaranteeBytes };
+}
+/**
+ * Where `devbridge-sessions.slice` lives on this machine.
+ *
+ * Two ways of answering, and the second is what makes this usable from a
+ * command the operator typed. The first is the reader's own cgroup, which is
+ * exact whenever the reader is under the user manager. The second builds the
+ * path from the user id, exactly as `userManagerCgroupControllers()` already
+ * does — a `systemd-run` scope, a login session and a bare shell all get the
+ * right answer that way, and the daemon gets the same one either way.
+ */
+export function sessionsSliceCgroupDir(io = {}) {
+    const selfCgroup = io.selfCgroup ?? readSelfCgroup;
+    const exists = io.exists ?? ((p) => fs.existsSync(p));
+    const self = selfCgroup();
+    const fromSelf = self === null ? null : sliceCgroupPath(self, SESSIONS_SLICE);
+    if (fromSelf !== null)
+        return fromSelf;
+    /**
+     * Whose user manager, when the reader's own cgroup cannot say.
+     *
+     * Two candidates and the order matters (#398 S7, B6). The runner's OWN uid
+     * comes first — that is the daemon and every ordinary CLI. But `doctor` is
+     * routinely run as `sudo devbridge-runner doctor` on a machine installed with
+     * `--user devbridge`, and then the process's uid is root's while the slice
+     * lives under the service user's manager: a correctly installed machine
+     * reported «collective brake MISSING» on its first acceptance run.
+     *
+     * The owner of the runner's state directory IS the service user, by
+     * construction — the installer creates it as them — so it is the honest
+     * second guess, and it costs one `stat`.
+     */
+    const uids = [io.selfUid?.() ?? runnerIdentity().uid, io.ownerUid?.() ?? stateDirOwnerUid()];
+    for (const uid of uids) {
+        if (uid < 0)
+            continue;
+        const guess = path.join('/sys/fs/cgroup/user.slice', `user-${uid}.slice`, `user@${uid}.service`, DEVBRIDGE_SLICE, SESSIONS_SLICE);
+        try {
+            if (exists(guess))
+                return guess;
+        }
+        catch {
+            // Unreadable is «not here», and the next candidate may still answer.
+        }
+    }
+    return null;
+}
+/** The uid that owns the runner's state directory — the service user. */
+function stateDirOwnerUid() {
+    try {
+        return fs.statSync(stateDir()).uid;
+    }
+    catch {
+        return -1;
+    }
+}
+let liveLadderSource = null;
+export function setLiveLadderSource(source) {
+    liveLadderSource = source;
+}
+/**
+ * The two numbers this session may be TOLD about (#398 S5).
+ *
+ * The guarantee and the ceiling, and deliberately not the live share. The share
+ * is recomputed every 30 s, so any value of it put into an environment variable
+ * or into a system prompt is stale within half a minute — and a number the agent
+ * believes and acts on after it has stopped being true is worse than no number.
+ * The guarantee is a constant of the formula and the ceiling barely moves.
+ *
+ * Null on a machine with no cage: there is nothing to promise there, and «нет
+ * cgroup — держим ноль» (#257) means we say nothing rather than invent a limit.
+ */
+export function sessionMemoryFor(id) {
+    const facts = sessionCage();
+    if (facts.mode !== 'scope')
+        return null;
+    const live = liveLadderSource?.(id) ?? null;
+    if (live) {
+        return {
+            guaranteedBytes: live.guaranteedBytes,
+            maxBytes: live.maxBytes,
+            swapBytes: live.swapBytes,
+        };
+    }
+    if (facts.memoryMaxBytes === null)
+        return null;
+    return {
+        // Before the allocator has anything to say, the honest floor is the brake
+        // the daemon measured: it is what this session would be held to.
+        guaranteedBytes: facts.memoryHighBytes ?? 0,
+        maxBytes: facts.memoryMaxBytes,
+        swapBytes: facts.swapMaxBytes ?? 0,
+    };
+}
+/**
+ * What the agent is told, and how — one text for both CLIs (#398 S5).
+ *
+ * A shared builder rather than two literals for the reason `DIRECT_BRANCH_RULE`
+ * in `adapters/types.ts` is shared: the two system-prompt appends are hand-kept
+ * copies of one another, and a third place for them to diverge was not worth
+ * having.
+ *
+ * The live share is named as something the agent CANNOT know, on purpose. Half
+ * of the incident this whole plan comes from was an agent raising its own heap
+ * twice — to 4 GB, then to 6 GB, against a wall of 4296 MB — because nothing
+ * had ever told it there was a wall.
+ */
+export function sessionMemoryEnv(id) {
+    const memory = sessionMemoryFor(id);
+    if (memory === null)
+        return {};
+    const mb = (bytes) => String(Math.max(0, Math.floor(bytes / MIB)));
+    return {
+        DEVBRIDGE_SESSION_MEMORY_GUARANTEED_MB: mb(memory.guaranteedBytes),
+        DEVBRIDGE_SESSION_MEMORY_MAX_MB: mb(memory.maxBytes),
+    };
+}
+/** The sentence for the system prompt, or null on a machine with no cage. */
+export function sessionMemoryPromptLine(id) {
+    const memory = sessionMemoryFor(id);
+    if (memory === null)
+        return null;
+    const mb = (bytes) => Math.max(0, Math.round(bytes / MIB));
+    const swap = memory.swapBytes > 0
+        ? `This machine has swap, so going over your share slows you down.`
+        : `This machine has NO swap, so going over your share does not slow you down — it stops you.`;
+    /**
+     * A guarantee is named only when one is actually in force (#398 S7, B3).
+     *
+     * `guaranteedBytes` is zero when nothing wrote `MemoryLow` — the systemd here
+     * refuses the property, or the slice above has no protection of its own. The
+     * agent plans around what it is told, so telling it about two gigabytes that
+     * nobody reserved is worse than telling it nothing.
+     */
+    if (memory.guaranteedBytes <= 0) {
+        return (`- Memory: this session can never exceed ${mb(memory.maxBytes)} MB ` +
+            `(DEVBRIDGE_SESSION_MEMORY_MAX_MB), and it has NO reserved share on this machine — under ` +
+            `pressure the kernel may reclaim anything it holds. How much you get at any moment is decided ` +
+            `by the machine and changes; you cannot read it, so do not plan around a number. ${swap} ` +
+            `If a command stands still for three minutes for want of memory, DevBridge stops that command ` +
+            `(not the session) and tells you. Do not raise --max-old-space-size above the ceiling: it is ` +
+            `enforced outside your process, and asking for more only makes the command fail sooner.`);
+    }
+    return (`- Memory: this session is guaranteed ${mb(memory.guaranteedBytes)} MB and can never exceed ` +
+        `${mb(memory.maxBytes)} MB (DEVBRIDGE_SESSION_MEMORY_GUARANTEED_MB and ` +
+        `DEVBRIDGE_SESSION_MEMORY_MAX_MB). How much you get above the guarantee at any moment is decided ` +
+        `by the machine and changes; you cannot read it, so do not plan around a number. ${swap} ` +
+        `If a command stands still for three minutes for want of memory, DevBridge stops that command ` +
+        `(not the session) and tells you. Do not raise --max-old-space-size above the ceiling: it is ` +
+        `enforced outside your process, and asking for more only makes the command fail sooner.`);
+}
 /**
  * `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
@@ -973,13 +1353,7 @@ export function explainMemoryDeath(id) {
     return (`There was not enough memory for this session and ${stopped} — ` +
         'send a message to carry on; if it keeps happening, run fewer sessions at once or give the machine more memory.');
 }
-const realSystemctl = async (args) => {
-    const { stdout, stderr } = await execFileAsync('systemctl', ['--user', ...args], {
-        timeout: 15_000,
-        env: systemdUserEnv(),
-    });
-    return { stdout, stderr };
-};
+const realSystemctl = async (args) => await runSystemctl(args);
 function showValue(stdout, property) {
     const line = stdout
         .split('\n')
@@ -1001,6 +1375,9 @@ function showValue(stdout, property) {
 export async function releaseSessionScope(unit, id, systemctl = realSystemctl) {
     const running = releaseSessionScopeInner(unit, id, systemctl);
     if (id !== undefined) {
+        // The process this named is gone with the scope; a pid outliving it would be
+        // a pid that means something else by the time anybody reads it.
+        agentPids.delete(id);
         releasing.set(id, running);
         void running.finally(() => {
             if (releasing.get(id) === running)
@@ -1051,9 +1428,19 @@ async function releaseSessionScopeInner(unit, id, systemctl) {
     if (id !== undefined)
         liveUnits.delete(id);
     let result = null;
+    let tasksLeft = null;
     try {
-        const { stdout } = await systemctl(['show', unit, '-p', 'Result']);
+        // Both properties in ONE call: this runs on every process exit, and the bus
+        // was measured at 2.7 s under load — two round trips where one will do is a
+        // cost paid on the path that is walked most.
+        const { stdout } = await systemctl(['show', unit, '-p', 'Result', '-p', 'TasksCurrent']);
         result = showValue(stdout, 'Result');
+        // Explicitly null-checked, not coerced: `Number(null)` is 0, and reading a
+        // property systemd never printed as «no tasks left» would silently turn the
+        // stop below off. systemd's own «unknown» is `[not set]`, which is NaN.
+        const raw = showValue(stdout, 'TasksCurrent');
+        const tasks = raw === null ? Number.NaN : Number(raw);
+        tasksLeft = Number.isFinite(tasks) ? tasks : null;
     }
     catch {
         // Already collected — a clean exit takes its scope with it.
@@ -1068,6 +1455,41 @@ async function releaseSessionScopeInner(unit, id, systemctl) {
         if (id !== undefined)
             rememberDeathFromResult(id);
     }
+    /**
+     * The agent's process is gone and the scope still holds tasks — put the tree
+     * out, here and nowhere else.
+     *
+     * Until 0.58.0 this function only ever `show`ed and `reset-failed` the unit,
+     * and nothing anywhere stopped it: `park()` kills ONE pid (the CLI), so a
+     * `pnpm typecheck` or a `vite build` the agent had started went on eating
+     * memory for a session that no longer existed, and the next start of the same
+     * session met «Unit … was already loaded» and died as
+     * «codex app-server exited before the session was ready (code 1)» (gotcha
+     * §479, measured 09.09 on vmi3219930: 3.4 GB free instead of 8.5).
+     *
+     * Deliberately in the RELEASE path rather than as a second call from the
+     * supervisor's park: all three call sites (`claude.ts`, `codex-protocol.ts`,
+     * `verify.ts`) already come through here on process exit, so one place keeps
+     * both agents and the verify runs identical and cannot race a second release
+     * of the same unit.
+     *
+     * `TasksCurrent > 0` is the gate rather than an unconditional stop, because
+     * the normal case is an empty scope systemd has already collected, and
+     * `stop` on it would be a bus call per session exit for nothing.
+     */
+    if (tasksLeft !== null && tasksLeft > 0) {
+        log.warn('session cage: the agent is gone but its commands are not — stopping the scope', {
+            unit,
+            tasksLeft,
+        });
+        try {
+            await systemctl(['stop', unit]);
+        }
+        catch {
+            // A scope that ended between the read and the stop answers «not loaded».
+            // The sweep on the watch tick is the second line of defence.
+        }
+    }
     let forgotten = false;
     try {
         await systemctl(['reset-failed', unit]);
@@ -1146,32 +1568,160 @@ export async function listSessionScopes(systemctl = realSystemctl) {
     }
     return out;
 }
+export function scopeOwnerLiveness(unit, io = {}) {
+    const readFile = io.readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
+    const cgroupDir = io.cgroupDir ?? scopeCgroupDir;
+    const isAlive = io.isAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                // `EPERM` means it exists and belongs to somebody else — alive either way.
+                return error.code === 'EPERM';
+            }
+        });
+    const dir = cgroupDir(unit);
+    if (dir === null)
+        return 'unknown';
+    let pids;
+    try {
+        pids = readFile(path.join(dir, 'cgroup.procs'))
+            .split('\n')
+            .map((line) => Number(line.trim()))
+            .filter((pid) => Number.isSafeInteger(pid) && pid > 0);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (pids.length === 0)
+        return 'empty';
+    let sawUnknown = false;
+    for (const pid of pids) {
+        let ppid;
+        try {
+            const status = readFile(path.join('/proc', String(pid), 'status'));
+            const line = status.split('\n').find((l) => l.startsWith('PPid:'));
+            const value = line === undefined ? Number.NaN : Number(line.slice('PPid:'.length).trim());
+            ppid = Number.isSafeInteger(value) ? value : null;
+        }
+        catch {
+            // Ended between the listing and the read — says nothing either way.
+            continue;
+        }
+        if (ppid === null) {
+            sawUnknown = true;
+            continue;
+        }
+        // Reparented to init: nobody is waiting on this process. `0` is the kernel's
+        // answer for a process that is going away.
+        if (ppid <= 1)
+            continue;
+        /**
+         * …and reparented to the USER MANAGER counts the same (measured 10.09.2026).
+         *
+         * `systemd --user` sets itself as a subreaper, so an orphan inside a user
+         * scope does not land on pid 1 at all — it lands on the manager, whose pid
+         * is an ordinary live pid. Read literally, «the parent is alive» then made
+         * every orphan look supervised, and the sweep would never remove anything
+         * again: the opposite failure to the one this whole change is about, and
+         * just as silent.
+         */
+        let parentComm;
+        try {
+            parentComm = readFile(path.join('/proc', String(ppid), 'comm')).trim();
+        }
+        catch {
+            // The parent went between the two reads: it is not supervising anything.
+            continue;
+        }
+        if (parentComm === 'systemd' || parentComm === 'init')
+            continue;
+        if (isAlive(ppid))
+            return 'owned';
+    }
+    return sawUnknown ? 'unknown' : 'orphaned';
+}
 /**
- * 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.
+ * Is this unit, RIGHT NOW, a cage somebody is running in?
  *
- * `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.
+ * A scan rather than a snapshot on purpose — the freshness is the point — and a
+ * scan rather than `new Set(liveUnits.values()).has(unit)`, which built a set
+ * per unit inside the sweep's loop for nothing. The register holds one entry
+ * per live session; on the biggest machine of the fleet that is six.
  */
-export async function sweepOrphanSessionScopes(liveIds = [], systemctl = realSystemctl) {
-    const spared = new Set();
+function isLiveCageUnit(unit) {
+    for (const live of liveUnits.values())
+        if (live === unit)
+            return true;
+    return false;
+}
+export async function sweepOrphanSessionScopes(liveIds = [], systemctl = realSystemctl, liveness = scopeOwnerLiveness) {
+    /**
+     * Asked here, and not left to the door in `cage-authority.ts` (#403).
+     *
+     * The loop below catches every failed `systemctl` on purpose — a scope that
+     * is already `failed` has nothing to stop — so a refusal down there would be
+     * swallowed and this function would report units as removed that it never
+     * touched. The register `liveUnits` is empty in any process but the daemon's,
+     * which is precisely why this function is the dangerous one: to a foreign
+     * process every real cage on the machine looks like litter.
+     */
+    if (systemctl === realSystemctl && !mayActOnSessionCages()) {
+        log.warn('session cage: this process may not sweep cages, nothing was touched', {
+            role: cageAuthority(),
+        });
+        return [];
+    }
+    const spared = new Set(liveUnits.values());
     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]);
+        /**
+         * …and asked AGAIN, immediately before the stop.
+         *
+         * `spared` is a snapshot, and between it and this line there are two
+         * `systemctl` calls — the listing, and every stop before this one — each of
+         * which the bus has been measured to hold for 2.7 s under load. A session
+         * that started inside that window would be in `list-units` and not in the
+         * snapshot, and this call would kill it. Found by the independent review of
+         * 10.09.2026.
+         *
+         * `liveUnits` is filled by `cageSpawn` BEFORE `systemd-run` is spawned, so
+         * a scope cannot exist without its name being in there first.
+         */
+        if (isLiveCageUnit(unit))
+            continue;
+        /**
+         * …and the kernel is asked too, because the register above only knows what
+         * THIS process started (#403).
+         *
+         * `owned` means a live parent outside the cage is supervising what is
+         * inside it — another daemon's session, or this machine's own runner seen
+         * from a second process. Whatever it is, it is not litter, and stopping it
+         * is the incident of 10.09.2026. `unknown` gets the same answer for the
+         * same reason: the sweep may only act on what it can prove.
+         */
+        const state = liveness(unit);
+        if (state === 'owned' || state === 'unknown') {
+            log.warn('session cage: left a scope alone — somebody is running in it', {
+                unit,
+                liveness: state,
+            });
+            continue;
         }
-        catch {
-            // A failed scope has nothing to stop; `reset-failed` below is the part
-            // that matters for it.
+        if (state !== 'empty') {
+            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]);