@bridge4dev/runner 0.64.1 → 0.65.1

package/dist/adapters/codex.js

@@ -6,6 +6,8 @@ import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
 import { truncate } from './claude.js';
+import { AgentTaskTray } from './agent-tasks.js';
+import { CodexSubagents, threadProbeOver } from './codex-subagents.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, folderRuleFor, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { clampPercent, rateWindowKeyFromMinutes } from './rate-limits.js';
 import { answerSummary, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -182,6 +184,24 @@ const APPROVAL_METHODS = new Set([
     'item/permissions/requestApproval',
     'mcpServer/elicitation/request',
 ]);
+/**
+ * Notifications that concern the whole session whichever thread they name
+ * (#382). Everything else from a thread other than the session's own belongs to
+ * a helper – see `CodexSession.onHelperNotification`.
+ *
+ *  - `serverRequest/resolved`: a helper's approval is shown as an ordinary card,
+ *    and the card has to close when it is answered elsewhere;
+ *  - MCP start-up and the warnings: the helpers share the session's servers and
+ *    configuration, and each distinct sentence is shown once anyway.
+ */
+const SESSION_WIDE = new Set([
+    'serverRequest/resolved',
+    'mcpServer/startupStatus/updated',
+    'configWarning',
+    'warning',
+    'guardianWarning',
+    'deprecationNotice',
+]);
 class CodexSession {
     spec;
     home;
@@ -236,6 +256,15 @@ class CodexSession {
     stopped = false;
     ready = false;
     capabilitiesInFlight = false;
+    /**
+     * Helpers at work beside the conversation (#382) – the same tray, and so the
+     * same «is anybody still working» rule, as the Claude adapter's.
+     */
+    tray = new AgentTaskTray({
+        emit: (event) => this.emit(event),
+        isStopped: () => this.stopped,
+    });
+    subagents;
     events = this.output;
     constructor(spec, home, deps) {
         this.spec = spec;
@@ -272,6 +301,16 @@ class CodexSession {
                 sessionId: spec.sessionId,
                 ...wiring,
             });
+        this.subagents = new CodexSubagents({
+            tray: this.tray,
+            ownThreadId: () => this.threadId,
+            probe: threadProbeOver((method, params, timeoutMs) => this.client.request(method, params, timeoutMs)),
+            isStopped: () => this.stopped,
+            ...(deps.subagentReconcileMs === undefined ? {} : { reconcileMs: deps.subagentReconcileMs }),
+            ...(deps.subagentSpawnGraceMs === undefined
+                ? {}
+                : { spawnGraceMs: deps.subagentSpawnGraceMs }),
+        });
         if (this.modeRefusedAtLaunch) {
             this.notice('warn', MODE_REFUSED_TEXT);
             this.emit({ type: 'settings', mode: this.mode });
@@ -307,6 +346,17 @@ class CodexSession {
                 throw new Error(`codex is using an unexpected CODEX_HOME (${reportedHome ?? 'not reported'}) — refusing to start the session`);
             }
             this.client.notify('initialized', {});
+            // The helper set is per PROCESS (#113, #382): a session relaunched after a
+            // runner restart must not go on showing the helpers of its previous life,
+            // and nothing else would say so until the next one starts or ends.
+            //
+            // Here and not in the constructor, and that is not tidiness: the
+            // supervisor reads the FIRST event of a session as «the process came up»
+            // and calls off the watch for a CLI that never boots (#225). A frame
+            // emitted before a single byte reached the app-server would answer that
+            // watch for every Codex session, on behalf of a process that has said
+            // nothing. This is the first moment the process really has.
+            this.tray.announceEmpty();
             if (this.home.auth === 'missing') {
                 // One repair attempt before telling the user their login is broken: the
                 // credential link can be removed under a running daemon, and putting it
@@ -956,6 +1006,9 @@ class CodexSession {
         if (this.stopped)
             return;
         this.stopped = true;
+        // The helpers go with the process; nothing more is published about them.
+        this.subagents.close();
+        this.tray.close();
         // Release anything the agent is blocked on so the child can exit cleanly —
         // and say in the feed that the runner did it, not the user. A pending card
         // used to gutter out looking like a human decision.
@@ -1262,6 +1315,17 @@ class CodexSession {
     }
     // ─── Notifications ─────────────────────────────────────────────────
     onNotification(method, params) {
+        // #382. One app-server runs the session's thread AND every helper it spawns,
+        // and the helpers' notifications arrive on this same connection tagged with
+        // their own thread id (measured on 0.154.0). Read as ours, a helper's
+        // `turn/completed` ended THIS session's turn while it was still working, its
+        // `turn/started` became the turn a Stop or a steer is aimed at, and its
+        // prose went into the feed as this session's answer.
+        const thread = str(params['threadId']);
+        if (thread && this.threadId && thread !== this.threadId && !SESSION_WIDE.has(method)) {
+            this.onHelperNotification(thread, method, params);
+            return;
+        }
         switch (method) {
             case 'item/started':
             case 'item/updated':
@@ -1417,21 +1481,100 @@ class CodexSession {
                 return;
         }
     }
+    /**
+     * A notification from another thread in this app-server – a helper's, or one
+     * of Codex's own (#382).
+     *
+     * What it may change is the helper count and, while a turn of this session is
+     * running, that turn's «work was done» flags – and nothing else: not the turn
+     * itself, not the feed, not the context meter or the settings on the header,
+     * and not the session's health. A helper's failure is the helper's; the one
+     * exception is the plan limit, which belongs to the account and refuses this
+     * session next. Its tool calls stay
+     * out of the feed too, and that is not tidiness: the supervisor reads any
+     * tool event from a resting session as «the agent is working» (#185), and no
+     * turn of THIS session would ever come to put it back – a helper finishing
+     * does not start one.
+     *
+     * Its items are still remembered: a helper's command that needs a person
+     * arrives as an ordinary approval request, and the card is only readable
+     * because the item behind it is known.
+     */
+    onHelperNotification(thread, method, params) {
+        switch (method) {
+            case 'item/started':
+            case 'item/updated':
+            case 'item/completed': {
+                const item = asRecord(params['item']);
+                this.rememberItem(item);
+                // What a helper does while this session's turn is running is that turn's
+                // work (#252, #257) – the Claude adapter counts a subagent's tool calls
+                // for the same reason: a helper's `git push` is still a push, and a
+                // failed turn that pushed must not be sent again as if nothing happened.
+                if (method === 'item/started' &&
+                    item['type'] === 'commandExecution' &&
+                    this.activeTurnId !== null &&
+                    this.subagents.isHelper(thread)) {
+                    this.noteWork(str(item['command']) ?? '');
+                }
+                this.subagents.onItem(thread, item);
+                return;
+            }
+            case 'turn/started':
+                this.subagents.onHelperTurn(thread, 'started');
+                return;
+            case 'turn/completed': {
+                const turn = asRecord(params['turn']);
+                // A helper refused by the plan limit is this ACCOUNT being refused: the
+                // session's own next turn will be refused too, so the API is told and
+                // the feed says why (#382). Only the announcement — no turn of this
+                // session ended, so there is no ending to mark `limitBlocked`.
+                if (str(turn['status']) === 'failed') {
+                    this.announceRateLimitRefusal(asRecord(turn['error']));
+                }
+                this.subagents.onHelperTurn(thread, 'completed', str(turn['status']));
+                return;
+            }
+            case 'thread/closed':
+                this.subagents.onThreadClosed(thread);
+                return;
+            case 'error':
+                if (params['willRetry'] !== true && this.subagents.isHelper(thread)) {
+                    const detail = asRecord(params['error']);
+                    // The one failure of a helper that is not the helper's own business:
+                    // the plan limit is the account's, and the session is next (#382).
+                    if (!this.announceRateLimitRefusal(detail)) {
+                        log.warn('codex: a helper agent reported an error', {
+                            sessionId: this.spec.sessionId,
+                            message: maskString(str(detail['message']) ?? '').slice(0, 300),
+                        });
+                    }
+                }
+                return;
+            default:
+                return;
+        }
+    }
+    /** Keep an item's last state – approval params alone are too thin. */
+    rememberItem(item) {
+        const id = str(item['id']);
+        if (!id)
+            return;
+        this.items.set(id, item);
+        // Bound the cache: a long session would otherwise hold every item.
+        if (this.items.size > 400) {
+            const oldest = this.items.keys().next().value;
+            if (oldest !== undefined)
+                this.items.delete(oldest);
+        }
+    }
     onItem(method, params) {
         const item = asRecord(params['item']);
         const type = str(item['type']);
         const id = str(item['id']);
         if (!type)
             return;
-        if (id) {
-            this.items.set(id, item);
-            // Bound the cache: a long session would otherwise hold every item.
-            if (this.items.size > 400) {
-                const oldest = this.items.keys().next().value;
-                if (oldest !== undefined)
-                    this.items.delete(oldest);
-            }
-        }
+        this.rememberItem(item);
         const done = method === 'item/completed';
         switch (type) {
             case 'agentMessage': {
@@ -1556,6 +1699,17 @@ class CodexSession {
                 }
                 return;
             }
+            case 'collabAgentToolCall':
+            case 'subAgentActivity': {
+                // #382: helpers starting, being handed work and finishing. Counted, and
+                // deliberately NOT a feed row: a helper's `completed` arrives after this
+                // session's turn is over, and a tool event then would put a resting
+                // session back to «working» with no turn to end it (see
+                // `onHelperNotification`).
+                if (this.threadId)
+                    this.subagents.onItem(this.threadId, item);
+                return;
+            }
             case 'webSearch':
             case 'dynamicToolCall': {
                 if (!done) {
@@ -1741,6 +1895,29 @@ class CodexSession {
      * one turn.
      */
     static LIMIT_SETTLE_MS = 180_000;
+    /**
+     * The plan is spent: tell the API so it can arm its clock, and tell the
+     * person in the feed. Says nothing about whose turn it was.
+     *
+     * Split out of `noteRateLimitRefusal` for the refusals that belong to no turn
+     * of this session at all — a helper's (#382). The block is account-wide: the
+     * same account, the same window, and the next turn of the session will be
+     * refused too. Silence here was a false «your turn» over a plan that had run
+     * out, with nothing in the feed to explain it and no pause armed.
+     */
+    announceRateLimitRefusal(error) {
+        const blocked = this.rateLimitRefusal(error);
+        if (!blocked)
+            return false;
+        this.emitRateLimits(blocked);
+        this.emit({
+            type: 'notice',
+            level: 'warn',
+            text: 'Codex refused the turn: the plan limit is spent' +
+                (blocked.resetsAt ? `, and it lifts at ${describeResetTime(blocked.resetsAt)}.` : '.'),
+        });
+        return true;
+    }
     /**
      * The plan is spent — say so, and keep the session alive to be woken.
      *
@@ -1758,16 +1935,8 @@ class CodexSession {
      * feed of the session this was found on.
      */
     noteRateLimitRefusal(error) {
-        const blocked = this.rateLimitRefusal(error);
-        if (!blocked)
+        if (!this.announceRateLimitRefusal(error))
             return false;
-        this.emitRateLimits(blocked);
-        this.emit({
-            type: 'notice',
-            level: 'warn',
-            text: 'Codex refused the turn: the plan limit is spent' +
-                (blocked.resetsAt ? `, and it lifts at ${describeResetTime(blocked.resetsAt)}.` : '.'),
-        });
         /**
          * The flag is set ONLY while a turn is in flight, and that is not caution.
          *
@@ -1800,6 +1969,7 @@ class CodexSession {
                 // is still working — a steer would be aimed at a turn that has ended,
                 // and the next real turn would look like a turn already in flight.
                 this.activeTurnId = null;
+                this.subagents.endTurn();
                 this.emit({
                     type: 'turn_end',
                     ok: false,
@@ -1864,6 +2034,10 @@ class CodexSession {
             return;
         }
         this.activeTurnId = null;
+        // #382: what is still running, said BEFORE the ending – the supervisor
+        // decides «is this the person's turn» on the count it holds when `turn_end`
+        // arrives.
+        this.subagents.endTurn();
         // A held plan means the turn ended by proposing, not by finishing the work.
         if (this.heldPlan)
             return;
@@ -1945,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,
@@ -2310,6 +2507,8 @@ class CodexSession {
     finish() {
         this.stopped = true;
         this.clearLimitSettle();
+        this.subagents.close();
+        this.tray.close();
         this.output.end();
     }
 }

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 {