auth: clarify timeout is indeterminate in probe contract

The wrapper produces TimeoutError for any operation that misses the
deadline, not only locked-but-reachable keyrings. The login path's
optimistic stay-on-keyring is still right (cost of guessing wrong is
one wasted OAuth ceremony, not a silently-plaintext token), but the
docstring and inline comment overclaimed by labeling timeout as
'reachable but locked'.

Author: simonfaltum

libs/auth/storage/cache.go

@@ -139,16 +139,16 @@ func applyLoginFallback(ctx context.Context, mode StorageMode, explicit bool, f
 		return c, mode, nil
 	case StorageModeSecure:
 		if probeErr := f.probeKeyring(); probeErr != nil {
-			// A timeout means the keyring is reachable but locked: the OS
-			// unlock prompt is on screen and the user is mid-typing. Stay on
-			// keyring regardless of explicit; by the time OAuth finishes the
-			// prompt has been answered and the final Store will succeed
-			// against an unlocked keyring. Mirrors gh CLI's accidentally-
-			// similar flow where AuthTokenWriteable's early keyring.Get
-			// triggers the same dialog without committing to plaintext.
+			// Timeout is indeterminate: usually a locked keyring with the
+			// GUI unlock prompt up and the user typing, but a hung or slow
+			// daemon produces the same error. Stay on keyring optimistically.
+			// If the user is unlocking, the final Store at end of OAuth lands
+			// in the now-unlocked keyring. If the keyring is genuinely stuck,
+			// the final Store also times out and login fails late, same
+			// outcome as failing here, but with no silently-plaintext token.
 			var timeoutErr *TimeoutError
 			if errors.As(probeErr, &timeoutErr) {
-				log.Debugf(ctx, "keyring probe timed out (%v); user is likely unlocking, staying on keyring", probeErr)
+				log.Debugf(ctx, "keyring probe timed out (%v); staying on keyring optimistically", probeErr)
 				return f.newKeyring(), mode, nil
 			}
 			if explicit {

libs/auth/storage/keyring.go

@@ -91,14 +91,20 @@ func NewKeyringCache() cache.TokenCache {
 // ProbeKeyring returns nil if a write+delete cycle completed within the
 // standard timeout. Callers distinguish two non-nil shapes via errors.As:
 //
-//   - *TimeoutError: the keyring is reachable but locked. On Linux this
-//     usually means the GUI unlock prompt is up and the user has not
-//     finished typing yet. The login path treats this as "stay on keyring"
-//     because the prompt continues in parallel with OAuth and the final
-//     Store will succeed against the by-then-unlocked keyring.
-//   - any other error: the keyring is genuinely unavailable (no daemon,
-//     headless session with no secret service, ...). Login falls back to
-//     plaintext now rather than failing after OAuth.
+//   - *TimeoutError: indeterminate. The keyring did not respond within
+//     the timeout. The common cause on Linux is a locked collection
+//     waiting on a GUI unlock prompt with the user mid-typing, but a
+//     hung or slow daemon produces the same shape. The login path
+//     optimistically stays on keyring: if the user is unlocking, the
+//     prompt continues in parallel with OAuth and the final Store
+//     succeeds against an unlocked keyring; if the keyring is genuinely
+//     stuck, the final Store also times out and login fails late
+//     instead of early. The cost of guessing wrong is one wasted OAuth
+//     ceremony, not a silently-plaintext token.
+//   - any other error: the keyring returned a definitive failure (no
+//     daemon, headless session with no secret service, dismissed prompt,
+//     ...). Login falls back to plaintext now rather than failing after
+//     OAuth.
 //
 // Probing also has a useful side effect: triggering the unlock prompt up
 // front, before the browser step. The user can answer it while OAuth is in