@bridge4dev/runner 0.57.0 → 0.58.1

package/dist/supervisor.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { log } from './log.js';
 import { CONTEXT_USAGE_MIN_DELTA_RATIO, CONTEXT_USAGE_MIN_DELTA_TOKENS, RATE_LIMITS_RESEND_INTERVAL_MS, } from './levels.js';
@@ -23,10 +24,15 @@ import { installAgent } from './agent-install.js';
 import { autoUpdateRefusal, claimAgentAutoUpdate } from './agent-auto-update.js';
 import { pruneNativeClaudeVersions } from './agent-cleanup.js';
 import { agentByDbValue } from './agent-registry.js';
+import { cageAuthority } from './cage-authority.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, stoppedProcesses, } from './session-cage.js';
+import { markScopeOomKillsSeen, readScopeHold, readScopeMemoryStatus, readSliceLimits, sessionAgentPid, sessionCage, sessionScopeUnitOf, setLiveLadderSource, stoppedProcesses, sweepOrphanSessionScopes, } from './session-cage.js';
+import { allocateSessionMemory, planLimitMove, SESSION_GUARANTEE_BYTES, } from './session-allocator.js';
+import { freshStallState, pickKillCandidate, readScopeProcesses, readStallSample, setScopeProperties, signalSubtree, stallStep, STALL_GRACE_MS, STALL_MUTE_AFTER_LOWER_MS, STALL_SIGKILL_AFTER_MS, STALL_WINDOW_MS, } from './session-stall.js';
+import { machineReserveBytes } from './service-unit.js';
+import { sessionLimitsChangedEnough, sessionLimitsHeartbeatDue, SESSION_LIMITS_HEARTBEAT_MS, } from './session-limits.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';
@@ -232,26 +238,45 @@ export class Supervisor {
             // 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();
+            // And the same argument one step further (#398, S1): a scope with nobody
+            // behind it is also something that HAPPENS, and until 0.58.0 the only
+            // sweep ran at daemon start — so an orphan held its memory until the next
+            // restart. `releaseSessionScope` is the primary path now; this is the net
+            // under it, for the exit that never fired at all.
+            void this.sweepOrphanCages();
+            // …and the third thing that only a tick can notice (#398 S3): how much of
+            // the machine is free RIGHT NOW, and therefore how much each session may
+            // use. The number this replaced was computed once, at daemon start.
+            void this.runAllocator(Date.now());
         }, opts.hostLoadSampleMs ?? HOST_LOAD_SAMPLE_INTERVAL_MS);
         this.hostLoadTimer.unref?.();
+        /**
+         * The stall detector, on its own faster clock (#398 S2).
+         *
+         * A second timer rather than more work on the 30 s one, and the reason is
+         * arithmetic: the deadline a standing session gets is three minutes, the
+         * verdict needs two consecutive windows, and at 30 s a session would spend a
+         * third of its deadline being diagnosed. Five seconds costs five small file
+         * reads per live caged session — nothing next to what the tick above already
+         * does — and only for sessions that have a cgroup at all.
+         */
+        this.limitsHeartbeatMs = opts.sessionLimitsHeartbeatMs ?? SESSION_LIMITS_HEARTBEAT_MS;
+        this.stallGraceMs = opts.stallGraceMs ?? STALL_GRACE_MS;
+        this.stallSampleMs = opts.stallSampleMs ?? STALL_WINDOW_MS;
+        this.stallTimer = setInterval(() => {
+            void this.watchSessionStalls();
+        }, this.stallSampleMs);
+        this.stallTimer.unref?.();
+        /**
+         * A session starting mid-tick asks the allocator for its numbers rather
+         * than taking the daemon-start snapshot (#398 S3, work 9).
+         *
+         * Registered here and cleared in `shutdown()`: the hook lives on the cage
+         * module, which cannot import this one, and a stale hook pointing at a dead
+         * supervisor would be worse than none.
+         */
+        setLiveLadderSource((id) => this.ladderForNewSession(id));
     }
-    /**
-     * 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;
@@ -617,6 +642,13 @@ export class Supervisor {
     /** The heartbeat window actually used — the constant, or a test's own. */
     hostLoadHeartbeatMs;
     hostLoadTimer;
+    /** #398 S2: the stall detector's clock, and the deadline it enforces. */
+    stallTimer;
+    stallGraceMs;
+    stallSampleMs;
+    limitsHeartbeatMs;
+    /** A stall tick is in flight — the next one waits rather than overlaps. */
+    watchingStalls = false;
     /** 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. */
@@ -647,22 +679,27 @@ export class Supervisor {
      * it had one.
      */
     /**
-     * Tell the person what the kernel is doing to each caged session (#387).
+     * Tell the person when the KERNEL killed something inside a caged session.
+     *
+     * One thing, since #398 S2 — `oom_kill` moved: the kernel stopped 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.
      *
-     * Three things the cgroup can say, each with its own line in the feed:
+     * **The three braking lines this tick used to write are gone** (decision D8 of
+     * `session-memory-fair-share.md`): «has hit its memory share», «has been over
+     * its memory share for 5 min», and the all-clear. Two reasons, and the second
+     * is the decisive one:
      *
-     *  - 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.
+     *  - they were state, not events. Being over the brake is a condition that
+     *    comes and goes; its place is the activity strip under the session and the
+     *    machine card, not the history a person scrolls back through;
+     *  - they disagreed with the mechanism that replaced them. The deadline in
+     *    `session-stall.ts` runs out after three minutes, so the five-minute line
+     *    could never have been printed at all.
      *
-     * 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.
+     * What a person sees instead: nothing while the machine copes, and exactly one
+     * line when a command was actually stopped.
      *
      * 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
@@ -671,8 +708,6 @@ export class Supervisor {
     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)
@@ -703,15 +738,7 @@ export class Supervisor {
                 status.ownLimitOom >= seen.ownOom;
             const base = carriedOver
                 ? seen
-                : {
-                    unit,
-                    oomKills: 0,
-                    ownOom: 0,
-                    highEvents: 0,
-                    brakedSince: null,
-                    warnedLong: false,
-                    calmTicks: 0,
-                };
+                : { unit, oomKills: 0, ownOom: 0, highEvents: 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
@@ -731,66 +758,778 @@ export class Supervisor {
                 // 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);
-            // `memory.high` reads `max` on a machine where the share never applied —
-            // then there is no number to name, and «its 0 MB share» is worse than no
-            // number at all.
-            const share = status.highBytes === null ? '' : ` ${mb(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 has hit its${share} memory share — commands run slower until it uses less memory.`,
-                    });
+            running.cageWatch = {
+                unit,
+                oomKills: status.oomKills,
+                ownOom: status.ownLimitOom,
+                highEvents: status.highEvents,
+            };
+        }
+    }
+    /** A sweep is in flight — see {@link sweepOrphanCages}. */
+    sweepingCages = false;
+    /**
+     * Stop every session scope with nobody behind it, on the watch tick (#398 S1).
+     *
+     * The sweep itself spares every LIVE cage by its own register, sessions and
+     * `verify` runs alike (`session-cage.ts`), so what is passed here is belt and
+     * braces rather than the guard — but passing it says at the call site which
+     * ids this supervisor believes are alive, and a divergence between the two
+     * would be a bug worth seeing in a test.
+     *
+     * Re-entrancy matters more than it looks: the sweep is a `systemctl` call and
+     * the bus was measured at 2.7 s under load, so on a machine where the tick is
+     * 30 s and the bus is slow two sweeps could otherwise overlap and each would
+     * see the other's half-stopped units.
+     *
+     * Never fatal, and deliberately silent on failure: the daemon carries a fatal
+     * `unhandledRejection` handler, and losing every session because a bus call
+     * failed would be a far worse trade than an orphan living one more tick.
+     */
+    async sweepOrphanCages() {
+        if (this.sweepingCages)
+            return;
+        const injected = this.opts.sweepOrphanSessionScopes;
+        /**
+         * Two gates, and the first one is the one that had to be rebuilt (#403).
+         *
+         * The guard here used to be «the cage has been probed», on the reasoning
+         * that no test probes it and every daemon does. On 10.09.2026 a new test
+         * probed it, and this sweep — from a vitest worker, with an empty register
+         * of live cages — stopped three live sessions belonging to other people.
+         * The lesson is not «that test was wrong»: a guard that depends on what
+         * OTHER people's future code happens to do cannot hold, and it failed
+         * silently, because an assumption cannot fail loudly.
+         *
+         * So the gate is now a right that has to be taken: only the process that
+         * claimed `daemon` at start-up sweeps, and a test process cannot claim it.
+         * `cage-authority.ts` refuses the underlying `systemctl` as well — this
+         * gate is the one that keeps the call from being made at all.
+         *
+         * The second gate is unchanged and is only thrift: on a machine with no
+         * cage there is nothing of ours under that prefix.
+         */
+        if (!injected && cageAuthority() !== 'daemon')
+            return;
+        if (!injected && sessionCage().mode !== 'scope')
+            return;
+        this.sweepingCages = true;
+        try {
+            const sweep = injected ?? sweepOrphanSessionScopes;
+            await sweep([...this.sessions.keys()]);
+        }
+        catch (error) {
+            log.debug('supervisor: the orphan cage sweep did not run', { error: String(error) });
+        }
+        finally {
+            this.sweepingCages = false;
+        }
+    }
+    /**
+     * The stall mechanism, once per window (#398 S2, D6, gotcha §480).
+     *
+     * The order is the whole design, and each step exists because the one before
+     * it was not enough:
+     *
+     *  1. **T0 — add.** If the machine has memory free, the brake goes up and the
+     *     session carries on. Nothing is written to the feed: the mechanism
+     *     worked, nothing changed for the person, the build is still going (D8).
+     *  2. **T1 — the deadline.** Three minutes, announced as state (the strip
+     *     under the session says how long is left) and never as a line in the
+     *     history. This is the window in which a person can step in without
+     *     paying for it with an entry they will scroll past for ever.
+     *  3. **T2 — stop the biggest command.** Not the session, not the agent: the
+     *     command. The agent stays alive, sees its command stopped, is told why,
+     *     and answers the person itself. Waiting for a human instead is what cost
+     *     the incident its hour — at night nobody comes.
+     *  4. **T3 — nothing to stop.** When all that is left in the cage is the agent
+     *     and its tools, this mechanism has no right to any of them. State again,
+     *     no line: the person decides with «Stop» or «Pause».
+     *
+     * Never throws out of here. The daemon carries a fatal `unhandledRejection`
+     * handler, so one unhandled error would end every session on the machine.
+     */
+    async watchSessionStalls() {
+        if (this.watchingStalls)
+            return;
+        this.watchingStalls = true;
+        try {
+            const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+            const sampleOf = this.opts.readStallSample ?? readStallSample;
+            const now = Date.now();
+            for (const running of this.sessions.values()) {
+                const unit = running.session === null ? null : unitOf(running.descriptor.id);
+                if (unit === null) {
+                    /**
+                     * Parked, or never caged. A stall belongs to a live process; keeping
+                     * the state would age into a deadline against a session that is not
+                     * running at all.
+                     *
+                     * …and so do the limits (#403). `running.limits` means «what systemd
+                     * was told about THIS scope», and a parked session has no scope: on
+                     * resume `cageSpawn` was starting the new one with yesterday's
+                     * numbers, `sessionMemoryEnv` was telling the agent a ceiling nobody
+                     * held, and the wall could only come down through four shrink ticks
+                     * that a fresh session does not have.
+                     */
+                    delete running.stall;
+                    delete running.limits;
+                    continue;
                 }
-                else if (!warnedLong && now - brakedSince >= longMs) {
-                    warnedLong = true;
-                    this.sendEvent(running, 'notice', {
-                        level: 'warn',
-                        text: `This session has been over its${share} memory share for ${Math.round(longMs / 60_000)} min and is now using ${mb(status.currentBytes)} — ` +
-                            'if a command is stuck rather than slow, stop the turn or pause the session.',
+                try {
+                    await this.stepOneStall(running, unit, sampleOf, now);
+                }
+                catch (error) {
+                    log.warn('supervisor: the memory stall check failed for a session', {
+                        sessionId: running.descriptor.id,
+                        error: String(error instanceof Error ? error.message : error),
                     });
                 }
             }
-            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: `This session is back under its${share} memory share — it runs at full speed again.`,
-                    });
+        }
+        finally {
+            this.watchingStalls = false;
+        }
+    }
+    async stepOneStall(running, unit, sampleOf, now) {
+        // The pending SIGKILL first, and before anything can return early: a subtree
+        // that ignored SIGTERM must get the second signal even on a tick where the
+        // cgroup could not be read at all.
+        this.escalatePendingKill(running, now);
+        /**
+         * Stamped at the READ, not at the start of the pass (#398 S7, B13).
+         *
+         * `now` is one clock for the whole sweep, and the sweep walks every live
+         * session doing file reads — so the last session's sample carried the first
+         * session's timestamp. The share this feeds is `Δpressure / windowMs`, and
+         * an offset between the two ends of a window is exactly the error that
+         * makes it wrong. `readHostLoad` has always stamped inside itself.
+         */
+        const sample = sampleOf(unit, Date.now());
+        if (sample === null)
+            return;
+        const previous = running.stall && running.stall.detector.unit === unit
+            ? running.stall
+            : {
+                detector: freshStallState(unit),
+                sample: null,
+                remainingMs: null,
+                kill: null,
+                reason: null,
+            };
+        const verdict = stallStep(previous.detector, sample, {
+            graceMs: this.stallGraceMs,
+            windowMs: this.stallSampleMs,
+            now,
+            // Alone in the slice, «somebody else's brake» has no somebody else — see
+            // the discriminator in `session-stall.ts` (#398 S7, B9).
+            soleSession: this.liveCagedSessions() <= 1,
+        });
+        const stall = {
+            ...previous,
+            detector: verdict.state,
+            sample,
+            remainingMs: verdict.remainingMs,
+        };
+        running.stall = stall;
+        if (!verdict.stuck) {
+            /**
+             * The session is moving again, so whatever the strip was saying about its
+             * memory stops being true — and state that outlives its cause is exactly
+             * what decision D8 moved out of the feed to avoid.
+             *
+             * Found by the independent review of 10.09.2026: `reason` was set and
+             * never cleared, so one episode made the strip say «low on memory» for
+             * the rest of the session's life. Kept while a subtree is still being
+             * stopped: the line about the stopped command is true until it is gone.
+             */
+            if (stall.kill === null)
+                stall.reason = null;
+            return;
+        }
+        // T0. Free memory on the machine is the cheapest answer there is, and it
+        // costs the person nothing to know about.
+        if (await this.addMemoryTo(running, sample, now)) {
+            stall.reason = 'added';
+            stall.detector = { ...stall.detector, hotWindows: 0, stalledSince: null, markBytes: 0 };
+            stall.remainingMs = null;
+            return;
+        }
+        /**
+         * The owner's switch (#398 S6). `report-only` leaves everything else
+         * exactly as it is — the deadline still runs, the strip still shows it, the
+         * person can still act — and only DevBridge stops acting on their behalf.
+         *
+         * Said at the START of the countdown and not at the end of it (#403). The
+         * strip renders the reason ahead of the clock, so while this was set only
+         * on expiry the owner of a report-only machine spent three minutes being
+         * promised «2:14 until a command is stopped» — a countdown to an event
+         * their own setting had already ruled out.
+         */
+        const action = this.opts.memoryStallAction ?? 'stop-command';
+        if (action === 'report-only')
+            stall.reason = 'report-only';
+        // T1. The deadline runs; the strip shows it. One victim at a time: while a
+        // subtree is still being stopped, nothing else is chosen.
+        if (!verdict.expired || stall.kill !== null)
+            return;
+        if (action === 'report-only') {
+            // Its own word, not «nothing to stop»: those are different facts about the
+            // machine, and telling the owner who chose this setting that there is
+            // nothing to stop would be a falsehood about their own machine (found by
+            // the independent review of 10.09.2026).
+            //
+            // Once per episode: compared against what the state held BEFORE this pass,
+            // because the line above has already set it for this one.
+            if (previous.reason !== 'report-only') {
+                log.warn('session memory: a session is standing still, and this machine is set to report only', {
+                    sessionId: running.descriptor.id,
+                    holdingMB: Math.round(sample.currentBytes / (1024 * 1024)),
+                });
+            }
+        }
+        else {
+            await this.stopBiggestCommand(running, unit, sample, now);
+        }
+        // Whatever we did or did not do, the clock starts again: the next attempt is
+        // a full deadline away, not five seconds.
+        stall.detector = { ...stall.detector, stalledSince: now, markBytes: sample.currentBytes };
+        stall.remainingMs = this.stallGraceMs;
+    }
+    /**
+     * Ask the allocator for more, now, because this session has stopped moving (T0).
+     *
+     * Since S3 there is no separate ladder here: `MemoryHigh` has exactly TWO
+     * writers, and they are the same code — the allocator on its tick and the
+     * allocator on this signal. Two independent writers of one number is how a
+     * limit ends up being whatever the last tick happened to think.
+     *
+     * The allocator needs no special case for a stall: a standing session's `hold`
+     * is by definition all the way up against its brake, so `hold + free` asks for
+     * everything the machine has spare. If there is nothing spare, nothing moves,
+     * and the deadline below is the answer instead.
+     */
+    async addMemoryTo(running, sample, now) {
+        // The brake as the CGROUP has it, not as this supervisor remembers writing
+        // it: on the first pass there is nothing remembered, and «did this session
+        // get more room» has to be answerable then too.
+        const before = sample.brakeBytes;
+        await this.runAllocator(now);
+        const after = running.limits?.brakeBytes ?? null;
+        if (before === null || after === null)
+            return false;
+        return after > before;
+    }
+    /** T2 and T3 — stop the biggest command of this session, or nothing at all. */
+    async stopBiggestCommand(running, unit, sample, now) {
+        const stall = running.stall;
+        if (!stall)
+            return;
+        const processes = (this.opts.readScopeProcesses ?? readScopeProcesses)(unit);
+        // Which pid is the agent, from the cage that spawned it — see
+        // `noteSessionAgentPid`. Null on a machine with no cage, and then
+        // `pickKillCandidate` falls back to «every parentless process».
+        const candidate = pickKillCandidate(processes, sessionAgentPid(running.descriptor.id));
+        const mb = (bytes) => Math.round(bytes / (1024 * 1024));
+        if (candidate === null) {
+            // T3. Everything left in the cage is the agent itself, its MCP servers or
+            // `git`. This mechanism may not touch any of them, and by D8 it does not
+            // write a line either — the strip says so while it is true.
+            if (stall.reason !== 'nothing-to-stop') {
+                log.warn('session memory: a session is out of memory and has nothing but the agent to stop', {
+                    sessionId: running.descriptor.id,
+                    holdingMB: mb(sample.currentBytes),
+                });
+            }
+            stall.reason = 'nothing-to-stop';
+            return;
+        }
+        const signal = this.opts.signalSubtree ?? signalSubtree;
+        const sent = signal(candidate.pids, 'SIGTERM');
+        stall.kill = {
+            identities: candidate.identities,
+            name: candidate.name,
+            at: now + STALL_SIGKILL_AFTER_MS,
+        };
+        stall.reason = 'stopped-command';
+        log.warn('session memory: stopped the biggest command of a session that had stopped moving', {
+            sessionId: running.descriptor.id,
+            command: candidate.name,
+            processes: sent,
+            commandMB: mb(candidate.rssBytes),
+            sessionMB: mb(sample.currentBytes),
+        });
+        // The one line a person gets out of the whole episode (D8). The command's
+        // NAME only — its arguments carry keys and tokens.
+        this.sendEvent(running, 'notice', {
+            level: 'warn',
+            text: `This session ran out of memory, so DevBridge stopped its biggest command — ` +
+                `${candidate.name}, holding ${mb(candidate.rssBytes)} MB of the session's ${mb(sample.currentBytes)} MB. ` +
+                'The session itself is still here.',
+        });
+        // And the agent is told, so it does not simply run the same thing again (D7).
+        this.tellAgent(running, `DevBridge stopped your \`${candidate.name}\` command: this session ran out of memory. ` +
+            `It was holding ${mb(candidate.rssBytes)} MB, the session's share is ` +
+            `${sample.brakeBytes === null ? 'unknown' : `${mb(sample.brakeBytes)} MB`}, and there was nothing free ` +
+            'on the machine to add. Running the same command again will end the same way — make it need less ' +
+            '(fewer parallel jobs, a smaller heap, a narrower scope) or split the work up. Do not raise ' +
+            '`--max-old-space-size`: the ceiling is enforced outside your process.');
+    }
+    /**
+     * Say something to the agent on the runner's own initiative, without stepping
+     * on a card the person has not answered (#398 S7, B7).
+     *
+     * `session.send()` looks like a neutral channel and is not one: with a
+     * question open, `ClaudeSession.send` answers it «discuss» and the API
+     * records `question_resolved {source: 'user'}` — a decision attributed to a
+     * person who never made it — while `CodexSession.send` declines a held plan
+     * the same way. Every other initiative of this supervisor already checks for
+     * an open card; the memory mechanism was the one that did not.
+     *
+     * Held rather than dropped: the agent is parked on the card, so it cannot run
+     * anything until the person answers anyway, and once they do the note is the
+     * first thing it reads.
+     */
+    tellAgent(running, text) {
+        if (running.openQuestions.size > 0 || running.openPermissions.size > 0) {
+            running.pendingAgentNote = running.pendingAgentNote
+                ? `${running.pendingAgentNote}\n\n${text}`
+                : text;
+            return;
+        }
+        running.session?.send(text);
+    }
+    /** Deliver what waited for a card to close — see {@link tellAgent}. */
+    flushPendingAgentNote(running) {
+        const note = running.pendingAgentNote;
+        if (note === undefined)
+            return;
+        if (running.openQuestions.size > 0 || running.openPermissions.size > 0)
+            return;
+        delete running.pendingAgentNote;
+        running.session?.send(note);
+    }
+    /** How many sessions are running in a cage right now (#398 S7, B9). */
+    liveCagedSessions() {
+        const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+        let count = 0;
+        for (const running of this.sessions.values()) {
+            if (running.session === null)
+                continue;
+            if (unitOf(running.descriptor.id) !== null)
+                count += 1;
+        }
+        return count;
+    }
+    /** SIGKILL for a subtree that did not take SIGTERM within the grace. */
+    escalatePendingKill(running, now) {
+        const kill = running.stall?.kill;
+        if (!kill || now < kill.at)
+            return;
+        const signal = this.opts.signalSubtree ?? signalSubtree;
+        /**
+         * Identities, not bare pids. Thirty seconds is long enough on a busy machine
+         * for a pid freed by the SIGTERM to be handed to something else, and a
+         * SIGKILL to the wrong process is the worst thing in this whole change —
+         * named as such by the independent review of 10.09.2026.
+         */
+        const sent = signal(kill.identities, 'SIGKILL');
+        if (sent > 0) {
+            log.warn('session memory: the stopped command did not go on its own', {
+                sessionId: running.descriptor.id,
+                command: kill.name,
+                processes: sent,
+            });
+        }
+        else if (kill.identities.length > 0) {
+            /**
+             * Nothing was signalled, and that is worth a line (#403).
+             *
+             * Two ways to get here and they are different machines. Either the
+             * processes ended on their own during the grace — the good outcome, and
+             * the common one — or their identity could not be read when the victim
+             * was chosen (`startedAtTicks: -1`), in which case `isSameProcess` refuses
+             * every one of them and the promised SIGKILL never happens at all. Under
+             * `if (sent > 0)` both were silent, so «stopped, then escalated» could
+             * quietly be neither.
+             */
+            log.info('session memory: nothing was left to SIGKILL', {
+                sessionId: running.descriptor.id,
+                command: kill.name,
+                identities: kill.identities.length,
+                unreadable: kill.identities.filter((i) => i.startedAtTicks < 0).length,
+            });
+        }
+        if (running.stall)
+            running.stall.kill = null;
+    }
+    /** An allocator pass is in flight — the next one waits rather than overlaps. */
+    allocating = false;
+    /** The last pass's machine-wide numbers, for the card and the session banner. */
+    lastAllocation = null;
+    /**
+     * The machine the last allocation was computed for, kept so the card's own
+     * number can be derived without measuring the machine a SECOND time (#403).
+     */
+    lastAllocatorMachine = null;
+    /** The last frame the API actually took from us, or null for «nothing yet». */
+    lastPublishedLimits = null;
+    /** When that frame went out, by this machine's clock. `0` = never. */
+    lastLimitsSentAt = 0;
+    /**
+     * Decide, and write, how much memory each live session may use (#398 S3).
+     *
+     * Runs on the 30 s watch tick and on the stall detector's signal, and nowhere
+     * else: `MemoryHigh` must have exactly one implementation of «what should this
+     * be», or the two writers disagree and the limit becomes whichever ran last.
+     *
+     * Everything that could be wrong about the machine is read fresh here rather
+     * than taken from the daemon-start probe: the pot moves when the hourly
+     * re-measure rewrites the slice, the collective brake decides whether
+     * overselling is even legal, and a neighbouring application growing is
+     * precisely the case #398 was opened about.
+     */
+    async runAllocator(now) {
+        if (this.allocating)
+            return;
+        const facts = sessionCage();
+        /**
+         * No explicit «is this machine caged» gate, and it stays that way (#398 S7,
+         * B5 — reviewed, tried, and rejected on 10.09.2026).
+         *
+         * The finding is real as far as it goes: `sessionScopeUnitOf` answers null
+         * for sessions started on an uncaged machine, but NOT for sessions that
+         * were already running when the machine lost its cage — for those the
+         * register still holds a unit name, and this loop would go on writing
+         * limits to scopes that may no longer be anybody's.
+         *
+         * A gate on `sessionCage().mode` is nonetheless the wrong fix, and the
+         * suite says so out loud: every memory test here drives the allocator
+         * through its injected readers WITHOUT probing a cage, so such a gate turns
+         * thirty tests off rather than making them pass — which is the shape of a
+         * change that looks green and proves nothing.
+         *
+         * What actually happens in the case the finding describes is small and
+         * self-correcting: the write fails, `setScopeProperties` logs it and
+         * returns false, and nothing is corrupted. Left as is, deliberately.
+         */
+        const slice = (this.opts.readSliceLimits ?? readSliceLimits)();
+        const load = (this.opts.readHostLoad ?? readHostLoad)();
+        if (slice === null || load === null)
+            return;
+        const holdOf = this.opts.readScopeHold ?? readScopeHold;
+        const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+        const live = [];
+        for (const running of this.sessions.values()) {
+            if (running.session === null)
+                continue;
+            const unit = unitOf(running.descriptor.id);
+            if (unit === null)
+                continue;
+            const hold = holdOf(unit);
+            if (hold === null)
+                continue;
+            live.push({ running, unit, hold });
+        }
+        // Computed even when nobody is running, and that is not a waste: half of
+        // what the card shows is about the MACHINE — the live pot, what is held by
+        // things that are not DevBridge, how many guarantees would fit — and an idle
+        // machine has to be able to say it too. With no sessions the loop below
+        // simply has nothing to write.
+        const machine = this.allocatorMachine(slice, load.memAvailableBytes, facts.swapMaxBytes ?? 0);
+        const allocation = allocateSessionMemory(machine, live.map(({ running, hold }) => ({
+            id: running.descriptor.id,
+            holdBytes: hold.holdBytes,
+            currentBytes: hold.currentBytes,
+        })), this.opts.memoryKnobs ?? {});
+        this.lastAllocation = allocation;
+        this.lastAllocatorMachine = machine;
+        this.allocating = true;
+        try {
+            const write = this.opts.setScopeProperties ?? setScopeProperties;
+            const readStatus = this.opts.readScopeMemoryStatus ?? readScopeMemoryStatus;
+            for (const { running, unit, hold } of live) {
+                const wanted = allocation.sessions.find((s) => s.id === running.descriptor.id);
+                if (!wanted)
+                    continue;
+                /**
+                 * Reconcile before planning (work 10 of the stage).
+                 *
+                 * What this supervisor believes it wrote and what the scope actually
+                 * holds are two different facts, and they have come apart before — a
+                 * drop-in that never applied while the card said «capped». The cgroup is
+                 * the authority, and reading it costs nothing here: the status is two
+                 * small files the watch already reads.
+                 */
+                const inForce = readStatus(unit);
+                let written = running.limits ?? null;
+                if (inForce !== null && written !== null) {
+                    const realBrake = inForce.highBytes;
+                    const realWall = inForce.maxBytes;
+                    if ((realBrake !== null && realBrake !== written.brakeBytes) ||
+                        (realWall !== null && realWall !== written.wallBytes)) {
+                        log.warn('session memory: the scope does not hold what this runner wrote', {
+                            sessionId: running.descriptor.id,
+                            believedBrakeMB: Math.round(written.brakeBytes / (1024 * 1024)),
+                            actualBrakeMB: realBrake === null ? null : Math.round(realBrake / (1024 * 1024)),
+                            believedWallMB: Math.round(written.wallBytes / (1024 * 1024)),
+                            actualWallMB: realWall === null ? null : Math.round(realWall / (1024 * 1024)),
+                        });
+                        written = {
+                            ...written,
+                            ...(realBrake === null ? {} : { brakeBytes: realBrake }),
+                            ...(realWall === null ? {} : { wallBytes: realWall }),
+                        };
+                    }
                 }
+                const move = planLimitMove(written, wanted, hold.holdBytes, facts.memoryLowFlag);
+                if (move.properties.length > 0) {
+                    if (!(await write(unit, move.properties)))
+                        continue;
+                    if (move.lowered) {
+                        /**
+                         * We just narrowed this session's brake, and that manufactures the
+                         * exact signal the stall detector looks for: measured on this host,
+                         * a process honestly writing at 6.4 MB/s stopped dead the instant
+                         * its `MemoryHigh` was narrowed on the live scope. Without this the
+                         * mechanism would catch its own edit and stop a command for it.
+                         */
+                        const stall = running.stall;
+                        if (stall) {
+                            stall.detector = {
+                                ...stall.detector,
+                                mutedUntil: now + STALL_MUTE_AFTER_LOWER_MS,
+                                hotWindows: 0,
+                                stalledSince: null,
+                            };
+                            stall.remainingMs = null;
+                        }
+                    }
+                }
+                running.limits = {
+                    brakeBytes: move.brakeBytes,
+                    wallBytes: move.wallBytes,
+                    guaranteedBytes: move.guaranteedBytes,
+                    swapBytes: move.swapBytes,
+                    holdBytes: move.holdBytes,
+                    shrinkTicks: move.shrinkTicks,
+                };
             }
-            running.cageWatch = {
-                unit,
-                oomKills: status.oomKills,
-                ownOom: status.ownLimitOom,
-                highEvents: status.highEvents,
-                brakedSince,
-                warnedLong,
-                calmTicks,
+        }
+        finally {
+            this.allocating = false;
+        }
+        // After the writes, never before: the frame reports what is IN FORCE, and
+        // reporting an intention that then failed to apply is how a card starts
+        // lying about a machine.
+        this.publishSessionLimits(now, allocation);
+    }
+    /** The machine as the allocator needs to see it, from live readings only. */
+    allocatorMachine(slice, availableBytes, swapBytes) {
+        const totalBytes = os.totalmem();
+        return {
+            potBytes: slice.potBytes,
+            availableBytes,
+            totalBytes,
+            reserveBytes: machineReserveBytes(totalBytes),
+            oomContinue: sessionCage().oomContinue,
+            // The hard invariant: overselling the brakes is legal only while the
+            // slice carries a live collective brake. Read back off cgroupfs, never
+            // assumed from what we wrote to the drop-in.
+            collectiveBrake: slice.collectiveBrakeBytes !== null,
+            swapBytes,
+        };
+    }
+    /**
+     * What a session STARTING right now should be given (#398 S3, work 9).
+     *
+     * The allocator is asked to compute as though this session already existed,
+     * so a session born at 03:00 gets the number its first tick will confirm
+     * rather than the one the daemon measured whenever it last started.
+     */
+    ladderForNewSession(id) {
+        /**
+         * A session that ALREADY exists is answered with what is in force for it,
+         * not with what a newcomer would get.
+         *
+         * Found by the independent review of 10.09.2026, and it was not only the
+         * cage that asked: `policyContextFor` calls `sessionMemoryFor` on every
+         * Bash tool call, so the heap gate was judging commands against a ceiling
+         * computed as though the asking session did not exist — which drops its own
+         * `memory.current` out of the live pot and makes the number much smaller
+         * exactly while the session is busy. The gate would then refuse a heap the
+         * cage would have allowed.
+         *
+         * The newcomer arithmetic below is for the one caller that really has no
+         * session yet: `cageSpawn`, at the moment of the start.
+         */
+        const inForce = this.sessions.get(id)?.limits ?? null;
+        if (inForce) {
+            return {
+                highBytes: inForce.brakeBytes,
+                maxBytes: inForce.wallBytes,
+                swapBytes: inForce.swapBytes,
+                guaranteedBytes: inForce.guaranteedBytes,
             };
         }
+        // Reached only from `cageSpawn`, which has already established that this
+        // machine has a cage — see `runAllocator` for why there is no second gate.
+        const facts = sessionCage();
+        const slice = (this.opts.readSliceLimits ?? readSliceLimits)();
+        const load = (this.opts.readHostLoad ?? readHostLoad)();
+        if (slice === null || load === null)
+            return null;
+        const holdOf = this.opts.readScopeHold ?? readScopeHold;
+        const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+        const sessions = [];
+        for (const running of this.sessions.values()) {
+            if (running.session === null || running.descriptor.id === id)
+                continue;
+            const unit = unitOf(running.descriptor.id);
+            const hold = unit === null ? null : holdOf(unit);
+            if (hold === null)
+                continue;
+            sessions.push({
+                id: running.descriptor.id,
+                holdBytes: hold.holdBytes,
+                currentBytes: hold.currentBytes,
+            });
+        }
+        // The starting session holds nothing yet, and saying so is the point: it
+        // must not be given the pot as though it already had it.
+        sessions.push({ id, holdBytes: 0, currentBytes: 0 });
+        const allocation = allocateSessionMemory(this.allocatorMachine(slice, load.memAvailableBytes, facts.swapMaxBytes ?? 0), sessions, this.opts.memoryKnobs ?? {});
+        const mine = allocation.sessions.find((s) => s.id === id);
+        if (!mine)
+            return null;
+        return {
+            highBytes: mine.brakeBytes,
+            maxBytes: mine.wallBytes,
+            swapBytes: mine.swapBytes,
+            guaranteedBytes: mine.guaranteedBytes,
+        };
+    }
+    /**
+     * Tell the API how this machine is dividing its memory — when it moved (#398 S4).
+     *
+     * Built from the pass the allocator has just finished rather than measured
+     * again: two readings of a moving machine taken a moment apart would let the
+     * card and the scope disagree about the same session, and «the card said 4 GB
+     * and the cgroup said 2» is the exact shape of the bug that made
+     * `limitsCurrent` untrustworthy once already.
+     *
+     * Recorded ONLY when the socket took it, same as `publishHostLoad`: a frame
+     * dropped by a dead socket must not be remembered as sent.
+     */
+    /**
+     * The number on the machine card: what ONE session gets when the machine is
+     * free (decision D4 of `runner-cage-authority.md`, 10.09.2026).
+     *
+     * The card used to carry the ceiling a newcomer would get RIGHT NOW, from the
+     * current crowd — which is honest per second and useless per person: on a
+     * 12 GiB machine with two sessions of 3 GiB it read ~6 GiB, it moved whenever
+     * a neighbour started or stopped, and the sentence beside it said «up to X on
+     * an idle machine», which is a different number entirely. A card is read to
+     * answer «what does this machine give a session», and that question has a
+     * still answer.
+     *
+     * Computed, not measured: the pot and the owner's knobs are all it takes, so
+     * this makes no second reading of a moving machine — the one the shape of
+     * `publishSessionLimits` warns against in its own header.
+     */
+    idleSessionCeiling(allocation) {
+        const machine = this.lastAllocatorMachine;
+        // No pot means no slice ceiling to be idle against, and then the pool the
+        // allocation already used is the honest answer.
+        if (machine === null || machine.potBytes === null)
+            return Math.floor(allocation.poolBytes);
+        const idle = allocateSessionMemory(
+        // «Free» is `available` big enough that the pot itself is the binding
+        // limit: the pool is `min(pot, available − reserve)` floored at the
+        // guarantee, so anything at or above `pot + reserve` gives a full pot.
+        { ...machine, availableBytes: machine.potBytes + machine.reserveBytes }, [{ id: '__card__', holdBytes: 0, currentBytes: 0 }], this.opts.memoryKnobs ?? {});
+        const only = idle.sessions[0];
+        return Math.floor(only?.brakeBytes ?? allocation.poolBytes);
+    }
+    publishSessionLimits(now, allocation) {
+        if (allocation === null)
+            return;
+        const load = (this.opts.readHostLoad ?? readHostLoad)();
+        if (load === null)
+            return;
+        /**
+         * Stamped HERE, not from the tick's own clock.
+         *
+         * One pass of the stall watch can publish twice — once from the allocator
+         * the stalled session asked for, once from the tick — and both were being
+         * stamped with the single `now` the pass began with. The gateway's ordering
+         * guard is `measuredAt <= last`, so the second frame was dropped while this
+         * side recorded it as sent, and the difference stayed invisible until the
+         * heartbeat a minute later. `host_load` has never had the bug because
+         * `readHostLoad` stamps inside itself, once per publish. Found by the
+         * independent review of 10.09.2026.
+         */
+        const measuredAt = Math.max(now, this.lastLimitsSentAt + 1);
+        // What is held on this machine by everything that is not us. The card had
+        // nowhere to get this, and it is the main question of #398.
+        const otherHeld = Math.max(0, os.totalmem() - load.memAvailableBytes - allocation.heldBytes);
+        const frame = {
+            at: new Date(measuredAt).toISOString(),
+            poolBytes: Math.floor(allocation.poolBytes),
+            heldBytes: Math.floor(allocation.heldBytes),
+            otherHeldBytes: Math.floor(otherHeld),
+            /**
+             * What is PROMISED, and only where the machine can keep the promise
+             * (#398 S7, B3): zero when the slice carries no `memory.low` of its own,
+             * because then nothing is reserved for anybody and the card must not say
+             * otherwise. Measured on this host: the file held 0 while the chip read
+             * «2.0 GB guaranteed».
+             */
+            guaranteeBytes: ((this.opts.readSliceLimits ?? readSliceLimits)()?.guaranteeBytes ?? 0) > 0
+                ? (this.opts.memoryKnobs?.guaranteeBytes ?? SESSION_GUARANTEE_BYTES)
+                : 0,
+            // Asked of the allocator, not derived from the pot: only it knows the
+            // owner's knobs, the band this machine uses and the single-session branch.
+            // On an IDLE machine, though — see `idleSessionCeiling`.
+            sessionCeilingBytes: this.idleSessionCeiling(allocation),
+            guaranteesFit: allocation.guaranteesFit,
+            seats: this.maxSessions,
+            swapPerSessionBytes: sessionCage().swapMaxBytes ?? 0,
+            collectiveBrake: !allocation.conservative,
+            conservative: allocation.conservative,
+            hungry: allocation.hungry,
+            sessions: allocation.sessions.map((s) => {
+                const running = this.sessions.get(s.id);
+                /**
+                 * What is IN FORCE, not what the allocator wanted.
+                 *
+                 * `running.limits` is what systemd was actually told; the allocation is
+                 * an intention, and the two come apart every time a write fails or a
+                 * movement rule refuses to lower something. A card drawn from the
+                 * intention would claim a session had a share no scope has ever held —
+                 * the kind of lie that made `limitsCurrent` untrustworthy once already.
+                 * Found by the independent review of 10.09.2026.
+                 */
+                const written = running?.limits ?? null;
+                return {
+                    sessionId: s.id,
+                    guaranteedBytes: Math.floor(written?.guaranteedBytes ?? s.guaranteedBytes),
+                    brakeBytes: Math.floor(written?.brakeBytes ?? s.brakeBytes),
+                    wallBytes: Math.floor(written?.wallBytes ?? s.wallBytes),
+                    holdBytes: Math.floor(written?.holdBytes ?? 0),
+                    tight: s.tight,
+                    stallRemainingMs: running?.stall?.remainingMs ?? null,
+                    reason: running?.stall?.reason ?? null,
+                };
+            }),
+        };
+        const heartbeatDue = sessionLimitsHeartbeatDue(now - this.lastLimitsSentAt, this.limitsHeartbeatMs);
+        if (!heartbeatDue && !sessionLimitsChangedEnough(this.lastPublishedLimits, frame))
+            return;
+        if (this.ws.send({ type: 'session_limits', ...frame })) {
+            this.lastPublishedLimits = frame;
+            this.lastLimitsSentAt = measuredAt;
+        }
     }
     publishHostLoad() {
         const sample = (this.opts.readHostLoad ?? readHostLoad)();
@@ -822,10 +1561,16 @@ export class Supervisor {
                 // is right only after five minutes of silence is not right.
                 this.lastPublishedHostLoad = null;
                 this.lastHostLoadSentAt = 0;
+                // …and for the memory numbers, which the API keeps the same way (#398 S4).
+                this.lastPublishedLimits = null;
+                this.lastLimitsSentAt = 0;
                 this.setMaxSessions(frame.maxSessions);
                 await this.reconcile(frame.sessions);
                 this.publishSlots();
                 this.publishHostLoad();
+                // Deliberately not awaited: this frame also carries the session
+                // reconciliation, and a slow cgroup read must not hold it up.
+                void this.runAllocator(Date.now());
                 // 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();
@@ -2733,6 +3478,8 @@ export class Supervisor {
                 return;
             case 'permission_resolved':
                 running.openPermissions.delete(event.requestId);
+                // …and the same for a permission card — see `tellAgent`.
+                this.flushPendingAgentNote(running);
                 this.sendEvent(running, 'permission_resolved', {
                     requestId: event.requestId,
                     allow: event.allow,
@@ -2778,6 +3525,8 @@ export class Supervisor {
                 return;
             case 'question_resolved':
                 running.openQuestions.delete(event.askId);
+                // Anything the runner itself wanted to say while the card was open.
+                this.flushPendingAgentNote(running);
                 this.sendEvent(running, 'question_resolved', {
                     askId: event.askId,
                     outcome: event.outcome,
@@ -6241,6 +6990,8 @@ export class Supervisor {
     shutdown() {
         clearInterval(this.slotsTimer);
         clearInterval(this.hostLoadTimer);
+        clearInterval(this.stallTimer);
+        setLiveLadderSource(null);
         clearInterval(this.agentVersionsTimer);
         clearTimeout(this.agentCleanupFirstTimer);
         clearInterval(this.agentCleanupTimer);