@bridge4dev/runner 0.57.0 → 0.58.2

package/dist/config.js

@@ -41,7 +41,65 @@ const ConfigSchema = z.object({
     // processes and worktrees may exist at once.
     limits: z
         .object({
-        max_sessions: z.number().int().min(1).max(64),
+        /**
+         * OPTIONAL since 0.58.0, and the change is a bug fix rather than a
+         * loosening.
+         *
+         * `loadConfig()` uses `.parse`, not `safeParse`, and a ZodError from it
+         * reaches `main().catch` and exits 1 — under systemd that is a restart
+         * loop. So while this field was required, a machine owner who opened
+         * `config.toml` to add any OTHER key under `[limits]` and did not happen
+         * to have this one would have taken their dev server down, and `doctor`
+         * could not have told them why: it dies on the same parse.
+         *
+         * The default is unchanged — absence means «the API's number decides»,
+         * which is what `get maxSessions()` already did.
+         */
+        max_sessions: z.number().int().min(1).max(64).optional(),
+        /**
+         * #398 S6: the emergency switch back to the pre-0.58.0 behaviour.
+         *
+         * `false` puts every session on the fixed `max(pot / 3, 2 GiB)` share
+         * that shipped in 0.55.0, computed once at daemon start and never moved.
+         * It exists because this formula travels to dev servers nobody here has
+         * ever seen, and the two previous memory rules were both reasonable on
+         * the author's machine and destructive somewhere else. A machine owner
+         * who has to get work done tonight needs a way back that does not involve
+         * downgrading the runner.
+         */
+        adaptive_memory: z.boolean().optional(),
+        /**
+         * The guarantee, in megabytes — what a session on this machine will not
+         * have taken away.
+         *
+         * The default is 2048, sized over the 1571 MB peak measured for a
+         * workspace `pnpm typecheck`. Lower it on a machine that runs lighter
+         * work and wants more sessions; raise it on one that runs heavier.
+         */
+        session_memory_min: z.number().int().min(256).max(262144).optional(),
+        /**
+         * A ceiling on the ceiling, in megabytes — the most any single session
+         * may be allowed to grow to, whatever the machine has free.
+         *
+         * For the owner who wants agents to leave room for something the runner
+         * cannot see (a build they run by hand, a database that spikes).
+         */
+        session_memory_max: z.number().int().min(256).max(1048576).optional(),
+        /**
+         * How long a session that has stopped moving is given before its biggest
+         * command is stopped, in seconds. Default 180 (decision D6).
+         */
+        memory_stall_grace_sec: z.number().int().min(30).max(3600).optional(),
+        /**
+         * What happens when that time runs out: `stop-command` (the default) or
+         * `report-only`.
+         *
+         * `report-only` is for the owner who would rather have a session stand
+         * still than have a command stopped under it. It changes nothing else —
+         * the deadline still runs and the strip still shows it, so the person can
+         * act; only DevBridge stops acting on their behalf.
+         */
+        memory_stall_action: z.enum(['stop-command', 'report-only']).optional(),
     })
         .optional(),
     /**

package/dist/daemon-lock.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One daemon per user manager, and the reason is the sweep (#403).
+ *
+ * `cmdDaemon` stops every session scope it does not know about, and at start-up
+ * it knows about none — that is the point: a scope outliving a killed daemon
+ * carries a whole process tree with it. But the same line, run by a SECOND
+ * daemon on a machine where the first one is working, ends every live session
+ * the first one is supervising. `pnpm --filter @bridge4dev/runner dev` beside a
+ * paired runner is enough, and no amount of care inside the test suite touches
+ * that path.
+ *
+ * The lock is in `/run/user/<uid>` and not in the state directory on purpose:
+ * `DEVBRIDGE_RUNNER_HOME` moves the state directory (the test contour uses it),
+ * and two daemons with different state directories still share one systemd user
+ * bus — which is the thing being protected.
+ */
+export interface DaemonLock {
+    /** Where the lock lives, for the message a person reads. */
+    path: string;
+    /** Give it up — on shutdown, or when the daemon is done with it. */
+    release: () => void;
+}
+export interface HeldByAnother {
+    heldBy: number;
+    path: string;
+}
+/** The lock file for this user's manager. */
+export declare function daemonLockPath(): string;
+/**
+ * Take the lock, or say who has it.
+ *
+ * A stale lock — the pid in it is gone — is taken over silently: a daemon that
+ * was killed with `SIGKILL` cannot clean up after itself, and refusing to start
+ * after a crash would be a worse failure than the one being prevented.
+ */
+export declare function acquireDaemonLock(io?: {
+    lockPath?: () => string;
+    isAlive?: (pid: number) => boolean;
+    now?: () => number;
+}): DaemonLock | HeldByAnother;
+/** True when this is a refusal rather than a lock. */
+export declare function isHeldByAnother(result: DaemonLock | HeldByAnother): result is HeldByAnother;
+//# sourceMappingURL=daemon-lock.d.ts.map

package/dist/daemon-lock.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runnerIdentity, systemdUserEnv } from './environment.js';
+import { log } from './log.js';
+import { isPidAlive } from './status-file.js';
+/** The lock file for this user's manager. */
+export function daemonLockPath() {
+    const runtimeDir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+    const uid = runnerIdentity().uid;
+    const dir = runtimeDir ?? path.join('/run/user', String(uid));
+    return path.join(dir, 'devbridge-runner.daemon.lock');
+}
+/**
+ * Take the lock, or say who has it.
+ *
+ * A stale lock — the pid in it is gone — is taken over silently: a daemon that
+ * was killed with `SIGKILL` cannot clean up after itself, and refusing to start
+ * after a crash would be a worse failure than the one being prevented.
+ */
+export function acquireDaemonLock(io = {}) {
+    const file = (io.lockPath ?? daemonLockPath)();
+    const alive = io.isAlive ?? isPidAlive;
+    const write = () => {
+        fs.writeFileSync(file, JSON.stringify({ pid: process.pid, at: (io.now ?? Date.now)() }), {
+            flag: 'w',
+        });
+    };
+    /**
+     * The directory first and on its own, because its `EEXIST` means the opposite
+     * of the one below: «the folder is already there», which is the ordinary
+     * case. Mixed into the same `try`, it was read as «somebody holds the lock».
+     */
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            log.warn('daemon: could not take the single-daemon lock, starting without it', {
+                path: file,
+                error: String(error instanceof Error ? error.message : error),
+            });
+            return { path: file, release: () => { } };
+        }
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            // `wx` fails when the file exists — that is the whole exclusion.
+            fs.writeFileSync(file, JSON.stringify({ pid: process.pid, at: (io.now ?? Date.now)() }), {
+                flag: 'wx',
+            });
+            return { path: file, release: () => releaseLockFile(file) };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                /**
+                 * The runtime directory is not there, or is not writable. Not a reason
+                 * to refuse to start: a machine with no `/run/user/<uid>` has no user
+                 * manager either, so it has no session scopes to protect.
+                 */
+                log.warn('daemon: could not take the single-daemon lock, starting without it', {
+                    path: file,
+                    error: String(error instanceof Error ? error.message : error),
+                });
+                return { path: file, release: () => { } };
+            }
+            const holder = readHolder(file);
+            if (holder !== null && holder !== process.pid && alive(holder)) {
+                return { heldBy: holder, path: file };
+            }
+            // Stale (the holder is gone) or ours from a previous life: take it over.
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch {
+                // Somebody else got there first; the next attempt will find out whose.
+            }
+            if (attempt === 1) {
+                write();
+                return { path: file, release: () => releaseLockFile(file) };
+            }
+        }
+    }
+    return { path: file, release: () => releaseLockFile(file) };
+}
+/** True when this is a refusal rather than a lock. */
+export function isHeldByAnother(result) {
+    return 'heldBy' in result;
+}
+function readHolder(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return typeof raw.pid === 'number' && raw.pid > 0 ? raw.pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function releaseLockFile(file) {
+    try {
+        if (readHolder(file) === process.pid)
+            fs.rmSync(file, { force: true });
+    }
+    catch {
+        // Gone already, or never ours. Nothing to undo.
+    }
+}
+//# sourceMappingURL=daemon-lock.js.map

package/dist/host-load.d.ts

@@ -12,6 +12,15 @@
  * both world-readable, neither containing a path, a command line, an
  * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
  *
+ * **One module is allowed past that line, and it is named here so the rule and
+ * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
+ * processes of ONE session's own cgroup, in order to choose which command to
+ * stop when that session has run out of memory (#398 S2). It is not telemetry —
+ * nothing it reads is reported anywhere, and the single thing that leaves the
+ * machine is a command NAME with no arguments, because arguments carry keys and
+ * tokens. Choosing a victim cannot be done from two summary files, and the
+ * alternative was killing the session instead of its command.
+ *
  * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
  * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
  * the source of truth, exactly like `levels.ts` mirrors the level thresholds

package/dist/host-load.js

@@ -15,6 +15,15 @@ import path from 'node:path';
  * both world-readable, neither containing a path, a command line, an
  * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
  *
+ * **One module is allowed past that line, and it is named here so the rule and
+ * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
+ * processes of ONE session's own cgroup, in order to choose which command to
+ * stop when that session has run out of memory (#398 S2). It is not telemetry —
+ * nothing it reads is reported anywhere, and the single thing that leaves the
+ * machine is a command NAME with no arguments, because arguments carry keys and
+ * tokens. Choosing a victim cannot be done from two summary files, and the
+ * alternative was killing the session instead of its command.
+ *
  * Mirror of `packages/shared/src/schemas/host-load.ts` and the `HOST_LOAD_*`
  * block of `packages/shared/src/constants/runner.ts` — the DevBridge side is
  * the source of truth, exactly like `levels.ts` mirrors the level thresholds

package/dist/index.js

@@ -9,6 +9,8 @@ import { ClaudeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
 import { sessionClaudePath } from './agent-binary.js';
+import { claimCageAuthority, runSystemctl } from './cage-authority.js';
+import { acquireDaemonLock, isHeldByAnother } from './daemon-lock.js';
 import { loadConfig, mergeIntoPairedConfig, requireConfig, saveConfig, } from './config.js';
 import { log } from './log.js';
 import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
@@ -17,12 +19,14 @@ import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
 import { RunnerWsClient } from './ws-client.js';
 import { RUNNER_VERSION } from './version.js';
-import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, sessionsSliceOverridePath, unitExecTarget, unitPath, writeLimitsOverride, DEVBRIDGE_SLICE, LIMITS_VERSION, SESSION_CPU_WEIGHT, SESSIONS_SLICE, } from './service-unit.js';
-import { initSessionCage, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
+import { SESSION_GUARANTEE_BYTES } from './session-allocator.js';
+import { STALL_GRACE_MS } from './session-stall.js';
+import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, sessionsSliceOverridePath, unitExecTarget, unitPath, writeLimitsOverride, DEVBRIDGE_SLICE, LIMITS_VERSION, SESSION_CPU_WEIGHT, SESSIONS_SLICE, readSwapTotalBytes, } from './service-unit.js';
+import { defaultCageProbe, initSessionCage, readSliceLimits, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
 import { SEARCH_GUARD_ENABLED, claudeSettingsPath, installSearchGuard, removeSearchGuard, searchGuardCommand, searchGuardHome, searchGuardHookPath, searchGuardStatus, } from './claude-settings.js';
 import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
 import { agentAuthStatuses } from './auth-relay.js';
-import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, systemdUserEnv, } from './environment.js';
+import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, } from './environment.js';
 import { mcpConfigDir } from './paths.js';
 import { readMemoryFactsFromSystemd } from './systemd-memory.js';
 const execFileAsync = promisify(execFile);
@@ -536,6 +540,11 @@ async function cmdPair(args) {
     // Probed here as well as at daemon start, so the very first record of this
     // server already carries the truth about its containment instead of the safe
     // default. Costs one throwaway process, once.
+    //
+    // `probe` and not `daemon` (#403): pairing may run its own throwaway unit and
+    // clean it up, and it has no business anywhere near a session's cage — there
+    // may be a daemon running sessions on this machine right now.
+    claimCageAuthority('probe');
     await initSessionCage();
     const capabilities = runnerCapabilities(apiUrl);
     const response = await fetch(`${apiUrl}/api/v1/dev/servers/claim`, {
@@ -607,7 +616,91 @@ const RESTART_DELAY_MS = 1_500;
  * a runner that refuses to start because it could not improve its own limits is
  * strictly worse than one that starts without the improvement.
  */
-async function repairResourceLimits() {
+/**
+ * The machine as the cage last measured it — see {@link reMeasureMachine}.
+ */
+let lastMachineFingerprint = null;
+/**
+ * Re-measure the machine on the hourly tick, and re-probe the cage when it has
+ * actually changed (#398 S3, work 11).
+ *
+ * `initSessionCage()` probes the machine EXACTLY ONCE, at daemon start, and
+ * remembers the answer; the hourly `repairResourceLimits` rewrites the slice's
+ * drop-in from fresh facts but never touches that cache. A live example, on the
+ * day of the incident: a swap file appeared on vmi3219930, and every session
+ * there went on being told `MemorySwapMax=0` — so the brake kept stopping dead
+ * instead of slowing down, on the one machine that had by then acquired
+ * somewhere to push pages. Until this, such a machine was cured only by
+ * restarting the runner.
+ *
+ * The probe costs a throwaway scope, so it is not done unconditionally: it runs
+ * only when the machine's fingerprint moved. New numbers reach LIVE sessions
+ * through the allocator's own tick, which reads the slice off cgroupfs and
+ * writes what has changed.
+ *
+ * The card is deliberately NOT promised here: `capabilities` are assembled once
+ * in `cmdDaemon` and travel only inside `hello`, so there is nothing to reissue
+ * them with short of a reconnect.
+ */
+async function reMeasureMachine(maxSessions) {
+    await repairResourceLimits(maxSessions);
+    try {
+        const slice = readSliceLimits();
+        const fingerprint = JSON.stringify({
+            swap: readSwapTotalBytes() ?? 0,
+            pot: slice?.potBytes ?? null,
+            brake: slice?.collectiveBrakeBytes ?? null,
+        });
+        if (lastMachineFingerprint === null) {
+            lastMachineFingerprint = fingerprint;
+            return;
+        }
+        if (fingerprint === lastMachineFingerprint)
+            return;
+        log.warn('daemon: the machine changed under us — re-measuring the session cage', {
+            was: lastMachineFingerprint,
+            now: fingerprint,
+        });
+        /**
+         * A re-probe that comes back WORSE does not take the cage away.
+         *
+         * `initSessionCage` replaces what the daemon knows, and its live probe is a
+         * `systemd-run` — one transient failure (a busy bus, a momentary
+         * `Failed to connect`) would answer `nice-only`, and from that moment every
+         * new session on that machine would start with no cage at all, until
+         * somebody restarted the runner. An hourly job must not be able to do that.
+         * Found by the independent review of 10.09.2026.
+         *
+         * Losing the cage for real is possible — someone remounts cgroups, the user
+         * bus goes — and it is not silent: the line below says so, and the next
+         * daemon start settles it.
+         */
+        // `keepCageIfWorse`: an hourly job must not be able to uncage a healthy
+        // machine on one transient `systemd-run` failure — see `initSessionCage`.
+        const facts = await initSessionCage(defaultCageProbe, { keepCageIfWorse: true });
+        /**
+         * Remembered only when the measurement actually SUCCEEDED (#398 S7, B4).
+         *
+         * The fingerprint used to be stored before the probe, so one transient
+         * failure — the very failure `keepCageIfWorse` exists to survive — left the
+         * next hour seeing an unchanged fingerprint and skipping the re-probe
+         * forever. The cage was kept, and the FACTS behind it stayed yesterday's:
+         * `swapMaxBytes` above all, which is the vmi3219930 bug this work was
+         * written for. Cured only by restarting the runner, which is what the whole
+         * job was supposed to stop needing.
+         */
+        if (facts.mode === 'scope')
+            lastMachineFingerprint = fingerprint;
+    }
+    catch (error) {
+        // Never fatal: a runner that dies because it could not re-measure is worse
+        // than one that keeps yesterday's numbers for another hour.
+        log.warn('daemon: could not re-measure the machine', {
+            error: String(error instanceof Error ? error.message : error),
+        });
+    }
+}
+async function repairResourceLimits(maxSessions) {
     try {
         const { facts, sessionsUsageBytes } = await readMemoryFactsFromSystemd();
         if (facts === null) {
@@ -628,17 +721,14 @@ async function repairResourceLimits() {
                 totalMB: Math.round(facts.totalBytes / 1048576),
             });
         }
-        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes))
+        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes, maxSessions))
             return;
         log.warn('daemon: resource limits drop-in written — reloading systemd', {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
             ...memoryPolicy(facts),
         });
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
-            timeout: 15_000,
-            env: systemdUserEnv(),
-        });
+        await runSystemctl(['daemon-reload'], { timeout: 15_000 });
         // Deliberately no restart: `daemon-reload` alone is enough for these
         // directives — verified live twice, in both directions: 2026-07-30 removing a
         // ceiling (MemoryMax 2G→infinity, OOMPolicy stop→continue) and 2026-08-12
@@ -757,13 +847,51 @@ async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
+    /**
+     * One daemon per user manager, checked BEFORE the sweep below (#403).
+     *
+     * The sweep stops every session scope this process does not know about, and
+     * at start-up that is all of them. A second daemon — `pnpm dev` of this
+     * package beside a paired runner, or a hand-started `devbridge-runner daemon`
+     * — therefore ends every live session the first one is supervising, and no
+     * guard inside the test suite covers that path.
+     *
+     * The escape hatch is deliberate and narrow: `DEVBRIDGE_ALLOW_SECOND_DAEMON=1`
+     * starts a second daemon with the `probe` grade, so it can run and be
+     * developed against but cannot touch anybody's cage.
+     */
+    const lock = acquireDaemonLock();
+    const second = isHeldByAnother(lock);
+    if (second) {
+        if (process.env['DEVBRIDGE_ALLOW_SECOND_DAEMON'] !== '1') {
+            fail(`another devbridge-runner daemon is already running on this user (pid ${lock.heldBy}). ` +
+                "Two daemons stop each other's sessions — see the lock at " +
+                `${lock.path}. Set DEVBRIDGE_ALLOW_SECOND_DAEMON=1 to start one that cannot touch cages.`);
+        }
+        log.warn('daemon: a second daemon, started without the right to act on session cages', {
+            heldBy: lock.heldBy,
+        });
+    }
+    else {
+        process.once('exit', () => lock.release());
+    }
+    /**
+     * The daemon is the ONE process on this machine allowed to act on session
+     * cages (#403), and it says so here, once, before the first sweep.
+     *
+     * Everything below — the sweep, the drop-ins, the probe, and later every
+     * limit written to a live scope — goes through `cage-authority.ts` and would
+     * be refused without this line. A test process cannot reach it at all: the
+     * claim throws there rather than granting anything.
+     */
+    claimCageAuthority(second ? 'probe' : 'daemon');
     // Nothing of ours is running yet, so every `devbridge-session-*.scope` on this
     // machine belongs to a process that is gone. Stopping the scope takes the
     // whole tree under it — which is the answer to the `ugrep` that outlived its
     // session by 10 h 51 min on 16.08, and to every scope the OOM killer left in
     // `failed` (a name systemd will otherwise refuse to reuse).
     await sweepOrphanSessionScopes();
-    await repairResourceLimits();
+    await repairResourceLimits(config.limits?.max_sessions);
     // After the drop-ins are on disk and reloaded, never before: the probe below
     // creates `devbridge-sessions.slice`, and a slice first loaded without its
     // policy would hold no ceiling until the next daemon-reload.
@@ -785,6 +913,29 @@ async function cmdDaemon() {
         },
         ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
         ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
+        /**
+         * #398 S6: the machine owner's memory knobs, read once here and passed
+         * down. Nothing outside this file imports `config.js`, and a module that
+         * read the file itself would be the first place for two answers about one
+         * setting to appear.
+         */
+        memoryKnobs: {
+            ...(config.limits?.adaptive_memory === undefined
+                ? {}
+                : { adaptive: config.limits.adaptive_memory }),
+            ...(config.limits?.session_memory_min === undefined
+                ? {}
+                : { guaranteeBytes: config.limits.session_memory_min * 1024 * 1024 }),
+            ...(config.limits?.session_memory_max === undefined
+                ? {}
+                : { sessionMaxBytes: config.limits.session_memory_max * 1024 * 1024 }),
+        },
+        ...(config.limits?.memory_stall_grace_sec === undefined
+            ? {}
+            : { stallGraceMs: config.limits.memory_stall_grace_sec * 1000 }),
+        ...(config.limits?.memory_stall_action === undefined
+            ? {}
+            : { memoryStallAction: config.limits.memory_stall_action }),
         // The same veto the capability list honours — announced AND enforced, so a
         // frame from an API that has not noticed still cannot start a run.
         verifyEnabled: config.verify?.enabled !== false,
@@ -836,7 +987,7 @@ async function cmdDaemon() {
     pruneTimer.unref();
     // Re-measure the machine — see `LIMITS_RECHECK_MS`. Writes nothing in the
     // normal case, so this is a file read and some arithmetic once an hour.
-    const limitsTimer = setInterval(() => void repairResourceLimits(), LIMITS_RECHECK_MS);
+    const limitsTimer = setInterval(() => void reMeasureMachine(config.limits?.max_sessions), LIMITS_RECHECK_MS);
     limitsTimer.unref();
     const shutdown = (signal) => {
         log.info(`daemon: ${signal} received, shutting down`);
@@ -931,6 +1082,9 @@ async function cmdInstallService() {
     requireConfig(); // fail early if not paired
     if (process.platform !== 'linux')
         fail('install-service supports Linux/systemd only');
+    // Installing the service writes the runner's own unit and starts it; it never
+    // touches a session's cage, so `install` and not `daemon` (#403).
+    claimCageAuthority('install');
     const target = unitPath();
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const exec = unitExecTarget();
@@ -979,10 +1133,8 @@ async function cmdInstallService() {
         print(`note: the service runs ${exec.execStart} directly — re-run install-service after reinstalling the package.`);
     }
     try {
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
-        await execFileAsync('systemctl', ['--user', 'enable', '--now', 'devbridge-runner'], {
-            env: systemdUserEnv(),
-        });
+        await runSystemctl(['daemon-reload']);
+        await runSystemctl(['enable', '--now', 'devbridge-runner']);
         print('Service enabled and started (systemctl --user).');
     }
     catch (error) {
@@ -1008,7 +1160,9 @@ function printCheck(check) {
 /** One property of the user service, or null when systemd cannot answer. */
 async function systemctlProperty(name) {
     try {
-        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', 'devbridge-runner', '-p', name, '--value'], { timeout: 10_000, env: systemdUserEnv() });
+        const { stdout } = await runSystemctl(['show', 'devbridge-runner', '-p', name, '--value'], {
+            timeout: 10_000,
+        });
         const value = stdout.trim();
         return value.length > 0 ? value : null;
     }
@@ -1378,6 +1532,9 @@ async function reportAgentReadiness(paths, fix) {
 }
 async function cmdDoctor(args) {
     const fix = args.includes('--fix');
+    // Reading needs no right at all; `--fix` writes the runner's own drop-in and
+    // reloads systemd, which is the `install` grade and nothing above it (#403).
+    claimCageAuthority(fix ? 'install' : 'probe');
     const config = loadConfig();
     print(`devbridge-runner ${RUNNER_VERSION}`);
     print(config ? `Paired with: ${config.server.name} (${config.api.url})` : 'Not paired');
@@ -1397,6 +1554,52 @@ async function cmdDoctor(args) {
     // build, so this is the honest ceiling regardless of what the dashboard says.
     const advised = Math.max(1, Math.floor(os.totalmem() / 1024 / 1024 / 1536));
     print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
+    /**
+     * #398 S6. Every memory number `doctor` printed before this block came off
+     * systemd or off `os` — it never said a word about `[limits]` in the machine
+     * owner's own `config.toml`, so «I set a guarantee and nothing changed» had no
+     * answer anywhere on the machine. Each line names the value in force AND
+     * where it came from.
+     */
+    print('');
+    print('Session memory (#398)');
+    {
+        const limits = loadConfig()?.limits;
+        const shipped = (value) => `${value} (shipped default)`;
+        const chosen = (value, unit) => `${value}${unit} (config.toml)`;
+        print(`  adaptive        ${limits?.adaptive_memory === false
+            ? 'OFF (config.toml) — sessions get the fixed pre-0.58.0 third'
+            : 'on (shipped default) — the share follows what is actually free'}`);
+        print(`  guarantee       ${limits?.session_memory_min === undefined
+            ? shipped(Math.round(SESSION_GUARANTEE_BYTES / 1024 / 1024)) + ' MB'
+            : chosen(limits.session_memory_min, ' MB')}`);
+        print(`  session ceiling ${limits?.session_memory_max === undefined
+            ? 'whatever the machine has free (shipped default)'
+            : chosen(limits.session_memory_max, ' MB')}`);
+        print(`  stall grace     ${limits?.memory_stall_grace_sec === undefined
+            ? shipped(Math.round(STALL_GRACE_MS / 1000)) + ' s'
+            : chosen(limits.memory_stall_grace_sec, ' s')}`);
+        print(`  when it stalls  ${limits?.memory_stall_action === 'report-only'
+            ? 'report only (config.toml) — DevBridge stops nothing'
+            : 'stop the biggest command (shipped default)'}`);
+        print(`  seats           ${limits?.max_sessions ?? 'the API decides (no max_sessions set)'}`);
+        const slice = readSliceLimits();
+        /**
+         * Named precisely, because «MISSING» alone sent people looking for a fault.
+         *
+         * The brake arrives with `LIMITS_VERSION` 6, and a machine whose runner has
+         * not restarted since the update simply does not have it yet — that is a
+         * pending update, not a broken machine. Found by the independent review of
+         * 10.09.2026.
+         */
+        const brakeInForce = slice?.collectiveBrakeBytes ?? null;
+        const dropInIsOld = limitsOverrideIsOutdated();
+        print(`  collective brake ${brakeInForce === null
+            ? dropInIsOld
+                ? 'not applied yet — the drop-in on this machine is older than this runner; `doctor --fix` writes it'
+                : 'MISSING — run `devbridge-runner doctor --fix`; until then sessions get a smaller share each'
+            : `${Math.round(brakeInForce / 1024 / 1024)} MB in force on the slice`}`);
+    }
     print('');
     print('Service limits');
     const { facts: memFacts, sessionsUsageBytes: memSessionsUsage } = await readMemoryFactsFromSystemd();
@@ -1476,8 +1679,7 @@ async function cmdDoctor(args) {
     }
     let effective;
     try {
-        const { stdout } = await execFileAsync('systemctl', [
-            '--user',
+        const { stdout } = await runSystemctl([
             'show',
             'devbridge-runner',
             '-p',
@@ -1490,7 +1692,7 @@ async function cmdDoctor(args) {
             'OOMPolicy',
             '-p',
             'NRestarts',
-        ], { env: systemdUserEnv() });
+        ]);
         effective = stdout.trim().split('\n').filter(Boolean);
     }
     catch {
@@ -1629,7 +1831,7 @@ async function cmdDoctor(args) {
         }
     }
     try {
-        await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
+        await runSystemctl(['daemon-reload']);
         print('systemctl --user daemon-reload — done.');
         print('Restart when sessions are idle: systemctl --user restart devbridge-runner');
     }

package/dist/policy.d.ts

@@ -71,6 +71,14 @@ export interface PolicyContext extends AgentGitPolicy {
      * than this release — and there the answer stays what it has always been.
      */
     agentAutoCommit?: boolean;
+    /**
+     * This session's memory ceiling in bytes, or `undefined` on a machine with no
+     * cage (#398 S5).
+     *
+     * Passed in rather than read here, so the pure policy stays pure and a test
+     * can put a session on a machine of any size.
+     */
+    sessionMemoryMaxBytes?: number;
     /**
      * Absolute path of the project's own prompt file, when this session was given
      * one (session 17).
@@ -226,5 +234,6 @@ export declare function evaluateRecipeCommand(command: string, ctx?: RecipeComma
  * workspace trust unchanged, which is exactly the old behaviour.
  */
 export declare function effectiveTrust(trustMode: TrustMode, mode?: AgentMode): TrustMode;
+export declare function requestedHeapBytes(command: string): number | null;
 export declare function evaluateToolUse(toolName: string, input: Record<string, unknown>, ctx: PolicyContext): PolicyDecision;
 //# sourceMappingURL=policy.d.ts.map