talon-agent 5.25.1 → 5.26.0

package/README.md

@@ -487,6 +487,7 @@ Config file: `~/.talon/config.json`
 | `model`                    | `"default"`  | Default model. Interpretation depends on the active backend.                                                            |
 | `agyBinary`                | ---          | Path to the Antigravity `agy` executable. `AGY_BINARY` overrides it. |
 | `codexApiKey`              | ---          | Codex-only OpenAI API key. Prefer this over `openaiApiKey` for Codex API-key auth. `codex login` takes precedence over shared `openaiApiKey`. |
+| `codexChatGptDefaultModel` | ---          | Model a ChatGPT-login Codex session falls back to when a model is rejected or none is set. Default: the Codex CLI's own default for the account (from `~/.codex/models_cache.json`). `TALON_CODEX_CHATGPT_MODEL` overrides it. |
 | `concurrency`              | `1`          | Max concurrent AI queries (1--20)                                                                                       |
 | `pulse`                    | `true`       | Periodic group engagement                                                                                               |
 | `heartbeat`                | `false`      | Background maintenance agent                                                                                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.25.1",
+  "version": "5.26.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/backend/agy/one-shot.ts

@@ -33,6 +33,7 @@ import {
   type AgyResult,
   type AgyStepUpdate,
 } from "./events.js";
+import { abortLogLine } from "../../core/agents/abort-reason.js";
 
 const ts = (): string => new Date().toISOString().slice(11, 19);
 
@@ -257,20 +258,39 @@ export async function runOneShotAgent(
       appendLog,
       ...(onAssistantText ? { onAssistantText } : {}),
       aborted: abortController.signal.aborted,
+      abortSignal: abortController.signal,
     });
   } catch (err) {
+    // settleOneShot already logged its own failure — just pass it on.
+    if (err instanceof AgyOneShotError) throw err;
     const msg = err instanceof Error ? err.message : String(err);
     if (abortController.signal.aborted || /abort/i.test(msg)) {
-      await appendLog(`\n### [${ts()}] Aborted\nRun aborted by timeout.\n`);
+      await appendLog(
+        `\n### [${ts()}] Aborted\n${abortLogLine(abortController.signal)}\n`,
+      );
       return;
     }
     logWarn("agent", `agy one-shot run failed: ${msg}`);
     await appendLog(`\n### [${ts()}] Error\n${msg}\n`);
+    // Surface it: a swallowed failure is recorded as a successful run by
+    // cron, heartbeat and the task table.
+    throw new AgyOneShotError(msg, { cause: err });
   } finally {
     unregisterMcpScope(scope);
   }
 }
 
+/**
+ * An agy one-shot that failed: no result, a non-SUCCESS turn, or a spawn
+ * error. Thrown so callers record the run as failed rather than ok.
+ */
+class AgyOneShotError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "AgyOneShotError";
+  }
+}
+
 /** Report the run's answer + usage, or its failure, to the log. */
 async function settleOneShot(inputs: {
   outcome: SpawnOutcome;
@@ -278,10 +298,14 @@ async function settleOneShot(inputs: {
   appendLog: (text: string) => Promise<void>;
   onAssistantText?: OneShotAgentParams["onAssistantText"];
   aborted: boolean;
+  abortSignal?: AbortSignal;
 }): Promise<OneShotUsage | void> {
   const { outcome, appendLog } = inputs;
   if (inputs.aborted) {
-    await appendLog(`\n### [${ts()}] Aborted\nRun aborted by timeout.\n`);
+    const line = inputs.abortSignal
+      ? abortLogLine(inputs.abortSignal)
+      : "Run aborted.";
+    await appendLog(`\n### [${ts()}] Aborted\n${line}\n`);
     return;
   }
   if (!outcome.result) {
@@ -290,7 +314,14 @@ async function settleOneShot(inputs: {
       : outcome.stderr.trim() || `agy exited ${outcome.code ?? "n/a"}`;
     logWarn("agent", `agy one-shot produced no result: ${reason}`);
     await appendLog(`\n### [${ts()}] Error\n${reason}\n`);
-    return;
+    throw new AgyOneShotError(reason);
+  }
+  if (outcome.result.status && outcome.result.status !== "SUCCESS") {
+    // logResult already wrote the "Turn <status>" section.
+    const reason =
+      outcome.result.error?.trim() || `agy turn ${outcome.result.status}`;
+    logWarn("agent", `agy one-shot turn ${outcome.result.status}: ${reason}`);
+    throw new AgyOneShotError(reason);
   }
   const response = outcome.result.response ?? "";
   if (response.trim()) {

package/src/backend/codex/auth.ts

@@ -293,10 +293,39 @@ export function detectCodexAuth(
  * `"not supported when using Codex with a ChatGPT account"`. Match on
  * that substring (case-insensitive, generous on whitespace) so a
  * future wording shift still trips a soft-match.
+ *
+ * Also matches the 404 "model … does not exist or you do not have
+ * access" shape ({@link isCodexModelNotFoundError}): a model retired for
+ * the account is the same situation from the caller's point of view.
  */
 export function isChatGptModelMismatchError(message: string): boolean {
-  return /not\s+supported\s+when\s+using\s+codex\s+with\s+a\s+chatgpt\s+account/i.test(
-    message,
+  if (
+    /not\s+supported\s+when\s+using\s+codex\s+with\s+a\s+chatgpt\s+account/i.test(
+      message,
+    )
+  ) {
+    return true;
+  }
+  return isCodexModelNotFoundError(message);
+}
+
+/**
+ * Detect the "model retired / not granted" 404 the ChatGPT Codex endpoint
+ * returns once a model is withdrawn from an account:
+ *
+ *   `unexpected status 404 Not Found: The model \`gpt-5.5\` does not exist
+ *    or you do not have access to it.`
+ *
+ * Every Codex cron run hit exactly this from 2026-09-24 onward. It is as
+ * definitive as the 400 mismatch — the server names the model and says
+ * the account can't use it — so it takes the same fallback/learning path.
+ * Requires both the 404 status and the "model … does not exist" wording
+ * so an unrelated 404 (a missing MCP resource, a bad URL) can't trip it.
+ */
+export function isCodexModelNotFoundError(message: string): boolean {
+  return (
+    /\b404\b/.test(message) &&
+    /\bmodel\b[^\n]{0,120}?\bdoes\s+not\s+exist\b/i.test(message)
   );
 }
 

package/src/backend/codex/constants.ts

@@ -37,14 +37,28 @@ export const CODEX_SYSTEM_PROMPT_SUFFIX = codexSystemPromptSuffix("telegram");
 export const CODEX_DEFAULT_MODEL = "gpt-5-codex";
 
 /**
- * Default model used by the Codex backend when the user is signed in
- * via ChatGPT OAuth (`~/.codex/auth.json` `auth_mode: "chatgpt"`).
- * The `gpt-5-codex` model is rejected with a 400
- * `invalid_request_error` ("not supported when using Codex with a
- * ChatGPT account") on this auth path; `gpt-5.5` is the supported
- * flagship for ChatGPT users.
+ * Last-resort default model for the Codex backend when the user is signed
+ * in via ChatGPT OAuth (`~/.codex/auth.json` `auth_mode: "chatgpt"`).
+ * The `gpt-5-codex` model is rejected with a 400 `invalid_request_error`
+ * ("not supported when using Codex with a ChatGPT account") on this auth
+ * path.
+ *
+ * This is only the floor of the resolution ladder — see
+ * `getCodexChatGptDefaultModel()` in `models.ts`, which prefers (1) an
+ * explicit operator override, then (2) the Codex CLI's own default for the
+ * signed-in account (the first listed model in `~/.codex/models_cache.json`
+ * by priority). `gpt-6-astra` is the first entry of the model catalog
+ * bundled with codex-cli 0.154. The previous value, `gpt-5.5`, was retired
+ * for ChatGPT accounts in Sep 2026: every run on it returned
+ * `404 The model gpt-5.5 does not exist or you do not have access to it`.
+ */
+export const CODEX_CHATGPT_DEFAULT_MODEL = "gpt-6-astra";
+
+/**
+ * Environment override for the ChatGPT-OAuth default model. Takes
+ * precedence over the `codexChatGptDefaultModel` config key.
  */
-export const CODEX_CHATGPT_DEFAULT_MODEL = "gpt-5.5";
+export const CODEX_CHATGPT_MODEL_ENV = "TALON_CODEX_CHATGPT_MODEL";
 
 /**
  * ThreadOptions permission settings shared by both the chat handler and

package/src/backend/codex/discovery.ts

@@ -72,6 +72,8 @@ interface CodexCacheModelEntry {
   description?: string;
   visibility?: "list" | "hide" | string;
   supported_in_api?: boolean;
+  /** Picker order — lower sorts first; the CLI's default is the lowest. */
+  priority?: number;
   context_window?: number;
   default_reasoning_level?: string;
   supported_reasoning_levels?: Array<{
@@ -351,6 +353,33 @@ export async function fetchOpenAiModels(
  * Non-existent cache file throws so the caller's catch path logs it
  * at debug level and the picker falls back to curated.
  */
+/**
+ * The Codex CLI's own default for the account: the listed, API-callable
+ * entry with the lowest `priority`. First entry wins ties, matching the
+ * CLI's stable sort. `null` when nothing qualifies.
+ */
+function cliDefaultModel(
+  data: ReadonlyArray<CodexCacheModelEntry | null | undefined>,
+): string | null {
+  let best: string | null = null;
+  let bestPriority = Number.POSITIVE_INFINITY;
+  for (const entry of data) {
+    if (!entry || typeof entry.slug !== "string" || !entry.slug) continue;
+    if (entry.visibility === "hide" || entry.supported_in_api === false) {
+      continue;
+    }
+    const priority =
+      typeof entry.priority === "number" && Number.isFinite(entry.priority)
+        ? entry.priority
+        : Number.MAX_SAFE_INTEGER;
+    if (priority < bestPriority) {
+      bestPriority = priority;
+      best = entry.slug;
+    }
+  }
+  return best;
+}
+
 export async function loadCodexCacheModels(): Promise<void> {
   const path = getCodexCachePath();
   let raw: string;
@@ -381,6 +410,7 @@ export async function loadCodexCacheModels(): Promise<void> {
   const state = getState();
   state.discoveredModels.clear();
   state.discoveredModelMetadata.clear();
+  state.discoveredDefaultModel = cliDefaultModel(data);
   let kept = 0;
   let dropped = 0;
   for (const entry of data) {
@@ -429,6 +459,7 @@ export async function loadCodexCacheModels(): Promise<void> {
   const fetchedAt = json.fetched_at ?? "unknown";
   log(
     "agent",
-    `Codex: loaded ${kept} models from ${path} (fetched_at=${fetchedAt}, filtered ${dropped} hidden/api-disabled entries)`,
+    `Codex: loaded ${kept} models from ${path} (fetched_at=${fetchedAt}, filtered ${dropped} hidden/api-disabled entries` +
+      `${state.discoveredDefaultModel ? `, CLI default ${state.discoveredDefaultModel}` : ""})`,
   );
 }

package/src/backend/codex/factory.ts

@@ -28,10 +28,7 @@ import { initCodexAgent, getCodexAuthInfo } from "./init.js";
 import { handleMessage as codexHandleMessage } from "./handler/index.js";
 import { runOneShotAgent as codexRunOneShotAgent } from "./one-shot.js";
 import { resetState as resetCodexState } from "./state.js";
-import {
-  CODEX_DEFAULT_MODEL,
-  CODEX_CHATGPT_DEFAULT_MODEL,
-} from "./constants.js";
+import { CODEX_DEFAULT_MODEL } from "./constants.js";
 import {
   resolveModel as codexResolveModel,
   getModelInfo as codexGetModelInfo,
@@ -40,6 +37,7 @@ import {
   getProviderModels as codexGetProviderModels,
   formatModelError as codexFormatModelError,
   listModels as codexListModels,
+  getCodexChatGptDefaultModel,
 } from "./models.js";
 
 const codexFactory: BackendFactory = {
@@ -71,7 +69,7 @@ const codexFactory: BackendFactory = {
       getDefaultModelId: () => {
         const auth = getCodexAuthInfo();
         return auth?.mode === "chatgpt"
-          ? CODEX_CHATGPT_DEFAULT_MODEL
+          ? getCodexChatGptDefaultModel()
           : CODEX_DEFAULT_MODEL;
       },
       getRawModelInfo: (id) => codexGetModelInfo(id),

package/src/backend/codex/handler/message.ts

@@ -45,7 +45,6 @@ import {
 import {
   codexSystemPromptSuffix,
   CODEX_DEFAULT_MODEL,
-  CODEX_CHATGPT_DEFAULT_MODEL,
   CODEX_THREAD_PERMISSIONS,
 } from "../constants.js";
 import {
@@ -64,6 +63,7 @@ import {
   chatGptFallbackFor,
   getModelInfo,
   isCodexOAuthIncompat,
+  getCodexChatGptDefaultModel,
 } from "../models.js";
 import { supportsReasoningLevel } from "../../../core/models/reasoning-levels.js";
 import { toCodexReasoningEffort } from "../effort.js";
@@ -142,7 +142,7 @@ async function maybeFallbackForChatGptMismatch(
   const isOAuth = authInfo?.mode === "chatgpt";
   const silent =
     isOAuth &&
-    activeModel !== CODEX_CHATGPT_DEFAULT_MODEL &&
+    activeModel !== getCodexChatGptDefaultModel() &&
     isSilentOAuthExitError(probeText);
 
   if (!explicit && !silent) return undefined;
@@ -170,7 +170,7 @@ async function maybeFallbackForChatGptMismatch(
   }
 
   const fallbackModel =
-    chatGptFallbackFor(activeModel) ?? CODEX_CHATGPT_DEFAULT_MODEL;
+    chatGptFallbackFor(activeModel) ?? getCodexChatGptDefaultModel();
   if (fallbackModel === activeModel) return undefined;
 
   // Only EXPLICIT mismatch errors are persisted as OAuth-incompat —
@@ -227,8 +227,8 @@ function buildTurnPrompt(params: QueryParams): string {
 /**
  * Codex accepts arbitrary model strings; we pass through whatever the
  * caller resolved (chat-settings → config) and fall back to the auth-aware
- * default: `gpt-5-codex` when an API key is present, `gpt-5.5` when only
- * ChatGPT OAuth is configured (because `gpt-5-codex` is rejected with a
+ * default: `gpt-5-codex` when an API key is present, the resolved ChatGPT
+ * default (`getCodexChatGptDefaultModel`) when only ChatGPT OAuth is configured (because `gpt-5-codex` is rejected with a
  * 400 on ChatGPT-mode accounts). A model known to be OAuth-incompat on a
  * ChatGPT-OAuth account is swapped pre-emptively rather than letting the
  * first turn fail.
@@ -237,13 +237,13 @@ function resolveCodexModel(chatId: string, requested: string | undefined) {
   const authInfo = getCodexAuthInfo();
   const authAwareDefault =
     authInfo?.mode === "chatgpt"
-      ? CODEX_CHATGPT_DEFAULT_MODEL
+      ? getCodexChatGptDefaultModel()
       : CODEX_DEFAULT_MODEL;
   const requestedModel = requested ?? authAwareDefault;
   let activeModel = requestedModel;
   if (authInfo?.mode === "chatgpt" && isCodexOAuthIncompat(requestedModel)) {
     const fallback =
-      chatGptFallbackFor(requestedModel) ?? CODEX_CHATGPT_DEFAULT_MODEL;
+      chatGptFallbackFor(requestedModel) ?? getCodexChatGptDefaultModel();
     // Guard against a learned-but-no-fallback case — only swap when the
     // fallback is actually different from what we'd already run.
     if (fallback !== requestedModel) {

package/src/backend/codex/models.ts

@@ -37,6 +37,36 @@ import { awaitDiscovery, hasAttemptedDiscovery } from "./discovery.js";
 import { getState } from "./state.js";
 import { getCodexAuthInfo } from "./init.js";
 import { isKnownOAuthIncompat } from "./oauth-incompat.js";
+import {
+  CODEX_CHATGPT_DEFAULT_MODEL,
+  CODEX_CHATGPT_MODEL_ENV,
+} from "./constants.js";
+
+/**
+ * The model a ChatGPT-OAuth Codex session runs when nothing more specific
+ * applies — the target of every pre-emptive OAuth swap and mismatch
+ * fallback. Resolution order:
+ *
+ *   1. `TALON_CODEX_CHATGPT_MODEL` env var (operator override);
+ *   2. `codexChatGptDefaultModel` in config;
+ *   3. the Codex CLI's own default for the signed-in account (first
+ *      listed model in `~/.codex/models_cache.json` by priority), unless
+ *      Talon has already learned that id fails on this account;
+ *   4. {@link CODEX_CHATGPT_DEFAULT_MODEL}, the bundled floor.
+ *
+ * Hardcoding a single id is what broke in Sep 2026: OpenAI retired
+ * `gpt-5.5` for ChatGPT accounts and every run 404'd until a release.
+ */
+export function getCodexChatGptDefaultModel(): string {
+  const env = process.env[CODEX_CHATGPT_MODEL_ENV]?.trim();
+  if (env) return env;
+  const state = getState();
+  const configured = state.config?.codexChatGptDefaultModel?.trim();
+  if (configured) return configured;
+  const discovered = state.discoveredDefaultModel;
+  if (discovered && !isKnownOAuthIncompat(discovered)) return discovered;
+  return CODEX_CHATGPT_DEFAULT_MODEL;
+}
 
 /**
  * Codex-specific model metadata extension.
@@ -56,15 +86,26 @@ export interface CodexModelInfo extends UnifiedModelInfo {
  * Curated metadata for models we recognise.
  *
  * Order matters: `getSettingsPresentation` lists curated models in
- * this order, and `gpt-5.5` is intentionally first because it's the
- * broadest-access flagship (works on both auth modes) — the safe
- * default for Talon-on-Codex deployments where the operator hasn't
- * explicitly picked a model.
+ * this order, and the current flagship is intentionally first — the
+ * safe default for Talon-on-Codex deployments where the operator hasn't
+ * explicitly picked a model. (`gpt-5.5` held that slot until it was
+ * retired for ChatGPT accounts in Sep 2026.)
  *
  * Discovered-but-not-curated ids are appended at the end (synthesised
  * with minimal metadata), so the curated entries always render first.
  */
 export const CODEX_MODELS: CodexModelInfo[] = [
+  {
+    // Flagship of the catalog bundled with codex-cli 0.154 and the floor
+    // of the ChatGPT default ladder (`getCodexChatGptDefaultModel`).
+    // No context window here: the account's models_cache.json supplies it.
+    id: "gpt-6-astra",
+    displayName: "GPT-6 Astra",
+    provider: "openai",
+    providerName: "OpenAI",
+    selectable: true,
+    reasoning: true,
+  },
   {
     id: "gpt-5.5",
     displayName: "GPT-5.5",
@@ -149,19 +190,20 @@ export function isCodexOAuthIncompat(id: string): boolean {
  *
  * Returns `undefined` when:
  *   - The id isn't recognised as OAuth-incompat (caller can skip).
- *   - The id IS the broadest-access flagship (`gpt-5.5`) itself — no
- *     further fallback exists; if even `gpt-5.5` fails, the credential
- *     is the problem, not the model.
+ *   - The id IS the resolved ChatGPT default
+ *     ({@link getCodexChatGptDefaultModel}) itself — no further fallback
+ *     exists; if even the default fails, the credential is the problem,
+ *     not the model.
  *
- * For everything else returns `gpt-5.5` as the verified-working OAuth
- * default. (The curated table has only `gpt-5-codex` flagged as
+ * For everything else returns the resolved ChatGPT default. (The curated table has only `gpt-5-codex` flagged as
  * `apiKeyOnly: true`; runtime-learned entries cover the rest:
  * `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, etc.)
  */
 export function chatGptFallbackFor(id: string): string | undefined {
   if (!isCodexOAuthIncompat(id)) return undefined;
-  if (id === "gpt-5.5") return undefined;
-  return "gpt-5.5";
+  const fallback = getCodexChatGptDefaultModel();
+  if (id === fallback) return undefined;
+  return fallback;
 }
 
 /**

package/src/backend/codex/one-shot.ts

@@ -24,13 +24,17 @@ import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
 import {
   CODEX_SYSTEM_PROMPT_SUFFIX,
-  CODEX_CHATGPT_DEFAULT_MODEL,
   CODEX_THREAD_PERMISSIONS,
 } from "./constants.js";
 import { isChatGptModelMismatchError } from "./auth.js";
-import { chatGptFallbackFor, isCodexOAuthIncompat } from "./models.js";
+import {
+  chatGptFallbackFor,
+  getCodexChatGptDefaultModel,
+  isCodexOAuthIncompat,
+} from "./models.js";
 import { markOAuthIncompat } from "./oauth-incompat.js";
 import { toCodexReasoningEffort } from "./effort.js";
+import { abortLogLine } from "../../core/agents/abort-reason.js";
 
 /**
  * Resolve the effective model for a one-shot run, applying the same
@@ -39,7 +43,8 @@ import { toCodexReasoningEffort } from "./effort.js";
  * Heartbeats and dream calls pass `params.model` straight through from
  * `config.heartbeatModel ?? config.model`. If that's an OAuth-incompat
  * id (curated `apiKeyOnly: true` or runtime-learned) AND the active
- * Codex credential is ChatGPT OAuth, swap to `gpt-5.5` to avoid the
+ * Codex credential is ChatGPT OAuth, swap to the resolved ChatGPT default
+ * (`getCodexChatGptDefaultModel`) to avoid the
  * silent exit-1 failure mode that hit a group chat on 2026-05-20 23:13Z.
  *
  * Returns the resolved model id, whether a swap occurred, and an
@@ -56,7 +61,8 @@ function resolveOneShotModel(requested: string): {
     return { model: requested, swapped: false };
   }
 
-  const fallback = chatGptFallbackFor(requested) ?? CODEX_CHATGPT_DEFAULT_MODEL;
+  const fallback =
+    chatGptFallbackFor(requested) ?? getCodexChatGptDefaultModel();
   if (fallback === requested) return { model: requested, swapped: false };
 
   return {
@@ -131,6 +137,14 @@ export async function runOneShotAgent(
     ...CODEX_THREAD_PERMISSIONS,
   });
 
+  // The real reason a run failed lives in the stream, not in whatever the
+  // SDK throws afterwards: a model the account can't use yields
+  // `turn.failed` ("404 … The model `gpt-5.5` does not exist …") and the
+  // SDK then throws only "Codex Exec exited with code 1: Reading prompt
+  // from stdin...". Capture both so the failure the caller records is the
+  // one that explains it.
+  const failure = new StreamFailure();
+
   try {
     if (abortController.signal.aborted) {
       throw new Error("Aborted before prompt was sent");
@@ -146,6 +160,7 @@ export async function runOneShotAgent(
     for await (const event of events) {
       if (abortController.signal.aborted) break;
       await appendCodexEvent(appendLog, event, onAssistantText);
+      failure.observe(event);
       if (event.type === "turn.completed") {
         const u = (event as { usage?: Record<string, number> }).usage;
         if (u) {
@@ -158,49 +173,136 @@ export async function runOneShotAgent(
         }
       }
     }
+    // A stream that ends cleanly after `turn.failed` is still a failed run
+    // — returning here is how 26/26 Codex cron runs were stored as "ok".
+    if (!abortController.signal.aborted && failure.message) {
+      throw new CodexOneShotError(failure.message);
+    }
     return usage;
   } catch (err) {
+    const thrown = err instanceof Error ? err.message : String(err);
     if (
-      abortController.signal.aborted ||
-      /abort/i.test(err instanceof Error ? err.message : String(err))
+      !(err instanceof CodexOneShotError) &&
+      (abortController.signal.aborted || /abort/i.test(thrown))
     ) {
       const ts = new Date().toISOString().slice(11, 19);
-      await appendLog(`\n### [${ts}] Aborted\nRun aborted by timeout.\n`);
+      await appendLog(
+        `\n### [${ts}] Aborted\n${abortLogLine(abortController.signal)}\n`,
+      );
       return;
     }
-    const msg = err instanceof Error ? err.message : String(err);
-
-    // Learn only from EXPLICIT mismatches in one-shot context.
-    // Silent-exit failures are ambiguous (transient outage vs real
-    // model-incompat) and persisting them would over-poison the
-    // learning store with the result that one bad heartbeat
-    // permanently downgrades the model. Explicit mismatches carry the
-    // unambiguous server message so they're safe to mark.
-    //
-    // Unlike the interactive handler, heartbeat/dream can't recurse for
-    // a retry (would mess with the timing contract and lock
-    // semantics), so silent-exit failures here simply surface to the
-    // run log; the next scheduled run takes a fresh swing.
-    const authInfo = getCodexAuthInfo();
-    if (
-      authInfo?.mode === "chatgpt" &&
-      activeModel !== CODEX_CHATGPT_DEFAULT_MODEL &&
-      isChatGptModelMismatchError(msg)
-    ) {
-      const recorded = await markOAuthIncompat(activeModel);
-      if (recorded) {
-        logWarn(
-          "agent",
-          `[${contextLabel}] Codex one-shot: recorded ${activeModel} as ` +
-            `OAuth-incompat (explicit mismatch) — next ${contextLabel} run ` +
-            `will pre-emptively swap to ${CODEX_CHATGPT_DEFAULT_MODEL}`,
-        );
-      }
-    }
-
+    const msg = failure.describe(thrown);
+    await learnFromMismatch(activeModel, msg, contextLabel);
     logWarn("agent", `Codex one-shot run failed: ${msg}`);
     const ts = new Date().toISOString().slice(11, 19);
     await appendLog(`\n### [${ts}] Error\n${msg}\n`);
+    throw err instanceof CodexOneShotError
+      ? err
+      : new CodexOneShotError(msg, { cause: err });
+  }
+}
+
+/**
+ * Record a model as OAuth-incompat when a one-shot failed on it with an
+ * explicit server mismatch, so the next run pre-emptively swaps.
+ */
+async function learnFromMismatch(
+  activeModel: string,
+  msg: string,
+  contextLabel: string,
+): Promise<void> {
+  // Learn only from EXPLICIT mismatches in one-shot context.
+  // Silent-exit failures are ambiguous (transient outage vs real
+  // model-incompat) and persisting them would over-poison the
+  // learning store with the result that one bad heartbeat
+  // permanently downgrades the model. Explicit mismatches (the 400
+  // "not supported … ChatGPT account" and the 404 "model … does not
+  // exist") carry the unambiguous server message so they're safe to
+  // mark.
+  //
+  // Unlike the interactive handler, heartbeat/dream can't recurse for
+  // a retry (would mess with the timing contract and lock
+  // semantics), so the failure is surfaced to the caller — the task
+  // settles as failed — and the next scheduled run takes a fresh
+  // swing on the learned fallback.
+  const authInfo = getCodexAuthInfo();
+  const fallback = getCodexChatGptDefaultModel();
+  if (
+    authInfo?.mode !== "chatgpt" ||
+    activeModel === fallback ||
+    !isChatGptModelMismatchError(msg)
+  ) {
+    return;
+  }
+  const recorded = await markOAuthIncompat(activeModel);
+  if (recorded) {
+    logWarn(
+      "agent",
+      `[${contextLabel}] Codex one-shot: recorded ${activeModel} as ` +
+        `OAuth-incompat (explicit mismatch) — next ${contextLabel} run ` +
+        `will pre-emptively swap to ${fallback}`,
+    );
+  }
+}
+
+/**
+ * A Codex one-shot that failed upstream. The message is the most specific
+ * reason the stream carried (the `turn.failed` text when there was one),
+ * so task tables, cron run records and the backend router see the cause
+ * rather than the SDK's generic exit wrapper.
+ */
+class CodexOneShotError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "CodexOneShotError";
+  }
+}
+
+/**
+ * Codex emits `error` events for transient retries it handles itself
+ * ("Reconnecting... 2/5 (…)", "Falling back from WebSockets to HTTPS
+ * transport. …"). Those are progress, not failure — only the terminal
+ * `turn.failed` / final `error` count.
+ */
+const TRANSIENT_ERROR_RE = /^\s*(reconnecting\.\.\.|falling back from)/i;
+
+/** Tracks the terminal failure reported on a Codex event stream. */
+class StreamFailure {
+  private turnFailed: string | undefined;
+  private lastError: string | undefined;
+
+  observe(event: { type: string } & Record<string, unknown>): void {
+    if (event.type === "turn.failed") {
+      const err = (event as { error?: { message?: unknown } }).error;
+      const text =
+        typeof err?.message === "string" && err.message.trim()
+          ? err.message.trim()
+          : "turn failed (no message)";
+      this.turnFailed = text;
+      return;
+    }
+    if (event.type === "error" && typeof event.message === "string") {
+      const text = event.message.trim();
+      if (text && !TRANSIENT_ERROR_RE.test(text)) this.lastError = text;
+    }
+  }
+
+  /** The failure the stream reported, or undefined when it reported none. */
+  get message(): string | undefined {
+    return this.turnFailed ?? this.lastError;
+  }
+
+  /**
+   * Combine the stream's failure with whatever the SDK threw, most
+   * specific first, without repeating the same text twice.
+   */
+  describe(thrown: string): string {
+    const streamed = this.message;
+    if (!streamed) return thrown;
+    if (!thrown || thrown === streamed || streamed.includes(thrown)) {
+      return streamed;
+    }
+    return `${streamed} (${thrown.trim()})`;
   }
 }