@bridge4dev/runner 0.45.1 → 0.47.0

package/dist/self-update.d.ts

@@ -45,6 +45,12 @@ export interface SelfUpdateOptions {
     packageDir?: string | null;
     /** Test seam: is this process supervised (defaults to autodetect). */
     supervised?: boolean;
+    /**
+     * Test seam for C4: whether this build runs sessions on the Claude binary
+     * bundled with it. Both branches must be provable — the `false` one is what
+     * stops every future runner update from rolling itself back.
+     */
+    bundledClaude?: boolean;
     /**
      * Test seam for the resource-limits drop-in. Injected rather than called
      * directly because the real one writes into `$HOME` — a test that exercised
@@ -134,4 +140,12 @@ export declare function manualUpdateCommand(tarballUrl: string, options?: {
     packageDir?: string | null;
 }): string;
 export declare function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdateOutcome>;
+/**
+ * The same reading of a failed child process, for `agent-install.ts`.
+ *
+ * Exported rather than copied: installing an agent CLI shells out to the very
+ * same npm, and a second implementation would drift into reporting the ERESOLVE
+ * wall this one exists to suppress.
+ */
+export declare function describeCommandFailure(error: unknown): string;
 //# sourceMappingURL=self-update.d.ts.map

package/dist/self-update.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { findClaudeCli } from './agent-binary.js';
+import { findClaudeCli, USE_BUNDLED_CLAUDE } from './agent-binary.js';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
@@ -237,18 +237,32 @@ function installArgs(source, prefix) {
     // npm cheerfully installs a SECOND copy somewhere the service does not exec,
     // reports success, and the runner restarts on the old version forever.
     //
-    // `--include=optional` is npm's default and is stated anyway (ticket #225):
-    // the Claude CLI ships as an OPTIONAL platform package, and a single
-    // `omit=optional` inherited from an `.npmrc`, an environment variable or a CI
-    // habit turns an update into a runner that cannot start a single Claude
-    // session — silently, because for npm a failed optional dependency is not a
-    // failure at all. The flag makes this deployment's intent explicit rather
-    // than dependent on whatever configuration the machine happens to carry.
+    // `--omit=optional` since 0.47.0, and it used to be its exact opposite.
+    //
+    // Until C3 the Claude CLI a session ran on WAS an optional platform package of
+    // the Agent SDK inside this package, so `--include=optional` was stated
+    // explicitly (ticket #225): a single `omit=optional` inherited from an
+    // `.npmrc` produced a runner that could not start one Claude session, and npm
+    // called that a success. Sessions now run on the system `claude` — installed,
+    // measured and updated like any other agent — so the 215 MB binary in here is
+    // no longer used by anything, and downloading it on every update would be a
+    // tax on every dev server for a file nothing opens.
+    //
+    // Read this beside `npmInstallArgs` in `agent-install.ts`, which says
+    // `--include=optional` and is not a contradiction: DIFFERENT packages. The
+    // runner no longer wants Claude's platform binary; `@openai/codex` keeps its
+    // own 320 MB executable in exactly such an optional package, and installing
+    // Codex without it yields a shim that cannot run — with npm exiting 0 either
+    // way (гоча #297, and #415 for the Codex half).
+    //
+    // C4 is what makes this safe: the bundled-binary check below is conditional on
+    // `USE_BUNDLED_CLAUDE`, so an update that no longer ships the binary is not
+    // read as a broken install and rolled back on every single machine, forever.
     return [
         'install',
         '-g',
         '--ignore-scripts',
-        '--include=optional',
+        '--omit=optional',
         '--loglevel=error',
         ...(prefix ? ['--prefix', prefix] : []),
         source,
@@ -269,7 +283,7 @@ export function manualUpdateCommand(tarballUrl, options = {}) {
     const prefix = options.prefix === undefined ? installPrefixFor(packageDir) : options.prefix;
     const user = options.user ?? os.userInfo().username;
     const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : -1);
-    const install = ['npm install -g --ignore-scripts --include=optional --loglevel=error']
+    const install = ['npm install -g --ignore-scripts --omit=optional --loglevel=error']
         .concat(prefix ? [`--prefix ${prefix}`] : [])
         .concat([tarballUrl])
         .join(' ');
@@ -367,6 +381,7 @@ export async function selfUpdate(options) {
     }
     // Derived once and threaded through every npm call below.
     const prefix = installPrefixFor(packageDir);
+    const usesBundledClaude = options.bundledClaude ?? USE_BUNDLED_CLAUDE;
     // Pack the current version FIRST: without a rollback artefact there is no
     // honest way back if the new build turns out to be broken.
     const rollbackDir = path.join(stateDir(), 'rollback');
@@ -442,7 +457,14 @@ export async function selfUpdate(options) {
     // One repair attempt first, because that is what the failure usually deserves:
     // a 300 MB optional package that did not download is a network hiccup, not a
     // broken release, and reinstalling it is cheaper for the user than a rollback.
-    if (!findClaudeCli(newPackageDir)) {
+    //
+    // Conditional since C4, and it has to be: after `USE_BUNDLED_CLAUDE` flips,
+    // the runner is installed WITHOUT that optional package on purpose (`--omit=
+    // optional`, −215 MB), so an unconditional check would find it missing and
+    // roll back every single runner update, for ever. The check is not deleted —
+    // while the bundled binary is what sessions run on, its absence is still the
+    // 2026-08-11 outage waiting to happen.
+    if (usesBundledClaude && !findClaudeCli(newPackageDir)) {
         log.warn('self-update: the Claude CLI is missing from the new build — repairing', {
             packageDir: newPackageDir,
         });
@@ -453,7 +475,7 @@ export async function selfUpdate(options) {
             log.warn('self-update: the repair install failed', { error: describe(error) });
         }
     }
-    if (!findClaudeCli(newPackageDir)) {
+    if (usesBundledClaude && !findClaudeCli(newPackageDir)) {
         log.error('self-update: still no Claude CLI after the repair — rolling back', {
             packageDir: newPackageDir,
         });
@@ -465,7 +487,7 @@ export async function selfUpdate(options) {
         }
         catch (rollbackError) {
             return fail(`The new version is broken (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
-                `Restore it on the server with: npm install -g --include=optional${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+                `Restore it on the server with: npm install -g --omit=optional${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
     // The service unit may be pinned to a file inside the directory this update
@@ -553,4 +575,14 @@ function describe(error) {
     const meaningful = npmErrors || raw;
     return meaningful.length > 400 ? `…${meaningful.slice(-400)}` : meaningful;
 }
+/**
+ * The same reading of a failed child process, for `agent-install.ts`.
+ *
+ * Exported rather than copied: installing an agent CLI shells out to the very
+ * same npm, and a second implementation would drift into reporting the ERESOLVE
+ * wall this one exists to suppress.
+ */
+export function describeCommandFailure(error) {
+    return describe(error);
+}
 //# sourceMappingURL=self-update.js.map

package/dist/supervisor.d.ts

@@ -1,6 +1,9 @@
 import { JournalStore } from './journal.js';
 import { proposeCommitMessage } from './commit-message.js';
 import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
+import { installAgent } from './agent-install.js';
+import { pruneNativeClaudeVersions } from './agent-cleanup.js';
+import { type AgentVersionsMeasurement } from './agent-versions.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
 import type { AgentAdapter } from './adapters/types.js';
@@ -53,6 +56,50 @@ export interface SupervisorOptions {
      * announced and no rewind can be started.
      */
     checkpointsEnabled?: boolean;
+    /**
+     * Test seam for the agent version measurement.
+     *
+     * A seam and not a detail: the real one spawns `claude`, `codex` and their
+     * doctors, and this class is constructed in every supervisor test — an
+     * unstubbed probe would run four processes per test file, on machines that
+     * may have neither CLI.
+     */
+    measureAgentVersions?: (options?: {
+        force?: boolean;
+    }) => Promise<AgentVersionsMeasurement>;
+    /**
+     * `[agents] install_enabled` from the runner's own config (#371), by the same
+     * rule as `[verify]` and `[checkpoints]`. Announced AND enforced: an API that
+     * has not noticed the veto still cannot install anything here.
+     */
+    agentInstallEnabled?: boolean;
+    /**
+     * Test seam for installing an agent CLI. The real one downloads 200–330 MB
+     * and writes into the npm prefix — not something a unit test may do.
+     */
+    installAgent?: typeof installAgent;
+    /**
+     * Test seam for the Р12 sweep of old Claude version files.
+     *
+     * A seam because the real one deletes 300 MB executables out of `$HOME`, and
+     * the thing worth testing HERE is not the deletion — that is
+     * `agent-cleanup.test.ts` — but the gate in front of it: no sessions, no
+     * install running. A test that had to move `$HOME` to prove a conditional
+     * would be proving the wrong thing in the wrong place.
+     */
+    pruneAgentVersions?: typeof pruneNativeClaudeVersions;
+    /**
+     * Test seam: how often the Р12 sweep runs, in ms — the first pass and every
+     * one after it.
+     *
+     * The same reason `emptyTurnSettleMs` exists. The real numbers are an hour
+     * and a day; no suite can wait either out, and fake timers are not an option
+     * here — they fire the WS client's liveness watchdog, which terminates the
+     * socket as «half-dead» and leaves the supervisor receiving nothing at all.
+     * Without this seam the gate in front of the sweep would never be executed by
+     * a test. Never set in production.
+     */
+    agentCleanupMs?: number;
     /**
      * How long a turn that produced nothing is held before it counts (#300).
      *
@@ -117,12 +164,121 @@ export declare class Supervisor {
      * than having no restore point for that one message.
      */
     private readonly repoLockDepth;
-    /** An update is installing right now — a second one would fight it. */
-    private selfUpdateInFlight;
+    /**
+     * One install at a time on this machine, whoever asked for it.
+     *
+     * `self_update` and `agent_install` both end in `npm install -g` into the
+     * SAME npm prefix under the dedicated-user layout, so two of them at once is
+     * a real conflict rather than a theoretical one. The API takes a Redis lock
+     * before pressing either button, but that lock cannot cover an install the
+     * runner starts by itself (stage D) — and the runner has no Redis. This is
+     * the only lock that sees both.
+     *
+     * Holds the holder's name rather than a boolean, so the refusal can say
+     * which of the two is running.
+     */
+    private installInFlight;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     private readonly verify;
     private readonly verifyReports;
     constructor(ws: RunnerWsClient, opts: SupervisorOptions);
+    /** How often the agent versions are re-derived. See the constructor. */
+    private static readonly AGENT_VERSIONS_INTERVAL_MS;
+    private readonly agentVersionsTimer;
+    /**
+     * Tell the API which agents this machine has and at which versions.
+     *
+     * Never throws and never blocks its caller: a machine where a probe hangs
+     * must still start sessions. A frame that could not be written is simply not
+     * sent — the next `hello_ack` or the hourly tick carries the same fact, and
+     * the measurement behind it is cached, so retrying is nearly free.
+     */
+    /**
+     * Why an install cannot start right now, in words for the person who pressed.
+     *
+     * `null` means the way is clear.
+     */
+    private installBusyReason;
+    /**
+     * A version change that has happened but has not reached the API yet.
+     *
+     * `ws.send` returns false when the socket is down, and an install finishing
+     * during a reconnect is not a rare case — it is a 300 MB download that takes
+     * minutes. The VERSION recovers on its own (the hourly tick and every
+     * `hello_ack` re-send the measurement), but `reason` and `changed` are the
+     * audit line itself: dropped, «why is my Codex suddenly different» has no
+     * answer anywhere, which is precisely what Р14 exists to prevent.
+     *
+     * Kept in memory rather than on disk on purpose. A daemon that died mid-install
+     * has a bigger hole than one lost line, and persisting it would risk filing an
+     * install that a rollback then undid.
+     */
+    private readonly pendingVersionChanges;
+    /**
+     * Two installs cannot overlap — the local lock sees to that — but two can
+     * both FINISH inside one outage, and each is a line the log owes. A queue
+     * rather than a slot, because the second would otherwise overwrite the first
+     * and the older install would be the one that vanished.
+     *
+     * Bounded: an outage long enough to strand nine installs is one where the
+     * missing audit lines are not the problem worth solving.
+     */
+    private static readonly MAX_PENDING_VERSION_CHANGES;
+    publishAgentVersions(reason: 'measured' | 'manual' | 'auto', changed?: {
+        agent: string;
+        from: string | null;
+        to: string;
+    }): Promise<void>;
+    private queueVersionChange;
+    /**
+     * Р13: the agent of a starting session, moved forward in the background.
+     *
+     * The whole mechanism hangs off ONE fact — whether the API put a version in
+     * the descriptor. It does that only for machines whose «Auto-update agents»
+     * switch is on, so there is no second copy of the setting here to disagree
+     * with it, and a runner that is told nothing does nothing.
+     *
+     * Never throws and never reports anything into the session feed. A person who
+     * pressed «start» asked for a session; a failed background download is not
+     * their business, and a scary red line about one would be worse than the
+     * silence. Where it IS visible is the server card: the `agent_versions` frame
+     * at the end goes out after every outcome, so a machine that ended up without
+     * a working agent says so within seconds rather than at the next hourly tick.
+     */
+    private maybeAutoUpdateAgent;
+    /** Once a day, per Р12 — the vendor adds at most one file a day. */
+    private static readonly AGENT_CLEANUP_INTERVAL_MS;
+    /** Long enough for `hello_ack` to have told us which sessions are live. */
+    private static readonly AGENT_CLEANUP_FIRST_DELAY_MS;
+    private readonly agentCleanupTimer;
+    private readonly agentCleanupFirstTimer;
+    /**
+     * Throw away the Claude version files nobody will run again (Р12, §4.7).
+     *
+     * Gated on NO LIVE AGENT PROCESS — `liveSessionCount`, not `sessions.size`.
+     *
+     * The stricter reading («nothing tracked at all») was the first version of
+     * this gate and it made the feature dead: parked sessions sit in that map
+     * until somebody closes them, so on any machine actually in use the sweep
+     * would never once have run, and Р12 would have shipped as a no-op nobody
+     * noticed. A parked session is not a risk to a version file either — it has
+     * no process, and when it wakes it relaunches through the launcher, which is
+     * the one file this sweep never touches.
+     *
+     * What guards a version somebody IS running is the per-file check in
+     * `agent-cleanup.ts` (`/proc/<pid>/exe`), which is the plan's own mechanism —
+     * «проверка по списку процессов». This gate is the cheap belt beside it: it
+     * keeps the sweep away from the minutes when Claude is most likely to be
+     * mid-spawn, where the process check has a window it cannot see.
+     *
+     * Also skipped while an install holds the lock: `claude install <version>` is
+     * rewriting the launcher right then, and «which file is current» has no stable
+     * answer until it finishes.
+     */
+    private sweepOldAgentVersions;
+    /** How often the seat report re-derives the truth. See the constructor. */
+    private static readonly SLOTS_REPORT_INTERVAL_MS;
+    private readonly slotsTimer;
     /**
      * Push every unacked verdict at the API.
      *
@@ -132,6 +288,38 @@ export declare class Supervisor {
      */
     private flushVerifyReports;
     get activeSessionIds(): string[];
+    /** The last set of seat-holders we told the API about, to send only changes. */
+    private lastPublishedSlots;
+    /**
+     * Tell the API which sessions are actually holding a seat here (0.46.0).
+     *
+     * The seat count is a property of THIS process, and until now the API could
+     * only guess it from its own rows. The guess was wrong whenever a session
+     * ended on paper without releasing its entry, and wrong in the direction that
+     * costs a person their session: the dashboard offers a seat, the create
+     * passes, this runner refuses, the session dies in fifty milliseconds.
+     *
+     * Called from `reportStatus` — the choke point every seat change already
+     * passes through — and from the interval in the constructor, which is the net
+     * under any path that forgets. Both are safe to call as often as they like:
+     * this compares what it is about to say against what it last said and returns
+     * without touching the socket when nothing moved.
+     *
+     * Two lists, because two different questions are being asked and answering
+     * both with one number is wrong in both directions:
+     *
+     *  - `sessionIds` — everything still tracked here, parked or not. This is the
+     *    reconciliation list, and it must be generous: a session the API has
+     *    buried needs laying to rest whatever state it is in on this side.
+     *  - `blockingIds` — what a new session would really have to wait for.
+     *    `ensureCapacity` parks an idle REVIEW or WAITING_INPUT session to make
+     *    room, so those seats are available on demand.
+     *
+     * Reporting the second as the first would have the API stop live REVIEW
+     * sessions; reporting the first as the second would call a machine full while
+     * it had room. Both were caught by the independent QA review of this change.
+     */
+    private publishSlots;
     private onFrame;
     private startSession;
     /**
@@ -570,7 +758,61 @@ export declare class Supervisor {
     private isMidTurn;
     /** The three live setters, in the order that lets an explicit pick win. */
     private applyLiveSettings;
+    /**
+     * Let go of a session the API says no longer exists, so its files can go.
+     *
+     * `purge_session` and `clean` used to refuse outright while ANY entry for the
+     * id was in the map. That reads as caution and behaves as a deadlock: the
+     * frame arrives precisely because the API has already deleted the row, so
+     * nothing will ever come along to release the entry, the worktree stays on
+     * disk, and the retry runs until the purge ages out of its window. On
+     * production one such tombstone was still failing two hours later, on a
+     * machine that was refusing new sessions for exactly the seat it held.
+     *
+     * The API is the authority on whether a session exists. If it says gone, the
+     * honest answer is to end it here too — the same teardown a reconnect
+     * performs for a session missing from `hello_ack` — and only then report that
+     * we could not finish, if the process really will not go.
+     *
+     * Returns true when nothing is holding the id any more.
+     */
+    private releaseForCleanup;
+    /**
+     * How long cleanup waits for a stopped agent process to actually be gone.
+     *
+     * Deliberately a small slice of the API's ten-second command budget: removing
+     * the worktree still has to happen after this, under the repository lock, and
+     * a purge that times out on the wire is reported as a failure even when it
+     * succeeded here. Three seconds is enough for an ordinary exit; anything
+     * slower is better answered honestly, so the drain comes back and finds the
+     * entry already gone.
+     */
+    private static readonly CLEANUP_RELEASE_MS;
     private stopSession;
+    /**
+     * The ONE way a session ends on this runner.
+     *
+     * A terminal status is two facts, not one: the API is told the session is
+     * over, AND this machine stops holding a seat for it. They used to be
+     * separate lines at eight call sites, and three of them wrote only the first
+     * — `settleTurnStatus`'s failed-turn branch, `forwardEvent`'s `case 'error'`
+     * and `runApiRetry`. Each left a `RunningSession` in the map with a live
+     * `session` handle and `stopRequested === false`, which is precisely what
+     * `liveSessionCount` counts. The seat was then held for a session the API had
+     * already buried, until the next reconnect — weeks, on a healthy runner.
+     *
+     * On production (31.08.2026) that arithmetic refused a fourth session on a
+     * machine whose database said one was running, and the dashboard had offered
+     * the seat a moment earlier. `launchCrashed` had the rule right all along
+     * («an entry left in the map would hold one of the runner's few slots»); it
+     * just could not be the only place that knew it.
+     *
+     * Deliberately NOT folded into `reportStatus`: that method is also how a
+     * session reaches REVIEW, WAITING_INPUT and RUNNING, and a teardown hidden
+     * inside it would be invisible at exactly the call sites that must not tear
+     * anything down. The name says what it does.
+     */
+    private finishSession;
     private reconcile;
     /**
      * Housekeeping for the journal directory. Safe to call any time: live