dsh-plugin-mobile-link 0.6.6 → 0.8.0

package/lib/link.js

@@ -7,7 +7,7 @@
 import { EventEmitter } from 'node:events'
 
 import { DshClient } from './dsh-client.js'
-import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
+import { agentEndpoint, decodeFrame, deviceListEndpoint, deviceRevokeEndpoint, encodeFrameChecked, isPlaceholderRelayUrl, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 
 /**
  * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
@@ -18,9 +18,10 @@ import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl
  * 挂在 `globalThis` 上是因为模块重载会把模块作用域清掉，只有进程级才留得住。
  */
 const LIVE_AGENT = Symbol.for('dsh.mobile-link.live-agent')
-import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
+import { EnrollError, enrollAgent, enrollCommand, inviteFrom, reportMachineAddress } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
 import { LinkJournal, defaultJournalPath } from './journal.js'
+import { LogSpool, defaultLogsRoot } from './logs.js'
 import { statusSnapshot } from './status.js'
 import { mintPairCode, regeneratePairCode } from './pairing.js'
 import {
@@ -28,7 +29,8 @@ import {
   EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
 } from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
-import { MissingIdentity, resolveIdentity } from './state.js'
+import { createJobsRoster } from './jobs-roster.js'
+import { MissingIdentity, defaultStatePath, readState, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
 const PROTOCOL_VERSION = 1
@@ -62,16 +64,19 @@ export class MobileLinkAgent extends EventEmitter {
     slowRequestMs = DEFAULT_SLOW_REQUEST_MS,
     // 关掉手机推送的接收（回退闸）；见 contracts/connector-diagnostics-method.md §4。
     diagnostics = true,
-    inviteCode, fetchImpl = fetch, env = process.env,
+    inviteCode, defaultRelayUrl, fetchImpl = fetch, env = process.env,
     // 生命周期流水（见 journal.js）：`journal` 传实例（测试注入），`journalPath`
     // 传路径（`defaultJournalPath()` 之外的位置），false 表示只留内存不落盘。
     journal, journalPath,
+    // 设备日志落盘（见 logs.js）：`logs` 传实例（测试注入），`logsRoot` 换目录，
+    // `logs: false` 关掉接收（手机会把它当旧连接器，静默忽略）。
+    logs = true, logsRoot,
     // 手机不在时替它攒下来的提问条数上限（见 router.js）；环境变量给部署用，
     // 构造参数给测试用。**没有"留多久"这个旋钮**：`$events` 一直留到设备被撤销。
     eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
   } = {}) {
     super()
-    this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, inviteCode }
+    this.config = { relayUrl, defaultRelayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, inviteCode }
     this.logger = logger
     this.heartbeatMs = heartbeatMs
     this.pongTimeoutMs = pongTimeoutMs
@@ -97,6 +102,12 @@ export class MobileLinkAgent extends EventEmitter {
       now,
       logger,
     })
+    /** 设备日志落盘：默认开着，目录在身份文件旁边，保留 7 天（清理在写入路径上）。 */
+    this.logsSpool = logs === false
+      ? null
+      : (logs && typeof logs === 'object'
+        ? logs
+        : new LogSpool({ root: logsRoot, logger, now }))
     this.router = new DeviceRouter({
       dsh: this.dsh,
       logger,
@@ -105,6 +116,7 @@ export class MobileLinkAgent extends EventEmitter {
       eventsBacklog,
       slowRequestMs: this.slowRequestMs,
       diagnostics: this.diagnostics,
+      logs: this.logsSpool,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
       // 设备侧的 attach/detach 与链路侧同源记进流水：事后想把"手机断了"和
       // "连接器拆链"对上时间，两边必须写在同一份文件里。
@@ -126,6 +138,15 @@ export class MobileLinkAgent extends EventEmitter {
     /// 历史读取（spec 007）：宿主 `sessionQuery` 就绪后由插件挂上；没挂上时
     /// 路由回 `link/unsupported`，手机继续走 `session/page`。
     this.setHistoryService = (service) => { this.router.history = service }
+    /// 活动名单与 `link/jobs` 推帧（spec 018）：帧由 router 广播给在线设备，
+    /// 订阅与去抖都在 roster 里。宿主服务由 `setJobsServices` 挂上。
+    this.jobsRoster = createJobsRoster({
+      deliver: (value) => this.router.publishEvent(value),
+      logger,
+      now,
+    })
+    this.router.bindJobsRoster(this.jobsRoster)
+    this.setJobsServices = (services) => this.jobsRoster.bindServices(services)
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -152,6 +173,8 @@ export class MobileLinkAgent extends EventEmitter {
     this._lastPong = 0
     this._loop = undefined
     this._loopActive = false
+    /** Single-flight guard for panel enrollment: two clicks redeem one code. */
+    this._enrolling = undefined
     this._watchdog = undefined
     this._lastProgressAt = 0
     this._abort = new AbortController()
@@ -264,7 +287,26 @@ export class MobileLinkAgent extends EventEmitter {
       }
     }
     globalThis[LIVE_AGENT] = this
-    if (this._loop) return this
+    // 只认"正在跑"的 loop：loop 可能因为未登记而结束，此时 `_loop` 还留着已完成的
+    // promise；拿它当"已在运行"会让面板登记完之后再也起不来。
+    if (this._loopActive) return this
+    // 显式 start 表示"要跑"：把 stop() 留下的栅栏放下来；不要靠 #launch 里
+    // 那个"正在停止就别启动"的保护来代劳。
+    this._stopping = false
+    this.#launch()
+    return this
+  }
+
+  /**
+   * Start one run of the reconnect loop.
+   *
+   * The single owner of "how a loop starts": `start()` calls it on boot and
+   * `enroll()` calls it after the identity is written. Never copy the loop
+   * bootstrapping into a second path — a divergent copy would skip the watchdog,
+   * the journal entry or the LIVE_AGENT bookkeeping.
+   */
+  #launch() {
+    if (this._stopping) return
     this._stopping = false
     this._abort = new AbortController()
     this.startedAt = this.now()
@@ -290,7 +332,6 @@ export class MobileLinkAgent extends EventEmitter {
     }).finally(() => {
       this._loopActive = false
     })
-    return this
   }
 
   async stop() {
@@ -376,7 +417,13 @@ export class MobileLinkAgent extends EventEmitter {
    * starts) and because `status()` reports whether it is still outstanding.
    */
   async enrollNow() {
-    const relayUrl = this.config.relayUrl
+    // A packaged install may pin only `defaultRelayUrl` (the panel prefill) and
+    // leave `relayUrl` at the placeholder; boot-time enrollment should still use
+    // the default rather than dial example.com.
+    const configured = this.config.relayUrl
+    const relayUrl = configured && !isPlaceholderRelayUrl(configured)
+      ? configured
+      : (this.config.defaultRelayUrl || configured)
     const settled = await enrollAgent({
       relayUrl,
       inviteCode: inviteFrom({ inviteCode: this.config.inviteCode, env: this.env }),
@@ -385,15 +432,151 @@ export class MobileLinkAgent extends EventEmitter {
       fetchImpl: this.fetchImpl,
       logger: this.logger,
     })
+    this.identity = settled
+    this.needsEnroll = false
+    this.lastError = undefined
+    this.emit('status')
+    return settled
+  }
+
+  /**
+   * Redeem an invite code supplied by the panel, then start the link in place.
+   *
+   * This is the only path that may enroll *while the process is running*. It is
+   * single-flight (a double click must not consume two codes), refuses to replace
+   * an existing identity, and writes nothing on failure. On success the loop is
+   * relaunched here, so the person does not have to restart DSH.
+   *
+   * @param {{inviteCode: string, relayUrl: string, agentName?: string}} options
+   */
+  enroll({ inviteCode, relayUrl, agentName } = {}) {
+    if (this._enrolling) return this._enrolling
+    this._enrolling = this.#enrollOnce({ inviteCode, relayUrl, agentName })
+      .finally(() => { this._enrolling = undefined })
+    return this._enrolling
+  }
+
+  async #enrollOnce({ inviteCode, relayUrl, agentName }) {
+    if (this.enabled === false) {
+      throw new EnrollError('enroll/disabled', 'mobile-link: the connector is disabled; enable it before enrolling')
+    }
+    if (this._stopping) {
+      throw new EnrollError('enroll/unavailable', 'mobile-link: the connector is stopping; try again')
+    }
+    const stateFile = this.config.stateFile || defaultStatePath()
+    const existing = await readState(stateFile)
+    if (existing?.agentId && existing?.agentSecret) {
+      // Never replace a working identity behind the user's back: that would
+      // silently unpair every phone that is already attached.
+      throw new EnrollError('enroll/already-registered',
+        `mobile-link: this computer is already registered (${existing.agentId}); refusing to replace it`,
+        { status: 409 })
+    }
+
+    const settled = await enrollAgent({
+      relayUrl,
+      inviteCode,
+      name: agentName,
+      stateFile,
+      fetchImpl: this.fetchImpl,
+      logger: this.logger,
+    })
+
+    // Publish the fresh identity before relaunching: `#enrollPending()` consults
+    // `this.identity`, and a stale value would make the new loop redeem the
+    // configured/env invite a second time on top of what the panel just wrote.
+    this.identity = settled
     this.needsEnroll = false
     this.lastError = undefined
+    this.reconnectAttempts = 0
     this.emit('status')
+
+    if (this.enabled !== false && !this._stopping) {
+      // If the previous loop is unwinding, let it finish before starting a new
+      // one; two loops would fight over the same relay agent session.
+      if (this._loopActive) await this._loop?.catch(() => {})
+      if (!this._loopActive && !this._stopping) this.#launch()
+    }
     return settled
   }
 
+  /**
+   * List every paired device for this agent, including ones that are offline.
+   * The router only knows attached devices; the panel needs the full roster so
+   * "已配对 N/M" and the visible rows describe the same set.
+   */
+  async listPairedDevices() {
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    let response
+    try {
+      response = await this.fetchImpl(deviceListEndpoint(identity.relayUrl), {
+        method: 'GET',
+        headers: { authorization: `Bearer ${identity.agentSecret}` },
+        signal: AbortSignal.timeout?.(15_000),
+      })
+    } catch (error) {
+      throw new Error(`mobile-link: cannot reach the relay to list devices: ${messageOf(error)}`)
+    }
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /devices`)
+    }
+    if (!response.ok || body?.ok !== true) {
+      throw new Error(body?.error?.message ?? `mobile-link: the relay rejected the device list (HTTP ${response.status})`)
+    }
+    return {
+      devices: Array.isArray(body.devices) ? body.devices : [],
+      maxPairedDevices: body.maxPairedDevices ?? null,
+      pairedDevices: body.pairedDevices ?? null,
+    }
+  }
+
+  /**
+   * Revoke one paired device through the relay, authenticated with this agent's
+   * secret. The relay enforces that the device belongs to this agent and drops
+   * its socket; the local router learns about it via `deviceDetach`.
+   *
+   * @param {string} deviceId
+   */
+  async revokeDevice(deviceId) {
+    const id = typeof deviceId === 'string' ? deviceId.trim() : ''
+    if (!id) throw new Error('mobile-link: a deviceId is required')
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    let response
+    try {
+      response = await this.fetchImpl(deviceRevokeEndpoint(identity.relayUrl), {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${identity.agentSecret}`,
+        },
+        body: JSON.stringify({ deviceId: id }),
+        signal: AbortSignal.timeout?.(15_000),
+      })
+    } catch (error) {
+      throw new Error(`mobile-link: cannot reach the relay to revoke ${id}: ${messageOf(error)}`)
+    }
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /devices/revoke`)
+    }
+    if (!response.ok || body?.ok !== true) {
+      throw new Error(body?.error?.message ?? `mobile-link: the relay rejected the revoke (HTTP ${response.status})`)
+    }
+    return { deviceId: body.deviceId ?? id }
+  }
+
   /** What a person has to run to register this computer. */
   enrollHint() {
-    return enrollCommand(this.config.relayUrl, this.config.agentName)
+    const configured = this.config.relayUrl
+    const relay = configured && !isPlaceholderRelayUrl(configured)
+      ? configured
+      : (this.config.defaultRelayUrl || configured)
+    return enrollCommand(relay, this.config.agentName)
   }
 
   /** One relay connection: resolves when the socket closes. */
@@ -401,6 +584,7 @@ export class MobileLinkAgent extends EventEmitter {
     const identity = await resolveIdentity(this.config)
     this.identity = identity
     this.needsEnroll = false
+    this.#backfillMachine(identity)
     this.relay = normalizeRelayUrl(identity.relayUrl)
     const url = `${agentEndpoint(identity.relayUrl)}?agentId=${encodeURIComponent(identity.agentId)}`
     const socket = await this.connectImpl(url, {
@@ -574,8 +758,30 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── relay I/O ───────────────────────────────────────────────────────────
 
+  /**
+   * 序列化一条出站帧，并把"修掉了落单代理项"记下来。
+   *
+   * 上游（宿主预览）切坏了 emoji 时，出口把它修成 U+FFFD 再发：帧合法，解码方
+   * 不会整条失败；同时留一条本机流水，出问题的源头仍然查得到。日志限流一分钟一次，
+   * 累计值不丢。
+   */
+  #encodeForWire(frame) {
+    const { text, repaired } = encodeFrameChecked(frame)
+    if (repaired <= 0) return text
+    this.surrogateRepairs = (this.surrogateRepairs ?? 0) + repaired
+    this.journal.record('frame.surrogate_repaired', { repaired, total: this.surrogateRepairs })
+    const now = this.now()
+    if (now - (this._lastSurrogateWarnAt ?? -Infinity) >= 60_000) {
+      this._lastSurrogateWarnAt = now
+      this.logger.warn?.(
+        `mobile-link: repaired ${repaired} unpaired surrogate(s) in an outbound frame ` +
+        `(a host preview was cut inside an emoji); ${this.surrogateRepairs} so far`)
+    }
+    return text
+  }
+
   #rawSend(frame) {
-    return this.#sendText(encodeFrame(frame))
+    return this.#sendText(this.#encodeForWire(frame))
   }
 
   /** 唯一的发送出口：socket 不在就丢掉，发送异常只记 debug、绝不抛。 */
@@ -595,7 +801,7 @@ export class MobileLinkAgent extends EventEmitter {
     // `deviceId` 为空＝这是一条**不带寻址**的帧（`fsPutAck`/`fsPutDone`/`fsErr` 那一族）：
     // relay 靠 `bid` 把回复对回发起的那个 HTTP 请求，多一个 deviceId 反而会让它对不上。
     if (deviceId === undefined || deviceId === null) return this.#rawSend(frame)
-    const text = encodeFrame({ ...frame, deviceId })
+    const text = this.#encodeForWire({ ...frame, deviceId })
     // 记字节给路由层的"慢请求/汇总"用（它按 deviceId 归）：只有这里知道真正上线了多少字节。
     this.router.noteSent?.(deviceId, Buffer.byteLength(text))
     return this.#sendText(text)
@@ -643,6 +849,27 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── mux-event delegates ─────────────────────────────────────────────────
 
+  /// 老身份在登记时还没有 MAC 字段：连接成功后补一次。只填一次，失败下轮再试，
+  /// 旧中转 404 视为不支持而不是链路故障。
+  #backfillMachine(identity) {
+    if (this._machineReportedFor === identity.agentId || this._machineReporting) return
+    this._machineReporting = true
+    void reportMachineAddress({
+      relayUrl: identity.relayUrl,
+      agentSecret: identity.agentSecret,
+      fetchImpl: this.fetchImpl,
+    }).then((result) => {
+      if (result.ok || result.unsupported) this._machineReportedFor = identity.agentId
+      if (result.ok && result.updated) {
+        this.logger.info?.(`mobile-link: recorded machine MAC ${result.macAddress}`)
+      }
+    }).catch((error) => {
+      this.logger.debug?.(`mobile-link: machine MAC backfill deferred: ${messageOf(error)}`)
+    }).finally(() => {
+      this._machineReporting = false
+    })
+  }
+
   onStreamItem(muxId, value) {
     this.router.onStreamItem(muxId, value)
   }

package/lib/logs.js

@@ -0,0 +1,242 @@
+/**
+ * 设备日志落盘（`_link/logs`）。
+ *
+ * 与 `journal.js` 的分工：journal 记的是**连接器自己**的生命周期事件（几百条、可以随手丢），
+ * 这里记的是**手机端**产生的日志行（量级大、需要按时间窗回看）。两者共用"诊断设施不许抛"
+ * 这条硬约束，但容量与保留期完全不同。
+ *
+ * 保留期 **7 天**，清理不靠定时器、也不新增任何进程：每次 `append` 顺手做一次，
+ * 且 60 秒内最多一次。理由是不引入定时任务就不会有"任务没跑起来、盘悄悄满了"这种状态。
+ *
+ * 目录布局：`<root>/<deviceId>/<YYYYMMDD>.jsonl`。按天分文件有三个好处：
+ * 清理只需 unlink 整个文件，不必重写；`tail` 只需盯当天的文件；超限时按天淘汰。
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { defaultStatePath } from './state.js'
+
+/** 日志保留期：7 天。 */
+export const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+/** 单台设备磁盘上限；超了按天淘汰最旧的。 */
+export const DEFAULT_MAX_DEVICE_BYTES = 200 * 1024 * 1024
+/** 单条日志正文上限；超长截断而不是丢弃（截断仍能看出是哪一行）。 */
+export const MAX_TEXT_CHARS = 4000
+/** 每批最多收多少条、多少字节；超了如实报 `accepted`，剩下的由手机下次推。 */
+export const MAX_BATCH_ENTRIES = 500
+export const MAX_BATCH_BYTES = 64 * 1024
+/** 清理的最小间隔：清理一次最多 60 秒一次。 */
+const PRUNE_INTERVAL_MS = 60 * 1000
+
+/** 默认落在身份文件旁边：`$DSH_HOME/mobile-link/logs`。测试用临时 DSH_HOME 自动隔离。 */
+export function defaultLogsRoot() {
+  return join(dirname(defaultStatePath()), 'logs')
+}
+
+/** 本地日 `YYYYMMDD`，与 journal 的 `local_day` 口径一致。 */
+export function dayStamp(ms) {
+  const date = new Date(ms)
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
+}
+
+/** 设备 id 会直接进路径：只留安全字符，避免 `../` 之类的路径穿越。 */
+export function safeDeviceId(deviceId) {
+  const text = String(deviceId ?? '').trim()
+  if (!text) return 'unknown'
+  return text.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 120)
+}
+
+/** 一条上报 → 一行落盘 JSON；非法条目返回 null（调用方计入拒收）。 */
+export function normalizeEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  const ms = Number(raw.ms)
+  const text = typeof raw.text === 'string' ? raw.text : ''
+  if (!Number.isFinite(ms) || !text) return null
+  const seq = Number(raw.seq)
+  return {
+    seq: Number.isFinite(seq) ? seq : undefined,
+    ms,
+    at: typeof raw.at === 'string' && raw.at ? raw.at : new Date(ms).toISOString(),
+    level: typeof raw.level === 'string' ? raw.level.slice(0, 16) : 'info',
+    source: typeof raw.source === 'string' ? raw.source.slice(0, 32) : 'app',
+    text: text.slice(0, MAX_TEXT_CHARS),
+  }
+}
+
+export class LogSpool {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.root] 目录（默认 `$DSH_HOME/mobile-link/logs`）
+   * @param {number} [options.retentionMs] 保留期
+   * @param {number} [options.maxDeviceBytes] 单设备上限
+   * @param {() => number} [options.now]
+   * @param {{ debug?: (message: string) => void }} [options.logger]
+   */
+  constructor({
+    root, retentionMs = DEFAULT_RETENTION_MS, maxDeviceBytes = DEFAULT_MAX_DEVICE_BYTES,
+    now = Date.now, logger,
+  } = {}) {
+    this.root = typeof root === 'string' && root.trim() ? root : defaultLogsRoot()
+    this.retentionMs = Math.max(60_000, Number(retentionMs) || DEFAULT_RETENTION_MS)
+    this.maxDeviceBytes = Math.max(1024, Number(maxDeviceBytes) || DEFAULT_MAX_DEVICE_BYTES)
+    this.now = now
+    this.logger = logger
+    /** 每台设备已接受的最高序号（幂等：同批重推不会写两遍）。 */
+    this.watermarks = new Map()
+    this._lastPruneAt = 0
+  }
+
+  /** 一台设备当天的文件路径。 */
+  pathFor(deviceId, ms = this.now()) {
+    return join(this.root, safeDeviceId(deviceId), `${dayStamp(ms)}.jsonl`)
+  }
+
+  /**
+   * 收一批并落盘。
+   *
+   * @returns {{accepted: number, lastSeq: number, dropped: number}}
+   *   `accepted` 是真正写下去的条数；被水位挡掉的重复条目不计入。
+   */
+  append(deviceId, entries, { full = false } = {}) {
+    const result = { accepted: 0, lastSeq: this.watermarks.get(deviceId) ?? 0, dropped: 0 }
+    if (!Array.isArray(entries) || entries.length === 0) return result
+    let bytes = 0
+    const byDay = new Map()
+    for (const raw of entries) {
+      const entry = normalizeEntry(raw)
+      if (!entry) { result.dropped += 1; continue }
+      const seq = Number(entry.seq)
+      const watermark = this.watermarks.get(deviceId) ?? 0
+      // `full` 是"整段重推"（App 冷启动回填或 `dsh://diag export`）：
+      // 水位不参与判断，但仍然照常推进，避免之后的增量重复。
+      if (!full && Number.isFinite(seq) && seq <= watermark) continue
+      const line = `${JSON.stringify({ ...entry, deviceId, full: full || undefined })}\n`
+      if (result.accepted > 0 && bytes + line.length > MAX_BATCH_BYTES) break
+      if (result.accepted >= MAX_BATCH_ENTRIES) break
+      const day = dayStamp(entry.ms)
+      const bucket = byDay.get(day) ?? []
+      bucket.push(line)
+      byDay.set(day, bucket)
+      bytes += line.length
+      result.accepted += 1
+      result.lastSeq = Math.max(result.lastSeq, Number.isFinite(seq) ? seq : result.lastSeq)
+    }
+    if (!byDay.size) return result
+    for (const [day, lines] of byDay) this.#write(deviceId, day, lines)
+    this.watermarks.set(deviceId, result.lastSeq)
+    this.#pruneIfDue()
+    return result
+  }
+
+  #write(deviceId, day, lines) {
+    const path = join(this.root, safeDeviceId(deviceId), `${day}.jsonl`)
+    try {
+      mkdirSync(dirname(path), { recursive: true })
+      appendFileSync(path, lines.join(''))
+    } catch (error) {
+      // 诊断设施不许把链路带崩：写不进去就只报一声。
+      this.logger?.debug?.(`mobile-link: logs spool write failed (${error?.message ?? error})`)
+    }
+  }
+
+  /** 60 秒内最多清理一次；清理本身不许抛。 */
+  #pruneIfDue() {
+    const now = this.now()
+    if (now - this._lastPruneAt < PRUNE_INTERVAL_MS) return
+    this._lastPruneAt = now
+    try {
+      this.prune(now)
+    } catch (error) {
+      this.logger?.debug?.(`mobile-link: logs prune failed (${error?.message ?? error})`)
+    }
+  }
+
+  /**
+   * 清理：先按保留期删整天文件，再按单设备上限删最旧的。
+   * 返回删掉的字节数（测试用；生产只看副作用）。
+   */
+  prune(now = this.now()) {
+    let freed = 0
+    let devices = []
+    try {
+      devices = readdirSync(this.root, { withFileTypes: true }).filter((item) => item.isDirectory())
+    } catch {
+      return 0
+    }
+    for (const device of devices) {
+      const dir = join(this.root, device.name)
+      let files = []
+      try {
+        files = readdirSync(dir).filter((name) => name.endsWith('.jsonl'))
+      } catch {
+        continue
+      }
+      if (!files.length) {
+        try { rmSync(dir, { recursive: true, force: true }) } catch { /* 目录删不掉无所谓 */ }
+        continue
+      }
+      const stats = []
+      for (const name of files.sort()) {
+        const path = join(dir, name)
+        try {
+          const info = statSync(path)
+          stats.push({ path, day: name.slice(0, 8), size: info.size, mtimeMs: info.mtimeMs })
+        } catch { /* 文件刚被删掉 */ }
+      }
+      // 保留期按**文件名里的日**判定，不看 mtime：mtime 会被备份、拷贝、恢复改动，
+      // 而"这是哪一天的日志"只写在名字里，判定必须与名字一致。
+      const cutoff = dayStamp(now - this.retentionMs)
+      for (const file of stats) {
+        if (file.day >= cutoff) continue
+        freed += this.#unlink(file)
+      }
+      let kept = stats.filter((file) => file.day >= cutoff)
+      let total = kept.reduce((sum, file) => sum + file.size, 0)
+      for (const file of kept) {
+        if (total <= this.maxDeviceBytes) break
+        total -= file.size
+        freed += this.#unlink(file)
+      }
+    }
+    return freed
+  }
+
+  #unlink(file) {
+    try {
+      unlinkSync(file.path)
+      return file.size
+    } catch {
+      return 0
+    }
+  }
+
+  /** 某台设备（或全部）的磁盘占用，给人看的。 */
+  usage() {
+    const rows = []
+    let devices = []
+    try {
+      devices = readdirSync(this.root, { withFileTypes: true }).filter((item) => item.isDirectory())
+    } catch {
+      return rows
+    }
+    for (const device of devices) {
+      const dir = join(this.root, device.name)
+      let bytes = 0
+      let files = 0
+      let newest = 0
+      try {
+        for (const name of readdirSync(dir)) {
+          if (!name.endsWith('.jsonl')) continue
+          const info = statSync(join(dir, name))
+          bytes += info.size
+          files += 1
+          newest = Math.max(newest, info.mtimeMs)
+        }
+      } catch { /* 忽略单台设备的读失败 */ }
+      rows.push({ deviceId: device.name, bytes, files, newestMs: newest })
+    }
+    return rows.sort((a, b) => b.bytes - a.bytes)
+  }
+}

package/lib/pairing.js

@@ -17,7 +17,7 @@ import { pairCodeEndpoint, pairCodeRegenerateEndpoint, qrPayload } from './dlp.j
  */
 export async function mintPairCode({ identity, ttlMs = null, fetchImpl = fetch }) {
   // 032：**持久码那条路不能把 `ttlMs` 放进请求体**。中转的判据是 `"ttlMs" not in body`
-  // （`relay/api.py` 的 `pair_code`）：带一个 `ttlMs: null` 会被读成"限时、但没给时长"，
+  // （`relay-go/internal/httpapi` 的 pair-code 处理）：带一个 `ttlMs: null` 会被读成"限时、但没给时长"，
   // 于是落到中转的默认 10 分钟——面板显示倒计时，码十分钟后就废（用户看到的就是这个）。
   const payload = ttlMs == null
     ? { agentId: identity.agentId }