feat(codex): converge account picker catalogs

[chrisae9]

Summary

• make retained catalog sync and evidence-bound convergence use the same deterministic observed-state merge path
• generate account-qualified Codex picker rows only when account-picker visibility is enabled, while preserving existing selector mappings and exact-account routing when it is disabled
• treat successful and empty provider discovery as authoritative, but preserve only the affected provider namespace when discovery or authentication is degraded
• preserve foreign/custom catalog rows, restore pristine native priorities, and refuse combo aliases that would shadow a row without a usable restore point
• migrate ownership of pre-marker custom-model rows at the first relevant config write, so an explicit deletion still wins during a provider outage without touching configs that never use custom models
• use installed Codex runtime evidence for reasoning-effort clamping and parse multi_agent_v2 from the admitted config bytes
• keep custom catalog files authoritative, emit typed degradation notices, and document the opt-in behavior across all supported locales

This is the third slice requested in #1019, following #1096 and #1152. It intentionally contains catalog construction, merge, and convergence behavior only. Management API/dashboard activation and the remaining lifecycle work stay in later slices.

Part of #425.

Verification

• merged current dev@fdc47db7
• latest feedback fix: 429 focused catalog/config/convergence tests passed across 6 files
• bun run typecheck
• bun run privacy:scan
• git diff --check
• independent backend correctness, security/privacy, and code-quality/conventions reviews found no remaining blockers

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Added the codexAccountPickerEnabled setting for account-qualified Codex model rows.
  • Disabling picker rows preserves account mappings and explicit routing while restoring native rows.
  • Improved custom catalog support, native model handling, and reasoning-effort compatibility.

• Bug Fixes

  • Improved catalog synchronization, restoration, collision handling, and preservation of managed entries.
  • Clarified behavior for degraded, unavailable, or authoritative provider discovery.

• Documentation

  • Updated Codex model and provider configuration guidance across supported languages.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
CodeRabbit/Codex review was requested via the review-ready label. If no review appears, comment @coderabbitai review to request one.
Maintainers: @lidge-jun @Ingwannu @Wibias

Hygiene

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds account-picker gating, separates catalog metadata from runtime support, records provider discovery authority, rewrites catalog merging around explicit observed state, and adds custom-model ownership migration. It also adds broad tests for convergence, restoration, collisions, provider degradation, and configuration persistence.

Changes

Codex catalog convergence

Layer / File(s)	Summary
Account-picker configuration and selector visibility src/codex/catalog/account-models.ts, docs-site/src/content/docs/..., tests/native-model-toggle.test.ts, tests/codex-convergence-account-selectors.test.ts	codexAccountPickerEnabled controls generated account-qualified rows. Disabled rows hide selectors and account-qualified native slugs while preserving namespace mappings and exact routing.
Catalog source and provider observation src/codex/catalog/bundled.ts, src/codex/catalog/provider-fetch.ts, src/codex/catalog/effort.ts, src/codex/catalog/parsing.ts, tests/codex-runtime.test.ts, tests/catalog-oauth-observation.test.ts	Catalog gathering separates selected catalog metadata from bundled runtime support. Provider fetches report authoritative or degraded discovery outcomes. Catalog rows retain ownership metadata.
Observed-state catalog construction and merge src/codex/catalog/sync.ts, src/codex/catalog/aggregation.ts, src/providers/slug-codec.ts, tests/codex-catalog.test.ts	Observed-state merging applies explicit native, routed, provider, account-bound, combo-shadow, and warning policies.
Evidence-bound convergence and retained synchronization src/codex/convergence.ts, src/codex/features.ts, structure/03_catalog-and-subagents.md	Convergence passes catalog kind, feature state, native baselines, provider outcomes, and degraded-provider state into catalog preparation and effort clamping.
Custom-model ownership migration src/codex/custom-model-catalog-migration.ts, src/config.ts, src/types.ts, tests/custom-model-catalog-migration.test.ts, tests/config-user-edits.test.ts	Configuration writes project and adopt versioned migration metadata. Legacy custom-model ownership is inferred only from valid pre-migration configurations.
Catalog, convergence, and configuration validation tests/codex-catalog-sync-hardening.test.ts, tests/codex-convergence-contract.test.ts, tests/codex-v2-gate.test.ts, tests/gather-routed-models-single-flight.test.ts, tests/codex-convergence-account-selectors.test.ts	Tests cover provider authority, runtime-support drift, explicit observed-state inputs, picker transitions, collision handling, deterministic synchronization, metadata preservation, and migration state.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Convergence
  participant CatalogSource
  participant ProviderFetch
  participant ObservedMerge
  participant ConfigPersistence
  Convergence->>CatalogSource: Resolve catalog kind and runtime support
  Convergence->>ProviderFetch: Gather models and provider outcomes
  ProviderFetch-->>Convergence: Return models with authoritative or degraded states
  Convergence->>ObservedMerge: Build and merge observed catalog state
  ObservedMerge-->>Convergence: Return normalized catalog entries
  ConfigPersistence->>ConfigPersistence: Project and adopt migration metadata

Loading

Possibly related PRs

• lidge-jun/opencodex#426: Extends the account-qualified Codex namespace implementation.
• lidge-jun/opencodex#359: Overlaps with bundled catalog runtime selection and reasoning-effort handling.
• lidge-jun/opencodex#1244: Builds on related Codex catalog synchronization and account-qualified model visibility changes.

Suggested reviewers: ingwannu, lidge-jun

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: deterministic convergence of Codex account picker catalogs.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4878de383

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[coderabbitai]

@github-actions[bot] I will review the current pull request state. I only have the latest comment context.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

@github-actions[bot] Acknowledged. The pull request is ready for review. I will review the current pull request state.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/codex-convergence-account-selectors.test.ts`:
- Around line 512-514: Update the convergence assertion around syncCatalogModels
so unchanged custom-catalog.json content expects catalogWritten to be false, or
adjust writeRetainedCatalogSync to skip replaceActiveCodexCatalog and its atomic
write when prepared bytes match the existing file; preserve true only when
content is physically written.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cbffb3b0-0bdf-4bf6-a7cd-92fc452c48b1

📥 Commits

Reviewing files that changed from the base of the PR and between a4878de and de53992.

📒 Files selected for processing (5)

• src/codex/catalog/bundled.ts
• src/codex/catalog/sync.ts
• tests/codex-catalog.test.ts
• tests/codex-convergence-account-selectors.test.ts
• tests/codex-runtime.test.ts

[Wibias]

Review - Request Changes

Requesting changes for one correctness issue I found.

P2 - Legacy custom models can ignore deletion during an outage after upgrading

There is a migration edge case around the new opencodex_catalog_kind = "custom-model-v1" marker.

Custom model rows created by older OpenCodex versions do not have this marker. In the new merge logic, an absent custom row is treated as an intentional deletion only when the existing catalog row already carries CODEX_CUSTOM_MODEL_CATALOG_KIND.

That means this sequence can leave a deleted model behind:

1. A pre-1212 version writes a custom model row such as offline/my-model.
2. The row has no ownership marker.
3. The user upgrades to this version.
4. The offline provider is currently degraded/unavailable.
5. The user removes offline/my-model from customModels.
6. Catalog convergence runs before any successful post-upgrade sync has stamped the old row.
7. Because the row has no custom-model marker, it falls into the degraded-provider preservation path and survives.

The result is that a model the user explicitly deleted can remain in the Codex catalog until a later authoritative provider refresh.

I think this needs either an ownership migration for legacy custom rows or another mechanism that lets config deletion remain authoritative during the first post-upgrade degraded refresh.

Please also add a regression covering:

• an old-style unmarked custom catalog row
• removal from config.customModels
• provider discovery degraded
• both convergence and retained sync remove the stale row

Apart from this, I did not find another merge-blocking correctness or security issue in the current diff. I also did not find a new credential/account-identity leak.

CI note

The current GitHub Actions run for de53992e is still action_required, so the PR does not yet have independently completed CI on the current head.

[coderabbitai]

@github-actions[bot] Acknowledged. I will review the current pull request state, including the reported resolution of the legacy custom-model deletion case.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chrisae9]

@Wibias Fixed in 92ec9d6.

The first relevant config write now records a one-time ownership ledger from the persisted pre-upgrade customModels list. Both convergence and retained sync use that same evidence, so a deleted old unmarked OpenCodex row is removed even when its provider is degraded. The migration stays dormant for configs that never use custom models.

The classification is deliberately narrow: foreign rows, account-selector rows, combo rows, and unknown future markers are preserved. If authoritative provider discovery later returns the same slug, it is marked as an ordinary provider row so a later outage cannot remove it using stale migration evidence.

I added the requested end-to-end regressions for both writers (old unmarked row, config removal, degraded discovery), including preservation of an unrelated degraded sibling. The migration/save-boundary and fail-closed cases are covered separately. The focused catalog/config/convergence run is 429 passing tests; typecheck, privacy scan, and diff check also pass.