@golba98/codexa 1.0.3 → 1.0.5

package/src/core/agent/tools.ts

@@ -0,0 +1,414 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import { runShellCommand, summarizeCommandResult } from "../process/CommandRunner.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import {
+  getShellWorkspaceGuardMessage,
+  isPathInsideAllowedRoots,
+  resolveWorkspacePath,
+} from "../workspace/workspaceGuard.js";
+import type { AgentToolName } from "./protocol.js";
+
+export interface AgentToolContext {
+  workspaceRoot: string;
+  runtime: ResolvedRuntimeConfig;
+  signal?: AbortSignal;
+}
+
+export interface AgentToolResult {
+  success: boolean;
+  tool: AgentToolName;
+  path?: string;
+  command?: string;
+  paths?: string[];
+  output?: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  durationMs?: number;
+  summary?: string;
+  error?: string;
+}
+
+const MAX_FILE_BYTES = 128 * 1024;
+const MAX_OUTPUT_CHARS = 4_000;
+const MAX_OUTPUT_LINES = 80;
+const SHELL_TIMEOUT_MS = 30_000;
+
+const DANGEROUS_SHELL_PATTERNS: RegExp[] = [
+  /\brm\s+-[^\n;|&]*r[f]?\b/i,
+  /\bsudo\b/i,
+  /\bdoas\b/i,
+  /\bdd\s+.*\bof=/i,
+  /\bmkfs(?:\.[a-z0-9]+)?\b/i,
+  /\bshutdown\b/i,
+  /\breboot\b/i,
+  /\bpoweroff\b/i,
+  /\bchmod\s+-R\s+777\b/i,
+  /:\(\)\s*\{\s*:\|:\s*&\s*\}\s*;/,
+  />\s*\/dev\/(?:sd|hd|nvme|disk)/i,
+];
+
+function preview(text: string, maxChars = MAX_OUTPUT_CHARS): string {
+  const sanitized = sanitizeTerminalOutput(text);
+  return sanitized.length > maxChars ? `${sanitized.slice(0, maxChars)}\n...[truncated]` : sanitized;
+}
+
+function trimOutputLines(text: string, preferTail: boolean): string {
+  const sanitized = sanitizeTerminalOutput(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const lines = sanitized.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  if (lines.length <= MAX_OUTPUT_LINES) return sanitized;
+  const visible = preferTail ? lines.slice(-MAX_OUTPUT_LINES) : lines.slice(0, MAX_OUTPUT_LINES);
+  const hidden = lines.length - visible.length;
+  const marker = `[...${hidden} line${hidden === 1 ? "" : "s"} truncated; showing ${preferTail ? "last" : "first"} ${MAX_OUTPUT_LINES} lines...]`;
+  return preferTail
+    ? [marker, ...visible].join("\n")
+    : [...visible, marker].join("\n");
+}
+
+function stringArg(args: Record<string, unknown>, key: string): string | null {
+  const value = args[key];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+function isReadOnly(runtime: ResolvedRuntimeConfig): boolean {
+  return runtime.policy.sandboxMode === "read-only";
+}
+
+function canWrite(runtime: ResolvedRuntimeConfig): boolean {
+  return runtime.policy.sandboxMode === "workspace-write"
+    || runtime.policy.sandboxMode === "danger-full-access";
+}
+
+function relativeDisplay(workspaceRoot: string, absolutePath: string): string {
+  const relative = path.relative(workspaceRoot, absolutePath).split(path.sep).join("/");
+  return relative || ".";
+}
+
+function hasCargoManifest(workspaceRoot: string): boolean {
+  return existsSync(path.join(workspaceRoot, "Cargo.toml"));
+}
+
+function rustCommandGuard(command: string, context: AgentToolContext): string | null {
+  if (!hasCargoManifest(context.workspaceRoot)) return null;
+  const normalized = command.trim().replace(/\s+/g, " ");
+  const rustcMatch = /^rustc(?:\s+--?[^\s]+)*\s+([^\s]+\.rs)\b/.exec(normalized);
+  if (!rustcMatch) return null;
+  const target = rustcMatch[1]!;
+  const resolved = path.resolve(context.workspaceRoot, target);
+  const rootMain = path.join(context.workspaceRoot, "main.rs");
+  if (resolved !== rootMain || !existsSync(rootMain)) {
+    return "This workspace has Cargo.toml. Use `cargo check` to validate or `cargo run` to run instead of compiling a Rust source file directly with rustc.";
+  }
+  return null;
+}
+
+function resolveAllowedPath(rawPath: string, context: AgentToolContext): { ok: true; absolutePath: string; relativePath: string } | { ok: false; error: string } {
+  if (!isPathInsideAllowedRoots(rawPath, context.workspaceRoot, context.runtime.policy.writableRoots)) {
+    return { ok: false, error: `Path is outside the workspace: ${rawPath}` };
+  }
+  const absolutePath = resolveWorkspacePath(rawPath, context.workspaceRoot);
+  return {
+    ok: true,
+    absolutePath,
+    relativePath: relativeDisplay(context.workspaceRoot, absolutePath),
+  };
+}
+
+async function listFiles(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  const rawPath = stringArg(args, "path") ?? ".";
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "list_files", path: rawPath, error: resolved.error };
+
+  const entries = await readdir(resolved.absolutePath, { withFileTypes: true });
+  const names = entries
+    .filter((entry) => ![".git", "node_modules", "dist", "build", "coverage"].includes(entry.name))
+    .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`)
+    .sort();
+  return {
+    success: true,
+    tool: "list_files",
+    path: resolved.relativePath,
+    output: names.slice(0, 200).join("\n"),
+    summary: `Listed ${names.length} item${names.length === 1 ? "" : "s"}.`,
+  };
+}
+
+async function readFileTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  const rawPath = stringArg(args, "path");
+  if (!rawPath) return { success: false, tool: "read_file", error: "Missing path." };
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "read_file", path: rawPath, error: resolved.error };
+
+  const fileStat = await stat(resolved.absolutePath);
+  if (fileStat.size > MAX_FILE_BYTES) {
+    return { success: false, tool: "read_file", path: resolved.relativePath, error: "File is too large to read through the agent tool." };
+  }
+  const content = await readFile(resolved.absolutePath, "utf8");
+  return {
+    success: true,
+    tool: "read_file",
+    path: resolved.relativePath,
+    output: content,
+    summary: `Read ${resolved.relativePath}.`,
+  };
+}
+
+async function writeFileTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime)) {
+    return { success: false, tool: "write_file", error: "write_file is blocked by read-only runtime policy." };
+  }
+  const rawPath = stringArg(args, "path");
+  const content = stringArg(args, "content");
+  if (!rawPath) return { success: false, tool: "write_file", error: "Missing path." };
+  if (content === null) return { success: false, tool: "write_file", path: rawPath, error: "Missing content." };
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "write_file", path: rawPath, error: resolved.error };
+
+  await mkdir(path.dirname(resolved.absolutePath), { recursive: true });
+  await writeFile(resolved.absolutePath, content, "utf8");
+  return {
+    success: true,
+    tool: "write_file",
+    path: resolved.relativePath,
+    paths: [resolved.relativePath],
+    summary: `Wrote ${resolved.relativePath}.`,
+  };
+}
+
+function parseApplyPatchPaths(patch: string): string[] {
+  const paths: string[] = [];
+  for (const line of patch.split(/\r?\n/)) {
+    const marker = /^(?:\*\*\* (?:Add|Update|Delete) File:|--- a\/|\+\+\+ b\/)\s*(.+)$/.exec(line);
+    if (marker?.[1] && marker[1] !== "/dev/null") {
+      paths.push(marker[1].trim());
+    }
+  }
+  return [...new Set(paths)];
+}
+
+function applyPatchFormatToContent(before: string, patchLines: string[]): string {
+  let contentLines = before.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  if (contentLines.at(-1) === "") contentLines = contentLines.slice(0, -1);
+  let cursor = 0;
+  let index = 0;
+
+  while (index < patchLines.length) {
+    if (!patchLines[index]?.startsWith("@@")) {
+      index += 1;
+      continue;
+    }
+    index += 1;
+    const oldLines: string[] = [];
+    const newLines: string[] = [];
+    while (index < patchLines.length && !patchLines[index]?.startsWith("@@") && !patchLines[index]?.startsWith("*** ")) {
+      const line = patchLines[index] ?? "";
+      if (line.startsWith(" ")) {
+        oldLines.push(line.slice(1));
+        newLines.push(line.slice(1));
+      } else if (line.startsWith("-")) {
+        oldLines.push(line.slice(1));
+      } else if (line.startsWith("+")) {
+        newLines.push(line.slice(1));
+      }
+      index += 1;
+    }
+
+    let matchAt = -1;
+    for (let candidate = cursor; candidate <= contentLines.length - oldLines.length; candidate += 1) {
+      const matches = oldLines.every((line, offset) => contentLines[candidate + offset] === line);
+      if (matches) {
+        matchAt = candidate;
+        break;
+      }
+    }
+    if (matchAt < 0) {
+      throw new Error("Patch context did not match the target file.");
+    }
+    contentLines.splice(matchAt, oldLines.length, ...newLines);
+    cursor = matchAt + newLines.length;
+  }
+
+  return `${contentLines.join("\n")}\n`;
+}
+
+async function applyPatchFormat(patch: string, context: AgentToolContext): Promise<AgentToolResult> {
+  const lines = patch.split(/\r?\n/);
+  const changedPaths: string[] = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const add = /^\*\*\* Add File:\s*(.+)$/.exec(lines[index] ?? "");
+    const update = /^\*\*\* Update File:\s*(.+)$/.exec(lines[index] ?? "");
+    const del = /^\*\*\* Delete File:\s*(.+)$/.exec(lines[index] ?? "");
+
+    if (add) {
+      const resolved = resolveAllowedPath(add[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: add[1], error: resolved.error };
+      index += 1;
+      const content: string[] = [];
+      while (index < lines.length && !lines[index]?.startsWith("*** ")) {
+        const line = lines[index] ?? "";
+        if (line.startsWith("+")) content.push(line.slice(1));
+        index += 1;
+      }
+      await mkdir(path.dirname(resolved.absolutePath), { recursive: true });
+      await writeFile(resolved.absolutePath, `${content.join("\n")}\n`, "utf8");
+      changedPaths.push(resolved.relativePath);
+      continue;
+    }
+
+    if (update) {
+      const resolved = resolveAllowedPath(update[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: update[1], error: resolved.error };
+      index += 1;
+      const patchLines: string[] = [];
+      while (index < lines.length && !/^\*\*\* (?:Add|Update|Delete|End)/.test(lines[index] ?? "")) {
+        patchLines.push(lines[index] ?? "");
+        index += 1;
+      }
+      const before = await readFile(resolved.absolutePath, "utf8");
+      await writeFile(resolved.absolutePath, applyPatchFormatToContent(before, patchLines), "utf8");
+      changedPaths.push(resolved.relativePath);
+      continue;
+    }
+
+    if (del) {
+      const resolved = resolveAllowedPath(del[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: del[1], error: resolved.error };
+      await rm(resolved.absolutePath, { force: true });
+      changedPaths.push(resolved.relativePath);
+      index += 1;
+      continue;
+    }
+
+    index += 1;
+  }
+
+  if (changedPaths.length === 0) {
+    return { success: false, tool: "apply_patch", error: "No supported patch operations were found." };
+  }
+
+  return {
+    success: true,
+    tool: "apply_patch",
+    paths: changedPaths,
+    summary: `Patched ${changedPaths.join(", ")}.`,
+  };
+}
+
+async function applyPatchTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime)) {
+    return { success: false, tool: "apply_patch", error: "apply_patch is blocked by read-only runtime policy." };
+  }
+  const patch = stringArg(args, "patch");
+  if (!patch) return { success: false, tool: "apply_patch", error: "Missing patch." };
+
+  const explicitPath = stringArg(args, "path");
+  const paths = explicitPath ? [explicitPath] : parseApplyPatchPaths(patch);
+  for (const patchPath of paths) {
+    const resolved = resolveAllowedPath(patchPath, context);
+    if (!resolved.ok) return { success: false, tool: "apply_patch", path: patchPath, error: resolved.error };
+  }
+
+  if (!patch.trimStart().startsWith("*** Begin Patch")) {
+    return { success: false, tool: "apply_patch", error: "Only *** Begin Patch format is supported by this agent tool." };
+  }
+
+  return applyPatchFormat(patch, context);
+}
+
+async function runShellTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime) || isReadOnly(context.runtime)) {
+    return { success: false, tool: "run_shell", error: "run_shell is blocked by read-only runtime policy." };
+  }
+  const command = stringArg(args, "command");
+  if (!command) return { success: false, tool: "run_shell", error: "Missing command." };
+
+  if (DANGEROUS_SHELL_PATTERNS.some((pattern) => pattern.test(command))) {
+    return { success: false, tool: "run_shell", command, error: "Shell command blocked as dangerous." };
+  }
+  const rustGuard = rustCommandGuard(command, context);
+  if (rustGuard) {
+    return { success: false, tool: "run_shell", command, exitCode: null, durationMs: 0, stdout: "", stderr: "", error: rustGuard };
+  }
+  const workspaceGuard = getShellWorkspaceGuardMessage(command, context.workspaceRoot, context.runtime.policy.writableRoots);
+  if (workspaceGuard) {
+    return { success: false, tool: "run_shell", command, error: workspaceGuard };
+  }
+
+  const runner = runShellCommand(command, {
+    cwd: context.workspaceRoot,
+    timeoutMs: SHELL_TIMEOUT_MS,
+  });
+  const cancel = () => runner.cancel();
+  context.signal?.addEventListener("abort", cancel, { once: true });
+  try {
+    const result = await runner.result;
+    const success = result.status === "completed" && result.exitCode === 0;
+    const stdout = trimOutputLines(result.stdout, !success);
+    const stderr = trimOutputLines(result.stderr, !success);
+    const output = preview([stdout, stderr].filter(Boolean).join("\n"));
+    return {
+      success,
+      tool: "run_shell",
+      command,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      stdout,
+      stderr,
+      output,
+      summary: summarizeCommandResult(command, result),
+      error: success ? undefined : result.userMessage,
+    };
+  } finally {
+    context.signal?.removeEventListener("abort", cancel);
+  }
+}
+
+async function getWorkspaceInfo(context: AgentToolContext): Promise<AgentToolResult> {
+  return {
+    success: true,
+    tool: "get_workspace_info",
+    path: ".",
+    output: JSON.stringify({
+      workspaceRoot: context.workspaceRoot,
+      sandboxMode: context.runtime.policy.sandboxMode,
+      writableRoots: context.runtime.policy.writableRoots,
+      packageJson: existsSync(path.join(context.workspaceRoot, "package.json")),
+    }),
+    summary: "Returned workspace info.",
+  };
+}
+
+export async function executeAgentTool(
+  name: AgentToolName,
+  args: Record<string, unknown>,
+  context: AgentToolContext,
+): Promise<AgentToolResult> {
+  try {
+    switch (name) {
+      case "list_files":
+        return await listFiles(args, context);
+      case "read_file":
+        return await readFileTool(args, context);
+      case "write_file":
+        return await writeFileTool(args, context);
+      case "apply_patch":
+        return await applyPatchTool(args, context);
+      case "run_shell":
+        return await runShellTool(args, context);
+      case "get_workspace_info":
+        return await getWorkspaceInfo(context);
+    }
+  } catch (error) {
+    return {
+      success: false,
+      tool: name,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/core/{codexExecArgs.ts → codex/codexExecArgs.ts}

@@ -1,5 +1,5 @@
-import type { ResolvedRuntimeConfig } from "../config/runtimeConfig.js";
-import type { CodexCliCapabilities } from "./models/codexCapabilities.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { CodexCliCapabilities } from "../models/codexCapabilities.js";
 
 export interface BuildCodexExecArgsOptions {
   runtime: ResolvedRuntimeConfig;

package/src/core/{codexLaunch.ts → codex/codexLaunch.ts}

@@ -1,8 +1,8 @@
 import { fileURLToPath } from "url";
 import { buildCodexExecArgs, type BuildCodexExecArgsOptions, type BuildCodexExecArgsResult } from "./codexExecArgs.js";
-import { getCodexCliCapabilities, type CodexCliCapabilities } from "./models/codexCapabilities.js";
-import { resolveCodexExecutable } from "./executables/codexExecutable.js";
-import * as perf from "./perf/profiler.js";
+import { getCodexCliCapabilities, type CodexCliCapabilities } from "../models/codexCapabilities.js";
+import { resolveCodexExecutable } from "../executables/codexExecutable.js";
+import * as perf from "../perf/profiler.js";
 
 // Assumed capability set when probeCapabilities is false — avoids a slow help-output probe on every run.
 const MODERN_CODEX_CLI_CAPABILITIES: CodexCliCapabilities = {

package/src/core/{codexPrompt.ts → codex/codexPrompt.ts}

@@ -1,6 +1,6 @@
-import type { AvailableMode } from "../config/settings.js";
-import type { ResolvedRuntimeConfig } from "../config/runtimeConfig.js";
-import type { ProjectInstructions } from "./projectInstructions.js";
+import type { AvailableMode } from "../../config/settings.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { ProjectInstructions } from "../workspace/projectInstructions.js";
 
 // ─── Write-intent detection ───────────────────────────────────────────────────
 

package/src/core/debug/modelStateDebug.ts

@@ -0,0 +1,34 @@
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+
+type ModelStateDebugDetails = Record<string, unknown>;
+
+let sequence = 0;
+
+export function isModelStateDebugEnabled(): boolean {
+  return process.env.CODEXA_RENDER_DEBUG === "1" || process.env.CODEXA_DEBUG_MODEL_STATE === "1";
+}
+
+export function getModelStateDebugLogPath(): string {
+  return process.env.CODEXA_RENDER_DEBUG_FILE?.trim()
+    || process.env.CODEXA_DEBUG_MODEL_STATE_LOG?.trim()
+    || join(process.cwd(), ".codexa", "debug", "render-status.log");
+}
+
+export function traceModelStateDebug(event: string, details: ModelStateDebugDetails = {}): void {
+  if (!isModelStateDebugEnabled()) return;
+
+  try {
+    const entry = {
+      ts: new Date().toISOString(),
+      seq: ++sequence,
+      event,
+      ...details,
+    };
+    const logPath = getModelStateDebugLogPath();
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Debug logging must never affect the TUI.
+  }
+}

package/src/core/executables/antigravityExecutable.ts

@@ -0,0 +1,48 @@
+import { runCommand } from "../process/CommandRunner.js";
+import { resolveExecutable } from "./executableResolver.js";
+
+type CommandRunner = typeof runCommand;
+
+let cachedExecutable: string | null = null;
+
+export function resetAgyExecutableCacheForTests(): void {
+  cachedExecutable = null;
+}
+
+/**
+ * Returns the resolved Antigravity CLI executable (full path or bare name).
+ *
+ * Priority:
+ *   1. Configured path override (antigravityCommandPath)
+ *   2. AGY_EXECUTABLE env var
+ *   3. Windows PATH lookup for real files: agy.exe, agy.cmd, agy.bat, agy
+ *   4. Bare name fallback "agy" (Unix PATH resolution)
+ */
+export async function resolveAgyExecutable(options?: {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+}): Promise<string> {
+  if (!options?.configuredPath && !options?.runCommandImpl && cachedExecutable !== null) {
+    return cachedExecutable;
+  }
+
+  const result = await resolveExecutable({
+    runCommandImpl: options?.runCommandImpl,
+    cwd: options?.cwd,
+    configuredPath: options?.configuredPath,
+    envOverrides: ["AGY_EXECUTABLE"],
+    commandNames: process.platform === "win32"
+      ? ["agy.exe", "agy.cmd", "agy.bat", "agy"]
+      : ["agy"],
+    knownPathDirectories: [],
+    knownFilePaths: [],
+    label: "antigravity",
+    allowBareFallback: true,
+  });
+
+  if (!options?.configuredPath && !options?.runCommandImpl) {
+    cachedExecutable = result;
+  }
+  return result;
+}

package/src/core/executables/executableResolver.ts

@@ -139,13 +139,17 @@ export async function resolveExecutable(options: ExecutableResolverOptions): Pro
 /**
  * Builds the spawn spec for a resolved executable.
  * .cmd and .bat files must be invoked via `cmd.exe /d /s /c` on Windows.
+ *
+ * `platform` defaults to the host platform; it is injectable so the Windows
+ * wrapping branch can be unit-tested from any OS.
  */
 export function buildSpawnSpec(
   executable: string,
   args: string[],
+  platform: NodeJS.Platform = process.platform,
 ): { executable: string; args: string[] } {
   const validatedExecutable = validateResolvedExecutable(executable, "Executable", process.cwd());
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     const lower = validatedExecutable.toLowerCase();
     if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
       validateWindowsBatchExecutableForCmd(validatedExecutable, "Windows batch executable");

package/src/core/models/codexModelCapabilities.ts

@@ -1,6 +1,9 @@
 import { type ChildProcess } from "child_process";
 import { APP_NAME, APP_VERSION, DEFAULT_MODEL, LEGACY_FALLBACK_MODELS, formatReasoningLabel } from "../../config/settings.js";
 import { resolveCodexExecutable, spawnCodexProcess } from "../executables/codexExecutable.js";
+import { loadSeededCodexCapabilities } from "./codexModelsCacheSeed.js";
+import { saveCachedProviderModels } from "./providerModelCache.js";
+import type { ProviderModel } from "../providerRuntime/types.js";
 
 export type ModelCapabilitySource = "runtime" | "fallback";
 export type ModelCapabilityStatus = "ready" | "fallback";
@@ -47,6 +50,8 @@ export interface GetCodexModelCapabilitiesOptions extends DiscoverCodexModelCapa
   ttlMs?: number;
   resolveExecutable?: typeof resolveCodexExecutable;
   discover?: typeof discoverCodexModelCapabilities;
+  seed?: typeof loadSeededCodexCapabilities;
+  persist?: typeof persistCodexModelCapabilities;
 }
 
 interface JsonRpcResponse {
@@ -439,14 +444,36 @@ export async function discoverCodexModelCapabilities(
   });
 }
 
-// Cache chain: TTL-based in-memory cache → live discovery → fallback model list on error.
-// Failed discoveries are evicted from the cache so retries are possible.
+// Persist a successful live discovery so the next launch can seed the model
+// picker without spawning the codex app-server. Best-effort by design.
+export function persistCodexModelCapabilities(capabilities: CodexModelCapabilities): void {
+  const models: ProviderModel[] = capabilities.models
+    .filter((capability) => !capability.hidden)
+    .map((capability) => ({
+      id: capability.id,
+      modelId: capability.model,
+      label: capability.label,
+      description: capability.description,
+      defaultReasoningLevel: capability.defaultReasoningLevel,
+      supportedReasoningLevels: capability.supportedReasoningLevels,
+      source: "discovered",
+    }));
+  saveCachedProviderModels("openai", { discoveredAt: capabilities.discoveredAt, models });
+}
+
+// Cache chain: TTL-based in-memory cache → live discovery → seeded local caches
+// (codex's own models_cache.json / Codexa's last-good discovery) → static
+// fallback model list. Failed discoveries are evicted from the in-memory cache
+// so retries are possible even when a seed satisfied the request.
 export async function getCodexModelCapabilities(
   options: GetCodexModelCapabilitiesOptions = {},
 ): Promise<CodexModelCapabilities> {
   const now = options.now?.() ?? Date.now();
   const ttlMs = options.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  const seed = options.seed ?? loadSeededCodexCapabilities;
+  const persist = options.persist ?? persistCodexModelCapabilities;
   let executable: string | null = null;
+  let liveDiscoverySucceeded = false;
 
   try {
     executable = options.executable ?? await (options.resolveExecutable ?? resolveCodexExecutable)();
@@ -462,7 +489,25 @@ export async function getCodexModelCapabilities(
       includeHidden: options.includeHidden,
       timeoutMs: options.timeoutMs,
       now: () => now,
-    }).catch((error) => createFallbackModelCapabilities(error, { discoveredAt: now, executable }));
+    }).then((discovered) => {
+      liveDiscoverySucceeded = true;
+      try {
+        persist(discovered);
+      } catch {
+        // Persistence must never fail a successful discovery.
+      }
+      return discovered;
+    }).catch((error) => {
+      try {
+        const seeded = seed();
+        if (seeded) {
+          return seeded;
+        }
+      } catch {
+        // Seed read failures fall through to the static list.
+      }
+      return createFallbackModelCapabilities(error, { discoveredAt: now, executable });
+    });
 
     capabilityCache.set(cacheKey, {
       expiresAt: now + ttlMs,
@@ -470,12 +515,20 @@ export async function getCodexModelCapabilities(
     });
 
     const result = await promise;
-    if (result.status === "fallback") {
+    if (!liveDiscoverySucceeded) {
       capabilityCache.delete(cacheKey);
     }
 
     return result;
   } catch (error) {
+    try {
+      const seeded = seed();
+      if (seeded) {
+        return seeded;
+      }
+    } catch {
+      // Seed read failures fall through to the static list.
+    }
     return createFallbackModelCapabilities(error, { discoveredAt: now, executable });
   }
 }