@bridge4dev/runner 0.53.0 → 0.54.0

package/dist/index.js

@@ -17,12 +17,14 @@ 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, memoryPolicy, readMemoryFacts, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
+import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, sessionsSliceOverridePath, unitExecTarget, unitPath, writeLimitsOverride, DEVBRIDGE_SLICE, LIMITS_VERSION, SESSION_CPU_WEIGHT, SESSIONS_SLICE, } from './service-unit.js';
+import { initSessionCage, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
 import { SEARCH_GUARD_ENABLED, claudeSettingsPath, installSearchGuard, removeSearchGuard, searchGuardCommand, searchGuardHome, searchGuardHookPath, searchGuardStatus, } from './claude-settings.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';
 import { mcpConfigDir } from './paths.js';
+import { readMemoryFactsFromSystemd } from './systemd-memory.js';
 const execFileAsync = promisify(execFile);
 /**
  * Identity of this process, and the note the previous one left.
@@ -405,6 +407,37 @@ function runnerCapabilities(apiUrlOverride) {
             // 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()),
+            /**
+             * How the sessions on this machine are actually contained (plan §5.4.3).
+             *
+             * `scope` — a cgroup and a memory ceiling per session; `nice-only` — the
+             * machine cannot do that (cgroup v1, no user bus, a foreign supervisor)
+             * and only the CPU priority applies; `none` — not even that.
+             *
+             * Reported rather than assumed because the containment fails QUIETLY:
+             * `systemd-run` accepts every limit on a cgroup v1 machine and applies
+             * none of them. Without this field «it did not work at the client's» is
+             * something to be guessed at; with it the card can say so.
+             */
+            sessionCage: sessionCage().mode,
+            // Why not `scope`, in one sentence, for the card to show under it.
+            // Empty string when the cage is on.
+            sessionCageReason: sessionCage().reason,
+            // What ONE session may hold, in bytes. Null when there is no cage —
+            // then the only ceiling is the service's, over all of them together.
+            sessionMemoryMaxBytes: sessionCage().memoryMaxBytes,
+            /**
+             * The ceiling over ALL sessions, as systemd has it in force — not as the
+             * drop-in on disk says.
+             *
+             * The live probe proves the personal ceiling and nothing else: a
+             * `MemoryMax` on a scope applies whatever the parent slice holds. So a
+             * machine whose `daemon-reload` never landed reported `scope` and
+             * `limitsCurrent: true` while three sessions of 2.5 GB ran over a slice
+             * at `infinity`, and the card said «Sessions capped»
+             * (QA-2026-09-07 MAJOR-3). Null is that machine, and the card says so.
+             */
+            sessionsMemoryMaxBytes: sessionCage().sessionsSliceMemoryMaxBytes,
         },
         /**
          * Identity of THIS process, so the API can tell a network blink from a
@@ -482,6 +515,11 @@ async function cmdPair(args) {
     }
     const apiUrl = (argValue(args, '--api') ?? 'https://api.bridge4.dev').replace(/\/$/, '');
     const name = argValue(args, '--name') ?? os.hostname();
+    // Probed here as well as at daemon start, so the very first record of this
+    // server already carries the truth about its containment instead of the safe
+    // default. Costs one throwaway process, once.
+    await initSessionCage();
+    const capabilities = runnerCapabilities(apiUrl);
     const response = await fetch(`${apiUrl}/api/v1/dev/servers/claim`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
@@ -490,7 +528,7 @@ async function cmdPair(args) {
             name,
             runnerVersion: RUNNER_VERSION,
             osInfo: `${os.type()} ${os.release()} ${os.arch()}`.slice(0, 200),
-            capabilities: runnerCapabilities(apiUrl),
+            capabilities,
         }),
     });
     const body = (await response.json().catch(() => null));
@@ -553,8 +591,17 @@ const RESTART_DELAY_MS = 1_500;
  */
 async function repairResourceLimits() {
     try {
-        const facts = readMemoryFacts();
-        if (facts && memoryPolicy(facts).starved) {
+        const { facts, sessionsUsageBytes } = await readMemoryFactsFromSystemd();
+        if (facts === null) {
+            // Neither systemd nor the cgroup files could answer, which on the daemon's
+            // own path means the machine is in a shape this policy cannot reason about
+            // at all. Leaving what is in force in force is the safe half of the
+            // decision; the loud line is the other half, because the alternative is a
+            // machine that silently keeps an old ceiling forever.
+            log.warn('daemon: resource limits unchanged — memory usage could not be measured; retrying in an hour', { recheckMs: LIMITS_RECHECK_MS });
+            return;
+        }
+        if (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.
@@ -563,12 +610,12 @@ async function repairResourceLimits() {
                 totalMB: Math.round(facts.totalBytes / 1048576),
             });
         }
-        if (!writeLimitsOverride(false, undefined, facts))
+        if (!writeLimitsOverride(false, undefined, facts, sessionsUsageBytes))
             return;
         log.warn('daemon: resource limits drop-in written — reloading systemd', {
             path: limitsOverridePath(),
             version: LIMITS_VERSION,
-            ...(facts ? memoryPolicy(facts) : {}),
+            ...memoryPolicy(facts),
         });
         await execFileAsync('systemctl', ['--user', 'daemon-reload'], {
             timeout: 15_000,
@@ -657,33 +704,6 @@ function repairSearchGuard() {
  * 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
@@ -719,7 +739,17 @@ async function cmdDaemon() {
     const config = requireConfig();
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
+    // Nothing of ours is running yet, so every `devbridge-session-*.scope` on this
+    // machine belongs to a process that is gone. Stopping the scope takes the
+    // whole tree under it — which is the answer to the `ugrep` that outlived its
+    // session by 10 h 51 min on 16.08, and to every scope the OOM killer left in
+    // `failed` (a name systemd will otherwise refuse to reuse).
+    await sweepOrphanSessionScopes();
     await repairResourceLimits();
+    // After the drop-ins are on disk and reloaded, never before: the probe below
+    // creates `devbridge-sessions.slice`, and a slice first loaded without its
+    // policy would hold no ceiling until the next daemon-reload.
+    await initSessionCage();
     repairSearchGuard();
     // A Claude token this runner captured through the sign-in relay. Applied
     // BEFORE any adapter exists, because `scrubbedEnv()` copies it out of this
@@ -892,8 +922,29 @@ async function cmdInstallService() {
     // `buildLimitsOverride`. Forced here: a fresh install must have it even if a
     // 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()}`);
+    // The slice reading goes with them: re-installing over a machine that is
+    // running sessions right now must not write a ceiling under them.
+    //
+    // Unmeasurable is a WARNING here, not a refusal, and the order above is why:
+    // the unit is already on disk, so the machine gets a runner either way. The
+    // states that produce «unmeasurable» — a failed service, a service mid
+    // auto-restart, an unhappy user bus — are exactly the states someone runs
+    // `install.sh --repair` from, and a repair that installs nothing because it
+    // could not size a ceiling is a repair that does not repair.
+    const installMem = await readMemoryFactsFromSystemd();
+    if (installMem.facts === null) {
+        print('warning: could not measure this machine — resource limits were left as they are. ' +
+            'Nothing was removed; the daemon re-measures hourly, or run `devbridge-runner doctor --fix`.');
+    }
+    else {
+        writeLimitsOverride(true, undefined, installMem.facts, installMem.sessionsUsageBytes);
+        print(`Wrote ${limitsOverridePath()}`);
+        // Two more files since 0.54.0: the sessions no longer live inside the
+        // service's cgroup, so the ceiling over all of them and the CPU share that
+        // keeps the daemon ahead of them belong to the slices (`session-cage.ts`).
+        print(`Wrote ${sessionsSliceOverridePath()}`);
+        print(`Wrote ${devbridgeSliceOverridePath()}`);
+    }
     // Привратник шаблонов поиска — та же логика, что и у политики ресурсов:
     // свежая установка должна получить его сразу. Пишем в ЧУЖОЙ файл настроек,
     // поэтому молча пропускаем, если тронуть его нельзя (`claude-settings.ts`).
@@ -1330,7 +1381,7 @@ async function cmdDoctor(args) {
     print(`  fits sessions   ~${advised} (at ~1.5 GB per session under load)`);
     print('');
     print('Service limits');
-    const memFacts = readMemoryFacts(await serviceMemoryCurrent());
+    const { facts: memFacts, sessionsUsageBytes: memSessionsUsage } = await readMemoryFactsFromSystemd();
     const outdated = limitsOverrideIsOutdated(undefined, undefined, memFacts);
     print(`  drop-in         ${limitsOverridePath()}`);
     print(`  version         ${outdated ? `MISSING or OLD (want ${LIMITS_VERSION})` : LIMITS_VERSION}`);
@@ -1346,6 +1397,62 @@ async function cmdDoctor(args) {
             ? `${mb(memFacts.availableBytes)} available + ${mb(memFacts.ownUsageBytes)} ours`
             : `55% of ${mb(memFacts.totalBytes)} — still booting, remeasured on the next start`}`);
     }
+    else {
+        // Не молча: без фактов о машине политика не считается вовсе, и `--fix`
+        // тогда НИЧЕГО не пишет — ни на сервис, ни на слайс. Строка про слайс
+        // остаётся полезной сама по себе: она говорит, что стоит на кону, если
+        // измерение так и не появится.
+        print("  memory ceiling  not computed — this machine's usage is unreadable");
+        print('                  --fix leaves every limits file exactly as it is');
+        print(`  sessions slice  ${memSessionsUsage === null
+            ? 'unreadable too'
+            : memSessionsUsage === 0
+                ? 'holds nothing right now'
+                : `holds ${Math.round(memSessionsUsage / 1024 / 1024)} MB — a ceiling under that would kill it`}`);
+    }
+    // The cage, and the reason it matters more than the numbers above it: those
+    // are the ceiling over the WHOLE service, and a session that has left the
+    // service's cgroup is not under them any more. If this section says anything
+    // but `scope`, the only containment on this machine is the CPU priority.
+    const cage = await initSessionCage();
+    print('');
+    print('Session cage (a cgroup per session)');
+    print(`  mode            ${cage.mode}`);
+    if (cage.reason)
+        print(`  why            ${cage.reason}`);
+    print(`  slice           ${SESSIONS_SLICE} (under ${DEVBRIDGE_SLICE}, CPUWeight=${SESSION_CPU_WEIGHT})`);
+    print(`  drop-ins        ${sessionsSliceOverridePath()}`);
+    print(`                  ${devbridgeSliceOverridePath()}`);
+    if (cage.mode === 'scope') {
+        const mb = (bytes) => bytes === null ? 'infinity' : `${Math.round(bytes / 1024 / 1024)} MB`;
+        print(`  per session     MemoryMax ${mb(cage.memoryMaxBytes)}, MemorySwapMax 0, TasksMax ${SESSION_TASKS_MAX}`);
+        // What systemd has IN FORCE on the slice, beside the paths of the files
+        // that were supposed to put it there. «В файле 7680M, действует 6.0G» is the
+        // lesson of §5.5, and the drop-in of a slice can fail to land in exactly the
+        // same way: a reload that never happened leaves every session personally
+        // capped and collectively unlimited (QA-2026-09-07 MAJOR-3).
+        print(`  all sessions    MemoryMax ${mb(cage.sessionsSliceMemoryMaxBytes)} in force on ${SESSIONS_SLICE}`);
+        if (cage.sessionsSliceMemoryMaxBytes === null) {
+            print('                  NOT CAPPED — the drop-in above has not been applied.');
+            print(`                  Apply with: ${systemctlHint('daemon-reload')}`);
+        }
+        print(`  service ceiling ${mb(cage.serviceMemoryMaxBytes)} (the per-session figure is half of the containing ceiling, capped)`);
+        print(`  expand-env flag ${cage.expandEnvironmentFlag ? 'passed (systemd ≥ 254)' : 'not passed — this systemd does not know it, and --scope does not expand anyway'}`);
+    }
+    else {
+        print('  per session     none — only the CPU priority from `process-priority.ts` applies');
+    }
+    const scopes = await listSessionScopes();
+    if (scopes.length === 0) {
+        print('  live scopes     none');
+    }
+    else {
+        print(`  live scopes     ${scopes.length}`);
+        for (const scope of scopes) {
+            const mb = (bytes) => bytes === null ? '?' : `${Math.round(bytes / 1024 / 1024)} MB`;
+            print(`    ${scope.unit}  ${scope.activeState ?? '?'}  ${mb(scope.memoryCurrentBytes)} of ${mb(scope.memoryMaxBytes)}  tasks ${scope.tasksCurrent ?? '?'}${scope.result && scope.result !== 'success' ? `  ${scope.result}` : ''}`);
+        }
+    }
     let effective;
     try {
         const { stdout } = await execFileAsync('systemctl', [
@@ -1372,6 +1479,19 @@ async function cmdDoctor(args) {
     print('Effective (systemd)');
     for (const line of effective)
         print(`  ${line}`);
+    // «В файле 7680M, действует 6.0G». Ровно это и получалось, пока самообновление
+    // звало `systemctl --user daemon-reload` без `XDG_RUNTIME_DIR`: systemd отвечал
+    // «Failed to connect to bus» и выходил с кодом 0, drop-in переписывался, а
+    // systemd продолжал жить по старому юниту (план §5.5). Причину починили, но
+    // расхождение может прийти и иначе — правкой юнита руками, оборванным
+    // обновлением, — и без этой строки строки выше выглядят как то, что
+    // действует, хотя это уже не так.
+    if ((await systemctlProperty('NeedDaemonReload')) === 'yes') {
+        print('');
+        print('STALE — systemd has NOT re-read the unit since it changed on disk,');
+        print('  so the numbers above are the OLD ones, not what the drop-in says.');
+        print(`  Apply with: ${systemctlHint('daemon-reload')}`);
+    }
     // Привратник шаблонов поиска. Печатается всегда, в том числе когда он ВЫКЛЮЧЕН
     // в коде: «стоит, хотя выключен» — это и есть та машина, которую пропустило
     // обновление, и увидеть её больше неоткуда.
@@ -1438,10 +1558,24 @@ async function cmdDoctor(args) {
             process.exit(1);
         return;
     }
-    const fixFacts = readMemoryFacts(await serviceMemoryCurrent());
-    writeLimitsOverride(true, undefined, fixFacts);
+    const { facts: fixFacts, sessionsUsageBytes: fixSessionsUsage } = await readMemoryFactsFromSystemd();
     print('');
-    print(`Wrote ${limitsOverridePath()}`);
+    // Unmeasurable leaves the files exactly as they are and says so — the one
+    // thing this must never do is replace a ceiling in force with a guess, or
+    // rewrite the file without its `MemoryMax` line, which RESETS the ceiling.
+    // The rest of the repair still runs: `doctor --fix` is also the search guard,
+    // the unit file and the daemon-reload, and a machine that cannot be measured
+    // this second still needs those. The non-zero exit at the end is what keeps
+    // «could not do the main thing» from reading as success to automation.
+    if (fixFacts === null) {
+        print('Resource limits: LEFT UNCHANGED — this machine could not be measured.');
+        print('  Nothing was removed. Re-run once `systemctl --user` answers again.');
+    }
+    else {
+        // Keep the service and the sessions under the same measured policy.
+        writeLimitsOverride(true, undefined, fixFacts, fixSessionsUsage);
+        print(`Wrote ${limitsOverridePath()}`);
+    }
     const guardOutcome = applySearchGuard(print);
     if (guardOutcome === 'installed') {
         print(`Installed search-pattern guard into ${claudeSettingsPath(searchGuardHome())}`);
@@ -1458,7 +1592,19 @@ async function cmdDoctor(args) {
         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.`);
+            // Which cgroup forced the ceiling up, not just «the service»: on a loaded
+            // machine it is the sessions slice, and naming the service there sent the
+            // reader looking at a daemon holding 400 MB (QA-2026-09-07 BLOCKER-1).
+            // The SAME numbers the floor is computed from (`managedUsageFloorBytes`),
+            // not the headroom ones: where the split is unknown those two differ, and
+            // a note sourced from the wrong pair names the wrong cgroup and a smaller
+            // number than the one that actually forced the ceiling up.
+            const ownFloor = fixFacts.ownFloorBytes ?? fixFacts.ownUsageBytes;
+            const sessionsFloor = fixFacts.sessionsFloorBytes ?? fixFacts.sessionsUsageBytes;
+            const holder = sessionsFloor > ownFloor
+                ? `the sessions on this machine already hold ${mb(sessionsFloor)} MB`
+                : `the service already holds ${mb(ownFloor)} MB`;
+            print(`note: ceiling raised to ${mb(applied.maxBytes)} MB — ${holder}, and ${mb(honest.maxBytes)} MB would kill it on reload. Re-run when idle.`);
         }
     }
     try {
@@ -1469,6 +1615,10 @@ async function cmdDoctor(args) {
     catch (error) {
         fail(`daemon-reload failed: ${String(error instanceof Error ? error.message : error)}`);
     }
+    // Everything else was repaired; the limits were not. Said with the exit code
+    // as well as with the line above, because `doctor --fix` is run by scripts.
+    if (fixFacts === null)
+        process.exit(1);
 }
 // ─── set-token ───────────────────────────────────────────────────────
 function cmdSetToken(args) {

package/dist/process-priority.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Everything an agent starts runs at a lower CPU priority than the daemon that
+ * supervises it.
+ *
+ * The failure this exists for is the runner starving itself with its own
+ * children (16.08): a session's build saturated the box, the daemon lost four
+ * heartbeats in a row, the server went Offline and every session on that
+ * machine answered 504 — while the work it was doing was fine. The daemon's job
+ * during a heavy turn is a few milliseconds of socket traffic; it should not
+ * have to queue behind a `tsc` it launched itself.
+ *
+ * **What this gives.** Inside the service's own cgroup the daemon (nice 0) gets
+ * the processor before the agents (nice 10); neighbouring sessions, all at 10,
+ * still share it evenly between themselves. Children inherit the nice value at
+ * fork, so a `vitest` the agent starts through Bash — several levels down from
+ * the process we renice — is covered without us knowing about it.
+ *
+ * Inheritance is why every call site is the line straight after its `spawn`:
+ * measured here, a grandchild forked AFTER the call comes up at 10 and one
+ * forked in the microseconds before it stays at 0. An agent needs hundreds of
+ * milliseconds to boot before it forks anything, so that window is empty in
+ * practice — but it is a window, and it only grows if the call drifts down the
+ * function.
+ *
+ * **What it does NOT give.** Against processes OUTSIDE the cgroup (production
+ * in `system.slice`) it does nothing at all: across cgroups the split is
+ * decided by `cpu.weight`, and nice only orders tasks within one. It does not
+ * touch memory, which is the mechanism behind three of the four incidents on
+ * other people's machines. This is the approach to stage 2 (a scope per session
+ * with a memory ceiling) and the fallback for it on cgroup v1, where stage 2
+ * cannot work — not a replacement for it.
+ *
+ * Priority is a convenience, not correctness: nothing here throws. A session
+ * that runs at the wrong priority is a slower machine; a session that fails to
+ * start because renicing failed is a broken product.
+ */
+/**
+ * The nice value every process the runner spawns for an agent gets.
+ *
+ * 10 rather than 19: the point is to lose to the daemon and to anything the
+ * owner is doing by hand, not to be scheduled last behind every background cron
+ * on the box. The scheduler's weight table gives nice 10 about a ninth of the
+ * share of nice 0 under contention (1024 → 110), which is all the room the
+ * heartbeat needs — 19 would buy an order of magnitude more and cost a session
+ * its throughput whenever anything else on the machine woke up.
+ */
+export declare const NICE = 10;
+/**
+ * Push one spawned process down to {@link NICE}. Never throws.
+ *
+ * Takes `number | undefined` because that is exactly what `child.pid` is: a
+ * spawn that failed has none, and the caller should not have to ask.
+ */
+export declare function lowerPriority(pid: number | undefined): void;
+//# sourceMappingURL=process-priority.d.ts.map

package/dist/process-priority.js

@@ -0,0 +1,99 @@
+import os from 'node:os';
+import { log } from './log.js';
+/**
+ * Everything an agent starts runs at a lower CPU priority than the daemon that
+ * supervises it.
+ *
+ * The failure this exists for is the runner starving itself with its own
+ * children (16.08): a session's build saturated the box, the daemon lost four
+ * heartbeats in a row, the server went Offline and every session on that
+ * machine answered 504 — while the work it was doing was fine. The daemon's job
+ * during a heavy turn is a few milliseconds of socket traffic; it should not
+ * have to queue behind a `tsc` it launched itself.
+ *
+ * **What this gives.** Inside the service's own cgroup the daemon (nice 0) gets
+ * the processor before the agents (nice 10); neighbouring sessions, all at 10,
+ * still share it evenly between themselves. Children inherit the nice value at
+ * fork, so a `vitest` the agent starts through Bash — several levels down from
+ * the process we renice — is covered without us knowing about it.
+ *
+ * Inheritance is why every call site is the line straight after its `spawn`:
+ * measured here, a grandchild forked AFTER the call comes up at 10 and one
+ * forked in the microseconds before it stays at 0. An agent needs hundreds of
+ * milliseconds to boot before it forks anything, so that window is empty in
+ * practice — but it is a window, and it only grows if the call drifts down the
+ * function.
+ *
+ * **What it does NOT give.** Against processes OUTSIDE the cgroup (production
+ * in `system.slice`) it does nothing at all: across cgroups the split is
+ * decided by `cpu.weight`, and nice only orders tasks within one. It does not
+ * touch memory, which is the mechanism behind three of the four incidents on
+ * other people's machines. This is the approach to stage 2 (a scope per session
+ * with a memory ceiling) and the fallback for it on cgroup v1, where stage 2
+ * cannot work — not a replacement for it.
+ *
+ * Priority is a convenience, not correctness: nothing here throws. A session
+ * that runs at the wrong priority is a slower machine; a session that fails to
+ * start because renicing failed is a broken product.
+ */
+/**
+ * The nice value every process the runner spawns for an agent gets.
+ *
+ * 10 rather than 19: the point is to lose to the daemon and to anything the
+ * owner is doing by hand, not to be scheduled last behind every background cron
+ * on the box. The scheduler's weight table gives nice 10 about a ninth of the
+ * share of nice 0 under contention (1024 → 110), which is all the room the
+ * heartbeat needs — 19 would buy an order of magnitude more and cost a session
+ * its throughput whenever anything else on the machine woke up.
+ */
+export const NICE = 10;
+/**
+ * EPERM is a property of the machine, not of the process — it means this kernel
+ * or container will not let us renice at all, and it will mean that for every
+ * spawn afterwards. Said once; the alternative is one warning per agent process
+ * for the life of the daemon, which is how a real line gets buried.
+ */
+let permissionWarned = false;
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return String(error.code);
+    }
+    return '';
+}
+/**
+ * Push one spawned process down to {@link NICE}. Never throws.
+ *
+ * Takes `number | undefined` because that is exactly what `child.pid` is: a
+ * spawn that failed has none, and the caller should not have to ask.
+ */
+export function lowerPriority(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        os.setPriority(pid, NICE);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        // ESRCH: the child was already gone — a binary that is not there exits
+        // before we get to it. Nothing happened and nothing is wrong, so nothing
+        // is said; the spawn failure itself is reported by whoever spawned it.
+        if (code === 'ESRCH')
+            return;
+        if (code === 'EPERM') {
+            if (permissionWarned)
+                return;
+            permissionWarned = true;
+            log.warn('priority: not allowed to renice agent processes on this machine', {
+                nice: NICE,
+                error: String(error),
+            });
+            return;
+        }
+        log.warn('priority: could not lower a spawned process', {
+            pid,
+            nice: NICE,
+            error: String(error),
+        });
+    }
+}
+//# sourceMappingURL=process-priority.js.map

package/dist/protocol.d.ts

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

package/dist/recipe-schema.d.ts

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