[tmfahey]

Summary

• A missing-scope 403 told every stored session to sign in again. It also passed along the API's "reach out to developer@gusto.com" text, which a CLI user can't act on. Signing in again doesn't help when the scope isn't part of the CLI's OAuth grant.
• The insufficient_scope error now lists the scopes the API named in missing_scopes and the error shape in category. For a stored session, the message says which scopes signing in again can add. For any it can't add, it points to gusto feedback.
• A scope counts as grantable when it's in REQUIRED_SCOPES or the new RETAINED_SCOPES. Tokens from GUSTO_ACCESS_TOKEN or --token-stdin keep the replace-the-token advice.
• details now carries only unrelated errors from the same response. Every other 4xx and 5xx still gets the full body.
• The second commit fixes an unrelated upgrade test that broke on the newer Ubuntu runner image. There, /bin/echo is a multi-call coreutils binary that won't run under the staging file's name, so the test now copies Bun's own binary.

Not in this PR:

• MCP-backed commands (timesheet, feedback) still suggest re-login on a scope error.
• A scope error nested inside another error entry could still carry the API's text in details. I haven't seen the API send that shape.
• RFC 6750 scope lists come back sorted, while Gusto's own entries keep the API's order.

Linked issue

AINT-1118

Test plan

• bun run test:all passes locally
• Manual run of touched commands works against sandbox
• --agent and --human output verified where touched

Against sandbox I ran the grantable, outside-the-grant, env-token, stdin-token and 404 cases, in JSON and human output. I also ran the built binary against a local stub through api request and payroll list for the edge cases: no scope named, mixed scopes, RFC scope lists, empty scope names, and plain 403/422/500. None of the output contained developer@gusto.com.

DCO

• Every commit is signed off (git commit -s) per the DCO

[cbento-gusto]

This change gives a CLI user a scope error they can act on. The grantable and ungrantable split is clear, the API's partner-facing text no longer leaks through, and the tests cover the mixed, plural, unnamed, and explicit-token cases well.

Checked and clear:

• Callers that read error.details (clarifyVersionConflict, clarifyEmptyTimesheetSync) gate on ExitCode.ApiClient, so the trimmed details on an Auth exit does not reach them.
• Production ApiClients always carry auth, so the new case undefined grouping only changes test-only paths.
• scopesFromBody dedupes Gusto entries, drops empty names, and falls back to the RFC 6750 scope in the same order scopeErrorCategory uses.
• nonScopeDetails keeps unrelated errors, and human mode still prints them as reason:.

Blockers: None.

🤖 for @cbento-gusto