@remnic/core 9.69.36 → 9.69.38

package/src/extraction.ts

@@ -20,18 +20,8 @@ import {
   type ProactiveQuestionsResultParsed,
   DaySummaryResultSchema,
 } from "./schemas.js";
-import type {
-  BufferTurn,
-  ExtractionResult,
-  ConsolidationResult,
-  MemoryFile,
-  PluginConfig,
-  LlmTraceEvent,
-  GatewayConfig,
-  MemoryCategory,
-  DaySummaryResult as DaySummaryResultShape,
-  ExtractionFailureClass,
-} from "./types.js";
+import type { BufferTurn, ExtractionResult, ConsolidationResult, MemoryFile, PluginConfig, LlmTraceEvent, GatewayConfig, MemoryCategory, DaySummaryResult as DaySummaryResultShape, ExtractionFailureClass } from "./types.js";
+import type { ExtractedFactSpanRef } from "./extraction-span-config.js";
 import { ModelRegistry } from "./model-registry.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
@@ -53,13 +43,14 @@ import { AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT, clampAmbientCaptureConfidence }
 import {
   CONSOLIDATION_RESPONSE_SCHEMA,
   CUE_ANCHOR_PROMPT_INSTRUCTION,
-  EXTRACTION_RESPONSE_SHAPE,
+  extractionResponseShape,
   OUTPUT_LANGUAGE_POLICY,
   PROFILE_CONSOLIDATION_RESPONSE_SCHEMA,
   buildConsolidationSystemPrompt,
   buildExtractionInstructions,
   buildProfileConsolidationSystemPrompt,
   eventTimePromptInstruction,
+  spanModePromptSection,
 } from "./extraction-prompt.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import {
@@ -70,8 +61,15 @@ import {
   isPlainRecord,
 } from "./extraction-normalization.js";
 export { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
+import {
+  applyExtractionSpanMaterialization,
+  bindLocalExtractionPrompt,
+  buildSpanMaterializeTurns,
+  stripUntrustedFactSpans,
+  truncateLocalExtractionConversation,
+  type SpanMaterializeTurn,
+} from "./extraction-span-materialize.js";
 import { resolveLocalLlmCapabilities, resolveMemoryLifecycleCapabilities, resolvePipelineProcessingCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
-
 type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
 type ExtractedEntityResult = ExtractionResult["entities"][number];
@@ -113,6 +111,28 @@ function normalizeQuestion(question: ExtractionQuestion): ExtractionQuestion {
   };
 }
 
+function normalizeExtractedSpanRef(value: unknown): ExtractedFactSpanRef | undefined {
+  if (!isPlainRecord(value)) return undefined;
+  const { sourceMessageIndex, charStart, charEnd, frame, sourceHash, sourceLength } = value;
+  if (
+    typeof sourceMessageIndex !== "number" ||
+    typeof charStart !== "number" ||
+    typeof charEnd !== "number" ||
+    typeof frame !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    sourceMessageIndex,
+    charStart,
+    charEnd,
+    frame,
+    ...(typeof sourceHash === "string" && typeof sourceLength === "number"
+      ? { sourceHash, sourceLength }
+      : {}),
+  };
+}
+
 function normalizeFactKey(fact: Pick<ExtractedFactResult, "category" | "content">): string {
   return `${fact.category}:${fact.content.trim().toLowerCase()}`;
 }
@@ -206,6 +226,22 @@ export class ExtractionEngine {
     return !this.useGatewayModelSource && this.client !== null;
   }
 
+  /**
+   * Span-mode materialization (issue #2333 Phase B): sibling module, called
+   * after parse and before sanitize/grounding so downstream sees one content
+   * form. Offsets index the exact prompt turn texts and die at materialization.
+   */
+  private applySpanMaterialization(
+    result: ExtractionResult,
+    spanTurns: readonly SpanMaterializeTurn[],
+  ): ExtractionResult {
+    return applyExtractionSpanMaterialization(
+      result,
+      spanTurns,
+      this.config.extraction?.spanMode ?? "off",
+    );
+  }
+
   /**
    * Build FallbackLlmOptions with the configured gateway agent ID injected.
    */
@@ -328,6 +364,7 @@ export class ExtractionEngine {
               procedureSteps,
               reasoningTrace,
               quote: extractionText(f.quote),
+              span: normalizeExtractedSpanRef(f.span),
               eventTime: extractionText(f.eventTime) ?? extractionText(f.event_time),
             };
           })
@@ -628,7 +665,7 @@ export class ExtractionEngine {
       const ambient = ctx.ambientCapture === true;
       const proactiveAdditions = await this.answerProactiveQuestions(
         conversation, base, proactive, maxAdditional, ctx.sourceConnector, ambient, signal);
-      const sanitizedAdditions = this.sanitizeExtractionResult(proactiveAdditions, ctx.messageTimestamp);
+      const sanitizedAdditions = this.sanitizeExtractionResult({ ...proactiveAdditions, facts: stripUntrustedFactSpans(proactiveAdditions.facts) }, ctx.messageTimestamp);
       const groundedAdditions = applyGroundingWithConnector(this.config, sanitizedAdditions, ctx);
       if (!this.hasExtractionOutputs(groundedAdditions)) return base;
       return this.mergeProactiveExtractionPass(base, groundedAdditions, maxAdditional);
@@ -1102,6 +1139,7 @@ export class ExtractionEngine {
       ? resolvedConnector
       : undefined;
     const { conversation, renderedConversation } = renderExtractionConversation(boundedTurns, headerConnector(sourceConnector));
+    const spanTurns = buildSpanMaterializeTurns(boundedTurns.map((turn) => turn.content));
 
     const groundingSource = boundedTurns
       .map((turn) => turn.content)
@@ -1191,7 +1229,16 @@ export class ExtractionEngine {
           this.profiler.endSpan("local-llm", extractionTraceId);
           this.emit({ kind: "llm_end", traceId, model: this.config.localLlmModel, operation: "extraction", durationMs });
           log.debug(`extraction: used local LLM — ${localResult.facts.length} facts, ${localResult.entities.length} entities`);
-          const sanitized = this.sanitizeExtractionResult(localResult, messageTimestamp);
+          const localSpanTurns = bindLocalExtractionPrompt(
+            conversation,
+            boundedTurns,
+            this.modelRegistry.calculateContextSizes(
+              this.config.localLlmModel,
+              this.config.localLlmMaxContext,
+            ).maxInputChars,
+            renderedConversation,
+          ).spanTurns;
+          const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(localResult, localSpanTurns), messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
           return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1240,7 +1287,7 @@ export class ExtractionEngine {
           this.profiler.endSpan("direct-client", extractionTraceId);
           this.emit({ kind: "llm_end", traceId, model: this.config.model, operation: "extraction", durationMs });
           log.debug(`extraction: used direct client (${this.config.model}) — ${directResult.facts.length} facts, ${directResult.entities.length} entities`);
-          const sanitized = this.sanitizeExtractionResult(directResult, messageTimestamp);
+          const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(directResult, spanTurns), messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
           return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1303,7 +1350,7 @@ export class ExtractionEngine {
           role: "system" as const,
           content:
             buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
-            `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
+            `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}`,
         },
         { role: "user" as const, content: conversation },
       ];
@@ -1338,7 +1385,7 @@ export class ExtractionEngine {
           `extracted ${result.facts.length} facts, ${result.entities.length} entities, ${(result.questions ?? []).length} questions via fallback (${detailed.modelUsed})`,
         );
         const normalized = this.normalizeExtractionResultPayload(result);
-        const sanitized = this.sanitizeExtractionResult(normalized, messageTimestamp);
+        const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(normalized, spanTurns), messageTimestamp);
         const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
         const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
         return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1414,9 +1461,7 @@ export class ExtractionEngine {
     log.debug(`Model context: ${contextSizes.description}`);
 
     const maxConversationChars = contextSizes.maxInputChars;
-    const truncatedConversation = conversation.length > maxConversationChars
-      ? conversation.slice(0, maxConversationChars) + "\n\n[truncated]"
-      : conversation;
+    const truncatedConversation = truncateLocalExtractionConversation(conversation, maxConversationChars);
 
     const localPrompt = `You are a memory extraction system. Extract durable, reusable memories from this conversation.
 
@@ -1449,9 +1494,9 @@ ${CUE_ANCHOR_PROMPT_INSTRUCTION}\n- Include at most five durable relationships.$
 - Each fact must include a quote copied verbatim from one contiguous conversation span.` : ""}${lifecycleCaps.extractionScopeClassification ? `
 - Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}${this.config.subjectClassification?.enabled === true ? `
 - Set each fact subject to "user" when it models the person (preferences, relationships, biography, moments, commitments about their life) or "agent" when it is reusable operating knowledge (procedures, principles, tool-usage lessons, debugging strategies, environment facts with no personal content).` : ""}${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}
-${eventTimePromptInstruction(this.config)}
+${eventTimePromptInstruction(this.config)}${spanModePromptSection(this.config.extraction?.spanMode ?? "off")}
 Return only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:
-${EXTRACTION_RESPONSE_SHAPE}
+${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}
 
 Conversation:
 ${truncatedConversation}`;
@@ -1542,7 +1587,7 @@ ${truncatedConversation}`;
             role: "system",
             content:
               buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
-              `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
+              `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}`,
           },
           { role: "user", content: conversation },
         ],

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();

package/src/index.ts

@@ -150,8 +150,7 @@ export {
   type CodexCliFallbackResult,
   type CodexCliFallbackRunner,
 } from "./cli-fallback.js";
-export { CODEX_SUBSCRIPTION_PROVIDER_ID, codexSubscriptionBuiltinProviderConfig, createCodexSubscriptionRunner, ensureCodexSubscriptionRunnerRegistered, CodexSubscriptionAuthError, CodexSubscriptionConfigError, CodexSubscriptionTimeoutError } from "./providers/codex-subscription.js";
-
+export { CODEX_SUBSCRIPTION_PROVIDER_ID, beginCodexSubscriptionShutdown, codexSubscriptionBuiltinProviderConfig, createCodexSubscriptionRunner, ensureCodexSubscriptionRunnerRegistered, getCodexSubscriptionRunnerForOwner, terminateActiveCodexSubscriptionChildren, CodexSubscriptionAuthError, CodexSubscriptionConfigError, CodexSubscriptionTimeoutError } from "./providers/codex-subscription.js";
 // ---------------------------------------------------------------------------
 // Smart buffer (issue #563)
 // ---------------------------------------------------------------------------
@@ -564,20 +563,7 @@ export {
   type StructuralSpawnFn,
 } from "./coding/structural-subprocess-provider.js";
 
-export {
-  validateRequest,
-  formatZodError,
-  recallRequestSchema,
-  observeRequestSchema,
-  memoryStoreRequestSchema,
-  suggestionSubmitRequestSchema,
-  type SchemaValidationError,
-  type SchemaName,
-  type RecallRequest,
-  type ObserveRequest,
-  type MemoryStoreRequest,
-  type SuggestionSubmitRequest,
-} from "./access-schema.js";
+export * from "./access-schema.js";
 
 // ---------------------------------------------------------------------------
 // Day summary / LCM