@indigoai-us/hq-cli 5.345.174 → 5.345.175

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.345.175] — 2026-10-28
+- A local bot whose coding tool crashed before it could start on a message (seen as "Claude Code stopped with an error" on the first message after a day or more idle) now tries that message once more on its own. If it crashes again, the reply carries a Heal bot card so HQ can restart the bot and send the message again, and the bot's log and `hq bot status` record what the tool printed, how long it ran and which binary it was, so the cause can be found.
+- `hq dm --attach` after a person `hq login` looks up the caller's `prs_` uid
+  when the session token has no `custom:entityUid` (human tokens never carry
+  that claim). Plain `hq dm` already worked; attaching a file no longer fails
+  with "Could not read your person uid from the session token".
+
 ## [5.345.174] — 2026-10-27
 - `hq channels delete <name> --yes` deletes a channel you own, including its
   messages. Group DMs stay undeletable. Without `--yes` the command refuses.

package/dist/commands/bot.js

@@ -1257,6 +1257,9 @@ async function runBotStatus(nameArg, opts) {
         if (status.modelHold && new Date(status.modelHold.until).getTime() > Date.now()) {
             console.log(`  ${chalk.yellow(`holding until ${status.modelHold.until}`)} after repeated model failures; the next message after that runs again`);
         }
+        if (status.lastCrash) {
+            console.log(`  last crash: ${chalk.yellow(`${status.lastCrash.at}, exit ${status.lastCrash.code ?? "?"}${status.lastCrash.durationMs !== undefined ? ` after ${status.lastCrash.durationMs} ms` : ""}`)}`);
+        }
         if (status.runtimeModelFallback) {
             console.log(`  model:      ${chalk.yellow(`running on ${status.runtimeModelFallback.to}`)} because ${row.runtime} here is too old for ${status.runtimeModelFallback.from || "its configured model"}; update ${row.runtime} to use it`);
         }

package/dist/commands/dm.d.ts

@@ -392,6 +392,13 @@ export interface CallerIdentity {
  * Pure → unit-testable.
  */
 export declare function callerFromToken(token: string): CallerIdentity;
+/**
+ * Vault scope uid for `--attach`. Human Cognito sessions do not carry
+ * `custom:entityUid` (hq-pro sets that only on agent and outpost tokens), so
+ * JWT peek is not enough after a normal `hq login`. Fall back to the
+ * canonical person lookup used by `--personal` files and secrets.
+ */
+export declare function callerUidForAttach(token: string): Promise<string>;
 /**
  * Newest-first channel history → the caller's most recent top-level eventId.
  * Replies (those with rootEventId) are skipped. Pure → unit-testable.

package/dist/commands/dm.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { resolveDestinationCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { resolveCallerPersonUid, resolveDestinationCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { isMachineIdentity } from "@indigoai-us/hq-cloud";
 import { peekIdToken } from "../utils/id-token.js";
 import { redactAgentInboxItem as redactInboxCredentials } from "../lib/agent-kit/inbox-redact.js";
@@ -792,9 +792,9 @@ async function runChannelSend(channelName, message, opts) {
         // personal channels in the caller's personal vault.
         let uploaded = [];
         if (localFiles.length > 0) {
-            const callerUid = callerFromToken(token).personUid;
+            const callerUid = await callerUidForAttach(token);
             const scopeUid = channel.companyUid?.trim()
-                ? attachmentScopeForChannel(channel, callerUid ?? "")
+                ? attachmentScopeForChannel(channel, callerUid)
                 : personalScopeForCaller(callerUid);
             uploaded = await uploadDmAttachments({
                 token,
@@ -989,7 +989,7 @@ async function runDmSend(recipient, message, rawOpts) {
         if (localFiles.length > 0) {
             // A 1:1 attachment is stored in the SENDER's personal vault under the
             // sorted participant pair; the server lets either member read it.
-            const callerUid = callerFromToken(token).personUid;
+            const callerUid = await callerUidForAttach(token);
             const scopeUid = personalScopeForCaller(callerUid);
             const peerUid = await resolveDmPeerUid(token, recipient);
             uploaded = await uploadDmAttachments({
@@ -1363,6 +1363,18 @@ export function callerFromToken(token) {
         ...(emailNorm ? { email: emailNorm } : {}),
     };
 }
+/**
+ * Vault scope uid for `--attach`. Human Cognito sessions do not carry
+ * `custom:entityUid` (hq-pro sets that only on agent and outpost tokens), so
+ * JWT peek is not enough after a normal `hq login`. Fall back to the
+ * canonical person lookup used by `--personal` files and secrets.
+ */
+export async function callerUidForAttach(token) {
+    const fromJwt = callerFromToken(token).personUid;
+    if (fromJwt)
+        return fromJwt;
+    return resolveCallerPersonUid(token, undefined, { command: "hq dm --attach" });
+}
 function isCallerMessage(m, me) {
     if (me.personUid && m.fromPersonUid === me.personUid)
         return true;

package/dist/lib/bot/run.d.ts

@@ -85,6 +85,8 @@ export declare const FAILURE_WINDOW_MS: number;
 export declare const FAILURE_LIMIT = 5;
 /** Resumed-session failures with the model CLI's unknown error, in a row, before the session is cleared. */
 export declare const RESUMED_UNKNOWN_ERROR_LIMIT = 2;
+/** Wait before the one automatic re-run of a turn whose runtime crashed before it started. */
+export declare const RUNTIME_CRASH_RETRY_DELAY_MS = 3000;
 export declare const MAX_ATTEMPTS_PER_MESSAGE = 3;
 export declare const THINKING_EMOJI = "\uD83D\uDC40";
 export declare const ROOM_THINKING_STATUS = "is thinking\u2026";

package/dist/lib/bot/run.js

@@ -129,6 +129,8 @@ export const FAILURE_WINDOW_MS = 10 * 60 * 1000;
 export const FAILURE_LIMIT = 5;
 /** Resumed-session failures with the model CLI's unknown error, in a row, before the session is cleared. */
 export const RESUMED_UNKNOWN_ERROR_LIMIT = 2;
+/** Wait before the one automatic re-run of a turn whose runtime crashed before it started. */
+export const RUNTIME_CRASH_RETRY_DELAY_MS = 3_000;
 /** The model CLI's own message, exactly; "Unexpected token" in a stack trace is not it. */
 const RESUMED_UNKNOWN_ERROR = /an unknown error occurred \(unexpected\)/i;
 export const MAX_ATTEMPTS_PER_MESSAGE = 3;
@@ -693,7 +695,7 @@ export async function runBot(deps) {
         // nothing while their next messages wait out the hold.
         if (tell) {
             try {
-                await tell(holdNoticeText(modelHoldMs, messagePending, cls ? runtimeFailureText(cls, runtime.id) : undefined));
+                await tell(holdNoticeText(modelHoldMs, messagePending, cls ? runtimeFailureText(cls, runtime.id, "message", config.name) : undefined));
             }
             catch (err) {
                 log("warn", `could not say that turns are on hold: ${err instanceof Error ? err.message : String(err)}`);
@@ -1039,16 +1041,35 @@ export async function runBot(deps) {
             }
             return turn;
         };
-        const session = readBotSession(dir, config.runtime, sessionScope);
+        const attemptOnce = async () => {
+            const session = readBotSession(dir, config.runtime, sessionScope);
+            try {
+                return await runAttempt(session, await composePrompt(session));
+            }
+            catch (err) {
+                if (!missingResumedSession(err))
+                    throw err;
+                clearBotSession(dir, sessionScope);
+                log("warn", "saved model session is gone; starting a new one with recent DM history");
+                return await runAttempt(null, await composePrompt(null));
+            }
+        };
         try {
-            return await runAttempt(session, await composePrompt(session));
+            return await attemptOnce();
         }
         catch (err) {
-            if (!missingResumedSession(err))
+            // The coding tool's process died before the turn started (Bun's
+            // "error: An unknown error occurred (Unexpected)" after a long idle,
+            // October 2026). A fresh process usually works: wait a moment and run
+            // the same turn once more. If that fails too, the caller's normal
+            // failure path tells the person (with the Heal bot card).
+            if (stream.signal?.aborted || classifyRuntimeError(err) !== "runtime-crashed")
                 throw err;
-            clearBotSession(dir, sessionScope);
-            log("warn", "saved model session is gone; starting a new one with recent DM history");
-            return await runAttempt(null, await composePrompt(null));
+            log("info", "runtime crashed before the turn started; retrying once");
+            await sleep(RUNTIME_CRASH_RETRY_DELAY_MS, stream.signal);
+            if (stream.signal?.aborted)
+                throw err;
+            return await attemptOnce();
         }
     };
     /** Failure bookkeeping shared by every model turn: window, health, status, log, stale session. */
@@ -1059,7 +1080,20 @@ export async function runBot(deps) {
         const count = failures.record(now().getTime());
         modelHealth = count >= FAILURE_LIMIT ? "failed" : "degraded";
         setStatus({ restarts: (readStatus()?.restarts ?? 0) + 1, recentFailures: count, lastError: excerpt.slice(0, 400) });
-        log("error", `model turn failed (${count}/${FAILURE_LIMIT} in window, ${classifyRuntimeError(err)}): ${excerpt}`);
+        const cls = classifyRuntimeError(err);
+        log("error", `model turn failed (${count}/${FAILURE_LIMIT} in window, ${cls}): ${excerpt}`);
+        if (cls === "runtime-crashed" && err instanceof RuntimeError) {
+            const stderr = (err.stderrFull ?? err.stderrExcerpt).slice(0, 2000);
+            log("error", `runtime crash evidence: exit ${err.exitCode ?? "?"}, lived ${err.durationMs ?? "?"} ms, binary ${err.binaryPath ?? runtime.binary}; stderr: ${JSON.stringify(stderr)}; stdout head: ${JSON.stringify((err.stdoutHead ?? "").slice(0, 300))}`);
+            setStatus({
+                lastCrash: {
+                    at: now().toISOString(),
+                    code: err.exitCode,
+                    ...(err.durationMs !== undefined ? { durationMs: err.durationMs } : {}),
+                    stderr,
+                },
+            });
+        }
         // A resumed session that no longer exists must not poison every turn: the
         // next turn starts fresh with the recent DM history prepended. The model
         // CLI's "An unknown error occurred (Unexpected)" (every turn of a
@@ -1683,7 +1717,7 @@ export async function runBot(deps) {
                 runtime: runtime.id,
                 botName: config.name,
                 context: "kickoff",
-                ...(outcome.started && poster.postedCount > 0 ? { text: runtimeDidNotFinishText(cls, runtime.id, true) } : {}),
+                ...(outcome.started && poster.postedCount > 0 ? { text: runtimeDidNotFinishText(cls, runtime.id, true, config.name) } : {}),
             });
         try {
             await postRepair(target, notice);
@@ -1852,7 +1886,7 @@ export async function runBot(deps) {
             }
             // A missing tool does not come back between retries: say so now.
             if (attempt >= MAX_ATTEMPTS_PER_MESSAGE || cls === "not-installed") {
-                const plain = runtimeFailureText(cls, runtime.id);
+                const plain = runtimeFailureText(cls, runtime.id, "message", config.name);
                 await sendToPerson(`I couldn't run this one. ${plain}`).catch(() => undefined);
                 await completeJobRun(jobId, id, { status: "failed", output: jobRunOutput(plain), disposition: `${runtime.id} could not be started` });
                 markReported("failed");
@@ -1872,12 +1906,12 @@ export async function runBot(deps) {
         // reports and says this real reason, not "the bot was restarted".
         // What the cloud stores as the run's output: plain words, never the raw
         // runtime text (that is in the bot log and status.json).
-        const jobOutput = outcome.aborted ? `${STOPPED_BY_OWNER_REASON}.` : runtimeFailureText(failureClass(outcome), runtime.id);
+        const jobOutput = outcome.aborted ? `${STOPPED_BY_OWNER_REASON}.` : runtimeFailureText(failureClass(outcome), runtime.id, "message", config.name);
         patchInflight(dir, id, { jobFailure: { reason, output: jobOutput } });
         try {
             await sendToPerson(outcome.aborted
                 ? didNotFinishText(reason, poster.postedCount > 0)
-                : runtimeDidNotFinishText(failureClass(outcome), runtime.id, poster.postedCount > 0));
+                : runtimeDidNotFinishText(failureClass(outcome), runtime.id, poster.postedCount > 0, config.name));
         }
         catch (err) {
             // Leave it un-acked with the marker: the next poll reports it.
@@ -2381,7 +2415,7 @@ export async function runBot(deps) {
                     runtime: runtime.id,
                     botName: config.name,
                     context: "message",
-                    text: runtimeDidNotFinishText(cls, runtime.id, poster.postedCount > 0),
+                    text: runtimeDidNotFinishText(cls, runtime.id, poster.postedCount > 0, config.name),
                     retryOf: item.eventId ?? id,
                 }), item.rootEventId);
             }

package/dist/lib/bot/runtime/index.js

@@ -394,12 +394,15 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     let modelFallback = remembered ? { from: remembered.from, to: remembered.to } : undefined;
     /** The retries on supported models failed too: report the first failure (its cause is the old CLI). */
     let fallbackFailure;
+    let spawnedAt = nowMs();
     try {
         result = await spawnImpl(binary, args, spawnOptions);
         if (runtime.id === "grok" && result.code !== 0 && !input.signal?.aborted) {
             const retryArgs = grokRetryArgsAfterInvalidOutputFormat(args, result.stderr);
-            if (retryArgs)
+            if (retryArgs) {
+                spawnedAt = nowMs();
                 result = await spawnImpl(binary, retryArgs, spawnOptions);
+            }
         }
         if (remembered) {
             // A turn on the remembered model: it either still works or the memo is wrong.
@@ -439,6 +442,7 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
                         continue;
                     tried.push(to);
                     const retryArgs = runtime.buildArgs({ ...turnInput, model: to }, { outputFile, newSessionId });
+                    spawnedAt = nowMs();
                     const retry = await spawnImpl(binary, retryArgs, spawnOptions);
                     if (input.signal?.aborted) {
                         // The owner stopped it: report the stop, remember nothing.
@@ -493,6 +497,11 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
         }
     }
     if (result.code !== 0 || result.signal) {
+        const durationMs = Math.max(0, nowMs() - spawnedAt);
+        const sawStreamEvent = result.stdout.split("\n").some((line) => {
+            const ev = parseJsonLine(line);
+            return ev !== null && (ev.type === "system" || ev.type === "assistant" || ev.type === "result");
+        });
         const reason = runtime.failureReason?.(result.stdout, result.stderr);
         // Streaming runtimes write JSON events to stdout: never show those to a
         // person as the reason. stderr, then a plain description, instead.
@@ -505,7 +514,14 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
                 : result.signal
                     ? `the ${runtime.binary} process was killed (${result.signal})`
                     : `${runtime.binary} exited with code ${result.code}`;
-        throw new RuntimeError(`${runtime.binary} exited with ${result.code ?? `signal ${result.signal}`}${reason ? `: ${reason.slice(0, 200)}` : ""}${fallbackFailure ? ` (${fallbackFailure})` : ""}`, reason ? reason.slice(0, 400) : fallback, result.code, !reason && stdoutTail ? { excerptIsOutputTail: true } : {});
+        throw new RuntimeError(`${runtime.binary} exited with ${result.code ?? `signal ${result.signal}`}${reason ? `: ${reason.slice(0, 200)}` : ""}${fallbackFailure ? ` (${fallbackFailure})` : ""}`, reason ? reason.slice(0, 400) : fallback, result.code, {
+            ...(!reason && stdoutTail ? { excerptIsOutputTail: true } : {}),
+            durationMs,
+            sawStreamEvent,
+            binaryPath: binary,
+            stderrFull: result.stderr.slice(0, 2000),
+            stdoutHead: result.stdout.slice(0, 300),
+        });
     }
     const parsed = runtime.parseOutput(result.stdout, { outputFile, outputFileText });
     // A turn that ran on the requested model and succeeded: nothing to remember.

package/dist/lib/bot/runtime/types.d.ts

@@ -128,10 +128,23 @@ export declare class RuntimeError extends Error {
      * must never decide what went wrong; only the message may.
      */
     readonly excerptIsOutputTail: boolean;
+    /** How long the runtime process lived, in ms, when known. */
+    readonly durationMs: number | undefined;
+    /** True when stdout carried at least one stream event (`system`, `assistant`, `result`): the turn started. */
+    readonly sawStreamEvent: boolean;
+    /** Crash evidence for the bot log: the binary spawned, full stderr and the head of stdout (bounded). */
+    readonly binaryPath: string | undefined;
+    readonly stderrFull: string | undefined;
+    readonly stdoutHead: string | undefined;
     constructor(message: string, stderrExcerpt: string, exitCode: number | null, opts?: {
         started?: boolean;
         aborted?: boolean;
         excerptIsOutputTail?: boolean;
+        durationMs?: number;
+        sawStreamEvent?: boolean;
+        binaryPath?: string;
+        stderrFull?: string;
+        stdoutHead?: string;
     });
 }
 export interface BotRuntime {

package/dist/lib/bot/runtime/types.js

@@ -19,6 +19,14 @@ export class RuntimeError extends Error {
      * must never decide what went wrong; only the message may.
      */
     excerptIsOutputTail;
+    /** How long the runtime process lived, in ms, when known. */
+    durationMs;
+    /** True when stdout carried at least one stream event (`system`, `assistant`, `result`): the turn started. */
+    sawStreamEvent;
+    /** Crash evidence for the bot log: the binary spawned, full stderr and the head of stdout (bounded). */
+    binaryPath;
+    stderrFull;
+    stdoutHead;
     constructor(message, stderrExcerpt, exitCode, opts = {}) {
         super(message);
         this.stderrExcerpt = stderrExcerpt;
@@ -27,6 +35,11 @@ export class RuntimeError extends Error {
         this.started = opts.started ?? true;
         this.aborted = opts.aborted ?? false;
         this.excerptIsOutputTail = opts.excerptIsOutputTail ?? false;
+        this.durationMs = opts.durationMs;
+        this.sawStreamEvent = opts.sawStreamEvent ?? false;
+        this.binaryPath = opts.binaryPath;
+        this.stderrFull = opts.stderrFull;
+        this.stdoutHead = opts.stdoutHead;
     }
 }
 /**

package/dist/lib/bot/runtime-failure.d.ts

@@ -27,16 +27,27 @@ export type RuntimeFailureClass =
  | "transient"
 /** The tool is not installed (or not on PATH) on this computer. */
  | "not-installed"
+/** The tool's process exited before the turn started (e.g. Bun's "error: ... (Unexpected)"). A restart heals it. */
+ | "runtime-crashed"
 /** Anything else. Neutral copy; never blames the sign-in. */
  | "unknown";
-/** The four classes that get a repair card in the DM. */
-export type RuntimeRepairClass = Extract<RuntimeFailureClass, "signed-out" | "cli-outdated" | "model-unsupported" | "transient">;
+/** The classes that get a repair card in the DM. */
+export type RuntimeRepairClass = Extract<RuntimeFailureClass, "signed-out" | "cli-outdated" | "model-unsupported" | "transient" | "runtime-crashed">;
 /** The one thing the person can do about it. The desktop maps each to a button. */
-export type RuntimeRepairAction = "signIn" | "update" | "switchModel" | "tryAgain";
+export type RuntimeRepairAction = "signIn" | "update" | "switchModel" | "tryAgain" | "restart";
 export declare const RUNTIME_REPAIR_ACTIONS: Record<RuntimeRepairClass, RuntimeRepairAction>;
 export declare function isRuntimeRepairClass(cls: RuntimeFailureClass): cls is RuntimeRepairClass;
 /** Sort a runtime's failure text into one class. Order matters: most specific first. */
 export declare function classifyRuntimeFailure(text: string | undefined | null): RuntimeFailureClass;
+export declare function isBunProcessError(text: string | undefined | null): boolean;
+/** A process that exits non-zero this soon, with no stream event, never started its turn. */
+export declare const RUNTIME_CRASH_MAX_MS = 5000;
+/**
+ * True when the coding tool's process exited before the turn started: a
+ * non-zero exit code, not stopped by the owner, no stream event on stdout,
+ * and either Bun's process error shape on stderr or a life under 5 s.
+ */
+export declare function isRuntimeCrash(err: unknown): boolean;
 /**
  * Class of a failed turn's error. A RuntimeError's excerpt (the runtime's own
  * reported error: failureReason, turn.failed, stderr) is the better evidence;
@@ -57,11 +68,11 @@ export type RuntimeFailureContext = "kickoff" | "message";
  */
 export declare function runtimeFailureReason(cls: RuntimeFailureClass, runtime: BotRuntimeId | string): string;
 /** The one next step, as a full sentence. */
-export declare function runtimeFailureNextStep(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, context?: RuntimeFailureContext): string;
+export declare function runtimeFailureNextStep(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, context?: RuntimeFailureContext, botName?: string): string;
 /** "My Codex app is out of date. Update Codex, then send me any message." */
-export declare function runtimeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, context?: RuntimeFailureContext): string;
+export declare function runtimeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, context?: RuntimeFailureContext, botName?: string): string;
 /** A failure after the model started (and maybe posted part of the answer). */
-export declare function runtimeDidNotFinishText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, progressPosted: boolean): string;
+export declare function runtimeDidNotFinishText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, progressPosted: boolean, botName?: string): string;
 /**
  * The machine-readable repair payload a failure DM carries. The DM transport
  * (POST /v1/notify/dm) stores structured data only in `richContent`

package/dist/lib/bot/runtime-failure.js

@@ -21,6 +21,7 @@ export const RUNTIME_REPAIR_ACTIONS = {
     "cli-outdated": "update",
     "model-unsupported": "switchModel",
     transient: "tryAgain",
+    "runtime-crashed": "restart",
 };
 export function isRuntimeRepairClass(cls) {
     return cls in RUNTIME_REPAIR_ACTIONS;
@@ -61,6 +62,38 @@ export function classifyRuntimeFailure(text) {
         return "transient";
     return "unknown";
 }
+/**
+ * Bun's process-level error line (Claude Code is a Bun-compiled binary):
+ * "error: An unknown error occurred (Unexpected)". The excerpt joins stderr
+ * lines with " | ", so each segment is checked on its own.
+ */
+const BUN_PROCESS_ERROR = /^error: .+ \((?:Unexpected|[A-Z][A-Za-z]+)\)\s*$/m;
+export function isBunProcessError(text) {
+    return (text ?? "")
+        .split(/\n| \| /)
+        .some((segment) => BUN_PROCESS_ERROR.test(segment.trim()));
+}
+/** A process that exits non-zero this soon, with no stream event, never started its turn. */
+export const RUNTIME_CRASH_MAX_MS = 5_000;
+function bunShaped(e) {
+    return (isBunProcessError(typeof e.stderrExcerpt === "string" ? e.stderrExcerpt : "") ||
+        isBunProcessError(typeof e.stderrFull === "string" ? e.stderrFull : ""));
+}
+/**
+ * True when the coding tool's process exited before the turn started: a
+ * non-zero exit code, not stopped by the owner, no stream event on stdout,
+ * and either Bun's process error shape on stderr or a life under 5 s.
+ */
+export function isRuntimeCrash(err) {
+    if (!err || typeof err !== "object" || !("stderrExcerpt" in err))
+        return false;
+    const e = err;
+    if (typeof e.exitCode !== "number" || e.exitCode === 0)
+        return false;
+    if (e.aborted === true || e.sawStreamEvent === true)
+        return false;
+    return bunShaped(e) || (typeof e.durationMs === "number" && e.durationMs < RUNTIME_CRASH_MAX_MS);
+}
 /**
  * Class of a failed turn's error. A RuntimeError's excerpt (the runtime's own
  * reported error: failureReason, turn.failed, stderr) is the better evidence;
@@ -73,12 +106,20 @@ export function classifyRuntimeError(err) {
     if (err && typeof err === "object" && "stderrExcerpt" in err) {
         const e = err;
         const message = typeof e.message === "string" ? e.message : "";
-        if (e.excerptIsOutputTail === true)
-            return classifyRuntimeFailure(message);
+        const crashed = isRuntimeCrash(err);
+        // Bun's own process error is the most specific evidence there is.
+        if (crashed && bunShaped(err))
+            return "runtime-crashed";
+        if (e.excerptIsOutputTail === true) {
+            const fromTailMessage = classifyRuntimeFailure(message);
+            return fromTailMessage === "unknown" && crashed ? "runtime-crashed" : fromTailMessage;
+        }
         const fromExcerpt = classifyRuntimeFailure(typeof e.stderrExcerpt === "string" ? e.stderrExcerpt : "");
         if (fromExcerpt !== "unknown")
             return fromExcerpt;
-        return classifyRuntimeFailure(message);
+        const fromMessage = classifyRuntimeFailure(message);
+        // A quick exit with no known cause: the process died before the turn.
+        return fromMessage === "unknown" && crashed ? "runtime-crashed" : fromMessage;
     }
     return classifyRuntimeFailure(err instanceof Error ? err.message : String(err ?? ""));
 }
@@ -106,14 +147,18 @@ export function runtimeFailureReason(cls, runtime) {
             return `${tool} is busy or out of reach right now`;
         case "not-installed":
             return `${tool} isn't installed on this computer`;
+        case "runtime-crashed":
+            return `my ${tool} process could not start`;
         default:
             return `${tool} stopped with an error`;
     }
 }
 /** The one next step, as a full sentence. */
-export function runtimeFailureNextStep(cls, runtime, context = "message") {
+export function runtimeFailureNextStep(cls, runtime, context = "message", botName) {
     const tool = runtimeDisplayName(runtime);
     switch (cls) {
+        case "runtime-crashed":
+            return `Press "Heal bot" in HQ, or run: hq bot restart ${botName ?? "<bot>"}`;
         case "signed-out":
             return `Use "Sign in to ${tool}" in HQ, then send me any message.`;
         case "cli-outdated":
@@ -136,12 +181,12 @@ function capitalize(s) {
     return s ? s[0].toUpperCase() + s.slice(1) : s;
 }
 /** "My Codex app is out of date. Update Codex, then send me any message." */
-export function runtimeFailureText(cls, runtime, context = "message") {
-    return `${capitalize(runtimeFailureReason(cls, runtime))}. ${runtimeFailureNextStep(cls, runtime, context)}`;
+export function runtimeFailureText(cls, runtime, context = "message", botName) {
+    return `${capitalize(runtimeFailureReason(cls, runtime))}. ${runtimeFailureNextStep(cls, runtime, context, botName)}`;
 }
 /** A failure after the model started (and maybe posted part of the answer). */
-export function runtimeDidNotFinishText(cls, runtime, progressPosted) {
-    return `I didn't finish that. ${runtimeFailureText(cls, runtime)}${progressPosted ? " The messages above show how far I got." : ""}`;
+export function runtimeDidNotFinishText(cls, runtime, progressPosted, botName) {
+    return `I didn't finish that. ${runtimeFailureText(cls, runtime, "message", botName)}${progressPosted ? " The messages above show how far I got." : ""}`;
 }
 export function runtimeRepairBlock(args) {
     return {
@@ -177,7 +222,7 @@ export function withRetrySuggestion(text) {
  * press.
  */
 export function runtimeRepairNotice(args) {
-    const text = args.text ?? runtimeFailureText(args.cls, args.runtime, args.context);
+    const text = args.text ?? runtimeFailureText(args.cls, args.runtime, args.context, args.botName);
     if (!isRuntimeRepairClass(args.cls))
         return { cls: args.cls, text };
     return {

package/dist/lib/bot/status.d.ts

@@ -55,6 +55,16 @@ export interface BotStatusFile {
         to: string;
         at: string;
     } | null;
+    /**
+     * The last time the coding tool's process exited before its turn started
+     * (runtime-crashed): when, exit code, how long it lived, and its stderr.
+     */
+    lastCrash?: {
+        at: string;
+        code: number | null;
+        durationMs?: number;
+        stderr: string;
+    };
     /**
      * Set while the bot holds its model turns after FAILURE_LIMIT failures in a
      * window (it used to exit instead, and a bot that exited could neither load

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.174",
+  "version": "5.345.175",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.174",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.174",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.174",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.174",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.174",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.174"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.175",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.175",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.175",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.175",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.175",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.175"
   }
 }