@bridge4dev/runner 0.56.0 → 0.58.1

package/dist/session-cage.d.ts

@@ -94,6 +94,14 @@ export interface SessionCageFacts {
      * `--scope` was off by default there anyway.
      */
     expandEnvironmentFlag: boolean;
+    /**
+     * Does this systemd take `MemoryLow=` on a scope? (#398 S3)
+     *
+     * False means the machine keeps its cage and loses only the guarantees — the
+     * brake and the wall are unaffected. Probed rather than assumed, because a
+     * `-p` systemd refuses makes `systemd-run` spawn nothing at all.
+     */
+    memoryLowFlag: boolean;
 }
 /**
  * The FLOOR the plan's formula does not have, and the reason it needs one.
@@ -118,6 +126,36 @@ export interface SessionCageFacts {
  * (QA-2026-09-07 MINOR-6, where the earlier wording promised the opposite).
  */
 export declare const SESSION_MEMORY_HIGH_MIN_BYTES: number;
+/**
+ * The gap between the brake and the wall, and never less than this (#398 S2).
+ *
+ * The brake is where the kernel starts reclaiming; the wall is where it kills.
+ * With the two at the same number there is no brake at all — that is the 0.54.0
+ * kill line, and #387 is the whole story of what it costs. So every path that
+ * computes the pair keeps at least a band between them, and the band is also
+ * the step by which the stall detector may raise a brake.
+ *
+ * 256 MiB is sized against what one `tsc` of this monorepo holds (~400 MB
+ * measured) divided by the overshoot a build makes in one 5 s window: enough
+ * room for the allocation that was refused, not enough to hide a runaway.
+ *
+ * {@link sessionMemoryBandBytes} widens it on the machines where reaching the
+ * wall costs the whole session rather than one process — see there.
+ */
+export declare const SESSION_MEMORY_BAND_BYTES: number;
+/**
+ * The band on THIS machine.
+ *
+ * Where the probe found no `OOMPolicy=continue` (systemd 249 and friends), a
+ * kill inside the scope stops the whole scope: the session dies, not one
+ * process. The band there is not a nicety but the only warning the session
+ * gets, so it is a quarter of the brake and never under 512 MiB.
+ *
+ * Two of the fleet's fifteen caged machines answer `sessionOomContinue: false`
+ * (`search aigain`, `trizailab`, measured 10.09.2026), so this is not a
+ * hypothetical branch.
+ */
+export declare function sessionMemoryBandBytes(brakeBytes: number, oomContinue: boolean): number;
 /**
  * The wall, when nothing on the machine can say where it should be.
  *
@@ -293,6 +331,7 @@ export interface CageProbe {
     probeMemoryMax: (options: {
         expandEnvironmentFlag: boolean;
         oomPolicyFlag: boolean;
+        memoryLowFlag: boolean;
     }) => Promise<CageProbeResult>;
     /** `MemoryMax` of the runner service in bytes; null for `infinity`. */
     serviceMemoryMax: () => Promise<number | null>;
@@ -328,6 +367,8 @@ export declare function detectSessionCage(probe?: CageProbe): Promise<SessionCag
  * must not be retried into a cage with a weaker policy.
  */
 export declare function refusesOomPolicy(error: string): boolean;
+/** The same question for `MemoryLow=`, and the same wording from systemd. */
+export declare function refusesMemoryLow(error: string): boolean;
 /**
  * Probe once, at daemon start, and remember the answer.
  *
@@ -335,7 +376,9 @@ export declare function refusesOomPolicy(error: string): boolean;
  * three sessions starting at once would mean three throwaway scopes before the
  * first agent got a word out.
  */
-export declare function initSessionCage(probe?: CageProbe): Promise<SessionCageFacts>;
+export declare function initSessionCage(probe?: CageProbe, options?: {
+    keepCageIfWorse?: boolean;
+}): Promise<SessionCageFacts>;
 /** What the last {@link initSessionCage} found; the safe default before it ran. */
 export declare function sessionCage(): SessionCageFacts;
 export interface CagedSpawn {
@@ -351,6 +394,10 @@ export interface CagedSpawn {
 }
 /** 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;
+/** Remember which process is the agent of this session. */
+export declare function noteSessionAgentPid(id: string, pid: number | undefined): void;
+/** The agent's pid for a live session, or null when nothing has said. */
+export declare function sessionAgentPid(id: string): number | null;
 /**
  * Wrap a command in its session's cage, or hand it back untouched.
  *
@@ -363,12 +410,30 @@ export declare function sessionScopeUnitOf(id: string): string | null;
  * spawn, because `systemd-run --scope` execs into the SAME pid — verified in the
  * spike, including `detached: true` + `process.kill(-pid)` in `verify.ts`
  * (`pgid === child.pid` still holds).
+ *
+ * Untouched is also the answer for a process that has no right to put units on
+ * this machine (#403). It is the mildest of the doors in `cage-authority.ts`:
+ * the command still runs, it simply runs uncaged, which is exactly what happens
+ * on every machine without cgroups.
  */
 export declare function cageSpawn(input: {
     id: string;
     command: string;
     args: string[];
 }): CagedSpawn;
+/**
+ * The command line itself, with no question of who is allowed to run it.
+ *
+ * Split out from {@link cageSpawn} so the shape of the line stays testable: the
+ * suite proves what `systemd-run` would be handed, and the door above proves
+ * who may hand it. One function could not do both — a test process legitimately
+ * needs the first answer and must never get the second.
+ */
+export declare function buildCagedSpawn(input: {
+    id: string;
+    command: string;
+    args: string[];
+}): CagedSpawn;
 /**
  * Did this process die in the window before `systemd-run` handed over?
  *
@@ -424,6 +489,14 @@ export declare function parseScopeMemoryStatus(files: {
     events: string;
     swapCurrent?: string;
 }): ScopeMemoryStatus | null;
+/**
+ * Where a session scope's cgroup lives, or null off a user manager.
+ *
+ * Exported for `session-stall.ts`, which reads three more files out of the same
+ * directory (`memory.pressure`, `memory.stat`, `cgroup.procs`). One resolver,
+ * so the two modules can never disagree about which cgroup a session is in.
+ */
+export declare function scopeCgroupDir(unit: string): string | 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).
@@ -432,6 +505,122 @@ export declare function parseScopeMemoryStatus(files: {
  * 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;
+/** What one session's cgroup holds, split into «can be given back» and «cannot». */
+export interface ScopeHold {
+    /** `memory.current`. */
+    currentBytes: number;
+    /** `memory.current − (file − shmem)` — the part a lower limit cannot reclaim. */
+    holdBytes: number;
+}
+/**
+ * What a live session holds, for the allocator (#398 S3).
+ *
+ * `readCgroupMemory` rather than a second parser: it already takes page cache
+ * out and puts `shmem` back, which is the difference between «cache we can give
+ * back» and «memory something would have to be killed for», and getting that
+ * wrong inflates every number by whatever the machine happened to have cached
+ * (measured at +19 % on this host).
+ */
+export declare function readScopeHold(unit: string): ScopeHold | null;
+/** What systemd has in force over ALL sessions together, read live off cgroupfs. */
+export interface SliceLimits {
+    /** `memory.max` of the slice — the pot. Null for `max`. */
+    potBytes: number | null;
+    /**
+     * `memory.high` of the slice — the COLLECTIVE brake, and the invariant the
+     * allocator's overselling rests on. Null for `max`, which means there is none.
+     */
+    collectiveBrakeBytes: number | null;
+    /**
+     * `memory.low` of the slice — is the GUARANTEE in force at all (#398 S7, B3)?
+     *
+     * The card and the agent's prompt both promise every session two gigabytes
+     * that will not be reclaimed, and nothing on this machine ever checked that
+     * the promise was written: measured on vmi3201430 on 10.09.2026, this file
+     * held `0` while the chip said «2.0 GB guaranteed». Zero is not «unknown» —
+     * it is the kernel's way of saying there is no protection here.
+     */
+    guaranteeBytes: number | null;
+}
+/**
+ * The slice's own two limits, from the filesystem rather than the bus.
+ *
+ * Live on purpose. What the probe found at daemon start is a snapshot, and the
+ * pot moves: the hourly `repairResourceLimits` rewrites it from a fresh
+ * measurement, and a machine whose neighbours grew or shrank gets a different
+ * number. Reading two small files on the tick costs nothing and cannot be stale;
+ * a `systemctl show` would cost a bus call measured at 2.7 s under load.
+ */
+export declare function readSliceLimits(readFile?: (p: string) => string): SliceLimits | null;
+/**
+ * Where `devbridge-sessions.slice` lives on this machine.
+ *
+ * Two ways of answering, and the second is what makes this usable from a
+ * command the operator typed. The first is the reader's own cgroup, which is
+ * exact whenever the reader is under the user manager. The second builds the
+ * path from the user id, exactly as `userManagerCgroupControllers()` already
+ * does — a `systemd-run` scope, a login session and a bare shell all get the
+ * right answer that way, and the daemon gets the same one either way.
+ */
+export declare function sessionsSliceCgroupDir(io?: {
+    selfCgroup?: () => string | null;
+    exists?: (p: string) => boolean;
+    /** The uid of THIS process — injected so a test does not depend on who runs it. */
+    selfUid?: () => number;
+    ownerUid?: () => number;
+}): string | null;
+/**
+ * The three numbers a session's scope should be started with, when something
+ * knows better than the daemon-start snapshot (#398 S3, work 9).
+ *
+ * Registered by the supervisor, which owns the allocator. Without it every new
+ * session would spend its first half-minute on the old `pot / 3` formula and
+ * then jump to the new one on the first tick — visible, unexplainable, and
+ * exactly the kind of thing that gets reported as a bug.
+ *
+ * A plain module-level hook rather than an import, because the allocator imports
+ * THIS module and the cycle would be real.
+ */
+export interface LiveLadder {
+    highBytes: number;
+    maxBytes: number;
+    swapBytes: number;
+    guaranteedBytes: number;
+}
+export declare function setLiveLadderSource(source: ((id: string) => LiveLadder | null) | null): void;
+/**
+ * The two numbers this session may be TOLD about (#398 S5).
+ *
+ * The guarantee and the ceiling, and deliberately not the live share. The share
+ * is recomputed every 30 s, so any value of it put into an environment variable
+ * or into a system prompt is stale within half a minute — and a number the agent
+ * believes and acts on after it has stopped being true is worse than no number.
+ * The guarantee is a constant of the formula and the ceiling barely moves.
+ *
+ * Null on a machine with no cage: there is nothing to promise there, and «нет
+ * cgroup — держим ноль» (#257) means we say nothing rather than invent a limit.
+ */
+export declare function sessionMemoryFor(id: string): {
+    guaranteedBytes: number;
+    maxBytes: number;
+    swapBytes: number;
+} | null;
+/**
+ * What the agent is told, and how — one text for both CLIs (#398 S5).
+ *
+ * A shared builder rather than two literals for the reason `DIRECT_BRANCH_RULE`
+ * in `adapters/types.ts` is shared: the two system-prompt appends are hand-kept
+ * copies of one another, and a third place for them to diverge was not worth
+ * having.
+ *
+ * The live share is named as something the agent CANNOT know, on purpose. Half
+ * of the incident this whole plan comes from was an agent raising its own heap
+ * twice — to 4 GB, then to 6 GB, against a wall of 4296 MB — because nothing
+ * had ever told it there was a wall.
+ */
+export declare function sessionMemoryEnv(id: string): Record<string, string>;
+/** The sentence for the system prompt, or null on a machine with no cage. */
+export declare function sessionMemoryPromptLine(id: string): string | 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
@@ -503,8 +692,46 @@ export declare function listSessionScopes(systemctl?: Systemctl): Promise<Sessio
  * `liveIds` exists so the same sweep can run later without killing work in
  * progress; only the CURRENT scope of a live session is spared, because an
  * earlier attempt of the same session is exactly the leftover we are here for.
+ *
+ * **Everything in {@link liveUnits} is spared too, whatever the caller passed.**
+ * A session is not the only thing that puts a scope under this prefix: a
+ * `verify` run cages itself as `verify-<runId>` (`verify.ts`), and a caller
+ * that hands over its list of SESSIONS would have the sweep stop a check that
+ * is running — a new bug in place of the old one. `liveUnits` is filled by
+ * `cageSpawn` and emptied by `releaseSessionScope`, so it is the full register
+ * of live cages regardless of who opened them; at daemon start it is empty by
+ * construction, which is exactly why the sweep there still takes everything.
+ */
+/**
+ * Who, if anybody, is alive inside a cage — asked of the kernel rather than of
+ * this process's own memory (#403).
+ *
+ * The sweep used to decide by `liveUnits`, which is a register of what THIS
+ * process started. In the daemon that is right; in any other process it is
+ * empty by construction, and «not in my register» then means «the whole
+ * machine». That inversion is what stopped three people's sessions on
+ * 10.09.2026.
+ *
+ * The cgroup answers the question properly, and it answers the same for
+ * everybody:
+ *
+ *  - `empty`            — no processes at all: nothing to stop, only a name to
+ *                         free (`reset-failed`).
+ *  - `orphaned`         — processes whose parent is gone (`PPid` 1 or 0, or a
+ *                         parent that no longer exists). This is the shape the
+ *                         sweep exists for: a scope that outlived the daemon
+ *                         that started it, carrying a `ugrep` for 10 h 51 min.
+ *  - `owned`            — a live parent outside the cage is supervising them.
+ *                         Somebody's session, and not ours to end.
+ *  - `unknown`          — `/proc` would not say. Left alone, loudly.
  */
-export declare function sweepOrphanSessionScopes(liveIds?: Iterable<string>, systemctl?: Systemctl): Promise<string[]>;
+export type ScopeLiveness = 'empty' | 'orphaned' | 'owned' | 'unknown';
+export declare function scopeOwnerLiveness(unit: string, io?: {
+    readFile?: (p: string) => string;
+    cgroupDir?: (unit: string) => string | null;
+    isAlive?: (pid: number) => boolean;
+}): ScopeLiveness;
+export declare function sweepOrphanSessionScopes(liveIds?: Iterable<string>, systemctl?: Systemctl, liveness?: (unit: string) => ScopeLiveness): Promise<string[]>;
 /**
  * The slice names and the CPU share — re-exported so a caller that reasons about
  * the cage needs one import, while the values themselves stay next to the