@indigoai-us/hq-cli 5.345.76 → 5.345.77

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

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

@@ -0,0 +1,180 @@
+/**
+ * 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 { isRuntimeSignInFailure, runtimeDisplayName } from "./runtime-sign-in.js";
+export const RUNTIME_REPAIR_ACTIONS = {
+    "signed-out": "signIn",
+    "cli-outdated": "update",
+    "model-unsupported": "switchModel",
+    transient: "tryAgain",
+};
+export function isRuntimeRepairClass(cls) {
+    return cls in RUNTIME_REPAIR_ACTIONS;
+}
+const NOT_INSTALLED = /\bis not installed or not on PATH\b|\bspawn \S+ ENOENT\b|\bcommand not found\b/i;
+/**
+ * The tool says it is too old for the model. Codex: "The 'gpt-6-astra' model
+ * requires a newer version of Codex. Please upgrade to the latest app or CLI
+ * and try again." Claude Code words it "... requires a newer version of
+ * Claude Code".
+ */
+const VERSION_TOO_OLD = /\brequires a newer version of (?:codex|claude code|grok|the (?:app|cli))\b|\bplease upgrade to the latest (?:app or cli|version of (?:codex|claude code|grok))\b/i;
+/** The failing model id inside a version-too-old message, when it names one. */
+const VERSION_TOO_OLD_MODEL = /\bthe ['"`]([^'"`\s]{1,128})['"`] model requires a newer version of\b/i;
+/**
+ * Claude Code: "There's an issue with the selected model" (its own wording for
+ * a model the account cannot use) and the API's 404 not_found_error whose
+ * message starts "model: <id>". Codex and the OpenAI API: model_not_found,
+ * "does not exist or you do not have access", "not supported when using
+ * Codex with a ChatGPT account".
+ */
+const MODEL_UNSUPPORTED = /there'?s an issue with the selected model|\bnot_found_error\b[^\n]{0,200}\bmodel:\s|\bmodel_not_found\b|\b(?:unknown|invalid|unsupported) model\b|\bthe (?:requested )?model ['"`]?[^'"`\s]{1,128}['"`]? (?:does not exist|is not supported|is not available|was not found|has been deprecated)\b|\bmodel ['"`][^'"`\s]{1,128}['"`] (?:does not exist|is not supported|is not available|not found)\b|\bdo(?:es)? not have access to (?:the )?model\b|\bmodel is not supported when using codex with a chatgpt account\b/i;
+const TRANSIENT = /\brate[_ ]limit|\busage[_ ]limit|\byou've hit your usage limit\b|\btoo many requests\b|\b429\b|\boverloaded\b|\b(?:502|503|504|529)\b|\bservice unavailable\b|\bbad gateway\b|\bgateway time-?out\b|\binternal server error\b|\bECONNRESET\b|\bECONNREFUSED\b|\bETIMEDOUT\b|\bENOTFOUND\b|\bEAI_AGAIN\b|\bENETUNREACH\b|\bsocket hang up\b|\bnetwork (?:error|is unreachable)\b|\bstream (?:disconnected|error)\b|\bconnection (?:reset|refused|closed|error)\b|\btimed out\b|\bexceeded \d+ms \(HQ_BOT_TURN_TIMEOUT_MS\)/i;
+/** Sort a runtime's failure text into one class. Order matters: most specific first. */
+export function classifyRuntimeFailure(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return "unknown";
+    if (NOT_INSTALLED.test(t))
+        return "not-installed";
+    if (VERSION_TOO_OLD.test(t))
+        return "cli-outdated";
+    if (isRuntimeSignInFailure(t))
+        return "signed-out";
+    if (MODEL_UNSUPPORTED.test(t))
+        return "model-unsupported";
+    if (TRANSIENT.test(t))
+        return "transient";
+    return "unknown";
+}
+/**
+ * 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 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 fromExcerpt = classifyRuntimeFailure(typeof e.stderrExcerpt === "string" ? e.stderrExcerpt : "");
+        if (fromExcerpt !== "unknown")
+            return fromExcerpt;
+        return classifyRuntimeFailure(message);
+    }
+    return classifyRuntimeFailure(err instanceof Error ? err.message : String(err ?? ""));
+}
+export function isRuntimeVersionTooOld(text) {
+    return VERSION_TOO_OLD.test((text ?? "").trim());
+}
+/** "gpt-6-astra" from "The 'gpt-6-astra' model requires a newer version of Codex ...". */
+export function versionTooOldModel(text) {
+    return VERSION_TOO_OLD_MODEL.exec(text ?? "")?.[1];
+}
+/**
+ * The plain reason, as a sentence fragment without a closing period
+ * ("my Codex app is out of date"). Used in job run dispositions.
+ */
+export function runtimeFailureReason(cls, runtime) {
+    const tool = runtimeDisplayName(runtime);
+    switch (cls) {
+        case "signed-out":
+            return `${tool} needs you to sign in again on this computer`;
+        case "cli-outdated":
+            return `my ${tool} app is out of date`;
+        case "model-unsupported":
+            return `the model I'm set to use isn't available in ${tool} here`;
+        case "transient":
+            return `${tool} is busy or out of reach right now`;
+        case "not-installed":
+            return `${tool} isn't installed on this computer`;
+        default:
+            return `${tool} stopped with an error`;
+    }
+}
+/** The one next step, as a full sentence. */
+export function runtimeFailureNextStep(cls, runtime, context = "message") {
+    const tool = runtimeDisplayName(runtime);
+    switch (cls) {
+        case "signed-out":
+            return `Use "Sign in to ${tool}" in HQ, then send me any message.`;
+        case "cli-outdated":
+            return `Update ${tool}, then send me any message.`;
+        case "model-unsupported":
+            return `Choose a different model in my settings, then send me any message.`;
+        case "transient":
+            return context === "kickoff"
+                ? `Send me any message in a few minutes and I'll get started.`
+                : `Send your message again in a few minutes.`;
+        case "not-installed":
+            return `Install ${tool} from HQ, then send me any message.`;
+        default:
+            return context === "kickoff"
+                ? `Send me any message and I'll try again. If it keeps happening, restart me from HQ.`
+                : `Send your message again. If it keeps happening, restart me from HQ.`;
+    }
+}
+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)}`;
+}
+/** 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 runtimeRepairBlock(args) {
+    return {
+        v: 1,
+        kind: "runtime-repair",
+        class: args.cls,
+        runtime: args.runtime,
+        action: RUNTIME_REPAIR_ACTIONS[args.cls],
+        botName: args.botName,
+        ...(args.retryOf ? { retryOf: args.retryOf } : {}),
+        ...(args.suggestedModel ? { suggestedModel: args.suggestedModel.slice(0, 128) } : {}),
+    };
+}
+/** The plain body plus, for a repairable class, the repair block. */
+export function runtimeRepairNotice(args) {
+    const text = args.text ?? runtimeFailureText(args.cls, args.runtime, args.context);
+    if (!isRuntimeRepairClass(args.cls))
+        return { cls: args.cls, text };
+    return {
+        cls: args.cls,
+        text,
+        richContent: {
+            v: 1,
+            blocks: [
+                runtimeRepairBlock({
+                    cls: args.cls,
+                    runtime: args.runtime,
+                    botName: args.botName,
+                    ...(args.retryOf ? { retryOf: args.retryOf } : {}),
+                    ...(args.suggestedModel ? { suggestedModel: args.suggestedModel } : {}),
+                }),
+            ],
+        },
+    };
+}
+//# sourceMappingURL=runtime-failure.js.map

package/dist/lib/bot/runtime-sign-in.js

@@ -10,7 +10,7 @@
  */
 /** Time between the bot's own retries while its sign-in is broken. */
 export const SIGN_IN_RETRY_MS = 60_000;
-const SIGN_IN_FAILURE = /failed to authenticate|authentication[_ ]failed|not logged in|not signed in|please (?:run \/login|log ?in|sign ?in)|(?:oauth|access|refresh) token (?:has been |was )?(?:expired|revoked|invalid)|oauth session expired|invalid api key|\b401\b|unauthori[sz]ed|login (?:required|expired)|sign-?in (?:required|expired)/i;
+const SIGN_IN_FAILURE = /failed to authenticate|authentication[_ ]failed|not logged in|not signed in|please (?:run \/login|log ?in|sign ?in)|(?:oauth|access|refresh) token (?:has been |has |was )?(?:expired|revoked|invalid)|oauth session expired|invalid api key|\b401\b|unauthori[sz]ed|login (?:required|expired)|sign-?in (?:required|expired)/i;
 /** Usage and rate limits are a different problem; a new sign-in does not fix them. */
 const NOT_SIGN_IN = /usage[_ ]limit|rate[_ ]limit|quota|too many requests|credits/i;
 export function isRuntimeSignInFailure(text) {
@@ -26,6 +26,6 @@ export function runtimeDisplayName(runtime) {
 export function signInNeededText(runtime, kickoff = false) {
     const tool = runtimeDisplayName(runtime);
     return (`I can't work right now: ${tool} needs you to sign in again on this computer. ` +
-        `Use "Sign in to ${tool}" in HQ, and I'll ${kickoff ? "get started" : "answer this"} as soon as it works again — no need to send it twice.`);
+        `Use "Sign in to ${tool}" in HQ, and I'll ${kickoff ? "get started" : "answer this"} as soon as it works again. No need to send it twice.`);
 }
 //# sourceMappingURL=runtime-sign-in.js.map

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

@@ -44,6 +44,27 @@ export interface BotStatusFile {
      * reason); cleared by the next turn that works. `null` = known to work.
      */
     runtimeSignIn?: RuntimeSignInIssue | null;
+    /**
+     * Set when the installed coding tool is too old for the model it was asked
+     * to use and the last turn ran on `to` instead (`from` is "" when the model
+     * came from the tool's own config). `null` once a turn runs on the model it
+     * was asked for again. Updating the tool clears it.
+     */
+    runtimeModelFallback?: {
+        from: string;
+        to: string;
+        at: string;
+    } | null;
+    /**
+     * 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
+     * an updated hq-cli nor answer the next message). `null` once the hold is
+     * over; the next message then runs a fresh turn.
+     */
+    modelHold?: {
+        until: string;
+        reason: string;
+    } | null;
     /** hq-cli version this process loaded (a bot keeps it until it restarts). */
     cliVersion?: string;
     updatedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.76",
+  "version": "5.345.77",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {