@bridge4dev/runner 0.37.0 → 0.39.0

package/dist/agent-binary.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The platform packages the SDK will look for, in its own order (`sdk.mjs`).
+ *
+ * BOTH linux variants are accepted rather than detecting musl the way the SDK
+ * does: the question here is «did the optional package get installed at all»,
+ * and answering it must never be the thing that blocks an update. A glibc
+ * binary on a musl host is a different failure — and since #225 it announces
+ * itself in the session feed instead of hiding.
+ */
+export declare function nativeCandidates(platform?: NodeJS.Platform, arch?: string): string[];
+/**
+ * Absolute path to the Claude CLI inside an installed runner package, or null.
+ *
+ * Resolved from the SDK's own file, exactly like the SDK resolves it — npm may
+ * hoist the platform package next to the SDK, next to the runner, or several
+ * levels up, and only the module resolver knows which happened here.
+ */
+export declare function findClaudeCli(packageDir: string): string | null;
+/**
+ * The same question about THIS process's own installation.
+ *
+ * Goes through the SDK's entry point rather than a path guess, so it answers
+ * correctly in every layout the runner runs in — a global npm install, a
+ * dedicated-user prefix, and the pnpm store of a source checkout, where the
+ * platform package is reachable from the SDK and from nowhere else.
+ */
+export declare function claudeCliPath(): string | null;
+//# sourceMappingURL=agent-binary.d.ts.map

package/dist/agent-binary.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/**
+ * Is the binary this runner would actually launch Claude with present?
+ *
+ * Not a hypothetical check (ticket #225, гоча #297). The Claude CLI does not
+ * live in this package: `@anthropic-ai/claude-agent-sdk` keeps it in a ~300 MB
+ * **optional** platform package, one per platform+arch. For npm the failure of
+ * an optional dependency is not an error — `npm install -g` exits 0, the runner
+ * reports a successful update and restarts into a build that cannot start a
+ * single Claude session. That is exactly what happened to transitway-dev-01 on
+ * 2026-08-11: every launch threw
+ * `Native CLI binary for linux-x64 not found` synchronously, before any event
+ * could be emitted, and a live session went silent for an hour and a half.
+ *
+ * The runner's own smoke test could not catch it: `devbridge-runner --version`
+ * loads the module graph, and the SDK resolves the platform binary lazily — on
+ * the first `query()`, which is a session, not a startup.
+ */
+const SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk';
+/**
+ * The platform packages the SDK will look for, in its own order (`sdk.mjs`).
+ *
+ * BOTH linux variants are accepted rather than detecting musl the way the SDK
+ * does: the question here is «did the optional package get installed at all»,
+ * and answering it must never be the thing that blocks an update. A glibc
+ * binary on a musl host is a different failure — and since #225 it announces
+ * itself in the session feed instead of hiding.
+ */
+export function nativeCandidates(platform = process.platform, arch = process.arch) {
+    const exe = platform === 'win32' ? 'claude.exe' : 'claude';
+    const packages = platform === 'android'
+        ? [`${SDK_PACKAGE}-linux-${arch}-android`]
+        : platform === 'linux'
+            ? [`${SDK_PACKAGE}-linux-${arch}`, `${SDK_PACKAGE}-linux-${arch}-musl`]
+            : [`${SDK_PACKAGE}-${platform}-${arch}`];
+    return packages.map((name) => `${name}/${exe}`);
+}
+/**
+ * Absolute path to the Claude CLI inside an installed runner package, or null.
+ *
+ * Resolved from the SDK's own file, exactly like the SDK resolves it — npm may
+ * hoist the platform package next to the SDK, next to the runner, or several
+ * levels up, and only the module resolver knows which happened here.
+ */
+export function findClaudeCli(packageDir) {
+    const found = resolveFromSdkEntry(path.join(packageDir, 'node_modules', SDK_PACKAGE, 'sdk.mjs'));
+    // Inside THIS installation, or it does not count. Node's resolver walks up the
+    // directory tree and consults the global folders, so a package that is absent
+    // from the build we just installed can still be found in the one we are about
+    // to retire — and answering «present» from there is exactly the false green
+    // this check exists to prevent. A global npm install keeps its dependencies
+    // under its own package directory, so containment is also simply true.
+    return found && isInside(packageDir, found) ? found : null;
+}
+function isInside(dir, file) {
+    const relative = path.relative(path.resolve(dir), path.resolve(file));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+/**
+ * The same question about THIS process's own installation.
+ *
+ * Goes through the SDK's entry point rather than a path guess, so it answers
+ * correctly in every layout the runner runs in — a global npm install, a
+ * dedicated-user prefix, and the pnpm store of a source checkout, where the
+ * platform package is reachable from the SDK and from nowhere else.
+ */
+export function claudeCliPath() {
+    let sdkEntry;
+    try {
+        sdkEntry = createRequire(import.meta.url).resolve(SDK_PACKAGE);
+    }
+    catch {
+        return null;
+    }
+    return resolveFromSdkEntry(sdkEntry);
+}
+function resolveFromSdkEntry(sdkEntry) {
+    let resolve;
+    try {
+        resolve = createRequire(sdkEntry).resolve;
+    }
+    catch {
+        return null;
+    }
+    for (const candidate of nativeCandidates()) {
+        try {
+            const resolved = resolve(candidate);
+            if (fs.existsSync(resolved))
+                return resolved;
+        }
+        catch {
+            // Not installed under this name — try the next candidate.
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=agent-binary.js.map

package/dist/index.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { ClaudeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
+import { claudeCliPath } from './agent-binary.js';
 import { loadConfig, requireConfig, saveConfig } from './config.js';
 import { log } from './log.js';
 import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
@@ -16,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';
@@ -62,8 +63,14 @@ function argValue(args, flag) {
  */
 function installedAgents() {
     const agents = [];
-    // Claude is bundled inside the Agent SDK, so it is always available.
-    agents.push('claude');
+    // Claude comes with the Agent SDK — but «comes with» is a claim about THIS
+    // installation, not a law (ticket #225). The CLI is an optional platform
+    // package, and an update that silently lost it leaves a runner that reports
+    // Claude, accepts Claude sessions, and cannot start a single one. Reported as
+    // measured, so the dashboard greys the agent out instead of offering a
+    // session that dies before its first word.
+    if (claudeCliPath())
+        agents.push('claude');
     if (hasExecutable('codex'))
         agents.push('codex');
     return agents;
@@ -352,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
@@ -490,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) {
@@ -513,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
@@ -613,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();
@@ -713,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
@@ -1136,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', [
@@ -1215,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/self-update.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { findClaudeCli } from './agent-binary.js';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
@@ -235,10 +236,19 @@ function installArgs(source, prefix) {
     // a directory the daemon cannot write — and, on the rarer host where it can,
     // npm cheerfully installs a SECOND copy somewhere the service does not exec,
     // reports success, and the runner restarts on the old version forever.
+    //
+    // `--include=optional` is npm's default and is stated anyway (ticket #225):
+    // the Claude CLI ships as an OPTIONAL platform package, and a single
+    // `omit=optional` inherited from an `.npmrc`, an environment variable or a CI
+    // habit turns an update into a runner that cannot start a single Claude
+    // session — silently, because for npm a failed optional dependency is not a
+    // failure at all. The flag makes this deployment's intent explicit rather
+    // than dependent on whatever configuration the machine happens to carry.
     return [
         'install',
         '-g',
         '--ignore-scripts',
+        '--include=optional',
         '--loglevel=error',
         ...(prefix ? ['--prefix', prefix] : []),
         source,
@@ -259,7 +269,7 @@ export function manualUpdateCommand(tarballUrl, options = {}) {
     const prefix = options.prefix === undefined ? installPrefixFor(packageDir) : options.prefix;
     const user = options.user ?? os.userInfo().username;
     const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : -1);
-    const install = ['npm install -g --ignore-scripts --loglevel=error']
+    const install = ['npm install -g --ignore-scripts --include=optional --loglevel=error']
         .concat(prefix ? [`--prefix ${prefix}`] : [])
         .concat([tarballUrl])
         .join(' ');
@@ -420,6 +430,44 @@ export async function selfUpdate(options) {
                 `Restore it on the server with: npm install -g${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
+    // The binary the sessions will actually be started with (ticket #225).
+    //
+    // The probe above is not enough and 2026-08-11 proved it: `--version` loads
+    // the module graph, but the SDK resolves the Claude CLI lazily — on the first
+    // `query()`, i.e. inside a session, long after this update reported success.
+    // A missing OPTIONAL platform package therefore sailed through every check
+    // here, the daemon restarted, and the machine spent an hour and a half
+    // answering «продолжай» with nothing.
+    //
+    // One repair attempt first, because that is what the failure usually deserves:
+    // a 300 MB optional package that did not download is a network hiccup, not a
+    // broken release, and reinstalling it is cheaper for the user than a rollback.
+    if (!findClaudeCli(newPackageDir)) {
+        log.warn('self-update: the Claude CLI is missing from the new build — repairing', {
+            packageDir: newPackageDir,
+        });
+        try {
+            await installGlobal(exec, options.tarballUrl, prefix);
+        }
+        catch (error) {
+            log.warn('self-update: the repair install failed', { error: describe(error) });
+        }
+    }
+    if (!findClaudeCli(newPackageDir)) {
+        log.error('self-update: still no Claude CLI after the repair — rolling back', {
+            packageDir: newPackageDir,
+        });
+        const detail = 'the Claude CLI (an optional platform package of @anthropic-ai/claude-agent-sdk) did not install, ' +
+            'so no Claude session could have started on this build';
+        try {
+            await installGlobal(exec, rollbackTarball, prefix);
+            return fail(`The new version was not activated (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+        catch (rollbackError) {
+            return fail(`The new version is broken (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
+                `Restore it on the server with: npm install -g --include=optional${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+    }
     // The service unit may be pinned to a file inside the directory this update
     // just replaced — early versions wrote the resolved script path, and a package
     // rename moves it. Then the restart we are about to ask for would fail with

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?
  *