phax

    When something goes wrong

    Troubleshooting

    • claude not found. Install Claude Code and make sure claude is on your $PATH; phax agent probe lists what phax finds.
    • A gate keeps failing. The run pauses once the fix attempts are spent. Read the attempt logs, ~/.phax/runs/<namespace>.<name>/phase-NN/checks-attempt-NN.log, fix the cause (or raise agent.maxFixAttempts), then phax resume <run>, which runs the gate again first. To start the phase over instead, phax reset-phase <run> before resuming.
    • Lock conflict. Another phax is working on that run, or one died; phax unlock <run> clears a stale lock.
    • The handoff is missing. The phase ended in handoff_failed: phax enter <run> takes you back into its session.
    • A rate or usage limit. The run stopped at exit 8 and keeps its place: phax resume <run> when the limit resets.
    • A plan is stale right after its approval. A plan that lists docs/plans/approvals.json among its files reads its own approval as a change. Leave the ledger out of its files for now; the fix is planned.

    Something else? phax report <run> opens a GitHub issue with the run's telemetry.