@bridge4dev/runner 0.37.0 → 0.38.0

package/dist/agent-binary.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The platform packages the SDK will look for, in its own order (`sdk.mjs`).
+ *
+ * BOTH linux variants are accepted rather than detecting musl the way the SDK
+ * does: the question here is «did the optional package get installed at all»,
+ * and answering it must never be the thing that blocks an update. A glibc
+ * binary on a musl host is a different failure — and since #225 it announces
+ * itself in the session feed instead of hiding.
+ */
+export declare function nativeCandidates(platform?: NodeJS.Platform, arch?: string): string[];
+/**
+ * Absolute path to the Claude CLI inside an installed runner package, or null.
+ *
+ * Resolved from the SDK's own file, exactly like the SDK resolves it — npm may
+ * hoist the platform package next to the SDK, next to the runner, or several
+ * levels up, and only the module resolver knows which happened here.
+ */
+export declare function findClaudeCli(packageDir: string): string | null;
+/**
+ * The same question about THIS process's own installation.
+ *
+ * Goes through the SDK's entry point rather than a path guess, so it answers
+ * correctly in every layout the runner runs in — a global npm install, a
+ * dedicated-user prefix, and the pnpm store of a source checkout, where the
+ * platform package is reachable from the SDK and from nowhere else.
+ */
+export declare function claudeCliPath(): string | null;
+//# sourceMappingURL=agent-binary.d.ts.map

package/dist/agent-binary.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/**
+ * Is the binary this runner would actually launch Claude with present?
+ *
+ * Not a hypothetical check (ticket #225, гоча #297). The Claude CLI does not
+ * live in this package: `@anthropic-ai/claude-agent-sdk` keeps it in a ~300 MB
+ * **optional** platform package, one per platform+arch. For npm the failure of
+ * an optional dependency is not an error — `npm install -g` exits 0, the runner
+ * reports a successful update and restarts into a build that cannot start a
+ * single Claude session. That is exactly what happened to transitway-dev-01 on
+ * 2026-08-11: every launch threw
+ * `Native CLI binary for linux-x64 not found` synchronously, before any event
+ * could be emitted, and a live session went silent for an hour and a half.
+ *
+ * The runner's own smoke test could not catch it: `devbridge-runner --version`
+ * loads the module graph, and the SDK resolves the platform binary lazily — on
+ * the first `query()`, which is a session, not a startup.
+ */
+const SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk';
+/**
+ * The platform packages the SDK will look for, in its own order (`sdk.mjs`).
+ *
+ * BOTH linux variants are accepted rather than detecting musl the way the SDK
+ * does: the question here is «did the optional package get installed at all»,
+ * and answering it must never be the thing that blocks an update. A glibc
+ * binary on a musl host is a different failure — and since #225 it announces
+ * itself in the session feed instead of hiding.
+ */
+export function nativeCandidates(platform = process.platform, arch = process.arch) {
+    const exe = platform === 'win32' ? 'claude.exe' : 'claude';
+    const packages = platform === 'android'
+        ? [`${SDK_PACKAGE}-linux-${arch}-android`]
+        : platform === 'linux'
+            ? [`${SDK_PACKAGE}-linux-${arch}`, `${SDK_PACKAGE}-linux-${arch}-musl`]
+            : [`${SDK_PACKAGE}-${platform}-${arch}`];
+    return packages.map((name) => `${name}/${exe}`);
+}
+/**
+ * Absolute path to the Claude CLI inside an installed runner package, or null.
+ *
+ * Resolved from the SDK's own file, exactly like the SDK resolves it — npm may
+ * hoist the platform package next to the SDK, next to the runner, or several
+ * levels up, and only the module resolver knows which happened here.
+ */
+export function findClaudeCli(packageDir) {
+    const found = resolveFromSdkEntry(path.join(packageDir, 'node_modules', SDK_PACKAGE, 'sdk.mjs'));
+    // Inside THIS installation, or it does not count. Node's resolver walks up the
+    // directory tree and consults the global folders, so a package that is absent
+    // from the build we just installed can still be found in the one we are about
+    // to retire — and answering «present» from there is exactly the false green
+    // this check exists to prevent. A global npm install keeps its dependencies
+    // under its own package directory, so containment is also simply true.
+    return found && isInside(packageDir, found) ? found : null;
+}
+function isInside(dir, file) {
+    const relative = path.relative(path.resolve(dir), path.resolve(file));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+/**
+ * The same question about THIS process's own installation.
+ *
+ * Goes through the SDK's entry point rather than a path guess, so it answers
+ * correctly in every layout the runner runs in — a global npm install, a
+ * dedicated-user prefix, and the pnpm store of a source checkout, where the
+ * platform package is reachable from the SDK and from nowhere else.
+ */
+export function claudeCliPath() {
+    let sdkEntry;
+    try {
+        sdkEntry = createRequire(import.meta.url).resolve(SDK_PACKAGE);
+    }
+    catch {
+        return null;
+    }
+    return resolveFromSdkEntry(sdkEntry);
+}
+function resolveFromSdkEntry(sdkEntry) {
+    let resolve;
+    try {
+        resolve = createRequire(sdkEntry).resolve;
+    }
+    catch {
+        return null;
+    }
+    for (const candidate of nativeCandidates()) {
+        try {
+            const resolved = resolve(candidate);
+            if (fs.existsSync(resolved))
+                return resolved;
+        }
+        catch {
+            // Not installed under this name — try the next candidate.
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=agent-binary.js.map

package/dist/index.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { ClaudeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
+import { claudeCliPath } from './agent-binary.js';
 import { loadConfig, requireConfig, saveConfig } from './config.js';
 import { log } from './log.js';
 import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
@@ -62,8 +63,14 @@ function argValue(args, flag) {
  */
 function installedAgents() {
     const agents = [];
-    // Claude is bundled inside the Agent SDK, so it is always available.
-    agents.push('claude');
+    // Claude comes with the Agent SDK — but «comes with» is a claim about THIS
+    // installation, not a law (ticket #225). The CLI is an optional platform
+    // package, and an update that silently lost it leaves a runner that reports
+    // Claude, accepts Claude sessions, and cannot start a single one. Reported as
+    // measured, so the dashboard greys the agent out instead of offering a
+    // session that dies before its first word.
+    if (claudeCliPath())
+        agents.push('claude');
     if (hasExecutable('codex'))
         agents.push('codex');
     return agents;

package/dist/self-update.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { findClaudeCli } from './agent-binary.js';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
@@ -235,10 +236,19 @@ function installArgs(source, prefix) {
     // a directory the daemon cannot write — and, on the rarer host where it can,
     // npm cheerfully installs a SECOND copy somewhere the service does not exec,
     // reports success, and the runner restarts on the old version forever.
+    //
+    // `--include=optional` is npm's default and is stated anyway (ticket #225):
+    // the Claude CLI ships as an OPTIONAL platform package, and a single
+    // `omit=optional` inherited from an `.npmrc`, an environment variable or a CI
+    // habit turns an update into a runner that cannot start a single Claude
+    // session — silently, because for npm a failed optional dependency is not a
+    // failure at all. The flag makes this deployment's intent explicit rather
+    // than dependent on whatever configuration the machine happens to carry.
     return [
         'install',
         '-g',
         '--ignore-scripts',
+        '--include=optional',
         '--loglevel=error',
         ...(prefix ? ['--prefix', prefix] : []),
         source,
@@ -259,7 +269,7 @@ export function manualUpdateCommand(tarballUrl, options = {}) {
     const prefix = options.prefix === undefined ? installPrefixFor(packageDir) : options.prefix;
     const user = options.user ?? os.userInfo().username;
     const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : -1);
-    const install = ['npm install -g --ignore-scripts --loglevel=error']
+    const install = ['npm install -g --ignore-scripts --include=optional --loglevel=error']
         .concat(prefix ? [`--prefix ${prefix}`] : [])
         .concat([tarballUrl])
         .join(' ');
@@ -420,6 +430,44 @@ export async function selfUpdate(options) {
                 `Restore it on the server with: npm install -g${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
+    // The binary the sessions will actually be started with (ticket #225).
+    //
+    // The probe above is not enough and 2026-08-11 proved it: `--version` loads
+    // the module graph, but the SDK resolves the Claude CLI lazily — on the first
+    // `query()`, i.e. inside a session, long after this update reported success.
+    // A missing OPTIONAL platform package therefore sailed through every check
+    // here, the daemon restarted, and the machine spent an hour and a half
+    // answering «продолжай» with nothing.
+    //
+    // One repair attempt first, because that is what the failure usually deserves:
+    // a 300 MB optional package that did not download is a network hiccup, not a
+    // broken release, and reinstalling it is cheaper for the user than a rollback.
+    if (!findClaudeCli(newPackageDir)) {
+        log.warn('self-update: the Claude CLI is missing from the new build — repairing', {
+            packageDir: newPackageDir,
+        });
+        try {
+            await installGlobal(exec, options.tarballUrl, prefix);
+        }
+        catch (error) {
+            log.warn('self-update: the repair install failed', { error: describe(error) });
+        }
+    }
+    if (!findClaudeCli(newPackageDir)) {
+        log.error('self-update: still no Claude CLI after the repair — rolling back', {
+            packageDir: newPackageDir,
+        });
+        const detail = 'the Claude CLI (an optional platform package of @anthropic-ai/claude-agent-sdk) did not install, ' +
+            'so no Claude session could have started on this build';
+        try {
+            await installGlobal(exec, rollbackTarball, prefix);
+            return fail(`The new version was not activated (${detail}). The previous version was restored and the runner keeps working.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+        catch (rollbackError) {
+            return fail(`The new version is broken (${detail}) and the rollback failed too (${describe(rollbackError)}). ` +
+                `Restore it on the server with: npm install -g --include=optional${prefix ? ` --prefix ${prefix}` : ''} ${rollbackTarball}`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
+        }
+    }
     // The service unit may be pinned to a file inside the directory this update
     // just replaced — early versions wrote the resolved script path, and a package
     // rename moves it. Then the restart we are about to ask for would fail with

package/dist/supervisor.d.ts

@@ -19,6 +19,12 @@ export interface SupervisorOptions {
     runnerToken?: string;
     /** Test seam for the `self_update` command. */
     selfUpdate?: typeof selfUpdate;
+    /**
+     * How long a freshly started agent process may say nothing before the session
+     * says so out loud (ticket #225). Test seam — the default is a minute, and a
+     * test that had to wait one would not be written.
+     */
+    startupSilenceMs?: number;
     /**
      * Called after a successful update, once the reply is on the wire. The daemon
      * exits here and systemd starts the new build; without a handler the runner
@@ -113,11 +119,53 @@ export declare 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.
      */
     private launchAgent;
+    /**
+     * 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.
+     */
+    private launchCrashed;
+    /** How long a freshly started agent may say nothing before we say so. */
+    private static readonly STARTUP_SILENCE_MS;
+    /**
+     * 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.
+     */
+    private watchForFirstSignOfLife;
+    /** The process spoke, or went away — either way the watch is over. */
+    private clearStartupWatch;
     /**
      * The project's own prompt file, read fresh for THIS agent process.
      *

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.37.0";
+export declare const RUNNER_VERSION = "0.38.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.37.0';
+export const RUNNER_VERSION = '0.38.0';
 //# sourceMappingURL=version.js.map

package/dist/ws-client.d.ts

@@ -1,4 +1,32 @@
 import { type GatewayFrame, type RunnerFrame } from './protocol.js';
+/**
+ * Mirror of `RUNNER_LIVENESS_*` in `@devbridge/shared` — the DevBridge side is the
+ * source of truth, exactly like `protocol.ts` mirrors the API's wire types.
+ * Copied rather than imported because this package is published to npm on its own
+ * (see the note in `recipe-schema.ts`).
+ *
+ * No inbound traffic for this long means the path is half-dead even though the
+ * socket still looks OPEN (QA-96 F16). The threshold has to stay comfortably
+ * BELOW the gateway's own budget (`RUNNER_GATEWAY_BUDGET_MS`, 60 s): a re-connect
+ * that lands before the gateway gives up is free — it replaces the old socket and
+ * the machine never leaves ONLINE — while one that lands after costs the user a
+ * «server is offline» banner over a working machine (QA-162 F2).
+ *
+ * It used to say «the gateway pings every 30s» and wait 90 s. The gateway has
+ * pinged every 15 s since devreport #117, so that 90 s had quietly become six
+ * missed pings instead of the three it was written for, and the runner sat blind
+ * for 90–120 s on every drop. Both ends now read one set of numbers.
+ */
+export declare const LIVENESS_TIMEOUT_MS = 35000;
+export declare const LIVENESS_CHECK_MS = 5000;
+/** Kept in step with `RUNNER_GATEWAY_BUDGET_MS`; asserted by `ws-liveness.test.ts`. */
+export declare const GATEWAY_BUDGET_MS = 60000;
+/**
+ * Worst-case cost of acting on the threshold: the check granularity, the first
+ * backoff step with its jitter, and a TLS+upgrade handshake. The invariant test
+ * uses it, because «the runner re-dials first» is only true with this included.
+ */
+export declare const RECONNECT_COST_MS: number;
 export interface WsClientEvents {
     frame: (frame: GatewayFrame) => void;
     open: () => void;

package/dist/ws-client.js

@@ -9,10 +9,34 @@ import { RUNNER_VERSION } from './version.js';
 const BACKOFF_BASE_MS = 1_000;
 const BACKOFF_MAX_MS = 60_000;
 const REPLACED_COOLDOWN_MS = 60_000;
-// The gateway pings every 30s; no inbound traffic for 90s means the path is
-// half-dead even though the socket looks OPEN (QA-96 F16).
-const LIVENESS_TIMEOUT_MS = 90_000;
-const LIVENESS_CHECK_MS = 30_000;
+/**
+ * Mirror of `RUNNER_LIVENESS_*` in `@devbridge/shared` — the DevBridge side is the
+ * source of truth, exactly like `protocol.ts` mirrors the API's wire types.
+ * Copied rather than imported because this package is published to npm on its own
+ * (see the note in `recipe-schema.ts`).
+ *
+ * No inbound traffic for this long means the path is half-dead even though the
+ * socket still looks OPEN (QA-96 F16). The threshold has to stay comfortably
+ * BELOW the gateway's own budget (`RUNNER_GATEWAY_BUDGET_MS`, 60 s): a re-connect
+ * that lands before the gateway gives up is free — it replaces the old socket and
+ * the machine never leaves ONLINE — while one that lands after costs the user a
+ * «server is offline» banner over a working machine (QA-162 F2).
+ *
+ * It used to say «the gateway pings every 30s» and wait 90 s. The gateway has
+ * pinged every 15 s since devreport #117, so that 90 s had quietly become six
+ * missed pings instead of the three it was written for, and the runner sat blind
+ * for 90–120 s on every drop. Both ends now read one set of numbers.
+ */
+export const LIVENESS_TIMEOUT_MS = 35_000;
+export const LIVENESS_CHECK_MS = 5_000;
+/** Kept in step with `RUNNER_GATEWAY_BUDGET_MS`; asserted by `ws-liveness.test.ts`. */
+export const GATEWAY_BUDGET_MS = 60_000;
+/**
+ * Worst-case cost of acting on the threshold: the check granularity, the first
+ * backoff step with its jitter, and a TLS+upgrade handshake. The invariant test
+ * uses it, because «the runner re-dials first» is only true with this included.
+ */
+export const RECONNECT_COST_MS = LIVENESS_CHECK_MS + BACKOFF_BASE_MS + 1_000 + 2_000;
 // Repeated HTTP 401/403 on the upgrade = bad token; slow way down.
 const AUTH_FAILURE_THRESHOLD = 5;
 const AUTH_FAILURE_COOLDOWN_MS = 10 * 60_000;
@@ -86,12 +110,17 @@ export class RunnerWsClient {
         if (this.stopped)
             return;
         log.info('ws: connecting', { url: this.wsUrl, attempt: this.attempts + 1 });
+        const dialedAt = Date.now();
         const socket = new WebSocket(this.wsUrl, {
             headers: { Authorization: `Bearer ${this.token}` },
             handshakeTimeout: 15_000,
         });
         this.socket = socket;
         socket.on('open', () => {
+            // Success used to be the only outcome that logged NOTHING, so «connected»
+            // and «hung mid-handshake» read identically in the journal — which is
+            // exactly where an hour went during QA-162. One line ends that.
+            log.info('ws: connected', { attempts: this.attempts + 1, elapsedMs: Date.now() - dialedAt });
             this.attempts = 0;
             this.authFailures = 0;
             this.lastInboundAt = Date.now();

package/package.json

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