@bridge4dev/runner 0.54.0 → 0.55.1

package/dist/session-cage.d.ts

@@ -1,9 +1,13 @@
 import { DEVBRIDGE_SLICE, SESSION_CPU_WEIGHT, SESSIONS_SLICE } from './service-unit.js';
 /**
- * What one session may hold. **Proposal Р3 of the plan, awaiting the owner.**
+ * The honest share of one session — where the BRAKE starts, not where it dies.
+ *
+ * Until #387 this was `MemoryMax`, the kill line. It is the same number and the
+ * same reasoning, moved one step down the ladder: above it the kernel reclaims
+ * and throttles (`MemoryHigh`), and the kill line is {@link sessionMemoryMaxBytes}.
  *
  * `min(2.5 GiB, service ceiling / 2)` — §3 of
- * `docs/plans/active/agent-sessions-host-resources.md`. Both halves matter:
+ * `docs/plans/shipped/agent-sessions-host-resources.md`. Both halves matter:
  *
  *  - the absolute number is sized against the measurement, not against a round
  *    figure. The heaviest ordinary thing a session runs is a workspace
@@ -20,7 +24,7 @@ import { DEVBRIDGE_SLICE, SESSION_CPU_WEIGHT, SESSIONS_SLICE } from './service-u
  * protects the machine is what systemd has in force, not what the drop-in on
  * disk says — those two have already drifted apart once (§5.5 of the plan).
  */
-export declare const SESSION_MEMORY_MAX_ABSOLUTE_BYTES: number;
+export declare const SESSION_MEMORY_HIGH_ABSOLUTE_BYTES: number;
 /**
  * Processes and threads per session.
  *
@@ -50,8 +54,26 @@ export interface SessionCageFacts {
     mode: SessionCageMode;
     /** Why not `scope`. Empty string when it is. */
     reason: string;
-    /** What one session gets, in bytes. Null unless `mode === 'scope'`. */
+    /**
+     * The brake — `MemoryHigh` on the scope: past it the kernel reclaims and slows
+     * the session down instead of killing anything. Null unless `mode === 'scope'`.
+     */
+    memoryHighBytes: number | null;
+    /**
+     * The wall — `MemoryMax` on the scope, far above the brake. Reaching it costs
+     * the session its hungriest process (and, without `oomContinue`, the session).
+     * Null unless `mode === 'scope'`.
+     */
     memoryMaxBytes: number | null;
+    /** Swap one session may use, bytes. 0 = none. Null unless `mode === 'scope'`. */
+    swapMaxBytes: number | null;
+    /**
+     * `OOMPolicy=continue` is on the scope: a kill inside it takes one process,
+     * not the session. False on a systemd whose scopes do not take the setting
+     * (Ubuntu 22.04 is 249, and there the whole scope still stops on any kill —
+     * which is why the wall has to be far away on every machine, not only here).
+     */
+    oomContinue: boolean;
     /** The service ceiling systemd has in force, as measured. Null = infinity. */
     serviceMemoryMaxBytes: number | null;
     /**
@@ -95,7 +117,30 @@ export interface SessionCageFacts {
  * cost the one thing it does buy: the runaway dying instead of its neighbours
  * (QA-2026-09-07 MINOR-6, where the earlier wording promised the opposite).
  */
-export declare const SESSION_MEMORY_MIN_BYTES: number;
+export declare const SESSION_MEMORY_HIGH_MIN_BYTES: number;
+/**
+ * The wall, when nothing on the machine can say where it should be.
+ *
+ * Every real path reads the wall off systemd (the slice, else the service) or
+ * measures it (`memoryPolicy`). This is the last resort for a machine that gave
+ * neither — twice the honest share, so that even blind the wall sits above the
+ * brake by a margin an honest build fits into, and a runaway still meets one.
+ */
+export declare const SESSION_MEMORY_WALL_FALLBACK_FACTOR = 2;
+/**
+ * The pool is cut into this many honest shares. Three, because that is what
+ * `maxSessions` defaults to on a dev server, so three sessions can sit at their
+ * brakes without the pool itself overflowing — and one runaway then meets its
+ * own wall (`ceiling − share`) while a neighbour on its share still fits.
+ */
+export declare const SESSION_SHARE_DIVISOR = 3;
+/**
+ * On a machine too small to leave a share of room, the brake is this fraction
+ * of the wall. The same 0.8 `memoryPolicy` puts between the service's own
+ * `MemoryHigh` and `MemoryMax`, for the same reason: a band, however narrow,
+ * beats a bare kill line.
+ */
+export declare const SESSION_BRAKE_OF_WALL = 0.8;
 /**
  * `clamp(ceiling / 2, 2 GiB, 2.5 GiB)`, never above the ceiling itself.
  *
@@ -114,7 +159,83 @@ export declare const SESSION_MEMORY_MIN_BYTES: number;
  * hand, and then «never more than the slice» has to still be true
  * (QA-2026-09-07 MINOR-5).
  */
-export declare function sessionMemoryMaxBytes(containingMemoryMaxBytes: number | null): number;
+export declare function sessionMemoryHighBytes(containingMemoryMaxBytes: number | null): number;
+/** The brake and the wall, decided together — see {@link sessionMemoryLadder}. */
+export interface SessionMemoryLadder {
+    highBytes: number;
+    maxBytes: number;
+}
+/**
+ * The two numbers of the cage, computed in ONE place because each is wrong
+ * without the other (QA of #387 found both halves broken separately).
+ *
+ * ```
+ *   brake = max(containing / 3, 2 GiB)      capped by the containing ceiling
+ *   wall  = containing − brake              never at or below the brake
+ * ```
+ *
+ * **Why a third, and no upper cap.** The owner's second note on #387: «ночью
+ * машина свободна (~9 ГБ), а сессии всё равно нельзя выйти за 2.5 ГБ… граница
+ * должна смотреть на то, сколько реально свободно». A fixed 2.5 GiB was right
+ * as a KILL line and is wrong as a brake: on a big machine it throttles honest
+ * work that the machine could have absorbed. A third of the pool is the largest
+ * share that still lets three sessions sit at their brakes inside the ceiling,
+ * which is what `maxSessions` defaults to. The 2 GiB floor stays — it is sized
+ * over the 1571 MB measured peak of a workspace `pnpm typecheck`, and a dev
+ * server that cannot run one of those is not a dev server.
+ *
+ * **Why the wall is `containing − brake` and not the ceiling itself.** 0.55.0's
+ * first shape put the wall AT the slice ceiling, and that is not a per-session
+ * wall at all: the kernel charges a leaf and every ancestor, so with any
+ * neighbour the SLICE overflows first, and then the victim is chosen across the
+ * whole slice. Measured on this host (a 300 MB slice, two 250 MB scopes): the
+ * scope that crept up survived to the end, and the **neighbour holding 200 MB
+ * under its own wall was killed** — slice `max 19, oom 1, oom_kill 1`, victim
+ * `max 0, oom 0, oom_kill 1`. Leaving one honest share of room under the
+ * ceiling is what makes the runaway meet its OWN wall first while a neighbour
+ * on its share still fits.
+ *
+ * **The tiny machine.** When the ceiling is so low that `containing − brake`
+ * would land at or under the brake, there is no room for isolation at all: the
+ * wall becomes the ceiling and the BRAKE is lowered to 80 % of it, so that
+ * there is still a braking band (`memoryPolicy` uses the same 0.8 for the
+ * service). Without this, a 4 GB machine got `MemoryHigh == MemoryMax` — the
+ * 0.54.0 kill line back in place, with the card claiming a brake.
+ */
+export declare function sessionMemoryLadder(containingMemoryMaxBytes: number | null, measuredCeilingBytes?: number | null): SessionMemoryLadder;
+/**
+ * The wall — `MemoryMax` on the scope — and why it is the WHOLE containing
+ * ceiling and not a fraction of it (#387).
+ *
+ * The owner's rule: the wall is protection against a runaway, not the norm of
+ * work. Where the norm lives is {@link sessionMemoryHighBytes}; the wall has to
+ * be far enough above it that honest work never touches it, and «far» on a dev
+ * server means «what the machine can actually spare» — which is exactly the
+ * number the slice ceiling already is (`memoryPolicy`: `MemAvailable` plus what
+ * we hold, minus a reserve). Giving a session less than that is the 2.5 GiB
+ * mistake with a different number.
+ *
+ * With `OOMPolicy=continue` on the scope, reaching the wall costs a runaway its
+ * fattest process and nothing else; the neighbours are protected by the slice,
+ * which holds the same number over all of them together.
+ *
+ * `containing` is what systemd has in force on the slice (else the service);
+ * `measured` is what the policy would write there; the factor is the last
+ * resort. Never below the brake — a wall under the brake is a kill line again.
+ */
+export declare function sessionMemoryMaxBytes(containingMemoryMaxBytes: number | null, measuredCeilingBytes?: number | null): number;
+/**
+ * Swap one session may push into — the reason the brake slows instead of stalls.
+ *
+ * Half of what the slice may use, the same «no single session takes the
+ * collective allowance» rule as the memory share. When systemd reports no
+ * bound on the slice (the drop-in never landed, MAJOR-3 shape) the share is cut
+ * from the machine's `SwapTotal` directly, with the same fraction the slice
+ * would have had, so the per-scope line is a real bound on its own. A machine
+ * with no swap gets 0, which is exactly 0.54.0's line — and exactly right:
+ * there is nothing to share.
+ */
+export declare function sessionSwapMaxBytes(sliceSwapMaxBytes: number | null, hostSwapTotalBytes: number | null): number;
 /**
  * The session id as systemd will accept it.
  *
@@ -171,11 +292,18 @@ export interface CageProbe {
     /** The one-shot scope that reads its own `memory.max`, built like a real one. */
     probeMemoryMax: (options: {
         expandEnvironmentFlag: boolean;
+        oomPolicyFlag: boolean;
     }) => Promise<CageProbeResult>;
     /** `MemoryMax` of the runner service in bytes; null for `infinity`. */
     serviceMemoryMax: () => Promise<number | null>;
     /** `MemoryMax` in force on `devbridge-sessions.slice`; null for `infinity`. */
     sessionsSliceMemoryMax: () => Promise<number | null>;
+    /** `MemorySwapMax` in force on the slice; 0 is a real answer, null = `infinity`/unknown. */
+    sessionsSliceSwapMax: () => Promise<number | null>;
+    /** `SwapTotal` of the machine, or null where `/proc/meminfo` will not say. */
+    hostSwapTotalBytes: () => number | null;
+    /** The ceiling `memoryPolicy` would write today, or null on an unmeasurable machine. */
+    machineCeilingBytes: () => number | null;
     /** Can this kernel renice at all — the fallback's own precondition. */
     canRenice: () => boolean;
 }
@@ -191,6 +319,15 @@ export interface CageProbe {
 export declare function cageEnv(): Record<string, string>;
 export declare const defaultCageProbe: CageProbe;
 export declare function detectSessionCage(probe?: CageProbe): Promise<SessionCageFacts>;
+/**
+ * Did `systemd-run` refuse the command line BECAUSE of `OOMPolicy=`?
+ *
+ * systemd's wording for a property a unit type does not take is «Unknown
+ * assignment: OOMPolicy=continue» (`bus_append_unit_property_assignment`); a
+ * refusal that does not name the property is some other machine's problem and
+ * must not be retried into a cage with a weaker policy.
+ */
+export declare function refusesOomPolicy(error: string): boolean;
 /**
  * Probe once, at daemon start, and remember the answer.
  *
@@ -212,6 +349,8 @@ export interface CagedSpawn {
     /** The scope unit this start will live in, or null when nothing was wrapped. */
     unit: string | null;
 }
+/** The scope a live caged id runs in, or null when it is not caged (or gone). */
+export declare function sessionScopeUnitOf(id: string): string | null;
 /**
  * Wrap a command in its session's cage, or hand it back untouched.
  *
@@ -246,6 +385,77 @@ export declare function killedBeforeExec(info: {
     sawOutput: boolean;
     caged: boolean;
 }): boolean;
+/** The counters of one session's cgroup, read straight off the filesystem. */
+export interface ScopeMemoryStatus {
+    /** `memory.current`. */
+    currentBytes: number;
+    /** `memory.high` — null for `max`. */
+    highBytes: number | null;
+    /** `memory.max` — null for `max`. */
+    maxBytes: number | null;
+    /** `memory.swap.current`, 0 where the file is missing. */
+    swapCurrentBytes: number;
+    /** `memory.events` `high`: how many times the brake engaged. Cumulative. */
+    highEvents: number;
+    /** `memory.events` `oom_kill`: processes the kernel killed in here. Cumulative. */
+    oomKills: number;
+    /**
+     * `memory.events` `oom`: how many times THIS cgroup's own limit was reached
+     * and an allocation was about to fail.
+     *
+     * The discriminator between «this session hit its wall» and «the pool over
+     * all sessions ran out and the kernel picked a victim anywhere in it».
+     * Measured on this host: the innocent neighbour that was killed read
+     * `max 0, oom 0, oom_kill 1`, while the slice read `max 19, oom 1,
+     * oom_kill 1`. Without it every kill was reported to the session it landed
+     * on as «you went over your ceiling», which for a neighbour is false.
+     */
+    ownLimitOom: number;
+}
+/**
+ * The pure half of {@link readScopeMemoryStatus}: the four files' text in, the
+ * status out. `memory.swap.current` is optional (no swap controller, cgroup v2
+ * without swap accounting); the rest are not.
+ */
+export declare function parseScopeMemoryStatus(files: {
+    current: string;
+    high: string;
+    max: string;
+    events: string;
+    swapCurrent?: string;
+}): ScopeMemoryStatus | null;
+/**
+ * What one live session's cgroup holds and has been through. Null when the
+ * cgroup is not there (the scope ended, or this machine has no cage).
+ *
+ * Filesystem, not `systemctl show`: this runs on the supervisor's 30 s tick for
+ * every live session, and the bus is the thing that took 2.7 s under load.
+ */
+export declare function readScopeMemoryStatus(unit: string, readFile?: (p: string) => string): ScopeMemoryStatus | null;
+export declare function markScopeOomKillsSeen(id: string, oomKills: number): void;
+/**
+ * «a process in it was stopped» / «3 processes in it were stopped», so the verb
+ * agrees. Shared with the supervisor's feed notices, which count the same
+ * thing and must not word it differently.
+ */
+export declare function stoppedProcesses(count: number, where?: 'it' | 'this one'): string;
+/**
+ * Snapshot the cgroup's verdict before systemd can take it away.
+ *
+ * Exported for the test seam only (`readStatus`): the real caller passes
+ * nothing and reads the live cgroup.
+ */
+export declare function rememberDeath(id: string, unit: string, readStatus?: (unit: string) => ScopeMemoryStatus | null): void;
+/**
+ * One sentence for the error the person reads, when the kernel had a hand in
+ * this death — or null when it had not. Consumed: a session restarted after an
+ * OOM must not carry the old sentence into its next, unrelated failure.
+ *
+ * The text that reached people in 0.54.0 was «exited with code 143» once and
+ * «terminated by signal SIGKILL» the next time, for the same cause, and neither
+ * said the word memory. This is that word.
+ */
+export declare function explainMemoryDeath(id: string): string | null;
 /** So the sweeper and the reader can be tested without a machine under them. */
 export type Systemctl = (args: string[]) => Promise<{
     stdout: string;
@@ -263,6 +473,13 @@ export type Systemctl = (args: string[]) => Promise<{
  * startable in the meantime.
  */
 export declare function releaseSessionScope(unit: string | null, id?: string, systemctl?: Systemctl): Promise<string | null>;
+/**
+ * The sentence for a death, once the verdict is in. Null when the kernel had no
+ * hand in it. Waits for the release of this session's scope, but never longer
+ * than `capMs`: an answer that arrives after the person has read the error is
+ * worth nothing, and a hung `systemctl` must not hold a failing session open.
+ */
+export declare function memoryDeathSentence(id: string, capMs?: number): Promise<string | null>;
 /** Unit names of every `devbridge-session-*.scope` systemd still knows about. */
 export declare function listSessionScopeUnits(systemctl?: Systemctl): Promise<string[]>;
 export interface SessionScopeInfo {