@bridge4dev/runner 0.37.0 → 0.39.0

package/dist/supervisor.js

@@ -51,6 +51,7 @@ function gitPolicyOf(descriptor) {
             : {}),
     };
 }
+const LAUNCH_REFUSED = { ok: false, reason: 'refused' };
 export class Supervisor {
     ws;
     opts;
@@ -367,7 +368,11 @@ export class Supervisor {
             await this.captureCheckpoint(running, 'TURN', 0);
             if (this.isStale(running))
                 return;
-            this.launchAgent(running, composeInitialPrompt(descriptor), null);
+            // 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) {
@@ -425,15 +430,23 @@ export class Supervisor {
      * free CHAT session with no prompt at all (the agent boots, reports its
      * capabilities and waits for the first message).
      *
-     * Returns whether an agent process actually started: a caller holding a user
-     * message needs to know, because a refused launch means the message has to
-     * stay queued rather than be marked delivered (session 9).
+     * Returns what came of it: a caller holding a user message needs to know,
+     * because anything but `ok` means the message has to stay queued rather than
+     * be marked delivered (session 9).
+     *
+     * NEVER throws (ticket #225). Everything from reading the project prompt to
+     * the adapter's own constructor runs inside one guard, because the caller
+     * chain above cannot tell the difference between «did not start» and
+     * «threw»: the message path swallows the exception into a log line, and the
+     * reconnect path lets it abort the restore of every OTHER session on the
+     * machine. A launch that fails is a state this session reports, not an
+     * exception somebody else has to remember to catch.
      */
     launchAgent(running, prompt, resumeId) {
         const { descriptor } = running;
         const adapter = this.opts.adapters[descriptor.agent];
         if (!adapter || !running.worktreePath || !running.branch)
-            return false;
+            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
@@ -455,7 +468,7 @@ export class Supervisor {
                 errorMessage: `Session budget ($${descriptor.workspace.budgetUsd}) is exhausted`,
             });
             this.sessions.delete(descriptor.id);
-            return false;
+            return LAUNCH_REFUSED;
         }
         // The time budget is already spent: relaunching would burn a process for
         // nothing and immediately stop again.
@@ -464,7 +477,7 @@ export class Supervisor {
                 level: 'warn',
                 text: 'The time budget is used up — press «Continue» to give the agent more time.',
             });
-            return false;
+            return LAUNCH_REFUSED;
         }
         running.lastPrompt = prompt;
         // Facts about this session only, plus the one file the project named. The
@@ -477,49 +490,60 @@ export class Supervisor {
         // «loaded» nor «unchanged».
         const rewinding = Boolean(running.rewindAnchor?.agentSession);
         const resuming = rewinding || Boolean(resumeId);
-        const agentPrompt = this.resolveAgentPrompt(running, resuming && !rewinding);
-        const workspaceContext = composeWorkspaceContext(descriptor, agentPrompt?.text);
+        // Held so the guard below can put it back: a rewind the person asked for
+        // must not be silently forgotten because the process that was going to
+        // apply it never started (ticket #225). The feed has already told them the
+        // conversation was cut.
         const rewind = running.rewindAnchor;
-        delete running.rewindAnchor;
-        // A rewind resumes the conversation the POINT names, which is not always
-        // the one this session is on now: rewinding twice, or rewinding the first
-        // message after a rewind, both reach back into the thread the fork came
-        // from. Its transcript is still on disk — that is what makes the point
-        // usable at all.
-        const resumeTarget = rewind ? rewind.agentSession : resumeId;
-        running.session = adapter.startSession({
-            sessionId: descriptor.id,
-            cwd: running.worktreePath,
-            ...(prompt ? { prompt } : {}),
-            ...(workspaceContext ? { workspaceContext } : {}),
-            // Only when it was actually read: layer 1 must refuse writes to the file
-            // this process was given, not to a path it was merely told about.
-            ...(agentPrompt ? { agentPromptFile: agentPrompt.absPath } : {}),
-            trustMode: descriptor.workspace.trustMode,
-            ...(descriptor.workspace.agentAutoCommit === undefined
-                ? {}
-                : { agentAutoCommit: descriptor.workspace.agentAutoCommit }),
-            // Session 18. Always present, even when every field inside it is absent:
-            // an absent OBJECT and an object of absent fields resolve identically
-            // (`resolveGitPolicy` gives both the restrictive reading), and passing it
-            // unconditionally keeps one code path instead of two.
-            gitPolicy: gitPolicyOf(descriptor),
-            mode: running.mode,
-            ...(running.model ? { model: running.model } : {}),
-            ...(running.effort ? { effort: running.effort } : {}),
-            ...(resumeTarget ? { resumeProviderSessionId: resumeTarget } : {}),
-            // Ticket #126: a conversation rewind takes effect exactly here, on the
-            // next process this session starts. Consumed rather than kept — a rewind
-            // is one event, not a standing setting, and re-applying it on a later
-            // relaunch would silently throw away everything said since.
-            ...(rewind ? { resumeAtAnchor: rewind.anchor } : {}),
-            // Descriptor MCP (auto-issued per-workspace key) wins over config.toml.
-            ...((descriptor.mcp ?? this.opts.mcp) ? { mcp: descriptor.mcp ?? this.opts.mcp } : {}),
-            // The SDK budget is per-process; hand the RESIDUAL session budget down.
-            ...(reportsCost(descriptor.agent) && descriptor.workspace.budgetUsd !== null
-                ? { maxBudgetUsd: Math.max(0.01, descriptor.workspace.budgetUsd - running.costBaseUsd) }
-                : {}),
-        });
+        try {
+            const agentPrompt = this.resolveAgentPrompt(running, resuming && !rewinding);
+            const workspaceContext = composeWorkspaceContext(descriptor, agentPrompt?.text);
+            delete running.rewindAnchor;
+            // A rewind resumes the conversation the POINT names, which is not always
+            // the one this session is on now: rewinding twice, or rewinding the first
+            // message after a rewind, both reach back into the thread the fork came
+            // from. Its transcript is still on disk — that is what makes the point
+            // usable at all.
+            const resumeTarget = rewind ? rewind.agentSession : resumeId;
+            running.session = adapter.startSession({
+                sessionId: descriptor.id,
+                cwd: running.worktreePath,
+                ...(prompt ? { prompt } : {}),
+                ...(workspaceContext ? { workspaceContext } : {}),
+                // Only when it was actually read: layer 1 must refuse writes to the file
+                // this process was given, not to a path it was merely told about.
+                ...(agentPrompt ? { agentPromptFile: agentPrompt.absPath } : {}),
+                trustMode: descriptor.workspace.trustMode,
+                ...(descriptor.workspace.agentAutoCommit === undefined
+                    ? {}
+                    : { agentAutoCommit: descriptor.workspace.agentAutoCommit }),
+                // Session 18. Always present, even when every field inside it is absent:
+                // an absent OBJECT and an object of absent fields resolve identically
+                // (`resolveGitPolicy` gives both the restrictive reading), and passing it
+                // unconditionally keeps one code path instead of two.
+                gitPolicy: gitPolicyOf(descriptor),
+                mode: running.mode,
+                ...(running.model ? { model: running.model } : {}),
+                ...(running.effort ? { effort: running.effort } : {}),
+                ...(resumeTarget ? { resumeProviderSessionId: resumeTarget } : {}),
+                // Ticket #126: a conversation rewind takes effect exactly here, on the
+                // next process this session starts. Consumed rather than kept — a rewind
+                // is one event, not a standing setting, and re-applying it on a later
+                // relaunch would silently throw away everything said since.
+                ...(rewind ? { resumeAtAnchor: rewind.anchor } : {}),
+                // Descriptor MCP (auto-issued per-workspace key) wins over config.toml.
+                ...((descriptor.mcp ?? this.opts.mcp) ? { mcp: descriptor.mcp ?? this.opts.mcp } : {}),
+                // The SDK budget is per-process; hand the RESIDUAL session budget down.
+                ...(reportsCost(descriptor.agent) && descriptor.workspace.budgetUsd !== null
+                    ? { maxBudgetUsd: Math.max(0.01, descriptor.workspace.budgetUsd - running.costBaseUsd) }
+                    : {}),
+            });
+        }
+        catch (error) {
+            if (rewind)
+                running.rewindAnchor = rewind;
+            return this.launchCrashed(running, error);
+        }
         // No prompt → nothing is running yet: the agent is up and waiting for the
         // user's first message (free CHAT session). reportStatus drives the budget
         // clock, so this call is also what starts (or does not start) billing.
@@ -527,6 +551,8 @@ export class Supervisor {
             branch: running.branch,
             worktreePath: running.worktreePath,
         });
+        // The object exists; the PROCESS still has to prove it does (ticket #225).
+        this.watchForFirstSignOfLife(running);
         // Ticket #196: a Stop or a pause that arrived while this process was coming
         // up was dropped on the floor — `interruptSession` returns early when there
         // is no adapter yet, and the window covers preparing the worktree and
@@ -541,7 +567,99 @@ export class Supervisor {
             }));
         }
         void this.pumpEvents(running);
-        return true;
+        return { ok: true };
+    }
+    /**
+     * The agent process could not be started at all (ticket #225).
+     *
+     * Three things have to happen here, and until this ticket none of them did:
+     * the reason is said WHERE THE PERSON IS LOOKING (an `error` event is the
+     * feed's red line), the session stops claiming to be working, and the stack
+     * reaches journald for whoever has to fix the machine. The status is the
+     * honest one for a session with no process — the agent is not running, and a
+     * session left in `RUNNING` shows a stop button for a turn that does not
+     * exist.
+     *
+     * Never rethrows: this IS the handling. The caller gets `crashed` and decides
+     * what to do with the message it was holding.
+     */
+    launchCrashed(running, error) {
+        const { descriptor } = running;
+        running.session = null;
+        log.error('supervisor: the agent process could not be started', {
+            sessionId: descriptor.id,
+            agent: descriptor.agent,
+            error: error instanceof Error ? (error.stack ?? error.message) : String(error),
+        });
+        const reason = maskSecretText(error);
+        this.sendEvent(running, 'error', {
+            message: `${AGENT_LABELS[descriptor.agent] ?? descriptor.agent} could not be started on this server: ${reason}`,
+        });
+        // A session that never began is FAILED — the same answer the neighbouring
+        // startup failures (no adapter, no worktree) already give. Everything else
+        // goes back to waiting for a human, which is the state «press Continue» is
+        // meaningful in; REVIEW keeps its row in the dashboard.
+        const status = running.lastReported === 'STARTING'
+            ? 'FAILED'
+            : running.lastReported === 'REVIEW'
+                ? 'REVIEW'
+                : 'WAITING_INPUT';
+        this.reportStatus(descriptor.id, status, {
+            costUsd: running.costUsd,
+            activeMs: running.activeMs,
+            errorMessage: `Agent process failed to start: ${reason}`,
+        });
+        // A FAILED session is over, and an entry left in the map would hold one of
+        // the runner's few slots for a process that never existed — `ensureCapacity`
+        // counts entries, not processes. Dropped exactly like the other startup
+        // failures do it. The parked states keep their entry on purpose: that is
+        // what «Продолжить» picks back up.
+        if (status === 'FAILED')
+            this.sessions.delete(descriptor.id);
+        return { ok: false, reason: 'crashed' };
+    }
+    /** How long a freshly started agent may say nothing before we say so. */
+    static STARTUP_SILENCE_MS = 60_000;
+    /**
+     * Watch for the first word out of a process we just started (ticket #225).
+     *
+     * «The adapter object exists» is not «the agent is running». A CLI that hangs
+     * before its first frame — a stuck hook, an MCP server that never answers, a
+     * transcript it cannot read — produces no events, no error and no exit, and
+     * the session sits in `RUNNING` forever. On a healthy launch the first event
+     * arrives in about two seconds, so a minute of silence is not a slow start,
+     * it is something worth saying out loud.
+     *
+     * Says it and stops there: no kill. A long conversation has the right to boot
+     * slowly, and killing it would cost the person the very turn they are waiting
+     * for.
+     */
+    watchForFirstSignOfLife(running) {
+        this.clearStartupWatch(running);
+        running.heardFromAgent = false;
+        const silentMs = this.opts.startupSilenceMs ?? Supervisor.STARTUP_SILENCE_MS;
+        const timer = setTimeout(() => {
+            delete running.startupTimer;
+            if (running.heardFromAgent || !running.session || this.isStale(running))
+                return;
+            log.warn('supervisor: the agent process has said nothing since it started', {
+                sessionId: running.descriptor.id,
+                silentMs,
+            });
+            this.sendEvent(running, 'notice', {
+                level: 'warn',
+                text: 'The agent process started but has not said a word for a minute. It may still be loading a long conversation. If nothing happens, press «Stop» and then «Continue» — and if that does not help either, this server needs a look.',
+            });
+        }, silentMs);
+        timer.unref?.();
+        running.startupTimer = timer;
+    }
+    /** The process spoke, or went away — either way the watch is over. */
+    clearStartupWatch(running) {
+        if (running.startupTimer) {
+            clearTimeout(running.startupTimer);
+            delete running.startupTimer;
+        }
     }
     /**
      * The project's own prompt file, read fresh for THIS agent process.
@@ -794,6 +912,9 @@ export class Supervisor {
             delete running.activeSince;
         }
         this.clearBudgetTimers(running);
+        // The process this watch was armed for is gone; whatever it did or did not
+        // say, there is nothing left to wait for (ticket #225).
+        this.clearStartupWatch(running);
         // Stale-resume recovery: relaunch once without a resume id.
         if (running.freshRetry && !running.stopRequested) {
             const { prompt } = running.freshRetry;
@@ -851,7 +972,8 @@ export class Supervisor {
             this.sendEvent(running, 'settings', { mode });
             // Empty prompt: the agent boots, reports its capabilities and waits, the
             // same as a free CHAT session. It must NOT start a turn of its own here.
-            if (this.launchAgent(running, '', running.descriptor.providerSessionId)) {
+            const relaunched = this.launchAgent(running, '', running.descriptor.providerSessionId);
+            if (relaunched.ok) {
                 // Anything typed during the park window is waiting on disk (see
                 // `deliverMessage`), and the new process is the one that can take it.
                 this.flushPendingMessages(running);
@@ -863,12 +985,17 @@ export class Supervisor {
                 }
                 return;
             }
-            // The agent did not start — an exhausted budget is the only way here. The
-            // session stays parked and resumable rather than silently disappearing.
-            this.reportStatus(descriptor.id, statusForReport(running), {
-                costUsd: running.costUsd,
-                activeMs: running.activeMs,
-            });
+            // The agent did not start — an exhausted budget, or a launch that crashed
+            // (ticket #225). The session stays parked and resumable rather than
+            // silently disappearing. A crash has already reported its own status and
+            // reason; re-reporting `statusForReport` here would overwrite them with
+            // the state the session was in before it failed.
+            if (relaunched.reason === 'refused') {
+                this.reportStatus(descriptor.id, statusForReport(running), {
+                    costUsd: running.costUsd,
+                    activeMs: running.activeMs,
+                });
+            }
             this.drainSessionsWaitingForCapacity();
             return;
         }
@@ -1153,6 +1280,15 @@ export class Supervisor {
     }
     forwardEvent(running, event) {
         const { descriptor } = running;
+        // Ticket #225: ANY event is the process proving it came up — its own
+        // capabilities probe answers within about two seconds of a healthy launch,
+        // long before the agent says anything a person would read. That is a
+        // deliberately weaker bar than «the agent is working» below: what this
+        // watch is for is a CLI that never boots at all.
+        if (!running.heardFromAgent) {
+            running.heardFromAgent = true;
+            this.clearStartupWatch(running);
+        }
         // Anything below that is the agent talking means the agent is working. Read
         // before the switch so every such case gets it, including the ones added
         // after this line was written.
@@ -1724,11 +1860,13 @@ export class Supervisor {
         // A person typing into the session is the clearest signal that the work is
         // back on track, so the automatic-continuation allowance starts over.
         clearAutoResume(running.descriptor.id);
-        if (this.launchAgent(running, text, running.descriptor.providerSessionId)) {
+        if (this.launchAgent(running, text, running.descriptor.providerSessionId).ok) {
             settle();
             return;
         }
-        // The agent did not start (an exhausted budget is the only way here). The
+        // The agent did not start (an exhausted budget, or a launch that crashed —
+        // ticket #225: it used to be swallowed into a log line, and the words the
+        // person typed were retired from disk as though an agent had them). The
         // instruction stays on disk, so «Продолжить» — which is what raises the
         // budget — carries it to the agent instead of dropping it.
         this.requeue(running, held, text, originSeq);
@@ -2167,210 +2305,263 @@ export class Supervisor {
             }
         }
         // Redeliver unacked events for every persisted journal (at-least-once).
+        //
+        // Per file, because one that cannot be read must not cost the whole
+        // reconnect (ticket #225): this runs BEFORE a single session is looked at,
+        // so a throw here means nothing is restored at all — no launch, no status,
+        // no note, on every reconnect for as long as the file stays broken.
         for (const sessionId of this.journals.persistedSessionIds()) {
-            const journal = this.journals.open(sessionId);
-            for (const event of journal.unacked()) {
-                this.ws.send({
-                    type: 'event',
+            try {
+                const journal = this.journals.open(sessionId);
+                for (const event of journal.unacked()) {
+                    this.ws.send({
+                        type: 'event',
+                        sessionId,
+                        seq: event.seq,
+                        eventType: event.eventType,
+                        payload: event.payload,
+                    });
+                }
+            }
+            catch (error) {
+                log.error('supervisor: journal could not be replayed', {
                     sessionId,
-                    seq: event.seq,
-                    eventType: event.eventType,
-                    payload: event.payload,
+                    error: String(error),
                 });
             }
         }
         for (const descriptor of descriptors) {
-            // 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);
-            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:
-                // the API drops frames stamped with an older one, so keeping ours would
-                // make every status this session ever sends invisible — it would sit in
-                // "waiting" while the agent worked.
-                if (descriptor.epoch > tracked.epoch) {
-                    tracked.epoch = descriptor.epoch;
-                    tracked.descriptor = { ...tracked.descriptor, epoch: descriptor.epoch };
-                }
-                // Ticket #196, QA-149 MAJOR-1. The pause is re-established HERE, and
-                // this is the case that matters most: a dropped socket leaves the agent
-                // process running, so «reconnect» is precisely when a session is
-                // `tracked`. The first cut of #196 read `pausedUntil` only in the two
-                // constructors of a NEW `RunningSession`, which meant it survived a
-                // runner RESTART and not a reconnect — and a pause set while the socket
-                // was down never arrived at all, because `session_pause` is
-                // fire-and-forget with no outbox behind it.
-                //
-                // Both directions matter: the row may have gained a clock (hold now) or
-                // lost one (release and send what was held). `applyPause` does both, and
-                // it runs BEFORE `flushSessionOutbox` arrives from the API side.
-                await this.applyPause(descriptor.id, descriptor.pausedUntil ?? null);
-                this.reportStatus(descriptor.id, statusForReport(tracked), {
-                    costUsd: tracked.costUsd,
-                    ...(tracked.branch ? { branch: tracked.branch } : {}),
-                    ...(tracked.worktreePath ? { worktreePath: tracked.worktreePath } : {}),
-                    ...(tracked.descriptor.providerSessionId
-                        ? { providerSessionId: tracked.descriptor.providerSessionId }
-                        : {}),
-                });
-                continue;
-            }
-            // 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);
+            // One session must never cost the others their restore (ticket #225).
+            // Everything below runs per descriptor, and until this guard existed a
+            // single throw — a launch that could not start, a worktree that moved —
+            // left the loop entirely: every session AFTER the failing one stayed
+            // unrestored, on every reconnect, with nothing said anywhere. The blast
+            // radius of a broken session is now that session.
+            try {
+                // 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);
+                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:
+                    // the API drops frames stamped with an older one, so keeping ours would
+                    // make every status this session ever sends invisible — it would sit in
+                    // "waiting" while the agent worked.
+                    if (descriptor.epoch > tracked.epoch) {
+                        tracked.epoch = descriptor.epoch;
+                        tracked.descriptor = { ...tracked.descriptor, epoch: descriptor.epoch };
                     }
+                    // Ticket #196, QA-149 MAJOR-1. The pause is re-established HERE, and
+                    // this is the case that matters most: a dropped socket leaves the agent
+                    // process running, so «reconnect» is precisely when a session is
+                    // `tracked`. The first cut of #196 read `pausedUntil` only in the two
+                    // constructors of a NEW `RunningSession`, which meant it survived a
+                    // runner RESTART and not a reconnect — and a pause set while the socket
+                    // was down never arrived at all, because `session_pause` is
+                    // fire-and-forget with no outbox behind it.
+                    //
+                    // Both directions matter: the row may have gained a clock (hold now) or
+                    // lost one (release and send what was held). `applyPause` does both, and
+                    // it runs BEFORE `flushSessionOutbox` arrives from the API side.
+                    await this.applyPause(descriptor.id, descriptor.pausedUntil ?? null);
+                    this.reportStatus(descriptor.id, statusForReport(tracked), {
+                        costUsd: tracked.costUsd,
+                        ...(tracked.branch ? { branch: tracked.branch } : {}),
+                        ...(tracked.worktreePath ? { worktreePath: tracked.worktreePath } : {}),
+                        ...(tracked.descriptor.providerSessionId
+                            ? { providerSessionId: tracked.descriptor.providerSessionId }
+                            : {}),
+                    });
                     continue;
                 }
-            }
-            if (descriptor.status === 'STARTING') {
-                await this.startSession(descriptor);
-            }
-            else if (descriptor.providerSessionId) {
-                // 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,
-                    stopRequested: false,
-                    parkRequested: false,
-                    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(),
-                    answeredAsks: new Set(),
-                    ...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);
-                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;
+                // 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;
+                    }
                 }
-                catch (error) {
-                    this.reportStatus(descriptor.id, 'FAILED', {
-                        errorMessage: `Failed to restore session worktree: ${String(error instanceof Error ? error.message : error).slice(0, 500)}`,
-                    });
-                    this.sessions.delete(descriptor.id);
-                    continue;
+                if (descriptor.status === 'STARTING') {
+                    await this.startSession(descriptor);
                 }
-                /**
-                 * 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`).
-                    if (this.launchAgent(running, AUTO_RESUME_PROMPT, resumeId)) {
-                        this.reportStatus(descriptor.id, 'RUNNING', {});
-                        this.flushPendingMessages(running);
+                else if (descriptor.providerSessionId) {
+                    // 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,
+                        stopRequested: false,
+                        parkRequested: false,
+                        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(),
+                        answeredAsks: new Set(),
+                        ...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);
+                    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) {
+                        this.reportStatus(descriptor.id, 'FAILED', {
+                            errorMessage: `Failed to restore session worktree: ${String(error instanceof Error ? error.message : error).slice(0, 500)}`,
+                        });
+                        this.sessions.delete(descriptor.id);
                         continue;
                     }
-                    // Could not start (an exhausted budget is the only way here). Fall
-                    // through to the old behaviour and say so honestly.
+                    /**
+                     * 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: 'Could not continue automatically — send a message to pick the work back up.',
+                        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);
+                            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".
+                    if (descriptor.status !== 'REVIEW') {
+                        this.reportStatus(descriptor.id, 'WAITING_INPUT', {});
+                    }
+                    this.flushPendingMessages(running);
                 }
-                // REVIEW stays REVIEW (WAITING_INPUT is not reachable from it);
-                // mid-turn statuses are downgraded to "waiting for the user".
-                if (descriptor.status !== 'REVIEW') {
-                    this.reportStatus(descriptor.id, 'WAITING_INPUT', {});
+                else if (descriptor.status === 'WAITING_INPUT') {
+                    // 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: '' });
+                }
+                else {
+                    this.reportStatus(descriptor.id, 'FAILED', {
+                        errorMessage: 'Runner restarted and this session cannot be resumed',
+                    });
                 }
-                this.flushPendingMessages(running);
-            }
-            else if (descriptor.status === 'WAITING_INPUT') {
-                // 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: '' });
             }
-            else {
-                this.reportStatus(descriptor.id, 'FAILED', {
-                    errorMessage: 'Runner restarted and this session cannot be resumed',
+            catch (error) {
+                log.error('supervisor: session could not be restored after reconnect', {
+                    sessionId: descriptor.id,
+                    error: error instanceof Error ? (error.stack ?? error.message) : String(error),
                 });
+                // Said on the session it belongs to, not only in journald. FAILED is
+                // the honest word: this runner is not going to run it as things stand,
+                // and «Продолжить» is what asks it to try again.
+                //
+                // Guarded in turn, and not out of superstition: reporting a status
+                // WRITES to that session's journal, so the most likely reason the body
+                // above failed — this session's own file — would fail the handler the
+                // same way and take the loop with it after all. The other sessions
+                // matter more than this one's status frame.
+                try {
+                    this.reportStatus(descriptor.id, 'FAILED', {
+                        errorMessage: `Runner could not restore this session: ${maskSecretText(error)}`,
+                    });
+                }
+                catch (reportError) {
+                    log.error('supervisor: could not even report the failed restore', {
+                        sessionId: descriptor.id,
+                        error: String(reportError),
+                    });
+                }
             }
         }
         // Redelivery is done — anything still on disk from long-finished sessions