@bridge4dev/runner 0.36.0 → 0.38.0

package/dist/agent-binary.d.ts

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

package/dist/agent-binary.js

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

package/dist/index.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { ClaudeAdapter } from './adapters/claude.js';
 import { CodexAdapter } from './adapters/codex.js';
 import { ensureCodexHome } from './adapters/codex-home.js';
+import { claudeCliPath } from './agent-binary.js';
 import { loadConfig, requireConfig, saveConfig } from './config.js';
 import { log } from './log.js';
 import { installIsWritable, installPrefixFor, isSupervisedProcess, manualUpdateCommand, resolveInstalledPackageDir, } from './self-update.js';
@@ -62,8 +63,14 @@ function argValue(args, flag) {
  */
 function installedAgents() {
     const agents = [];
-    // Claude is bundled inside the Agent SDK, so it is always available.
-    agents.push('claude');
+    // Claude comes with the Agent SDK — but «comes with» is a claim about THIS
+    // installation, not a law (ticket #225). The CLI is an optional platform
+    // package, and an update that silently lost it leaves a runner that reports
+    // Claude, accepts Claude sessions, and cannot start a single one. Reported as
+    // measured, so the dashboard greys the agent out instead of offering a
+    // session that dies before its first word.
+    if (claudeCliPath())
+        agents.push('claude');
     if (hasExecutable('codex'))
         agents.push('codex');
     return agents;
@@ -389,6 +396,11 @@ function runnerCapabilities(apiUrlOverride) {
             'agent_prompt_state',
             'propose_commit_message',
             'recall_message',
+            // The answer to a parked question, as a command that ANSWERS rather than
+            // a frame written into a socket and hoped for. Announced here because
+            // this list is what `runCommand` actually dispatches on, and the API
+            // falls back to the old frame for runners that do not name it.
+            'answer_question',
             'compact_context',
             ...(checkpointsEnabled
                 ? [

package/dist/protocol.d.ts

@@ -272,6 +272,78 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     workMode?: unknown;
 }>;
 export type SessionDescriptor = z.infer<typeof SessionDescriptorSchema>;
+/**
+ * One human answer to a parked agent question, minus the session it belongs to.
+ *
+ * Written once and used twice on purpose: as the body of the `question_answer`
+ * frame every runner since 0.14 understands, and as the arguments of the
+ * `answer_question` COMMAND that replaced it (session 18). The two must not
+ * drift — an answer that the frame accepts and the command rejects would fail
+ * exactly on the machines whose connection is bad enough to need the command.
+ */
+export declare const QuestionAnswerShape: {
+    readonly askId: z.ZodString;
+    readonly action: z.ZodEnum<["answer", "discuss"]>;
+    readonly answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        questionId: z.ZodString;
+        values: z.ZodArray<z.ZodString, "many">;
+        custom: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }, {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }>, "many">>;
+    readonly text: z.ZodOptional<z.ZodString>;
+};
+/** The `answer_question` command's arguments — the shape above on its own. */
+export declare const QuestionAnswerArgsSchema: z.ZodObject<{
+    readonly askId: z.ZodString;
+    readonly action: z.ZodEnum<["answer", "discuss"]>;
+    readonly answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        questionId: z.ZodString;
+        values: z.ZodArray<z.ZodString, "many">;
+        custom: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }, {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }>, "many">>;
+    readonly text: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    askId: string;
+    action: "answer" | "discuss";
+    text?: string | undefined;
+    answers?: {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }[] | undefined;
+}, {
+    askId: string;
+    action: "answer" | "discuss";
+    text?: string | undefined;
+    answers?: {
+        values: string[];
+        questionId: string;
+        custom?: string | undefined;
+        notes?: string | undefined;
+    }[] | undefined;
+}>;
 export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"hello_ack">;
     serverId: z.ZodString;
@@ -1104,8 +1176,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     requestId: string;
     note?: string | undefined;
 }>, z.ZodObject<{
-    type: z.ZodLiteral<"question_answer">;
-    sessionId: z.ZodString;
     askId: z.ZodString;
     action: z.ZodEnum<["answer", "discuss"]>;
     answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1125,6 +1195,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         notes?: string | undefined;
     }>, "many">>;
     text: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"question_answer">;
+    sessionId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
     type: "question_answer";

package/dist/protocol.js

@@ -183,6 +183,31 @@ export const SessionDescriptorSchema = z.object({
     // project). Preferred over the [mcp] section of config.toml when present.
     mcp: z.object({ url: z.string().url(), token: z.string().min(1) }).optional(),
 });
+/**
+ * One human answer to a parked agent question, minus the session it belongs to.
+ *
+ * Written once and used twice on purpose: as the body of the `question_answer`
+ * frame every runner since 0.14 understands, and as the arguments of the
+ * `answer_question` COMMAND that replaced it (session 18). The two must not
+ * drift — an answer that the frame accepts and the command rejects would fail
+ * exactly on the machines whose connection is bad enough to need the command.
+ */
+export const QuestionAnswerShape = {
+    askId: z.string().min(1).max(64),
+    action: z.enum(['answer', 'discuss']),
+    answers: z
+        .array(z.object({
+        questionId: z.string().min(1).max(120),
+        values: z.array(z.string().max(2_000)).max(16),
+        custom: z.string().max(10_000).optional(),
+        notes: z.string().max(2_000).optional(),
+    }))
+        .max(4)
+        .optional(),
+    text: z.string().max(20_000).optional(),
+};
+/** The `answer_question` command's arguments — the shape above on its own. */
+export const QuestionAnswerArgsSchema = z.object(QuestionAnswerShape);
 export const GatewayFrameSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('hello_ack'),
@@ -238,18 +263,7 @@ export const GatewayFrameSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('question_answer'),
         sessionId: z.string().uuid(),
-        askId: z.string().min(1).max(64),
-        action: z.enum(['answer', 'discuss']),
-        answers: z
-            .array(z.object({
-            questionId: z.string().min(1).max(120),
-            values: z.array(z.string().max(2_000)).max(16),
-            custom: z.string().max(10_000).optional(),
-            notes: z.string().max(2_000).optional(),
-        }))
-            .max(4)
-            .optional(),
-        text: z.string().max(20_000).optional(),
+        ...QuestionAnswerShape,
     }),
     z.object({ type: z.literal('session_stop'), sessionId: z.string().uuid() }),
     z.object({ type: z.literal('session_interrupt'), sessionId: z.string().uuid() }),

package/dist/self-update.js

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

package/dist/supervisor.d.ts

@@ -19,6 +19,12 @@ export interface SupervisorOptions {
     runnerToken?: string;
     /** Test seam for the `self_update` command. */
     selfUpdate?: typeof selfUpdate;
+    /**
+     * How long a freshly started agent process may say nothing before the session
+     * says so out loud (ticket #225). Test seam — the default is a minute, and a
+     * test that had to wait one would not be written.
+     */
+    startupSilenceMs?: number;
     /**
      * Called after a successful update, once the reply is on the wire. The daemon
      * exits here and systemd starts the new build; without a handler the runner
@@ -113,11 +119,53 @@ export declare class Supervisor {
      * free CHAT session with no prompt at all (the agent boots, reports its
      * capabilities and waits for the first message).
      *
-     * Returns whether an agent process actually started: a caller holding a user
-     * message needs to know, because a refused launch means the message has to
-     * stay queued rather than be marked delivered (session 9).
+     * Returns what came of it: a caller holding a user message needs to know,
+     * because anything but `ok` means the message has to stay queued rather than
+     * be marked delivered (session 9).
+     *
+     * NEVER throws (ticket #225). Everything from reading the project prompt to
+     * the adapter's own constructor runs inside one guard, because the caller
+     * chain above cannot tell the difference between «did not start» and
+     * «threw»: the message path swallows the exception into a log line, and the
+     * reconnect path lets it abort the restore of every OTHER session on the
+     * machine. A launch that fails is a state this session reports, not an
+     * exception somebody else has to remember to catch.
      */
     private launchAgent;
+    /**
+     * The agent process could not be started at all (ticket #225).
+     *
+     * Three things have to happen here, and until this ticket none of them did:
+     * the reason is said WHERE THE PERSON IS LOOKING (an `error` event is the
+     * feed's red line), the session stops claiming to be working, and the stack
+     * reaches journald for whoever has to fix the machine. The status is the
+     * honest one for a session with no process — the agent is not running, and a
+     * session left in `RUNNING` shows a stop button for a turn that does not
+     * exist.
+     *
+     * Never rethrows: this IS the handling. The caller gets `crashed` and decides
+     * what to do with the message it was holding.
+     */
+    private launchCrashed;
+    /** How long a freshly started agent may say nothing before we say so. */
+    private static readonly STARTUP_SILENCE_MS;
+    /**
+     * Watch for the first word out of a process we just started (ticket #225).
+     *
+     * «The adapter object exists» is not «the agent is running». A CLI that hangs
+     * before its first frame — a stuck hook, an MCP server that never answers, a
+     * transcript it cannot read — produces no events, no error and no exit, and
+     * the session sits in `RUNNING` forever. On a healthy launch the first event
+     * arrives in about two seconds, so a minute of silence is not a slow start,
+     * it is something worth saying out loud.
+     *
+     * Says it and stops there: no kill. A long conversation has the right to boot
+     * slowly, and killing it would cost the person the very turn they are waiting
+     * for.
+     */
+    private watchForFirstSignOfLife;
+    /** The process spoke, or went away — either way the watch is over. */
+    private clearStartupWatch;
     /**
      * The project's own prompt file, read fresh for THIS agent process.
      *