@bridge4dev/runner 0.53.0 → 0.54.0

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 = 4;
+/**
+ * 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,6 +113,43 @@ 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;
 }
@@ -102,6 +176,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 +198,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 +221,7 @@ 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;
+export declare function readOwnCgroupMemory(): CgroupMemory | null;
 /**
  * What the cgroup holds that `MemAvailable` has NOT already counted.
  *
@@ -154,17 +233,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 +330,74 @@ 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=0` 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).
+ *
+ * No `MemoryHigh` here either. Soft pressure on the slice would throttle every
+ * session on the machine to keep one runaway alive a little longer — the exact
+ * trade the spike measured and rejected: 60 seconds of delays instead of a
+ * 380 ms honest death.
+ *
+ * `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 +417,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?
  *