@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/service-unit.js

@@ -129,15 +129,69 @@ export function buildUnit(execStart, nodeBinary = process.execPath) {
  * which is the only way to fix the servers that already have the bad numbers
  * baked in — and it never overwrites a unit the operator edited by hand.
  */
-export const LIMITS_VERSION = 3;
+export const LIMITS_VERSION = 5;
 const LIMITS_MARKER = '# devbridge-limits-version:';
 /** `zz-` so it sorts last: an operator's own drop-in should still win. */
 const LIMITS_FILE = 'zz-devbridge-limits.conf';
+/**
+ * Where the agent sessions live once they have a cage of their own.
+ *
+ * A `systemd-run --scope` is a SIBLING of the service, not a child of it: a
+ * session started that way leaves the service's `MemoryMax`, `CPUQuota`,
+ * `OOMPolicy=continue` and `KillMode=control-group` behind entirely. So the
+ * collective ceiling has to move with them, onto the slice — otherwise the cage
+ * per session would arrive at the price of the ceiling over all of them.
+ *
+ * The dash is systemd's hierarchy separator: `devbridge-sessions.slice` is a
+ * child of `devbridge.slice`, which is where the CPU share for everything the
+ * agents run is set.
+ */
+export const SESSIONS_SLICE = 'devbridge-sessions.slice';
+export const DEVBRIDGE_SLICE = 'devbridge.slice';
+/**
+ * Half the default weight, on `devbridge.slice` and on every session scope.
+ *
+ * Lives here rather than in `session-cage.ts` because the number has to be the
+ * SAME in both places — the slice sets the share of the agents against the
+ * daemon, the scope sets one session's share against another's — and a
+ * duplicated literal is how those two drift apart. Why 50 and what it replaces:
+ * `buildDevbridgeSliceOverride` below.
+ */
+export const SESSION_CPU_WEIGHT = 50;
 export function limitsOverridePath(home = systemdUserHome()) {
     return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service.d`, LIMITS_FILE);
 }
+/**
+ * Drop-in path for a slice unit that has no unit FILE at all.
+ *
+ * systemd synthesises `devbridge-sessions.slice` the first time something asks
+ * for it, and it reads drop-ins for the synthesised unit exactly as for a real
+ * one — verified on this machine: a `[Slice] MemoryMax=64M` drop-in with no
+ * fragment gave `MemoryMax=67108864` on the live slice. So there is no unit file
+ * to write and no unit file to keep in sync; the policy is the drop-in.
+ */
+export function sliceOverridePath(slice, home = systemdUserHome()) {
+    return path.join(home, '.config', 'systemd', 'user', `${slice}.d`, LIMITS_FILE);
+}
+export function sessionsSliceOverridePath(home = systemdUserHome()) {
+    return sliceOverridePath(SESSIONS_SLICE, home);
+}
+export function devbridgeSliceOverridePath(home = systemdUserHome()) {
+    return sliceOverridePath(DEVBRIDGE_SLICE, home);
+}
 const MIB = 1024 * 1024;
 const GIB = 1024 * MIB;
+/**
+ * How much of the machine's swap ALL sessions together may use (#387).
+ *
+ * Half, not all: swap belongs to the machine (the spike's 200 MB cage drained
+ * the host's 2 GB and the box hung), so the other half stays with the neighbours
+ * and the kernel. Each session gets half of this again (`sessionSwapMaxBytes`).
+ * On the 2 GB swap this machine has today that is 512 MB per session — enough
+ * for a build's overshoot, not for a runaway; the owner's note on #387 is that
+ * the swap itself has to grow for the brake to have real room.
+ */
+export const SESSIONS_SWAP_SHARE = 0.5;
 /**
  * How long after boot `MemAvailable` starts telling the truth.
  *
@@ -149,7 +203,7 @@ const GIB = 1024 * MIB;
  */
 export const BOOT_SETTLE_SEC = 600;
 /**
- * The ceiling is never written BELOW what the cgroup already holds.
+ * The ceiling is never written BELOW what the cgroups already hold.
  *
  * Until 0.39.0 this policy only ever REMOVED a limit, so applying it to a running
  * service was free. Now it sets one, and systemd applies `memory.max` to a LIVE
@@ -158,11 +212,29 @@ export const BOOT_SETTLE_SEC = 600;
  * running yet — but `doctor --fix` on a busy machine would otherwise take out
  * somebody's session as a side effect of running a diagnostic.
  *
+ * `max` of the two holders, not the sum: the SAME number is written to the
+ * service and to `devbridge-sessions.slice`, so it has to clear whichever of the
+ * two is fuller — each cgroup is measured against it on its own.
+ *
  * The cost is that a machine fixed WHILE a runaway is in progress writes a ceiling
  * above that runaway, which protects nothing. It resolves itself: the next daemon
- * start measures an idle cgroup, and the drift check rewrites the inflated number.
+ * start measures idle cgroups, and the drift check rewrites the inflated number.
  */
 const CEILING_HEADROOM_OVER_CURRENT = 1.25;
+/** What the ceiling about to be written has to clear, in either cgroup. */
+export function managedUsageFloorBytes(facts) {
+    return (Math.max(facts.ownFloorBytes ?? facts.ownUsageBytes, facts.sessionsFloorBytes ?? facts.sessionsUsageBytes) * CEILING_HEADROOM_OVER_CURRENT);
+}
+/**
+ * Below this a dev server cannot run one agent, so the policy never goes under it.
+ *
+ * Named rather than repeated because it is now used twice: as the lower clamp of
+ * the measured ceiling, and as the lower clamp of the ceiling written to the
+ * sessions slice on a machine the policy could not measure at all — where the
+ * only other number available is what that slice happens to hold this second,
+ * and `1.25 × 100 MB` is a cage, not a ceiling.
+ */
+const CEILING_FLOOR_BYTES = 2 * GIB;
 /**
  * The two numbers, and the incident that decides them.
  *
@@ -183,8 +255,10 @@ const CEILING_HEADROOM_OVER_CURRENT = 1.25;
  *
  * So the percentage has to be of what the machine can SPARE, not of what it has:
  *
- *   headroom = MemAvailable + our own usage   (ours is added back, or every
- *              rewrite would walk the ceiling down by what we already hold)
+ *   headroom = MemAvailable + everything WE hold   (ours is added back, or every
+ *              rewrite would walk the ceiling down by what we already hold —
+ *              and since 0.54.0 «ours» is the daemon's cgroup PLUS the sessions
+ *              slice, because the agents moved out of the daemon's one)
  *   MemoryMax  = headroom − reserve
  *   MemoryHigh = 80 % of MemoryMax            (reclaim and throttle first, kill last)
  *
@@ -203,11 +277,18 @@ const CEILING_HEADROOM_OVER_CURRENT = 1.25;
  *  - cap 85 % of total: on an idle dedicated box `MemAvailable` is nearly the whole
  *    machine, and a ceiling of «everything» is the bug this function exists to fix.
  */
-export function memoryPolicy(facts, minCeilingBytes = facts.ownUsageBytes * CEILING_HEADROOM_OVER_CURRENT) {
-    const { totalBytes, availableBytes, ownUsageBytes, uptimeSec } = facts;
+export function memoryPolicy(facts, minCeilingBytes = managedUsageFloorBytes(facts)) {
+    const { totalBytes, availableBytes, ownUsageBytes, sessionsUsageBytes, uptimeSec } = facts;
+    const swapMaxBytes = Math.floor(Math.max(0, facts.swapTotalBytes ?? 0) * SESSIONS_SWAP_SHARE);
     const withFloor = (maxBytes, measured, starved = false) => {
         const ceiling = Math.floor(Math.max(maxBytes, minCeilingBytes));
-        return { maxBytes: ceiling, highBytes: Math.floor(ceiling * 0.8), measured, starved };
+        return {
+            maxBytes: ceiling,
+            highBytes: Math.floor(ceiling * 0.8),
+            swapMaxBytes,
+            measured,
+            starved,
+        };
     };
     // Still booting: the neighbours have not claimed their memory yet, so measuring
     // now would hand back almost the whole machine. Take a fraction of TOTAL
@@ -227,13 +308,17 @@ export function memoryPolicy(facts, minCeilingBytes = facts.ownUsageBytes * CEIL
     // while the cgroup sits at its ceiling. Proportional on a big machine, absolute
     // on a small one, because 15 % of 4 GB is not enough to stay reachable.
     const reserve = Math.max(1.5 * GIB, totalBytes * 0.15);
-    const headroom = availableBytes + ownUsageBytes;
+    // Both cgroups are added back, and for the same reason ours always was: what
+    // they hold is already OUT of `MemAvailable`, so leaving the sessions out
+    // makes a loaded machine look starved and walks the ceiling down under the
+    // very sessions it covers.
+    const headroom = availableBytes + ownUsageBytes + sessionsUsageBytes;
     const cap = totalBytes * 0.85;
     // `min` with the cap, not a bare 2 GiB: below ~2.4 GB of RAM the floor would be
     // ABOVE the cap and `clamp` would silently return the cap anyway — with the
     // reserve ignored and the «2 GB or nothing» promise quietly broken. Saying it
     // here makes the tiny-machine answer deliberate instead of accidental.
-    const floor = Math.min(2 * GIB, cap);
+    const floor = Math.min(CEILING_FLOOR_BYTES, cap);
     const wanted = headroom - reserve;
     return withFloor(clamp(wanted, floor, cap), true, wanted < floor);
 }
@@ -244,8 +329,8 @@ function clamp(value, low, high) {
 function asMiB(bytes) {
     return `${Math.max(1, Math.floor(bytes / MIB))}M`;
 }
-/** `MemTotal`/`MemAvailable` in bytes, or null where there is no `/proc`. */
-function readMemInfo() {
+/** One `kB` field of `/proc/meminfo`, in bytes; null when absent or unreadable. */
+function memInfoField(name) {
     let text;
     try {
         text = fs.readFileSync('/proc/meminfo', 'utf8');
@@ -253,13 +338,20 @@ function readMemInfo() {
     catch {
         return null;
     }
-    const field = (name) => {
-        const match = new RegExp(`^${name}:\\s+(\\d+) kB$`, 'm').exec(text);
-        return match?.[1] ? Number(match[1]) * 1024 : null;
-    };
-    const totalBytes = field('MemTotal');
-    const availableBytes = field('MemAvailable');
-    return totalBytes && availableBytes ? { totalBytes, availableBytes } : null;
+    const match = new RegExp(`^${name}:\\s+(\\d+) kB$`, 'm').exec(text);
+    return match?.[1] ? Number(match[1]) * 1024 : null;
+}
+/** `MemTotal`/`MemAvailable`/`SwapTotal` in bytes, or null where there is no `/proc`. */
+function readMemInfo() {
+    const totalBytes = memInfoField('MemTotal');
+    const availableBytes = memInfoField('MemAvailable');
+    // 0 is a real answer here (no swap), unlike the two above.
+    const swapTotalBytes = memInfoField('SwapTotal') ?? 0;
+    return totalBytes && availableBytes ? { totalBytes, availableBytes, swapTotalBytes } : null;
+}
+/** `SwapTotal` of this machine, or null where `/proc/meminfo` will not say. */
+export function readSwapTotalBytes() {
+    return memInfoField('SwapTotal');
 }
 /**
  * What our own cgroup currently holds.
@@ -271,8 +363,7 @@ function readMemInfo() {
  * already using. Returns 0 on cgroup v1 or in a container without the file, which
  * is the safe direction: a slightly lower ceiling, never a higher one.
  */
-function readOwnCgroupUsage() {
-    let cgroup;
+export function readSelfCgroup() {
     try {
         const line = fs
             .readFileSync('/proc/self/cgroup', 'utf8')
@@ -280,11 +371,16 @@ function readOwnCgroupUsage() {
             .find((l) => l.startsWith('0::'));
         if (!line)
             return null; // cgroup v1 — no v2 path to read
-        cgroup = line.slice('0::'.length).trim();
+        return line.slice('0::'.length).trim();
     }
     catch {
         return null;
     }
+}
+export function readOwnCgroupMemory() {
+    const cgroup = readSelfCgroup();
+    if (cgroup === null)
+        return null;
     // `/proc/self` is the CALLER. For the daemon that is the service, and this is
     // the hot path. For `doctor --fix` or `install-service` typed over ssh it is a
     // `session-N.scope` holding a few MB — measuring that and calling it «what the
@@ -294,32 +390,120 @@ function readOwnCgroupUsage() {
     // know» and let the caller supply the number.
     if (!cgroup.endsWith(`/${SERVICE_NAME}.service`))
         return null;
-    return readCgroupUnreclaimable(path.join('/sys/fs/cgroup', cgroup));
+    return readCgroupMemory(path.join('/sys/fs/cgroup', cgroup));
 }
-/**
- * What the cgroup holds that `MemAvailable` has NOT already counted.
- *
- * `memory.current` is `anon + file + kernel`, and `file` is page cache — which
- * `MemAvailable` already lists as reclaimable. Adding the whole of
- * `memory.current` back to `MemAvailable` therefore counts our page cache twice
- * and inflates the ceiling by exactly that much: measured at +19 % on this host
- * (1.1 GB of cache in a 2.3 GB cgroup), and the cache is largest during builds —
- * precisely when memory is tightest. Subtracting `file` keeps the part we really
- * do hold and cannot give back on demand.
- */
-export function readCgroupUnreclaimable(dir) {
+export function readCgroupMemory(dir) {
     try {
-        const current = Number(fs.readFileSync(path.join(dir, 'memory.current'), 'utf8').trim());
-        if (!Number.isFinite(current))
+        const raw = fs.readFileSync(path.join(dir, 'memory.current'), 'utf8').trim();
+        const current = Number(raw);
+        if (!/^\d+$/.test(raw) || !Number.isSafeInteger(current))
             return null;
-        const file = /^file (\d+)$/m.exec(fs.readFileSync(path.join(dir, 'memory.stat'), 'utf8'));
-        const cache = file?.[1] ? Number(file[1]) : 0;
-        return Math.max(0, current - cache);
+        const stat = fs.readFileSync(path.join(dir, 'memory.stat'), 'utf8');
+        const file = /^file (\d+)$/m.exec(stat);
+        // `file` COUNTS shmem, and shmem is the one page cache the kernel cannot
+        // drop under `MemorySwapMax=0`: there is nowhere to put it. Taking it back
+        // out is the difference between «cache we can give back» and «cache that
+        // has to be killed for», and only the first belongs on the reclaimable side.
+        const shmem = /^shmem (\d+)$/m.exec(stat);
+        const cache = Math.max(0, (file?.[1] ? Number(file[1]) : 0) - (shmem?.[1] ? Number(shmem[1]) : 0));
+        return { currentBytes: current, unreclaimableBytes: Math.max(0, current - cache) };
     }
     catch {
         return null;
     }
 }
+export function readCgroupUnreclaimable(dir) {
+    return readCgroupMemory(dir)?.unreclaimableBytes ?? null;
+}
+/**
+ * Where a slice unit's cgroup lives, worked out from the cgroup we are in.
+ *
+ * systemd's dash rule spells the hierarchy out: `devbridge-sessions.slice` sits
+ * inside `devbridge.slice`, which sits directly under the user manager's own
+ * cgroup — verified on this host with a throwaway `--slice=dbqa-probe-sub.slice`,
+ * which landed in `user@0.service/dbqa.slice/dbqa-probe.slice/dbqa-probe-sub.slice`.
+ *
+ * The user manager's cgroup is found rather than assembled: the runner runs as
+ * root and as a dedicated user (`user@0.service`, `user@1001.service`), and the
+ * same guess-the-path mistake that `readOwnCgroupUsage` avoids would silently
+ * return 0 here — which is exactly the blindness BLOCKER-1 was.
+ *
+ * Null means «there is no user manager above us», and then there is no
+ * `--user` slice for the sessions to be in either.
+ */
+export function sliceCgroupPath(selfCgroup, slice) {
+    const segments = selfCgroup.split('/').filter(Boolean);
+    const managerAt = segments.findIndex((segment) => /^user@\d+\.service$/.test(segment));
+    if (managerAt < 0)
+        return null;
+    const name = slice.replace(/\.slice$/, '');
+    const parts = name.split('-');
+    // `a-b-c.slice` → `a.slice/a-b.slice/a-b-c.slice`, systemd's own nesting.
+    const chain = parts.map((_, index) => `${parts.slice(0, index + 1).join('-')}.slice`);
+    return path.join('/sys/fs/cgroup', ...segments.slice(0, managerAt + 1), ...chain);
+}
+/**
+ * What the agents are holding right now, outside the daemon's own cgroup — or
+ * null where this machine cannot say.
+ *
+ * Read from the filesystem rather than through `systemctl show`, because this is
+ * the hourly path inside the daemon and it has to stay synchronous — the same
+ * reason `readOwnCgroupUsage` reads `/proc`. Callers that are not the daemon can
+ * pass the number in; see {@link readMemoryFacts}.
+ *
+ * A missing directory is 0 and not «unknown»: systemd removes the cgroup of an
+ * empty slice, so «no directory» means «no session is holding anything». The two
+ * are kept apart because they now lead to opposite decisions — 0 lets a blind
+ * ceiling be written onto the slice, «unknown» forbids it (see
+ * {@link buildSessionsSliceOverride}).
+ */
+export function readSessionsSliceMemory() {
+    const self = readSelfCgroup();
+    if (self === null)
+        return null; // cgroup v1, or a container without the file
+    const dir = sliceCgroupPath(self, SESSIONS_SLICE);
+    if (dir === null)
+        return null; // no user manager above us — no `--user` slice
+    if (!fs.existsSync(dir))
+        return { currentBytes: 0, unreclaimableBytes: 0 };
+    return readCgroupMemory(dir);
+}
+/**
+ * The same tri-state, read out of `systemctl show` instead of the filesystem —
+ * the authoritative source for the paths a person types (`doctor --fix`,
+ * `install-service`), which run outside the daemon's cgroup.
+ *
+ * `[not set]` is the ambiguous answer and the reason `activeState` is asked for
+ * as well: systemd prints it for a slice that has no cgroup (nothing has ever
+ * run there) AND for one whose accounting is off, and those two must not lead to
+ * the same decision. Only «systemd loaded the unit and it is not even active» is
+ * a positive statement that nothing can be killed by what we write; everything
+ * else is «unknown», which writes no ceiling at all.
+ *
+ * A failed `systemctl` call is null on both counts — including the 10-second
+ * timeout, which fires exactly on the overloaded machine this policy protects.
+ */
+export function parseSliceUsage(memoryCurrent, activeState) {
+    const raw = memoryCurrent?.trim() ?? '';
+    const value = Number(raw);
+    if (raw.length > 0 && Number.isFinite(value) && value >= 0)
+        return value;
+    return activeState?.trim() === 'inactive' ? 0 : null;
+}
+/**
+ * The slice's number for the callers that take one, and «unknown» kept apart
+ * from «empty»: an unreadable live slice must never be replaced with zero.
+ *
+ * The FLOOR reading, not the headroom one — this feeds a ceiling that has to
+ * clear what the slice holds, and where the split is unknown the whole reading
+ * has to be assumed unreclaimable.
+ */
+export function readSessionsSliceUsageOrNull() {
+    const memory = readSessionsSliceMemory();
+    if (memory === null)
+        return null;
+    return memory.unreclaimableBytes ?? memory.currentBytes;
+}
 function readUptimeSec() {
     try {
         return Number(fs.readFileSync('/proc/uptime', 'utf8').split(/\s+/)[0]) || 0;
@@ -331,17 +515,37 @@ function readUptimeSec() {
 /**
  * Everything `memoryPolicy` needs, straight off this machine.
  *
- * `ownUsageBytes` is passed in by callers that are not the daemon — `doctor` and
- * `install-service` run in the operator's own cgroup and cannot read the
- * service's usage from `/proc/self`. Returns null when the service's usage is
- * unknowable, because guessing 0 there is the one dangerous direction: it removes
- * the floor that stops a live session from being killed on `daemon-reload`.
+ * Both readings are passed in by callers that are not the daemon — `doctor` and
+ * `install-service` run in the operator's own `session-N.scope` and cannot read
+ * the service's usage from `/proc/self`; they ask systemd instead
+ * (`readMemoryFactsFromSystemd`). Returns null when either cgroup is unknowable,
+ * because guessing there is the one dangerous direction: it removes the floor
+ * that stops a live session from being killed on the next `daemon-reload`.
+ *
+ * The default reads both from the filesystem, which is right for the daemon:
+ * its own cgroup through `/proc/self`, and the sessions slice through the user
+ * manager's cgroup, which sits above the daemon and the CLI alike.
  */
-export function readMemoryFacts(ownUsageBytes = readOwnCgroupUsage()) {
+export function readMemoryFacts(own = readOwnCgroupMemory(), sessions = readSessionsSliceMemory()) {
     const info = readMemInfo();
-    if (!info || ownUsageBytes === null)
+    // Either cgroup being unreadable is the whole answer: the ceiling computed
+    // here is written to BOTH units, so a number that clears one and not the
+    // other is the collective kill of QA-2026-09-07 BLOCKER-1 with extra steps.
+    if (!info || own === null || sessions === null)
         return null;
-    return { ...info, ownUsageBytes, uptimeSec: readUptimeSec() };
+    return {
+        ...info,
+        // Headroom gets only what `MemAvailable` has not already counted, and an
+        // unknown split contributes nothing: guessing high here would raise the
+        // ceiling on a machine we cannot see.
+        ownUsageBytes: own.unreclaimableBytes ?? 0,
+        sessionsUsageBytes: sessions.unreclaimableBytes ?? 0,
+        // The floor errs the other way, and has to: an unknown split may be all
+        // anonymous memory, and a ceiling written under it kills.
+        ownFloorBytes: own.unreclaimableBytes ?? own.currentBytes,
+        sessionsFloorBytes: sessions.unreclaimableBytes ?? sessions.currentBytes,
+        uptimeSec: readUptimeSec(),
+    };
 }
 /**
  * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
@@ -416,6 +620,135 @@ export function buildLimitsOverride(cpuCount = os.cpus().length, facts = readMem
         'TasksMax=8192',
     ].join('\n') + '\n');
 }
+const MANAGED_HEADER = [
+    `${LIMITS_MARKER} ${LIMITS_VERSION}`,
+    '# Managed by devbridge-runner. Put your own overrides in a file that sorts',
+    '# after this one, or edit the unit itself — neither is touched by updates.',
+    '',
+];
+/**
+ * The ceiling over ALL sessions, on the slice they were moved into.
+ *
+ * Same number as the service's, and deliberately so — but it is a COPY, not a
+ * move, and that is deliberate too. The plan asked for the ceiling to be carried
+ * across; shrinking the service's to «what the daemon alone needs» would be
+ * correct only on a machine where the cage actually took. On cgroup v1, without
+ * a user bus, under a foreign supervisor — every `nice-only` machine — the
+ * sessions are still CHILDREN of the service, and a service ceiling sized for
+ * the daemon would cap all of them at a few hundred MB. This file is written
+ * before anything has probed which of the two machines this is, so the safe
+ * shape is the same number twice: on a caged machine the slice is the ceiling
+ * that binds, on an uncaged one the service is, and neither machine is ever
+ * left with a ceiling that is too small for what is under it.
+ *
+ * The price is that a caged machine formally permits `service + slice`. It is
+ * not the guarantee `memoryPolicy` computes, and it is written down here rather
+ * than glossed over (QA-2026-09-07 MINOR-4).
+ *
+ * `MemorySwapMax` is a BOUND on the slice for the same reason it is on every
+ * scope: a ceiling on resident memory alone is not a ceiling, it is a swap pump
+ * (a 200 MB cage allocated 2 GB and drained the host's swap during the spike).
+ * Since #387 the bound is a share of the machine's swap rather than 0
+ * (`SESSIONS_SWAP_SHARE`), because each session now carries a `MemoryHigh`
+ * brake, and a brake with no swap under it stalls the session instead of
+ * slowing it. The unmeasured branch still writes 0: no measurement, no swap to
+ * hand out.
+ *
+ * No `MemoryHigh` here. The brake belongs on each SCOPE (`session-cage.ts`):
+ * soft pressure on the slice would throttle every session on the machine to
+ * keep one runaway alive a little longer.
+ *
+ * `sessionsUsageBytes` is the door that used to lead around all of the above.
+ * `facts` is null whenever the SERVICE's `MemoryCurrent` is unreadable — a
+ * stopped service, or a runner under a foreign supervisor — and this file then
+ * fell back to a flat `MemoryMax=55%`. But the sessions are SIBLINGS of the
+ * service, not its children: they survive `systemctl --user stop
+ * devbridge-runner`, so «the service is not running» says nothing at all about
+ * what the slice is holding, and `doctor --fix` on such a machine wrote 55 % of
+ * total onto a live slice and then called `daemon-reload` — the collective kill
+ * of QA-2026-09-07 BLOCKER-1 arriving through a door with no policy behind it.
+ *
+ * So the slice's own usage is read separately, and the promise made on
+ * `buildLimitsOverride` («the floor belongs to the policy, so every caller gets
+ * it and none can opt out») holds on this path too:
+ *   - a number → the ceiling clears it by the same 1.25 the policy uses, and
+ *                never drops below what one agent needs;
+ *   - 0        → nothing is running there, so the blind fraction can kill
+ *                nothing and stays;
+ *   - null     → this machine could not say, and NO ceiling is written at all.
+ *                Leaving whatever is in force in force is strictly better than
+ *                applying an unfounded number to a cgroup that may be full: the
+ *                daemon rewrites the file with a measured ceiling the moment it
+ *                can measure one (the drift check treats a file with no
+ *                `MemoryMax` as outdated).
+ */
+export function buildSessionsSliceOverride(facts = readMemoryFacts(), sessionsUsageBytes = readSessionsSliceUsageOrNull()) {
+    const memory = facts ? memoryPolicy(facts) : null;
+    return ([
+        ...MANAGED_HEADER,
+        '[Slice]',
+        ...(memory
+            ? [
+                `# ${memory.measured ? 'measured headroom' : 'still booting — conservative fraction of total'}`,
+                `MemoryMax=${asMiB(memory.maxBytes)}`,
+            ]
+            : unmeasuredSliceCeiling(sessionsUsageBytes)),
+        // The line the cage is built on. See `session-cage.ts` and the note above.
+        `MemorySwapMax=${memory && memory.swapMaxBytes > 0 ? asMiB(memory.swapMaxBytes) : '0'}`,
+        'TasksMax=8192',
+        'MemoryAccounting=yes',
+        'TasksAccounting=yes',
+        'CPUAccounting=yes',
+    ].join('\n') + '\n');
+}
+/**
+ * The `[Slice]` lines for a machine whose memory the policy could not measure.
+ * See {@link buildSessionsSliceOverride} for why each of the three answers is
+ * what it is.
+ */
+function unmeasuredSliceCeiling(sessionsUsageBytes) {
+    if (sessionsUsageBytes === null) {
+        return [
+            '# machine not measurable, and neither is this slice — no ceiling is written',
+            '# here at all: whatever systemd has in force stays in force, because a number',
+            '# with nothing behind it kills live sessions on the next daemon-reload.',
+        ];
+    }
+    if (sessionsUsageBytes === 0) {
+        return [
+            '# machine not measurable; this slice holds nothing, so a blind fraction can',
+            '# kill nothing — the same one the service falls back to',
+            'MemoryMax=55%',
+        ];
+    }
+    return [
+        `# machine not measurable — floored by the ${asMiB(sessionsUsageBytes)} this slice holds right now`,
+        `MemoryMax=${asMiB(Math.max(sessionsUsageBytes * CEILING_HEADROOM_OVER_CURRENT, CEILING_FLOOR_BYTES))}`,
+    ];
+}
+/**
+ * The CPU share of everything the agents run, against the daemon's own.
+ *
+ * `nice(2)` orders tasks INSIDE one cgroup. The moment a session gets a scope of
+ * its own it is no longer inside the service's cgroup, and the split between the
+ * two is decided by `cpu.weight` — which is 100 everywhere by default,
+ * `app.slice` (where the service lives) included. Without this file the cage
+ * would silently undo stage 1a and hand back the failure of 16.08: the daemon
+ * starved by its own children, four missed heartbeats, the server Offline and
+ * 504 on every session. 50 against 100 leaves the daemon two thirds.
+ *
+ * `process-priority.ts` stays exactly as it is: it is what protects the daemon
+ * on cgroup v1 and on every machine where the cage does not apply.
+ */
+export function buildDevbridgeSliceOverride() {
+    return ([
+        ...MANAGED_HEADER,
+        '[Slice]',
+        `CPUWeight=${SESSION_CPU_WEIGHT}`,
+        'CPUAccounting=yes',
+        'MemoryAccounting=yes',
+    ].join('\n') + '\n');
+}
 /**
  * Is the shipped resource policy missing or from an older runner?
  *
@@ -427,9 +760,21 @@ export function buildLimitsOverride(cpuCount = os.cpus().length, facts = readMem
  * version-based answer.
  */
 export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'utf8'), home = systemdUserHome(), facts = null) {
+    // Three files since 0.54.0, and any one of them being stale means the policy
+    // is: the ceiling on the service protects the daemon, the ceiling on
+    // `devbridge-sessions.slice` protects the machine from the sessions that
+    // LEFT the service's cgroup, and the weight on `devbridge.slice` is what
+    // keeps the daemon ahead of them. A runner that shipped the cage without the
+    // weight would be strictly worse than one that shipped neither.
+    return (fileIsOutdated(readFile, limitsOverridePath(home), facts) ||
+        fileIsOutdated(readFile, sessionsSliceOverridePath(home), facts) ||
+        // No ceiling in this one, so nothing in it can drift.
+        fileIsOutdated(readFile, devbridgeSliceOverridePath(home), null));
+}
+function fileIsOutdated(readFile, target, facts) {
     let contents;
     try {
-        contents = readFile(limitsOverridePath(home));
+        contents = readFile(target);
     }
     catch {
         return true; // never written — every server that predates 0.21.0
@@ -457,6 +802,14 @@ export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'u
  */
 const CEILING_DRIFT_TOLERANCE = 0.15;
 function memoryCeilingHasDrifted(contents, facts) {
+    // The swap share drifts for its own reason, and on its own schedule: an
+    // operator who enlarges the machine's swapfile (the one lever that makes the
+    // brake a brake rather than a freeze) would otherwise keep the old, smaller
+    // share until the next `LIMITS_VERSION` — and each session would keep getting
+    // half of it (#387 QA). Zero to non-zero and back is always drift; above that
+    // the same tolerance as the ceiling.
+    if (swapShareHasDrifted(contents, facts))
+        return true;
     // Never re-measure a machine that is still booting: the static pair it is
     // holding is deliberate, and «drift» against a lie is not drift.
     if (!memoryPolicy(facts).measured)
@@ -479,6 +832,19 @@ function memoryCeilingHasDrifted(contents, facts) {
     const wanted = memoryPolicy(facts).maxBytes;
     return Math.abs(writtenBytes - wanted) / wanted > CEILING_DRIFT_TOLERANCE;
 }
+function swapShareHasDrifted(contents, facts) {
+    const written = [...contents.matchAll(/^MemorySwapMax=(\d+)([KMG]?)$/gm)].at(-1);
+    // Not written at all: only the slice file carries this line, and the service
+    // file legitimately has none. Silence is not drift.
+    if (!written?.[1])
+        return false;
+    const scale = { '': 1, K: 1024, M: MIB, G: 1024 * MIB }[written[2] ?? ''] ?? MIB;
+    const writtenBytes = Number(written[1]) * scale;
+    const wanted = memoryPolicy(facts).swapMaxBytes;
+    if (writtenBytes === 0 || wanted === 0)
+        return writtenBytes !== wanted;
+    return Math.abs(writtenBytes - wanted) / wanted > CEILING_DRIFT_TOLERANCE;
+}
 /**
  * Write the drop-in. Returns false when nothing needed doing.
  *
@@ -487,14 +853,27 @@ function memoryCeilingHasDrifted(contents, facts) {
  * arrive at the same number — otherwise a write whose floor was binding would be
  * seen as drifted on the very next call and rewritten forever.
  */
-export function writeLimitsOverride(force = false, home = systemdUserHome(), facts = readMemoryFacts()) {
+export function writeLimitsOverride(force = false, home = systemdUserHome(), facts = readMemoryFacts(), sessionsUsageBytes = readSessionsSliceUsageOrNull()) {
+    // Unknown usage can be a busy service whose systemd query timed out. Do not
+    // replace an existing drop-in with a guessed percentage, or remove a limit
+    // by rewriting the file without its MemoryMax line. Defer the whole policy.
+    if (facts === null)
+        return false;
     if (!force && !limitsOverrideIsOutdated(undefined, home, facts))
         return false;
-    const target = limitsOverridePath(home);
-    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(target, buildLimitsOverride(undefined, facts), { mode: 0o644 });
+    // All three or none. They are one policy split across three units only
+    // because systemd has no other way to say it, and a machine holding two of
+    // them is a machine whose sessions are capped but whose daemon is not
+    // prioritised — the regression described on `buildDevbridgeSliceOverride`.
+    write(limitsOverridePath(home), buildLimitsOverride(undefined, facts));
+    write(sessionsSliceOverridePath(home), buildSessionsSliceOverride(facts, sessionsUsageBytes));
+    write(devbridgeSliceOverridePath(home), buildDevbridgeSliceOverride());
     return true;
 }
+function write(target, contents) {
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(target, contents, { mode: 0o644 });
+}
 /**
  * Does the installed unit point at something that no longer exists?
  *