feat(codex): add account picker lifecycle settings

[chrisae9]

Summary

• Add the optional codexAccountPickerEnabled lifecycle setting for account-qualified Codex picker entries.
• Initialize privacy-safe selector bindings when enabled, preserve stable bindings across disable/delete/re-add flows, and keep exact selector routing available even while generated picker rows are hidden.
• Reserve the canonical policy namespace and slash-qualified routing-profile alias prefixes so picker enable and account add cannot create ambiguous or unloadable combined configs.
• Persist account and setting changes before catalog refresh, retry refresh once after a short delay, and report catalogRefreshPending without leaking internal errors when the catalog is missing, unwritten, or its models cache cannot be invalidated.
• Surface a generic ocx sync recovery warning in the dashboard and CLI when an account change succeeds but its catalog refresh remains pending; JSON clients retain the boolean completion field.
• Fail closed on a malformed persisted picker flag without discarding providers, accounts, or exact selector routes; live config writes remain strict.
• Prevent the physical ChatGPT account ID selected by Pool auth from being echoed through ordinary errors, combo failures, redirects, or compact responses while preserving unrelated provider identifiers and retry classification.
• Document picker visibility, exact-account routing, account lifecycle recovery, and management behavior in English, Japanese, Simplified Chinese, Korean, and Russian. A dedicated dashboard control remains a follow-up layer.
• Continue the account-targeting work from feat(codex): add exact account routing #671 and feat(codex): add account-qualified catalog entries #949.

Dashboard feedback

Verification

• Focused picker/account/catalog/routing-profile, config-recovery, response-privacy, combo, redirect, and compact regression suites pass.
• Independent security/privacy review suite: 284 pass.
• Full dashboard suite: 587 pass, plus lint, i18n lint, and production build.
• bun run typecheck
• bun run privacy:scan
• cd docs-site && bun run build (216 pages)
• git diff upstream/dev...HEAD --check
• Full suite after the RI-06 sync (96c33aa8): 8,504 pass and 10 skip; the same unrelated native-main sideband admission timing test failed only under aggregate load. Its exact regression then passed 10 consecutive isolated runs.
• Independent frontend/code-quality, architecture/conventions, and security/privacy reviews completed after merging dev, with no remaining findings.
• Latest dev sync (ebcfff44): tri-state Codex fastMode injection is merged; its 52 affected tests plus 193 picker/config regressions, typecheck, privacy scan, and diff-check pass.

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.

Summary by CodeRabbit

• New Features

  • Added optional Codex account-picker visibility controls.
  • Picker rows show available accounts while preserving exact routes.
  • Settings and account-management responses report pending catalog refreshes.
  • Enabling the picker can initialize namespaces without exposing private metadata.

• Bug Fixes

  • Added rollback protection for failed updates.
  • Catalog refreshes retry automatically and provide sync guidance.
  • Added warning notifications across the dashboard and CLI.
  • Improved namespace collision validation and unavailable-account handling.

• Documentation

  • Documented picker visibility, routing preservation, and refresh behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds configurable Codex account-picker visibility, preserves exact selector routing, persists account changes before catalog refresh, retries refreshes, and reports catalogRefreshPending through APIs, CLI output, and GUI notifications.

Changes

Codex account picker lifecycle

Layer / File(s)	Summary
Picker visibility and catalog selectors src/types.ts, src/config.ts, src/codex/account-namespaces.ts, src/codex/catalog/account-models.ts, src/routing/*, tests/*, structure/*, docs-site/src/content/docs/*	codexAccountPickerEnabled controls generated account-qualified rows. Visible entries target available accounts. Routing-profile aliases and the policy namespace participate in collision checks. Hidden rows preserve exact selector routes.
Management settings and catalog refresh src/codex/catalog-refresh-status.ts, src/server/management-api.ts, src/server/management/context.ts, src/server/management/config-routes.ts, tests/settings-stream-mode.test.ts	Settings routes validate and persist picker state, initialize bindings when required, roll back failed mutations, retry catalog refreshes, and return pending status.
Account persistence and lifecycle refresh src/codex/account-lifecycle.ts, src/codex/auth-api.ts, tests/codex-auth-api.test.ts, structure/05_gui-and-management-api.md	Manual creation, deletion, and OAuth login persist account state before refresh. Completion responses include catalogRefreshPending when refresh remains incomplete.
CLI and GUI completion feedback src/cli/*, gui/src/*, gui/tests/*, tests/cli-account.test.ts	CLI output preserves pending status in JSON and emits generic sync guidance otherwise. GUI account mutations use structured completion data and warning notification tones.

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

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AccountAPI
  participant OcxConfig
  participant CatalogRefresh
  participant Catalog
  Client->>AccountAPI: create, delete, or complete OAuth login
  AccountAPI->>OcxConfig: persist account and selector bindings
  AccountAPI->>CatalogRefresh: refresh catalog with retry
  CatalogRefresh->>Catalog: write and synchronize catalog
  Catalog-->>CatalogRefresh: completion result
  CatalogRefresh-->>AccountAPI: catalogRefreshPending
  AccountAPI-->>Client: mutation result and refresh status

Loading

Possibly related PRs

• lidge-jun/opencodex#949: Extends account-qualified catalog behavior with picker visibility and refresh handling.
• lidge-jun/opencodex#512: Provides the Codex namespace foundation used by the picker flow.
• lidge-jun/opencodex#526: Provides catalog refresh completion state used by this change.

Suggested reviewers: ingwannu, wibias, lidge-jun

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.64% 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 summarizes the main change: adding lifecycle settings for the Codex account picker.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{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: fb44b7d353

ℹ️ 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]

Actionable comments posted: 2

🤖 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 `@src/server/management-api.ts`:
- Around line 105-109: Update refreshCodexCatalogStrict and auth-api’s
refreshAccountNamespaceCatalog to inspect the refresh result and reject when
catalogExists is false, while preserving successful refresh handling. Ensure the
existing retry and catalogRefreshPending flow receives this failure, and add a
regression covering a non-throwing incomplete refresh.

In `@tests/settings-stream-mode.test.ts`:
- Around line 359-367: Update the response assertions in the settings
stream-mode test to decode the response body once, reuse it for the existing
field checks, and assert that its serialized payload does not contain “private
refresh failure detail” in any field. Keep the existing status and refresh-count
assertions unchanged.

🪄 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: 7040a690-d68b-483f-83f6-82f68682bbfd

📥 Commits

Reviewing files that changed from the base of the PR and between 6ed4c78 and fb44b7d.

📒 Files selected for processing (19)

• src/codex/account-lifecycle.ts
• src/codex/account-namespaces.ts
• src/codex/auth-api.ts
• src/codex/catalog-refresh-status.ts
• src/codex/catalog/account-models.ts
• src/config.ts
• src/server/management-api.ts
• src/server/management/config-routes.ts
• src/server/management/context.ts
• src/types.ts
• structure/02_config-and-codex-home.md
• structure/03_catalog-and-subagents.md
• structure/05_gui-and-management-api.md
• tests/codex-account-namespaces.test.ts
• tests/codex-auth-api.test.ts
• tests/config.test.ts
• tests/native-model-toggle.test.ts
• tests/router.test.ts
• tests/settings-stream-mode.test.ts

[coderabbitai]

Actionable comments posted: 6

🤖 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 `@docs-site/src/content/docs/ja/reference/management-api.md`:
- Line 204: Update the table row for GET, POST, DELETE /api/codex-auth/accounts
to add the missing trailing pipe and replace the redundant 「することができます」 phrasing
with the concise equivalent, preserving the row’s meaning and table formatting.

In `@src/codex/account-lifecycle.ts`:
- Around line 73-83: Extend the focused Bun regression coverage for
deleteCodexAccount and its auth-api refresh path: verify enabled pickers with a
stored pool account and matching namespace return true, while disabled pickers
or orphaned namespaces return false. Also verify deleting and re-adding the same
account preserves the namespace and triggers refresh when visibility is enabled,
using the existing lifecycle/catalog test symbols under tests/ rather than
relying only on router.test.ts.

In `@src/codex/auth-api.ts`:
- Around line 1316-1318: Make the deletion flow around deleteCodexAccount and
saveRuntimeConfig atomic: ensure the credential tombstone and runtimeConfig
account removal occur within one mutation critical section, or add compensating
rollback that restores both when saveRuntimeConfig throws
ConfigMutationLockError. Preserve the 503 response while preventing partial
deletion, and add a delete-specific test covering save failure and state
restoration.

In `@src/codex/catalog-refresh-status.ts`:
- Around line 28-36: In the retry loop surrounding refresh, add a short delay
between the failed first attempt and the second attempt, using the existing
retry-delay convention from renameAtomicFile where practical. Keep the current
two-attempt limit, immediate success return, and generic failure handling
unchanged; only pause before retrying after a caught error.
- Around line 32-35: Update the catch block in the catalog refresh retry flow to
bind the caught error and call debugProviderDiagnostic("codex",
"catalog-refresh-failed", ...) for every failed attempt. Extract the error
message explicitly rather than serializing Error directly, sanitize it with
redactSecretString and redactUserPath before recording, and preserve the
existing generic terminal warning.

In `@src/server/management/context.ts`:
- Around line 12-16: Export a shared CodexCatalogRefreshCompletion type from
catalog-refresh-status.ts and use it as the return result type of
refreshCodexCatalog in the management context. Update
assertCodexCatalogRefreshComplete to accept void | CodexCatalogRefreshCompletion
while preserving its existing behavior, and remove the duplicated inline object
shape.

🪄 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: 32d4ce77-5ce2-40da-9ea6-96e424668bb6

📥 Commits

Reviewing files that changed from the base of the PR and between fb44b7d and eae13eb.

📒 Files selected for processing (39)

• docs-site/src/content/docs/guides/codex-app-models.md
• docs-site/src/content/docs/guides/web-dashboard.md
• docs-site/src/content/docs/ja/guides/codex-app-models.md
• docs-site/src/content/docs/ja/guides/web-dashboard.md
• docs-site/src/content/docs/ja/reference/configuration/providers.md
• docs-site/src/content/docs/ja/reference/management-api.md
• docs-site/src/content/docs/ko/guides/codex-app-models.md
• docs-site/src/content/docs/ko/guides/web-dashboard.md
• docs-site/src/content/docs/ko/reference/configuration/providers.md
• docs-site/src/content/docs/ko/reference/management-api.md
• docs-site/src/content/docs/reference/configuration/providers.md
• docs-site/src/content/docs/reference/management-api.md
• docs-site/src/content/docs/ru/guides/codex-app-models.md
• docs-site/src/content/docs/ru/guides/web-dashboard.md
• docs-site/src/content/docs/ru/reference/configuration/providers.md
• docs-site/src/content/docs/ru/reference/management-api.md
• docs-site/src/content/docs/zh-cn/guides/codex-app-models.md
• docs-site/src/content/docs/zh-cn/guides/web-dashboard.md
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
• docs-site/src/content/docs/zh-cn/reference/management-api.md
• src/codex/account-lifecycle.ts
• src/codex/account-namespaces.ts
• src/codex/auth-api.ts
• src/codex/catalog-refresh-status.ts
• src/codex/catalog/account-models.ts
• src/config.ts
• src/server/management-api.ts
• src/server/management/config-routes.ts
• src/server/management/context.ts
• src/types.ts
• structure/02_config-and-codex-home.md
• structure/03_catalog-and-subagents.md
• structure/05_gui-and-management-api.md
• tests/codex-account-namespaces.test.ts
• tests/codex-auth-api.test.ts
• tests/config.test.ts
• tests/native-model-toggle.test.ts
• tests/router.test.ts
• tests/settings-stream-mode.test.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eae13eb170

ℹ️ 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".

[chrisae9]

@coderabbitai review

[coderabbitai]

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs-site/src/content/docs/reference/configuration/providers.md (1)

20-21: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document exact account-route retention and pool management.

The new text says that exact selector routing uses the binding map. It does not state that an account-qualified route keeps its selected account and never falls through to another credential. It also omits the CLI commands that manage the same account pools.

• docs-site/src/content/docs/reference/configuration/providers.md#L20-L21: State that exact <selector>/<native-openai-model> routes retain the selected account without Pool fallback. Distinguish Pool routing from Direct routing. Add ocx account list, ocx account current, and ocx account use.
• docs-site/src/content/docs/ja/reference/configuration/providers.md#L19-L20: Add the equivalent Japanese wording.
• docs-site/src/content/docs/ko/reference/configuration/providers.md#L19-L20: Add the equivalent Korean wording.

As per path instructions, “exact account-qualified routes retain their selected account and do not silently fall through to other credentials; users can manage the same account pools with ocx account list/current/use.”

🤖 Prompt for 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.

In `@docs-site/src/content/docs/reference/configuration/providers.md` around lines
20 - 21, Update the provider configuration documentation to state that exact
account-qualified routes retain their selected account and never silently fall
back to other credentials, while distinguishing Pool routing from Direct
routing. Add the account-pool management commands ocx account list, ocx account
current, and ocx account use to
docs-site/src/content/docs/reference/configuration/providers.md lines 20-21, and
add equivalent wording in
docs-site/src/content/docs/ja/reference/configuration/providers.md lines 19-20
and docs-site/src/content/docs/ko/reference/configuration/providers.md lines
19-20.

Source: Path instructions

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

Outside diff comments:
In `@docs-site/src/content/docs/reference/configuration/providers.md`:
- Around line 20-21: Update the provider configuration documentation to state
that exact account-qualified routes retain their selected account and never
silently fall back to other credentials, while distinguishing Pool routing from
Direct routing. Add the account-pool management commands ocx account list, ocx
account current, and ocx account use to
docs-site/src/content/docs/reference/configuration/providers.md lines 20-21, and
add equivalent wording in
docs-site/src/content/docs/ja/reference/configuration/providers.md lines 19-20
and docs-site/src/content/docs/ko/reference/configuration/providers.md lines
19-20.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 60b52466-2be5-4b6d-98bb-a1e08cdf8dd5

📥 Commits

Reviewing files that changed from the base of the PR and between e947442 and a8fb1ce.

📒 Files selected for processing (23)

• docs-site/src/content/docs/ja/reference/configuration/providers.md
• docs-site/src/content/docs/ja/reference/management-api.md
• docs-site/src/content/docs/ko/reference/configuration/providers.md
• docs-site/src/content/docs/ko/reference/management-api.md
• docs-site/src/content/docs/reference/configuration/providers.md
• docs-site/src/content/docs/reference/configuration/routing.md
• docs-site/src/content/docs/reference/management-api.md
• docs-site/src/content/docs/ru/reference/configuration/providers.md
• docs-site/src/content/docs/ru/reference/management-api.md
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
• docs-site/src/content/docs/zh-cn/reference/management-api.md
• gui/src/styles.css
• src/cli/account-auth.ts
• src/codex/account-namespaces.ts
• src/config.ts
• src/routing/profile-namespace.ts
• src/routing/profile.ts
• src/server/management-api.ts
• src/types.ts
• tests/cli-account.test.ts
• tests/codex-account-namespaces.test.ts
• tests/config.test.ts
• tests/settings-stream-mode.test.ts

💤 Files with no reviewable changes (1)

• gui/src/styles.css

[chrisae9]

@coderabbitai review

[coderabbitai]

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs-site/src/content/docs/reference/configuration/providers.md (1)

20-21: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Document the catalog recovery action in all locales.

The codexAccountPickerEnabled rows describe persisted picker changes but omit the recovery action when catalog refresh remains pending. Add a localized instruction or link to the existing guidance: run ocx sync.

• docs-site/src/content/docs/reference/configuration/providers.md:20-21
• docs-site/src/content/docs/ja/reference/configuration/providers.md:19-20
• docs-site/src/content/docs/ko/reference/configuration/providers.md:19-20
• docs-site/src/content/docs/ru/reference/configuration/providers.md:20-21
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md:19-20

🤖 Prompt for 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.

In `@docs-site/src/content/docs/reference/configuration/providers.md` around lines
20 - 21, Update the codexAccountPickerEnabled documentation to include a
localized recovery instruction or link to the existing guidance to run “ocx
sync” when catalog refresh remains pending. Apply this change in
docs-site/src/content/docs/reference/configuration/providers.md:20-21,
docs-site/src/content/docs/ja/reference/configuration/providers.md:19-20,
docs-site/src/content/docs/ko/reference/configuration/providers.md:19-20,
docs-site/src/content/docs/ru/reference/configuration/providers.md:20-21, and
docs-site/src/content/docs/zh-cn/reference/configuration/providers.md:19-20,
translating the instruction appropriately for each locale.

Source: Path instructions

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

Outside diff comments:
In `@docs-site/src/content/docs/reference/configuration/providers.md`:
- Around line 20-21: Update the codexAccountPickerEnabled documentation to
include a localized recovery instruction or link to the existing guidance to run
“ocx sync” when catalog refresh remains pending. Apply this change in
docs-site/src/content/docs/reference/configuration/providers.md:20-21,
docs-site/src/content/docs/ja/reference/configuration/providers.md:19-20,
docs-site/src/content/docs/ko/reference/configuration/providers.md:19-20,
docs-site/src/content/docs/ru/reference/configuration/providers.md:20-21, and
docs-site/src/content/docs/zh-cn/reference/configuration/providers.md:19-20,
translating the instruction appropriately for each locale.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8f1d057d-b60d-4f3d-a05e-e66c4a474897

📥 Commits

Reviewing files that changed from the base of the PR and between a8fb1ce and 1f98cb1.

📒 Files selected for processing (5)

• docs-site/src/content/docs/ja/reference/configuration/providers.md
• docs-site/src/content/docs/ko/reference/configuration/providers.md
• docs-site/src/content/docs/reference/configuration/providers.md
• docs-site/src/content/docs/ru/reference/configuration/providers.md
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md

[chrisae9]

@coderabbitai review

[coderabbitai]

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