[COR-345] auth-go refresh tier e2e: ctx-cancel + cross-process rotation race

[khaong]

Summary

Stacked on #12 (COR-343). Adds the two highest-value e2e scenarios still missing after that harness lands. Three new subprocess tests in tokenmanager/e2e_subprocess_test.go, plus one small additive extension to internal/testoauth.Server. No production code changes.

What lands

1. TestE2ESub_CtxCancelReleasesLocks — A CLI Ctrl+C'd mid-refresh is the most common real-world scenario the harness doesn't touch. Helper A's 150ms context.WithTimeout fires while the server is stalled; helper B then refreshes against the same LockDir and must succeed in < 2s. Proves both refreshMu and the cross-process proclock were released on the ctx-cancel path. New helper mode refresh-with-timeout.

2. TestE2ESub_NonCooperatingRaceStrictRevokes — Two helpers with distinct LockDirs but a shared fileStore (non-cooperating actors) race the same family. With IdempotencySuccessor: 0, the loser's first grant gets invalid_grant + family revocation; doRefresh's retry with cur.RefreshToken also fails; surfaces ErrReauthRequired. Server sees GrantCount==3, RefreshGrantCount==1, FamilyRevoked==true. Validates the retry plumbing fires end-to-end against real RFC 9700 server semantics, where COR-343's harness could only exercise it with fakes.

3. TestE2ESub_NonCooperatingRaceLaxAbsorbs — Same race with IdempotencySuccessor: 5s. The loser's grant returns the already-issued successor idempotently — no retry, no revocation, both succeed. Asserts GrantCount==2, RefreshGrantCount==2, family not revoked. Validates Manager + server idempotency window mesh cleanly.

Extension to internal/testoauth.Server (additive, no behaviour change)

StallNextRefresh() now returns (release func(), stalled <-chan struct{}). The stalled channel closes when the next refresh enters the stall wait — replaces the previous polling-plus-30ms-sleep race-ordering pattern with deterministic synchronisation. Existing self-test adapted to the new return.

Not testable end-to-end (and why)

doRefresh's "first grant fails, retry SUCCEEDS with new RT" branch isn't reachable against a well-behaved RFC 9700 server — the family state is shared between an RT and its successor, so either the first grant succeeds idempotently (within the window) or the first grant + retry both fail (outside the window, family revoked). The branch is defensive code for a server that decouples per-RT invalidation from family state, which RFC 9700 explicitly rules out. The existing unit test TestDoRefresh_RotationRaceRetriesWithNewRT exercises it with a fake refresh fn; that remains the only place. The race-mechanics-observability limit is explicitly documented in Test 2a.

Process

Same TDD subagent flow. Multi-agent PR review caught real items pre-push, all closed in b7d768a (squashed into the test commit's intent):

• Replaced the polling-plus-30ms-sleep race ordering with the new stalled channel — the latent flake vector both reviewers converged on.
• Narrowed helperRefreshWithTimeout's OK-criterion to specific known substrings instead of a loose strings.Contains("context") that could mask unrelated errors.
• Switched the new tests to the existing decodeHelperOutput helper (consistent with older tests).
• Tightened elapsed thresholds 5000→2000ms.
• Added a comment documenting Test 2a's observability limits on distinguishing "retry-with-cur-RT" vs "retry-with-original-RT" (both produce the same external state under strict mode; the unit test covers the distinction directly).

Verification

• gofmt -l . clean, golangci-lint run ./... 0 issues, govulncheck clean
• go test ./... -race -count=10 — all packages green
• go test ./tokenmanager/ -race -count=50 -run TestE2ESub_(CtxCancel|NonCooperating) — 50/50 clean (~2.1s per iteration)
• GOOS=windows go build ./... clean
• Bugbot review (post-push)

Branch ordering

Stacked on alex/cor-343-.... Base is set to that branch on this PR so the diff GitHub shows is the cor-345-only delta. When #12 merges, this rebases onto main automatically.

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are limited to test harness, mock OAuth server, and documentation; production auth paths are unchanged.

Overview
Adds three subprocess e2e tests in tokenmanager/e2e_subprocess_test.go for refresh-tier gaps after COR-343: context cancel mid-refresh (locks released so a follow-up refresh on the same LockDir finishes in <2s), and two-process rotation races with separate LockDirs but a shared file store—strict idempotency (ErrReauthRequired, family revoked, GrantCount shows retry plumbing) vs lax window (both succeed, no revocation).

Introduces helper mode refresh-with-timeout (AUTHGO_E2E_CTX_TIMEOUT_MS) and extends testoauth.Server.StallNextRefresh to return a stalled channel for deterministic “helper A is blocked” sync (replacing sleep/polling for race tests). Existing stall call sites use release, _ := …. Adds an approved design spec doc; no production tokenmanager code changes.

^{Reviewed by Cursor Bugbot for commit b7d768a. Configure here.}

[khaong]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b7d768a. Configure here.}