fix(codex): preflight sync injection before catalog writes

[Ingwannu]

Summary

• Run the real Codex injection transformation and coordination-eligibility checks in a non-writing preflight before provider discovery or catalog/cache replacement.
• Stop deterministic injection refusals before they can degrade a previously usable catalog, and send the concrete refusal to stderr instead of hiding it behind the generic CLI summary.
• Keep the normal injector call as the final write authority, and document why the preflight is an early guard rather than a reusable authorization result.
• Add regression coverage for refusal ordering, stderr fidelity, byte-identical catalog/cache preservation, and artifact-free successful preflight.

Closes #1453

Exact-head verification

• Base: dev@20c513198e4ef943fa990decad21fff92f3cfad4
• Head: 9c9ca092a19b8e21c8d4b8aebaa91c10f1b4a3d2
• bun test tests/codex-sync-api.test.ts tests/cli-restore-back.test.ts — 16 passed
• bun run typecheck — passed
• bun run privacy:scan — passed
• git diff --check — passed
• GitHub CI — gates, API/storage, all keyring and packaging jobs, macOS, and Linux shards 1/2/3 passed on this exact head. Linux shard 4 was cancelled at the 15-minute job limit, so the aggregate ci check is red.

The same patch on the immediately preceding dev@87e3ff9f6 base also built all 221 documentation pages. Its local full suite reached 10,930 passed and 11 skipped, with no assertion failure in the changed sync/injection path.

The exact-head shard-4 log failed before the affected sync/injection tests: Bun 1.3.14 raised EEXIST: file already exists, epoll_ctl while loading tests/catalog-oauth-observation.test.ts, followed by Cannot call beforeEach() after the test run has completed. The runner then stopped producing test output after starting an unrelated Claude Desktop config-path test until the 15-minute limit cancelled it and Actions terminated an orphan bun process. The preceding code-equivalent runs hit the same Bun loader failure and dangling-process family on other Linux shards. No product assertion failed in the changed path, and no product code was changed to accommodate the runner defect; the PR remains draft pending independent review and a green required aggregate.

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

• Bug Fixes
  • ocx sync now validates managed Codex configuration before making changes.
  • Failed validation reports a specific error and preserves existing catalog, cache, configuration, and journal data.
  • ocx restore back applies the same safety checks before re-enabling routing.
  • Synchronization now clearly separates success messages from errors, improving command-line feedback.
• Tests
  • Added coverage confirming failed validation leaves existing files and synchronization artifacts unchanged.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d2158713-459f-4578-9cf4-9123debad4ca

📥 Commits

Reviewing files that changed from the base of the PR and between 20c5131 and 9c9ca09.

📒 Files selected for processing (6)

• docs-site/src/content/docs/reference/cli/lifecycle.md
• src/codex/inject.ts
• src/codex/sync.ts
• structure/02_config-and-codex-home.md
• tests/cli-restore-back.test.ts
• tests/codex-sync-api.test.ts

---

📝 Walkthrough

Walkthrough

ocx sync and ocx restore back now validate managed Codex configuration without writing before provider discovery or catalog/cache replacement. Failures report concrete errors on stderr and preserve existing artifacts. The injector still revalidates before final writes.

Changes

Codex preflight and synchronization

Layer / File(s)	Summary
Injector validation-only path src/codex/inject.ts	Adds validateOnly support. Validation performs configuration transformation and eligibility checks without changing files or removing journal entries.
Sync and restore-back preflight src/codex/sync.ts, docs-site/src/content/docs/reference/cli/lifecycle.md, structure/02_config-and-codex-home.md	Runs preflight before catalog gathering and reports failures on stderr. Successful and failed injection messages use the appropriate output stream. Documentation describes preflight and final write-boundary revalidation.
Preflight behavior coverage tests/codex-sync-api.test.ts, tests/cli-restore-back.test.ts	Tests refusal, no-write validation, prevented catalog refresh, unchanged catalog/cache files, and repeated injection during catalog-refresh fallback.

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

Possibly related PRs

• lidge-jun/opencodex#333: Modifies Codex injection and sync behavior for externally managed providers.
• lidge-jun/opencodex#1097: Adds Codex injection integration coverage for externally managed provider preservation.
• lidge-jun/opencodex#1202: Refines Codex injection validation and failure handling.

Suggested reviewers: lidge-jun, wibias, vsnote

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Injector
  participant CatalogCache
  participant CodexHome
  CLI->>Injector: Run validation-only injection
  Injector-->>CLI: Return success or concrete failure
  alt Validation succeeds
    CLI->>CatalogCache: Refresh catalog and cache
    CLI->>Injector: Run final injection
    Injector->>CodexHome: Write Codex configuration artifacts
  else Validation fails
    CLI-->>CodexHome: Preserve existing catalog and cache
  end

Loading

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-1453-sync-transaction

---

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

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

Exact-head CI review complete for d6dad871d9b997673f98796216b756d64a935c09.

The changed sync/injection path remains green locally (16 focused tests, typecheck, privacy scan, diff check). GitHub gates, service checks, macOS, packaging, keyring, API/storage jobs, and Linux shards 1/2 passed.

The remaining red jobs are repeatable Bun 1.3.14/runner failures, not product assertions:

• Linux shard 3 failed on both the initial attempt and its rerun with EEXIST: file already exists, epoll_ctl while loading unrelated test files. The later Cannot call afterEach()/describe() after the test run has completed errors are secondary fallout.
• Rerun shard 4 hit the same Bun loader error in unrelated memory/catalog tests, then the known tests/cli-models.test.ts dangling-process path stalled and the run was canceled.

I am not changing the product patch to accommodate this runtime failure and will not churn a third identical rerun. The PR remains draft for independent review/integration; no merge was performed.