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

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

@@ -0,0 +1,794 @@
+/**
+ * 会话扩展桥(extension-bridge,RFC docs/rfc/user-session-data-rfc.md §2.2 通道 C——2026-08-29 founder 定案为 PRIMARY 传输)。
+ *
+ * 形态:Node http 服务,懒启动单例,只绑 127.0.0.1,端口池 8791-8795(与 extension/manifest.json
+ * host_permissions 一一对应,防漂移测试守住);**零新依赖**(node:http 手写,对齐已退役 shell 薄壳
+ * 的回环纪律;不引 ws——MV3 Service Worker 靠 ≤20s 的长轮询节奏维持 30s 存活窗口,HTTP 够用)。
+ *
+ * 授权模型:扩展经「一次性安装」获得信任,每请求校验 Origin ∈ 双通道扩展源白名单
+ * (网页发起的跨域请求必带邪恶 Origin,直接 403;POST 端点强制;GET /health /status 是本机
+ * 诊断面放行)。不做 CORS——有 host_permissions 的扩展 fetch 天然免预检,网页过不来。
+ * 双通道 ID 实录(2026-09-02):unpacked 通道(bundled/GitHub Releases)由 manifest 固定 key
+ * 派生 EXTENSION_ID;Chrome Web Store 用商店自己的签名 key 重签(不认 manifest key),
+ * 商店版 ID = EXTENSION_ID_STORE。两个 ID 都是 founder 控制的同一扩展,白名单双收。
+ *
+ * 协议(长轮询):
+ *   GET  /health           → lastSeen 刷新(扩展每 ≤30s 一次 + 每次断线重连)
+ *   GET  /status           → 诊断面 {port, extensionConnected, lastSeenMsAgo, queued, inFlight, parked}
+ *   POST /jobs             → 长轮询取活(hold ≤20s 返 {job:null});扩展单客户端
+ *   POST /results/:jobId   → 善果/失败回传(≤8MB;batchSearch ~550KB)
+ * 语义:桥不存在即整个扩展车道不存在——fail-closed 不变量在调用方(session-search 的 needs-extension)。
+ * 审计:job 提交/回传写 GuardAuditEntry 同款 JSONL(kind:'extension-session-job',channel 层负责)。
+ */
+
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+
+/** 桥端口池(extension/manifest.json host_permissions 必须同面;§38 断言) */
+export const BRIDGE_PORTS = [8791, 8792, 8793, 8794, 8795] as const
+export const BRIDGE_PROTOCOL = 'session-bridge.v1'
+/** 扩展固定 ID(unpacked 通道:manifest key 派生;bundled/GitHub Releases 均此 ID。变更即失配,Node 侧拒绝) */
+export const EXTENSION_ID = 'olpgkofjhhiiiahdkkbcninhjmegghfe'
+export const EXTENSION_ORIGIN = `chrome-extension://${EXTENSION_ID}`
+/**
+ * Chrome Web Store 版扩展 ID(2026-09-02 上架):商店用自己生成的签名 key 重签,
+ * **不认 manifest 里的固定 key**——商店版 ID 与 unpacked 版不同(上架材料文档的
+ * 「若商店不认 key」预案坐实)。item ID 即商店详情页 URL 末段。
+ */
+export const EXTENSION_ID_STORE = 'oeajpiccmonococjcegddlooeeohlbgd'
+export const EXTENSION_ORIGIN_STORE = `chrome-extension://${EXTENSION_ID_STORE}`
+/** 商店详情页(一键安装 + 自动更新通道;推荐安装方式) */
+export const EXTENSION_STORE_URL = `https://chromewebstore.google.com/detail/gotry-session-bridge/${EXTENSION_ID_STORE}`
+/** 桥信任的扩展 Origin 白名单:unpacked(固定 key)+ 商店版,双通道同一扩展同源信任 */
+export const EXTENSION_ORIGINS: readonly string[] = [EXTENSION_ORIGIN, EXTENSION_ORIGIN_STORE]
+
+/**
+ * 本地 unpacked 通道是否已落位(~/.gotry/extension/manifest.json)。
+ * 商店版没有本地文件面(装在 Chrome 里),离线不可探测——本函数只回答「本地通道在不在」,
+ * 商店版用户在这里恒 false,这正是 D-24 自适应文案的判定输入。
+ */
+export function localExtensionInstalled(home = homedir()): boolean {
+  return existsSync(join(home, '.gotry', 'extension', 'manifest.json'))
+}
+
+/**
+ * needs-extension 自适应摘要(issue #117,D-24 残量):
+ * - 本地 unpacked 已落位 → 完整双通道指引(商店 + GitHub/开发者模式本地通道);
+ * - 未落位(商店版用户,或完全未装)→ 只推商店一键装,并给「已装商店版?打开 Chrome 即可」
+ *   提示——**不再出现开发者模式/本地通道文案**(已装商店版的用户不该再被指导 load unpacked)。
+ * 影响面统一行:账号会话通道断 → 列表底部工具不提供;其余工具不受影响。
+ * 纯函数(默认 HOME 可注入)。
+ *
+ * 双语对照:CN=本函数返回值;EN 权威见 docs/capability-onboarding.md「Session Bridge 安装」段。
+ */
+const EXTENSION_IMPACT_LINE = '影响面:gotry_session_search / gotry_session_login(账号会话通道)不可用;携程机票/酒店实时检索、12306 余票、Dida 实时报价都依赖此通道。其它工具(机票 FlyAI、酒店 hbcli、地图、天气等)不受影响。'
+export function needsExtensionSummary(opts: { localInstalled?: boolean; home?: string } = {}): string {
+  const local = opts.localInstalled ?? localExtensionInstalled(opts.home)
+  if (local) {
+    return 'GoTry Session Bridge 扩展未连接(未安装或已停用)。推荐 Chrome 应用商店一键装(自动更新) '
+      + `${EXTENSION_STORE_URL} ;或 npx @danceiny/gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension。`
+      + EXTENSION_IMPACT_LINE
+  }
+  return 'GoTry Session Bridge 扩展未连接。若你已从 Chrome 商店安装(自动更新):打开 Chrome 并确认扩展已启用即可自动连接,无需再装。'
+    + `若尚未安装:应用商店一键装 ${EXTENSION_STORE_URL} (装完零弹窗,浏览器自己当安装器)。`
+    + EXTENSION_IMPACT_LINE
+}
+/** 扩展在线判定:/health 心跳 ≤30s 一次 + 轮询重连,1.5 倍容差 */
+export const EXTENSION_CONNECTED_WINDOW_MS = 45_000
+/** /jobs 长轮询 hold 上限(必须 < MV3 SW 30s 存活窗口) */
+export const JOBS_LONG_POLL_MS = 20_000
+/** 提交 job 时扩展尚未上线,等它连上桥的宽限(首次调用后桥才拉起,扩展 5s 内即回连) */
+export const DEFAULT_EXTENSION_WAIT_MS = 6_000
+/** /results 回包上限(batchSearch ~550KB,余量给未来酒店/多航段) */
+export const MAX_RESULT_BODY_BYTES = 8 * 1024 * 1024
+
+export type ExtensionJobKind = 'search' | 'open-login' | 'cookie-names'
+
+/** search + multiCollect(dida 推荐流):按接口类别分桶的嗅探回包体 */
+export interface SniffBodies {
+  hotels?: string
+  recommendPrices?: string
+  realtime?: string
+  /** /hotel/list 查询态价格面(2026-09-21): 按城市+日期的酒店报价列表 */
+  searchCache?: string
+}
+
+export interface ExtensionJob {
+  jobId: string
+  kind: ExtensionJobKind
+  site: string
+  /** search / open-login:置顶导航地址(白名单域在扩展侧再校验一道) */
+  url?: string
+  /** search:等嗅探回包上限 */
+  timeoutMs?: number
+  /**
+   * search:dida 推荐流多回包收集(2026-09-11,执行环境迁浏览器客户端)——
+   * find 页加载自发 hotels + recommendPrices 两个接口,单首包语义会丢一半数据;
+   * true 时扩展按类别收齐(或超时结算)后经 bodies 回传
+   */
+  multiCollect?: boolean
+}
+
+export interface ExtensionJobResult {
+  ok: boolean
+  kind?: ExtensionJobKind
+  /** cookie-names:命中票据名(名字级——协议面不存在 cookie 值字段) */
+  names?: string[]
+  /** search:NETWORK_HINTS 命中的响应原文 */
+  body?: string
+  /** search:the exact NETWORK_HINTS response URL selected for body;未命中/超时为空 */
+  url?: string
+  /** search + multiCollect:分桶回包体(见 SniffBodies) */
+  bodies?: SniffBodies
+  title?: string
+  /** search:页面级挑战标记(content-bridge 按 DOM 判定) */
+  challenge?: boolean
+  opened?: boolean
+  timeout?: boolean
+  error?: string
+}
+
+export type SubmitOutcome =
+  | { ok: true; result: ExtensionJobResult; origin?: string; clientId?: string }
+  | { ok: false; reason: 'bridge-unavailable' | 'extension-not-connected' | 'timeout'; summary: string }
+
+export interface SessionJobHandle {
+  submit(job: Omit<ExtensionJob, 'jobId'>, opts?: { timeoutMs?: number; extensionWaitMs?: number; preferredOrigin?: string; preferredClientId?: string }): Promise<SubmitOutcome>
+  extensionConnected(): boolean
+  port: number
+  close(): Promise<void>
+}
+
+export interface SessionBridgeOptions {
+  /** 测试用 [0] 让 OS 分配;缺省 8791..8795 端口池 */
+  ports?: number[]
+  /** 测试覆盖信任的扩展 Origin 白名单;缺省 EXTENSION_ORIGINS(unpacked + 商店版双通道) */
+  extensionOrigins?: readonly string[]
+  now?: () => number
+  /**
+   * **保持桥进程钉住事件循环**(不 unref)。wizard 期间需要:扩展 SW 周期心跳
+   * ≤30s,unref 后 wizard main 一退桥就退,扩展再发心跳连不上 → 误判扩展未就绪。
+   * 真实 session 检索走单 job 流程,默认 unref=true(任何跑完主流程的宿主进程能退出)。
+   * run-all §40 onboarding-tests 用 keepBridge=true 验证 wizard 探活;
+   * §38 session 套件走默认 unref,语义不变。
+   */
+  keepBridge?: boolean
+}
+
+interface QueuedJob {
+  job: ExtensionJob
+  resolve: (outcome: SubmitOutcome) => void
+  timer: ReturnType<typeof setTimeout> | null
+  preferredOrigin?: string
+  claimedOrigin?: string
+  preferredClientId?: string
+  claimedClientId?: string
+}
+
+/**
+ * capability 路由(2026-09-09):/jobs 轮询体里的 capabilities(扩展 SITES 键清单)
+ * 从「上报即弃」升级为**路由依据**——扩展只领自己声明的站点的 job。
+ * 背景:同机多 Chrome(日常 + 测试/多 profile)各自装着同一扩展的不同版本时,
+ * 旧版扩展会领走新站点 job 并答 ok:true 空 names(cookie-names 语义里 conf 缺失
+ * 返 []),把「未登录」伪造成普查结论。按 site ∈ capabilities 匹配后,新站点 job
+ * 只会落到认识它的扩展手里;capabilities 缺省(理论上不存在,当前扩展全部上报)
+ * 视为 match-all,向前兼容。
+ */
+interface ParkedPoller {
+  res: ServerResponse
+  timer: ReturnType<typeof setTimeout>
+  capabilities: Set<string> | null
+  origin: string
+  clientId?: string
+}
+
+/** 扩展客户端标识形状(每 SW 生命周期一个 crypto.randomUUID);导出供事件上行端点(批次 B)同链校验 */
+export const CLIENT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+function jobMatches(entry: QueuedJob, capabilities: Set<string> | null, origin: string, clientId?: string): boolean {
+  if (entry.preferredOrigin && entry.preferredOrigin !== origin) return false
+  if (entry.preferredClientId && entry.preferredClientId !== clientId) return false
+  return capabilities == null || capabilities.size === 0 || capabilities.has(entry.job.site)
+}
+
+function readBody(req: IncomingMessage, cap: number): Promise<string | { err: string }> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    let done = false
+    req.on('data', (c: Buffer) => {
+      if (done) return
+      size += c.length
+      if (size > cap) {
+        done = true
+        req.removeAllListeners('data')
+        resolve({ err: `body 超 ${cap} 字节上限(防失控回包)` })
+        return
+      }
+      chunks.push(c)
+    })
+    req.on('end', () => { if (!done) { done = true; resolve(Buffer.concat(chunks).toString('utf8')) } })
+    req.on('error', () => { if (!done) { done = true; resolve({ err: 'body 读取失败' }) } })
+  })
+}
+
+export interface BridgeQueueStats {
+  queued: number
+  inFlight: number
+  parked: number
+  lastSeenMsAgo: number | null
+}
+
+/**
+ * 传输无关的桥作业队列(2026-09-11 抽出,founder 定案:执行环境=浏览器客户端,
+ * 服务端零 Chrome)——queue/inFlight/parked 三态 + 长轮询协议处理器,
+ * 可挂两种形态:
+ *   - loopback 独立桥(createSessionBridge;gotry 桌面形态,扩展与本机进程同机)
+ *   - gotry-backend 鉴权面挂载(handleMountedRequest;远程扩展经 bearer 鉴权连入,
+ *     浏览器客户端即执行环境,服务器只做编排/队列)
+ */
+export interface BridgeJobQueue extends SessionJobHandle {
+  stats(): BridgeQueueStats
+  /** 完整桥协议(loopback 独立桥形态;/results/:jobId 路径式) */
+  handleRequest(req: IncomingMessage, res: ServerResponse): void
+  /** 挂载形态(/v1/session/bridge 前缀;/results?jobId= 查询式;bearer 鉴权由宿主模块前置) */
+  handleMountedRequest(req: IncomingMessage, res: ServerResponse): void
+  /**
+   * 开机恢复(批次 A;仅 store 注入形态存在,纯内存无此方法):
+   * queued→重排 / claimed 已超时→unresolved+节律记账 / claimed 未超时→复活 inFlight。
+   * gotry-backend 会话模块启动路径调用(见 backend/modules/session-search.ts)。
+   */
+  recoverOnBoot?(): BridgeRecoverySummary
+}
+
+export interface BridgeJobQueueOptions {
+  /** 信任的扩展 Origin 白名单;缺省 EXTENSION_ORIGINS(unpacked + 商店版双通道) */
+  extensionOrigins?: readonly string[]
+  now?: () => number
+  /** 长轮询 parked 定时器是否 unref(独立桥惰性形态用;gotry-backend 常驻服务无需) */
+  keepBridge?: boolean
+  /**
+   * 可选持久账本(DI,批次 A「桥作业账本化」2026-10-01):缺省 undefined = 现状纯内存
+   * (桌面 loopback 形态零变化);gotry-backend 挂载路径传 bridge-ledger 的 SQLite 实现,
+   * 队列/在飞/节律/客户端注册落 <stateRoot>/gotry-state/bridge.db,重启经 recoverOnBoot 收敛。
+   */
+  store?: BridgeJobStore
+}
+
+/**
+ * 桥作业持久账本契约(实现方:capabilities/session/bridge-ledger.ts)。
+ * 只承载**控制状态**——job 元数据、回包、节律、客户端能力清单;协议面不存在
+ * cookie 值字段(§38 红线),账本零凭据。时间戳一律 epoch 毫秒。
+ */
+export interface BridgeJobStore {
+  /** write-before-submit:入队前先落 queued;**抛错 = 提交失败,调用方不得入队派发** */
+  insertQueuedJob(job: ExtensionJob, timeoutAt: number): void
+  /** 领取(/jobs 派发与 dispatchToParked 两处):claimed + 领取者,attempts 递增 */
+  markClaimed(jobId: string, claim: { origin: string; clientId?: string }): void
+  markResolved(jobId: string, result: ExtensionJobResult): void
+  /** 超时/对账结算:曾被领取却未拿到善果终态(带回包则由 recordOrphanResult 落 result) */
+  markUnresolved(jobId: string, note?: { reason: string }): void
+  /** 从未被领取的终态作废(零站点花费) */
+  markVoid(jobId: string): void
+  /** 孤儿回包落库(未知 jobId 的回包内容以 unresolved 保留,供对账) */
+  recordOrphanResult(jobId: string, result: ExtensionJobResult): void
+  /** bridge_clients upsert(/jobs 轮询体 clientId + capabilities 到达即刷新) */
+  upsertClient(clientId: string, origin: string, capabilities: readonly string[]): void
+  /** cookie-names 命中票据名(名字级)→ 记客户端在该站点持有登录态 */
+  recordClientLoginSite(clientId: string, site: string): void
+  /** 站点导航类作业提交/领取:记命中时刻并推冷却 */
+  noteSiteHit(site: string): void
+  /** 超时结算冷却(claimed 超时:站点可能已被打) */
+  applyCooldown(site: string): void
+  pacingOf(site: string): { lastHitAt: number; cooldownUntil: number } | null
+  /** recoverOnBoot 输入:未终态(queued/claimed)作业投影 */
+  listPendingJobs(): Array<{
+    id: string
+    kind: string
+    site: string
+    payload_json: string
+    status: 'queued' | 'claimed'
+    claimed_by_client: string | null
+    claimed_origin: string | null
+    timeout_at: number | null
+    attempts: number
+  }>
+}
+
+/** recoverOnBoot 结算摘要(挂载路径启动日志/测试断言面) */
+export interface BridgeRecoverySummary {
+  /** queued 且未过期 → 重新入队(迟到回包仍可 resolved 落账) */
+  requeued: number
+  /** claimed 且未超时 → 复活进 inFlight(扩展若已领取,回包直达 resolved) */
+  rehydratedInFlight: number
+  /** claimed 且 timeout_at 已过 → unresolved + 节律记账 */
+  settledUnresolved: number
+  /** queued 且 timeout_at 已过(未被领取即过期)→ void,零花费不再派发 */
+  voidedStale: number
+}
+
+/** 站点导航类作业(会真实打开供应商页面的 kind;cookie-names 只读不导航) */
+const NAVIGATION_JOB_KINDS: ReadonlySet<ExtensionJobKind> = new Set(['search', 'open-login'])
+export function isNavigationJobKind(kind: ExtensionJobKind): boolean {
+  return NAVIGATION_JOB_KINDS.has(kind)
+}
+
+export function createBridgeJobQueue(opts: BridgeJobQueueOptions = {}): BridgeJobQueue {
+  const extensionOrigins = new Set(opts.extensionOrigins ?? EXTENSION_ORIGINS)
+  const now = opts.now ?? Date.now
+  const store = opts.store
+  const queue: QueuedJob[] = []
+  const inFlight = new Map<string, QueuedJob>()
+  const parked: ParkedPoller[] = []
+  let lastSeenAt = 0
+  let closed = false
+  const extensionConnected = (): boolean => lastSeenAt > 0 && now() - lastSeenAt < EXTENSION_CONNECTED_WINDOW_MS
+
+  /**
+   * 账本写兜底:持久面故障不得打断桥协议主路径(write-before-submit 的 INSERT 除外,
+   * 它在 submit 里直接决定提交成败)。stderr 留痕,作业照常流转。
+   */
+  const record = (label: string, write: () => void): void => {
+    if (!store) return
+    try {
+      write()
+    } catch (e) {
+      process.stderr.write(`[bridge] 账本写入失败(${label}): ${e instanceof Error ? e.message : String(e)}\n`)
+    }
+  }
+
+  /** 领走首个 capability 匹配的 job(移入 inFlight——回包按 jobId 路由,两处都可找到) */
+  function takeMatching(capabilities: Set<string> | null, origin: string, clientId?: string): QueuedJob | null {
+    const idx = queue.findIndex((q) => jobMatches(q, capabilities, origin, clientId))
+    if (idx < 0) return null
+    const [next] = queue.splice(idx, 1)
+    next.claimedOrigin = origin
+    next.claimedClientId = clientId
+    inFlight.set(next.job.jobId, next)
+    record('markClaimed', () => store!.markClaimed(next.job.jobId, { origin, clientId }))
+    if (isNavigationJobKind(next.job.kind)) record('noteSiteHit', () => store!.noteSiteHit(next.job.site))
+    return next
+  }
+
+  /** 扩展回包:queued 与 inFlight 两处都可寻址(job 执行失败 = result.ok:false,桥自身不吞) */
+  function resolveJob(jobId: string, parsed: ExtensionJobResult): void {
+    const inFlightHit = inFlight.get(jobId)
+    if (inFlightHit) {
+      inFlight.delete(jobId)
+      if (inFlightHit.timer) clearTimeout(inFlightHit.timer)
+      record('markResolved', () => store!.markResolved(jobId, parsed))
+      record('client-login-site', () => {
+        const names = Array.isArray(parsed.names) ? parsed.names : []
+        if (parsed.ok === true && inFlightHit.job.kind === 'cookie-names' && names.length > 0 && inFlightHit.claimedClientId) {
+          store!.recordClientLoginSite(inFlightHit.claimedClientId, inFlightHit.job.site)
+        }
+      })
+      inFlightHit.resolve({ ok: true, result: parsed, origin: inFlightHit.claimedOrigin, clientId: inFlightHit.claimedClientId })
+      return
+    }
+    const idx = queue.findIndex((q) => q.job.jobId === jobId)
+    if (idx < 0) return
+    const [entry] = queue.splice(idx, 1)
+    if (entry.timer) clearTimeout(entry.timer)
+    record('markResolved', () => store!.markResolved(jobId, parsed))
+    entry.resolve({ ok: true, result: parsed })
+  }
+
+  /** 新 job 入队时即时派发给 capability 匹配的 parked 取活者(否则要白等一个 20s 长轮询周期) */
+  function dispatchToParked(entry: QueuedJob): boolean {
+    const i = parked.findIndex((p) => jobMatches(entry, p.capabilities, p.origin, p.clientId))
+    if (i < 0) return false
+    const [p] = parked.splice(i, 1)
+    clearTimeout(p.timer)
+    entry.claimedOrigin = p.origin
+    entry.claimedClientId = p.clientId
+    inFlight.set(entry.job.jobId, entry)
+    record('markClaimed', () => store!.markClaimed(entry.job.jobId, { origin: p.origin, clientId: p.clientId }))
+    if (isNavigationJobKind(entry.job.kind)) record('noteSiteHit', () => store!.noteSiteHit(entry.job.site))
+    p.res.statusCode = 200
+    p.res.setHeader('content-type', 'application/json')
+    p.res.end(JSON.stringify({ job: entry.job }))
+    return true
+  }
+
+  const stats = (): BridgeQueueStats => ({
+    queued: queue.length,
+    inFlight: inFlight.size,
+    parked: parked.length,
+    lastSeenMsAgo: lastSeenAt > 0 ? now() - lastSeenAt : null,
+  })
+
+  /**
+   * 结算器(submit 与 recoverOnBoot 复活条目共用):内存三态清理 + 账本终态落笔。
+   * 幂等护栏(settled 标记)防 waitTimer 兜底在 resolved 之后二次结算把账本写花。
+   * 超时结算规则(批次 A):曾被领取→unresolved+导航类记节律冷却(站点可能已被打);
+   * 从未被领取→void(零花费)。extension-not-connected 同为零花费 void;
+   * close 作废时已领取条目**留在 claimed**——持久记录交给下一轮 recoverOnBoot 收敛
+   * (扩展迟到回包仍可经 recordOrphanResult 对账,不虚构终态)。
+   */
+  function armSettle(entry: QueuedJob, deliver?: (outcome: SubmitOutcome) => void): (outcome: SubmitOutcome) => void {
+    let settled = false
+    return (outcome: SubmitOutcome): void => {
+      if (settled) return
+      settled = true
+      if (entry.timer) clearTimeout(entry.timer)
+      const i = queue.findIndex((q) => q.job.jobId === entry.job.jobId)
+      if (i >= 0) queue.splice(i, 1)
+      const wasClaimed = inFlight.delete(entry.job.jobId) || entry.claimedOrigin !== undefined
+      // outcome.ok 的 resolved 已在 resolveJob 落账;这里只结算失败终态
+      if (store && !outcome.ok) {
+        if (outcome.reason === 'timeout') {
+          if (wasClaimed) {
+            record('markUnresolved', () => store!.markUnresolved(entry.job.jobId, { reason: 'timeout' }))
+            if (isNavigationJobKind(entry.job.kind)) record('applyCooldown', () => store!.applyCooldown(entry.job.site))
+          } else {
+            record('markVoid', () => store!.markVoid(entry.job.jobId))
+          }
+        } else if (outcome.reason === 'extension-not-connected') {
+          record('markVoid', () => store!.markVoid(entry.job.jobId))
+        } else if (!wasClaimed) {
+          record('markVoid', () => store!.markVoid(entry.job.jobId))
+        }
+      }
+      deliver?.(outcome)
+    }
+  }
+
+  /**
+   * 开机恢复(仅 store 形态;纯内存 no-op):
+   *   queued 未过期 → 重新入队(可被派发,迟到善果仍 resolved 落账);
+   *   queued 已过期 → void(未被领取即过期,零花费不再派发);
+   *   claimed 未超时 → 复活进 inFlight(重启丢在飞作业的修复面:扩展若已领取,回包直达);
+   *   claimed 已超时 → unresolved + 导航类记节律冷却(该站点可能已被打)。
+   * payload 损坏(id 不匹配/非 JSON)按不可对账处理:queued→void / claimed→unresolved。
+   */
+  function recoverOnBoot(): BridgeRecoverySummary {
+    const summary: BridgeRecoverySummary = { requeued: 0, rehydratedInFlight: 0, settledUnresolved: 0, voidedStale: 0 }
+    if (!store || closed) return summary
+    let pending: ReturnType<BridgeJobStore['listPendingJobs']> = []
+    try {
+      pending = store.listPendingJobs()
+    } catch (e) {
+      process.stderr.write(`[bridge] 账本恢复读取失败:${e instanceof Error ? e.message : String(e)}\n`)
+      return summary
+    }
+    for (const row of pending) {
+      const expired = row.timeout_at !== null && row.timeout_at <= now()
+      let job: ExtensionJob | null = null
+      try {
+        const parsed = JSON.parse(row.payload_json) as ExtensionJob
+        if (parsed && typeof parsed.jobId === 'string' && parsed.jobId === row.id) job = parsed
+      } catch { /* 损坏 payload 按不可对账处理 */ }
+      if (row.status === 'claimed') {
+        if (!expired && job) {
+          const entry: QueuedJob = {
+            job,
+            resolve: null as unknown as (o: SubmitOutcome) => void,
+            timer: null,
+            claimedOrigin: row.claimed_origin ?? undefined,
+            claimedClientId: row.claimed_by_client ?? undefined,
+          }
+          const settle = armSettle(entry)
+          entry.resolve = settle
+          const remaining = row.timeout_at !== null ? Math.max(row.timeout_at - now(), 1) : 30_000
+          entry.timer = setTimeout(() => settle({ ok: false, reason: 'timeout', summary: `恢复作业 ${row.id} 超时未回包` }), remaining)
+          inFlight.set(row.id, entry)
+          summary.rehydratedInFlight++
+        } else {
+          record('markUnresolved', () => store!.markUnresolved(row.id, { reason: 'timeout' }))
+          if (isNavigationJobKind(row.kind as ExtensionJobKind)) record('applyCooldown', () => store!.applyCooldown(row.site))
+          summary.settledUnresolved++
+        }
+      } else {
+        if (!expired && job) {
+          const entry: QueuedJob = {
+            job,
+            resolve: null as unknown as (o: SubmitOutcome) => void,
+            timer: null,
+          }
+          const settle = armSettle(entry)
+          entry.resolve = settle
+          const remaining = row.timeout_at !== null ? Math.max(row.timeout_at - now(), 1) : 30_000
+          entry.timer = setTimeout(() => settle({ ok: false, reason: 'timeout', summary: `恢复作业 ${row.id} 超时未回包` }), remaining)
+          if (!dispatchToParked(entry)) queue.push(entry)
+          summary.requeued++
+        } else {
+          record('markVoid', () => store!.markVoid(row.id))
+          summary.voidedStale++
+        }
+      }
+    }
+    return summary
+  }
+
+  /**
+   * 协议处理器工厂:prefix='' 为独立桥形态(路径式 results);prefix='/v1/session/bridge'
+   * 为挂载形态(查询式 results——gotry-backend 内核只支持精确路由,jobId 走 query)。
+   * Origin 白名单校验内置于两种形态(远程形态同样强制:网页跨域请求必带邪恶 Origin)。
+   */
+  function makeHandler(prefix: string, resultsViaQuery: boolean, statusExtra?: () => Record<string, unknown>) {
+    return (req: IncomingMessage, res: ServerResponse): void => {
+      if (closed) { res.statusCode = 503; res.end(); return }
+      const urlPath = (req.url ?? '').split('?')[0]
+      const path = prefix && urlPath.startsWith(prefix) ? urlPath.slice(prefix.length) : urlPath
+      const origin = req.headers.origin
+      const isPost = req.method === 'POST'
+      const originTrusted = typeof origin === 'string' && extensionOrigins.has(origin)
+      // 网页侧请求必带 Origin;桥端点只信任白名单内的 chrome-extension:// 源(诊断 GET 面放行)
+      if (isPost && !originTrusted) {
+        res.statusCode = 403
+        res.setHeader('content-type', 'application/json')
+        res.end(JSON.stringify({ ok: false, error: 'origin 不在桥白名单' }))
+        return
+      }
+      // 心跳:扩展平时只走 /jobs 长轮询(健康只在启动探测时 ping 一次)——
+      // 一切携带白名单扩展 Origin 的请求都刷新 lastSeen,否则 45s 后误判扩展掉线;
+      // 无 Origin 的诊断 GET(/health /status)不记心跳,curl 探活不能伪造「扩展在线」
+      if (originTrusted) {
+        lastSeenAt = now()
+      }
+      const finish = (code: number, body: unknown): void => {
+        res.statusCode = code
+        res.setHeader('content-type', 'application/json')
+        res.end(JSON.stringify(body))
+      }
+      if (req.method === 'GET' && path === '/health') {
+        finish(200, { ok: true, service: 'gotry-session-bridge', protocol: BRIDGE_PROTOCOL })
+        return
+      }
+      if (req.method === 'GET' && path === '/status') {
+        finish(200, {
+          ok: true, protocol: BRIDGE_PROTOCOL, ...stats(),
+          extensionConnected: extensionConnected(),
+          ...(statusExtra ? statusExtra() : {}),
+        })
+        return
+      }
+      if (isPost && path === '/jobs') {
+        // 轮询体携带 {extensionVersion, capabilities: SITES 键清单}——按站点 capability
+        // 路由(见 ParkedPoller 注);体缺失/非 JSON 视为 match-all,向前兼容旧扩展。
+        void readBody(req, 64 * 1024).then((body) => {
+          const pollerInfo = ((): { capabilities: Set<string> | null; clientId?: string } => {
+            if (typeof body !== 'string') return { capabilities: null }
+            try {
+              const parsed = JSON.parse(body) as { capabilities?: unknown; clientId?: unknown }
+              return {
+                capabilities: Array.isArray(parsed.capabilities) ? new Set(parsed.capabilities.filter((c): c is string => typeof c === 'string')) : null,
+                ...(typeof parsed.clientId === 'string' && CLIENT_ID_RE.test(parsed.clientId) ? { clientId: parsed.clientId } : {}),
+              }
+            } catch {
+              return { capabilities: null }
+            }
+          })()
+          // 客户端注册落账(store 形态):轮询即刷新 origin/capabilities/last_seen(bridge_clients upsert)
+          if (pollerInfo.clientId) {
+            record('upsertClient', () => store!.upsertClient(pollerInfo.clientId!, origin as string, [...(pollerInfo.capabilities ?? [])]))
+          }
+          const next = takeMatching(pollerInfo.capabilities, origin as string, pollerInfo.clientId)
+          if (next) { finish(200, { job: next.job }); return }
+          // 长轮询:hold ≤ JOBS_LONG_POLL_MS(必须 < MV3 SW 30s 存活窗口,每次响应都续命);
+          // 新 job 提交时即时唤醒 parked 取活者(见 dispatchToParked)
+          const poller: ParkedPoller = { res, timer: null as unknown as ReturnType<typeof setTimeout>, capabilities: pollerInfo.capabilities, origin: origin as string, clientId: pollerInfo.clientId }
+          const parkTimer = setTimeout(() => {
+            const i = parked.findIndex((p) => p.res === res)
+            if (i >= 0) parked.splice(i, 1)
+            finish(200, { job: null })
+          }, JOBS_LONG_POLL_MS)
+          poller.timer = parkTimer
+          // 默认桥是惰性能力:外部扩展的 parked 轮询不得在主流程结束后钉住 CLI。
+          // keepBridge wizard 反过来要靠它守住进程,因此只对默认形态 unref。
+          if (!opts.keepBridge) parkTimer.unref()
+          parked.push(poller)
+          res.on('close', () => {
+            const i = parked.findIndex((p) => p.res === res)
+            if (i >= 0) parked.splice(i, 1)
+            clearTimeout(parkTimer)
+          })
+        })
+        return
+      }
+      const isResults = isPost && (resultsViaQuery ? path === '/results' : path.startsWith('/results/'))
+      if (isResults) {
+        const jobId = resultsViaQuery
+          ? new URL(req.url ?? '', 'http://bridge.local').searchParams.get('jobId') ?? ''
+          : decodeURIComponent(path.slice('/results/'.length))
+        if (!jobId) { finish(400, { ok: false, error: '缺 jobId' }); return }
+        void readBody(req, MAX_RESULT_BODY_BYTES).then((body) => {
+          if (typeof body !== 'string') { finish(400, { ok: false, error: body.err }); return }
+          let parsed: ExtensionJobResult
+          try {
+            parsed = JSON.parse(body) as ExtensionJobResult
+          } catch {
+            finish(400, { ok: false, error: '回包不是 JSON' })
+            return
+          }
+          const assigned = inFlight.get(jobId)
+          if (assigned?.claimedOrigin && assigned.claimedOrigin !== origin) {
+            finish(403, { ok: false, error: '作业由另一扩展 Origin 领取' })
+            return
+          }
+          if (assigned?.claimedClientId && assigned.claimedClientId !== req.headers['x-gotry-client-id']) {
+            finish(403, { ok: false, error: '作业由另一扩展客户端领取' })
+            return
+          }
+          // 未知 jobId(批次 A):不再 200 静默丢弃——404 明示,孤儿回包内容落账
+          // (status='unresolved',result_json 保留)供对账。扩展 postResult 本就有
+          // catch 且不检查状态码(extension/background.js),协议兼容零改动。
+          const known = assigned !== undefined || queue.some((q) => q.job.jobId === jobId)
+          if (!known) {
+            record('orphan-result', () => store!.recordOrphanResult(jobId, parsed))
+            finish(404, { ok: false, error: 'unknown-job' })
+            return
+          }
+          finish(200, { ok: true })
+          resolveJob(jobId, parsed)
+        })
+        return
+      }
+      finish(404, { ok: false, error: 'unknown endpoint' })
+    }
+  }
+
+  const queueHandle: BridgeJobQueue = {
+    port: 0,
+    extensionConnected,
+    stats,
+    handleRequest: makeHandler('', false),
+    handleMountedRequest: makeHandler('/v1/session/bridge', true),
+    ...(store ? { recoverOnBoot } : {}),
+    submit(job, submitOpts = {}) {
+      const extensionWaitMs = submitOpts.extensionWaitMs ?? DEFAULT_EXTENSION_WAIT_MS
+      const timeoutMs = submitOpts.timeoutMs ?? job.timeoutMs ?? 30_000
+      const full: ExtensionJob = { jobId: randomUUID(), ...job }
+      return new Promise<SubmitOutcome>((resolve) => {
+        if (closed) { resolve({ ok: false, reason: 'bridge-unavailable', summary: '扩展桥已关闭' }); return }
+        if (submitOpts.preferredOrigin && !extensionOrigins.has(submitOpts.preferredOrigin)) {
+          resolve({ ok: false, reason: 'bridge-unavailable', summary: '指定扩展 Origin 不在桥白名单' })
+          return
+        }
+        if (submitOpts.preferredClientId && !CLIENT_ID_RE.test(submitOpts.preferredClientId)) {
+          resolve({ ok: false, reason: 'bridge-unavailable', summary: '指定扩展客户端标识无效' })
+          return
+        }
+        // write-before-submit(store 形态):先落 queued 再入队/派发——持久面失败即提交失败,
+        // 绝不派发无账作业。桌面纯内存形态此步整体跳过,行为零变化。
+        if (store) {
+          try {
+            store.insertQueuedJob(full, now() + timeoutMs)
+          } catch (e) {
+            resolve({ ok: false, reason: 'bridge-unavailable', summary: `桥账本写入失败,作业不入队:${e instanceof Error ? e.message : String(e)}` })
+            return
+          }
+          if (isNavigationJobKind(full.kind)) record('noteSiteHit', () => store!.noteSiteHit(full.site))
+        }
+        const entry: QueuedJob = { job: full, resolve: null as unknown as (o: SubmitOutcome) => void, timer: null, preferredOrigin: submitOpts.preferredOrigin, preferredClientId: submitOpts.preferredClientId }
+        const settle = armSettle(entry, resolve)
+        entry.resolve = settle
+        entry.timer = setTimeout(() => {
+          settle({ ok: false, reason: 'timeout', summary: `扩展未在 ${timeoutMs}ms 内回包(标签页无嗅探命中或扩展已停用)` })
+        }, timeoutMs)
+        if (!dispatchToParked(entry)) queue.push(entry)
+        // 扩展未上线:有界等待(桥刚拉起时扩展 ≤5s 即连上);宽限过仍无 → 立即 no-spend 失败,不空耗
+        let waited = 0
+        const waitTimer = setInterval(() => {
+          waited += 250
+          if (queueHandle.extensionConnected()) { clearInterval(waitTimer); return }
+          if (waited >= extensionWaitMs) {
+            clearInterval(waitTimer)
+            settle({
+              ok: false,
+              reason: 'extension-not-connected',
+              // D-24 自适应文案(issue #117):按本地通道是否落位决定是否提及开发者模式
+              summary: needsExtensionSummary(),
+            })
+          }
+        }, 250)
+      })
+    },
+    close: () =>
+      new Promise<void>((resolve) => {
+        closed = true
+        const voided: SubmitOutcome = { ok: false, reason: 'bridge-unavailable', summary: '扩展桥关闭,任务作废(零花费)' }
+        for (const q of queue.splice(0)) {
+          if (q.timer) clearTimeout(q.timer)
+          q.resolve(voided)
+        }
+        for (const [, q] of inFlight) {
+          if (q.timer) clearTimeout(q.timer)
+          q.resolve(voided)
+        }
+        inFlight.clear()
+        for (const p of parked.splice(0)) {
+          clearTimeout(p.timer)
+          p.res.destroy()
+        }
+        resolve()
+      }),
+  }
+  return queueHandle
+}
+
+/** 创 Bridge 服务(测试可直接调;生产走 getOrCreateSessionBridge 懒单例) */
+export async function createSessionBridge(opts: SessionBridgeOptions = {}): Promise<{ ok: true; bridge: SessionJobHandle } | { ok: false; summary: string }> {
+  const ports = opts.ports ?? [...BRIDGE_PORTS]
+  const queueHandle = createBridgeJobQueue(opts)
+  let port = 0
+
+  const server = createServer((req, res) => queueHandle.handleRequest(req, res))
+  server.on('connection', (socket) => {
+    // server.unref() 只解开监听器;已接受的扩展长轮询 socket 仍会引用事件循环。
+    if (!opts.keepBridge) socket.unref()
+  })
+
+  const bridge: SessionJobHandle = {
+    port: 0,
+    extensionConnected: queueHandle.extensionConnected,
+    submit: (job, submitOpts) => queueHandle.submit(job, submitOpts),
+    close: () =>
+      new Promise<void>((resolve) => {
+        void queueHandle.close().then(() => {
+          server.close(() => resolve())
+          server.closeAllConnections?.()
+        })
+      }),
+  }
+
+  const listenAt = (p: number): Promise<void> =>
+    new Promise((resolve, reject) => {
+      const onError = (e: Error): void => { server.off('listening', onListening); reject(e) }
+      const onListening = (): void => { server.off('error', onError); resolve() }
+      server.once('error', onError)
+      server.once('listening', onListening)
+      server.listen(p, '127.0.0.1')
+    })
+
+  for (const p of ports) {
+    try {
+      await listenAt(p)
+      if (!opts.keepBridge) {
+        // 桥是后台服务:不得钉住事件循环——否则任何跑完主流程的宿主进程(如 smoke/CI)无法退出
+        server.unref()
+      }
+      // keepBridge 模式下:wizard 期间要持续监听扩展心跳(30s 周期),
+      // 不 unref 让 server 钉事件循环,wizard main 退时再显式 close 释放。
+      port = (server.address() as { port: number }).port
+      bridge.port = port
+      return { ok: true, bridge }
+    } catch {
+      // 端口被占(如另一个 gotry 实例)——试端口池下一个
+    }
+  }
+  await queueHandle.close().catch(() => { /* ignore */ })
+  return {
+    ok: false,
+    summary: `扩展桥端口池 ${ports.join('/')} 全部被占(多为并行 gotry 实例);不影响官方通道 gotry_flyai_search。关闭多余实例后重试。`,
+  }
+}
+
+/* ---------- 生产懒单例(进程内随 dsh 存活;失败可重试) ---------- */
+
+let singleton: { ok: true; bridge: SessionJobHandle } | { ok: false; summary: string } | null = null
+
+export async function getOrCreateSessionBridge(opts: SessionBridgeOptions = {}): Promise<{ ok: true; bridge: SessionJobHandle } | { ok: false; summary: string }> {
+  if (singleton) return singleton
+  const created = await createSessionBridge(opts)
+  const result = created.ok
+    ? ({ ok: true, bridge: created.bridge } as { ok: true; bridge: SessionJobHandle })
+    : ({ ok: false, summary: created.summary } as { ok: false; summary: string })
+  singleton = result
+  return result
+}
+
+/** 测试隔离:丢弃单例(端口是进程内资源,close 后端口池立即可复用) */
+export async function __resetSessionBridgeForTest(): Promise<void> {
+  if (singleton?.ok) await singleton.bridge.close().catch(() => { /* ignore */ })
+  singleton = null
+}
+
+/** 测试注入:以临时端口的桥替换单例(channel 层测试不碰真实端口池) */
+export function __setSessionBridgeForTest(bridge: SessionJobHandle | null): void {
+  singleton = bridge ? { ok: true, bridge } : null
+}