fix(cli): say what a 404 could not find, and which runner

[Goran Gajic (gorangajic)]

Every HTTP 404 from the QA Wolf API came back as "could not find X for that environment. Check the --env value" — even when the request had nothing to do with an environment. The two common causes are a runner that is no longer running and a run id from qawolf runner run passed to qawolf run get. A customer team spent time chasing an environment because of the wording.

Relates to WIZ-12140. Builds on WIZ-12139, which makes the platform name the missing runner in its response; this change prefers that reason when it arrives and stands on its own wording when it does not.

Overview of Changes

A 404 now answers with what the request named. A runner-targeting command says the runner is not running, names it, and gives the launch command. qawolf run get says there is no such run on this team, and that ids printed by qawolf runner run belong to that runner — read them with qawolf runner events run-status. Only a request genuinely scoped to an environment still points at --env.

Runner failures also say which of --runner, QAWOLF_RUNNER_ID or this directory's stored default chose the id. None of that reached the error before, so a reader of an agent transcript could not tell which runner was meant or why.

These failures exit 8 instead of 4. Exit 4 reads as "retry", and a terminated runner never comes back, so callers burned their retry budget on an id that could not work. The exit-code doc and the agent skill reference are updated to match.

Testing

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

New unit tests cover each routed 404, including the case where the server still answers a bare "Not found", and the runner-id source on each of the four ways a runner is chosen.

Checklist

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

A caller branching on exit 4 for a missing runner now sees 8. That is the point of the change, and the published exit-code contract is updated with it.

🤖 Generated with Claude Code

[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: dac09ba0-a2ba-44e3-9816-fecd76688295

📥 Commits

Reviewing files that changed from the base of the PR and between 2b538b3 and c9d61b9.

📒 Files selected for processing (14)

• .changeset/not-found-names-what-is-missing.md
• docs/exit-codes.md
• skills/qawolf-cli/references/run-results.md
• src/commands/qawolfCliRunResults.template.md
• src/core/messages/authErrors.ts
• src/runnerSdk/errorDetail.test.ts
• src/runnerSdk/lifecycleVerbs.ts
• src/runnerSdk/runVerbs.ts
• src/runnerSdk/toSdkFailure.ts
• src/runnerSdk/toSdkResult.ts
• src/runnerSdk/types.ts
• src/shell/platform/describeErrors.test.ts
• src/shell/platform/describeNotFound.test.ts
• src/shell/platform/describeNotFound.ts

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

---

Walkthrough

The CLI now classifies HTTP 404 responses by resource and returns exit code 8 for missing runners, runs, environments, and other named resources. Runner ID resolution carries source metadata through interactive runner and SDK flows. Runner request failures use a shared mapper that distinguishes retryable network failures from missing runners. SDK failures preserve optional detail, and documentation covers the new messages, commands, exit codes, and runner ID handling.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Suggested reviewers: chajac, theonly1me

Merge Risk: ⚪ Minimal · up to c9d61

The updated CLI and SDK diagnostics provide resource-specific 404 guidance without an identified compatibility or runtime regression. The change is ready to merge.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits with the valid fix(cli) prefix, uses imperative mood, stays under 72 characters, and specifically describes the 404 and runner messaging change.
Description check	✅ Passed	The description includes the required Overview of Changes, Testing, and Checklist sections. It explains the behavior change, testing commands, updated tests, and intentional exit-code contract change.
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 unit tests (beta)

• Commit to this branch
• Create a new PR

---

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