@bitkyc08/opencodex 2.7.42 → 2.7.43

package/src/codex/auth-context.ts

@@ -9,13 +9,16 @@ import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
 import {
-  getCodexAccountHealthSnapshot,
+  codexQuotaScopeForModel,
+  getCodexQuotaHealthSnapshot,
   releaseCodexQuotaProbeLease,
+  releaseCodexQuotaScopeProbeLease,
   tryAcquireCodexQuotaProbeLease,
-  pickLowestUsageCodexAccount,
+  tryAcquireCodexQuotaScopeProbeLease,
+  pickAlternateCodexAccount,
   resolveCodexAccountForThreadDetailed,
 } from "./routing";
-import type { CodexCooldownSource } from "./routing";
+import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse } from "../bridge";
 import { getAccountQuota } from "./quota";
@@ -34,8 +37,12 @@ export type CodexAuthContext =
        * Set when this request was admitted through an active quota cooldown as
        * the account's single probe. Must be echoed into the upstream outcome so
        * only this request can clear the cooldown (#433).
-       */
+      */
       probeLeaseId?: string;
+      /** Native model quota group selected for this request, when known. */
+      quotaScope?: CodexQuotaScope;
+      /** Scope that owns `probeLeaseId`, when it is a scoped recovery probe. */
+      probeQuotaScope?: CodexQuotaScope;
     }
   | {
       // Main Codex account participating in rotation: token injected from ~/.codex/auth.json
@@ -46,6 +53,8 @@ export type CodexAuthContext =
       chatgptAccountId: string;
       /** See `pool.probeLeaseId`. */
       probeLeaseId?: string;
+      quotaScope?: CodexQuotaScope;
+      probeQuotaScope?: CodexQuotaScope;
     };
 
 /** Probe lease carried by this context, when it holds one. */
@@ -53,13 +62,20 @@ export function codexProbeLeaseId(ctx: CodexAuthContext | undefined): string | u
   return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeLeaseId : undefined;
 }
 
+/** Scope of a lease carried by this context, when it probes a model-specific quota. */
+export function codexProbeQuotaScope(ctx: CodexAuthContext | undefined): CodexQuotaScope | undefined {
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeQuotaScope : undefined;
+}
+
 /**
  * Hand back a probe lease for a request that will not reach upstream. Safe to
  * call with a context that holds no lease.
  */
 export function releaseCodexAuthContextProbeLease(ctx: CodexAuthContext | undefined): void {
   const leaseId = codexProbeLeaseId(ctx);
-  if (ctx && leaseId) releaseCodexQuotaProbeLease(ctx.accountId!, leaseId);
+  if (!ctx || ctx.kind === "main" || !leaseId) return;
+  if (ctx.probeQuotaScope) releaseCodexQuotaScopeProbeLease(ctx.accountId!, ctx.probeQuotaScope, leaseId);
+  else releaseCodexQuotaProbeLease(ctx.accountId!, leaseId);
 }
 
 export type OcxRuntimeProviderConfig = OcxProviderConfig & {
@@ -99,13 +115,20 @@ export class CodexAccountCooldownError extends Error {
   accountId: string;
   cooldownUntil: number;
   cooldownSource?: CodexCooldownSource;
+  quotaScope?: CodexQuotaScope;
 
-  constructor(accountId: string, cooldownUntil: number, cooldownSource?: CodexCooldownSource) {
+  constructor(
+    accountId: string,
+    cooldownUntil: number,
+    cooldownSource?: CodexCooldownSource,
+    quotaScope?: CodexQuotaScope,
+  ) {
     super("Selected Codex account is cooling down");
     this.name = "CodexAccountCooldownError";
     this.accountId = accountId;
     this.cooldownUntil = cooldownUntil;
     this.cooldownSource = cooldownSource;
+    this.quotaScope = quotaScope;
   }
 }
 
@@ -127,7 +150,12 @@ export function cooldownAccountLabel(accountId: string): string {
  */
 export function cooldownErrorMessage(err: CodexAccountCooldownError): string {
   const until = new Date(err.cooldownUntil).toISOString();
-  return `Selected Codex account (${cooldownAccountLabel(err.accountId)}) is cooling down until ${until}`
+  const scope = err.quotaScope === "spark"
+    ? "Spark quota"
+    : err.quotaScope === "shared"
+      ? "shared native quota"
+      : null;
+  return `Selected Codex account (${cooldownAccountLabel(err.accountId)})${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
     + ` (source: ${err.cooldownSource ?? "default"}).`
     + ` Run 'ocx account list openai' to find the id, then`
     + ` 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.`;
@@ -157,6 +185,8 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
 
 export interface ResolveCodexAuthContextOptions {
   excludeAccountId?: string;
+  /** Final native model selected for this request, used to select its quota group. */
+  modelId?: string;
 }
 
 export async function resolveCodexAuthContext(
@@ -171,16 +201,17 @@ export async function resolveCodexAuthContext(
   }
   reconcileMainCodexAccountRuntimeState();
   const threadId = headers.get("x-codex-parent-thread-id");
+  const quotaScope = codexQuotaScopeForModel(options.modelId);
   const resolution = options.excludeAccountId
     ? (() => {
-        const accountId = pickLowestUsageCodexAccount(config, options.excludeAccountId);
+        const accountId = pickAlternateCodexAccount(config, options.excludeAccountId!, Date.now(), quotaScope);
         return accountId
           ? { status: "selected" as const, accountId }
           : { status: "none" as const };
       })()
-    : resolveCodexAccountForThreadDetailed(threadId, config);
+    : resolveCodexAccountForThreadDetailed(threadId, config, Date.now(), quotaScope);
   if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
-  const accountId = resolution.status === "selected" ? resolution.accountId : null;
+  let accountId = resolution.status === "selected" ? resolution.accountId : null;
   if (!accountId) throw new CodexPoolAuthenticationError();
   // Lazy prime: if the selected account has no quota yet, the pool is likely
   // unprimed (dashboard never opened, or startup prime was blocked). Kick a
@@ -194,15 +225,21 @@ export async function resolveCodexAuthContext(
   }
   // Snapshot (not just the deadline) so a refused request can report WHY it is cooled:
   // a literal Retry-After reads very differently to a user than a reset-derived guess.
-  const cooldown = getCodexAccountHealthSnapshot(accountId);
+  const cooldown = getCodexQuotaHealthSnapshot(accountId, quotaScope);
   const cooldownUntil = cooldown?.cooldownUntil;
   // A cooled-down account never sends traffic, so upstream recovery can never be
   // observed and the cooldown outlives the real limit. Admit one probe per
   // interval; its outcome decides whether the cooldown ends (#433).
   let probeLeaseId: string | undefined;
+  let probeQuotaScope: CodexQuotaScope | undefined;
   if (cooldownUntil) {
-    probeLeaseId = tryAcquireCodexQuotaProbeLease(accountId) ?? undefined;
-    if (!probeLeaseId) throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource);
+    probeQuotaScope = cooldown?.quotaScope;
+    probeLeaseId = probeQuotaScope
+      ? tryAcquireCodexQuotaScopeProbeLease(accountId, probeQuotaScope) ?? undefined
+      : tryAcquireCodexQuotaProbeLease(accountId) ?? undefined;
+    if (!probeLeaseId) {
+      throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
+    }
   }
 
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
@@ -210,7 +247,8 @@ export async function resolveCodexAuthContext(
     const token = getMainAccountToken();
     if (!token) {
       // Nothing will reach upstream, so give the probe back instead of burning it.
-      if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+      if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
+      else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
       throw new CodexPoolAuthenticationError();
     }
     return {
@@ -218,7 +256,9 @@ export async function resolveCodexAuthContext(
       accountId,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
+      ...(probeQuotaScope ? { probeQuotaScope } : {}),
     };
   }
 
@@ -230,10 +270,13 @@ export async function resolveCodexAuthContext(
       generation: token.generation,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
+      ...(probeQuotaScope ? { probeQuotaScope } : {}),
     };
   } catch (cause) {
-    if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+    if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
+    else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
     if (shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
       markAccountNeedsReauth(accountId);
     }
@@ -245,9 +288,9 @@ export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefine
   if (ctx?.kind !== "pool" && ctx?.kind !== "main-pool") return;
   // A context holding the probe lease was deliberately admitted through the cooldown.
   if (ctx.probeLeaseId) return;
-  const cooldown = getCodexAccountHealthSnapshot(ctx.accountId);
+  const cooldown = getCodexQuotaHealthSnapshot(ctx.accountId, ctx.quotaScope);
   if (cooldown?.cooldownUntil) {
-    throw new CodexAccountCooldownError(ctx.accountId, cooldown.cooldownUntil, cooldown.cooldownSource);
+    throw new CodexAccountCooldownError(ctx.accountId, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope);
   }
 }
 

package/src/codex/catalog/parsing.ts

@@ -141,9 +141,24 @@ export function isMediaGenerationModelId(id: string): boolean {
   return MEDIA_GEN_ID_RE.test(id);
 }
 
+/**
+ * Gemini image-capable chat models produce inline images within text responses
+ * via the Responses API. Explicit allowlist only — a broad `/gemini/ && /image/`
+ * heuristic resurrects standalone media-gen IDs (e.g. gemini-3-pro-image).
+ */
+const GEMINI_IMAGE_CHAT_MODEL_IDS = new Set([
+  "gemini-3.1-flash-image",
+  "gemini-2.0-flash-preview-image-generation",
+  "gemini-3-pro-image-preview",
+]);
+
+function isGeminiImageChatModel(id: string): boolean {
+  return GEMINI_IMAGE_CHAT_MODEL_IDS.has(id);
+}
+
 export function shouldExposeRoutedModel(model: CatalogModel): boolean {
   if (isRoutedModelCompatibilityExcluded(`${model.provider}/${model.id}`)) return false;
-  if (model.provider === "cursor" && model.id === "gemini-3-pro-image-preview") return true;
+  if (isGeminiImageChatModel(model.id)) return true;
   return !isMediaGenerationModelId(model.id);
 }
 

package/src/codex/catalog/provider-fetch.ts

@@ -39,7 +39,11 @@ import {
   targetKey,
 } from "../../combos";
 import type { NormalizedComboConfig } from "../../combos/types";
-import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import {
+  ProviderOutboundPolicyError,
+  providerOutboundGet,
+  providerRedirectError,
+} from "../../lib/provider-outbound";
 import { redactSecretString } from "../../lib/redact";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 
@@ -71,6 +75,32 @@ export function isProviderModelsApiItems(value: unknown): value is ProviderModel
   );
 }
 
+/**
+ * Normalize OpenAI-compatible /models payloads for catalog discovery.
+ * Supports `{ data: [...] }` and top-level arrays (Together AI `#617`).
+ * Google's `{ models: [...] }` is handled by the connectivity probe only — catalog
+ * discovery must not treat a stray `models` key on openai-chat responses as valid.
+ */
+export function providerModelsListFromResponse(json: unknown): unknown {
+  if (Array.isArray(json)) return json;
+  if (json !== null && typeof json === "object" && !Array.isArray(json)) {
+    const data = (json as { data?: unknown }).data;
+    if (Array.isArray(data)) return data;
+  }
+  return undefined;
+}
+
+/** Connectivity-probe shape: also accepts Google `{ models: [...] }`. */
+export function providerModelsListFromProbeResponse(json: unknown): unknown {
+  if (Array.isArray(json)) return json;
+  if (json !== null && typeof json === "object" && !Array.isArray(json)) {
+    const obj = json as { data?: unknown; models?: unknown };
+    if (Array.isArray(obj.data)) return obj.data;
+    if (Array.isArray(obj.models)) return obj.models;
+  }
+  return undefined;
+}
+
 export function configuredContextWindow(prov: OcxProviderConfig, id: string): number | undefined {
   const configured = modelRecordValue(prov.modelContextWindows, id) ?? prov.contextWindow;
   return typeof configured === "number" && configured > 0 ? configured : undefined;
@@ -322,21 +352,20 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     };
   };
   try {
-    const destinationError = await providerDestinationResolvedError(name, {
-      baseUrl: url,
-      allowPrivateNetwork: prov.allowPrivateNetwork,
+    const res = await providerOutboundGet(name, prov, url, {
+      headers,
+      signal: AbortSignal.timeout(8000),
     });
-    if (destinationError) {
-      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
+    const redirectError = await providerRedirectError(res, url);
+    if (redirectError) {
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
       if (shouldLog) {
         console.warn(
-          `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${destinationError} [urlClass=${urlClass}, fallback=${fallback}].`,
+          `[opencodex] Provider model discovery for "${name}" ${redirectError} [urlClass=${urlClass}, fallback=${fallback}].`,
         );
       }
       return models;
     }
-
-    const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
       if (shouldLog) {
@@ -366,9 +395,7 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
       }
       return models;
     }
-    const data = json !== null && typeof json === "object" && !Array.isArray(json)
-      ? (json as { data?: unknown }).data
-      : undefined;
+    const data = providerModelsListFromResponse(json);
     if (!isProviderModelsApiItems(data)) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
       if (shouldLog) {
@@ -421,6 +448,15 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     setCached(name, live);
     return live;
   } catch (error) {
+    if (error instanceof ProviderOutboundPolicyError) {
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${error.message} [urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
+      return models;
+    }
     const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "network" });
     if (shouldLog) {
       console.warn(

package/src/codex/catalog/sync.ts

@@ -329,9 +329,11 @@ export function mergeCatalogEntriesForSync(
   multiAgentMode: MultiAgentMode = "default",
   exactComboSlugs: ReadonlySet<string> = new Set(),
   hasPhysicalComboProvider = false,
+  includeNativeOpenAi = true,
 ): RawEntry[] {
   const rank = new Map(featured.map((slug, i) => [slug, i] as const));
-  const native = catalogModels
+  const native = includeNativeOpenAi
+    ? catalogModels
     .filter(m => typeof m.slug === "string"
       && !(m.slug as string).includes("/")
       && m.owned_by !== COMBO_NAMESPACE
@@ -367,11 +369,14 @@ export function mergeCatalogEntriesForSync(
       // for subagent max spawns; wire-clamped to the model's real top rung).
       if (!isGpt56NativeSlug(slug)) ensureUltraReasoningLevel(preserved);
       return preserved;
-    });
+    })
+    : [];
 
   // Backfill any native OpenAI slug that the on-disk catalog is missing (e.g. gpt-5.5), so a
   // routed provider exposing the same id can never delete the native OpenAI/Codex base row.
+  // Skip when no enabled canonical openai provider exists (#636) — bare gpt-* would 404.
   const nativeSlugs = new Set(native.flatMap(m => typeof m.slug === "string" ? [m.slug] : []));
+  if (includeNativeOpenAi) {
   for (const slug of nativeOpenAiSlugs()) {
     if (nativeSlugs.has(slug)) continue;
     nativeSlugs.add(slug);
@@ -382,6 +387,7 @@ export function mergeCatalogEntriesForSync(
         : 9;
     native.push(deriveEntry(template ? JSON.parse(JSON.stringify(template)) : null, slug, "OpenAI native model (Codex OAuth passthrough).", priority));
   }
+  }
 
   const freshSlugs = new Set(
     routedEntries.flatMap(entry => typeof entry.slug === "string" ? [entry.slug] : []),
@@ -497,7 +503,16 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{
   // native AND routed so the advertised flag matches the implemented endpoint (phase 120.4) and a
   // native template can never leak supports_websockets while the flag is off.
   const wsEnabled = websocketsEnabled(config);
-  catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider);
+  const enabledProviders = Object.entries(config.providers ?? {})
+    .filter(([, prov]) => prov.disabled !== true);
+  const hasCanonicalOpenai = enabledProviders.some(([name, prov]) =>
+    name === "openai" && isCanonicalOpenAiForwardProvider(prov),
+  );
+  // #636: when the user only configured non-OpenAI providers (e.g. kimi), do not advertise
+  // bare gpt-* rows that hard-404 via NoEnabledOpenAiProviderError. Keep natives when no
+  // providers are configured yet (fresh install / catalog bootstrap tests).
+  const includeNativeOpenAi = enabledProviders.length === 0 || hasCanonicalOpenai;
+  catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider, includeNativeOpenAi);
   clampCatalogModelsToCodexSupport(catalog.models);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");

package/src/codex/catalog.ts

@@ -1,6 +1,6 @@
 // AUTO-SPLIT facade: original catalog.ts body moved into ./catalog/* modules.
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
-export { isMediaGenerationModelId, readCodexCatalogPath, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
+export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
 export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";

package/src/codex/history-provider.ts

@@ -1,10 +1,18 @@
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { zstdDecompressSync } from "node:zlib";
 import { Database } from "bun:sqlite";
 import { CODEX_HOME } from "./paths";
 import { atomicWriteFile, getConfigDir } from "../config";
 
+/**
+ * Cap for decompressing a lone `.jsonl.zst` rollout during quarantine restore.
+ * Bounds peak memory while reconstructing thread rows; never write the decoded
+ * JSONL to disk.
+ */
+export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+
 const STATE_DB_PATH = join(CODEX_HOME, "state_5.sqlite");
 function historyBackupPathFor(stateDbPath: string): string {
   const normalized = process.platform === "win32" ? resolve(stateDbPath).toLowerCase() : resolve(stateDbPath);
@@ -252,7 +260,7 @@ function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
  * (codex-rs `apply_session_meta_from_item`). We base our patch on the most recent metadata so we
  * never resurrect a stale provider that a later app-written `session_meta` already changed.
  */
-function readLatestSessionMeta(path: string): ParsedSessionMeta | null {
+export function readLatestSessionMeta(path: string): ParsedSessionMeta | null {
   const raw = readFileSync(path, "utf8");
   const lines = raw.split("\n");
   for (let i = lines.length - 1; i >= 0; i--) {
@@ -265,6 +273,142 @@ function readLatestSessionMeta(path: string): ParsedSessionMeta | null {
   return null;
 }
 
+/**
+ * Fields needed to re-insert a production-shaped `threads` row from a rollout JSONL when a
+ * Phase-2 quarantine predates full `satellite-backup.json` thread snapshots.
+ *
+ * Uses the same last-writer-wins `session_meta` fold as {@link readLatestSessionMeta}, plus the
+ * first user-message preview (codex-rs `list.rs` / `EventMsg::UserMessage` path).
+ */
+export interface RolloutThreadFields {
+  id: string;
+  modelProvider: string;
+  source: string;
+  firstUserMessage: string;
+  hasUserEvent: number;
+  cwd?: string;
+  historyMode?: string;
+  cliVersion?: string;
+}
+
+function textFromContentParts(content: unknown): string | null {
+  if (typeof content === "string" && content.trim()) return content.trim();
+  if (!Array.isArray(content)) return null;
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as Record<string, unknown>;
+    if (typeof p.text === "string" && p.text.trim()) parts.push(p.text.trim());
+    else if (typeof p.input_text === "string" && p.input_text.trim()) parts.push(p.input_text.trim());
+  }
+  const joined = parts.join("\n").trim();
+  return joined || null;
+}
+
+/** Extract the first user-message preview from a rollout line, or null. */
+function extractUserMessagePreview(line: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as { type?: unknown; payload?: unknown };
+  const payload = record.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const p = payload as Record<string, unknown>;
+
+  if (record.type === "event_msg") {
+    // codex-rs EventMsg::UserMessage — payload.type is "user_message" (or omitted in fixtures).
+    if (p.type === "user_message" || typeof p.message === "string") {
+      if (typeof p.message === "string" && p.message.trim()) return p.message.trim();
+      const fromContent = textFromContentParts(p.content);
+      if (fromContent) return fromContent;
+    }
+    return null;
+  }
+
+  if (record.type === "response_item") {
+    if (p.type === "message" && p.role === "user") {
+      return textFromContentParts(p.content);
+    }
+  }
+  return null;
+}
+
+/**
+ * Reconstruct thread identity + listing fields from a staged/restored rollout JSONL.
+ * Returns null when the file is missing or has no parseable `session_meta`.
+ *
+ * Accepts plain `.jsonl` or a lone `.jsonl.zst` (legacy Phase-2 quarantine). Compressed
+ * rollouts are decompressed in memory with {@link MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES};
+ * no decompressed copy is written to disk.
+ */
+export function readThreadFieldsFromRollout(path: string): RolloutThreadFields | null {
+  if (!path || !existsSync(path)) return null;
+  let raw: string;
+  try {
+    raw = path.endsWith(".zst")
+      ? decompressRolloutZstUtf8(path)
+      : readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  return parseThreadFieldsFromRolloutText(raw);
+}
+
+function decompressRolloutZstUtf8(
+  path: string,
+  maxBytes: number = MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES,
+): string {
+  const compressed = readFileSync(path);
+  const decoded = zstdDecompressSync(compressed as Uint8Array<ArrayBuffer>, {
+    maxOutputLength: maxBytes,
+  });
+  if (decoded.byteLength > maxBytes) {
+    throw new Error("rollout_zst_too_large");
+  }
+  return new TextDecoder().decode(decoded);
+}
+
+function parseThreadFieldsFromRolloutText(raw: string): RolloutThreadFields | null {
+  const lines = raw.split("\n");
+  let latest: ParsedSessionMeta | null = null;
+  let firstUserMessage = "";
+  for (const line of lines) {
+    if (!line) continue;
+    if (line.includes("\"session_meta\"")) {
+      const meta = parseSessionMetaLine(line);
+      if (meta) latest = meta;
+    }
+    if (!firstUserMessage) {
+      const preview = extractUserMessagePreview(line);
+      if (preview) firstUserMessage = preview;
+    }
+  }
+  if (!latest) return null;
+  const payload = latest.record.payload;
+  const id = typeof payload.id === "string" ? payload.id : "";
+  if (!id) return null;
+  const modelProvider = typeof payload.model_provider === "string" && payload.model_provider
+    ? payload.model_provider
+    : "openai";
+  const source = typeof payload.source === "string" && payload.source
+    ? payload.source
+    : "cli";
+  return {
+    id,
+    modelProvider,
+    source,
+    firstUserMessage,
+    hasUserEvent: firstUserMessage.trim() ? 1 : 0,
+    ...(typeof payload.cwd === "string" ? { cwd: payload.cwd } : {}),
+    ...(typeof payload.history_mode === "string" ? { historyMode: payload.history_mode } : {}),
+    ...(typeof payload.cli_version === "string" ? { cliVersion: payload.cli_version } : {}),
+  };
+}
+
 /**
  * Make a thread's rollout reflect a provider/source change by APPENDING a new `session_meta` line,
  * rather than rewriting line 1. The appended line clones the latest metadata payload (so no field