dsh-plugin-mobile-link 0.6.0 → 0.6.6

package/lib/journal.js

@@ -0,0 +1,279 @@
+/**
+ * 链路与设备的生命周期流水。
+ *
+ * 为什么需要它（2026-10-12/13 那次"手机连不上"的教训）：连接器的日志走宿主
+ * `ctx.logger`，而宿主既不落盘也不保留历史，于是"连接器为什么把这条中转链路拆了"
+ * 只能靠中转侧日志反推——`lastError` 只留最后一条，中间发生过几次拆链、每次什么原因，
+ * 事后一概查不到。这一族事件就是补这个洞。
+ *
+ * 两条出口，用途不同：
+ *   * **内存环**（定长，默认 200 条）：随 `/mobile-link/status` 一起读，正在跑的时候看；
+ *   * **JSONL 文件**（可选，默认写在身份文件旁边，超过上限滚动一次）：进程重启后还在，
+ *     用于事后复盘——重连风暴的现场往往在重启之后就没了。
+ *
+ * 硬约束：**这里任何一步都不许抛**。它是诊断设施，不能因为磁盘满、权限错、
+ * 路径怪就把链路带崩；写失败只记一条 `journal.error` 然后闭嘴。
+ */
+
+import { appendFileSync, mkdirSync, renameSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { defaultStatePath } from './state.js'
+
+/** 内存环里保留多少条。 */
+export const DEFAULT_LIMIT = 200
+/** 单个 JSONL 文件的上限；超了就滚动成 `<path>.1`，所以磁盘占用上限约两倍。 */
+export const DEFAULT_MAX_BYTES = 256 * 1024
+/** 单条事件序列化后的上限；见 `#shrink` 的两步处理。 */
+export const MAX_EVENT_BYTES = 2048
+
+/**
+ * 事件目录（`kind` 词表）——**与契约逐字一致**，由 `npm run check:contracts` 机械核对。
+ *
+ * 契约：`docs/diagnostics-events.md`（§2 既有 + §3 新增 + 内部）。
+ * 为什么把词表放进代码：写入侧需要一个能自检的集合（防止手滑写错 kind 后没人发现），
+ * 而插件是独立发布的包，不能运行时去读仓库里的 spec 文件。
+ */
+export const EVENT_KINDS = Object.freeze([
+  // §2 既有（本次之前就有，语义不变）
+  'link.start',
+  'link.open',
+  'link.close',
+  'link.backoff',
+  'link.failed',
+  'link.unregistered',
+  'link.stop',
+  'watchdog.repull',
+  'watchdog.drop',
+  'dsh.ok',
+  'dsh.unreachable',
+  'device.attach',
+  'device.reattach',
+  'device.attach-again',
+  'device.detach',
+  'device.revoked',
+  // §3 本次新增
+  'device.phase',
+  'request.slow',
+  'device.summary',
+  'app.dial',
+  'app.hello',
+  'app.first-request',
+  'app.first-response',
+  'app.request',
+  'app.first-screen',
+  'app.first-render',
+  'app.scene',
+  'app.push',
+  // 内部：写失败与超大条目自报（不在契约的对外表里，但同属写入侧词表）
+  'journal.error',
+])
+
+/** 信封字段：detail 里的同名键一律忽略（否则会把时刻/事件名冲掉）。 */
+const PROTECTED_KEYS = new Set(['at', 'ms', 'kind'])
+
+/** 单条事件里字符串值的最长保留长度（`#shrink` 用）。 */
+const MAX_STRING_CHARS = 200
+
+
+/** 默认落在身份文件旁边（`$DSH_HOME/mobile-link/`），测试用临时 DSH_HOME 时会自动隔离。 */
+export function defaultJournalPath() {
+  return join(dirname(defaultStatePath()), 'link-events.jsonl')
+}
+
+/**
+ * 把一条事件序列化成一行 JSON。
+ *
+ * 同时给 `at`（给人看的 ISO 8601）与 `ms`（给脚本比对的整数），因为这两种读者都存在：
+ * 人 grep 时想直接看到时刻，脚本算间隔时不想解析日期。
+ */
+function toLine(entry) {
+  try {
+    return `${JSON.stringify(entry)}\n`
+  } catch {
+    // 循环引用之类的 detail 不该让整条事件丢掉：退化成只留 kind。
+    return `${JSON.stringify({ at: entry.at, ms: entry.ms, kind: entry.kind })}\n`
+  }
+}
+
+export class LinkJournal {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.path] JSONL 路径；不传＝只留内存，不碰磁盘
+   * @param {number} [options.limit] 内存环容量
+   * @param {number} [options.maxBytes] 单个文件上限
+   * @param {() => number} [options.now] 取时刻（测试注入）
+   * @param {{ debug?: (message: string) => void }} [options.logger]
+   */
+  constructor({
+    path, limit = DEFAULT_LIMIT, maxBytes = DEFAULT_MAX_BYTES,
+    now = Date.now, logger,
+  } = {}) {
+    this._path = typeof path === 'string' && path.trim() ? path : undefined
+    this.maxBytes = Math.max(1024, Number(maxBytes) || DEFAULT_MAX_BYTES)
+    this.limit = Math.max(1, Number(limit) || DEFAULT_LIMIT)
+    this.now = now
+    this.logger = logger
+    /** @type {Array<Record<string, unknown>>} */
+    this._entries = []
+    /** 因为环满而被挤掉的条数：读写两侧都不是无损的，得让读者知道。 */
+    this.dropped = 0
+    /** 落盘写坏了几次（第一次就停手，避免刷屏）。 */
+    this.fileErrors = 0
+    this._bytes = undefined
+    this._fileBroken = false
+    /** 写入过的总条数（含被挤掉的）。 */
+    this.recorded = 0
+  }
+
+  /** 落盘路径；`null` 表示这份流水只在内存里。 */
+  get path() {
+    return this._path ?? null
+  }
+
+  /**
+   * 记一条。**永不抛**。
+   *
+   * @param {string} kind 事件名（`link.open` / `device.detach` …），未知取值允许写入
+   *   （老读者必须忽略不认识的 kind），但单测会盯住目录漂移
+   * @param {Record<string, unknown>} [detail] 该事件自带的字段（`undefined` 一律丢弃）
+   * @returns {Record<string, unknown>} 写进去的那条（测试要断言，所以返回）
+   */
+  record(kind, detail) {
+    const entry = this.#build(kind, detail)
+    const line = toLine(entry)
+    // 两条分支必须返回同一形状：小的直接过，大的走两步降级。
+    const sized = Buffer.byteLength(line) <= MAX_EVENT_BYTES ? { entry, line } : this.#shrink(entry)
+    this.#push(sized.entry)
+    this.#append(sized.line)
+    return sized.entry
+  }
+
+  /**
+   * 组装条目：信封 + 过滤掉 `undefined` 的 detail。
+   *
+   * **信封字段受保护**：`at`/`ms`/`kind` 不会被 detail 覆盖。这条是 2026-10-13 踩出来的——
+   * 当时 `request.slow`/`app.hello` 的 detail 里也有一个 `ms`（含义是**耗时**），
+   * 摊平后把事件的**时刻**冲掉了，时间线上那条事件会跑到 1970 年。耗时一律叫 `elapsedMs`。
+   */
+  #build(kind, detail) {
+    const ms = this.now()
+    const entry = { at: new Date(ms).toISOString(), ms, kind }
+    if (detail && typeof detail === 'object') {
+      for (const [key, value] of Object.entries(detail)) {
+        if (value === undefined || PROTECTED_KEYS.has(key)) continue
+        entry[key] = value
+      }
+    }
+    return entry
+  }
+
+  /**
+   * 记一条**别人钟上**的事件（App 推上来的那些）：时刻用给定的值，不用本机时钟。
+   *
+   * 单独一个入口而不是"让 detail 覆盖 ms"：覆盖是隐式的，谁都能不小心改掉时刻；
+   * 这里只有显式调用才会保留外部时刻。
+   */
+  recordForeign(kind, { at, ms, ...detail } = {}) {
+    const stamp = Number.isFinite(ms) ? ms : this.now()
+    const entry = { at: typeof at === 'string' && at ? at : new Date(stamp).toISOString(), ms: stamp, kind }
+    for (const [key, value] of Object.entries(detail)) {
+      if (value === undefined || PROTECTED_KEYS.has(key)) continue
+      entry[key] = value
+    }
+    const line = toLine(entry)
+    const sized = Buffer.byteLength(line) <= MAX_EVENT_BYTES ? { entry, line } : this.#shrink(entry)
+    this.#push(sized.entry)
+    this.#append(sized.line)
+    return sized.entry
+  }
+
+  /** 记进内存环（磁盘那半由 `record` 负责）。 */
+  #push(entry) {
+    this._entries.push(entry)
+    this.recorded += 1
+    while (this._entries.length > this.limit) {
+      this._entries.shift()
+      this.dropped += 1
+    }
+  }
+
+  /**
+   * 超大条目的两步降级：先把长字符串截短（保住这一条），仍超限则丢掉它并自报一条 `journal.error`。
+   *
+   * 为什么不在写入侧直接抛/直接丢：诊断设施最怕"因为自己太胖把现场弄没了"。
+   * 截断会留 `truncated: true`，读者知道这条不完整；真的截不动（例如深嵌套对象）才丢，且丢也要留痕。
+   */
+  #shrink(entry) {
+    const shortened = { ...entry }
+    for (const [key, value] of Object.entries(shortened)) {
+      if (typeof value === 'string' && value.length > MAX_STRING_CHARS) {
+        shortened[key] = `${value.slice(0, MAX_STRING_CHARS)}…`
+      }
+    }
+    shortened.truncated = true
+    const line = toLine(shortened)
+    if (Buffer.byteLength(line) <= MAX_EVENT_BYTES) return { entry: shortened, line }
+    const fallback = this.#build('journal.error', {
+      // 字段名不能叫 `kind`：`#build` 会把 detail 的键盖到信封上，那样这条自报就冒充成原事件了。
+      originalKind: entry.kind,
+      bytes: Buffer.byteLength(toLine(entry)),
+      reason: 'event too large even after truncation',
+    })
+    return { entry: fallback, line: toLine(fallback) }
+  }
+
+  /** 最近的 `count` 条，最旧在前。 */
+  recent(count = this.limit) {
+    const size = Math.max(0, Number(count) || 0)
+    return this._entries.slice(Math.max(0, this._entries.length - size))
+  }
+
+  /** 内存环里现有的全部条目（副本）。 */
+  entries() {
+    return this._entries.slice()
+  }
+
+  #append(line) {
+    if (!this._path || this._fileBroken) return
+    try {
+      if (this._bytes === undefined) {
+        mkdirSync(dirname(this._path), { recursive: true, mode: 0o700 })
+        this._bytes = this.#sizeOf(this._path)
+      }
+      const bytes = Buffer.byteLength(line)
+      if (this._bytes > 0 && this._bytes + bytes > this.maxBytes) this.#rotate()
+      appendFileSync(this._path, line, { mode: 0o600 })
+      this._bytes += bytes
+    } catch (error) {
+      this.fileErrors += 1
+      this._fileBroken = true
+      this.logger?.debug?.(`mobile-link: link journal disabled (${error?.message ?? error})`)
+    }
+  }
+
+  #sizeOf(path) {
+    try {
+      return statSync(path).size
+    } catch {
+      return 0
+    }
+  }
+
+  /** 滚一次：现文件改名成 `<path>.1`，旧的那份直接丢掉（只保两代）。 */
+  #rotate() {
+    const archived = `${this._path}.1`
+    try {
+      renameSync(this._path, archived)
+    } catch {
+      // Windows 上改名到已存在的目标会失败；删掉目标再试一次。
+      try {
+        unlinkSync(archived)
+        renameSync(this._path, archived)
+      } catch (error) {
+        throw error
+      }
+    }
+    this._bytes = 0
+  }
+}

package/lib/link.js

@@ -20,13 +20,14 @@ import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl
 const LIVE_AGENT = Symbol.for('dsh.mobile-link.live-agent')
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
+import { LinkJournal, defaultJournalPath } from './journal.js'
 import { statusSnapshot } from './status.js'
-import { mintPairCode } from './pairing.js'
+import { mintPairCode, regeneratePairCode } from './pairing.js'
 import {
-  DEFAULT_EVENTS_BACKLOG,
+  DEFAULT_EVENTS_BACKLOG, DEFAULT_SLOW_REQUEST_MS,
   EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
 } from './router.js'
-import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
+import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
 import { MissingIdentity, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
@@ -57,7 +58,14 @@ export class MobileLinkAgent extends EventEmitter {
     logger = console, heartbeatMs = 20000, pongTimeoutMs = 60000, maxBackoffMs = 30000,
     random = Math.random, now = Date.now, dshClient, connectImpl = wsConnect, enabled = true,
     watchdogMs = 180000,
+    // 慢请求阈值（毫秒）；0 = 关闭逐条慢请求记录。见 router.js 的 DEFAULT_SLOW_REQUEST_MS。
+    slowRequestMs = DEFAULT_SLOW_REQUEST_MS,
+    // 关掉手机推送的接收（回退闸）；见 contracts/connector-diagnostics-method.md §4。
+    diagnostics = true,
     inviteCode, fetchImpl = fetch, env = process.env,
+    // 生命周期流水（见 journal.js）：`journal` 传实例（测试注入），`journalPath`
+    // 传路径（`defaultJournalPath()` 之外的位置），false 表示只留内存不落盘。
+    journal, journalPath,
     // 手机不在时替它攒下来的提问条数上限（见 router.js）；环境变量给部署用，
     // 构造参数给测试用。**没有"留多久"这个旋钮**：`$events` 一直留到设备被撤销。
     eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
@@ -69,6 +77,8 @@ export class MobileLinkAgent extends EventEmitter {
     this.pongTimeoutMs = pongTimeoutMs
     this.maxBackoffMs = maxBackoffMs
     this.watchdogMs = watchdogMs
+    this.slowRequestMs = Number(slowRequestMs) || 0
+    this.diagnostics = diagnostics !== false
     this.random = random
     this.now = now
     this.connectImpl = connectImpl
@@ -79,13 +89,29 @@ export class MobileLinkAgent extends EventEmitter {
     //: to fix, not a transport problem to retry.
     this.needsEnroll = false
     this.dsh = dshClient ?? new DshClient({ explicitUrl: dshUrl, logger })
+    /** 生命周期流水：内存环 +（默认）一份 JSONL，见 journal.js 的文件头。 */
+    this.journal = journal ?? new LinkJournal({
+      path: journalPath === false
+        ? undefined
+        : (typeof journalPath === 'string' && journalPath ? journalPath : defaultJournalPath()),
+      now,
+      logger,
+    })
     this.router = new DeviceRouter({
       dsh: this.dsh,
       logger,
       now,
       protocolVersion: PROTOCOL_VERSION,
       eventsBacklog,
+      slowRequestMs: this.slowRequestMs,
+      diagnostics: this.diagnostics,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
+      // 设备侧的 attach/detach 与链路侧同源记进流水：事后想把"手机断了"和
+      // "连接器拆链"对上时间，两边必须写在同一份文件里。
+      // `options.foreign` 表示这条事件用的是**别人的钟**（App 推上来的），必须原样保留时刻。
+      onEvent: (kind, detail, options) => (options?.foreign
+        ? this.journal.recordForeign(kind, detail)
+        : this.journal.record(kind, detail)),
       // 「跑完了 / 待你回应」到了就报一声（`{t:'notify'}`）。这是 agent 侧控制帧，
       // **不带 deviceId**：连接器不知道、也不需要知道这台电脑配了哪些手机，
       // 「该不该推给某台手机」由中转判（它手里才有"这台设备此刻在不在线"）。
@@ -108,6 +134,16 @@ export class MobileLinkAgent extends EventEmitter {
     this.startedAt = undefined
     this.connectedAt = undefined
     this.reconnectAttempts = 0
+    /** 最近一次拆链的时刻（用来在 `link.open` 里报"距上次断开多久"）。 */
+    this._lastClosedAt = undefined
+    /**
+     * socket 上最后一次系统错误（`onError` 的文本）。
+     *
+     * 为什么要专门留住它：链路被异常关闭时，`close` 回调只给一个代码（实测常见 1006，
+     * 含义是"没有关闭帧"），据此无法判断是网络、代理还是对端。系统错误文本是唯一线索，
+     * 而它以前只进了 debug 日志、不落流水（2026-10-13 现场诊断时卡在这里）。
+     */
+    this._socketError = undefined
 
     this._stopping = false
     this._sessionClosed = undefined
@@ -233,6 +269,15 @@ export class MobileLinkAgent extends EventEmitter {
     this._abort = new AbortController()
     this.startedAt = this.now()
     this.state = 'connecting'
+    this.journal.record('link.start', {
+      // 这里只能报**配置值**：真身份（含实际中转地址）要等 `#session()` 里的
+      // `resolveIdentity()` 才读到，那条记在 `link.open` 上。名字带 configured，
+      // 免得读者把占位符 `wss://relay.example.com/dsh-link` 当成真的在连的地址。
+      configuredRelay: this.config.relayUrl,
+      agentId: this.config.agentId || undefined,
+      attempt: this.reconnectAttempts,
+      host: this.hostForm,
+    })
     // 解析器可能在上一次会话里就已经装好；这里补一次本机发现（失败无妨）。
     void this.refreshLocal()
     this._lastProgressAt = this.now()
@@ -262,6 +307,7 @@ export class MobileLinkAgent extends EventEmitter {
     this._loop = undefined
     this.dsh.close()
     this.state = 'stopped'
+    this.journal.record('link.stop', {})
     this.emit('status')
   }
 
@@ -278,6 +324,7 @@ export class MobileLinkAgent extends EventEmitter {
           this.needsEnroll = true
           this.state = 'unregistered'
           this.lastError = messageOf(error)
+          this.journal.record('link.unregistered', { error: this.lastError })
           this.logger.error?.(this.lastError)
           this.emit('status')
           return
@@ -295,11 +342,13 @@ export class MobileLinkAgent extends EventEmitter {
           this.needsEnroll = true
           this.state = 'unregistered'
           this.lastError = messageOf(error)
+          this.journal.record('link.unregistered', { error: this.lastError })
           this.logger.error?.(`${this.lastError}\n  ${this.enrollHint()}`)
           this.emit('status')
           return
         }
         this.lastError = messageOf(error)
+        this.journal.record('link.failed', { error: this.lastError, attempt: this.reconnectAttempts })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
       }
       if (this._stopping) break
@@ -307,6 +356,7 @@ export class MobileLinkAgent extends EventEmitter {
       this.emit('status')
       const delay = nextBackoff(this.reconnectAttempts, { maxMs: this.maxBackoffMs, random: this.random })
       this.reconnectAttempts += 1
+      this.journal.record('link.backoff', { attempt: this.reconnectAttempts, delayMs: Math.round(delay) })
       await sleep(delay, this._abort.signal)
     }
     this.state = 'stopped'
@@ -365,6 +415,16 @@ export class MobileLinkAgent extends EventEmitter {
     this.router.lastError = undefined
     this._lastPong = this.now()
     this.logger.info?.(`mobile-link: connected to ${this.relay.wsBase} as ${identity.agentId}`)
+    this.journal.record('link.open', {
+      relay: this.relay?.wsBase,
+      agentId: identity.agentId,
+      attempt: this.reconnectAttempts,
+      sinceCloseMs: this._lastClosedAt === undefined ? undefined : this.now() - this._lastClosedAt,
+      // 这次连接属于哪套版本：连接器 + 宿主 DSH。一连接一行，事后从本机流水就能
+      // 认出"出问题的那天跑的是哪两个版本"，不必再去翻安装记录。
+      serverVersion: SERVER_VERSION,
+      hostVersion: hostVersion(),
+    })
     this.emit('status')
 
     socket.onMessage((text) => {
@@ -373,7 +433,10 @@ export class MobileLinkAgent extends EventEmitter {
         .catch((error) => this.logger.debug?.(`mobile-link: frame handler error: ${messageOf(error)}`))
       return this._inbox
     })
-    socket.onError((error) => this.logger.debug?.(`mobile-link: relay socket error: ${messageOf(error)}`))
+    socket.onError((error) => {
+      this._socketError = messageOf(error)
+      this.logger.debug?.(`mobile-link: relay socket error: ${this._socketError}`)
+    })
     socket.onClose((code, reason) => this.#teardownSocket(`relay closed the socket (${code ?? '?'} ${reason ?? ''})`))
 
     this.#startHeartbeat()
@@ -386,9 +449,13 @@ export class MobileLinkAgent extends EventEmitter {
       // 进程外工具（本机脚本、iOS 集成测试辅助）靠这份交接文件拿带凭据地址；
       // 写入失败不影响链路（`#writeHandoff` 自己吞异常）。
       await this.#writeHandoff()
+      this.journal.record('dsh.ok', { endpoint: this.dsh?.endpoint?.base })
     } catch (error) {
       this.dshError = messageOf(error)
       this.lastError = this.dshError
+      // 这一条很关键：本机 DSH 不可达时，手机那句 `_link/hello`/`sessions` 探针
+      // 必然超时，App 会据此重建整条链路——于是"连接器在、手机却连不上"。
+      this.journal.record('dsh.unreachable', { error: this.dshError, kind: this.dsh?.errorKind })
       this.logger.warn?.(`mobile-link: local DSH is not reachable yet: ${this.dshError}`)
     }
     this.emit('status')
@@ -419,6 +486,7 @@ export class MobileLinkAgent extends EventEmitter {
       const idle = this.now() - this._lastProgressAt
       if (!this._loopActive) {
         this.lastError = `链路循环不在了（看门狗重拉，空闲 ${Math.round(idle / 1000)}s）`
+        this.journal.record('watchdog.repull', { idleMs: Math.round(idle) })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
         this._loop = undefined
         this._lastProgressAt = this.now()
@@ -427,6 +495,7 @@ export class MobileLinkAgent extends EventEmitter {
       }
       if (this.state === 'connected' && idle > this.pongTimeoutMs) {
         this.lastError = `relay 超过 ${Math.round(idle / 1000)}s 没有动静（看门狗拆连接）`
+        this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
         this.#teardownSocket(this.lastError)
         this._lastProgressAt = this.now()
@@ -434,6 +503,7 @@ export class MobileLinkAgent extends EventEmitter {
       }
       if (this.state !== 'connected' && idle > this.watchdogMs) {
         this.lastError = `链路 ${Math.round(idle / 1000)}s 没有进展（看门狗重建连接）`
+        this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
         this.#teardownSocket(this.lastError)
         this._lastProgressAt = this.now()
@@ -469,6 +539,7 @@ export class MobileLinkAgent extends EventEmitter {
   #teardownSocket(reason) {
     this.#stopHeartbeat()
     const socket = this.socket
+    const from = this.state
     this.socket = undefined
     if (socket) {
       try {
@@ -483,6 +554,18 @@ export class MobileLinkAgent extends EventEmitter {
     this.dsh.close()
     if (this.state !== 'stopped' && this.state !== 'disabled') this.state = 'disconnected'
     this.lastError = this.lastError ?? reason
+    this._lastClosedAt = this.now()
+    // 「为什么拆的」是这一族事件唯一要回答的问题：reason 来自调用点，
+    // from 是拆之前的状态（connected / backoff / connecting），
+    // connectedForMs 用来区分"刚连上就掉"和"挂了很久才掉"。
+    this.journal.record('link.close', {
+      reason,
+      from,
+      connectedForMs: this.connectedAt === undefined ? undefined : this.now() - this.connectedAt,
+      // 有系统错误才带这个字段（正常关闭时不该凭空多一个 null）。
+      socketError: this._socketError,
+    })
+    this._socketError = undefined
     const resolve = this._sessionClosed
     this._sessionClosed = undefined
     this.emit('status')
@@ -492,10 +575,15 @@ export class MobileLinkAgent extends EventEmitter {
   // ── relay I/O ───────────────────────────────────────────────────────────
 
   #rawSend(frame) {
+    return this.#sendText(encodeFrame(frame))
+  }
+
+  /** 唯一的发送出口：socket 不在就丢掉，发送异常只记 debug、绝不抛。 */
+  #sendText(text) {
     const socket = this.socket
     if (!socket || socket.closed) return false
     try {
-      socket.send(encodeFrame(frame))
+      socket.send(text)
       return true
     } catch (error) {
       this.logger.debug?.(`mobile-link: send failed: ${messageOf(error)}`)
@@ -507,7 +595,10 @@ export class MobileLinkAgent extends EventEmitter {
     // `deviceId` 为空＝这是一条**不带寻址**的帧（`fsPutAck`/`fsPutDone`/`fsErr` 那一族）：
     // relay 靠 `bid` 把回复对回发起的那个 HTTP 请求，多一个 deviceId 反而会让它对不上。
     if (deviceId === undefined || deviceId === null) return this.#rawSend(frame)
-    return this.#rawSend({ ...frame, deviceId })
+    const text = encodeFrame({ ...frame, deviceId })
+    // 记字节给路由层的"慢请求/汇总"用（它按 deviceId 归）：只有这里知道真正上线了多少字节。
+    this.router.noteSent?.(deviceId, Buffer.byteLength(text))
+    return this.#sendText(text)
   }
 
   sendHostStatus() {
@@ -519,6 +610,10 @@ export class MobileLinkAgent extends EventEmitter {
         name: this.identity?.agentName || undefined,
         dshPort: this.dsh?.endpoint?.port,
         protocol: PROTOCOL_VERSION,
+        // 这台电脑的两段版本。中转据此按 agent 记一行（变化才写），手机据此
+        // 在「关于」里显示 DSH 版本——只在控制帧上走一次，不进任何业务流。
+        version: SERVER_VERSION,
+        hostVersion: hostVersion(),
       },
     })
   }
@@ -566,12 +661,22 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── relay-side helpers ──────────────────────────────────────────────────
 
-  /** Ask the relay to mint a pairing code for this agent (relay NOTES.md §2). */
-  async mintPairCode({ ttlMs = 10 * 60 * 1000, fetchImpl = fetch } = {}) {
+  /**
+   * Ask the relay to mint a pairing code for this agent (relay NOTES.md §2).
+   *
+   * 032：默认持久（`ttlMs: null`）；传秒数得到限时码。
+   */
+  async mintPairCode({ ttlMs = null, fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
     return mintPairCode({ identity, ttlMs, fetchImpl })
   }
 
+  /** 用户点「重新生成」：作废旧码、铸新的，**不碰已配对设备**（032）。 */
+  async regeneratePairCode({ fetchImpl = fetch } = {}) {
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    return regeneratePairCode({ identity, fetchImpl })
+  }
+
   /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */
   status() {
     return statusSnapshot(this)

package/lib/pairing.js

@@ -1,25 +1,34 @@
 /**
- * Pairing helper: ask the relay to mint a one-time code and build the QR
- * payload the desktop shows. Spec §2.1 plus docs/RELAY-NOTES.md §2 (the endpoint the
- * spec's table is missing).
+ * Pairing helper: ask the relay to mint a pairing code and build the QR payload
+ * the desktop shows. Spec §2.1 plus docs/RELAY-NOTES.md §2 (the endpoint the spec's
+ * table is missing).
+ *
+ * 032：默认铸**持久码**（不过期，直到用户点「重新生成」）。传 `ttlMs` 仍然得到一张
+ * 限时码——那是老行为，留给还用它的调用方与老测试。
  */
 
-import { pairCodeEndpoint, qrPayload } from './dlp.js'
+import { pairCodeEndpoint, pairCodeRegenerateEndpoint, qrPayload } from './dlp.js'
 
 /**
  * @param {object} options
  * @param {{agentId: string, agentSecret: string, relayUrl: string}} options.identity
- * @param {number} [options.ttlMs] requested lifetime (the relay caps it at 1 hour)
+ * @param {number|null} [options.ttlMs] requested lifetime; `null`/省略 = 持久码
  * @param {typeof fetch} [options.fetchImpl] injectable for tests
  */
-export async function mintPairCode({ identity, ttlMs = 10 * 60 * 1000, fetchImpl = fetch }) {
+export async function mintPairCode({ identity, ttlMs = null, fetchImpl = fetch }) {
+  // 032：**持久码那条路不能把 `ttlMs` 放进请求体**。中转的判据是 `"ttlMs" not in body`
+  // （`relay/api.py` 的 `pair_code`）：带一个 `ttlMs: null` 会被读成"限时、但没给时长"，
+  // 于是落到中转的默认 10 分钟——面板显示倒计时，码十分钟后就废（用户看到的就是这个）。
+  const payload = ttlMs == null
+    ? { agentId: identity.agentId }
+    : { agentId: identity.agentId, ttlMs }
   const response = await fetchImpl(pairCodeEndpoint(identity.relayUrl), {
     method: 'POST',
     headers: {
       'content-type': 'application/json',
       authorization: `Bearer ${identity.agentSecret}`,
     },
-    body: JSON.stringify({ agentId: identity.agentId, ttlMs }),
+    body: JSON.stringify(payload),
   })
   let body
   try {
@@ -32,8 +41,50 @@ export async function mintPairCode({ identity, ttlMs = 10 * 60 * 1000, fetchImpl
   }
   return {
     code: body.code,
-    expiresAt: body.expiresAt,
-    ttlMs: body.ttlMs ?? ttlMs,
+    expiresAt: body.expiresAt ?? null,
+    ttlMs: body.ttlMs ?? ttlMs ?? null,
+    persistent: body.persistent === true || body.expiresAt == null,
+    // 「已配对 N/8」以中转的库为准：连接器只知道自己这次见过的设备。
+    maxPairedDevices: Number(body.maxPairedDevices ?? 0) || null,
+    pairedDevices: Number(body.pairedDevices ?? 0),
+    relayUrl: identity.relayUrl,
+    agentId: identity.agentId,
+    qrPayload: qrPayload({ relay: identity.relayUrl, code: body.code }),
+  }
+}
+
+/**
+ * 用户点「重新生成」：让中转作废旧码、铸一枚新的。
+ *
+ * **不碰已配对的设备**（032 FR-002）：那台手机/浏览器靠自己的 deviceToken 活着，
+ * 换码只影响"还没来配的人"。所以这个动作可以放心点，不需要提醒"会把手机踢下线"。
+ */
+export async function regeneratePairCode({ identity, fetchImpl = fetch }) {
+  const response = await fetchImpl(pairCodeRegenerateEndpoint(identity.relayUrl), {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${identity.agentSecret}`,
+    },
+    body: JSON.stringify({ agentId: identity.agentId }),
+  })
+  let body
+  try {
+    body = await response.json()
+  } catch {
+    throw new Error(`relay returned HTTP ${response.status} for /pair/code/regenerate`)
+  }
+  if (!response.ok || body?.ok !== true) {
+    throw new Error(body?.error?.message ?? `relay refused the regeneration (HTTP ${response.status})`)
+  }
+  return {
+    code: body.code,
+    expiresAt: null,
+    ttlMs: null,
+    persistent: true,
+    revoked: Number(body.revoked ?? 0),
+    maxPairedDevices: Number(body.maxPairedDevices ?? 0) || null,
+    pairedDevices: Number(body.pairedDevices ?? 0),
     relayUrl: identity.relayUrl,
     agentId: identity.agentId,
     qrPayload: qrPayload({ relay: identity.relayUrl, code: body.code }),