@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/cli-installation-targets.ts

@@ -0,0 +1,158 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { win32 } from "node:path";
+import { SHIM_MARKER } from "./shim-templates";
+import type { CodexCliInstallationIdentityInput } from "./cli-installation-identity";
+
+/**
+ * The proof-captured launcher snapshot used to identify the selected candidate.
+ * Every field is optional because older launchers and direct Bun/source runs
+ * supply no snapshot at all; derivation fails closed rather than reading the
+ * ambient environment.
+ */
+export interface CodexCliInstallationSnapshot {
+  readonly codexCliPath?: string | null;
+  readonly path?: string | null;
+  readonly pathExt?: string | null;
+}
+
+export type CodexCliInstallationTargetRefusal =
+  | "unsupported_platform"
+  | "candidate_unavailable"
+  | "unsupported_layout"
+  | "toolchain_unresolved";
+
+export type CodexCliInstallationTargetDerivation =
+  | { readonly kind: "derived"; readonly input: CodexCliInstallationIdentityInput }
+  | { readonly kind: "unavailable"; readonly reason: CodexCliInstallationTargetRefusal };
+
+export interface CodexCliInstallationTargetDeps {
+  readonly platform?: NodeJS.Platform;
+  readonly exists?: (path: string) => boolean;
+  /** Bounded prefix read used only to recognize an OpenCodex-owned wrapper. */
+  readonly fileContains?: (path: string, marker: string) => boolean;
+}
+
+const DEFAULT_PATH_EXT = ".COM;.EXE;.BAT;.CMD;.PS1";
+const SHIM_PROBE_BYTES = 8 * 1024;
+const CODEX_PACKAGE_SUFFIX = "\\node_modules\\@openai\\codex\\bin\\codex.js";
+
+function defaultFileContains(path: string, marker: string): boolean {
+  let descriptor: number | undefined;
+  let contains = false;
+  try {
+    descriptor = openSync(path, "r");
+    const bytes = Buffer.allocUnsafe(SHIM_PROBE_BYTES);
+    const count = readSync(descriptor, bytes, 0, bytes.length, 0);
+    contains = bytes.subarray(0, count).toString("utf8").includes(marker);
+  } catch {
+    contains = false;
+  } finally {
+    if (descriptor !== undefined) {
+      try { closeSync(descriptor); } catch { contains = false; }
+    }
+  }
+  return contains;
+}
+
+/**
+ * First match wins, mirroring PATH resolution: directories in order, and within
+ * each directory every PATHEXT suffix in order (or the exact name when it
+ * already carries an extension). Skipping a hit to keep scanning would attest
+ * something other than the launcher that actually resolves.
+ */
+function scanPath(
+  name: string,
+  pathValue: string | null | undefined,
+  pathExt: string | null | undefined,
+  exists: (path: string) => boolean,
+): string | null {
+  const extensions = (pathExt ?? DEFAULT_PATH_EXT).split(";").map(value => value.trim()).filter(Boolean);
+  const names = /\.[a-z0-9]+$/i.test(name) ? [name] : extensions.map(ext => name + ext.toLowerCase());
+  for (const entry of (pathValue ?? "").split(";")) {
+    const dir = entry.trim().replace(/^"+|"+$/g, "");
+    if (!dir) continue;
+    for (const candidateName of names) {
+      const candidate = win32.join(dir, candidateName);
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Derive the four attestation inputs from the proof-captured launcher snapshot.
+ * Discovery only proposes candidate paths; the held-handle observation remains
+ * the authority, so a stale or racing probe can only produce a refusal, never a
+ * false identity. No ambient environment is read: without a snapshot the result
+ * is unavailable rather than silently trusting the child's environment.
+ */
+export function deriveCodexCliInstallationInput(
+  snapshot: CodexCliInstallationSnapshot,
+  deps: CodexCliInstallationTargetDeps = {},
+): CodexCliInstallationTargetDerivation {
+  if ((deps.platform ?? process.platform) !== "win32") {
+    return { kind: "unavailable", reason: "unsupported_platform" };
+  }
+  const exists = deps.exists ?? existsSync;
+  const fileContains = deps.fileContains ?? defaultFileContains;
+  const configured = snapshot.codexCliPath;
+
+  let candidate: string | null;
+  if (configured) {
+    if (/^[a-z]:[\\/]/i.test(configured)) {
+      if (!exists(configured)) return { kind: "unavailable", reason: "candidate_unavailable" };
+      candidate = win32.normalize(configured);
+    } else {
+      if (configured.includes("/") || configured.includes("\\")) {
+        return { kind: "unavailable", reason: "candidate_unavailable" };
+      }
+      candidate = scanPath(configured, snapshot.path, snapshot.pathExt, exists);
+      if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+    }
+  } else {
+    candidate = scanPath("codex", snapshot.path, snapshot.pathExt, exists);
+    if (!candidate) return { kind: "unavailable", reason: "candidate_unavailable" };
+  }
+
+  // An OpenCodex wrapper at the npm prefix is our own launcher, not the npm
+  // artifact. The renamed original beside it is the file npm wrote.
+  if (/\.cmd$/i.test(candidate) && fileContains(candidate, SHIM_MARKER)) {
+    const backing = candidate.slice(0, -".cmd".length) + ".opencodex-real.cmd";
+    if (!exists(backing)) return { kind: "unavailable", reason: "unsupported_layout" };
+    candidate = backing;
+  }
+
+  const base = win32.basename(candidate).toLowerCase();
+  let prefix: string;
+  if (base === "codex.cmd" || base === "codex.opencodex-real.cmd") {
+    prefix = win32.dirname(candidate);
+  } else if (candidate.toLowerCase().endsWith(CODEX_PACKAGE_SUFFIX)) {
+    prefix = candidate.slice(0, candidate.length - CODEX_PACKAGE_SUFFIX.length);
+  } else {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+  if (!exists(win32.join(prefix, "node_modules", "@openai", "codex", "package.json"))) {
+    return { kind: "unavailable", reason: "unsupported_layout" };
+  }
+
+  // The npm cmd-shim itself prefers %dp0%\node.exe before falling back to PATH.
+  let node = win32.join(prefix, "node.exe");
+  if (!exists(node)) {
+    const resolved = scanPath("node.exe", snapshot.path, null, exists);
+    if (!resolved) return { kind: "unavailable", reason: "toolchain_unresolved" };
+    node = resolved;
+  }
+  const npmCli = win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!exists(npmCli)) return { kind: "unavailable", reason: "toolchain_unresolved" };
+
+  return {
+    kind: "derived",
+    input: Object.freeze({
+      candidate,
+      npmPrefix: prefix,
+      npmCli,
+      node,
+      candidateSource: "selected",
+    }),
+  };
+}

package/src/codex/context-compat.ts

@@ -7,14 +7,17 @@ export const CONTEXT_BACKEND_PREFIX = "/backend-api/codex";
 
 /** The single definition of the opt-in, shared by injection and the runtime gate. */
 export function contextExperimentalEnabled(configContent: string): boolean {
-  let parsed: { features?: { context_management?: { experimental_mode?: boolean } } };
+  let parsed: { features?: { context_management?: boolean | { experimental_mode?: boolean } } };
   try {
     parsed = Bun.TOML.parse(configContent) as typeof parsed;
   } catch {
     // Injection tolerates incomplete user config; malformed TOML is not an opt-in.
     return false;
   }
-  return parsed.features?.context_management?.experimental_mode === true;
+  // Codex FeatureToml accepts either a boolean or the experimental_mode table.
+  // Keep strict true checks: malformed values must not activate a credentialed relay.
+  const setting = parsed.features?.context_management;
+  return setting === true || (typeof setting === "object" && setting?.experimental_mode === true);
 }
 
 let activation: { key: string; active: boolean } | undefined;

package/src/codex/convergence.ts

@@ -36,6 +36,7 @@ import {
   catalogHasRoutedEntries,
   findSupportedNativeTemplate,
   legacyCatalogBackupPath,
+  nativeMultiAgentDefaults,
   parseCatalogJson,
   type RawCatalog,
   type RawEntry,
@@ -69,6 +70,7 @@ import {
   clampCatalogModelsToObservedCodexSupport,
   supportedCodexReasoningEffortsFromObservedCatalog,
 } from "./catalog/effort";
+import { suppressedSyntheticMaxCatalogSlugs } from "./catalog/model-hints";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
@@ -305,6 +307,7 @@ function prepareCatalog(
     [catalog.models ?? [], ...nativeRecoverySources],
   );
   const catalogModels = nativeCatalogModels;
+  const suppressedSyntheticMaxSlugs = suppressedSyntheticMaxCatalogSlugs(config, ordered, catalogModels);
   const routedEntries = buildCatalogEntriesFromObservedState({
     template: template ? JSON.parse(JSON.stringify(template)) : null,
     gptSlugs: [],
@@ -371,8 +374,10 @@ function prepareCatalog(
     includeNativeOpenAi,
     accountBoundEntries,
     suppressedBareNativeSlugs,
+    suppressedSyntheticMaxSlugs,
     openaiContextCap,
     nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
+    nativeMultiAgentDefaults: nativeMultiAgentDefaults(baselineCatalogModels),
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],

package/src/codex/desired-state.ts

@@ -260,7 +260,10 @@ export async function syncCodexOnStartIfEnabled(
   // The `.catch` is deliberate and stays: a failure to APPLY must not stop the
   // proxy from coming up. A failed sync simply reports no writes. The readiness
   // gate observes the real outcome so /readyz reflects the sync state exactly as
-  // the PR contract defines (ready only on ok=true with no warning).
+  // the contract defines: ready on ok=true once the sync has settled. A nonempty
+  // `warning` is a local-Codex-artifact degradation the sync chose to continue
+  // past, and #5181 is what it cost to treat it as terminal — a healthy
+  // multi-provider proxy reported itself permanently unready.
   const outcome = readinessGate
     ? await runStartupReadinessSync(readinessGate, async () => (await sync(port)) ?? null)
     : await sync(port).catch(() => undefined);

package/src/codex/history-job.ts

@@ -23,7 +23,7 @@ import type {
   CodexHistoryWorkerOperation,
   HistoryWorkerResult,
 } from "./history-worker";
-import { currentHistoryDbBusyTimeoutMs, historyBackupPathFor } from "./history-provider";
+import { currentHistoryDbBusyTimeoutMs, resolveExistingHistoryBackupPath } from "./history-provider";
 import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
 import { getCodexHome, resolveCodexStateDbPath } from "./paths";
 
@@ -32,7 +32,7 @@ import { getCodexHome, resolveCodexStateDbPath } from "./paths";
  *
  * The SQLite root can differ from CODEX_HOME and both environment/config inputs
  * can change between invocations. The parent resolves one exact target and hands
- * those canonical paths to the Worker rather than asking the Worker to infer a
+ * those resolved paths to the Worker rather than asking the Worker to infer a
  * possibly different environment.
  */
 export function resolveCodexHistoryJobTarget(): {
@@ -45,10 +45,10 @@ export function resolveCodexHistoryJobTarget(): {
   return {
     canonicalCodexHome: home,
     canonicalStateDbPath: stateDb,
-    // Derived by the provider's own rule rather than guessed: the manifest lives
-    // in the config directory under a hash of the state database, so a
-    // hand-built path would address a different file entirely.
-    canonicalBackupPath: historyBackupPathFor(stateDb),
+    // Resolve through the provider's canonical-first compatibility rule. Passing
+    // only the newly normalized name would hide a pre-#4442 Windows manifest from
+    // the Worker and make an upgrade look like an empty backup.
+    canonicalBackupPath: resolveExistingHistoryBackupPath(stateDb),
   };
 }
 

package/src/codex/history-provider.ts

@@ -1,9 +1,11 @@
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { zstdDecompressSync } from "node:zlib";
+import { parseSessionMetaLine, type ParsedSessionMeta } from "./history-rollout-read";
+export { MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES, readThreadFieldsFromRollout, type RolloutThreadFields } from "./history-rollout-read";
 import { Database } from "bun:sqlite";
 import { resolveCodexStateDbPath } from "./paths";
+import { openCodexStateForPreflight } from "./history-state-open";
 import { atomicWriteFile, getConfigDir } from "../config";
 import {
   CODEX_HISTORY_RESUMABLE_SOURCES,
@@ -15,13 +17,6 @@ import {
   type CodexHistoryBackupManifest,
 } from "./history-manifest";
 
-/**
- * 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;
-
 /**
  * The manifest that shadows one state database.
  *
@@ -433,23 +428,39 @@ export function preflightCodexHistoryInjection(
     if (!existsSync(resolvedPath)) {
       return restoreEntries.length > 0 ? "history_state_database_missing" : null;
     }
-    db = new Database(resolvedPath, { readonly: true });
+    // Read-only, and narrowed so a cleanly-closed WAL store is inspected rather than refused
+    // (#4943). The open order is the safety property; see history-state-open.ts.
+    db = openCodexStateForPreflight(resolvedPath);
     const columns = db.query<{ name: string }, []>("PRAGMA table_info(threads)").all();
     const paginatedColumn = columns.some(column => column.name === "history_mode");
     if (paginatedColumn && restoreEntries.length > 0) return HISTORY_RELABEL_STANDS_DOWN;
     for (const entry of restoreEntries) assertLegacyHistoryWritable(entry.rolloutPath);
-    const rows = db.query<{ rollout_path: string; history_mode: string | null }, []>(`
-      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}
+    const rows = db.query<{ rollout_path: string; history_mode: string | null; model_provider: string }, []>(`
+      SELECT rollout_path, ${paginatedColumn ? "history_mode" : "NULL AS history_mode"}, model_provider
       FROM threads
       WHERE ${providerTableMode
         ? resumeHistory ? "model_provider IN ('openai', 'opencodex')" : "0"
         : "model_provider = 'opencodex'"}
     `).all();
+    // No ORDER BY: a paginated opencodex row can precede a paginated openai one, so the
+    // verdict waits for the full scan instead of standing down on the first paginated row.
+    let foundPaginatedRow = false;
+    let foundPaginatedOpenaiRow = false;
     for (const row of rows) {
-      if (paginatedColumn || row.history_mode === "paginated") return HISTORY_RELABEL_STANDS_DOWN;
+      if (paginatedColumn || row.history_mode === "paginated") {
+        foundPaginatedRow = true;
+        // A provider-table transition removes the root openai_base_url, and a row already
+        // paginated cannot be relabeled: standing it down would route the openai-tagged
+        // thread to Codex's built-in OpenAI endpoint. A still-legacy row only stands down.
+        if (providerTableMode && row.history_mode === "paginated" && row.model_provider === "openai") {
+          foundPaginatedOpenaiRow = true;
+        }
+        continue;
+      }
       assertLegacyHistoryWritable(row.rollout_path);
     }
-    return null;
+    if (foundPaginatedOpenaiRow) return "history_paginated_openai_requires_native_writer";
+    return foundPaginatedRow ? HISTORY_RELABEL_STANDS_DOWN : null;
   } catch (error) {
     return error instanceof CodexHistoryIntegrityError
       ? error.message
@@ -1018,24 +1029,6 @@ function assertRestoreReadback(
   }
 }
 
-interface ParsedSessionMeta {
-  record: { type?: unknown; timestamp?: unknown; payload: { model_provider?: unknown; source?: unknown } & Record<string, unknown> };
-}
-
-/** Parse one JSONL line into a `session_meta` record, or null if it isn't one. */
-function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
-  const record = parsed as ParsedSessionMeta["record"];
-  if (record.type !== "session_meta" || !record.payload || typeof record.payload !== "object") return null;
-  return { record };
-}
-
 /**
  * Find the LAST `session_meta` line in a rollout, mirroring the app's last-writer-wins fold
  * (codex-rs `apply_session_meta_from_item`). We base our patch on the most recent metadata so we
@@ -1104,142 +1097,6 @@ function compensateConcurrentSessionMetaAppend(
   }
 }
 
-/**
- * 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

package/src/codex/history-rollout-read.ts

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from "node:fs";
+import { zstdDecompressSync } from "node:zlib";
+
+/**
+ * Reading side of Codex rollout JSONL files: the `session_meta` fold and the thread fields a
+ * quarantine restore reconstructs from a rollout.
+ *
+ * Split out of `history-provider.ts` when that file crossed the repository file-size ratchet at
+ * 2009 lines. The cut follows a real seam rather than a line count: everything here reads a
+ * rollout file and returns plain data, while the module it left keeps the database and manifest
+ * writes. Nothing here opens a database or touches a backup manifest.
+ *
+ * `history-provider.ts` re-exports the public names, so existing importers are unaffected.
+ */
+/**
+ * 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;
+
+export interface ParsedSessionMeta {
+  record: { type?: unknown; timestamp?: unknown; payload: { model_provider?: unknown; source?: unknown } & Record<string, unknown> };
+}
+
+/** Parse one JSONL line into a `session_meta` record, or null if it isn't one. */
+export function parseSessionMetaLine(line: string): ParsedSessionMeta | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const record = parsed as ParsedSessionMeta["record"];
+  if (record.type !== "session_meta" || !record.payload || typeof record.payload !== "object") return null;
+  return { record };
+}
+
+/**
+ * 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 } : {}),
+  };
+}