[nicknisi]

Stacked on #268. Review this after it; the diff here is only what was added on top.

What changes

• Retries. A failed exchange is retried on a network error (including a connection that drops while the response is read) or a 5xx, three attempts in total (0.5 s, then 1 s). A 4xx is final. A request sent with a WIF token is re-sent once after a 401, with a freshly exchanged token.
• Errors that say what to fix. Every OAuth error from the exchange now has a hint, including unauthorized_client: check that the client has an enabled trust, that workload identity federation is on for the team, and that the client targets a non-production environment.
• Docs. The READMEs cover retries, unauthorized_client, and WORKOS_ENVIRONMENT_ID being optional (it must match the client's bound environment when set).
• A WIF failure during a request is reported as itself, not as "Failed to connect to WorkOS API".

The branch also merges main (release 0.24.0), so the release files show in the diff.

Checked

• A real GitHub Actions run with this branch's CLI against a local API built from that server stack (https://github.com/nicknisi/wif-test/actions/runs/43271835510): workos api listed organizations and created one using only the job's OIDC token. It passed again with this branch at aeaa5ad against the current server tip: https://github.com/nicknisi/wif-test/actions/runs/43374371447.
• Typecheck, lint and format pass.
• 209 tests in the WIF-related specs pass, including new ones for retries and each error hint, and one asserting neither token appears in any log or error. The whole suite (3,576 tests) passes.

Not checked

• A deployed WorkOS token endpoint. The server side is in review as a stack starting at workos/workos#79789.
• bun run build.
• The wording still says "M2M application" and "trust rule", as feat: authenticate in GitHub Actions with workload identity federation #268 does. The server side is moving to "machine client" and "trust".

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; both previous findings are fixed and no new actionable issue remains.

Summary

Adds bounded WIF token-exchange retries, one retry after an API 401, and clearer OAuth error hints.

• WIF token exchanges retry temporary failures up to three times.
• WIF requests refresh their token and resend once after a 401.
• WIF OAuth errors and setup guides point to the settings to check.
• The package and release metadata now show version 0.24.0.

_{Reviews (2) · Last reviewed commit: "fix(wif): retry a dropped response body ..." · Reviewed by Greptile}