@bridge4dev/runner 0.46.1 → 0.48.0

package/dist/supervisor.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { log } from './log.js';
+import { CONTEXT_USAGE_MIN_DELTA_RATIO, CONTEXT_USAGE_MIN_DELTA_TOKENS, RATE_LIMITS_RESEND_INTERVAL_MS, } from './levels.js';
 import { claimAutoResume, clearAutoResume, pruneAutoResume } from './auto-resume.js';
 import { classifyFailure, isRepeatOfSameFailure, MAX_RETRIES_PER_SESSION, retryDelayMs, } from './adapters/error-policy.js';
 import { evaluateRecipeCommand, maskSecrets, maskString } from './policy.js';
@@ -17,6 +18,11 @@ import { fsView } from './fsview.js';
 import { publishFile } from './file-publish.js';
 import { agentAuthStatuses, AuthRelay, clearAgentAuthFailure, noteAgentAuthFailure, } from './auth-relay.js';
 import { selfUpdate } from './self-update.js';
+import { installAgent } from './agent-install.js';
+import { autoUpdateRefusal, claimAgentAutoUpdate } from './agent-auto-update.js';
+import { pruneNativeClaudeVersions } from './agent-cleanup.js';
+import { agentByDbValue } from './agent-registry.js';
+import { invalidateAgentVersions, measureAgentVersions, } from './agent-versions.js';
 import { rememberWorkspacePath } from './environment.js';
 import { composeMessageWithAttachments, saveAttachments, } from './attachments.js';
 import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, previewRewind, pruneCheckpoints, } from './checkpoints.js';
@@ -53,6 +59,16 @@ function gitPolicyOf(descriptor) {
             : {}),
     };
 }
+function freshLevels() {
+    return {
+        contextSent: null,
+        contextHeld: null,
+        contextPassNext: false,
+        limitsSent: null,
+        sent: 0,
+        dropped: 0,
+    };
+}
 const LAUNCH_REFUSED = { ok: false, reason: 'refused' };
 export class Supervisor {
     ws;
@@ -80,6 +96,7 @@ export class Supervisor {
     static EMPTY_TURN_SETTLE_MS = 25_000;
     /** The window actually used — the constant, or a test's own shorter one. */
     emptyTurnSettleMs;
+    rateLimitsResendMs;
     /** A finished session's journal is kept this long for a late reconnect. */
     static JOURNAL_TTL_MS = 72 * 3_600_000;
     /** Backstop: events the API will never accept must not pile up forever. */
@@ -108,8 +125,20 @@ export class Supervisor {
      * than having no restore point for that one message.
      */
     repoLockDepth = new Map();
-    /** An update is installing right now — a second one would fight it. */
-    selfUpdateInFlight = false;
+    /**
+     * 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.
+     */
+    installInFlight = null;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     verify;
     verifyReports = new VerifyReportQueue();
@@ -118,6 +147,7 @@ export class Supervisor {
         this.opts = opts;
         this.journals = opts.journals ?? new JournalStore();
         this.emptyTurnSettleMs = opts.emptyTurnSettleMs ?? Supervisor.EMPTY_TURN_SETTLE_MS;
+        this.rateLimitsResendMs = opts.rateLimitsResendMs ?? RATE_LIMITS_RESEND_INTERVAL_MS;
         this.verify = new VerifyRunner({
             enabled: opts.verifyEnabled !== false,
             onReport: (report) => {
@@ -148,6 +178,293 @@ export class Supervisor {
          */
         this.slotsTimer = setInterval(() => this.publishSlots(), Supervisor.SLOTS_REPORT_INTERVAL_MS);
         this.slotsTimer.unref?.();
+        /**
+         * Agent versions on a heartbeat too, for a different reason than seats.
+         *
+         * Nothing on this machine tells us when somebody updates Codex by hand, and
+         * the measurement behind the frame is cached for an hour anyway — so the
+         * tick costs a cached read most of the time and still notices a hand-made
+         * change within the hour. What makes a freshly connected card correct
+         * immediately is the same frame sent on every `hello_ack`.
+         */
+        this.agentVersionsTimer = setInterval(() => void this.publishAgentVersions('measured'), Supervisor.AGENT_VERSIONS_INTERVAL_MS);
+        this.agentVersionsTimer.unref?.();
+        /**
+         * Р12: the old Claude version files, swept once a day.
+         *
+         * Two timers rather than one, and the delayed first sweep is the load-bearing
+         * half. The gate below is «this runner is tracking no sessions», and at the
+         * moment a daemon starts that is trivially true — the map fills from the
+         * `hello_ack` reconciliation seconds later. Sweeping in that window would be
+         * sweeping exactly when the answer is least trustworthy, on the one machine
+         * shape (restarted often) where it would happen every time.
+         */
+        const cleanupFirst = opts.agentCleanupMs ?? Supervisor.AGENT_CLEANUP_FIRST_DELAY_MS;
+        const cleanupEvery = opts.agentCleanupMs ?? Supervisor.AGENT_CLEANUP_INTERVAL_MS;
+        this.agentCleanupFirstTimer = setTimeout(() => this.sweepOldAgentVersions(), cleanupFirst);
+        this.agentCleanupFirstTimer.unref?.();
+        this.agentCleanupTimer = setInterval(() => this.sweepOldAgentVersions(), cleanupEvery);
+        this.agentCleanupTimer.unref?.();
+    }
+    /** How often the agent versions are re-derived. See the constructor. */
+    static AGENT_VERSIONS_INTERVAL_MS = 60 * 60 * 1_000;
+    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.
+     */
+    installBusyReason() {
+        if (this.installInFlight === 'self_update')
+            return 'An update is already running';
+        if (this.installInFlight === 'agent_install') {
+            return 'An agent is already being installed on this server';
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    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.
+     */
+    static MAX_PENDING_VERSION_CHANGES = 8;
+    async publishAgentVersions(reason, changed) {
+        try {
+            const measure = this.opts.measureAgentVersions ?? measureAgentVersions;
+            // After an install — ours or the auto one — the cached number is a lie,
+            // and a stale `at` with it would be dropped by the API's ordering guard
+            // together with the audit line the install owes. Forcing it here means a
+            // caller cannot forget to invalidate the cache first.
+            const measurement = await measure({ force: reason !== 'measured' });
+            // A plain tick carries an earlier install's news rather than replacing it.
+            // The API keys the audit line by the measurement's `at`, so the same
+            // change arriving under a later `at` is one line, not two.
+            //
+            // `changed` is only ever handed over by an install, and an install always
+            // calls this with `manual` or `auto` — never `measured`.
+            if (changed && reason !== 'measured') {
+                this.queueVersionChange({ reason, changed });
+            }
+            const carried = this.pendingVersionChanges[0];
+            const sent = this.ws.send({
+                type: 'agent_versions',
+                at: measurement.at,
+                reason: carried?.reason ?? reason,
+                agents: measurement.agents,
+                ...(carried ? { changed: carried.changed } : {}),
+            });
+            // Dropped only once a frame is genuinely written.
+            if (sent && carried) {
+                this.pendingVersionChanges.shift();
+                // One line per frame, so a backlog needs one frame each. Recursing only
+                // after a SUCCESSFUL send is what makes this terminate: the queue is
+                // shorter every time, and a failed write leaves the loop instead.
+                if (this.pendingVersionChanges.length > 0) {
+                    void this.publishAgentVersions('measured');
+                }
+            }
+        }
+        catch (error) {
+            if (changed && reason !== 'measured')
+                this.queueVersionChange({ reason, changed });
+            log.warn('supervisor: could not report agent versions', { error: String(error) });
+        }
+    }
+    queueVersionChange(entry) {
+        if (this.pendingVersionChanges.length >= Supervisor.MAX_PENDING_VERSION_CHANGES) {
+            log.warn('supervisor: dropping the oldest unreported version change', {
+                agent: this.pendingVersionChanges[0]?.changed.agent,
+            });
+            this.pendingVersionChanges.shift();
+        }
+        this.pendingVersionChanges.push(entry);
+    }
+    /**
+     * Р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.
+     */
+    async maybeAutoUpdateAgent(descriptor) {
+        const latest = descriptor.agentLatestVersion;
+        // The switch. Absent = off, and that covers «the card says no», «we never
+        // managed to ask a registry» and «the API predates this release» alike.
+        if (!latest)
+            return;
+        // The machine owner's veto over installing agents at all covers this too:
+        // it is the same download onto the same disk, asked for by us instead of by
+        // a person. Refusing the button and allowing the timer would be a hole in a
+        // control whose entire point is that the server cannot talk past it.
+        if (this.opts.agentInstallEnabled === false)
+            return;
+        const runtime = agentByDbValue(descriptor.agent);
+        if (!runtime)
+            return;
+        try {
+            // The CACHED measurement, not a fresh probe.
+            //
+            // This runs on every session start, and a fresh probe is two child
+            // processes per start — `claude --version` plus `claude doctor` — on the
+            // machine somebody is trying to start work on. The cache is an hour old at
+            // worst and the throttle below is a day, so staleness cannot cost a missed
+            // update; and being wrong the other way costs nothing either, because
+            // `installAgent` measures again for real and answers «already at that
+            // version» without touching anything.
+            const measure = this.opts.measureAgentVersions ?? measureAgentVersions;
+            const snapshot = await measure();
+            const measured = snapshot.agents[runtime.wireKey] ?? {
+                version: null,
+                managedBy: 'unknown',
+            };
+            const refusal = autoUpdateRefusal({ runtime, measured, latest });
+            if (refusal) {
+                log.debug('agent-auto-update: leaving it alone', {
+                    agent: runtime.wireKey,
+                    reason: refusal,
+                });
+                return;
+            }
+            // The lock is read BEFORE the day is claimed, and the order matters: three
+            // sessions starting at once are the ordinary case here, and spending the
+            // claim on an attempt that the lock then refuses would cost the agent its
+            // whole day for an install that never began.
+            //
+            // Still exactly one winner: `installBusyReason`, `claimAgentAutoUpdate`
+            // and the assignment below are all synchronous, with no await between
+            // them, so no second coroutine can interleave into the gap.
+            if (this.installBusyReason() !== null)
+                return;
+            // Claimed before the install and written to disk: a machine that fails for
+            // a reason it cannot fix (no space, no network) must go quiet for the day
+            // instead of retrying at every session start.
+            if (!claimAgentAutoUpdate(runtime.wireKey))
+                return;
+            this.installInFlight = 'agent_install';
+            let outcome;
+            try {
+                const run = this.opts.installAgent ?? installAgent;
+                outcome = await run({ agent: runtime.wireKey, version: latest });
+            }
+            finally {
+                this.installInFlight = null;
+            }
+            if (outcome.ok) {
+                log.info('agent-auto-update: installed', {
+                    agent: runtime.wireKey,
+                    from: outcome.fromVersion,
+                    to: outcome.toVersion,
+                });
+            }
+            else {
+                log.warn('agent-auto-update: install failed', {
+                    agent: runtime.wireKey,
+                    version: latest,
+                    error: outcome.detail,
+                });
+            }
+            // After EVERY outcome, for the reason the button's handler gives: a failed
+            // install is exactly when the card is most likely to be wrong, because npm
+            // can unlink the old package before dying. `reason: 'auto'` is what earns
+            // the `dev.server.agent_auto_updated` audit line on the other side (Р14),
+            // and `changed` is its payload — omitted when nothing actually moved.
+            invalidateAgentVersions();
+            const moved = outcome.ok && outcome.toVersion !== undefined && outcome.toVersion !== outcome.fromVersion
+                ? { agent: outcome.agent, from: outcome.fromVersion, to: outcome.toVersion }
+                : undefined;
+            await this.publishAgentVersions('auto', moved);
+        }
+        catch (error) {
+            // `installAgent` never throws, but `measureAgent` spawns processes and the
+            // whole point of this path is that nothing it does can reach the session.
+            log.warn('agent-auto-update: gave up', {
+                agent: runtime.wireKey,
+                error: String(error instanceof Error ? error.message : error),
+            });
+        }
+    }
+    /** Once a day, per Р12 — the vendor adds at most one file a day. */
+    static AGENT_CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1_000;
+    /** Long enough for `hello_ack` to have told us which sessions are live. */
+    static AGENT_CLEANUP_FIRST_DELAY_MS = 60 * 60 * 1_000;
+    agentCleanupTimer;
+    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.
+     */
+    sweepOldAgentVersions() {
+        // The empty string matches no session id, so this is «any live process».
+        if (this.liveSessionCount('') > 0)
+            return;
+        if (this.installBusyReason() !== null)
+            return;
+        try {
+            const swept = (this.opts.pruneAgentVersions ?? pruneNativeClaudeVersions)();
+            if (swept.removed.length > 0) {
+                log.info('agent-cleanup: removed old Claude versions', {
+                    removed: swept.removed,
+                    freedMb: Math.round(swept.freedBytes / 1024 / 1024),
+                });
+            }
+        }
+        catch (error) {
+            log.warn('agent-cleanup: sweep failed', { error: String(error) });
+        }
     }
     /** How often the seat report re-derives the truth. See the constructor. */
     static SLOTS_REPORT_INTERVAL_MS = 15_000;
@@ -253,6 +570,10 @@ export class Supervisor {
                 // A build that finished while the socket was down has its verdict
                 // sitting on disk. This is the moment it can be delivered.
                 this.flushVerifyReports();
+                // The card of a machine that just came back must not show yesterday's
+                // agent versions. Deliberately not awaited: this same frame carries the
+                // session reconciliation, and a slow `codex doctor` must not hold it up.
+                void this.publishAgentVersions('measured');
                 break;
             case 'verify_report_ack':
                 this.verifyReports.ack(frame.runId);
@@ -417,6 +738,17 @@ export class Supervisor {
             });
             return;
         }
+        /**
+         * Р13: move THIS session's agent forward, behind this session's back.
+         *
+         * Deliberately not awaited, and started before the workspace is prepared:
+         * the person asked for a session, and a 320 MB download must not be
+         * something they wait through. This session then finishes on the file it
+         * has already opened — replacing a binary does not disturb a process that
+         * holds it — and the new version takes effect for the next one. That is
+         * exactly the promise the switch's caption makes on the card.
+         */
+        void this.maybeAutoUpdateAgent(descriptor);
         const running = {
             descriptor,
             journal: this.journals.open(descriptor.id),
@@ -424,6 +756,7 @@ export class Supervisor {
             lastReported: descriptor.status,
             costUsd: descriptor.costUsd,
             costBaseUsd: descriptor.costUsd,
+            levels: freshLevels(),
             stopRequested: false,
             parkRequested: false,
             pendingMessages: [],
@@ -1378,12 +1711,101 @@ export 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.
+     */
+    forwardContextUsage(running, usedTokens, maxTokens) {
+        const levels = running.levels;
+        const frame = { usedTokens, maxTokens };
+        const last = levels.contextSent;
+        const turnOpen = running.lastReported === 'RUNNING';
+        const moved = last === null ? Number.POSITIVE_INFINITY : Math.abs(usedTokens - last.usedTokens);
+        const pass = last === null ||
+            last.maxTokens !== maxTokens ||
+            levels.contextPassNext ||
+            !turnOpen ||
+            moved >= CONTEXT_USAGE_MIN_DELTA_TOKENS ||
+            moved / maxTokens >= CONTEXT_USAGE_MIN_DELTA_RATIO;
+        // Only the newest value is worth keeping; whatever it replaces is gone.
+        if (levels.contextHeld !== null)
+            levels.dropped += 1;
+        if (!pass) {
+            levels.contextHeld = frame;
+            return;
+        }
+        levels.contextHeld = null;
+        levels.contextPassNext = false;
+        levels.contextSent = frame;
+        levels.sent += 1;
+        this.sendEvent(running, 'context_usage', frame);
+    }
+    /** Send the value the gate was holding, if any – strictly before `turn_end`. */
+    flushHeldContextUsage(running) {
+        const levels = running.levels;
+        const held = levels.contextHeld;
+        if (held === null)
+            return;
+        levels.contextHeld = null;
+        // A held value identical to the last one sent is not news – flushing it
+        // would add a frame to every turn and give back half the saving.
+        const sent = levels.contextSent;
+        if (sent !== null && sent.usedTokens === held.usedTokens && sent.maxTokens === held.maxTokens) {
+            return;
+        }
+        levels.contextSent = held;
+        levels.sent += 1;
+        this.sendEvent(running, 'context_usage', held);
+    }
+    /**
+     * 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.
+     */
+    forwardRateLimits(running, limits) {
+        const levels = running.levels;
+        const print = JSON.stringify({ ...limits, measuredAt: undefined });
+        const now = Date.now();
+        const last = levels.limitsSent;
+        const pass = last === null ||
+            Boolean(limits.blocked) ||
+            last.print !== print ||
+            now - last.at >= this.rateLimitsResendMs;
+        if (!pass) {
+            levels.dropped += 1;
+            return;
+        }
+        levels.limitsSent = { print, at: now };
+        levels.sent += 1;
+        this.sendEvent(running, 'rate_limits', { ...limits });
+    }
     completeTurn(running, descriptor, event) {
+        // #366: the ring at rest must be exact – the value the gate held back
+        // during the turn goes out first, so it is older than `turn_end` by seq.
+        this.flushHeldContextUsage(running);
         this.sendEvent(running, 'turn_end', {
             ok: event.ok,
             errorMessage: event.errorMessage,
             ...(event.aborted ? { aborted: true } : {}),
         });
+        // …and whatever the adapter measures once the turn is over (Claude does,
+        // asynchronously) is news, not a step of the same turn.
+        running.levels.contextPassNext = true;
+        log.info('supervisor: levels', {
+            sessionId: descriptor.id,
+            sent: running.levels.sent,
+            dropped: running.levels.dropped,
+        });
         // The session is already on its way out with a status that MEANS
         // something — a spent budget, a Stop, a teardown. A turn ending inside
         // that window is a consequence of it, and letting the line below
@@ -1902,17 +2324,17 @@ export class Supervisor {
                 });
                 return;
             case 'context_usage':
-                this.sendEvent(running, 'context_usage', {
-                    usedTokens: event.usedTokens,
-                    maxTokens: event.maxTokens,
-                });
+                // #366. A LEVEL: only a value that moved is worth a frame. The gate
+                // decides before `sendEvent`, so a dropped frame never spends a seq.
+                this.forwardContextUsage(running, event.usedTokens, event.maxTokens);
                 return;
             // #279. A LEVEL signal like `agent_tasks`: every frame carries the whole
-            // snapshot, so the API stores what arrived rather than merging, and a
+            // snapshot, so the API keeps what arrived rather than merging, and a
             // dropped frame costs freshness, never correctness. Account-wide, not
             // session-wide — the API files it under the SERVER, not this session.
+            // #366: gated the same way as the context meter, see `forwardRateLimits`.
             case 'rate_limits':
-                this.sendEvent(running, 'rate_limits', { ...event.limits });
+                this.forwardRateLimits(running, event.limits);
                 return;
             case 'agent_tasks': {
                 // Ticket #113. A LEVEL signal: every frame carries the whole live set,
@@ -3125,6 +3547,7 @@ export class Supervisor {
                         lastReported: descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT',
                         costUsd: descriptor.costUsd,
                         costBaseUsd: descriptor.costUsd,
+                        levels: freshLevels(),
                         stopRequested: false,
                         parkRequested: false,
                         pendingMessages: [],
@@ -4109,10 +4532,10 @@ export class Supervisor {
                     // Second line of defence behind the API's per-server lock: two
                     // overlapping `npm install -g` into the same prefix is not something
                     // to leave to chance on someone else's machine.
-                    if (this.selfUpdateInFlight) {
-                        return void reply({ ok: false, error: 'An update is already running' });
-                    }
-                    this.selfUpdateInFlight = true;
+                    const busy = this.installBusyReason();
+                    if (busy)
+                        return void reply({ ok: false, error: busy });
+                    this.installInFlight = 'self_update';
                     const run = this.opts.selfUpdate ?? selfUpdate;
                     let outcome;
                     try {
@@ -4120,7 +4543,7 @@ export class Supervisor {
                     }
                     catch (error) {
                         // A failed update must be retryable without restarting the daemon.
-                        this.selfUpdateInFlight = false;
+                        this.installInFlight = null;
                         throw error;
                     }
                     // Deliberately NOT cleared on success: the process only exits ~1.5s
@@ -4128,7 +4551,7 @@ export class Supervisor {
                     // API releases its own lock the moment the reply lands. Clearing here
                     // left a window in which a second press started an `npm install -g`
                     // that systemd then killed mid-flight (QA-103 MINOR-8).
-                    this.selfUpdateInFlight = outcome.ok && outcome.restart;
+                    this.installInFlight = outcome.ok && outcome.restart ? 'self_update' : null;
                     reply({
                         ok: outcome.ok,
                         result: outcome,
@@ -4138,6 +4561,69 @@ export class Supervisor {
                         this.opts.onRestartRequested?.(outcome);
                     return;
                 }
+                case 'agent_install': {
+                    // The veto is enforced here as well as withheld from `hello`: an API
+                    // that has not noticed still must not install anything on a machine
+                    // whose owner said no.
+                    if (this.opts.agentInstallEnabled === false) {
+                        return void reply({
+                            ok: false,
+                            error: 'Installing agents is switched off on this server ([agents] install_enabled = false)',
+                        });
+                    }
+                    // Only these three ever cross the wire. The package name, the
+                    // installer URL and the command come from the registry compiled into
+                    // this build — a server that could name them would be a server that
+                    // could run anything here (§6 of the plan).
+                    const agent = str(frame.args?.['agent']);
+                    if (!agent)
+                        return void reply({ ok: false, error: 'agent is required' });
+                    const version = str(frame.args?.['version']);
+                    if (!version)
+                        return void reply({ ok: false, error: 'version is required' });
+                    const allowDowngrade = frame.args?.['allowDowngrade'] === true;
+                    const installBusy = this.installBusyReason();
+                    if (installBusy)
+                        return void reply({ ok: false, error: installBusy });
+                    this.installInFlight = 'agent_install';
+                    let installed;
+                    try {
+                        const runInstall = this.opts.installAgent ?? installAgent;
+                        installed = await runInstall({
+                            agent,
+                            version,
+                            ...(allowDowngrade ? { allowDowngrade: true } : {}),
+                        });
+                    }
+                    finally {
+                        // Always cleared, unlike `self_update`: an agent install does not
+                        // restart the daemon, so a holder left behind would block every
+                        // later install for the life of the process.
+                        this.installInFlight = null;
+                    }
+                    reply({
+                        ok: installed.ok,
+                        result: installed,
+                        ...(installed.ok ? {} : { error: installed.detail ?? 'Install failed' }),
+                    });
+                    // Re-measure after EVERY terminal outcome, not only after a success.
+                    // A failed install is exactly when the card is most likely to be
+                    // wrong: npm can unlink the old global package before dying, and a
+                    // rollback can fail too — and the hour-long measurement cache would
+                    // then keep re-publishing «0.150.0, up to date» about a machine that
+                    // no longer has the agent at all, on every reconnect.
+                    //
+                    // `changed` stays conditional: it is the audit payload (Р14), and
+                    // «updated from 1.2.3 to 1.2.3» would be a line about nothing.
+                    invalidateAgentVersions();
+                    const moved = installed.ok &&
+                        installed.toVersion !== undefined &&
+                        installed.toVersion !== installed.fromVersion
+                        ? { agent: installed.agent, from: installed.fromVersion, to: installed.toVersion }
+                        : undefined;
+                    void this.publishAgentVersions('manual', moved);
+                    return;
+                }
                 /**
                  * «Would this file reach the agent, and how big is it» (ticket #192).
                  *
@@ -4522,6 +5008,9 @@ export class Supervisor {
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown() {
         clearInterval(this.slotsTimer);
+        clearInterval(this.agentVersionsTimer);
+        clearTimeout(this.agentCleanupFirstTimer);
+        clearInterval(this.agentCleanupTimer);
         this.authRelay.cancel();
         for (const running of this.sessions.values()) {
             this.clearBudgetTimers(running);

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.46.1";
+export declare const RUNNER_VERSION = "0.48.0";
 //# 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.46.1';
+export const RUNNER_VERSION = '0.48.0';
 //# sourceMappingURL=version.js.map

package/package.json

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