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
• 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

• rebased onto dev@3e60b1d9
• affected catalog/convergence files (isolated one process per file): 352 passed
• exact Linux CI shard containing the known sideband timing test: 2,520 passed, 0 failed
• full unsharded suite: 9,690 passed, 11 skipped; the existing sideband close-timing assertion failed once under full load and immediately passed 3/3 in isolation
• bun run typecheck
• bun run privacy:scan
• docs site build: 221 pages
• git diff --check
• independent backend correctness, security/privacy, code-quality/conventions, and docs 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

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a47762db-f94e-43f7-8707-742f43ae3377

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds codexAccountPickerEnabled, separates catalog metadata from runtime support, records provider discovery authority, and rewrites catalog merging and convergence around explicit observed state. It adds tests for picker visibility, provider degradation, runtime evidence, collisions, restoration, and deterministic synchronization.

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	The setting controls generated account-qualified rows. Disabled rows hide selectors and account-qualified native slugs while preserving 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 metadata from bundled runtime support. Provider fetches report authoritative or degraded discovery outcomes. Custom catalog models carry provenance 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.
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/slug-codec.test.ts	Tests cover provider authority, runtime-support drift, explicit observed-state inputs, collision handling, catalog determinism, and slug equivalence.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Convergence
  participant CatalogSource
  participant ProviderFetch
  participant ObservedMerge
  participant CatalogWriter
  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
  Convergence->>CatalogWriter: Persist the converged catalog

Loading

Possibly related PRs

• lidge-jun/opencodex#426: Adds the account-qualified Codex namespace behavior extended by this PR.
• lidge-jun/opencodex#512: Provides the codexAccountNamespaces foundation used by the picker toggle.
• lidge-jun/opencodex#359: Overlaps with bundled catalog runtime selection and reasoning-effort handling.

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 26.23% 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 identifies the main catalog convergence change for Codex account picker rows.

✨ 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.