@bridge4dev/runner 0.38.0 → 0.40.0

package/dist/adapters/claude.js

@@ -287,6 +287,15 @@ class ClaudeSession {
     mcpFallbackNotice = null;
     /** Guards against overlapping capability probes. */
     capabilitiesInFlight = false;
+    /**
+     * Has the first main-loop answer of this process already asked for the
+     * context window? (ticket #223)
+     *
+     * `q` is `readonly` — one adapter per CLI process — so this never needs
+     * resetting: a restarted process is a new instance with the flag back to
+     * false, which is exactly the moment the meter needs a fresh number.
+     */
+    contextProbedAfterFirstReply = false;
     mode;
     /**
      * A launch-time mode this workspace does not allow, remembered so the feed
@@ -559,6 +568,13 @@ class ClaudeSession {
         // message would otherwise show no model list at all — while the control
         // requests themselves work as soon as the CLI is up.
         this.refreshCapabilities();
+        // Same reasoning for the context meter (ticket #223). It used to be asked
+        // for only at the END of a turn, so a session that had not finished its
+        // first one had no numbers at all and the gauge did not exist — worst in a
+        // session that parked a question, which can sit there for hours. This probe
+        // costs one control round-trip and gives the meter its denominator (the
+        // model's window) from the moment the process is up.
+        this.refreshContextUsage();
     }
     /**
      * Write this session's MCP config to a 0600 file and return its path, or null
@@ -623,10 +639,14 @@ class ClaudeSession {
         this.output.push(maskSecrets(event));
     }
     /**
-     * How full the context window is, after a finished turn. Fire-and-forget with
-     * a timeout on purpose: this is one more control round-trip on a channel that
-     * can hang, and it must never be able to stall the event loop that carries the
-     * conversation.
+     * How full the context window is. Fire-and-forget with a timeout on purpose:
+     * this is one more control round-trip on a channel that can hang, and it must
+     * never be able to stall the event loop that carries the conversation.
+     *
+     * Called from four places, each answering a different gap: process start and
+     * first main-loop reply (ticket #223 — otherwise a session shows no gauge at
+     * all until its first turn ends), model change (the window's size differs 5x
+     * between 200k and 1M), and end of turn.
      */
     refreshContextUsage() {
         if (this.stopped)
@@ -1845,6 +1865,17 @@ class ClaudeSession {
                                 });
                             }
                         }
+                        // Ticket #223. The startup probe fires before the CLI has read
+                        // anything, so its number is the empty window; this one lands after
+                        // the agent has actually said something and is the first figure
+                        // worth showing. Once per process, and only for the main loop: it is
+                        // a control round-trip on a channel that can hang, subagent chatter
+                        // is not this session's context, and the end-of-turn probe covers
+                        // everything after.
+                        if (!fromSubagent && !this.contextProbedAfterFirstReply) {
+                            this.contextProbedAfterFirstReply = true;
+                            this.refreshContextUsage();
+                        }
                         break;
                     }
                     case 'user': {

package/dist/attachments.js

@@ -18,9 +18,32 @@ const execFileAsync = promisify(execFile);
  */
 /** Directory inside the worktree; also the line written to info/exclude. */
 export const ATTACHMENT_DIR = '.devbridge/attachments';
-/** Hard ceiling per file; the API allows 10 MB for images and 25 MB otherwise. */
-const MAX_ATTACHMENT_BYTES = 26 * 1024 * 1024;
-const DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * Hard ceiling per file; the API allows 10 MB for images and 50 MB otherwise.
+ *
+ * Mirror of `MAX_DOCUMENT_ATTACHMENT_SIZE_BYTES` in `@devbridge/shared` plus a
+ * megabyte of slack — the runner cannot import that package (see
+ * `recipe-schema.ts`: the published tarball would not resolve it). The slack is
+ * what keeps the two halves from disagreeing on a rounding: the API refuses
+ * first, with an error the person actually sees, and this only catches bytes
+ * that no upload path should have produced.
+ *
+ * Raise the API side and this one in the SAME runner release. A ceiling that
+ * moves only in DevBridge lets a file upload and then vanish: the refusal below
+ * is a warning line in the session, not something the uploader is shown.
+ */
+const MAX_ATTACHMENT_BYTES = 51 * 1024 * 1024;
+/**
+ * A minute was plenty while the ceiling was 26 MB; at 50 MB it is a coin flip.
+ *
+ * The whole file is buffered by the API and pushed through nginx in one
+ * response, so this timeout covers the entire transfer, not idle time between
+ * packets. 60 s for 50 MB demands ~7 Mbit/s sustained end to end — ordinary for
+ * two VPSes, not ordinary for a dev server on a home uplink or behind a
+ * throttled proxy. Three minutes covers ~2.3 Mbit/s, and the cost of being
+ * generous is nil: a stalled download fails the same way, just later.
+ */
+const DOWNLOAD_TIMEOUT_MS = 180_000;
 /**
  * A file name that is safe to write and unambiguous to read.
  *
@@ -153,9 +176,16 @@ export async function saveAttachments(input) {
     pruneAttachmentDir(dir);
     return { saved, failed };
 }
-/** Keep at most this much history in one worktree's attachment folder. */
+/**
+ * Keep at most this much history in one worktree's attachment folder.
+ *
+ * Sized in files, not in bytes: 512 MB was twenty attachments at the old 25 MB
+ * ceiling and would be ten at the new one — an afternoon of work, after which
+ * the folder starts evicting documents a running session may still be told to
+ * open. A gigabyte restores the same twenty-file depth.
+ */
 const ATTACHMENT_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
-const ATTACHMENT_DIR_BUDGET_BYTES = 512 * 1024 * 1024;
+const ATTACHMENT_DIR_BUDGET_BYTES = 1024 * 1024 * 1024;
 /**
  * Delete old attachments from a session worktree.
  *

package/dist/index.js

@@ -17,7 +17,7 @@ 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, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
+import { buildUnit, cpuQuotaPercent, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.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';
@@ -359,7 +359,9 @@ function runnerCapabilities(apiUrlOverride) {
             memTotalBytes: os.totalmem(),
             memAvailableBytes: os.freemem(),
             limitsVersion: LIMITS_VERSION,
-            limitsCurrent: !limitsOverrideIsOutdated(),
+            // 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()),
         },
         /**
          * Identity of THIS process, so the API can tell a network blink from a
@@ -497,20 +499,32 @@ const RESTART_DELAY_MS = 1_500;
  */
 async function repairResourceLimits() {
     try {
-        if (!writeLimitsOverride())
+        const facts = readMemoryFacts();
+        if (facts && 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.
+            log.warn('daemon: not enough free memory for a real ceiling — neighbours have the machine', {
+                availableMB: Math.round(facts.availableBytes / 1048576),
+                totalMB: Math.round(facts.totalBytes / 1048576),
+            });
+        }
+        if (!writeLimitsOverride(false, undefined, facts))
             return;
         log.warn('daemon: resource limits drop-in written — reloading systemd', {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
+            ...(facts ? memoryPolicy(facts) : {}),
         });
         await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
             timeout: 15_000,
             env: systemdUserEnv(),
         });
         // Deliberately no restart: `daemon-reload` alone is enough for these
-        // directives (verified live — OOMPolicy went stop→continue and MemoryMax
-        // 2G→infinity with the PID unchanged), and restarting here would park every
-        // live session to apply a setting that is already in force.
+        // directives — verified live twice, in both directions: 2026-07-30 removing a
+        // ceiling (MemoryMax 2G→infinity, OOMPolicy stop→continue) and 2026-08-12
+        // installing one (infinity→1234M), each with the PID unchanged. Restarting
+        // here would park every live session to apply a setting already in force.
         log.info('daemon: resource limits applied without a restart');
     }
     catch (error) {
@@ -520,6 +534,51 @@ async function repairResourceLimits() {
         });
     }
 }
+/**
+ * How often the daemon re-measures the machine after the first time.
+ *
+ * Doing this only at startup left a hole big enough to matter. The runner is a
+ * user unit and comes up 20–60 seconds into a boot, which is inside
+ * `BOOT_SETTLE_SEC` — so a machine that reboots gets the blind static fraction
+ * and then keeps it for as long as the daemon lives, which can be weeks. On a
+ * dedicated 8 GB box that is 3.5 GB of soft brake against the 3.3 GB three
+ * sessions and a build actually cost: throttling ordinary work for no reason.
+ * Worse, `limitsCurrent` in `hello` is computed from FRESH facts, so the API
+ * would keep logging «limits outdated» on every reconnect for a machine that had
+ * no way to fix itself.
+ *
+ * Hourly is right because drift is slow by definition — it tracks what else is
+ * installed on the machine, not what it is doing this minute — and because the
+ * 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
@@ -620,6 +679,10 @@ async function cmdDaemon() {
     // that stays connected for weeks.
     const pruneTimer = setInterval(() => supervisor.pruneJournals(), 6 * 3_600_000);
     pruneTimer.unref();
+    // Re-measure the machine — see `LIMITS_RECHECK_MS`. Writes nothing in the
+    // normal case, so this is a file read and some arithmetic once an hour.
+    const limitsTimer = setInterval(() => void repairResourceLimits(), LIMITS_RECHECK_MS);
+    limitsTimer.unref();
     const shutdown = (signal) => {
         log.info(`daemon: ${signal} received, shutting down`);
         supervisor.shutdown();
@@ -720,8 +783,9 @@ async function cmdInstallService() {
     print(`Wrote ${target}`);
     // Resource policy is a versioned drop-in, not part of the unit — see
     // `buildLimitsOverride`. Forced here: a fresh install must have it even if a
-    // file from an older runner is already sitting there.
-    writeLimitsOverride(true);
+    // 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()}`);
     if (!exec.viaCommand) {
         // Worth saying out loud: a unit pinned to a file inside the package directory
@@ -1143,10 +1207,22 @@ async function cmdDoctor(args) {
     print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
     print('');
     print('Service limits');
-    const outdated = limitsOverrideIsOutdated();
+    const memFacts = readMemoryFacts(await serviceMemoryCurrent());
+    const outdated = limitsOverrideIsOutdated(undefined, undefined, memFacts);
     print(`  drop-in         ${limitsOverridePath()}`);
     print(`  version         ${outdated ? `MISSING or OLD (want ${LIMITS_VERSION})` : LIMITS_VERSION}`);
     print(`  cpu quota       ${quota === null ? 'none (fewer than 4 cpus)' : `${quota}%`}`);
+    // Spelled out because the whole point of 0.39.0 is that this number is measured
+    // rather than a percentage of the machine: on a server with neighbours, «80% of
+    // total» sat above what was actually free and never engaged (gotcha #301).
+    if (memFacts) {
+        const policy = memoryPolicy(memFacts);
+        const mb = (bytes) => `${Math.round(bytes / 1024 / 1024)} MB`;
+        print(`  memory ceiling  ${mb(policy.maxBytes)} hard / ${mb(policy.highBytes)} soft`);
+        print(`  sized from      ${policy.measured
+            ? `${mb(memFacts.availableBytes)} available + ${mb(memFacts.ownUsageBytes)} ours`
+            : `55% of ${mb(memFacts.totalBytes)} — still booting, remeasured on the next start`}`);
+    }
     let effective;
     try {
         const { stdout } = await execFileAsync('systemctl', [
@@ -1222,9 +1298,22 @@ async function cmdDoctor(args) {
             process.exit(1);
         return;
     }
-    writeLimitsOverride(true);
+    const fixFacts = readMemoryFacts(await serviceMemoryCurrent());
+    writeLimitsOverride(true, undefined, fixFacts);
     print('');
     print(`Wrote ${limitsOverridePath()}`);
+    // Say it out loud when the ceiling had to be raised above the honest answer to
+    // avoid killing whatever is running right now. Lowering a ceiling under load is
+    // a decision, not a side effect of running a diagnostic — and without this line
+    // the number written here looks unexplainably generous.
+    if (fixFacts) {
+        const honest = memoryPolicy(fixFacts, 0);
+        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.`);
+        }
+    }
     try {
         await execFileAsync('systemctl', ['--user', 'daemon-reload'], { env: systemdUserEnv() });
         print('systemctl --user daemon-reload — done.');

package/dist/service-unit.d.ts

@@ -57,8 +57,114 @@ 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 = 2;
+export declare const LIMITS_VERSION = 3;
 export declare function limitsOverridePath(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
+ * numbers of a server it does not have.
+ */
+export interface MemoryFacts {
+    /** `MemTotal` — the whole machine. */
+    totalBytes: number;
+    /** `MemAvailable` — what can be handed out without swapping. Already excludes
+     *  what the co-tenants hold, and already counts reclaimable page cache. */
+    availableBytes: number;
+    /**
+     * What our own cgroup holds that `MemAvailable` has not already counted —
+     * `memory.current` minus its page cache. Added back to the headroom, and used
+     * as the floor under the ceiling; see `memoryPolicy`.
+     */
+    ownUsageBytes: number;
+    /** Seconds since boot. Below `BOOT_SETTLE_SEC` the measurement is a lie. */
+    uptimeSec: number;
+}
+export interface MemoryPolicy {
+    maxBytes: number;
+    highBytes: number;
+    /** false = the conservative static pair, because the machine was still booting. */
+    measured: boolean;
+    /**
+     * The honest headroom was below the 2 GB floor — the neighbours have eaten the
+     * machine and this ceiling sits ABOVE what is free. Not an error (a dev server
+     * that cannot run one agent is worse than a busy one), but the only signal the
+     * owner will ever get that the box is oversubscribed, so callers log it.
+     */
+    starved: boolean;
+}
+/**
+ * How long after boot `MemAvailable` starts telling the truth.
+ *
+ * The runner is a user unit ordered `After=network-online.target`, and the things
+ * it shares the machine with — dockerd and its containers, mysql, pm2 — come up
+ * around the same time. Measure at second 20 and the neighbours have not claimed
+ * their memory yet: on the 12 GB machine below that reads as 11 GB free and
+ * produces a ceiling that protects nothing.
+ */
+export declare const BOOT_SETTLE_SEC = 600;
+/**
+ * The two numbers, and the incident that decides them.
+ *
+ * Until 0.21.0 the policy was a 2 GB hard ceiling with systemd's default
+ * `OOMPolicy=stop`: one agent over the line and the whole service died, taking
+ * every other session with it (QA-112, gotcha #100). The fix removed the ceiling
+ * entirely and left a soft `MemoryHigh=80%`, on this reasoning, quoted from the
+ * code it replaced: «the machine keeps a fifth of its memory for everything that
+ * is not this service».
+ *
+ * That reasoning holds on a DEDICATED dev server and fails on a shared one, which
+ * is what vmi2502773 is: 11.9 GB total with ~4 GB permanently held by 18 docker
+ * containers, mysql, flowise, chroma and pm2. There, 80 % of TOTAL is 9.5 GB while
+ * only ~8 GB is actually free — so the soft brake sat ABOVE the real headroom and
+ * could never engage. The machine swapped, `kcompactd0` blocked for over 120
+ * seconds and the box hung; 2026-08-05 it was a `claude` at 4.2 GB, 2026-08-12 a
+ * single grep at 6.8 GB with 160 MB left. Only a power cycle recovered it.
+ *
+ * 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)
+ *   MemoryMax  = headroom − reserve
+ *   MemoryHigh = 80 % of MemoryMax            (reclaim and throttle first, kill last)
+ *
+ * A hard ceiling is safe to have again only because the OTHER half of the 0.21.0
+ * fix stayed: `OOMPolicy=continue` is still set below, so the kernel killing one
+ * runaway child no longer tears down the service. Restoring the ceiling without
+ * that would re-open QA-112.
+ *
+ * The clamps are the two ways this can go wrong:
+ *  - floor 2 GB: on a machine whose neighbours already ate everything, a computed
+ *    ceiling of a few hundred MB would mean a dev server that cannot run one
+ *    agent. Measured cost of ordinary work is 512–646 MB per `claude` and 1571 MB
+ *    for a workspace `pnpm -r typecheck`, so anything under 2 GB is not a dev
+ *    server at all — an unusable one is a worse failure than a busy one, the same
+ *    call `cpuQuotaPercent` makes below;
+ *  - 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 declare function memoryPolicy(facts: MemoryFacts, minCeilingBytes?: number): MemoryPolicy;
+/**
+ * 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 declare function readCgroupUnreclaimable(dir: string): 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`.
+ */
+export declare function readMemoryFacts(ownUsageBytes?: number | 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.
@@ -69,17 +175,27 @@ export declare function limitsOverridePath(home?: string): string;
  * than a busy one.
  */
 export declare function cpuQuotaPercent(cpuCount?: number): number | null;
-export declare function buildLimitsOverride(cpuCount?: number): string;
+export declare function buildLimitsOverride(cpuCount?: number, facts?: MemoryFacts | null): string;
 /**
  * Is the shipped resource policy missing or from an older runner?
  *
  * Deliberately version-based rather than content-based: an operator may add
  * their own directives to our file, and re-writing on every start would fight
- * them. Only the version number decides.
+ * them. The version number decides — plus, since 0.39.0 and only when `facts` are
+ * supplied, whether the measured ceiling still fits the machine (see
+ * `memoryCeilingHasDrifted`). Callers that pass no facts get the old, purely
+ * version-based answer.
+ */
+export declare function limitsOverrideIsOutdated(readFile?: (p: string) => string, home?: string, facts?: MemoryFacts | null): boolean;
+/**
+ * Write the drop-in. Returns false when nothing needed doing.
+ *
+ * The «never below what we already hold» guard lives in `memoryPolicy` itself
+ * (`CEILING_HEADROOM_OVER_CURRENT`), so writing, reading and the drift check all
+ * 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 limitsOverrideIsOutdated(readFile?: (p: string) => string, home?: string): boolean;
-/** Write the drop-in. Returns false when nothing needed doing. */
-export declare function writeLimitsOverride(force?: boolean, home?: string): boolean;
+export declare function writeLimitsOverride(force?: boolean, home?: string, facts?: MemoryFacts | null): boolean;
 /**
  * Does the installed unit point at something that no longer exists?
  *

package/dist/service-unit.js

@@ -129,13 +129,220 @@ 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 = 2;
+export const LIMITS_VERSION = 3;
 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';
 export function limitsOverridePath(home = systemdUserHome()) {
     return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service.d`, LIMITS_FILE);
 }
+const MIB = 1024 * 1024;
+const GIB = 1024 * MIB;
+/**
+ * How long after boot `MemAvailable` starts telling the truth.
+ *
+ * The runner is a user unit ordered `After=network-online.target`, and the things
+ * it shares the machine with — dockerd and its containers, mysql, pm2 — come up
+ * around the same time. Measure at second 20 and the neighbours have not claimed
+ * their memory yet: on the 12 GB machine below that reads as 11 GB free and
+ * produces a ceiling that protects nothing.
+ */
+export const BOOT_SETTLE_SEC = 600;
+/**
+ * The ceiling is never written BELOW what the cgroup already holds.
+ *
+ * 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
+ * cgroup on `daemon-reload`: a value under current usage makes the kernel reclaim
+ * and then kill inside the cgroup. At daemon start that is harmless — nothing is
+ * running yet — but `doctor --fix` on a busy machine would otherwise take out
+ * somebody's session as a side effect of running a diagnostic.
+ *
+ * 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.
+ */
+const CEILING_HEADROOM_OVER_CURRENT = 1.25;
+/**
+ * The two numbers, and the incident that decides them.
+ *
+ * Until 0.21.0 the policy was a 2 GB hard ceiling with systemd's default
+ * `OOMPolicy=stop`: one agent over the line and the whole service died, taking
+ * every other session with it (QA-112, gotcha #100). The fix removed the ceiling
+ * entirely and left a soft `MemoryHigh=80%`, on this reasoning, quoted from the
+ * code it replaced: «the machine keeps a fifth of its memory for everything that
+ * is not this service».
+ *
+ * That reasoning holds on a DEDICATED dev server and fails on a shared one, which
+ * is what vmi2502773 is: 11.9 GB total with ~4 GB permanently held by 18 docker
+ * containers, mysql, flowise, chroma and pm2. There, 80 % of TOTAL is 9.5 GB while
+ * only ~8 GB is actually free — so the soft brake sat ABOVE the real headroom and
+ * could never engage. The machine swapped, `kcompactd0` blocked for over 120
+ * seconds and the box hung; 2026-08-05 it was a `claude` at 4.2 GB, 2026-08-12 a
+ * single grep at 6.8 GB with 160 MB left. Only a power cycle recovered it.
+ *
+ * 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)
+ *   MemoryMax  = headroom − reserve
+ *   MemoryHigh = 80 % of MemoryMax            (reclaim and throttle first, kill last)
+ *
+ * A hard ceiling is safe to have again only because the OTHER half of the 0.21.0
+ * fix stayed: `OOMPolicy=continue` is still set below, so the kernel killing one
+ * runaway child no longer tears down the service. Restoring the ceiling without
+ * that would re-open QA-112.
+ *
+ * The clamps are the two ways this can go wrong:
+ *  - floor 2 GB: on a machine whose neighbours already ate everything, a computed
+ *    ceiling of a few hundred MB would mean a dev server that cannot run one
+ *    agent. Measured cost of ordinary work is 512–646 MB per `claude` and 1571 MB
+ *    for a workspace `pnpm -r typecheck`, so anything under 2 GB is not a dev
+ *    server at all — an unusable one is a worse failure than a busy one, the same
+ *    call `cpuQuotaPercent` makes below;
+ *  - 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;
+    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 };
+    };
+    // 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
+    // instead — it needs no measurement at all.
+    //
+    // 55 % is chosen against the machine that failed rather than against a tidy
+    // number: 55 % of 11.9 GB is 6.5 GB, which still leaves 1.4 GB after the 4 GB
+    // its neighbours hold, and puts the brake at 5.2 GB — engaged with plenty free.
+    // 60 % looked reasonable and left only 760 MB, which is not a margin. This
+    // number works blind, so it is sized for the crowded case, and it costs a
+    // dedicated box nothing: it only applies for the first ten minutes of uptime,
+    // before any session exists. The next daemon start measures and replaces it.
+    if (!Number.isFinite(uptimeSec) || uptimeSec < BOOT_SETTLE_SEC) {
+        return withFloor(totalBytes * 0.55, false);
+    }
+    // Enough for sshd, journald, the kernel and some page cache to keep working
+    // 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;
+    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 wanted = headroom - reserve;
+    return withFloor(clamp(wanted, floor, cap), true, wanted < floor);
+}
+function clamp(value, low, high) {
+    return Math.min(Math.max(value, low), high);
+}
+/** systemd takes a plain byte count, but a unit file is read by people. */
+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() {
+    let text;
+    try {
+        text = fs.readFileSync('/proc/meminfo', 'utf8');
+    }
+    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;
+}
+/**
+ * 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.
+ */
+function readOwnCgroupUsage() {
+    let cgroup;
+    try {
+        const line = fs
+            .readFileSync('/proc/self/cgroup', 'utf8')
+            .split('\n')
+            .find((l) => l.startsWith('0::'));
+        if (!line)
+            return null; // cgroup v1 — no v2 path to read
+        cgroup = line.slice('0::'.length).trim();
+    }
+    catch {
+        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
+    // runner holds» produced a ceiling 34 % away from the daemon's own answer on
+    // this very host, so the two paths would each see the other as drift and
+    // rewrite the file forever. Anything that is not the service must say «I do not
+    // know» and let the caller supply the number.
+    if (!cgroup.endsWith(`/${SERVICE_NAME}.service`))
+        return null;
+    return readCgroupUnreclaimable(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) {
+    try {
+        const current = Number(fs.readFileSync(path.join(dir, 'memory.current'), 'utf8').trim());
+        if (!Number.isFinite(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);
+    }
+    catch {
+        return null;
+    }
+}
+function readUptimeSec() {
+    try {
+        return Number(fs.readFileSync('/proc/uptime', 'utf8').split(/\s+/)[0]) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 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`.
+ */
+export function readMemoryFacts(ownUsageBytes = readOwnCgroupUsage()) {
+    const info = readMemInfo();
+    if (!info || ownUsageBytes === null)
+        return null;
+    return { ...info, ownUsageBytes, uptimeSec: readUptimeSec() };
+}
 /**
  * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
  * box unreachable, but never so little that ordinary work is throttled.
@@ -148,8 +355,16 @@ export function limitsOverridePath(home = systemdUserHome()) {
 export function cpuQuotaPercent(cpuCount = os.cpus().length) {
     return cpuCount >= 4 ? (cpuCount - 1) * 100 : null;
 }
-export function buildLimitsOverride(cpuCount = os.cpus().length) {
+export function buildLimitsOverride(cpuCount = os.cpus().length, facts = readMemoryFacts()) {
     const quota = cpuQuotaPercent(cpuCount);
+    // No `minCeilingBytes` parameter on purpose. It existed here for one revision
+    // and passed an explicit `0`, which silently DEFEATED the default in
+    // `memoryPolicy` — the writer produced a ceiling below live cgroup usage while
+    // the drift check and `doctor` both computed the floored one. Two consequences,
+    // both found in QA: `doctor --fix` could kill a session on a loaded machine,
+    // and the file was rewritten on every start because no fixed point existed.
+    // The floor belongs to the policy, so every caller gets it and none can opt out.
+    const memory = facts ? memoryPolicy(facts) : null;
     return ([
         `${LIMITS_MARKER} ${LIMITS_VERSION}`,
         '# Managed by devbridge-runner. Put your own overrides in a file that sorts',
@@ -163,14 +378,34 @@ export function buildLimitsOverride(cpuCount = os.cpus().length) {
         'StartLimitBurst=0',
         '',
         '[Service]',
-        // The whole point of the change: one child's OOM must not take the fleet.
+        // The whole point of the 0.21.0 change, and the reason the ceiling below is
+        // safe to have at all: one child's OOM must not take the fleet.
         'OOMPolicy=continue',
-        // Clears `MemoryMax=2G` from units written before 0.21.0.
-        'MemoryMax=',
-        // Soft pressure instead of a hard ceiling: the kernel reclaims and
-        // throttles rather than killing, and the machine keeps a fifth of its
-        // memory for everything that is not this service.
-        'MemoryHigh=80%',
+        // Both values also override the `MemoryMax=2G` baked into units written
+        // before 0.21.0.
+        //
+        // The unmeasurable branch used to write `MemoryMax=` + `MemoryHigh=80%` —
+        // literally the pair this release exists to remove. Because an empty
+        // assignment RESETS a directive and a drop-in sorts after the unit, that
+        // branch would have stripped the ceiling the API's fallback unit now carries
+        // and left the machine weaker than if we had written nothing at all. A
+        // drop-in must never disarm the unit it overrides, so it falls back to the
+        // same static pair used during boot.
+        ...(memory
+            ? [
+                `# ${memory.measured ? 'measured headroom' : 'still booting — conservative fraction of total'}`,
+                `MemoryMax=${asMiB(memory.maxBytes)}`,
+                // Soft pressure below the hard stop: the kernel reclaims and throttles
+                // here, and only kills at MemoryMax. This is the line that failed on
+                // vmi2502773 — as a percentage of TOTAL it sat above what the machine
+                // could spare, so it never engaged.
+                `MemoryHigh=${asMiB(memory.highBytes)}`,
+            ]
+            : [
+                '# machine not measurable — same conservative pair as the fallback unit',
+                'MemoryMax=55%',
+                'MemoryHigh=44%',
+            ]),
         // Either a computed quota, or an explicit reset — both of which clear the
         // `CPUQuota=80%` baked into units written before 0.21.0.
         quota === null ? 'CPUQuota=' : `CPUQuota=${quota}%`,
@@ -186,9 +421,12 @@ export function buildLimitsOverride(cpuCount = os.cpus().length) {
  *
  * Deliberately version-based rather than content-based: an operator may add
  * their own directives to our file, and re-writing on every start would fight
- * them. Only the version number decides.
+ * them. The version number decides — plus, since 0.39.0 and only when `facts` are
+ * supplied, whether the measured ceiling still fits the machine (see
+ * `memoryCeilingHasDrifted`). Callers that pass no facts get the old, purely
+ * version-based answer.
  */
-export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'utf8'), home = systemdUserHome()) {
+export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'utf8'), home = systemdUserHome(), facts = null) {
     let contents;
     try {
         contents = readFile(limitsOverridePath(home));
@@ -200,15 +438,61 @@ export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'u
     if (!line)
         return true;
     const version = Number.parseInt(line.slice(LIMITS_MARKER.length).trim(), 10);
-    return !Number.isFinite(version) || version < LIMITS_VERSION;
+    if (!Number.isFinite(version) || version < LIMITS_VERSION)
+        return true;
+    return facts ? memoryCeilingHasDrifted(contents, facts) : false;
 }
-/** Write the drop-in. Returns false when nothing needed doing. */
-export function writeLimitsOverride(force = false, home = systemdUserHome()) {
-    if (!force && !limitsOverrideIsOutdated(undefined, home))
+/**
+ * Since 0.39.0 the ceiling is a measurement, and a measurement goes stale.
+ *
+ * A machine that gained a database and a dozen containers after the drop-in was
+ * written would keep a ceiling sized for the machine it used to be — which is the
+ * original bug wearing a different hat. So the version marker is no longer the
+ * only thing that can make the file outdated.
+ *
+ * The 15 % band is what keeps this from becoming a rewrite on every start:
+ * `MemAvailable` moves by hundreds of MB just from page cache, and re-writing our
+ * file that often would fight an operator who added their own directives to it
+ * (the reason the check was version-only to begin with).
+ */
+const CEILING_DRIFT_TOLERANCE = 0.15;
+function memoryCeilingHasDrifted(contents, facts) {
+    // 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)
+        return false;
+    // LAST match, not the first: systemd applies the last assignment, and the file
+    // explicitly invites the operator to add their own lines. Reading the first one
+    // would measure drift against a directive that is not in force.
+    const written = [...contents.matchAll(/^MemoryMax=(\d+)([KMG]?)$/gm)].at(-1);
+    // Anything we cannot read as a byte count is replaced, and that is deliberate:
+    // an EMPTY `MemoryMax=` is the 0.21.0 shape this release exists to remove, and
+    // `MemoryMax=55%` is the blind pair we write when the machine is unmeasurable —
+    // both must give way the moment a real measurement is available. The operator's
+    // own directives belong in a file that sorts after this one, which the header of
+    // every generated file says; a value they appended HERE is still honoured,
+    // because a plain `4G` parses above and is compared like any other.
+    if (!written?.[1])
+        return true;
+    const scale = { '': 1, K: 1024, M: MIB, G: 1024 * MIB }[written[2] ?? ''] ?? MIB;
+    const writtenBytes = Number(written[1]) * scale;
+    const wanted = memoryPolicy(facts).maxBytes;
+    return Math.abs(writtenBytes - wanted) / wanted > CEILING_DRIFT_TOLERANCE;
+}
+/**
+ * Write the drop-in. Returns false when nothing needed doing.
+ *
+ * The «never below what we already hold» guard lives in `memoryPolicy` itself
+ * (`CEILING_HEADROOM_OVER_CURRENT`), so writing, reading and the drift check all
+ * 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()) {
+    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(), { mode: 0o644 });
+    fs.writeFileSync(target, buildLimitsOverride(undefined, facts), { mode: 0o644 });
     return true;
 }
 /**

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.38.0";
+export declare const RUNNER_VERSION = "0.40.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.38.0';
+export const RUNNER_VERSION = '0.40.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",