Skip token refresh when gh's state directory is not writable - #14845

Fixes #14844

Description

When a user signs in with an expiring token, gh stores a short-lived access token and a refresh token. Shortly before the access token expires, gh exchanges the refresh token for a new pair and saves it. The server rotates the refresh token on every exchange, so the old one stops working right away. To keep concurrent gh processes from spending the same refresh token, the exchange runs under a file lock, refresh.lock, in gh's state directory ($XDG_STATE_HOME/gh, usually ~/.local/state/gh).

Agent sandboxes often make everything outside the workspace read-only, including gh's state and config directories. In that case gh fails to create the lock, carries on without it, and refreshes anyway. The server rotates the refresh token, but gh cannot save the new credential. That one command works, but the stored refresh token is now dead. The next run outside the sandbox gets rejected, gh removes the credential, and the user has to sign in again. Several sandboxed processes starting at once can also each spend the token.

This PR makes gh skip the refresh when it cannot create or open the lock file because the filesystem denies the write. A failure like that means the refreshed credential most likely could not be saved either. gh keeps presenting the current access token and leaves the stored refresh token untouched, so a later run outside the sandbox refreshes it normally. gh also records a warning, which is printed to stderr just before gh exits:

! Skipped refreshing the token of account monalisa on github.com because gh's state directory (/home/monalisa/.local/state/gh) is not writable. The token has expired or is about to expire. To fix this, grant gh write access to that directory. If gh is running in a sandbox, you may need to run `gh auth status` outside of it.

How did you test this change?

On Ubuntu 24.04, I pointed gh's state directory at a read-only squashfs snap mount (/snap/core22/2411) and at a 0555 temp directory, then called the lock acquisition directly from a temporary test. Every failure was a *fs.PathError and was classified as inaccessible:

With a config holding a fake expired refreshable token and XDG_STATE_HOME on the read-only mount, I ran the built gh auth token. It printed the stored access token, then the warning above on stderr, and exited 0. The config file was unchanged.

On macOS 27.2 (arm64), the built binary was run against the same kind of fake config under sandbox-exec with the profile (version 1) (allow default) (deny file-write* (subpath "<tmp>/state")):

Windows was not tested.

Key points

• Only an *fs.PathError whose cause is a permission error (EACCES, EPERM) or EROFS triggers the skip. MkdirAll and opening the lock file return errors of this type. Errors from the locking syscall itself (for example ENOLCK on filesystems without advisory locking) and lock timeouts are not path errors, so gh still refreshes without the lock in those cases, as before.
• When the refresh is skipped, gh keeps presenting the current token instead of failing locally, even if the token looks expired. The server decides, which also covers clock skew. Inside the 10 minute refresh window the token still works. Once it has really expired, API calls in the sandbox get 401 until gh runs somewhere that can refresh.
• The warning is collected on AuthConfig and printed by Main because the refresh runs inside the HTTP transport (AddAuthTokenHeaderWithRefresh), and a RoundTripper can only return a response or an error, with no way to pass a warning back to the command. Replacing the 401 response with a custom error was rejected as a risky, likely incompatible change. http.Client would wrap it in a *url.Error, so errors.As checks for api.HTTPError with status 401 (the "Try authenticating with" and scopes hints in internal/ghcmd/cmd.go, the expired token explanation in gh auth status) would stop matching. Commands that match on error text would also break, and so would gh api, which prints the raw response body that scripts parse.
• The warning prints on every exit, including successful ones, because a skipped refresh inside the refresh window still succeeds and the user should know the token is about to stop working. It is deduplicated per account and host, and stdout and exit codes are unchanged. The existing "Try authenticating with" hint on 401 is left as is.
• A new refresh status, RefreshStatusSkipped, reports the outcome, and gh.AuthConfig gets a Warnings() method that Main reads before exiting.
• Trade-off: a setup that blocks the state directory but can still save credentials (for example in the keyring, or in a writable config directory) used to get working refreshes and now gets the skip and warning. A failed lock write is still the best available signal that the credential cannot be saved, and a wrong guess there costs the user a forced re-login.

Notes for reviewers

Start with isRefreshLockInaccessible and the skip branch in refreshCredentialForUser in internal/config/refreshable.go. withFreshConfigForRefresh now passes the lock error to its callback instead of a boolean, so the callback can tell why the lock is missing. Then read the warning collection on AuthConfig in internal/config/config.go and printAuthWarnings in internal/ghcmd/cmd.go.

The skip happens after gh re-reads the credential under the lock and confirms it still needs a refresh, but before the token exchange, so a skipped refresh never contacts the server.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @babakks will read and reply directly.
• An agent will draft replies and @username will read them before they are posted.
• Nobody has explicitly committed to replying.