Issue

Fixes #10757

Context

Kilo already coalesces simultaneous Codex OAuth refreshes inside one process and can recover from some cross-process 401 races after another process persists rotated credentials. Separate Kilo processes still had a window where both could submit the same single-use refresh token before either persisted the replacement.

Implementation

Serialize the Codex refresh transaction with Kilo's existing heartbeat-backed Flock utility. The lock is acquired before re-reading stored auth and held through the token POST and rotated credential persistence, so waiters adopt the winner's valid credential without posting the old refresh token again.

The refresh POST now sends User-Agent: kilo/<version> for attribution. The existing in-process pending map and post-401 recovery remain in place as fast paths and defense in depth.

Screenshots / Video

N/A: no visual changes.

How to Test

Manual/local verification

Executed by the agent:

• bun install --frozen-lockfile
• cd packages/opencode && bun run typecheck
• cd packages/opencode && bun test ./test/kilocode/codex-auth-refresh.test.ts ./test/kilocode/oauth-branding.test.ts ./test/plugin/codex.test.ts
  • Passed: 24 tests.
  • Includes five early-401 and five delayed-401 two-process trials sharing one Kilo home. Every trial submitted the starting refresh token exactly once.
  • Includes a delayed token response longer than the injected stale-lock interval to verify heartbeat ownership.
  • Includes a runtime assertion for User-Agent: kilo/<version> on the OAuth refresh POST.
• cd packages/core && bun test ./test/util/flock.test.ts
  • Passed: 10 tests, including process contention, timeout, crashed-owner recovery, stale cleanup, heartbeat metadata, and compromised-lock handling.
• bun run script/check-opencode-annotations.ts
• bunx changeset status --output /tmp/kilo-changeset-status.json
• bun run lint
  • Completed with zero errors. The repository currently reports existing warnings outside this change.

Reviewer test steps

1. Run cd packages/opencode && bun test ./test/kilocode/codex-auth-refresh.test.ts ./test/kilocode/oauth-branding.test.ts ./test/plugin/codex.test.ts.
2. Run cd packages/core && bun test ./test/util/flock.test.ts.
3. Run cd packages/opencode && bun run typecheck.

Blocked checks and substitute verification

• None.

Checklist

• Issue linked above, or exception explained
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.