@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/bin/gotry-bootstrap.js

@@ -0,0 +1,1788 @@
+#!/usr/bin/env node
+/**
+ * gotry 外部依赖自举(founder 2026-08-29 指令:安装 gotry 时按上游本身的方式装好外部依赖):
+ *   hbcli(hotelbyte-cli)  → npm 优先(staicli@npmjs;Node ≥ 20),原生二进制 install.sh 兜底
+ *   agent-reach            → 官方 pip 安装 git+ upstream(包内 .venv,与 z3-solver 同址原则)
+ *   flyai                  → 无需安装(npx 每次自拉 @fly-ai/flyai-cli)
+ *   dsh-better-sidebar     → dsh 宿主层插件市场组件(dshmarket.com #1 UI,18.9 万周装):
+ *                           dsh web 侧栏工作台(文件浏览/Markdown/Mermaid/PDF 预览)——
+ *                           gotry 产物(工单交付 md/行程 md)的成熟查看面(issue #25)。
+ *                           宿主层安装(dsh plugin → ~/.dsh/profiles/web),不进 gotry 依赖。
+ *   gotry-session-bridge   → 会话检索浏览器扩展(issue #21 传输层方案 C,2026-08-29 定案):
+ *                           一次性安装替代逐连接 CDP 弹窗;已上架 Chrome Web Store
+ *                           (2026-09-02,一键装+自动更新)。**gory 不介入浏览器**——
+ *                           商店页安装是浏览器的事;`gotry setup wizard` 仅作离线检测的
+ *                           进程护栏(打印商店 URL + 健康探活等待),不动剪贴板、
+ *                           不弹 osascript、不 open 浏览器。
+ *
+ * 用法:
+ *   node bin/gotry-bootstrap.js              # 显式安装(缺啥装啥;失败 exit 1)
+ *   node bin/gotry-bootstrap.js --auto       # postinstall 模式:CI/跳过开关检测,任何失败不挡安装(exit 0)
+ *   node bin/gotry-bootstrap.js --check-only # 只探测报告,不安装(测试钩子)
+ *   node bin/gotry-bootstrap.js --extension-from=github
+ *                                           # 扩展改走 GitHub Releases 下载通道(ADR-21):
+ *                                           #   dist-manifest → tar.gz → SHA256 → key 钉扎 → 原子交换;
+ *                                           #   任何失败显式降级回包内副本(离线确定性不变)。
+ *   node bin/gotry-bootstrap.js calendar        # 可选日历挂载开关(D-9,setup 状态面):
+ *                                               #   默认写 ~/.gotry/calendar.json {"enabled":true};
+ *                                               #   --off 删除恢复默认不挂载;--status 只读查看。
+ *   node bin/gotry-bootstrap.js doctor      # 可选依赖体检(2026-09-02 迪拜 session 复盘):
+ *                                           #   扩展/agent-reach/.venv/hbcli/flyai key/sidebar/calendar
+ *                                           #   逐项只读检查 + 精确补装指引;
+ *                                           #   报告落 gotry-state/doctor-report.md(侧栏工作台可预览)。
+ *   node bin/gotry-bootstrap.js doctor --fix # 体检后按缺失项补装(复用下方三个安装器;LLM key 永不管)。
+ *   node bin/gotry-bootstrap.js wizard       # 会话扩展 onboarding 闭环(issue #21 onboarding UX,§3.3):
+ *                                           #   5 步编排 + 后台 health-watch 等扩展心跳,
+ *                                           #   扩展一就位 stdout 翻绿并自动重放同 query。
+ *                                           # 详见 docs/rfc/user-session-data-rfc.md §3.3 / RFC P3.6。
+ *
+ * 环境开关:
+ *   GOTRY_SETUP_SKIP=1            全部跳过
+ *   GOTRY_SETUP_HBCLI=0           跳过 hbcli
+ *   GOTRY_SETUP_REACH=0           跳过 agent-reach
+ *   GOTRY_SETUP_SIDEBAR=0         跳过 dsh-better-sidebar
+ *   GOTRY_SETUP_EXTENSION=0       跳过会话检索扩展落位
+ *   GOTRY_EXTENSION_SOURCE=github 等效 --extension-from=github(显式 opt-in,默认 bundled)
+ *   GOTRY_EXTENSION_RELEASE_BASE=<url> 下载通道基址覆盖(镜像/测试;缺省 GitHub 官方)
+ *   GOTRY_ONBOARDING_HEADLESS=1   wizard 仅 stdout(SSH/CI 默认探测)
+ *
+ * 设计纪律(wizard 子命令,2026-09-02 商店上架后):
+ * **浏览器自己当安装器**——浏览器商店页直达,点「添加至 Chrome」即完事;gotry
+ * 不扮演 GUI/CLI 越界者:不动剪贴板、不动 osascript/zenity/msg、不 open 浏览器。
+ * dsh host UI 是 gotry 工具渲染面,needs-extension 时 URL 走 verdict 字段给 UI
+ * 自渲。wizard 子命令退化为「离线健康探活等待」,只输出 stdout,不挡用户。
+ */
+
+import { spawn } from 'node:child_process'
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { createHash } from 'node:crypto'
+
+// ── FlyAI 凭据面(纯 JS 内联;与 ts/capabilities/flyai-config.ts 成对维护,
+// 口径以官方 @fly-ai/flyai-cli 1.0.16 解包事实为准。bootstrap 由 inner 以
+// plain node spawn,不能 import .ts——同 doctorChecks 的既有成对模式)──────
+
+function flyaiNonEmpty(value) {
+  if (typeof value !== 'string') return undefined
+  const text = value.trim()
+  return text || undefined
+}
+function flyaiConfigFile() { return join(homedir(), '.flyai', 'config.json') }
+function flyaiVerificationFile() { return join(homedir(), '.gotry', 'flyai-verification.json') }
+
+function readFlyaiConfigObject() {
+  const path = flyaiConfigFile()
+  if (!existsSync(path)) return { ok: true, data: {} }
+  let text
+  try { text = readFileSync(path, 'utf8') } catch (e) { return { ok: false, error: e.message } }
+  if (!text.trim()) return { ok: true, data: {} }
+  try {
+    const parsed = JSON.parse(text)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, error: 'config 顶层不是 JSON 对象' }
+    }
+    return { ok: true, data: parsed }
+  } catch {
+    return { ok: false, error: 'config JSON 解析失败（为保护凭据，不显示原文）' }
+  }
+}
+
+/** 官方 1.0.16 同优先级:FLYAI_API_KEY → DEBUG_FLYAI_API_KEY → config 文件 → none */
+function resolveFlyaiKeyInline() {
+  const configPath = flyaiConfigFile()
+  const envKey = flyaiNonEmpty(process.env.FLYAI_API_KEY)
+  if (envKey) return { key: envKey, source: 'env', configPath }
+  const debugKey = flyaiNonEmpty(process.env.DEBUG_FLYAI_API_KEY)
+  if (debugKey) return { key: debugKey, source: 'env-debug', configPath }
+  const read = readFlyaiConfigObject()
+  const fileKey = read.ok ? flyaiNonEmpty(read.data.FLYAI_API_KEY) : undefined
+  if (fileKey) return { key: fileKey, source: 'config', configPath }
+  return { source: 'none', configPath }
+}
+
+function resolveFlyaiEndpointInline() {
+  const debugUrl = flyaiNonEmpty(process.env.DEBUG_FLYAI_MCP_URL)
+  if (debugUrl) return { url: debugUrl, debug: true }
+  return { url: 'https://flyai.open.fliggy.com/mcp', debug: false }
+}
+
+function maskFlyaiKeyInline(key) {
+  const text = typeof key === 'string' ? key.trim() : ''
+  if (!text) return ''
+  if (text.length <= 4) return '****'
+  return `****${text.slice(-4)}`
+}
+
+function isPlaceholderFlyaiKeyInline(key) {
+  const text = key.trim().toLowerCase()
+  if (!text) return true
+  return /^(your?-?(key|api[._-]?key)|xxxx+|<[^>]+>|sk-[a-z]*$|test|placeholder|changeme|foo|bar)$/.test(text)
+}
+
+function sha256Inline(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex')
+}
+
+function normalizeEndpointInline(url) {
+  try {
+    return new URL(url).href
+  } catch { return undefined }
+}
+
+function endpointFingerprintInline(url) {
+  const normalized = normalizeEndpointInline(url)
+  return normalized ? sha256Inline(normalized) : undefined
+}
+
+function displayEndpointInline(url) {
+  try {
+    const u = new URL(url)
+    return `${u.protocol}//${u.host}${u.pathname || '/'}${u.search || u.hash ? '?(已隐藏敏感参数)' : ''}`
+  } catch { return '<非法 endpoint>' }
+}
+
+/** 权限硬校验(POSIX):dir 0700,file(存在时)0600 */
+function verifySecureModeInline(dir, file) {
+  if (process.platform === 'win32') return { ok: false, unsupported: true }
+  try {
+    const dirMode = statSync(dir).mode & 0o777
+    if (dirMode !== 0o700) return { ok: false, error: `目录权限 ${dirMode.toString(8)} ≠ 700` }
+    if (existsSync(file)) {
+      const fileMode = statSync(file).mode & 0o777
+      if (fileMode !== 0o600) return { ok: false, error: `文件权限 ${fileMode.toString(8)} ≠ 600` }
+    }
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, error: e.message }
+  }
+}
+
+/**
+ * 官方 CLI 首次运行可能先创建 ~/.flyai 为 0755(并写入 0600 device-id)。
+ * 仅对当前用户拥有、且本身不是 symlink 的 .flyai 目录收紧权限；.gotry
+ * 仍由 atomicWriteJsonInline 严格要求预先存在时就是 0700，不走此兼容路径。
+ */
+function prepareFlyaiConfigDirInline() {
+  const dir = dirname(flyaiConfigFile())
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
+    const entry = lstatSync(dir)
+    if (entry.isSymbolicLink()) return { ok: false, error: '.flyai 目录是符号链接,拒绝写入' }
+    if (!entry.isDirectory()) return { ok: false, error: '.flyai 路径不是目录,拒绝写入' }
+    if (typeof process.getuid === 'function' && entry.uid !== process.getuid()) {
+      return { ok: false, error: '.flyai 目录不属于当前用户,拒绝写入' }
+    }
+    if ((entry.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
+    const after = lstatSync(dir)
+    if (after.isSymbolicLink() || !after.isDirectory()) return { ok: false, error: '.flyai 目录状态发生变化,拒绝写入' }
+    if (typeof process.getuid === 'function' && after.uid !== process.getuid()) return { ok: false, error: '.flyai 目录所有者发生变化,拒绝写入' }
+    return verifySecureModeInline(dir, flyaiConfigFile())
+  } catch (e) {
+    return { ok: false, error: e.message }
+  }
+}
+
+/**
+ * 原子写 JSON:tmp(mode 0600)→ 权限校验 → rename → 目标权限校验。
+ * finally 删除本操作 tmp:rename 失败也不留含明文残留。
+ */
+function atomicWriteJsonInline(path, value) {
+  const dir = dirname(path)
+  let tmp
+  try {
+    const dirExisted = existsSync(dir)
+    mkdirSync(dir, { recursive: true })
+    if (!dirExisted) try { chmodSync(dir, 0o700) } catch { /* 新建目录后 chmod 失败由 mode 校验拦 */ }
+    const dirCheck = verifySecureModeInline(dir, path)
+    if (dirCheck.unsupported) return { ok: false, error: 'Windows 无 0700/0600 权限位,安全写不支持' }
+    if (!dirCheck.ok) return { ok: false, error: dirCheck.error }
+
+    tmp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    let check = verifySecureModeInline(dir, tmp)
+    if (!check.ok) return { ok: false, error: check.error }
+
+    renameSync(tmp, path)
+    tmp = undefined
+    check = verifySecureModeInline(dir, path)
+    if (!check.ok) return { ok: false, error: check.error }
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, error: e.message }
+  } finally {
+    if (tmp) { try { rmSync(tmp, { force: true }) } catch { /* best effort */ } }
+  }
+}
+
+function readFlyaiVerificationInline() {
+  try {
+    const path = flyaiVerificationFile()
+    if (!existsSync(path)) return undefined
+    const v = JSON.parse(readFileSync(path, 'utf8'))
+    if (v?.schema !== 'gotry.flyai-verification.v1' || typeof v.keySha256 !== 'string') return undefined
+    return v
+  } catch { return undefined }
+}
+
+/**
+ * setup flyai 子命令(#521;唯一凭据写面,模型工具不可达):
+ *   --stdin 非交互输入;缺省 TTY 隐藏输入(raw mode 不回显);
+ *   --status 只读;--clear 删 config 字段(env/debug 来源清不掉如实标注)。
+ * 保存 = 非空/非占位 → 候选 key scrub-env 真实只读验证 → 原子写 → 验证回执。
+ * 验证失败/写盘失败不动旧配置。
+ */
+async function runSetupFlyai() {
+  const STATUS = process.argv.includes('--status')
+  const CLEAR = process.argv.includes('--clear')
+  const STDIN = process.argv.includes('--stdin')
+
+  const printStatus = (extra = '') => {
+    const r = resolveFlyaiKeyInline()
+    const endpoint = resolveFlyaiEndpointInline()
+    const verification = readFlyaiVerificationInline()
+    say('[gotry-setup] FlyAI(飞猪官方只读检索凭据)')
+    say(`  来源: ${r.source}${r.source === 'env-debug' ? '(DEBUG 调试覆盖)' : ''}`)
+    if (r.key) say(`  key: ${maskFlyaiKeyInline(r.key)}(脱敏;明文不显示)`)
+    say(`  配置文件: ${r.configPath}`)
+    say(`  endpoint: ${displayEndpointInline(endpoint.url)}${endpoint.debug ? '(DEBUG_FLYAI_MCP_URL 调试覆盖)' : ''}`)
+    if (r.key) {
+      const keySha = sha256Inline(r.key)
+      if (verification && verification.keySha256 === keySha) {
+        const sourceMatch = verification.source === r.source
+        const endpointMatch = verification.endpointFingerprint === endpointFingerprintInline(endpoint.url)
+        if (verification.verdict === 'verified' && sourceMatch && endpointMatch && verification.endpointDebug === endpoint.debug) {
+          say(`  验证: 已验证 @ ${verification.at}${endpoint.debug ? '(调试 endpoint)' : ''}`)
+        } else if (verification.verdict === 'verified') {
+          say('  验证: 已配置,未按当前来源/endpoint 验证(回执与当前生效上下文不匹配)')
+        } else {
+          say(`  验证: 验证失败(${verification.verdict}@ ${verification.at})——已配置不等于有效`)
+        }
+      } else {
+        say('  验证: 已配置,未验证(非空不等于鉴权通过;运行不带 --status 的 setup 触发验证)')
+      }
+    } else {
+      say('  验证: 未配置——可直接匿名试用(共享额度易达限),或粘贴正式 key 验证后保存')
+    }
+    if (extra) say(extra)
+    say('  凭据修改仅本机命令可达: `gotry setup flyai`(隐藏输入)/ `--stdin` / `--clear`;模型工具不能传 key')
+  }
+
+  if (STATUS) {
+    printStatus()
+    return 0
+  }
+
+  if (CLEAR) {
+    const read = readFlyaiConfigObject()
+    if (!read.ok) {
+      say(`[gotry-setup] 原配置损坏,已拒绝操作保留原字节(${read.error});请先人工修复 ${flyaiConfigFile()}`)
+      return 1
+    }
+    let hadField = false
+    if (Object.prototype.hasOwnProperty.call(read.data, 'FLYAI_API_KEY')) {
+      hadField = true
+      const next = { ...read.data }
+      delete next.FLYAI_API_KEY
+      if (Object.keys(next).length === 0) {
+        rmSync(flyaiConfigFile(), { force: true })
+      } else {
+        const configDir = prepareFlyaiConfigDirInline()
+        if (!configDir.ok) { say(`[gotry-setup] 清除写入失败,旧配置保留:${configDir.error}`); return 1 }
+        const w = atomicWriteJsonInline(flyaiConfigFile(), next)
+        if (!w.ok) { say(`[gotry-setup] 清除写入失败,旧配置保留:${w.error}`); return 1 }
+      }
+      try { rmSync(flyaiVerificationFile(), { force: true }) } catch { /* best effort */ }
+    }
+    const now = resolveFlyaiKeyInline()
+    if (now.key) {
+      say(`[gotry-setup] config 字段${hadField ? '已删' : '本不存在'};但当前仍由来源 ${now.source}(${maskFlyaiKeyInline(now.key)})生效——文件操作清不掉 env/debug`)
+    } else {
+      say(`[gotry-setup] ✓ 已清除${hadField ? `(字段来自 ${flyaiConfigFile()})` : ''};当前匿名试用态`)
+    }
+    return 0
+  }
+
+  // ── save:取得候选 key ──
+  let candidate
+  if (STDIN || !process.stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of process.stdin) chunks.push(chunk)
+    candidate = Buffer.concat(chunks).toString('utf8')
+    if (!STDIN && !process.stdin.isTTY) {
+      // 非 TTY 且未显式 --stdin:仍接受管道输入,但不进入交互隐藏模式。
+    }
+  } else {
+    say('[gotry-setup] FlyAI API key 设置(输入隐藏,不回显;粘贴后回车)')
+    say('  打开 https://flyai.open.fliggy.com/console，登录后复制 API Key。直接回车取消。')
+    candidate = await hiddenInput('  key: ')
+  }
+  candidate = (candidate ?? '').trim()
+  if (!candidate) {
+    say('[gotry-setup] 未输入 key——已取消,配置未改动(仍可用匿名试用)')
+    return 0
+  }
+  if (isPlaceholderFlyaiKeyInline(candidate)) {
+    say('[gotry-setup] 拒绝:这是文档占位串,不是真实 API key;配置未改动')
+    return 1
+  }
+
+  // 候选 key 真实只读验证:scrub 掉两个覆盖 env 后注入候选,
+  // 保证验证请求用的是候选 key,不被进程已有 env 遮蔽。
+  say('[gotry-setup] 用候选 key 做只读验证(单次,不重试鉴权错误)…')
+  const verify = await verifyCandidateKeyInline(candidate)
+  if (verify.verdict !== 'hit') {
+    say(`[gotry-setup] ✗ 验证未通过(${verify.verdict}):${verify.error ?? ''}`)
+    say('  配置未改动(失败不覆盖原有效设置)。核对 key 后重试,或 `--clear` 回退匿名。')
+    return 1
+  }
+
+  const before = readFlyaiConfigObject()
+  if (!before.ok) {
+    say(`[gotry-setup] 原配置损坏,已拒绝覆盖保留原字节(${before.error});请先人工修复 ${flyaiConfigFile()}`)
+    return 1
+  }
+  const hadConfigFile = existsSync(flyaiConfigFile())
+  const configDir = prepareFlyaiConfigDirInline()
+  if (!configDir.ok) {
+    say(`[gotry-setup] ✗ 配置目录不安全,旧配置保留:${configDir.error}`)
+    return 1
+  }
+  const write = atomicWriteJsonInline(flyaiConfigFile(), { ...before.data, FLYAI_API_KEY: candidate })
+  if (!write.ok) {
+    say(`[gotry-setup] ✗ 写入失败,旧配置保留:${write.error}`)
+    return 1
+  }
+
+  const epAfter = resolveFlyaiEndpointInline()
+  const endpointFingerprint = endpointFingerprintInline(epAfter.url)
+  if (!endpointFingerprint) {
+    const rollback = hadConfigFile
+      ? atomicWriteJsonInline(flyaiConfigFile(), before.data)
+      : (() => { try { rmSync(flyaiConfigFile(), { force: true }); return { ok: true } } catch (e) { return { ok: false, error: e.message } } })()
+    say(`[gotry-setup] ✗ endpoint 非法,未生成验证回执;旧配置${rollback.ok ? '已保留' : `回滚失败:${rollback.error}`}`)
+    return 1
+  }
+  const receipt = {
+    schema: 'gotry.flyai-verification.v1',
+    // 验证的是刚注入并准备写入 config 的候选 key；环境覆盖不能冒充候选来源。
+    source: 'config',
+    keySha256: sha256Inline(candidate),
+    maskedKey: maskFlyaiKeyInline(candidate),
+    verdict: 'verified',
+    endpointFingerprint,
+    endpointDebug: epAfter.debug,
+    at: new Date().toISOString(),
+  }
+  const receiptWrite = atomicWriteJsonInline(flyaiVerificationFile(), receipt)
+  if (!receiptWrite.ok) {
+    const rollback = hadConfigFile
+      ? atomicWriteJsonInline(flyaiConfigFile(), before.data)
+      : (() => { try { rmSync(flyaiConfigFile(), { force: true }); return { ok: true } } catch (e) { return { ok: false, error: e.message } } })()
+    say(`[gotry-setup] ✗ 验证回执写入失败:${receiptWrite.error};旧配置${rollback.ok ? '已保留' : `回滚失败:${rollback.error}`}`)
+    return 1
+  }
+  const after = resolveFlyaiKeyInline()
+  say(`[gotry-setup] ✓ 候选 key 验证通过并已保存(明文不落日志)`)
+  printStatus(`  savedTo: ${after.configPath}`)
+  return 0
+}
+
+/** TTY 隐藏输入:raw mode,不回显;Enter 结束;Ctrl+C/Ctrl+D 取消 */
+function hiddenInput(prompt) {
+  return new Promise((resolve) => {
+    process.stdout.write(prompt)
+    let buf = ''
+    const stdin = process.stdin
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.setEncoding('utf8')
+    const stop = () => {
+      try { stdin.setRawMode(false) } catch { /* ignore */ }
+      stdin.pause()
+      process.stdout.write('\n')
+    }
+    const onData = (d) => {
+      for (const ch of d) {
+        if (ch === '\n' || ch === '\r') {
+          stdin.removeListener('data', onData)
+          stop()
+          resolve(buf)
+          return
+        }
+        if (ch === '') {
+          stdin.removeListener('data', onData)
+          stop()
+          resolve('')
+          return
+        }
+        if (ch === '') {
+          // Ctrl+D
+          stdin.removeListener('data', onData)
+          stop()
+          resolve(buf)
+          return
+        }
+        if (ch === '' || ch === '\x7f') {
+          buf = buf.slice(0, -1)
+        } else {
+          buf += ch
+        }
+      }
+    }
+    stdin.on('data', onData)
+  })
+}
+
+/**
+ * 候选 key 验证:spawn 官方 CLI(cliBin 可由测试 env 注入 fixture),
+ * 子进程 env scrub FLYAI_API_KEY/DEBUG_FLYAI_API_KEY 后注入候选。
+ * 返回 {verdict,error}。
+ */
+function verifyCandidateKeyInline(candidate) {
+  const GOTRY_FLYAI_CLI = process.env.GOTRY_FLYAI_CLI_BIN ?? ''
+  const cliBin = GOTRY_FLYAI_CLI || 'npx'
+  const prefix = GOTRY_FLYAI_CLI ? [] : ['-y', '@fly-ai/flyai-cli@1.0.16']
+  const env = { ...process.env }
+  delete env.FLYAI_API_KEY
+  delete env.DEBUG_FLYAI_API_KEY
+  env.FLYAI_API_KEY = candidate
+  const date = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10)
+  const args = [...prefix, 'search-flight', '--origin', '上海', '--destination', '丽江', '--dep-date', date]
+  const configuredTimeout = Number(process.env.GOTRY_FLYAI_VERIFY_TIMEOUT_MS ?? 20_000)
+  const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? Math.min(configuredTimeout, 60_000) : 20_000
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let timedOut = false
+    let settled = false
+    const child = spawn(cliBin, args, {
+      env, stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    })
+    const finish = (v) => {
+      if (settled) return
+      settled = true
+      resolve(v)
+    }
+    const killGroup = (signal) => {
+      if (process.platform !== 'win32' && child.pid) {
+        try { process.kill(-child.pid, signal); return } catch { /* fall through */ }
+      }
+      try { child.kill(signal) } catch { /* ignore */ }
+    }
+    const timer = setTimeout(() => { timedOut = true; killGroup('SIGKILL') }, timeoutMs)
+    child.stdout?.on('data', d => { stdout += d.toString() })
+    child.stderr?.on('data', d => { stderr += d.toString() })
+    child.on('error', (e) => { clearTimeout(timer); finish({ verdict: 'error', error: e.message }) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      const combined = `${stderr}\n${stdout}`
+      if (timedOut) return finish({ verdict: 'timeout', error: `验证调用超时 ${timeoutMs}ms` })
+      if (/Invalid API key|HTTP\s*401|\b401\b/.test(combined)) {
+        return finish({ verdict: 'auth-error', error: '401 Invalid API key' })
+      }
+      if (/HTTP\s*403|\b403\b/.test(combined)) {
+        return finish({ verdict: 'forbidden', error: 'HTTP 403：无访问权限，请核对控制台权限。' })
+      }
+      if (/Trial limit reached/.test(combined)) {
+        return finish({ verdict: 'needs-setup', error: 'Trial limit reached(候选 key 未被识别为正式 key?)' })
+      }
+      if (/HTTP\s*429|\b429\b/.test(combined)) {
+        return finish({ verdict: 'rate-limited', error: '普通限流,稍后重试' })
+      }
+      if (code !== 0) {
+        // Upstream diagnostics can echo credentials or a private debug URL.
+        return finish({ verdict: 'error', error: `验证进程失败（exit ${code}）；请检查网络与服务状态。` })
+      }
+      try {
+        const envelope = JSON.parse(stdout)
+        if (Array.isArray(envelope?.data?.itemList)) {
+          return finish({ verdict: 'hit', count: envelope.data.itemList.length })
+        }
+        return finish({ verdict: 'error', error: '响应缺 data.itemList' })
+      } catch {
+        return finish({ verdict: 'error', error: '响应不是合法 JSON' })
+      }
+    })
+  })
+}
+
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const AUTO = process.argv.includes('--auto')
+const CHECK_ONLY = process.argv.includes('--check-only')
+const WIZARD = process.argv.includes('wizard') || process.argv.includes('--wizard')
+const WIZARD_DRY_RUN = process.argv.includes('--dry-run')
+// 扩展分发源(ADR-21):默认 bundled(包内副本,离线确定性);github 显式 opt-in
+// (镜像 GOTRY_SESSION_TRANSPORT=cdp 的显式 opt-in 文化——不静默引入网络依赖)
+const EXT_FROM_ARG = (process.argv.find((a) => a.startsWith('--extension-from=')) ?? '').split('=')[1]
+const EXTENSION_FROM = EXT_FROM_ARG === 'github' || EXT_FROM_ARG === 'bundled' ? EXT_FROM_ARG : process.env.GOTRY_EXTENSION_SOURCE === 'github' ? 'github' : 'bundled'
+
+// hbcli 安装通道:npm 优先(staicli@npmjs 双轨;显式 registry 防 bnpm 404),install.sh 兜底
+const HBCLI_NPM_INSTALL_CMD = 'npm install -g staicli --registry=https://registry.npmjs.org/'
+const HBCLI_INSTALL_CMD = HBCLI_NPM_INSTALL_CMD
+const REACH_INSTALL_URL = 'git+https://github.com/Panniantong/Agent-Reach.git'
+
+let activeInstallerChild = null
+let activeInstallerGroupPid = null
+let installerSignalHandling = false
+const installerSignalListeners = new Map()
+const INSTALLER_TERM_GRACE_MS = 2_000
+const INSTALLER_KILL_WAIT_MS = 1_000
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const waitChildClose = (child, ms) => new Promise((resolve) => {
+  if (!child) { resolve(false); return }
+  let done = false
+  const finish = (value) => {
+    if (done) return
+    done = true
+    clearTimeout(timer)
+    child.off('close', onClose)
+    child.off('error', onError)
+    resolve(value)
+  }
+  const onClose = () => finish(true)
+  const onError = () => finish(true)
+  const timer = setTimeout(() => finish(false), ms)
+  child.once('close', onClose)
+  child.once('error', onError)
+})
+const signalInstallerChild = (child, signal, groupPid = null) => {
+  if (!child) return
+  if (process.platform !== 'win32' && groupPid) {
+    try { process.kill(-groupPid, signal); return } catch { /* fallback */ }
+  }
+  try { child.kill(signal) } catch { /* ignore */ }
+}
+const terminateInstallerChild = async (child, signal, groupPid = null, graceMs = INSTALLER_TERM_GRACE_MS, killMs = INSTALLER_KILL_WAIT_MS) => {
+  if (!child) return
+  signalInstallerChild(child, signal, groupPid)
+  const closed = await waitChildClose(child, graceMs)
+  if (closed) return
+  signalInstallerChild(child, 'SIGKILL', groupPid)
+  await waitChildClose(child, killMs)
+}
+const registerInstallerSignalForwarding = () => {
+  if (installerSignalListeners.size) return
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    const listener = () => {
+      if (installerSignalHandling) return
+      installerSignalHandling = true
+      void (async () => {
+        await terminateInstallerChild(activeInstallerChild, sig, activeInstallerGroupPid)
+        for (const [s, l] of installerSignalListeners) process.off(s, l)
+        installerSignalListeners.clear()
+        process.kill(process.pid, sig)
+        await wait(2_000)
+        process.exit(128 + (sig === 'SIGINT' ? 2 : 15))
+      })()
+    }
+    process.on(sig, listener)
+    installerSignalListeners.set(sig, listener)
+  }
+}
+const unregisterInstallerSignalForwarding = () => {
+  for (const [s, l] of installerSignalListeners) process.off(s, l)
+  installerSignalListeners.clear()
+  installerSignalHandling = false
+}
+
+/** 带超时的子进程(inherit stdio 让用户看见上游安装进度);POSIX 下用进程组约束 installer 子树 */
+function run(cmd, args, { timeoutMs, cwd, env } = {}) {
+  return new Promise((resolve) => {
+    const detachedInstaller = process.platform !== 'win32'
+    const child = spawn(cmd, args, { stdio: 'inherit', cwd, env: env ?? process.env, detached: detachedInstaller })
+    activeInstallerChild = child
+    activeInstallerGroupPid = detachedInstaller ? child.pid : null
+    registerInstallerSignalForwarding()
+    let done = false
+    let timer = null
+    const finish = (result) => {
+      if (done) return
+      done = true
+      if (timer) clearTimeout(timer)
+      activeInstallerChild = null
+      activeInstallerGroupPid = null
+      unregisterInstallerSignalForwarding()
+      resolve(result)
+    }
+    timer = setTimeout(() => {
+      void (async () => {
+        if (done) return
+        await terminateInstallerChild(child, 'SIGTERM', activeInstallerGroupPid)
+        finish({ ok: false, error: 'timeout' })
+      })()
+    }, timeoutMs)
+    child.on('error', (e) => finish({ ok: false, error: e.message }))
+    child.on('close', (code, signal) => finish({ ok: code === 0, error: code === 0 ? undefined : signal ? `signal ${signal}` : `exit ${code}` }))
+  })
+}
+
+/** 静默探测命令是否可执行(带超时) */
+function probe(cmd, args, timeoutMs = 10_000) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'ignore' })
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(false) }
+    }, timeoutMs)
+    child.on('error', () => { if (!done) { done = true; clearTimeout(timer); resolve(false) } })
+    child.on('exit', (code) => { if (!done) { done = true; clearTimeout(timer); resolve(code === 0) } })
+  })
+}
+
+/**
+ * 探测命令 stdout,失败(spawn 错误/非零退出/超时)返回 null。
+ * 在 'close' 而非 'exit' 结算:'exit' 触发时 stdout 管道可能还没读完,输出会丢成空串
+ * (与 ts/capabilities/doctor.ts 的 probeStdout 同一处修复,#622)。
+ */
+function probeStdout(cmd, args, timeoutMs = 10_000) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] })
+    let out = ''
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(null) }
+    }, timeoutMs)
+    child.on('error', () => { if (!done) { done = true; clearTimeout(timer); resolve(null) } })
+    child.stdout?.on('data', (d) => { out += d.toString() })
+    child.on('close', (code) => { if (!done) { done = true; clearTimeout(timer); resolve(code === 0 ? out.trim() : null) } })
+  })
+}
+
+/**
+ * 按 `hbcli --json auth whoami` 的输出判凭证(hotelbyte-cli 三档 api_key/portal/customer 任一
+ * configured 即有效),不看退出码——whoami 没有凭证时也退 0,按退出码判会把「没登录」报成「凭证有效」(#623)。
+ * 与工具层 ts/capabilities/doctor.ts 同语义:输出不可解析(超旧版/异常)保守视为有效;取不到输出(null)视为未确认。
+ * 两处实现的一致性由 bootstrap-tests 的 CLI↔工具层对拍守住。
+ */
+function classifyHbcliWhoami(out) {
+  if (out === null) return { ok: false, customer: false }
+  try {
+    const w = JSON.parse(out)
+    const customer = !!w?.customer?.configured
+    return { ok: !!(w?.api_key?.configured || w?.portal?.configured || customer), customer }
+  } catch {
+    return { ok: true, customer: false }
+  }
+}
+
+const say = (s) => console.log(s)
+
+/** hbcli 最低版本(可用 GOTRY_MIN_HBCLI_VERSION 覆盖)。
+ * 0.0.3 修了 portal-ticket fallback bug(issue #142):低于该版本的 hbcli
+ * 会把 literal "stored-ticket" 当 bearer 发到 hotel-be,让 trade.* /
+ * search/checkAvail 等 @permission: openapi 端点全部 401。 */
+const MIN_HBCLI_VERSION = process.env.GOTRY_MIN_HBCLI_VERSION ?? '0.0.3'
+
+function parseVersion(v) {
+  const m = String(v || '').match(/(\d+)\.(\d+)\.(\d+)/)
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+}
+
+function versionAtLeast(v, min) {
+  // v 可能是 hbcliVersion 已解析的数组,也可能是原始字符串——两者都接受
+  const a = Array.isArray(v) ? v : parseVersion(v); const b = parseVersion(min)
+  if (!a || !b) return false
+  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i] }
+  return true
+}
+
+async function hbcliVersion(bin) {
+  const cmd = bin === 'hbcli(PATH)' ? 'hbcli' : bin
+  return new Promise((resolve) => {
+    const child = spawn(cmd, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] })
+    let out = ''
+    let done = false
+    const timer = setTimeout(() => { if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(null) } }, 10_000)
+    child.on('error', () => { if (!done) { done = true; clearTimeout(timer); resolve(null) } })
+    child.stdout?.on('data', (d) => { out += d.toString() })
+    child.on('close', (code) => { if (!done) { done = true; clearTimeout(timer); resolve(code === 0 ? parseVersion(out.trim()) : null) } })
+  })
+}
+
+async function setupHbcli() {
+  say(`[gotry-setup] hbcli(hotelbyte-cli,可选酒店实时源;需 ≥ v${MIN_HBCLI_VERSION},低于会踩 issue #142 的 401)`)
+  const candidates = ['hbcli', join(homedir(), '.local/bin/hbcli'), join(homedir(), '.staicli/current/hbcli')]
+  const present = candidates.some((p) => existsSync(p)) && (await probe(candidates[0], ['version']) || await probe(candidates[1], ['version']) || await probe(candidates[2], ['version']))
+  const credFile = join(homedir(), '.staicli', 'credentials.json')
+  if (present) {
+    const hit = candidates.find((p) => existsSync(p)) || 'hbcli'
+    const v = await hbcliVersion(hit)
+    if (v && !versionAtLeast(v, MIN_HBCLI_VERSION)) {
+      say(`  ✗ 版本过旧(v${v.join('.')} < v${MIN_HBCLI_VERSION})——@permission: openapi 端点(trade.* / search/checkAvail)会 401(issue #142)`)
+      say(`    升级: npm install -g staicli --registry=https://registry.npmjs.org/`)
+      return { ok: CHECK_ONLY ? true : false }
+    }
+    say(`  ✓ 已安装(v${v ? v.join('.') : '?'})`)
+    if (existsSync(credFile)) say('  ✓ 凭证已配置(自检: hbcli auth whoami)')
+    else say('  ✗ 凭证未配置——酒店检索将用内置静态包(非实时),账号配置见下方指引')
+    if (CHECK_ONLY) say('  (--check-only 只报告,不安装)')
+    return { ok: true }
+  }
+  if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
+  say(`  安装中(npm,staicli@npmjs): ${HBCLI_INSTALL_CMD}`)
+  const r = await run('bash', ['-c', HBCLI_INSTALL_CMD], { timeoutMs: 120_000 })
+  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx @danceiny/gotry setup`); return { ok: false } }
+  const binDir = join(homedir(), '.local/bin')
+  if (!process.env.PATH.split(':').includes(binDir)) {
+    say(`  ⚠ ${binDir} 不在当前 PATH —— gotry 工具已内建候选路径回退,无需手动处理;其他程序可用: export PATH="${binDir}:$PATH"`)
+  }
+  say('  ✓ 安装完成——账号配置(未配时酒店检索自动用静态包,非实时):')
+  say('    · 快速试用(官方沙箱演示账号): hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo')
+  say('    · 正式接入: 向 HotelByte 申请专属 appKey/appSecret 后用同一命令替换')
+  say('    · 门户账号(权限更大,酒店搜索无必要): hbcli auth login --username <email>')
+  say('  自检: hbcli auth whoami(api_key.configured=true 即就位)')
+  return { ok: true }
+}
+
+async function setupReach() {
+  say('[gotry-setup] agent-reach(可选网页/社媒读取源,pip 装入包内 .venv)')
+  const venvBin = join(repoRoot, '.venv/bin/agent-reach')
+  if (existsSync(venvBin)) { say('  ✓ 已安装(.venv)'); return { ok: true } }
+  if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
+  const hasPy = await probe('python3', ['--version'], 10_000)
+  if (!hasPy) { say('  ✗ 跳过:未找到 python3(agent-reach 需 Python 3;装好后重跑 npx @danceiny/gotry setup)'); return { ok: false } }
+  say(`  创建 .venv 并安装上游(${REACH_INSTALL_URL})`)
+  const venv = await run('python3', ['-m', 'venv', join(repoRoot, '.venv')], { timeoutMs: 120_000 })
+  if (!venv.ok) { say(`  ✗ venv 创建失败(${venv.error})——不影响 gotry,gotry_agent_reach 将返回 not-installed 指引`); return { ok: false } }
+  const pip = join(repoRoot, '.venv/bin/pip')
+  const inst = await run(pip, ['install', '-q', REACH_INSTALL_URL], { timeoutMs: 300_000 })
+  if (!inst.ok) { say(`  ✗ pip 安装失败(${inst.error})——可稍后重试: npx @danceiny/gotry setup`); return { ok: false } }
+  say('  ✓ 安装完成(渠道凭证选配见 docs/tokens.md: .venv/bin/agent-reach configure --from-browser chrome --platform <渠道>)')
+  return { ok: true }
+}
+
+/** sidebar 落盘状态 = 与 doctor 检查同口径的唯一事实面(profile 里的 package.json) */
+function sidebarInstalled() {
+  return existsSync(join(homedir(), '.dsh/profiles/web/node_modules/dsh-better-sidebar/package.json'))
+}
+
+/** dsh plugin 在 profile 目录里跑 pnpm;pnpm ≥10.5 默认不执行依赖构建脚本,严格态
+ *  (pnpm 11 默认 / strict-dep-builds)下 ERR_PNPM_IGNORED_BUILDS 直接 exit 1——
+ *  但包本身已完整落盘(2026-09-08 实测:exit 1 而 167 包全部就位,doctor 复检即绿)。
+ *  对该调用降回警告态(env 只作用于这一次 spawn,不改用户全局 pnpm 配置);
+ *  老版本 pnpm 不认识此配置,零影响。 */
+const SIDEBAR_PNPM_ENV = { ...process.env, npm_config_strict_dep_builds: 'false' }
+
+async function setupSidebar(attemptInstall) {  say('[gotry-setup] dsh-better-sidebar(dsh web 侧栏工作台,产物查看面 issue #25)')
+  if (sidebarInstalled()) { say('  ✓ 已安装(~/.dsh/profiles/web)'); return { ok: true } }
+  if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
+  const SIDEBAR_PKG = 'dsh-better-sidebar@latest'
+  // dsh CLI:本包依赖里的 @deepseek-ai/dsh 优先;解析不到走 npx 自拉(官方安装途径同款)。
+  // attemptInstall 注入位供测试模拟「安装器失败但状态落盘」(pnpm 忽略构建脚本策略)。
+  const require_ = createRequire(join(repoRoot, 'package.json'))
+  const defaultAttempt = async () => {
+    try {
+      const dshBin = require_.resolve('@deepseek-ai/dsh/lib/bin.js')
+      say(`  安装中(dsh plugin → web profile): ${SIDEBAR_PKG}`)
+      return await run(process.execPath, [dshBin, 'plugin', '--profile', 'web', 'add', SIDEBAR_PKG], { timeoutMs: 300_000, env: SIDEBAR_PNPM_ENV })
+    } catch { return { ok: false, noDsh: true } }
+  }
+  const r = await (attemptInstall ?? defaultAttempt)()
+  if (r.ok) {
+    say('  ✓ 安装完成(gotry web 刷新浏览器即见右侧工作台;工作区里的产物 md 可直接预览)')
+    return { ok: true }
+  }
+  // exit 非 0 ≠ 没装上(pnpm 忽略构建脚本策略):先按落盘状态复核,再决定是否回退 npx 途径
+  if (sidebarInstalled()) {
+    say('  ✓ 安装完成(安装器 exit 非 0,但按落盘状态复核已就位;gotry web 刷新浏览器即见右侧工作台)')
+    say('  ⚠ pnpm 跳过了 node-pty(侧栏内嵌终端)的构建脚本——预览功能不受影响;如需内嵌终端:cd ~/.dsh/profiles/web && pnpm approve-builds 勾选 node-pty')
+    return { ok: true }
+  }
+  if (r.noDsh) say('  本包未携带 @deepseek-ai/dsh,走 npx 途径安装')
+  else say('  ✗ dsh plugin 安装失败且未落盘——尝试 npx 途径')
+  const r2 = await run('npx', ['-y', '--package', '@deepseek-ai/dsh', 'dsh', 'plugin', '--profile', 'web', 'add', SIDEBAR_PKG], { timeoutMs: 300_000, env: SIDEBAR_PNPM_ENV })
+  if (r2.ok) {
+    say('  ✓ 安装完成(gotry web 刷新浏览器即见右侧工作台)')
+    return { ok: true }
+  }
+  if (sidebarInstalled()) {
+    say('  ✓ 安装完成(npx 途径 exit 非 0,但按落盘状态复核已就位)')
+    return { ok: true }
+  }
+  say('  ✗ 安装失败——不影响 gotry:产物仍可在对话里说「看看我生成的行程」经 gotry_artifacts_list/read 查看;可稍后重试: npx @danceiny/gotry doctor --fix')
+  return { ok: false }
+}
+
+// ---------------------------------------------------------------------------
+// doctor(可选依赖体检;与 ts/capabilities/doctor.ts 同一状态面,-bootstrap 是
+// CLI 执行面纯 JS、capabilities 是 MCP 工具面 TS——两边清单/口径成对修改)
+// ---------------------------------------------------------------------------
+
+const DOCTOR = process.argv.includes('doctor')
+const DOCTOR_FIX = process.argv.includes('--fix')
+// onboarding 子命令(issue #258):`gotry web` 启动前的显式可选能力配置 prompt——每次符合条件的
+// 启动评估一次、至多问一次,无跨启动持久确认。inner 以 `onboarding --result-file=…` 同步 inherit
+// 调用;`--scan` 只读查看计划(测试/调试)。
+const ONBOARDING = process.argv.includes('onboarding')
+// calendar 子命令(issue #106/D-9):可选日历挂载的 setup 状态管理面。
+// `gotry setup calendar`=开启;`--off`=关闭(删状态文件恢复默认);`--status`=只读查看。
+const CALENDAR_CMD = process.argv.includes('calendar')
+const CALENDAR_OFF = process.argv.includes('--off')
+const CALENDAR_STATUS = process.argv.includes('--status')
+
+// setup flyai 子命令(issue #521):`gotry setup flyai [--stdin|--status|--clear]`。
+// 与 calendar 区分:argv 同时含 'setup' 与 'flyai'。
+const FLYAI_SETUP_CMD = process.argv.includes('flyai') && !DOCTOR && !process.argv.some((a) => a === 'search-flight' || a === 'search-hotel' || a === 'search-train')
+
+// --- calendar setup 状态面(与扩展 manifest 同居 ~/.gotry;运行时 inner 与
+// doctor 两端同读这一份,禁止 env 控制产品行为——founder 2026-09-03 纠偏)---
+function calendarStatePath() { return join(homedir(), '.gotry', 'calendar.json') }
+function readCalendarState() {
+  try { return JSON.parse(readFileSync(calendarStatePath(), 'utf8')) } catch { return null }
+}
+function calendarProfileConfigured() {
+  try {
+    const patch = readFileSync(join(homedir(), '.dsh', 'profiles', 'web', 'cordis.patch.yml'), 'utf8')
+    return /calendar/.test(patch) && /username\s*:/.test(patch)
+  } catch { return false }
+}
+
+/** 挂载/配置双态人话(bootstrap doctor 与 calendar 子命令共用) */
+function calendarDetail(state) {
+  if (!state || state.enabled !== true) return '默认未挂载(D-9:未配置的日历工具不进工具箱;工作窗口由访谈覆盖,不影响任何检索)'
+  return calendarProfileConfigured()
+    ? `已挂载且已配置(${calendarStatePath()})`
+    : '已挂载但 calendar 未配置 username——日历工具会话中会报「未配置」;影响面:工作窗口只能由访谈覆盖,日历读取工具不会自动跑;机票/酒店/地图等检索不受影响'
+}
+
+async function runCalendar() {
+  say('[gotry-setup] dsh-calendar(可选日历,CalDAV 工作窗口读取;默认不挂载)')
+  if (CALENDAR_STATUS) {
+    const state = readCalendarState()
+    say(`  状态: ${calendarDetail(state)}`)
+    say(`  状态文件: ${calendarStatePath()}`)
+    say('  说明: 挂载=`npx @danceiny/gotry setup calendar`;关闭=`npx @danceiny/gotry setup calendar --off`;配置在 dsh profile 的 cordis.patch.yml 覆盖 calendar 行 config 填 username')
+    return 0
+  }
+  if (CALENDAR_OFF) {
+    try { rmSync(calendarStatePath()) } catch { /* 本就未开启 */ }
+    say('  ✓ 已关闭——恢复默认不挂载(状态文件已删除;如需再开: npx @danceiny/gotry setup calendar)')
+    return 0
+  }
+  mkdirSync(dirname(calendarStatePath()), { recursive: true })
+  writeFileSync(calendarStatePath(), `${JSON.stringify({ enabled: true, updatedAt: new Date().toISOString() }, null, 2)}\n`, 'utf8')
+  say(`  ✓ 已开启挂载(状态文件 ${calendarStatePath()};重启 gotry web/headless 生效)`)
+  if (calendarProfileConfigured()) {
+    say('  ✓ calendar 已在 dsh profile 配置 username——全部就绪')
+  } else {
+    say('  ⚠ 还差最后一步:在 dsh profile 的 cordis.patch.yml 覆盖 calendar 行的 config,填你的 CalDAV username,例如:')
+    say('      - id: dsh-calendar')
+    say('        config:')
+    say('          username: <你的日历账号>')
+    say('    未配置时日历工具会话中会报「未配置」;不需要日历时可用 --off 恢复默认不挂载。')
+  }
+  return 0
+}
+
+/** 逐项只读检查(永不抛错;LLM key 显式让渡给 dsh 宿主,不体检)。
+ *  level 与 ts/capabilities/doctor.ts DoctorStatus 同构:ok / missing / degraded。 */
+async function doctorChecks() {
+  const items = []
+  // Node 运行时
+  const nv = process.versions.node
+  const [maj, min] = nv.split('.').map(Number)
+  const nodeFine = maj > 22 || (maj === 22 && min >= 15)
+  items.push({ label: 'Node 运行时', ok: nodeFine, level: nodeFine ? 'ok' : 'missing', detail: `Node ${nv}(需 ≥22.15)`, fix: nodeFine ? undefined : '升级 Node.js 至 22.15+(https://nodejs.org)' })
+  // 扩展
+  const extManifest = join(homedir(), '.gotry', 'extension', 'manifest.json')
+  const extOk = existsSync(extManifest)
+  items.push({ label: 'GoTry Session Bridge 扩展', ok: extOk, level: extOk ? 'ok' : 'missing', detail: extOk ? `已就位(${extManifest})` : '未安装——影响面:gotry_session_search / gotry_session_login(账号会话通道)不可用;携程机票/酒店实时检索、12306 余票、Dida 实时报价都依赖此通道。其它工具(机票 FlyAI、酒店 hbcli、地图、天气等)不受影响', fix: extOk ? undefined : '在 Chrome 应用商店一键安装(自动更新): https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd' })
+  // agent-reach(.venv 装在包内)
+  const venvPython = join(repoRoot, '.venv/bin/python')
+  const reachBin = join(repoRoot, '.venv/bin/agent-reach')
+  const reachOk = existsSync(reachBin)
+  const reachLevel = reachOk ? 'ok' : existsSync(venvPython) ? 'degraded' : 'missing'
+  items.push({ label: 'Agent Reach(网页/社媒读取)', ok: reachOk, level: reachLevel, detail: reachOk ? `已安装(${reachBin})` : reachLevel === 'degraded' ? '.venv 在但缺 agent-reach 包——gotry_agent_reach / gotry_web_search 读页会失败' : '未装配——gotry_agent_reach / gotry_web_search(读网页)/ gotry_video_subtitle / gotry_github_search 全部不可用', fix: reachOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
+  // hbcli(裸名靠 PATH 探测;绝对路径 existsSync;版本 < MIN_HBCLI_VERSION 视为 missing,见 issue #142)
+  let hbBin = ''
+  for (const p of ['hbcli', join(homedir(), '.local/bin/hbcli'), join(homedir(), '.staicli/current/hbcli')]) {
+    if (p === 'hbcli') { if (await probe(p, ['version'])) { hbBin = 'hbcli(PATH)'; break } } else if (existsSync(p)) { hbBin = p; break }
+  }
+  if (hbBin) {
+    const v = await hbcliVersion(hbBin)
+    if (v && !versionAtLeast(v, MIN_HBCLI_VERSION)) {
+      items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: `版本过旧(v${v.join('.')} < v${MIN_HBCLI_VERSION})——trade.* / search/checkAvail 会 401(issue #142)`, fix: 'npm install -g staicli --registry=https://registry.npmjs.org/' })
+    } else {
+      // 凭证按 whoami 的 JSON 三档判定,不再看退出码(#623:whoami 无凭证也退 0,旧判法恒报「凭证有效」)
+      const cred = classifyHbcliWhoami(await probeStdout(hbBin === 'hbcli(PATH)' ? 'hbcli' : hbBin, ['--json', 'auth', 'whoami']))
+      items.push({
+        label: 'hbcli(酒店实时源)', ok: cred.ok, level: cred.ok ? 'ok' : 'degraded',
+        detail: cred.ok
+          ? `已安装且凭证有效(${hbBin}, v${v ? v.join('.') : '?'}${cred.customer ? ',customer 档在用(客户邮箱验证码登录)' : ''})`
+          : '二进制在,但凭证未配置/失效——酒店检索将降级静态包(非实时)',
+        fix: cred.ok ? undefined : 'hbcli auth customer-send-code --email you@mail.com 收码后 hbcli auth customer-login --email you@mail.com --code <收件码>(客户邮箱验证码登录,新邮箱即注册,需 npm staicli ≥ 0.0.4);B 端租户注册走 hbcli auth register(先 auth send-code);或 hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo(快速试用沙箱;正式 key 向 HotelByte 申请)',
+      })
+    }
+  } else {
+    items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: '未安装——酒店检索降级静态包(公开渠道估算,非实时,仅覆盖内置场景)', fix: 'npx @danceiny/gotry doctor --fix' })
+  }
+  // flyai(#521):区分「已配置」与「已验证」——非空只表示 configured,
+  // 不承诺正式有效/无限额;有效性必须有 key hash+endpoint 匹配的验证回执。
+  const flyaiResolved = resolveFlyaiKeyInline()
+  const flyaiEndpoint = resolveFlyaiEndpointInline()
+  const flyaiReceipt = readFlyaiVerificationInline()
+  let flyaiLevel = 'degraded'
+  let flyaiDetail
+  let flyaiFix
+  if (!flyaiResolved.key) {
+    flyaiDetail = '未配置 key——匿名试用中(共享额度易达限;达限报 Trial limit reached)。影响面:共享池额度小,频繁会话易触顶;达限本会话内 gotry_flyai_search(机票/酒店/票务/AI/万豪 8 类)失败,改走 gotry_session_search 账号会话通道。'
+    flyaiFix = '本机运行 `gotry setup flyai`(隐藏输入,先验证后保存 FLYAI_API_KEY);打开 https://flyai.open.fliggy.com/console，登录后复制 API Key'
+  } else {
+    const keySha = sha256Inline(flyaiResolved.key)
+    const receiptMatches = flyaiReceipt
+      && flyaiReceipt.keySha256 === keySha
+      && flyaiReceipt.source === flyaiResolved.source
+      && flyaiReceipt.verdict === 'verified'
+      && flyaiReceipt.endpointFingerprint === endpointFingerprintInline(flyaiEndpoint.url)
+      && flyaiReceipt.endpointDebug === flyaiEndpoint.debug
+    const sourceNote = `来源 ${flyaiResolved.source}${flyaiResolved.source === 'env-debug' ? '(DEBUG)' : ''},${maskFlyaiKeyInline(flyaiResolved.key)}`
+    if (receiptMatches) {
+      flyaiLevel = 'ok'
+      flyaiDetail = `已验证 ${flyaiReceipt.at}(${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})`
+    } else if (flyaiReceipt && flyaiReceipt.keySha256 === keySha && flyaiReceipt.verdict !== 'verified') {
+      flyaiDetail = `已配置未通过验证(${flyaiReceipt.verdict}@ ${flyaiReceipt.at};${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})——非空不等于鉴权通过`
+      flyaiFix = '本机运行 `gotry setup flyai` 重新验证;`gotry setup flyai --clear` 回退匿名'
+    } else {
+      flyaiDetail = `已配置,未验证(${sourceNote};endpoint ${displayEndpointInline(flyaiEndpoint.url)}${flyaiEndpoint.debug ? '(DEBUG)' : ''})`
+      flyaiFix = '本机运行 `gotry setup flyai`(候选 key scrub-env 验证后保存)'
+    }
+  }
+  items.push({ label: 'FlyAI(飞猪官方检索:机/火/酒/景/关键词/AI/万豪 8 类)', ok: flyaiLevel === 'ok', level: flyaiLevel, detail: flyaiDetail, fix: flyaiFix })
+  // sidebar(状态面与 setupSidebar 的落盘复核同一口径)
+  const sbOk = sidebarInstalled()
+  items.push({ label: 'dsh-better-sidebar(侧栏工作台)', ok: sbOk, level: sbOk ? 'ok' : 'missing', detail: sbOk ? '已安装——web UI 右侧工作台可预览产物与 doctor 报告(gotry-state/doctor-report.md)' : '未安装——dsh web 无右侧工作台,产物与 doctor 报告只能在对话里看(gotry_artifacts_list)', fix: sbOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
+  // dsh-calendar(setup 状态面;默认不挂载=ok 是合法态,opt-in 未配置才 degraded)
+  const calState = readCalendarState()
+  const calOn = calState?.enabled === true
+  const calConfigured = calOn && calendarProfileConfigured()
+  items.push({ label: 'dsh-calendar(日历工作窗口)', ok: !calOn || calConfigured, level: !calOn ? 'ok' : calConfigured ? 'ok' : 'degraded', detail: calendarDetail(calState), fix: !calOn ? undefined : calConfigured ? undefined : '在 ~/.dsh/profiles/web/cordis.patch.yml 覆盖 calendar 行 config 填 username(或 npx @danceiny/gotry setup calendar --off 恢复默认不挂载)' })
+  // dsh-map-tools(patch 分发面宿主插件,issue #139):解析失败启动时整块静默剔除,
+  // doctor 把两态照亮。候选清单与 bin/gotry-inner.js 解析链、ts/capabilities/doctor.ts 同口径:
+  // tarball vendor 副本优先(随 files[] 分发,不进 npm 依赖——历史上游 peerDependencies
+  // 要求 dsh-settings/dsh-tools >=0.1.2-rc.1,与锁定的 0.1.2-alpha.3 家族在 npm 严格 peer
+  // 解析下 ERESOLVE;当前锁定 0.2.0-rc.2 家族,vendored 0.7.3 保留上游开区间 peers(>=0.1.2-rc.1)直接通过 0.2.0 起的运行时 peer 兼容闸,
+  // 保持 vendored 形态复用适配补丁),其余覆盖 source/提升/profile 布局。
+  const rootRequire = createRequire(join(repoRoot, 'package.json'))
+  const mapCandidates = [
+    join(repoRoot, 'ts/dsh-runtime/vendor/dsh-map-tools/lib/index.js'),
+    join(repoRoot, 'ts/dsh-runtime/node_modules/dsh-map-tools/lib/index.js'),
+    join(repoRoot, 'node_modules/dsh-map-tools/package.json'),
+    join(repoRoot, 'ts/node_modules/dsh-map-tools/package.json'),
+    join(homedir(), '.dsh/profiles/web/node_modules/dsh-map-tools/package.json'),
+  ]
+  let mapHit = mapCandidates.find((p) => existsSync(p))
+  // npm 提升布局:gotry 的依赖不在包目录 node_modules 里,而在同级提升位——
+  // 与 inner 的 require_.resolve 同机制(createRequire 从包位置向上走查)
+  if (!mapHit) { try { mapHit = rootRequire.resolve('dsh-map-tools') } catch { mapHit = undefined } }
+  items.push(mapHit
+    ? { label: 'dsh-map-tools(地图/路线/POI)', ok: true, level: 'ok', detail: `已就位(${mapHit})——地图工具可用(零 key,走 OSM/OSRM)`, fix: undefined }
+    : { label: 'dsh-map-tools(地图/路线/POI)', ok: false, level: 'missing', detail: '未随包解析——启动时该 patch 条目被静默剔除,地图/路线/POI 工具不会出现在模型工具箱(缺地图不挡旅行规划,只少能力)', fix: '重装 @danceiny/gotry(地图插件随包 vendor 分发,缺失多为安装不完整)' })
+  // dsh-tool-ask-user(结构化澄清卡,人格契约 (5) 的卡片形态载体)
+  const askCandidates = [
+    join(repoRoot, 'ts/dsh-runtime/vendor/deepseek-ai-dsh-tool-ask-user/package.json'),
+    join(repoRoot, 'node_modules/@deepseek-ai/dsh-tool-ask-user/package.json'),
+    join(homedir(), '.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tool-ask-user/package.json'),
+  ]
+  let askHit = askCandidates.find((p) => existsSync(p))
+  // 与 inner 同口径:优先从 dsh 包上下文解析(pnpm 嵌套布局只有 dsh 看得见),再从包根上下文
+  // (npm/npx 提升布局),最后静态候选(source vendored / profile)
+  if (!askHit) {
+    try {
+      const reqFromDsh = createRequire(rootRequire.resolve('@deepseek-ai/dsh/lib/bin.js'))
+      askHit = reqFromDsh.resolve('@deepseek-ai/dsh-tool-ask-user')
+    } catch {
+      try { askHit = rootRequire.resolve('@deepseek-ai/dsh-tool-ask-user') } catch { askHit = undefined }
+    }
+  }
+  items.push(askHit
+    ? { label: 'dsh-tool-ask-user(结构化澄清卡)', ok: true, level: 'ok', detail: `已就位(${askHit})——ask_user_question 澄清卡可用(web 原生卡片;headless+TTY 用 stdio 提供方)`, fix: undefined }
+    : { label: 'dsh-tool-ask-user(结构化澄清卡)', ok: false, level: 'missing', detail: '未解析——启动时澄清卡注入被静默剔除,模型只能散文追问(人格契约 (5) 退化文本形态)', fix: '重装 @danceiny/gotry——该依赖随 dsh 闭包自带,缺失多为安装不完整' })
+  // LLM key:显式让渡(founder 2026-09-02:doctor 不管 key)
+  items.push({ label: 'LLM key', ok: true, level: 'ok', detail: '由 dsh 宿主 UI 管理——不在体检范围(gotry 不接触、不回显凭证)', fix: undefined })
+  return items
+}
+
+const doctorIcon = { ok: '✅', missing: '❌', degraded: '⚠️' }
+
+/** 修复指引入表:命令类才加反引号( prose 类如「到控制台申请 key」原样) */
+const fixCell = (fix) => (!fix ? '—' : /^(npx|hbcli|curl|pip|python|\$)/.test(fix) ? `\`${fix}\`` : fix)
+
+/** 启动一次性摘要行(issue #114,design §3.1③):全 ok 返回 null(静默零输出);
+ *  有待处理项给一行人话 + 指路(对话里 gotry_doctor 看详情 / 终端 npx @danceiny/gotry doctor)。
+ *  纯函数,bootstrap-tests 直接断言。 */
+function startupDoctorLine(items) {
+  const broken = (items ?? []).filter((i) => i.level && i.level !== 'ok')
+  if (broken.length === 0) return null
+  const human = (lv) => (lv === 'missing' ? '缺' : '半可用')
+  return `[gotry] doctor: ${broken.length} 项待处理(${broken.map((i) => `${i.label}=${human(i.level)}`).join('、')})——对话里让助手调 gotry_doctor 看详情与指引,或终端跑 npx @danceiny/gotry doctor`
+}
+
+/** 体检报告 markdown(与 ts/capabilities/doctor.ts renderDoctorReportMd 同形) */
+function renderDoctorReportMd(items) {
+  const broken = items.filter((i) => i.level !== 'ok' && i.label !== 'LLM key')
+  const lines = [
+    '# GoTry 依赖体检报告(doctor)',
+    '',
+    `> 生成于 ${new Date().toISOString()};重新生成:终端 \`npx @danceiny/gotry doctor\`,或在对话里让助手调 gotry_doctor。`,
+    '',
+    '| 状态 | 依赖 | 现状 | 修复指引 |',
+    '|---|---|---|---|',
+    ...items.map((i) => `| ${doctorIcon[i.level]} | ${i.label} | ${i.detail} | ${fixCell(i.fix)} |`),
+    '',
+    `**结论**:${broken.length === 0 ? '全部就绪(可选依赖齐,LLM key 归 dsh 宿主管)。' : `${broken.length} 项待处理:${broken.map((i) => i.label).join('、')}。补装: npx @danceiny/gotry doctor --fix`}`,
+    '',
+    '---',
+    '',
+    '- `npx @danceiny/gotry doctor` 随时可重跑(只读,不改任何东西);',
+    '- `npx @danceiny/gotry doctor --fix` 按上表补装(hbcli 官方脚本 / agent-reach pip / dsh-better-sidebar 插件);',
+    '- LLM key 由 dsh 宿主 UI 管理,gotry 永不体检、不回显。',
+    '',
+  ]
+  return lines.join('\n')
+}
+
+/** doctor 主流程:体检 → 打印 →(可选)fix → 报告落盘。
+ *  exit 0=就绪(或仅剩有自动回退的降级项);exit 1=仍有缺失类问题。 */
+async function runDoctor() {
+  let items = await doctorChecks()
+  // 启动一次性摘要(issue #114):inner 分离子进程带 --summary 调用——只读体检,
+  // 有待处理项打一行 stderr,零写盘零 header;全 ok 静默。与完整体检面(逐项/报告落盘/exit 语义)分离。
+  if (process.argv.includes('--summary')) {
+    const line = startupDoctorLine(items)
+    if (line) console.error(line)
+    return 0
+  }
+  say('[gotry-doctor] GoTry 可选依赖体检(只读;LLM key 归 dsh 宿主管,不在范围)')
+  for (const i of items) {
+    say(`  ${doctorIcon[i.level]} ${i.label}:${i.detail}`)
+    if (i.level !== 'ok' && i.fix) say(`      ↳ 修复: ${i.fix}`)
+  }
+  if (DOCTOR_FIX) {
+    if (!doctorFixAutoSupported()) {
+      say('[gotry-doctor] --fix 在 Windows 暂不支持自动安装(hbcli/agent-reach/sidebar 上游无 win 安装面);请按各项修复指引手动处理')
+    } else {
+      say('[gotry-doctor] 开始补装缺失项(--fix)…')
+      const results = []
+      if (process.env.GOTRY_SETUP_HBCLI !== '0') results.push(await setupHbcli())
+      if (process.env.GOTRY_SETUP_REACH !== '0') results.push(await setupReach())
+      if (process.env.GOTRY_SETUP_SIDEBAR !== '0') results.push(await setupSidebar())
+      const failedFix = results.filter((r) => !r.ok).length
+      say(failedFix === 0 ? '[gotry-doctor] 补装完成;下面是补装后复检。' : `[gotry-doctor] ${failedFix} 项补装失败——见上方安装器输出;可重跑 npx @danceiny/gotry doctor --fix`)
+      items = await doctorChecks()
+      for (const i of items) {
+        say(`  ${doctorIcon[i.level]} ${i.label}:${i.detail}`)
+      }
+    }
+  }
+  // 报告落盘(侧栏工作台预览面;写失败不挡体检结论)
+  try {
+    const stateDir = join(repoRoot, 'gotry-state')
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(join(stateDir, 'doctor-report.md'), renderDoctorReportMd(items), 'utf8')
+    say(`[gotry-doctor] 报告已写: ${join(stateDir, 'doctor-report.md')}(dsh 侧栏工作台可直接预览)`)
+  } catch (e) {
+    say(`[gotry-doctor] 报告写盘失败(${e.message})——体检结论仍有效`)
+  }
+  // 降级类(凭证未配/flyai 试用)不挡 exit 0——降级有自动回退路径,缺失类才挡
+  const stillMissing = items.filter((i) => i.level === 'missing').length
+  return stillMissing === 0 ? 0 : 1
+}
+
+// ---------------------------------------------------------------------------
+// onboarding(issue #258):`npx @danceiny/gotry web` 启动前的显式可选能力配置 prompt——每次符合条件的启动
+//  评估一次、至多问一次,无跨启动持久确认(不写「已问过」标记,每次 web 启动独立判定)。
+//  契约:仅交互式 TTY + 有「可自动安装」缺项时问一次;y → 复用 doctor --fix 的幂等
+//  安装器(setupHbcli/setupReach/setupSidebar,不建第二套);n → 立即继续 web。
+//  CI/benchmark/非 TTY/全健康/GOTRY_SETUP_SKIP=1/GOTRY_ONBOARDING_SKIP=1/--no-onboarding
+//  均零 prompt 零安装,仍启 web;永不 postinstall 或后台任务里安装。结果三态:
+//  installed / needs-user-action / unavailable,各带具体原因;浏览器商店/凭证/账号/
+//  key/上游授权永不冒充自动完成。部分失败不挡 web 且给重试命令;再跑不重装已健康项
+//  (安装器自带存在性短路 + doctor 复检)。纯函数(classify/plan/skipReason)与
+//  runOnboardingFix(注入安装器)均导出供 bootstrap-tests 隔离单测,不跑真安装器。
+// ---------------------------------------------------------------------------
+
+/** 安装器 id 映射:doctor item label → 安装器 id(与 GOTRY_SETUP_* env 同名)。纯函数。 */
+function installerIdFor(label) {
+  if (typeof label !== 'string') return null
+  if (label.startsWith('Agent Reach')) return 'reach'
+  if (label.startsWith('hbcli')) return 'hbcli'
+  if (label.startsWith('dsh-better-sidebar')) return 'sidebar'
+  return null
+}
+
+/** 该安装器是否被 GOTRY_SETUP_*=0 显式 opt-out(与 runDoctor 同口径)。纯函数。
+ *  env 可注入:测试与可复用逻辑不依赖 ambient GOTRY_SETUP_*,生产 CLI 路径仍取 process.env。 */
+function installerEnabled(id, env = process.env) {
+  if (id === 'hbcli') return env.GOTRY_SETUP_HBCLI !== '0'
+  if (id === 'reach') return env.GOTRY_SETUP_REACH !== '0'
+  if (id === 'sidebar') return env.GOTRY_SETUP_SIDEBAR !== '0'
+  return true
+}
+
+/** doctor --fix 自动安装的平台支持面(共享契约):win32 上 hbcli(staicli)/agent-reach(pip venv)
+ *  上游无 win 安装面,dsh-better-sidebar(dsh plugin → pnpm)在 win32 同样不自动跑——runDoctor
+ *  的 --fix 守卫与 onboarding 的 auto 分桶复用同一条边界,不在 win32 把这些缺项分到 auto
+ *  (否则 prompt 了却装不上,不诚实)。纯函数,可注入 platform 供确定性单测。 */
+function doctorFixAutoSupported(platform = process.platform) {
+  return platform !== 'win32'
+}
+
+/** win32 上本可 auto 的缺项降为 unavailable 时的具体原因(诚实,不冒充 auto / 不给无效的
+ *  `npx @danceiny/gotry doctor --fix` 指引)。纯函数。 */
+function platformAutoUnavailableReason(id) {
+  if (id === 'hbcli') return 'Windows 暂不支持 hbcli 自动安装(staicli 上游无 win 安装面);请按 doctor 指引手动配置或切到 macOS/Linux'
+  if (id === 'reach') return 'Windows 暂不支持 agent-reach 自动安装(pip venv 上游无 win 安装面);请按 doctor 指引手动配置或切到 macOS/Linux'
+  if (id === 'sidebar') return 'Windows 暂不支持 dsh-better-sidebar 自动安装(dsh plugin → pnpm 在 win32 不自动跑);请按 doctor 指引手动配置或切到 macOS/Linux'
+  return 'Windows 暂不支持自动安装;请按 doctor 指引手动配置'
+}
+
+/**
+ * 把单个 doctor item 分到 onboarding 桶(纯函数,与 ts/capabilities/doctor.ts 同口径)。
+ *  auto = 本机可自动安装(setupHbcli/setupReach/setupSidebar 且未被 env opt-out);
+ *  user-action = 浏览器商店/凭证/账号/key/上游授权/手动配置——必须用户本人操作;
+ *  unavailable = 本仓无自动安装面(重装 gotry / Node 升级 / env opt-out / 安装器不自动升级项)。
+ *  LLM key 永远 ok,不进任何桶。
+ */
+function classifyDoctorGap(item, opts = {}) {
+  const platform = opts.platform ?? process.platform
+  const env = opts.env ?? process.env
+  if (!item || !item.level || item.level === 'ok') return 'ok'
+  const label = item.label ?? ''
+  if (label === 'LLM key') return 'ok'
+  const autoSupported = doctorFixAutoSupported(platform)
+  if (label.startsWith('Agent Reach')) return installerEnabled('reach', env) && autoSupported ? 'auto' : 'unavailable'
+  // hbcli:二进制缺失(missing)= auto(setupHbcli 装;win32 → unavailable,上游无 win 安装面);
+  // 凭证未配(degraded)= user-action(平台无关);旧版本(missing,安装器不自动升级)= auto 分桶
+  // 但安装会失败 → 结果兜底 unavailable,诚实不冒充。
+  if (label.startsWith('hbcli')) {
+    if (item.level === 'degraded') return 'user-action'
+    return installerEnabled('hbcli', env) && autoSupported ? 'auto' : 'unavailable'
+  }
+  if (label.startsWith('dsh-better-sidebar')) return installerEnabled('sidebar', env) && autoSupported ? 'auto' : 'unavailable'
+  if (label.startsWith('GoTry Session Bridge')) return 'user-action' // 浏览器商店一键装
+  if (label.startsWith('FlyAI')) return 'user-action' // 上游控制台申请 key
+  if (label.startsWith('dsh-calendar')) return 'user-action' // profile cordis.patch.yml 配置
+  if (label.startsWith('dsh-map-tools')) return 'unavailable' // 随包 vendor,缺失即重装 gotry
+  if (label.startsWith('dsh-tool-ask-user')) return 'unavailable' // 随 dsh 闭包,缺失即重装 gotry
+  if (label.startsWith('Node')) return 'unavailable' // 手动升级运行时
+  return 'unavailable'
+}
+
+/**
+ * 由 doctor items 构建 onboarding 计划(纯函数)。
+ *  promptable = 存在可自动安装缺项(决定是否问那一次)。
+ */
+function buildOnboardingPlan(items, opts = {}) {
+  const platform = opts.platform ?? process.platform
+  const env = opts.env ?? process.env
+  const auto = []
+  const userAction = []
+  const unavailable = []
+  for (const item of items ?? []) {
+    const bucket = classifyDoctorGap(item, { platform, env })
+    if (bucket === 'ok') continue
+    const entry = { label: item.label, level: item.level, detail: item.detail, fix: item.fix }
+    if (bucket === 'auto') auto.push(entry)
+    else if (bucket === 'user-action') userAction.push(entry)
+    else {
+      // win32 平台把本可 auto 的缺项降为 unavailable 时,给具体平台原因(诚实,不冒充 auto,
+      // 也不给 win32 上无效的 `npx @danceiny/gotry doctor --fix` 指引);env opt-out / 随包缺失等保持原 detail。
+      const id = installerIdFor(item.label)
+      if (id && !doctorFixAutoSupported(platform) && installerEnabled(id, env)) {
+        entry.detail = platformAutoUnavailableReason(id)
+      }
+      unavailable.push(entry)
+    }
+  }
+  return { promptable: auto.length > 0, auto, userAction, unavailable }
+}
+
+/**
+ * onboarding 跳过原因(纯函数;inner 与 bootstrap 共用,确保两边判定一致且可单测)。
+ *  返回原因字符串则跳过(零 prompt 零安装),null 则可继续。mode/benchmark 仅 inner
+ *  提供;bootstrap 直接调用时 mode 缺省(不检 non-web),只检 env/argv/isTTY。
+ */
+function onboardingSkipReason({ mode, benchmark, env = process.env, argv = process.argv, isTTY = process.stdin?.isTTY } = {}) {
+  if (mode !== undefined && mode !== 'web') return 'non-web-mode'
+  if (benchmark) return 'benchmark'
+  if (env.GOTRY_SETUP_SKIP === '1') return 'GOTRY_SETUP_SKIP=1'
+  if (env.GOTRY_ONBOARDING_SKIP === '1') return 'GOTRY_ONBOARDING_SKIP=1'
+  if (env.CI) return 'CI'
+  if (Array.isArray(argv) && argv.includes('--no-onboarding')) return '--no-onboarding'
+  if (!isTTY) return 'non-tty'
+  return null
+}
+
+/** 读取 stdin 一行(对 TTY 与注入流均工作;finish 后 pause,不干扰后续 dsh web 的 stdin)。 */
+function readOneLine(input) {
+  return new Promise((resolve) => {
+    let buf = ''
+    let done = false
+    const finish = (line) => {
+      if (done) return
+      done = true
+      input.removeListener('data', onData)
+      input.removeListener('end', onEnd)
+      try { input.pause?.() } catch { /* ignore */ }
+      resolve(line ?? '')
+    }
+    const onData = (chunk) => {
+      buf += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk)
+      const nl = buf.indexOf('\n')
+      if (nl >= 0) finish(buf.slice(0, nl).replace(/\r$/, ''))
+    }
+    const onEnd = () => finish(buf)
+    input.on('data', onData)
+    input.on('end', onEnd)
+    try { input.resume?.() } catch { /* ignore */ }
+  })
+}
+
+/**
+ * 交互 prompt:打印缺项概览 + 一次询问,读一行返回 'yes' | 'no'。
+ *  input/output 可注入(测试);默认 process.stdin/process.stdout。
+ */
+async function promptOnboarding(plan, opts = {}) {
+  const input = opts.input ?? process.stdin
+  const output = opts.output ?? process.stdout
+  output.write('\n[gotry] 启动前检测到可选能力缺项,其中可自动配置:\n')
+  for (const g of plan.auto) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  if (plan.userAction.length || plan.unavailable.length) {
+    output.write('需你本人操作(浏览器商店 / 凭证 / key / 重装),gotry 不自动处理:\n')
+    for (const g of plan.userAction) output.write(`  • ${g.label} —— ${g.detail}\n`)
+    for (const g of plan.unavailable) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  output.write('\n现在自动配置可安装项吗?(y/N,随后继续启动 web) ')
+  const answer = await readOneLine(input)
+  return /^\s*y(es)?\s*$/i.test(answer) ? 'yes' : 'no'
+}
+
+/**
+ * 渲染分类计划(无可自动安装项时):把 needs-user-action / unavailable 逐项带具体原因打印,
+ * 不 prompt 不安装。用于 win32 等无 auto 安装面、或仅凭证/key/重装缺口的交互式启动——
+ * 让用户看见分类与原因,而非只剩后台一行摘要。output 可注入(测试)。
+ */
+function renderClassifiedPlan(plan, output) {
+  output.write('\n[gotry] 启动前检测到可选能力缺项(无可自动安装项,以下需你本人操作或本机暂不支持):\n')
+  if (plan.userAction.length) {
+    output.write('需你本人操作(浏览器商店 / 凭证 / key / 配置),gotry 不自动处理:\n')
+    for (const g of plan.userAction) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  if (plan.unavailable.length) {
+    output.write('本机暂不支持自动安装(平台限制 / 重装 gotry / Node 升级):\n')
+    for (const g of plan.unavailable) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  output.write('详情与指引:对话里让助手调 gotry_doctor,或终端跑 npx @danceiny/gotry doctor\n')
+}
+
+/**
+ * 执行安装(复用 setupHbcli/setupReach/setupSidebar,不建第二套)。
+ *  installers/recheck 可注入(测试用 fakes,永不跑真安装器)。返回逐项结果:
+ *  installed / needs-user-action / unavailable(失败带重试命令)。部分失败不抛、不挡 web。
+ */
+const ONBOARDING_DEFAULT_INSTALLERS = { hbcli: setupHbcli, reach: setupReach, sidebar: setupSidebar }
+
+async function runOnboardingFix(plan, opts = {}) {
+  const installers = { ...ONBOARDING_DEFAULT_INSTALLERS, ...(opts.installers ?? {}) }
+  const recheck = opts.recheck ?? doctorChecks
+  const attempts = {}
+  for (const gap of plan.auto) {
+    const id = installerIdFor(gap.label)
+    const installer = id ? installers[id] : null
+    if (!installer) { attempts[gap.label] = { ok: false, error: 'no installer mapped for this gap' }; continue }
+    try {
+      const r = await installer()
+      attempts[gap.label] = { ok: r?.ok === true, error: r?.error }
+    } catch (e) {
+      attempts[gap.label] = { ok: false, error: e?.message ?? String(e) }
+    }
+  }
+  // 复检决定 auto 项最终状态(安装器自带存在性短路 → 已健康项不重装;幂等)
+  const rechecked = await recheck()
+  const byLabel = new Map(rechecked.map((i) => [i.label, i]))
+  const results = []
+  for (const gap of plan.auto) {
+    const item = byLabel.get(gap.label)
+    if (item && item.level === 'ok') {
+      results.push({ label: gap.label, status: 'installed', reason: item.detail ?? '已就位' })
+    } else {
+      const a = attempts[gap.label]
+      results.push({ label: gap.label, status: 'unavailable', reason: a?.error ?? item?.detail ?? 'install failed', retry: 'npx @danceiny/gotry doctor --fix' })
+    }
+  }
+  for (const gap of plan.userAction) {
+    results.push({ label: gap.label, status: 'needs-user-action', reason: gap.fix ?? gap.detail ?? '需用户本人操作' })
+  }
+  for (const gap of plan.unavailable) {
+    results.push({ label: gap.label, status: 'unavailable', reason: gap.detail ?? '本仓无自动安装面' })
+  }
+  return results
+}
+
+/**
+ * `onboarding` 子命令(inner 以 `onboarding --result-file=…` 同步 inherit 调用;
+ *  亦可直接 `node gotry-bootstrap.js onboarding --scan` 只读查看计划)。
+ *  恒 exit 0(永不挡 web);result JSON 写到 --result-file 告知 inner 是否 prompt 过。
+ *
+ *  opts(注入位,供 bootstrap-tests 在进程内跨 inner→onboarding→web 边界跑真实 onboarding 逻辑,
+ *  永不跑真安装器/开浏览器):input/output(注入流替 stdin/stdout)、isTTY/env/argv(覆盖跳过判定)、
+ *  scan(注入 doctor items 替真机探测)、installers/recheck(注入假安装器/复检)、platform(注入平台)。
+ *  返回 result 对象({ prompted, answered?, results?, skipped?, plan? });CLI 仍恒 exit 0。
+ */
+async function runOnboarding(args, opts = {}) {
+  const resultFile = (args.find((a) => a.startsWith('--result-file=')) ?? '').slice('--result-file='.length) || null
+  const scanOnly = args.includes('--scan')
+  const input = opts.input ?? process.stdin
+  const output = opts.output ?? process.stdout
+  const isTTY = opts.isTTY ?? process.stdin?.isTTY
+  const env = opts.env ?? process.env
+  const argv = opts.argv ?? process.argv
+  const scan = opts.scan ?? doctorChecks
+  const platform = opts.platform ?? process.platform
+  // result 通道硬化:mode 0600 + flag wx——存在路径/符号链接永不覆盖(inner 在 0700
+  // mkdtemp 私有目录下传 result.json,这里 wx 防该确切路径被预置/符号链接互换攻击)。
+  const writeResult = (r) => { if (resultFile) { try { writeFileSync(resultFile, JSON.stringify(r), { mode: 0o600, flag: 'wx' }) } catch { /* 坏 result 不挡 web */ } } }
+
+  if (scanOnly) {
+    const plan = buildOnboardingPlan(await scan(), { platform, env })
+    say(JSON.stringify(plan))
+    return { prompted: false, scan: true, plan }
+  }
+
+  const skipReason = onboardingSkipReason({ env, argv, isTTY })
+  if (skipReason) {
+    const result = { prompted: false, skipped: skipReason }
+    writeResult(result)
+    return result
+  }
+
+  const plan = buildOnboardingPlan(await scan(), { platform, env })
+  if (!plan.promptable) {
+    // 无可自动安装缺项。两类:
+    //  (1) 有需用户操作/不可用项(如 win32 平台不支持自动安装,或仅凭证/key/重装缺口):
+    //      渲染分类计划与具体原因,不 prompt 不安装;标记 reported 让 inner 抑制重复的
+    //      detached doctor 摘要(design §3.1③,#114)——用户已看见分类,不再叠一行摘要。
+    //  (2) 全健康:静默(后台摘要亦静默),不渲染。
+    const reportable = plan.userAction.length + plan.unavailable.length
+    if (reportable > 0) {
+      renderClassifiedPlan(plan, output)
+      const result = { prompted: false, reported: true, plan }
+      writeResult(result)
+      return result
+    }
+    const result = { prompted: false, plan }
+    writeResult(result)
+    return result
+  }
+
+  const answer = await promptOnboarding(plan, { input, output })
+  if (answer === 'yes') {
+    say('[gotry] 开始自动配置可安装项(复用 doctor --fix 幂等安装器)…')
+    const results = await runOnboardingFix(plan, { installers: opts.installers, recheck: opts.recheck })
+    say('')
+    say('[gotry] 配置结果:')
+    for (const r of results) {
+      const tag = r.status === 'installed' ? '✅ installed' : r.status === 'needs-user-action' ? '↪ needs-user-action' : '✗ unavailable'
+      say(`  ${tag}  ${r.label} —— ${r.reason}${r.retry ? `(重试: ${r.retry})` : ''}`)
+    }
+    const result = { prompted: true, answered: 'yes', results }
+    writeResult(result)
+    return result
+  }
+  say('  跳过——随时可跑: npx @danceiny/gotry doctor --fix(随后继续启动 web)')
+  const result = { prompted: true, answered: 'no' }
+  writeResult(result)
+  return result
+}
+
+/**
+ * web 模式的 onboarding + 启动编排(issue #258 E2E 边界缝):
+ *  跳过判定 →(可选)onboarding →(可选)后台 doctor 摘要 → dsh web 启动。抽成显式注入依赖的
+ *  函数,使 bootstrap-tests 能在不 spawn 真 dsh / 不跑真安装器的前提下,断言 inner 的真实编排跨过
+ *  inner→onboarding→web 启动边界(yes/no/非 TTY/部分失败/summary 抑制均到达 web 启动标记)。
+ *  生产侧 inner 传入真实依赖(spawnSync 跑 bootstrap onboarding 子进程、spawn detached 跑 doctor
+ *  --summary、spawn 跑 dsh web);launchWeb 即 web 启动边界标记。
+ *  摘要抑制契约:onboarding 已 prompt(用户交互过)或已 reported(渲染过分类计划,如 win32 无 auto
+ *  安装面)时,抑制重复的 detached doctor 摘要;跳过态(非 TTY/CI/opt-out)与全健康态仍走摘要
+ *  (全健康时摘要本身静默)。返回 onboardingPrompted 供 inner 复用(本函数内已处理摘要抑制,返回值仅信息性)。
+ */
+async function orchestrateWebLaunch({ onboardingSkip, runOnboarding, runSummary, launchWeb }) {
+  let onboardingPrompted = false
+  let onboardingResult = null
+  if (!onboardingSkip) {
+    try { onboardingResult = await runOnboarding() } catch { /* onboarding 不可用不挡 web */ }
+    onboardingPrompted = onboardingResult?.prompted === true
+  }
+  // onboarding 已 prompt 或已 reported(渲染过分类计划)时抑制重复后台摘要(design §3.1③,#114)
+  if (!onboardingPrompted && !onboardingResult?.reported) {
+    try { runSummary() } catch { /* 体检不可用不挡启动 */ }
+  }
+  await launchWeb()
+  return { launched: true, onboardingPrompted, onboardingResult }
+}
+
+const EXTENSION_FILES = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js', 'README.md']
+
+function readManifestVersion(manifestPath) {
+  try { return JSON.parse(readFileSync(manifestPath, 'utf8')).version ?? null } catch { return null }
+}
+
+function copyExtensionDir(srcDir, dstDir) {
+  mkdirSync(dstDir, { recursive: true })
+  for (const f of EXTENSION_FILES) {
+    const s = join(srcDir, f)
+    if (!existsSync(s)) continue
+    copyFileSync(s, join(dstDir, f))
+  }
+}
+
+/** 会话检索扩展(issue #21 方案 C):包内 extension/ → ~/.gotry/extension 幂等落位 + 一次性加载指引 */
+async function setupExtension() {
+  say('[gotry-setup] GoTry Session Bridge 扩展(会话检索数据面 issue #21;一次性安装,替代逐连接弹窗)')
+  const srcDir = join(repoRoot, 'extension')
+  const srcManifest = join(srcDir, 'manifest.json')
+  if (!existsSync(srcManifest)) {
+    say(`  ✗ 包内未找到扩展文件(${srcDir})——不影响 gotry:会话检索降级,重装 npx @danceiny/gotry 可恢复`)
+    return { ok: false }
+  }
+  const srcVersion = readManifestVersion(srcManifest)
+  const dstDir = join(homedir(), '.gotry', 'extension')
+  const dstVersion = readManifestVersion(join(dstDir, 'manifest.json'))
+  if (dstVersion != null && dstVersion === srcVersion) {
+    say(`  ✓ 已就位(~/.gotry/extension,v${dstVersion};若浏览器里尚未加载:chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → 选 ~/.gotry/extension)`)
+    return { ok: true }
+  }
+  if (CHECK_ONLY) { say(`  ✗ ${dstVersion == null ? `未安装(落位 ${dstDir})` : `待更新 v${dstVersion} → v${srcVersion},落位 ${dstDir}`}(--check-only 只报告)`); return { ok: true } }
+  try {
+    copyExtensionDir(srcDir, dstDir)
+  } catch (e) {
+    say(`  ✗ 落位失败(${e.message})——不影响 gotry:会话检索降级;可手动拷贝 ${srcDir} → ${dstDir}`)
+    return { ok: false }
+  }
+  say(`  ✓ 已落位 ${dstDir}(v${srcVersion};manifest 带固定 key,unpacked 扩展 ID 恒为 olpgkofjhhiiiahdkkbcninhjmegghfe)`)
+  say('  推荐(免下面三步):Chrome 应用商店一键安装 GoTry Session Bridge(自动更新): https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd')
+  say('  本地加载(每台浏览器一次,约 30 秒):Chrome 打开 chrome://extensions → 右上角开启「开发者模式」→「加载已解压的扩展程序」→ 选择 ~/.gotry/extension')
+  say('  获取/更新本地通道扩展可走 GitHub Releases:npx @danceiny/gotry setup --extension-from=github(自动下载校验落位;手动下载: github.com/Danceiny/gotry/releases 标签 ext-*)')
+  say('  装好即生效,零系统弹窗;扩展卡片开关=总闸(与 gotry 授权闸 sessionAccess 双重控制)')
+  return { ok: true }
+}
+
+/**
+ * GitHub Releases 下载通道(ADR-21 分发 A,--extension-from=github 显式 opt-in):
+ * repo 态 spawn tsx CLI(与 wizard/health-watch 同款单行 JSON 回传),npm 态 import dist JS;
+ * 任何失败显式降级 bundled 包内副本——安装外部产物永远不挡 gotry 本体。
+ */
+async function setupExtensionFromGithub() {
+  say('[gotry-setup] GoTry Session Bridge 扩展 · GitHub Releases 下载通道(dist-manifest → tar.gz → SHA256 → key 钉扎)')
+  const destDir = join(homedir(), '.gotry', 'extension')
+  const cliScript = join(repoRoot, 'ts', 'scripts', 'extension-distribution-cli.ts')
+  const releaseBase = process.env.GOTRY_EXTENSION_RELEASE_BASE // 镜像/测试基址覆盖;缺省 GitHub 官方
+  let r = null
+  if (existsSync(cliScript)) {
+    r = await new Promise((resolve) => {
+      const child = spawn('npx', ['--yes', 'tsx', cliScript, '--dest', destDir, '--source-dir', join(repoRoot, 'extension'), ...(releaseBase ? ['--release-base', releaseBase] : []), ...(CHECK_ONLY ? ['--check-only'] : [])], {
+        cwd: join(repoRoot, 'ts'),
+        stdio: ['ignore', 'pipe', 'inherit'],
+      })
+      let buf = ''
+      child.stdout.on('data', (c) => { buf += c.toString('utf8') })
+      child.on('close', () => {
+        const line = (buf.trim().split('\n').pop() ?? '')
+        if (line.startsWith('{')) { try { resolve(JSON.parse(line)); return } catch { /* 落到下一行 */ } }
+        resolve({ ok: false, action: 'fallback-bundled', error: `CLI 无 JSON 输出(末行:${line.slice(0, 120)})` })
+      })
+      child.on('error', (e) => resolve({ ok: false, action: 'fallback-bundled', error: `CLI 启动失败 ${e.message}` }))
+    })
+  } else {
+    try {
+      const mod = await import('../dist/capabilities/session/extension-distribution.js')
+      r = await mod.installExtensionFromGithub({ destDir, pinnedSourceDir: join(repoRoot, 'extension'), ...(releaseBase ? { releaseBase } : {}), checkOnly: CHECK_ONLY })
+    } catch (e) {
+      r = { ok: false, action: 'fallback-bundled', error: `dist 模块不可用:${e.message}` }
+    }
+  }
+  if (r && r.ok) {
+    if (r.action === 'installed') {
+      say(`  ✓ 已从 GitHub Releases 落位 ${destDir}(v${r.version}${r.previousVersion ? `,旧 v${r.previousVersion}` : ''})`)
+      say('  已装过旧版的浏览器:chrome://extensions → GoTry Session Bridge 卡片 → 「重新加载」一次即生效(新装跳过)。')
+      return { ok: true }
+    }
+    // up-to-date(check-only 下远端更新也会走到这里,只报告不落盘)
+    if (r.version != null && r.previousVersion != null && r.version !== r.previousVersion) {
+      say(`  ✓ 远端有新版 v${r.version}(本地 v${r.previousVersion})${CHECK_ONLY ? '(--check-only 只报告)' : ''}`)
+      return { ok: true }
+    }
+    say(`  ✓ 已是最新(v${r.version ?? '?'});若浏览器里尚未加载:chrome://extensions → 开发者模式 → 加载已解压 → 选 ${destDir}`)
+    return { ok: true }
+  }
+  say(`  ✗ GitHub 通道失败(${r && r.error ? r.error : '未知'})——显式降级包内副本:`)
+  return setupExtension()
+}
+
+/**
+ * 调 (npm 安装态降级)只确保扩展落位后跑扩展分支 hydration。wizard.ts 现在
+ * 只做 ensure + watch precheck(Node 端职责),不 spawn 任何 GUI;真正的浏览器
+ * 商店页安装走 dsh UI 渲染的 verdict.installUrl,健康探活走 runHealthWatch。
+ *
+ * 历史:wizard-bootstrap.ts(此文件之前 spawn 的 tsx 子进程)已删除;
+ * run-all §40 onboarding-tests 直接 import wizard.ts 的 runOnboardingWizard。
+ */
+async function runWizardBootstrap() {
+  // wizard.ts 已退化为纯 Node 2 步(ensure + watch precheck),不 spawn 任何东西;
+  // tsx 子进程路径 = <repoRoot>/ts;npm 安装态(wizard-bootstrap.ts 已删除)走包内 setupExtension。
+  const wizardScript = join(repoRoot, 'ts', 'scripts', 'wizard-bootstrap.ts')
+  if (!existsSync(wizardScript)) {
+    say('[gotry-wizard] 内置 wizard 脚本缺失(已装 npm 包态;npm 安装态应在浏览器商店一键装,不需要 wizard 跑落位)——只跑包内扩展落位:')
+    await setupExtension()
+    return { ok: true }
+  }
+  return new Promise((resolve) => {
+    const child = spawn('npx', ['--yes', 'tsx', wizardScript, '--extension-dir', join(homedir(), '.gotry', 'extension'), '--source-dir', join(repoRoot, 'extension')], {
+      cwd: join(repoRoot, 'ts'),
+      stdio: ['ignore', 'pipe', 'inherit'],
+    })
+    let stdoutBuf = ''
+    let resolved = false
+    const finish = (r) => {
+      if (resolved) return
+      resolved = true
+      resolve(r)
+    }
+    child.stdout.on('data', (c) => {
+      stdoutBuf += c.toString('utf8')
+      let nl = stdoutBuf.indexOf('\n')
+      while (nl >= 0) {
+        const line = stdoutBuf.slice(0, nl).trim()
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line.startsWith('{')) {
+          try {
+            const o = JSON.parse(line)
+            // 打印 2 步 status(wizard 自己的 print 已在子进程跑了;此处父进程再 human-friendly 一次)
+            if (Array.isArray(o.steps)) {
+              for (const s of o.steps) {
+                const tag = s.status === 'ok' ? '✅' : s.status === 'skip' ? '⏭ ' : '❌'
+                say(`[gotry-wizard] ${tag} ${s.step}: ${s.summary}`)
+              }
+            }
+            say(`[gotry-wizard] extensionDir=${o.extensionDir}; ok=${o.ok}`)
+            finish({ ok: o.ok === true })
+          } catch {
+            say('[gotry-wizard] ✗ wizard JSON 解析失败')
+            finish({ ok: false })
+          }
+          try { child.kill('SIGTERM') } catch { /* ignore */ }
+          return
+        }
+        nl = stdoutBuf.indexOf('\n')
+      }
+    })
+    child.on('exit', (code) => {
+      if (!resolved) {
+        say(`[gotry-wizard] ✗ wizard 子进程 exit ${code}(stdout 无 JSON)`)
+        finish({ ok: code === 0 })
+      }
+    })
+    child.on('error', (e) => {
+      say(`[gotry-wizard] ✗ wizard 子进程启动失败: ${e.message}`)
+      finish({ ok: false })
+    })
+  })
+}
+
+/**
+ * 后台探活扩展心跳(wizard 闭环「装完零重跑」,§3.3):
+ * spawn tsx 跑 health-watch.ts(纯 TS 探活,run-all §40 同一份代码),接 stdout JSON 结果行。
+ * 探活期间每 5s stdout 一行 `.`,用户看见 stdout 持续推进,不卡死假象。
+ * 默认 120s 超时;若用户提前 Ctrl+C,timeoutMs 走 0 立即返回 cancelled。
+ */
+async function runHealthWatch() {
+  // 跨语言:bootstrap 是纯 JS,health-watch 是 TS;走 spawn npx tsx 子进程,stdout 解析。
+  // tsx 子进程路径 = <repoRoot>/ts;不在 npm 包里跑(发布面只走 src/bin,不走 wizard 自动化)
+  const watcherScript = join(repoRoot, 'ts', 'scripts', 'health-watch-cli.ts')
+  // 默认 120s / 5s,§3.3 设计值;env 可覆盖(bootstrap-tests 跑真实路径用)
+  const timeoutMs = parseInt(process.env.GOTRY_ONBOARDING_TIMEOUT_MS ?? '120000', 10) || 120_000
+  const probeIntervalMs = parseInt(process.env.GOTRY_ONBOARDING_INTERVAL_MS ?? '5000', 10) || 5_000
+  return new Promise((resolve) => {
+    const args = [watcherScript, '--timeout', String(timeoutMs), '--interval', String(probeIntervalMs), '--json']
+    // 先确认 watcher 脚本存在(npm 安装态可能未带 ts/目录——降级:走内联 node:http 短探活,避免挡用户)
+    if (!existsSync(watcherScript)) {
+      say(`[gotry-wizard] 内置探活脚本缺失(${watcherScript})——改用内置 5s 轮询`)
+      resolve(runInlineHealthWatch(timeoutMs))
+      return
+    }
+    const child = spawn('npx', ['--yes', 'tsx', ...args], {
+      cwd: join(repoRoot, 'ts'),
+      stdio: ['ignore', 'pipe', 'inherit'],
+      env: { ...process.env, GOTRY_ONBOARDING_HEADLESS: process.env.GOTRY_ONBOARDING_HEADLESS ?? '1' },
+    })
+    let stdoutBuf = ''
+    let heartbeatTicker = 0
+    const hbInterval = setInterval(() => {
+      heartbeatTicker += 1
+      process.stdout.write('.')
+      if (heartbeatTicker % 12 === 0) process.stdout.write(`(${Math.round(heartbeatTicker * probeIntervalMs / 1000)}s)\n`)
+    }, probeIntervalMs)
+    child.stdout.on('data', (c) => {
+      const s = c.toString('utf8')
+      stdoutBuf += s
+      // JSON 结果行以 \n 分隔;watcher 一次性 stdout 一行 JSON 退出
+      let nl = stdoutBuf.indexOf('\n')
+      while (nl >= 0) {
+        const line = stdoutBuf.slice(0, nl).trim()
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line.startsWith('{')) {
+          clearInterval(hbInterval)
+          try {
+            const o = JSON.parse(line)
+            resolve({ ready: o.ready === true, attempts: o.attempts ?? 0, waitedMs: o.waitedMs ?? 0, reason: o.reason ?? 'timeout', timeoutMs })
+          } catch {
+            resolve({ ready: false, attempts: 0, waitedMs: 0, reason: 'parse-error', timeoutMs })
+          }
+          try { child.kill('SIGTERM') } catch { /* ignore */ }
+          return
+        }
+        nl = stdoutBuf.indexOf('\n')
+      }
+    })
+    child.on('exit', (code) => {
+      clearInterval(hbInterval)
+      process.stdout.write('\n')
+      if (code !== 0 && stdoutBuf.trim() === '') {
+        resolve({ ready: false, attempts: 0, waitedMs: 0, reason: `watcher-exit-${code}`, timeoutMs })
+      }
+    })
+    child.on('error', () => {
+      clearInterval(hbInterval)
+      resolve({ ready: false, attempts: 0, waitedMs: 0, reason: 'watcher-spawn-error', timeoutMs })
+    })
+  })
+}
+
+/** npm 安装态(无 ts/目录)降级:内置 5s 轮询 node:http,与 health-watch 同节奏 */
+async function runInlineHealthWatch(timeoutMs) {
+  const intervalMs = parseInt(process.env.GOTRY_ONBOARDING_INTERVAL_MS ?? '5000', 10) || 5_000
+  const ports = [8791, 8792, 8793, 8794, 8795]
+  const http = await import('node:http')
+  const startedAt = Date.now()
+  let attempts = 0
+  while (Date.now() - startedAt < timeoutMs) {
+    attempts += 1
+    for (const port of ports) {
+      const ok = await new Promise((resolve) => {
+        const req = http.request({ host: '127.0.0.1', port, path: '/status', method: 'GET', timeout: 2_000 }, (res) => {
+          if (!res.statusCode || res.statusCode >= 400) { resolve(false); return }
+          let buf = ''
+          res.setEncoding('utf8')
+          res.on('data', (c) => { buf += c })
+          res.on('end', () => {
+            try { resolve(JSON.parse(buf).extensionConnected === true) } catch { resolve(false) }
+          })
+          res.on('error', () => resolve(false))
+        })
+        req.on('error', () => resolve(false))
+        req.on('timeout', () => { req.destroy(); resolve(false) })
+        req.end()
+      })
+      if (ok) {
+        process.stdout.write('\n')
+        return { ready: true, attempts, waitedMs: Date.now() - startedAt, reason: 'ready', timeoutMs }
+      }
+    }
+    process.stdout.write('.')
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+  process.stdout.write('\n')
+  return { ready: false, attempts, waitedMs: Date.now() - startedAt, reason: 'timeout', timeoutMs }
+}
+
+async function main() {
+  // setup flyai 子命令(issue #521):凭据唯一写面(隐藏/stdin/status/clear),
+  // 必须先于 CALENDAR_CMD 判定(命令形如 `setup flyai`)。
+  if (FLYAI_SETUP_CMD) process.exit(await runSetupFlyai())
+
+  // calendar 子命令(issue #106/D-9):可选日历挂载的 setup 状态管理(on/off/status)
+  if (CALENDAR_CMD) process.exit(await runCalendar())
+
+  // doctor 子命令(2026-09-02 迪拜 session 复盘):可选依赖体检 + 补装指引/补装执行;
+  // 只读体检零副作用(--fix 才装),win32 也可跑体检(fix 面另有提示)。
+  if (DOCTOR) process.exit(await runDoctor())
+
+  // onboarding 子命令(issue #258):web 启动前的交互式可选能力配置(恒 exit 0,不挡 web)。
+  if (ONBOARDING) { await runOnboarding(process.argv.slice(2)); process.exit(0) }
+
+// wizard 子命令(2026-09-02 商店上架后退化):**只走 stdout 提示 + 健康探活等待**;
+// 不 spawn 任何 GUI 工具(不动 pbcopy / osascript / open / xdg-open / zenity),
+// 不打开 chrome://extensions,不动扩展路径——浏览器自己当安装器,gotry 不越界。
+if (WIZARD) {
+    if (WIZARD_DRY_RUN) {
+      say('[gotry-wizard] dry-run(零网络零浏览器零剪贴板;run-all §40 走这条)')
+      say('  步骤: ensure-extension-files → watch-extension-ready(2 步纯 Node 端)')
+      say('  平台: 不依赖 darwin/linux/win32(只 stdout)')
+      say('  ✅ exit 0')
+      process.exit(0)
+    }
+    say('')
+    say('[gotry-wizard] ────────────────────────────────')
+    say('[gotry-wizard] GoTry Session Bridge 是浏览器的事——在 Chrome 应用商店一键装:')
+    say('[gotry-wizard]   https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd')
+    say('[gotry-wizard] 装好即生效;装完后我会自动检测到(下方探活等待,最长 120s)。')
+    say('[gotry-wizard] 全过程 gotry 不动你的剪贴板、不开你的 Chrome、不弹任何面板。')
+    say('[gotry-wizard] ────────────────────────────────')
+    say('')
+    say('[gotry-wizard] 探活中(Ctrl+C 立即退出)…')
+
+    // 健康探活等待:扩展一就位即返回;无 GUI/剪贴板副作用
+    const watchResult = await runHealthWatch()
+    if (watchResult.ready) {
+      say(`[gotry-wizard] ✅ 扩展就绪(${watchResult.attempts} 次探活,等待 ${watchResult.waitedMs}ms)`)
+      process.exit(0)
+    } else {
+      say(`[gotry-wizard] ✗ ${watchResult.reason}——未在 ${watchResult.timeoutMs}ms 内就绪`)
+      say('[gotry-wizard] 不需重跑;扩展未装时 dsh UI 中 gotry_session_search 的 needs-extension 会带商店链接,wizard 完全幂等。')
+      process.exit(1)
+    }
+  }
+
+  if (process.platform === 'win32') {
+    say('[gotry-setup] GoTry Session Bridge 扩展:推荐 Chrome 应用商店一键安装 https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd ;本地通道:手动把包内 extension/ 目录拷到 %USERPROFILE%\\.gotry\\extension,再在 chrome://extensions 开发者模式「加载已解压的扩展程序」')
+    process.exit(AUTO ? 0 : 1)
+  }
+  if (AUTO && (process.env.CI || process.env.GOTRY_SETUP_SKIP === '1')) {
+    say('[gotry-setup] CI/GOTRY_SETUP_SKIP 检测——跳过')
+    process.exit(0)
+  }
+  if (!AUTO && process.env.GOTRY_SETUP_SKIP === '1') { say('[gotry-setup] GOTRY_SETUP_SKIP=1——跳过'); process.exit(0) }
+  const results = []
+  // gotry 自留面只剩扩展是否就位;hbcli/agent-reach/dsh-better-sidebar 由各自宿主生态自管。
+  if (process.env.GOTRY_SETUP_EXTENSION !== '0') results.push(await (EXTENSION_FROM === 'github' ? setupExtensionFromGithub() : setupExtension()))
+  else say('[gotry-setup] GoTry Session Bridge 扩展:GOTRY_SETUP_EXTENSION=0 跳过')
+  const failed = results.filter((r) => !r.ok).length
+  if (failed > 0) {
+    say(`[gotry-setup] ${failed} 项未就绪——gotry 本体不受影响;可稍后重跑: npx @danceiny/gotry setup`)
+    process.exit(AUTO ? 0 : 1)
+  }
+  say('[gotry-setup] 扩展就绪检查完成。')
+  process.exit(0)
+}
+
+// 直接执行才跑 main(bootstrap-tests import 本模块做 setupSidebar 单测时不触发安装面;
+// bin/gotry-inner.js 始终以 `node …/gotry-bootstrap.js` 直接 spawn,不受影响)
+if (process.argv[1] && process.argv[1].endsWith('gotry-bootstrap.js')) {
+  main().catch((e) => {
+    say(`[gotry-setup] 异常:${e.message}(不影响 gotry 本体;可重试 npx @danceiny/gotry setup)`)
+    process.exit(AUTO ? 0 : 1)
+  })
+}
+
+export {
+  setupSidebar, sidebarInstalled,
+  classifyDoctorGap, buildOnboardingPlan, onboardingSkipReason,
+  runOnboardingFix, promptOnboarding, renderClassifiedPlan, runOnboarding, orchestrateWebLaunch,
+  doctorFixAutoSupported, platformAutoUnavailableReason, installerEnabled,
+  classifyHbcliWhoami,
+}