@bridge4dev/runner 0.45.1 → 0.47.0

package/dist/supervisor.js

@@ -14,8 +14,14 @@ import { VerifyRunner, runOneOffCommand, } from './verify.js';
 import { VerifyReportQueue } from './verify-queue.js';
 import { applySession, gitBranches, gitCommit, gitDiff, gitLog, gitPush, gitRefs, gitShow, gitStatus, revertApply, gitStage, gitUnstage, gitDiscard, gitPull, gitMergeAbort, updateFromBase, workspaceState, } from './gitops.js';
 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';
@@ -107,8 +113,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();
@@ -131,7 +149,313 @@ export class Supervisor {
         ws.on('frame', (frame) => {
             void this.onFrame(frame).catch((error) => log.error('supervisor: frame handler failed', { type: frame.type, error: String(error) }));
         });
+        /**
+         * The seat report is on a heartbeat, not only on the events that change it.
+         *
+         * Deliberate, and the lesson of the bug this whole frame exists for: seat
+         * state lives in three mutable fields on each entry (`session`,
+         * `stopRequested`, `parkRequested`), so there is no single mutation to hook
+         * — and «every call site remembers to tell the API» is exactly the rule
+         * that had already been broken in three places. A tick that re-derives the
+         * truth cannot be forgotten by a future call site.
+         *
+         * Nearly free: `publishSlots` fingerprints what it last sent and returns
+         * without touching the socket when nothing moved, so a quiet runner sends
+         * one frame per change and none in between.
+         */
+        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;
+    slotsTimer;
     /**
      * Push every unacked verdict at the API.
      *
@@ -153,14 +477,90 @@ export class Supervisor {
     get activeSessionIds() {
         return [...this.sessions.keys()];
     }
+    /** The last set of seat-holders we told the API about, to send only changes. */
+    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.
+     */
+    publishSlots() {
+        const tracked = [];
+        const blocking = [];
+        for (const entry of this.sessions.values()) {
+            const id = entry.descriptor.id;
+            tracked.push(id);
+            if (entry.stopRequested || entry.parkRequested || !entry.session)
+                continue;
+            // `ensureCapacity` would park this one to make room, so its seat is
+            // available on demand and does not refuse anybody. Counting it as taken
+            // reported a machine with three finished-turn sessions as full while it
+            // would happily have started a fourth (independent QA, 31.08.2026).
+            if (this.isParkable(entry))
+                continue;
+            blocking.push(id);
+        }
+        tracked.sort();
+        blocking.sort();
+        const limit = this.maxSessions;
+        const fingerprint = `${limit}:${tracked.join(',')}|${blocking.join(',')}`;
+        if (fingerprint === this.lastPublishedSlots)
+            return;
+        // Recorded only when it actually went out. A frame dropped because the
+        // socket was down must not be remembered as sent — otherwise the seat
+        // report would go quiet until the set changed again, which on an idle
+        // machine is exactly never.
+        if (this.ws.send({
+            type: 'session_slots',
+            sessionIds: tracked,
+            blockingIds: blocking,
+            maxSessions: limit,
+        })) {
+            this.lastPublishedSlots = fingerprint;
+        }
+    }
     async onFrame(frame) {
         switch (frame.type) {
             case 'hello_ack':
+                // A new connection knows nothing about the seats we reported to the
+                // last one — the API keeps that beside the socket, not in the database,
+                // because it is only true while the socket is. Forget what we told the
+                // old one so the first tick after this reconnect actually sends.
+                this.lastPublishedSlots = '';
                 this.setMaxSessions(frame.maxSessions);
                 await this.reconcile(frame.sessions);
+                this.publishSlots();
                 // 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);
@@ -325,6 +725,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),
@@ -1111,6 +1522,11 @@ export class Supervisor {
             isTerminal(running.lastReported)) {
             this.journals.closeAndDelete(descriptor.id);
         }
+        // The map just lost an entry, and this is the one place where that happens
+        // WITHOUT a status frame to carry the news: the terminal status was already
+        // reported before the process stream ended. Without this the API goes on
+        // believing the runner tracks a session that is gone, until the next tick.
+        this.publishSlots();
         // A resume arrived while this life was winding down — start it now that the
         // map entry is gone. One place, after every removal path above.
         if (running.pendingRestart && !this.sessions.has(descriptor.id)) {
@@ -1356,7 +1772,12 @@ export class Supervisor {
             });
         }
         else {
-            this.reportStatus(descriptor.id, 'FAILED', {
+            // The turn failed for a reason nothing above could soften: not a plan
+            // refusal, not a retryable provider fault. FAILED is terminal, so the
+            // process and the seat go with it — see `finishSession`. Reporting the
+            // status alone is what left this machine holding a seat for a session
+            // the API had already buried (31.08.2026).
+            this.finishSession(running, 'FAILED', {
                 costUsd: running.costUsd,
                 activeMs: Supervisor.spentMs(running),
                 errorMessage: event.errorMessage ?? 'Agent turn failed',
@@ -1620,7 +2041,43 @@ export class Supervisor {
                 // No `lastPrompt` guard: a free CHAT session boots with an empty prompt
                 // and is exactly the case that hits an auth failure at startup, so
                 // requiring one excluded the sessions that need the retry most.
-                if (isAuthCode(event.code) && !running.authRetryDone) {
+                // FIRST, and before any decision about retrying (#365). This is the only
+                // authority on a login the credentials file cannot see through — a
+                // provider-side revocation leaves the file looking perfectly healthy,
+                // and `codex login status` never leaves the machine — so it is the one
+                // thing that turns the server panel from «signed in» to «sign in
+                // needed» (#121).
+                //
+                // It used to sit BELOW the retry, i.e. it wanted a SECOND refusal. On
+                // Codex a second refusal never came: the first one was swallowed in
+                // favour of a relaunch that could not happen, so the panel kept showing
+                // a dead login as healthy — and the owner spent an hour signing into
+                // the wrong machine while this line waited for its turn.
+                //
+                // `auth_expired` ONLY, and not every auth code. `auth_missing` means the
+                // credential was locally absent — nothing was refused — and the panel's
+                // own probe already answers «not signed in» for that machine without
+                // any help from here. Marking it would only add a way to be wrong: the
+                // mark outranks a healthy file for fifteen minutes, so a home that was
+                // repaired a second later would keep a red panel over a working login.
+                if (event.code === 'auth_expired') {
+                    const refused = relayAgent(String(descriptor.agent).toLowerCase());
+                    if (refused)
+                        noteAgentAuthFailure(refused);
+                }
+                // Only `auth_missing` is worth a relaunch, and the distinction is the
+                // adapter's own (`probeAuth`), not a guess from prose.
+                //
+                //  - `auth_missing` — there is no credential where we look. Usually the
+                //    link into the shared store went out from under a live daemon, and
+                //    the adapter re-asserts its home on start, so one relaunch really
+                //    does fix it.
+                //  - `auth_expired` — the provider refused a credential that IS there.
+                //    A repeat presents the same dead token and gets the same answer,
+                //    while the person waits for a retry that was never going to work.
+                //    `error-policy.ts` has said exactly this about Claude since 0.44.1
+                //    («A person has to sign in; a repeat cannot») — the two now agree.
+                if (event.code === 'auth_missing' && !running.authRetryDone) {
                     running.authRetry = { prompt: running.lastPrompt };
                     this.sendEvent(running, 'notice', {
                         level: 'warn',
@@ -1628,22 +2085,18 @@ export class Supervisor {
                     });
                     return;
                 }
-                // The retry is spent and the agent is still refused — this is the only
-                // authority on a login the credentials file cannot see through (a
-                // provider-side revocation leaves the file looking perfectly healthy).
-                // The panel is told from here, not from a guess (#121).
-                if (isAuthCode(event.code)) {
-                    const refused = relayAgent(String(descriptor.agent).toLowerCase());
-                    if (refused)
-                        noteAgentAuthFailure(refused);
-                }
                 // Forward the code: the API stores the payload as-is, so the dashboard
                 // can offer "Sign in" instead of a dead error card.
                 this.sendEvent(running, 'error', {
                     message: event.message,
                     ...(event.code ? { code: event.code } : {}),
                 });
-                this.reportStatus(descriptor.id, 'FAILED', {
+                // Through `finishSession`, not `reportStatus`: this branch is the one
+                // the 31.08.2026 incident was traced to. It filed the session FAILED
+                // and returned, and the agent process went on streaming for another
+                // seventy-one seconds — holding a seat on a machine whose database said
+                // it was free.
+                this.finishSession(running, 'FAILED', {
                     costUsd: running.costUsd,
                     activeMs: Supervisor.spentMs(running),
                     errorMessage: event.message,
@@ -2185,9 +2638,11 @@ export class Supervisor {
         }
         if (!running.session) {
             // The process died while we waited. Relaunching is `launchAgent`'s job and
-            // it needs a prompt; without one there is nothing honest to do here.
-            this.clearApiRetry(running);
-            this.reportStatus(running.descriptor.id, 'FAILED', {
+            // it needs a prompt; without one there is nothing honest to do here — so
+            // the session ends, entry and all (`finishSession`). It used to end only
+            // on paper, and the row left behind then swallowed the next
+            // `session_start` for the same id.
+            this.finishSession(running, 'FAILED', {
                 errorMessage: 'The agent process ended while waiting to retry',
             });
             return;
@@ -2708,6 +3163,65 @@ export class Supervisor {
             });
         }
     }
+    /**
+     * 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.
+     */
+    async releaseForCleanup(sessionId) {
+        const running = this.sessions.get(sessionId);
+        if (!running)
+            return true;
+        log.warn('supervisor: cleanup asked for a session this runner still held', { sessionId });
+        if (!running.stopRequested) {
+            running.stopRequested = true;
+            this.clearBudgetTimers(running);
+            this.clearApiRetry(running);
+            this.clearEmptyTurn(running);
+            this.withdrawOpenQuestions(running, 'session_stopped');
+            // No status report: the row is already gone on the other side, so a frame
+            // about it would be answered with «Unknown session» and nothing else.
+            running.session?.stop('session_stopped');
+            if (!running.session)
+                this.sessions.delete(sessionId);
+            this.drainSessionsWaitingForCapacity();
+            this.publishSlots();
+        }
+        // `pumpEvents` removes the entry when the process stream actually ends, and
+        // that is asynchronous. Bounded wait rather than an unbounded one: the
+        // caller is a command with its own timeout, and a purge that has to happen
+        // on the next drain instead of this one costs a retry, not the worktree.
+        for (let waited = 0; waited < Supervisor.CLEANUP_RELEASE_MS; waited += 100) {
+            if (!this.sessions.has(sessionId))
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        return !this.sessions.has(sessionId);
+    }
+    /**
+     * 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.
+     */
+    static CLEANUP_RELEASE_MS = 3_000;
     stopSession(sessionId) {
         const running = this.sessions.get(sessionId);
         if (!running)
@@ -2726,6 +3240,59 @@ export class Supervisor {
                 this.journals.closeAndDelete(sessionId);
             }
         }
+        this.publishSlots();
+    }
+    /**
+     * 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.
+     */
+    finishSession(running, status, extra) {
+        const sessionId = running.descriptor.id;
+        // Before the report, so a frame that races the teardown cannot re-arm
+        // anything the teardown is in the middle of taking away.
+        running.stopRequested = true;
+        this.clearBudgetTimers(running);
+        this.clearApiRetry(running);
+        this.clearEmptyTurn(running);
+        // The cards die with the turn: a question nobody can answer any more is a
+        // worse thing to leave on screen than no question at all.
+        this.withdrawOpenQuestions(running, 'session_stopped');
+        this.reportStatus(sessionId, status, extra);
+        if (running.session) {
+            // `pumpEvents` deletes the entry when the stream ends, and its
+            // `stopRequested` branch skips the STOPPED frame because `lastReported`
+            // is already terminal. Until then the seat is free anyway: `stopRequested`
+            // takes the entry out of `liveSessionCount` on this very line.
+            running.session.stop('session_stopped');
+        }
+        else {
+            this.sessions.delete(sessionId);
+            if (this.ws.connected && running.journal.unacked().length === 0) {
+                this.journals.closeAndDelete(sessionId);
+            }
+        }
+        // A freed seat is only useful to whoever is waiting for one.
+        this.drainSessionsWaitingForCapacity();
+        this.publishSlots();
     }
     // ─── Reconciliation (hello_ack) ────────────────────────────────────
     async reconcile(descriptors) {
@@ -2977,11 +3544,30 @@ export class Supervisor {
                             });
                         }
                     }
-                    // REVIEW stays REVIEW (WAITING_INPUT is not reachable from it);
-                    // mid-turn statuses are downgraded to "waiting for the user".
-                    if (descriptor.status !== 'REVIEW') {
-                        this.reportStatus(descriptor.id, 'WAITING_INPUT', {});
-                    }
+                    /**
+                     * REVIEW stays REVIEW (WAITING_INPUT is not reachable from it);
+                     * mid-turn statuses are downgraded to "waiting for the user".
+                     *
+                     * REVIEW is now REPORTED rather than skipped — ticket #356, and the
+                     * news in that frame is not the status, which has not moved. It is
+                     * the ZERO riding on it.
+                     *
+                     * `running.backgroundTasks` is seeded to 0 above, because a runner
+                     * restart takes every subagent with it. But the number the API holds
+                     * is written by the runner ALONE, and it is only ever written by a
+                     * frame that carries the field — which `reportStatus` attaches only
+                     * for a tracked session. Skipping the report here left the API
+                     * believing whatever the dead process last said, for good: the badge
+                     * would keep saying «Agents», the Inbox would keep hiding the card,
+                     * and no later frame would ever correct either. `setBackgroundTasks`
+                     * cannot help — it compares against the in-memory 0 and returns
+                     * early, having nothing to announce.
+                     *
+                     * Same-status frames are legal (`canDevSessionTransition` answers
+                     * `true` for `from === to`), so this costs one no-op write and buys
+                     * back a session that would otherwise have been lost.
+                     */
+                    this.reportStatus(descriptor.id, statusForReport(running), {});
                     this.flushPendingMessages(running);
                 }
                 else if (descriptor.status === 'WAITING_INPUT') {
@@ -3072,8 +3658,22 @@ export class Supervisor {
                     const sessionId = frame.sessionId;
                     if (!sessionId)
                         return void reply({ ok: false, error: 'sessionId is required' });
-                    const running = this.sessions.get(sessionId);
-                    if (running)
+                    /**
+                     * `clean` keeps the flat refusal. `purge_session` does not. The
+                     * difference is who is allowed to ask.
+                     *
+                     * `purge_session` only ever arrives after the API has deleted the
+                     * row, so «wait for it to wind down» waits for something that will
+                     * never happen — that is the deadlock `releaseForCleanup` exists to
+                     * break. `clean` is a user-callable command
+                     * (`POST /dev/sessions/:id/commands`, any dev member) and the API
+                     * checks no status before relaying it. This refusal is the ONLY guard
+                     * on that route: releasing here would stop a mid-turn agent and then
+                     * `git worktree remove --force` its worktree, destroying every
+                     * uncommitted change in it. Caught by the independent QA review of
+                     * this change, by two reviewers separately.
+                     */
+                    if (this.sessions.get(sessionId))
                         return void reply({ ok: false, error: 'Session is still active — stop it first' });
                     // `worktree remove` also mutates the shared .git registration.
                     await this.withRepoLockFor(sessionWorktreePath(sessionId), () => removeSessionWorktree(sessionId));
@@ -3085,7 +3685,7 @@ export class Supervisor {
                     const sessionId = frame.sessionId;
                     if (!sessionId)
                         return void reply({ ok: false, error: 'sessionId is required' });
-                    if (this.sessions.get(sessionId)) {
+                    if (!(await this.releaseForCleanup(sessionId))) {
                         return void reply({ ok: false, error: 'Session is still active — stop it first' });
                     }
                     const branch = str(frame.args?.['branch']);
@@ -3777,6 +4377,43 @@ export class Supervisor {
                         return void reply({ ok: false, error: 'root argument is required' });
                     return void reply({ ok: true, result: fsView(root, str(frame.args?.['path']) ?? '.') });
                 }
+                /**
+                 * Выложить файл с этой машины (0.46.0).
+                 *
+                 * Адрес, куда уходят байты, раннер собирает САМ из своего `apiUrl` —
+                 * во фрейме его нет и быть не должно. Иначе одна подделанная команда
+                 * стала бы способом вытянуть файл с чужой машины на чужой хост.
+                 */
+                case 'fs_publish': {
+                    const root = str(frame.args?.['root']);
+                    const filePath = str(frame.args?.['path']);
+                    const slotId = str(frame.args?.['slotId']);
+                    if (!root || !filePath || !slotId) {
+                        return void reply({ ok: false, error: 'root, path and slotId are required' });
+                    }
+                    if (!this.opts.apiUrl || !this.opts.runnerToken) {
+                        return void reply({
+                            ok: false,
+                            error: 'This runner has no API credentials configured',
+                        });
+                    }
+                    const maxBytesRaw = frame.args?.['maxBytes'];
+                    const maxBytes = typeof maxBytesRaw === 'number' ? maxBytesRaw : 0;
+                    try {
+                        const result = await publishFile({
+                            root,
+                            relPath: filePath,
+                            slotId,
+                            maxBytes,
+                            apiUrl: this.opts.apiUrl,
+                            token: this.opts.runnerToken,
+                        });
+                        return void reply({ ok: true, result });
+                    }
+                    catch (error) {
+                        return void reply({ ok: false, error: String(error.message ?? error) });
+                    }
+                }
                 case 'self_update': {
                     // Everything that can refuse this lives in self-update.ts; here we
                     // only make sure the answer is on the wire BEFORE the process goes
@@ -3791,10 +4428,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 {
@@ -3802,7 +4439,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
@@ -3810,7 +4447,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,
@@ -3820,6 +4457,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).
                  *
@@ -4193,9 +4893,20 @@ export class Supervisor {
             // would mean it goes on claiming background work forever.
             ...(running ? { backgroundTasks: running.backgroundTasks } : {}),
         });
+        // Every seat change is accompanied by a status report — a session starting,
+        // parking, ending. Hooking the seat report here rather than at each of those
+        // is the whole point: «remember to also tell the API» is the rule that had
+        // already been broken in three places, and it is what this frame exists to
+        // stop mattering. `publishSlots` sends only when the answer actually
+        // changed, and the interval in the constructor is the net under both.
+        this.publishSlots();
     }
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown() {
+        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);
@@ -4380,10 +5091,6 @@ const AGENT_LABELS = { CLAUDE: 'Claude Code', CODEX: 'Codex' };
 function reportsCost(agent) {
     return agent === 'CLAUDE';
 }
-/** Adapter error codes that mean "the sign-in did not work". */
-function isAuthCode(code) {
-    return code === 'auth_expired' || code === 'auth_missing';
-}
 /**
  * Does this descriptor point at work that already exists on a branch?
  * If so, silently creating a fresh branch off HEAD would hide the agent's