feat(codex): initialize account picker selectors

[chrisae9]

Summary

• add a pure selector initializer that runs only after an explicit account-picker opt-in and only when the selector map is absent or empty
• build the complete selector map before one assignment, preserving non-empty user maps by identity and insertion order
• reserve the canonical policy namespace and existing slash-qualified routing-profile prefixes during default and append allocation
• preserve exact-case account/profile prefix matching while keeping provider and reserved namespace collision checks normalized
• reject routing-profile/account-selector collisions before mutation, persistence, catalog convergence, or reference migration, without exposing private account identifiers
• document the selector namespace ownership contract in the internal SOT and provider references

This is the second slice requested in #1019, following #1096. It intentionally contains only selector initialization and collision foundations. Catalog convergence and management API/dashboard activation remain in later slices.

Part of #425.

Verification

• rebased onto dev@44dce33a
• focused feature suite: 189 passed across namespace, config, routing-profile, and management regression coverage
• final changed-area smoke: 35 passed
• bun run typecheck
• bun run privacy:scan
• bun test tests/repo-hygiene.test.ts
• node --test .github/scripts/pr-sponsored-surface.test.cjs
• git diff --check
• exact CI test shards (bun test --isolate tests --shard=N/4): 9,636 passed, 11 skipped, 0 failed
• independent design, security/privacy, and repository-conventions reviews found no remaining blockers

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

  • Improved automatic account-selector namespace generation to avoid conflicts with providers, combos, routing policies, and routing-profile aliases.
  • Added opt-in initialization for default account selectors while preserving existing configuration.

• Bug Fixes

  • Prevented invalid namespace collisions, including policy and case-insensitive variants.
  • Routing-profile aliases that conflict with account-selector namespaces are now rejected without changing configuration.

• Documentation

  • Updated provider configuration guidance across supported languages to clarify namespace collision rules.

[coderabbitai]

📝 Walkthrough

Walkthrough

Codex account selector validation now reserves the policy namespace and routing-profile alias prefixes. Default selector generation and initialization avoid these namespaces. Documentation and tests cover validation, preservation, atomic failure, and routing-profile management operations.

Changes

Namespace validation and allocation

Layer / File(s)	Summary
Routing namespace contracts and validation src/routing/profile-namespace.ts, src/routing/profile.ts, src/config.ts, tests/config.test.ts, docs-site/src/content/docs/.../configuration/providers.md	The policy namespace and routing-profile alias prefixes now participate in selector collision checks. Documentation and tests cover case-insensitive policy collisions.
Account selector generation and initialization src/codex/account-namespaces.ts, tests/codex-account-namespaces.test.ts, structure/03_catalog-and-subagents.md	Generated selectors avoid routing-profile prefixes and reserved namespaces. Initialization is opt-in, preserves existing non-empty maps, and fails atomically when allocation is unavailable.
Routing-profile management validation coverage tests/routing-profile-management-editor.test.ts	Create and update operations reject conflicting aliases before mutation, persistence, refresh, or reference migration. Tests verify that private account data and derived log labels are not exposed.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Config as OcxConfig
  participant Validator as Selector validation
  participant ProfileEditor as Routing-profile editor
  participant Storage as Persistence and catalog
  Config->>Validator: validate policy and routing-profile namespace collisions
  ProfileEditor->>Validator: validate profile alias
  Validator-->>ProfileEditor: accept or return invalid_profile
  ProfileEditor->>Storage: persist and refresh only after validation

Loading

Possibly related PRs

• lidge-jun/opencodex#1011: Introduces routing-profile namespace and POLICY_NAMESPACE handling extended by this change.
• lidge-jun/opencodex#1012: Adds related policy namespace collision validation in src/config.ts.
• lidge-jun/opencodex#1108: Adds related routing-profile management alias validation.

Suggested reviewers: ingwannu, wibias, lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: opt-in initialization of Codex account picker selectors.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
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.

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

[Wibias]

Looks good from my side overall. I didn’t find a code-level blocker.

Before I approve, please:

• rebase feat(codex): initialize account picker selectors #1152 onto the latest dev and rerun CI on the rebased head
• clear the CodeRabbit docstring coverage warning as well (66.67% vs 80%). It looks like a small documentation-only cleanup, so we might as well leave the PR fully clean.

If the rebased diff stays clean and CI passes, I’m good to approve.

[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]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[chrisae9]

Rebased and pushed. The current head is 440432b5 on dev 44dce33.

I also added JSDoc for the changed namespace helper and the new public policy namespace constant to clear the 66.67% coverage warning.

Local checks on this head are green: all four isolated Linux shards (9,636 pass / 11 skip), GUI tests (646 pass), focused selector tests (170 pass), typecheck, privacy scan, GUI build, release-script build, CLI smoke, hygiene, and sponsorship checks.

The PR is back Ready with the 4/4 checklist complete. GitHub's fork workflows still need maintainer approval before they can run:

• Cross-platform CI
• React Doctor

CodeRabbit is also re-reviewing the final head.

[coderabbitai]

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

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

Caution

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

⚠️ Outside diff range comments (1)

src/codex/account-namespaces.ts (1)

76-90: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Check runtime consumers for routing-profile defaults.

src/codex/account-namespaces.ts defines initializeDefaultCodexAccountNamespaces and appendDefaultCodexAccountNamespace in lines 115 and 139, and no tracked runtime call site currently passes them. Add the callers through the shared config flow or require the same routingProfiles shape there; otherwise generated selectors can still collide with routing-profile alias prefixes.

🤖 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 `@src/codex/account-namespaces.ts` around lines 76 - 90, Update the shared
configuration flow around initializeDefaultCodexAccountNamespaces and
appendDefaultCodexAccountNamespace so runtime callers provide routingProfiles,
or route initialization through the existing config path that does. Ensure
generated account selectors reserve routing-profile alias prefixes consistently
with occupiedNamespaces and defaultCodexAccountNamespaces, preventing
collisions.

🤖 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 `@src/codex/account-namespaces.ts`:
- Around line 76-90: Update the shared configuration flow around
initializeDefaultCodexAccountNamespaces and appendDefaultCodexAccountNamespace
so runtime callers provide routingProfiles, or route initialization through the
existing config path that does. Ensure generated account selectors reserve
routing-profile alias prefixes consistently with occupiedNamespaces and
defaultCodexAccountNamespaces, preventing collisions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 02f31d98-a569-46ce-bbb3-f5cabd50e1a8

📥 Commits

Reviewing files that changed from the base of the PR and between e73ed2b and 440432b.

📒 Files selected for processing (2)

• src/codex/account-namespaces.ts
• src/routing/profile-namespace.ts

[chrisae9]

Checked the outside-diff CodeRabbit note. No code change is needed in this slice: both selector helpers already require routingProfiles in their config shape and route allocation through occupiedNamespaces, which reserves slash-qualified routing-profile alias prefixes. There are intentionally no runtime call sites yet because this PR is the initialization/collision foundation requested by the split; wiring activation into the shared config/account lifecycle belongs to the later catalog/lifecycle slice. Adding those callers here would cross the agreed slice boundary. The docstring check is now clear at 83.33%.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@github-actions[bot] Acknowledged. The PR readiness gate is complete at 440432b55cbcd0b485ae8af84464ce565367cff7. The pull request is ready for review.

_{You are interacting with an AI system.}

[chrisae9]

One upstream CI job needs a maintainer rerun: test 1/4 hit Bun's internal EEXIST: file already exists, epoll_ctl between test files, followed by Cannot call afterEach() after the test run has completed. It was not an assertion failure. On the same 440432b5 head, tests/baseten-provider.test.ts passes 7/7 and the exact bun test --isolate tests --shard=1/4 command passes 2,321 / 5 skipped / 0 failed locally. All other CI jobs, including macOS and shards 2–4, passed. I attempted to rerun the failed jobs, but GitHub restricts that action to repository admins. Could a maintainer rerun the failed jobs? No branch code change is indicated, so the PR remains Ready.

[chrisae9]

@Wibias, the fork run you approved completed with the runner-only Bun failure described just above. Could you rerun the failed jobs when you have a moment? GitHub blocks contributor reruns; the exact shard is green locally on this head.

[chrisae9]

@Wibias, thank you—the failed-job rerun passed. All required checks are now green, GitHub reports the PR clean and mergeable, and there are no unresolved review threads.