@bridge4dev/runner 0.56.0 → 0.58.1

package/dist/session-limits.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The live memory numbers this machine reports (#398 S4).
+ *
+ * Mirror of `packages/shared/src/schemas/session-limits.ts` — the DevBridge side
+ * is the source of truth, exactly like `host-load.ts` mirrors the load frame and
+ * `levels.ts` mirrors the level thresholds. Copied rather than imported on
+ * purpose: this package is published to npm on its own and installed on machines
+ * that have never heard of `@devbridge/shared`.
+ *
+ * CHECKED: `session-limits.test.ts` reads the shared file and compares every
+ * field below against it, so a change on one side that is not made on the other
+ * turns a test red instead of turning a card blank.
+ */
+/** One session's three numbers, as they leave the machine. */
+export interface SessionLimitsEntry {
+    sessionId: string;
+    guaranteedBytes: number;
+    brakeBytes: number;
+    wallBytes: number;
+    holdBytes: number;
+    /** This session's guarantee does not fit in the pot beside the others (D9). */
+    tight: boolean;
+    /** Milliseconds until its biggest command is stopped; null when it is moving. */
+    stallRemainingMs: number | null;
+    /** Why its limits last moved. */
+    reason: 'added' | 'stopped-command' | 'nothing-to-stop' | 'report-only' | null;
+}
+export interface SessionLimitsFrame {
+    at: string;
+    poolBytes: number;
+    heldBytes: number;
+    otherHeldBytes: number;
+    /** What one session is guaranteed here — the constant, so a card with no
+     *  session on it can still name the number. */
+    guaranteeBytes: number;
+    /** The brake a session starting right now would get — the card cannot derive it. */
+    sessionCeilingBytes: number;
+    guaranteesFit: number;
+    seats: number;
+    swapPerSessionBytes: number;
+    collectiveBrake: boolean;
+    conservative: boolean;
+    hungry: boolean;
+    sessions: SessionLimitsEntry[];
+}
+/** Mirror of `SESSION_LIMITS_HEARTBEAT_MS`. */
+export declare const SESSION_LIMITS_HEARTBEAT_MS = 60000;
+/** Mirror of `SESSION_LIMITS_MIN_DELTA_RATIO`. */
+export declare const SESSION_LIMITS_MIN_DELTA_RATIO = 0.1;
+/**
+ * Is this frame different enough from the last one to be worth the socket?
+ *
+ * The allocator runs every 30 s and its numbers breathe with the machine, so
+ * without a gate this would be a write per machine per half-minute for a card
+ * nobody is looking at. What counts as a change:
+ *
+ *  - anything about WHO is on the machine — a session appearing or leaving, or
+ *    a session's limits actually being rewritten. Those are the moments a person
+ *    would notice, and no ratio must be able to hide them;
+ *  - a state that a person acts on — the deadline appearing or disappearing, the
+ *    crowding flag, the collective brake going missing;
+ *  - and otherwise a tenth of the pot, which is the same dead zone the allocator
+ *    uses before it will write to a scope at all.
+ */
+export declare function sessionLimitsChangedEnough(previous: SessionLimitsFrame | null, next: SessionLimitsFrame): boolean;
+/**
+ * Is a heartbeat due? Same shape and same reason as `hostLoadHeartbeatDue`: a
+ * backwards clock step is «due», not «early».
+ */
+export declare function sessionLimitsHeartbeatDue(sinceLastSentMs: number, heartbeatMs: number): boolean;
+//# sourceMappingURL=session-limits.d.ts.map

package/dist/session-limits.js

@@ -0,0 +1,93 @@
+/**
+ * The live memory numbers this machine reports (#398 S4).
+ *
+ * Mirror of `packages/shared/src/schemas/session-limits.ts` — the DevBridge side
+ * is the source of truth, exactly like `host-load.ts` mirrors the load frame and
+ * `levels.ts` mirrors the level thresholds. Copied rather than imported on
+ * purpose: this package is published to npm on its own and installed on machines
+ * that have never heard of `@devbridge/shared`.
+ *
+ * CHECKED: `session-limits.test.ts` reads the shared file and compares every
+ * field below against it, so a change on one side that is not made on the other
+ * turns a test red instead of turning a card blank.
+ */
+/** Mirror of `SESSION_LIMITS_HEARTBEAT_MS`. */
+export const SESSION_LIMITS_HEARTBEAT_MS = 60_000;
+/** Mirror of `SESSION_LIMITS_MIN_DELTA_RATIO`. */
+export const SESSION_LIMITS_MIN_DELTA_RATIO = 0.1;
+/**
+ * Is this frame different enough from the last one to be worth the socket?
+ *
+ * The allocator runs every 30 s and its numbers breathe with the machine, so
+ * without a gate this would be a write per machine per half-minute for a card
+ * nobody is looking at. What counts as a change:
+ *
+ *  - anything about WHO is on the machine — a session appearing or leaving, or
+ *    a session's limits actually being rewritten. Those are the moments a person
+ *    would notice, and no ratio must be able to hide them;
+ *  - a state that a person acts on — the deadline appearing or disappearing, the
+ *    crowding flag, the collective brake going missing;
+ *  - and otherwise a tenth of the pot, which is the same dead zone the allocator
+ *    uses before it will write to a scope at all.
+ */
+export function sessionLimitsChangedEnough(previous, next) {
+    if (previous === null)
+        return true;
+    if (previous.sessions.length !== next.sessions.length)
+        return true;
+    if (previous.collectiveBrake !== next.collectiveBrake ||
+        previous.conservative !== next.conservative ||
+        previous.hungry !== next.hungry ||
+        previous.guaranteeBytes !== next.guaranteeBytes ||
+        // Exact, and it can be: since #403 this is the ceiling of an IDLE machine,
+        // computed from the pot and the owner's knobs alone. It does not follow
+        // `MemAvailable`, so it does not breathe, and any move in it is a fact
+        // worth a frame. (While it was the live ceiling of the current crowd, this
+        // line sent one every thirty seconds from every machine.)
+        previous.sessionCeilingBytes !== next.sessionCeilingBytes ||
+        previous.guaranteesFit !== next.guaranteesFit ||
+        previous.seats !== next.seats ||
+        previous.swapPerSessionBytes !== next.swapPerSessionBytes) {
+        return true;
+    }
+    const before = new Map(previous.sessions.map((s) => [s.sessionId, s]));
+    for (const session of next.sessions) {
+        const was = before.get(session.sessionId);
+        if (!was)
+            return true;
+        if (was.tight !== session.tight ||
+            was.reason !== session.reason ||
+            // «A countdown is running» and «it is not» are different states; the exact
+            // number of seconds left is not, or the strip would repaint every tick.
+            (was.stallRemainingMs === null) !== (session.stallRemainingMs === null)) {
+            return true;
+        }
+        if (was.guaranteedBytes !== session.guaranteedBytes ||
+            was.brakeBytes !== session.brakeBytes ||
+            was.wallBytes !== session.wallBytes) {
+            // The allocator has its own dead zone before it writes, so a limit that
+            // moved at all is a limit worth reporting.
+            return true;
+        }
+    }
+    const base = Math.max(1, previous.poolBytes);
+    if (Math.abs(next.poolBytes - previous.poolBytes) / base >= SESSION_LIMITS_MIN_DELTA_RATIO) {
+        return true;
+    }
+    if (Math.abs(next.heldBytes - previous.heldBytes) / base >= SESSION_LIMITS_MIN_DELTA_RATIO) {
+        return true;
+    }
+    if (Math.abs(next.otherHeldBytes - previous.otherHeldBytes) / base >=
+        SESSION_LIMITS_MIN_DELTA_RATIO) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Is a heartbeat due? Same shape and same reason as `hostLoadHeartbeatDue`: a
+ * backwards clock step is «due», not «early».
+ */
+export function sessionLimitsHeartbeatDue(sinceLastSentMs, heartbeatMs) {
+    return sinceLastSentMs >= heartbeatMs || sinceLastSentMs < 0;
+}
+//# sourceMappingURL=session-limits.js.map

package/dist/session-stall.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Telling «this session is standing still» from «this session is slow» — and
+ * doing something about it before the night is over (#398 S2, gotcha §480).
+ *
+ * Above `MemoryHigh` the kernel does not kill, it puts the allocating thread to
+ * sleep on the way back to userspace; with `MemorySwapMax=0` there is nothing to
+ * push out, so the penalty is up to 2 s per 256 KB and the process never reaches
+ * `MemoryMax` at all — it simply stops. On 09.09.2026 that cost one session an
+ * hour of silence on a build that printed nothing but its startup warnings.
+ * Ten of the fleet's fifteen caged machines have a session swap of zero, so this
+ * is the ordinary case and not the exotic one.
+ *
+ * The measure is ONE number and it is not the one three earlier drafts reached
+ * for.
+ *
+ *  - **Not CPU.** A process wedged in direct reclaim burns system time in bursts:
+ *    the same stuck process was measured at 3.6 %, 2.9 %, 6.9 %, 18.7 %, 98 %,
+ *    53 %, 22 %, 67 % of one core on consecutive seconds. Any threshold over it
+ *    both misfires and misses.
+ *  - **Not swap.** The first draft counted growth in `memory.swap.current` and
+ *    `pgmajfault` as evidence of progress, out of a fear of killing honest work
+ *    on a machine that swaps. The measurement refuted it: a live session with
+ *    232 MB of swap and 1.3 M major faults stood still for 2 h 15 min out of 18.
+ *    Swap does not separate useful paging from thrashing.
+ *  - **Pressure does.** `memory.pressure`, line `full`, field `total=`, is
+ *    cumulative microseconds during which NO task in the cgroup could run for
+ *    want of memory. Measured on this host: a wedged process, 27.9 s of stall in
+ *    a 27.5 s window (~100 %); a healthy live session, 10.7 s in six hours
+ *    (0.05 %); a session thrashing swap, 8093 s in 18 hours with the share close
+ *    to 1 inside the bad stretches. Three orders of magnitude between honest
+ *    work and a stall, in one number, on every machine that has PSI.
+ *
+ * The second condition is a cheap fuse and it is also a measurement: on a live
+ * scope of this host `anon` was 308 MB against a `memory.current` of 1033 MB
+ * with 9246 brake events — i.e. the brake very often catches page cache, which
+ * the kernel takes back with no stall at all. Those episodes must not reach the
+ * counter, let alone the deadline.
+ */
+/**
+ * One detector window.
+ *
+ * Five seconds, not the watch's thirty: the deadline below is three minutes, and
+ * a measure that needs two consecutive windows would spend a third of the
+ * deadline deciding at the 30 s cadence. Five seconds of `full` stall is also
+ * long enough that a single scheduling hiccup cannot fill it.
+ */
+export declare const STALL_WINDOW_MS = 5000;
+/**
+ * Share of the window spent with nothing in the cgroup able to run, above which
+ * the window counts as a standing one.
+ *
+ * **A fifth, not a half, and the difference was found by measurement.** The plan
+ * this module implements said 50 %, taken from a hard stall that read ~100 %.
+ * Reproducing the incident itself — a cage with a 64 MiB brake and no swap, a
+ * process touching what it allocates — gave four consecutive windows of
+ * **0.766, 0.484, 0.443, 0.542** (10.09.2026, this host). Two of the four sit
+ * BELOW a half: at that line the very shape this mechanism exists for would
+ * trip and clear in turn and never reach its deadline.
+ *
+ * There is room to move the line because the gap is enormous. Measured on the
+ * same host: a healthy live session, 0.0005; honest disk-bound work under the
+ * same 64 MiB brake writing 6.3 GB at 739 MB/s, exactly **0.0** with the brake
+ * never firing at all. A fifth is four hundred times what healthy work shows and
+ * half of what the mildest stalled window did.
+ */
+export declare const STALL_SHARE = 0.2;
+/**
+ * …and the share it has to fall BELOW before a running deadline is cleared.
+ *
+ * Two lines, not one, for the reason the cage watch already had `calmTicks`: a
+ * genuine stall is not a flat number, it breathes. One line means one dip
+ * cancels three minutes of standing still. Half the trip line, and still two
+ * hundred times the 0.0005 healthy work shows.
+ */
+export declare const STALL_SHARE_CLEAR = 0.1;
+/** Consecutive windows over the line before the session counts as standing still. */
+export declare const STALL_WINDOWS_TO_TRIP = 2;
+/**
+ * `(anon + shmem) / memory.current` above which the pressure is about memory the
+ * kernel cannot simply drop. Below it the brake is grinding page cache.
+ */
+export declare const STALL_ANON_SHARE = 0.9;
+/**
+ * How long a standing session is given before its biggest command is stopped
+ * (decision D6 of the plan).
+ *
+ * Three minutes: long enough for a person who is watching to intervene, short
+ * enough that a session which stalls at 02:00 is not still standing at 08:00.
+ * Doubled on a machine without PSI, where the fallback measure below is weaker.
+ */
+export declare const STALL_GRACE_MS = 180000;
+/**
+ * A drop of this much in `memory.current` counts as real progress and clears the
+ * deadline.
+ *
+ * A new line of output does NOT: in the incident the build printed startup
+ * warnings for seventeen minutes while allocating nothing.
+ */
+export declare const STALL_PROGRESS_DROP_BYTES: number;
+/**
+ * How long the detector stays quiet after WE lowered this session's brake.
+ *
+ * Measured on this host: a process honestly writing a file at 6.4 MB/s was
+ * stopped dead the instant its `MemoryHigh` was narrowed on the live scope. Any
+ * lowering therefore manufactures exactly the signal this module looks for, and
+ * without the mute the mechanism would catch its own edit and stop a command for
+ * it. One window plus the deadline, with room to spare.
+ */
+export declare const STALL_MUTE_AFTER_LOWER_MS = 240000;
+/**
+ * Between SIGTERM and SIGKILL for the subtree being stopped.
+ *
+ * Thirty seconds, not five: neither `pnpm install` nor `docker build` can put
+ * its own house in order in five, and half-written state costs the next turn
+ * more than the wait costs this one.
+ */
+export declare const STALL_SIGKILL_AFTER_MS = 30000;
+/**
+ * Growth under which the PSI-less fallback still calls a session stuck:
+ * `min(1 % of the brake, 16 MiB)` per window.
+ */
+export declare const STALL_FALLBACK_GROWTH_BYTES: number;
+/** What one read of a session's cgroup says about whether it is moving. */
+export interface StallSample {
+    /**
+     * `memory.pressure`, line `full`, `total=` — cumulative microseconds with no
+     * task in the cgroup able to run. Null on a kernel built without `CONFIG_PSI`.
+     */
+    pressureFullUs: number | null;
+    /** `memory.events` `high`, cumulative — the fallback measure. */
+    highEvents: number;
+    /** `memory.current`. */
+    currentBytes: number;
+    /** `anon` + `shmem` from `memory.stat` — what cannot simply be dropped. */
+    anonBytes: number;
+    /** `memory.high`, null for `max`. */
+    brakeBytes: number | null;
+    /** When this sample was taken. */
+    at: number;
+}
+/** The detector's memory of one session. Deliberately its own, not `cageWatch`. */
+export interface StallState {
+    /**
+     * Which cgroup these numbers came from. A relaunch gets the same unit NAME
+     * back once the failed unit is reset, so the counters are checked as well:
+     * anything that went backwards is a new cgroup, not a counter that shrank.
+     */
+    unit: string;
+    last: StallSample | null;
+    /** Consecutive windows over the line. */
+    hotWindows: number;
+    /** When the deadline started running; null = this session is not stuck. */
+    stalledSince: number | null;
+    /** `memory.current` when the deadline started — the yardstick for «it moved». */
+    markBytes: number;
+    /** Detection is off until this moment, because we moved the brake ourselves. */
+    mutedUntil: number;
+}
+export declare function freshStallState(unit: string): StallState;
+/**
+ * The pure half: five files' text in, a sample out. Null when `memory.current`
+ * could not be read, which means the cgroup is gone.
+ */
+export declare function parseStallSample(files: {
+    current: string;
+    high: string;
+    events: string;
+    stat: string;
+    pressure?: string;
+}, at: number): StallSample | null;
+/** Read one sample off a live scope. Null when the cgroup is not there. */
+export declare function readStallSample(unit: string, at: number, readFile?: (p: string) => string): StallSample | null;
+/** What the detector decided about one window. */
+export interface StallVerdict {
+    state: StallState;
+    /** Is this session standing still right now? */
+    stuck: boolean;
+    /** Milliseconds left before its biggest command is stopped; null when not stuck. */
+    remainingMs: number | null;
+    /** The deadline has run out — the caller stops a command now. */
+    expired: boolean;
+    /** PSI was unavailable, so the weaker measure was used and the grace doubled. */
+    degraded: boolean;
+}
+/**
+ * One window of the detector, as a pure function of the previous state.
+ *
+ * Everything the caller must not get wrong lives here: two windows before the
+ * counter trips, the anon fuse, the mute after our own edit, and a reset that
+ * only real progress can buy.
+ */
+export declare function stallStep(previous: StallState, sample: StallSample, options?: {
+    graceMs?: number;
+    now?: number;
+    windowMs?: number;
+    /**
+     * Is this the only session in the slice right now (#398 S7, B9)?
+     *
+     * When it is, «somebody else's brake» has no somebody else: the collective
+     * brake on the slice can only have been filled by this session, and the
+     * discriminator below must not read that as innocence.
+     */
+    soleSession?: boolean;
+}): StallVerdict;
+/** One process of a session's cgroup, as `/proc` describes it. */
+export interface ScopeProcess {
+    pid: number;
+    ppid: number;
+    /**
+     * Field 22 of `/proc/<pid>/stat` — the moment this process started, in clock
+     * ticks since boot.
+     *
+     * The identity of a pid, and the reason it is carried: pids are REUSED. A
+     * subtree is asked to stop with SIGTERM and killed thirty seconds later, and
+     * on a busy machine a pid freed in between can belong to something else
+     * entirely by then — so the second signal is checked against this before it
+     * is sent. Found by the independent review of 10.09.2026, which called it the
+     * most dangerous line in the change, and it was right.
+     */
+    startedAtTicks: number;
+    /** `/proc/<pid>/comm` — the executable's name, never its arguments. */
+    comm: string;
+    /** Resident set, bytes, from `/proc/<pid>/statm`. */
+    rssBytes: number;
+    /** Does the command line name an MCP server? Then it is the agent's, not work. */
+    mcp: boolean;
+}
+/** The chosen victim: a whole subtree, named by its heaviest process. */
+export interface KillCandidate {
+    /** Root of the subtree — the process whose whole tree is stopped. */
+    rootPid: number;
+    /** Every pid in that subtree, deepest last. */
+    pids: number[];
+    /**
+     * The same pids with the moment each one started, so the SIGKILL thirty
+     * seconds later can prove it is still signalling the same processes.
+     */
+    identities: Array<{
+        pid: number;
+        startedAtTicks: number;
+    }>;
+    /** The heaviest process in it, by name only — arguments can carry a token. */
+    name: string;
+    /** What the whole subtree holds. */
+    rssBytes: number;
+}
+/**
+ * Anything whose command line says «MCP server» is the agent's own plumbing.
+ *
+ * Deliberately generous, because the direction of a mistake matters: a false
+ * positive costs us a candidate (we stop something smaller, or nothing), a false
+ * negative costs the session its tools mid-turn.
+ *
+ * **Widened after the independent review of 10.09.2026, which found the first
+ * version matched nothing real.** The command lines actually on this machine are
+ * `npm exec @playwright/mcp@latest …` and `node …/playwright-mcp --output-dir …`
+ * — in the first `mcp` is followed by `@`, in the second preceded by `-`, and
+ * the original character classes allowed neither. So the rule is now simply
+ * «`mcp` as a word», which does match both.
+ *
+ * The same review found the mirror-image defect, and it was the worse of the
+ * two: the AGENT's own command line contains `--mcp-config …`, so the agent
+ * matched, and protection used to be spread from anything that matched — which
+ * protected the agent's ENTIRE subtree and made every Claude session return no
+ * candidate at all. Protection is no longer spread from a tree root: a root is
+ * protected on its own account (it is the agent), and spreading from it would
+ * protect the very builds this mechanism exists to stop.
+ */
+export declare const MCP_MARKER: RegExp;
+export declare function residentPageSize(readFile?: (p: string) => string, procDir?: string): number;
+/**
+ * Read `/proc` for every process in one session's cgroup.
+ *
+ * **The exception to the rule in `host-load.ts`**, and the only one: that module
+ * states in full what this runner may read for telemetry, and says «no
+ * `/proc/<pid>` walk, no `ps`». This is not telemetry — nothing here leaves the
+ * machine except one command NAME — and choosing a victim cannot be done from
+ * two summary files. The rule and this exception are noted in both places.
+ *
+ * `ppid` is taken from after the LAST `)` of `/proc/<pid>/stat`, never by field
+ * number: a process name may contain spaces and parentheses (`(npm exec
+ * @playw)`), which moves every field after it (gotcha §441).
+ */
+export declare function readScopeProcesses(unit: string, readFile?: (p: string) => string, procDir?: string): ScopeProcess[];
+/**
+ * The biggest command of this session, defined by the letter and not by «the
+ * fattest thing on the machine».
+ *
+ * Every exclusion below is a measurement or an incident:
+ *
+ *  - **only pids of THIS cgroup.** By RSS the fattest processes on a dev server
+ *    are `dockerd`, the production API and other people's agents; a candidate
+ *    chosen machine-wide would stop one of those.
+ *  - **never the agent.** The agent is the one process in the scope whose parent
+ *    is OUTSIDE it — `systemd-run --scope` execs into it and the runner spawned
+ *    it. That is a structural fact and needs no pid handed down through two
+ *    adapters. Stopping the agent is what the top «Stop» button is for; this
+ *    mechanism has no right to it (D6).
+ *  - **never an MCP server**, nor anything under one: those are the agent's
+ *    tools, not its work.
+ *  - **never `git`.** It is never the fattest thing, and a killed `git` leaves
+ *    `.git/index.lock` behind, which then costs the session its restore points
+ *    and its next turns.
+ *  - **the whole subtree**, not one pid: over a `tsc` there is a `pnpm`, and
+ *    over that a `sh`, and killing the leaf leaves the parent to start another.
+ */
+export declare function pickKillCandidate(processes: ScopeProcess[], agentPid?: number | null): KillCandidate | null;
+/**
+ * Is this pid still the process it was when we decided to stop it?
+ *
+ * `starttime` never repeats for one pid, so comparing it is the cheap and exact
+ * answer. Anything unreadable is «not the same», which is the safe direction: a
+ * signal not sent costs a command another thirty seconds, a signal sent to the
+ * wrong process costs somebody something we know nothing about.
+ */
+export declare function isSameProcess(identity: {
+    pid: number;
+    startedAtTicks: number;
+}, readFile?: (p: string) => string, procDir?: string): boolean;
+/**
+ * Send one signal to every pid of a subtree. Processes that ended are skipped.
+ *
+ * When identities are given, each pid is checked against the process it was
+ * when the subtree was chosen — see {@link isSameProcess}. The SIGKILL that
+ * follows a SIGTERM thirty seconds later is the call that needs it: on a busy
+ * machine a pid freed in between can belong to something else by then.
+ */
+export declare function signalSubtree(pids: Array<number | {
+    pid: number;
+    startedAtTicks: number;
+}>, signal: NodeJS.Signals, kill?: (pid: number, signal: NodeJS.Signals) => void, sameProcess?: (identity: {
+    pid: number;
+    startedAtTicks: number;
+}) => boolean): number;
+/**
+ * Raise this session's brake on the live scope.
+ *
+ * `systemctl --user set-property --runtime`, never a write into the cgroup
+ * files: a direct write is undone by the next `daemon-reload`, and the runner
+ * calls one itself every hour. `--runtime` is not optional either — without it
+ * systemd persists the property into `~/.config/systemd/user.control/`, which
+ * OUTRANKS the drop-in this runner ships and which `doctor` reports as an
+ * emergency override (`index.ts`).
+ *
+ * Never throws. A failure here must not take down the tick, let alone the
+ * daemon: the daemon carries a fatal `unhandledRejection` handler, so one
+ * unhandled write error would end every live session on the machine. A
+ * `set-property` on a unit that ended between the measurement and the write
+ * exits 1 with «Unit … not found» — the ordinary outcome of a race, not an
+ * error worth a loud line.
+ */
+export declare function setScopeProperties(unit: string, properties: string[], run?: (args: string[]) => Promise<unknown>): Promise<boolean>;
+//# sourceMappingURL=session-stall.d.ts.map