[WRONG BRANCH] fix(doctor): tolerate malformed $CODEX_HOME/agents path

[luvs01]

Motivation

• ocx doctor added a scan of $CODEX_HOME/agents/*.toml that could throw when the agents path exists but is not a readable directory, causing the diagnostic command to abort instead of degrading to a warning.

Description

• Change scanCodexAgentRolesWithTomlModelFallback to accept an optional onListError callback, catch enumeration errors, invoke the callback with the cause, and return an empty list on failure instead of throwing.
• Update the doctor UI (runDoctor) to call the scanner with an error callback and emit a [WARN] unable to scan $CODEX_HOME/agents/*.toml: ... message when scanning fails.
• Add a regression test in tests/subagent-model-fallback.test.ts that creates a malformed agents path (a regular file) and asserts the scanner returns [] and reports an Error to the callback.
• Keep existing behavior unchanged when the agents directory is valid and readable.

Testing

• Ran the focused tests in tests/subagent-model-fallback.test.ts via the repository test harness and the new test passed (52 tests in that file passed).
• Ran type checking with bun run typecheck and it passed.
• Ran the full test suite with bun run test in this environment; the focused regression passed but the full suite exposed unrelated environment-dependent failures in other tests (these failures are pre-existing and not caused by this change).

---

Codex Task

Summary by CodeRabbit

• Bug Fixes
  • ocx doctor now warns when Codex agent scanning fails, rather than incorrectly reporting no agent roles.
  • Agent role scanning now handles invalid or inaccessible agent paths gracefully and reports the underlying error.
  • Successful scans continue to display existing empty or non-empty results as expected.

[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: 72fa6e68-bd8e-464f-bd2f-284e8483f467

📥 Commits

Reviewing files that changed from the base of the PR and between 6d881db and c84721c.

📒 Files selected for processing (3)

• src/cli/doctor.ts
• src/codex/subagent-model-fallback.ts
• tests/subagent-model-fallback.test.ts

---

📝 Walkthrough

Walkthrough

The Codex agent-role scanner now reports directory-listing errors through an optional callback. ocx doctor displays scan failures as warnings. Tests cover an agents path that is a file.

Changes

Codex agent scan handling

Layer / File(s)	Summary
Scan error reporting and validation src/codex/subagent-model-fallback.ts, src/cli/doctor.ts, tests/subagent-model-fallback.test.ts	The scanner reports listing errors through an optional callback and returns an empty list. ocx doctor prints a warning for scan failures. Tests cover a non-directory agents path.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: 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 identifies the doctor fix and the malformed $CODEX_HOME/agents path that the pull request handles.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-crash-in-doctor-for-malformed-agents-path

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

⏳ DRAFT

• wrong target branch (main); retarget to dev.

What to do

• Retarget this PR to dev — all contributions go to dev.

Its title has been prefixed with [WRONG BRANCH].
This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.