dsh-plugin-mobile-link 0.4.1 → 0.6.0

package/lib/history.js

@@ -0,0 +1,355 @@
+import { HOST_CALL_TIMEOUT_MS, withTimeout, messageOf } from './history/shared.js'
+import { createProbeRunner } from './history/probe.js'
+import {
+  DEFAULT_LIMIT, DEFAULT_MAX_BYTES, WINDOW_CHUNK,
+  bytesOfRecords, displayRoleOf, roleOf, toRecord,
+} from './history/records.js'
+import { pageFrom, scanOlder } from './history/window.js'
+
+// Re-exported for the caller/tests that read them off this module (single source
+// is `history/records.js`; the call ceiling lives in `history/shared.js`).
+export { DEFAULT_MAX_BYTES, DEFAULT_LIMIT, WINDOW_CHUNK } from './history/records.js'
+export { HOST_CALL_TIMEOUT_MS } from './history/shared.js'
+
+/**
+ * History window reads and in-session search, answered **locally** by the connector.
+ *
+ * Why local: the Host already owns a correct, seq-exact reader
+ * (`ctx.sessionQuery`, see @deepseek-ai/dsh-session-query) but does **not** expose
+ * it over the remote API the phone talks to. The only history method on that
+ * surface is `session/page`, whose `beforeSeq` lands in log-offset space, so a
+ * session containing offset-only events silently skips a stretch of history —
+ * measured at 235 seqs on a real session (see DSHKit's TranscriptPageBoundary).
+ *
+ * So the connector reads the Host's own state through the injected service and
+ * answers two extra methods:
+ *
+ *   _link/sessionWindow  exact window ending before a given seq
+ *   _link/sessionFind    literal text search within one session
+ *
+ * Feature detection is the switch, not version comparison: a connector that
+ * lacks the injected service answers `link/unsupported`, and the phone keeps
+ * using `session/page`. Nothing about the existing methods changes.
+ *
+ * SPIKE NOTE (spec 007, task T008): `probe()` below is a temporary read-only
+ * measurement used to pick the exact Host API mapping. It is wired to
+ * `GET /mobile-link/history-probe` and is removed once the mapping is locked.
+ */
+
+export const WINDOW_METHOD = '_link/sessionWindow'
+export const FIND_METHOD = '_link/sessionFind'
+
+/// Declared in `_link/hello`; the phone switches channels on these.
+/// `history-role-filter`: `_link/sessionWindow` accepts an optional `roles`
+/// array (e.g. `["me"]`) and returns only matching records; the seq cursor
+/// semantics are unchanged (spec 009 T031).
+/// `history-scan-boundary`: a `roles`-filtered page also carries `scanBoundary`,
+/// the seq the scan really reached, so a caller can advance its cursor when a
+/// whole page is filtered empty (spec 009 T039). Purely additive: a client that
+/// does not read the field keeps the old cursor rule.
+export const HISTORY_CAPABILITIES = [
+  'history-window', 'session-search', 'history-role-filter', 'history-scan-boundary',
+]
+
+export function isHistoryMethod(method) {
+  return method === WINDOW_METHOD || method === FIND_METHOD
+}
+
+/// One search chunk, and how many of them one call may scan. Measured on a
+/// 12968-event session: ~320ms per 2000-event chunk, so four chunks keep a call
+/// near 1.3s — well inside the 8s host-call budget and short enough not to hold
+/// the connector's single inbound chain for long (spec 007 FR-019).
+export const SEARCH_CHUNK = 2000
+export const MAX_SEARCH_CHUNKS_PER_CALL = 4
+export const DEFAULT_SEARCH_LIMIT = 50
+export const MIN_QUERY_LENGTH = 2
+
+function idOfAddress(address) {
+  if (address === null || typeof address !== 'object') return undefined
+  if (address.kind === 'session') return typeof address.sessionId === 'string' ? address.sessionId : undefined
+  if (address.kind === 'subagent') {
+    return typeof address.childSessionId === 'string' ? address.childSessionId : undefined
+  }
+  return undefined
+}
+
+/// Validate the optional `roles` argument: unknown values would silently match
+/// nothing, so the caller gets a bad-request instead of an empty page.
+const KNOWN_ROLES = new Set(['me', 'agent', 'tool'])
+
+function parseRoles(value) {
+  if (value === undefined) return { roles: undefined }
+  if (!Array.isArray(value) || value.length === 0) return { roles: undefined }
+  const roles = new Set(value)
+  for (const role of roles) {
+    if (!KNOWN_ROLES.has(role)) {
+      return { error: failure('gateway/bad-request', `unknown role "${String(role)}"`) }
+    }
+  }
+  return { roles }
+}
+
+/// A hit snippet with the highlight offsets the phone's list already renders.
+///
+/// Offsets, not ranges: the value crosses the wire and a character offset stays
+/// meaningful on the other side.
+function makeSnippet(text, query, radius = 36) {
+  const haystack = String(text ?? '')
+  const at = haystack.toLowerCase().indexOf(query.toLowerCase())
+  if (at < 0) {
+    const head = haystack.slice(0, radius * 2).replace(/\s+/g, ' ').trim()
+    return { snippet: head, highlightStart: 0, highlightLength: 0 }
+  }
+  const start = Math.max(0, at - radius)
+  const end = Math.min(haystack.length, at + query.length + radius)
+  const snippet = haystack.slice(start, end).replace(/\s+/g, ' ').trim()
+  // Re-find the match inside the flattened snippet so the offsets line up with
+  // what is actually displayed.
+  const flatAt = snippet.toLowerCase().indexOf(query.toLowerCase())
+  return {
+    snippet,
+    highlightStart: flatAt < 0 ? 0 : flatAt,
+    highlightLength: flatAt < 0 ? 0 : query.length,
+  }
+}
+
+function failure(code, message, details = {}) {
+  return { ok: false, error: { code, message, details } }
+}
+
+/// Map a thrown Host/gateway error onto the contract's codes.
+function hostFailure(error) {
+  const message = messageOf(error)
+  if (/timed out after/.test(message)) return failure('link/timeout', message)
+  if (/not found|no such session/i.test(message)) return failure('session/unknown', message)
+  return failure('gateway/failed', message)
+}
+
+/**
+ * @param {{ logger?: { warn?: Function, info?: Function } }} deps
+ */
+export function createHistoryService({ logger = console } = {}) {
+  let sessionQuery
+  const probeRunner = createProbeRunner({ getQuery: () => sessionQuery, logger })
+  /// Set to false after the Host has told us its full-text index is closed
+  /// (`openAt: "never"`), so later searches go straight to the scan.
+  let indexSearchable = true
+  const inFlight = new Set()
+  const lastSeqCache = new Map()
+
+  /// The log's newest seq, cached briefly: it is only needed to clamp a request
+  /// that runs past the end (a session can be trimmed between two pages).
+  async function newestSeq(sessionId) {
+    const cached = lastSeqCache.get(sessionId)
+    if (cached !== undefined && Date.now() - cached.at < 5000) return cached.seq
+    const records = await withTimeout(sessionQuery.listEvents(sessionId), HOST_CALL_TIMEOUT_MS, 'listEvents')
+    const seq = records.length > 0 ? records[records.length - 1].seq : -1
+    lastSeqCache.set(sessionId, { at: Date.now(), seq })
+    return seq
+  }
+
+  /// One exact backward window ending at `seq` (inclusive).
+  ///
+  /// `clamped` is reported upward: when the session was trimmed, the page cannot
+  /// abut the phone's window, and the phone needs to know that the gap is the
+  /// log's doing rather than a hole it should treat as a bug (FR-002/FR-041).
+  async function readChunk(sessionId, seq) {
+    try {
+      const window = await withTimeout(
+        sessionQuery.readEvent({ sessionId, seq, before: WINDOW_CHUNK, after: 0 }),
+        HOST_CALL_TIMEOUT_MS,
+        'readEvent',
+      )
+      return { window, clamped: false }
+    } catch (error) {
+      // Past the end of a trimmed log: clamp once and retry, never guess.
+      if (!/has no event at seq/.test(messageOf(error))) throw error
+      const newest = await newestSeq(sessionId)
+      if (newest < 0 || newest >= seq) throw error
+      lastSeqCache.delete(sessionId)
+      const window = await withTimeout(
+        sessionQuery.readEvent({ sessionId, seq: newest, before: WINDOW_CHUNK, after: 0 }),
+        HOST_CALL_TIMEOUT_MS,
+        'readEvent(clamped)',
+      )
+      return { window, clamped: true }
+    }
+  }
+
+  /// One page of in-session literal search (spec 007 FR-010…FR-012).
+  ///
+  /// Preferred path is the Host's indexed `searchEvents`; this deployment ships it
+  /// disabled (`openAt: "never"`), so the working path is a bounded scan: chunks of
+  /// `SEARCH_CHUNK` seqs, filtered by seq range **and** the literal text, newest
+  /// first. Each call scans at most `MAX_SEARCH_CHUNKS_PER_CALL` chunks and hands
+  /// back a cursor, so "keep looking older" is the reader's next request rather
+  /// than one call that holds the tunnel.
+  async function find(args) {
+    const sessionId = idOfAddress(args.address)
+    if (sessionId === undefined) return failure('gateway/bad-request', 'address must name a session')
+    const query = typeof args.query === 'string' ? args.query.trim() : ''
+    const roles = Array.isArray(args.roles) && args.roles.length > 0 ? new Set(args.roles) : undefined
+    // 浏览模式：**没有关键词但带了 roles**（读者要看"我问过的全部提问"）。
+    // 这时不按文本过滤，只按 seq 段扫，按角色筛。
+    const browsing = query.length === 0 && roles !== undefined
+    if (!browsing && query.length < MIN_QUERY_LENGTH) {
+      return failure('link/query-too-short', `query must be at least ${MIN_QUERY_LENGTH} characters`)
+    }
+    const limit = Number.isSafeInteger(Number(args.limit)) && Number(args.limit) > 0
+      ? Math.min(Number(args.limit), 200) : DEFAULT_SEARCH_LIMIT
+    // Advanced knob (also used by the measurement route and the tests): a smaller
+    // chunk makes the cursor path reachable on short sessions. Clamped, never 0.
+    const chunk = Number.isSafeInteger(Number(args.chunk)) && Number(args.chunk) > 0
+      ? Math.min(Number(args.chunk), SEARCH_CHUNK) : SEARCH_CHUNK
+    const key = `find:${sessionId}`
+    if (inFlight.has(key)) return failure('link/busy', 'another search is in flight for this session')
+    inFlight.add(key)
+    try {
+      // Fast path when the deployment has the index open. One attempt, and a
+      // refusal is remembered: the scan below is the path that always works.
+      if (indexSearchable && args.cursor === undefined && typeof sessionQuery.searchEvents === 'function') {
+        try {
+          const page = await withTimeout(
+            sessionQuery.searchEvents({ sessionId, query, limit }),
+            HOST_CALL_TIMEOUT_MS,
+            'searchEvents',
+          )
+          const indexed = (page.items ?? [])
+            .map((item) => {
+              const role = roleOf(item)
+              if (roles !== undefined && (role === undefined || !roles.has(role))) return undefined
+              const display = displayRoleOf(item)
+              if (display === undefined) return undefined
+              return { seq: item.seq, role: display, ...makeSnippet(item.snippet ?? item.text ?? '', query) }
+            })
+            .filter(Boolean)
+          return {
+            ok: true,
+            value: {
+              hits: indexed,
+              cursor: page.hasMore === true && page.cursor !== undefined ? String(page.cursor) : null,
+              hasMore: page.hasMore === true,
+              source: 'index',
+            },
+          }
+        } catch (error) {
+          indexSearchable = false
+          logger.info?.(`mobile-link: full-text index unavailable, scanning instead: ${messageOf(error)}`)
+        }
+      }
+      const from = parseSearchCursor(args.cursor)
+      const ceiling = from !== undefined ? from : await newestSeq(sessionId)
+      const hits = []
+      let to = ceiling
+      let scanned = 0
+      while (to >= 0 && hits.length < limit && scanned < MAX_SEARCH_CHUNKS_PER_CALL) {
+        const chunkFrom = Math.max(0, to - chunk + 1)
+        const filters = [{ kind: 'seq', from: chunkFrom, to }]
+        if (!browsing) filters.push({ kind: 'text', text: query })
+        const docs = await withTimeout(
+          sessionQuery.filterEvents(sessionId, filters),
+          HOST_CALL_TIMEOUT_MS,
+          'filterEvents(search)',
+        )
+        scanned += 1
+        // Newest first inside the chunk: the reader asked about something recent
+        // far more often than about something old.
+        for (let index = docs.length - 1; index >= 0; index -= 1) {
+          const doc = docs[index]
+          const role = roleOf(doc)
+          if (roles !== undefined && (role === undefined || !roles.has(role))) continue
+          const display = displayRoleOf(doc)
+          if (display === undefined) continue
+          hits.push({ seq: doc.seq, role: display, ...(query.length > 0
+            ? makeSnippet(doc.text, query)
+            : { snippet: String(doc.text ?? '').slice(0, 72).replace(/\s+/g, ' ').trim(),
+                highlightStart: 0, highlightLength: 0 }) })
+          if (hits.length >= limit) break
+        }
+        to = chunkFrom - 1
+      }
+      const hasMore = to >= 0 && hits.length >= limit ? true : to >= 0
+      return {
+        ok: true,
+        value: {
+          hits,
+          cursor: hasMore ? String(to) : null,
+          hasMore,
+          scannedChunks: scanned,
+          source: 'scan',
+        },
+      }
+    } catch (error) {
+      logger.warn?.(`mobile-link: sessionFind failed: ${messageOf(error)}`)
+      return hostFailure(error)
+    } finally {
+      inFlight.delete(key)
+    }
+  }
+
+  /// The cursor is the next `to` seq — opaque to the phone, validated here.
+  function parseSearchCursor(cursor) {
+    if (typeof cursor !== 'string' || cursor.length === 0) return undefined
+    const value = Number(cursor)
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined
+  }
+
+  async function window(args) {
+    const sessionId = idOfAddress(args.address)
+    const before = Number(args.before)
+    if (sessionId === undefined) return failure('gateway/bad-request', 'address must name a session')
+    if (!Number.isSafeInteger(before) || before < 0) return failure('gateway/bad-request', 'before must be a non-negative integer')
+    const limit = Number.isSafeInteger(Number(args.limit)) && Number(args.limit) > 0 ? Number(args.limit) : DEFAULT_LIMIT
+    const maxBytes = Number.isSafeInteger(Number(args.maxBytes)) && Number(args.maxBytes) > 0
+      ? Number(args.maxBytes) : DEFAULT_MAX_BYTES
+    const through = Number.isSafeInteger(Number(args.through)) ? Number(args.through) : undefined
+    // Optional role filter (spec 009 T031): e.g. `roles: ["me"]` returns only
+    // the caller's own questions. Filtering affects **which records come back,
+    // never the cursor**: the window is still read as contiguous seqs and
+    // `before` still bounds the newest edge exactly. Since T039 a filtered page
+    // also carries `scanBoundary` (see history/window.js) so a caller can keep
+    // moving when a whole page is filtered empty.
+    const { roles, error: rolesError } = parseRoles(args.roles)
+    if (rolesError) return rolesError
+
+    const key = `window:${sessionId}`
+    if (inFlight.has(key)) return failure('link/busy', 'another window read is in flight for this session')
+    inFlight.add(key)
+    try {
+      const scan = await scanOlder({ readChunk, sessionId, before, through, limit, maxBytes, roles })
+      return { ok: true, value: pageFrom(scan, { limit, maxBytes, roles }) }
+    } catch (error) {
+      logger.warn?.(`mobile-link: sessionWindow failed: ${messageOf(error)}`)
+      return hostFailure(error)
+    } finally {
+      inFlight.delete(key)
+    }
+  }
+
+  return {
+    /// Called from an optional injection; absent on Hosts that predate the service.
+    bindQuery(service) {
+      sessionQuery = service
+      logger.info?.('mobile-link: history service bound to ctx.sessionQuery')
+    },
+    get available() {
+      return sessionQuery !== undefined
+    },
+
+    /// Frame handler for the two methods.
+    async handle(method, args = {}) {
+      if (sessionQuery === undefined) {
+        return failure('link/unsupported', 'this Host does not expose the session query service')
+      }
+      if (method === WINDOW_METHOD) return window(args)
+      if (method === FIND_METHOD) return find(args)
+      return failure('link/unknown-method', String(method))
+    },
+
+    /// Exposed for the unit tests and the (gated) measurement route.
+    /// 只读测量（spec 007 T008/T047）：实现见 `history/probe.js`。
+    async probe(args = {}) {
+      return probeRunner(args)
+    },
+  }
+}

package/lib/index.js

@@ -7,12 +7,15 @@
  *      never been registered, redeem the invite code from the environment (or
  *      the config) first, so a fresh install becomes usable without the relay
  *      operator provisioning anything by hand.
- *   2. Three routes under `/mobile-link` behind DSH's own connection fence:
+ *   2. Two routes under `/mobile-link` behind DSH's own connection fence:
  *      GET  /status     — is the link up, which devices are attached, and is
  *                         this computer registered yet
- *      POST /pair-code  — mint a pairing code + QR payload through the relay
- *      GET  /qr         — the same code rendered as a scannable QR SVG
+ *      POST /pair-code  — mint a pairing code through the relay, with the QR
+ *                         payload and the symbol rendered alongside it
  *
+ * The pairing screen itself lives in the client half (`lib/client.js`, spec 010):
+ * a standing button in the sidebar plus a panel that shows the code, its QR and
+ * the paired phones. There is no browser page for pairing any more.
  * Deliberate design choices:
  *   * The plugin declares **no required services** (`inject` is empty). The DLP
  *     agent must run even if a future DSH renames or drops `webServer` /
@@ -28,6 +31,7 @@
 
 import { MobileLinkAgent } from './link.js'
 import { registerMobileLinkRoutes } from './routes.js'
+import { createHistoryService } from './history.js'
 
 /** Cordis function-plugin name (the loader row id is separate). */
 export const name = 'mobile-link'
@@ -116,10 +120,10 @@ function startAgent(ctx, agent, logger) {
 }
 
 /** 三条本机 HTTP 路由；只依赖 `webServer`，缺了也不影响链路。 */
-function registerRoutes(ctx, agent, logger, config) {
+function registerRoutes(ctx, agent, logger, config, history) {
   try {
     ctx.inject(['webServer'], (scope) => {
-      const disposers = registerMobileLinkRoutes(scope, { agent, logger, config })
+      const disposers = registerMobileLinkRoutes(scope, { agent, logger, config, history })
       scope.effect?.(() => () => {
         for (const dispose of disposers) {
           try {
@@ -154,6 +158,22 @@ function wireEndpointResolver(ctx, agent, logger) {
   }
 }
 
+/**
+ * 把宿主的会话查询服务交给历史能力（**可选注入**）。
+ *
+ * 拿不到就保持"不支持"：宿主里没有这个服务（旧版本）时，历史能力回 `link/unsupported`，
+ * 手机端继续走 `session/page`。这条注入刻意独立于链路本身——注入失败不影响连接器运行。
+ */
+function wireSessionQuery(ctx, history, logger) {
+  try {
+    ctx.inject(['sessionQuery'], (scope) => {
+      history.bindQuery(scope.sessionQuery)
+    })
+  } catch (error) {
+    logger.warn?.(`mobile-link: session query unavailable (history falls back): ${error}`)
+  }
+}
+
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
  * @param {Record<string, unknown>} rawConfig
@@ -162,10 +182,13 @@ export function apply(ctx, rawConfig) {
   const config = { ...DEFAULTS, ...asRecord(rawConfig) }
   const logger = ctx.logger ?? console
   const agent = buildAgent(config, logger)
+  const history = createHistoryService({ logger })
+  agent.setHistoryService?.(history)
 
   startAgent(ctx, agent, logger)
-  registerRoutes(ctx, agent, logger, config)
+  registerRoutes(ctx, agent, logger, config, history)
   wireEndpointResolver(ctx, agent, logger)
+  wireSessionQuery(ctx, history, logger)
   logger.info?.(`mobile-link: ready (relay ${config.relayUrl})`)
 }
 

package/lib/link.js

@@ -8,6 +8,16 @@ import { EventEmitter } from 'node:events'
 
 import { DshClient } from './dsh-client.js'
 import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
+
+/**
+ * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
+ *
+ * 为什么需要它：插件热更会重新求值模块、再建一个 Link，而旧的实例还占着那条连接
+ * （中转只认一个 agent 会话）。新实例于是连不上、手机那侧"连上了却没有链路"。
+ * 2026-10-09 00:00–00:42 真机连不上就是这个：连接器 43 分钟没回来。
+ * 挂在 `globalThis` 上是因为模块重载会把模块作用域清掉，只有进程级才留得住。
+ */
+const LIVE_AGENT = Symbol.for('dsh.mobile-link.live-agent')
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
 import { statusSnapshot } from './status.js'
@@ -46,6 +56,7 @@ export class MobileLinkAgent extends EventEmitter {
     relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl,
     logger = console, heartbeatMs = 20000, pongTimeoutMs = 60000, maxBackoffMs = 30000,
     random = Math.random, now = Date.now, dshClient, connectImpl = wsConnect, enabled = true,
+    watchdogMs = 180000,
     inviteCode, fetchImpl = fetch, env = process.env,
     // 手机不在时替它攒下来的提问条数上限（见 router.js）；环境变量给部署用，
     // 构造参数给测试用。**没有"留多久"这个旋钮**：`$events` 一直留到设备被撤销。
@@ -57,6 +68,7 @@ export class MobileLinkAgent extends EventEmitter {
     this.heartbeatMs = heartbeatMs
     this.pongTimeoutMs = pongTimeoutMs
     this.maxBackoffMs = maxBackoffMs
+    this.watchdogMs = watchdogMs
     this.random = random
     this.now = now
     this.connectImpl = connectImpl
@@ -85,6 +97,9 @@ export class MobileLinkAgent extends EventEmitter {
     this.identity = undefined
     /** Which host form we are running in (`desktop` / `web` / `unknown`); set by the plugin. */
     this.hostForm = 'unknown'
+    /// 历史读取（spec 007）：宿主 `sessionQuery` 就绪后由插件挂上；没挂上时
+    /// 路由回 `link/unsupported`，手机继续走 `session/page`。
+    this.setHistoryService = (service) => { this.router.history = service }
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -100,6 +115,9 @@ export class MobileLinkAgent extends EventEmitter {
     this._inbox = Promise.resolve()
     this._lastPong = 0
     this._loop = undefined
+    this._loopActive = false
+    this._watchdog = undefined
+    this._lastProgressAt = 0
     this._abort = new AbortController()
 
     // The mux is shared by every device, so its events are wired once here.
@@ -199,6 +217,17 @@ export class MobileLinkAgent extends EventEmitter {
       this.emit('status')
       return this
     }
+    // 先把上一个实例停掉（热更留下的那条连接）：不停的话两个实例会抢同一个 agent 会话，
+    // 表现就是"手机连上中转、却等不到任何回复"。
+    const previous = globalThis[LIVE_AGENT]
+    if (previous && previous !== this) {
+      try {
+        await previous.stop()
+      } catch {
+        /* 旧实例停不掉也不能挡住新的 */
+      }
+    }
+    globalThis[LIVE_AGENT] = this
     if (this._loop) return this
     this._stopping = false
     this._abort = new AbortController()
@@ -206,15 +235,22 @@ export class MobileLinkAgent extends EventEmitter {
     this.state = 'connecting'
     // 解析器可能在上一次会话里就已经装好；这里补一次本机发现（失败无妨）。
     void this.refreshLocal()
+    this._lastProgressAt = this.now()
+    this.#startWatchdog()
+    this._loopActive = true
     this._loop = this.#run().catch((error) => {
       this.lastError = messageOf(error)
       this.state = 'failed'
       this.emit('status')
+    }).finally(() => {
+      this._loopActive = false
     })
     return this
   }
 
   async stop() {
+    this.#stopWatchdog()
+    if (globalThis[LIVE_AGENT] === this) globalThis[LIVE_AGENT] = undefined
     this._stopping = true
     this._abort.abort()
     this.#teardownSocket('agent stopped')
@@ -324,6 +360,7 @@ export class MobileLinkAgent extends EventEmitter {
     this.socket = socket
     this.state = 'connected'
     this.connectedAt = this.now()
+    this._lastProgressAt = this.now()
     this.lastError = undefined
     this.router.lastError = undefined
     this._lastPong = this.now()
@@ -362,6 +399,54 @@ export class MobileLinkAgent extends EventEmitter {
     })
   }
 
+  /**
+   * 看门狗：**与单次会话的心跳无关**的兜底。
+   *
+   * 心跳只在"连上之后"跑，而且会话卡死时它依赖 `setInterval` 还在（热更把它换掉就没了）。
+   * 看门狗每 `heartbeatMs` 看一次"链路最近有没有进展"：
+   *  * 已连上但超过 `pongTimeoutMs` 没动静 ⇒ 强制拆掉这条 socket（会话随即返回、进重连）；
+   *  * **循环已经不在了**（`_loopActive === false`，典型是热更换掉了实例）⇒ 重新拉起循环。
+   * 正常重连退避期间（循环还在、状态是 connecting/backoff）它什么都不做，只在
+   * 超过 `watchdogMs` 仍无进展时把 socket 拆掉重来一次，避免"半开连接永远挂着"。
+   */
+  #startWatchdog() {
+    this.#stopWatchdog()
+    // 检查频率：至少在"判定超时"的窗口里看两次，最多 5 秒一次、最少 1 秒一次。
+    // 不能跟着 `heartbeatMs` 走——心跳间隔设得大（例如测试里 60s）会让看门狗也 20s 才醒一次。
+    const every = Math.max(1000, Math.min(Math.floor(this.pongTimeoutMs / 2) || 1000, 5000))
+    this._watchdog = setInterval(() => {
+      if (this._stopping || this.enabled === false) return
+      const idle = this.now() - this._lastProgressAt
+      if (!this._loopActive) {
+        this.lastError = `链路循环不在了（看门狗重拉，空闲 ${Math.round(idle / 1000)}s）`
+        this.logger.warn?.(`mobile-link: ${this.lastError}`)
+        this._loop = undefined
+        this._lastProgressAt = this.now()
+        void this.start()
+        return
+      }
+      if (this.state === 'connected' && idle > this.pongTimeoutMs) {
+        this.lastError = `relay 超过 ${Math.round(idle / 1000)}s 没有动静（看门狗拆连接）`
+        this.logger.warn?.(`mobile-link: ${this.lastError}`)
+        this.#teardownSocket(this.lastError)
+        this._lastProgressAt = this.now()
+        return
+      }
+      if (this.state !== 'connected' && idle > this.watchdogMs) {
+        this.lastError = `链路 ${Math.round(idle / 1000)}s 没有进展（看门狗重建连接）`
+        this.logger.warn?.(`mobile-link: ${this.lastError}`)
+        this.#teardownSocket(this.lastError)
+        this._lastProgressAt = this.now()
+      }
+    }, every)
+    this._watchdog.unref?.()
+  }
+
+  #stopWatchdog() {
+    if (this._watchdog) clearInterval(this._watchdog)
+    this._watchdog = undefined
+  }
+
   #startHeartbeat() {
     this.#stopHeartbeat()
     this._heartbeat = setInterval(() => {
@@ -440,9 +525,12 @@ export class MobileLinkAgent extends EventEmitter {
 
   /** Route one frame from the relay. */
   async handleRelayFrame(frame) {
+    // 中转来的任何一帧都算"链路有进展"——看门狗据此区分"半开连接"与"正在正常工作"。
+    this._lastProgressAt = this.now()
     if (!frame || typeof frame !== 'object') return
     if (frame.t === 'pong') {
       this._lastPong = this.now()
+      this._lastProgressAt = this.now()
       return
     }
     if (frame.t === 'ping') {

package/lib/qr.js

@@ -551,11 +551,19 @@ export function qrMatrix(text, { mask } = {}) {
  * One path element rather than thousands of rects: small enough to print in a
  * terminal response, and it renders identically. The four-module quiet zone is
  * not decoration — scanners need it to find the symbol at all.
+ *
+ * `caption` draws one line under the symbol. It exists because a pairing code
+ * expires and the page is only a picture: without the line, "还剩多久" is
+ * something a person has to guess, and a guess is what leads to scanning a code
+ * that is already gone. The font stack names the CJK faces explicitly — the
+ * default SVG font renders the caption as boxes on some systems.
  */
-export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light = '#ffffff', mask } = {}) {
+export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light = '#ffffff',
+                              mask, caption } = {}) {
   const matrix = qrMatrix(text, mask === undefined ? {} : { mask })
   const size = matrix.length
   const extent = (size + quietZone * 2) * scale
+  const captionHeight = caption ? Math.round(scale * 4.5) : 0
   const segments = []
   for (let row = 0; row < size; row += 1) {
     for (let column = 0; column < size; column += 1) {
@@ -565,14 +573,35 @@ export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light
       segments.push(`M${x} ${y}h${scale}v${scale}h-${scale}z`)
     }
   }
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${extent}" height="${extent}"`
-    + ` viewBox="0 0 ${extent} ${extent}" shape-rendering="crispEdges" role="img"`
+  const captionMarkup = caption
+    ? `<text x="${extent / 2}" y="${extent + Math.round(captionHeight * 0.7)}"`
+      + ` text-anchor="middle" font-family="PingFang SC, Hiragino Sans GB, Microsoft YaHei, sans-serif"`
+      + ` font-size="${Math.round(scale * 1.75)}" fill="${dark}">${escapeXml(caption)}</text>`
+    : ''
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${extent}" height="${extent + captionHeight}"`
+    + ` viewBox="0 0 ${extent} ${extent + captionHeight}" role="img"`
     + ` aria-label="DSH 配对二维码">`
-    + `<rect width="${extent}" height="${extent}" fill="${light}"/>`
-    + `<path d="${segments.join('')}" fill="${dark}"/>`
+    + `<rect width="${extent}" height="${extent + captionHeight}" fill="${light}"/>`
+    // crispEdges belongs to the symbol, not to the document: the caption is text,
+    // and rendering *that* without antialiasing is what makes it look broken.
+    + `<path d="${segments.join('')}" fill="${dark}" shape-rendering="crispEdges"/>`
+    + captionMarkup
     + '</svg>'
 }
 
+/**
+ * The five characters that cannot appear literally in XML text.
+ *
+ * The caption is built from a clock and a count, but it is a parameter, so it is
+ * escaped here rather than trusted: an unescaped `&` produces an SVG the browser
+ * refuses to render at all — a pairing screen that shows nothing.
+ */
+function escapeXml(value) {
+  return String(value).replace(/[&<>"']/g, (ch) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
+  }[ch]))
+}
+
 /**
  * The same symbol for a terminal, two matrix rows per line of text.
  *