@remnic/core 9.69.37 → 9.69.39

package/src/config.test.ts

@@ -2724,3 +2724,175 @@ test("parseConfig coerces string-typed sharedContextAllowBindingAuthority from t
     );
   }
 });
+
+test("parseConfig consumes backgroundGeneration and leaves openaiBaseUrl untouched", () => {
+  withIsolatedConnectorsDir(false, () => {
+    const previousKey = process.env.OPENAI_API_KEY;
+    const previousBase = process.env.OPENAI_BASE_URL;
+    delete process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_BASE_URL;
+    try {
+      const parsed = parseConfig({
+        backgroundGeneration: {
+          endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+          token: "bridge-token-fixture",
+          timeoutSeconds: 120,
+        },
+      });
+      assert.equal(parsed.openaiBaseUrl, undefined);
+      assert.equal(parsed.openaiApiKey, undefined);
+      assert.deepEqual(parsed.backgroundGeneration, {
+        endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+        token: "bridge-token-fixture",
+        timeoutSeconds: 120,
+      });
+
+      const explicitOpenAi = parseConfig({
+        backgroundGeneration: {
+          endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+          token: "bridge-token-fixture",
+          timeoutSeconds: 120,
+        },
+        openaiBaseUrl: "http://127.0.0.1:9999/v1",
+        openaiApiKey: "keep-me",
+      });
+      assert.equal(explicitOpenAi.openaiBaseUrl, "http://127.0.0.1:9999/v1");
+      assert.equal(explicitOpenAi.openaiApiKey, "keep-me");
+      assert.equal(
+        explicitOpenAi.backgroundGeneration?.endpoint,
+        "http://127.0.0.1:8765/v1/chat/completions",
+      );
+    } finally {
+      if (previousKey === undefined) delete process.env.OPENAI_API_KEY;
+      else process.env.OPENAI_API_KEY = previousKey;
+      if (previousBase === undefined) delete process.env.OPENAI_BASE_URL;
+      else process.env.OPENAI_BASE_URL = previousBase;
+    }
+  });
+});
+
+test("parseConfig ignores llmBridgeClientConfigPath", () => {
+  withIsolatedConnectorsDir(false, () => {
+    const parsed = parseConfig({
+      llmBridgeClientConfigPath: "/no/such/remnic-llm-bridge-client.json",
+    });
+    assert.equal(parsed.backgroundGeneration, undefined);
+  });
+});
+
+test("parseConfig rejects backgroundGeneration without a token", () => {
+  withIsolatedConnectorsDir(false, () => {
+    assert.throws(
+      () =>
+        parseConfig({
+          backgroundGeneration: {
+            endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+          },
+        }),
+      /must include a token/,
+    );
+  });
+});
+
+test("parseConfig ignores Hermes timeout_seconds on backgroundGeneration", () => {
+  withIsolatedConnectorsDir(false, () => {
+    const parsed = parseConfig({
+      backgroundGeneration: {
+        endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+        token: "bridge-token-fixture",
+        timeout_seconds: 45,
+      },
+    });
+    assert.equal(parsed.backgroundGeneration?.timeoutSeconds, 120);
+  });
+});
+
+test("parseConfig keeps env openaiBaseUrl isolated from backgroundGeneration", () => {
+  withIsolatedConnectorsDir(false, () => {
+    const previousKey = process.env.OPENAI_API_KEY;
+    const previousBase = process.env.OPENAI_BASE_URL;
+    process.env.OPENAI_API_KEY = "env-openai-key";
+    process.env.OPENAI_BASE_URL = "http://127.0.0.1:9999/v1";
+    try {
+      const parsed = parseConfig({
+        backgroundGeneration: {
+          endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+          token: "bridge-token-fixture",
+          timeoutSeconds: 45,
+        },
+      });
+      assert.equal(parsed.openaiBaseUrl, "http://127.0.0.1:9999/v1");
+      assert.equal(parsed.openaiApiKey, "env-openai-key");
+      assert.deepEqual(parsed.backgroundGeneration, {
+        endpoint: "http://127.0.0.1:8765/v1/chat/completions",
+        token: "bridge-token-fixture",
+        timeoutSeconds: 45,
+      });
+    } finally {
+      if (previousKey === undefined) delete process.env.OPENAI_API_KEY;
+      else process.env.OPENAI_API_KEY = previousKey;
+      if (previousBase === undefined) delete process.env.OPENAI_BASE_URL;
+      else process.env.OPENAI_BASE_URL = previousBase;
+    }
+  });
+});
+
+test("parseConfig rejects a non-object backgroundGeneration value", () => {
+  withIsolatedConnectorsDir(false, () => {
+    assert.throws(
+      () => parseConfig({ backgroundGeneration: "http://127.0.0.1:8765/v1/chat/completions" }),
+      /backgroundGeneration must be an object/,
+    );
+  });
+});
+
+test("parseConfig strips a slash-rich bridge endpoint without regex", () => {
+  withIsolatedConnectorsDir(false, () => {
+    const parsed = parseConfig({
+      backgroundGeneration: {
+        endpoint: `http://127.0.0.1:8765/v1/chat/completions${"/".repeat(10_000)}`,
+        token: "bridge-token-fixture",
+      },
+    });
+    assert.equal(
+      parsed.backgroundGeneration?.endpoint,
+      "http://127.0.0.1:8765/v1/chat/completions",
+    );
+    assert.equal(parsed.openaiBaseUrl, undefined);
+  });
+});
+
+test("parseConfig rejects plaintext non-loopback backgroundGeneration endpoints", () => {
+  withIsolatedConnectorsDir(false, () => {
+    for (const endpoint of [
+      "http://192.168.10.20:8765/v1/chat/completions",
+      "http://example.test/v1/chat/completions",
+    ]) {
+      assert.throws(
+        () =>
+          parseConfig({
+            backgroundGeneration: {
+              endpoint,
+              token: "bridge-token-fixture",
+            },
+          }),
+        /must use HTTPS unless the host is loopback/,
+      );
+    }
+
+    for (const endpoint of [
+      "http://127.0.0.1:8765/v1/chat/completions",
+      "http://localhost:8765/v1/chat/completions",
+      "http://[::1]:8765/v1/chat/completions",
+      "https://example.test/v1/chat/completions",
+    ]) {
+      const parsed = parseConfig({
+        backgroundGeneration: {
+          endpoint,
+          token: "bridge-token-fixture",
+        },
+      });
+      assert.equal(parsed.backgroundGeneration?.endpoint, endpoint);
+    }
+  });
+});

package/src/config.ts

@@ -25,6 +25,7 @@ import type {
   TriggerMode,
   TrustWeights,
 } from "./types.js";
+import { parseLocalLlmConfig } from "./local-llm-config.js";
 import { parseConvergeConfig } from "./converge-config.js";
 import { parseExternalWikiRecallGuard } from "./external-wiki-guard.js";
 import { log } from "./logger.js";
@@ -2680,49 +2681,7 @@ export function parseConfig(
       typeof cfg.abstractionNodeStoreDir === "string" && cfg.abstractionNodeStoreDir.trim().length > 0
         ? cfg.abstractionNodeStoreDir.trim()
         : path.join(memoryDir, "state", "abstraction-nodes"),
-    // Local LLM Provider (v2.1)
-    localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true", // default: false
-    localLlmUrl:
-      typeof cfg.localLlmUrl === "string" && cfg.localLlmUrl.length > 0
-        ? cfg.localLlmUrl
-        : "http://localhost:1234/v1",
-    localLlmModel:
-      typeof cfg.localLlmModel === "string" && cfg.localLlmModel.length > 0
-        ? cfg.localLlmModel
-        : "local-model",
-    localLlmApiKey:
-      typeof cfg.localLlmApiKey === "string" && cfg.localLlmApiKey.length > 0
-        ? resolveEnvVars(cfg.localLlmApiKey)
-        : localLlmApiKeyEnv === undefined
-          ? undefined
-          : readEnvVar(localLlmApiKeyEnv),
-    localLlmApiKeyEnv,
-    localLlmHeaders:
-      cfg.localLlmHeaders && typeof cfg.localLlmHeaders === "object" && !Array.isArray(cfg.localLlmHeaders)
-        ? Object.fromEntries(
-            Object.entries(cfg.localLlmHeaders as Record<string, unknown>)
-              .filter(([, value]) => typeof value === "string")
-              .map(([key, value]) => [key, String(value)]),
-          )
-        : undefined,
-    localLlmAuthHeader: cfg.localLlmAuthHeader !== false,
-    localLlmFallback: cfg.localLlmFallback !== false, // default: true
-    localLlmHomeDir:
-      typeof cfg.localLlmHomeDir === "string" && cfg.localLlmHomeDir.length > 0
-        ? cfg.localLlmHomeDir
-        : undefined,
-    localLmsCliPath:
-      typeof cfg.localLmsCliPath === "string" && cfg.localLmsCliPath.length > 0
-        ? cfg.localLmsCliPath
-        : undefined,
-    localLmsBinDir:
-      typeof cfg.localLmsBinDir === "string" && cfg.localLmsBinDir.length > 0
-        ? cfg.localLmsBinDir
-        : undefined,
-    localLlmTimeoutMs:
-      parseBoundedIntegerMs(cfg.localLlmTimeoutMs, 180_000, 1, 86_400_000),
-    localLlmMaxContext:
-      parseOptionalIntegerAtLeast(cfg.localLlmMaxContext, 1024, "localLlmMaxContext"),
+    ...parseLocalLlmConfig(cfg, localLlmApiKeyEnv, resolveEnvVars),
     // Observability (disabled by default to avoid log spam)
     slowLogEnabled: cfg.slowLogEnabled === true,
     slowLogThresholdMs:

package/src/fallback-llm-codex-subscription.ts

@@ -0,0 +1,168 @@
+/**
+ * Codex-subscription helpers for FallbackLlmClient (issue #2833).
+ *
+ * Terminal error classification, the `api: "codex-cli"` provider attempt,
+ * and Codex runner/lifecycle helpers live here so fallback-llm.ts stays
+ * generic chain orchestration.
+ */
+
+import { raceAbort } from "./abort-error.js";
+import { callCodexCliFallback, isCodexCliFallbackRunnerRegistered } from "./cli-fallback.js";
+import type { CodexCliFallbackRunner } from "./cli-fallback.js";
+import {
+  CODEX_SUBSCRIPTION_PROVIDER_ID,
+  CodexSubscriptionAuthError,
+  CodexSubscriptionConfigError,
+  CodexSubscriptionTimeoutError,
+  assertNoApiKeyConfig,
+  ensureCodexSubscriptionRunnerRegistered,
+  getCodexSubscriptionShutdownSignal,
+  isDefaultRegisteredCodexSubscriptionRunner,
+} from "./providers/codex-subscription.js";
+import type { ModelProviderConfig } from "./types.js";
+
+type CodexSubscriptionAttemptResult = {
+  content: string;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+  };
+};
+
+/**
+ * Terminal codex-subscription failures (timeout, auth, config contract).
+ * These carry documented caller guidance (`TimeoutError` name, `codex login`
+ * steps), so they must survive the chain instead of collapsing into a
+ * generic empty/http_error result (issue #2833).
+ */
+export function isTerminalCodexSubscriptionError(error: unknown): boolean {
+  return (
+    error instanceof CodexSubscriptionTimeoutError ||
+    error instanceof CodexSubscriptionAuthError ||
+    error instanceof CodexSubscriptionConfigError
+  );
+}
+
+/**
+ * Settle a fallback-LLM chain at the caller deadline. Abort the in-flight
+ * work, return immediately, and observe the abandoned promise so a late
+ * rejection cannot become unhandled.
+ */
+export async function raceFallbackLlmDeadline<T>(
+  work: Promise<T>,
+  timeoutMs: number,
+  abortOnTimeout: () => void,
+): Promise<{ timedOut: true } | { timedOut: false; value: T }> {
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(), timeoutMs);
+  deadline.signal.addEventListener("abort", abortOnTimeout, { once: true });
+  try {
+    const value = await raceAbort(
+      work,
+      deadline.signal,
+      `fallback LLM timed out after ${timeoutMs}ms`,
+    );
+    return { timedOut: false, value };
+  } catch (error) {
+    if (!deadline.signal.aborted) throw error;
+    const afterAbort = await Promise.race([
+      work.then(
+        (value) => ({ state: "value" as const, value }),
+        (lateError) => ({ state: "error" as const, error: lateError }),
+      ),
+      new Promise<{ state: "pending" }>((resolve) => {
+        setImmediate(() => resolve({ state: "pending" }));
+      }),
+    ]);
+    if (afterAbort.state === "value") return { timedOut: false, value: afterAbort.value };
+    if (afterAbort.state === "error") throw afterAbort.error;
+    void work.then(
+      () => undefined,
+      () => undefined,
+    );
+    return { timedOut: true };
+  } finally {
+    clearTimeout(timer);
+    deadline.signal.removeEventListener("abort", abortOnTimeout);
+  }
+}
+
+/**
+ * Attempt the Codex CLI / subscription provider. Returns `undefined` when the
+ * model is not `api: "codex-cli"` so the generic FallbackLlmClient path runs.
+ *
+ * Subscription ids reject a configured apiKey before generic secret resolution
+ * — otherwise an unresolvable ref throws a generic error and the provider's
+ * `codex login` guidance never surfaces (issue #2833). Other `codex-cli`
+ * providers still resolve a configured key. Runtime auth is skipped: the CLI
+ * login is the credential.
+ */
+export async function tryCodexSubscriptionProvider(
+  model: {
+    providerId: string;
+    modelId: string;
+    providerConfig: ModelProviderConfig;
+  },
+  messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+  options: { timeoutMs?: number; signal?: AbortSignal },
+  resolveFallbackApiKey: () => Promise<string | undefined>,
+  runner?: CodexCliFallbackRunner,
+): Promise<CodexSubscriptionAttemptResult | undefined> {
+  if (model.providerConfig.api !== "codex-cli") return undefined;
+
+  if (model.providerId === CODEX_SUBSCRIPTION_PROVIDER_ID) {
+    assertNoApiKeyConfig(model.providerConfig);
+  }
+
+  const resolvedApiKey =
+    model.providerConfig.apiKey === undefined ? undefined : await resolveFallbackApiKey();
+  const rawKey = model.providerConfig.apiKey;
+  const needsResolution =
+    rawKey === "secretref-managed" || (typeof rawKey === "object" && rawKey !== null);
+  if (needsResolution && !resolvedApiKey) {
+    throw new Error(`API key for provider "${model.providerId}" could not be resolved from secret ref`);
+  }
+
+  const effectiveConfig: ModelProviderConfig = {
+    ...model.providerConfig,
+    ...(resolvedApiKey ? { apiKey: resolvedApiKey } : {}),
+  };
+
+  // Let the provider surface its typed timeout before the generic outer deadline.
+  const callOptions = {
+    timeoutMs: options.timeoutMs === undefined
+      ? undefined
+      : Math.max(1, options.timeoutMs - Math.min(100, Math.max(5, Math.floor(options.timeoutMs / 5)))),
+    signal: options.signal,
+  };
+  // A host/benchmark runner on the process seam still wins. The core
+  // default runner does not: prefer the owning runtime so shutdown
+  // terminates the request that runtime started.
+  if (isCodexCliFallbackRunnerRegistered() && !(runner && isDefaultRegisteredCodexSubscriptionRunner())) {
+    return await callCodexCliFallback(effectiveConfig, model.modelId, messages, callOptions);
+  }
+  if (runner) {
+    return await callCodexCliFallback(effectiveConfig, model.modelId, messages, callOptions, runner);
+  }
+  ensureCodexSubscriptionRunnerRegistered();
+  return await callCodexCliFallback(effectiveConfig, model.modelId, messages, callOptions);
+}
+
+export function abortReason(signal: AbortSignal | undefined): Error {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new Error("fallback LLM request aborted");
+}
+
+export function withCodexRuntimeShutdown<T extends { signal?: AbortSignal }>(
+  options: T,
+  runner: CodexCliFallbackRunner | undefined,
+): T {
+  if (!runner) return options;
+  const shutdown = getCodexSubscriptionShutdownSignal(runner);
+  if (!shutdown) return options;
+  return {
+    ...options,
+    signal: options.signal ? AbortSignal.any([options.signal, shutdown]) : shutdown,
+  };
+}

package/src/fallback-llm.test.ts

@@ -939,6 +939,52 @@ test("fallback llm aborts codex-cli fallback requests when timeout wins", { conc
   }
 });
 
+test("fallback llm timeout is a hard deadline when the provider never settles", { concurrency: false }, async () => {
+  clearModelsJsonCache();
+  clearSecretCache();
+
+  const restoreRunner = __codexCliFallbackTestHooks.setRunCodexCliForTest(
+    async (request) =>
+      await new Promise<never>(() => {
+        request.options.signal?.addEventListener("abort", () => undefined, { once: true });
+      }),
+  );
+
+  const llm = new FallbackLlmClient({
+    agents: {
+      defaults: {
+        model: {
+          primary: "codex-cli/gpt-custom",
+        },
+      },
+    },
+    models: {
+      providers: {
+        "codex-cli": {
+          baseUrl: "",
+          api: "codex-cli",
+          apiKey: "codex-test-key",
+          models: [],
+        },
+      },
+    },
+  });
+
+  try {
+    const started = Date.now();
+    const response = await llm.chatCompletion(
+      [{ role: "user", content: "Say OK" }],
+      { temperature: 0, maxTokens: 16, timeoutMs: 30 },
+    );
+    assert.equal(response, null);
+    assert.ok(Date.now() - started < 1_000, "outer timeout must settle without waiting on the provider");
+  } finally {
+    restoreRunner();
+    clearModelsJsonCache();
+    clearSecretCache();
+  }
+});
+
 test("fallback llm can call Ollama native chat and suppress thinking", { concurrency: false }, async () => {
   clearModelsJsonCache();
   clearSecretCache();

package/src/fallback-llm.ts

@@ -16,10 +16,17 @@ import {
 import {
   CODEX_SUBSCRIPTION_PROVIDER_ID,
   codexSubscriptionBuiltinProviderConfig,
-  ensureCodexSubscriptionRunnerRegistered,
+  getCodexSubscriptionRunnerForOwner,
 } from "./providers/codex-subscription.js";
 import { loadModelsJsonProviders } from "./models-json.js";
-import { callCodexCliFallback } from "./cli-fallback.js";
+import {
+  abortReason,
+  isTerminalCodexSubscriptionError,
+  raceFallbackLlmDeadline,
+  tryCodexSubscriptionProvider,
+  withCodexRuntimeShutdown,
+} from "./fallback-llm-codex-subscription.js";
+import type { CodexCliFallbackRunner } from "./cli-fallback.js";
 import { resolveHomeDir } from "./runtime/env.js";
 import { expandTildePath } from "./utils/path.js";
 
@@ -85,6 +92,8 @@ export interface FallbackLlmRuntimeContext {
   getRuntimeAuthForModel?: GetRuntimeAuthForModelFn | null;
   resolveApiKeyForProvider?: ResolveApiKeyFn | null;
   workspaceDir?: string;
+  /** Per-runtime Codex child owner. Shutdown must terminate only this runner. */
+  codexSubscriptionRunner?: CodexCliFallbackRunner;
 }
 
 export function fallbackLlmRuntimeContextFromConfig(
@@ -98,6 +107,7 @@ export function fallbackLlmRuntimeContextFromConfig(
     workspaceDir: config.workspaceDir,
     resolveApiKeyForProvider: config.providerApiKeyResolver,
     getRuntimeAuthForModel: config.runtimeAuthForModelResolver,
+    codexSubscriptionRunner: getCodexSubscriptionRunnerForOwner(config),
     ...overrides,
   };
 }
@@ -224,12 +234,14 @@ export class FallbackLlmClient {
       log.warn("fallback LLM: no models configured in gateway");
       return null;
     }
+    options = withCodexRuntimeShutdown(options, this.runtimeContext.codexSubscriptionRunner);
 
     const runChain = async (
       initialOptions: FallbackLlmOptions,
     ): Promise<FallbackLlmResponse | null> => {
       let runOptions = initialOptions;
       let lastRejectedResponse: FallbackLlmResponse | null = null;
+      let terminalError: unknown;
       // Try each model in the chain
       for (let i = 0; i < models.length; i++) {
         if (runOptions.signal?.aborted) {
@@ -257,6 +269,9 @@ export class FallbackLlmClient {
             return response;
           }
         } catch (err) {
+          if (isTerminalCodexSubscriptionError(err) && runOptions.signal?.aborted) {
+            throw err;
+          }
           if (runOptions.signal?.aborted) {
             throw abortReason(runOptions.signal);
           }
@@ -289,6 +304,9 @@ export class FallbackLlmClient {
                 continue;
               }
             } catch (retryError) {
+              if (isTerminalCodexSubscriptionError(retryError) && runOptions.signal?.aborted) {
+                throw retryError;
+              }
               if (runOptions.signal?.aborted) throw abortReason(runOptions.signal);
               const retryErrorMsg = runOptions.redactProviderErrors
                 ? "provider error details redacted"
@@ -298,6 +316,9 @@ export class FallbackLlmClient {
               log.debug(
                 `fallback LLM: ${model.modelString} unstructured retry failed (${retryErrorMsg})`,
               );
+              if (isTerminalCodexSubscriptionError(retryError)) {
+                terminalError = retryError;
+              }
             }
             continue;
           }
@@ -307,11 +328,20 @@ export class FallbackLlmClient {
               ? err.message
               : String(err);
           log.debug(`fallback LLM: ${model.modelString} failed (${errorMsg}), trying next...`);
+          if (isTerminalCodexSubscriptionError(err)) {
+            terminalError = err;
+          }
           // Continue to next model in chain
         }
       }
 
       log.warn(`fallback LLM: all ${models.length} models in chain failed`);
+      // A terminal typed provider failure must reach the caller when the
+      // chain is exhausted — the documented timeout/re-login guidance
+      // depends on it (issue #2833).
+      if (terminalError !== undefined) {
+        throw terminalError;
+      }
       return lastRejectedResponse;
     };
 
@@ -320,7 +350,6 @@ export class FallbackLlmClient {
         log.warn("fallback LLM: timed out before request started");
         return null;
       }
-      let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
       const controller = new AbortController();
       const onCallerAbort = (): void => {
         controller.abort(abortReason(options.signal));
@@ -331,22 +360,22 @@ export class FallbackLlmClient {
       }
       const timedOptions = { ...options, signal: controller.signal };
       const chain = runChain(timedOptions);
-      chain.catch(() => {});
+      const guarded = chain.then(
+        (value) => value,
+        (err) => {
+          if (isTerminalCodexSubscriptionError(err)) throw err;
+          return null;
+        },
+      );
       try {
-        return await Promise.race([
-          chain,
-          new Promise<null>((resolve) => {
-            timeoutHandle = setTimeout(() => {
-              log.warn(`fallback LLM: timed out after ${options.timeoutMs}ms`);
-              controller.abort(
-                new Error(`fallback LLM timed out after ${options.timeoutMs}ms`),
-              );
-              resolve(null);
-            }, options.timeoutMs);
-          }),
-        ]);
+        const outcome = await raceFallbackLlmDeadline(guarded, options.timeoutMs, () => {
+          log.warn(`fallback LLM: timed out after ${options.timeoutMs}ms`);
+          controller.abort(
+            new Error(`fallback LLM timed out after ${options.timeoutMs}ms`),
+          );
+        });
+        return outcome.timedOut ? null : outcome.value;
       } finally {
-        if (timeoutHandle) clearTimeout(timeoutHandle);
         options.signal?.removeEventListener("abort", onCallerAbort);
       }
     }
@@ -386,7 +415,9 @@ export class FallbackLlmClient {
       // Caller aborts must propagate (e.g. recall planner cancellation) — do
       // not swallow them as a provider failure, or abort-driven callers lose
       // cancellation and treat it as an extraction error (codex review).
-      if (options.signal?.aborted) throw err;
+      // Terminal codex-subscription failures propagate for the same reason:
+      // their TimeoutError/auth guidance is the documented contract.
+      if (options.signal?.aborted || isTerminalCodexSubscriptionError(err)) throw err;
       log.warn("fallback LLM: chatCompletion threw during structured parse:", err);
       return { result: null, failureReason: "http_error" };
     }
@@ -643,24 +674,22 @@ export class FallbackLlmClient {
     messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
     options: FallbackLlmOptions,
   ): Promise<{ content: string; usage?: FallbackLlmResponse["usage"] } | null> {
-    // Try the gateway's native runtime auth first — it handles all provider-
-    // specific transforms (OAuth exchange, base URL rewrite, etc.)
-    const runtimeAuth = model.providerConfig.api === "codex-cli"
-      ? null
-      : await this.resolveRuntimeAuth(model);
+    const codexResult = await tryCodexSubscriptionProvider(
+      model,
+      messages,
+      options,
+      () => this.resolveFallbackApiKey(model),
+      this.runtimeContext.codexSubscriptionRunner,
+    );
+    if (codexResult !== undefined) return codexResult;
+    const runtimeAuth = await this.resolveRuntimeAuth(model);
     const effectiveBaseUrl = runtimeAuth?.baseUrl ?? model.providerConfig.baseUrl;
-    const resolvedApiKey = runtimeAuth?.apiKey
-      ?? (
-        model.providerConfig.api === "codex-cli" && model.providerConfig.apiKey === undefined
-          ? undefined
-          : await this.resolveFallbackApiKey(model)
-      );
+    const resolvedApiKey = runtimeAuth?.apiKey ?? await this.resolveFallbackApiKey(model);
 
     // If the raw key looks like an unresolved secret ref and resolution fails,
     // skip this provider entirely so the chain falls through to the next.
     const rawKey = model.providerConfig.apiKey;
-    const needsResolution = rawKey === "secretref-managed"
-      || (typeof rawKey === "object" && rawKey !== null);
+    const needsResolution = rawKey === "secretref-managed" || (typeof rawKey === "object" && rawKey !== null);
     if (needsResolution && !resolvedApiKey) {
       throw new Error(`API key for provider "${model.providerId}" could not be resolved from secret ref`);
     }
@@ -675,18 +704,6 @@ export class FallbackLlmClient {
       return await this.callAnthropic(effectiveConfig, model.modelId, messages, options);
     }
 
-    if (model.providerConfig.api === "codex-cli") {
-      // Registers the core subprocess transport only when no host/benchmark
-      // runner claimed the seam, so daemon/plugin runtimes work out of the box.
-      ensureCodexSubscriptionRunnerRegistered();
-      return await callCodexCliFallback(
-        effectiveConfig,
-        model.modelId,
-        messages,
-        { timeoutMs: options.timeoutMs, signal: options.signal },
-      );
-    }
-
     if (model.providerConfig.api === "ollama-chat") {
       return await this.callOllamaChat(effectiveConfig, model.modelId, messages, options);
     }
@@ -1125,11 +1142,6 @@ export class FallbackLlmClient {
   }
 }
 
-function abortReason(signal: AbortSignal | undefined): Error {
-  const reason = signal?.reason;
-  return reason instanceof Error ? reason : new Error("fallback LLM request aborted");
-}
-
 function normalizeRuntimePath(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();