@bridge4dev/runner 0.58.2 → 0.60.0

package/dist/adapters/claude.js

@@ -11,7 +11,7 @@ import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
 import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
 import { applyUsagePercentages, lastUsageRows, readUsageRows } from './claude-usage.js';
-import { claudeExecutableOption, sessionClaudePath } from '../agent-binary.js';
+import { assertClaudeInstalled, claudeExecutableOption, sessionClaudePath, } from '../agent-binary.js';
 /** Same 2KB the SDK keeps: enough for the CLI's last words, not a log sink. */
 const STDERR_TAIL_LIMIT = 2048;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
@@ -340,10 +340,21 @@ class ClaudeSession {
      * has no such field. Without stashing it, the supervisor would be left with a
      * sentence — and a decision made from a sentence can be made by prose (#252).
      *
-     * Reset per turn in `endTaskTurn`, which already owns the turn epoch.
+     * Reset when a turn BEGINS — `beginTurnFacts`, reached from `resumingTurn`
+     * for every turn this runner starts and from the boundary guard in the read
+     * loop for one the CLI started by itself (#406). The docblock used to say
+     * `endTaskTurn` owns the epoch; it never has, and reading it that way is what
+     * made «a code from this turn» and «a code from some turn» look identical.
      */
     turnFailureCode = null;
     turnFailureStatus = null;
+    /**
+     * A `result` has gone out and no new message has arrived since (#406).
+     *
+     * The marker the read loop uses to tell a turn the CLI opened by itself from
+     * a second `result` for the turn that just ended.
+     */
+    turnClosed = false;
     /**
      * Did this turn put ANYTHING on the wire — text, thinking, or a tool call?
      *
@@ -1798,10 +1809,17 @@ class ClaudeSession {
         // as work. The id is forgotten when that task settles instead, which is the
         // moment it stops being able to come back.
         this.turnEpoch += 1;
-        // Straight through `flushTasks` rather than an empty frame of its own: the
-        // counters changed, so the fingerprint differs and it will publish — and
-        // what it publishes is the truth about what is still running.
+        // Straight through `flushTasks` rather than an empty frame of its own, and
+        // with the de-duplication disarmed for this one frame (plan
+        // `workflow-mode-fixes` S1 p.10). The turn's counters usually changed, but
+        // not always: a task started in an earlier turn and still running, and a
+        // turn that started nothing new, produce exactly the frame the last turn
+        // ended on — and the end of a turn is the moment the API and the tray most
+        // need to hear what is still running, whether or not it is news. The
+        // supervisor de-duplicates the COUNT on its own side; this frame is the
+        // tray's freshness, not the database's.
         this.taskPublishedAt = 0;
+        this.lastTaskFingerprint = '';
         this.flushTasks();
     }
     /**
@@ -2219,6 +2237,25 @@ class ClaudeSession {
     async consume() {
         try {
             for await (const msg of this.q) {
+                /**
+                 * A turn the CLI started by itself begins here (#406).
+                 *
+                 * `beginTurnFacts` has exactly one other caller, `resumingTurn`, and it
+                 * covers every turn THIS runner opens. The CLI opens turns too — a
+                 * background subagent finishing wakes one, and its `result` carries
+                 * `origin.kind: 'task-notification'` — and those used to inherit the
+                 * previous turn's `turnFailureCode`, `turnProduced` and
+                 * `turnIrreversible`, which is how a long-healed stream cut could still
+                 * be the reason attached to a turn an hour later.
+                 *
+                 * The guard is «a message that is not another `result`», not «the turn
+                 * ended»: one Stop can produce two results (see the stop-cycle tests),
+                 * and the second one has to see the same facts as the first.
+                 */
+                if (this.turnClosed && msg.type !== 'result') {
+                    this.turnClosed = false;
+                    this.beginTurnFacts();
+                }
                 // Ticket #126: where we are in the transcript, remembered BEFORE the
                 // message is interpreted.
                 //
@@ -2419,7 +2456,50 @@ class ClaudeSession {
                         // once, for exactly one result.
                         const aborted = this.aborting;
                         this.aborting = false;
-                        const failure = msg.subtype === 'success' ? '' : classifyError(msg.subtype, msg.errors);
+                        /**
+                         * The CLI's own word for why it stopped — and the one signal that
+                         * it gave up (#406).
+                         *
+                         * `subtype` alone is not that signal: on 12.09.2026 Claude Code
+                         * wrote «API Error: Connection lost mid-response», ended the turn,
+                         * and stamped the result `subtype: "success"` with
+                         * `terminal_reason: "api_error"` beside it. The runner read the
+                         * first field, reported a clean turn, and the session stood for
+                         * 5 h 17 min with «your turn» on it.
+                         *
+                         * Deliberately NOT the accumulated `turnFailureCode`: Claude Code
+                         * survives most stream cuts by itself, and a code left over from
+                         * one it survived would fail three healthy turns an hour (the
+                         * correction on §492, ticket #406's second comment).
+                         */
+                        const terminalReason = typeof msg.terminal_reason === 'string'
+                            ? msg.terminal_reason
+                            : null;
+                        /**
+                         * The other half of the turn boundary above (#406).
+                         *
+                         * The guard in the read loop forgets the last turn on the first
+                         * message that is not a `result` — which a turn the CLI woke and
+                         * that said NOTHING never sends. Its only message is its own
+                         * closing `result`, and `origin.kind` is the field the SDK marks it
+                         * with; #373 already treats that field as the one thing that tells a
+                         * genuinely new internal turn from a second ending of the last one.
+                         * Without this, a silent internal turn would report the `produced`
+                         * and `irreversible` of whatever ran before it.
+                         */
+                        const originKind = typeof msg.origin?.kind === 'string'
+                            ? msg.origin.kind
+                            : null;
+                        if (this.turnClosed && originKind === 'task-notification') {
+                            this.turnClosed = false;
+                            this.beginTurnFacts();
+                        }
+                        const gaveUp = msg.subtype === 'success' && terminalReason === 'api_error';
+                        const failure = gaveUp
+                            ? API_ERROR_TURN_MESSAGE
+                            : msg.subtype === 'success'
+                                ? ''
+                                : classifyError(msg.subtype, msg.errors);
                         // #373, plan stage D. What the incident could not answer: the second
                         // result's origin was never recorded, so «is this the same turn
                         // twice or a turn the CLI started by itself» had no evidence either
@@ -2445,10 +2525,13 @@ class ClaudeSession {
                                 code: 'rewind_failed',
                             });
                         }
-                        else if (msg.subtype === 'success' || aborted) {
-                            // A turn the user stopped is not a failed turn. Reporting it as
-                            // one moved the session to FAILED, which is terminal — pressing
-                            // Stop cost people the session they meant to keep.
+                        else if (aborted || (msg.subtype === 'success' && !gaveUp)) {
+                            // `aborted` is tested FIRST, and stays ahead of `gaveUp`: a turn
+                            // the user stopped is not a failed turn whatever the CLI writes
+                            // beside it, and an abort can land on top of an API error.
+                            // Reporting a stop as a failure moved the session to FAILED,
+                            // which is terminal — pressing Stop cost people the session they
+                            // meant to keep.
                             this.emit({
                                 type: 'turn_end',
                                 ok: true,
@@ -2480,7 +2563,17 @@ class ClaudeSession {
                                 // the closed enum rides on the assistant message, this `result`
                                 // has no such field. Handed over so the supervisor can decide
                                 // from a code rather than from the sentence in `errorMessage`.
-                                ...(this.turnFailureCode !== null ? { failureCode: this.turnFailureCode } : {}),
+                                //
+                                // #406: a turn the CLI gave up on always carries a code, even
+                                // when nothing in it named one — `server_error` is what «their
+                                // side, try again» is spelled as, and without it `classifyFailure`
+                                // would have only the sentence to go on, which is the thing #252
+                                // took away from it.
+                                ...(this.turnFailureCode !== null
+                                    ? { failureCode: this.turnFailureCode }
+                                    : gaveUp
+                                        ? { failureCode: 'server_error' }
+                                        : {}),
                                 ...(this.turnFailureStatus !== null
                                     ? { failureStatus: this.turnFailureStatus }
                                     : {}),
@@ -2489,6 +2582,11 @@ class ClaudeSession {
                             });
                             this.refreshUsage();
                         }
+                        // #406: the facts above have been reported, so the next message —
+                        // whoever starts the turn it belongs to — may forget them. Armed
+                        // here rather than cleared here, because a second `result` for this
+                        // same ending has to read exactly what the first one did.
+                        this.turnClosed = true;
                         break;
                     }
                     default:
@@ -2664,6 +2762,15 @@ function stringifyContent(content) {
     }
     return content === undefined ? '' : JSON.stringify(content);
 }
+/**
+ * What the feed says about a turn Claude Code gave up on (#406).
+ *
+ * Deliberately free of «mid-response» and «may be incomplete»: `refine()` in
+ * `error-policy.ts` matches those two phrases and narrows a retry to a single
+ * «carry on» attempt. Here the narrowing must come from `produced`, which is a
+ * fact about the turn, and not from the wording of a sentence.
+ */
+const API_ERROR_TURN_MESSAGE = 'The connection to the model failed and Claude Code ended the turn on an API error';
 function classifyError(subtype, errors) {
     // Optional on purpose despite the SDK's type: a `result` without `errors`
     // threw from inside the event pump, which the loop's catch turned into a
@@ -2738,6 +2845,23 @@ export class ClaudeAdapter {
         this.queryFn = queryFn;
     }
     startSession(spec) {
+        /**
+         * «There is no Claude here» is answered once, and here (#395).
+         *
+         * BEFORE the session object exists, and that placement is the point: the
+         * constructor writes the MCP config — a 0600 file holding this workspace's
+         * live key — before it builds `Options`, and nothing removes that file for
+         * a constructor that threw. The supervisor turns this throw into one red
+         * line in the feed (`launchCrashed`) and a FAILED session, which is the
+         * honest answer when the agent is not on the machine.
+         *
+         * Only for the real SDK. An adapter built on an injected `query` is a test
+         * or a probe: it spawns nothing, so the fallback this guards against cannot
+         * happen — and asking anyway would fail the whole suite on every machine
+         * without the CLI, CI included. That is how the 0.56.0 release broke.
+         */
+        if (this.queryFn === query)
+            assertClaudeInstalled();
         return new ClaudeSession(spec, this.queryFn);
     }
 }

package/dist/agent-binary.d.ts

@@ -62,13 +62,54 @@ export declare const USE_BUNDLED_CLAUDE = false;
  * the tests also need the real behaviour of; production always takes the default.
  */
 export declare function sessionClaudePath(useBundled?: boolean): string | null;
+/**
+ * What every caller says when Claude Code is not on this machine (#395).
+ *
+ * Word for word the API's own refusal (`assertAgentAvailable` in
+ * `dev-sessions.service.ts`): the two halves answer the same question about the
+ * same binary, and a person who meets both — the API when it can see the
+ * measurement, this one when it cannot — should not have to work out whether
+ * they are being told two different things.
+ */
+export declare const CLAUDE_NOT_INSTALLED = "Claude Code is not installed on this server \u2014 install it there, or pick another agent";
+/** Thrown where a run would otherwise start on a binary nobody chose. */
+export declare class ClaudeNotInstalledError extends Error {
+    constructor();
+}
+/**
+ * Refuse, in words, when a real Claude run has nothing legitimate to start.
+ *
+ * ## The hole this closes (#395, decision D14)
+ *
+ * With the bundled binary switched off and no system `claude`,
+ * `claudeExecutableOption` has nothing to pin and returns `{}`. To the SDK an
+ * absent `pathToClaudeCodeExecutable` does not mean «there is no Claude» — it
+ * means «resolve your own». So the machine either ran sessions on a SECOND
+ * Claude of a different version while its card said «not installed» (five
+ * sessions on `vmi3024903`, one of them $93), or — on a machine installed the
+ * standard way, where `--omit=optional` means the bundled package is not there
+ * at all — died inside the SDK with `Native CLI binary for linux-x64 not found`
+ * before its first word.
+ *
+ * ## Why it is a separate call and not a throw from `claudeExecutableOption`
+ *
+ * Both places that build `Options` do so eagerly, including in tests, where the
+ * SDK is replaced by a fake `query` and no binary is ever spawned. A throw from
+ * the option builder would therefore fail the whole suite on any machine
+ * without the CLI — CI among them, which is exactly how the 0.56.0 release
+ * broke. The callers below ask this question only on the path that reaches the
+ * REAL SDK.
+ */
+export declare function assertClaudeInstalled(useBundled?: boolean, 
+/** Where the binary is looked up. Production always takes the default. */
+resolve?: (useBundled: boolean) => string | null): void;
 /**
  * The SDK option that pins the executable, for both places that build `Options`.
  *
- * Empty while the bundled binary is in use: the SDK then resolves its own, which
- * is exactly today's behaviour and keeps `main` neutral. Empty also when the
- * system binary is missing — passing a path we know is not there would turn a
- * clear «Claude is not installed» into an SDK spawn error.
+ * Empty while the bundled binary is in use: the SDK then resolves its own,
+ * which is exactly what `USE_BUNDLED_CLAUDE = true` asks for. Empty also when
+ * there is no system binary — and that emptiness is no longer allowed to reach
+ * the real SDK: `assertClaudeInstalled` is asked first, on both paths.
  */
 export declare function claudeExecutableOption(useBundled?: boolean): {
     pathToClaudeCodeExecutable?: string;

package/dist/agent-binary.js

@@ -137,13 +137,62 @@ export const USE_BUNDLED_CLAUDE = false;
 export function sessionClaudePath(useBundled = USE_BUNDLED_CLAUDE) {
     return useBundled ? claudeCliPath() : whichExecutable(AGENT_RUNTIMES.claude.bin);
 }
+/**
+ * What every caller says when Claude Code is not on this machine (#395).
+ *
+ * Word for word the API's own refusal (`assertAgentAvailable` in
+ * `dev-sessions.service.ts`): the two halves answer the same question about the
+ * same binary, and a person who meets both — the API when it can see the
+ * measurement, this one when it cannot — should not have to work out whether
+ * they are being told two different things.
+ */
+export const CLAUDE_NOT_INSTALLED = 'Claude Code is not installed on this server — install it there, or pick another agent';
+/** Thrown where a run would otherwise start on a binary nobody chose. */
+export class ClaudeNotInstalledError extends Error {
+    constructor() {
+        super(CLAUDE_NOT_INSTALLED);
+        this.name = 'ClaudeNotInstalledError';
+    }
+}
+/**
+ * Refuse, in words, when a real Claude run has nothing legitimate to start.
+ *
+ * ## The hole this closes (#395, decision D14)
+ *
+ * With the bundled binary switched off and no system `claude`,
+ * `claudeExecutableOption` has nothing to pin and returns `{}`. To the SDK an
+ * absent `pathToClaudeCodeExecutable` does not mean «there is no Claude» — it
+ * means «resolve your own». So the machine either ran sessions on a SECOND
+ * Claude of a different version while its card said «not installed» (five
+ * sessions on `vmi3024903`, one of them $93), or — on a machine installed the
+ * standard way, where `--omit=optional` means the bundled package is not there
+ * at all — died inside the SDK with `Native CLI binary for linux-x64 not found`
+ * before its first word.
+ *
+ * ## Why it is a separate call and not a throw from `claudeExecutableOption`
+ *
+ * Both places that build `Options` do so eagerly, including in tests, where the
+ * SDK is replaced by a fake `query` and no binary is ever spawned. A throw from
+ * the option builder would therefore fail the whole suite on any machine
+ * without the CLI — CI among them, which is exactly how the 0.56.0 release
+ * broke. The callers below ask this question only on the path that reaches the
+ * REAL SDK.
+ */
+export function assertClaudeInstalled(useBundled = USE_BUNDLED_CLAUDE, 
+/** Where the binary is looked up. Production always takes the default. */
+resolve = sessionClaudePath) {
+    if (useBundled)
+        return;
+    if (!resolve(useBundled))
+        throw new ClaudeNotInstalledError();
+}
 /**
  * The SDK option that pins the executable, for both places that build `Options`.
  *
- * Empty while the bundled binary is in use: the SDK then resolves its own, which
- * is exactly today's behaviour and keeps `main` neutral. Empty also when the
- * system binary is missing — passing a path we know is not there would turn a
- * clear «Claude is not installed» into an SDK spawn error.
+ * Empty while the bundled binary is in use: the SDK then resolves its own,
+ * which is exactly what `USE_BUNDLED_CLAUDE = true` asks for. Empty also when
+ * there is no system binary — and that emptiness is no longer allowed to reach
+ * the real SDK: `assertClaudeInstalled` is asked first, on both paths.
  */
 export function claudeExecutableOption(useBundled = USE_BUNDLED_CLAUDE) {
     if (useBundled)

package/dist/attachments.d.ts

@@ -56,6 +56,10 @@ export declare function ensureGitExclude(worktreePath: string): Promise<void>;
  * Returns what actually landed — a file that could not be fetched is reported
  * and skipped rather than failing the whole message, because the text the user
  * typed is usually still worth delivering.
+ *
+ * Each file gets up to `DOWNLOAD_ATTEMPTS` goes inside ONE `DOWNLOAD_TIMEOUT_MS`
+ * budget (#407): the ceiling on how long a person waits for their own message is
+ * unchanged, and the attempts share it rather than each getting their own.
  */
 export declare function saveAttachments(input: {
     worktreePath: string;
@@ -63,6 +67,8 @@ export declare function saveAttachments(input: {
     token: string;
     attachments: RemoteAttachment[];
     fetchImpl?: typeof fetch;
+    /** Test seam: the pauses between attempts, so a suite does not sit through them. */
+    sleepImpl?: (ms: number) => Promise<void>;
 }): Promise<{
     saved: SavedAttachment[];
     failed: string[];

package/dist/attachments.js

@@ -44,6 +44,105 @@ const MAX_ATTACHMENT_BYTES = 51 * 1024 * 1024;
  * generous is nil: a stalled download fails the same way, just later.
  */
 const DOWNLOAD_TIMEOUT_MS = 180_000;
+/**
+ * How many times one file is fetched before the message goes without it (#407).
+ *
+ * One attempt was the whole defect: on 13.09.2026 a 656 KB screenshot died on
+ * `ECONNRESET` half-way through the body — the API had answered 200 and the
+ * proxy had written all 656 604 bytes — and the person got a line in the feed
+ * instead of their screenshot. Re-fetching the same file from the same machine
+ * reproduced it about 5 times in 65, so the second attempt is very nearly free
+ * and the third is the one that covers a bad minute.
+ *
+ * Three and not more because of the far end: `RATE_LIMIT.DEV_RUNNER_FILE` is 60
+ * requests a minute per runner and a message carries at most
+ * `DEV_SESSION_MESSAGE_ATTACHMENT_CAP` = 5 files, so the worst message on this
+ * path costs 15 — a quarter of the budget, with the rest left for the other
+ * sessions on the machine.
+ */
+const DOWNLOAD_ATTEMPTS = 3;
+/**
+ * What to wait before attempt 2 and before attempt 3.
+ *
+ * Short on purpose: a person is watching a message they just sent, and the
+ * fault this retries is a dropped connection rather than a busy server — the
+ * one case that genuinely needs a long wait (429) brings its own number below.
+ */
+const RETRY_PAUSES_MS = [1_000, 3_000];
+/**
+ * The longest a `Retry-After` may hold up one file.
+ *
+ * The header is honoured because a 429 is the far end asking for room, and
+ * capped because it is allowed to say «600» — which would spend the whole
+ * budget below on waiting and deliver the message without the file anyway.
+ */
+const MAX_RETRY_AFTER_MS = 10_000;
+/** `Retry-After` in seconds or as an HTTP date, clamped — or nothing usable. */
+function retryAfterMs(response, now) {
+    const header = response.headers.get('retry-after');
+    if (!header)
+        return undefined;
+    const seconds = Number(header.trim());
+    const ms = Number.isFinite(seconds)
+        ? seconds * 1_000
+        : Number.isNaN(Date.parse(header))
+            ? NaN
+            : Date.parse(header) - now;
+    if (!Number.isFinite(ms) || ms <= 0)
+        return undefined;
+    return Math.min(ms, MAX_RETRY_AFTER_MS);
+}
+/**
+ * Fetch one attachment once, and say whether the failure is worth repeating.
+ *
+ * Retried: anything `fetch` throws (a refused connection, a reset, a timeout)
+ * and anything thrown while reading the body — the incident was in the body, not
+ * in the response — plus 5xx and 429, which are the far end saying «not now».
+ *
+ * Not retried: every other 4xx (the file is gone, or this token may not have
+ * it), and a file over the ceiling, which will be over it again.
+ */
+async function fetchAttachmentOnce(doFetch, url, token, budgetMs) {
+    let response;
+    try {
+        response = await doFetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(budgetMs),
+        });
+    }
+    catch (error) {
+        return { ok: false, retry: true, reason: String(error) };
+    }
+    if (!response.ok) {
+        const retry = response.status >= 500 || response.status === 429;
+        return {
+            ok: false,
+            retry,
+            reason: `HTTP ${response.status}`,
+            ...(response.status === 429
+                ? (() => {
+                    const after = retryAfterMs(response, Date.now());
+                    return after === undefined ? {} : { retryAfterMs: after };
+                })()
+                : {}),
+        };
+    }
+    let buffer;
+    try {
+        buffer = Buffer.from(await response.arrayBuffer());
+    }
+    catch (error) {
+        return { ok: false, retry: true, reason: String(error) };
+    }
+    if (buffer.length > MAX_ATTACHMENT_BYTES) {
+        return {
+            ok: false,
+            retry: false,
+            reason: `file is larger than ${Math.round(MAX_ATTACHMENT_BYTES / 1024 / 1024)}MB`,
+        };
+    }
+    return { ok: true, buffer };
+}
 /**
  * A file name that is safe to write and unambiguous to read.
  *
@@ -134,9 +233,18 @@ export async function ensureGitExclude(worktreePath) {
  * Returns what actually landed — a file that could not be fetched is reported
  * and skipped rather than failing the whole message, because the text the user
  * typed is usually still worth delivering.
+ *
+ * Each file gets up to `DOWNLOAD_ATTEMPTS` goes inside ONE `DOWNLOAD_TIMEOUT_MS`
+ * budget (#407): the ceiling on how long a person waits for their own message is
+ * unchanged, and the attempts share it rather than each getting their own.
  */
 export async function saveAttachments(input) {
     const doFetch = input.fetchImpl ?? fetch;
+    const sleep = input.sleepImpl ??
+        ((ms) => new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+        }));
     const dir = path.join(input.worktreePath, ATTACHMENT_DIR);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     await ensureGitExclude(input.worktreePath);
@@ -144,18 +252,59 @@ export async function saveAttachments(input) {
     const failed = [];
     const base = input.apiUrl.replace(/\/$/, '');
     for (const attachment of input.attachments) {
-        try {
-            const response = await doFetch(`${base}/api/v1/dev/runner/attachments/${encodeURIComponent(attachment.id)}`, {
-                headers: { Authorization: `Bearer ${input.token}` },
-                signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
+        const url = `${base}/api/v1/dev/runner/attachments/${encodeURIComponent(attachment.id)}`;
+        const deadline = Date.now() + DOWNLOAD_TIMEOUT_MS;
+        let buffer = null;
+        let lastReason = 'unknown';
+        /** What actually happened, for the summary line — not the ceiling. */
+        let made = 0;
+        for (let attempt = 1; attempt <= DOWNLOAD_ATTEMPTS; attempt++) {
+            const budget = deadline - Date.now();
+            if (budget <= 0) {
+                lastReason = 'the time allowed for this file ran out';
+                break;
             }
-            const buffer = Buffer.from(await response.arrayBuffer());
-            if (buffer.length > MAX_ATTACHMENT_BYTES) {
-                throw new Error(`file is larger than ${Math.round(MAX_ATTACHMENT_BYTES / 1024 / 1024)}MB`);
+            made += 1;
+            const outcome = await fetchAttachmentOnce(doFetch, url, input.token, budget);
+            if (outcome.ok) {
+                buffer = outcome.buffer;
+                break;
             }
+            lastReason = outcome.reason;
+            // Every attempt is in the log with its number, so «it worked the second
+            // time» is visible afterwards rather than being a silent success.
+            log.warn('attachments: download attempt failed', {
+                attachmentId: attachment.id,
+                attempt,
+                of: DOWNLOAD_ATTEMPTS,
+                willRetry: outcome.retry && attempt < DOWNLOAD_ATTEMPTS,
+                error: outcome.reason,
+            });
+            if (!outcome.retry || attempt === DOWNLOAD_ATTEMPTS)
+                break;
+            const pause = Math.min(outcome.retryAfterMs ?? RETRY_PAUSES_MS[attempt - 1] ?? 0, 
+            // Never wait past the budget: the wait would be the whole of what is
+            // left and the attempt it buys would have no time to run.
+            Math.max(0, deadline - Date.now()));
+            if (pause > 0)
+                await sleep(pause);
+        }
+        if (buffer === null) {
+            // One line per FILE at the end, next to the line the session feed gets.
+            log.warn('attachments: download failed', {
+                attachmentId: attachment.id,
+                // What was actually tried, and the ceiling beside it. Printing the
+                // ceiling alone said «3 attempts» for a 404 that was asked once — and
+                // «did the retry run on this file» is the one question this whole
+                // change exists to let somebody answer from the log.
+                attempts: made,
+                of: DOWNLOAD_ATTEMPTS,
+                error: lastReason,
+            });
+            failed.push(attachment.fileName);
+            continue;
+        }
+        try {
             const name = safeAttachmentName(attachment.id, attachment.fileName);
             fs.writeFileSync(path.join(dir, name), buffer, { mode: 0o600 });
             saved.push({
@@ -166,7 +315,9 @@ export async function saveAttachments(input) {
             });
         }
         catch (error) {
-            log.warn('attachments: download failed', {
+            // The bytes are here and the disk refused them — not something a repeat
+            // of the download would mend.
+            log.warn('attachments: could not write the file', {
                 attachmentId: attachment.id,
                 error: String(error),
             });

package/dist/commit-message.js

@@ -1,5 +1,5 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { claudeExecutableOption } from './agent-binary.js';
+import { assertClaudeInstalled, claudeExecutableOption } from './agent-binary.js';
 import { scrubbedEnv } from './adapters/claude.js';
 import { gitBranchDiff } from './gitops.js';
 import { isSecretPath, maskString } from './policy.js';
@@ -149,6 +149,13 @@ export async function proposeCommitMessage(input, queryFn = query) {
     }
     let text = '';
     try {
+        // The second place a real Claude run starts (#395). Same question as
+        // `ClaudeAdapter.startSession`, asked for the same reason and only of the
+        // real SDK: without it this run would reach for whatever binary the SDK
+        // resolves by itself. Inside the `try`, so the answer is the ordinary
+        // `{ ok: false, error }` this function already returns.
+        if (queryFn === query)
+            assertClaudeInstalled();
         const run = queryFn({
             prompt: buildPrompt(input, diff),
             options: {

package/dist/index.js

@@ -13,7 +13,7 @@ import { claimCageAuthority, runSystemctl } from './cage-authority.js';
 import { acquireDaemonLock, isHeldByAnother } from './daemon-lock.js';
 import { loadConfig, mergeIntoPairedConfig, requireConfig, saveConfig, } from './config.js';
 import { log } from './log.js';
-import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
+import { installIsWritable, installPrefixFor, isSupervisedProcess, restartCapability, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
 import { applyStoredClaudeToken } from './agent-auth.js';
 import { Supervisor } from './supervisor.js';
 import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './status-file.js';
@@ -175,6 +175,21 @@ function runnerCapabilities(apiUrlOverride) {
         ...(selfUpdatable()
             ? { selfUpdate: true }
             : { selfUpdateBlocked: selfUpdateBlockedReason() ?? 'unsupervised' }),
+        /**
+         * 0.60.0: can be told to restart itself (#396), the same contract shape as
+         * the pair above.
+         *
+         * The condition is `isSupervisedProcess()` ALONE, and deliberately not
+         * `selfUpdatable()`: replacing the package needs an installed, writable npm
+         * package, but restarting needs only something that will start us again —
+         * a source checkout under systemd (this dogfood box) restarts perfectly
+         * well and must get the button.
+         *
+         * Announced rather than inferred from the version, because an older runner
+         * drops a command it cannot parse WITHOUT answering, and the dashboard
+         * would then offer a button that hangs until the gateway gives up.
+         */
+        ...restartCapability(),
         /**
          * Which OS user this daemon runs as (0.24.0).
          *
@@ -526,6 +541,12 @@ function runnerCapabilities(apiUrlOverride) {
             // это чтение, а не установка, и машину, чей владелец запретил ставить из
             // дашборда, спросить о том, что на ней стоит, по-прежнему можно.
             'agent_versions_refresh',
+            // #396. Listed unconditionally, unlike the `restart` flag above: the
+            // flag is what the dashboard draws a button from, and this list is what
+            // `runCommand` dispatches on. A machine that cannot restart still
+            // ANSWERS the command, with a sentence saying why — which is a better
+            // outcome than a frame nobody replies to.
+            'runner_restart',
         ],
     };
 }
@@ -911,6 +932,20 @@ async function cmdDaemon() {
             CLAUDE: new ClaudeAdapter(),
             ...(codex ? { CODEX: codex } : {}),
         },
+        /**
+         * #395: an agent installed from the dashboard is usable without a restart.
+         *
+         * The map above is built once, from what was on PATH when this process
+         * started — the same frozen snapshot `capabilities.agents` was. Claude does
+         * not need this (its adapter is unconditional and asks for the binary at
+         * session start), Codex does: its adapter is only built when `codex` was
+         * already there, so pressing «Install Codex» used to leave a machine that
+         * the card called ready and every session on which died at once.
+         *
+         * `hasExecutable` is asked HERE, at the moment of the question, which is
+         * the whole point.
+         */
+        makeAdapter: (agent) => agent === 'CODEX' && hasExecutable('codex') ? bootstrapCodex(config) : null,
         ...(config.mcp ? { mcp: { url: config.mcp.url, token: config.mcp.token } } : {}),
         ...(config.limits?.max_sessions ? { maxSessionsLimit: config.limits.max_sessions } : {}),
         /**
@@ -961,6 +996,22 @@ async function cmdDaemon() {
             }, RESTART_DELAY_MS);
             timer.unref();
         },
+        // #396: the same exit, asked for directly rather than as the tail of an
+        // update. The delay is the same and for the same reason — the answer has
+        // to leave the socket before the process does, or the card shows a timeout
+        // for a restart that is happening.
+        onRestartCommanded: (note) => {
+            log.info('daemon: restarting on a command from the dashboard', {
+                sessions: supervisor.activeSessionIds.length,
+                told: Boolean(note),
+            });
+            const timer = setTimeout(() => {
+                supervisor.shutdown();
+                ws.stop();
+                process.exit(0);
+            }, RESTART_DELAY_MS);
+            timer.unref();
+        },
     });
     const updateStatus = () => writeStatusFile({
         pid: process.pid,
@@ -1276,7 +1327,13 @@ async function runnerChecks() {
                 // /root/.local — a directory the daemon's user cannot write — and
                 // the install died naming a home nobody had chosen. `sudo -iu` hands
                 // the string to the TARGET user's login shell, so `$HOME` is theirs.
-                fix: `sudo -iu ${me.user} sh -lc 'npm config set prefix "$HOME/.local" && npm install -g --ignore-scripts --loglevel=error @bridge4dev/runner'`,
+                // `--omit=optional` is not cosmetic here (#395): without it npm pulls
+                // the SDK's bundled Claude — 215 MB and a SECOND Claude of a
+                // different version on the machine — and every other install path in
+                // the product omits it (`dev-runner-install.sh`, `self-update.ts`).
+                // This one line was how a hand-repaired machine ended up with a
+                // binary no card could account for.
+                fix: `sudo -iu ${me.user} sh -lc 'npm config set prefix "$HOME/.local" && npm install -g --ignore-scripts --omit=optional --loglevel=error @bridge4dev/runner'`,
                 fixMore: `(the \`npm config set prefix\` half is what keeps the button working: without it every LATER update aims at the system prefix again and fails with EACCES)`,
             }),
     });

package/dist/self-update.d.ts

@@ -116,6 +116,28 @@ export declare function installIsWritable(packageDir?: string | null): boolean;
  * that would work is recoverable, disappearing from the user's server is not.
  */
 export declare function isSupervisedProcess(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The `hello` pair that decides whether the card draws a «Restart runner»
+ * button (#396, plan `workflow-stage-restart` R13).
+ *
+ * The same shape as `selfUpdate` / `selfUpdateBlocked`, and for the same
+ * reason: an older runner drops a command it cannot parse without answering, so
+ * the dashboard must gate on an announced capability rather than on a version.
+ *
+ * Only `isSupervisedProcess()`, and NOT `selfUpdatable()`: replacing the
+ * package needs an installed, writable npm package, restarting needs only
+ * something that will start us again. A daemon run from a source checkout under
+ * systemd — the dogfood box — restarts perfectly well and must get the button.
+ *
+ * Lives here rather than beside the other capabilities in `index.ts` because
+ * that file exports nothing and is the CLI entry point: a key spelled wrong
+ * there is caught by nobody, and `capabilities` is an untyped bag on both ends.
+ */
+export declare function restartCapability(env?: NodeJS.ProcessEnv): {
+    restart: true;
+} | {
+    restartBlocked: 'unsupervised';
+};
 /**
  * Same origin as the API we are paired with, and it really is a tarball.
  *

package/dist/self-update.js

@@ -148,6 +148,28 @@ export function installIsWritable(packageDir = resolveInstalledPackageDir()) {
 export function isSupervisedProcess(env = process.env) {
     return typeof env['INVOCATION_ID'] === 'string' && env['INVOCATION_ID'].length > 0;
 }
+/**
+ * The `hello` pair that decides whether the card draws a «Restart runner»
+ * button (#396, plan `workflow-stage-restart` R13).
+ *
+ * The same shape as `selfUpdate` / `selfUpdateBlocked`, and for the same
+ * reason: an older runner drops a command it cannot parse without answering, so
+ * the dashboard must gate on an announced capability rather than on a version.
+ *
+ * Only `isSupervisedProcess()`, and NOT `selfUpdatable()`: replacing the
+ * package needs an installed, writable npm package, restarting needs only
+ * something that will start us again. A daemon run from a source checkout under
+ * systemd — the dogfood box — restarts perfectly well and must get the button.
+ *
+ * Lives here rather than beside the other capabilities in `index.ts` because
+ * that file exports nothing and is the CLI entry point: a key spelled wrong
+ * there is caught by nobody, and `capabilities` is an untyped bag on both ends.
+ */
+export function restartCapability(env = process.env) {
+    // The literal string matters: the dashboard renders the explanatory sentence
+    // for exactly this value and silently draws nothing for any other.
+    return isSupervisedProcess(env) ? { restart: true } : { restartBlocked: 'unsupervised' };
+}
 /**
  * Same origin as the API we are paired with, and it really is a tarball.
  *

package/dist/supervisor.d.ts

@@ -39,6 +39,20 @@ export interface SupervisorOptions {
      * reports the new version only after the next manual restart.
      */
     onRestartRequested?: (outcome: SelfUpdateOutcome) => void;
+    /**
+     * Called after a `runner_restart` the machine agreed to, once the reply is on
+     * the wire (#396). Separate from `onRestartRequested` rather than folded into
+     * it: that one is typed on `SelfUpdateOutcome` and its handler logs the
+     * version it is restarting INTO, which a plain restart has no answer for.
+     */
+    onRestartCommanded?: (note: string | null) => void;
+    /**
+     * Build an adapter for an agent that was not on PATH when the daemon started
+     * (#395). Returning `null` means «still not here», and the session is refused
+     * in the same words as before. Only the entry point can supply this: it owns
+     * the config the adapters are built from.
+     */
+    makeAdapter?: (agent: 'CLAUDE' | 'CODEX') => AgentAdapter | null;
     /**
      * Local ceiling on concurrent agent processes, from the runner's own config
      * (layer 1). When set it wins over the API's number if it is stricter — the
@@ -210,7 +224,30 @@ export interface SupervisorOptions {
     readScopeHold?: (unit: string) => ScopeHold | null;
     /** #398 S4: the heartbeat for the memory frame. Real one is a minute. */
     sessionLimitsHeartbeatMs?: number;
+    /**
+     * S1 of plan `workflow-mode-fixes`: how often a resting session re-asserts
+     * a background count it still holds — a test seam over
+     * `BACKGROUND_TASKS_HEARTBEAT_MS`. Real one is five minutes.
+     */
+    backgroundTasksHeartbeatMs?: number;
 }
+/**
+ * How often a resting session says «I still hold N background tasks» — the
+ * same `session_status` frame, the same status, sent again (plan
+ * `workflow-mode-fixes` S1 p.9).
+ *
+ * The count is a level the API stamps on arrival, and every reader over there
+ * — the workflow gate, its reminder, the «Agents» badge, the Inbox — believes
+ * it for an hour from that stamp. A task that simply runs (a forty-minute
+ * build) changes nothing in the tray, so nothing else would ever send the
+ * count again, and the platform would stop believing a live task after an
+ * hour. This is the frame that keeps it believed for as long as it is true.
+ *
+ * Mirrored by value in `@devbridge/shared` (`constants/dev-sessions.ts`),
+ * which this package cannot import; `supervisor.test.ts` holds the two copies
+ * together and keeps this well inside the API's trust window.
+ */
+export declare const BACKGROUND_TASKS_HEARTBEAT_MS: number;
 export declare class Supervisor {
     private readonly ws;
     private readonly opts;
@@ -282,6 +319,13 @@ export declare class Supervisor {
      * which of the two is running.
      */
     private installInFlight;
+    /**
+     * A `runner_restart` has been agreed to and the exit is coming (#396).
+     *
+     * Never cleared: the process has ~1.5 s left, and everything it must refuse in
+     * that window it must refuse for good.
+     */
+    private restarting;
     /** A restore-point collection is running; a second reconnect must not start another (#388). */
     private checkpointGcInFlight;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
@@ -299,6 +343,21 @@ export declare class Supervisor {
      * sent — the next `hello_ack` or the hourly tick carries the same fact, and
      * the measurement behind it is cached, so retrying is nearly free.
      */
+    /**
+     * The adapter for this agent — built now if it was not there at boot (#395).
+     *
+     * `opts.adapters` is assembled once, when the daemon starts, from what was on
+     * PATH at that moment. That is the SAME frozen snapshot `capabilities.agents`
+     * was, one layer down: press «Install Codex» on a running machine and the
+     * measurement updates, the card lights up, the API lets the session through —
+     * and this map still has no CODEX in it, so the session is created and dies
+     * at once. Asking the factory closes the last of the three lists.
+     *
+     * Built at most once per process and remembered: preparing Codex's isolated
+     * home clones ~90 MB on a machine that has never run it, and that is a price
+     * to pay on the first session, not on every one.
+     */
+    private adapterFor;
     /**
      * Why an install cannot start right now, in words for the person who pressed.
      *
@@ -438,6 +497,14 @@ export declare class Supervisor {
     private publishSlots;
     /** The heartbeat window actually used — the constant, or a test's own. */
     private readonly hostLoadHeartbeatMs;
+    /** S1 p.9: how often a held background count is said again. */
+    private readonly backgroundTasksHeartbeatMs;
+    /**
+     * The API has answered this socket's `hello` (S1 p.9). Frames sent before
+     * that are closed with 4002; the reconnect path re-sends every status in
+     * `reconcile` anyway, so the heartbeat has nothing to say until then.
+     */
+    private helloAcked;
     private readonly hostLoadTimer;
     /** #398 S2: the stall detector's clock, and the deadline it enforces. */
     private readonly stallTimer;
@@ -655,6 +722,28 @@ export declare class Supervisor {
      */
     private idleSessionCeiling;
     private publishSessionLimits;
+    /**
+     * Re-assert the background count of every resting session that still holds
+     * one (S1 p.9) — the same `session_status`, the same status, sent again.
+     *
+     * Only at rest, and only in the two statuses somebody over there reads the
+     * age of the number in: `REVIEW` and `WAITING_INPUT`. NOT in
+     * `WAITING_PERMISSION` — after a denied card `lastReported` stays there
+     * until the turn ends while the API has already healed its row to `RUNNING`,
+     * and repeating the old status would put the row back to «waiting for
+     * permission» with no card behind it, a fresh `statusChangedAt` and a
+     * needless nudge of the workflow engine. Not mid-turn either: a turn ends
+     * with a status frame of its own.
+     *
+     * Straight through `reportStatus`, past the equality check in
+     * `setBackgroundTasks`: that one exists to stay quiet when nothing changed,
+     * and «nothing changed» is exactly what this frame is for. Measured from the
+     * last status frame of ANY kind — every one carries the count — so a session
+     * that just reported is not reported twice, and a reconnect (which re-sends
+     * every tracked session's status in `reconcile`) restarts the five minutes
+     * by itself.
+     */
+    private publishBackgroundHeartbeats;
     private publishHostLoad;
     private onFrame;
     private startSession;

package/dist/supervisor.js

@@ -19,7 +19,7 @@ import { applySession, gitBranches, gitCommit, gitDiff, gitLog, gitPush, gitRefs
 import { fsView } from './fsview.js';
 import { publishFile } from './file-publish.js';
 import { agentAuthStatuses, AuthRelay, clearAgentAuthFailure, noteAgentAuthFailure, } from './auth-relay.js';
-import { selfUpdate } from './self-update.js';
+import { isSupervisedProcess, selfUpdate } from './self-update.js';
 import { installAgent } from './agent-install.js';
 import { autoUpdateRefusal, claimAgentAutoUpdate } from './agent-auto-update.js';
 import { pruneNativeClaudeVersions } from './agent-cleanup.js';
@@ -80,6 +80,23 @@ function freshLevels() {
     };
 }
 const LAUNCH_REFUSED = { ok: false, reason: 'refused' };
+/**
+ * How often a resting session says «I still hold N background tasks» — the
+ * same `session_status` frame, the same status, sent again (plan
+ * `workflow-mode-fixes` S1 p.9).
+ *
+ * The count is a level the API stamps on arrival, and every reader over there
+ * — the workflow gate, its reminder, the «Agents» badge, the Inbox — believes
+ * it for an hour from that stamp. A task that simply runs (a forty-minute
+ * build) changes nothing in the tray, so nothing else would ever send the
+ * count again, and the platform would stop believing a live task after an
+ * hour. This is the frame that keeps it believed for as long as it is true.
+ *
+ * Mirrored by value in `@devbridge/shared` (`constants/dev-sessions.ts`),
+ * which this package cannot import; `supervisor.test.ts` holds the two copies
+ * together and keeps this well inside the API's trust window.
+ */
+export const BACKGROUND_TASKS_HEARTBEAT_MS = 5 * 60 * 1000;
 export class Supervisor {
     ws;
     opts;
@@ -151,6 +168,13 @@ export class Supervisor {
      * which of the two is running.
      */
     installInFlight = null;
+    /**
+     * A `runner_restart` has been agreed to and the exit is coming (#396).
+     *
+     * Never cleared: the process has ~1.5 s left, and everything it must refuse in
+     * that window it must refuse for good.
+     */
+    restarting = false;
     /** A restore-point collection is running; a second reconnect must not start another (#388). */
     checkpointGcInFlight = false;
     /** Session 14: one project-recipe run per machine, and its verdict queue. */
@@ -177,6 +201,9 @@ export class Supervisor {
         ws.on('frame', (frame) => {
             void this.onFrame(frame).catch((error) => log.error('supervisor: frame handler failed', { type: frame.type, error: String(error) }));
         });
+        ws.on('close', () => {
+            this.helloAcked = false;
+        });
         /**
          * The seat report is on a heartbeat, not only on the events that change it.
          *
@@ -233,8 +260,14 @@ export class Supervisor {
          * actually moved (or the heartbeat came due).
          */
         this.hostLoadHeartbeatMs = opts.hostLoadHeartbeatMs ?? HOST_LOAD_HEARTBEAT_MS;
+        this.backgroundTasksHeartbeatMs =
+            opts.backgroundTasksHeartbeatMs ?? BACKGROUND_TASKS_HEARTBEAT_MS;
         this.hostLoadTimer = setInterval(() => {
             this.publishHostLoad();
+            // The fourth thing only a tick can notice (S1 p.9): a background task
+            // that is simply still running produces no event, and the API's belief
+            // in the count runs out an hour after it was last said.
+            this.publishBackgroundHeartbeats();
             // Same cadence, same reason: what a session's cgroup is going through is
             // something that happens to it, and only a tick can notice (#387).
             this.watchSessionCages();
@@ -288,12 +321,41 @@ export class Supervisor {
      * sent — the next `hello_ack` or the hourly tick carries the same fact, and
      * the measurement behind it is cached, so retrying is nearly free.
      */
+    /**
+     * The adapter for this agent — built now if it was not there at boot (#395).
+     *
+     * `opts.adapters` is assembled once, when the daemon starts, from what was on
+     * PATH at that moment. That is the SAME frozen snapshot `capabilities.agents`
+     * was, one layer down: press «Install Codex» on a running machine and the
+     * measurement updates, the card lights up, the API lets the session through —
+     * and this map still has no CODEX in it, so the session is created and dies
+     * at once. Asking the factory closes the last of the three lists.
+     *
+     * Built at most once per process and remembered: preparing Codex's isolated
+     * home clones ~90 MB on a machine that has never run it, and that is a price
+     * to pay on the first session, not on every one.
+     */
+    adapterFor(agent) {
+        const known = this.opts.adapters[agent];
+        if (known)
+            return known;
+        const built = this.opts.makeAdapter?.(agent) ?? null;
+        if (built)
+            this.opts.adapters[agent] = built;
+        return built ?? undefined;
+    }
     /**
      * Why an install cannot start right now, in words for the person who pressed.
      *
      * `null` means the way is clear.
      */
     installBusyReason() {
+        // #396: the same window `self_update` documents below, for a plain restart.
+        // The process only exits ~1.5 s after the reply, and the API frees its own
+        // lock the moment the reply lands — so an install that slipped into that
+        // window would be an `npm install -g` the exit kills half-written.
+        if (this.restarting)
+            return 'This runner is restarting';
         if (this.installInFlight === 'self_update')
             return 'An update is already running';
         if (this.installInFlight === 'agent_install') {
@@ -641,6 +703,14 @@ export class Supervisor {
     }
     /** The heartbeat window actually used — the constant, or a test's own. */
     hostLoadHeartbeatMs;
+    /** S1 p.9: how often a held background count is said again. */
+    backgroundTasksHeartbeatMs;
+    /**
+     * The API has answered this socket's `hello` (S1 p.9). Frames sent before
+     * that are closed with 4002; the reconnect path re-sends every status in
+     * `reconcile` anyway, so the heartbeat has nothing to say until then.
+     */
+    helloAcked = false;
     hostLoadTimer;
     /** #398 S2: the stall detector's clock, and the deadline it enforces. */
     stallTimer;
@@ -1531,6 +1601,58 @@ export class Supervisor {
             this.lastLimitsSentAt = measuredAt;
         }
     }
+    /**
+     * Re-assert the background count of every resting session that still holds
+     * one (S1 p.9) — the same `session_status`, the same status, sent again.
+     *
+     * Only at rest, and only in the two statuses somebody over there reads the
+     * age of the number in: `REVIEW` and `WAITING_INPUT`. NOT in
+     * `WAITING_PERMISSION` — after a denied card `lastReported` stays there
+     * until the turn ends while the API has already healed its row to `RUNNING`,
+     * and repeating the old status would put the row back to «waiting for
+     * permission» with no card behind it, a fresh `statusChangedAt` and a
+     * needless nudge of the workflow engine. Not mid-turn either: a turn ends
+     * with a status frame of its own.
+     *
+     * Straight through `reportStatus`, past the equality check in
+     * `setBackgroundTasks`: that one exists to stay quiet when nothing changed,
+     * and «nothing changed» is exactly what this frame is for. Measured from the
+     * last status frame of ANY kind — every one carries the count — so a session
+     * that just reported is not reported twice, and a reconnect (which re-sends
+     * every tracked session's status in `reconcile`) restarts the five minutes
+     * by itself.
+     */
+    publishBackgroundHeartbeats() {
+        // `helloAcked` and not merely `connected`: the socket is open from the
+        // `open` event, but the gateway answers any frame that reaches it before
+        // its own `hello` bookkeeping is done with a close (4002) — a window of
+        // tens of milliseconds on every reconnect that a tick can land in.
+        if (!this.ws.connected || !this.helloAcked)
+            return;
+        const now = Date.now();
+        for (const running of this.sessions.values()) {
+            if (running.backgroundTasks <= 0)
+                continue;
+            // Only a session with a process behind it. The count is zeroed when the
+            // process is found gone, but not on every path that loses one: a
+            // relaunch that crashed leaves the entry with `session = null` and the
+            // count it was holding, and re-asserting that would be the platform
+            // confirming work nobody is doing.
+            if (!running.session)
+                continue;
+            if (running.lastReported !== 'REVIEW' && running.lastReported !== 'WAITING_INPUT')
+                continue;
+            const sinceLastSent = now - (running.statusSentAt ?? 0);
+            // A backwards clock step is «due», not «early» — same allowance as the
+            // host-load heartbeat, for the same reason.
+            if (sinceLastSent < this.backgroundTasksHeartbeatMs && sinceLastSent >= 0)
+                continue;
+            this.reportStatus(running.descriptor.id, running.lastReported, {
+                costUsd: running.costUsd,
+                activeMs: Supervisor.spentMs(running),
+            });
+        }
+    }
     publishHostLoad() {
         const sample = (this.opts.readHostLoad ?? readHostLoad)();
         if (!sample)
@@ -1549,6 +1671,7 @@ export class Supervisor {
     async onFrame(frame) {
         switch (frame.type) {
             case 'hello_ack':
+                this.helloAcked = true;
                 // A new connection knows nothing about the seats we reported to the
                 // last one — the API keeps that beside the socket, not in the database,
                 // because it is only true while the socket is. Forget what we told the
@@ -1736,7 +1859,7 @@ export class Supervisor {
             });
             return;
         }
-        if (!this.opts.adapters[descriptor.agent]) {
+        if (!this.adapterFor(descriptor.agent)) {
             this.reportStatus(descriptor.id, 'FAILED', {
                 errorMessage: `${AGENT_LABELS[descriptor.agent] ?? descriptor.agent} is not installed on this server`,
             });
@@ -1986,7 +2109,7 @@ export class Supervisor {
      */
     launchAgent(running, prompt, resumeId) {
         const { descriptor } = running;
-        const adapter = this.opts.adapters[descriptor.agent];
+        const adapter = this.adapterFor(descriptor.agent);
         if (!adapter || !running.worktreePath || !running.branch)
             return LAUNCH_REFUSED;
         /**
@@ -3327,6 +3450,28 @@ export class Supervisor {
                 // when it finally succeeds or finally gives up.
                 if (!event.ok && this.armApiRetry(running, descriptor, event))
                     return;
+                /**
+                 * A turn that ended well closes the retry EPISODE (#406).
+                 *
+                 * `running.apiRetry` records «attempt N of rule R», and `armApiRetry`
+                 * reads it to answer two questions: have we run out of attempts, and
+                 * did the same failure come straight back. Both are questions about ONE
+                 * episode. Until now the record was only ever cleared when a person
+                 * typed, a session stopped, or a session was torn down — so a session
+                 * that recovered kept «attempt 1 of claude.server_error» for the rest of
+                 * its life, and the NEXT api_error hours later read as «the same failure
+                 * came back after an automatic retry», got no retry, and ended the
+                 * session with a note that was not true.
+                 *
+                 * Nobody met that before this release: an `api_error` turn was reported
+                 * as a SUCCESS and never reached this code at all. With #406 it does,
+                 * and a long unattended run meets two network hiccups more often than
+                 * one. `apiRetriesUsed` — the ceiling that does not depend on the table
+                 * being right — is deliberately NOT reset here: it is a fact about the
+                 * session, and only a person typing clears it.
+                 */
+                if (event.ok)
+                    this.clearApiRetry(running);
                 this.completeTurn(running, descriptor, event);
                 return;
             }
@@ -6429,6 +6574,50 @@ export class Supervisor {
                         this.opts.onRestartRequested?.(outcome);
                     return;
                 }
+                /**
+                 * «Restart the runner» from the server card (#396, plan R13).
+                 *
+                 * The whole errand on this side: answer, tell every live session why it
+                 * is about to go quiet, and exit for the service to start us again. The
+                 * API cannot do the middle part — the feeds belong to sessions only this
+                 * process knows about — and it does not try to.
+                 *
+                 * Refused, in words, when nothing would bring the daemon back: a runner
+                 * started by hand that exits here is a machine that has lost its runner
+                 * until somebody with SSH notices. Same condition and the same shape of
+                 * sentence as `self_update`'s (`self-update.ts`), and the same reason.
+                 */
+                case 'runner_restart': {
+                    if (!isSupervisedProcess()) {
+                        const detail = 'The runner is not running as a service on this machine, so nothing would start it ' +
+                            'again. Install it with `devbridge-runner install-service`, or restart it by hand.';
+                        return void reply({ ok: false, result: { ok: false, detail }, error: detail });
+                    }
+                    // Second line of defence behind the API's per-server lock, exactly as
+                    // `self_update` has: exiting in the middle of an `npm install -g`
+                    // leaves a half-written package for the service to start.
+                    const busy = this.installBusyReason();
+                    if (busy)
+                        return void reply({ ok: false, result: { ok: false, detail: busy }, error: busy });
+                    const note = str(frame.args?.['note']);
+                    // BEFORE `shutdown()`, which clears the session map — and before the
+                    // exit, because everything on this path is journaled synchronously
+                    // for the reason spelled out on `shutdown` itself. A person whose
+                    // session goes quiet did not press the button; the line is how they
+                    // find out it was pressed at all.
+                    if (note) {
+                        for (const running of this.sessions.values()) {
+                            this.sendEvent(running, 'system_note', { code: 'runner_restart', text: note });
+                        }
+                    }
+                    // Set BEFORE the reply: the API releases its per-server lock the
+                    // moment the reply lands, and the next errand must meet a machine
+                    // that already knows it is leaving.
+                    this.restarting = true;
+                    reply({ ok: true, result: { ok: true } });
+                    this.opts.onRestartCommanded?.(note);
+                    return;
+                }
                 case 'agent_install': {
                     // The veto is enforced here as well as withheld from `hello`: an API
                     // that has not noticed still must not install anything on a machine
@@ -6978,6 +7167,10 @@ export class Supervisor {
             // would mean it goes on claiming background work forever.
             ...(running ? { backgroundTasks: running.backgroundTasks } : {}),
         });
+        // …and the count's age starts here (S1 p.9): the background heartbeat is
+        // due five minutes after the last frame that carried it, whichever it was.
+        if (running)
+            running.statusSentAt = Date.now();
         // Every seat change is accompanied by a status report — a session starting,
         // parking, ending. Hooking the seat report here rather than at each of those
         // is the whole point: «remember to also tell the API» is the rule that had

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.58.2";
+export declare const RUNNER_VERSION = "0.60.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.58.2';
+export const RUNNER_VERSION = '0.60.0';
 //# sourceMappingURL=version.js.map

package/package.json

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