refactor(cli): normalize process exit through dispatchCommand

[Wibias]

Summary

Normalize process exit handling so dispatch owns every exit code.

• src/cli/dispatch.ts: CommandRunner becomes (deps) => Promise<number>. Every runner returns an exit code instead of calling process.exit or setting process.exitCode directly. dispatchCommand aggregates and returns the final code (unknown command → 1, help forms → 0).
• src/cli/index.ts: the single process.exit(await dispatchCommand(...)) is now the only exit site in the CLI entry.
• restore, route, integration, claude, ready, and health runners preserve their per-branch exit codes as return values.

Behavior is unchanged: exit code values and message text are identical; only the mechanism (return vs process.exit) changed.

Verification

• bun run typecheck — exit 0.
• ocx --version — exit 0.
• ocx help nosuch — exit 1, Unknown command: nosuch.
• ocx ready --timeout 5 — exit 64.
• ocx sync --help — exit 0.
• CLI-focused suite — 157 pass; the only failures are the known pre-existing cli-restore-back (2) and POST /api/sync (2) cases.

No GUI changes; no screenshot required.

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 notes (stacked PR): stacks on #1451 (codex/cli-dispatch). Does not target dev. Diff is only the exit normalization (0bb19e1e..300c9cda): 3 files, +90/−66. Merge only after #1444, #1446, #1451 land.

Summary by CodeRabbit

• Bug Fixes

  • Improved CLI exit-code handling so command results are reported consistently.
  • Preserved specific failure codes for readiness checks and other command errors.
  • Unknown commands now return a failure status instead of exiting unpredictably.

• Tests

  • Updated CLI and readiness checks to validate returned exit codes and process termination behavior.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d2ee747d-0f34-4ab7-a85d-e3ee1796c399

📥 Commits

Reviewing files that changed from the base of the PR and between 2e134fa and a43ec84.

📒 Files selected for processing (3)

• src/cli/dispatch.ts
• src/cli/index.ts
• tests/cli-ready.test.ts

---

📝 Walkthrough

Walkthrough

The CLI dispatch system now returns numeric exit codes from command runners through dispatchCommand to the top-level process.exit call. Readiness, health, integration, restore, update, tray, and other command paths preserve explicit status results.

Changes

CLI exit-code propagation

Layer / File(s)	Summary
Command runner result propagation src/cli/dispatch.ts	Command runners return explicit success and failure codes. Existing diagnostics, cleanup, side effects, and delegated results remain intact.
Dispatch and process exit contract src/cli/dispatch.ts, src/cli/index.ts	dispatchCommand returns Promise<number>, including 0 for help and 1 for unknown commands. The CLI passes the returned code to process.exit.
Exit-code behavior validation tests/cli-ready.test.ts	Tests verify the Promise<number> contract, dispatch result propagation, and readiness returning 64 when required arguments are missing.

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

Possibly related PRs

• lidge-jun/opencodex#569: Both changes modify handleReady, dispatchCommand, and readiness exit-code propagation.
• lidge-jun/opencodex#1444: Both changes modify CLI dispatch and readiness handling in src/cli/index.ts.
• lidge-jun/opencodex#1451: This change extends the dispatch and dependency contracts by propagating numeric runner results.

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 0.00% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: centralizing CLI process exit handling in dispatchCommand.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cli-exit

---

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

[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 `@src/cli/dispatch.ts`:
- Around line 374-375: Update the ready dispatch flow so normal results
propagate through the single top-level exit: change CliDispatchDeps.handleReady
to return Promise<number>, have index.ts handleReady return runReady(args)
instead of exiting, and preserve the missing-arguments 64 result. Add a focused
regression test alongside the existing ready dispatch tests covering a valid
ready command and asserting its result is returned.

🪄 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: e7552f0b-afe6-42ea-8f30-dee98ae10f71

📥 Commits

Reviewing files that changed from the base of the PR and between 5d8c4fe and 2e134fa.

📒 Files selected for processing (3)

• src/cli/dispatch.ts
• src/cli/index.ts
• tests/cli-ready.test.ts