@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/process-priority.js

@@ -0,0 +1,99 @@
+import os from 'node:os';
+import { log } from './log.js';
+/**
+ * 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 const NICE = 10;
+/**
+ * EPERM is a property of the machine, not of the process — it means this kernel
+ * or container will not let us renice at all, and it will mean that for every
+ * spawn afterwards. Said once; the alternative is one warning per agent process
+ * for the life of the daemon, which is how a real line gets buried.
+ */
+let permissionWarned = false;
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return String(error.code);
+    }
+    return '';
+}
+/**
+ * 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 function lowerPriority(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        os.setPriority(pid, NICE);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        // ESRCH: the child was already gone — a binary that is not there exits
+        // before we get to it. Nothing happened and nothing is wrong, so nothing
+        // is said; the spawn failure itself is reported by whoever spawned it.
+        if (code === 'ESRCH')
+            return;
+        if (code === 'EPERM') {
+            if (permissionWarned)
+                return;
+            permissionWarned = true;
+            log.warn('priority: not allowed to renice agent processes on this machine', {
+                nice: NICE,
+                error: String(error),
+            });
+            return;
+        }
+        log.warn('priority: could not lower a spawned process', {
+            pid,
+            nice: NICE,
+            error: String(error),
+        });
+    }
+}
+//# sourceMappingURL=process-priority.js.map

package/dist/protocol.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { HostLoadFrame } from './host-load.js';
 export declare const SessionDescriptorSchema: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<["TICKET", "CHAT"]>;
@@ -1150,7 +1151,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         branchPlan?: unknown;
     }>;
 }, "strip", z.ZodTypeAny, {
-    type: "session_start";
     session: {
         mode: "ask" | "plan" | "auto" | "full";
         agent: "CLAUDE" | "CODEX";
@@ -1201,8 +1201,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseSha?: string | undefined;
         } | undefined;
     };
-}, {
     type: "session_start";
+}, {
     session: {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -1248,6 +1248,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         branchHint?: unknown;
         branchPlan?: unknown;
     };
+    type: "session_start";
 }>, z.ZodObject<{
     type: z.ZodLiteral<"session_message">;
     sessionId: z.ZodString;
@@ -1651,7 +1652,28 @@ export type RunnerFrame = {
         from: string | null;
         to: string;
     };
-} | {
+}
+/**
+ * What this machine's own load looks like, right now (plan §5.3).
+ *
+ * A frame of its own rather than a field of `hello`, for the same reason
+ * `agent_versions` is one: `hello` is composed once per process and replayed
+ * on every reconnect, so a load put there would be frozen at daemon start —
+ * a number that is always wrong except in the first second of the machine's
+ * life. This one is measured on a timer and sent only when it moved.
+ *
+ * Nothing static travels here. `machine: {cpuCount, memTotalBytes,
+ * memAvailableBytes}` is already in `hello`, and repeating facts is how two
+ * sources of one truth start disagreeing. `cpuCount` is the single exception
+ * and it earns its place: load1 without it cannot be read as a ratio, and a
+ * consumer joining two frames to find out would eventually paint one
+ * machine's load against another's core count.
+ *
+ * Fields and thresholds mirror `@devbridge/shared` — see `host-load.ts`.
+ */
+ | ({
+    type: 'host_load';
+} & HostLoadFrame) | {
     type: 'pong';
 };
 //# sourceMappingURL=protocol.d.ts.map

package/dist/recipe-schema.d.ts

@@ -50,14 +50,14 @@ export declare const ProjectRecipePreviewSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     run: string;
     url?: string | undefined;
-    project?: string | undefined;
     stop?: string | undefined;
+    project?: string | undefined;
     timeoutSec?: number | undefined;
 }, {
     run: string;
     url?: string | undefined;
-    project?: string | undefined;
     stop?: string | undefined;
+    project?: string | undefined;
     timeoutSec?: number | undefined;
 }>;
 export declare const ProjectRecipeSchema: z.ZodObject<{
@@ -200,14 +200,14 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         run: string;
         url?: string | undefined;
-        project?: string | undefined;
         stop?: string | undefined;
+        project?: string | undefined;
         timeoutSec?: number | undefined;
     }, {
         run: string;
         url?: string | undefined;
-        project?: string | undefined;
         stop?: string | undefined;
+        project?: string | undefined;
         timeoutSec?: number | undefined;
     }>>;
     notes: z.ZodOptional<z.ZodString>;
@@ -243,8 +243,8 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
     preview?: {
         run: string;
         url?: string | undefined;
-        project?: string | undefined;
         stop?: string | undefined;
+        project?: string | undefined;
         timeoutSec?: number | undefined;
     } | undefined;
     notes?: string | undefined;
@@ -257,8 +257,8 @@ export declare const ProjectRecipeSchema: z.ZodObject<{
     preview?: {
         run: string;
         url?: string | undefined;
-        project?: string | undefined;
         stop?: string | undefined;
+        project?: string | undefined;
         timeoutSec?: number | undefined;
     } | undefined;
     notes?: string | undefined;

package/dist/self-update.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { findClaudeCli, USE_BUNDLED_CLAUDE } from './agent-binary.js';
+import { systemdUserEnv } from './environment.js';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
@@ -330,6 +331,8 @@ async function installGlobal(exec, source, prefix) {
  * npm needs PATH/HOME and a writable cache; everything else is stripped, both to
  * keep provider credentials out of a child process that touches the network and
  * to stop a stray `npm_config_*` from redirecting the install.
+ *
+ * NOT for `systemctl` — see `systemctlEnv()` below.
  */
 function npmEnv() {
     const env = {
@@ -344,6 +347,44 @@ function npmEnv() {
         env['XDG_CACHE_HOME'] = process.env['XDG_CACHE_HOME'];
     return env;
 }
+/**
+ * What `systemctl --user` needs, and nothing more.
+ *
+ * `npmEnv()` was used here too, and that was the whole defect (plan §5.5): it
+ * strips `XDG_RUNTIME_DIR`, which is how the client finds this user's D-Bus
+ * socket. Without it systemd prints «Failed to connect to bus: No medium found»
+ * and exits **0** — so every self-update reported a `daemon-reload` that never
+ * happened, and the memory ceiling written into the drop-in a line earlier never
+ * came into effect. In the file 7680M, in effect 6.0G, and no error anywhere.
+ *
+ * The two environments are merged rather than swapped, because each one answers
+ * a question the other does not:
+ *
+ *  - `systemdUserEnv()` alone would work, and is what the rest of the runner
+ *    passes to `systemctl`. But it starts from the full `process.env`, and in
+ *    the daemon that includes the agent provider keys. This module deliberately
+ *    hands no child a credential it has no use for (there is a test for exactly
+ *    that), and `systemctl` has no use for one.
+ *  - `npmEnv()` alone is the bug.
+ *
+ * So: the minimal shape of `npmEnv()` — PATH to find the binary, HOME for
+ * completeness — plus the two bus variables `systemdUserEnv()` resolves. The
+ * `npm_config_*` half is left out; it means nothing to systemctl.
+ */
+function systemctlEnv() {
+    const resolved = systemdUserEnv();
+    const env = {
+        PATH: process.env['PATH'] ?? '/usr/local/bin:/usr/bin:/bin',
+        HOME: process.env['HOME'] ?? '',
+    };
+    const runtimeDir = resolved['XDG_RUNTIME_DIR'];
+    if (runtimeDir)
+        env['XDG_RUNTIME_DIR'] = runtimeDir;
+    const busAddress = resolved['DBUS_SESSION_BUS_ADDRESS'];
+    if (busAddress)
+        env['DBUS_SESSION_BUS_ADDRESS'] = busAddress;
+    return env;
+}
 export async function selfUpdate(options) {
     const exec = options.exec ??
         ((file, args, opts) => execFileAsync(file, args, { timeout: opts.timeout, env: opts.env, maxBuffer: 4_000_000 }));
@@ -501,7 +542,7 @@ export async function selfUpdate(options) {
             fs.writeFileSync(unitPath(), buildUnit(installed.command));
             await exec('systemctl', ['--user', 'daemon-reload'], {
                 timeout: VERIFY_TIMEOUT_MS,
-                env: npmEnv(),
+                env: systemctlEnv(),
             });
             log.warn('self-update: the service unit pointed at the previous location — rewritten', {
                 execStart: installed.command,
@@ -525,7 +566,7 @@ export async function selfUpdate(options) {
         if ((options.writeLimits ?? writeLimitsOverride)()) {
             await exec('systemctl', ['--user', 'daemon-reload'], {
                 timeout: VERIFY_TIMEOUT_MS,
-                env: npmEnv(),
+                env: systemctlEnv(),
             });
             log.warn('self-update: resource limits drop-in written', {
                 path: limitsOverridePath(),

package/dist/service-unit.d.ts

@@ -57,8 +57,45 @@ export declare function buildUnit(execStart?: string, nodeBinary?: string): stri
  * 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 declare const LIMITS_VERSION = 3;
+export declare const LIMITS_VERSION = 5;
+/**
+ * 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 declare const SESSIONS_SLICE = "devbridge-sessions.slice";
+export declare 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 declare const SESSION_CPU_WEIGHT = 50;
 export declare function limitsOverridePath(home?: string): string;
+/**
+ * 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 declare function sliceOverridePath(slice: string, home?: string): string;
+export declare function sessionsSliceOverridePath(home?: string): string;
+export declare function devbridgeSliceOverridePath(home?: string): string;
 /**
  * What the memory policy needs to know about this machine. Read once and passed
  * in, so the policy itself is a pure function that a test can drive with the
@@ -76,12 +113,68 @@ export interface MemoryFacts {
      * as the floor under the ceiling; see `memoryPolicy`.
      */
     ownUsageBytes: number;
+    /**
+     * What a LOWER ceiling could not reclaim its way out of — the number the
+     * ceiling has to clear, and not the same question as the one above.
+     *
+     * Equal to `ownUsageBytes` whenever the split is known, which is every path
+     * that can read the cgroup's own `memory.stat`. It differs only where the
+     * split is unknown — systemd answered `MemoryCurrent` but the files behind it
+     * could not be read — and there it is the FULL reading: a ceiling written
+     * under an unknown cgroup must assume none of it can be given back.
+     *
+     * Page cache is deliberately NOT part of it when the split IS known: lowering
+     * `MemoryMax` under clean file pages makes the kernel reclaim them, not kill
+     * anything, so counting them would inflate every ceiling by whatever the
+     * machine happened to have cached (measured: +87 % on this host) — and the
+     * floor is applied AFTER the 85 %-of-total cap, so that inflation walks the
+     * ceiling straight past the cap this policy exists to enforce.
+     */
+    ownFloorBytes?: number;
+    /**
+     * The same reading for `devbridge-sessions.slice`, and the reason it is a
+     * separate number rather than part of the one above.
+     *
+     * Since 0.54.0 the agents live in that slice, NOT in the service's cgroup, and
+     * the ceiling this policy computes is written to both units. So both cgroups
+     * are invisible to `MemAvailable` and both have to survive the write — a
+     * policy that measures only the daemon computes a ceiling from a machine it
+     * cannot see and then applies it to one it can kill (QA-2026-09-07 BLOCKER-1:
+     * the hourly re-measure wrote 2 GiB onto a slice holding 6 GiB, with
+     * `MemorySwapMax=0`, which is every session on the machine).
+     *
+     * 0 is the honest answer on a machine where the cage never took: there the
+     * sessions are still inside the service's cgroup and `ownUsageBytes` already
+     * counts them.
+     */
+    sessionsUsageBytes: number;
+    /** The same distinction as {@link MemoryFacts.ownFloorBytes}, for the slice. */
+    sessionsFloorBytes?: number;
     /** Seconds since boot. Below `BOOT_SETTLE_SEC` the measurement is a lie. */
     uptimeSec: number;
+    /**
+     * `SwapTotal` — what the sessions' swap share is cut from (#387). Absent or 0
+     * means a machine without swap, and then the share is 0: the brake on such a
+     * machine can only drop page cache, and the wall is what stops a runaway.
+     */
+    swapTotalBytes?: number;
 }
+/**
+ * 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 declare const SESSIONS_SWAP_SHARE = 0.5;
 export interface MemoryPolicy {
     maxBytes: number;
     highBytes: number;
+    /** `MemorySwapMax` for the sessions slice: `SESSIONS_SWAP_SHARE` of `SwapTotal`. */
+    swapMaxBytes: number;
     /** false = the conservative static pair, because the machine was still booting. */
     measured: boolean;
     /**
@@ -102,6 +195,8 @@ export interface MemoryPolicy {
  * produces a ceiling that protects nothing.
  */
 export declare const BOOT_SETTLE_SEC = 600;
+/** What the ceiling about to be written has to clear, in either cgroup. */
+export declare function managedUsageFloorBytes(facts: MemoryFacts): number;
 /**
  * The two numbers, and the incident that decides them.
  *
@@ -122,8 +217,10 @@ export declare const BOOT_SETTLE_SEC = 600;
  *
  * 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)
  *
@@ -143,6 +240,20 @@ export declare const BOOT_SETTLE_SEC = 600;
  *    machine, and a ceiling of «everything» is the bug this function exists to fix.
  */
 export declare function memoryPolicy(facts: MemoryFacts, minCeilingBytes?: number): MemoryPolicy;
+/** `SwapTotal` of this machine, or null where `/proc/meminfo` will not say. */
+export declare function readSwapTotalBytes(): number | null;
+/**
+ * What our own cgroup currently holds.
+ *
+ * Read through `/proc/self/cgroup` rather than assembling the path from the
+ * service name: the runner runs as root and as a dedicated user, under
+ * `user@0.service` and under `user@1001.service`, and guessing that path wrong
+ * silently returns 0 — which would quietly shrink the ceiling by whatever we are
+ * 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.
+ */
+export declare function readSelfCgroup(): string | null;
+export declare function readOwnCgroupMemory(): CgroupMemory | null;
 /**
  * What the cgroup holds that `MemAvailable` has NOT already counted.
  *
@@ -154,17 +265,92 @@ export declare function memoryPolicy(facts: MemoryFacts, minCeilingBytes?: numbe
  * precisely when memory is tightest. Subtracting `file` keeps the part we really
  * do hold and cannot give back on demand.
  */
+export interface CgroupMemory {
+    /** Everything the cgroup holds, page cache included. */
+    currentBytes: number;
+    /**
+     * The part of it a lower ceiling could not reclaim its way out of, or null
+     * when only the total is known — systemd answered `MemoryCurrent` but the
+     * cgroup's own files could not be read. Null is «unknown», never «zero»:
+     * the two lead to different ceilings, and only one of them is safe.
+     */
+    unreclaimableBytes: number | null;
+}
+export declare function readCgroupMemory(dir: string): CgroupMemory | null;
 export declare function readCgroupUnreclaimable(dir: string): number | 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 declare function sliceCgroupPath(selfCgroup: string, slice: string): string | null;
+/**
+ * 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 declare function readSessionsSliceMemory(): CgroupMemory | null;
+/**
+ * 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 declare function parseSliceUsage(memoryCurrent: string | null, activeState: string | null): number | 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 declare function readSessionsSliceUsageOrNull(): number | null;
 /**
  * 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 declare function readMemoryFacts(ownUsageBytes?: number | null): MemoryFacts | null;
+export declare function readMemoryFacts(own?: CgroupMemory | null, sessions?: CgroupMemory | null): MemoryFacts | null;
 /**
  * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
  * box unreachable, but never so little that ordinary work is throttled.
@@ -176,6 +362,78 @@ export declare function readMemoryFacts(ownUsageBytes?: number | null): MemoryFa
  */
 export declare function cpuQuotaPercent(cpuCount?: number): number | null;
 export declare function buildLimitsOverride(cpuCount?: number, facts?: MemoryFacts | null): string;
+/**
+ * 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 declare function buildSessionsSliceOverride(facts?: MemoryFacts | null, sessionsUsageBytes?: number | null): string;
+/**
+ * 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 declare function buildDevbridgeSliceOverride(): string;
 /**
  * Is the shipped resource policy missing or from an older runner?
  *
@@ -195,7 +453,7 @@ export declare function limitsOverrideIsOutdated(readFile?: (p: string) => strin
  * 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 declare function writeLimitsOverride(force?: boolean, home?: string, facts?: MemoryFacts | null): boolean;
+export declare function writeLimitsOverride(force?: boolean, home?: string, facts?: MemoryFacts | null, sessionsUsageBytes?: number | null): boolean;
 /**
  * Does the installed unit point at something that no longer exists?
  *