@legioncodeinc/rflectr 0.1.1 → 0.1.2

package/library/requirements/completed/prd-008-preferences-tiers-favorites/prd-008-preferences-tiers-favorites-index.md

@@ -1,249 +0,0 @@
-# PRD-008: Preferences, Subscription Tiers & Favorites *(Retroactive)*
-
-> **Status:** Shipped
-> **Priority:** —
-> **Effort:** —
-> **Written:** June 2026
-> **Retroactive:** Yes — written after implementation (rflectr v0.2.7).
-> **Source:** `src/config.ts`, `src/favorites.ts`, `src/favorites-resolver.ts`, `src/prompts.ts`
-
----
-
-## Overview
-
-`rflectr` keeps a small, durable layer of user state so the CLI feels personal across sessions: the last backend/model/provider you launched, recently used models per provider, a curated list of favorite models for the mid-session `/model` switch menu, and per-command `server` settings. All of it lives in a single JSON file under a per-user app-home directory, resolved with an override hook and migrated transparently from two earlier locations.
-
-On top of that state sit three interaction systems:
-
-1. **Preferences store** — read/write helpers around `~/.rflectr/config.json`, with legacy-path migration and a `--dry-run` write-skip contract.
-2. **Subscription / Zen tier filtering** — a `RegistrySubscriptionFilter` (`free` / `zen` / `go`) carried on the OpenCode Zen registry stub that scopes which cloud models surface; seeded as `free` during first-run.
-3. **Favorites** — a manager command (`rflectr models`) plus a resolver shared with the Codex catalog, capped at `MAX_MODEL_CATALOG` (20), and a large-catalog UX (search + pagination) that keeps long model lists navigable.
-
-This PRD documents what was built, grounded in the shipped code.
-
----
-
-## What Was Built
-
-- A single app-home directory (`~/.rflectr`, override via `RFLECTR_HOME`) holding `config.json` and sibling files, created `0o700` / files `0o600` (`src/paths.ts:28`, `src/config.ts:63`).
-- `loadPreferences()` / `savePreferences()` with a shallow per-key merge so callers pass only what changed (`src/config.ts:67`, `src/config.ts:85`).
-- `recordLaunchSelection(agent, providerId, modelId, prefs)` — updates the per-agent `last*` fields and prepends to `recentModelsByProvider` (deduped, capped at 3) (`src/config.ts:101`).
-- Two-stage legacy migration: dotfile dir (`~/.opencode-starter`) then OS `conf` store, both one-directional and idempotent (`src/config.ts:17`, `src/config.ts:34`).
-- `lastProvider === 'opencode'` normalized to `'zen'` on read (`src/config.ts:70`).
-- Pure favorites algebra: `isFavorite`, `addFavorite` (duplicate / cap results), `removeFavorite` (`src/favorites.ts`).
-- The `rflectr models` favorites manager: list / add (global search or browse-by-provider, multi-select) / remove, single save on Done (`src/cli.ts:534`).
-- A surface-agnostic favorites resolver shared by Claude and Codex (`src/favorites-resolver.ts`).
-- Recent-models hint at the top of the local-model picker, with a "Browse all models →" escape hatch (`src/prompts.ts:305`).
-- Large-catalog UX: search at `MODEL_SEARCH_THRESHOLD = 25`, pagination at `MODEL_PAGE_SIZE = 15` (`src/prompts.ts:22`).
-- Inline, never-dead-end first-run wizard that ends in launch or explicit cancel (`src/first-run.ts:36`).
-
----
-
-## Goals
-
-- Persist enough state that repeat launches pre-select the user's prior choice rather than starting cold.
-- Make a curated multi-model `/model` switch menu possible without re-picking every session.
-- Keep one canonical config location, surviving the project's two historical renames without user action.
-- Honor `--dry-run` as a true no-write simulation of a fresh first run.
-- Keep long provider model lists usable (search / paginate) instead of dumping 100+ entries into one prompt.
-
-## Non-Goals
-
-- Touching `~/.claude/settings.json` — launch config is env-var-only (see [PRD-001](../prd-001-cli-core-launch-orchestration/prd-001-cli-core-launch-orchestration-index.md)).
-- Storing secrets in `config.json` — API keys live in the OS credential store ([PRD-006](../prd-006-credential-storage/) — folder pending). The server password is migrated *out* of `config.json` into the keyring on first read (`src/config.ts:131`).
-- Cloud-syncing preferences across machines (the file is per-user, per-host).
-
----
-
-## Features
-
-| # | Feature | Entry point | Notes |
-|---|---------|-------------|-------|
-| F1 | App-home resolution + override | `getAppHome()` (`src/paths.ts:28`) | `RFLECTR_HOME` (or deprecated `OPENCODE_STARTER_HOME`) wins, else `~/.rflectr` |
-| F2 | Preferences load/save (shallow merge) | `loadPreferences` / `savePreferences` (`src/config.ts:67`) | Pass only changed keys |
-| F3 | Record launch selection | `recordLaunchSelection` (`src/config.ts:101`) | Per-agent `last*` + recent list (max 3, dedup) |
-| F4 | Legacy migration (2 stages) | `ensureConfigMigrated` (`src/config.ts:34`) | Dotfile dir → OS conf store; idempotent |
-| F5 | Subscription/Zen tier filter | `RegistrySubscriptionFilter` (`src/registry/types.ts:7`) | `free` / `zen` / `go` on the Zen stub |
-| F6 | Favorites algebra | `addFavorite` / `removeFavorite` (`src/favorites.ts`) | Cap at `MAX_MODEL_CATALOG` (20) |
-| F7 | Favorites manager command | `runModelsCommand` (`src/cli.ts:534`) | `rflectr models`; saves once on Done |
-| F8 | Favorites resolver (shared) | `resolveFavorite` / `buildFavoritesList` (`src/favorites-resolver.ts:52`) | Stale favorites dropped silently |
-| F9 | Recent-models picker | `pickLocalModel` (`src/prompts.ts:305`) | Recent shown first + "Browse all" |
-| F10 | Large-catalog search/pagination | `selectModelWithSearch` / `selectLargeCatalog` (`src/prompts.ts:246`) | Thresholds 25 / 15 |
-| F11 | First-run wizard | `runFirstRunWizard` (`src/first-run.ts:36`) | Zen quick-start / import / providers |
-
----
-
-## Architecture & Implementation
-
-### Config store schema
-
-`config.json` is parsed into `UserPreferences` (`src/types.ts:72`). Unknown keys are tolerated; everything is optional.
-
-| Field | Type | Purpose | Cite |
-|-------|------|---------|------|
-| `lastBackend` | `'zen' \| 'go'` | Last cloud backend launched | `src/types.ts:73` |
-| `lastModel` | `string` | Last Claude Code model (pre-selects wizard) | `src/types.ts:74` |
-| `lastProvider` | `string` | Last Claude Code provider (`'opencode'`→`'zen'` on read) | `src/config.ts:70` |
-| `lastCodexProvider` / `lastCodexModel` | `string` | Last Codex selection | `src/types.ts:76` |
-| `lastGeminiProvider` / `lastGeminiModel` | `string` | Last Gemini selection | `src/types.ts:78` |
-| `recentModelsByProvider` | `Record<string,string[]>` | Up to 3 recent model ids per provider | `src/types.ts:80` |
-| `favoriteModels` | `FavoriteModel[]` | `{ providerId, modelId }`, max 20 | `src/types.ts:81` |
-| `server` | object | `savedPassword`, `exposedProviders`, `maskGatewayIds`, `favoritesOnly` | `src/types.ts:82` |
-
-**Write path.** `writeConfig()` creates the parent dir `0o700` and writes the file `0o600` with a trailing newline (`src/config.ts:61`). `savePreferences()` is a key-by-key conditional merge — every field is copied through only when `!== undefined`, so partial updates never clobber siblings (`src/config.ts:85`).
-
-> **Note on `subscriptionTier`.** Earlier drafts of the design (and `CLAUDE.md`) describe a `subscriptionTier` (`free`/`zen`/`go`/`both`) preference field. In the shipped v0.2.7 code that field is **not** part of `UserPreferences`, `loadPreferences()`, or `savePreferences()`. The tier concept survives instead as `RegistrySubscriptionFilter` on the registry's Zen provider stub (see *Tier behavior* below). This PRD documents the code as shipped.
-
-### App home & override
-
-`getAppHome(env)` returns `resolveAppHomeOverride(env)` when `RFLECTR_HOME`/`OPENCODE_STARTER_HOME` is set (trimmed, non-empty), else `~/.rflectr` (`src/paths.ts:23`, `src/paths.ts:28`). Sibling path helpers (`getConfigPath`, `getProvidersPath`, `getLogsPath`, `getVertexModelsPath`) all derive from it (`src/paths.ts:38`).
-
-### Legacy migration
-
-`readConfig()` runs `ensureConfigMigrated()` before every read (`src/config.ts:56`). Both stages bail the instant `~/.rflectr/config.json` already exists, making migration idempotent:
-
-1. `ensureAppHomeMigrated()` copies `~/.opencode-starter/config.json` (and `vertex-models.json` alongside) into the new home (`src/config.ts:17`).
-2. `ensureConfigMigrated()` then copies the even-older OS `conf` file (`getLegacyConfPath`, platform-specific — `src/paths.ts:54`) and best-effort renames the source to `…​.migrated` (`src/config.ts:49`).
-
-### Tier behavior
-
-The Zen registry stub carries an optional `subscriptionFilter: RegistrySubscriptionFilter` (`src/registry/types.ts:7`, `src/registry/builtins.ts:7`). First-run seeds it as `'free'` via `zenRegistryStub('free')` (`src/first-run.ts:31`). The filter scopes which OpenCode cloud models surface; combined Zen+Go lists track the originating backend per model so the correct base URL is set per selection (see [PRD-003](../prd-003-model-discovery-classification/) for model-discovery merge and `sourceBackend`).
-
-| Filter | Behavior |
-|--------|----------|
-| `free` | Zen free models only — seeded default on first-run (`src/first-run.ts:31`) |
-| `zen` | Zen backend models |
-| `go` | OpenCode Go (paid) backend models |
-
-`lastBackend` (`'zen' \| 'go'`) records the most recently launched cloud backend independently of the filter (`src/types.ts:73`). The two cloud backends are defined in `BACKENDS` (`src/constants.ts:9`); their `baseUrl` must **not** include `/v1` (the Anthropic SDK appends `/v1/messages`).
-
-### Favorites flow
-
-Pure algebra (`src/favorites.ts`):
-
-- `isFavorite(list, fav)` — `providerId` + `modelId` equality.
-- `addFavorite(list, fav, max=MAX_MODEL_CATALOG)` returns `{ ok:false, reason:'duplicate' }`, `{ ok:false, reason:'cap' }`, or `{ ok:true, list }` (`src/favorites.ts:14`).
-- `removeFavorite(list, fav)` — filtered copy (`src/favorites.ts:24`).
-
-Manager (`runModelsCommand`, `src/cli.ts:534`): fetches the provider catalog, builds a `providerId:modelId → label` lookup, then loops a menu where each favorite row removes-on-select, `+ Add a model →` offers global cross-provider search (`pickGlobalFavoriteModel`, `src/favorites-picker.ts:85`) or browse-by-provider multi-select, and `Done` exits. State is held in memory and written **once** on exit via `savePreferences({ favoriteModels })` only when `favoritesDirty` (`src/cli.ts:728`). The cap is enforced both in the UI (`atCap` disables Add, `src/cli.ts:579`) and in `addFavorite`.
-
-**Resolution shared with Codex.** `resolveFavorite(fav, ctx)` (`src/favorites-resolver.ts:52`) is route-shape-agnostic — each surface (Claude / Codex / Server) builds its own `ResolveContext`. Zen/Go favorites resolve against `zenModels`/`goModels` + `zenGoApiKey` and carry `sourceBackend`; registry favorites resolve via `ctx.findLocalModel` and are dropped when `ctx.agent` blacklists them via `shouldHideModel` (`src/favorites-resolver.ts:73`). `buildFavoritesList(starting, favorites, ctx, max=20)` dedups (starting model + favorites), caps at `max`, and returns `{ resolved, droppedFavorites }` — **stale / unavailable favorites are silently skipped** (`src/favorites-resolver.ts:87`). Resolved favorites become catalog routes (see [PRD-005](../prd-005-local-proxy-catalog-routing/)); the Codex catalog consumes the same resolver (see [PRD-009](../prd-009-codex-integration/prd-009-codex-integration-index.md)).
-
-### Recent models per provider
-
-On launch, `recordLaunchSelection()` prepends the chosen model id to `recentModelsByProvider[providerId]`, dedupes, and slices to `MAX_RECENT_MODELS = 3` (`src/config.ts:99`, `src/config.ts:107`). `pickLocalModel()` reads them back, showing up to 3 with a `'recent'` hint plus a "Browse all models →" option; when there are none it goes straight to the full browse (`src/prompts.ts:311`).
-
-### Large-catalog UX
-
-`selectModelWithSearch()` shows a flat list when `models.length <= MODEL_SEARCH_THRESHOLD` (25), otherwise delegates to `selectLargeCatalog()` which offers search vs paginated browse at `MODEL_PAGE_SIZE` (15) per page (`src/prompts.ts:246`, `src/prompts.ts:155`). `pickModelFromPagedList()` provides prev/next paging and computes the initial page from a target model id (`src/prompts.ts:87`). Search tokenizes the query on whitespace + punctuation with AND logic across id/name/brand (`src/prompts.ts:52`).
-
-### First-run
-
-`needsFirstRunSetup()` returns true only when the registry is empty **and** no Zen/Go key is stored (`src/first-run.ts:21`). `runFirstRunWizard()` offers Zen quick-start (collect key → seed `zenRegistryStub('free')`), import-from-OpenCode, or set-up-your-own-provider — and every branch terminates in `continue` (launch) or explicit `cancel`, never a dead end (`src/first-run.ts:36`).
-
-### `--dry-run`
-
-All preference writes are gated on the caller passing `dryRun`. In dry-run, favorites load as `[]` (`src/cli.ts:761`) and the launch path skips `recordLaunchSelection`, so a fresh first-run is fully simulated without mutating `config.json`.
-
----
-
-## Data Shapes
-
-```ts
-// src/types.ts:67
-export interface FavoriteModel {
-  providerId: string;
-  modelId: string;
-}
-
-// src/types.ts:72
-export interface UserPreferences {
-  lastBackend?: 'zen' | 'go';
-  lastModel?: string;
-  lastProvider?: string;
-  lastCodexProvider?: string;
-  lastCodexModel?: string;
-  lastGeminiProvider?: string;
-  lastGeminiModel?: string;
-  recentModelsByProvider?: Record<string, string[]>;
-  favoriteModels?: FavoriteModel[];
-  server?: {
-    savedPassword?: string;
-    exposedProviders?: string[];
-    maskGatewayIds?: boolean;
-    favoritesOnly?: boolean;
-  };
-}
-
-// src/registry/types.ts:7
-export type RegistrySubscriptionFilter = 'free' | 'zen' | 'go';
-
-// src/favorites-resolver.ts:8
-export interface ResolvedFavorite {
-  providerId: string;
-  providerName: string;
-  model: LocalProviderModel | ServerModelInfo;
-  apiKey: string;
-  sourceBackend?: 'zen' | 'go';
-}
-```
-
----
-
-## Acceptance Criteria
-
-- [x] App home resolves from `RFLECTR_HOME` (or deprecated `OPENCODE_STARTER_HOME`), else `~/.rflectr` (`src/paths.ts:23`).
-- [x] Config dir created `0o700`, file written `0o600` with trailing newline (`src/config.ts:61`).
-- [x] `savePreferences()` shallow-merges, copying only defined keys (`src/config.ts:85`).
-- [x] `recordLaunchSelection()` sets per-agent `last*` and prepends to `recentModelsByProvider`, deduped and capped at 3 (`src/config.ts:101`).
-- [x] Legacy migration runs both stages, is idempotent, and renames the old conf file best-effort (`src/config.ts:34`).
-- [x] `lastProvider === 'opencode'` is normalized to `'zen'` on read (`src/config.ts:70`).
-- [x] Zen registry stub carries a `subscriptionFilter`, seeded `'free'` at first-run (`src/first-run.ts:31`, `src/registry/builtins.ts:7`).
-- [x] `addFavorite` rejects duplicates and enforces the `MAX_MODEL_CATALOG` (20) cap (`src/favorites.ts:14`).
-- [x] `rflectr models` saves favorites once on Done, only when dirty (`src/cli.ts:728`).
-- [x] Favorites resolver drops stale/unavailable favorites silently and is shared across Claude/Codex/Server (`src/favorites-resolver.ts:87`).
-- [x] `buildFavoritesList` dedups starting model + favorites and caps at `max` (`src/favorites-resolver.ts:103`).
-- [x] `pickLocalModel` surfaces up to 3 recent models with a "Browse all" escape hatch (`src/prompts.ts:311`).
-- [x] Lists above `MODEL_SEARCH_THRESHOLD` (25) switch to search/paginated browse at `MODEL_PAGE_SIZE` (15) (`src/prompts.ts:257`).
-- [x] First-run wizard never dead-ends; every path returns `continue` or `cancel` (`src/first-run.ts:36`).
-- [x] `--dry-run` loads favorites as `[]` and skips all preference writes (`src/cli.ts:761`).
-
----
-
-## Files
-
-| File | Role |
-|------|------|
-| `src/config.ts` | Read/write preferences, legacy migration, server-password keyring move, recent-models recording |
-| `src/paths.ts` | App-home resolution, override hook, sibling path helpers, legacy conf path |
-| `src/types.ts` | `UserPreferences`, `FavoriteModel` shapes |
-| `src/favorites.ts` | Pure favorites algebra (`isFavorite`/`addFavorite`/`removeFavorite`) |
-| `src/favorites-picker.ts` | Global cross-provider favorite search (`pickGlobalFavoriteModel`) |
-| `src/favorites-resolver.ts` | Surface-agnostic favorite → route resolution, shared with Codex |
-| `src/prompts.ts` | `pickLocalModel`, recent-models, large-catalog search/pagination |
-| `src/first-run.ts` | Inline never-dead-end first-run wizard |
-| `src/cli.ts` | `runModelsCommand` favorites manager; launch-time recent/favorite wiring |
-| `src/constants.ts` | `BACKENDS`, `MAX_MODEL_CATALOG` |
-| `src/registry/builtins.ts` | Zen/Go registry stubs carrying `subscriptionFilter` |
-| `src/registry/types.ts` | `RegistrySubscriptionFilter` type |
-
----
-
-## Risks & Known Limitations
-
-- **`subscriptionTier` drift:** the field named in `CLAUDE.md` is not present in shipped code; tier filtering is registry-stub-based (`subscriptionFilter`). Documentation that references a `subscriptionTier` preference key is stale.
-- **Stale favorites are invisible:** unavailable favorites (provider removed, model retired) are silently dropped at resolution time; in the `rflectr models` list they render as `★ <id> — provider gone` (`src/cli.ts:575`) but are not auto-pruned from `config.json`.
-- **No schema versioning:** `config.json` has no version field; forward/backward compat relies on all keys being optional and unknown keys being tolerated.
-- **Per-host only:** preferences are not synced across machines.
-- **Best-effort legacy rename:** if renaming the old conf file to `…​.migrated` fails (permissions), the copy still succeeds but the stale source remains (`src/config.ts:51`).
-- **Context window in switch-menu mode** reflects the launch model, not live `/model` switches — a downstream limitation of the catalog/gateway path (see [PRD-005](../prd-005-local-proxy-catalog-routing/)), not the preferences layer.
-
----
-
-## Related
-
-- **Knowledge:** [`preferences-config.md`](../../../knowledge/private/data/preferences-config.md)
-- [PRD-001 — CLI Core & Launch Orchestration](../prd-001-cli-core-launch-orchestration/prd-001-cli-core-launch-orchestration-index.md) — launch flow that reads/writes these preferences
-- [PRD-003 — Model Discovery & Classification](../prd-003-model-discovery-classification/) — tier-scoped model lists, `sourceBackend` merge
-- [PRD-005 — Local Proxy & Catalog Routing](../prd-005-local-proxy-catalog-routing/) — catalog routes built from resolved favorites
-- [PRD-009 — Codex Integration](../prd-009-codex-integration/prd-009-codex-integration-index.md) — Codex favorites catalog using the shared resolver

package/library/requirements/completed/prd-009-codex-integration/prd-009-codex-integration-index.md

@@ -1,212 +0,0 @@
-# PRD-009: Codex Integration (CLI + Desktop App) *(Retroactive)*
-
-> **Status:** Shipped
-> **Priority:** —
-> **Effort:** —
-> **Written:** June 2026
-> **Retroactive:** Yes — written after implementation (rflectr v0.2.7).
-> **Source:** `src/codex/*`, `src/codex.ts`, `src/codex-app.ts`, `src/codex-proxy.ts`, `src/codex-responses-adapter.ts`
-
-## Overview
-
-`rflectr codex` and `rflectr codex-app` launch OpenAI **Codex** — the terminal CLI and the desktop app — against any model in the user's rflectr registry (Anthropic, xAI, Gemini, Nvidia, DeepSeek, OpenAI, OpenCode Zen/Go, Vertex AI), even though Codex speaks the **OpenAI Responses API** (`POST /v1/responses`) and most of those providers do not.
-
-The integration follows the shared host-harness skeleton (see [`harnesses.md`](../../../knowledge/private/integrations/harnesses.md)): find the Codex binary → resolve provider + model → start a local proxy that speaks the Responses wire format → point Codex at it → restore/clean up on exit. Codex departs from the Claude Code flow in two ways that define this PRD:
-
-1. **A Responses-API translation proxy** (`src/codex-proxy.ts` + `src/codex-responses-adapter.ts`) instead of the Anthropic-format proxy.
-2. **Two binding mechanisms.** The **CLI** is pointed at the proxy by a *sidecar TOML profile* (`~/.codex/rflectr-launch.config.toml`) and `codex --profile rflectr-launch -m <model>` — it never edits `~/.codex/config.toml`. The **desktop app** cannot inherit env or a `--profile` flag, so its `config.toml` is *patched in place with a backup* and *restored on exit* via a lock file.
-
-A two-tier routing model decides whether a proxy is even needed: **Tier 1 (direct)** for OpenAI API-key providers (Codex talks to OpenAI natively); **Tier 2 (proxy)** for everyone else, including OpenAI via OAuth (`src/codex/routing.ts:60-91`).
-
-## What Was Built
-
-**CLI entry — `runCodexCommand`** (`src/codex.ts:301`): parses `--help` / `--restore` / `--config` / `--vertex` / `--provider` / `--model` / `--trace`, recovers interrupted sessions, builds the provider catalog filtered to Codex-compatible providers, runs the picker (or skips it for scripted launch), resolves a `CodexRoute`, starts the proxy when the route is Tier 2, writes the sidecar profile + catalog, takes a session lock, and spawns Codex. A `finally` block closes the proxy and removes the overlay on exit (`src/codex.ts:653-656`).
-
-**App entry — `runCodexAppCommand`** (`src/codex-app.ts:284`): macOS/Windows only, parses the same flags, runs the picker, *always* starts the proxy (App is always Tier 2), saves a restore snapshot, backs up and patches `~/.codex/config.toml`, opens (or restarts) the Codex app, then **blocks on `Ctrl+C`** and restores the original config on shutdown (`src/codex-app.ts:589-606`).
-
-**Responses proxy — `startCodexProxy`** (`src/codex-proxy.ts:138`): a `127.0.0.1:0` HTTP server serving `GET /health`, `GET /v1/models`, `GET /v1/models/<id>`, and `POST /v1/responses`. It pre-instantiates one `LanguageModel` per route via `createLanguageModel()`, resolves the requested model id against the route table (with fuzzy slug lookup and a fallback to `routes[0]`), translates the request through the Responses adapter, optionally trims history to the context window, and streams or returns the SDK result as Responses SSE/JSON.
-
-**Responses adapter** (`src/codex-responses-adapter.ts`): `translateResponsesRequest` → SDK call params; `streamResponsesResponse` / `generateResponsesResponse` → Responses SSE/JSON; rate-limit and error stream helpers. This reuses the shared Vercel AI SDK translation machinery (`proxy-shared.ts`, `provider-factory.ts`) — the same single translation path documented in PRD-004.
-
-**Favorites catalog mode**: when `prefs.favoriteModels.length > 0`, both commands resolve favorites via the shared `src/favorites-resolver.ts` (filtered by an `agent: 'codex'` blacklist), build a `CodexProxyRoute[]`, and start a single multi-route proxy. Catalog slugs are collision-safe `${providerId}__${modelId}` (`src/codex/favorites-catalog.ts:13`).
-
-## Goals
-
-- Launch Codex CLI and the Codex desktop app against any registry provider/model, bridging Responses ↔ upstream via one local proxy.
-- **Never edit `~/.codex/config.toml` for CLI launches** — use a disposable sidecar profile so the user's personal Codex settings remain untouched.
-- For the App, patch `config.toml` *safely*: snapshot + backup before, restore on `Ctrl+C` or crash recovery, never delete conversations.
-- Preserve Codex's history visibility in the App by keeping `model_provider = "openai"` and redirecting via `openai_base_url` (a custom provider would hide existing OpenAI/ChatGPT threads).
-- Route OpenAI API-key providers directly (Tier 1) and everyone else through the proxy (Tier 2).
-- Support a multi-model favorites catalog for mid-session switching, capped at 20 routes.
-- Default the CLI sandbox to `danger-full-access` so shell tools reach the network, and strip CI env vars so IDE terminals don't force read-only mode.
-- Protect against context overflow (early auto-compaction config for the App + proxy-level truncation as a last resort).
-
-## Non-Goals
-
-- Owning the SDK translation layer itself — that is PRD-004 (this PRD reuses it via the Responses adapter).
-- Owning the generic local proxy / catalog routing for Claude Code — that is PRD-005 (Codex has its own Responses proxy, but shares the favorites-resolver and provider-factory).
-- Owning the favorites/tier data model — that is PRD-008 (this PRD consumes `favoriteModels` and resolves them per-surface).
-- Owning credential storage (PRD-006) or OAuth device flows (PRD-007) — Codex reads resolved credentials and forwards them.
-- Supporting the Codex desktop app on Linux (no app exists there).
-- Mid-session live model switching in the App via a hot config swap — switching is via the catalog the app loads at launch.
-
-## Features
-
-| Feature | `rflectr codex` (CLI) | `rflectr codex-app` (App) | Source |
-|---|---|---|---|
-| Binding mechanism | Sidecar TOML profile + `--profile`/`-m` flags; never edits `config.toml` | Patches `~/.codex/config.toml` in place, with backup + restore | `src/codex/profile.ts:31`, `src/codex/app-config.ts:198` |
-| Tier 1 direct (OpenAI API key) | Yes — Codex calls OpenAI natively, no proxy | No — always proxied | `src/codex/routing.ts:86-90` |
-| Tier 2 proxy (everyone else) | Yes | Yes (always) | `src/codex-proxy.ts:138` |
-| Proxy auth | `requireAuth: true` → `RFLECTR_CODEX_KEY=proxy-local` token | `requireAuth: false` (GUI can't send a token) + loopback origin check | `src/codex-proxy.ts:144-194`, `src/codex/launch.ts:90-92` |
-| Catalog file | `models-<provider>.json` / `models-favorites.json` | `app-models-<provider>.json` / `app-models-favorites.json` | `src/codex/session.ts:52`, `src/codex/app-session.ts:42` |
-| Catalog slug (single) | `stripGoogleModelPrefix(id)` | bare id (`codexAppModelSlug`) | `src/codex/catalog.ts:101-105` |
-| Catalog slug (favorites) | `${providerId}__${modelId}` | `${providerId}__${modelId}` | `src/codex/favorites-catalog.ts:13` |
-| Session lock | `session.json` (one CLI session) | `session-app.json` + `app-restore-state.json` + backups | `src/codex/session.ts:44`, `src/codex/app-session.ts:34-44` |
-| Sandbox | `danger-full-access` (profile + spawn args) | n/a (app manages its own) | `src/codex/profile.ts:17`, `src/codex/launch.ts:82-85` |
-| Context overflow | Proxy-level truncation (85% window) | `model_context_window` + `model_auto_compact_token_limit` (70%) + proxy truncation | `src/codex-proxy.ts:40-51`, `src/codex/app-profile.ts:47-50` |
-| Vertex AI path | `--vertex` (gcloud ADC) | `--vertex` (gcloud ADC) | `src/codex.ts:206`, `src/codex-app.ts:142` |
-| Favorites catalog | Up to 20 routes, multi-route proxy | Up to 20 routes, multi-route proxy | `src/codex/favorites-launch.ts:12`, `src/favorites-resolver.ts:91` |
-| `--config` preview | Writes profile + catalog, prints paths, no launch | **Preview only** — prints the TOML, no disk writes, no app, no proxy | `src/codex.ts:583`, `src/codex-app.ts:481` |
-| `--restore` | Removes overlay files (`models-*.json`, profile, lock) | Restores `config.toml`, removes `app-models-*.json`; refuses if a live session holds the lock | `src/codex/session.ts:142`, `src/codex/app-session.ts:143` |
-
-## Architecture & Implementation
-
-### CLI launch flow (`rflectr codex`)
-
-```mermaid
-flowchart TD
-    start["runCodexCommand (src/codex.ts:301)"]
-    start --> bin["findCodexBinary (codex/launch.ts:48)"]
-    bin --> recover["recoverInterruptedCodexSession (codex/session.ts:173)"]
-    recover --> cat["fetchProviderCatalog agent:codex"]
-    cat --> compat["codexCompatibleProviders (codex/routing.ts:40)"]
-    compat --> pick["pickCodexProvider / pickCodexModel (codex/prompts.ts)"]
-    pick --> route["resolveCodexRoute (codex/routing.ts:61)"]
-    route -->|tier=direct, OpenAI key| direct["env OPENAI_API_KEY; profile model_provider=openai; no proxy"]
-    route -->|tier=proxy| proxy["startCodexProxy requireAuth:true (codex-proxy.ts:138)"]
-    proxy --> profile["buildCodexProfileToml → rflectr-launch.config.toml (codex/profile.ts:31)"]
-    direct --> profile
-    profile --> lock["writeSessionLock session.json (codex/session.ts:111)"]
-    lock --> spawn["launchCodex --profile rflectr-launch -m model (codex/launch.ts:100)"]
-    spawn --> done["on exit: proxyHandle.close() + restoreCodexOverlay (codex.ts:653)"]
-```
-
-**Routing** (`src/codex/routing.ts:61-91`): `resolveCodexRoute` returns `tier: 'direct'` only when `model.npm === '@ai-sdk/openai'`, the provider is **not** OAuth, and `modelFormat === 'openai'`; everything else is `tier: 'proxy'`. For Zen/Go cloud backends the endpoint format is taken from `modelFormat` (the registry npm is unreliable there) and the base URL gets a `/v1` suffix for non-Anthropic models (`src/codex/routing.ts:49-58`).
-
-**Sidecar profile** (`src/codex/profile.ts:31-64`): a Tier 2 profile defines `model_provider = "rflectr-proxy"`, `[model_providers.rflectr-proxy]` with `base_url = http://127.0.0.1:<port>/v1`, `wire_api = "responses"`, `env_key = "RFLECTR_CODEX_KEY"`, plus `sandbox = "danger-full-access"`. A Tier 1 profile points `base_url` at OpenAI and uses the provider's real `env_key` (e.g. `OPENAI_API_KEY`).
-
-**Child env** (`src/codex/launch.ts:87-98`): Tier 2 sets `RFLECTR_CODEX_KEY=proxy-local` (the placeholder the proxy validates); Tier 1 sets the provider's real key env var. `stripCodexInheritedEnv` removes nine CI vars (`CI`, `CODEX_CI`, `GITHUB_ACTIONS`, …) so IDE terminals don't drop Codex into read-only CI mode. Spawn always injects `-s danger-full-access` unless the user passed their own sandbox flag (`src/codex/launch.ts:82-85`, `:107`).
-
-**Session lock & recovery** (`src/codex/session.ts`): `session.json` records pid + paths; a session is "stale" only when the owning pid is no longer alive (`isSessionStale`, `:134`). On launch, `recoverInterruptedCodexSession` removes orphaned overlay files unless a concurrent live session holds the lock. `--restore` calls `restoreCodexOverlay` to delete the profile, lock, and all `models-*.json`.
-
-### App launch flow (`rflectr codex-app`)
-
-```mermaid
-flowchart TD
-    a["runCodexAppCommand (src/codex-app.ts:284)"]
-    a --> supp["codexAppSupported() — macOS/Windows only"]
-    supp --> rec["recoverInterruptedCodexAppSession (app-session.ts:178)"]
-    rec --> pick["picker → resolveCodexRoute (tier forced to proxy)"]
-    pick --> px["startCodexProxy requireAuth:false (codex-proxy.ts:138)"]
-    px --> snap["saveAppRestoreStateBeforePatch (app-session.ts:107)"]
-    snap --> bak["backupConfigToml → backups/config.toml.<ts>.bak (app-session.ts:95)"]
-    bak --> patch["applyAppConfigPatch ~/.codex/config.toml (app-config.ts:198)"]
-    patch --> lock["writeAppSessionLock session-app.json (app-session.ts:66)"]
-    lock --> open["launchOrRestartCodexApp (app-launch.ts:203)"]
-    open --> wait["waitForShutdownWithConfirm — block on Ctrl+C (codex-app.ts:59)"]
-    wait --> quit["quitCodexAppGracefully + restoreCodexAppOverlay (codex-app.ts:593-600)"]
-```
-
-**Config patch** (`src/codex/app-config.ts:121-212`): `mergeAppConfig` keeps the user's existing root keys but overwrites `model`, `model_provider`, `openai_base_url`, `model_catalog_json`, and the two context fields; it strips any legacy `profile` key and the legacy `rflectr-launch-codex-app` provider/profile tables. The written config is validated (`validateAppConfigText`, `:175`) to assert `model_provider` stays `openai`, the `openai_base_url` matches the proxy port, and the catalog path matches.
-
-**Why `model_provider = "openai"`** (`src/codex/app-profile.ts:33-52`): the app records the provider on every local thread and filters history by provider, so a custom provider would hide the user's existing OpenAI/ChatGPT threads while a rflectr session is active. rflectr therefore writes the display model `CODEX_APP_DISPLAY_MODEL = 'gpt-5.5'` and redirects the built-in provider with `openai_base_url`. The proxy routes the actual selected model via its fallback mechanism.
-
-**Backup + lock + restore**: before patching, `saveAppRestoreStateBeforePatch` snapshots the pre-session root keys to `app-restore-state.json`, and `backupConfigToml` copies `config.toml` to a rotating `backups/config.toml.<ts>.bak` (max 5). The lock `session-app.json` records `pid`, `configPath`, `catalogPaths`, `restoreStatePath`, `backupPath`, and `proxyPort`. On exit, `restoreCodexAppOverlay` (`src/codex/app-session.ts:143`) restores from the snapshot (preferred) or the backup file, removes `app-models-*.json`, and clears the lock. It **refuses** to run while another live session holds the lock (`:145-151`). Crash recovery on the next launch is automatic (`recoverInterruptedCodexAppSession`, `:178`).
-
-**App launch/quit** (`src/codex/app-launch.ts`): finds `Codex.app` (macOS, via fixed paths + `mdfind` on bundle id `com.openai.codex`) or `Codex.exe` (Windows, via `%LOCALAPPDATA%\Programs` candidates + `Get-StartApps`). "Is it running?" uses `osascript` (macOS) / `Get-CimInstance` + window-handle checks (Windows). If Codex is already running, rflectr offers to restart it so new settings apply; otherwise it just opens it.
-
-### The Responses proxy & adapter
-
-`startCodexProxy(routes, options)` (`src/codex-proxy.ts:138`) builds a `Map<modelId, LanguageModel>` up front by calling `createLanguageModel({ npm, modelId: upstreamModelId, apiKey, baseURL, vertex })` per route (`:147-159`), then serves:
-
-- **`GET /v1/models`** — synthesizes a catalog entry for each route under three id shapes: bare `modelId`, `codexAppModelSlug(modelId)`, and `${providerId}__${modelId}` (`:215-221`), so any slug Codex requests resolves.
-- **`POST /v1/responses`** — when `requireAuth`, validates the inbound key equals `proxy-local` (`PROXY_PLACEHOLDER_KEY`, `:74`); resolves the model (with `codexRouteLookupIds` fuzzy matching across `/`, `__`, and app-slug prefixes, `:76-93`); falls back to `routes[0]` if unmatched (handles the app's hardcoded background `gpt-5.4`/`gpt-5.5` ids); translates via `translateResponsesRequest`; trims to the context window if set; then streams (`streamResponsesResponse`) or returns (`generateResponsesResponse`). 429s become a Responses rate-limit body/stream; other upstream errors map to honest HTTP statuses (`upstreamHttpStatus`, `:109-117`).
-
-**App-mode security** (`requireAuth: false`, `src/codex-proxy.ts:177-194`): since the GUI cannot send the token, POSTs are gated by a loopback `Origin`/`Referer` check instead.
-
-**Context truncation** (`src/codex-proxy.ts:24-51`): `trimToContextLimit` estimates characters (≈4 chars/token) and drops the oldest messages until the estimate is under 85% of the window, always keeping at least one user-led message.
-
-**Error formatting** (`src/codex/upstream-error.ts`): `formatUpstreamError` extracts the shortest honest user-facing message from SDK/upstream error shapes — no stack traces, no `file://` noise — for the Codex TUI.
-
-### Favorites catalog
-
-When favorites are active, `resolveCodexFavorites` (`src/codex/favorites-launch.ts:54`) builds a per-surface `ResolveContext` and calls the shared `buildFavoritesList` (`src/favorites-resolver.ts:87`, cap 20). Zen/Go favorites require an OpenCode API key (resolved via `resolveOrCollectApiKey` / credential store) and are dropped if absent. `buildCodexProxyRoutesFromResolved` (`:12`) maps each resolved favorite to a `CodexProxyRoute`, skipping OAuth providers with an empty key (OAuth refresh isn't supported in the favorites proxy, `:24-27`). Each route's catalog slug is the collision-safe `${providerId}__${modelId}`. The starting model is launched via that slug (`codexCliFavoritesSlug`), which must match the profile `model` and `codex -m`.
-
-## Acceptance Criteria
-
-- [x] `rflectr codex` launches Codex CLI against a selected registry provider/model.
-- [x] CLI launches **never edit** `~/.codex/config.toml` — only the sidecar `rflectr-launch.config.toml` (`src/codex/profile.ts:31`).
-- [x] OpenAI API-key providers route Tier 1 direct (no proxy); OpenAI-via-OAuth and all others route Tier 2 through the proxy (`src/codex/routing.ts:86-90`).
-- [x] The Tier 2 CLI child gets `RFLECTR_CODEX_KEY=proxy-local`, and the proxy rejects any other key when `requireAuth` (`src/codex/launch.ts:91`, `src/codex-proxy.ts:248-252`).
-- [x] CLI default sandbox is `danger-full-access` in both the profile and the spawn args (`src/codex/profile.ts:17`, `src/codex/launch.ts:84`).
-- [x] CI env vars are stripped before spawning Codex (`src/codex/launch.ts:16-34`).
-- [x] `rflectr codex-app` patches `config.toml` with a backup and restores it on `Ctrl+C` (`src/codex-app.ts:547-600`).
-- [x] App config keeps `model_provider = "openai"` and redirects via `openai_base_url`, validated on write (`src/codex/app-config.ts:185-195`).
-- [x] App proxy runs with `requireAuth: false` and a loopback origin guard (`src/codex-proxy.ts:177-194`).
-- [x] App writes `model_context_window` + `model_auto_compact_token_limit` (70%) when a window is known (`src/codex/app-profile.ts:47-50`).
-- [x] Proxy serves `/v1/responses`, `/v1/models`, `/v1/models/<id>`, and `/health`, translating through the Responses adapter (`src/codex-proxy.ts:196-375`).
-- [x] Proxy falls back to `routes[0]` for unknown model ids so the app's hardcoded background ids still resolve (`src/codex-proxy.ts:287-293`).
-- [x] Favorites mode builds a multi-route catalog (≤20) with `${providerId}__${modelId}` slugs (`src/codex/favorites-catalog.ts:13`, `src/favorites-resolver.ts:91`).
-- [x] Zen/Go favorites are included only when an OpenCode API key is available, and OAuth-empty favorites are skipped (`src/codex/favorites-launch.ts:24-27`, `src/favorites-resolver.ts:57-59`).
-- [x] `--config` previews without launching (CLI writes files + prints paths; App prints TOML with zero writes) (`src/codex.ts:583`, `src/codex-app.ts:481-521`).
-- [x] `--restore` cleans up overlay/app files; App `--restore` refuses while a live session holds the lock (`src/codex/app-session.ts:143-151`).
-- [x] Interrupted sessions auto-recover on the next launch (`src/codex/session.ts:173`, `src/codex/app-session.ts:178`).
-- [x] A concurrent live session is detected and blocks a second launch (`src/codex/session.ts:195`, `src/codex/app-session.ts:194`).
-- [x] `--vertex` launches Claude models through Google Vertex AI via gcloud ADC for both CLI and App (`src/codex.ts:206`, `src/codex-app.ts:142`).
-- [x] App launch is gated to macOS/Windows; Linux is rejected with a clear message (`src/codex/app-launch.ts:12-16`).
-
-## Files
-
-| File | Role |
-|---|---|
-| `src/codex.ts` | CLI entry `runCodexCommand`; help text; launch artifact writers; Vertex CLI path |
-| `src/codex-app.ts` | App entry `runCodexAppCommand`; config patch orchestration; Ctrl+C shutdown loop; Vertex App path |
-| `src/codex-proxy.ts` | Local Responses-API proxy (`startCodexProxy`); `CodexProxyRoute`; route resolution; `/v1/models` + `/v1/responses` |
-| `src/codex-responses-adapter.ts` | Responses ↔ Vercel AI SDK translation (`translateResponsesRequest`, stream/generate, rate-limit/error helpers) |
-| `src/codex/routing.ts` | Tier 1/Tier 2 routing; `resolveCodexRoute`; routable-model filter; `codexProviderEnvKey` |
-| `src/codex/profile.ts` | Sidecar `rflectr-launch.config.toml` builder; sandbox constant; catalog path helpers |
-| `src/codex/launch.ts` | `findCodexBinary`; CI-env stripping; sandbox-arg injection; child env; `launchCodex` spawn |
-| `src/codex/catalog.ts` | `model_catalog_json` builder; reasoning fields; label formatting; serialize |
-| `src/codex/session.ts` | CLI overlay session: lock, backup rotation, stale/recovery, restore |
-| `src/codex/app-config.ts` | Read/merge/validate/restore `~/.codex/config.toml`; managed-config detection |
-| `src/codex/app-profile.ts` | App root config content; display model; context fields; slug helpers |
-| `src/codex/app-session.ts` | App session: backup, restore-state snapshot, lock, recovery |
-| `src/codex/app-launch.ts` | Find/open/quit/restart the Codex desktop app (macOS + Windows) |
-| `src/codex/favorites-catalog.ts` | Favorites slug (`${providerId}__${modelId}`); CLI/App favorites catalog builders |
-| `src/codex/favorites-launch.ts` | Resolve favorites → `CodexProxyRoute[]`; OAuth skip; stale-favorite warnings |
-| `src/codex/prompts.ts` | Codex provider/model pickers; managed-flag rejection; launch confirm |
-| `src/codex/ui.ts` | Intro/outro, proxy/model log lines, session/cleanup panels |
-| `src/codex/upstream-error.ts` | Short user-facing messages from SDK/upstream failures |
-| `src/favorites-resolver.ts` | Shared per-surface favorite resolution (also used by Claude/Server) |
-
-## Risks & Known Limitations
-
-- **`@ai-sdk/github-copilot` won't work.** OpenCode loads it from internal `@opencode-ai/core`, not a public npm factory rflectr can ship — such providers are silently unroutable.
-- **Zen/Go favorites are skipped in Codex when no OpenCode key is present** (and have no gateway path in Codex generally); resolution drops them (`src/favorites-resolver.ts:57-59`).
-- **OAuth-empty favorites are dropped from the favorites proxy** — OAuth refresh flows aren't supported there (`src/codex/favorites-launch.ts:24-27`).
-- **Codex App is a stateless client** — it resends the full accumulated history every turn (no `previous_response_id`), so a long GPT-5.5 session can't be transparently resumed on a smaller-window model. Mitigated by early auto-compaction config + proxy-level truncation, both lossy as a last resort.
-- **App labels any catalog-loaded model "Custom"** (cosmetic) and periodically sends **background requests with hardcoded OpenAI ids** (`gpt-5.4`, `gpt-5.5`); the proxy routes these to the starting model via `routes[0]` fallback.
-- **OAuth tokens refresh at launch only** — long sessions may 401 when a token expires; restart to re-auth.
-- **Cost display is inaccurate for non-Anthropic models** (the host applies its own pricing table) — a documented, by-design limitation shared across harnesses.
-- **macOS sandbox quirk:** the profile TOML alone may not grant network access; rflectr also passes `-s danger-full-access` on spawn ([Codex #10390](https://github.com/openai/codex/issues/10390)).
-- **App support is macOS/Windows only** — there is no Codex desktop app on Linux.
-
-## Related
-
-- [`harnesses.md`](../../../knowledge/private/integrations/harnesses.md) — host-harness pattern; where Codex CLI/App depart from it.
-- [`codex.md`](../../../knowledge/public/guides/codex.md) — user-facing Codex guide (flags, files owned, tiers, troubleshooting).
-- [PRD-004 — Translation Layer](../prd-004-translation-layer/prd-004-translation-layer-index.md) — the SDK adapter the Responses adapter reuses.
-- [PRD-005 — Local Proxy & Catalog Routing](../prd-005-local-proxy-catalog-routing/prd-005-local-proxy-catalog-routing-index.md) — the Claude-side proxy this mirrors; shared `provider-factory` / `proxy-shared`.
-- [PRD-008 — Preferences, Tiers & Favorites](../prd-008-preferences-tiers-favorites/prd-008-preferences-tiers-favorites-index.md) — favorites data model and `favorites-resolver`.
-- [PRD-011 — Claude Desktop Integration](../prd-011-claude-desktop-integration/prd-011-claude-desktop-integration-index.md) — sibling desktop-app integration (config patch + lock-file restore, gateway path).
-- [PRD-001 — CLI Core & Launch Orchestration](../prd-001-cli-core-launch-orchestration/prd-001-cli-core-launch-orchestration-index.md) — subcommand dispatch that routes to `codex` / `codex-app`.