@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/session-cage.d.ts

@@ -0,0 +1,297 @@
+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.**
+ *
+ * `min(2.5 GiB, service ceiling / 2)` — §3 of
+ * `docs/plans/active/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
+ *    `pnpm typecheck`, measured at a 1571 MB peak; three live `claude`
+ *    processes are 512/577/646 MB. 2.5 GiB leaves ~60 % headroom over the
+ *    worst measured case, which is the margin between "kills a runaway" and
+ *    "kills the work";
+ *  - the half-of-the-service half is what keeps ONE session from being able to
+ *    fill the ceiling that covers all of them. On this machine the service
+ *    ceiling is 7680M, so half is 3.75 GiB and the absolute number wins.
+ *
+ * The service ceiling is read off systemd (`systemctl --user show
+ * devbridge-runner -p MemoryMax`) rather than recomputed here, because what
+ * 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;
+/**
+ * Processes and threads per session.
+ *
+ * An agent forks a lot (a monorepo build is hundreds of short-lived processes),
+ * so this is not a memory limit in disguise — it is the fork-bomb stop. 512 is
+ * far above anything measured on a real session and far below the 8192 the
+ * whole service gets.
+ */
+export declare const SESSION_TASKS_MAX = 512;
+/** Prefix of every scope this module creates. The sweeper matches on it. */
+export declare const SESSION_SCOPE_PREFIX = "devbridge-session-";
+/**
+ * How the sessions on this machine are contained.
+ *
+ * `scope`     — a cgroup per session with a memory ceiling (this module).
+ * `nice-only` — cgroup v2 is not usable here; stage 1a's `nice(2)` is all there
+ *               is. Correct on cgroup v1/hybrid (Ubuntu 20.04, CentOS 7/8) and
+ *               under a foreign supervisor.
+ * `none`      — not even that: the kernel refuses `setpriority` as well.
+ *
+ * Travels in `hello` as `machine.sessionCage` so the dashboard can SAY that the
+ * containment did not take on a given machine, instead of leaving it to be
+ * guessed (plan §5.4.3).
+ */
+export type SessionCageMode = 'scope' | 'nice-only' | 'none';
+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'`. */
+    memoryMaxBytes: number | null;
+    /** The service ceiling systemd has in force, as measured. Null = infinity. */
+    serviceMemoryMaxBytes: number | null;
+    /**
+     * The ceiling over ALL sessions together, as systemd has it in force on
+     * `devbridge-sessions.slice`. Null means there is none.
+     *
+     * Read rather than assumed, because the live probe proves only the PERSONAL
+     * ceiling: a `MemoryMax` on a scope applies whatever the parent slice says. A
+     * machine whose `daemon-reload` never happened therefore passed the probe,
+     * announced `sessionCage: 'scope'` and `limitsCurrent: true`, and had three
+     * sessions of 2.5 GB each over a slice at `MemoryMax=infinity` — with the card
+     * saying «Sessions capped» (QA-2026-09-07 MAJOR-3).
+     */
+    sessionsSliceMemoryMaxBytes: number | null;
+    /**
+     * Is `--expand-environment=no` on the command line? systemd ≥ 254 only — see
+     * the module header. False is not a downgrade below 254: expansion in
+     * `--scope` was off by default there anyway.
+     */
+    expandEnvironmentFlag: boolean;
+}
+/**
+ * The FLOOR the plan's formula does not have, and the reason it needs one.
+ *
+ * `min(2.5 GiB, ceiling / 2)` is right on a big machine and wrong on a small
+ * one: at the 2 GiB ceiling `memoryPolicy` gives the smallest supported box,
+ * half is 1 GiB — BELOW the 1571 MB a workspace `pnpm typecheck` was measured
+ * at. The cage would then kill honest work on exactly the machines least able
+ * to afford a failed run, and it would look like a flaky agent rather than a
+ * limit. A containment that fires on correct work is not containment.
+ *
+ * So the floor is set above the worst measured ordinary peak, not at a round
+ * number.
+ *
+ * It is a floor and not a switch: below ~2.4 GB of RAM the containing ceiling
+ * itself drops under this number, and there the last clamp in
+ * {@link sessionMemoryMaxBytes} wins and a session is capped below the floor.
+ * That is not the cage killing honest work — the slice would have killed the
+ * same `pnpm typecheck` a moment later anyway, because it holds the same
+ * number — so removing `MemoryMax` from the scope there would buy nothing and
+ * 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;
+/**
+ * `clamp(ceiling / 2, 2 GiB, 2.5 GiB)`, never above the ceiling itself.
+ *
+ * Three bounds, each for its own reason — see
+ * {@link SESSION_MEMORY_MAX_ABSOLUTE_BYTES} for the upper two and
+ * {@link SESSION_MEMORY_MIN_BYTES} for the lower one. The last clamp matters
+ * on a tiny machine: a per-session number ABOVE the slice's own ceiling is not
+ * a limit at all, it is a bigger number that never applies, and printing it in
+ * `doctor` would be a straight lie about what is in force.
+ *
+ * The argument is the ceiling of the cgroup that CONTAINS the session, and
+ * since 0.54.0 that is `devbridge-sessions.slice` and not the service — the
+ * caller reads the slice and falls back to the service only when systemd has
+ * nothing to say about the slice. The two are the same number by construction
+ * today; they come apart the moment a drop-in fails to apply or is edited by
+ * 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;
+/**
+ * The session id as systemd will accept it.
+ *
+ * Ids are UUIDs today and arbitrary text tomorrow — they arrive from the API,
+ * and `verify` keys its cage by a run id. systemd unit names take only
+ * `[A-Za-z0-9:_.-]`, so everything else is folded to `-`. Folding is lossy, and
+ * lossy is how two different sessions end up fighting over one scope, so
+ * anything that had to be changed or cut also gets eight hex digits of the
+ * original — deterministic, so the same session always names the same unit and
+ * the sweeper can still recognise it.
+ */
+export declare function sanitizeCageId(id: string): string;
+/**
+ * The scope unit for one START of one session.
+ *
+ * `attempt` is not decoration. A scope the OOM killer took stays loaded in
+ * `failed` until something resets it, and `systemd-run --unit=` on a name that
+ * is still loaded fails outright — measured: «Unit devbridge-….scope was
+ * already loaded or has a fragment file», exit 1, nothing spawned. So a session
+ * that is restarted after an OOM (which is exactly when it IS restarted) would
+ * be unable to start at all if the name never changed.
+ * {@link releaseSessionScope} clears the failed unit and only then lets the
+ * counter fall back to 1, so the plain `devbridge-session-<id>.scope` is the
+ * normal case and the marker appears only while the old scope is still there.
+ */
+export declare function sessionScopeUnit(id: string, attempt?: number): string;
+/**
+ * The systemd release that added `--expand-environment=`.
+ *
+ * Below it `systemd-run` answers `unrecognized option` and exits 1 — the probe
+ * then reads as «the cage did not hold» on a machine whose cgroups are perfect
+ * (Ubuntu 22.04 is 249, Debian 12 and RHEL 9 are 252). See the module header for
+ * why the flag is not needed there either.
+ */
+export declare const EXPAND_ENVIRONMENT_MIN_SYSTEMD = 254;
+/** What one run of the throwaway scope answered, and why it did not run. */
+export interface CageProbeResult {
+    /** `memory.max` as the scope read it back. Null when the scope never ran. */
+    memoryMax: string | null;
+    /** `systemd-run`'s own first line of complaint. Null when it ran. */
+    error: string | null;
+}
+/** Everything about this machine the detector needs, so a test can lie about all of it. */
+export interface CageProbe {
+    /** `cgroup2fs`, `tmpfs`, or whatever else is mounted at `/sys/fs/cgroup`. */
+    cgroupFsType: () => string | null;
+    systemdRunOnPath: () => boolean;
+    /** Major version of `systemd-run`, or null when it would not say. */
+    systemdRunVersion: () => Promise<number | null>;
+    /** `$XDG_RUNTIME_DIR` when `$XDG_RUNTIME_DIR/bus` exists, else null. */
+    userBusPath: () => string | null;
+    /** Controllers delegated to this user's manager, or null when unreadable. */
+    delegatedControllers: () => string[] | null;
+    /** The one-shot scope that reads its own `memory.max`, built like a real one. */
+    probeMemoryMax: (options: {
+        expandEnvironmentFlag: 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>;
+    /** Can this kernel renice at all — the fallback's own precondition. */
+    canRenice: () => boolean;
+}
+/**
+ * Variables the child needs to reach the user's systemd, and nothing else.
+ *
+ * `systemd-run --user` finds the bus through `XDG_RUNTIME_DIR` (sd-bus falls
+ * back to `$XDG_RUNTIME_DIR/bus` when `DBUS_SESSION_BUS_ADDRESS` is unset), and
+ * that variable is already on both spawn allowlists — so merging this into a
+ * session's environment widens nothing. `DBUS_SESSION_BUS_ADDRESS` is passed on
+ * only when the daemon really has one of its own, never synthesised.
+ */
+export declare function cageEnv(): Record<string, string>;
+export declare const defaultCageProbe: CageProbe;
+export declare function detectSessionCage(probe?: CageProbe): Promise<SessionCageFacts>;
+/**
+ * Probe once, at daemon start, and remember the answer.
+ *
+ * The probe costs a process, so it is not something a spawn can afford to do:
+ * 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>;
+/** What the last {@link initSessionCage} found; the safe default before it ran. */
+export declare function sessionCage(): SessionCageFacts;
+export interface CagedSpawn {
+    command: string;
+    args: string[];
+    /**
+     * Variables to MERGE into the child's environment (`{...yours, ...cage.env}`).
+     * Empty when nothing was wrapped.
+     */
+    env: Record<string, string>;
+    /** The scope unit this start will live in, or null when nothing was wrapped. */
+    unit: string | null;
+}
+/**
+ * Wrap a command in its session's cage, or hand it back untouched.
+ *
+ * Untouched is the honest answer on every machine where the cage was not proved
+ * to work: `systemd-run` would accept the flags there and apply nothing, and a
+ * session that believes it is contained when it is not is worse than one that
+ * knows it is not.
+ *
+ * Pipes, exit codes, signals and stdin EOF behave exactly as with a direct
+ * 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).
+ */
+export declare function cageSpawn(input: {
+    id: string;
+    command: string;
+    args: string[];
+}): CagedSpawn;
+/**
+ * Did this process die in the window before `systemd-run` handed over?
+ *
+ * Starting a scope took 0.07–2.5 s in the spike, and 2741 ms on a loaded
+ * machine. A stop inside that window signals `systemd-run` itself, before the
+ * `exec`, and the parent sees `{code: null, signal: 'SIGTERM'}` with nothing on
+ * stdout at all. That is «the session never started», not «the agent died
+ * silently» — told apart here so no supervisor has to infer it from an empty
+ * buffer.
+ */
+export declare function killedBeforeExec(info: {
+    code: number | null;
+    signal: string | null;
+    sawOutput: boolean;
+    caged: boolean;
+}): boolean;
+/** So the sweeper and the reader can be tested without a machine under them. */
+export type Systemctl = (args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Read why the scope ended, say so, and then let systemd forget it.
+ *
+ * This is the whole reason `--collect` is not passed. The order is fixed: the
+ * process has already exited, `Result` is read, the reason is logged, and only
+ * then is the unit reset — because `reset-failed` is what deletes the answer.
+ *
+ * Failure here is never fatal: a unit that could not be reset is swept at the
+ * next daemon start, and the counter in {@link cageSpawn} keeps the session
+ * startable in the meantime.
+ */
+export declare function releaseSessionScope(unit: string | null, id?: string, systemctl?: Systemctl): 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 {
+    unit: string;
+    memoryMaxBytes: number | null;
+    memoryCurrentBytes: number | null;
+    tasksCurrent: number | null;
+    result: string | null;
+    activeState: string | null;
+}
+/** What `doctor` prints for each caged session. */
+export declare function listSessionScopes(systemctl?: Systemctl): Promise<SessionScopeInfo[]>;
+/**
+ * Stop and forget every session scope that has no session behind it.
+ *
+ * At daemon start that is all of them by definition, and it is the point: a
+ * scope outlives a killed daemon carrying the whole process tree with it, which
+ * is the shape of the 10 h 51 min `ugrep` of 16.08. Stopping the scope takes the
+ * tree, not just the process we happened to know about.
+ *
+ * `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.
+ */
+export declare function sweepOrphanSessionScopes(liveIds?: Iterable<string>, systemctl?: Systemctl): 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
+ * drop-in that writes them (`service-unit.ts`).
+ */
+export { SESSIONS_SLICE, DEVBRIDGE_SLICE, SESSION_CPU_WEIGHT };
+//# sourceMappingURL=session-cage.d.ts.map