fix(runner): stop reading a spend-limit refusal as retryable

[Jason Allen (JAllen2022)]

Overview of Changes

Today the four runner handlers rebuild every platform failure with exit code 4, documented as "Apex unreachable" - so an agent driving the CLI reads a spend-limit refusal as transient and retries forever. 402 now gets its own documented exit code, 7 payment, assigned in describeRequestError next to the existing 401 → 3 mapping, and the handlers keep an exit code the platform layer already set instead of overwriting it with 4.

The server's own reason ("You have reached your monthly limit of …") already travels in the error body and still does.

Also: the same overwrite was clobbering the 401 → 3 mapping on these four verbs, a 401 on runner run exited 4. It exits 3 now.

Testing

bun run typecheck
bun run lint
bun run format:check
bun run knip
bun run test
bun run build

All green locally. New cases: describeErrors.test.ts covers the 402 mapping, evaluateSnippet.spendLimit.test.ts and importPackage.test.ts prove the exit code survives the handlers' rebuild.

Checklist

• Changes follow the code style of this project
• Self-review completed
• Tests added/updated (or not applicable)
• No breaking changes (or described below)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: ed99275b-93e7-44eb-9198-b58b11991b55

📥 Commits

Reviewing files that changed from the base of the PR and between 177a9eb and 0eec92a.

📒 Files selected for processing (12)

• docs/exit-codes.md
• src/core/messages/auth.ts
• src/domains/interactiveRunner/evaluateSnippet.spendLimit.test.ts
• src/domains/interactiveRunner/evaluateSnippet.ts
• src/domains/interactiveRunner/importPackage.test.ts
• src/domains/interactiveRunner/importPackage.ts
• src/domains/interactiveRunner/launchAndRemember.ts
• src/domains/interactiveRunner/sendRunFlowRequest.ts
• src/shell/exit.test.ts
• src/shell/exit.ts
• src/shell/platform/describeErrors.test.ts
• src/shell/platform/describeErrors.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

Walkthrough

The CLI adds public exit code 7 for payment-related HTTP 402 responses. Request error handling returns a billing-specific message, parsed error body, and payment exit code. Interactive runner operations preserve API-provided exit codes and fall back to the network exit code when absent. Tests cover request errors, spend-limit refusals, and package import failures.

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

Merge Risk: ⚪ Minimal · up to 0eec9

The change makes spend-limit and authentication failures return their intended exit codes instead of being treated as transient runner failures. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Runner
  participant QA Wolf API
  participant describeRequestError
  participant CLI
  Runner->>QA Wolf API: Send request
  QA Wolf API-->>Runner: HTTP 402 payment refusal
  Runner->>describeRequestError: Describe response
  describeRequestError-->>Runner: Payment message and exit code 7
  Runner-->>CLI: Return failure with exit code 7

Loading

Suggested reviewers: theonly1me

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows the Conventional Commits format, uses an allowed type and scope, uses imperative mood, stays under 72 characters, and clearly describes the runner spend-limit handling change.
Description check	✅ Passed	The description includes the required Overview of Changes, Testing, and Checklist sections. It explains the 402 and 401 exit-code changes, lists concrete verification commands, and confirms the checkl…
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.

Full details: Description check

Explanation

The description includes the required Overview of Changes, Testing, and Checklist sections. It explains the 402 and 401 exit-code changes, lists concrete verification commands, and confirms the checklist items.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jallen/nova-1689-refuse-a-run-on-a-live-public-runner-once-the-organization

---

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