@bridge4dev/runner 0.46.1 → 0.48.0

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).
      *
@@ -62,6 +109,13 @@ export interface SupervisorOptions {
      * firing over a working agent (QA-2026-08-16 M-4). Never set in production.
      */
     emptyTurnSettleMs?: number;
+    /**
+     * How long an unchanged plan-usage snapshot is held before it is re-sent
+     * (#366) – a test seam over `RATE_LIMITS_RESEND_INTERVAL_MS`, for the same
+     * reason `emptyTurnSettleMs` exists: the real floor is three minutes and this
+     * suite runs on real timers. Never set in production.
+     */
+    rateLimitsResendMs?: number;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -89,6 +143,7 @@ export declare class Supervisor {
     private static readonly EMPTY_TURN_SETTLE_MS;
     /** The window actually used — the constant, or a test's own shorter one. */
     private readonly emptyTurnSettleMs;
+    private readonly rateLimitsResendMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     private static readonly JOURNAL_TTL_MS;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -117,12 +172,118 @@ 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;
@@ -372,6 +533,29 @@ export declare class Supervisor {
      * its timer runs out, and it must end in exactly the way it would have
      * ended immediately. A copy would be two behaviours one edit apart.
      */
+    /**
+     * The level gate for the context meter (#366).
+     *
+     * While a turn is open, a frame goes out only when the meter moved by at
+     * least one of the shared thresholds or the window itself changed; the
+     * newest held-back value is flushed right before `turn_end`, so the ring at
+     * rest is exact. Outside a turn every frame passes – there are only a handful
+     * (process start, a model change, and the Claude adapter's own measurement,
+     * which resolves AFTER `turn_end`), and each one is news.
+     */
+    private forwardContextUsage;
+    /** Send the value the gate was holding, if any – strictly before `turn_end`. */
+    private flushHeldContextUsage;
+    /**
+     * The level gate for plan usage (#366).
+     *
+     * A snapshot goes out when it is the first, when anything but `measuredAt`
+     * changed, when it carries a refusal (#258 – always, even twice in a row), or
+     * when the one last sent is older than the resend floor. The fingerprint is
+     * the whole payload minus the clock, so a field an adapter adds tomorrow is
+     * part of it without anybody remembering to list it here.
+     */
+    private forwardRateLimits;
     private completeTurn;
     /**
      * Move the session to the status a finished turn leaves it in.