@indigoai-us/hq-cli 5.345.75 → 5.345.77

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

@@ -13,8 +13,140 @@
  * Verified against Codex CLI on 2026-09-10 (event names; the model itself
  * cannot run under this machine's account).
  */
-import { parseJsonLine, RuntimeError } from "./types.js";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { MAX_MODEL_FALLBACK_RETRIES, parseJsonLine, RuntimeError } from "./types.js";
 import { resolveRuntimeBinary } from "./windows.js";
+import { versionTooOldModel } from "../runtime-failure.js";
+/**
+ * The model a turn falls back to when the installed Codex is too old for the
+ * one it was asked to use (usually the person's own `model` in
+ * ~/.codex/config.toml, set by a newer Codex app) and the first choice from
+ * Codex's bundled catalog is refused as well. Every Codex CLI since mid 2026
+ * ships it.
+ */
+export const CODEX_PINNED_FALLBACK_MODEL = "gpt-5.5";
+/**
+ * The generation number in a Codex model slug: 6 for "gpt-6-astra", 6.1 for
+ * "gpt-6.1-sol", 5.6 for "gpt-5.6-terra". Undefined when the slug has none
+ * ("codex-auto-review").
+ */
+export function codexModelGeneration(slug) {
+    const m = /^gpt-(\d+(?:\.\d+)?)(?:$|[-.])/i.exec(slug.trim());
+    return m ? Number(m[1]) : undefined;
+}
+/** [0, 147, 0] from "codex-cli 0.147.0". */
+export function parseCodexVersion(text) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(text ?? "");
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+function versionOf(value) {
+    if (typeof value === "string")
+        return parseCodexVersion(value);
+    if (Array.isArray(value) && value.length > 0 && value.every((n) => typeof n === "number" && Number.isFinite(n))) {
+        return value;
+    }
+    return undefined;
+}
+function compareVersions(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * The model Codex itself would offer first that this Codex is most likely to
+ * run, from the JSON of `codex debug models --bundled` (`{ "models": [...] }`
+ * or a bare array). Lowest `priority` wins among the models that are listed
+ * in the picker, not `exclude`d, not newer than `installed` (when the catalog
+ * carries `minimal_client_version`; the real one does not), and of an OLDER
+ * generation than `refused` (gpt-6.1-sol is no better than gpt-6-astra for a
+ * Codex that refuses gpt-6; gpt-5.6-sol is). The bundled catalog of an old
+ * Codex still lists models it cannot run, because the "requires a newer
+ * version" check is the server's, so the generation rule is what matters.
+ */
+export function pickCodexFallbackModel(catalogJson, opts = {}) {
+    let root;
+    try {
+        root = JSON.parse(catalogJson);
+    }
+    catch {
+        return undefined;
+    }
+    const list = Array.isArray(root)
+        ? root
+        : root && typeof root === "object" && Array.isArray(root.models)
+            ? root.models
+            : [];
+    const exclude = new Set((opts.exclude ?? []).filter(Boolean));
+    const refusedGen = opts.refused ? codexModelGeneration(opts.refused) : undefined;
+    const candidates = [];
+    list.forEach((entry, index) => {
+        if (!entry || typeof entry !== "object")
+            return;
+        const m = entry;
+        const slug = typeof m.slug === "string" ? m.slug.trim() : "";
+        if (!slug || exclude.has(slug) || !/^[\w.:/-]{1,128}$/.test(slug))
+            return;
+        if (typeof m.visibility === "string" && m.visibility !== "list")
+            return;
+        if (refusedGen !== undefined) {
+            const gen = codexModelGeneration(slug);
+            if (gen === undefined || gen >= refusedGen)
+                return;
+        }
+        const min = versionOf(m.minimal_client_version);
+        if (min && opts.installed && compareVersions(min, opts.installed) > 0)
+            return;
+        const priority = typeof m.priority === "number" && Number.isFinite(m.priority) ? m.priority : Number.POSITIVE_INFINITY;
+        candidates.push({ slug, priority, index });
+    });
+    candidates.sort((a, b) => a.priority - b.priority || a.index - b.index);
+    return candidates[0]?.slug;
+}
+/**
+ * The models to try, best first, after this Codex refused `failing` as too
+ * new: the best older-generation model from the bundled catalog, then the
+ * pinned fallback. At most MAX_MODEL_FALLBACK_RETRIES, never `failing` itself.
+ * `codex debug models --bundled` reads only the catalog inside the binary: no
+ * network, no sign-in, no cache write.
+ */
+export async function codexFallbackModels(args) {
+    const failing = versionTooOldModel(args.reason) ?? args.requestedModel;
+    const exclude = [failing ?? "", args.requestedModel ?? ""];
+    // With no refused model named, or one whose slug carries no generation, the
+    // catalog cannot say which models are older: the pinned fallback alone.
+    if (!failing || codexModelGeneration(failing) === undefined) {
+        return exclude.includes(CODEX_PINNED_FALLBACK_MODEL) ? [] : [CODEX_PINNED_FALLBACK_MODEL];
+    }
+    const out = [];
+    let installed;
+    try {
+        const v = await args.run(["--version"]);
+        if (v.code === 0)
+            installed = parseCodexVersion(v.stdout);
+    }
+    catch {
+        /* unknown version: the catalog is still filtered by generation and visibility */
+    }
+    try {
+        const catalog = await args.run(["debug", "models", "--bundled"]);
+        if (catalog.code === 0) {
+            const picked = pickCodexFallbackModel(catalog.stdout, { exclude, ...(installed ? { installed } : {}), ...(failing ? { refused: failing } : {}) });
+            if (picked)
+                out.push(picked);
+        }
+    }
+    catch {
+        /* older Codex without `debug models`: the pinned fallback alone */
+    }
+    if (!exclude.includes(CODEX_PINNED_FALLBACK_MODEL) && !out.includes(CODEX_PINNED_FALLBACK_MODEL))
+        out.push(CODEX_PINNED_FALLBACK_MODEL);
+    return out.slice(0, MAX_MODEL_FALLBACK_RETRIES);
+}
 /** Progress events in one codex JSONL line: finished agent messages and tool starts. */
 export function codexStreamEvents(line) {
     const ev = parseJsonLine(line);
@@ -79,11 +211,70 @@ function unwrapApiError(raw) {
     }
     return t;
 }
+export function isExecutableFile(candidate) {
+    try {
+        if (!fs.statSync(candidate).isFile())
+            return false;
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** App bundles that carry the Codex CLI, in the HQ desktop app's lookup order. */
+export const CODEX_APP_BUNDLES = ["ChatGPT.app", "Codex.app"];
+/** Where the CLI sits inside a bundle: current layout first, then the older one. */
+export const CODEX_BUNDLE_CLI_PATHS = [
+    path.join("Contents", "Resources", "codex-cli", "bin", "codex"),
+    path.join("Contents", "Resources", "codex"),
+];
+/**
+ * The Codex CLI shipped inside the ChatGPT or Codex desktop app. A Mac that
+ * only has the desktop app has no `codex` on PATH, yet the HQ app counts it as
+ * installed, so a bot must be able to use it too. Order matches the HQ desktop
+ * app (apps/sync/src-tauri/src/commands/launch.rs, bundled_codex_bin_in):
+ * /Applications before ~/Applications, ChatGPT.app before Codex.app, and the
+ * codex-cli/bin layout before the older Resources/codex one.
+ */
+export function bundledCodexBin(homeDir = os.homedir(), isExecutable = isExecutableFile) {
+    const appDirs = ["/Applications", path.join(homeDir, "Applications")];
+    for (const dir of appDirs) {
+        for (const bundle of CODEX_APP_BUNDLES) {
+            for (const rel of CODEX_BUNDLE_CLI_PATHS) {
+                const candidate = path.join(dir, bundle, rel);
+                if (isExecutable(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+function codexOnPath(env, isExecutable) {
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (dir && isExecutable(path.join(dir, "codex")))
+            return true;
+    }
+    return false;
+}
+/**
+ * PATH wins. On macOS, fall back to the desktop app's bundled CLI. When
+ * nothing is found the bare name is returned, so the spawn fails with the
+ * usual "codex is not installed or not on PATH" error.
+ */
+export function resolveCodexBinary(env, homeDir, platform = process.platform, cwd = process.cwd(), isExecutable = isExecutableFile) {
+    if (platform === "win32")
+        return resolveRuntimeBinary("codex", env, platform, undefined, cwd);
+    if (platform !== "darwin" || codexOnPath(env, isExecutable))
+        return "codex";
+    // `||`, not `??`: an empty HOME must not turn ~/Applications into a relative path.
+    return bundledCodexBin(homeDir || env.HOME || os.homedir(), isExecutable) ?? "codex";
+}
 export function createCodexRuntime() {
     return {
         id: "codex",
         binary: "codex",
-        resolveBinary: (env, cwd, platform) => resolveRuntimeBinary("codex", env, platform ?? process.platform, undefined, cwd),
+        resolveBinary: (env, cwd, platform) => resolveCodexBinary(env, undefined, platform ?? process.platform, cwd),
         buildArgs(input, scratch) {
             const promptArg = input.platform === "win32" ? "-" : codexPrompt(input);
             const common = ["--json", "--skip-git-repo-check", "-o", scratch.outputFile];
@@ -138,7 +329,7 @@ export function createCodexRuntime() {
             const fromFile = extra.outputFileText?.trim();
             const text = (fromFile || lastMessage || "").trim();
             if (!text) {
-                throw new RuntimeError(`codex produced no reply${errorMessage ? `: ${errorMessage.slice(0, 200)}` : ""}`, (errorMessage ?? stdout.slice(-400)).slice(0, 400), null);
+                throw new RuntimeError(`codex produced no reply${errorMessage ? `: ${errorMessage.slice(0, 200)}` : ""}`, (errorMessage ?? stdout.slice(-400)).slice(0, 400), null, errorMessage ? {} : { excerptIsOutputTail: true });
             }
             return { text, sessionId };
         },
@@ -148,6 +339,9 @@ export function createCodexRuntime() {
         failureReason(stdout) {
             return codexFailureReason(stdout);
         },
+        fallbackModelsAfterVersionMismatch(args) {
+            return codexFallbackModels(args);
+        },
     };
 }
 //# sourceMappingURL=codex.js.map

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

@@ -150,12 +150,12 @@ export function createGrokRuntime(opts = {}) {
             if (legacy) {
                 const text = String(legacy.text);
                 if (!text.trim())
-                    throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null);
+                    throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null, { excerptIsOutputTail: true });
                 return { text, sessionId: typeof legacy.sessionId === "string" ? legacy.sessionId : undefined };
             }
             const result = messagesStreamResult(stdout, "grok");
             if (!result.text.trim())
-                throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null);
+                throw new RuntimeError("grok produced no reply", stdout.trim().slice(-400), null, { excerptIsOutputTail: true });
             return result;
         },
         parseStreamLine(line) {

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

@@ -20,6 +20,12 @@ export declare function descendantPids(pid: number, listProcesses?: () => string
 /** After a stop, wait this long for the output pipes to close before settling anyway. */
 export declare const STOP_SETTLE_GRACE_MS = 2000;
 export declare const defaultSpawn: SpawnLike;
+/** Time limit for the short helper commands a turn may run (`--version`, the bundled model catalog). */
+export declare const AUX_COMMAND_TIMEOUT_MS = 20000;
+export declare const MODEL_FALLBACK_RECHECK_MS: number;
+export declare const MODEL_FALLBACK_RECHECK_TURNS = 10;
+/** Test seam. */
+export declare function forgetModelFallbacks(): void;
 export interface RunTurnDeps {
     spawnImpl?: SpawnLike;
     env?: NodeJS.ProcessEnv;
@@ -27,6 +33,8 @@ export interface RunTurnDeps {
     scratchDir?: string;
     newSessionId?: () => string;
     platform?: NodeJS.Platform;
+    /** Clock for the fallback memo (test seam). */
+    now?: () => number;
 }
 /**
  * Run one turn: spawn the runtime CLI, parse the reply, clean up scratch.

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

@@ -9,7 +9,8 @@ import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
 import { stripControlTokens } from "./sanitize.js";
-import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, } from "./types.js";
+import { isRuntimeVersionTooOld, versionTooOldModel } from "../runtime-failure.js";
+import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, MAX_MODEL_FALLBACK_RETRIES, } from "./types.js";
 export * from "./types.js";
 export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
 export { createCodexRuntime, codexPrompt } from "./codex.js";
@@ -317,6 +318,16 @@ export const defaultSpawn = (command, args, options) => new Promise((resolve, re
         });
     });
 });
+/** Time limit for the short helper commands a turn may run (`--version`, the bundled model catalog). */
+export const AUX_COMMAND_TIMEOUT_MS = 20_000;
+const rememberedModelFallbacks = new Map();
+const fallbackKey = (runtime, requestedModel) => `${runtime.id}|${requestedModel ?? ""}`;
+export const MODEL_FALLBACK_RECHECK_MS = 30 * 60_000;
+export const MODEL_FALLBACK_RECHECK_TURNS = 10;
+/** Test seam. */
+export function forgetModelFallbacks() {
+    rememberedModelFallbacks.clear();
+}
 /**
  * Run one turn: spawn the runtime CLI, parse the reply, clean up scratch.
  * Throws RuntimeError (with a bounded stderr excerpt) on any failure.
@@ -327,7 +338,13 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const outputFile = path.join(scratchDir, "last-message.txt");
     const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
     const turnInput = { ...input, platform: deps.platform ?? input.platform ?? process.platform };
-    const args = runtime.buildArgs(turnInput, { outputFile, newSessionId });
+    const nowMs = deps.now ?? Date.now;
+    const memoKey = fallbackKey(runtime, input.model);
+    const memo = rememberedModelFallbacks.get(memoKey);
+    // Time to try the requested model again (the person may have updated the CLI).
+    const recheck = memo !== undefined && (nowMs() - memo.at >= MODEL_FALLBACK_RECHECK_MS || memo.turns >= MODEL_FALLBACK_RECHECK_TURNS);
+    const remembered = memo && !recheck ? memo : undefined;
+    const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     const env = input.env ?? deps.env ?? process.env;
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);
@@ -356,6 +373,9 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
         ...(input.signal ? { signal: input.signal } : {}),
     };
     let result;
+    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;
     try {
         result = await spawnImpl(binary, args, spawnOptions);
         if (runtime.id === "grok" && result.code !== 0 && !input.signal?.aborted) {
@@ -363,6 +383,68 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
             if (retryArgs)
                 result = await spawnImpl(binary, retryArgs, spawnOptions);
         }
+        if (remembered) {
+            // A turn on the remembered model: it either still works or the memo is wrong.
+            if (result.code === 0 && !result.signal)
+                remembered.turns += 1;
+            else if (!input.signal?.aborted)
+                rememberedModelFallbacks.delete(memoKey);
+        }
+        // The installed CLI is too old for the requested model (often the person's
+        // own default, set by a newer app of the same tool). The request was
+        // refused before the model did anything, so run the same turn again on the
+        // models this CLI should support, at most MAX_MODEL_FALLBACK_RETRIES
+        // times, instead of failing the turn.
+        //
+        // On `exec resume` the refused attempt may already have written the user
+        // message into the thread's rollout before the server answered, so the
+        // retry can leave that message twice in a row in the history. Codex has no
+        // way to drop the last message of a thread, and two identical user turns
+        // with nothing between them read as one request, so it is left as is.
+        if ((result.code !== 0 || result.signal) && !input.signal?.aborted && runtime.fallbackModelsAfterVersionMismatch && !remembered) {
+            const reason = runtime.failureReason?.(result.stdout, result.stderr) ?? stderrExcerpt(result.stderr);
+            if (isRuntimeVersionTooOld(reason)) {
+                // Still refused at a recheck: the remembered model is the only candidate (no catalog).
+                const candidates = memo
+                    ? [memo.to]
+                    : await runtime
+                        .fallbackModelsAfterVersionMismatch({
+                        reason,
+                        requestedModel: input.model,
+                        run: (auxArgs) => spawnImpl(binary, auxArgs, { cwd: input.cwd, env, timeoutMs: AUX_COMMAND_TIMEOUT_MS }),
+                    })
+                        .catch(() => []);
+                const from = versionTooOldModel(reason) ?? input.model ?? "";
+                const tried = [];
+                for (const to of candidates.slice(0, MAX_MODEL_FALLBACK_RETRIES)) {
+                    if (!to || to === input.model || tried.includes(to) || input.signal?.aborted)
+                        continue;
+                    tried.push(to);
+                    const retryArgs = runtime.buildArgs({ ...turnInput, model: to }, { outputFile, newSessionId });
+                    const retry = await spawnImpl(binary, retryArgs, spawnOptions);
+                    if (input.signal?.aborted) {
+                        // The owner stopped it: report the stop, remember nothing.
+                        result = retry;
+                        break;
+                    }
+                    if (retry.code === 0 && !retry.signal) {
+                        result = retry;
+                        modelFallback = { from, to };
+                        rememberedModelFallbacks.set(memoKey, { from, to, at: nowMs(), turns: 0 });
+                        fallbackFailure = undefined;
+                        break;
+                    }
+                    // The remembered model no longer works either: forget it.
+                    if (memo && to === memo.to)
+                        rememberedModelFallbacks.delete(memoKey);
+                    const retryReason = runtime.failureReason?.(retry.stdout, retry.stderr) ?? stderrExcerpt(retry.stderr);
+                    fallbackFailure = `${fallbackFailure ? `${fallbackFailure}; ` : ""}retry on ${to} failed too${retryReason ? `: ${retryReason.slice(0, 200)}` : ""}`;
+                    // Only another version refusal is worth the next candidate.
+                    if (!isRuntimeVersionTooOld(retryReason))
+                        break;
+                }
+            }
+        }
     }
     catch (err) {
         const code = err.code;
@@ -397,21 +479,25 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
         // Streaming runtimes write JSON events to stdout: never show those to a
         // person as the reason. stderr, then a plain description, instead.
         const stdoutIsEvents = result.stdout.split("\n").some((line) => parseJsonLine(line) !== null);
+        const stdoutTail = !result.stderr.trim() && Boolean(result.stdout.trim()) && !stdoutIsEvents;
         const fallback = result.stderr.trim()
             ? stderrExcerpt(result.stderr)
-            : result.stdout.trim() && !stdoutIsEvents
+            : stdoutTail
                 ? stderrExcerpt(result.stdout)
                 : 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)}` : ""}`, reason ? reason.slice(0, 400) : fallback, 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 } : {});
     }
     const parsed = runtime.parseOutput(result.stdout, { outputFile, outputFileText });
+    // A turn that ran on the requested model and succeeded: nothing to remember.
+    if (!modelFallback)
+        rememberedModelFallbacks.delete(memoKey);
     // Strip any leaked model control token (`<|eos|>` etc.) from the final reply
     // before it is posted; a reply that was only such tokens becomes empty and the
     // caller applies its normal empty-reply handling.
     const text = stripControlTokens(parsed.text);
     // A resumed session keeps its id even when the CLI omits it from the envelope.
-    return { text, sessionId: parsed.sessionId ?? input.sessionId };
+    return { text, sessionId: parsed.sessionId ?? input.sessionId, ...(modelFallback ? { modelFallback } : {}) };
 }
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/runtime/messages-stream.js

@@ -85,7 +85,7 @@ export function messagesStreamResult(stdout, runtimeName) {
         }
     }
     if (!sawJson)
-        throw new RuntimeError(`${runtimeName} returned non-JSON output`, stdout.trim().slice(-400), null);
+        throw new RuntimeError(`${runtimeName} returned non-JSON output`, stdout.trim().slice(-400), null, { excerptIsOutputTail: true });
     if (result?.is_error === true) {
         const detail = typeof result.result === "string" && result.result ? result.result : String(result.subtype ?? "error");
         throw new RuntimeError(`${runtimeName} reported an error: ${detail.slice(0, 200)}`, detail.slice(0, 400), null);

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

@@ -70,6 +70,16 @@ export type RuntimeStreamEvent = {
 export interface RuntimeTurnResult {
     text: string;
     sessionId?: string;
+    /**
+     * Set when the first attempt failed because the installed CLI is too old for
+     * the model it was asked to use, and the turn was run again on a model this
+     * CLI supports. `from` is the refused model ("" when it came from the CLI's
+     * own config), `to` the one that answered.
+     */
+    modelFallback?: {
+        from: string;
+        to: string;
+    };
 }
 export interface SpawnResult {
     code: number | null;
@@ -106,9 +116,17 @@ export declare class RuntimeError extends Error {
     readonly started: boolean;
     /** True when the turn was ended on purpose (owner stop), not by a model failure. */
     readonly aborted: boolean;
+    /**
+     * True when `stderrExcerpt` is a tail of the runtime's ordinary output, not
+     * an error it reported. Such a tail can contain anything the model printed
+     * ("command not found" from a shell step, a 503 in a fetched page), so it
+     * must never decide what went wrong; only the message may.
+     */
+    readonly excerptIsOutputTail: boolean;
     constructor(message: string, stderrExcerpt: string, exitCode: number | null, opts?: {
         started?: boolean;
         aborted?: boolean;
+        excerptIsOutputTail?: boolean;
     });
 }
 export interface BotRuntime {
@@ -145,6 +163,19 @@ export interface BotRuntime {
      * than the stderr excerpt is known. Pure.
      */
     failureReason?(stdout: string, stderr: string): string | undefined;
+    /**
+     * Optional: after a failed turn whose reason says this CLI is too old for
+     * the requested model, the models to try instead, best first (at most
+     * `MAX_MODEL_FALLBACK_RETRIES`), or empty when none is known. The turn is
+     * run again on each in order until one is not refused for its version.
+     * `run` spawns the same binary with other arguments (catalog, version) and
+     * must not need the network or a sign-in.
+     */
+    fallbackModelsAfterVersionMismatch?(args: {
+        reason: string;
+        requestedModel: string | undefined;
+        run: (args: string[]) => Promise<SpawnResult>;
+    }): Promise<string[]>;
 }
 /**
  * Turns have no time limit: a turn runs until the model process exits (the
@@ -152,6 +183,8 @@ export interface BotRuntime {
  * unset, empty, zero or invalid means unlimited.
  */
 export declare const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+/** Most extra attempts one turn makes on other models after a version refusal. Never a loop. */
+export declare const MAX_MODEL_FALLBACK_RETRIES = 2;
 export declare function turnTimeoutMs(env?: NodeJS.ProcessEnv): number | undefined;
 /** Parse one NDJSON line; null when it is not a JSON object. */
 export declare function parseJsonLine(line: string): Record<string, unknown> | null;

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

@@ -12,6 +12,13 @@ export class RuntimeError extends Error {
     started;
     /** True when the turn was ended on purpose (owner stop), not by a model failure. */
     aborted;
+    /**
+     * True when `stderrExcerpt` is a tail of the runtime's ordinary output, not
+     * an error it reported. Such a tail can contain anything the model printed
+     * ("command not found" from a shell step, a 503 in a fetched page), so it
+     * must never decide what went wrong; only the message may.
+     */
+    excerptIsOutputTail;
     constructor(message, stderrExcerpt, exitCode, opts = {}) {
         super(message);
         this.stderrExcerpt = stderrExcerpt;
@@ -19,6 +26,7 @@ export class RuntimeError extends Error {
         this.name = "RuntimeError";
         this.started = opts.started ?? true;
         this.aborted = opts.aborted ?? false;
+        this.excerptIsOutputTail = opts.excerptIsOutputTail ?? false;
     }
 }
 /**
@@ -27,6 +35,8 @@ export class RuntimeError extends Error {
  * unset, empty, zero or invalid means unlimited.
  */
 export const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+/** Most extra attempts one turn makes on other models after a version refusal. Never a loop. */
+export const MAX_MODEL_FALLBACK_RETRIES = 2;
 export function turnTimeoutMs(env = process.env) {
     const raw = Number(env[TURN_TIMEOUT_ENV]);
     return Number.isFinite(raw) && raw > 0 ? raw : undefined;

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

@@ -0,0 +1,113 @@
+/**
+ * What went wrong with a bot's coding tool (Claude Code, Codex, Grok), in a
+ * class a person can act on.
+ *
+ * A failed model turn used to be reported by quoting the runtime's own error
+ * in the DM ("Sorry, I couldn't get started on my own (codex failed: The
+ * 'gpt-6-astra' model requires a newer version of Codex ...)"), and the
+ * fallback copy told the person to check the sign-in even when the cause was
+ * something else. Now every failure is classified here, the person gets one
+ * plain sentence plus one next step, and the raw text goes only to the bot
+ * log. For the four repairable classes the DM also carries a machine-readable
+ * `runtime-repair` block in its `richContent` so the desktop can render a
+ * repair card; the plain body stays the fallback.
+ *
+ * Matching is narrow on purpose: each class has its own known error shapes,
+ * and anything unrecognised is `unknown`, which never blames the sign-in.
+ */
+import type { BotRuntimeId } from "./config.js";
+export type RuntimeFailureClass = 
+/** The tool's login is missing, expired or revoked. */
+"signed-out"
+/** The installed tool is too old for the model it was asked to use. */
+ | "cli-outdated"
+/** The model id is unknown, retired, or not available to this account. */
+ | "model-unsupported"
+/** Network trouble, a rate or usage limit, an overloaded service, or a timeout. */
+ | "transient"
+/** The tool is not installed (or not on PATH) on this computer. */
+ | "not-installed"
+/** 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 one thing the person can do about it. The desktop maps each to a button. */
+export type RuntimeRepairAction = "signIn" | "update" | "switchModel" | "tryAgain";
+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;
+/**
+ * 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;
+ * its message (what HQ saw, e.g. "codex is not installed or not on PATH")
+ * decides when the excerpt says nothing known. An excerpt that is only a tail
+ * of the runtime's ordinary output (`excerptIsOutputTail`) is never read: the
+ * model may have printed "command not found" or a 503 itself.
+ */
+export declare function classifyRuntimeError(err: unknown): RuntimeFailureClass;
+export declare function isRuntimeVersionTooOld(text: string | undefined | null): boolean;
+/** "gpt-6-astra" from "The 'gpt-6-astra' model requires a newer version of Codex ...". */
+export declare function versionTooOldModel(text: string | undefined | null): string | undefined;
+/** Where the failure happened, which changes only the next step's wording. */
+export type RuntimeFailureContext = "kickoff" | "message";
+/**
+ * The plain reason, as a sentence fragment without a closing period
+ * ("my Codex app is out of date"). Used in job run dispositions.
+ */
+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;
+/** "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;
+/** 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;
+/**
+ * The machine-readable repair payload a failure DM carries. The DM transport
+ * (POST /v1/notify/dm) stores structured data only in `richContent`
+ * (`{ v: 1, blocks: [...] }`, each block with a string `kind`), so this object
+ * travels as `richContent.blocks[0]`. The plain `body` is always the fallback.
+ */
+export interface RuntimeRepairBlock {
+    v: 1;
+    kind: "runtime-repair";
+    class: RuntimeRepairClass;
+    runtime: BotRuntimeId | string;
+    action: RuntimeRepairAction;
+    /** The bot's handle (its folder name), as `hq bot set-model` takes it. */
+    botName: string;
+    /** Event id of the person's message that failed, so "Try again" can resend it. */
+    retryOf?: string;
+    /** For `switchModel`: a model this computer's tool can run. */
+    suggestedModel?: string;
+}
+export interface RuntimeRichContent {
+    v: 1;
+    blocks: [RuntimeRepairBlock];
+}
+export interface RuntimeRepairNotice {
+    cls: RuntimeFailureClass;
+    /** The plain DM body. */
+    text: string;
+    /** Absent for `not-installed` and `unknown`: those get the plain text only. */
+    richContent?: RuntimeRichContent;
+}
+export declare function runtimeRepairBlock(args: {
+    cls: RuntimeRepairClass;
+    runtime: BotRuntimeId | string;
+    botName: string;
+    retryOf?: string;
+    suggestedModel?: string;
+}): RuntimeRepairBlock;
+/** The plain body plus, for a repairable class, the repair block. */
+export declare function runtimeRepairNotice(args: {
+    cls: RuntimeFailureClass;
+    runtime: BotRuntimeId | string;
+    botName: string;
+    context: RuntimeFailureContext;
+    /** Overrides the default body (e.g. the "I didn't finish that" form). */
+    text?: string;
+    retryOf?: string;
+    suggestedModel?: string;
+}): RuntimeRepairNotice;
+//# sourceMappingURL=runtime-failure.d.ts.map