@bridge4dev/runner 0.59.1 → 0.61.0

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/journal.d.ts

@@ -58,6 +58,23 @@ export declare class SessionJournal {
         anchor: string;
         providerSessionId: string;
     } | null;
+    /**
+     * Every card this journal has published, and whether it is still open —
+     * in the order they were asked (#392).
+     *
+     * The persistent twin of the supervisor's `running.openQuestions`: that set
+     * dies with the process, and a process that dies ungracefully never gets to
+     * `shutdown()`, which is the only place it withdraws them. This one is
+     * rebuilt from the file, so the next process can close what the last one
+     * left open — the card in the browser does not know the runner restarted.
+     *
+     * Closed cards are remembered too, not only dropped: «this card was closed
+     * by somebody» is the fact that stops a SECOND tombstone. A queued answer
+     * that reaches the next process after a restore has already closed the card
+     * must rescue the words and say nothing more about the card — and the only
+     * witness that the card was closed is this file.
+     */
+    private readonly asks;
     constructor(sessionId: string, dir?: string);
     private replay;
     private write;
@@ -86,6 +103,29 @@ export declare class SessionJournal {
     recordStatus(status: string, extra?: Record<string, unknown>, epoch?: number): void;
     /** Assign the next seq and persist the event before it is sent. */
     append(eventType: string, payload: Record<string, unknown>): JournalEvent;
+    /**
+     * Keep `openAsks` in step with the cards going out through `append` (#392).
+     *
+     * Here and not in the supervisor, because `append` is the one door every
+     * event takes: a card that was published was published through it, and so
+     * was every resolution — the adapter's own, `withdrawOpenQuestions`, the
+     * `not_open` miss. A set kept beside the callers would need every one of
+     * them to remember it, which is exactly how the in-memory set came to be
+     * empty at the moment it was needed.
+     *
+     * A resolution for a card this journal never published writes nothing:
+     * there is nothing to close, and remembering strangers would only grow the
+     * file.
+     */
+    private trackAsk;
+    /** The cards still waiting on a person, oldest first (#392). */
+    openAskIds(): string[];
+    /**
+     * What this journal knows about one card (#392): `open`, `closed`, or
+     * nothing at all — a card asked by a runner from before these lines existed,
+     * or one this state directory never saw.
+     */
+    askState(askId: string): 'open' | 'closed' | undefined;
     /**
      * Never reuse a seq the API already stored: after a runner state-dir wipe the
      * local counter restarts at 1 and every replayed event would collide with an

package/dist/journal.js

@@ -21,6 +21,23 @@ export class SessionJournal {
     lastStatus = null;
     /** The agent's conversation tip, and the provider session it lives in. */
     lastAnchor = null;
+    /**
+     * Every card this journal has published, and whether it is still open —
+     * in the order they were asked (#392).
+     *
+     * The persistent twin of the supervisor's `running.openQuestions`: that set
+     * dies with the process, and a process that dies ungracefully never gets to
+     * `shutdown()`, which is the only place it withdraws them. This one is
+     * rebuilt from the file, so the next process can close what the last one
+     * left open — the card in the browser does not know the runner restarted.
+     *
+     * Closed cards are remembered too, not only dropped: «this card was closed
+     * by somebody» is the fact that stops a SECOND tombstone. A queued answer
+     * that reaches the next process after a restore has already closed the card
+     * must rescue the words and say nothing more about the card — and the only
+     * witness that the card was closed is this file.
+     */
+    asks = new Map();
     constructor(sessionId, dir = journalDir()) {
         this.sessionId = sessionId;
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -50,6 +67,16 @@ export class SessionJournal {
                 });
                 if (parsed.seq >= this.nextSeq)
                     this.nextSeq = parsed.seq + 1;
+                // The event lines carry the same fact as `ask_open`/`ask_closed`, and
+                // replaying both is harmless: the set is a set.
+                this.trackAsk(parsed.eventType, parsed.payload, false);
+            }
+            else if (parsed.kind === 'ask_open') {
+                if (this.asks.get(parsed.askId) !== 'closed')
+                    this.asks.set(parsed.askId, 'open');
+            }
+            else if (parsed.kind === 'ask_closed') {
+                this.asks.set(parsed.askId, 'closed');
             }
             else if (parsed.kind === 'ack') {
                 this.unackedBySeq.delete(parsed.seq);
@@ -107,6 +134,11 @@ export class SessionJournal {
         if (this.lastAnchor) {
             lines.push({ kind: 'anchor', ...this.lastAnchor });
         }
+        // AFTER the event lines: an unacked `question` re-written above would
+        // otherwise reopen, on the next replay, a card these lines say is closed.
+        for (const [askId, state] of this.asks) {
+            lines.push({ kind: state === 'open' ? 'ask_open' : 'ask_closed', askId });
+        }
         if (this.lastStatus) {
             lines.push({
                 kind: 'status',
@@ -182,8 +214,58 @@ export class SessionJournal {
         const event = { seq: this.nextSeq++, eventType, payload };
         this.write({ kind: 'event', ...event, ts: new Date().toISOString() });
         this.unackedBySeq.set(event.seq, event);
+        this.trackAsk(eventType, payload, true);
         return event;
     }
+    /**
+     * Keep `openAsks` in step with the cards going out through `append` (#392).
+     *
+     * Here and not in the supervisor, because `append` is the one door every
+     * event takes: a card that was published was published through it, and so
+     * was every resolution — the adapter's own, `withdrawOpenQuestions`, the
+     * `not_open` miss. A set kept beside the callers would need every one of
+     * them to remember it, which is exactly how the in-memory set came to be
+     * empty at the moment it was needed.
+     *
+     * A resolution for a card this journal never published writes nothing:
+     * there is nothing to close, and remembering strangers would only grow the
+     * file.
+     */
+    trackAsk(eventType, payload, persist) {
+        if (eventType !== 'question' && eventType !== 'question_resolved')
+            return;
+        const askId = payload['askId'];
+        if (typeof askId !== 'string' || !askId)
+            return;
+        const state = this.asks.get(askId);
+        if (eventType === 'question') {
+            // A card is asked once; a replayed event line for one already closed
+            // (compaction keeps unacked events) must not reopen it.
+            if (state !== undefined)
+                return;
+            this.asks.set(askId, 'open');
+            if (persist)
+                this.write({ kind: 'ask_open', askId });
+            return;
+        }
+        if (state !== 'open')
+            return;
+        this.asks.set(askId, 'closed');
+        if (persist)
+            this.write({ kind: 'ask_closed', askId });
+    }
+    /** The cards still waiting on a person, oldest first (#392). */
+    openAskIds() {
+        return [...this.asks].filter(([, state]) => state === 'open').map(([askId]) => askId);
+    }
+    /**
+     * What this journal knows about one card (#392): `open`, `closed`, or
+     * nothing at all — a card asked by a runner from before these lines existed,
+     * or one this state directory never saw.
+     */
+    askState(askId) {
+        return this.asks.get(askId);
+    }
     /**
      * Never reuse a seq the API already stored: after a runner state-dir wipe the
      * local counter restarts at 1 and every replayed event would collide with an

package/dist/protocol.d.ts

@@ -32,6 +32,20 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
      * behaviour every runner had before this release.
      */
     pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    /**
+     * Subagents the API still believes to be alive in this session (#393).
+     *
+     * The number is the dead process's last word, kept by the API: a runner
+     * restart takes every subagent with it, and the new process seeds its own
+     * count at zero — so the descriptor is the only place the number survives
+     * long enough to be written down. The API sends it only while it still
+     * believes it (its own trust window on the count's age); absent or zero
+     * means «nothing to say», and a restore says nothing.
+     *
+     * `.catch(undefined)` like its neighbours: one malformed value must cost
+     * its own session a line at most, never the frame (QA-100 MAJOR-1).
+     */
+    backgroundTasks: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
     /**
      * The newest published version of THIS session's agent — Р13, §4.8.
      *
@@ -246,6 +260,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     } | undefined;
     workMode?: "DIRECT" | "BRANCH" | undefined;
     pausedUntil?: string | null | undefined;
+    backgroundTasks?: number | undefined;
     agentLatestVersion?: string | undefined;
     skipAgentPrompt?: boolean | undefined;
     branchHint?: string | undefined;
@@ -295,6 +310,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     activeMsBase?: number | undefined;
     extraBudgetMinutes?: number | null | undefined;
     pausedUntil?: unknown;
+    backgroundTasks?: unknown;
     agentLatestVersion?: unknown;
     skipAgentPrompt?: unknown;
     branchHint?: unknown;
@@ -450,6 +466,20 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
          * behaviour every runner had before this release.
          */
         pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+        /**
+         * Subagents the API still believes to be alive in this session (#393).
+         *
+         * The number is the dead process's last word, kept by the API: a runner
+         * restart takes every subagent with it, and the new process seeds its own
+         * count at zero — so the descriptor is the only place the number survives
+         * long enough to be written down. The API sends it only while it still
+         * believes it (its own trust window on the count's age); absent or zero
+         * means «nothing to say», and a restore says nothing.
+         *
+         * `.catch(undefined)` like its neighbours: one malformed value must cost
+         * its own session a line at most, never the frame (QA-100 MAJOR-1).
+         */
+        backgroundTasks: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
         /**
          * The newest published version of THIS session's agent — Р13, §4.8.
          *
@@ -664,6 +694,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
+        backgroundTasks?: number | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
@@ -713,6 +744,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        backgroundTasks?: unknown;
         agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
@@ -759,6 +791,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
+        backgroundTasks?: number | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
@@ -814,6 +847,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        backgroundTasks?: unknown;
         agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
@@ -883,6 +917,20 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
          * behaviour every runner had before this release.
          */
         pausedUntil: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+        /**
+         * Subagents the API still believes to be alive in this session (#393).
+         *
+         * The number is the dead process's last word, kept by the API: a runner
+         * restart takes every subagent with it, and the new process seeds its own
+         * count at zero — so the descriptor is the only place the number survives
+         * long enough to be written down. The API sends it only while it still
+         * believes it (its own trust window on the count's age); absent or zero
+         * means «nothing to say», and a restore says nothing.
+         *
+         * `.catch(undefined)` like its neighbours: one malformed value must cost
+         * its own session a line at most, never the frame (QA-100 MAJOR-1).
+         */
+        backgroundTasks: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
         /**
          * The newest published version of THIS session's agent — Р13, §4.8.
          *
@@ -1097,6 +1145,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
+        backgroundTasks?: number | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
@@ -1146,6 +1195,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        backgroundTasks?: unknown;
         agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
@@ -1192,6 +1242,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         } | undefined;
         workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
+        backgroundTasks?: number | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
         branchHint?: string | undefined;
@@ -1244,6 +1295,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         activeMsBase?: number | undefined;
         extraBudgetMinutes?: number | null | undefined;
         pausedUntil?: unknown;
+        backgroundTasks?: unknown;
         agentLatestVersion?: unknown;
         skipAgentPrompt?: unknown;
         branchHint?: unknown;

package/dist/protocol.js

@@ -59,6 +59,20 @@ export const SessionDescriptorSchema = z.object({
      * behaviour every runner had before this release.
      */
     pausedUntil: z.string().max(40).nullable().optional().catch(undefined),
+    /**
+     * Subagents the API still believes to be alive in this session (#393).
+     *
+     * The number is the dead process's last word, kept by the API: a runner
+     * restart takes every subagent with it, and the new process seeds its own
+     * count at zero — so the descriptor is the only place the number survives
+     * long enough to be written down. The API sends it only while it still
+     * believes it (its own trust window on the count's age); absent or zero
+     * means «nothing to say», and a restore says nothing.
+     *
+     * `.catch(undefined)` like its neighbours: one malformed value must cost
+     * its own session a line at most, never the frame (QA-100 MAJOR-1).
+     */
+    backgroundTasks: z.number().int().min(0).optional().catch(undefined),
     /**
      * The newest published version of THIS session's agent — Р13, §4.8.
      *