ccx-native 0.1.0 → 0.2.0

package/ccx/codex/daemon/worker.py

@@ -23,6 +23,14 @@ if TYPE_CHECKING:
 _TERMINAL_STATES = {"dead", "idle-killed", "crashed", "budget-stopped"}
 
 
+def _system_error_reason(error) -> str:
+    """The crash reason, with Codex's own error message when there is one."""
+    message = error.get("message") if isinstance(error, dict) else None
+    if isinstance(message, str) and message.strip():
+        return "Codex thread system error: " + message.strip()[:500]
+    return "Codex thread system error"
+
+
 _PARENT_NOTIFY_FENCES = 32
 
 
@@ -1373,8 +1381,21 @@ class Worker:
                                     reason="Codex thread system error",
                                 )
                         self._abandon_active_compact_locked("Codex thread system error")
-                        self.record["lifecycle"]["state"] = "crashed"
-                        self.record["lifecycle"]["lastError"] = "Codex thread system error"
+                        # Best effort: name the native cause when it is
+                        # already known (Codex may also report it later, on
+                        # turn/completed).
+                        lifecycle = self.record["lifecycle"]
+                        native_error = None
+                        active_error = self.record.get("activeTurnError")
+                        last_turn = self.record.get("lastTurn")
+                        if lifecycle.get("activeTurnId"):
+                            if (isinstance(active_error, dict) and active_error.get("turnId")
+                                    == lifecycle.get("activeTurnId")):
+                                native_error = active_error.get("error")
+                        elif isinstance(last_turn, dict) and last_turn.get("status") == "failed":
+                            native_error = last_turn.get("error")
+                        lifecycle["state"] = "crashed"
+                        lifecycle["lastError"] = _system_error_reason(native_error)
             elif method == "turn/completed":
                 changed = True
                 turn = params.get("turn") or {}
@@ -1527,6 +1548,12 @@ class Worker:
                     # demote a worker whose runtime health is already known to
                     # be bad.
                     self.record["lifecycle"]["state"] = "crashed"
+                    # Best effort: name the native cause (a 429, a refused
+                    # compact) instead of only the generic status.
+                    if self.record["lifecycle"].get("lastError") == _system_error_reason(None):
+                        self.record["lifecycle"]["lastError"] = (
+                            _system_error_reason(turn.get("error"))
+                        )
                 elif isinstance(self.record.get("activeCompact"), dict):
                     # A foreign/native turn can settle while compaction still
                     # owns its own operation fence. Do not publish idle until
@@ -2134,31 +2161,32 @@ class Worker:
                 return failure
 
         if op == "interrupt":
+            # The notification reader publishes a successor turn under the
+            # worker lock, so read state, turn and thread together once and
+            # interrupt exactly the turn that was checked.
+            with self.lock:
+                state = self.record["lifecycle"]["state"]
+                turn_id = self.record["lifecycle"].get("activeTurnId")
+                # Full-UUID records keep the original thread under native.threadId.
+                native = self.record.get("native") or {}
+                thread_id = native.get("threadId") or self.record.get("threadId")
             expected_turn_id = message.get("expectedTurnId")
-            current_turn_id = self.record["lifecycle"].get("activeTurnId")
-            if (
-                expected_turn_id is not None
-                and expected_turn_id != current_turn_id
-            ):
+            if expected_turn_id is not None and expected_turn_id != turn_id:
                 return {
                     "ok": False,
                     "error": "active turn changed",
                     "state": state,
-                    "turnId": current_turn_id,
+                    "turnId": turn_id,
                     "definitive": True,
                 }
             if state not in {"busy", "waiting"}:
                 return {"ok": False, "definitive": True,
                         "error": "no active turn", "state": state}
-            turn_id = self.record["lifecycle"].get("activeTurnId")
             if not turn_id:
                 return {"ok": False, "definitive": True,
                         "error": "active turn id is unavailable", "state": state}
-            # Full-UUID records keep the original thread under native.threadId.
-            native = self.record.get("native") or {}
             self.client.request("turn/interrupt", {
-                "threadId": native.get("threadId") or self.record["threadId"],
-                "turnId": turn_id,
+                "threadId": thread_id, "turnId": turn_id,
             })
             return {"ok": True, "state": state, "turnId": turn_id}
         if op in {"approve", "reject"}:

package/ccx/codex/history_store.py

@@ -0,0 +1,131 @@
+"""Read one Codex thread's history from Codex's local history database.
+
+Codex keeps a SQLite projection of every thread's rollout,
+``$CODEX_HOME/thread_history_1.sqlite``. Its ``thread_items.item_json`` holds
+the same ThreadItem JSON app-server returns, so a thread rebuilt from it feeds
+:func:`ccx.ops.conversation.build_codex` unchanged and yields the same turn
+sequence and item ordinals. Reading it takes milliseconds where app-server
+paging can take minutes, and loads nothing into codexd.
+
+It is Codex's private store, so every read is defensive: opened read-only
+(``mode=ro``, never ``immutable=1``, so SQLite still honours the WAL), gated on
+the tables and columns used here, short, and always closed. Any doubt returns
+``None`` and the caller falls back to app-server ``thread/read``.
+
+The thread id must come from the worker's verified original source
+(``codex.telemetry._original_source``), never from a record field read here.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from urllib.parse import quote
+
+HISTORY_DB_NAME = "thread_history_1.sqlite"
+
+# The schema this reader was checked against (2026-11, Codex `_sqlx_migrations`
+# version 8). A newer version is still read when the required columns exist;
+# the document then says so in a warning.
+VERIFIED_SCHEMA_VERSION = 8
+
+_REQUIRED = {
+    "thread_turns": {"thread_id", "turn_id", "rollout_ordinal", "status",
+                     "error_json", "started_at", "completed_at", "duration_ms"},
+    "thread_items": {"thread_id", "turn_id", "item_id", "rollout_ordinal",
+                     "item_json"},
+    "_sqlx_migrations": {"version", "success"},
+}
+_TURN_STATUSES = frozenset({"completed", "failed", "inProgress", "interrupted"})
+_BUSY_TIMEOUT_S = 2.0
+
+
+def history_db_path() -> Path:
+    # Like Codex itself, an empty CODEX_HOME means unset.
+    return Path(os.environ.get("CODEX_HOME") or "~/.codex").expanduser() / HISTORY_DB_NAME
+
+
+def _schema_ok(conn: sqlite3.Connection) -> bool:
+    for table, columns in _REQUIRED.items():
+        found = {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
+        if not columns <= found:
+            return False
+    return True
+
+
+def read_thread_db(thread_id: str, *, path: Path | None = None) -> dict | None:
+    """Return the ``thread/read(includeTurns)`` shape for one thread, or ``None``.
+
+    Turns come in ``rollout_ordinal`` order, including turns with no items;
+    each turn's items come in their own ``rollout_ordinal`` order. The result
+    carries ``historySource: "codex-history-db"`` and ``historyDbVersion``.
+    """
+    if not isinstance(thread_id, str) or not thread_id:
+        return None
+    db = path or history_db_path()
+    if not db.is_file():
+        return None
+    try:
+        conn = sqlite3.connect(f"file:{quote(str(db))}?mode=ro", uri=True,
+                               timeout=_BUSY_TIMEOUT_S)
+    except sqlite3.Error:
+        return None
+    try:
+        if not _schema_ok(conn):
+            return None
+        row = conn.execute(
+            "SELECT max(version) FROM _sqlx_migrations WHERE success").fetchone()
+        version = row[0] if row else None
+        # One read transaction: turns and items come from the same snapshot.
+        conn.execute("BEGIN")
+        turn_rows = conn.execute(
+            "SELECT turn_id, status, error_json, started_at, completed_at, duration_ms"
+            " FROM thread_turns WHERE thread_id = ? ORDER BY rollout_ordinal",
+            (thread_id,)).fetchall()
+        item_rows = conn.execute(
+            "SELECT turn_id, item_json FROM thread_items"
+            " WHERE thread_id = ? ORDER BY rollout_ordinal",
+            (thread_id,)).fetchall()
+        conn.execute("COMMIT")
+    except sqlite3.Error:
+        return None
+    finally:
+        conn.close()
+
+    if not turn_rows:
+        return None
+    items: dict[str, list[dict]] = {}
+    for turn_id, item_json in item_rows:
+        try:
+            item = json.loads(item_json)
+        except (TypeError, ValueError):
+            return None
+        if not isinstance(item, dict):
+            return None
+        items.setdefault(turn_id, []).append(item)
+    known = {r[0] for r in turn_rows}
+    if set(items) - known:
+        return None  # items of a turn the projection doesn't list: not coherent
+
+    turns = []
+    for turn_id, status, error_json, started, completed, duration in turn_rows:
+        if status not in _TURN_STATUSES:
+            return None
+        error = None
+        if error_json:
+            try:
+                error = json.loads(error_json)
+            except ValueError:
+                return None
+        turns.append({
+            "id": turn_id, "status": status, "error": error,
+            "startedAt": started, "completedAt": completed, "durationMs": duration,
+            "items": items.get(turn_id, []), "itemsView": "full",
+        })
+    return {"id": thread_id, "turns": turns, "historySource": "codex-history-db",
+            "historyDbVersion": version}
+
+
+__all__ = ["HISTORY_DB_NAME", "VERIFIED_SCHEMA_VERSION", "history_db_path",
+           "read_thread_db"]

package/ccx/codex/runtime.py

@@ -54,6 +54,8 @@ CODEXD_BOOT_TIMEOUT_S = 60
 # How long a caller without a deadline waits for a stopping codexd to exit. Its
 # shutdown closes the app-server (up to three 3s waits) before it lets go.
 CODEXD_STOP_WAIT_S = 15
+# One presence probe's reply budget; a slower one is retried, not refused.
+PRESENCE_PROBE_S = 5
 
 
 @contextmanager
@@ -104,8 +106,8 @@ def _short_lived_app_server(
             client.close()
 
 
-def list_models(*, cwd: str, timeout: float = 30) -> list[str]:
-    """Return every model ID advertised by Codex's stable ``model/list`` API."""
+def list_model_entries(*, cwd: str, timeout: float = 30) -> list[dict]:
+    """Return model/list's item dictionaries (default visibility, every page)."""
     try:
         with _short_lived_app_server(
             cwd=cwd,
@@ -113,18 +115,15 @@ def list_models(*, cwd: str, timeout: float = 30) -> list[str]:
             timeout=timeout,
             rejection_prefix="unsupported request during model list read",
         ) as client:
-            models: list[str] = []
+            entries: list[dict] = []
             cursor: str | None = None
             seen_cursors: set[str] = set()
             while True:
                 params = {"cursor": cursor} if cursor is not None else {}
                 page = client.request("model/list", params, timeout=timeout)
                 for item in page.get("data") or []:
-                    if not isinstance(item, dict):
-                        continue
-                    model_id = item.get("model") or item.get("id")
-                    if isinstance(model_id, str) and model_id and model_id not in models:
-                        models.append(model_id)
+                    if isinstance(item, dict):
+                        entries.append(item)
                 next_cursor = page.get("nextCursor")
                 if not isinstance(next_cursor, str) or not next_cursor:
                     break
@@ -132,15 +131,27 @@ def list_models(*, cwd: str, timeout: float = 30) -> list[str]:
                     raise RuntimeError("model/list returned a repeated cursor")
                 seen_cursors.add(next_cursor)
                 cursor = next_cursor
-            if not models:
-                raise RuntimeError("model/list returned no model IDs")
-            return models
+            if not entries:
+                raise RuntimeError("model/list returned no model entries")
+            return entries
     except (OSError, RuntimeError) as error:
         raise SessionUnavailable(
             f"Codex model list unavailable: {error}"
         ) from error
 
 
+def list_models(*, cwd: str, timeout: float = 30) -> list[str]:
+    """Return every model ID advertised by Codex's stable model/list API."""
+    models: list[str] = []
+    for item in list_model_entries(cwd=cwd, timeout=timeout):
+        model_id = item.get("model") or item.get("id")
+        if isinstance(model_id, str) and model_id and model_id not in models:
+            models.append(model_id)
+    if not models:
+        raise SessionUnavailable("Codex model list unavailable: model/list returned no model IDs")
+    return models
+
+
 def validate_model(model: str, *, cwd: str, timeout: float = 30) -> list[str]:
     """Validate one explicit model and return the complete advertised ID list."""
     if not isinstance(model, str) or not model:
@@ -233,7 +244,7 @@ def observation_daemon(
             return False
         if transport != RUNTIME_SERVED:
             raise SessionUnavailable(
-                "codexd presence is inconclusive; no second app-server was started",
+                inconclusive_presence(probe, "no second app-server was started"),
                 short=short or "codexd",
             )
         require_compatible_daemon(probe, short=short)
@@ -292,8 +303,15 @@ def _lifetime_lock_held() -> bool | None:
 
 def _transport_failure(error: BaseException) -> dict[str, Any]:
     """Classify a failed socket observation without confusing timeout with absence."""
-    if isinstance(error, (TimeoutError, socket.timeout)):
-        presence = RUNTIME_INCONCLUSIVE
+    if isinstance(error, (TimeoutError, socket.timeout, EOFError)):
+        # A busy machine or a daemon mid-exit: unknown, but worth asking again
+        # inside the caller's budget. Never evidence of absence.
+        return {
+            "ok": False,
+            "error": f"codexd unavailable: {error.__class__.__name__}",
+            "transport": RUNTIME_INCONCLUSIVE,
+            "retry": True,
+        }
     elif isinstance(error, OSError) and getattr(error, "errno", None) in {
         2,  # ENOENT: no socket file
         32,  # EPIPE: the listener closed under the request
@@ -536,7 +554,8 @@ def preflight_daemon(
         return probe
     if probe.get("transport") != RUNTIME_SERVED:
         raise SessionUnavailable(
-            "codexd presence is inconclusive", short=short or "codexd"
+            inconclusive_presence(probe, "nothing was sent"),
+            short=short or "codexd",
         )
     require_compatible_daemon(probe, short=short)
     return None
@@ -569,9 +588,16 @@ def rpc(
     )
 
 
-def daemon_status(timeout: float = 2) -> dict[str, Any]:
-    """Probe the daemon. Deliberately unchecked: status is a recovery tool."""
-    return daemon_rpc({"op": "daemon-status"}, timeout=timeout)
+def daemon_status(timeout: float = 2, *, presence_only: bool = False) -> dict[str, Any]:
+    """Probe the daemon. Deliberately unchecked: status is a recovery tool.
+
+    ``presence_only`` skips the per-worker states, which take every worker's
+    lock; a daemon that predates the flag ignores it and lists them anyway.
+    """
+    message: dict[str, Any] = {"op": "daemon-status"}
+    if presence_only:
+        message["workers"] = False
+    return daemon_rpc(message, timeout=timeout)
 
 
 def _stopping(probe: dict[str, Any]) -> bool:
@@ -584,22 +610,37 @@ def _stopping(probe: dict[str, Any]) -> bool:
 
 
 def settled_daemon_status(deadline: float | None) -> dict[str, Any]:
-    """Probe the daemon, waiting out one that is binding or shutting down.
+    """Probe the daemon, waiting out one that is slow, binding or shutting down.
 
     A stopping codexd refuses new loads and is about to release the runtime,
-    so neither "use it" nor "start another" is right yet. Waiting is bounded by
-    the caller's deadline (or ``CODEXD_STOP_WAIT_S``); what is still
-    transitional then is returned as the inconclusive probe it is.
+    so neither "use it" nor "start another" is right yet; a probe that timed
+    out says nothing either way. Both are asked again until the caller's
+    deadline (or ``CODEXD_STOP_WAIT_S``); what is still unknown then is
+    returned as the inconclusive probe it is, with how long it was waited for.
     """
-    limit = (
-        deadline if deadline is not None
-        else time.monotonic() + CODEXD_STOP_WAIT_S
-    )
+    started = time.monotonic()
+    limit = deadline if deadline is not None else started + CODEXD_STOP_WAIT_S
+    attempts = 0
     while True:
-        probe = daemon_status(timeout=max(0.25, remaining(deadline, 1)))
-        if not _stopping(probe) or time.monotonic() >= limit:
+        attempts += 1
+        probe = daemon_status(timeout=remaining(limit, PRESENCE_PROBE_S),
+                              presence_only=True)
+        now = time.monotonic()
+        if not (_stopping(probe) or probe.get("retry")) or now >= limit:
+            if probe.get("transport") == RUNTIME_INCONCLUSIVE:
+                probe = {**probe, "attempts": attempts,
+                         "waitedSeconds": round(now - started, 1)}
             return probe
-        time.sleep(min(0.05, max(0.0, limit - time.monotonic())))
+        time.sleep(min(0.1, max(0.0, limit - now)))
+
+
+def inconclusive_presence(probe: dict[str, Any], outcome: str) -> str:
+    """The refusal for a presence probe that never settled, with its evidence."""
+    error = str(probe.get("error") or "no reply").removeprefix("codexd unavailable: ")
+    attempts = probe.get("attempts") or 1
+    tried = (f" after {attempts} probes over {probe.get('waitedSeconds')}s"
+             if attempts > 1 else "")
+    return f"codexd presence is inconclusive ({error}{tried}); {outcome}"
 
 
 def observe_worker(
@@ -1198,7 +1239,7 @@ def ensure_daemon(deadline: float | None = None) -> dict[str, Any]:
         probe.get("transport") == RUNTIME_INCONCLUSIVE and probe.get("transitional")
     ):
         raise SessionUnavailable(
-            "codexd presence is inconclusive; refusing to start a second daemon",
+            inconclusive_presence(probe, "refusing to start a second daemon"),
             short="codexd",
         )
     with daemon_spawn_lock(deadline):
@@ -1211,7 +1252,7 @@ def ensure_daemon(deadline: float | None = None) -> dict[str, Any]:
             "transitional"
         ):
             raise SessionUnavailable(
-                "codexd presence is inconclusive; refusing to start a second daemon",
+                inconclusive_presence(probe, "refusing to start a second daemon"),
                 short="codexd",
             )
         process = None
@@ -1389,6 +1430,7 @@ __all__ = [
     "daemon_stop",
     "ensure_daemon",
     "identity",
+    "list_model_entries",
     "list_models",
     "daemon_generation",
     "daemon_spawn_lock",

package/ccx/models.py

@@ -0,0 +1,225 @@
+"""Read-only, engine-neutral model catalogs with private per-engine caching."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime, timezone
+import hashlib
+from pathlib import Path
+import time
+
+from ccx import constants
+from ccx.claude.oauth import oauth_organization_uuid
+from ccx.claude.usage_control import request_models
+from ccx.codex.runtime import list_model_entries
+from ccx.errors import InvalidRequest
+from ccx.system.private_json import _atomic_private_json, _read_private_json
+from ccx.types import ModelCatalog, ModelInfo
+
+_CACHE_TTL_S = 24 * 60 * 60
+_CACHE_VERSION = 1
+_ENGINES = ("claude", "codex")
+
+
+def _text(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _efforts(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return list(dict.fromkeys(entry for entry in value
+                              if isinstance(entry, str) and entry))
+
+
+def normalize_claude_models(entries: object) -> list[ModelInfo]:
+    """Project Claude initialize's models only, with per-model capabilities."""
+    if not isinstance(entries, list):
+        return []
+    models = []
+    for item in entries:
+        if not isinstance(item, dict):
+            continue
+        ident = _text(item.get("value"))
+        resolved = _text(item.get("resolvedModel"))
+        name = _text(item.get("displayName"))
+        if not (ident and resolved and name):
+            continue
+        models.append(ModelInfo(
+            id=ident,
+            resolved=resolved,
+            display_name=name,
+            description=(item.get("description")
+                         if isinstance(item.get("description"), str) else None),
+            alias=ident != resolved,
+            default=ident == "default",
+            efforts=(_efforts(item.get("supportedEffortLevels"))
+                     if item.get("supportsEffort") is True else []),
+            default_effort=None,
+            features={
+                "fast": item.get("supportsFastMode") is True,
+                "auto": item.get("supportsAutoMode") is True,
+                "thinkingOff": item.get("supportsThinkingOff") is True,
+            },
+        ))
+    return models
+
+
+def normalize_codex_models(entries: object) -> list[ModelInfo]:
+    """Project model/list items; Codex's model ID is the --model spelling."""
+    if not isinstance(entries, list):
+        return []
+    models = []
+    seen = set()
+    for item in entries:
+        if not isinstance(item, dict) or item.get("hidden") is True:
+            continue
+        ident = _text(item.get("model")) or _text(item.get("id"))
+        if not ident or ident in seen:
+            continue
+        seen.add(ident)
+        efforts = item.get("supportedReasoningEfforts")
+        levels = (_efforts([entry.get("reasoningEffort") for entry in efforts
+                            if isinstance(entry, dict)])
+                  if isinstance(efforts, list) else [])
+        models.append(ModelInfo(
+            id=ident,
+            resolved=ident,
+            display_name=_text(item.get("displayName")) or ident,
+            description=(item.get("description")
+                         if isinstance(item.get("description"), str) else None),
+            alias=False,
+            default=item.get("isDefault") is True,
+            efforts=levels,
+            default_effort=_text(item.get("defaultReasoningEffort")),
+            features={},
+        ))
+    return models
+
+
+def _cache_path(engine: str) -> Path:
+    return constants.CCX_ROOT / f"models-{engine}.json"
+
+
+def _local_claude_version() -> str | None:
+    # Bypass oauth.py's process-wide lru_cache: a live CcxClient must notice
+    # when the installed Claude Code binary changes beneath it.
+    from ccx.claude.oauth import claude_code_version
+    return claude_code_version.__wrapped__()
+
+
+def _cache_key(engine: str) -> dict:
+    if engine == "codex":
+        # No cheap native Codex version helper; this engine uses the TTL only.
+        return {}
+    org = oauth_organization_uuid()
+    return {
+        "version": _local_claude_version(),
+        "orgDigest": hashlib.sha256(org.encode()).hexdigest() if org else None,
+    }
+
+
+def _read_cache(engine: str) -> tuple[ModelCatalog | None, dict]:
+    try:
+        data = _read_private_json(_cache_path(engine))
+        if not isinstance(data, dict) or data.get("version") != _CACHE_VERSION:
+            return None, {}
+        catalog = ModelCatalog.from_dict(data["catalog"])
+        if catalog.engine != engine:
+            return None, {}
+        key = data.get("key")
+        return catalog, key if isinstance(key, dict) else {}
+    except (OSError, ValueError, KeyError, TypeError, UnicodeError):
+        return None, {}
+
+
+def _fresh(catalog: ModelCatalog, saved_key: dict, current_key: dict) -> bool:
+    if catalog.engine == "claude":
+        if saved_key.get("orgDigest") != current_key.get("orgDigest"):
+            return False
+        # If the installed version cannot be read, only TTL/org can be checked.
+        local_version = current_key.get("version")
+        if local_version is not None and catalog.engine_version != local_version:
+            return False
+    try:
+        stamped = datetime.fromisoformat(catalog.fetched_at.replace("Z", "+00:00"))
+        if stamped.tzinfo is None:
+            return False
+        age = time.time() - stamped.timestamp()
+    except (ValueError, OverflowError):
+        return False
+    return 0 <= age < _CACHE_TTL_S
+
+
+def _probe(engine: str) -> tuple[str | None, list[ModelInfo]]:
+    if engine == "claude":
+        reply = request_models()
+        if reply.get("kind") != "success":
+            raise RuntimeError(reply.get("error") or "initialize unavailable")
+        body = reply["body"]
+        return _text(body.get("claude_code_version")), normalize_claude_models(body.get("models"))
+    # Account-level catalog, independent of the calling project's cwd.
+    return None, normalize_codex_models(list_model_entries(cwd=str(Path.home())))
+
+
+def _builtin(engine: str, note: str) -> ModelCatalog:
+    # Only Claude has known aliases; inventing Codex model names would be wrong.
+    models = ([ModelInfo(
+        id=alias, resolved=None, display_name=alias.title(),
+        description=None, alias=True, default=False, efforts=[],
+        default_effort=None, features={},
+    ) for alias in constants.MODEL_ALIASES] if engine == "claude" else [])
+    return ModelCatalog(
+        engine=engine, engine_version=None, source="builtin",
+        fetched_at=_now(), note=note, models=models,
+    )
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _catalog(engine: str, *, refresh: bool) -> ModelCatalog:
+    cached, saved_key = _read_cache(engine)
+    try:
+        current_key = _cache_key(engine)
+    except Exception:
+        # Broken or unavailable local identity metadata cannot block the other
+        # engine's catalog (or the provider read for this engine).
+        current_key = {}
+    if not refresh and cached is not None and _fresh(cached, saved_key, current_key):
+        return replace(cached, source="cache")
+
+    try:
+        version, models = _probe(engine)
+        if not models:
+            raise RuntimeError("no valid model entries")
+    except Exception as error:
+        note = f"{engine.capitalize()} model list unavailable: {error}"
+        if cached is not None:
+            return replace(cached, source="stale", note=note)
+        return _builtin(engine, note)
+
+    result = ModelCatalog(
+        engine=engine, engine_version=version, source="live",
+        fetched_at=_now(), note=None, models=models,
+    )
+    try:
+        _atomic_private_json(_cache_path(engine), {
+            "version": _CACHE_VERSION,
+            "key": ({"version": version, "orgDigest": current_key.get("orgDigest")}
+                    if engine == "claude" else {}),
+            "catalog": result.as_dict(),
+        })
+    except OSError:
+        # A live listing remains useful if the private cache cannot be saved.
+        pass
+    return result
+
+
+def read_models(*, engine: str | None = None, refresh: bool = False) -> list[ModelCatalog]:
+    """Return one or both model catalogs; probe failures degrade per engine."""
+    if engine is not None and engine not in _ENGINES:
+        raise InvalidRequest("engine must be claude or codex")
+    return [_catalog(name, refresh=refresh)
+            for name in ((engine,) if engine else _ENGINES)]