@bridge4dev/runner 0.55.1 → 0.57.0

package/dist/supervisor.js

@@ -31,6 +31,7 @@ import { composeMessageWithAttachments, saveAttachments, } from './attachments.j
 import { applyRewind, createCheckpoint, dropCheckpoints, listCheckpoints, MAX_BUSY_SESSIONS, previewRewind, pruneCheckpoints, } from './checkpoints.js';
 import { DeliverMessageArgsSchema, QuestionAnswerArgsSchema } from './protocol.js';
 import { availableModes, MODE_REFUSED_TEXT } from './adapters/types.js';
+import { answersAsMessage } from './adapters/questions.js';
 /** Refusals shared by every checkpoint command (ticket #126). */
 const CHECKPOINTS_OFF = 'Restore points are switched off on this server ([checkpoints] enabled = false)';
 const AGENT_BUSY = 'The agent is still working — stop the turn first';
@@ -144,6 +145,8 @@ export class Supervisor {
      * which of the two is running.
      */
     installInFlight = null;
+    /** A restore-point collection is running; a second reconnect must not start another (#388). */
+    checkpointGcInFlight = false;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
     verify;
     verifyReports = new VerifyReportQueue();
@@ -1015,6 +1018,9 @@ export class Supervisor {
             levels: freshLevels(),
             stopRequested: false,
             parkRequested: false,
+            // Set here rather than at the first `await`: frames are dispatched
+            // concurrently, so anything assigned later is already too late (#401).
+            starting: true,
             pendingMessages: [],
             activeMs: descriptor.activeMsBase,
             extraBudgetMinutes: descriptor.extraBudgetMinutes,
@@ -1068,71 +1074,84 @@ export class Supervisor {
             }
         }
         try {
-            const prepared = await this.prepareWorkspace(descriptor);
-            running.branch = prepared.branch;
-            running.worktreePath = prepared.worktreePath;
-            // Only when WE created the branch: the fork point is a fact the API can
-            // learn nowhere else, and it pins the first answer it gets.
-            if (prepared.baseSha)
-                running.baseSha = prepared.baseSha;
-            if (prepared.baseBranch)
-                running.baseBranch = prepared.baseBranch;
-        }
-        catch (error) {
-            this.workspacePrepareFailed(running, error, 'Failed to prepare git worktree');
-            return;
-        }
-        // A session that is already past STARTING (re-sent because this runner
-        // asked for it) resumes on the next message instead of replaying its
-        // original prompt.
-        if (descriptor.status === 'STARTING') {
-            // Ticket #126: the point before the agent has touched anything. It is
-            // anchored to seq 0 — the synthetic opening bubble the dashboard puts in
-            // front of every feed — so "put it all back" is reachable from the very
-            // first thing on the page.
-            await this.captureCheckpoint(running, 'TURN', 0);
-            if (this.isStale(running))
-                return;
-            // A launch that failed has already said so and reported a status the
-            // person can act on. Flushing the queue into it would only walk the same
-            // failure again, once per waiting message (ticket #225).
-            if (!this.launchAgent(running, composeInitialPrompt(descriptor), null).ok)
+            try {
+                const prepared = await this.prepareWorkspace(descriptor);
+                running.branch = prepared.branch;
+                running.worktreePath = prepared.worktreePath;
+                // Only when WE created the branch: the fork point is a fact the API can
+                // learn nowhere else, and it pins the first answer it gets.
+                if (prepared.baseSha)
+                    running.baseSha = prepared.baseSha;
+                if (prepared.baseBranch)
+                    running.baseBranch = prepared.baseBranch;
+            }
+            catch (error) {
+                this.workspacePrepareFailed(running, error, 'Failed to prepare git worktree');
                 return;
-        }
-        else {
-            if (descriptor.epoch > 0) {
-                // The API owns the resume transition; the feed marker has to come from
-                // here because the runner is the only writer of the event seq.
-                //
-                // Ticket #177: which of the two sentences is true depends on whether
-                // there is a conversation to go back to. `providerSessionId` is the
-                // agent's own name for it, and it is what the next launch hands to
-                // `--resume` / `thread/resume`. Without it the next process starts the
-                // conversation over — which is a real loss, and promising «continue
-                // where the agent left off» there is the one thing the feed must not do.
-                // It happens for real: a process that dies before it reports its session
-                // id (the SIGABRT this ticket came from) leaves the row with none.
-                //
-                // Ticket #370: the sentence about the agent's MEMORY waits for proof.
-                // It used to be written here, on the strength of a stored id and before
-                // the CLI had been asked anything — and on Athanor it appeared sixty
-                // seconds before `thread/resume` timed out and took the session with it.
-                // What is honest at this moment is that the runner is back; whether the
-                // conversation reopens is answered by the process, in `provider_session`.
-                if (descriptor.providerSessionId)
-                    running.resumeClaimPending = true;
-                this.sendEvent(running, 'system_note', {
-                    text: descriptor.providerSessionId
-                        ? 'Session resumed — send a message and the agent picks its conversation back up.'
-                        : 'Session resumed, 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.',
+            }
+            // A session that is already past STARTING (re-sent because this runner
+            // asked for it) resumes on the next message instead of replaying its
+            // original prompt.
+            if (descriptor.status === 'STARTING') {
+                // Ticket #126: the point before the agent has touched anything. It is
+                // anchored to seq 0 — the synthetic opening bubble the dashboard puts in
+                // front of every feed — so "put it all back" is reachable from the very
+                // first thing on the page.
+                await this.captureCheckpoint(running, 'TURN', 0);
+                if (this.isStale(running))
+                    return;
+                // A launch that failed has already said so and reported a status the
+                // person can act on. Flushing the queue into it would only walk the same
+                // failure again, once per waiting message (ticket #225).
+                if (!this.launchAgent(running, composeInitialPrompt(descriptor), null).ok)
+                    return;
+            }
+            else {
+                if (descriptor.epoch > 0) {
+                    // The API owns the resume transition; the feed marker has to come from
+                    // here because the runner is the only writer of the event seq.
+                    //
+                    // Ticket #177: which of the two sentences is true depends on whether
+                    // there is a conversation to go back to. `providerSessionId` is the
+                    // agent's own name for it, and it is what the next launch hands to
+                    // `--resume` / `thread/resume`. Without it the next process starts the
+                    // conversation over — which is a real loss, and promising «continue
+                    // where the agent left off» there is the one thing the feed must not do.
+                    // It happens for real: a process that dies before it reports its session
+                    // id (the SIGABRT this ticket came from) leaves the row with none.
+                    //
+                    // Ticket #370: the sentence about the agent's MEMORY waits for proof.
+                    // It used to be written here, on the strength of a stored id and before
+                    // the CLI had been asked anything — and on Athanor it appeared sixty
+                    // seconds before `thread/resume` timed out and took the session with it.
+                    // What is honest at this moment is that the runner is back; whether the
+                    // conversation reopens is answered by the process, in `provider_session`.
+                    if (descriptor.providerSessionId)
+                        running.resumeClaimPending = true;
+                    this.sendEvent(running, 'system_note', {
+                        text: descriptor.providerSessionId
+                            ? 'Session resumed — send a message and the agent picks its conversation back up.'
+                            : 'Session resumed, 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.',
+                    });
+                }
+                running.lastReported = descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT';
+                this.reportStatus(descriptor.id, running.lastReported, {
+                    branch: running.branch,
+                    worktreePath: running.worktreePath,
+                    activeMs: running.activeMs,
                 });
             }
-            running.lastReported = descriptor.status === 'REVIEW' ? 'REVIEW' : 'WAITING_INPUT';
-            this.reportStatus(descriptor.id, running.lastReported, {
-                branch: running.branch,
-                worktreePath: running.worktreePath,
-                activeMs: running.activeMs,
-            });
+        }
+        finally {
+            /**
+             * The startup gate opens again on EVERY exit, including the failed ones.
+             *
+             * #401: this flag is what makes `acceptUserMessage` hold a message until
+             * the first process exists. Left standing by an early return it would
+             * hold the person's words in the queue for the life of the session, so
+             * it is cleared here rather than at each `return` above.
+             */
+            running.starting = false;
         }
         this.flushPendingMessages(running);
     }
@@ -1225,6 +1244,40 @@ export class Supervisor {
         const adapter = this.opts.adapters[descriptor.agent];
         if (!adapter || !running.worktreePath || !running.branch)
             return LAUNCH_REFUSED;
+        /**
+         * One process per session, enforced where the slot is written (#401).
+         *
+         * `running.session` is a single field, and until this check it was assigned
+         * unconditionally: a second launch overwrote the reference to a process
+         * that was still running, and nobody held it any more. Everything the
+         * session then did — a message, an answer to a question, `stop`, the memory
+         * watch — addressed the survivor, while the orphan kept working, kept its
+         * own cgroup and outlived even the service restart.
+         *
+         * Safe as an entry check because this method is SYNCHRONOUS from here to
+         * the assignment: nothing yields in between, so «free now» is still true
+         * when the slot is filled.
+         *
+         * Every legitimate caller reaches this with an empty slot, by one of three
+         * arguments: the four one-shot relaunches run in the tail of `pumpEvents`,
+         * where the slot was emptied because the process is gone; `deliverMessage`
+         * only gets here past its own `running.session` test and is serialised by
+         * the session's delivery chain; and the two opening doors hold `starting`
+         * for exactly as long as it takes them to decide, which is what keeps the
+         * queue from starting an agent out from under them.
+         *
+         * A refusal here is therefore not a race being caught — it is a bug, and
+         * the log line says so. Read it together with `starting`: this guard alone
+         * would turn «two processes» into «the session's own task never sent», the
+         * quieter of the two failures.
+         */
+        if (running.session) {
+            log.error('supervisor: refusing to launch a second agent for one session', {
+                sessionId: descriptor.id,
+                processSeq: running.processSeq,
+            });
+            return LAUNCH_REFUSED;
+        }
         // An exhausted USD budget must not relaunch $0.01-floor processes (QA-96 F4).
         // Codex reports no cost at all, so its costUsd never leaves 0 — gating on it
         // would be a limit that can never fire while the UI shows $0.00. Those
@@ -1691,8 +1744,35 @@ export class Supervisor {
             });
         }
         // Stream ended — the agent process is gone.
-        if (running.session !== session)
-            return; // superseded (shouldn't happen in v0)
+        if (running.session !== session) {
+            /**
+             * Somebody else holds the slot while this process's stream ends.
+             *
+             * Since #401 the launch REFUSES to overwrite a live process, and the slot
+             * is emptied only where the process is known to be gone — the line below
+             * and `launchCrashed`. So this branch no longer means «a live agent was
+             * orphaned»; it means the entry was rebuilt under this stream, and the
+             * cleanup below belongs to whoever holds it now. Said out loud rather
+             * than returned in silence: the old comment here called the case
+             * impossible, and it was the shape four production sessions took.
+             */
+            log.warn('supervisor: event stream ended for a process that no longer holds the slot', {
+                sessionId: descriptor.id,
+                processSeq: running.processSeq,
+            });
+            return;
+        }
+        /**
+         * The slot describes a LIVE process, so it is emptied the moment there is
+         * none — here, and not by whoever launches next (#401).
+         *
+         * Three of the one-shot relaunches below (`freshRetry`, `rewindRetry`,
+         * `authRetry`) used to call `launchAgent` with the dead adapter still in
+         * the slot and rely on being overwritten. That overwrite is exactly what
+         * the launch now refuses, so without this line the recovery paths would
+         * refuse themselves. Nothing between here and them reads the field.
+         */
+        running.session = null;
         // Backstop for a process that died without going through `stop()` (a crash,
         // an SDK error, an agent that exited mid-question): the adapter never got
         // to withdraw its cards, and a card nobody can answer must not stay live.
@@ -1766,7 +1846,9 @@ export class Supervisor {
             const { priorStatus } = running.modeRelaunch;
             delete running.modeRelaunch;
             running.parkRequested = false;
-            running.session = null;
+            // The slot was emptied where the process was found gone (#401) — this
+            // branch used to be the only one that remembered to do it, and the three
+            // above did not. One place, so they cannot disagree again.
             running.costBaseUsd = running.costUsd; // the next process starts from here
             const mode = running.mode;
             // «Your conversation is kept» is only true when there IS one to keep
@@ -1830,7 +1912,7 @@ export class Supervisor {
             !isTerminal(running.lastReported) &&
             running.descriptor.providerSessionId) {
             // Idle process ended (parked or died between turns) — stay resumable.
-            running.session = null;
+            // The slot itself was emptied above, where the process was found gone.
             running.parkRequested = false;
             /**
              * The subagents died with it (QA-2026-08-16 M-5).
@@ -2878,8 +2960,26 @@ export class Supervisor {
         // words below have now been published once, and a redelivery must not
         // publish them again.
         running.answeredAsks.add(frame.askId);
+        /**
+         * The reply, whichever control the person used to give it (#401).
+         *
+         * `frame.text` alone was not it: that field carries the bottom input of the
+         * card («Discuss instead»), and the dashboard sends the ORDINARY answer as
+         * `answers` with no text at all. So a branch that rescued only the text
+         * lost the entire reply of everyone who answered by tapping the options —
+         * silently, because the card stayed live and said nothing. That is what
+         * happened to the owner on 08.09.2026 and it is the second half of this
+         * ticket: a question that could not be answered AND an answer that
+         * vanished.
+         *
+         * Both halves, joined rather than one or the other: the frame allows a
+         * person to have typed AND picked, and dropping either would be the same
+         * defect on a narrower path. The sentence comes first because that is the
+         * order the card puts them in.
+         */
+        const rescued = [typed, answersAsMessage(frame.answers ?? [])].filter(Boolean).join('\n');
         this.sendEvent(running, 'system_note', {
-            text: typed
+            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.',
         });
@@ -2887,8 +2987,8 @@ export class Supervisor {
         // 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).
-        if (typed) {
-            this.acceptUserMessage(frame.sessionId, typed);
+        if (rescued) {
+            this.acceptUserMessage(frame.sessionId, rescued);
             return 'not_open';
         }
         // Nothing to deliver — but the API optimistically flipped the session to
@@ -2978,11 +3078,22 @@ export class Supervisor {
             ...(attachments?.length ? { attachments } : {}),
         });
         const originSeq = echoed.seq;
-        if (!running.worktreePath || Supervisor.isPaused(running)) {
+        if (running.starting || !running.worktreePath || Supervisor.isPaused(running)) {
             // Session is still being prepared — deliver after launch (QA-96 F3).
             // Attachments travel as metadata and are downloaded at delivery time,
             // which is the first moment the worktree is guaranteed to exist.
             //
+            // #401: `starting` is the half of that promise the condition used to be
+            // missing. The folder is ready in milliseconds and the first process only
+            // seconds later, so testing the folder alone let a message through into a
+            // session that had no agent yet — and the delivery path then started one
+            // of its own, beside the one `startSession` was about to start. Both
+            // halves are named because they fail apart: a session past STARTING has a
+            // folder and no `starting`, and waking it with a message is correct.
+            //
+            // Nothing is lost by waiting: `flushPendingMessages` runs on the way out
+            // of `startSession`, after the launch, and delivers this queue in order.
+            //
             // Or the session is held under a clock (#196). The API refuses live
             // messages for a paused session, but not every path goes through that
             // check — the outbox flushes on reconnect, and the git service posts its
@@ -3401,9 +3512,20 @@ export class Supervisor {
      * a second session opened. The neighbours are recorded on the point instead —
      * the conversation can always be rewound to it, the files cannot.
      *
-     * Every refusal is now audible. A restore point that was never taken is
-     * invisible until the day somebody reaches for it, and «the button is not
-     * there» is not a sentence anybody can act on.
+     * A refusal is audible when it is a refusal — when the person can do
+     * something about it, or when a way back they might reach for is not there.
+     * A restore point that was never taken is invisible until the day somebody
+     * reaches for it, and «the button is not there» is not a sentence anybody can
+     * act on.
+     *
+     * «This session was still answering» is the exception, and it is the only one
+     * (#384). It is not a fault and not a state to act on: it is what a follow-up
+     * note to a working agent looks like from in here, thirty times in a day on
+     * one machine, and it costs almost nothing — the point in front of the turn
+     * already stands, and rewinding to it takes back the files AND the
+     * conversation, including the note. So it goes to the runner's own log, where
+     * support can answer «why is there no point for that step», and not into the
+     * feed, where it read as breakage.
      */
     async captureCheckpoint(running, kind, messageSeq) {
         const worktreePath = running.worktreePath;
@@ -3421,7 +3543,13 @@ export class Supervisor {
             return;
         }
         if (kind === 'TURN' && this.isSessionMidTurn(running)) {
-            this.noticeOncePerTurn(running, 'checkpoint-self-busy', 'No restore point was taken for this step: this session was still answering when it was due.');
+            // Silent in the feed, on purpose (#384) — see the note above. The `return`
+            // is not cosmetic and does not go: reading a tree the agent is writing
+            // produces a restore point that restores half a file (gotcha 438).
+            log.info('supervisor: no restore point — the session was mid-turn', {
+                sessionId: running.descriptor.id,
+                ...(messageSeq === undefined ? {} : { messageSeq }),
+            });
             return;
         }
         if (await this.isRepoLocked(worktreePath)) {
@@ -3433,7 +3561,8 @@ export class Supervisor {
         // rewind resumes the session the point names rather than whichever one the
         // session happens to be on now.
         const anchor = this.currentAnchor(running);
-        const result = await createCheckpoint({
+        const takeCheckpoint = this.opts.createCheckpoint ?? createCheckpoint;
+        const result = await takeCheckpoint({
             worktreePath,
             sessionId: running.descriptor.id,
             kind,
@@ -3487,16 +3616,18 @@ export class Supervisor {
     /**
      * Say something once per BUSY PERIOD, not once per message (#310).
      *
-     * A folder held by a neighbour stays held for minutes, and a session mid-turn
-     * can be sent three follow-up notes inside one answer. Keying this on the
-     * message seq would have counted each of those as its own turn and said the
-     * same sentence three times — the noise the frequency policy exists to
-     * prevent. The set is cleared when the session next comes to rest
-     * (`reportStatus`), which is exactly when the reason stops being true.
+     * A repository held by another git command stays held for as long as that
+     * command runs, and three follow-up notes can arrive inside one answer.
+     * Keying this on the message seq would have counted each of those as its own
+     * turn and said the same sentence three times — the noise the frequency
+     * policy exists to prevent. The set is cleared when the session next comes to
+     * rest (`reportStatus`), which is exactly when the reason stops being true.
      *
      * A SET of keys, not the last one said: two different reasons can both come
      * up inside one period, and remembering only the most recent would let them
-     * take turns re-announcing each other.
+     * take turns re-announcing each other. One key uses this today — «another git
+     * command holds this repository» — and the set stays a set for that reason,
+     * not out of habit: the mid-turn key left when it stopped being said (#384).
      */
     noticeOncePerTurn(running, key, text) {
         running.noticesThisTurn ??= new Set();
@@ -3518,6 +3649,33 @@ export class Supervisor {
         // pause. Held work stays held until the clock is off.
         if (Supervisor.isPaused(running))
             return;
+        /**
+         * …and by the same argument, none of them knew about a session that has not
+         * finished starting (#401, found by the independent QA of this fix).
+         *
+         * The queue is drained from six places, and two of them fire on somebody
+         * else's news: `drainSessionsWaitingForCapacity` runs whenever ANY session
+         * on this runner frees a slot, and the pause release runs when a clock comes
+         * off. Either can land in the middle of another session's opening, where the
+         * slot is legitimately empty — so delivery would start the agent with the
+         * queued message, and the opening's own launch would then be refused by the
+         * guard in `launchAgent`. The session's task would never be handed over at
+         * all, and the only trace would be one line in the daemon's log.
+         *
+         * That is a QUIETER failure than the two processes this ticket started
+         * from, so the check belongs here, at the one place the queue turns into
+         * delivery, and not at each of the six callers.
+         *
+         * This does NOT make the `starting` test in `acceptUserMessage` redundant:
+         * that one decides whether a message joins the queue at all, and without it
+         * a message would go straight down the delivery chain and never be seen
+         * here. Two different questions, both needed.
+         *
+         * The opening procedure drains its own queue on the way out, after clearing
+         * the flag — `startSession` and the reconnect branch both do it.
+         */
+        if (running.starting)
+            return;
         const pending = running.pendingMessages.splice(0);
         if (pending.length === 0)
             return;
@@ -4275,14 +4433,26 @@ export class Supervisor {
         // switched off leaves restore points — a full copy of a working tree —
         // with no row anywhere pointing at them, and nothing else on this machine
         // would ever collect them.
-        void pruneCheckpoints({ liveSessionIds: known }).then((result) => {
-            if (result.droppedRefs > 0) {
-                log.info('supervisor: collected orphaned restore points', {
-                    sessions: result.droppedSessions.length,
-                    refs: result.droppedRefs,
-                });
-            }
-        }, (error) => log.warn('supervisor: restore-point GC failed', { error: String(error) }));
+        //
+        // One at a time (#388): reconnects come in runs, and since the collection
+        // holds the store while it collects, a second one started on top of the
+        // first would only queue — in front of the restore points of whoever is
+        // working. The next reconnect collects whatever this pass leaves.
+        if (!this.checkpointGcInFlight) {
+            this.checkpointGcInFlight = true;
+            void pruneCheckpoints({ liveSessionIds: known })
+                .then((result) => {
+                if (result.droppedRefs > 0) {
+                    log.info('supervisor: collected orphaned restore points', {
+                        sessions: result.droppedSessions.length,
+                        refs: result.droppedRefs,
+                    });
+                }
+            }, (error) => log.warn('supervisor: restore-point GC failed', { error: String(error) }))
+                .finally(() => {
+                this.checkpointGcInFlight = false;
+            });
+        }
         for (const [sessionId, running] of [...this.sessions]) {
             if (known.has(sessionId))
                 continue;
@@ -4417,6 +4587,9 @@ export class Supervisor {
                         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.
@@ -4442,110 +4615,132 @@ export class Supervisor {
                     running.pendingMessages.push(...running.journal.pending());
                     this.sessions.set(descriptor.id, running);
                     try {
-                        // A session being restored after a runner restart already has its
-                        // branch, so the API sends `CONTINUE` — the NEW guard inside would
-                        // otherwise fire on the runner's own previous work.
-                        const prepared = await this.prepareWorkspace(descriptor);
-                        running.branch = prepared.branch;
-                        running.worktreePath = prepared.worktreePath;
-                        if (prepared.baseSha)
-                            running.baseSha = prepared.baseSha;
-                        if (prepared.baseBranch)
-                            running.baseBranch = prepared.baseBranch;
-                    }
-                    catch (error) {
-                        // The same treatment as the start door (#360). Two doors doing one
-                        // thing is how the pause bug of #373 stayed half-fixed for a
-                        // release; this one used to mask its text differently AND emit no
-                        // feed event at all, so a session that could not be restored went
-                        // FAILED with nothing to read anywhere.
-                        this.workspacePrepareFailed(running, error, 'Failed to restore session worktree');
-                        continue;
-                    }
-                    /**
-                     * Was a turn actually in flight when the process died?
-                     *
-                     * `RUNNING` and `WAITING_PERMISSION` are the mid-turn statuses; the
-                     * others mean the agent was already waiting for a human, and there is
-                     * nothing to continue. REVIEW is deliberately excluded — the work is
-                     * finished and waiting to be looked at.
-                     */
-                    const wasMidTurn = descriptor.status === 'RUNNING' || descriptor.status === 'WAITING_PERMISSION';
-                    const resumeId = descriptor.providerSessionId;
-                    // Ticket #177: `resumeId` is required, not merely nice to have. Without
-                    // it the relaunch starts a FRESH conversation, and `AUTO_RESUME_PROMPT`
-                    // — "continue from where you stopped, re-check what you were in the
-                    // middle of" — would be addressed to an agent that remembers none of
-                    // it. A process killed before it reported its session id (the SIGABRT
-                    // this ticket came from) leaves the row in exactly that state.
-                    // Ticket #196: a paused session is never continued automatically. The
-                    // row still says RUNNING — a pause interrupts the turn but is not a
-                    // status — so without this the reconnect would read «mid-turn» and
-                    // relaunch the agent with «continue from where you stopped», which is
-                    // the exact opposite of what the clock was set for.
-                    const willContinue = wasMidTurn &&
-                        !Supervisor.isPaused(running) &&
-                        Boolean(resumeId) &&
-                        claimAutoResume(descriptor.id);
-                    // The note stays either way (owner's call): an interruption is a fact
-                    // about the session and must not disappear just because we recovered
-                    // 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', {
-                        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.',
-                    });
-                    if (willContinue) {
-                        // Resumed through the PROVIDER session, so the agent keeps its whole
-                        // conversation; the prompt is only the nudge a human would otherwise
-                        // have to type. Exactly what «продолжай» did by hand — no new class of
-                        // risk, and the same ceiling protects against a crash loop doing it
-                        // forever (see `auto-resume.ts`).
-                        const continued = this.launchAgent(running, AUTO_RESUME_PROMPT, resumeId);
-                        if (continued.ok) {
-                            this.reportStatus(descriptor.id, 'RUNNING', {});
-                            this.flushPendingMessages(running);
+                        try {
+                            // A session being restored after a runner restart already has its
+                            // branch, so the API sends `CONTINUE` — the NEW guard inside would
+                            // otherwise fire on the runner's own previous work.
+                            const prepared = await this.prepareWorkspace(descriptor);
+                            running.branch = prepared.branch;
+                            running.worktreePath = prepared.worktreePath;
+                            if (prepared.baseSha)
+                                running.baseSha = prepared.baseSha;
+                            if (prepared.baseBranch)
+                                running.baseBranch = prepared.baseBranch;
+                        }
+                        catch (error) {
+                            // The same treatment as the start door (#360). Two doors doing one
+                            // thing is how the pause bug of #373 stayed half-fixed for a
+                            // release; this one used to mask its text differently AND emit no
+                            // feed event at all, so a session that could not be restored went
+                            // FAILED with nothing to read anywhere.
+                            this.workspacePrepareFailed(running, error, 'Failed to restore session worktree');
                             continue;
                         }
-                        // Could not start — an exhausted budget, or a launch that crashed
-                        // (ticket #225: this is the exact line the incident died on, and the
-                        // throw took the WHOLE restore loop with it). Fall through to the old
-                        // behaviour and say so honestly; a crash has already put its own
-                        // reason in the feed, so this note would only repeat it.
-                        if (continued.reason === 'refused') {
-                            this.sendEvent(running, 'system_note', {
-                                text: 'Could not continue automatically — send a message to pick the work back up.',
-                            });
+                        /**
+                         * Was a turn actually in flight when the process died?
+                         *
+                         * `RUNNING` and `WAITING_PERMISSION` are the mid-turn statuses; the
+                         * others mean the agent was already waiting for a human, and there is
+                         * nothing to continue. REVIEW is deliberately excluded — the work is
+                         * finished and waiting to be looked at.
+                         */
+                        const wasMidTurn = descriptor.status === 'RUNNING' || descriptor.status === 'WAITING_PERMISSION';
+                        const resumeId = descriptor.providerSessionId;
+                        // Ticket #177: `resumeId` is required, not merely nice to have. Without
+                        // it the relaunch starts a FRESH conversation, and `AUTO_RESUME_PROMPT`
+                        // — "continue from where you stopped, re-check what you were in the
+                        // middle of" — would be addressed to an agent that remembers none of
+                        // it. A process killed before it reported its session id (the SIGABRT
+                        // this ticket came from) leaves the row in exactly that state.
+                        // Ticket #196: a paused session is never continued automatically. The
+                        // row still says RUNNING — a pause interrupts the turn but is not a
+                        // status — so without this the reconnect would read «mid-turn» and
+                        // relaunch the agent with «continue from where you stopped», which is
+                        // the exact opposite of what the clock was set for.
+                        const willContinue = wasMidTurn &&
+                            !Supervisor.isPaused(running) &&
+                            Boolean(resumeId) &&
+                            claimAutoResume(descriptor.id);
+                        // The note stays either way (owner's call): an interruption is a fact
+                        // about the session and must not disappear just because we recovered
+                        // 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', {
+                            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.',
+                        });
+                        if (willContinue) {
+                            // Resumed through the PROVIDER session, so the agent keeps its whole
+                            // conversation; the prompt is only the nudge a human would otherwise
+                            // have to type. Exactly what «продолжай» did by hand — no new class of
+                            // risk, and the same ceiling protects against a crash loop doing it
+                            // forever (see `auto-resume.ts`).
+                            const continued = this.launchAgent(running, AUTO_RESUME_PROMPT, resumeId);
+                            if (continued.ok) {
+                                this.reportStatus(descriptor.id, 'RUNNING', {});
+                                // The opening is over — hand the queue back before draining it,
+                                // because `flushPendingMessages` refuses a session that is still
+                                // starting (#401). The `finally` below is the net for the exits
+                                // that never get here.
+                                running.starting = false;
+                                this.flushPendingMessages(running);
+                                continue;
+                            }
+                            // Could not start — an exhausted budget, or a launch that crashed
+                            // (ticket #225: this is the exact line the incident died on, and the
+                            // throw took the WHOLE restore loop with it). Fall through to the old
+                            // behaviour and say so honestly; a crash has already put its own
+                            // reason in the feed, so this note would only repeat it.
+                            if (continued.reason === 'refused') {
+                                this.sendEvent(running, 'system_note', {
+                                    text: 'Could not continue automatically — send a message to pick the work back up.',
+                                });
+                            }
                         }
+                        /**
+                         * 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), {});
+                        // As above: the flag comes off first, or the drain below is a no-op.
+                        running.starting = false;
+                        this.flushPendingMessages(running);
+                    }
+                    finally {
+                        /**
+                         * The same gate as the start door, for the same reason (#401).
+                         *
+                         * This branch registers the entry BEFORE awaiting the worktree —
+                         * deliberately, so a racing message is buffered rather than dropped
+                         * (QA-96 F3) — and then decides for itself whether to bring the
+                         * agent back up. A message let through in between would make that
+                         * decision instead, and the feed would go on to say the session
+                         * could not be continued automatically while it plainly was.
+                         */
+                        running.starting = false;
                     }
-                    /**
-                     * 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') {
                     // A session that never had a turn (a free session still waiting for