@bridge4dev/runner 0.59.1 → 0.61.0

package/dist/supervisor.js

@@ -19,7 +19,7 @@ import { applySession, gitBranches, gitCommit, gitDiff, gitLog, gitPush, gitRefs
 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 { isSupervisedProcess, 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';
@@ -123,6 +123,8 @@ export class Supervisor {
     static EMPTY_TURN_SETTLE_MS = 25_000;
     /** The window actually used — the constant, or a test's own shorter one. */
     emptyTurnSettleMs;
+    /** The compaction net actually used — the constant, or a test's own. */
+    compactionWatchdogMs;
     rateLimitsResendMs;
     /** The stop-settle window actually used — the constant, or a test's own. */
     stopSettleMs;
@@ -168,8 +170,31 @@ export class Supervisor {
      * which of the two is running.
      */
     installInFlight = null;
+    /**
+     * A `runner_restart` has been agreed to and the exit is coming (#396).
+     *
+     * Never cleared: the process has ~1.5 s left, and everything it must refuse in
+     * that window it must refuse for good.
+     */
+    restarting = false;
     /** A restore-point collection is running; a second reconnect must not start another (#388). */
     checkpointGcInFlight = false;
+    /**
+     * Sessions the current `hello_ack` names, while `reconcile` is walking them
+     * (#392).
+     *
+     * The unacked replay at the top of `reconcile` sends every journal's
+     * leftovers before a single session is registered, and the acks come back
+     * while the loop is still awaiting an earlier session's worktree. The ack
+     * handler deletes the journal of a session it does not know once nothing is
+     * unacked — which used to be exactly the journal the loop was about to
+     * restore from: its open cards, its queued messages, its anchor, gone a
+     * moment before they were read. Membership here is what «this session is
+     * known» means until the loop reaches it.
+     */
+    reconciling = new Map();
+    /** How long a dashboard-requested compaction may go unreported before the session is handed back. */
+    static COMPACTION_WATCHDOG_MS = 10 * 60_000;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     verify;
     verifyReports = new VerifyReportQueue();
@@ -178,6 +203,7 @@ export class Supervisor {
         this.opts = opts;
         this.journals = opts.journals ?? new JournalStore();
         this.emptyTurnSettleMs = opts.emptyTurnSettleMs ?? Supervisor.EMPTY_TURN_SETTLE_MS;
+        this.compactionWatchdogMs = opts.compactionWatchdogMs ?? Supervisor.COMPACTION_WATCHDOG_MS;
         this.rateLimitsResendMs = opts.rateLimitsResendMs ?? RATE_LIMITS_RESEND_INTERVAL_MS;
         this.stopSettleMs = opts.stopSettleMs ?? Supervisor.STOP_SETTLE_MS;
         this.verify = new VerifyRunner({
@@ -314,12 +340,41 @@ export class Supervisor {
      * 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.
      */
+    /**
+     * The adapter for this agent — built now if it was not there at boot (#395).
+     *
+     * `opts.adapters` is assembled once, when the daemon starts, from what was on
+     * PATH at that moment. That is the SAME frozen snapshot `capabilities.agents`
+     * was, one layer down: press «Install Codex» on a running machine and the
+     * measurement updates, the card lights up, the API lets the session through —
+     * and this map still has no CODEX in it, so the session is created and dies
+     * at once. Asking the factory closes the last of the three lists.
+     *
+     * Built at most once per process and remembered: preparing Codex's isolated
+     * home clones ~90 MB on a machine that has never run it, and that is a price
+     * to pay on the first session, not on every one.
+     */
+    adapterFor(agent) {
+        const known = this.opts.adapters[agent];
+        if (known)
+            return known;
+        const built = this.opts.makeAdapter?.(agent) ?? null;
+        if (built)
+            this.opts.adapters[agent] = built;
+        return built ?? undefined;
+    }
     /**
      * Why an install cannot start right now, in words for the person who pressed.
      *
      * `null` means the way is clear.
      */
     installBusyReason() {
+        // #396: the same window `self_update` documents below, for a plain restart.
+        // The process only exits ~1.5 s after the reply, and the API frees its own
+        // lock the moment the reply lands — so an install that slipped into that
+        // window would be an `npm install -g` the exit kills half-written.
+        if (this.restarting)
+            return 'This runner is restarting';
         if (this.installInFlight === 'self_update')
             return 'An update is already running';
         if (this.installInFlight === 'agent_install') {
@@ -1775,7 +1830,8 @@ export class Supervisor {
                 const journal = this.journals.open(frame.sessionId);
                 journal.ack(frame.seq); // nack retires the seq too — it is permanent
                 const running = this.sessions.get(frame.sessionId);
-                if (!running && journal.unacked().length === 0) {
+                // Not while a reconnect is still about to restore it — see `reconciling`.
+                if (!running && !this.reconciling.has(frame.sessionId) && journal.unacked().length === 0) {
                     this.journals.closeAndDelete(frame.sessionId);
                 }
                 break;
@@ -1788,7 +1844,15 @@ export class Supervisor {
         }
     }
     // ─── Lifecycle ─────────────────────────────────────────────────────
-    async startSession(descriptor) {
+    async startSession(descriptor, 
+    /**
+     * What to tell a person about a card a previous life of this session left
+     * open (#392): `runner_restarted` from the reconnect, `not_held` from an
+     * ordinary `session_start` — a «Continue» after an ending the runner never
+     * got to write down, where the honest fact is only that no process holds
+     * the ask any more.
+     */
+    withdrawReason = 'not_held') {
         const existing = this.sessions.get(descriptor.id);
         if (existing) {
             // A resume (higher epoch) can land while the previous life is still
@@ -1823,7 +1887,7 @@ export class Supervisor {
             });
             return;
         }
-        if (!this.opts.adapters[descriptor.agent]) {
+        if (!this.adapterFor(descriptor.agent)) {
             this.reportStatus(descriptor.id, 'FAILED', {
                 errorMessage: `${AGENT_LABELS[descriptor.agent] ?? descriptor.agent} is not installed on this server`,
             });
@@ -1884,6 +1948,11 @@ export class Supervisor {
         // exist (session 9).
         running.pendingMessages.push(...running.journal.pending());
         this.sessions.set(descriptor.id, running);
+        // A card a previous life of this session left open is dead now: whatever
+        // starts here is a new process, and the process that asked is gone (#392).
+        // A first start finds nothing; a resume after an ungraceful ending finds
+        // the cards the restore branch would otherwise have closed.
+        this.withdrawJournaledQuestions(running, withdrawReason);
         /**
          * Messages that arrived for a session this runner did not know yet.
          *
@@ -2073,7 +2142,7 @@ export class Supervisor {
      */
     launchAgent(running, prompt, resumeId) {
         const { descriptor } = running;
-        const adapter = this.opts.adapters[descriptor.agent];
+        const adapter = this.adapterFor(descriptor.agent);
         if (!adapter || !running.worktreePath || !running.branch)
             return LAUNCH_REFUSED;
         /**
@@ -2170,6 +2239,8 @@ export class Supervisor {
         delete running.stopCycle;
         running.liveToolUses.clear();
         running.openPermissions.clear();
+        // …and a compaction the previous process never reported the end of (#348).
+        this.endCompaction(running, 'Compaction ended with the agent process.', 'warn');
         try {
             const agentPrompt = this.resolveAgentPrompt(running, resuming && !rewinding);
             const workspaceContext = composeWorkspaceContext(descriptor, agentPrompt?.text);
@@ -2621,6 +2692,18 @@ export class Supervisor {
         // Both sets describe THIS process and nothing else (#373).
         running.liveToolUses.clear();
         running.openPermissions.clear();
+        // So does a compaction it was in the middle of (#348). Guarded like the
+        // withdrawal below: a journal that cannot be written must not take the
+        // exit path with it.
+        try {
+            this.endCompaction(running, 'Compaction ended with the agent process.', 'warn');
+        }
+        catch (error) {
+            log.warn('supervisor: could not close the compaction', {
+                sessionId: descriptor.id,
+                error: String(error),
+            });
+        }
         try {
             this.clearApiRetry(running);
             this.withdrawOpenQuestions(running, 'session_stopped');
@@ -2849,6 +2932,37 @@ export class Supervisor {
             });
         }
     }
+    /**
+     * Close out the asks a PREVIOUS process of this runner left open (#392).
+     *
+     * `withdrawOpenQuestions` above reads `running.openQuestions`, and that set
+     * is memory: a process that died without reaching `shutdown()` — killed,
+     * crashed, machine rebooted — took it along, and the restore used to create
+     * a fresh empty set and write only «Runner reconnected». The card in the
+     * browser is closed by one thing, a `question_resolved` with its askId in
+     * the feed, so it stayed answerable for ever, and everything typed into it
+     * was lost (the 07.09.2026 session in the ticket: six restarts, zero
+     * tombstones).
+     *
+     * The journal is the set that survived: `SessionJournal.append` notes every
+     * card this runner published and every resolution it published, whoever
+     * wrote it. That is also the «already closed» check the plan asks to name:
+     * a graceful `shutdown()` sends its `question_resolved` through the same
+     * `append`, so by the time a restore runs, a card closed that way is no
+     * longer in the set — one tombstone per card, never two.
+     */
+    withdrawJournaledQuestions(running, reason) {
+        for (const askId of running.journal.openAskIds()) {
+            running.openQuestions.delete(askId);
+            // `sendEvent` → `journal.append` marks the card closed as a side effect.
+            this.sendEvent(running, 'question_resolved', {
+                askId,
+                outcome: 'invalidated',
+                source: 'runner',
+                reason,
+            });
+        }
+    }
     /**
      * Deliver messages that were held because every slot was taken.
      *
@@ -3049,6 +3163,11 @@ export class Supervisor {
         // #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);
+        // A turn ending is the agent speaking; the compaction net is for silence —
+        // and on Claude the turn IS the compaction, so a compaction still open here
+        // ended with it, whatever the adapter managed to say (a cancel before the
+        // CLI's first «compacting» status, a status stream that lost the end).
+        this.endCompaction(running, event.aborted ? 'Compaction cancelled.' : 'Compaction ended with the turn.');
         this.sendEvent(running, 'turn_end', {
             ok: event.ok,
             errorMessage: event.errorMessage,
@@ -3205,6 +3324,73 @@ export class Supervisor {
         clearTimeout(running.emptyTurnTimer);
         running.emptyTurnTimer = undefined;
     }
+    /**
+     * A compaction is over for a reason other than the agent saying so (#348):
+     * the turn it rode on ended, the process died, a new process was launched.
+     * The feed gets its closing line so the pair is complete, and the runner's
+     * own state is dropped so the NEXT compaction opens a new pair — left set,
+     * every later start would be read as a repeat and written nowhere (QA S4).
+     */
+    endCompaction(running, text, level = 'info') {
+        this.clearCompactionWatchdog(running);
+        if (!running.compaction)
+            return;
+        delete running.compaction;
+        this.sendEvent(running, 'system_note', {
+            code: level === 'warn' ? 'compaction_failed' : 'compaction_finished',
+            ...(level === 'warn' ? { level } : {}),
+            text,
+        });
+    }
+    /** A compaction has begun: say so in the feed, once, and remember who started it (#348). */
+    openCompaction(running, source) {
+        running.compaction = { source };
+        this.sendEvent(running, 'system_note', {
+            code: 'compaction_started',
+            source,
+            text: 'Compacting the conversation…',
+        });
+    }
+    /**
+     * The net under a dashboard-requested compaction (#348) — see
+     * `RunningSession.compactionWatchdog`. Fires only into a session that has
+     * said nothing since: every agent event and every ending clears it.
+     */
+    armCompactionWatchdog(running) {
+        this.clearCompactionWatchdog(running);
+        const timer = setTimeout(() => {
+            delete running.compactionWatchdog;
+            if (this.isStale(running))
+                return;
+            if (running.lastReported !== 'RUNNING' || running.stopRequested || running.budgetSpent) {
+                return;
+            }
+            // Not over a card the agent is parked on (the compaction is queued
+            // behind it and will run once the person answers), and not over a turn
+            // that demonstrably has tools in flight: both are an agent that is
+            // busy, not one that fell silent.
+            if (running.openQuestions.size > 0 || running.liveToolUses.size > 0)
+                return;
+            log.warn('supervisor: no end of the compaction was reported — handing the session back', {
+                sessionId: running.descriptor.id,
+            });
+            delete running.compaction;
+            this.sendEvent(running, 'system_note', {
+                code: 'compaction_failed',
+                level: 'warn',
+                text: 'The agent did not report the end of the compaction in ten minutes — the session is yours again.',
+            });
+            this.settleTurnStatus(running, running.descriptor, { ok: true });
+        }, this.compactionWatchdogMs);
+        timer.unref();
+        running.compactionWatchdog = timer;
+    }
+    clearCompactionWatchdog(running) {
+        if (!running.compactionWatchdog)
+            return;
+        clearTimeout(running.compactionWatchdog);
+        delete running.compactionWatchdog;
+    }
     /**
      * Record how many subagents are alive, and say so when it matters (#236).
      *
@@ -3222,16 +3408,35 @@ export class Supervisor {
     setBackgroundTasks(running, live) {
         if (live === running.backgroundTasks)
             return;
-        const finished = running.backgroundTasks > 0 && live === 0;
         running.backgroundTasks = live;
         const resting = running.lastReported === 'WAITING_INPUT' || running.lastReported === 'REVIEW'
             ? running.lastReported
             : null;
-        if (finished && resting) {
+        if (resting) {
+            // On reaching zero this is the report that makes the session the
+            // person's (#236); on any other change it is the same frame the
+            // five-minute heartbeat would send later, sent now — so the number the
+            // API holds is the number that is true, whenever a restart reads it.
             this.reportStatus(running.descriptor.id, resting, {
                 costUsd: running.costUsd,
                 activeMs: Supervisor.spentMs(running),
             });
+            return;
+        }
+        /**
+         * Mid-turn, the number moves with the frame that carries it (#393).
+         *
+         * The API's copy of the count is written only from `session_status`, and
+         * until now a change during a turn sent none: subagents that finished (or
+         * were spawned) between two status frames left the row holding the count
+         * of the frame before. The row is what a restarting runner is told, and
+         * «the restart stopped 2 background agents» about two agents that had
+         * already reported — or silence about eight that had not — is the exact
+         * lie #393 is about. A same-status frame is legal and moves nothing on the
+         * API but the count and its stamp.
+         */
+        if (running.lastReported === 'RUNNING') {
+            this.reportStatus(running.descriptor.id, 'RUNNING', {});
         }
     }
     isParkable(running) {
@@ -3290,8 +3495,9 @@ export class Supervisor {
      * It happens for real: a background subagent's report wakes a new turn inside
      * the agent process (SDK 0.3.226 emits a second `system:init` and a `result`
      * carrying `origin: {kind:'task-notification'}`), and nothing here reports a
-     * turn the runner did not start. Compaction does the same, and so does a
-     * question this runner withdraws by itself.
+     * turn the runner did not start. So does a question this runner withdraws by
+     * itself. (A compaction used to be the third case; `compact_context` reports
+     * RUNNING itself now, and #348 gave the compaction lines of its own.)
      *
      * An open question is the one thing that must survive: there, WAITING_INPUT
      * means a tool call is parked on a person, and the agent narrating around its
@@ -3329,6 +3535,9 @@ export class Supervisor {
         // before the switch so every such case gets it, including the ones added
         // after this line was written.
         if (event.type === 'message' ? event.role === 'assistant' : AGENT_OUTPUT_EVENTS.has(event.type)) {
+            // A working agent is not a silent one: the compaction net is for the
+            // session that hears nothing at all (#348).
+            this.clearCompactionWatchdog(running);
             // Ticket #196. The same signal, read twice for opposite reasons: when the
             // session is free it proves the agent is working (#185), and when the
             // session is held under a clock it proves something started that should
@@ -3414,6 +3623,28 @@ export class Supervisor {
                 // when it finally succeeds or finally gives up.
                 if (!event.ok && this.armApiRetry(running, descriptor, event))
                     return;
+                /**
+                 * A turn that ended well closes the retry EPISODE (#406).
+                 *
+                 * `running.apiRetry` records «attempt N of rule R», and `armApiRetry`
+                 * reads it to answer two questions: have we run out of attempts, and
+                 * did the same failure come straight back. Both are questions about ONE
+                 * episode. Until now the record was only ever cleared when a person
+                 * typed, a session stopped, or a session was torn down — so a session
+                 * that recovered kept «attempt 1 of claude.server_error» for the rest of
+                 * its life, and the NEXT api_error hours later read as «the same failure
+                 * came back after an automatic retry», got no retry, and ended the
+                 * session with a note that was not true.
+                 *
+                 * Nobody met that before this release: an `api_error` turn was reported
+                 * as a SUCCESS and never reached this code at all. With #406 it does,
+                 * and a long unattended run meets two network hiccups more often than
+                 * one. `apiRetriesUsed` — the ceiling that does not depend on the table
+                 * being right — is deliberately NOT reset here: it is a fact about the
+                 * session, and only a person typing clears it.
+                 */
+                if (event.ok)
+                    this.clearApiRetry(running);
                 this.completeTurn(running, descriptor, event);
                 return;
             }
@@ -3731,6 +3962,69 @@ export class Supervisor {
                 this.sendEvent(running, 'notice', { level: event.level, text: event.text });
                 return;
             }
+            case 'compaction': {
+                /**
+                 * #348. A `system_note` with a code, never a `notice`: the de-dup
+                 * above is per session for life, so «Conversation compacted» reached
+                 * the feed once and every later compaction was three minutes of
+                 * silence and a bare `turn_end` (gotcha §148). The dashboard reads its
+                 * «compacting…» indicator off these lines — the last one open means a
+                 * compaction is under way, on any tab, after any reload — so every
+                 * compaction has to leave its pair.
+                 *
+                 * One pair per compaction: a start while one is open is the CLI
+                 * repeating itself (Claude re-says «compacting» every thirty seconds
+                 * while it waits on a precomputed summary), or the agent confirming a
+                 * compaction `compact_context` already announced. An end with no start
+                 * open is still written — a process that came up mid-compaction has
+                 * nothing else to say about it.
+                 */
+                if (event.phase === 'started') {
+                    // The agent confirmed it is compacting: the net under a REQUESTED
+                    // compaction is for an agent that never did, and a confirmed one
+                    // reports its end through the adapter — or ends with its turn or
+                    // its process, both of which close the pair. Left armed, it would
+                    // hand back a session in the middle of a long, honest compaction.
+                    this.clearCompactionWatchdog(running);
+                    if (running.compaction)
+                        return;
+                    this.openCompaction(running, 'agent');
+                    return;
+                }
+                delete running.compaction;
+                this.clearCompactionWatchdog(running);
+                if (event.ok) {
+                    this.sendEvent(running, 'system_note', {
+                        code: 'compaction_finished',
+                        text: event.skipped ? 'Compaction skipped.' : 'Conversation compacted.',
+                    });
+                }
+                else {
+                    this.sendEvent(running, 'system_note', {
+                        code: 'compaction_failed',
+                        level: 'warn',
+                        text: `Compaction failed: ${event.error ?? 'unknown'}`,
+                    });
+                }
+                /**
+                 * Codex runs a compaction started from the dashboard outside any turn,
+                 * so no `turn_end` is coming to take the session off RUNNING — which
+                 * `compact_context` put it on, for good reasons (a WAITING_INPUT
+                 * session with no open question is parkable). Left alone it read
+                 * «Working» until the person's next message: the «eternal Working» of
+                 * the ticket. Settled here, directly and without the phantom-turn
+                 * hold: that hold exists for a turn that produced nothing, and this
+                 * is not a turn. A compaction inside a live turn (`standalone: false`)
+                 * is left to that turn's own ending.
+                 */
+                if (event.standalone &&
+                    running.lastReported === 'RUNNING' &&
+                    !running.stopRequested &&
+                    !running.budgetSpent) {
+                    this.settleTurnStatus(running, descriptor, { ok: true });
+                }
+                return;
+            }
             case 'tool':
                 // #373: which calls are in flight, so a stop can tell its own tail from
                 // work starting up. Kept here rather than in the adapters — both of them
@@ -3791,11 +4085,44 @@ export class Supervisor {
                 this.sendEvent(running, 'message', { role: 'user', text: typed });
             return 'answered';
         }
-        running.openQuestions.delete(frame.askId);
+        // Was the ask ours at all? A refusal for a card this process still holds
+        // (the adapter turned the answer down but kept the ask parked) is not a
+        // card nobody holds, and must not be announced as one: the rescued words
+        // below reach the adapter as an ordinary message, which closes the ask in
+        // its own honest words (QA S4 №14).
+        const held = running.openQuestions.delete(frame.askId);
         // Remembered even though it was a miss: whatever happened to the ask, the
         // words below have now been published once, and a redelivery must not
         // publish them again.
         running.answeredAsks.add(frame.askId);
+        /**
+         * The card dies where the browser looks (#392).
+         *
+         * The grey note below is words; the only thing that closes a question card
+         * in the feed is a `question_resolved` carrying its askId, and this exit
+         * never sent one. So the card stayed answerable: the next press met the
+         * API's «no longer open» for a day, and the day after that a fresh
+         * attempt reached this branch again and printed the note again — a card
+         * that could not die and published its own obituary once a day. This is
+         * the one second the runner is CERTAIN, and it now writes it down.
+         * `not_held` rather than a guess at why: a card from a previous life of
+         * the process and an ask withdrawn a moment ago look the same from here.
+         *
+         * Unless the journal says the card is ALREADY closed: an answer queued
+         * while the runner was away arrives right after a restore that has just
+         * closed the same card with `runner_restarted`, and a second tombstone
+         * would overwrite that honest reason with this vaguer one. The words are
+         * still rescued below; only the card is left as it is.
+         */
+        const alreadyClosed = running.journal.askState(frame.askId) === 'closed';
+        if (!alreadyClosed && !held) {
+            this.sendEvent(running, 'question_resolved', {
+                askId: frame.askId,
+                outcome: 'invalidated',
+                source: 'runner',
+                reason: 'not_held',
+            });
+        }
         /**
          * The reply, whichever control the person used to give it (#401).
          *
@@ -3814,16 +4141,16 @@ export class Supervisor {
          * order the card puts them in.
          */
         const rescued = [typed, answersAsMessage(frame.answers ?? [])].filter(Boolean).join('\n');
-        this.sendEvent(running, 'system_note', {
-            text: rescued
-                ? 'That question is no longer open — sending your reply as an ordinary message instead.'
-                : 'That question is no longer open — the agent has already moved on.',
-        });
         // The words must not be eaten. This is the ordinary case after a runner
         // restart: the card in the browser outlived the process that asked, and
         // showing the user's own message in the feed while nothing receives it is
         // the exact failure `acceptUserMessage` was hardened against (QA-106 M2).
+        // The grey line explains where the words went; with nothing to rescue the
+        // card's own «withdrawn» line already says everything there is to say.
         if (rescued) {
+            this.sendEvent(running, 'system_note', {
+                text: 'That question is no longer open — sending your reply as an ordinary message instead.',
+            });
             this.acceptUserMessage(frame.sessionId, rescued);
             return 'not_open';
         }
@@ -4244,6 +4571,9 @@ export class Supervisor {
                 return;
             }
             settle();
+            // A message handed to the agent starts a turn of its own: whatever the
+            // compaction net was waiting for, this session is no longer silent (#348).
+            this.clearCompactionWatchdog(running);
             this.reportStatus(running.descriptor.id, 'RUNNING', {});
             return;
         }
@@ -4881,6 +5211,8 @@ export class Supervisor {
         this.flushHeldContextUsage(running);
         // A phantom held from an earlier turn must not fire after this one closed.
         this.clearEmptyTurn(running);
+        // As in `completeTurn`: a stopped turn takes its compaction with it (#348).
+        this.endCompaction(running, 'Compaction cancelled.');
         this.sendEvent(running, 'turn_end', {
             ok: true,
             // A turn that finished on its own in the same instant is not «stopped».
@@ -5259,11 +5591,107 @@ export class Supervisor {
         this.publishSlots();
     }
     // ─── Reconciliation (hello_ack) ────────────────────────────────────
+    /**
+     * The terminal status a reconnect should replay for this session instead
+     * of restoring it, or null (QA-96 F1).
+     *
+     * Only a terminal status from THIS life of the session. A resumed session
+     * carries a higher epoch, and replaying the FAILED it was resumed from would
+     * kill it again the moment the runner reconnects. A journal written by a
+     * runner from before session 13 could hold a `DONE` — it is no longer a
+     * status this runner may report, and replaying one would close the session
+     * for the user. Drop it and let the session be picked back up like any
+     * other. Pure: reads the journal and decides, so the pre-registration pass
+     * and the loop answer the question the same way.
+     */
+    terminalStatusToReplay(descriptor) {
+        if (!this.journals.exists(descriptor.id))
+            return null;
+        const last = this.journals.open(descriptor.id).lastStatus;
+        if (last &&
+            isTerminal(last.status) &&
+            last.status !== 'DONE' &&
+            (last.epoch ?? 0) >= descriptor.epoch) {
+            return last;
+        }
+        return null;
+    }
+    /**
+     * Build and register the entry for a session a runner restart interrupted,
+     * and close the cards its dead process left open (#392).
+     *
+     * Synchronous on purpose, and called for EVERY such session before the
+     * reconnect awaits anything: registered, the session is known (a message
+     * for it waits in its queue behind the `starting` gate of #401 instead of
+     * coming back as `session_unknown`), and its cards go dark first thing —
+     * above the line about the restart, so a person reading down sees the card
+     * close before they read why.
+     */
+    registerRestoredSession(descriptor) {
+        const running = {
+            descriptor,
+            journal: this.journals.open(descriptor.id),
+            session: null,
+            lastReported: descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT',
+            costUsd: descriptor.costUsd,
+            costBaseUsd: descriptor.costUsd,
+            levels: freshLevels(),
+            stopRequested: false,
+            parkRequested: false,
+            // Registered before the worktree await, so the gate has to be up
+            // before it too (#401).
+            starting: true,
+            pendingMessages: [],
+            // Seed from the API, not 0: a runner restart used to hand the session
+            // a full fresh budget silently.
+            activeMs: descriptor.activeMsBase,
+            extraBudgetMinutes: descriptor.extraBudgetMinutes,
+            epoch: descriptor.epoch,
+            openQuestions: new Set(),
+            openPermissions: new Set(),
+            liveToolUses: new Set(),
+            pauseEpoch: 0,
+            processSeq: 0,
+            answeredAsks: new Set(),
+            deliveredMessageIds: new Set(),
+            backgroundTasks: 0,
+            ...pausedUntilOf(descriptor),
+            mode: descriptor.mode,
+            ...(descriptor.model ? { model: descriptor.model } : {}),
+            ...(descriptor.effort ? { effort: descriptor.effort } : {}),
+            lastPrompt: '',
+        };
+        running.journal.ensureSeqAbove(descriptor.lastSeq);
+        // Anything the API handed us before the daemon stopped (session 9).
+        running.pendingMessages.push(...running.journal.pending());
+        this.sessions.set(descriptor.id, running);
+        this.withdrawJournaledQuestions(running, 'runner_restarted');
+        return running;
+    }
     async reconcile(descriptors) {
         // Sessions the API no longer considers live (e.g. stopped from the
         // dashboard while this runner was offline) must not keep an agent process
         // running and holding the single runner slot (QA-99 MAJOR-2).
         const known = new Set(descriptors.map((d) => d.id));
+        // Counted, not assigned: a second `hello_ack` can start while this one is
+        // still walking, and whichever finishes first must not strip the other's
+        // sessions of their protection.
+        for (const id of known)
+            this.reconciling.set(id, (this.reconciling.get(id) ?? 0) + 1);
+        try {
+            await this.reconcileKnown(descriptors, known);
+        }
+        finally {
+            for (const id of known) {
+                const left = (this.reconciling.get(id) ?? 1) - 1;
+                if (left <= 0)
+                    this.reconciling.delete(id);
+                else
+                    this.reconciling.set(id, left);
+            }
+        }
+    }
+    async reconcileKnown(descriptors, known) {
         // Ticket #126: this list is the only moment the runner learns which
         // sessions still exist. Deleting a session while its dev server is
         // switched off leaves restore points — a full copy of a working tree —
@@ -5330,6 +5758,41 @@ export class Supervisor {
                 });
             }
         }
+        /**
+         * Every session this pass is going to restore is registered NOW, before
+         * the first await (#392, QA S4).
+         *
+         * The loop below awaits per session — a pause, a worktree, a launch — and
+         * anything that arrives for a LATER session meanwhile (the API flushes its
+         * outbox right after `hello_ack`) used to meet a runner that did not know
+         * it: `session_unknown`, a `session_start` in reply, and `startSession`
+         * restoring that session through the wrong door, with the wrong reason on
+         * its cards and no line about the restart. Registered here, the session is
+         * known and `starting`, so a message waits in its queue and the
+         * descriptor re-sent for it is a no-op — and its cards are closed before
+         * anybody can answer them.
+         */
+        const restoring = new Map();
+        for (const descriptor of descriptors) {
+            // The whole classification is per session, like the loop below (#225):
+            // a journal that cannot be read throws on open, and that must cost this
+            // session its restore and nothing else.
+            try {
+                if (this.sessions.has(descriptor.id))
+                    continue;
+                if (this.terminalStatusToReplay(descriptor))
+                    continue;
+                if (descriptor.status === 'STARTING' || !descriptor.providerSessionId)
+                    continue;
+                restoring.set(descriptor.id, this.registerRestoredSession(descriptor));
+            }
+            catch (error) {
+                log.error('supervisor: could not register a session for restore', {
+                    sessionId: descriptor.id,
+                    error: String(error),
+                });
+            }
+        }
         for (const descriptor of descriptors) {
             // One session must never cost the others their restore (ticket #225).
             // Everything below runs per descriptor, and until this guard existed a
@@ -5338,9 +5801,10 @@ export class Supervisor {
             // unrestored, on every reconnect, with nothing said anywhere. The blast
             // radius of a broken session is now that session.
             try {
+                const restored = restoring.get(descriptor.id);
                 // Live local session: statuses are fire-and-forget on the wire, so a
                 // status reached while the WS was down is re-reported here (QA-96 F1).
-                const tracked = this.sessions.get(descriptor.id);
+                const tracked = restored ? undefined : this.sessions.get(descriptor.id);
                 if (tracked) {
                     // The session was resumed server-side while this runner was offline, and
                     // the local copy is that same work. Adopt the new epoch BEFORE reporting:
@@ -5377,79 +5841,33 @@ export class Supervisor {
                 // Session that went terminal while we were offline: the journal keeps
                 // the last reported status — replay it instead of resurrecting the
                 // session as resumable (QA-96 F1).
-                if (this.journals.exists(descriptor.id)) {
-                    const journal = this.journals.open(descriptor.id);
-                    const last = journal.lastStatus;
-                    // Only replay a terminal status from THIS life of the session. A
-                    // resumed session carries a higher epoch, and replaying the FAILED it
-                    // was resumed from would kill it again the moment the runner reconnects.
-                    // A journal written by a runner from before session 13 could hold a
-                    // `DONE` — it is no longer a status this runner may report, and
-                    // replaying one would close the session for the user. Drop it and let
-                    // the session be picked back up like any other.
-                    if (last &&
-                        isTerminal(last.status) &&
-                        last.status !== 'DONE' &&
-                        (last.epoch ?? 0) >= descriptor.epoch) {
-                        this.ws.send({
-                            type: 'session_status',
-                            sessionId: descriptor.id,
-                            status: last.status,
-                            ...(last.extra ?? {}),
-                            // Guarded above to be >= the descriptor's epoch, so the API keeps it.
-                            ...(last.epoch === undefined ? {} : { epoch: last.epoch }),
-                        });
-                        if (journal.unacked().length === 0) {
-                            this.journals.closeAndDelete(descriptor.id);
-                        }
-                        continue;
+                const last = restored ? null : this.terminalStatusToReplay(descriptor);
+                if (last) {
+                    this.ws.send({
+                        type: 'session_status',
+                        sessionId: descriptor.id,
+                        status: last.status,
+                        ...(last.extra ?? {}),
+                        // Guarded in `terminalStatusToReplay` to be >= the descriptor's
+                        // epoch, so the API keeps it.
+                        ...(last.epoch === undefined ? {} : { epoch: last.epoch }),
+                    });
+                    if (this.journals.open(descriptor.id).unacked().length === 0) {
+                        this.journals.closeAndDelete(descriptor.id);
                     }
+                    continue;
                 }
                 if (descriptor.status === 'STARTING') {
-                    await this.startSession(descriptor);
+                    await this.startSession(descriptor, 'runner_restarted');
                 }
-                else if (descriptor.providerSessionId) {
+                else if (restored) {
                     // Runner restarted mid-session. The provider session is resumable —
-                    // park it until the user sends the next instruction. The map entry is
-                    // registered BEFORE the worktree await so a racing message is
-                    // buffered instead of dropped (QA-96 F3).
-                    const running = {
-                        descriptor,
-                        journal: this.journals.open(descriptor.id),
-                        session: null,
-                        lastReported: descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT',
-                        costUsd: descriptor.costUsd,
-                        costBaseUsd: descriptor.costUsd,
-                        levels: freshLevels(),
-                        stopRequested: false,
-                        parkRequested: false,
-                        // Registered before the worktree await, so the gate has to be up
-                        // before it too (#401).
-                        starting: true,
-                        pendingMessages: [],
-                        // Seed from the API, not 0: a runner restart used to hand the session
-                        // a full fresh budget silently.
-                        activeMs: descriptor.activeMsBase,
-                        extraBudgetMinutes: descriptor.extraBudgetMinutes,
-                        epoch: descriptor.epoch,
-                        openQuestions: new Set(),
-                        openPermissions: new Set(),
-                        liveToolUses: new Set(),
-                        pauseEpoch: 0,
-                        processSeq: 0,
-                        answeredAsks: new Set(),
-                        deliveredMessageIds: new Set(),
-                        backgroundTasks: 0,
-                        ...pausedUntilOf(descriptor),
-                        mode: descriptor.mode,
-                        ...(descriptor.model ? { model: descriptor.model } : {}),
-                        ...(descriptor.effort ? { effort: descriptor.effort } : {}),
-                        lastPrompt: '',
-                    };
-                    running.journal.ensureSeqAbove(descriptor.lastSeq);
-                    // Anything the API handed us before the daemon stopped (session 9).
-                    running.pendingMessages.push(...running.journal.pending());
-                    this.sessions.set(descriptor.id, running);
+                    // park it until the user sends the next instruction. The map entry
+                    // was registered before the first await of this pass (see
+                    // `restoring` above) so a racing message is buffered instead of
+                    // dropped (QA-96 F3), and the cards of the dead process are already
+                    // closed (#392).
+                    const running = restored;
                     try {
                         try {
                             // A session being restored after a runner restart already has its
@@ -5502,12 +5920,42 @@ export class Supervisor {
                         // from it. Only the instruction at the end changes — telling someone to
                         // send a message while the agent is already working again would be a lie.
                         this.sendEvent(running, 'system_note', {
+                            // The code is for the dashboard (#348): a compaction the dead
+                            // process was in the middle of ends here, and this line is the
+                            // only thing in the feed that says so.
+                            code: 'runner_reconnected',
                             text: willContinue
                                 ? 'Runner reconnected. The session was resumed — continuing the interrupted turn.'
                                 : resumeId
                                     ? 'Runner reconnected. The session was resumed — send a message to continue.'
                                     : 'Runner reconnected, but the agent never got as far as naming its conversation, so it starts this one over. Your files, your branch and everything above are untouched.',
                         });
+                        /**
+                         * The subagents that died with the process (#393).
+                         *
+                         * «Four of twelve. Waiting.» followed by «Runner reconnected» reads
+                         * as «the other eight are still coming». They are not: a restart
+                         * kills the agent process and every subagent inside it, and
+                         * `--resume` brings back the conversation, never the work. One short
+                         * line with the number, and only when there is a number to give —
+                         * the API sends `backgroundTasks` only while it still believes the
+                         * count (its own trust window), and sends nothing when everyone had
+                         * reported before the process died.
+                         *
+                         * BEFORE `reportStatus` below, which carries this session's fresh
+                         * zero: once that frame lands, the number is gone everywhere. And
+                         * once per restart rather than per reconnect by construction — a
+                         * session this process already tracks never reaches this branch.
+                         * «Stopped», never «finished»: to a person waiting for a report the
+                         * two are opposites.
+                         */
+                        if (descriptor.backgroundTasks && descriptor.backgroundTasks > 0) {
+                            const n = descriptor.backgroundTasks;
+                            this.sendEvent(running, 'system_note', {
+                                code: 'background_tasks_lost',
+                                text: `The runner restart stopped ${n} background agent${n === 1 ? '' : 's'}.`,
+                            });
+                        }
                         if (willContinue) {
                             // Resumed through the PROVIDER session, so the agent keeps its whole
                             // conversation; the prompt is only the nudge a human would otherwise
@@ -5582,7 +6030,7 @@ export class Supervisor {
                     // A session that never had a turn (a free session still waiting for
                     // its first message) has nothing to resume — just bring the agent back
                     // up and keep waiting, instead of failing the session.
-                    await this.startSession({ ...descriptor, status: 'STARTING', prompt: '' });
+                    await this.startSession({ ...descriptor, status: 'STARTING', prompt: '' }, 'runner_restarted');
                 }
                 else {
                     this.reportStatus(descriptor.id, 'FAILED', {
@@ -6079,12 +6527,14 @@ export class Supervisor {
                             error: 'The agent could not compact right now — wait for the current turn to finish',
                         });
                     }
-                    // Ticket #185. Compaction is a whole agent turn — `/compact` goes in
-                    // as an ordinary user message — and until now nobody said so: the
-                    // session read «Ваш ход» for the entire squeeze, and the dashboard
-                    // papered over it with `compactingSince`, a variable that exists only
-                    // in the tab that pressed the button. A second tab, a teammate or a
-                    // reload saw a session waiting for a person who had nothing to do.
+                    // Ticket #185. On Claude a compaction is a whole agent turn —
+                    // `/compact` goes in as an ordinary user message — and until 0.36
+                    // nobody said so: the session read «Ваш ход» for the entire squeeze.
+                    // The end of it is the turn's own ending there; on Codex, which runs
+                    // it outside any turn, the end is the adapter's `compaction` event
+                    // (#348, `forwardEvent`), and both agents now leave their lines in
+                    // the feed — the dashboard reads its indicator from those, not from
+                    // a variable of the tab that pressed the button.
                     //
                     // It is also not only cosmetic here: a session reading WAITING_INPUT
                     // with no open question is parkable, and parking it would kill the
@@ -6094,6 +6544,16 @@ export class Supervisor {
                         this.syncBudgetClock(running);
                         this.reportStatus(running.descriptor.id, 'RUNNING', {});
                     }
+                    // The start line comes from HERE, not from the agent (#348): the
+                    // agent's own «compacting» arrives when it gets round to it — on
+                    // Codex the `contextCompaction` item may only show up at the end —
+                    // and the moment a person can see the indicator is the moment the
+                    // request was taken, on every tab. The agent's later start is then
+                    // the same compaction (de-duplicated above). `user`, because that is
+                    // who asked: only this kind is offered a «Cancel».
+                    if (!running.compaction)
+                        this.openCompaction(running, 'user');
+                    this.armCompactionWatchdog(running);
                     return void reply({ ok: true, result: { started: true } });
                 }
                 case 'git_status': {
@@ -6516,6 +6976,50 @@ export class Supervisor {
                         this.opts.onRestartRequested?.(outcome);
                     return;
                 }
+                /**
+                 * «Restart the runner» from the server card (#396, plan R13).
+                 *
+                 * The whole errand on this side: answer, tell every live session why it
+                 * is about to go quiet, and exit for the service to start us again. The
+                 * API cannot do the middle part — the feeds belong to sessions only this
+                 * process knows about — and it does not try to.
+                 *
+                 * Refused, in words, when nothing would bring the daemon back: a runner
+                 * started by hand that exits here is a machine that has lost its runner
+                 * until somebody with SSH notices. Same condition and the same shape of
+                 * sentence as `self_update`'s (`self-update.ts`), and the same reason.
+                 */
+                case 'runner_restart': {
+                    if (!isSupervisedProcess()) {
+                        const detail = 'The runner is not running as a service on this machine, so nothing would start it ' +
+                            'again. Install it with `devbridge-runner install-service`, or restart it by hand.';
+                        return void reply({ ok: false, result: { ok: false, detail }, error: detail });
+                    }
+                    // Second line of defence behind the API's per-server lock, exactly as
+                    // `self_update` has: exiting in the middle of an `npm install -g`
+                    // leaves a half-written package for the service to start.
+                    const busy = this.installBusyReason();
+                    if (busy)
+                        return void reply({ ok: false, result: { ok: false, detail: busy }, error: busy });
+                    const note = str(frame.args?.['note']);
+                    // BEFORE `shutdown()`, which clears the session map — and before the
+                    // exit, because everything on this path is journaled synchronously
+                    // for the reason spelled out on `shutdown` itself. A person whose
+                    // session goes quiet did not press the button; the line is how they
+                    // find out it was pressed at all.
+                    if (note) {
+                        for (const running of this.sessions.values()) {
+                            this.sendEvent(running, 'system_note', { code: 'runner_restart', text: note });
+                        }
+                    }
+                    // Set BEFORE the reply: the API releases its per-server lock the
+                    // moment the reply lands, and the next errand must meet a machine
+                    // that already knows it is leaving.
+                    this.restarting = true;
+                    reply({ ok: true, result: { ok: true } });
+                    this.opts.onRestartCommanded?.(note);
+                    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
@@ -7098,6 +7602,9 @@ export class Supervisor {
             // redelivered on the next connection (QA-106 M1).
             try {
                 this.withdrawOpenQuestions(running, 'runner_restarted');
+                // …and what only the journal still knows about (#392): a card from a
+                // previous life this process inherited the file from but never held.
+                this.withdrawJournaledQuestions(running, 'runner_restarted');
             }
             catch (error) {
                 log.warn('supervisor: could not withdraw open questions on shutdown', {