@danceiny/gotry 0.0.1-rc.15 → 0.0.1-rc.17

package/ts/capabilities/session/extension-distribution.ts

@@ -0,0 +1,264 @@
+/**
+ * 扩展产物分发(issue #21 分发通道,ADR-21;founder 2026-08-30「产物下载和安装也得做成更好的
+ * 用户体验,可以用 github 作为分发渠道」)。
+ *
+ * 平台硬约束(诚实前置):Chrome 禁止普通用户从任意 URL 安装打包 CRX——GitHub 只能改善
+ * 「下载」(版本化/回滚/与 npm 发版节奏解耦),改善不了「安装」;「开发者模式加载已解压」
+ * 那 3 次点击只有上架 Chrome Web Store 才能消掉(商店版自动更新,见 extension-webstore-submission.md)。
+ * manifest 固定 key ⇒ 双通道是同一个扩展 ID(olpgkofjhhiiiahdkkbcninhjmegghfe),端口池/
+ * host_permissions 不随通道漂移——本模块用 key 钉住这一不变量。
+ *
+ * 单一职责:① 产物源解析(bundled 默认离线确定性 | github 显式 opt-in);
+ * ② GitHub Releases 下载链:dist-manifest → tar.gz → SHA256 校验 → tar 解压 → key 钉扎校验
+ *    → 版本比较 → 原子交换 ~/.gotry/extension;
+ * ③ 失败语义:github 源任何失败(无网/404/校验不过/key 漂移)→ 结构化 fallback bundled,
+ *    绝不挡 setup(安装外部产物永远不挡 gotry 本体——bootstrap 契约)。
+ *
+ * 信任边界(诚实声明):TLS 传输 + 同源 dist-manifest 哈希完整性——防截断/损坏/误传资产,
+ * 不防仓库本身被攻陷(无独立 pinning;独立 pin 需把哈希烘进 npm 包,与「扩展更新与 npm
+ * 发版解耦」目标冲突,明确不做)。
+ *
+ * 零新 npm 依赖:fetch 走 Node ≥22 全局;解压走平台原生 `tar -xzf`(macOS/Linux/Windows10+
+ * 自带);SHA256 走 node:crypto。spawn/fetch 可注入(离线测试)。
+ */
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Releases 稳定资产名(每版覆盖同名上传;latest/download 永久链只认稳定名)。
+ *  与 scripts/package-extension.mjs 的资产名必须逐字一致——extension-distribution-tests 防漂移。 */
+export const DIST_ASSET_TARBALL = 'gotry-session-bridge.tar.gz'
+export const DIST_ASSET_STORE_ZIP = 'gotry-session-bridge-store.zip'
+export const DIST_ASSET_MANIFEST = 'extension-dist-manifest.json'
+
+export const DEFAULT_RELEASE_BASE = 'https://github.com/Danceiny/gotry/releases'
+
+export interface ExtensionDistManifest {
+  version: string
+  tarball: string
+  tarballSha256: string
+  zip: string
+  zipSha256: string
+  builtFromCommit?: string
+}
+
+export interface GithubSourceOptions {
+  /** Releases 基址(测试/镜像可指回环);默认 GitHub 官方 */
+  releaseBase?: string
+  /** 注入 fetch(离线测试);默认全局 fetch */
+  fetch?: typeof fetch
+  /** 注入 spawn(离线测试拦截 tar);默认 child_process.spawn */
+  spawnFn?: typeof spawn
+  /** 下载/解压超时(默认 60s,有界) */
+  timeoutMs?: number
+}
+
+export type ExtensionInstallAction = 'installed' | 'up-to-date' | 'fallback-bundled'
+
+export interface ExtensionInstallResult {
+  ok: boolean
+  action: ExtensionInstallAction
+  /** 远端 dist-manifest 声明的版本(action=up-to-date 时也带回,供比较报告) */
+  version?: string
+  /** 交换前 dest 里已就位的版本(无则 undefined) */
+  previousVersion?: string
+  error?: string
+}
+
+/** 纯函数:三段数字版本比较(a<b 负 / 相等 0 / a>b 正;非数字段按 0 处理,长度差补 0) */
+export function compareVersions(a: string, b: string): number {
+  const pa = String(a).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const pb = String(b).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const n = Math.max(pa.length, pb.length)
+  for (let i = 0; i < n; i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+/** 纯函数:Releases latest/download 永久链(稳定资产名) */
+export function distAssetUrls(releaseBase: string = DEFAULT_RELEASE_BASE): { tarball: string; storeZip: string; manifest: string } {
+  const base = releaseBase.replace(/\/+$/, '')
+  return {
+    tarball: `${base}/latest/download/${DIST_ASSET_TARBALL}`,
+    storeZip: `${base}/latest/download/${DIST_ASSET_STORE_ZIP}`,
+    manifest: `${base}/latest/download/${DIST_ASSET_MANIFEST}`,
+  }
+}
+
+const SHA256_RE = /^[0-9a-f]{64}$/
+
+/** 纯函数:dist-manifest 解析,fail-closed(坏 JSON/缺字段/资产名漂移/哈希非 64-hex 一律拒绝) */
+export function parseDistManifest(raw: string): ExtensionDistManifest {
+  let obj: Record<string, unknown>
+  try {
+    obj = JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    throw new Error('dist-manifest 不是合法 JSON')
+  }
+  const version = obj.version
+  const tarball = obj.tarball
+  const tarballSha256 = obj.tarballSha256
+  const zip = obj.zip
+  const zipSha256 = obj.zipSha256
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) throw new Error('dist-manifest.version 缺失或非 x.y.z')
+  if (tarball !== DIST_ASSET_TARBALL) throw new Error(`dist-manifest.tarball 资产名漂移(期望 ${DIST_ASSET_TARBALL})`)
+  if (zip !== DIST_ASSET_STORE_ZIP) throw new Error(`dist-manifest.zip 资产名漂移(期望 ${DIST_ASSET_STORE_ZIP})`)
+  if (typeof tarballSha256 !== 'string' || !SHA256_RE.test(tarballSha256)) throw new Error('dist-manifest.tarballSha256 非 64-hex')
+  if (typeof zipSha256 !== 'string' || !SHA256_RE.test(zipSha256)) throw new Error('dist-manifest.zipSha256 非 64-hex')
+  return {
+    version,
+    tarball,
+    tarballSha256,
+    zip,
+    zipSha256,
+    builtFromCommit: typeof obj.builtFromCommit === 'string' ? obj.builtFromCommit : undefined,
+  }
+}
+
+export function sha256Hex(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/** 读取扩展 manifest 的 key(固定 key ⇒ 固定扩展 ID;分发通道 ID 不变量的锚点) */
+export function readExtensionKey(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { key?: unknown }
+    return typeof m.key === 'string' ? m.key : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function readExtensionVersion(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { version?: unknown }
+    return typeof m.version === 'string' ? m.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function runTar(args: string[], spawnFn: typeof spawn, timeoutMs: number): Promise<{ ok: boolean; error?: string }> {
+  return new Promise((resolve) => {
+    const child = spawnFn('tar', args, { stdio: 'ignore' })
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) {
+        done = true
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          /* ignore */
+        }
+        resolve({ ok: false, error: `tar 超时(>${timeoutMs}ms)` })
+      }
+    }, timeoutMs)
+    child.on('error', (e) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve({ ok: false, error: `tar 不可用:${e.message}` })
+      }
+    })
+    child.on('close', (code) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve(code === 0 ? { ok: true } : { ok: false, error: `tar exit ${code}` })
+      }
+    })
+  })
+}
+
+async function fetchBytes(url: string, fetchFn: typeof fetch, timeoutMs: number): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; error: string }> {
+  try {
+    const res = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status} ${url}` }
+    const buf = new Uint8Array(await res.arrayBuffer())
+    return { ok: true, bytes: buf }
+  } catch (e) {
+    return { ok: false, error: `下载失败 ${(e as Error).message}` }
+  }
+}
+
+export interface InstallFromGithubOptions extends GithubSourceOptions {
+  /** 落位目录(默认 ~/.gotry/extension 由调用方决定,本层不猜) */
+  destDir: string
+  /** 钉扎参照:bundled extension/ 目录(其 manifest key 是 ID 不变量的基准;缺省只做版本校验) */
+  pinnedSourceDir?: string
+  /** 只报告不落盘(up-to-date/将安装哪个版本;不下载 tarball 之外的任何东西) */
+  checkOnly?: boolean
+}
+
+/**
+ * GitHub Releases → ~/.gotry/extension 安装链。
+ * 任何失败都返回 { ok:false, action:'fallback-bundled' }——调用方显式降级 bundled,
+ * 本函数不抛出(bootstrap 契约:安装外部产物永远不挡 gotry 本体)。
+ */
+export async function installExtensionFromGithub(opts: InstallFromGithubOptions): Promise<ExtensionInstallResult> {
+  const timeoutMs = opts.timeoutMs ?? 60_000
+  const fetchFn = opts.fetch ?? fetch
+  const spawnFn = opts.spawnFn ?? spawn
+  const urls = distAssetUrls(opts.releaseBase)
+  const fail = (error: string): ExtensionInstallResult => ({ ok: false, action: 'fallback-bundled', error })
+
+  const mRes = await fetchBytes(urls.manifest, fetchFn, timeoutMs)
+  if (!mRes.ok) return fail(mRes.error)
+  let manifest: ExtensionDistManifest
+  try {
+    manifest = parseDistManifest(new TextDecoder().decode(mRes.bytes))
+  } catch (e) {
+    return fail(`dist-manifest 校验失败:${(e as Error).message}`)
+  }
+
+  const previousVersion = readExtensionVersion(opts.destDir)
+  if (previousVersion != null && compareVersions(manifest.version, previousVersion) <= 0) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion }
+  }
+  if (opts.checkOnly) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion } // check-only 语义:报告远端版本,不落盘
+  }
+
+  const tRes = await fetchBytes(urls.tarball, fetchFn, timeoutMs)
+  if (!tRes.ok) return fail(tRes.error)
+  const actual = sha256Hex(tRes.bytes)
+  if (actual !== manifest.tarballSha256) return fail(`SHA256 不符(期望 ${manifest.tarballSha256.slice(0, 12)}… 实得 ${actual.slice(0, 12)}…)`)
+
+  // 落盘 → tar 解压 → key 钉扎 → 原子交换;incoming 目录同盘保证 rename 原子性
+  const incoming = `${opts.destDir}.incoming-${process.pid}-${Date.now()}`
+  const tarPath = `${incoming}.tar.gz`
+  try {
+    rmSync(incoming, { recursive: true, force: true })
+    mkdirSync(incoming, { recursive: true })
+    writeFileSync(tarPath, tRes.bytes)
+    // 包内含顶层目录 gotry-session-bridge/;--strip-components 落到 incoming 根
+    const ext = await runTar(['-xzf', tarPath, '-C', incoming, '--strip-components', '1'], spawnFn, timeoutMs)
+    if (!ext.ok) return fail(ext.error!)
+
+    const incomingKey = readExtensionKey(incoming)
+    if (incomingKey == null) return fail('解压产物缺 manifest.json/key(非法包)')
+    if (opts.pinnedSourceDir) {
+      const pinnedKey = readExtensionKey(opts.pinnedSourceDir)
+      if (pinnedKey != null && incomingKey !== pinnedKey) return fail('扩展 key 漂移(通道产物与 bundled 不同 ID——拒绝安装,防端口池/host 权限漂移)')
+    }
+    const incomingVersion = readExtensionVersion(incoming)
+    if (incomingVersion !== manifest.version) return fail(`解压产物版本(${incomingVersion})与 dist-manifest(${manifest.version})不符`)
+
+    rmSync(opts.destDir, { recursive: true, force: true })
+    cpSync(incoming, opts.destDir, { recursive: true })
+    return { ok: true, action: 'installed', version: manifest.version, previousVersion }
+  } catch (e) {
+    return fail(`落位失败 ${(e as Error).message}`)
+  } finally {
+    rmSync(incoming, { recursive: true, force: true })
+    rmSync(tarPath, { force: true })
+  }
+}

package/ts/capabilities/session/golden-score.ts

@@ -0,0 +1,139 @@
+import {
+  SESSION_FIELD_ACCURACY_THRESHOLD,
+  type SessionComparableRecord,
+} from './benchmark.ts'
+
+export interface GoldenBand {
+  query_id: string
+  from: string
+  to: string
+  date: string
+  window_dep_local: { earliest: string; latest: string }
+  window_arr_local: { earliest: string; latest: string }
+  duration_min: { min: number; max: number }
+  price_cny: { min: number; max: number }
+  transport_hint: string
+  known_flights: string[]
+}
+
+export interface GoldenSoftScore {
+  pass: boolean
+  total: number
+  correct: number
+  accuracy: number
+  missing: string[]
+  incorrect: string[]
+  golden_source: string
+}
+
+function parseHHmm(value: string): number {
+  const [hours, minutes] = value.split(':')
+  return parseInt(hours!, 10) * 60 + parseInt(minutes!, 10)
+}
+
+function parseLocalMinutes(value: string): number | null {
+  const match = value.match(/(\d{2}):(\d{2})/)
+  if (!match) return null
+  return parseInt(match[1]!, 10) * 60 + parseInt(match[2]!, 10)
+}
+
+function parseLocalDate(value: string): string | null {
+  return value.match(/^(\d{4}-\d{2}-\d{2})[T ]/)?.[1] ?? null
+}
+
+export function scoreSessionAgainstGoldenBand(
+  session: SessionComparableRecord,
+  band: GoldenBand,
+  goldenSource: string,
+): GoldenSoftScore {
+  const missing: string[] = []
+  const hardIncorrect: string[] = []
+  const segment = session.route_segments[0]
+
+  if (!session.query_id) missing.push('query_id')
+  else if (session.query_id !== band.query_id) hardIncorrect.push('query_id')
+  if (!session.currency) missing.push('currency')
+  else if (session.currency !== 'CNY') hardIncorrect.push('currency')
+  if (!session.source) missing.push('source')
+  else if (session.source !== 'ctrip-flight') hardIncorrect.push('source')
+  if (!session.verdict) missing.push('verdict')
+  else if (session.verdict !== 'hit') hardIncorrect.push('verdict')
+
+  if (!segment) {
+    missing.push(
+      'route_segments[0].from',
+      'route_segments[0].to',
+      'route_segments[0].departure_at',
+      'route_segments[0].arrival_at',
+      'route_segments[0].transport_number',
+    )
+  } else {
+    if (!segment.from) missing.push('route_segments[0].from')
+    else if (segment.from !== band.from) hardIncorrect.push('route_segments[0].from')
+    if (!segment.to) missing.push('route_segments[0].to')
+    else if (segment.to !== band.to) hardIncorrect.push('route_segments[0].to')
+    if (!segment.departure_at) missing.push('route_segments[0].departure_at')
+    else if (parseLocalDate(segment.departure_at) !== band.date) {
+      hardIncorrect.push('route_segments[0].departure_at.date')
+    }
+    if (!segment.arrival_at) missing.push('route_segments[0].arrival_at')
+    else if (parseLocalDate(segment.arrival_at) !== band.date) {
+      hardIncorrect.push('route_segments[0].arrival_at.date')
+    }
+    if (!segment.transport_number) missing.push('route_segments[0].transport_number')
+  }
+
+  const softChecks: Array<{ path: string; ok: boolean }> = []
+  if (segment?.departure_at) {
+    const minutes = parseLocalMinutes(segment.departure_at)
+    softChecks.push({
+      path: 'route_segments[0].departure_at',
+      ok: minutes !== null
+        && minutes >= parseHHmm(band.window_dep_local.earliest)
+        && minutes <= parseHHmm(band.window_dep_local.latest),
+    })
+  }
+  if (segment?.arrival_at) {
+    const minutes = parseLocalMinutes(segment.arrival_at)
+    softChecks.push({
+      path: 'route_segments[0].arrival_at',
+      ok: minutes !== null
+        && minutes >= parseHHmm(band.window_arr_local.earliest)
+        && minutes <= parseHHmm(band.window_arr_local.latest),
+    })
+  }
+  if (segment?.transport_number) {
+    const actual = segment.transport_number.toUpperCase()
+    softChecks.push({
+      path: 'route_segments[0].transport_number',
+      ok: band.known_flights.some((flight) => actual.startsWith(flight.toUpperCase()))
+        || band.known_flights.some((flight) => actual.includes(flight.toUpperCase().slice(0, 2))),
+    })
+  }
+  if (Number.isFinite(session.price) && session.price > 0) {
+    const margin = band.price_cny.max * 0.15
+    softChecks.push({
+      path: 'price',
+      ok: session.price >= band.price_cny.min - margin
+        && session.price <= band.price_cny.max + margin,
+    })
+  } else missing.push('price')
+
+  const softIncorrect = softChecks.filter((check) => !check.ok).map((check) => check.path)
+  const incorrect = [...hardIncorrect, ...softIncorrect]
+  // 合同字段固定为 13，缺字段不能靠缩小分母抬高准确率。
+  const total = 13
+  const correct = Math.max(0, total - new Set(missing).size - incorrect.length)
+  const accuracy = total > 0 ? correct / total : 0
+  return {
+    pass: missing.length === 0
+      && hardIncorrect.length === 0
+      && accuracy >= SESSION_FIELD_ACCURACY_THRESHOLD,
+    total,
+    correct,
+    accuracy,
+    missing: Array.from(new Set(missing)),
+    incorrect,
+    golden_source: goldenSource,
+  }
+}

package/ts/capabilities/session/health-watch.ts

@@ -0,0 +1,257 @@
+/**
+ * 扩展健康检查 + 自动重放(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
+ * RFC user-session-data-rfc.md §3.3)。
+ *
+ * 动机:首次 `sessionFlightSearch` 遇 `needs-extension` 时,旧版要求用户装完扩展后**自己重跑命令**;
+ * 本模块把「用户手工重跑」改成「后台有界轮询 + 扩展一就位自动重放同一 query_id」——
+ * 用户装完扩展零后续动作,gotry 自己感知到 ready 后立刻跑同一条 query。
+ *
+ * 形态:
+ * - `startExtensionHealthWatch({ timeoutMs, intervalMs, probe })` 启后台轮询。
+ *   probe 是异步检测函数(默认 GET http://127.0.0.1:{port}/status,扩展 ≤30s 心跳一次,
+ *   1.5 倍容差 EXTENSION_CONNECTED_WINDOW_MS=45s;§38 已经验证扩展心跳节奏)。
+ * - 命中 ready → 调用方自动重放(query_id / args 不变;同一证据文件覆盖)。
+ * - 超时(timeoutMs 默认 120_000)→ 返回 'timeout',调用方降级回 `needs-extension` 错误面。
+ *
+ * 离线合同(run-all §40 onboarding-tests 5/5):
+ * - 三时序分支:probe 0ms ready / 中途 ready / 120s+1ms 超时;
+ * - 同 query_id 重放语义(参数透传);
+ * - 取消语义(timeoutMs=0 立即 timeout;cancel() 立即返回 'cancelled');
+ * - 重放上限(防止 watch 反复 ready/抖动导致无限重放;maxRetries 默认 1)。
+ *
+ * 纪律:
+ * - 不引 GUI 依赖;只 spawn `node:http` 探活(已经在扩展桥验证过,§38 24 断言覆盖);
+ * - 不持锁、不轮询文件、不读 dsh-runtime 共享状态;
+ * - 不污染扩展桥 single-instance;probe 走独立短连接。
+ */
+
+import { request } from 'node:http'
+import {
+  BRIDGE_PORTS,
+  EXTENSION_CONNECTED_WINDOW_MS,
+  type SessionBridgeOptions,
+} from './extension-bridge.ts'
+
+export type HealthWatchOutcome =
+  | { ready: true; attempts: number; waitedMs: number }
+  | { ready: false; reason: 'timeout' | 'cancelled'; attempts: number; waitedMs: number }
+
+export interface HealthWatchOptions extends SessionBridgeOptions {
+  /** 最长等多久(默认 120s);0 = 立即 timeout(便于测试) */
+  timeoutMs?: number
+  /** 探活间隔(默认 5s);必须 < EXTENSION_CONNECTED_WINDOW_MS,否则抖动期漏心跳 */
+  intervalMs?: number
+  /** 探活函数:返回 true 即视为扩展就绪(测试可注入 fake probe)。
+   * 默认走双因子:① 心跳 `/status` extensionConnected === true
+   * + ② 业务探针 cookie-names 真回包(timeout 5s);二者同时通过才算真 ready。
+   * 仅心跳通过但 cookie-names 失败 = 扩展 SW 跑着但 chrome.cookies 权限缺 → 不算 ready。 */
+  probe?: () => Promise<boolean>
+  /** 最大重放次数(默认 1);防止 ready 抖动反复触发 query 重放 */
+  maxRetries?: number
+  /** 取消信号(可选)——给调用方提供立刻终止 watch 的逃生口 */
+  signal?: AbortSignal
+  /** 时间源(测试可注入 fake clock) */
+  now?: () => number
+  /**
+   * 是否启用业务探针(cookie-names)。wizard 默认 true(用户刚装扩展,首次需要双因子验证);
+   * 上线 session 检索可传 false(快速心跳足矣,业务探针会另发一次请求)。
+   */
+  businessProbe?: boolean
+}
+
+export interface HealthWatchController {
+  /** Promise:resolve 时扩展已 ready,可执行重放 */
+  waitReady(): Promise<HealthWatchOutcome>
+  /** 立刻取消;waitReady 立即 resolve {ready:false, reason:'cancelled'} */
+  cancel(reason?: string): void
+  /** 当前 ready 次数(供诊断/审计) */
+  readonly readyCount: number
+}
+
+interface InternalState {
+  cancelled: boolean
+  readyCount: number
+  resolveOutcome: ((o: HealthWatchOutcome) => void) | null
+}
+
+/**
+ * 双因子 probe(默认):心跳 + 业务探针(cookie-names)。
+ * 心跳通过只能证 SW 跑着;业务探针通过证 chrome.cookies 权限齐——二者同过才算
+ * 扩展真正 ready。wizard 必须双因子(用户刚装的扩展可能权限不全),上线 session
+ * 检索可传 `businessProbe:false` 跳业务探针(避免每次检索额外打一次 cookie-names)。
+ *
+ * 不直接 import extension-channel.ts(避免环)—用 dynamic import 懒拿。
+ */
+export async function combinedProbe(opts: HealthWatchOptions, businessProbe: boolean): Promise<boolean> {
+  if (!(await defaultProbe(opts))) return false
+  if (!businessProbe) return true
+  try {
+    // 动态 import 避免 health-watch ↔ extension-channel 双向环
+    const channel = await import('./extension-channel.ts')
+    const bridge = await import('./extension-bridge.ts')
+    // 双因子探针需要常驻桥(wizard 期间):keepBridge=true 透传到 bridge 单例
+    bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true })
+    // 心跳已 ready(刚 defaultProbe 通过)= 扩展一定在线;cookie-names 超时给 8s,
+    // 比心跳间隔 5s 长——保证 tick 间不会撞死 cookie job
+    const cookie = await channel.extensionCookieNames({
+      site: 'ctrip-flight',
+      domain: 'ctrip.com',
+      ticketNames: ['cticket', 'uid'],
+      timeoutMs: 8_000,
+    })
+    // cookie-names.ok = true 表示扩展 SW 真能调 chrome.cookies.getAll(权限齐全);
+    // cookie-names.ok = true + names = [] 也算 ok(用户没登携程但扩展权限齐)。
+    // cookie-names.ok = false 分两类:bridge-unavailable/extension-not-connected(心跳 false 时) / timeout(扩展没回包)——
+    // 后者更可能是 SW 卡了,不应当 ready。但 wizard 必须严格:让用户明确知道权限缺或登录缺。
+    return cookie.ok
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 默认 probe:GET http://127.0.0.1:{port}/status,看 extensionConnected: true
+ * (扩展心跳 ≤30s 一刷,窗口 EXTENSION_CONNECTED_WINDOW_MS=45s 容差)。
+ * 不在端口池内挑一个试——端口是已启动桥的事实,直接拿 opts.ports[0] 或 8791。
+ * 测试可注入 fake probe 跳过网络。
+ */
+export async function defaultProbe(opts: HealthWatchOptions): Promise<boolean> {
+  const ports = opts.ports ?? [...BRIDGE_PORTS]
+  for (const port of ports) {
+    const ok = await new Promise<boolean>((resolve) => {
+      const req = 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: string) => { buf += c })
+          res.on('end', () => {
+            try {
+              const payload = JSON.parse(buf) as { extensionConnected?: boolean }
+              resolve(payload.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) return true
+  }
+  return false
+}
+
+export function startExtensionHealthWatch(opts: HealthWatchOptions = {}): HealthWatchController {
+  const timeoutMs = opts.timeoutMs ?? 120_000
+  const intervalMs = opts.intervalMs ?? 5_000
+  const maxRetries = opts.maxRetries ?? 1
+  const businessProbe = opts.businessProbe ?? true
+  // 关键:wizard 期间需要常驻桥(keepBridge=true 透传到 getOrCreateSessionBridge),
+  // 否则启桥后 wizard main 一退桥就退,扩展心跳发不进来。
+  // 用 dynamic import 避免与 extension-bridge 顶层环(channel 也引 bridge,但 health-watch 引 channel/bridge 双向会死循环)
+  const probe = opts.probe ?? (async () => {
+    // 先确保桥存在 + keepBridge
+    const bridge = await import('./extension-bridge.ts')
+    await bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true })
+    return combinedProbe(opts, businessProbe)
+  })
+  const now = opts.now ?? Date.now
+  const state: InternalState = { cancelled: false, readyCount: 0, resolveOutcome: null }
+
+  const finish = (outcome: HealthWatchOutcome): void => {
+    if (state.resolveOutcome) {
+      const resolve = state.resolveOutcome
+      state.resolveOutcome = null
+      resolve(outcome)
+    }
+  }
+
+  // 取消信号 -> 立刻 timeout-ish 终态(不进 ready 路径)
+  const onAbort = (): void => {
+    state.cancelled = true
+    finish({ ready: false, reason: 'cancelled', attempts: state.readyCount, waitedMs: 0 })
+  }
+  opts.signal?.addEventListener('abort', onAbort, { once: true })
+
+  const waitReady = (): Promise<HealthWatchOutcome> => new Promise<HealthWatchOutcome>((resolve) => {
+    if (state.cancelled) { resolve({ ready: false, reason: 'cancelled', attempts: 0, waitedMs: 0 }); return }
+    if (timeoutMs === 0) { resolve({ ready: false, reason: 'timeout', attempts: 0, waitedMs: 0 }); return }
+    state.resolveOutcome = resolve
+    const deadline = now() + timeoutMs
+    let attempts = 0
+    let waitedMs = 0
+
+    const tick = async (): Promise<void> => {
+      if (state.cancelled || state.resolveOutcome === null) return
+      attempts += 1
+      try {
+        const ready = await probe()
+        if (ready && !state.cancelled) {
+          state.readyCount += 1
+          waitedMs = timeoutMs - Math.max(0, deadline - now())
+          // readyCount > maxRetries → 视为抖动,继续等(避免一次性重放洪流)
+          if (state.readyCount <= maxRetries) {
+            finish({ ready: true, attempts, waitedMs: waitedMs > 0 ? waitedMs : 0 })
+            return
+          }
+        }
+      } catch { /* probe 失败继续轮询,不挡主流程 */ }
+      waitedMs = timeoutMs - Math.max(0, deadline - now())
+      if (now() >= deadline) {
+        finish({ ready: false, reason: 'timeout', attempts, waitedMs })
+        return
+      }
+      // 间隔 = intervalMs;若剩余时间 < intervalMs 则最后一次等剩余时间
+      const remaining = deadline - now()
+      const delay = Math.min(intervalMs, Math.max(0, remaining))
+      if (delay <= 0) {
+        finish({ ready: false, reason: 'timeout', attempts, waitedMs })
+        return
+      }
+      setTimeout(tick, delay)
+    }
+    void tick()
+  })
+
+  return {
+    waitReady,
+    cancel: () => onAbort(),
+    get readyCount() { return state.readyCount },
+  }
+}
+
+/**
+ * 自动重放 wrapper:首次调用走 fetch(返回 needs-extension) → 启 watch →
+ * 扩展 ready → 同 query 重放。语义:用户侧**只看到一条 query 的最终结果**;
+ * 中间产物(query_id 标记 + 尝试次数)落 evidence 文件,便于离线追溯。
+ *
+ * 这是 §3.3「用户零手工重跑」的对外契约:调用方把 fetch 包成 withAutoRetryOnExtension,
+ * 用户装完扩展→自然出结果;用户不装→等 120s 后返回 needs-extension,而不是「再跑一次试试」。
+ */
+export async function withAutoRetryOnExtension<T>(args: {
+  fetch: () => Promise<T>
+  isExtensionNeeded: (result: T) => boolean
+  /** watch 配置(测试可注入 fake probe) */
+  watch?: HealthWatchOptions
+  /** 重放 fetcher(默认复用 fetch) */
+  retry?: () => Promise<T>
+}): Promise<{ result: T; retried: boolean; attempts: number; outcome: HealthWatchOutcome }> {
+  const first = await args.fetch()
+  if (!args.isExtensionNeeded(first)) {
+    return { result: first, retried: false, attempts: 1, outcome: { ready: true, attempts: 0, waitedMs: 0 } }
+  }
+  const watch = startExtensionHealthWatch(args.watch ?? {})
+  const outcome = await watch.waitReady()
+  if (!outcome.ready) {
+    return { result: first, retried: false, attempts: 1, outcome }
+  }
+  const retriedResult = await (args.retry ?? args.fetch)()
+  return { result: retriedResult, retried: true, attempts: 2, outcome }
+}
+
+/** 留作运行时只读检查,防止扩展心跳节律假设漂移(§38 防漂移同款语义) */
+export const HEALTH_WATCH_INTERVAL_FLOOR_MS = 1_000
+export const HEALTH_WATCH_INTERVAL_CEIL_MS = EXTENSION_CONNECTED_WINDOW_MS - 1_000