Troubleshooting

Run /ca:doctor in Claude Code or $ca-doctor in Codex when codeArbiter is not behaving as expected. The command is a read-only health check over interpreter, payload, cache, activation, and live-fire enforcement. Claude also checks statusline wiring. Codex instead requires its hook set to be trusted through /hooks; start a fresh thread after approving a changed set.

For a defect in your application, use Investigate and fix a defect. Doctor diagnoses codeArbiter installation and enforcement; it is not an application root-cause analysis.

Run the Check

Open the project where the problem appears and run the host-native command:

/ca:doctor
$ca-doctor

Doctor prints a result for each check and exits 0 if all pass, non-zero otherwise. Fix failures in the order reported: later failures are often downstream of the first.

What Doctor Checks

Interpreter Health

Doctor confirms that the interpreter selected by the active adapter resolves. Claude Code carries its documented python3/python fallback shape. Codex uses OS-specific hook handlers and reports a loud failure if the selected interpreter is absent. Pi keeps its TypeScript wrappers active and blocks mutating calls with an interpreter breadcrumb until the Python bridge is healthy. In every case, a failed interpreter row means governance is not healthy.

To fix: add Python 3 to PATH. Verify outside Claude Code with python3 --version or python --version. At least one must succeed.

Payload Integrity

Doctor checks that the plugin payload is internally consistent and all expected files are present.

To fix: if integrity fails, reinstall or update the plugin.

Stale-Cache Detection

Cached payload data and settings paths can lag behind a plugin update. Doctor detects outdated entries and reports which ones are stale.

To fix: run /ca:doctor after every plugin update and follow the remediation it prints.

Repo Activation

Doctor reads .codearbiter/CONTEXT.md and checks three things:

1. The file exists at the repo root.
2. The leading YAML frontmatter opens with --- on line 1 and closes with a second ---.
3. The closed block contains arbiter: enabled.

A repo without the file is dormant: the gates do not fire and no orchestrator persona is injected. An unclosed frontmatter block surfaces as a malformed-state error rather than silently treating the repo as disabled.

To fix: confirm the first three lines of .codearbiter/CONTEXT.md read:

---
arbiter: enabled
---

If the file is absent, run /ca:init to scaffold it.

Use the same three-state classification when reading doctor output.

Live-Fire Hook Probe

Doctor runs a hook invocation to confirm a hook binary actually executes end-to-end, not just that an interpreter binary is on PATH. A passing interpreter check alongside a failing probe points to a registration or permissions problem with the hook files themselves.

To fix: reinstall the plugin to repair hook registration.

Statusline Wiring

Claude Code only. Codex has no statusline surface; do not treat that absence as a failed check.

Doctor checks that the statusLine.command entry in ~/.claude/settings.json points to the current version of statusline.py. The stored path is absolute and version-pinned, so a plugin update can leave it pointing at the previous version. The SessionStart hook repairs this automatically each session, but doctor will report a stale wire before the first post-update session runs.

To fix: run /ca:statusline to re-wire explicitly, or open a new Claude Code session to trigger the automatic repair.

Typed specifications and plans

Doctor inspects the installation-pinned artifact capability and, when HTML artifacts exist, a bounded artifact catalog. Preserve its exact code and package identity before remediation.

Diagnostic	Meaning	Next action
Diagnostic CAPABILITY_MISSING, INVALID_INSTALLATION, PACKAGE_INTEGRITY	Meaning Missing or mismatched installed payload	Next action Repair the qualified installed package; do not select a repository binary
Diagnostic UNVERIFIED_PLATFORM, UNSUPPORTED_PLATFORM	Meaning The selected platform/storage cell is not qualified	Next action Check supported environments; do not override the platform identity
Diagnostic DRAFT_BINDING	Meaning The requested operation needs a different specification binding	Next action Inspect the selected identity and use native binding maintenance; draft status does not block ordinary authorized work
Diagnostic AUTHORITY_UNVERIFIED	Meaning An explicit attestation operation lacks required evidence	Next action Keep that proof claim unverified and inspect its evidence boundary; continue independent authorized work
Diagnostic REVISION_CONFLICT, STALE_CURSOR	Meaning The prior read is stale	Next action Reread and reconsider; never force the old write
Diagnostic LOCK_BUSY	Meaning Another bounded writer owns the lock	Next action Preserve the conflict; do not delete lock files
Diagnostic RECOVERY_REQUIRED, COMMIT_OUTCOME_UNKNOWN	Meaning Transaction outcome needs reconciliation	Next action Keep the operation ID and inspect recovery before another write
Diagnostic UNSUPPORTED_VERSION, UNSUPPORTED_RENDERER	Meaning Format/renderer compatibility is not established	Next action Use a reviewed upgrade path, not raw HTML/JSON editing

Resume and recover gives the operator procedure. Existing Markdown work remains on its exact legacy path; a failure on HTML is not permission to switch formats. A valid HTML rendering or passing schema check does not authenticate an approval or prove tests were run.

Pi

ca-pi currently ships as a Feature Forge preview. Real use and feedback are welcome; reports from live repositories help it graduate.

On Pi, run /ca-doctor first. It is the diagnostic entry point, checking the active package path, canonical Pi CLI and package origin, command ownership, supported-version fingerprints, Python/core/bridge health, child fingerprint, final mutator wrappers, and the H-03 wrapper self-test.

Pi has several distinct silent-inactivity states that look alike but have different fixes:

Symptom	Likely cause	Fix
Symptom Nothing enforces, no orchestrator persona	Likely cause .codearbiter/CONTEXT.md missing or arbiter: enabled not set	Fix Run /ca-init, per Repo Activation above
Symptom Repo is enabled but still dormant	Likely cause Pi project trust not granted	Fix Grant Pi project trust for the repo, then start a fresh session
Symptom Trust was just granted but still dormant	Likely cause Trust was granted in the current session, not a fresh one	Fix Start a new session after granting trust: the parent registers repository-aware dispatch only on a fresh session that reports the trust decision
Symptom Mutating calls fail, or an interpreter breadcrumb appears	Likely cause Python 3 not on PATH	Fix Add Python 3 to PATH; ca-pi blocks mutating calls rather than failing silently when the interpreter is missing
Symptom /ca-<name> doesn’t do anything	Likely cause Wrong invocation syntax	Fix Pi uses /ca-<name> generated aliases with /skill:ca-<name> as the host-native fallback. This differs from Codex’s $ca-<name> convention
Symptom Doctor reports an unsupported version	Likely cause Pi CLI is not 1.1.0	Fix Upgrade to exact Pi 1.1.0, the only supported version in this release line; see Compatibility

Symptom Reference

Symptom	Likely cause	Suggested check
Symptom Claude gates don’t fire in any repo	Likely cause neither registered interpreter resolves	Suggested check Claude doctor’s interpreter section; verify python3 --version or python --version in a shell
Symptom Codex hook handler fails before evaluating a gate	Likely cause its OS-specific Python command does not resolve	Suggested check Codex doctor’s interpreter section and the exact handler error
Symptom Pi mutation is blocked with an interpreter breadcrumb	Likely cause Python bridge is unavailable	Suggested check /ca-doctor, then add Python 3 to PATH and start a fresh session
Symptom Gates don’t fire in one specific repo	Likely cause arbiter: enabled missing or frontmatter unclosed	Suggested check Doctor’s repo activation section; inspect .codearbiter/CONTEXT.md
Symptom Orchestrator persona not loading	Likely cause Repo not opted in; SessionStart finds no activation flag	Suggested check Doctor’s repo activation section; run /ca:init if the file is absent
Symptom Stale behavior after a plugin update	Likely cause Cached payload or statusline path is outdated	Suggested check Doctor’s stale-cache and statusline sections
Symptom Statusline shows wrong stage or stale data	Likely cause Statusline wired to previous statusline.py path	Suggested check Doctor’s statusline section; run /ca:statusline to re-wire
Symptom Malformed-state error on session start	Likely cause Frontmatter opens with --- but never closes	Suggested check Inspect the complete leading frontmatter for the missing closing ---; line 2 may legitimately contain a field
Symptom Merged PR but task still open on board	Likely cause Merged-but-not-flipped task	Suggested check Doctor runs a read-only reconciliation sweep and reports any such tasks

Related

• Enforcement and Security for the activation contract and dual-interpreter registration
• Hooks reference for per-hook behavior and fail postures that doctor inspects
• doctor command reference for the full command description