@bridge4dev/runner 0.54.0 → 0.55.0

package/dist/adapters/claude.js

@@ -6,7 +6,7 @@ import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
 import { mcpConfigPath } from '../paths.js';
 import { lowerPriority } from '../process-priority.js';
-import { cageSpawn, releaseSessionScope } from '../session-cage.js';
+import { cageSpawn, memoryDeathSentence, releaseSessionScope } from '../session-cage.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
@@ -2444,9 +2444,17 @@ class ClaudeSession {
             // appended it to as well.
             const message = maskString(String(error instanceof Error ? error.message : error) + this.stderrSuffix());
             const code = errorCode(message);
+            // #387: «exited with code 143» and «terminated by signal SIGKILL» were the
+            // two faces of one cause — the kernel's OOM killer inside this session's
+            // cgroup — and neither said so. The cage remembers the kill counter at
+            // exit; when it moved, the sentence about memory rides on the error.
+            // Awaited, not read: on a systemd that stops the whole scope the cgroup
+            // is already gone when the process's `exit` fires, and the only surviving
+            // record is `Result=oom-kill`, which the release is still fetching.
+            const memory = await memoryDeathSentence(this.spec.sessionId);
             this.emit({
                 type: 'error',
-                message: classifyRunError(message),
+                message: memory ? `${classifyRunError(message)} ${memory}` : classifyRunError(message),
                 ...(code ? { code } : {}),
                 // #373: this catch is the CLI process falling over under the read loop —
                 // the only place in this adapter where that is what happened. Our own

package/dist/adapters/codex.js

@@ -1,6 +1,7 @@
 import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
+import { memoryDeathSentence } from '../session-cage.js';
 import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
@@ -1866,8 +1867,36 @@ class CodexSession {
                 processGone: true,
             });
         }
+        if (!this.stopped)
+            this.sayIfMemoryKilledIt();
         this.finish();
     }
+    /**
+     * «codex app-server exited (code null)» is the same sentence whether the CLI
+     * crashed or the kernel took it for memory, and #387 is the ticket about
+     * exactly that silence. The cage knows which it was; here it reaches the
+     * person.
+     *
+     * A follow-up `notice` rather than a longer error message, because both death
+     * paths in this adapter are synchronous by design (one is a notification
+     * handler, the other a catch that closes the output queue on the next line),
+     * and the verdict needs an await — `Result=oom-kill` is read after the exit.
+     */
+    sayIfMemoryKilledIt() {
+        if (this.memoryVerdictAsked)
+            return;
+        this.memoryVerdictAsked = true;
+        void memoryDeathSentence(this.spec.sessionId)
+            .then((sentence) => {
+            if (sentence)
+                this.emit({ type: 'notice', level: 'warn', text: sentence });
+        })
+            .catch(() => {
+            // A verdict we could not fetch is no verdict; the error text stands.
+        });
+    }
+    /** One verdict per process — both death paths can fire for the same exit. */
+    memoryVerdictAsked = false;
     // ─── Capabilities ──────────────────────────────────────────────────
     refreshCapabilities() {
         if (this.capabilitiesInFlight || this.stopped)
@@ -2120,6 +2149,10 @@ class CodexSession {
             return code;
         }
         this.emit({ type: 'error', message: `Codex session error: ${message.slice(0, 1_000)}` });
+        // The generic door: a pending request rejected because the app-server died
+        // (`failAll`). If the kernel is why it died, say so (#387).
+        if (/app-server exited|SIGKILL/i.test(message))
+            this.sayIfMemoryKilledIt();
         return null;
     }
     /**

package/dist/index.js

@@ -423,9 +423,27 @@ function runnerCapabilities(apiUrlOverride) {
             // Why not `scope`, in one sentence, for the card to show under it.
             // Empty string when the cage is on.
             sessionCageReason: sessionCage().reason,
-            // What ONE session may hold, in bytes. Null when there is no cage —
-            // then the only ceiling is the service's, over all of them together.
+            /**
+             * The ladder one session lives under (#387), in bytes. Null when there is
+             * no cage — then the only ceiling is the service's, over all of them.
+             *
+             * `High` is the brake: past it the kernel slows the session down instead
+             * of killing. `Max` is the wall, far above — the machine's measured
+             * headroom, where only a runaway ever arrives. Runners up to 0.54.0 sent
+             * `Max` alone, and it was the kill line at 2.5 GiB; a card that sees no
+             * `High` is looking at one of those.
+             */
+            sessionMemoryHighBytes: sessionCage().memoryHighBytes,
             sessionMemoryMaxBytes: sessionCage().memoryMaxBytes,
+            /** Swap one session may push into while braked. 0 on a machine without swap. */
+            sessionSwapMaxBytes: sessionCage().swapMaxBytes,
+            /**
+             * Whether reaching the wall costs the session ONE process (`OOMPolicy=
+             * continue` on the scope) or is left to that systemd's own default —
+             * older systemds do not take the setting on a scope at all. The card
+             * words the wall by it.
+             */
+            sessionOomContinue: sessionCage().oomContinue,
             /**
              * The ceiling over ALL sessions, as systemd has it in force — not as the
              * drop-in on disk says.
@@ -1425,7 +1443,10 @@ async function cmdDoctor(args) {
     print(`                  ${devbridgeSliceOverridePath()}`);
     if (cage.mode === 'scope') {
         const mb = (bytes) => bytes === null ? 'infinity' : `${Math.round(bytes / 1024 / 1024)} MB`;
-        print(`  per session     MemoryMax ${mb(cage.memoryMaxBytes)}, MemorySwapMax 0, TasksMax ${SESSION_TASKS_MAX}`);
+        print(`  per session     MemoryHigh ${mb(cage.memoryHighBytes)} (brake: slows, never kills), MemoryMax ${mb(cage.memoryMaxBytes)} (wall), MemorySwapMax ${mb(cage.swapMaxBytes)}, TasksMax ${SESSION_TASKS_MAX}`);
+        print(`  at the wall     ${cage.oomContinue
+            ? 'OOMPolicy=continue — the kernel kills the hungriest process, the session stays up'
+            : 'this systemd does not take OOMPolicy on a scope (it is newer than the rest of the cage), so what happens at the wall is its own default — on systemd 253+ that is «stop the whole session»'}`);
         // What systemd has IN FORCE on the slice, beside the paths of the files
         // that were supposed to put it there. «В файле 7680M, действует 6.0G» is the
         // lesson of §5.5, and the drop-in of a slice can fail to land in exactly the
@@ -1436,7 +1457,7 @@ async function cmdDoctor(args) {
             print('                  NOT CAPPED — the drop-in above has not been applied.');
             print(`                  Apply with: ${systemctlHint('daemon-reload')}`);
         }
-        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (the per-session figure is half of the containing ceiling, capped)`);
+        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (the per-session brake is half of the containing ceiling, capped at 2.5 GiB; the wall IS the containing ceiling)`);
         print(`  expand-env flag ${cage.expandEnvironmentFlag ? 'passed (systemd ≥ 254)' : 'not passed — this systemd does not know it, and --scope does not expand anyway'}`);
     }
     else {

package/dist/service-unit.d.ts

@@ -57,7 +57,7 @@ export declare function buildUnit(execStart?: string, nodeBinary?: string): stri
  * which is the only way to fix the servers that already have the bad numbers
  * baked in — and it never overwrites a unit the operator edited by hand.
  */
-export declare const LIMITS_VERSION = 4;
+export declare const LIMITS_VERSION = 5;
 /**
  * Where the agent sessions live once they have a cage of their own.
  *
@@ -152,10 +152,29 @@ export interface MemoryFacts {
     sessionsFloorBytes?: number;
     /** Seconds since boot. Below `BOOT_SETTLE_SEC` the measurement is a lie. */
     uptimeSec: number;
+    /**
+     * `SwapTotal` — what the sessions' swap share is cut from (#387). Absent or 0
+     * means a machine without swap, and then the share is 0: the brake on such a
+     * machine can only drop page cache, and the wall is what stops a runaway.
+     */
+    swapTotalBytes?: number;
 }
+/**
+ * How much of the machine's swap ALL sessions together may use (#387).
+ *
+ * Half, not all: swap belongs to the machine (the spike's 200 MB cage drained
+ * the host's 2 GB and the box hung), so the other half stays with the neighbours
+ * and the kernel. Each session gets half of this again (`sessionSwapMaxBytes`).
+ * On the 2 GB swap this machine has today that is 512 MB per session — enough
+ * for a build's overshoot, not for a runaway; the owner's note on #387 is that
+ * the swap itself has to grow for the brake to have real room.
+ */
+export declare const SESSIONS_SWAP_SHARE = 0.5;
 export interface MemoryPolicy {
     maxBytes: number;
     highBytes: number;
+    /** `MemorySwapMax` for the sessions slice: `SESSIONS_SWAP_SHARE` of `SwapTotal`. */
+    swapMaxBytes: number;
     /** false = the conservative static pair, because the machine was still booting. */
     measured: boolean;
     /**
@@ -221,6 +240,19 @@ export declare function managedUsageFloorBytes(facts: MemoryFacts): number;
  *    machine, and a ceiling of «everything» is the bug this function exists to fix.
  */
 export declare function memoryPolicy(facts: MemoryFacts, minCeilingBytes?: number): MemoryPolicy;
+/** `SwapTotal` of this machine, or null where `/proc/meminfo` will not say. */
+export declare function readSwapTotalBytes(): number | null;
+/**
+ * What our own cgroup currently holds.
+ *
+ * Read through `/proc/self/cgroup` rather than assembling the path from the
+ * service name: the runner runs as root and as a dedicated user, under
+ * `user@0.service` and under `user@1001.service`, and guessing that path wrong
+ * silently returns 0 — which would quietly shrink the ceiling by whatever we are
+ * already using. Returns 0 on cgroup v1 or in a container without the file, which
+ * is the safe direction: a slightly lower ceiling, never a higher one.
+ */
+export declare function readSelfCgroup(): string | null;
 export declare function readOwnCgroupMemory(): CgroupMemory | null;
 /**
  * What the cgroup holds that `MemAvailable` has NOT already counted.
@@ -349,14 +381,18 @@ export declare function buildLimitsOverride(cpuCount?: number, facts?: MemoryFac
  * not the guarantee `memoryPolicy` computes, and it is written down here rather
  * than glossed over (QA-2026-09-07 MINOR-4).
  *
- * `MemorySwapMax=0` for the same reason it is on every scope: a ceiling on
- * resident memory alone is not a ceiling, it is a swap pump (a 200 MB cage
- * allocated 2 GB and drained the host's swap during the spike).
- *
- * No `MemoryHigh` here either. Soft pressure on the slice would throttle every
- * session on the machine to keep one runaway alive a little longer — the exact
- * trade the spike measured and rejected: 60 seconds of delays instead of a
- * 380 ms honest death.
+ * `MemorySwapMax` is a BOUND on the slice for the same reason it is on every
+ * scope: a ceiling on resident memory alone is not a ceiling, it is a swap pump
+ * (a 200 MB cage allocated 2 GB and drained the host's swap during the spike).
+ * Since #387 the bound is a share of the machine's swap rather than 0
+ * (`SESSIONS_SWAP_SHARE`), because each session now carries a `MemoryHigh`
+ * brake, and a brake with no swap under it stalls the session instead of
+ * slowing it. The unmeasured branch still writes 0: no measurement, no swap to
+ * hand out.
+ *
+ * No `MemoryHigh` here. The brake belongs on each SCOPE (`session-cage.ts`):
+ * soft pressure on the slice would throttle every session on the machine to
+ * keep one runaway alive a little longer.
  *
  * `sessionsUsageBytes` is the door that used to lead around all of the above.
  * `facts` is null whenever the SERVICE's `MemoryCurrent` is unreadable — a

package/dist/service-unit.js

@@ -129,7 +129,7 @@ export function buildUnit(execStart, nodeBinary = process.execPath) {
  * which is the only way to fix the servers that already have the bad numbers
  * baked in — and it never overwrites a unit the operator edited by hand.
  */
-export const LIMITS_VERSION = 4;
+export const LIMITS_VERSION = 5;
 const LIMITS_MARKER = '# devbridge-limits-version:';
 /** `zz-` so it sorts last: an operator's own drop-in should still win. */
 const LIMITS_FILE = 'zz-devbridge-limits.conf';
@@ -181,6 +181,17 @@ export function devbridgeSliceOverridePath(home = systemdUserHome()) {
 }
 const MIB = 1024 * 1024;
 const GIB = 1024 * MIB;
+/**
+ * How much of the machine's swap ALL sessions together may use (#387).
+ *
+ * Half, not all: swap belongs to the machine (the spike's 200 MB cage drained
+ * the host's 2 GB and the box hung), so the other half stays with the neighbours
+ * and the kernel. Each session gets half of this again (`sessionSwapMaxBytes`).
+ * On the 2 GB swap this machine has today that is 512 MB per session — enough
+ * for a build's overshoot, not for a runaway; the owner's note on #387 is that
+ * the swap itself has to grow for the brake to have real room.
+ */
+export const SESSIONS_SWAP_SHARE = 0.5;
 /**
  * How long after boot `MemAvailable` starts telling the truth.
  *
@@ -268,9 +279,16 @@ const CEILING_FLOOR_BYTES = 2 * GIB;
  */
 export function memoryPolicy(facts, minCeilingBytes = managedUsageFloorBytes(facts)) {
     const { totalBytes, availableBytes, ownUsageBytes, sessionsUsageBytes, uptimeSec } = facts;
+    const swapMaxBytes = Math.floor(Math.max(0, facts.swapTotalBytes ?? 0) * SESSIONS_SWAP_SHARE);
     const withFloor = (maxBytes, measured, starved = false) => {
         const ceiling = Math.floor(Math.max(maxBytes, minCeilingBytes));
-        return { maxBytes: ceiling, highBytes: Math.floor(ceiling * 0.8), measured, starved };
+        return {
+            maxBytes: ceiling,
+            highBytes: Math.floor(ceiling * 0.8),
+            swapMaxBytes,
+            measured,
+            starved,
+        };
     };
     // Still booting: the neighbours have not claimed their memory yet, so measuring
     // now would hand back almost the whole machine. Take a fraction of TOTAL
@@ -311,8 +329,8 @@ function clamp(value, low, high) {
 function asMiB(bytes) {
     return `${Math.max(1, Math.floor(bytes / MIB))}M`;
 }
-/** `MemTotal`/`MemAvailable` in bytes, or null where there is no `/proc`. */
-function readMemInfo() {
+/** One `kB` field of `/proc/meminfo`, in bytes; null when absent or unreadable. */
+function memInfoField(name) {
     let text;
     try {
         text = fs.readFileSync('/proc/meminfo', 'utf8');
@@ -320,13 +338,20 @@ function readMemInfo() {
     catch {
         return null;
     }
-    const field = (name) => {
-        const match = new RegExp(`^${name}:\\s+(\\d+) kB$`, 'm').exec(text);
-        return match?.[1] ? Number(match[1]) * 1024 : null;
-    };
-    const totalBytes = field('MemTotal');
-    const availableBytes = field('MemAvailable');
-    return totalBytes && availableBytes ? { totalBytes, availableBytes } : null;
+    const match = new RegExp(`^${name}:\\s+(\\d+) kB$`, 'm').exec(text);
+    return match?.[1] ? Number(match[1]) * 1024 : null;
+}
+/** `MemTotal`/`MemAvailable`/`SwapTotal` in bytes, or null where there is no `/proc`. */
+function readMemInfo() {
+    const totalBytes = memInfoField('MemTotal');
+    const availableBytes = memInfoField('MemAvailable');
+    // 0 is a real answer here (no swap), unlike the two above.
+    const swapTotalBytes = memInfoField('SwapTotal') ?? 0;
+    return totalBytes && availableBytes ? { totalBytes, availableBytes, swapTotalBytes } : null;
+}
+/** `SwapTotal` of this machine, or null where `/proc/meminfo` will not say. */
+export function readSwapTotalBytes() {
+    return memInfoField('SwapTotal');
 }
 /**
  * What our own cgroup currently holds.
@@ -338,7 +363,7 @@ function readMemInfo() {
  * already using. Returns 0 on cgroup v1 or in a container without the file, which
  * is the safe direction: a slightly lower ceiling, never a higher one.
  */
-function readSelfCgroup() {
+export function readSelfCgroup() {
     try {
         const line = fs
             .readFileSync('/proc/self/cgroup', 'utf8')
@@ -620,14 +645,18 @@ const MANAGED_HEADER = [
  * not the guarantee `memoryPolicy` computes, and it is written down here rather
  * than glossed over (QA-2026-09-07 MINOR-4).
  *
- * `MemorySwapMax=0` for the same reason it is on every scope: a ceiling on
- * resident memory alone is not a ceiling, it is a swap pump (a 200 MB cage
- * allocated 2 GB and drained the host's swap during the spike).
+ * `MemorySwapMax` is a BOUND on the slice for the same reason it is on every
+ * scope: a ceiling on resident memory alone is not a ceiling, it is a swap pump
+ * (a 200 MB cage allocated 2 GB and drained the host's swap during the spike).
+ * Since #387 the bound is a share of the machine's swap rather than 0
+ * (`SESSIONS_SWAP_SHARE`), because each session now carries a `MemoryHigh`
+ * brake, and a brake with no swap under it stalls the session instead of
+ * slowing it. The unmeasured branch still writes 0: no measurement, no swap to
+ * hand out.
  *
- * No `MemoryHigh` here either. Soft pressure on the slice would throttle every
- * session on the machine to keep one runaway alive a little longer — the exact
- * trade the spike measured and rejected: 60 seconds of delays instead of a
- * 380 ms honest death.
+ * No `MemoryHigh` here. The brake belongs on each SCOPE (`session-cage.ts`):
+ * soft pressure on the slice would throttle every session on the machine to
+ * keep one runaway alive a little longer.
  *
  * `sessionsUsageBytes` is the door that used to lead around all of the above.
  * `facts` is null whenever the SERVICE's `MemoryCurrent` is unreadable — a
@@ -664,8 +693,8 @@ export function buildSessionsSliceOverride(facts = readMemoryFacts(), sessionsUs
                 `MemoryMax=${asMiB(memory.maxBytes)}`,
             ]
             : unmeasuredSliceCeiling(sessionsUsageBytes)),
-        // The line the cage is built on. See `session-cage.ts`.
-        'MemorySwapMax=0',
+        // The line the cage is built on. See `session-cage.ts` and the note above.
+        `MemorySwapMax=${memory && memory.swapMaxBytes > 0 ? asMiB(memory.swapMaxBytes) : '0'}`,
         'TasksMax=8192',
         'MemoryAccounting=yes',
         'TasksAccounting=yes',
@@ -773,6 +802,14 @@ function fileIsOutdated(readFile, target, facts) {
  */
 const CEILING_DRIFT_TOLERANCE = 0.15;
 function memoryCeilingHasDrifted(contents, facts) {
+    // The swap share drifts for its own reason, and on its own schedule: an
+    // operator who enlarges the machine's swapfile (the one lever that makes the
+    // brake a brake rather than a freeze) would otherwise keep the old, smaller
+    // share until the next `LIMITS_VERSION` — and each session would keep getting
+    // half of it (#387 QA). Zero to non-zero and back is always drift; above that
+    // the same tolerance as the ceiling.
+    if (swapShareHasDrifted(contents, facts))
+        return true;
     // Never re-measure a machine that is still booting: the static pair it is
     // holding is deliberate, and «drift» against a lie is not drift.
     if (!memoryPolicy(facts).measured)
@@ -795,6 +832,19 @@ function memoryCeilingHasDrifted(contents, facts) {
     const wanted = memoryPolicy(facts).maxBytes;
     return Math.abs(writtenBytes - wanted) / wanted > CEILING_DRIFT_TOLERANCE;
 }
+function swapShareHasDrifted(contents, facts) {
+    const written = [...contents.matchAll(/^MemorySwapMax=(\d+)([KMG]?)$/gm)].at(-1);
+    // Not written at all: only the slice file carries this line, and the service
+    // file legitimately has none. Silence is not drift.
+    if (!written?.[1])
+        return false;
+    const scale = { '': 1, K: 1024, M: MIB, G: 1024 * MIB }[written[2] ?? ''] ?? MIB;
+    const writtenBytes = Number(written[1]) * scale;
+    const wanted = memoryPolicy(facts).swapMaxBytes;
+    if (writtenBytes === 0 || wanted === 0)
+        return writtenBytes !== wanted;
+    return Math.abs(writtenBytes - wanted) / wanted > CEILING_DRIFT_TOLERANCE;
+}
 /**
  * Write the drop-in. Returns false when nothing needed doing.
  *