@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/host-load.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * What this machine can say about its own load, read straight from `/proc`.
+ *
+ * Until this existed, an overloaded dev server was visible in exactly one
+ * place: `sar` on the machine itself. The product could not say «this machine
+ * is on its knees», so it said nothing, and the first symptom a user saw was a
+ * session that had gone quiet (plan `agent-sessions-host-resources.md` §5.3).
+ *
+ * Two files and nothing else. That is a security property, not an
+ * implementation detail: this runner reports to a server, so what it may read
+ * for telemetry is listed here in full — `/proc/loadavg` and `/proc/meminfo`,
+ * both world-readable, neither containing a path, a command line, an
+ * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
+ *
+ * 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
+ * and `protocol.ts` mirrors the API's wire types. Copied rather than imported
+ * on purpose: this package is published to npm on its own and installed by
+ * users who have no DevBridge workspace, so a `@devbridge/shared` import would
+ * make the published tarball unresolvable (see `recipe-schema.ts`).
+ *
+ * CHECKED: `host-load.test.ts` reads the shared file and compares every number
+ * below against it. A threshold edited on one side only would make the runner
+ * send frames the API throws away — or go silent while a card waits for one.
+ */
+/**
+ * How often the runner LOOKS at `/proc`. Not how often it sends.
+ *
+ * Fine enough that a card is never more than half a minute stale, coarse
+ * enough that reading two small files costs nothing measurable.
+ */
+export const HOST_LOAD_SAMPLE_INTERVAL_MS = 30_000;
+/**
+ * The heartbeat: an unchanged machine still reports this often.
+ *
+ * Without it a quiet runner would go silent and the API's key would expire,
+ * turning «nothing is happening» into «we have no idea» on the card. With it,
+ * silence really does mean the runner stopped talking.
+ *
+ * Bound to the API's `HOST_LOAD_TTL_MS` (120 s), and the order is the design:
+ * a heartbeat LONGER than the TTL means a healthy quiet machine shows «no
+ * data» for the gap between them. The first draft had 5 minutes against a
+ * 2-minute TTL — three silent minutes out of every five.
+ */
+export const HOST_LOAD_HEARTBEAT_MS = 60_000;
+/**
+ * How much load1 must move before an otherwise unchanged sample earns a frame.
+ *
+ * Same principle as `publishSlots`: a tick that would repeat what the server
+ * already knows is not sent at all. 0.5 is below the resolution at which a
+ * person reads the number and well above the noise of an idle machine.
+ */
+export const HOST_LOAD_MIN_DELTA_LOAD1 = 0.5;
+/** The same idea for memory, as a fraction — see `hostLoadChangedEnough`. */
+export const HOST_LOAD_MIN_DELTA_MEM_RATIO = 0.05;
+const PROC_DIR = '/proc';
+/** kB in `/proc/meminfo` means kibibytes, and has since the field was added. */
+const MEMINFO_UNIT_BYTES = 1024;
+/**
+ * `MemTotal:       16307180 kB` → `['MemTotal', 16307180 * 1024]`.
+ *
+ * The `kB` suffix is required rather than assumed. A handful of `/proc/meminfo`
+ * rows carry no unit at all (`HugePages_Total`), and multiplying one of those
+ * by 1024 because it happened to be named like the row we wanted would produce
+ * a number that is wrong by three orders of magnitude and looks perfectly
+ * plausible on a card.
+ */
+const MEMINFO_LINE = /^([A-Za-z0-9_()]+):\s+(\d+)\s+kB$/;
+function parseMeminfo(text) {
+    const values = new Map();
+    for (const line of text.split('\n')) {
+        const match = MEMINFO_LINE.exec(line.trim());
+        if (!match)
+            continue;
+        const [, key, amount] = match;
+        if (!key || amount === undefined)
+            continue;
+        const parsed = Number(amount);
+        if (!Number.isFinite(parsed))
+            continue;
+        values.set(key, parsed * MEMINFO_UNIT_BYTES);
+    }
+    return values;
+}
+/** `0.42 0.53 0.60 2/1234 56789` → the three windows, or `null` if it is not that. */
+function parseLoadavg(text) {
+    const parts = text.trim().split(/\s+/);
+    const windows = parts.slice(0, 3).map(Number);
+    if (windows.length < 3)
+        return null;
+    for (const value of windows) {
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+    }
+    const [load1, load5, load15] = windows;
+    return { load1, load5, load15 };
+}
+/**
+ * Measure this machine, or say honestly that we cannot.
+ *
+ * `null` is a first-class answer and every caller must treat it as «send
+ * nothing». There is deliberately no `process.platform` check in front of it:
+ * the absence of the files IS the check, and it is the wider one — it also
+ * covers a Linux container with `/proc` masked or mounted `hidepid`, which a
+ * platform test would sail straight past into an exception. The runner is
+ * Linux-only by its installer, but «only runs on Linux» must never mean
+ * «crashes anywhere else»: this is called from a timer, and an exception here
+ * would take the whole session supervisor with it.
+ */
+export function readHostLoad(sources = {}) {
+    const procDir = sources.procDir ?? PROC_DIR;
+    try {
+        const load = parseLoadavg(fs.readFileSync(path.join(procDir, 'loadavg'), 'utf8'));
+        if (!load)
+            return null;
+        const meminfo = parseMeminfo(fs.readFileSync(path.join(procDir, 'meminfo'), 'utf8'));
+        const memAvailableBytes = meminfo.get('MemAvailable');
+        // No `MemAvailable` means a kernel older than 3.14 (2014). Reporting
+        // `MemFree` in its place would be worse than reporting nothing: on a
+        // healthy machine it is near zero by design, so every such card would
+        // permanently read «out of memory».
+        if (memAvailableBytes === undefined)
+            return null;
+        // Swap is reported only when BOTH halves are there. A kernel built without
+        // swap support has neither, and 0/0 is the truthful answer for it — but
+        // one half without the other is a shape we do not understand, and guessing
+        // `free = 0` for a real swap area would paint that machine as permanently
+        // paging, which is the one verdict this frame exists to make trustworthy.
+        const swapTotalRaw = meminfo.get('SwapTotal');
+        const swapFreeRaw = meminfo.get('SwapFree');
+        const swapKnown = swapTotalRaw !== undefined && swapFreeRaw !== undefined;
+        const swapTotalBytes = swapKnown ? swapTotalRaw : 0;
+        const swapFreeBytes = swapKnown ? swapFreeRaw : 0;
+        const cpuCount = sources.cpuCount ?? os.cpus().length;
+        // A frame the API's schema would reject is worse than no frame, and
+        // `os.cpus()` has been seen returning an empty array in containers. Nor may
+        // it be quietly replaced by 1: load1 is read as a ratio of this number, so
+        // a made-up core count would paint a working eight-core machine red.
+        if (!Number.isInteger(cpuCount) || cpuCount < 1)
+            return null;
+        const at = (sources.now?.() ?? new Date()).toISOString();
+        return {
+            ...load,
+            cpuCount,
+            memAvailableBytes,
+            swapTotalBytes,
+            swapFreeBytes,
+            at,
+        };
+    }
+    catch {
+        // ENOENT on a Mac, EACCES in a locked-down container, EIO on a machine
+        // that is already having a very bad day. All of them mean the same thing
+        // to the caller, and none of them is worth a log line every 30 seconds.
+        return null;
+    }
+}
+/**
+ * Is the heartbeat due, given how long ago the last frame actually went out?
+ *
+ * The second half of the answer is the whole reason this is a function: a
+ * backwards clock step makes «how long ago» NEGATIVE, and a machine whose load
+ * never moves would then say nothing for the entire offset — an hour of silence
+ * on a machine that may be on fire. A clock correction is due, not early.
+ *
+ * The API makes the same allowance for the same step, and has to: it drops
+ * frames older than the one it holds unless the step is larger than a
+ * measurement's lifetime (`HOST_LOAD_TTL_MS`, `runner-gateway.ts`). Half of this
+ * fix on one side of the socket is no fix at all.
+ */
+export function hostLoadHeartbeatDue(sinceLastSentMs, heartbeatMs) {
+    return sinceLastSentMs >= heartbeatMs || sinceLastSentMs < 0;
+}
+/**
+ * Is this sample worth a frame at all? The «a quiet runner says nothing» rule.
+ *
+ * Same shape as `publishSlots`: what the server already knows is not repeated.
+ * The alternative is 2 880 identical frames a day per machine, each one waking
+ * the gateway, a Redis write and every open dashboard socket.
+ *
+ * The memory threshold is 5 % of the machine's TOTAL memory, not 5 % of what
+ * is currently available. Two reasons, and both were the deciding one:
+ *
+ *  - a fraction of `memAvailable` shrinks as the machine fills, so the frames
+ *    would get chattiest exactly when the machine is least able to afford it —
+ *    5 % of the last 200 MB is a 10 MB trigger;
+ *  - `memTotal` is fixed per machine, so «the card moves when a GB moves» reads
+ *    the same on every server instead of meaning something different on each.
+ *
+ * Swap counts too, though the plan names only load and memory. It is one of the
+ * three verdicts behind «overloaded», and it is the only one with no other
+ * trigger: a machine that starts paging with its load and its `MemAvailable`
+ * both flat would otherwise wait up to five minutes for the heartbeat to say
+ * so, and paging is the state whose wall-clock cost is unbounded.
+ */
+export function hostLoadChangedEnough(previous, next, memTotalBytes = os.totalmem()) {
+    // Nothing said yet — the first measurement after a (re)connect is always news.
+    if (!previous)
+        return true;
+    if (Math.abs(next.load1 - previous.load1) >= HOST_LOAD_MIN_DELTA_LOAD1)
+        return true;
+    // A machine that cannot say how much memory it has still gets a working
+    // threshold: the sample's own availability is a poor denominator but a
+    // finite one, and the alternative is dividing by zero forever.
+    const memBase = memTotalBytes > 0 ? memTotalBytes : next.memAvailableBytes;
+    const memDelta = Math.abs(next.memAvailableBytes - previous.memAvailableBytes);
+    if (memBase > 0 && memDelta >= memBase * HOST_LOAD_MIN_DELTA_MEM_RATIO)
+        return true;
+    // Swap size itself can change (`swapon`), and that is news by the same rule.
+    if (next.swapTotalBytes !== previous.swapTotalBytes)
+        return true;
+    if (next.swapTotalBytes > 0) {
+        const swapDelta = Math.abs(next.swapFreeBytes - previous.swapFreeBytes);
+        if (swapDelta >= next.swapTotalBytes * HOST_LOAD_MIN_DELTA_MEM_RATIO)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=host-load.js.map

package/dist/index.js

@@ -17,12 +17,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, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.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 { 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 { mcpConfigDir } from './paths.js';
+import { readMemoryFactsFromSystemd } from './systemd-memory.js';
 const execFileAsync = promisify(execFile);
 /**
  * Identity of this process, and the note the previous one left.
@@ -405,6 +407,55 @@ function runnerCapabilities(apiUrlOverride) {
             // Facts passed on purpose: since 0.39.0 «current» also means the measured
             // ceiling still fits this machine, not just that the version matches.
             limitsCurrent: !limitsOverrideIsOutdated(undefined, undefined, readMemoryFacts()),
+            /**
+             * How the sessions on this machine are actually contained (plan §5.4.3).
+             *
+             * `scope` — a cgroup and a memory ceiling per session; `nice-only` — the
+             * machine cannot do that (cgroup v1, no user bus, a foreign supervisor)
+             * and only the CPU priority applies; `none` — not even that.
+             *
+             * Reported rather than assumed because the containment fails QUIETLY:
+             * `systemd-run` accepts every limit on a cgroup v1 machine and applies
+             * none of them. Without this field «it did not work at the client's» is
+             * something to be guessed at; with it the card can say so.
+             */
+            sessionCage: sessionCage().mode,
+            // Why not `scope`, in one sentence, for the card to show under it.
+            // Empty string when the cage is on.
+            sessionCageReason: sessionCage().reason,
+            /**
+             * The ladder one session lives under (#387), in bytes. Null when there is
+             * no cage — then the only ceiling is the service's, over all of them.
+             *
+             * `High` is the brake: past it the kernel slows the session down instead
+             * of killing. `Max` is the wall, far above — the machine's measured
+             * headroom, where only a runaway ever arrives. Runners up to 0.54.0 sent
+             * `Max` alone, and it was the kill line at 2.5 GiB; a card that sees no
+             * `High` is looking at one of those.
+             */
+            sessionMemoryHighBytes: sessionCage().memoryHighBytes,
+            sessionMemoryMaxBytes: sessionCage().memoryMaxBytes,
+            /** Swap one session may push into while braked. 0 on a machine without swap. */
+            sessionSwapMaxBytes: sessionCage().swapMaxBytes,
+            /**
+             * Whether reaching the wall costs the session ONE process (`OOMPolicy=
+             * continue` on the scope) or is left to that systemd's own default —
+             * older systemds do not take the setting on a scope at all. The card
+             * words the wall by it.
+             */
+            sessionOomContinue: sessionCage().oomContinue,
+            /**
+             * The ceiling over ALL sessions, as systemd has it in force — not as the
+             * drop-in on disk says.
+             *
+             * The live probe proves the personal ceiling and nothing else: a
+             * `MemoryMax` on a scope applies whatever the parent slice holds. So a
+             * machine whose `daemon-reload` never landed reported `scope` and
+             * `limitsCurrent: true` while three sessions of 2.5 GB ran over a slice
+             * at `infinity`, and the card said «Sessions capped»
+             * (QA-2026-09-07 MAJOR-3). Null is that machine, and the card says so.
+             */
+            sessionsMemoryMaxBytes: sessionCage().sessionsSliceMemoryMaxBytes,
         },
         /**
          * Identity of THIS process, so the API can tell a network blink from a
@@ -482,6 +533,11 @@ async function cmdPair(args) {
     }
     const apiUrl = (argValue(args, '--api') ?? 'https://api.bridge4.dev').replace(/\/$/, '');
     const name = argValue(args, '--name') ?? os.hostname();
+    // 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.
+    await initSessionCage();
+    const capabilities = runnerCapabilities(apiUrl);
     const response = await fetch(`${apiUrl}/api/v1/dev/servers/claim`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
@@ -490,7 +546,7 @@ async function cmdPair(args) {
             name,
             runnerVersion: RUNNER_VERSION,
             osInfo: `${os.type()} ${os.release()} ${os.arch()}`.slice(0, 200),
-            capabilities: runnerCapabilities(apiUrl),
+            capabilities,
         }),
     });
     const body = (await response.json().catch(() => null));
@@ -553,8 +609,17 @@ const RESTART_DELAY_MS = 1_500;
  */
 async function repairResourceLimits() {
     try {
-        const facts = readMemoryFacts();
-        if (facts && memoryPolicy(facts).starved) {
+        const { facts, sessionsUsageBytes } = await readMemoryFactsFromSystemd();
+        if (facts === null) {
+            // Neither systemd nor the cgroup files could answer, which on the daemon's
+            // own path means the machine is in a shape this policy cannot reason about
+            // at all. Leaving what is in force in force is the safe half of the
+            // decision; the loud line is the other half, because the alternative is a
+            // machine that silently keeps an old ceiling forever.
+            log.warn('daemon: resource limits unchanged — memory usage could not be measured; retrying in an hour', { recheckMs: LIMITS_RECHECK_MS });
+            return;
+        }
+        if (memoryPolicy(facts).starved) {
             // The only signal the machine's owner will ever get that the neighbours
             // have taken the box: the honest headroom was below the 2 GB floor, so the
             // ceiling we are about to write sits above what is actually free.
@@ -563,12 +628,12 @@ async function repairResourceLimits() {
                 totalMB: Math.round(facts.totalBytes / 1048576),
             });
         }
-        if (!writeLimitsOverride(false, undefined, facts))
+        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes))
             return;
         log.warn('daemon: resource limits drop-in written — reloading systemd', {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
-            ...(facts ? memoryPolicy(facts) : {}),
+            ...memoryPolicy(facts),
         });
         await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
             timeout: 15_000,
@@ -657,33 +722,6 @@ function repairSearchGuard() {
  * check writes nothing when the version matches and the ceiling still fits.
  */
 const LIMITS_RECHECK_MS = 3_600_000;
-/**
- * What the SERVICE's cgroup holds, for the paths that are not the service.
- *
- * `readMemoryFacts()` defaults to reading `/proc/self`, which is right for the
- * daemon and wrong for everything a person types: `doctor --fix` and
- * `install-service` run in the operator's own `session-N.scope`, worth a few MB.
- * Measuring that and calling it «what the runner holds» made the CLI compute a
- * ceiling 34 % away from the daemon's answer on a real host — each path then saw
- * the other as drift and rewrote the file, forever.
- *
- * `MemoryCurrent` is `memory.current`, so it still counts page cache the way
- * `MemAvailable` does. Subtracting it is not worth a second systemd call here:
- * the CLI paths run once, by hand, and erring toward a LOWER ceiling is the safe
- * direction. Returns null when the service is not running or systemd cannot be
- * reached — the caller then has no facts, and writes nothing rather than writing
- * a ceiling with no floor under it.
- */
-async function serviceMemoryCurrent() {
-    try {
-        const { stdout } = await execFileAsync('systemctl', ['--user', 'show', 'devbridge-runner', '-p', 'MemoryCurrent', '--value'], { timeout: 10_000, env: systemdUserEnv() });
-        const value = Number(stdout.trim());
-        return Number.isFinite(value) && value > 0 ? value : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Ticket #119. `ClaudeAdapter.stop()` removes each session's MCP config file,
  * but a kill -9, an OOM or a machine reboot leaves it behind — a live project
@@ -719,7 +757,17 @@ async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
+    // 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();
+    // 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.
+    await initSessionCage();
     repairSearchGuard();
     // A Claude token this runner captured through the sign-in relay. Applied
     // BEFORE any adapter exists, because `scrubbedEnv()` copies it out of this
@@ -892,8 +940,29 @@ async function cmdInstallService() {
     // `buildLimitsOverride`. Forced here: a fresh install must have it even if a
     // file from an older runner is already sitting there. Facts come from the
     // service rather than from `/proc/self`, which here is the installing shell.
-    writeLimitsOverride(true, undefined, readMemoryFacts(await serviceMemoryCurrent()));
-    print(`Wrote ${limitsOverridePath()}`);
+    // The slice reading goes with them: re-installing over a machine that is
+    // running sessions right now must not write a ceiling under them.
+    //
+    // Unmeasurable is a WARNING here, not a refusal, and the order above is why:
+    // the unit is already on disk, so the machine gets a runner either way. The
+    // states that produce «unmeasurable» — a failed service, a service mid
+    // auto-restart, an unhappy user bus — are exactly the states someone runs
+    // `install.sh --repair` from, and a repair that installs nothing because it
+    // could not size a ceiling is a repair that does not repair.
+    const installMem = await readMemoryFactsFromSystemd();
+    if (installMem.facts === null) {
+        print('warning: could not measure this machine — resource limits were left as they are. ' +
+            'Nothing was removed; the daemon re-measures hourly, or run `devbridge-runner doctor --fix`.');
+    }
+    else {
+        writeLimitsOverride(true, undefined, installMem.facts, installMem.sessionsUsageBytes);
+        print(`Wrote ${limitsOverridePath()}`);
+        // Two more files since 0.54.0: the sessions no longer live inside the
+        // service's cgroup, so the ceiling over all of them and the CPU share that
+        // keeps the daemon ahead of them belong to the slices (`session-cage.ts`).
+        print(`Wrote ${sessionsSliceOverridePath()}`);
+        print(`Wrote ${devbridgeSliceOverridePath()}`);
+    }
     // Привратник шаблонов поиска — та же логика, что и у политики ресурсов:
     // свежая установка должна получить его сразу. Пишем в ЧУЖОЙ файл настроек,
     // поэтому молча пропускаем, если тронуть его нельзя (`claude-settings.ts`).
@@ -1330,7 +1399,7 @@ async function cmdDoctor(args) {
     print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
     print('');
     print('Service limits');
-    const memFacts = readMemoryFacts(await serviceMemoryCurrent());
+    const { facts: memFacts, sessionsUsageBytes: memSessionsUsage } = await readMemoryFactsFromSystemd();
     const outdated = limitsOverrideIsOutdated(undefined, undefined, memFacts);
     print(`  drop-in         ${limitsOverridePath()}`);
     print(`  version         ${outdated ? `MISSING or OLD (want ${LIMITS_VERSION})` : LIMITS_VERSION}`);
@@ -1346,6 +1415,65 @@ async function cmdDoctor(args) {
             ? `${mb(memFacts.availableBytes)} available + ${mb(memFacts.ownUsageBytes)} ours`
             : `55% of ${mb(memFacts.totalBytes)} — still booting, remeasured on the next start`}`);
     }
+    else {
+        // Не молча: без фактов о машине политика не считается вовсе, и `--fix`
+        // тогда НИЧЕГО не пишет — ни на сервис, ни на слайс. Строка про слайс
+        // остаётся полезной сама по себе: она говорит, что стоит на кону, если
+        // измерение так и не появится.
+        print("  memory ceiling  not computed — this machine's usage is unreadable");
+        print('                  --fix leaves every limits file exactly as it is');
+        print(`  sessions slice  ${memSessionsUsage === null
+            ? 'unreadable too'
+            : memSessionsUsage === 0
+                ? 'holds nothing right now'
+                : `holds ${Math.round(memSessionsUsage / 1024 / 1024)} MB — a ceiling under that would kill it`}`);
+    }
+    // The cage, and the reason it matters more than the numbers above it: those
+    // are the ceiling over the WHOLE service, and a session that has left the
+    // service's cgroup is not under them any more. If this section says anything
+    // but `scope`, the only containment on this machine is the CPU priority.
+    const cage = await initSessionCage();
+    print('');
+    print('Session cage (a cgroup per session)');
+    print(`  mode            ${cage.mode}`);
+    if (cage.reason)
+        print(`  why            ${cage.reason}`);
+    print(`  slice           ${SESSIONS_SLICE} (under ${DEVBRIDGE_SLICE}, CPUWeight=${SESSION_CPU_WEIGHT})`);
+    print(`  drop-ins        ${sessionsSliceOverridePath()}`);
+    print(`                  ${devbridgeSliceOverridePath()}`);
+    if (cage.mode === 'scope') {
+        const mb = (bytes) => bytes === null ? 'infinity' : `${Math.round(bytes / 1024 / 1024)} MB`;
+        print(`  per session     MemoryHigh ${mb(cage.memoryHighBytes)} (brake: slows, never kills), MemoryMax ${mb(cage.memoryMaxBytes)} (wall), MemorySwapMax ${mb(cage.swapMaxBytes)}, TasksMax ${SESSION_TASKS_MAX}`);
+        print(`  at the wall     ${cage.oomContinue
+            ? 'OOMPolicy=continue — the kernel kills the hungriest process, the session stays up'
+            : 'this systemd does not take OOMPolicy on a scope (it is newer than the rest of the cage), so what happens at the wall is its own default — on systemd 253+ that is «stop the whole session»'}`);
+        // What systemd has IN FORCE on the slice, beside the paths of the files
+        // that were supposed to put it there. «В файле 7680M, действует 6.0G» is the
+        // lesson of §5.5, and the drop-in of a slice can fail to land in exactly the
+        // same way: a reload that never happened leaves every session personally
+        // capped and collectively unlimited (QA-2026-09-07 MAJOR-3).
+        print(`  all sessions    MemoryMax ${mb(cage.sessionsSliceMemoryMaxBytes)} in force on ${SESSIONS_SLICE}`);
+        if (cage.sessionsSliceMemoryMaxBytes === null) {
+            print('                  NOT CAPPED — the drop-in above has not been applied.');
+            print(`                  Apply with: ${systemctlHint('daemon-reload')}`);
+        }
+        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (the per-session brake is half of the containing ceiling, capped at 2.5 GiB; the wall IS the containing ceiling)`);
+        print(`  expand-env flag ${cage.expandEnvironmentFlag ? 'passed (systemd ≥ 254)' : 'not passed — this systemd does not know it, and --scope does not expand anyway'}`);
+    }
+    else {
+        print('  per session     none — only the CPU priority from `process-priority.ts` applies');
+    }
+    const scopes = await listSessionScopes();
+    if (scopes.length === 0) {
+        print('  live scopes     none');
+    }
+    else {
+        print(`  live scopes     ${scopes.length}`);
+        for (const scope of scopes) {
+            const mb = (bytes) => bytes === null ? '?' : `${Math.round(bytes / 1024 / 1024)} MB`;
+            print(`    ${scope.unit}  ${scope.activeState ?? '?'}  ${mb(scope.memoryCurrentBytes)} of ${mb(scope.memoryMaxBytes)}  tasks ${scope.tasksCurrent ?? '?'}${scope.result && scope.result !== 'success' ? `  ${scope.result}` : ''}`);
+        }
+    }
     let effective;
     try {
         const { stdout } = await execFileAsync('systemctl', [
@@ -1372,6 +1500,19 @@ async function cmdDoctor(args) {
     print('Effective (systemd)');
     for (const line of effective)
         print(`  ${line}`);
+    // «В файле 7680M, действует 6.0G». Ровно это и получалось, пока самообновление
+    // звало `systemctl --user daemon-reload` без `XDG_RUNTIME_DIR`: systemd отвечал
+    // «Failed to connect to bus» и выходил с кодом 0, drop-in переписывался, а
+    // systemd продолжал жить по старому юниту (план §5.5). Причину починили, но
+    // расхождение может прийти и иначе — правкой юнита руками, оборванным
+    // обновлением, — и без этой строки строки выше выглядят как то, что
+    // действует, хотя это уже не так.
+    if ((await systemctlProperty('NeedDaemonReload')) === 'yes') {
+        print('');
+        print('STALE — systemd has NOT re-read the unit since it changed on disk,');
+        print('  so the numbers above are the OLD ones, not what the drop-in says.');
+        print(`  Apply with: ${systemctlHint('daemon-reload')}`);
+    }
     // Привратник шаблонов поиска. Печатается всегда, в том числе когда он ВЫКЛЮЧЕН
     // в коде: «стоит, хотя выключен» — это и есть та машина, которую пропустило
     // обновление, и увидеть её больше неоткуда.
@@ -1438,10 +1579,24 @@ async function cmdDoctor(args) {
             process.exit(1);
         return;
     }
-    const fixFacts = readMemoryFacts(await serviceMemoryCurrent());
-    writeLimitsOverride(true, undefined, fixFacts);
+    const { facts: fixFacts, sessionsUsageBytes: fixSessionsUsage } = await readMemoryFactsFromSystemd();
     print('');
-    print(`Wrote ${limitsOverridePath()}`);
+    // Unmeasurable leaves the files exactly as they are and says so — the one
+    // thing this must never do is replace a ceiling in force with a guess, or
+    // rewrite the file without its `MemoryMax` line, which RESETS the ceiling.
+    // The rest of the repair still runs: `doctor --fix` is also the search guard,
+    // the unit file and the daemon-reload, and a machine that cannot be measured
+    // this second still needs those. The non-zero exit at the end is what keeps
+    // «could not do the main thing» from reading as success to automation.
+    if (fixFacts === null) {
+        print('Resource limits: LEFT UNCHANGED — this machine could not be measured.');
+        print('  Nothing was removed. Re-run once `systemctl --user` answers again.');
+    }
+    else {
+        // Keep the service and the sessions under the same measured policy.
+        writeLimitsOverride(true, undefined, fixFacts, fixSessionsUsage);
+        print(`Wrote ${limitsOverridePath()}`);
+    }
     const guardOutcome = applySearchGuard(print);
     if (guardOutcome === 'installed') {
         print(`Installed search-pattern guard into ${claudeSettingsPath(searchGuardHome())}`);
@@ -1458,7 +1613,19 @@ async function cmdDoctor(args) {
         const applied = memoryPolicy(fixFacts);
         if (applied.maxBytes > honest.maxBytes) {
             const mb = (b) => Math.round(b / 1024 / 1024);
-            print(`note: ceiling raised to ${mb(applied.maxBytes)} MB — the service already holds ${mb(fixFacts.ownUsageBytes)} MB, and ${mb(honest.maxBytes)} MB would kill it on reload. Re-run when idle.`);
+            // Which cgroup forced the ceiling up, not just «the service»: on a loaded
+            // machine it is the sessions slice, and naming the service there sent the
+            // reader looking at a daemon holding 400 MB (QA-2026-09-07 BLOCKER-1).
+            // The SAME numbers the floor is computed from (`managedUsageFloorBytes`),
+            // not the headroom ones: where the split is unknown those two differ, and
+            // a note sourced from the wrong pair names the wrong cgroup and a smaller
+            // number than the one that actually forced the ceiling up.
+            const ownFloor = fixFacts.ownFloorBytes ?? fixFacts.ownUsageBytes;
+            const sessionsFloor = fixFacts.sessionsFloorBytes ?? fixFacts.sessionsUsageBytes;
+            const holder = sessionsFloor > ownFloor
+                ? `the sessions on this machine already hold ${mb(sessionsFloor)} MB`
+                : `the service already holds ${mb(ownFloor)} MB`;
+            print(`note: ceiling raised to ${mb(applied.maxBytes)} MB — ${holder}, and ${mb(honest.maxBytes)} MB would kill it on reload. Re-run when idle.`);
         }
     }
     try {
@@ -1469,6 +1636,10 @@ async function cmdDoctor(args) {
     catch (error) {
         fail(`daemon-reload failed: ${String(error instanceof Error ? error.message : error)}`);
     }
+    // Everything else was repaired; the limits were not. Said with the exit code
+    // as well as with the line above, because `doctor --fix` is run by scripts.
+    if (fixFacts === null)
+        process.exit(1);
 }
 // ─── set-token ───────────────────────────────────────────────────────
 function cmdSetToken(args) {

package/dist/process-priority.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Everything an agent starts runs at a lower CPU priority than the daemon that
+ * supervises it.
+ *
+ * The failure this exists for is the runner starving itself with its own
+ * children (16.08): a session's build saturated the box, the daemon lost four
+ * heartbeats in a row, the server went Offline and every session on that
+ * machine answered 504 — while the work it was doing was fine. The daemon's job
+ * during a heavy turn is a few milliseconds of socket traffic; it should not
+ * have to queue behind a `tsc` it launched itself.
+ *
+ * **What this gives.** Inside the service's own cgroup the daemon (nice 0) gets
+ * the processor before the agents (nice 10); neighbouring sessions, all at 10,
+ * still share it evenly between themselves. Children inherit the nice value at
+ * fork, so a `vitest` the agent starts through Bash — several levels down from
+ * the process we renice — is covered without us knowing about it.
+ *
+ * Inheritance is why every call site is the line straight after its `spawn`:
+ * measured here, a grandchild forked AFTER the call comes up at 10 and one
+ * forked in the microseconds before it stays at 0. An agent needs hundreds of
+ * milliseconds to boot before it forks anything, so that window is empty in
+ * practice — but it is a window, and it only grows if the call drifts down the
+ * function.
+ *
+ * **What it does NOT give.** Against processes OUTSIDE the cgroup (production
+ * in `system.slice`) it does nothing at all: across cgroups the split is
+ * decided by `cpu.weight`, and nice only orders tasks within one. It does not
+ * touch memory, which is the mechanism behind three of the four incidents on
+ * other people's machines. This is the approach to stage 2 (a scope per session
+ * with a memory ceiling) and the fallback for it on cgroup v1, where stage 2
+ * cannot work — not a replacement for it.
+ *
+ * Priority is a convenience, not correctness: nothing here throws. A session
+ * that runs at the wrong priority is a slower machine; a session that fails to
+ * start because renicing failed is a broken product.
+ */
+/**
+ * The nice value every process the runner spawns for an agent gets.
+ *
+ * 10 rather than 19: the point is to lose to the daemon and to anything the
+ * owner is doing by hand, not to be scheduled last behind every background cron
+ * on the box. The scheduler's weight table gives nice 10 about a ninth of the
+ * share of nice 0 under contention (1024 → 110), which is all the room the
+ * heartbeat needs — 19 would buy an order of magnitude more and cost a session
+ * its throughput whenever anything else on the machine woke up.
+ */
+export declare const NICE = 10;
+/**
+ * Push one spawned process down to {@link NICE}. Never throws.
+ *
+ * Takes `number | undefined` because that is exactly what `child.pid` is: a
+ * spawn that failed has none, and the caller should not have to ask.
+ */
+export declare function lowerPriority(pid: number | undefined): void;
+//# sourceMappingURL=process-priority.d.ts.map