@bridge4dev/runner 0.65.0 → 0.65.1

package/dist/adapters/codex.js

@@ -2119,12 +2119,35 @@ class CodexSession {
         // codex is chatty on stderr (bubblewrap notices, MCP transport spam). Log
         // locally, never turn it into session events.
         log.warn('codex: stderr', { text: maskString(trimmed).slice(0, 500) });
-    }
+        /**
+         * …with one exception, kept for the death below (#431). A process that
+         * never reached `initialize` said exactly one thing on its way out, and
+         * that sentence is the difference between «code 1» and a cause: on 16.09 it
+         * was systemd's «Unit … was already loaded», and the person got the code.
+         *
+         * Only until the session is ready: after that this is never read again, and
+         * codex is chatty enough on stderr for «never read» to be worth not
+         * computing (independent review of #431).
+         */
+        if (this.ready)
+            return;
+        const last = trimmed
+            .split('\n')
+            .filter((line) => line.trim())
+            .pop();
+        if (last !== undefined)
+            this.lastStderrLine = last.trim();
+    }
+    /** The last thing this process said on stderr — see {@link onStderr}. */
+    lastStderrLine = '';
     onExit(info) {
         if (!this.stopped && !this.ready) {
+            // The cause, when the process left one. Masked and cut like every other
+            // line that comes out of a child process here.
+            const said = this.lastStderrLine ? `: ${maskString(this.lastStderrLine).slice(0, 200)}` : '';
             this.emit({
                 type: 'error',
-                message: `codex app-server exited before the session was ready (code ${info.code ?? 'null'})`,
+                message: `codex app-server exited before the session was ready (code ${info.code ?? 'null'})${said}`,
                 // #373: the process is what ended, not a turn. `stopped` is already
                 // excluded above, so this is always an exit nobody here asked for.
                 processGone: true,

package/dist/daemon-exit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The one way out of the daemon process (#431).
+ *
+ * Its own module, and not four lines inside `cmdDaemon`, for one reason: the
+ * defect this ticket is about WAS those four lines. `supervisor.shutdown();
+ * ws.stop(); process.exit(0);` in a single tick killed one process per session
+ * and left everything that process had started running inside a cgroup systemd
+ * would then refuse to reuse by name. Nothing in the suite could see that,
+ * because no test in this package imports `index.ts` — found by the independent
+ * review of #431, which also pointed out that the next edit to that file would
+ * be just as invisible.
+ *
+ * So the order is code with a test on it rather than a comment:
+ *
+ *  1. **`shutdown()`** — its synchronous half runs before it returns: the cards
+ *     a person was still being asked are withdrawn, the line saying what this
+ *     restart costs goes into the journal, the agents are killed.
+ *  2. **the socket is closed** — after the events above needed it open, and
+ *     before the wait below, which must not be a window in which an `event_ack`
+ *     or a `session_start` reaches a supervisor that has let go of everything.
+ *  3. **the promise is awaited** — the cages, and nothing else. What does not
+ *     finish inside the supervisor's own budget continues on systemd's side:
+ *     the stop has been accepted by then.
+ *  4. **`exit`**, always — including when the wait ends in a rejection. A
+ *     daemon that would not die because a bus call failed is worse than one
+ *     that leaves a scope behind.
+ */
+export interface DaemonExitDeps {
+    /** The supervisor's shutdown. The synchronous half must run before it returns. */
+    shutdown: () => Promise<void>;
+    /** Close the socket, both directions. */
+    stopWs: () => void;
+    /** Write the status file, so `doctor` sees a daemon that is going down. */
+    noteStatus?: () => void;
+    /** End the process. Injected so the order above can be proved. */
+    exit: (code: number) => void;
+}
+/** Build the exit door. The returned function is safe to call more than once. */
+export declare function daemonExit(deps: DaemonExitDeps): (code: number) => void;
+//# sourceMappingURL=daemon-exit.d.ts.map

package/dist/daemon-exit.js

@@ -0,0 +1,29 @@
+import { log } from './log.js';
+/** Build the exit door. The returned function is safe to call more than once. */
+export function daemonExit(deps) {
+    let leaving = false;
+    return (code) => {
+        /**
+         * A second signal does not shorten the first departure.
+         *
+         * Two `SIGTERM`s, or «Update runner» racing a restart command, used to run
+         * the whole thing twice: a second `verify.shutdown()` signalling a group
+         * that is already dying, and an `exit` from the second call cutting the
+         * first call's wait for its cages — the very wait this door exists for.
+         */
+        if (leaving) {
+            log.warn('daemon: already leaving, this second request changes nothing', { code });
+            return;
+        }
+        leaving = true;
+        const cages = deps.shutdown();
+        deps.stopWs();
+        deps.noteStatus?.();
+        void cages
+            .catch((error) => {
+            log.warn('daemon: the cages did not all stop cleanly', { error: String(error) });
+        })
+            .finally(() => deps.exit(code));
+    };
+}
+//# sourceMappingURL=daemon-exit.js.map

package/dist/index.js

@@ -25,6 +25,7 @@ import { buildUnit, cpuQuotaPercent, devbridgeSliceOverridePath, limitsOverrideI
 import { defaultCageProbe, initSessionCage, readSliceLimits, listSessionScopes, sessionCage, sweepOrphanSessionScopes, SESSION_TASKS_MAX, } from './session-cage.js';
 import { SEARCH_GUARD_ENABLED, claudeSettingsPath, installSearchGuard, removeSearchGuard, searchGuardCommand, searchGuardHome, searchGuardHookPath, searchGuardStatus, } from './claude-settings.js';
 import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
+import { daemonExit } from './daemon-exit.js';
 import { agentAuthStatuses } from './auth-relay.js';
 import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, } from './environment.js';
 import { mcpConfigDir } from './paths.js';
@@ -1019,11 +1020,7 @@ async function cmdDaemon() {
                 from: outcome.fromVersion,
                 to: outcome.toVersion ?? 'unknown',
             });
-            const timer = setTimeout(() => {
-                supervisor.shutdown();
-                ws.stop();
-                process.exit(0);
-            }, RESTART_DELAY_MS);
+            const timer = setTimeout(() => leave(0), RESTART_DELAY_MS);
             timer.unref();
         },
         // #396: the same exit, asked for directly rather than as the tail of an
@@ -1035,11 +1032,7 @@ async function cmdDaemon() {
                 sessions: supervisor.activeSessionIds.length,
                 told: Boolean(note),
             });
-            const timer = setTimeout(() => {
-                supervisor.shutdown();
-                ws.stop();
-                process.exit(0);
-            }, RESTART_DELAY_MS);
+            const timer = setTimeout(() => leave(0), RESTART_DELAY_MS);
             timer.unref();
         },
     });
@@ -1052,13 +1045,21 @@ async function cmdDaemon() {
         activeSessionIds: supervisor.activeSessionIds,
         updatedAt: new Date().toISOString(),
     });
+    /**
+     * The one way out of this process — the order lives in `daemon-exit.ts`,
+     * where a test can hold it (#431).
+     */
+    const leave = daemonExit({
+        shutdown: () => supervisor.shutdown(),
+        stopWs: () => ws.stop(),
+        noteStatus: updateStatus,
+        exit: (code) => process.exit(code),
+    });
     ws.on('open', updateStatus);
     ws.on('close', updateStatus);
     ws.on('revoked', (reason) => {
         log.error(`daemon: access revoked (${reason}) — exiting`);
-        supervisor.shutdown();
-        updateStatus();
-        process.exit(3);
+        leave(3);
     });
     const statusTimer = setInterval(updateStatus, 30_000);
     statusTimer.unref();
@@ -1072,10 +1073,7 @@ async function cmdDaemon() {
     limitsTimer.unref();
     const shutdown = (signal) => {
         log.info(`daemon: ${signal} received, shutting down`);
-        supervisor.shutdown();
-        ws.stop();
-        updateStatus();
-        process.exit(0);
+        leave(0);
     };
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));

package/dist/session-cage.d.ts

@@ -300,6 +300,13 @@ export declare function sanitizeCageId(id: string): string;
  * normal case and the marker appears only while the old scope is still there.
  */
 export declare function sessionScopeUnit(id: string, attempt?: number): string;
+/**
+ * Is there a cgroup by this unit's name — that is, processes still in it?
+ *
+ * `dirOf` is the test seam: the answer depends on a cgroup tree, and a suite
+ * has none. Everything else about this function is one `stat`.
+ */
+export declare function cageCgroupExists(unit: string, dirOf?: (unit: string) => string | null): boolean;
 /**
  * The systemd release that added `--expand-environment=`.
  *
@@ -433,6 +440,16 @@ export declare function buildCagedSpawn(input: {
     id: string;
     command: string;
     args: string[];
+}, 
+/**
+ * The two things this function does to the machine besides building a command
+ * line, as seams (#431): whether a cage of that name still exists, and what to
+ * do about it. A suite has neither a cgroup tree nor a systemd to answer.
+ */
+io?: {
+    cageExists?: (unit: string) => boolean;
+    cageLiveness?: (unit: string) => ScopeLiveness;
+    stopCage?: (unit: string) => void;
 }): CagedSpawn;
 /**
  * Did this process die in the window before `systemd-run` handed over?
@@ -628,6 +645,23 @@ export declare function markScopeOomKillsSeen(id: string, oomKills: number): voi
  * thing and must not word it differently.
  */
 export declare function stoppedProcesses(count: number, where?: 'it' | 'this one'): string;
+/**
+ * What the feed says when the runner takes a session's cage down with itself
+ * (#431).
+ *
+ * Next to {@link stoppedProcesses} and for the same reason: two places that
+ * count the same thing must not word it differently. This one counts COMMANDS,
+ * because that is what a person can act on — «7 processes» is the same build
+ * said in a way nobody can use.
+ *
+ * The middle sentence is the part that matters. A command that outlives the
+ * process which started it cannot hand its output back to anybody: the pipe
+ * died with the agent, and the agent that comes back is a different process
+ * with a different tool call. Stopping it is not a loss, it is the refusal to
+ * keep a zombie — but the person has to be told, or they will wait for a build
+ * that nobody is going to report.
+ */
+export declare function restartStoppedCommands(count: number): string;
 /**
  * Snapshot the cgroup's verdict before systemd can take it away.
  *
@@ -669,6 +703,21 @@ export declare function releaseSessionScope(unit: string | null, id?: string, sy
  * worth nothing, and a hung `systemctl` must not hold a failing session open.
  */
 export declare function memoryDeathSentence(id: string, capMs?: number): Promise<string | null>;
+/**
+ * Stop a cage and let systemd forget its name — the other half of killing the
+ * agent (#431, грабля §524).
+ *
+ * {@link releaseSessionScope} is the path for a process that ENDED: it reads
+ * the verdict first and only stops what is left. This one is for the two
+ * moments where there is nothing to read and no time to read it — the daemon
+ * going down, and a start that found its own name still taken. It asks for the
+ * stop and nothing else.
+ *
+ * Worth knowing on the shutdown path: once `stop` has been accepted, the job
+ * belongs to systemd. A caller that gives up waiting still gets the cage
+ * stopped — it simply does not get to see it happen.
+ */
+export declare function stopSessionScope(unit: string | null, systemctl?: Systemctl): Promise<boolean>;
 /** Unit names of every `devbridge-session-*.scope` systemd still knows about. */
 export declare function listSessionScopeUnits(systemctl?: Systemctl): Promise<string[]>;
 export interface SessionScopeInfo {

package/dist/session-cage.js

@@ -367,6 +367,45 @@ export function sessionScopeUnit(id, attempt = 1) {
     const base = `${SESSION_SCOPE_PREFIX}${sanitizeCageId(id)}`;
     return attempt <= 1 ? `${base}.scope` : `${base}-r${attempt}.scope`;
 }
+/**
+ * How many names one start may walk through before giving up and letting
+ * systemd refuse it (#431). Three is two more than has ever been needed.
+ */
+const CAGE_NAME_MAX_TRIES = 3;
+/**
+ * Is there a cgroup by this unit's name — that is, processes still in it?
+ *
+ * `dirOf` is the test seam: the answer depends on a cgroup tree, and a suite
+ * has none. Everything else about this function is one `stat`.
+ */
+export function cageCgroupExists(unit, dirOf = scopeCgroupDir) {
+    const dir = dirOf(unit);
+    if (dir === null)
+        return false;
+    try {
+        return fs.existsSync(dir);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Put out the cage that is holding a name this session needs, and say so if it
+ * would not go.
+ *
+ * Loud on failure, because the fallback is the dangerous one: the start moves
+ * to `-r2` either way, and if the old tree is STILL running under the old name
+ * the agent that comes back will start the same command beside it — two runs of
+ * one build in one folder (independent review of #431). Nothing here can undo
+ * that; the machine's log is what lets a person see it happened.
+ */
+function defaultStopCage(unit) {
+    void stopSessionScope(unit).then((stopped) => {
+        if (!stopped) {
+            log.warn('session cage: the cage holding this name would not stop', { unit });
+        }
+    });
+}
 // ─── capability detection ────────────────────────────────────────────
 /** cgroup v2 unified, from `statfs` — the number behind `stat -fc %T`. */
 const CGROUP2_SUPER_MAGIC = 0x63677270;
@@ -874,7 +913,13 @@ export function cageSpawn(input) {
  * who may hand it. One function could not do both — a test process legitimately
  * needs the first answer and must never get the second.
  */
-export function buildCagedSpawn(input) {
+export function buildCagedSpawn(input, 
+/**
+ * The two things this function does to the machine besides building a command
+ * line, as seams (#431): whether a cage of that name still exists, and what to
+ * do about it. A suite has neither a cgroup tree nor a systemd to answer.
+ */
+io = {}) {
     const facts = sessionCage();
     if (facts.mode !== 'scope' ||
         facts.memoryMaxBytes === null ||
@@ -896,9 +941,64 @@ export function buildCagedSpawn(input) {
     const maxBytes = live?.maxBytes ?? facts.memoryMaxBytes;
     const swapMaxBytes = live?.swapBytes ?? facts.swapMaxBytes;
     const guaranteedBytes = live?.guaranteedBytes ?? null;
-    const attempt = (attempts.get(input.id) ?? 0) + 1;
+    let attempt = (attempts.get(input.id) ?? 0) + 1;
+    let unit = sessionScopeUnit(input.id, attempt);
+    /**
+     * The last line of defence: a name that is STILL taken (#431).
+     *
+     * The counter above is memory, and memory is exactly what a restarted daemon
+     * does not have: after `systemctl restart` it starts at one again and asks
+     * for the plain `devbridge-session-<id>.scope` — the name the previous life
+     * of this session may still be holding with a build nobody killed. systemd
+     * answers «was already loaded or has a fragment file» and exits 1, and the
+     * session dies before it starts (the whole of #431).
+     *
+     * Asked of the cgroup tree rather than of systemd on purpose: this runs on
+     * the start of every session, and the bus has been measured at 2.7 s under
+     * load. A directory that exists means processes are in it, which is the case
+     * that matters; a unit left `failed` and EMPTY has no directory, and the
+     * sweep at daemon start clears those by name.
+     *
+     * And the tree is not left to run under a different name. It cannot hand its
+     * output to anybody — the pipes died with the process that started it — while
+     * the agent coming back will start the same command again: two `docker
+     * compose` runs of one project in one folder is a worse outcome than the
+     * failure this guard exists to prevent.
+     */
+    const exists = io.cageExists ?? cageCgroupExists;
+    const liveness = io.cageLiveness ?? scopeOwnerLiveness;
+    const stop = io.stopCage ?? defaultStopCage;
+    for (let tries = 0; tries < CAGE_NAME_MAX_TRIES && exists(unit); tries += 1) {
+        /**
+         * Asked of the kernel, not of this process's memory (independent review of
+         * #431).
+         *
+         * The first version compared the name against `liveUnits` and stopped
+         * anything that was not in it. That register holds ONE unit per session, so
+         * in the shape it was meant to protect — two processes of one session,
+         * #401 — the live cage is the one MISSING from it, and the guard would have
+         * put out an agent somebody was using. `scopeOwnerLiveness` answers the
+         * question that actually matters, on evidence: `orphaned` and `empty` are
+         * the previous life of this session, and nothing else may be touched.
+         */
+        const state = liveness(unit);
+        if (state === 'orphaned' || state === 'empty') {
+            log.warn('session cage: the name of this cage is still taken, stopping what is left in it', {
+                unit,
+                liveness: state,
+            });
+            stop(unit);
+        }
+        else {
+            log.warn('session cage: the name of this cage is taken by something alive, leaving it', {
+                unit,
+                liveness: state,
+            });
+        }
+        attempt += 1;
+        unit = sessionScopeUnit(input.id, attempt);
+    }
     attempts.set(input.id, attempt);
-    const unit = sessionScopeUnit(input.id, attempt);
     liveUnits.set(input.id, unit);
     // A verdict nobody read belongs to the process that just ended, not to the
     // one starting now: without this, a kill that was never surfaced would be
@@ -1281,6 +1381,31 @@ export function stoppedProcesses(count, where = 'it') {
         ? `a process in ${where} was stopped`
         : `${count} processes in ${where} were stopped`;
 }
+/**
+ * What the feed says when the runner takes a session's cage down with itself
+ * (#431).
+ *
+ * Next to {@link stoppedProcesses} and for the same reason: two places that
+ * count the same thing must not word it differently. This one counts COMMANDS,
+ * because that is what a person can act on — «7 processes» is the same build
+ * said in a way nobody can use.
+ *
+ * The middle sentence is the part that matters. A command that outlives the
+ * process which started it cannot hand its output back to anybody: the pipe
+ * died with the agent, and the agent that comes back is a different process
+ * with a different tool call. Stopping it is not a loss, it is the refusal to
+ * keep a zombie — but the person has to be told, or they will wait for a build
+ * that nobody is going to report.
+ */
+export function restartStoppedCommands(count) {
+    return count === 1
+        ? 'The runner was restarted, so the command this session had running was stopped. ' +
+            'Nothing can hand its output back now — start it again if you still need it. ' +
+            'The session itself is fine: its conversation was not touched.'
+        : `The runner was restarted, so the ${count} commands this session had running were stopped. ` +
+            'Nothing can hand their output back now — start them again if you still need them. ' +
+            'The session itself is fine: its conversation was not touched.';
+}
 const deaths = new Map();
 /**
  * Snapshot the cgroup's verdict before systemd can take it away.
@@ -1373,11 +1498,28 @@ function showValue(stdout, property) {
  * startable in the meantime.
  */
 export async function releaseSessionScope(unit, id, systemctl = realSystemctl) {
-    const running = releaseSessionScopeInner(unit, id, systemctl);
+    /**
+     * Is the scope being released the one this session is CURRENTLY in?
+     *
+     * It usually is, and then everything below behaves as it always did. It is
+     * not when the agent was relaunched while the previous process was still on
+     * its way out — the one-shot relaunches empty the slot when the event stream
+     * ends, and the CLI's `exit` lands a second or two later. By then the
+     * register names the LIVE cage, and wiping it by session id threw away the
+     * only record of it: the memory watch lost the cgroup, the sweep lost a
+     * spare, and since #431 `shutdown()` reads exactly this to decide whose cage
+     * to put out — «this session has no cage» would have left the live one
+     * running, which is the defect this ticket is about. Found by the
+     * independent review of #431.
+     */
+    const current = unit !== null && id !== undefined && liveUnits.get(id) === unit;
+    const running = releaseSessionScopeInner(unit, id, systemctl, current);
     if (id !== undefined) {
         // The process this named is gone with the scope; a pid outliving it would be
-        // a pid that means something else by the time anybody reads it.
-        agentPids.delete(id);
+        // a pid that means something else by the time anybody reads it. Only when
+        // this IS that process — see `current` above.
+        if (current)
+            agentPids.delete(id);
         releasing.set(id, running);
         void running.finally(() => {
             if (releasing.get(id) === running)
@@ -1416,7 +1558,9 @@ export async function memoryDeathSentence(id, capMs = 3_000) {
     }
     return explainMemoryDeath(id);
 }
-async function releaseSessionScopeInner(unit, id, systemctl) {
+async function releaseSessionScopeInner(unit, id, systemctl, 
+/** Is this the cage the session is in right now — see {@link releaseSessionScope}. */
+current) {
     if (!unit)
         return null;
     // Synchronously and FIRST: the cgroup's own counters are the one record of an
@@ -1425,7 +1569,7 @@ async function releaseSessionScopeInner(unit, id, systemctl) {
     // empty. This is what the adapter's error text is built from (#387).
     if (id !== undefined)
         rememberDeath(id, unit);
-    if (id !== undefined)
+    if (id !== undefined && current)
         liveUnits.delete(id);
     let result = null;
     let tasksLeft = null;
@@ -1504,10 +1648,45 @@ async function releaseSessionScopeInner(unit, id, systemctl) {
     // which systemd answers with «was already loaded or has a fragment file» and
     // spawns nothing — the exact failure the counter exists to prevent
     // (QA-2026-09-07 MINOR-11).
-    if (id !== undefined && forgotten)
+    if (id !== undefined && forgotten && current)
         attempts.delete(id);
     return result;
 }
+/**
+ * Stop a cage and let systemd forget its name — the other half of killing the
+ * agent (#431, грабля §524).
+ *
+ * {@link releaseSessionScope} is the path for a process that ENDED: it reads
+ * the verdict first and only stops what is left. This one is for the two
+ * moments where there is nothing to read and no time to read it — the daemon
+ * going down, and a start that found its own name still taken. It asks for the
+ * stop and nothing else.
+ *
+ * Worth knowing on the shutdown path: once `stop` has been accepted, the job
+ * belongs to systemd. A caller that gives up waiting still gets the cage
+ * stopped — it simply does not get to see it happen.
+ */
+export async function stopSessionScope(unit, systemctl = realSystemctl) {
+    if (!unit)
+        return false;
+    let stopped = false;
+    try {
+        await systemctl(['stop', unit]);
+        stopped = true;
+    }
+    catch (error) {
+        // A scope that ended by itself answers «not loaded», and a process with no
+        // right to act on cages answers with a refusal. Neither is worth a session.
+        log.debug('session cage: could not stop the scope', { unit, error: String(error) });
+    }
+    try {
+        await systemctl(['reset-failed', unit]);
+    }
+    catch {
+        // Nothing to forget: the usual answer for a scope that stopped cleanly.
+    }
+    return stopped;
+}
 /** Unit names of every `devbridge-session-*.scope` systemd still knows about. */
 export async function listSessionScopeUnits(systemctl = realSystemctl) {
     let stdout;
@@ -1568,6 +1747,17 @@ export async function listSessionScopes(systemctl = realSystemctl) {
     }
     return out;
 }
+/**
+ * Did this read fail because the process is gone, or because we could not read?
+ *
+ * `ENOENT` is /proc's answer for a pid that ended; `ESRCH` is the same answer
+ * from the other syscalls. Everything else — permissions, descriptors, a broken
+ * read — is ignorance, and ignorance is never evidence of litter.
+ */
+function processIsGone(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'ESRCH';
+}
 export function scopeOwnerLiveness(unit, io = {}) {
     const readFile = io.readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
     const cgroupDir = io.cgroupDir ?? scopeCgroupDir;
@@ -1597,6 +1787,19 @@ export function scopeOwnerLiveness(unit, io = {}) {
     }
     if (pids.length === 0)
         return 'empty';
+    /**
+     * Who is INSIDE, as a set — the difference between «a live parent» and «a
+     * live parent outside the cage» (#431).
+     *
+     * An agent's command is never one process: `bash -lc 'docker compose …'` is a
+     * tree, and every process below its root has a living parent — its own
+     * neighbour in this cgroup. Without this set the question below answered
+     * «somebody is supervising them» for every abandoned build on the machine,
+     * so the sweep left it alone for ever, the cage kept its name, and the next
+     * start of that session died as «(code 1)» (measured 16.09.2026). The single
+     * orphan of §479 answered correctly only because it had no children.
+     */
+    const inside = new Set(pids);
     let sawUnknown = false;
     for (const pid of pids) {
         let ppid;
@@ -1606,8 +1809,23 @@ export function scopeOwnerLiveness(unit, io = {}) {
             const value = line === undefined ? Number.NaN : Number(line.slice('PPid:'.length).trim());
             ppid = Number.isSafeInteger(value) ? value : null;
         }
-        catch {
-            // Ended between the listing and the read — says nothing either way.
+        catch (error) {
+            /**
+             * Two different answers wearing one coat, and the difference decides
+             * whether a live session may be stopped (независимая проверка #431).
+             *
+             * `ENOENT`/`ESRCH` is the kernel saying the process ended between the
+             * listing and the read — it says nothing either way, and the scan goes
+             * on. Anything else (`EACCES` under `hidepid`, `EMFILE` on a busy
+             * daemon, `EIO`) is a /proc we could not read, and «could not read» has
+             * exactly one safe reading in this function: `unknown`, which is never
+             * swept. Until the tree rule above, a live session survived this by
+             * accident — its neighbours' parents were alive; now the agent's own
+             * line is the only voice for «somebody is working here», and losing it
+             * must not read as «litter».
+             */
+            if (!processIsGone(error))
+                sawUnknown = true;
             continue;
         }
         if (ppid === null) {
@@ -1618,6 +1836,10 @@ export function scopeOwnerLiveness(unit, io = {}) {
         // answer for a process that is going away.
         if (ppid <= 1)
             continue;
+        // A parent in the SAME cage is a neighbour, not an owner: it is part of the
+        // same abandoned tree, and its own parent is asked about in its own turn.
+        if (inside.has(ppid))
+            continue;
         /**
          * …and reparented to the USER MANAGER counts the same (measured 10.09.2026).
          *
@@ -1632,8 +1854,12 @@ export function scopeOwnerLiveness(unit, io = {}) {
         try {
             parentComm = readFile(path.join('/proc', String(ppid), 'comm')).trim();
         }
-        catch {
+        catch (error) {
             // The parent went between the two reads: it is not supervising anything.
+            // Anything other than «it is gone» is a /proc we could not read — see the
+            // catch above; the same rule, for the same reason.
+            if (!processIsGone(error))
+                sawUnknown = true;
             continue;
         }
         if (parentComm === 'systemd' || parentComm === 'init')

package/dist/session-stall.d.ts

@@ -305,6 +305,31 @@ export declare function readScopeProcesses(unit: string, readFile?: (p: string)
  *    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;
+/**
+ * How many COMMANDS this session has running, counted the way a person counts
+ * them (#431).
+ *
+ * Used on the way out: the runner is about to take the cage down with it, and
+ * the line it writes into the feed has to say how much work that costs. The
+ * number must therefore mean what the sentence says – «commands», not
+ * «processes»: `bash -lc 'docker compose up'` is three or four processes and
+ * exactly one command, and a person who is told «7 processes were stopped»
+ * learns nothing they can act on.
+ *
+ * The exclusions are {@link pickKillCandidate}'s, for the same reasons and with
+ * the same reading of `agentPid`:
+ *
+ *  - **the agent is not a command.** It is the root of the tree, and stopping
+ *    it is what the restart is.
+ *  - **MCP servers and everything under them are not commands.** They are the
+ *    agent's own plumbing; the session did not ask for them and nothing of the
+ *    person's work is lost with them.
+ *
+ * `git` is NOT excluded here, though it is excluded there: that rule exists so
+ * the memory brake does not leave `.git/index.lock` behind, and this function
+ * stops nothing – it counts what is about to go either way.
+ */
+export declare function countRunningCommands(processes: ScopeProcess[], agentPid?: number | null): number;
 /**
  * Is this pid still the process it was when we decided to stop it?
  *

package/dist/session-stall.js

@@ -668,6 +668,90 @@ export function pickKillCandidate(processes, agentPid = null) {
     }
     return best;
 }
+/**
+ * How many COMMANDS this session has running, counted the way a person counts
+ * them (#431).
+ *
+ * Used on the way out: the runner is about to take the cage down with it, and
+ * the line it writes into the feed has to say how much work that costs. The
+ * number must therefore mean what the sentence says – «commands», not
+ * «processes»: `bash -lc 'docker compose up'` is three or four processes and
+ * exactly one command, and a person who is told «7 processes were stopped»
+ * learns nothing they can act on.
+ *
+ * The exclusions are {@link pickKillCandidate}'s, for the same reasons and with
+ * the same reading of `agentPid`:
+ *
+ *  - **the agent is not a command.** It is the root of the tree, and stopping
+ *    it is what the restart is.
+ *  - **MCP servers and everything under them are not commands.** They are the
+ *    agent's own plumbing; the session did not ask for them and nothing of the
+ *    person's work is lost with them.
+ *
+ * `git` is NOT excluded here, though it is excluded there: that rule exists so
+ * the memory brake does not leave `.git/index.lock` behind, and this function
+ * stops nothing – it counts what is about to go either way.
+ */
+export function countRunningCommands(processes, agentPid = null) {
+    if (processes.length === 0)
+        return 0;
+    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]);
+    }
+    const roots = processes.filter((p) => !byPid.has(p.ppid)).map((p) => p.pid);
+    /**
+     * The agent, and ONLY the agent, when its pid is known (independent review of
+     * #431).
+     *
+     * `pickKillCandidate` protects every parentless process, and there that is
+     * right: it chooses something to KILL, and a command wrongly spared costs a
+     * retry while the agent wrongly killed costs the session. Counting is the
+     * other way round. A cage has more than one parentless process whenever the
+     * agent left something behind it — `setsid`, `nohup pnpm dev &`, a double
+     * fork: the child stays in the cgroup and is reparented to the user manager,
+     * OUTSIDE the cage. Measured on this machine 16.09.2026: such a command was
+     * counted as zero, so the person was told nothing at all while it was being
+     * stopped — the exact silence this line exists to break (#427).
+     */
+    const excluded = new Set(agentPid === null ? roots : [agentPid]);
+    const spread = (pid) => {
+        for (const child of children.get(pid) ?? []) {
+            if (excluded.has(child))
+                continue;
+            excluded.add(child);
+            spread(child);
+        }
+    };
+    for (const p of processes) {
+        if (!p.mcp)
+            continue;
+        excluded.add(p.pid);
+        // …but never from the agent: its own command line names the MCP config, so
+        // spreading from it would hide every command it ever started.
+        const isAgent = agentPid === null ? roots.includes(p.pid) : p.pid === agentPid;
+        if (!isAgent)
+            spread(p.pid);
+    }
+    let commands = 0;
+    for (const p of processes) {
+        if (excluded.has(p.pid))
+            continue;
+        // Only the top of each surviving subtree: a process whose parent is also a
+        // command is part of that command, not another one.
+        if (byPid.has(p.ppid) && !excluded.has(p.ppid))
+            continue;
+        commands += 1;
+    }
+    return commands;
+}
 /**
  * Is this pid still the process it was when we decided to stop it?
  *

package/dist/supervisor.d.ts

@@ -186,6 +186,19 @@ export interface SupervisorOptions {
      * it never calls it twice at once. Production sweeps for real.
      */
     sweepOrphanSessionScopes?: (liveIds: Iterable<string>) => Promise<string[]>;
+    /**
+     * #431: taking a session's cage down together with its agent. A test has no
+     * systemd to answer, and the daemon must not need one to be testable here.
+     */
+    stopSessionScope?: (unit: string | null) => Promise<boolean>;
+    /** How long those stops are given. The real one is 3 s — no suite waits it out. */
+    cageStopBudgetMs?: number;
+    /**
+     * Which pid in a cage is the agent. Production reads the register the spawn
+     * filled; without the seam every test counted commands through the fallback
+     * branch, i.e. never the one the daemon uses (independent review of #431).
+     */
+    sessionAgentPid?: (id: string) => number | null;
     /**
      * #398 S2: the stall mechanism's four doors to the machine.
      *
@@ -765,6 +778,16 @@ export declare class Supervisor {
      */
     private publishBackgroundHeartbeats;
     private publishHostLoad;
+    /**
+     * Set by {@link shutdown}, and read wherever this supervisor could still be
+     * ASKED to do something after it has let go of everything (#431).
+     *
+     * It exists because the daemon now outlives `shutdown()` by up to three
+     * seconds — the time its cages are given to stop. Until that change every
+     * caller exited in the same tick and «after shutdown» was not a state
+     * anything could be in.
+     */
+    private shuttingDown;
     private onFrame;
     private startSession;
     /**
@@ -1601,8 +1624,49 @@ export declare class Supervisor {
      */
     private sendEvent;
     private reportStatus;
-    /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
-    shutdown(): void;
+    /**
+     * How long the whole fleet of cages is given to stop before this process goes
+     * anyway (#431).
+     *
+     * The bus has been measured at 2.7 s under load and the stops run in
+     * parallel, so three seconds is room for all of them on a bad day. Going over
+     * it costs nothing: `stop` has been ACCEPTED by then, and systemd finishes
+     * the job whether or not anybody is still here to watch. systemd's own
+     * patience with this service is `TimeoutStopSec`, far above this.
+     */
+    private static readonly CAGE_STOP_BUDGET_MS;
+    /**
+     * Graceful daemon shutdown: kill agents, take their cages with them, keep
+     * sessions resumable server-side.
+     *
+     * **Everything that has to survive this process happens BEFORE the first
+     * `await`** — the withdrawn cards, the feed line, and the word to each agent
+     * that it is over (a signal for Codex; for Claude, stdin closed and the SDK's
+     * own `close()`, whose SIGTERM is a timer this process will not live to see —
+     * on a caged machine what actually ends it is the stop below). A caller that
+     * does not wait (the suite does not) gets exactly the shutdown it always got;
+     * what it misses is only the stop of the cgroups. Written this way rather
+     * than as two methods because «kill the agent» and «put its cage out» are one
+     * action, and the shape of the code is what stops them drifting apart again
+     * (грабля §479).
+     *
+     * What the caller owes in return: close the socket between the two halves.
+     * The events above need it open, and the seconds below must not be a window
+     * in which a `session_start` arrives at a supervisor that has already let go
+     * of everything (`index.ts`).
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Put out every cage this daemon was holding, in parallel and on a clock.
+     *
+     * Until 0.65.0 nothing did this: `releaseSessionScope` hangs off the agent
+     * process's `exit`, and on a restart the daemon is gone before that event
+     * fires. What stayed behind was a whole tree — a build, its docker client,
+     * their children — holding the name of a scope systemd will then refuse to
+     * reuse, so the FIRST start of that session after the restart died as
+     * «exited before the session was ready (code 1)» (#431).
+     */
+    private stopCages;
 }
 /**
  * The first message the agent gets.

package/dist/supervisor.js

@@ -28,9 +28,9 @@ import { cageAuthority } from './cage-authority.js';
 import { invalidateAgentVersions, measureAgentVersions, } from './agent-versions.js';
 import { rememberWorkspacePath } from './environment.js';
 import { hostLoadChangedEnough, hostLoadHeartbeatDue, readHostLoad, HOST_LOAD_HEARTBEAT_MS, HOST_LOAD_SAMPLE_INTERVAL_MS, } from './host-load.js';
-import { markScopeOomKillsSeen, readScopeHold, readScopeMemoryStatus, readSliceLimits, sessionAgentPid, sessionCage, sessionScopeUnitOf, setLiveLadderSource, stoppedProcesses, sweepOrphanSessionScopes, } from './session-cage.js';
+import { markScopeOomKillsSeen, readScopeHold, readScopeMemoryStatus, readSliceLimits, restartStoppedCommands, sessionAgentPid, sessionCage, sessionScopeUnitOf, setLiveLadderSource, stopSessionScope, stoppedProcesses, sweepOrphanSessionScopes, } from './session-cage.js';
 import { allocateSessionMemory, planLimitMove, SESSION_GUARANTEE_BYTES, } from './session-allocator.js';
-import { freshStallState, pickKillCandidate, readScopeProcesses, readStallSample, setScopeProperties, signalSubtree, stallStep, STALL_GRACE_MS, STALL_MUTE_AFTER_LOWER_MS, STALL_SIGKILL_AFTER_MS, STALL_WINDOW_MS, } from './session-stall.js';
+import { countRunningCommands, freshStallState, pickKillCandidate, readScopeProcesses, readStallSample, setScopeProperties, signalSubtree, stallStep, STALL_GRACE_MS, STALL_MUTE_AFTER_LOWER_MS, STALL_SIGKILL_AFTER_MS, STALL_WINDOW_MS, } from './session-stall.js';
 import { machineReserveBytes } from './service-unit.js';
 import { sessionLimitsChangedEnough, sessionLimitsHeartbeatDue, SESSION_LIMITS_HEARTBEAT_MS, } from './session-limits.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
@@ -1693,7 +1693,28 @@ export class Supervisor {
             this.lastHostLoadSentAt = now;
         }
     }
+    /**
+     * Set by {@link shutdown}, and read wherever this supervisor could still be
+     * ASKED to do something after it has let go of everything (#431).
+     *
+     * It exists because the daemon now outlives `shutdown()` by up to three
+     * seconds — the time its cages are given to stop. Until that change every
+     * caller exited in the same tick and «after shutdown» was not a state
+     * anything could be in.
+     */
+    shuttingDown = false;
     async onFrame(frame) {
+        /**
+         * Nothing from the wire is answered once the shutdown has started.
+         *
+         * The socket is closed right after the synchronous half of `shutdown()`,
+         * but closing is a handshake: a frame already in flight still lands. The
+         * client refuses to deliver it (`ws-client.ts`) and this is the second
+         * door, on the side that would act on it — an `event_ack` here deletes the
+         * journal of a session this supervisor has already released.
+         */
+        if (this.shuttingDown)
+            return;
         switch (frame.type) {
             case 'hello_ack':
                 this.helloAcked = true;
@@ -1866,6 +1887,21 @@ export class Supervisor {
      * the ask any more.
      */
     withdrawReason = 'not_held') {
+        /**
+         * Nothing is started once this runner is going down (#431).
+         *
+         * The wire is already shut by then, but this door has a second caller: the
+         * tail of `pumpEvents`, which runs a microtask after the agent's stream
+         * ends — and since the shutdown waits for its cages, the process is still
+         * here to run it. What it would build first is a worktree and a branch, and
+         * what it would build last is a fresh cage, moments before `process.exit`.
+         */
+        if (this.shuttingDown) {
+            log.warn('supervisor: not starting a session, this runner is going down', {
+                sessionId: descriptor.id,
+            });
+            return;
+        }
         const existing = this.sessions.get(descriptor.id);
         if (existing) {
             // A resume (higher epoch) can land while the previous life is still
@@ -2192,6 +2228,22 @@ export class Supervisor {
             });
             return LAUNCH_REFUSED;
         }
+        /**
+         * …and no agent at all once the daemon is on its way out (#431).
+         *
+         * The five one-shot relaunches live in the tail of `pumpEvents`, which runs
+         * a microtask after the event stream of the dying process ends — and since
+         * the shutdown waits for its cages, the process is still here to run it.
+         * A launch there would put a NEW cage on the machine moments before
+         * `process.exit`, leaving behind exactly the orphan this ticket is about.
+         * Found by the independent review of #431.
+         */
+        if (this.shuttingDown) {
+            log.warn('supervisor: not launching an agent, this runner is going down', {
+                sessionId: descriptor.id,
+            });
+            return LAUNCH_REFUSED;
+        }
         // An exhausted USD budget must not relaunch $0.01-floor processes (QA-96 F4).
         // Codex reports no cost at all, so its costUsd never leaves 0 — gating on it
         // would be a limit that can never fire while the UI shows $0.00. Those
@@ -7676,8 +7728,40 @@ export class Supervisor {
         // changed, and the interval in the constructor is the net under both.
         this.publishSlots();
     }
-    /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
-    shutdown() {
+    /**
+     * How long the whole fleet of cages is given to stop before this process goes
+     * anyway (#431).
+     *
+     * The bus has been measured at 2.7 s under load and the stops run in
+     * parallel, so three seconds is room for all of them on a bad day. Going over
+     * it costs nothing: `stop` has been ACCEPTED by then, and systemd finishes
+     * the job whether or not anybody is still here to watch. systemd's own
+     * patience with this service is `TimeoutStopSec`, far above this.
+     */
+    static CAGE_STOP_BUDGET_MS = 3_000;
+    /**
+     * Graceful daemon shutdown: kill agents, take their cages with them, keep
+     * sessions resumable server-side.
+     *
+     * **Everything that has to survive this process happens BEFORE the first
+     * `await`** — the withdrawn cards, the feed line, and the word to each agent
+     * that it is over (a signal for Codex; for Claude, stdin closed and the SDK's
+     * own `close()`, whose SIGTERM is a timer this process will not live to see —
+     * on a caged machine what actually ends it is the stop below). A caller that
+     * does not wait (the suite does not) gets exactly the shutdown it always got;
+     * what it misses is only the stop of the cgroups. Written this way rather
+     * than as two methods because «kill the agent» and «put its cage out» are one
+     * action, and the shape of the code is what stops them drifting apart again
+     * (грабля §479).
+     *
+     * What the caller owes in return: close the socket between the two halves.
+     * The events above need it open, and the seconds below must not be a window
+     * in which a `session_start` arrives at a supervisor that has already let go
+     * of everything (`index.ts`).
+     */
+    async shutdown() {
+        // First line: every door that could put work back on this machine reads it.
+        this.shuttingDown = true;
         clearInterval(this.slotsTimer);
         clearInterval(this.hostLoadTimer);
         clearInterval(this.stallTimer);
@@ -7686,6 +7770,10 @@ export class Supervisor {
         clearTimeout(this.agentCleanupFirstTimer);
         clearInterval(this.agentCleanupTimer);
         this.authRelay.cancel();
+        const unitOf = this.opts.sessionScopeUnitOf ?? sessionScopeUnitOf;
+        const readProcesses = this.opts.readScopeProcesses ?? readScopeProcesses;
+        const agentPidOf = this.opts.sessionAgentPid ?? sessionAgentPid;
+        const cages = [];
         for (const running of this.sessions.values()) {
             this.clearBudgetTimers(running);
             // BEFORE stop(), and from here rather than from the adapter: the adapter
@@ -7707,15 +7795,86 @@ export class Supervisor {
                     error: String(error),
                 });
             }
+            /**
+             * What this restart costs, in the person's units, before anything is
+             * killed (#431).
+             *
+             * The count comes from the cage itself rather than from anything this
+             * process believes: the runner does not track what the agent started —
+             * that is the whole shape of the problem — and the cgroup does. Read
+             * BEFORE `stop()`, because a moment later there is nothing left to count.
+             *
+             * Silent when the number is zero: an agent that was only thinking loses
+             * nothing, and «0 commands were stopped» is a line a person has to read
+             * and cannot use (D8).
+             */
+            const unit = unitOf(running.descriptor.id);
+            if (unit !== null) {
+                cages.push(unit);
+                try {
+                    const commands = countRunningCommands(readProcesses(unit), agentPidOf(running.descriptor.id));
+                    if (commands > 0) {
+                        this.sendEvent(running, 'notice', {
+                            level: 'warn',
+                            text: restartStoppedCommands(commands),
+                        });
+                    }
+                }
+                catch (error) {
+                    // /proc said nothing readable. The cage is still stopped below — the
+                    // person simply does not get the number.
+                    log.warn('supervisor: could not count what this session was running', {
+                        sessionId: running.descriptor.id,
+                        error: String(error),
+                    });
+                }
+            }
             // The reason matters here: this path also runs for «Update runner», and a
             // card that vanishes during an update must say why (session 12).
-            running.session?.stop('runner_restarted');
+            //
+            // Guarded like its neighbours in this loop: one adapter that throws on
+            // its way out must not cost every OTHER session the stop of its cage —
+            // the lines below it are what puts them out (independent review of #431).
+            try {
+                running.session?.stop('runner_restarted');
+            }
+            catch (error) {
+                log.warn('supervisor: an agent did not take its stop cleanly', {
+                    sessionId: running.descriptor.id,
+                    error: String(error),
+                });
+            }
         }
         this.sessions.clear();
         // A build that was mid-flight is abandoned, not judged: its row stays
         // RUNNING until the API's sweep turns it into LOST. A verdict nobody
         // observed must never become PASSED.
         this.verify.shutdown();
+        await this.stopCages(cages);
+    }
+    /**
+     * Put out every cage this daemon was holding, in parallel and on a clock.
+     *
+     * Until 0.65.0 nothing did this: `releaseSessionScope` hangs off the agent
+     * process's `exit`, and on a restart the daemon is gone before that event
+     * fires. What stayed behind was a whole tree — a build, its docker client,
+     * their children — holding the name of a scope systemd will then refuse to
+     * reuse, so the FIRST start of that session after the restart died as
+     * «exited before the session was ready (code 1)» (#431).
+     */
+    async stopCages(units) {
+        if (units.length === 0)
+            return;
+        const stop = this.opts.stopSessionScope ?? stopSessionScope;
+        log.info('supervisor: stopping the cages of this runner', { count: units.length });
+        const all = Promise.allSettled(units.map((unit) => stop(unit))).then(() => undefined);
+        let timer;
+        const budget = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.opts.cageStopBudgetMs ?? Supervisor.CAGE_STOP_BUDGET_MS);
+        });
+        await Promise.race([all, budget]);
+        if (timer)
+            clearTimeout(timer);
     }
 }
 /**

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.65.0";
+export declare const RUNNER_VERSION = "0.65.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.65.0';
+export const RUNNER_VERSION = '0.65.1';
 //# sourceMappingURL=version.js.map

package/dist/ws-client.js

@@ -137,6 +137,20 @@ export class RunnerWsClient {
             this.lastInboundAt = Date.now();
         });
         socket.on('message', (data) => {
+            /**
+             * A client that was stopped answers nothing, in either direction (#431).
+             *
+             * `close()` is the START of a handshake, not a cut: the socket lives on
+             * for a round trip, and this listener used to keep delivering frames off
+             * it. That was harmless while every caller of `stop()` exited in the same
+             * tick; since the daemon waits for its cages to be put out, the window is
+             * seconds wide, and the supervisor on the other side of `frame` has
+             * already let go of every session. An `event_ack` landing there DELETES
+             * the journal of a live session (found by the independent review of
+             * #431); a `session_start` starts an agent nobody will ever stop.
+             */
+            if (this.stopped)
+                return;
             this.lastInboundAt = Date.now();
             let parsed;
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.65.0",
+  "version": "0.65.1",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",