@bridge4dev/runner 0.57.0 → 0.58.1

package/dist/session-stall.js

@@ -0,0 +1,760 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { killProcess, runSystemctl } from './cage-authority.js';
+import { log } from './log.js';
+import { scopeCgroupDir } from './session-cage.js';
+const MIB = 1024 * 1024;
+/**
+ * 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 const STALL_WINDOW_MS = 5_000;
+/**
+ * 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 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 const STALL_SHARE_CLEAR = 0.1;
+/** Consecutive windows over the line before the session counts as standing still. */
+export 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 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 const STALL_GRACE_MS = 180_000;
+/**
+ * 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 const STALL_PROGRESS_DROP_BYTES = 64 * MIB;
+/**
+ * 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 const STALL_MUTE_AFTER_LOWER_MS = 240_000;
+/**
+ * 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 const STALL_SIGKILL_AFTER_MS = 30_000;
+/**
+ * Growth under which the PSI-less fallback still calls a session stuck:
+ * `min(1 % of the brake, 16 MiB)` per window.
+ */
+export const STALL_FALLBACK_GROWTH_BYTES = 16 * MIB;
+export function freshStallState(unit) {
+    return { unit, last: null, hotWindows: 0, stalledSince: null, markBytes: 0, mutedUntil: 0 };
+}
+/**
+ * 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 function parseStallSample(files, at) {
+    const count = (raw) => {
+        const trimmed = raw.trim();
+        if (!/^\d+$/.test(trimmed))
+            return null;
+        const value = Number(trimmed);
+        return Number.isSafeInteger(value) ? value : null;
+    };
+    const currentBytes = count(files.current);
+    if (currentBytes === null)
+        return null;
+    const statField = (name) => {
+        const match = new RegExp(`^${name} (\\d+)$`, 'm').exec(files.stat);
+        return match?.[1] ? Number(match[1]) : 0;
+    };
+    const event = (name) => {
+        const line = files.events.split('\n').find((l) => l.startsWith(`${name} `));
+        return line ? (count(line.slice(name.length + 1)) ?? 0) : 0;
+    };
+    // `full avg10=… avg60=… avg300=… total=12417907`. The averages are the kernel's
+    // own smoothing over windows we did not choose; `total` is the raw counter and
+    // the only one a window of our own length can be cut out of.
+    const full = files.pressure?.split('\n').find((l) => l.startsWith('full '));
+    const totalMatch = full ? /(?:^|\s)total=(\d+)/.exec(full) : null;
+    const pressureFullUs = totalMatch?.[1] ? Number(totalMatch[1]) : null;
+    return {
+        pressureFullUs: pressureFullUs !== null && Number.isSafeInteger(pressureFullUs) ? pressureFullUs : null,
+        highEvents: event('high'),
+        currentBytes,
+        anonBytes: statField('anon') + statField('shmem'),
+        brakeBytes: files.high.trim() === 'max' ? null : count(files.high),
+        at,
+    };
+}
+/** Read one sample off a live scope. Null when the cgroup is not there. */
+export function readStallSample(unit, at, readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    const dir = scopeCgroupDir(unit);
+    if (dir === null)
+        return null;
+    try {
+        let pressure;
+        try {
+            pressure = readFile(path.join(dir, 'memory.pressure'));
+        }
+        catch {
+            // A kernel without `CONFIG_PSI` has no such file. Not a failure — it
+            // decides which measure is used and doubles the deadline, nothing more.
+            pressure = undefined;
+        }
+        return parseStallSample({
+            current: readFile(path.join(dir, 'memory.current')),
+            high: readFile(path.join(dir, 'memory.high')),
+            events: readFile(path.join(dir, 'memory.events')),
+            stat: readFile(path.join(dir, 'memory.stat')),
+            ...(pressure === undefined ? {} : { pressure }),
+        }, at);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function stallStep(previous, sample, options = {}) {
+    const now = options.now ?? sample.at;
+    const graceMs = options.graceMs ?? STALL_GRACE_MS;
+    // The nominal window, so a suite can run the whole mechanism in a second
+    // without fake timers — which are not an option here: they fire the WS
+    // client's liveness watchdog and it terminates the socket as half-dead.
+    const nominalWindowMs = options.windowMs ?? STALL_WINDOW_MS;
+    const degraded = sample.pressureFullUs === null;
+    const clean = (mutedUntil) => ({
+        state: {
+            ...previous,
+            last: sample,
+            hotWindows: 0,
+            stalledSince: null,
+            markBytes: 0,
+            mutedUntil,
+        },
+        stuck: false,
+        remainingMs: null,
+        expired: false,
+        degraded,
+    });
+    const before = previous.last;
+    // A cgroup this detector has not seen, or one whose counters went backwards —
+    // which can only be a NEW cgroup behind the same unit name. Start from zero
+    // rather than measure a window against a stranger's counter.
+    const sameCgroup = before !== null &&
+        sample.at > before.at &&
+        sample.highEvents >= before.highEvents &&
+        (sample.pressureFullUs === null ||
+            before.pressureFullUs === null ||
+            sample.pressureFullUs >= before.pressureFullUs);
+    if (!sameCgroup)
+        return clean(previous.mutedUntil);
+    if (now < previous.mutedUntil)
+        return clean(previous.mutedUntil);
+    const windowMs = sample.at - before.at;
+    const effectiveGraceEarly = (options.graceMs ?? STALL_GRACE_MS) * (degraded ? 2 : 1);
+    // A window shorter than half the nominal one is a tick that fired early; its
+    // share would be noise divided by a small number. The old sample is KEPT, so
+    // the next window is measured over a full span instead of two short ones —
+    // and the deadline, if one is running, keeps running.
+    if (windowMs < nominalWindowMs / 2) {
+        const running = previous.stalledSince !== null;
+        return {
+            state: { ...previous, last: before },
+            stuck: running,
+            remainingMs: running
+                ? Math.max(0, effectiveGraceEarly - (now - (previous.stalledSince ?? now)))
+                : null,
+            expired: false,
+            degraded,
+        };
+    }
+    /**
+     * Three answers, not two, and the middle one is what the measurement bought.
+     *
+     * `hot` starts and continues a deadline. `clear` ends one. `warm` — between
+     * the two lines — does neither: a stall that dips for one window is still a
+     * stall, and a session that has not started standing still does not start now.
+     */
+    const anonShare = sample.currentBytes > 0 ? sample.anonBytes / sample.currentBytes : 0;
+    const anonFuse = anonShare >= STALL_ANON_SHARE;
+    /**
+     * …and it has to be THIS session's own doing.
+     *
+     * `memory.pressure` counts every microsecond a task of this cgroup could not
+     * run for want of memory — INCLUDING when the reason is an ancestor. Since S3
+     * put a collective `MemoryHigh` on the sessions slice, that is no longer
+     * hypothetical: a greedy sibling filling the slice makes the kernel throttle
+     * everybody, and an innocent session sitting far under its own limits sees a
+     * high `full` share with nothing wrong on its side.
+     *
+     * The independent review of 10.09.2026 reproduced it with real cgroups: a
+     * scope holding a steady 430 MB, 1.5 GB under its own brake, below even its
+     * own `MemoryLow`, with `memory.events high = 0` for the whole run, showed
+     * shares of 0.22–0.42 for 45 consecutive windows — and the mechanism would
+     * have stopped its command at 214 s. That is precisely the failure #387 is
+     * about, the innocent neighbour, coming back through a new door.
+     *
+     * `memory.events` `high` is the discriminator, and it is exact: it counts
+     * times THIS cgroup's own brake was breached, and it does not move when an
+     * ancestor is the one throttling. Measured on this host, a session stalled by
+     * its OWN brake moved it by about a thousand per five-second window
+     * (4595 → 5785 → 6805 → 7655); the innocent neighbour above moved it not at
+     * all.
+     */
+    /**
+     * «This session's own doing», by three signs and not one (#398 S7, B9).
+     *
+     * `memory.events high` is exact when it fires, and it has two blind spots
+     * that the rest of this stage created:
+     *
+     *  1. **The brake is not always above the hold.** On a tight machine the
+     *     allocator floors the brake at `max(guarantee, hold × 1.05)`, so an
+     *     INNOCENT session's own counter ticks on any growth at all. Hence the
+     *     counter alone is not enough to convict — but it was never the only
+     *     evidence: the deadline still needs pressure over the line for two
+     *     windows.
+     *  2. **The slice's brake can bind first.** Above a pot of about 22.5 GiB a
+     *     lone session's brake (`top − band`) sits ABOVE the collective brake on
+     *     the slice (0.9 × pot), so the kernel throttles at the slice and this
+     *     counter never moves — the detector switched off in precisely the
+     *     headline case of the ticket. `nearOwnBrake` and `soleSession` cover it:
+     *     a session sitting at its own ceiling, or alone in the slice, is not
+     *     standing in anybody else's queue.
+     */
+    const nearOwnBrake = sample.brakeBytes !== null && sample.currentBytes >= Math.floor(sample.brakeBytes * 0.95);
+    const ownBrakeFired = sample.highEvents > before.highEvents || nearOwnBrake || options.soleSession === true;
+    /**
+     * A frozen counter no longer cancels a deadline by itself, and it no longer
+     * needs a special case to avoid it either (#403).
+     *
+     * The first attempt at this bug added one: «a still counter means warm while
+     * a deadline runs», on the reasoning that a session wedged hard enough to
+     * stop allocating looks exactly like an innocent neighbour. It was the right
+     * observation and the wrong place — with a real neighbour in the slice the
+     * deadline then ran to its end anyway, and the innocent session lost its
+     * command. Reproduced in the suite, two sessions and one SIGTERM.
+     *
+     * `nearOwnBrake` above answers it properly: a session that has stopped
+     * allocating because its OWN limit is what stops it is sitting at that limit,
+     * which is a fact about the cgroup and not a guess about its intentions. So
+     * `ownBrakeFired` is true for it, and «somebody else's brake» keeps meaning
+     * exactly what it says.
+     */
+    let heat;
+    if (sample.pressureFullUs !== null && before.pressureFullUs !== null) {
+        const share = (sample.pressureFullUs - before.pressureFullUs) / (windowMs * 1000);
+        if (!anonFuse || !ownBrakeFired || share < STALL_SHARE_CLEAR)
+            heat = 'clear';
+        else if (share >= STALL_SHARE)
+            heat = 'hot';
+        else
+            heat = 'warm';
+    }
+    else {
+        // No PSI. The brake fired at least once, the cgroup barely grew, and what it
+        // holds is not page cache. Weaker than pressure, hence the doubled grace.
+        const growth = sample.currentBytes - before.currentBytes;
+        const ceiling = Math.min(sample.brakeBytes === null
+            ? STALL_FALLBACK_GROWTH_BYTES
+            : Math.floor(sample.brakeBytes * 0.01), STALL_FALLBACK_GROWTH_BYTES);
+        if (!anonFuse || growth >= ceiling) {
+            // It is allocating, so it is moving. That IS the progress this measure has.
+            heat = 'clear';
+        }
+        else if (sample.highEvents > before.highEvents)
+            heat = 'hot';
+        else
+            heat = 'warm';
+    }
+    const effectiveGrace = degraded ? graceMs * 2 : graceMs;
+    if (heat === 'clear')
+        return clean(previous.mutedUntil);
+    // Real progress, even while the pressure stays up: the session gave memory back.
+    if (previous.stalledSince !== null &&
+        previous.markBytes - sample.currentBytes >= STALL_PROGRESS_DROP_BYTES) {
+        return clean(previous.mutedUntil);
+    }
+    // Warm and not already standing: nothing starts here.
+    if (heat === 'warm' && previous.stalledSince === null) {
+        return {
+            state: { ...previous, last: sample, stalledSince: null, markBytes: 0 },
+            stuck: false,
+            remainingMs: null,
+            expired: false,
+            degraded,
+        };
+    }
+    const hotWindows = heat === 'hot' ? previous.hotWindows + 1 : previous.hotWindows;
+    if (hotWindows < STALL_WINDOWS_TO_TRIP) {
+        return {
+            state: { ...previous, last: sample, hotWindows, stalledSince: null, markBytes: 0 },
+            stuck: false,
+            remainingMs: null,
+            expired: false,
+            degraded,
+        };
+    }
+    const stalledSince = previous.stalledSince ?? now;
+    const markBytes = previous.stalledSince === null ? sample.currentBytes : previous.markBytes;
+    const elapsed = now - stalledSince;
+    return {
+        state: { ...previous, last: sample, hotWindows, stalledSince, markBytes },
+        stuck: true,
+        remainingMs: Math.max(0, effectiveGrace - elapsed),
+        expired: elapsed >= effectiveGrace,
+        degraded,
+    };
+}
+/**
+ * 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 const MCP_MARKER = /(^|[^a-z0-9])mcp([^a-z0-9]|$)|modelcontextprotocol/i;
+/**
+ * Bytes per page of `/proc/<pid>/statm`, worked out rather than assumed.
+ *
+ * 4096 is right on x86-64 and wrong on an arm64 kernel built with 16 KB or
+ * 64 KB pages — where every size this module reports would be off by a factor of
+ * four or sixteen. The ranking would survive (the error is uniform), but the
+ * number in the line a person reads would not. `/proc/self/status` gives `VmRSS`
+ * in kB and `/proc/self/statm` gives the same figure in pages, so dividing one
+ * by the other answers the question with no subprocess and no guess.
+ *
+ * Measured once per process: the page size cannot change under a running kernel.
+ */
+let cachedPageSize = null;
+export function residentPageSize(readFile = (p) => fs.readFileSync(p, 'utf8'), procDir = '/proc') {
+    if (cachedPageSize !== null)
+        return cachedPageSize;
+    let size = 4096;
+    try {
+        const status = readFile(path.join(procDir, 'self', 'status'));
+        const rssKb = /^VmRSS:\s+(\d+) kB$/m.exec(status);
+        const pages = Number(readFile(path.join(procDir, 'self', 'statm'))
+            .trim()
+            .split(/\s+/)[1]);
+        if (rssKb?.[1] && Number.isSafeInteger(pages) && pages > 0) {
+            const derived = Math.round((Number(rssKb[1]) * 1024) / pages);
+            // Only a real page size: a power of two between 4 KiB and 64 KiB.
+            if (derived >= 4096 && derived <= 65536 && (derived & (derived - 1)) === 0)
+                size = derived;
+        }
+    }
+    catch {
+        // No `/proc/self`. 4096 is the right guess everywhere this runner runs.
+    }
+    cachedPageSize = size;
+    return size;
+}
+/**
+ * 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 function readScopeProcesses(unit, readFile = (p) => fs.readFileSync(p, 'utf8'), procDir = '/proc') {
+    const dir = scopeCgroupDir(unit);
+    if (dir === null)
+        return [];
+    let listing;
+    try {
+        listing = readFile(path.join(dir, 'cgroup.procs'));
+    }
+    catch {
+        return [];
+    }
+    const pageSize = residentPageSize(readFile, procDir);
+    const out = [];
+    for (const line of listing.split('\n')) {
+        const pid = Number(line.trim());
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            continue;
+        try {
+            const stat = readFile(path.join(procDir, String(pid), 'stat'));
+            const close = stat.lastIndexOf(')');
+            if (close < 0)
+                continue;
+            const after = stat
+                .slice(close + 1)
+                .trim()
+                .split(/\s+/);
+            // After `comm` come `state` then `ppid`; `starttime` is field 22 of the
+            // whole line, i.e. index 19 of what follows the closing parenthesis.
+            const ppid = Number(after[1]);
+            const startedAtTicks = Number(after[19]);
+            const statm = readFile(path.join(procDir, String(pid), 'statm'))
+                .trim()
+                .split(/\s+/);
+            const resident = Number(statm[1]);
+            const comm = readFile(path.join(procDir, String(pid), 'comm')).trim();
+            let cmdline = '';
+            try {
+                cmdline = readFile(path.join(procDir, String(pid), 'cmdline'));
+            }
+            catch {
+                // A process that ended between the listing and the read. Treated as
+                // ordinary work, which only ever makes it a candidate — and a candidate
+                // that no longer exists is skipped when the signal is sent.
+            }
+            if (!Number.isSafeInteger(ppid) || !Number.isSafeInteger(resident))
+                continue;
+            out.push({
+                pid,
+                ppid,
+                startedAtTicks: Number.isSafeInteger(startedAtTicks) ? startedAtTicks : -1,
+                comm,
+                rssBytes: resident * pageSize,
+                mcp: MCP_MARKER.test(cmdline.replace(/\0/g, ' ')),
+            });
+        }
+        catch {
+            // Gone between the listing and the read.
+        }
+    }
+    return out;
+}
+/**
+ * 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 function pickKillCandidate(processes, agentPid = null) {
+    if (processes.length === 0)
+        return null;
+    const byPid = new Map(processes.map((p) => [p.pid, p]));
+    const children = new Map();
+    for (const p of processes) {
+        if (!byPid.has(p.ppid))
+            continue;
+        const list = children.get(p.ppid);
+        if (list)
+            list.push(p.pid);
+        else
+            children.set(p.ppid, [p.pid]);
+    }
+    // The agent: the root of the tree. On a scope there is exactly one, but a
+    // machine can surprise us, so every parentless process is protected.
+    const roots = processes.filter((p) => !byPid.has(p.ppid)).map((p) => p.pid);
+    const rootComms = new Set(roots.map((pid) => byPid.get(pid)?.comm ?? ''));
+    const protectedPids = new Set(roots);
+    const spread = (pid) => {
+        for (const child of children.get(pid) ?? []) {
+            if (protectedPids.has(child))
+                continue;
+            protectedPids.add(child);
+            spread(child);
+        }
+    };
+    for (const p of processes) {
+        if (!p.mcp)
+            continue;
+        protectedPids.add(p.pid);
+        /**
+         * …but never FROM THE AGENT. See the note on `MCP_MARKER`: the agent's own
+         * command line names the MCP config, so spreading from it protected every
+         * build the agent ever started.
+         *
+         * Which one is the agent is now KNOWN when the caller says so (#403).
+         * «Every root» was the old answer, and it was too wide by exactly one case:
+         * an MCP server whose launcher exited is a root too, and under that answer
+         * its own children — a browser, a language server — silently lost the
+         * protection they had before S7b. They are the agent's tools either way.
+         */
+        const isAgent = agentPid === null ? roots.includes(p.pid) : p.pid === agentPid;
+        if (!isAgent)
+            spread(p.pid);
+    }
+    const subtree = (pid) => {
+        const acc = [pid];
+        for (const child of children.get(pid) ?? [])
+            acc.push(...subtree(child));
+        return acc;
+    };
+    let best = null;
+    for (const p of processes) {
+        if (protectedPids.has(p.pid))
+            continue;
+        // Only tree roots among what is left: a process whose parent is also a
+        // candidate is part of that parent's subtree, not a candidate of its own.
+        if (byPid.has(p.ppid) && !protectedPids.has(p.ppid))
+            continue;
+        if (p.comm === 'git')
+            continue;
+        // A second agent process (a background CLI) is not «a command» either.
+        if (rootComms.has(p.comm))
+            continue;
+        /**
+         * `git` is spared, and only `git` — not everything that happens to share a
+         * tree with it (#403).
+         *
+         * Two corrections, in this order. The review of 10.09.2026 found the first:
+         * the ordinary shape of a git command from an agent is `bash -lc "git …"`,
+         * so the root is `bash` and the `git` underneath it was killed with the
+         * tree, leaving `.git/index.lock` behind. The fix for it skipped any
+         * subtree CONTAINING a git — and that was too much, because in Claude Code
+         * every Bash tool call lives under ONE long-lived shell: a momentary
+         * `git status` made the four-gigabyte build in the same tree unkillable,
+         * and T2 quietly degraded into T3 «nothing to stop here».
+         *
+         * So the git processes and their children are removed from the signal list
+         * while the rest of the subtree stays a candidate. `comm` is truncated to
+         * 15 characters by the kernel, hence the prefix test — it also covers
+         * `git-remote-http` and `git-lfs`, which have the same lock to lose.
+         */
+        const isGit = (pid) => (byPid.get(pid)?.comm ?? '').startsWith('git');
+        const spared = new Set();
+        const spareTree = (pid) => {
+            spared.add(pid);
+            for (const child of children.get(pid) ?? [])
+                spareTree(child);
+        };
+        for (const pid of subtree(p.pid))
+            if (isGit(pid))
+                spareTree(pid);
+        const pids = subtree(p.pid).filter((pid) => !spared.has(pid));
+        // Nothing but git under here: that is a git command, and it is spared whole.
+        if (pids.length === 0)
+            continue;
+        const rssBytes = pids.reduce((sum, pid) => sum + (byPid.get(pid)?.rssBytes ?? 0), 0);
+        // The NAME the person reads is the heaviest process of the subtree, not its
+        // root: over a `node` doing the work there is usually a `sh` or a `pnpm`,
+        // and «sh» tells nobody anything. Arguments are never taken — they carry
+        // keys and tokens.
+        const heaviest = pids
+            .map((pid) => byPid.get(pid))
+            .filter((x) => x !== undefined)
+            .sort((a, b) => b.rssBytes - a.rssBytes)[0];
+        if (best === null || rssBytes > best.rssBytes) {
+            best = {
+                rootPid: p.pid,
+                pids,
+                identities: pids.map((pid) => ({
+                    pid,
+                    startedAtTicks: byPid.get(pid)?.startedAtTicks ?? -1,
+                })),
+                name: heaviest?.comm ?? p.comm,
+                rssBytes,
+            };
+        }
+    }
+    return best;
+}
+/**
+ * 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 function isSameProcess(identity, readFile = (p) => fs.readFileSync(p, 'utf8'), procDir = '/proc') {
+    if (identity.startedAtTicks < 0)
+        return false;
+    try {
+        const stat = readFile(path.join(procDir, String(identity.pid), 'stat'));
+        const close = stat.lastIndexOf(')');
+        if (close < 0)
+            return false;
+        const after = stat
+            .slice(close + 1)
+            .trim()
+            .split(/\s+/);
+        return Number(after[19]) === identity.startedAtTicks;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function signalSubtree(pids, signal, kill = killProcess, sameProcess = isSameProcess) {
+    let sent = 0;
+    // Deepest first, so a parent cannot notice a child dying and start another.
+    for (const entry of [...pids].reverse()) {
+        const pid = typeof entry === 'number' ? entry : entry.pid;
+        if (typeof entry !== 'number' && !sameProcess(entry))
+            continue;
+        try {
+            kill(pid, signal);
+            sent += 1;
+        }
+        catch {
+            // Already gone, or not ours. Either way there is nothing to stop.
+        }
+    }
+    return sent;
+}
+/**
+ * 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 async function setScopeProperties(unit, properties, run = (args) => runSystemctl(args)) {
+    if (properties.length === 0)
+        return true;
+    try {
+        await run(['set-property', '--runtime', unit, ...properties]);
+        return true;
+    }
+    catch (error) {
+        const text = String(error instanceof Error ? error.message : error);
+        if (/not found|not loaded/i.test(text)) {
+            log.debug('session memory: the scope ended before its limits could be written', { unit });
+        }
+        else {
+            log.warn('session memory: could not write the limits of a live session', {
+                unit,
+                error: text,
+            });
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=session-stall.js.map