[yaoharry]

Changes

Serialize file-backed OAuth cache refreshes and writers with a stable lease on the canonical effective cache path. Reload and recheck after acquisition, stage the complete map, and publish once after success. Valid-cache reads stay fast; explicit force refresh still exchanges the latest generation. Login, logout, pending device-code state and file mirrors participate without changing the Store interface, dependency versions or main's secure backend.

This is an explicitly attributed file-backed alternative related to #6759. It builds on Vivek1106-04's OS-locking foundation and retains the Unix/Windows adapters byte-for-byte, with the original author credited as co-author. It is proposed from an owned branch against main.

Why

Two processes can share one custom cache file while using different HOME directories. Locking must follow that effective file across atomic replacement, and multi-step updates must remain invisible until successful publication. Rechecking under the lease avoids exchanging a stale refresh token; staging prevents failed updates from exposing provisional entries or overwriting unrelated grants. JSON null entries remain readable as missing entries without breaking healthy entries or later writes.

The coordination guarantee covers participating file-backed writers. Keyring/asynchronous secure operations and older, nonparticipating clients remain outside this change. Release adoption is required before installed clients benefit.

Known follow-up gap — keep this draft: after a provider rotates a refresh token, failed cache publication can leave the old generation available to a fresh client. A subsequent isolated fake-provider diagnostic reproduced that replay. Persistent pre-exchange intent is under design and is not implemented at this head. The local gate results below do not close that failure window.

Tests

Local required test legs passed with Go 1.27.3, FIPS v1.0.0, ordinary timeouts and no automatic reruns:

Scope	Passed	Failed	Default skips	Exit
Full root	12,059	0	134	0
Full acceptance	3,468	0	5	0
Full tools	82	0	0	0

No package failures. Normal ./task fmt, ./task checks and ./task lint exit 0; ./task doctest passed on unchanged Python source. Focused storage/U2M has 264 passing leaves, included in the broader root scope rather than added to it.

Maintained regressions use real FileStore/OS locks, two processes, separate HOME directories and a shared custom cache file with fake OAuth transport. Controls cover near-expiry refresh, force, cancellation, lock release, writer preservation, rollback, constructor-context compatibility and null entries. Test metadata uses scoped finite fake endpoints; completion/DMS consumers drain output while preserving original goldens and producer failure detection. No assertions, budgets, timeouts or skip conditions were weakened.

Runs used fake HOME/config, read-only dependencies and guarded network access; root's required anonymous public SDK metadata reads retained real TLS responses. Linux keyring acceptance covers the supported unavailable-backend path with unreachable owned D-Bus addresses. Working keyring integration and Windows/macOS runtime behavior remain outside local execution; no live auth, user credential, browser or provider calls were used.

This PR was written with Codex assistance.

[github-actions]

Thanks for the contribution! This pull request was opened from a fork.

If you're a member of the Databricks organization, please request access to the cli-contrib team and open your pull request from a branch in this repository instead of a fork — fork PRs don't run integration tests automatically and have reduced CI access.

If you're an external contributor, no action is needed; a maintainer will review your pull request.

[github-actions]

An authorized user can trigger integration tests manually by following the instructions below:

Trigger:
go/deco-tests-run/cli

Inputs:

• PR number: 7396
• Commit SHA: d4cda6b9a57ff3858fddb6d13326da94e40b4e7a

Checks will be approved automatically on success.