fix: keep Grok Bot CLI connected when the desktop gateway route disappears

[tomer-ben-david]

Context

Authenticated CLI commands should keep working when the signed-in app removes its cached gateway route. Grok Bot can remove gateway-descriptor.json when its cloud computer is kept asleep; the active encrypted account remains in sand-secrets.json. The CLI currently treats the missing route as missing auth, selects local-files mode, and reports an agents-directory error despite the desktop being signed in.

This PR retains the earlier version 3 descriptor fix and adds reconnection for the missing-file case.

Before and after

Input / state	Before	After
A version 3 descriptor with one encrypted entry	Rejects Unsupported Grok Bot gateway descriptor version 3	Reads the entry using the existing v2 validation rules
No descriptor; active signed-in desktop account; no manual token env	bots list selects files mode and fails with Could not find a Grok Bot agents directory	Reads only the active encrypted account and calls EnsureSandBox for a fresh route, then lists the cloud roster
macOS needs a fresh route; SAND_CLIENT_VERSION unset	Sends fixed 0.20.0; observed backend response was HTTP 401, This version of Grok Bot is no longer supported	Detects the installed app version from its Info.plist (observed 0.68.1) and successfully reconnects
Account archive has inactive saved accounts but no active account	No automatic login	No automatic login; inactive accounts are never selected

Goals

Restore commands for v3 descriptors and missing cached routes, preserve the active account's selected team, and keep explicit gateway/token/version overrides.

Non-goals

Select another saved account, refresh or persist OAuth credentials, change cloud sleep/privacy settings, or make an independent local copy of the roster. Automatic installed-app version detection is macOS-specific; other platforms retain the existing version override/default behavior.

Solution

• Accept v3 through the v2 single-entry validation path; retain v1/v2 support and ambiguous-entry errors.
• Add the active sand-secrets.json account as a gateway auth source. Decrypt it with the shared native Safe Storage helpers, and use its access token plus selected team for the existing bounded EnsureSandBox request. Do not modify the app's credential files.
• Retain auth precedence: explicit gateway pair, cached app route, explicit CURSOR_ACCESS_TOKEN, then active app credentials. Existing errors for present but invalid descriptors remain unchanged.
• Detect the installed macOS app version for backend headers, while preserving SAND_CLIENT_VERSION as the override. Doctor distinguishes a missing cached route from available active-account credentials.
• Add regression tests and patch changesets; rebuild the committed CLI/MCP/relay artifacts.

Verification

At 9c36b08:

• Focused authentication/header tests: 37/37 passed.
• Full unit suite: 451/452 passed. The remaining test/history.test.js:204 assertion (0 !== 1) also fails in an archived checkout of the previous head ff9bdc1, and was previously reproduced on unchanged upstream 43499fa.
• Route tests: 97/97 passed. Typecheck, build, artifact validation, and git diff --check passed.
• Read-only macOS acceptance: with the gateway descriptor absent, the built CLI's doctor detects active credentials and bots list returns seven bots. Both Homebrew and NVM command paths were verified locally without restarting the app or setting a token/version env variable.
• Linux basic-text credentials and inactive-account selection are covered by fixtures; Windows credential fallback and Linux keyring fallback have not received live acceptance testing.

Next steps

Merge and release through the repository's Changesets/OIDC workflow. The locally installed build is prepared from this source; the registry release is still pending.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9c36b08

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
grok-bot-cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR