@bridge4dev/runner 0.54.0 → 0.55.1

package/dist/session-cage.js

@@ -6,7 +6,7 @@ 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';
+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
@@ -25,17 +25,28 @@ const execFileAsync = promisify(execFile);
  * `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
+ *  - `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.
- *  - 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`.
+ *    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
@@ -74,10 +85,14 @@ const execFileAsync = promisify(execFile);
 const MIB = 1024 * 1024;
 const GIB = 1024 * MIB;
 /**
- * What one session may hold. **Proposal Р3 of the plan, awaiting the owner.**
+ * 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/active/agent-sessions-host-resources.md`. Both halves matter:
+ * `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
@@ -94,7 +109,7 @@ const GIB = 1024 * MIB;
  * 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);
+export const SESSION_MEMORY_HIGH_ABSOLUTE_BYTES = Math.round(2.5 * GIB);
 /**
  * Processes and threads per session.
  *
@@ -128,7 +143,30 @@ export const SESSION_SCOPE_PREFIX = 'devbridge-session-';
  * 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;
+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.
  *
@@ -147,14 +185,111 @@ export const SESSION_MEMORY_MIN_BYTES = 2 * GIB;
  * 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;
+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 half = Math.floor(containingMemoryMaxBytes / 2);
-    const clamped = Math.min(SESSION_MEMORY_MAX_ABSOLUTE_BYTES, Math.max(SESSION_MEMORY_MIN_BYTES, half));
+    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.
-    return Math.max(1, Math.min(clamped, Math.floor(containingMemoryMaxBytes)));
+    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 ──────────────────────────────────────────────────────
 /**
@@ -297,9 +432,14 @@ async function runLiveProbe(options) {
             // 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',
@@ -355,15 +495,31 @@ async function readSystemdRunVersion() {
     }
 }
 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', 'MemoryMax', '--value'], { timeout: 10_000, env: systemdUserEnv() });
-        const value = Number(stdout.trim());
-        return Number.isFinite(value) && value > 0 ? value : null;
+        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'),
@@ -378,6 +534,9 @@ export const defaultCageProbe = {
     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
@@ -396,7 +555,10 @@ 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,
@@ -426,7 +588,18 @@ export async function detectSessionCage(probe = defaultCageProbe) {
     // 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 });
+    // `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.
@@ -437,17 +610,36 @@ export async function detectSessionCage(probe = defaultCageProbe) {
     }
     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: '',
-        // 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),
+        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.
  *
@@ -459,7 +651,10 @@ export async function detectSessionCage(probe = defaultCageProbe) {
 const UNPROBED = {
     mode: 'nice-only',
     reason: 'not probed yet',
+    memoryHighBytes: null,
     memoryMaxBytes: null,
+    swapMaxBytes: null,
+    oomContinue: false,
     serviceMemoryMaxBytes: null,
     sessionsSliceMemoryMaxBytes: null,
     expandEnvironmentFlag: false,
@@ -477,7 +672,10 @@ export async function initSessionCage(probe = defaultCageProbe) {
     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,
@@ -517,6 +715,16 @@ export function sessionCage() {
  * 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.
  *
@@ -532,12 +740,21 @@ const attempts = new Map();
  */
 export function cageSpawn(input) {
     const facts = sessionCage();
-    if (facts.mode !== 'scope' || facts.memoryMaxBytes === null) {
+    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: [
@@ -550,14 +767,26 @@ 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 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 it there is no cage at all: `MemoryMax` bounds
+            // 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.
-            // Never remove, never make conditional.
+            // 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=0',
+            `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',
@@ -583,6 +812,167 @@ export function cageSpawn(input) {
 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);
+}
+/**
+ * «a process in it was stopped» / «3 processes in it were stopped», so the verb
+ * agrees. Shared with the supervisor's feed notices, which count the same
+ * thing and must not word it differently.
+ */
+export function stoppedProcesses(count, where = 'it') {
+    return count === 1
+        ? `a process in ${where} was stopped`
+        : `${count} processes in ${where} were stopped`;
+}
+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.
+        reached: status.ownLimitOom > 0 ? 'own-ceiling' : 'shared-pool',
+    });
+}
+/**
+ * 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 reached is
+        // not in `Result`, and neither claim may be guessed.
+        reached: 'unknown',
+    });
+}
+/**
+ * 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 stopped = stoppedProcesses(death.oomKills);
+    const ceiling = death.maxBytes === null ? '' : ` of ${Math.round(death.maxBytes / MIB)} MB`;
+    if (death.reached === 'own-ceiling') {
+        return (`This session reached its memory ceiling${ceiling} and ${stopped} — ` +
+            'send a message to carry on; if it keeps happening, the machine needs more memory.');
+    }
+    if (death.reached === 'shared-pool') {
+        return (`The machine ran out of memory for agent sessions and ${stoppedProcesses(death.oomKills, 'this one')} — ` +
+            'send a message to carry on; if it keeps happening, run fewer sessions at once or give the machine more memory.');
+    }
+    // Which ceiling was reached is unknowable here, so the sentence names no
+    // culprit: it has to be true whether this session was the greedy one or a
+    // bystander.
+    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,
@@ -609,8 +999,57 @@ function showValue(stdout, property) {
  * 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']);
@@ -624,6 +1063,10 @@ export async function releaseSessionScope(unit, id, systemctl = realSystemctl) {
             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 {