fix(app-session): read gateway descriptor version 3

[nicolasmertens]

Problem

Current Grok Bot desktop builds write gateway-descriptor.json with "version": 3. Every command that needs the app session then fails:

$ gbot bots list --json
{"error":{"code":"render-failed","message":"Unsupported Grok Bot gateway descriptor version 3."}}

Seen on macOS with gbot 0.12.4.

What v3 looks like

Same wrapper layout as v2, plus a savedAtMs timestamp per entry:

{ "version": 3, "entries": { "<hash>": { "savedAtMs": 1791320229049, "encrypted": "..." } } }

The decrypted payload still carries baseUrl, token and headers, plus a new vncProxy block that the CLI doesn't need.

Change

• encryptedPayload accepts version 3 and reads it the same way as version 2.
• The multiple-entries AMBIGUOUS_ENTRIES safety check is unchanged (see Support explicit account/gateway-entry selection for multi-account Grok Bot desktop sessions #102).
• Tests: added "loads a version 3 descriptor" and "rejects a version 3 descriptor with ambiguous entries". The unsupported-version test now uses version 4.
• Added a changeset (patch) and rebuilt artifact/.

Verification

• npm test: 444 pass, 0 fail. npm run validate:artifact: passes.
• Against a live Grok Bot desktop session on macOS, the patched build returns the bot list; gbot doctor reports Grok Bot app session: usable.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F7jcCQRFPBA9cNGeLvEoJi

[changeset-bot]

🦋 Changeset detected

Latest commit: e9ac663

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

[2689508458]

补充原生 Windows 实测结果：本 PR 的 v3 兼容修改解决了本机的 UNSUPPORTED_VERSION，修复代码归本 PR 原作者所有。

验证日期：2026-10-11。环境：Grok Bot Desktop 0.68.1、grok-bot-cli 0.12.4、Node.js 24.13.0、原生 Windows / PowerShell。

复现和恢复过程：

1. 桌面端已运行并登录，但 gateway-descriptor.json 缺失，gbot doctor 无法找到可用会话；这与 Windows: "Could not find a Grok Bot agents directory" after the Oct 5 Grok Bot app update (gateway-descriptor.json no longer written) #147 一致。
2. 先在桌面端打开云电脑并等待连接，再从系统托盘彻底退出 Grok Bot，趁云电脑仍处于唤醒状态立即重新打开。连接文件随后生成，因此 Windows: "Could not find a Grok Bot agents directory" after the Oct 5 Grok Bot app update (gateway-descriptor.json no longer written) #147 中此前仅在 macOS 验证的恢复方法在本机 Windows 上也有效。
3. 未打补丁的 0.12.4 随后报告 Unsupported Grok Bot gateway descriptor version 3.，错误码为 UNSUPPORTED_VERSION。
4. 将本 PR 的提交 e9ac66339d422733a6054ff61795d9841ffe43da 中的构建产物用于本地 CLI 和 Codex 插件后，会话可以读取。逐个比对代码产物，逻辑差异仅为允许版本 3、让版本 3 沿用版本 2 的 entries 分支；同时同步了对应构建校验元数据。

验证结果：

• gbot doctor：appSessionPresent=true、appSessionUsable=true、gatewayAuthPresent=true。
• gbot bots list --json：退出码 0，成功返回非空的真实云端 Bot 列表。
• 本 PR 的 app-session、doctor、url-policy 离线测试共 28 项通过。
• 打补丁后的 Codex 插件 MCP 完成 stdio initialize 和 tools/list，返回 22 个工具。这一项只验证 MCP 加载与发现，不代表已验证消息执行。

本次没有应用 #145 的凭据回退，没有修改 Grok Bot 桌面应用，也没有导出凭据或发送 Bot 任务。Windows 的 gbot codex status --json 仍返回 windows-unsupported；Codex 自动回传桥接属于独立限制，不在本次验证范围内。

结论：#147 的连接文件缺失与这里的 v3 读取不兼容是两个连续出现的问题；本机需要先恢复连接文件，再应用本 PR，才能恢复 CLI 只读云端连接。感谢提供这个最小兼容修复。