dsh-plugin-mobile-link 0.6.0 → 0.6.5

package/lib/link.js

@@ -20,10 +20,11 @@ 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 {
-  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'
@@ -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,12 @@ 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,
+    })
     this.emit('status')
 
     socket.onMessage((text) => {
@@ -373,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()
@@ -386,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')
@@ -419,6 +482,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 +491,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 +499,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 +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 {
@@ -483,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')
@@ -492,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)}`)
@@ -507,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() {

package/lib/router.js

@@ -17,6 +17,7 @@ import { FileFetcher, FSGET_CANCEL } from './files-out.js'
 import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 import { isHistoryMethod } from './history.js'
+import { trimRecordsForWire } from './history/records.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -75,6 +76,62 @@ export function errorObject(code, message, details = {}) {
   return { code, message, details }
 }
 
+/**
+ * 旧分页通道（`session/page`）的下发形态清洗（016）。
+ *
+ * 这一路是**降级通道**：宿主自己回一页记录，连接器只是转发。它和精确窗口
+ * （`_link/sessionWindow`）必须守同一条口径 —— 只用于诊断的宿主模型输出日志
+ * 不下发（见 `specs/016-history-load-perf/contracts/history-record-trim.md`）。
+ *
+ * 两种形态都要认：宿主 RPC 的信封 `{ ok, value: { records } }`，以及直接给
+ * `{ records }` 的桩/测试形态。其余方法或结构一律原样返回，不做推断。
+ */
+export function trimHistoryPageForWire(method, result) {
+  if (method !== 'session/page') return result
+  if (result === null || typeof result !== 'object') return result
+  const page = result.value ?? result
+  if (page === null || typeof page !== 'object' || !Array.isArray(page.records)) return result
+  const trimmed = { ...page, records: trimRecordsForWire(page.records) }
+  return result.value === undefined ? trimmed : { ...result, value: trimmed }
+}
+
+import { DeviceTimeline } from './diagnostics.js'
+import { SESSION_DIGEST_METHOD, digestSessionList, encodeDigest } from './session-digest.js'
+
+/** 慢请求阈值默认值（毫秒）；0 = 关闭逐条慢请求记录。 */
+export const DEFAULT_SLOW_REQUEST_MS = 2000
+
+/** App 把自己那份阶段记录推上来的方法（契约 connector-diagnostics-method.md）。 */
+export const DIAGNOSTICS_METHOD = '_link/diagnostics'
+/** 单批上限：超过就截断并如实报 `accepted`，剩下的由 App 下次再推（水位不推进）。 */
+export const DIAGNOSTICS_BATCH_BYTES = 32 * 1024
+/** 单条事件里字符串字段的保留长度。 */
+const DIAGNOSTICS_MAX_TEXT = 400
+
+/**
+ * 只留标量（字符串/数字/布尔）与标量数组。
+ *
+ * **必须把 App 的 `detail` 摊平到顶层**：App 侧的 JSONL 信封是
+ * `{kind, seq, ms, at, detail:{...}}`（见 DSHKit 的 `LinkDiagnostics.Event`），而连接器
+ * 自己的流水是**扁平**的。不摊平的话 `phase`/`ms` 这些字段会在清洗时被当成嵌套对象丢掉——
+ * 实测症状：`app.dial` 落盘后一个字段都没有（2026-10-13 09:25 的中转运行）。
+ */
+function sanitizeDiagnosticEvent(event) {
+  if (!event || typeof event !== 'object' || typeof event.kind !== 'string') return null
+  const { detail, ...envelope } = event
+  const flat = { ...envelope, ...(detail && typeof detail === 'object' ? detail : {}) }
+  const clean = { kind: event.kind }
+  for (const [key, value] of Object.entries(flat)) {
+    if (key === 'kind') continue
+    if (typeof value === 'string') clean[key] = value.slice(0, DIAGNOSTICS_MAX_TEXT)
+    else if (typeof value === 'number' || typeof value === 'boolean') clean[key] = value
+    else if (Array.isArray(value) && value.every((item) => typeof item === 'string' || typeof item === 'number')) {
+      clean[key] = value.slice(0, 32)
+    }
+  }
+  return clean
+}
+
 export class DeviceRouter {
   /**
    * @param {object} options
@@ -84,13 +141,28 @@ export class DeviceRouter {
    */
   constructor({
     dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
-    eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {},
+    eventsBacklog = DEFAULT_EVENTS_BACKLOG, notify = () => {}, onEvent = () => {},
+    slowRequestMs = DEFAULT_SLOW_REQUEST_MS, diagnostics = true,
   } = {}) {
     this.dsh = dsh
     this.eventsBacklog = eventsBacklog
+    this.slowRequestMs = Number(slowRequestMs) || 0
+    this.diagnosticsEnabled = diagnostics !== false
+    /** 每个 deviceId 当前这次接入的计时（attach 时建、detach 时收）。 */
+    this.timelines = new Map()
+    /**
+     * 当前这次请求已经发出去的字节数（在 `noteSent` 里累加、在请求收尾时取走）。
+     *
+     * 同一设备上并发请求会把字节算到一起——诊断只要量级对得上（"这次响应是几 KB 还是几 MB"），
+     * 不值得为它引入逐请求关联（那要改所有回包点的形状）。
+     */
+    this._sentBytes = new Map()
     // 「跑完了 / 待你回应」这类事件到了就报一声（见 `notifyFor`）。默认空函数，
     // 测试与不关心提醒的调用方可以不管它。帧由 link.js 发（router 不发帧）。
     this.notify = notify
+    // 生命周期事件（设备 attach/detach 等）的去处，由 link.js 接到流水（journal.js）。
+    // 默认空函数，所以 router 单独用时（单测、本地脚本）不需要日志设施。
+    this.onEvent = onEvent
     // Reported to the app so it can tell which wire revision it is talking to.
     this.protocolVersion = protocolVersion
     this.send = send
@@ -156,9 +228,12 @@ export class DeviceRouter {
       return
     }
     switch (frame.t) {
-      case 'req':
+      case 'req': {
+        const startedAt = this.now()
         await this.handleRequest(deviceId, frame)
+        this.#noteRequest(deviceId, frame.method, startedAt)
         return
+      }
       case 'open':
         await this.handleOpen(deviceId, frame)
         return
@@ -259,16 +334,117 @@ export class DeviceRouter {
 
   // ── device lifecycle ────────────────────────────────────────────────────
 
+  /**
+   * 记一条请求的耗时与字节（spec 020 的 FR-001–FR-003）。
+   *
+   * `bytes` 取"这次请求期间发出去的字节"（见 `noteSent`）——它是一个近似值，
+   * 只在同一设备上并发请求时才会串味，而诊断要回答的是"这次响应是几 KB 还是几 MB"。
+   */
+  #noteRequest(deviceId, method, startedAt) {
+    const timeline = this.timelines.get(deviceId)
+    if (!timeline) return
+    const bytes = this._sentBytes.get(deviceId) ?? 0
+    this._sentBytes.set(deviceId, 0)
+    timeline.noteRequest({ method, startedAt, ms: this.now() - startedAt, bytes })
+  }
+
+  /** 每发一帧给某台设备就累加它的字节数（由 `link.js` 的 `sendToDevice` 调用）。 */
+  noteSent(deviceId, bytes) {
+    if (!deviceId || !Number.isFinite(bytes)) return
+    this._sentBytes.set(deviceId, (this._sentBytes.get(deviceId) ?? 0) + bytes)
+  }
+
+  /**
+   * 收下 App 推来的阶段记录（spec 020 的 FR-011 / 契约 §2）。
+   *
+   * 三条硬规则：
+   *   1. **时刻照抄**：App 事件的 `at`/`ms` 是它自己钟上的读数，连接器不许改写
+   *      （否则"手机侧几点了"这条信息就没了，而它正是区分"App 挂起"与"拨号卡住"的依据）；
+   *   2. **按序号幂等**：同一批重推不会写两遍（水位记在设备记录上）；
+   *   3. **超批上限就截断**：只收前若干条并如实报 `accepted`/`lastSeq`，剩下的下次再推——
+   *      绝不假装收全了。
+   *
+   * @returns {{ok: true, value: {accepted: number, lastSeq: number}}}
+   */
+  acceptDiagnostics(deviceId, args = {}) {
+    if (!this.diagnosticsEnabled) {
+      // 回退闸：关掉时明确拒绝，手机据此静默忽略（不影响连接）。
+      return { ok: false, error: errorObject('diagnostics/disabled', 'diagnostics intake is disabled on this connector') }
+    }
+    const record = this.devices.get(deviceId)
+    const watermark = Number(record?.diagnosticsSeq) || 0
+    const events = Array.isArray(args.events) ? args.events : []
+    let accepted = 0
+    let lastSeq = watermark
+    let bytes = 0
+    for (const raw of events) {
+      const event = sanitizeDiagnosticEvent(raw)
+      if (!event) continue
+      const seq = Number(event.seq)
+      if (Number.isFinite(seq) && seq <= watermark) continue
+      const size = JSON.stringify(event).length
+      if (bytes > 0 && bytes + size > DIAGNOSTICS_BATCH_BYTES) break
+      // 用 recordForeign：App 的时刻照抄（它是"手机侧几点"的唯一来源）。
+      // 补 `deviceId`：App 自己不知道它的 id，而多设备时没有这一列就没法把事件归到某台手机上。
+      this.onEvent(event.kind, { ...event, deviceId, source: 'app' }, { foreign: true })
+      bytes += size
+      accepted += 1
+      if (Number.isFinite(seq)) lastSeq = Math.max(lastSeq, seq)
+    }
+    if (record) record.diagnosticsSeq = lastSeq
+    const sentAt = Number(args.sentAt)
+    this.onEvent('app.push', {
+      deviceId,
+      count: accepted,
+      dropped: Number(args.dropped) || 0,
+      sentAt: Number.isFinite(sentAt) ? sentAt : undefined,
+      // 手机时钟与本机时钟的差（单向延迟几十毫秒）；采集侧的对齐就靠这一个数。
+      skewMs: Number.isFinite(sentAt) ? this.now() - sentAt : undefined,
+    })
+    return { ok: true, value: { accepted, lastSeq } }
+  }
+
+  /** 起一次新的接入计时（回头客也重起：那确实是一次新连接）。 */
+  #startTimeline(deviceId) {
+    this.timelines.get(deviceId)?.finish()
+    this.timelines.set(deviceId, new DeviceTimeline({
+      deviceId,
+      slowRequestMs: this.slowRequestMs,
+      now: this.now,
+      onEvent: this.onEvent,
+    }))
+    this._sentBytes.set(deviceId, 0)
+  }
+
+  /** 收掉一次接入计时（断开、撤销、进程收尾都走这里）。 */
+  #finishTimeline(deviceId) {
+    const timeline = this.timelines.get(deviceId)
+    if (!timeline) return
+    timeline.finish()
+    this.timelines.delete(deviceId)
+    this._sentBytes.delete(deviceId)
+  }
+
   async attachDevice(deviceId, info = {}) {
     if (!nonEmptyString(deviceId)) return
+    this.#startTimeline(deviceId)
     const existing = this.devices.get(deviceId)
     if (existing) {
       // 回头客：手机又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
       if (existing.offlineSince !== undefined) {
+        const offlineForMs = this.now() - existing.offlineSince
         existing.offlineSince = undefined
+        this.onEvent('device.reattach', { deviceId, offlineForMs, pending: existing.eventsPending.size })
         this.logger.info?.(
           `mobile-link: device ${deviceId} reattached with ${existing.eventsPending.size} unanswered question(s)`)
         this.#changed()
+      } else {
+        // **这条是"同一台设备同时又开了一条"**：中转的 `attach_device` 会直接覆盖旧
+        // 链路，旧的那条既不会再收到 `deviceDetach`、也不会出现在任何一方的状态里
+        // （2026-10-13 01:10 实测：attach 与上一条 detach 之间空了 34 秒）。记下来，
+        // 否则事后只看得到"它连上了"，看不到"它连了两条"。
+        this.onEvent('device.attach-again', { deviceId, connectedForMs: this.now() - existing.connectedAt })
+        this.logger.warn?.(`mobile-link: device ${deviceId} attached again while still attached`)
       }
       return
     }
@@ -288,6 +464,7 @@ export class DeviceRouter {
       offlineSince: undefined,
       eventsPending: new Map(),
     })
+    this.onEvent('device.attach', { deviceId, name: info?.name, model: info?.model })
     this.logger.info?.(`mobile-link: device ${deviceId} attached (${info?.name ?? 'unknown'})`)
     this.#changed()
     await this.ensureEventsStream(deviceId)
@@ -304,10 +481,12 @@ export class DeviceRouter {
    * 那段的说明）。这也是「撤销即放下」是唯一出口的原因。
    */
   async detachDevice(deviceId, reason) {
+    this.#finishTimeline(deviceId)
     const record = this.devices.get(deviceId)
     if (!record) return
     if (reason === 'revoked') {
       await this.#dropDevice(deviceId)
+      this.onEvent('device.revoked', { deviceId })
       this.logger.info?.(`mobile-link: device ${deviceId} 已被撤销，放下（不再替它值班）`)
       return
     }
@@ -326,6 +505,7 @@ export class DeviceRouter {
     for (const entry of keep) record.dlpIds.add(entry.dlpId)
 
     if (record.offlineSince === undefined) record.offlineSince = this.now()
+    this.onEvent('device.detach', { deviceId, reason: reason ?? 'closed' })
     this.logger.info?.(
       `mobile-link: device ${deviceId} detached (${reason ?? 'closed'})；`
       + '$events 流一直替它留着，直到设备被撤销或进程退出')
@@ -366,16 +546,48 @@ export class DeviceRouter {
   teardownAll() {
     const muxIds = []
     for (const deviceId of [...this.devices.keys()]) {
+      // 进程收尾/链路重建也要把这次接入的汇总写掉，否则"连上过、发过请求"这件事没有数字。
+      this.#finishTimeline(deviceId)
       muxIds.push(...this.streams.removeDevice(deviceId))
       this.devices.delete(deviceId)
     }
     this.streams = new StreamTable()
+    // 不该有残留：上面的循环已经逐个收过；这里兜底，防止 attach 之后没进 devices 的路径留下脏项。
+    this.timelines.clear()
+    this._sentBytes.clear()
     return muxIds
   }
 
   // ── device requests ─────────────────────────────────────────────────────
 
   async handleRequest(deviceId, frame) {
+    // App 推上来的阶段记录：**只落盘，不影响任何连接行为**（契约
+    // connector-diagnostics-method.md §4）。放在最前面，免得被后面的方法族顺序影响。
+    // 精简版会话列表（spec 021）：同一份宿主数据，去掉 App 侧零读取点的字段，可按要求 gzip。
+    // 老方法 `session/list` 一个字节都不改——老版本手机继续走它，这是兼容的前提。
+    if (frame.method === SESSION_DIGEST_METHOD) {
+      const args = frame.args ?? {}
+      let result
+      try {
+        result = await this.dsh.rpc('session/list', { _request: args._request ?? {} })
+      } catch (error) {
+        result = { ok: false, error: errorObject('host/unavailable', messageOf(error)) }
+        this.lastError = messageOf(error)
+        this.#changed()
+      }
+      const payload = result?.ok === true
+        ? { ok: true, value: encodeDigest(digestSessionList(result), args.encoding) }
+        : result
+      this.send(deviceId, resultFrame(frame.id, payload, deviceId))
+      return
+    }
+
+    if (frame.method === DIAGNOSTICS_METHOD) {
+      const result = this.acceptDiagnostics(deviceId, frame.args ?? {})
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     // Files the phone sends are answered here rather than forwarded: the Host
     // has no upload endpoint, and carrying them on the existing unary frame
     // means neither the relay nor the protocol has to change.
@@ -458,6 +670,7 @@ export class DeviceRouter {
     let result
     try {
       result = await this.dsh.rpc(frame.method, frame.args ?? {})
+      result = trimHistoryPageForWire(frame.method, result)
     } catch (error) {
       result = { ok: false, error: errorObject('host/unavailable', messageOf(error)) }
       this.lastError = messageOf(error)

package/lib/routes.js

@@ -94,40 +94,8 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
   const guard = makeGuard(ctx, logger)
   const STATUS_ROUTE = '/mobile-link/status'
   const PAIR_ROUTE = '/mobile-link/pair-code'
-  /// SPIKE（spec 007 / T008）：只读测量宿主窗口与检索 API 的语义。
-  /// 默认关闭，只有 `DSH_MOBILE_LINK_HISTORY_PROBE=1` 时注册——它是一次性测量工具，
-  /// 不是产品面（结论已写回 specs/007-transcript-history/plan.md 的 Phase 0）。
-  const PROBE_ROUTE = '/mobile-link/history-probe'
   const disposers = []
 
-  if (history !== undefined && process.env.DSH_MOBILE_LINK_HISTORY_PROBE === '1') {
-    disposers.push(ctx.webServer.register({
-      kind: 'exact',
-      path: PROBE_ROUTE,
-      handler: async (req, res) => {
-        if (guard(req, res)) return
-        if (req.method !== 'GET') {
-          res.statusCode = 405
-          res.setHeader('allow', 'GET')
-          res.end()
-          return
-        }
-        const url = new URL(req.url ?? '/', 'http://127.0.0.1')
-        try {
-          const result = await history.probe({
-            sessionId: url.searchParams.get('sessionId') ?? '',
-            seq: url.searchParams.get('seq') ?? undefined,
-            n: url.searchParams.get('n') ?? undefined,
-            text: url.searchParams.get('text') ?? undefined,
-          })
-          sendJson(res, 200, result)
-        } catch (error) {
-          sendJson(res, 500, { ok: false, error: String(error?.message ?? error) })
-        }
-      },
-    }))
-  }
-
   disposers.push(ctx.webServer.register({
     kind: 'exact',
     path: STATUS_ROUTE,