wkgeo-cli 0.2.0

package/lib/login.mjs

@@ -0,0 +1,1332 @@
+/**
+ * `login`：授权码 + PKCE 的本地回调流程。
+ *
+ * 完整时序（按本项目的真实实现）：
+ *   1. CLI 起一个**只监听 127.0.0.1** 的临时 HTTP 服务
+ *   2. 生成 code_verifier / S256 challenge / state
+ *   3. 打开浏览器到 `authorization_endpoint?client_id&redirect_uri&scope&state&code_challenge…`
+ *      —— 未登录会先跳登录页，然后回到同意页
+ *   4. 用户在页面上点「同意」，页面 POST /api/oauth/consent，服务端签发 code 并跳回 redirect_uri
+ *   5. CLI 的本地服务收到 `?code=…&state=…` → **先校验 state**（服务端不校验，这是客户端的活）
+ *   6. CLI 用 code + code_verifier 换 token → 写本地凭据（0600）→ 回一个"可以关闭本页"的 HTML
+ *
+ * 为什么端口默认写死 53682 又要能换：
+ *   服务端登记的 redirect_uri 是 `http://127.0.0.1:53682/callback`。
+ *   服务端按 RFC 8252 对**回环地址忽略端口**（实测 54321 也匹配），所以端口被占用时
+ *   退到随机端口依然能授权成功。这条很重要：用户机器上 53682 被占是常事，
+ *   不能因为这个就让他去改客户端配置。
+ *
+ * 依赖注入（deps）是为了**可测**：offline 单测里把 fetch / 开浏览器 / 端口都替换掉，
+ * 就成了一台"假浏览器"，可以逐条验证 state 校验、超时、错误页这些分支。
+ *
+ * ⚠️ 两个等待窗口（别搞混，`commands/auth.mjs` 靠 `kind` 区分"要不要自动改设备码"）：
+ *   * `DEFAULT_CALLBACK_FIRST_WAIT_MS`（**180 秒**，`--callback-first-wait` 可调/可关，
+ *     ★ **只在检测到系统代理时**才由命令层启用）
+ *     → 到点抛 `kind = 'callback_first_wait'` → **自动改用设备码继续，不退出**（第二条保险）；
+ *   * `config.loginTimeoutMs`（默认 300 秒，`--timeout` 可调）
+ *     → 到点抛 `kind = 'timeout'`（整段等待的兜底，也是老板报的那个故障的现场）。
+ *
+ * ★★ 2026-10-03（老板真机反馈）起，这两条"到点"都**不再关掉本地回调监听**：
+ *   命令层会通过 `deps.handoff` 拿到通知，**并发**去跑设备码那条路，**哪条先成功就用哪条**
+ *   （详见 `DEFAULT_CALLBACK_FIRST_WAIT_MS` 与 `deps.handoff` 的注释）。
+ */
+
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { URL } from 'node:url';
+
+import { createApi } from './api.mjs';
+import { successPage, errorPage, alreadyDonePage } from './page.mjs';
+import { createVerifier, challengeOf, createState, safeEqual } from './pkce.mjs';
+import { writeCredentials, credentialsFromToken } from './credentials.mjs';
+import { withTrailingSlash } from './config.mjs';
+import { proxyRiskHint } from './proxy.mjs';
+import { CliError, EXIT } from './errors.mjs';
+
+/**
+ * 每个平台**依次尝试哪几个程序**打开网址，以及怎么把 URL 传给它。
+ *
+ * ⚠️⚠️ 为什么必须"多条策略"而不是"一条命令"（老板 2026-10-01 反馈）：
+ *   老板的 Windows 上**两次"什么都没弹出来"**，而当时 win32 只有一条
+ *   `rundll32 url.dll,FileProtocolHandler` —— 它既不报错、退出码也是 0，
+ *   失败是**完全静默**的。单条命令的可用性取决于这台机器上恰好装了/启用了它；
+ *   三条互不依赖的路径同时不可用的概率远低于任意一条。
+ *   （真客户不会自己复制粘贴网址，所以"自动打开"失败等于流程断掉。）
+ *
+ * ⚠️⚠️ Windows 这条分支踩过一个真机实测的大坑（2026-10-01）：
+ *   原来的写法是 `spawn('cmd', ['/c', 'start', '', url])` —— 浏览器**确实弹出来了**，
+ *   但打开的是光秃秃的 `/admin/oauth/authorize`，**所有 query 参数都没了**，
+ *   授权页显示「授权请求不完整」。
+ *
+ *   机理（必须记住）：**在 Windows 的 cmd.exe 里，`&` 是命令分隔符**。
+ *   `spawn` 不带 `shell: true` 时虽然不经过 shell，但我们**主动**去调了 `cmd.exe` ——
+ *   于是 cmd 拿到整条命令行后会**重新解析一遍**：
+ *     cmd /c start "" https://www.wkongai.cn/admin/oauth/authorize/?client_id=…&redirect_uri=…
+ *                                                                          ↑ 这里被当成命令分隔
+ *   → cmd 认为第一条命令是 `start "" https://…?client_id=…`（query 只剩第一个参数），
+ *      `&` 后面的 `redirect_uri=…` / `scope=…` / `state=…` / `code_challenge=…`
+ *      被当成**另一条命令**（cmd 报"不是内部或外部命令"，用户看不到，因为是隐藏窗口）。
+ *   本质上和"手拼 URL 不编码"是同一类坑：URL 交给**另一个命令行解析器**时被二次解释。
+ *
+ *   修法（现在是三条策略，按顺序试；2026-10-01 又调了一次①的位置 —— 见下面"为什么这么排"）：
+ *     ① `rundll32 url.dll,FileProtocolHandler <url>` —— **最稳的一条，所以排第一**：
+ *        * 它**不是 shell**：URL 作为独立 argv 传给进程，`&`、`=`、`%` 都只是普通字符
+ *          （CreateProcess → CommandLineToArgvW，`&` 在这里没有特殊含义）；
+ *        * 所以 URL 是**逐字符原样**落到系统里的，不存在"被另一个命令行解析器二次解释"；
+ *        * rundll32.exe + url.dll 是 Windows 自带，不需要用户装任何东西；
+ *        * 它也正是之前线上一直在用、真机实测**确实能弹出浏览器**的那条。
+ *     ② `cmd /c start "" "<url>"` —— 退到第二位做**兜底**（写法与引号**原样保留**）：
+ *        * 能用 `start` 是最贴近"用户双击网址"的路径（走的正是资源管理器里双击 URL
+ *          那条注册表路径，对"装了非默认浏览器 / 处理器注册得不规范"的机器命中率最高），
+ *          所以它必须留着；引号也**必须留在字符串里**（见下面策略表上的说明）。
+ *        * 但它的解析路径和①**根本不同**：URL 要先经过 cmd.exe 的命令行解析。
+ *          哪怕写了引号，这条路径上仍然有**残余风险**："命令退出码 0，而 URL 里的 `&`
+ *          已经被截断" —— 这是**静默失败**：兜底逻辑根本不会触发，
+ *          用户只会看到「授权请求不完整」。所以它只能排在①后面当兜底，绝不能放第一。
+ *          另外 args 里的引号还要再经过 Node/libuv 的 Windows 命令行转义，而 `\"` 在 cmd
+ *          里的解释与 CommandLineToArgvW 并不一致，也可能出现"看起来加了引号其实还是被拆开"。
+ *     ③ `powershell -NoProfile -Command "Start-Process '<url>'"` —— 前两条都哑了时的最后一条。
+ *    为什么这么排：①（不经 shell、URL 原样）是**最不可能静默失败**的一条，放最前面；
+ *    ② 虽是"用户双击"路径、命中率最高，却带上面那个残余解析风险，所以只在前一条不可用时
+ *    才启用；③ 收尾。这样单条失败**不再等于**整个自动打开失败（这正是这次要修的问题）。
+ */
+export const BROWSER_STRATEGY_TABLE = {
+  /**
+   * ⚠️⚠️ Windows 第 ② 条（`cmd /c start`）的**引号**是必须的（老板真机踩过，见上面那段记录）：
+   *    `cmd.exe` 里 `&` 是**命令分隔符**，而授权 URL 的 query 里全是 `&`
+   *    （client_id&redirect_uri&response_type&scope&state&code_challenge…）。
+   *    所以必须写成 `start "" "<url>"`，并且**整串（连引号）放进同一个 argv 元素**，
+   *    让那对 `"` 真的出现在 cmd 的命令行上。
+   *    ⛔ **不要**改成 `['/c', 'start', '', url]`：那样 URL 是作为**独立 argv**
+   *    交给 cmd 的，cmd 会再解析一遍命令行，`&` 又开始生效 ——
+   *    第一个 `&` 之后的内容会被当成"另一条命令"，浏览器只拿到光秃秃的
+   *    `/admin/oauth/authorize`（页面报「授权请求不完整」），cmd 还会因为
+   *    `redirect_uri=…` 不是可执行命令而返回非零退出码。旧 bug 就是这么来的。
+   *    三条里只有②经过 cmd；① rundll32 与 ③ powershell 都不过 shell，
+   *    URL 里的 `&`、`=`、`%` 都只是普通字符。
+   */
+  win32: [
+    // ① 最稳的一条：不经任何 shell，URL 作为独立 argv 逐字符原样交给系统（线上实测能弹浏览器的那条）
+    { label: 'rundll32 url.dll,FileProtocolHandler', cmd: 'rundll32', args: (url) => ['url.dll,FileProtocolHandler', url] },
+    // ② 兜底：命令与引号写法**保持原样**（引号必须在字符串里）；它要经 cmd 解析，存在"退出码 0 却截断 URL"的残余风险，所以不排第一
+    { label: 'cmd /c start', cmd: 'cmd', args: (url) => ['/c', `start "" "${url}"`] },
+    // ③ 前两条都哑了时的最后一条
+    { label: 'powershell Start-Process', cmd: 'powershell', args: (url) => ['-NoProfile', '-Command', `Start-Process '${url}'`] },
+  ],
+  darwin: [
+    { label: 'open', cmd: 'open', args: (url) => [url] },
+    // 兜底：`open <url>` 是交给 LaunchServices 挑处理器，偶尔挑不出来；指名 Safari 再试一次
+    { label: 'open -a Safari', cmd: 'open', args: (url) => ['-a', 'Safari', url] },
+  ],
+  // linux 以及其它类 unix（freebsd 等）：xdg-open 是桌面环境的事实标准，后两条是常见兜底
+  linux: [
+    { label: 'xdg-open', cmd: 'xdg-open', args: (url) => [url] },
+    { label: 'sensible-browser', cmd: 'sensible-browser', args: (url) => [url] },
+    { label: 'x-www-browser', cmd: 'x-www-browser', args: (url) => [url] },
+  ],
+};
+
+/** 找不到对应平台时按 linux 处理（xdg-open 在非 Windows/macOS 上最通用） */
+const FALLBACK_STRATEGIES = BROWSER_STRATEGY_TABLE.linux;
+
+/** 每条策略最多等多久（3~5 秒区间；为什么超时按"乐观成功"处理见 launchStrategy） */
+export const BROWSER_LAUNCH_TIMEOUT_MS = 4000;
+
+/**
+ * ★ 「回调模式首轮等待」窗口（默认 **180 秒**）—— 第二条保险，**只在检测到系统代理时启用**。
+ *
+ * ## ⚠️⚠️ 2026-10-03 老板真机反馈：这条自愈**被用错了场景**（本次修的就是它）
+ *   老板**没有开任何 VPN / 代理**，但连着重跑几次 `wkgeo login` 都**自动变成了设备码**，
+ *   原话：「现在变成设备码了，我们因为没有开任何VPN，所以这个是不对的。」
+ *   现场：旧逻辑把这个窗口**无条件**挂在 60 秒上，而"把授权页送到用户面前、用户读完再点
+ *   【同意】"经常超过 60 秒 —— 于是明明不需要设备码，也切了过去。
+ *   ⇒ 现在：**只有 `proxy_warning.detected === true`（真检测到生效中的代理）才启用**；
+ *     **没有代理时一律不启用**（老老实实等满 `--timeout`）。
+ *     用户**显式**写 `--callback-first-wait <秒>` 或 `WKONGAI_CALLBACK_FIRST_WAIT_MS` 时照旧尊重
+ *     —— **显式指定优先于自动判断**（他怎么要求就怎么做）。
+ *   ⇒ 连带结论：`auto_device.applied=true, reason='callback_first_wait'` **只可能出现在有代理的机器上**；
+ *     没有代理、用户也没显式指定时，**绝不会**发生。
+ *   （判定点在 `commands/auth.mjs` 的 `resolveCallbackFirstWaitMs()`，那边有一份对应的说明与单测钉子。）
+ *
+ * ## 为什么还需要它（什么时候它是对的）
+ *   "代理把回调吃掉了"这种故障里，用户其实早就点完【同意授权】了，只是结果回不来；
+ *   而设备码**不需要任何入站回调**，几分钟内就能拿到令牌 —— 比让他干等 5~15 分钟强得多。
+ *   放宽到 180 秒（原来是 60 秒）就是给"用户真在认真读授权页"留足余量：
+ *   它只在"有代理、回调本来就可能回不来"的机器上生效，宁可多等一会儿再改道。
+ *
+ * ## ★★ 到点之后**不关本地回调监听**（同一次修复的第二条，真机证据见下）
+ *   旧行为：到点 → 抛 `callback_first_wait` → 命令层改走设备码，而 `runLogin` 的 `finally`
+ *   **已经把本地 server 关掉了**。于是用户随后才点【同意授权】时，浏览器跳到
+ *   `http://127.0.0.1:<port>/callback?code=…` 得到 **ERR_CONNECTION_REFUSED**
+ *   （老板真机截图见过）—— 用户以为授权失败，又重来一次（其实他马上就会登录成功）。
+ *   现在的契约：调用方传了 `deps.handoff` 时，到点**只通知、不结束、不关监听**（见 `runLogin`），
+ *   由命令层**并发**跑设备码，两条路**先到先得**。
+ *
+ * ## 覆盖方式（优先级：命令行 > 环境变量 > 这个默认值）
+ *   * `--callback-first-wait <时长>`：默认单位**秒**（`--callback-first-wait 90` = 90 秒），
+ *     也支持 `90s` / `90000ms`；写 `0` / `off` / `none` 表示**关掉这个自愈窗口**
+ *     （那就只剩整段 `--timeout` 窗口）。
+ *   * `WKONGAI_CALLBACK_FIRST_WAIT_MS`：毫秒（沿用 `WKONGAI_LOGIN_TIMEOUT_MS` 的口径）。
+ *   * `--no-auto-device` / `WKONGAI_AUTO_DEVICE=0` 时**强制关闭**：用户明确要求只走回调，
+ *     我们就没有"改道"这个选项，不能偷偷改（见 `commands/auth.mjs` 的 resolveCallbackFirstWaitMs）。
+ *
+ * ## 约束
+ *   * 必须**小于** `config.loginTimeoutMs` 才有意义（否则只会先撞整段超时）；
+ *   * 到点后抛 `kind = 'callback_first_wait'`（**不是** `timeout`），命令层据此自动改设备码、
+ *     **不退出**；换票失败/被拒绝等其他错误**照旧不降级**。
+ */
+export const DEFAULT_CALLBACK_FIRST_WAIT_MS = 180_000;
+
+/**
+ * ★ 设备码那条路**先**拿到令牌之后，本地回调监听再多留多久（毫秒）。
+ *
+ * 为什么需要：用户很可能在两个标签页之间来回 —— 一边是 CLI 让他打开的授权页（回调模式），
+ * 一边是切设备码后让他打开的确认页。设备码先确认成功后，如果**立刻**关掉监听，
+ * 他回到那个还开着的授权页点【同意授权】时，浏览器就又是一次
+ * `ERR_CONNECTION_REFUSED`（真机截图见过的那一幕，用户会以为授权失败）。
+ * 留这一小段时间，迟到的回调会拿到一张「本次登录已经完成」的页面（见 page.mjs 的 alreadyDonePage）。
+ *
+ * ## 两个刻意的选择
+ *   * **只给"首轮等待"这条自愈留 grace**：那时候用户很可能正在读授权页、手指就在鼠标上；
+ *     而"整段 `--timeout` 用完"（默认 300 秒，授权码本身也就 5 分钟有效期）之后再来的回调，
+ *     基本已经换不到令牌了，留监听没有意义 ⇒ 那种情况 grace = 0（立刻收尾）。
+ *   * **不 await**：`runLogin` 立刻把结果交回命令层（用户马上看到"授权成功"），
+ *     监听与这个定时器在后台再活一小会儿，到点（或被那次迟到的回调提前唤醒）就自行关闭。
+ *     代价是进程会晚几秒退出 —— 换来的是"用户之后点的那一下不会看到连接被拒绝"。
+ */
+export const DEFAULT_POST_DEVICE_GRACE_MS = 3000;
+
+/**
+ * 取某个平台要**依次尝试**的策略表。
+ * `strategies` 可整体注入 —— 单测靠它构造"前两条失败、第三条成功"和"全失败"，
+ * 且注入的是**数据**而不是替换整个 `openInBrowser`，这样被测代码还是生产那份。
+ */
+export function strategiesFor(platform, strategies) {
+  if (Array.isArray(strategies) && strategies.length > 0) return strategies;
+  return BROWSER_STRATEGY_TABLE[platform] || FALLBACK_STRATEGIES;
+}
+
+/** 子进程的固定选项：不继承 stdio、独立进程组（CLI 退出后浏览器继续活着）、不闪黑框 */
+function browserSpawnOptions() {
+  return { stdio: 'ignore', detached: true, windowsHide: true };
+}
+
+/**
+ * 打开浏览器（**同步**版，按策略表依次尝试）。
+ *
+ * 这是 `openInBrowser` 的历史契约，`device.mjs`（设备码模式）与 `lib/index.mjs`
+ * 都在用它，所以**返回值必须保持 boolean**、函数必须保持同步。
+ * 它只能判断"进程有没有被创建出来"（spawn 同步抛错 → 试下一条），
+ * 判断不了退出码 —— 要那份判断请用异步的 `openInBrowserWithFallback`（login 走那条）。
+ *
+ * 异步失败（进程创建不出来 → 下个 tick emit `error`）时，它会在**后台静默**继续试
+ * 后面的策略；只有**全部策略都异步失败**才回调 `onError`（只回调一次，
+ * 避免用户看到三遍一模一样的提示）。
+ *
+ * **永不抛错、永不中断登录**：失败只返回 `false`。
+ *
+ * @param {string} url              要打开的**完整**授权地址（含 query，逐字符传给系统）
+ * @param {object} [opts]
+ * @param {string} [opts.platform]  平台（默认 process.platform；测试可注入）
+ * @param {Function} [opts.spawnImpl] child_process.spawn（测试可注入，避免真的弹浏览器）
+ * @param {Array} [opts.strategies] 策略表（默认按平台取；测试可注入）
+ * @param {(e:Error)=>void} [opts.onError] **异步**失败的回调（同步失败直接 return false）
+ * @returns {boolean} 是否成功把打开动作交给了系统（乐观判断，见上）
+ */
+export function openInBrowser(url, { platform = process.platform, spawnImpl = spawn, onError, strategies } = {}) {
+  const target = typeof url === 'string' ? url.trim() : '';
+  // 空地址没有任何可打开的：直接 false，别去 spawn 一个空参数
+  if (!target) return false;
+
+  const list = strategiesFor(platform, strategies);
+
+  /**
+   * `fromAsync` 用来区分两种失败，别把提示打成两遍：
+   *   * 同步失败（spawn 直接抛）：返回值已经是 false，调用方自己会提示"手动复制"，
+   *     这里**不再**回调 onError；
+   *   * 异步失败（emit `error`）：返回值当时是 true，只能靠 onError 告诉用户"没打开成功"。
+   */
+  const attempt = (i, fromAsync, lastError) => {
+    if (i >= list.length) {
+      if (fromAsync && typeof onError === 'function') onError(lastError);
+      return false;
+    }
+    const strategy = list[i];
+    let child;
+    try {
+      child = spawnImpl(strategy.cmd, strategy.args(target), browserSpawnOptions());
+    } catch (e) {
+      // spawn 同步抛（参数非法等）：不致命，换下一条策略
+      return attempt(i + 1, fromAsync, e);
+    }
+    if (!child) return attempt(i + 1, fromAsync, lastError);
+
+    /**
+     * ⚠️ `error` 监听**必须挂**：spawn 的目标不存在（例如容器里没有 xdg-open）时，
+     *    Node 会在**下一个 tick** 异步 emit `error`。没有监听者的话 EventEmitter
+     *    会把它当未捕获异常**直接崩掉整个 CLI**（登录进程半途而死，用户只看到一段栈）。
+     *
+     * 挂上之后它同时是"静默降级到下一条策略"的入口 —— 多策略的意义就在这里。
+     */
+    if (typeof child.on === 'function') {
+      child.on('error', (e) => attempt(i + 1, true, e));
+    }
+    // detached + unref：浏览器进程不归 CLI 管，CLI 退出后它继续活着
+    if (typeof child.unref === 'function') child.unref();
+    return true;
+  };
+
+  return attempt(0, false, null);
+}
+
+/**
+ * 依次尝试策略表里的每一条，**每一条都等结果**（`error` / 退出码 / 超时）再决定下一条。
+ * 这是 `login`（本地回调模式）走的那条路 —— 老板要的"每个都检查结果后再决定下一个"。
+ *
+ * 与同步版的分工：同步版只为 `device.mjs` 保持历史契约（它 await 不了），
+ * 这里才拿得到"到底哪几条试过、最后成没成"。
+ *
+ * **永不抛错**（只 resolve，不 reject）：调用方可以放心 await 而不用担心
+ * "因为打不开浏览器把登录搞失败"。
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {string} [opts.platform]   平台（默认 process.platform）
+ * @param {Function} [opts.spawnImpl] child_process.spawn（测试可注入）
+ * @param {Array} [opts.strategies]  策略表（测试可注入，构造"前两条失败、第三条成功"）
+ * @param {number} [opts.timeoutMs]  单条策略的超时（默认 BROWSER_LAUNCH_TIMEOUT_MS）
+ * @param {(info:object)=>void} [opts.onAttempt] 每条策略结束后的回调（--verbose 用）
+ * @returns {Promise<{attempted:boolean, opened:boolean, tried:string[], url:string}>}
+ */
+export async function openInBrowserWithFallback(url, opts = {}) {
+  const {
+    platform = process.platform,
+    spawnImpl = spawn,
+    strategies,
+    timeoutMs = BROWSER_LAUNCH_TIMEOUT_MS,
+    onAttempt,
+  } = opts;
+
+  const target = typeof url === 'string' ? url.trim() : '';
+  // 空地址：一条策略都不试（`attempted:false` 让上层能如实上报"根本没试"）
+  if (!target) return { attempted: false, opened: false, tried: [], url: '' };
+
+  const status = { attempted: true, opened: false, tried: [], url: target };
+  for (const strategy of strategiesFor(platform, strategies)) {
+    status.tried.push(strategy.label);
+    const result = await launchStrategy(strategy, target, spawnImpl, timeoutMs);
+    if (typeof onAttempt === 'function') {
+      try {
+        onAttempt({ label: strategy.label, ok: result.ok, error: result.error, timedOut: result.timedOut === true });
+      } catch {
+        /* 记日志本身失败绝不能影响"打开浏览器"这件事 */
+      }
+    }
+    if (result.ok) {
+      status.opened = true;
+      return status;
+    }
+    // 失败**静默**试下一条（只有 --verbose 才由 onAttempt 记一笔）
+  }
+  return status;
+}
+
+/**
+ * 跑**单条**策略：等 `error` / 退出码 / 超时，谁先到谁说了算。**永不 reject**。
+ *
+ * ⚠️ 超时按"乐观成功"处理（不再试后面的策略）：
+ *    这些启动器（cmd start / rundll32 / open / xdg-open / Start-Process）都是
+ *    "把 URL 交给系统就立刻退出"的程序，正常几十~几百毫秒就会 exit；
+ *    真拖到 3~5 秒说明它既没报错也没退出（吊住了）。此时再试下一条有把浏览器
+ *    **开两次**的风险，而多开一个窗口比少开一次更惹人烦 —— 何况网址本来就打印在上面。
+ *
+ * ⚠️ 超时定时器**故意不 unref**：它就是"保证这次 await 一定会结算"的锚。
+ *    （子进程是 unref 的，若定时器也 unref，事件循环可能直接空转退出，
+ *      这个 Promise 就永远不 resolve，登录会卡死在"打开浏览器"这一步。）
+ */
+function launchStrategy(strategy, target, spawnImpl, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    let child;
+    try {
+      child = spawnImpl(strategy.cmd, strategy.args(target), browserSpawnOptions());
+    } catch (e) {
+      resolve({ ok: false, error: e });
+      return;
+    }
+    if (!child) {
+      resolve({ ok: false, error: new Error('spawn 没有返回子进程') });
+      return;
+    }
+
+    timer = setTimeout(() => settle({ ok: true, timedOut: true }), timeoutMs);
+
+    if (typeof child.on === 'function') {
+      // 命令不存在 / 没权限 → 下个 tick 的 error：这条策略算失败，试下一条
+      child.on('error', (e) => settle({ ok: false, error: e }));
+      // 进程正常退出才算成功：非零退出码意味着"它自己认为没干成"（例如 xdg-open 找不到浏览器）
+      child.on('exit', (code, signal) => {
+        if (code === 0) return settle({ ok: true });
+        settle({ ok: false, error: new Error(`退出码 ${code}${signal ? `（信号 ${signal}）` : ''}`) });
+      });
+    } else {
+      // 注入的假子进程连事件接口都没有：只能当"已交给系统"
+      settle({ ok: true });
+    }
+    if (typeof child.unref === 'function') child.unref();
+  });
+}
+
+/**
+ * 把"打开浏览器"的结果统一成事件里的那四个字段（`open_browser`）。
+ * 兼容历史注入：老测试注入的是 `() => true` / `() => false` 这种 boolean 返回值。
+ */
+function normalizeOpenStatus(raw, url, skippedReason = null) {
+  if (raw && typeof raw === 'object') {
+    return {
+      attempted: raw.attempted !== false,
+      opened: raw.opened === true,
+      tried: Array.isArray(raw.tried) ? raw.tried.slice() : [],
+      url: typeof raw.url === 'string' && raw.url ? raw.url : url,
+      skipped_reason: raw.skipped_reason === undefined ? skippedReason : raw.skipped_reason,
+    };
+  }
+  return { attempted: true, opened: raw === true, tried: [], url, skipped_reason: skippedReason };
+}
+
+/**
+ * ★★ 「要不要替用户弹**系统**浏览器」—— **全 CLI 唯一的裁决点**。
+ *
+ * ## ★ 老板最终拍板：走**传统路线**（弹系统浏览器），本函数因此回到"默认总是尝试打开"
+ *   原话：「还是返回以前那种**打开跳到一个浏览器**，然后打开授权那个吧，**大家也都是那个的**。
+ *    我们在右侧这个……能力还不会太完善，我们这样做也不太好，**还是走传统的路吧**。」
+ *   （A 路线 = CLI 自动弹系统浏览器 ✔ 采用；B 路线 = AI 客户端右侧内置浏览器 ✘ 暂时不做。）
+ *
+ *   为什么传统路线更好（写进代码里，免得下次又被"弹窗会不会吓到用户"带偏）：
+ *   * **稳定**：各平台都有成熟的启动器（`rundll32` / `open` / `xdg-open`…），
+ *     而"在 AI 客户端右侧打开"要靠宿主插件 + 客户端配合，能力还**不完善**；
+ *   * **`window.close()` 在独立浏览器里生效**：授权页/收银台完成后的那一屏能**自己关掉**，
+ *     用户不会留下一个"我是不是没成功"的疑问窗口（内置侧边栏里关不掉，反而更别扭）。
+ *
+ * ## 判定（三条，顺序即优先级）
+ *   1. `--no-browser`（`noBrowser`）→ **不打开**（`skipped_reason: "no_browser"`）。
+ *      ⚠️ 这是 AI 端"我不想弹窗"的**唯一开关**，也压过 `--open-browser`；
+ *   2. `--open-browser`（`forceOpen`）→ 打开（`mode: "forced"`）。
+ *      ⚠️ 它现在与**默认行为等价**，但**保留**：显式语义 + 兼容既有脚本；
+ *   3. 默认（其它一切情况）→ **总是尝试打开系统浏览器**：
+ *      * 人在终端（`isTTY === true && json !== true`）→ `mode: "terminal"`；
+ *      * 其余（非 TTY / `--json` = **AI 场景**）→ `mode: "agent"`，★ **同样打开**。
+ *      ⇒ 这是本次的行为变更：`json` / `isTTY` **不再**是"不打开"的理由。
+ *
+ * ## ⚠️ 已弃用的取值：`skipped_reason = "non_tty_agent_mode"`（不再可能出现）
+ *   2026-10-01 曾按"AI 场景默认不弹、改提示用户去右侧内置浏览器打开"做过一版，
+ *   那时才会有这个取值。老板最终拍板走传统路线后**它已经消失** ——
+ *   现在 `skipped_reason` 只有 `"no_browser"` 或 `null` 两种（老文档/老代码看到它就知道是历史值）。
+ *   ⚠️ `open_browser` 的**结构与取值口径没有变**：`{attempted, opened, tried, url, skipped_reason}`。
+ *
+ * ## ⚠️ 绝不允许因为"没打开浏览器"让命令失败
+ *   返回 `allow:false` 只是"不弹窗"；即使 `allow:true` 而打开失败（`attempted:true, opened:false`），
+ *   也只是多打一段**含完整 URL** 的醒目提示（见 `browserFailedHintLines`）——
+ *   授权/支付流程**照旧继续等回调、继续轮询**，语义完全不变。
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.isTTY]     stdout 是不是终端（命令层传 `!!stdout.isTTY`；现在只影响 `mode` 这个诊断字段）
+ * @param {boolean} [opts.json]      是不是 JSON 输出（同上，只影响 `mode`）
+ * @param {boolean} [opts.forceOpen] 用户写了 `--open-browser`
+ * @param {boolean} [opts.noBrowser] 用户写了 `--no-browser`（或 deps.openBrowser === false）
+ * @returns {{allow:boolean, mode:'off'|'forced'|'terminal'|'agent', skipped_reason:('no_browser'|null)}}
+ */
+export function resolveBrowserIntent({ isTTY = false, json = false, forceOpen = false, noBrowser = false } = {}) {
+  // ① 用户明确关掉：连 `--open-browser` 也不许把它顶回来（--no-browser 优先）
+  if (noBrowser === true) return { allow: false, mode: 'off', skipped_reason: 'no_browser' };
+  // ② 用户明确要求打开：保留（与默认行为等价，但显式语义与兼容性都要留住）
+  if (forceOpen === true) return { allow: true, mode: 'forced', skipped_reason: null };
+  // ③ 人在终端：保持 CLI 一直以来的体验（这条**不能**破坏）
+  if (isTTY === true && json !== true) return { allow: true, mode: 'terminal', skipped_reason: null };
+  // ④ AI 场景（非 TTY / --json）：★ 本次改回来的那一条 —— **同样尝试打开系统浏览器**
+  return { allow: true, mode: 'agent', skipped_reason: null };
+}
+
+/**
+ * ★ 打开成功时的一句话（老板最终拍板走**传统路线**：弹系统浏览器）。
+ *
+ * 文案的两个要点：
+ *   1. **先说结果**（「已为你打开浏览器」）—— 用户第一眼要确认"它到底开了没有"；
+ *      以前这里写的是「正在打开浏览器…」，打开失败时那句话会让用户以为"还在开"；
+ *   2. 说清**去那里干什么**（授权 / 支付），别让他回终端猜。
+ * "完成后页面会自动关闭 / 没关就手动关掉即可"由调用方紧接着单独打一行
+ * （**失败路径**也要同一句话，所以不塞进这一行）。
+ */
+export function browserOpenedText({ kind = 'auth' } = {}) {
+  return kind === 'pay'
+    ? '✅ 已为你打开浏览器，请在那里完成支付（微信扫码）。'
+    : '✅ 已为你打开浏览器，请在那里完成授权。';
+}
+
+/**
+ * ★ 打开失败时的一段**醒目提示**（`⚠️` 起头 + **完整 URL 单独一行**，可直接复制）。
+ *
+ * 三条硬要求（都是老板反馈里点名的）：
+ *   1. **醒目**：明确说"没能自动打开"，别让用户以为还在打开中；
+ *   2. **可操作**：把**完整 URL 原样再打一遍**（就在这段提示里，用户不用往上翻页找），
+ *      并说清动作是"复制这一整行 → 粘贴到浏览器地址栏"；
+ *   3. 说清打开之后干什么（点「同意」/ 用微信扫码），让非技术用户也能走完。
+ * 真客户不会自己去找网址，所以这段是"自动打开失败"时唯一能救回流程的东西。
+ *
+ * @param {string} url 完整地址（逐字符原样打印，方便复制）
+ * @param {object} [opts]
+ * @param {'auth'|'pay'} [opts.kind]
+ * @param {boolean} [opts.agent] AI 场景（非 TTY / `--json`）时追加一句**可选**提示：
+ *   "若你的 AI 客户端支持内置浏览器，也可以让它在那里打开" ——
+ *   ⚠️ 只是备选，**不是主路径**（B 路线暂时不做，老板最终选择传统路线）。
+ * @param {string} [opts.cause] 失败原因（spawn 报的原文），有就附在第一行括号里，方便排障
+ */
+export function browserFailedHintLines(url, { kind = 'auth', agent = false, cause = '' } = {}) {
+  const 动作 = kind === 'pay' ? '支付' : '授权';
+  return [
+    '',
+    `⚠️ 浏览器没能自动打开${cause ? `（${cause}）` : ''}，请手动复制这个地址到浏览器完成${动作}：`,
+    `  ${url}`,
+    kind === 'pay'
+      ? '（这是我们网站的收银台页面：打开后用微信扫码支付；支付成功后页面会自动尝试关闭，没关就手动关掉即可。）'
+      : '（打开后点「同意」即可；授权完成后回到终端。授权成功后页面会自动尝试关闭，没关就手动关掉即可。）',
+    ...(agent ? ['（若你的 AI 客户端支持内置浏览器，也可以让它在那里打开同一个地址；这只是备选，不是必须的。）'] : []),
+    '',
+  ];
+}
+
+/**
+ * 「照着念」的一句话 —— 给 AI 端直接转述用（AI 不该自己组织语言，否则很容易漏掉网址）。
+ *
+ * ★ 老板最终拍板走传统路线（弹系统浏览器）之后，**两种场景共用同一句话术**：
+ *   以"已为你打开浏览器"为主，并把地址**原样带上**（万一本机没弹出来，AI 还能把它交给用户手动打开）。
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {'auth'|'pay'} [opts.kind]
+ * @param {boolean} [opts.agent] ⚠️ **已弃用**（仅为兼容既有调用方而保留）：
+ *   以前用它切"请在右侧（内置浏览器）…"的口径；B 路线暂停后两种场景话术已统一，
+ *   这个入参**不再影响输出**。
+ */
+export function browserPasteText(url, { kind = 'auth', agent = false } = {}) {
+  // 已弃用：见上面的参数说明（保留形参只是不想为了一个布尔值去改所有调用方）
+  void agent;
+  const 收尾 = '（完成后页面会自动关闭；没关就手动关掉即可）';
+  return kind === 'pay'
+    ? `已为你打开浏览器，请在那里完成支付（微信扫码）：${url}${收尾}`
+    : `已为你打开浏览器，请在那里完成授权：${url}${收尾}`;
+}
+
+/**
+ * 默认的"打开浏览器"实现（单独抽出来是为了**可测**）。
+ *
+ * `deps.spawnImpl` / `deps.platform` 可以注入 —— 这样单测能让"打开失败"真实发生
+ * （而不是把 openBrowser 整个换掉，那样就测不到 warn 文案与"不中断"这两件事了）。
+ *
+ * 两种失败（同步抛 / 异步 emit error）都打**同一段**"请手动复制这个地址…"的醒目提示，
+ * 而且提示里**自带完整 URL**（真客户不会往上翻页找地址），并且**都不中断**授权。
+ */
+export function defaultOpenBrowser(deps = {}, log = () => {}) {
+  const agent = !(deps.isTTY === true && deps.json !== true);
+  return (url) =>
+    openInBrowser(url, {
+      platform: deps.platform,
+      spawnImpl: deps.spawnImpl,
+      onError: (e) =>
+        log(
+          browserFailedHintLines(url, {
+            kind: deps.browserHintKind === 'pay' ? 'pay' : 'auth',
+            agent,
+            cause: (e && e.message) || String(e),
+          }).join('\n'),
+        ),
+    });
+}
+
+/**
+ * `login`（本地回调模式）专用的默认实现：**异步**版，多策略逐条等待结果。
+ *
+ * ⚠️ 为什么不复用上面的 `defaultOpenBrowser`：`device.mjs`（设备码模式）是**同步**调用它
+ *    并拿 boolean 的，那段代码不在本次改动范围内 —— 所以同步版保留原契约不动，
+ *    login 这条链路上再加一个能 await 结果的版本。两者共用同一张策略表，
+ *    差别只在"要不要等退出码"。
+ *
+ * 失败**不在这里**打印长提示：login 主流程拿到 `opened:false` 后会打印
+ * 一段**带完整 URL** 的醒目提示（见 runLogin 第 4 步）。这里只在 `--verbose` 时
+ * 逐条记录"哪条策略为什么挂了"，方便真机排障。
+ *
+ * @param {object} deps  { platform, spawnImpl, browserStrategies, browserTimeoutMs, verbose }
+ * @param {(msg:string)=>void} log
+ */
+export function defaultOpenBrowserAsync(deps = {}, log = () => {}) {
+  const verbose = deps.verbose === true;
+  return (url) =>
+    openInBrowserWithFallback(url, {
+      platform: deps.platform,
+      spawnImpl: deps.spawnImpl,
+      strategies: deps.browserStrategies,
+      timeoutMs: deps.browserTimeoutMs,
+      onAttempt: verbose
+        ? ({ label, ok, error, timedOut }) =>
+            log(
+              ok
+                ? `[verbose] 打开浏览器：「${label}」${timedOut ? '超时未返回，按已交给系统处理' : '成功'}`
+                : `[verbose] 打开浏览器：「${label}」失败（${(error && error.message) || error}），静默试下一条`,
+            )
+        : undefined,
+    });
+}
+
+/**
+ * 「把一个网址交给用户的浏览器」—— **全 CLI 唯一入口**（login / 钱包充值共用）。
+ *
+ * ## 为什么必须抽出来（不允许各命令自己 spawn 一份）
+ *
+ * 打开浏览器这件事踩过的坑全在这个文件顶部（`cmd /c start` 的引号、URL 里的 `&`
+ * 被 shell 吃掉、`http.server` 没挂 `error` 监听……）。各命令自己复制一份，
+ * 就等于把这些坑再踩一遍，而且**只有其中一份会被修**。
+ *
+ * 与 `defaultOpenBrowserAsync` 的区别：
+ *   * `defaultOpenBrowserAsync` 只管"按多策略打开"，返回原始结果；
+ *   * 本函数是**给命令层用的**：把"注入的假实现（测试里返回 boolean）"与
+ *     "真实现（返回四个字段）"**归一化成同一个状态对象**，并且
+ *     **吞掉任何异常**（打不开浏览器绝不能把命令搞失败 —— 网址已经打印给用户了）。
+ *
+ * @param {string} url 要打开的完整网址
+ * @param {object} [opts]
+ * @param {object} [opts.deps] 运行期依赖 `{ openBrowser, platform, spawnImpl, browserStrategies, browserTimeoutMs, verbose,
+ *                              isTTY, json, forceOpen, noBrowser }`
+ * @param {(msg:string)=>void} [opts.log] 诊断日志（`--verbose` 用）
+ * @returns {Promise<{attempted:boolean, opened:boolean, tried:string[], url:string, skipped_reason:(string|null)}>}
+ */
+export async function openUrlForUser(url, { deps = {}, log = () => {} } = {}) {
+  const target = typeof url === 'string' ? url.trim() : '';
+  /**
+   * ★ 先过**唯一闸门**（见 resolveBrowserIntent）：默认**总是尝试打开**系统浏览器
+   *   （人在终端 ✔ + AI 场景 ✔），只有 `--no-browser` 才不打开。
+   *   ⚠️ 这里是钱包充值那条链路（login 走 runLogin 里的同一个函数），所以两处行为天然一致 ——
+   *      **不允许**在任何命令里自己判断一遍 TTY 再决定要不要 spawn（那就是复制逻辑，
+   *      迟早会出现"授权不弹、支付还弹"这种不一致）。
+   */
+  const intent = resolveBrowserIntent({
+    isTTY: deps.isTTY === true,
+    json: deps.json === true,
+    forceOpen: deps.forceOpen === true,
+    noBrowser: deps.noBrowser === true || deps.openBrowser === false,
+  });
+  if (!intent.allow) {
+    // 不弹窗 ≠ 失败：地址照常由调用方打印/放进 JSON，流程一丝不变
+    return { attempted: false, opened: false, tried: [], url: target, skipped_reason: intent.skipped_reason };
+  }
+  const opener =
+    typeof deps.openBrowser === 'function'
+      ? deps.openBrowser
+      : defaultOpenBrowserAsync(
+          {
+            platform: deps.platform,
+            spawnImpl: deps.spawnImpl,
+            browserStrategies: deps.browserStrategies,
+            browserTimeoutMs: deps.browserTimeoutMs,
+            verbose: deps.verbose === true,
+          },
+          log,
+        );
+  try {
+    return normalizeOpenStatus(await opener(target), target);
+  } catch (e) {
+    // 注入的实现抛错 / 真实现 reject：如实记成"没打开"，命令继续往下走
+    log(`[verbose] 打开浏览器时抛错（已忽略）：${(e && e.message) || e}`);
+    return { attempted: true, opened: false, tried: [], url: target, skipped_reason: null };
+  }
+}
+
+/**
+ * 回一个 HTML 页面。
+ *
+ * 页面本体（成功页 / 各错误页）都在 `./page.mjs` —— 那里是**纯模板**，
+ * 单测可以直接断言文案与体积，不必起 server；本文件只负责"发出去"。
+ *
+ * ⚠️ `Content-Type` 必须显式写 `charset=utf-8`：不写的话浏览器会按**本地
+ *    默认编码**猜（中文 Windows 上常猜成 GBK），而这个页面**通篇是中文**，
+ *    猜错就是整页乱码 —— 比白屏还糟（用户以为授权坏了）。
+ * ⚠️ `Cache-Control: no-store`：回调 URL 里带着一次性授权码，
+ *    绝不能被浏览器缓存、也不该留在历史里。
+ */
+function sendHtml(res, status, page) {
+  res.writeHead(status, {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Cache-Control': 'no-store',
+    'Content-Length': Buffer.byteLength(page.html),
+  });
+  res.end(page.html);
+}
+
+/**
+ * 跑一次登录。
+ * @param {object} args
+ * @param {object} args.config  已生效的配置（base/clientId/scope/credentialsFile/callback*）
+ * @param {(msg:string)=>void} args.log
+ * @param {object} [args.deps]  { fetchImpl, openBrowser, now, listenPort, callbackFirstWaitMs,
+ *                                spawnImpl, platform, onAuthorizationUrl, proxyRisk,
+ *                                ★ isTTY, json, forceBrowser, noBrowser —— 见 resolveBrowserIntent(),
+ *                                ★ handoff, postDeviceGraceMs —— 见下 }
+ *   ★ `isTTY` / `json` / `forceBrowser`（`--open-browser`）/ `noBrowser`（`--no-browser`）四个字段
+ *     决定"要不要替用户弹系统浏览器"：★ **默认总是尝试打开**（人在终端与 AI 场景都一样），
+ *     只有 `noBrowser`（`--no-browser`）才不打开；`isTTY` / `json` 现在只影响 `mode` 这个诊断字段
+ *     ——理由见 resolveBrowserIntent()。
+ *   `callbackFirstWaitMs` —— ★ 首轮等待窗口（默认 `DEFAULT_CALLBACK_FIRST_WAIT_MS` = 180 秒；
+ *   传 0 或负数 = 关掉自愈，只等整段 `loginTimeoutMs`）。命令层会把它透传进来
+ *   （**只有检测到系统代理时才给非 0**，见 `commands/auth.mjs` 的 resolveCallbackFirstWaitMs），
+ *   单测则用短窗口（例如 400ms）来验证"自动改设备码"这条分支，不必真的等 180 秒。
+ *   ★★ `handoff` —— **「回调 / 设备码两条路并存」的交接面**（2026-10-03 修 ERR_CONNECTION_REFUSED 时加的）。
+ *     调用方（命令层）传一个**可变对象**，两边各填一半：
+ *       * 调用方**先**填 `handoff.onSwitch(reason)` —— 首轮等待/整段超时到点时会被调用
+ *         （`reason` 是 `'callback_first_wait'` 或 `'callback_timeout'`），它应当去启动设备码那条路，
+ *         **不要**在这里结束回调这条路：本地监听由本函数继续持有；
+ *       * 本函数填 `handoff.finishWithDevice(result)` / `handoff.abort(error)` ——
+ *         设备码那条路先拿到令牌时调前者（本函数据此收尾，并给"迟到的回调"回一张已完成页），
+ *         设备码那条路也失败时调后者（本函数用这个错误结束等待）。
+ *     ⚠️ **没传 `handoff`（或 `onSwitch` 不是函数）= 旧契约**：到点直接抛 `callback_first_wait` /
+ *        `timeout` 并在 `finally` 里关掉监听（既有的 runLogin 级单测走的就是这条，语义不许变）。
+ *   `postDeviceGraceMs` —— 设备码先成功后，本地监听再多留多久（默认 `DEFAULT_POST_DEVICE_GRACE_MS`；
+ *     只对"首轮等待"这条自愈生效；单测注入小值即可确定性地验证"迟到的回调拿到已完成页"）。
+ */
+export async function runLogin({ config, log = () => {}, deps = {} }) {
+  const fetchImpl = deps.fetchImpl || globalThis.fetch;
+  /**
+   * ⚠️ 这里必须用 `!== false` 显式判断，不能写 `deps.openBrowser || 默认实现` ——
+   *    后来加 `--no-browser` 时传的就是 `openBrowser: false`，`false || 默认` 会**打开浏览器**，
+   *    等于开关失效（经典 `||` 陷阱）。同时支持注入一个函数用于测试。
+   *
+   * ★ 2026-10-01 起：`deps.openBrowser === false` 只是"用户主动关掉"这一种情况；
+   *   **要不要弹系统浏览器**这件事统一由 `resolveBrowserIntent()` 裁决 ——
+   *   ★ 老板最终拍板走**传统路线**：**默认总是尝试打开**（AI 场景也打开），
+   *     只有 `--no-browser` 才不打开（见 resolveBrowserIntent 的说明）。
+   */
+  const browserIntent = resolveBrowserIntent({
+    isTTY: deps.isTTY === true,
+    json: deps.json === true,
+    forceOpen: deps.forceBrowser === true,
+    noBrowser: deps.openBrowser === false || deps.noBrowser === true,
+  });
+  /**
+   * ★★ 最终是否自动打开系统浏览器 = **唯一闸门**的结论。
+   *
+   * ★ 本次变更（老板最终拍板）：「**总是尝试打开**」重新成为默认 ——
+   *   人在终端 ✔、AI 场景（非 TTY / `--json`）✔ 都打开；`json` / `isTTY` **不再**是"不打开"的理由。
+   *   唯一的"不打开"开关是 `--no-browser`（AI 端不想弹窗就用它）。
+   *   为什么回到传统路线（原话）：
+   *     「还是返回以前那种打开跳到一个浏览器，然后打开授权那个吧，大家也都是那个的。
+   *       我们在右侧这个……能力还不会太完善……还是走传统的路吧。」
+   *   ⇒ 稳定（成熟的系统启动器）+ `window.close()` 在独立浏览器里生效（页面能自己关）。
+   * ⚠️ 无论哪种情况，**绝不**因为"没打开浏览器"让登录失败 —— 地址一直完整打印，回调照旧等。
+   */
+  const shouldOpenBrowser = browserIntent.allow;
+  /**
+   * 默认实现走 `defaultOpenBrowserAsync(deps, log)`：**异步多策略**版 —— 把
+   * `deps.spawnImpl` / `deps.platform`（以及测试用的 `browserStrategies` /
+   * `browserTimeoutMs`）透传给 `openInBrowserWithFallback`，逐条策略等结果，
+   * 拿得到"试过哪几条、最后成没成"（`--json` 的 `open_browser` 字段就是它）。
+   *
+   * ⚠️ 注意这里和 `device.mjs` 用的 `defaultOpenBrowser`（同步版）是**两个**函数：
+   *    device 那条链路不在本次改动范围内，不能改它的同步 boolean 契约。
+   */
+  const openBrowser =
+    typeof deps.openBrowser === 'function'
+      ? deps.openBrowser
+      : defaultOpenBrowserAsync({ ...deps, verbose: deps.verbose === true || config.verbose === true }, log);
+  const now = deps.now || (() => Date.now());
+  /** 回调地址在真正 listen 之后才知道端口；handler 里要用，所以先声明 */
+  let redirectUri = '';
+  const api = createApi({ config, fetchImpl });
+  /**
+   * 代理风险（命令层探测后经 `deps.proxyRisk` 透传进来）。
+   *
+   * ⚠️ 为什么**不在这里**自己探测：探测只需要做一次（runtime 里做了记忆化），
+   *    而命令层必须在本流程**开始之前**就拿到结论（先提示、甚至直接改走设备码）。
+   *    这里只是把同一份结论织进"回调没等到"的错误提示里 —— 那是老板报的那个故障的现场。
+   */
+  const proxyHint = proxyRiskHint(deps.proxyRisk, { cmdName: config.cmdName || 'wkgeo' });
+
+  /* ---- 1. 发现授权端点（metadata）---- */
+  let metadata = null;
+  try {
+    metadata = await api.metadata();
+  } catch (e) {
+    // metadata 拉不到不算致命：用兜底地址继续（但要如实告知）
+    log(`⚠️ 读取授权服务器元数据失败（${e.message}），改用内置默认授权地址继续`);
+  }
+
+  let authorizeBase = (metadata && metadata.authorization_endpoint) || `${config.oauthWebBase}/oauth/authorize`;
+  // 线上曾经返回 http://localhost:8000/...（云函数默认值没配环境变量）。
+  // 那种地址打开的是**用户自己机器**的端口 → 第一步就断，必须纠正。
+  // ★ 2026-10-02（三站拆分）：纠偏目标改成**授权站子域** `config.oauthWebBase`。
+  // 顺带加一条守卫：host 不属于本平台域名（*.wkgeo.com / *.wkongai.cn）的一律纠偏 ——
+  // 服务端配置写错域名时，比"打开一个陌生站点"更安全的做法是用内置默认值。
+  const 本平台授权域 = /^https?:\/\/[^/]*\.(wkgeo\.com|wkgeo\.cn)(:\d+)?\//i;
+  if (
+    /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?/i.test(String(authorizeBase)) ||
+    !本平台授权域.test(String(authorizeBase))
+  ) {
+    log(
+      `⚠️ 服务端返回的授权地址不是本平台域名（${authorizeBase}），已改用 ${config.oauthWebBase}/oauth/authorize`,
+    );
+    authorizeBase = `${config.oauthWebBase}/oauth/authorize`;
+  }
+
+  /**
+   * ★ 授权页地址**从构造时就带尾斜杠**（`/admin/oauth/authorize/?client_id=…`）。
+   *
+   * 为什么：前端是静态导出（每个路由一个目录），托管侧（OSS 静态托管 / 阿里云 ESA）
+   * 对**不带尾斜杠**的目录路径会 302，而那个 302 **不携带 query** ——
+   * 授权参数会在任何 JS 执行之前就被丢光，页面显示「授权请求不完整」。
+   * 这里对**两种来源**都做一次归一化（服务端 metadata 给的 + 我们自己拼的兜底地址）：
+   *   * 线上 metadata 已修好、会返回带斜杠的地址 → 这一步是无副作用的兜底（不拼出 `//`）；
+   *   * 但不能假设服务端配置永远正确（本项目真被 `authorization_endpoint` 配成本机地址坑过一次），
+   *     客户端多做一道是**便宜且必要**的防御。
+   * 收口在 `config.mjs` 的 `withTrailingSlash()`（唯一构造入口，有单测钉住）。
+   */
+  authorizeBase = withTrailingSlash(authorizeBase);
+
+  const ttlSec = Number(metadata && metadata.access_token_ttl_seconds);
+  const onExpiry = (metadata && metadata.on_token_expiry) || 'reauthorize';
+
+  /* ---- 2. PKCE + state ---- */
+  const verifier = createVerifier();
+  const challenge = challengeOf(verifier);
+  const state = createState();
+
+  /* ---- 3. 起本地回调服务（只监听 127.0.0.1）---- */
+  let resolveFlow;
+  let rejectFlow;
+  const flow = new Promise((resolve, reject) => {
+    resolveFlow = resolve;
+    rejectFlow = reject;
+  });
+  /**
+   * ⚠️ 这里挂一个空 catch 是**必须**的：
+   *    `finish()` 可能在调用方 `await flow` **之前**就 reject（比如换票失败发生在 HTTP 回调里，
+   *    而调用方此刻还在 await fetch）。Node 16+ 对"无人处理的 rejection"会直接崩进程，
+   *    单测里就表现为"login：换票失败"这条用例莫名其妙地失败。
+   *    挂一个空 catch 只是加一个旁观者，不影响后面正常的 await（仍然会抛）。
+   */
+  flow.catch(() => {});
+
+  let settled = false;
+  let server;
+  let timer = null;
+  /** ★ 首轮等待定时器（见 DEFAULT_CALLBACK_FIRST_WAIT_MS）：到点 → 让命令层改走设备码 */
+  let firstWaitTimer = null;
+  /**
+   * ★★ 交接面（见 deps.handoff 的说明）：命令层传进来的可变对象，两边各填一半。
+   *   `onSwitch` 由命令层填（到点时启动设备码那条路），`finishWithDevice` / `abort` 由这里填。
+   *   ⚠️ `canHandoff === false`（没传/形状不对）= 保持旧契约：到点直接抛错并关监听。
+   */
+  const handoff = deps.handoff && typeof deps.handoff === 'object' ? deps.handoff : null;
+  const canHandoff = !!(handoff && typeof handoff.onSwitch === 'function');
+  /** 这次自愈是被哪个窗口触发的（只有 `callback_first_wait` 才留 grace，见 DEFAULT_POST_DEVICE_GRACE_MS） */
+  let switchReason = null;
+  /** 设备码那条路**已经**拿到令牌（命令层调 handoff.finishWithDevice 之后为 true） */
+  let deviceDone = false;
+  let deviceResult = null;
+  /** 设备码先成功后，本地监听"再活多久"（毫秒）；0 = 立刻收尾 */
+  let postGraceMs = 0;
+  let graceTimer = null;
+
+  const finish = (err, value) => {
+    if (settled) return;
+    settled = true;
+    if (timer) clearTimeout(timer);
+    if (firstWaitTimer) clearTimeout(firstWaitTimer);
+    if (graceTimer) clearTimeout(graceTimer);
+    if (err) rejectFlow(err);
+    else resolveFlow(value);
+  };
+
+  /** 关掉本地监听（grace 结束后或被"迟到的回调"提前唤醒时用） */
+  const closeServer = () =>
+    new Promise((resolve) => {
+      try {
+        // ⚠️ 浏览器可能用 keep-alive 挂着连接，`close()` 会一直等它 —— 直接掐断更干脆
+        if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+        server.close(() => resolve());
+      } catch {
+        resolve();
+      }
+    });
+
+  /**
+   * ★★ 设备码那条路**先**拿到令牌 → 这里收尾（真机证据与取舍见 DEFAULT_POST_DEVICE_GRACE_MS）。
+   *
+   * 关键点：**不立刻关监听**，而且**不 await** —— 命令层要马上拿到结果去打印"授权成功"，
+   * 本地监听在后台再活 `postGraceMs`（或被一次迟到的回调提前唤醒，见 handler 里的 `deviceDone` 分支）。
+   */
+  if (handoff) {
+    handoff.finishWithDevice = (result) => {
+      if (settled) return;
+      deviceDone = true;
+      deviceResult = result;
+      // 令牌已经到手：这两个窗口的定时器都不再有意义（否则它们会在 grace 期间把流程判成失败）
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (firstWaitTimer) {
+        clearTimeout(firstWaitTimer);
+        firstWaitTimer = null;
+      }
+      postGraceMs = switchReason === 'callback_first_wait' ? Number(deps.postDeviceGraceMs ?? DEFAULT_POST_DEVICE_GRACE_MS) : 0;
+      if (!Number.isFinite(postGraceMs) || postGraceMs < 0) postGraceMs = 0;
+      finish(null, result);
+    };
+    /** 设备码那条路也没走通 → 用命令层给的"两条路都不通"错误结束等待（见 commands/auth.mjs） */
+    handoff.abort = (err) => finish(err);
+  }
+
+  /**
+   * ★ 把"回调这条路没等到结果"**交接**给命令层（只通知、不结束、**不关监听**）。
+   *
+   * 文案与旧版保持一致的关键词（`没收到回调` / `本地回调没有等到结果` / `已自动改用`），
+   * 既有单测与排障文档按这些字样检索；新增的只有"监听继续保留"这句 —— 那正是本次修复的核心。
+   */
+  const handOff = (reason) => {
+    if (settled || switchReason) return;
+    switchReason = reason;
+    const 原因 = reason === 'callback_first_wait' ? '首轮等待没收到回调' : '等待超时';
+    log('');
+    log(`⚠️ 本地回调没有等到结果（${原因}）：已自动改用【设备码模式】继续（不需干等，两条路并行）。`);
+    log(
+      'ℹ️ 本机回调监听**继续保留**：如果你之后才在浏览器里点【同意授权】，那一次照样能直接完成登录' +
+        '（不会再出现"连接被拒绝 / ERR_CONNECTION_REFUSED"）。',
+    );
+    try {
+      handoff.onSwitch(reason);
+    } catch (e) {
+      // 交接失败不能让"回调这条路"跟着崩：它还在正常等回调，用户还有机会成功
+      log(`[verbose] 交接给设备码那条路时出错（已忽略，回调这条路继续等）：${(e && e.message) || e}`);
+    }
+  };
+
+  server = http.createServer(async (req, res) => {
+    // 只管回调路径；其它路径（比如浏览器自动请求 /favicon.ico）一律 404，避免误判
+    let parsed;
+    try {
+      parsed = new URL(req.url, `http://${req.headers.host || '127.0.0.1'}`);
+    } catch {
+      res.writeHead(400).end('bad request');
+      return;
+    }
+    if (parsed.pathname !== config.callbackPath) {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('not found');
+      return;
+    }
+    if (req.method !== 'GET') {
+      sendHtml(
+        res,
+        405,
+        errorPage({
+          tone: 'warn',
+          heading: '方法不允许',
+          reason: '这个回调地址只接受浏览器直接打开的 GET 请求（收到了 ' + req.method + '）。',
+          hint: '请把终端里打印的那一整行授权网址复制到浏览器地址栏打开。',
+        }),
+      );
+      return;
+    }
+
+    /**
+     * ★★ 设备码那条路**已经拿到令牌**了 ⇒ 这一次回调只是"用户后来才点的同意"。
+     *
+     * 真机证据（老板 2026-10-03 反馈的连带缺陷）：旧逻辑在切设备码时**关掉了本地回调监听**，
+     * 于是用户随后点【同意授权】时浏览器跳到 `http://127.0.0.1:<port>/callback?code=…`
+     * 得到 **ERR_CONNECTION_REFUSED** —— 用户会以为授权失败（而他其实已经登录成功了）。
+     * 现在监听还开着，所以这里**必须**给一张友好的"已完成"页，而**不是**任何错误页。
+     *
+     * 🔴 两条硬约束：
+     *   1. **不要**拿这个 code 去换票：凭据已经由设备码那条路写好，再换一次等于同一份授权重复签发
+     *      （多一份令牌，还可能把刚写好的凭据覆盖掉）；
+     *   2. 这一页**不回显** code，也不出现任何令牌（与其它页同一条安全底线）。
+     */
+    if (deviceDone) {
+      sendHtml(res, 200, alreadyDonePage(deviceResult && deviceResult.account));
+      // 页面已经交给浏览器了：grace 不必再等，监听立刻收尾
+      if (graceTimer) {
+        clearTimeout(graceTimer);
+        graceTimer = null;
+      }
+      closeServer();
+      return;
+    }
+
+    const gotState = parsed.searchParams.get('state');
+    const code = parsed.searchParams.get('code');
+    const err = parsed.searchParams.get('error');
+    const errDesc = parsed.searchParams.get('error_description');
+
+    // ★ state 校验：**服务端原样回传但不校验**，防 CSRF/串号是客户端自己的责任。
+    //   不匹配就拒绝这一条，但**不结束流程**（可能是别人瞎打的），等真正的回调。
+    if (!gotState || !safeEqual(gotState, state)) {
+      /**
+       * ⚠️ 大标题保留「state 校验失败」这句原文：它是本文件的**契约字样**，
+       *    `test/login.test.mjs` 用它分辨"这条分支被走到了"，
+       *    外部排障文档也按这句话搜索。改样式可以，改这句话不行。
+       */
+      sendHtml(
+        res,
+        400,
+        errorPage({
+          tone: 'warn',
+          heading: 'state 校验失败',
+          reason: '这次回调带的 state 与本次登录不一致，已忽略（可能是别人误打进来的请求）。',
+          hint: '如果终端还在等待授权，请回到浏览器重新走一次同意页；已重新点过同意的话，回终端重跑一次即可。',
+        }),
+      );
+      return;
+    }
+
+    if (err) {
+      const hint = err === 'access_denied' ? '你（或页面上的人）点了「拒绝」。' : `服务端返回错误：${err}`;
+      sendHtml(
+        res,
+        200,
+        errorPage({
+          tone: 'warn',
+          heading: '授权未完成',
+          reason: hint,
+          hint: '没有拿到授权码，也没有写入任何凭据。',
+          /**
+           * ⚠️ 这一页**不自动关闭**，哪怕它已经是终态（下面 `finish(...)` 会带着错误结束等待）。
+           *    两个理由：
+           *      1. 用户可能想看清"到底为什么没成"（拒绝了？还是服务端报错？）；
+           *      2. 阿里云 `mcp-remote` 那套的教训 —— 它在**刚收到 code** 就替用户宣告成功并
+           *         `window.close()`，而此刻令牌还没换（后面才 POST token 端点）；一旦换票失败，
+           *         用户已经被打发走了，只剩一个"我刚才是不是失败了"的疑惑。
+           *    所以本项目的口径是：**只有"真的把凭据写进本机"之后的那张成功页**才尝试自动关，
+           *    其余页面（含本页）一律留在屏幕上让人看完。见 `page.mjs` 里 AUTO_CLOSE_SCRIPT 的注释。
+           */
+        }),
+      );
+      finish(new CliError(err === 'access_denied' ? '用户拒绝了本次授权' : `授权失败：${err}${errDesc ? ' — ' + errDesc : ''}`, {
+        kind: err === 'access_denied' ? 'denied' : 'authz_error',
+        code: err,
+        hint: '没有拿到授权码，未写入任何凭据',
+        exitCode: EXIT.AUTH,
+      }));
+      return;
+    }
+
+    if (!code) {
+      sendHtml(
+        res,
+        400,
+        errorPage({
+          tone: 'warn',
+          heading: '缺少授权码',
+          reason: '回调地址里没有 code 参数，无法继续换票。',
+          hint: '通常说明授权页那边没走完（或被手工改过地址）。',
+        }),
+      );
+      return;
+    }
+
+    // 用 code 换 token（先换再回页面，页面才能如实显示成功/失败）
+    try {
+      const tokenResponse = await api.token({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: config.clientId,
+        code_verifier: verifier,
+      });
+
+      let account = null;
+      try {
+        account = await api.userinfo(tokenResponse.access_token);
+      } catch {
+        // 身份信息拿不到不影响"已经登录"这个事实（权限收敛在服务端，不依赖它）
+      }
+
+      const credentials = credentialsFromToken({
+        clientId: config.clientId,
+        tokenResponse,
+        account,
+        scope: config.scope,
+        now: now(),
+      });
+      const mode = writeCredentials(config.credentialsFile, credentials, { now: now() });
+
+      /**
+       * ⚠️ 成功页只吃 `account`（邮箱/昵称/脱敏手机号），**绝不**把
+       *    `tokenResponse` 传进去 —— 那是"页面里不出现令牌"这条红线的实现方式：
+       *    模板没有接收令牌的位置，就不可能漏出去。
+       *
+       * ⚠️ **顺序是有约束的，别调换**：必须先 `await api.token(...)` 换到令牌、
+       *    再 `writeCredentials(...)` 落盘，**最后**才回这张成功页 ——
+       *    因为成功页会尝试自动关掉标签页（见 page.mjs 的 AUTO_CLOSE_SCRIPT）。
+       *    阿里云那套正是在"刚收到 code、还没换票"时就回了成功页并关窗，
+       *    于是换票失败时用户已被打发走、还被告知"成功"（那个坑别踩）。
+       *    我们这里失败一律走下面的 catch → 换票失败页（**不自动关闭**，原因留在屏幕上）。
+       */
+      sendHtml(res, 200, successPage(account));
+
+      finish(null, { credentials, account, mode, metadata });
+    } catch (e) {
+      const msg = (e && e.message) || String(e);
+      /**
+       * ⚠️ 失败原因来自服务端/网络层，可能夹带用户不可控的内容 ——
+       *    `errorPage` 内部会做 HTML 转义（见 page.mjs 的安全底线 4）。
+       * ⚠️ 这里**只放原因**，不放任何凭据：换票失败时服务端的响应体里
+       *    可能带 `error_description`，但绝不会带明文令牌（签发成功才会走上面那条路）。
+       */
+      sendHtml(res, 500, errorPage({ heading: '换取令牌失败', reason: msg, hint: '没有写入任何凭据。' }));
+      finish(e instanceof CliError ? e : new CliError(`换取令牌失败：${msg}`, { kind: 'token_exchange', hint: '重新运行 `wkgeo login`' }));
+    }
+  });
+
+  const listenOn = (port) =>
+    new Promise((resolve, reject) => {
+      const onError = (e) => {
+        server.removeListener('listening', onListening);
+        reject(e);
+      };
+      const onListening = () => {
+        server.removeListener('error', onError);
+        resolve(server.address());
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      // ⚠️ 只绑 127.0.0.1：绑 0.0.0.0 等于把授权码暴露给同网段任何人
+      server.listen(port, config.callbackHost);
+    });
+
+  let bound;
+  try {
+    bound = await listenOn(deps.listenPort ?? config.callbackPort);
+  } catch (e) {
+    if (e && e.code === 'EADDRINUSE') {
+      log(`端口 ${config.callbackPort} 被占用，改用随机回环端口（服务端按 RFC 8252 忽略端口，仍能回调成功）`);
+      bound = await listenOn(0);
+    } else {
+      throw new CliError(`无法在 ${config.callbackHost} 上监听回调端口：${e.message}`, {
+        kind: 'listen',
+        hint: `检查防火墙/端口占用，或用 --callback-port 指定其它端口${proxyHint ? `。另外：${proxyHint}` : ''}`,
+        cause: e,
+      });
+    }
+  }
+  const actualPort = bound.port;
+  redirectUri = `http://${config.callbackHost}:${actualPort}${config.callbackPath}`;
+  const authUrl = new URL(authorizeBase);
+  authUrl.searchParams.set('client_id', config.clientId);
+  authUrl.searchParams.set('redirect_uri', redirectUri);
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('scope', config.scope);
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('code_challenge', challenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+
+  /* ---- 4. 交给用户 ---- */
+  // 授权网址必须**同时**以人类可读文本（走 log，JSON 模式下命令层会把它转到 stderr）
+  // 和机器可读 JSON（走 onAuthorizationUrl 回调）输出 —— AI 端要拿到链接交给用户点。
+  log('');
+  log('请在浏览器中完成授权（设备码/回调模式都是同一条授权页；未登录会先让你登录）：');
+  log('');
+  log(`  ${authUrl.toString()}`);
+  log('');
+  if (shouldOpenBrowser) {
+    log('如果浏览器没有自动打开，请把上面这一整行复制到浏览器地址栏打开。');
+  }
+  /**
+   * ★ 2026-10-02（老板）：授权成功后**那个页面会自己关掉** —— 提前交代一句，
+   *   否则用户会一直等一个其实已经结束的页面，或者回去找那个标签页。
+   *   ⚠️ "没关就手动关掉即可"**不能省**：`window.close()` 只对**脚本打开的**窗口有效，
+   *      本页是用户自己点开的标签页 ⇒ 大概率关不掉，那句话就是兜底。
+   *   ★ 现在对**所有**路径都打（`--no-browser` / 打开成功 / 打开失败都一样）——
+   *      B 路线（内置浏览器）暂停后不再有"只给 AI 场景打提示"的分支。
+   */
+  log('（授权成功后页面会自动尝试关闭；没关就手动关掉即可。）');
+
+  /**
+   * 自动打开浏览器：**多策略依次尝试**（策略表见文件顶部的 BROWSER_STRATEGY_TABLE）。
+   *
+   * ⚠️ 打开失败**绝不允许**让 login 失败：地址已经完整打印在上面（那一整行），
+   *    手动复制照样能走完流程。所以连"注入的 openBrowser 抛错 / 返回 rejected Promise"
+   *    都要在这里吞掉 —— 以前不 await，注入的异步实现 reject 会变成 unhandledRejection
+   *    直接把进程崩掉，比"打不开浏览器"严重得多。
+   *
+   * ⚠️ 顺序是刻意的：先在**人类可读那一段**里打印完整网址，再尝试打开，再打印结果。
+   *    这样哪怕打开很慢（多策略逐条超时，最坏十几秒），用户第一眼也已经看到网址了。
+   *    代价是 `--json` 的 `awaiting_callback` 事件要等打开动作结束才发出去 —— 值得，
+   *    因为 AI 端要靠事件里的 `open_browser` 判断"到底要不要催用户手动打开"。
+   */
+  let openStatus = {
+    attempted: false,
+    opened: false,
+    tried: [],
+    url: authUrl.toString(),
+    // ★ 现在只可能因为 `--no-browser` 不尝试（`non_tty_agent_mode` 已随老板拍板走传统路线而弃用）
+    skipped_reason: browserIntent.skipped_reason,
+  };
+  if (shouldOpenBrowser) {
+    try {
+      /**
+       * `await` 是必须的：注入的同步实现返回 boolean（`await` 一个非 Promise 就是它本身），
+       * 生产默认实现（`defaultOpenBrowserAsync`）返回上面那四个字段。
+       */
+      openStatus = normalizeOpenStatus(await openBrowser(authUrl.toString()), authUrl.toString());
+    } catch (e) {
+      // 打开浏览器**永不允许**把登录搞失败：如实记成"没打开"，继续等回调
+      openStatus = { attempted: true, opened: false, tried: [], url: authUrl.toString(), skipped_reason: null };
+      log(`[verbose] 打开浏览器时抛错（已忽略，继续等回调）：${(e && e.message) || e}`);
+    }
+  }
+  if (!shouldOpenBrowser) {
+    // ⚠️ 只有"--no-browser"才打这一行（用户主动关掉的，不该报"失败"）
+    if (browserIntent.skipped_reason === 'no_browser') log('（已按 --no-browser 跳过自动打开）');
+  } else if (openStatus.opened) {
+    // ★ 成功：明说"已经打开了"，并告诉用户去那里做什么（老板最终拍板走传统路线）
+    log(browserOpenedText({ kind: 'auth' }));
+  } else {
+    /**
+     * 全部策略都失败时的提示：`browserFailedHintLines()` 统一了三条硬要求
+     * —— 醒目（`⚠️`）、**自带完整 URL**、说清打开之后干什么；
+     * AI 场景（非 TTY / `--json`）再多一句"客户端支持内置浏览器也可以在那里打开"的可选提示。
+     * 真客户不会自己去找网址，所以这段是"自动打开失败"时唯一能救回流程的东西。
+     */
+    for (const line of browserFailedHintLines(authUrl.toString(), { kind: 'auth', agent: browserIntent.mode === 'agent' })) {
+      log(line);
+    }
+  }
+
+  log(`等待你在浏览器里完成授权…（最多 ${Math.round(config.loginTimeoutMs / 1000)} 秒，Ctrl+C 可取消）`);
+  if (typeof deps.onAuthorizationUrl === 'function') {
+    deps.onAuthorizationUrl(authUrl.toString(), {
+      redirect_uri: redirectUri,
+      timeout_ms: config.loginTimeoutMs,
+      scope: config.scope,
+      client_id: config.clientId,
+      /**
+       * ★ 机器可读的"自动打开"状态：AI 端据此判断"到底要不要催用户手动打开"。
+       *   `authorization_url` 仍然照旧单独给（绝不能因为多了这个字段就把它挤掉）。
+       *   ★ 老板最终拍板走**传统路线**：CLI 默认**总是尝试**打开系统浏览器（AI 场景也一样），
+       *     所以 `skipped_reason` 现在只有两种取值：
+       *       * `null`        = 真的尝试过（成没成看 `opened`）；
+       *       * `"no_browser"` = 调用方/用户明确要求别打开（唯一开关）。
+       *     （历史取值 `"non_tty_agent_mode"` 已弃用，见 resolveBrowserIntent 的注释。）
+       */
+      open_browser: openStatus,
+      /** ★ 给 AI 端"照着念"的一句话（AI 不该自己组织语言，否则容易漏掉网址） */
+      paste_text: browserPasteText(authUrl.toString(), { kind: 'auth' }),
+    });
+  }
+
+  timer = setTimeout(() => {
+    /**
+     * ⚠️ 超时是**老板报的那个故障的现场**：用户在同意页点了「同意」，终端却一直等。
+     *    最常见的原因就是"代理把 127.0.0.1 的回调也接管了"（code 从没打到本地服务）。
+     *    所以检测到代理时，hint 里必须带上"三选一"的可照做指引（第 3 条是设备码模式）。
+     *    （⚠️ 注意：有代理时命令层通常**已经**走设备码了，根本走不到这里；
+     *      能走到这里的情况是"用户在代理下强制回调"或"探测没发现代理但回调仍被别的
+     *      东西挡了 —— 防火墙/安全软件/浏览器插件"。）
+     * ★ 传了 `handoff` 时**不再抛错**：改成通知命令层"并发去跑设备码"，本地监听**保持开着**
+     *   （用户随后才点的那次【同意】照样能成功；见 DEFAULT_CALLBACK_FIRST_WAIT_MS 的真机证据）。
+     */
+    if (canHandoff && !deviceDone) {
+      handOff('callback_timeout');
+      return;
+    }
+    finish(new CliError(`等待授权超时（${config.loginTimeoutMs}ms）`, {
+      kind: 'timeout',
+      hint:
+        '授权码本身只有 5 分钟有效期。请重新运行 `wkgeo login`（浏览器里通常还有登录态，点一下同意即可）' +
+        (proxyHint ? `。另外：${proxyHint}` : ''),
+      exitCode: EXIT.AUTH,
+    }));
+  }, config.loginTimeoutMs);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+
+  /**
+   * ★ 第二条保险：**首轮等待**（默认 180 秒，且只由命令层在"检测到代理"时给非 0 值）没等到回调
+   *   → 主动结束这一轮等待，让命令层自动改用设备码继续（`kind = 'callback_first_wait'`，**不是** `timeout`）。
+   *
+   * 为什么不是在这里直接改走设备码：设备码流程在 `device.mjs` / `commands/auth.mjs`，
+   *   而 `runLogin` 的契约是"要么拿到凭据、要么抛一个说明原因的错误"。
+   *   由命令层统一裁决"这个错要不要降级"更简单，也保证 `finally` 里把本地 server 关干净
+   *   （否则 53682 端口会被自己占着，回落到回调时反而起不来）。
+   *   ⚠️ **2026-10-03 起**：命令层传了 `deps.handoff` 时，上面这条"关干净"的口径变了 ——
+   *      到点**只通知、不关监听**，因为关掉监听正是真机上 ERR_CONNECTION_REFUSED 的成因。
+   *
+   * ⚠️ 只在 `0 < firstWait < loginTimeoutMs` 时挂：否则先撞到的必然是整段超时，
+   *    挂上去只会让两个定时器互相打乱，也让错误信息变得难以理解。
+   */
+  const firstWaitMs = Number(deps.callbackFirstWaitMs ?? DEFAULT_CALLBACK_FIRST_WAIT_MS);
+  if (Number.isFinite(firstWaitMs) && firstWaitMs > 0 && firstWaitMs < config.loginTimeoutMs) {
+    const label = firstWaitMs >= 1000 ? `${Math.round(firstWaitMs / 1000)} 秒` : `${firstWaitMs} 毫秒`;
+    // 提前告知"不用干等"，并说清"监听还会开着"（后者正是本次修复：用户之后点同意也来得及）
+    log(`（如果 ${label}内没收到回调，会自动改用设备码模式继续，不用一直干等；本地回调监听也会继续保留）`);
+    firstWaitTimer = setTimeout(() => {
+      if (canHandoff && !deviceDone) {
+        handOff('callback_first_wait');
+        return;
+      }
+      finish(new CliError(`等待授权回调的前 ${label}没有收到结果`, {
+        kind: 'callback_first_wait',
+        hint:
+          '本地回调在这段时间内没有收到结果；命令层会自动改用设备码模式继续（不需要本地回调，授权页照旧点同意即可）' +
+          (proxyHint ? `。另外：${proxyHint}` : ''),
+        exitCode: EXIT.AUTH,
+      }));
+    }, firstWaitMs);
+    // 与整段超时一致：unref 掉，避免"登录早就结束了，进程还被定时器吊着"
+    if (firstWaitTimer && typeof firstWaitTimer.unref === 'function') firstWaitTimer.unref();
+  }
+
+  // Ctrl+C 时把监听端口关掉再退（否则 53682 会短暂占用）
+  const onSigint = () => {
+    // 令牌已经拿到（设备码那条路先成功）时，Ctrl+C 不该把它判成失败：照旧把结果交出去
+    if (deviceDone) {
+      finish(null, deviceResult);
+      return;
+    }
+    finish(new CliError('用户中断了登录', { kind: 'aborted', exitCode: 130 }));
+  };
+  process.once('SIGINT', onSigint);
+
+  try {
+    const result = await flow;
+    return {
+      ...result,
+      redirectUri,
+      tokenTtlSeconds: ttlSec,
+      onTokenExpiry: onExpiry,
+      metadata,
+    };
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+    if (deviceDone && postGraceMs > 0) {
+      /**
+       * ★★ 设备码先成功时**不马上关监听**（见 DEFAULT_POST_DEVICE_GRACE_MS）：
+       *   用户可能还在那个授权页上，他之后点【同意】时不该看到 ERR_CONNECTION_REFUSED。
+       *   ⚠️ 这里刻意**不 await**：调用方要立刻拿到结果去打印"授权成功"；
+       *      监听与 grace 定时器在后台再活一小会儿，到点（或被那次迟到的回调提前唤醒）自行关闭。
+       *      定时器 unref 掉不吃事件循环 —— 让进程活下来的是 server 本身，关掉它进程就退出了。
+       */
+      graceTimer = setTimeout(() => {
+        graceTimer = null;
+        closeServer();
+      }, postGraceMs);
+      if (graceTimer && typeof graceTimer.unref === 'function') graceTimer.unref();
+    } else {
+      await closeServer();
+    }
+  }
+}