@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/supervisor.d.ts

@@ -4,6 +4,8 @@ import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
 import { installAgent } from './agent-install.js';
 import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { type AgentVersionsMeasurement } from './agent-versions.js';
+import { type HostLoadFrame } from './host-load.js';
+import { type ScopeMemoryStatus } from './session-cage.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
 import type { AgentAdapter } from './adapters/types.js';
@@ -122,6 +124,37 @@ export interface SupervisorOptions {
      * in production.
      */
     stopSettleMs?: number;
+    /**
+     * Test seam for the host-load measurement (§5.3).
+     *
+     * A seam because the real one reads THIS machine's `/proc`, and a test that
+     * had to arrange the kernel into «load 12.4, swap 98 % used» would not be
+     * written — so the rule this frame exists for (send only what moved) would
+     * go unverified on the one machine shape that matters.
+     */
+    readHostLoad?: () => HostLoadFrame | null;
+    /**
+     * How often `/proc` is sampled, in ms — a test seam over
+     * `HOST_LOAD_SAMPLE_INTERVAL_MS`, for the same reason `agentCleanupMs`
+     * exists: the real cadence is 30 s and this suite runs on real timers (fake
+     * ones fire the WS client's liveness watchdog and kill the socket). Never
+     * set in production.
+     */
+    hostLoadSampleMs?: number;
+    /**
+     * The heartbeat window, in ms — a test seam over `HOST_LOAD_HEARTBEAT_MS`.
+     * The real one is five minutes; without this seam «an unchanged machine
+     * still reports» would be an untested promise. Never set in production.
+     */
+    hostLoadHeartbeatMs?: number;
+    /**
+     * #387: the memory watch's two readers, so a test can put a caged session
+     * over its brake without a cgroup under it. Production reads the cage module.
+     */
+    sessionScopeUnitOf?: (id: string) => string | null;
+    readScopeMemoryStatus?: (unit: string) => ScopeMemoryStatus | null;
+    /** How long over the brake before the second, «do something» warning. A test seam. */
+    cageBrakeLongMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -198,6 +231,23 @@ export declare class Supervisor {
     private readonly verify;
     private readonly verifyReports;
     constructor(ws: RunnerWsClient, opts: SupervisorOptions);
+    /**
+     * How long a session may sit over its brake before the feed says more than
+     * «slower» (#387, step 3). Five minutes is a starting point, not a
+     * measurement: an honest `pnpm typecheck` overshoots for tens of seconds, a
+     * runaway for ever, and the number that tells them apart on real machines is
+     * still to be read off `memory.events`. Sized so the first warning is never
+     * the only one a night-time run leaves behind.
+     */
+    private static readonly CAGE_BRAKE_LONG_MS;
+    /**
+     * Calm ticks before the feed says the braking is over.
+     *
+     * `memory.high` holds usage AT the line, so a single sample under it means
+     * nothing. Two (a minute at the 30 s cadence) is the difference between an
+     * episode that ended and a build that breathed.
+     */
+    private static readonly CAGE_CALM_TICKS_TO_RELEASE;
     /** How often the agent versions are re-derived. See the constructor. */
     private static readonly AGENT_VERSIONS_INTERVAL_MS;
     private readonly agentVersionsTimer;
@@ -346,6 +396,62 @@ export declare class Supervisor {
      * it had room. Both were caught by the independent QA review of this change.
      */
     private publishSlots;
+    /** The heartbeat window actually used — the constant, or a test's own. */
+    private readonly hostLoadHeartbeatMs;
+    private readonly hostLoadTimer;
+    /** The last measurement the API actually took from us, or `null` for «nothing yet». */
+    private lastPublishedHostLoad;
+    /** When that frame went out, by this machine's clock. `0` = never. */
+    private lastHostLoadSentAt;
+    /**
+     * Tell the API what this machine's load looks like — when it is worth telling.
+     *
+     * Three ways a frame goes out, and each covers a hole the others leave:
+     *
+     *  - the value MOVED past a threshold (`hostLoadChangedEnough`) — the reason
+     *    the frame exists, and the only one that makes the card timely;
+     *  - the heartbeat came due — an idle machine still has to say «still here,
+     *    still idle», because the API expires the measurement after two minutes
+     *    and silence would otherwise turn «nothing is happening» into «we have no
+     *    idea» on a perfectly healthy card;
+     *  - nothing was ever sent on this connection (`hello_ack` clears the memory)
+     *    — a fresh socket knows nothing about what the last one was told.
+     *
+     * `null` from the sampler is a complete answer: not Linux, `/proc` masked, a
+     * kernel too old for `MemAvailable`. Nothing is sent and nothing is logged —
+     * a machine that cannot measure itself leaves the card saying «no data»,
+     * which is exactly what is true.
+     *
+     * Recorded ONLY when the socket took it, same as `publishSlots`: a frame
+     * dropped by a dead socket must not be remembered as sent, or a machine whose
+     * load never moves again would go silent until the heartbeat — and on a
+     * reconnect the API would have no measurement at all while this side believed
+     * it had one.
+     */
+    /**
+     * Tell the person what the kernel is doing to each caged session (#387).
+     *
+     * Three things the cgroup can say, each with its own line in the feed:
+     *
+     *  - the brake engaged (`memory.current` over `memory.high`): the session is
+     *    being slowed down, not killed. Said once per episode, and again when it
+     *    has lasted `CAGE_BRAKE_LONG_MS` — that second line is the one that
+     *    suggests an action, because by then «slower» may mean «stuck»;
+     *  - the brake released: said once, so a person who saw the warning knows the
+     *    wait is over without reading the numbers;
+     *  - `oom_kill` moved: the kernel killed a process inside the session. With
+     *    `OOMPolicy=continue` the session itself is still here, and the person
+     *    has to be told that the command that was running is probably what died.
+     *
+     * Until this tick existed the runner knew all three and wrote them to its own
+     * log only; the feed said «exited with code 143» and nothing about memory.
+     *
+     * A parked session has no process and no cgroup, and is skipped without a
+     * read. A session whose cgroup cannot be read (no cage on this machine, or
+     * the scope already gone) is skipped the same way: the watch never guesses.
+     */
+    private watchSessionCages;
+    private publishHostLoad;
     private onFrame;
     private startSession;
     /**

package/dist/supervisor.js

@@ -25,6 +25,8 @@ import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { agentByDbValue } from './agent-registry.js';
 import { invalidateAgentVersions, measureAgentVersions, } from './agent-versions.js';
 import { rememberWorkspacePath } from './environment.js';
+import { hostLoadChangedEnough, hostLoadHeartbeatDue, readHostLoad, HOST_LOAD_HEARTBEAT_MS, HOST_LOAD_SAMPLE_INTERVAL_MS, } from './host-load.js';
+import { markScopeOomKillsSeen, readScopeMemoryStatus, sessionScopeUnitOf, } from './session-cage.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
 import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, MAX_BUSY_SESSIONS, previewRewind, pruneCheckpoints, } from './checkpoints.js';
 import { DeliverMessageArgsSchema, QuestionAnswerArgsSchema } from './protocol.js';
@@ -209,7 +211,44 @@ export class Supervisor {
         this.agentCleanupFirstTimer.unref?.();
         this.agentCleanupTimer = setInterval(() => this.sweepOldAgentVersions(), cleanupEvery);
         this.agentCleanupTimer.unref?.();
+        /**
+         * The machine's own load, sampled on a timer for the reason the seat report
+         * is: nothing on this side is an EVENT. Load is not something the runner
+         * does, it is something that happens to it — a `pnpm build` a person
+         * started over ssh, a neighbour container, this machine's own three agents
+         * — and there is no call site to hook. A tick that re-reads the truth is
+         * the only shape that cannot be forgotten.
+         *
+         * Nearly free, and quiet by default: two small files are read, and
+         * `publishHostLoad` returns without touching the socket unless the number
+         * actually moved (or the heartbeat came due).
+         */
+        this.hostLoadHeartbeatMs = opts.hostLoadHeartbeatMs ?? HOST_LOAD_HEARTBEAT_MS;
+        this.hostLoadTimer = setInterval(() => {
+            this.publishHostLoad();
+            // Same cadence, same reason: what a session's cgroup is going through is
+            // something that happens to it, and only a tick can notice (#387).
+            this.watchSessionCages();
+        }, opts.hostLoadSampleMs ?? HOST_LOAD_SAMPLE_INTERVAL_MS);
+        this.hostLoadTimer.unref?.();
     }
+    /**
+     * How long a session may sit over its brake before the feed says more than
+     * «slower» (#387, step 3). Five minutes is a starting point, not a
+     * measurement: an honest `pnpm typecheck` overshoots for tens of seconds, a
+     * runaway for ever, and the number that tells them apart on real machines is
+     * still to be read off `memory.events`. Sized so the first warning is never
+     * the only one a night-time run leaves behind.
+     */
+    static CAGE_BRAKE_LONG_MS = 5 * 60_000;
+    /**
+     * Calm ticks before the feed says the braking is over.
+     *
+     * `memory.high` holds usage AT the line, so a single sample under it means
+     * nothing. Two (a minute at the 30 s cadence) is the difference between an
+     * episode that ended and a build that breathed.
+     */
+    static CAGE_CALM_TICKS_TO_RELEASE = 2;
     /** How often the agent versions are re-derived. See the constructor. */
     static AGENT_VERSIONS_INTERVAL_MS = 60 * 60 * 1_000;
     agentVersionsTimer;
@@ -572,6 +611,201 @@ export class Supervisor {
             this.lastPublishedSlots = fingerprint;
         }
     }
+    /** The heartbeat window actually used — the constant, or a test's own. */
+    hostLoadHeartbeatMs;
+    hostLoadTimer;
+    /** The last measurement the API actually took from us, or `null` for «nothing yet». */
+    lastPublishedHostLoad = null;
+    /** When that frame went out, by this machine's clock. `0` = never. */
+    lastHostLoadSentAt = 0;
+    /**
+     * Tell the API what this machine's load looks like — when it is worth telling.
+     *
+     * Three ways a frame goes out, and each covers a hole the others leave:
+     *
+     *  - the value MOVED past a threshold (`hostLoadChangedEnough`) — the reason
+     *    the frame exists, and the only one that makes the card timely;
+     *  - the heartbeat came due — an idle machine still has to say «still here,
+     *    still idle», because the API expires the measurement after two minutes
+     *    and silence would otherwise turn «nothing is happening» into «we have no
+     *    idea» on a perfectly healthy card;
+     *  - nothing was ever sent on this connection (`hello_ack` clears the memory)
+     *    — a fresh socket knows nothing about what the last one was told.
+     *
+     * `null` from the sampler is a complete answer: not Linux, `/proc` masked, a
+     * kernel too old for `MemAvailable`. Nothing is sent and nothing is logged —
+     * a machine that cannot measure itself leaves the card saying «no data»,
+     * which is exactly what is true.
+     *
+     * Recorded ONLY when the socket took it, same as `publishSlots`: a frame
+     * dropped by a dead socket must not be remembered as sent, or a machine whose
+     * load never moves again would go silent until the heartbeat — and on a
+     * reconnect the API would have no measurement at all while this side believed
+     * it had one.
+     */
+    /**
+     * Tell the person what the kernel is doing to each caged session (#387).
+     *
+     * Three things the cgroup can say, each with its own line in the feed:
+     *
+     *  - the brake engaged (`memory.current` over `memory.high`): the session is
+     *    being slowed down, not killed. Said once per episode, and again when it
+     *    has lasted `CAGE_BRAKE_LONG_MS` — that second line is the one that
+     *    suggests an action, because by then «slower» may mean «stuck»;
+     *  - the brake released: said once, so a person who saw the warning knows the
+     *    wait is over without reading the numbers;
+     *  - `oom_kill` moved: the kernel killed a process inside the session. With
+     *    `OOMPolicy=continue` the session itself is still here, and the person
+     *    has to be told that the command that was running is probably what died.
+     *
+     * Until this tick existed the runner knew all three and wrote them to its own
+     * log only; the feed said «exited with code 143» and nothing about memory.
+     *
+     * A parked session has no process and no cgroup, and is skipped without a
+     * read. A session whose cgroup cannot be read (no cage on this machine, or
+     * the scope already gone) is skipped the same way: the watch never guesses.
+     */
+    watchSessionCages() {
+        const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+        const read = this.opts.readScopeMemoryStatus ?? readScopeMemoryStatus;
+        const longMs = this.opts.cageBrakeLongMs ?? Supervisor.CAGE_BRAKE_LONG_MS;
+        const now = Date.now();
+        const mb = (bytes) => `${Math.round(bytes / (1024 * 1024))} MB`;
+        for (const running of this.sessions.values()) {
+            if (running.session === null)
+                continue;
+            const unit = unitOf(running.descriptor.id);
+            if (unit === null)
+                continue;
+            const status = read(unit);
+            if (status === null)
+                continue;
+            const seen = running.cageWatch;
+            /**
+             * A cgroup this watch has not seen before starts from zero.
+             *
+             * Two ways that happens, and the second is why the counters are checked
+             * as well as the name: a session relaunched after its scope was released
+             * gets the SAME unit name back (`sessionScopeUnit` falls back to the
+             * plain name once the failed unit is reset), so «same name» does not mean
+             * «same cgroup». Counters that went backwards can only be a new one —
+             * without this the episode of the dead process carried over, and the
+             * feed opened with «memory is back under the share» for a process that
+             * had never been over it (#387 QA).
+             */
+            const carriedOver = seen !== undefined &&
+                seen.unit === unit &&
+                status.oomKills >= seen.oomKills &&
+                status.highEvents >= seen.highEvents &&
+                status.ownLimitOom >= seen.ownOom;
+            const base = carriedOver
+                ? seen
+                : {
+                    unit,
+                    oomKills: 0,
+                    ownOom: 0,
+                    highEvents: 0,
+                    brakedSince: null,
+                    warnedLong: false,
+                    calmTicks: 0,
+                };
+            if (status.oomKills > base.oomKills) {
+                // WHOSE limit was hit decides the sentence. `oom` moves only in the
+                // cgroup whose own ceiling was reached; a kill with our counter still
+                // where it was came from the slice over ALL sessions, and telling this
+                // session it went over its ceiling would be false (measured on this
+                // host: the killed neighbour read `max 0, oom 0, oom_kill 1`).
+                const ownWall = status.ownLimitOom > base.ownOom;
+                const killed = status.oomKills - base.oomKills === 1
+                    ? 'a process'
+                    : `${status.oomKills - base.oomKills} processes`;
+                this.sendEvent(running, 'notice', {
+                    level: 'warn',
+                    text: ownWall
+                        ? `This session went over its memory ceiling${status.maxBytes === null ? '' : ` of ${mb(status.maxBytes)}`} and the kernel killed ${killed} inside it. ` +
+                            'The session itself is still running; the command that was in flight most likely died with it — check its output before going on.'
+                        : `The machine ran out of memory for agent sessions — they share one ceiling — and the kernel killed ${killed} in this session. ` +
+                            `This session was using ${mb(status.currentBytes)}${status.maxBytes === null ? '' : ` of its own ${mb(status.maxBytes)}`}, so it was not necessarily the greedy one. ` +
+                            'It is still running; the command that was in flight most likely died with it.',
+                });
+                // So a death minutes later is not blamed on a kill the feed already carries.
+                markScopeOomKillsSeen(running.descriptor.id, status.oomKills);
+            }
+            /**
+             * «Being braked» is the EVENT counter first, the level second.
+             *
+             * `memory.high` works by holding usage at the line: a 30 s sample of
+             * `current > high` lands over it and under it in turn, which produced a
+             * warning and an all-clear on alternate ticks for one long build. The
+             * `high` counter only ever moves when the kernel actually throttled this
+             * cgroup, so a delta is the honest answer to «is it being slowed down
+             * right now», and the level is kept as the answer for a session that is
+             * sitting over the line without allocating.
+             */
+            const throttled = status.highEvents > base.highEvents ||
+                (status.highBytes !== null && status.currentBytes > status.highBytes);
+            let { brakedSince, warnedLong, calmTicks } = base;
+            if (throttled) {
+                calmTicks = 0;
+                if (brakedSince === null) {
+                    brakedSince = now;
+                    warnedLong = false;
+                    this.sendEvent(running, 'notice', {
+                        level: 'warn',
+                        text: `This session is over its memory share (${mb(status.highBytes ?? 0)}, using ${mb(status.currentBytes)}), so the kernel is slowing it down instead of killing it. ` +
+                            'Heavy commands will finish slower until memory is freed.',
+                    });
+                }
+                else if (!warnedLong && now - brakedSince >= longMs) {
+                    warnedLong = true;
+                    this.sendEvent(running, 'notice', {
+                        level: 'warn',
+                        text: `Still over its memory share after ${Math.round(longMs / 60_000)} min (using ${mb(status.currentBytes)} of a ${mb(status.highBytes ?? 0)} share). ` +
+                            `If the current command is stuck rather than slow, stop it or pause the session.${status.maxBytes === null
+                                ? ''
+                                : ` The hard ceiling, where a process would be killed, is ${mb(status.maxBytes)}.`}`,
+                    });
+                }
+            }
+            else if (brakedSince !== null) {
+                // One calm sample is noise — see above. Two in a row is an episode that
+                // really ended, and only then is the all-clear worth a line in the feed.
+                calmTicks += 1;
+                if (calmTicks >= Supervisor.CAGE_CALM_TICKS_TO_RELEASE) {
+                    brakedSince = null;
+                    warnedLong = false;
+                    this.sendEvent(running, 'notice', {
+                        level: 'info',
+                        text: `Memory is back under the session's share (${mb(status.highBytes ?? 0)}); it runs at full speed again.`,
+                    });
+                }
+            }
+            running.cageWatch = {
+                unit,
+                oomKills: status.oomKills,
+                ownOom: status.ownLimitOom,
+                highEvents: status.highEvents,
+                brakedSince,
+                warnedLong,
+                calmTicks,
+            };
+        }
+    }
+    publishHostLoad() {
+        const sample = (this.opts.readHostLoad ?? readHostLoad)();
+        if (!sample)
+            return;
+        const now = Date.now();
+        const sinceLastSent = now - this.lastHostLoadSentAt;
+        // A backwards clock step is «due», not «early» — see `hostLoadHeartbeatDue`.
+        const heartbeatDue = hostLoadHeartbeatDue(sinceLastSent, this.hostLoadHeartbeatMs);
+        if (!heartbeatDue && !hostLoadChangedEnough(this.lastPublishedHostLoad, sample))
+            return;
+        if (this.ws.send({ type: 'host_load', ...sample })) {
+            this.lastPublishedHostLoad = sample;
+            this.lastHostLoadSentAt = now;
+        }
+    }
     async onFrame(frame) {
         switch (frame.type) {
             case 'hello_ack':
@@ -580,9 +814,17 @@ export class Supervisor {
                 // because it is only true while the socket is. Forget what we told the
                 // old one so the first tick after this reconnect actually sends.
                 this.lastPublishedSlots = '';
+                // Same rule for the load: the API keeps the measurement in Redis beside
+                // the socket, with a TTL shorter than our heartbeat, so a machine that
+                // has just come back has no load on its card at all. Forget what the
+                // last connection was told and say it again immediately — a card that
+                // is right only after five minutes of silence is not right.
+                this.lastPublishedHostLoad = null;
+                this.lastHostLoadSentAt = 0;
                 this.setMaxSessions(frame.maxSessions);
                 await this.reconcile(frame.sessions);
                 this.publishSlots();
+                this.publishHostLoad();
                 // A build that finished while the socket was down has its verdict
                 // sitting on disk. This is the moment it can be delivered.
                 this.flushVerifyReports();
@@ -5805,6 +6047,7 @@ export class Supervisor {
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown() {
         clearInterval(this.slotsTimer);
+        clearInterval(this.hostLoadTimer);
         clearInterval(this.agentVersionsTimer);
         clearTimeout(this.agentCleanupFirstTimer);
         clearInterval(this.agentCleanupTimer);

package/dist/systemd-memory.d.ts

@@ -0,0 +1,35 @@
+import { type CgroupMemory, type MemoryFacts } from './service-unit.js';
+/**
+ * Read the unit's group, never the CLI's own `/proc/self` group. A missing
+ * reading is not an empty service: a timed-out user bus can belong to a busy
+ * machine. Raw `memory.current` deliberately survives beside the split, so the
+ * safety floor never depends on an estimate of how much can be reclaimed.
+ */
+export declare function unitMemoryReading(output: string, cgroupRoot?: string): CgroupMemory | null;
+/**
+ * Both units, measured through systemd, with the filesystem underneath.
+ *
+ * One helper so `doctor`, `doctor --fix`, `install-service` and the daemon's
+ * hourly re-measure cannot drift apart in what they measure — which is how the
+ * CLI once computed a ceiling 34 % away from the daemon's and the two rewrote
+ * the file forever.
+ *
+ * The fallback is not a second opinion, it is the same reading taken another
+ * way, and it is safe for every caller precisely because each reader
+ * self-identifies: `readOwnCgroupMemory` hands back null for any process that
+ * is not the service itself, so the daemon measures itself when the bus is
+ * unhappy and a CLI never mistakes its own `session-N.scope` for the service.
+ * Without it, one slow `systemctl` meant the daemon wrote no policy at all —
+ * for an hour, on the overloaded machine this policy exists to protect.
+ */
+export declare function readMemoryFactsFromSystemd(): Promise<MemoryReadings>;
+export interface MemoryReadings {
+    facts: MemoryFacts | null;
+    sessionsUsageBytes: number | null;
+}
+/** The half of the above that has no bus in it, so it can be tested. */
+export declare function memoryReadings(service: CgroupMemory | null, sessions: CgroupMemory | null, fromFilesystem?: {
+    own: () => CgroupMemory | null;
+    sessions: () => CgroupMemory | null;
+}): MemoryReadings;
+//# sourceMappingURL=systemd-memory.d.ts.map

package/dist/systemd-memory.js

@@ -0,0 +1,115 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { systemdUserEnv } from './environment.js';
+import { readCgroupMemory, readMemoryFacts, readOwnCgroupMemory, readSessionsSliceMemory, SERVICE_NAME, SESSIONS_SLICE, } from './service-unit.js';
+const execFileAsync = promisify(execFile);
+function bytes(raw) {
+    if (raw === undefined || !/^\d+$/.test(raw.trim()))
+        return null;
+    const value = Number(raw);
+    // systemd prints UINT64_MAX for «not set» on some versions, which is above
+    // `MAX_SAFE_INTEGER` and would otherwise arrive as a plausible byte count.
+    return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+/**
+ * Read the unit's group, never the CLI's own `/proc/self` group. A missing
+ * reading is not an empty service: a timed-out user bus can belong to a busy
+ * machine. Raw `memory.current` deliberately survives beside the split, so the
+ * safety floor never depends on an estimate of how much can be reclaimed.
+ */
+export function unitMemoryReading(output, cgroupRoot = '/sys/fs/cgroup') {
+    const properties = new Map(output.split('\n').map((line) => {
+        const separator = line.indexOf('=');
+        return [line.slice(0, separator), line.slice(separator + 1).trim()];
+    }));
+    // An empty answer is not a fact about the unit: everything below reads meaning
+    // into what systemd said, so there has to have been an answer first. A dead
+    // bus prints nothing and stays «unknown». `ControlGroup` is not required to be
+    // PRESENT — only to be empty where it decides emptiness below — so a systemd
+    // that does not print it leaves «unknown» too, and the filesystem reader
+    // behind this one covers that machine.
+    if (!properties.has('ActiveState'))
+        return null;
+    const current = bytes(properties.get('MemoryCurrent'));
+    const group = properties.get('ControlGroup');
+    if (group !== undefined && group.startsWith('/') && group !== '/') {
+        const root = path.resolve(cgroupRoot);
+        const directory = path.resolve(root, `.${group}`);
+        if (directory.startsWith(`${root}${path.sep}`)) {
+            try {
+                const measured = readCgroupMemory(directory);
+                if (measured !== null)
+                    return measured;
+                const raw = bytes(fs.readFileSync(path.join(directory, 'memory.current'), 'utf8'));
+                // Without `memory.stat` the split between «cache we can give back» and
+                // «memory that has to be killed for» is unknown, and null says so: the
+                // floor then assumes all of it, the headroom none of it.
+                if (raw !== null)
+                    return { currentBytes: raw, unreclaimableBytes: null };
+            }
+            catch {
+                // Unsupported controller, removed cgroup or unreadable file: unknown.
+            }
+        }
+    }
+    if (current !== null)
+        return { currentBytes: current, unreclaimableBytes: null };
+    // A unit with NO cgroup holds nothing a new ceiling could kill, whatever its
+    // ActiveState says — and that is the whole point of not asking for
+    // `inactive` here. `failed` and `activating (auto-restart)` report exactly
+    // the shape `inactive` does (verified on systemd 255: `ControlGroup=`,
+    // `MemoryCurrent=[not set]`), and those are precisely the states a machine is
+    // in when someone runs `install.sh --repair` or `doctor --fix` on it. Reading
+    // them as «unknown» turned the cure into a refusal on the only machines that
+    // need it.
+    return group === '' ? { currentBytes: 0, unreclaimableBytes: 0 } : null;
+}
+async function readUnitUsage(unit) {
+    try {
+        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', unit, '-p', 'MemoryCurrent', '-p', 'ActiveState', '-p', 'ControlGroup'], { timeout: 10_000, env: systemdUserEnv() });
+        return unitMemoryReading(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Both units, measured through systemd, with the filesystem underneath.
+ *
+ * One helper so `doctor`, `doctor --fix`, `install-service` and the daemon's
+ * hourly re-measure cannot drift apart in what they measure — which is how the
+ * CLI once computed a ceiling 34 % away from the daemon's and the two rewrote
+ * the file forever.
+ *
+ * The fallback is not a second opinion, it is the same reading taken another
+ * way, and it is safe for every caller precisely because each reader
+ * self-identifies: `readOwnCgroupMemory` hands back null for any process that
+ * is not the service itself, so the daemon measures itself when the bus is
+ * unhappy and a CLI never mistakes its own `session-N.scope` for the service.
+ * Without it, one slow `systemctl` meant the daemon wrote no policy at all —
+ * for an hour, on the overloaded machine this policy exists to protect.
+ */
+export async function readMemoryFactsFromSystemd() {
+    const [service, sessions] = await Promise.all([
+        readUnitUsage(SERVICE_NAME),
+        readUnitUsage(SESSIONS_SLICE),
+    ]);
+    return memoryReadings(service, sessions);
+}
+/** The half of the above that has no bus in it, so it can be tested. */
+export function memoryReadings(service, sessions, fromFilesystem = { own: readOwnCgroupMemory, sessions: readSessionsSliceMemory }) {
+    const serviceMemory = service ?? fromFilesystem.own();
+    const sessionsMemory = sessions ?? fromFilesystem.sessions();
+    return {
+        facts: readMemoryFacts(serviceMemory, sessionsMemory),
+        // The floor reading, and «unknown» kept apart from «empty»: this number is
+        // the only thing standing between a live slice and the ceiling written by
+        // a command typed on a machine whose service cannot be measured.
+        sessionsUsageBytes: sessionsMemory === null
+            ? null
+            : (sessionsMemory.unreclaimableBytes ?? sessionsMemory.currentBytes),
+    };
+}
+//# sourceMappingURL=systemd-memory.js.map

package/dist/verify.js

@@ -5,6 +5,8 @@ import { promisify } from 'node:util';
 import { log } from './log.js';
 import { maskString } from './policy.js';
 import { evaluateRecipeCommand } from './policy.js';
+import { lowerPriority } from './process-priority.js';
+import { cageSpawn, releaseSessionScope } from './session-cage.js';
 import { recipeFingerprint } from './recipe.js';
 import { StringDecoder } from 'node:string_decoder';
 import { stateDir } from './paths.js';
@@ -301,6 +303,7 @@ export class VerifyRunner {
             logPath,
             logBytes: 0,
             child: null,
+            scopeUnit: null,
             cancelled: false,
             branch: input.branch,
             commitSha: input.commitSha,
@@ -540,6 +543,11 @@ export class VerifyRunner {
                 settled = true;
                 clearTimeout(timer);
                 run.child = null;
+                // Read why the scope ended and let systemd forget it, in that order —
+                // a scope the OOM killer took stays in `failed` and would refuse the
+                // very same unit name to the next step (`session-cage.ts`).
+                void releaseSessionScope(run.scopeUnit, `verify-${run.runId}`);
+                run.scopeUnit = null;
                 resolve({
                     step: run.currentStep ?? '',
                     durationMs: this.now() - startedAt,
@@ -547,14 +555,26 @@ export class VerifyRunner {
                     ...(timedOut ? { timedOut: true } : {}),
                 });
             };
+            // A verification step is the heaviest thing on the machine that has an id
+            // of its own, so it gets a cage of its own too — keyed by the run rather
+            // than by a session, because that is the identity a verify run has. The
+            // scope survives `detached: true`: `systemd-run --scope` execs in the
+            // same pid, so `setsid` still makes the child its own group leader and
+            // `process.kill(-pid)` below still reaches the compilers.
+            const caged = cageSpawn({
+                id: `verify-${run.runId}`,
+                command: '/bin/sh',
+                args: ['-c', step.run],
+            });
+            run.scopeUnit = caged.unit;
             let child;
             try {
                 // `detached` so the whole process tree gets the signal: a build script
                 // is a shell that spawns compilers, and killing only the shell leaves
                 // them running with the disk and the CPU.
-                child = spawn('/bin/sh', ['-c', step.run], {
+                child = spawn(caged.command, caged.args, {
                     cwd: run.cwd,
-                    env: buildEnv(step.env),
+                    env: { ...buildEnv(step.env), ...caged.env },
                     detached: true,
                     stdio: ['ignore', 'pipe', 'pipe'],
                 });
@@ -565,6 +585,12 @@ export class VerifyRunner {
                 return;
             }
             run.child = child;
+            // A recipe step is the heaviest thing the runner starts on its own — a
+            // full build or a full test run — and the one with nobody waiting on a
+            // keystroke. It goes behind the daemon and level with the agent sessions;
+            // the whole process group inherits it, which is the point, because
+            // `detached` means the compilers are down there and not here.
+            lowerPriority(child.pid);
             // A StringDecoder per stream, not `buffer.toString('utf8')` per chunk.
             //
             // A pipe read ends wherever the kernel filled the buffer, which is

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.53.0";
+export declare const RUNNER_VERSION = "0.55.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.53.0';
+export const RUNNER_VERSION = '0.55.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",