dsh-plugin-mobile-link 0.4.1 → 0.6.5

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

@@ -8,12 +8,23 @@ 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 { LinkJournal, defaultJournalPath } from './journal.js'
 import { statusSnapshot } from './status.js'
 import { mintPairCode } 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'
@@ -46,7 +57,15 @@ 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,
+    // 慢请求阈值（毫秒）；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),
@@ -57,6 +76,9 @@ export class MobileLinkAgent extends EventEmitter {
     this.heartbeatMs = heartbeatMs
     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
@@ -67,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**：连接器不知道、也不需要知道这台电脑配了哪些手机，
       // 「该不该推给某台手机」由中转判（它手里才有"这台设备此刻在不在线"）。
@@ -85,6 +123,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'
@@ -93,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
@@ -100,6 +151,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,22 +253,49 @@ 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()
     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()
+    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')
@@ -226,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')
   }
 
@@ -242,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
@@ -259,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
@@ -271,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'
@@ -324,10 +410,17 @@ 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()
     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,
+    })
     this.emit('status')
 
     socket.onMessage((text) => {
@@ -336,7 +429,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()
@@ -349,9 +445,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')
@@ -362,6 +462,57 @@ 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.journal.record('watchdog.repull', { idleMs: Math.round(idle) })
+        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.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()
+        return
+      }
+      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()
+      }
+    }, every)
+    this._watchdog.unref?.()
+  }
+
+  #stopWatchdog() {
+    if (this._watchdog) clearInterval(this._watchdog)
+    this._watchdog = undefined
+  }
+
   #startHeartbeat() {
     this.#stopHeartbeat()
     this._heartbeat = setInterval(() => {
@@ -384,6 +535,7 @@ export class MobileLinkAgent extends EventEmitter {
   #teardownSocket(reason) {
     this.#stopHeartbeat()
     const socket = this.socket
+    const from = this.state
     this.socket = undefined
     if (socket) {
       try {
@@ -398,6 +550,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')
@@ -407,10 +571,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)}`)
@@ -422,7 +591,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() {
@@ -440,9 +612,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') {