@bridge4dev/runner 0.53.0 → 0.55.0

package/dist/session-cage.d.ts

@@ -0,0 +1,508 @@
+import { DEVBRIDGE_SLICE, SESSION_CPU_WEIGHT, SESSIONS_SLICE } from './service-unit.js';
+/**
+ * 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/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
+ *    `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_HIGH_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;
+    /**
+     * 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;
+    /**
+     * 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_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.
+ *
+ * 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 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.
+ *
+ * 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;
+        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;
+}
+/**
+ * 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>;
+/**
+ * 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.
+ *
+ * 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;
+}
+/** 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.
+ *
+ * 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;
+/** 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;
+/**
+ * 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;
+    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>;
+/**
+ * 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 {
+    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