Reduce exit codes to invocation, transport and assertion

[korya]

Problem

A CI job reading the exit code could not tell an unreachable service from one that answered wrongly, nor a forgotten flag from a network failure. The five codes had accidental boundaries — assigned by whichever internal layer failed, not by what kind of failure it was: the same typo exited 103 (with a 40-line usage dump) from the command line but 71 (one clean line) from the environment; a run with zero assertions reported the transport-failure code (#25); and the distinction the docs promise — "a broken service vs a broken invocation" — was exactly the one the codes didn't make.

Solution

Three non-zero codes, each answering "whose fault?": 71 — the invocation was rejected, no request attempted; 92 — no usable response arrived; 93 — a response arrived and an assertion failed.

Before → After:

Condition	Before	After
bad flag value / combination	71	71
bad value via environment	71	71
type typo, unknown flag, arg count	103 + usage dump	71, one line
unbuildable request (-X, URL)	91	71
zero assertions (#25)	93	71
unreachable / TLS / timeout / redirect bound	93	92
assertion failed	93	93

Failure category is decided where it's understood — inside the attempt, where transport and assertion failures part ways — and carried to the exit in a typed error that survives the retry wrapper via %w/errors.As, so retry exhaustion inherits the last attempt's category. An untagged error defaults to the transport bucket: wrong by at most one category, never misreported as the caller's mistake. Cobra's own error printing is silenced so every failure exits through the same one-line path.

This is a deliberate breaking change, pre-1.0: 91/103 are gone and transport failures leave 93. Scripts testing non-zero are unaffected; the README carries a migration note.

Other Changes

• TestE2EExitCodes now covers all three categories plus both invocation channels — including the CLI-vs-environment typo pair that used to exit differently, and the zero-assertion case flipped out of the known-issues file per its protocol (closes Zero assertions is reported as "Cannot perform request" with exit 93 #25).
• The help-sync test enumerates the new set and asserts the retired codes (2, 91, 103) are no longer advertised.
• Every exit-code assertion in the e2e suites was re-triaged individually (transport vs assertion), not batch-renamed.

Related:

• Zero assertions is reported as "Cannot perform request" with exit 93 #25

🤖 Generated with Claude Code

https://claude.ai/code/session_01TiEcuZhTyL5XbrCwyiHau8