dsh-plugin-mobile-link 0.6.6 → 0.7.0

package/README.md

@@ -80,7 +80,7 @@ dsh plugin --profile web add ./plugins/mobile-link
    dsh-mobile-link enroll --invite <邀请码> --relay wss://<你的站点>/dsh-link
    ```
 
-   …or register it on the relay host with `relay/admin.py agent-register
+   …or register it on the relay host with `dsh-relay admin agent-register
    --write-config ~/.dsh/mobile-link/agent.json`.
 
 2. Mint a pairing code, and show it as a QR the phone camera can read:

package/cordis.patch.yml

@@ -32,6 +32,12 @@
 #                  (the per-attach `device.summary` is still written).
 #   diagnostics    false refuses the phone's phase uploads (`_link/diagnostics`) with
 #                  `diagnostics/disabled`; the phone ignores it and stays connected.
+#   logs           false refuses the phone's runtime logs (`_link/logs`) with
+#                  `logs/disabled`; the phone keeps them in its own ring and retries.
+#   logsFile       log spool root (default ~/.dsh/mobile-link/logs). One directory
+#                  per device, one JSONL per local day, pruned to the last 7 days
+#                  in the write path itself — there is no timer or background job
+#                  to keep alive. Read it with `node scripts/dev/ios-logs.mjs`.
 #   dshUrl         explicit local DSH base URL override (default: discovery)
 #
 # Address resolution order: this config block, then DSH_RELAY_URL (or

package/lib/dir-listing.js

@@ -0,0 +1,167 @@
+/**
+ * `_link/dirListing`：`workspaceFiles/list` 的同形增强副本，本机补 `mtimeMs`。
+ *
+ * 为什么要它：宿主 `workspaceFiles/list` 的条目只有 `name/type/size?`（宿主类型见
+ * `@deepseek-ai/dsh-api-workspace-files` 的 `WorkspaceDirectoryEntry`），
+ * 没有任何时间字段；`workspaceFiles/stat` 的 `version` 是 opaque token（类型注释明确
+ * "never parsed"），推不出时间。用户要的是"哪个文件最近被动过"，所以由电脑侧补。
+ *
+ * 三条纪律（与 `session-digest.js` 同款）：
+ *   1. **清单的所有者仍是宿主**：连接器只往条目上加一个字段，不删、不改、不重排；
+ *      宿主报错时错误信封逐字透传。
+ *   2. **拿不到就原样返回**：root 缺失/相对/越界、单条目 stat 失败、超出总预算——
+ *      一律退回未增强的原始清单。装饰永不弄坏清单，目录本身一定能打开。
+ *   3. **不提速、不重试**：一个条目最多 stat 一次；没有缓存（mtime 会变，缓存就要失效
+ *      逻辑，而列目录本来就是低频动作）。
+ *
+ * 符号链接用 `fs.stat`（跟随链接）报**目标**的时间——宿主列的 `type`/`size` 本来就是
+ * 按目标解析的（类型注释："A symlink reports the type of its destination"），
+ * `lstat` 报的链接自身时间只在重指时变化，回答不了"内容什么时候改的"。
+ */
+
+import { stat } from 'node:fs/promises'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+/** 方法名（设备发起；`_link/` 前缀 = 连接器自答，永不转发宿主）。 */
+export const DIR_LISTING_METHOD = '_link/dirListing'
+
+/** 宿主的清单方法：连接器只读它，不改它。 */
+const HOST_LIST_METHOD = 'workspaceFiles/list'
+
+/** 可调的上限。`statBudgetMs` 是全部条目补时间的总预算（见 §2.2 失败语义表）。 */
+export const LIMITS = Object.freeze({
+  statBudgetMs: 2000,
+})
+
+export function isDirListingMethod(method) {
+  return method === DIR_LISTING_METHOD
+}
+
+/**
+ * 给一份宿主目录清单补上 `mtimeMs`。
+ *
+ * 认两种输入形状（与 `digestSessionList` 同款）：宿主信封 `{ ok, value: { entries } }`
+ * 以及直接给的 `{ entries }`。**返回的始终是同形状的值**，调用方不必再猜信封在哪一层。
+ * 结构不是预期的样子就原样返回入参——装饰不许把"看不懂"变成"改掉"。
+ *
+ * @param {object} options
+ * @param {{ rpc: (method: string, args: object) => Promise<unknown> }} options.dsh 宿主 RPC
+ * @param {object} options.args 设备发来的参数（`workspaceFileScopeId` / `path` / `root`）
+ * @param {{ debug?: (message: string) => void, warn?: (message: string) => void }} [options.logger]
+ * @param {(path: string) => Promise<{ mtimeMs: number }>} [options.statImpl] 可注入，供单测
+ * @param {number} [options.budgetMs] 总预算，缺省 `LIMITS.statBudgetMs`
+ * @returns {Promise<unknown>} 增强后的同形值；降级时是原始值
+ */
+export async function dirListing({ dsh, args, logger, statImpl = stat, budgetMs = LIMITS.statBudgetMs }) {
+  const request = args ?? {}
+  const result = await dsh.rpc(HOST_LIST_METHOD, {
+    workspaceFileScopeId: request.workspaceFileScopeId,
+    path: typeof request.path === 'string' ? request.path : '.',
+  })
+
+  const entries = listingEntries(result)
+  if (entries === null) {
+    logger?.debug?.('dir-listing: host answered a shape this connector does not decorate')
+    return result
+  }
+
+  const directory = resolveDirectory(request.root, entries.path)
+  if (directory === null) {
+    // root 缺失 / 非绝对 / 宿主回的 path 越出 root：不是错误，只是补不了时间。
+    logger?.debug?.(`dir-listing: cannot resolve the listed directory from root ${JSON.stringify(request.root)}`)
+    return result
+  }
+
+  const decorated = await withBudget(
+    Promise.all(entries.items.map((entry) => decorate(entry, directory, statImpl))),
+    budgetMs
+  )
+  if (decorated === null) {
+    logger?.warn?.(`dir-listing: stat budget of ${budgetMs}ms ran out, answering the plain listing`)
+    return result
+  }
+  return replaceEntries(result, decorated)
+}
+
+/**
+ * 取出清单本体（`{ entries: [...], path }`），形状不对时返回 null。
+ *
+ * 信封可能是 `result` 本身，也可能是 `result.value`——按"哪一层有 entries 数组"判定，
+ * 与 `digestSessionList` 同一读法。
+ */
+function listingEntries(result) {
+  if (result === null || typeof result !== 'object') return null
+  if (result.ok !== true) return null
+  const container = Array.isArray(result.entries) ? result : result.value
+  if (container === null || typeof container !== 'object' || !Array.isArray(container.entries)) return null
+  return { path: container.path, items: container.entries }
+}
+
+/** 按原形状放回增强后的条目数组。 */
+function replaceEntries(result, items) {
+  if (Array.isArray(result.entries)) return { ...result, entries: items }
+  return { ...result, value: { ...result.value, entries: items } }
+}
+
+/**
+ * 宿主回的 `path` 词法解析成绝对目录；解析不了（要求降级）时返回 null。
+ *
+ * - `path` 可以是相对的（`""` 表根、`"docs"`）也可以是绝对的（App/宿主都有先例）。
+ * - 结果必须位于 root 之内：`resolved === root || resolved.startsWith(root + sep)`。
+ *   只比 `startsWith(root)` 会把 `/a/b-sibling` 当成 `/a/b` 的子路径。
+ * - **不做 realpath 越界拦截**（设计 §2.2 决策 1）：符号链接的目标可以合法地在工作区
+ *   之外，宿主今天已经按目标报 `type`/`size`，这里保持同一语义。
+ */
+function resolveDirectory(root, echoedPath) {
+  if (typeof root !== 'string' || !isAbsolute(root)) return null
+  const base = resolve(root)
+  const echoed = typeof echoedPath === 'string' ? echoedPath : ''
+  const resolved = isAbsolute(echoed) ? resolve(echoed) : resolve(base, echoed)
+  if (resolved !== base && !resolved.startsWith(base + sep)) return null
+  return resolved
+}
+
+/**
+ * 一条条目：stat 成功且时间可用就加 `mtimeMs`，其余情况原样返回。
+ *
+ * 条目名逐段校验：含 `/`、`\` 或等于 `.` / `..` 的名字直接跳过（宿主契约说是 basename，
+ * 这里是纵深防御，防的是异常回包，不是防用户）。跳过的意思是"不给它补时间"，
+ * **不是把条目从清单里删掉**——清单的所有者是宿主。
+ */
+async function decorate(entry, directory, statImpl) {
+  if (entry === null || typeof entry !== 'object') return entry
+  if (typeof entry.name !== 'string' || !isPlainName(entry.name)) return entry
+  try {
+    const info = await statImpl(resolve(directory, entry.name))
+    const mtimeMs = info?.mtimeMs
+    if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs)) return entry
+    const rounded = Math.round(mtimeMs)
+    if (!Number.isFinite(rounded)) return entry
+    return { ...entry, mtimeMs: rounded }
+  } catch {
+    // 断链、权限、竞态删除：这个条目没有时间，其余条目照旧。
+    return entry
+  }
+}
+
+function isPlainName(name) {
+  return name.length > 0 && name !== '.' && name !== '..' && !name.includes('/') && !name.includes('\\')
+}
+
+/**
+ * 给整批 stat 一个总预算。超时返回 `null`（调用方据此降级），
+ * **不取消**后台的 stat——它们会自然收尾，取消反而要给每条挂一个 signal。
+ */
+async function withBudget(work, budgetMs) {
+  if (!(budgetMs > 0)) return await work
+  let timer
+  const expiry = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), budgetMs)
+  })
+  try {
+    const outcome = await Promise.race([work, expiry])
+    return outcome === null ? null : outcome
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/lib/dlp.js

@@ -6,6 +6,8 @@
  * Wire contract: docs/RELAY-PROTOCOL.md §3.
  */
 
+import { repairLoneSurrogatesWithCount } from './unicode.js'
+
 /** Frame ceiling aligned with DSH's image-attachment limit (spec §5). */
 export const MAX_FRAME_BYTES = 32 * 1024 * 1024
 
@@ -40,8 +42,23 @@ export const RELAY_TO_AGENT_CONTROL = new Set(['fsGetCancel'])
 
 const ID_FRAMES = new Set(['req', 'open', 'cancel', 'res', 'item', 'end', 'streamError', 'eventResult'])
 
+/**
+ * 出站帧的唯一序列化出口。
+ *
+ * 为什么要过一遍代理项修复：宿主会给我们**截断过**的预览（`turnOutline` 的
+ * prompt/response 截到 50/120 个码元），截断点落在 emoji 中间时字符串里就有
+ * 落单代理项，`JSON.stringify` 会忠实写成 `"\ud83d…"`。中转能把它修回 U+FFFD，
+ * 但解码方（iOS `JSONDecoder`）遇到这种转义会整条拒绝，所以生产端先把帧修好。
+ */
 export function encodeFrame(frame) {
-  return JSON.stringify(frame)
+  return encodeFrameChecked(frame).text
+}
+
+/** `encodeFrame` 的带诊断版本：`repaired` 是这条帧里修掉的落单代理项条数。 */
+export function encodeFrameChecked(frame) {
+  const raw = JSON.stringify(frame)
+  const { text, repaired } = repairLoneSurrogatesWithCount(raw)
+  return { text, repaired }
 }
 
 /**

package/lib/enroll.js

@@ -2,11 +2,11 @@
  * First-run enrollment: turn an invite code into a durable agent identity.
  *
  * Until now an identity could only be provisioned by whoever owns the relay
- * (`relay/admin.py agent-register --write-config`). That does not distribute:
+ * (`dsh-relay admin agent-register --write-config`). That does not distribute:
  * somebody else installs DSH plus this connector on their own computer and has
  * to be handed a credential by the operator, out of band.
  *
- * So the relay grew `POST /agents/enroll` (relay/api.py), which redeems a
+ * So the relay grew `POST /agents/enroll` (relay-go/internal/httpapi), which redeems a
  * one-time invite code for a fresh `agentId` / `agentSecret`. This module is the
  * connector half: one call, then the identity is written to the same
  * `~/.dsh/mobile-link/agent.json` (mode 0600) that `agent-register` writes, so

package/lib/files.js

@@ -26,6 +26,24 @@ export function isFileMethod(method) {
   return method === FILE_BEGIN || method === FILE_CHUNK || method === FILE_END
 }
 
+/**
+ * 多久没有新分片就认定这次上传已经没人要了。
+ *
+ * 这个时限不是"请求超时"：正在慢慢传的上传每来一片就重新计时。它要解决的是
+ * 一种**线上没有信号**的中断——relay 的 `PUT /files/up` 被手机掐掉之后，两个
+ * 中转（Python 与 Go）都只在本地摘掉桥接，**不会给连接器发任何取消帧**，也不会
+ * 断开 agent 的 WebSocket。连接器因此永远等不到下一次 `fsPutChunk`/`fsPutEnd`，
+ * `.part` 的 fd 就一直开着（M8 文件联调实测）。
+ *
+ * 取值要能容下慢速链路：1 MiB 一片，即便链路慢到 100 KB/s 也约 10 秒一片；
+ * 10 分钟的空档只可能是手机侧被系统挂起或请求早已死掉。真被清扫时，这次上传
+ * 会以 `fsErr`/HTTP 错误明确失败，用户重传即可，不会静默写出半截文件。
+ */
+export const DEFAULT_TRANSFER_IDLE_MS = 10 * 60 * 1000
+
+/** 空闲清扫的周期：只决定"最晚多久之后"释放，不决定"多久算空闲"。 */
+export const DEFAULT_SWEEP_MS = 30 * 1000
+
 /**
  * One in-flight transfer.
  *
@@ -40,7 +58,10 @@ export function isFileMethod(method) {
  * checks out, so a half-sent file is never mistaken for a complete one.
  */
 class Transfer {
-  constructor({ sessionId, name, bytes }) {
+  /** 注入的时钟；FileInbox 把它传给每次 Transfer，保证"空闲多久"只有一份口径。 */
+  #now
+
+  constructor({ sessionId, name, bytes, now = Date.now }) {
     this.sessionId = sessionId
     this.name = basename(name || 'file')
     this.bytes = Number.isFinite(bytes) ? bytes : undefined
@@ -51,6 +72,12 @@ class Transfer {
     this.directory = join(dshHome(), 'inbox', sessionId)
     mkdirSync(this.directory, { recursive: true, mode: 0o700 })
     this.staging = join(this.directory, `.${this.name}.part`)
+    // 最后一次收到分片的时刻（空闲清扫用）。时钟由 FileInbox 注入，测试里可精确推进。
+    this.#now = now
+    this.lastActivityAt = now()
+    // 释放只能发生一次：fd 与 `.part` 是同一份资源的两个面，重复释放要么是空操作、
+    // 要么会删到别人刚建好的同路径文件（重传接管时正好是这种情况）。
+    this.released = false
     // Opened once and kept: reopening per chunk would be a syscall per chunk for
     // no benefit. `w` truncates, which is what a retried transfer wants.
     this.fd = undefined
@@ -72,6 +99,7 @@ class Transfer {
     writeSync(this.#handle(), buffer)
     this.received += buffer.length
     this.expectedSeq += 1
+    this.lastActivityAt = this.#now()
   }
 
   finish() {
@@ -95,7 +123,15 @@ class Transfer {
     }
   }
 
+  /**
+   * 放弃这次上传：关句柄、删暂存文件，幂等。
+   *
+   * **只碰 `.part`**：`finish()` 已把暂存改名成成品，这里再调一次也只是对一个
+   * 不存在的暂存路径做 no-op，成品不会被误删（`已完成的文件不会被清理路径误删` 用例守着）。
+   */
   dispose() {
+    if (this.released) return
+    this.released = true
     this.#close()
     rmSync(this.staging, { force: true })
   }
@@ -105,9 +141,56 @@ class Transfer {
 export class FileInbox {
   #transfers = new Map()
   #logger
+  #idleMs
+  #now
+  #sweeper
 
-  constructor(logger) {
+  /**
+   * @param {object} [logger]
+   * @param {object} [options]
+   * @param {number} [options.idleMs] 多久没有新分片算"没人要了"
+   * @param {number} [options.sweepMs] 空闲清扫周期
+   * @param {() => number} [options.now] 注入时钟（测试用；生产就是 `Date.now`）
+   */
+  constructor(logger, {
+    idleMs = DEFAULT_TRANSFER_IDLE_MS,
+    sweepMs = DEFAULT_SWEEP_MS,
+    now = Date.now,
+  } = {}) {
     this.#logger = logger
+    this.#idleMs = idleMs
+    this.#now = now
+    // 定时器是**兜底信号**：relay 从不为上传发取消帧，也不在上传中断时断开
+    // agent 的 WebSocket，所以"再也不会来分片"只能由时间发现。`unref` 掉，
+    // 别让一个空的收件箱按住进程退出（与 link.js / jobs-roster.js 同一口径）。
+    this.#sweeper = setInterval(() => this.sweep(), Math.max(1, sweepMs))
+    this.#sweeper.unref?.()
+  }
+
+  /**
+   * 释放空闲超过 `idleMs` 的上传；返回本次释放的个数。
+   *
+   * 单独暴露是为了让测试给出确定时刻，而不是 sleep 等定时器；生产里由构造时
+   * 安好的 interval 调用。
+   */
+  sweep(now = this.#now()) {
+    let released = 0
+    for (const [transferId, transfer] of this.#transfers) {
+      const idle = now - transfer.lastActivityAt
+      if (idle < this.#idleMs) continue
+      this.#release(transferId, transfer)
+      this.#logger.warn?.(
+        `mobile-link: file transfer ${transferId} released after ${Math.round(idle / 1000)}s idle`,
+      )
+      released += 1
+    }
+    return released
+  }
+
+  /** 收掉一次在传上传；释放本身幂等，重复到达的取消/清扫都是空操作。 */
+  #release(transferId, transfer) {
+    transfer.dispose()
+    this.#transfers.delete(transferId)
   }
 
   /** Answers one reserved call. Throws `Error` for the router to report. */
@@ -118,12 +201,21 @@ export class FileInbox {
     if (method === FILE_BEGIN) {
       const sessionId = String(args.sessionId ?? '')
       if (!sessionId) throw new Error('sessionId is required')
-      this.#transfers.get(transferId)?.dispose()
-      this.#transfers.set(
-        transferId,
-        new Transfer({ sessionId, name: args.name, bytes: Number(args.bytes) })
+      const transfer = new Transfer({
+        sessionId, name: args.name, bytes: Number(args.bytes), now: this.#now,
+      })
+      // 一条 `.part` 同时只能有一个写者。两种"重来"都要在这里把旧的收掉：
+      // 同一个 bid 重来，以及手机换了新 bid 但落盘路径相同（中断后重传）。
+      // 不收的话旧 fd 会一直握着一个已被 unlink 的 inode——M8 联调实测的泄漏。
+      for (const [id, existing] of this.#transfers) {
+        if (id === transferId || existing.staging === transfer.staging) {
+          this.#release(id, existing)
+        }
+      }
+      this.#transfers.set(transferId, transfer)
+      this.#logger.debug?.(
+        `mobile-link: file transfer ${transferId} started for ${sessionId}`,
       )
-      this.#logger.debug?.(`mobile-link: file transfer ${transferId} started for ${sessionId}`)
       return { accepted: true }
     }
 
@@ -131,7 +223,14 @@ export class FileInbox {
     if (!transfer) throw new Error(`unknown transfer ${transferId}`)
 
     if (method === FILE_CHUNK) {
-      transfer.append(Number(args.seq ?? 0), String(args.data ?? ''))
+      try {
+        transfer.append(Number(args.seq ?? 0), String(args.data ?? ''))
+      } catch (error) {
+        // 这一片已经给这次上传判了死（调用方随后回 `fsErr`）：句柄与 `.part`
+        // 一起收掉，别等空闲清扫——它可能永远等不到下一次触发。
+        this.#release(transferId, transfer)
+        throw error
+      }
       return { received: transfer.received }
     }
 
@@ -143,14 +242,21 @@ export class FileInbox {
       )
       return done
     } finally {
-      transfer.dispose()
-      this.#transfers.delete(transferId)
+      this.#release(transferId, transfer)
     }
   }
 
+  /** 放弃一次上传（relay 的 `fsPutCancel`）。未知 id 是空操作，与 `fsGetCancel` 同口径。 */
+  cancel(transferId) {
+    const id = String(transferId ?? '')
+    const transfer = this.#transfers.get(id)
+    if (transfer) this.#release(id, transfer)
+  }
+
   /** Drops every in-flight transfer, e.g. when the link goes down. */
   clear() {
-    for (const transfer of this.#transfers.values()) transfer.dispose()
-    this.#transfers.clear()
+    for (const [transferId, transfer] of this.#transfers) {
+      this.#release(transferId, transfer)
+    }
   }
 }

package/lib/git.js

@@ -19,6 +19,7 @@
 import { execFile } from 'node:child_process'
 import { statSync } from 'node:fs'
 import { isAbsolute, resolve } from 'node:path'
+import { truncateSafe } from './unicode.js'
 
 /** Reserved method names this module answers; never forwarded to the Host. */
 export const GIT_STATUS = '_link/gitStatus'
@@ -44,10 +45,24 @@ export const LIMITS = {
   readTimeoutMs: 15_000,
 }
 
-/** The environment every git call runs in. */
-function gitEnv() {
+/** The environment every git call runs in.
+ *
+ * 导出给单测的 fixture 使用：测试自己也要起 git，两边必须是同一份环境口径，
+ * 否则 hook 里跑测试时 fixture 会写进外层仓库。
+ */
+export function gitEnv() {
+  const env = { ...process.env }
+  // "看哪个仓库"只由 `-C <dir>` 决定。调用方环境里可能带着仓库定位变量（从
+  // .githooks 里启动 DSH、或在 git rebase 里启动时都会这样），它们会盖掉 `-C`，
+  // 让手机看到另一个仓库、甚至报 "nothing to commit"。这里清掉，归属唯一。
+  for (const key of [
+    'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_NAMESPACE',
+    'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  ]) {
+    delete env[key]
+  }
   return {
-    ...process.env,
+    ...env,
     // Never wait for a credential prompt or open an editor: a phone review
     // must not be able to wedge a process on the computer.
     GIT_TERMINAL_PROMPT: '0',
@@ -400,7 +415,7 @@ export class GitBridge {
       staged,
       untracked,
       binary,
-      text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+      text: binary ? '' : truncateSafe(text, LIMITS.diffBytes),
       truncated: !binary && buffer.length > LIMITS.diffBytes,
     }
   }
@@ -450,7 +465,7 @@ export class GitBridge {
         sha,
         path,
         binary,
-        text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+        text: binary ? '' : truncateSafe(text, LIMITS.diffBytes),
         truncated: !binary && buffer.length > LIMITS.diffBytes,
       }
     }

package/lib/hello.js

@@ -98,6 +98,28 @@ export const SERVER_CAPABILITIES = [
   // search-progress: 扫描式搜索的每一页都带 `totalChunks` / `remainingChunks`，
   // 界面据此从第一页起就能显示「已扫 k/N 片」（026 之后的 App 才读）。
   'search-progress',
+  // history-compression: `_link/sessionWindow` 可按要求把回包压成
+  // `deflate-raw` 的 base64 信封（见 history/compress.js）。手机只在看到这条
+  // 能力时请求；旧客户端不传 encoding，回包与改动前逐字一致。
+  'history-compression',
+  // history-fold-summary: `_link/sessionWindow` 接受 `fold: true`，把已完成轮次的
+  // 过程事件折成一条 `+link/fold` 摘要（见 history/fold.js）；手机展开时用普通请求取回。
+  'history-fold-summary',
+  // history-fold-summary-v2: `_link/sessionWindow` 另接受 `fold: "summary"`——概要先行
+  // 取数（只回讲话 + `+link/fold` v2 概要 + 正式回答，按整轮切页，见
+  // history/fold-summary.js 与 history/summary-window.js）。**独立能力位**：
+  // 不声明 `"summary"` 的老客户端拿到的回包与改动前逐字节相同。
+  'history-fold-summary-v2',
+  'history-coverage',
+  // jobs-roster: 连接器答 `_link/jobRoster`（逐活会话聚合宿主任务），并推
+  // `link/jobs` 帧（spec 018）。手机**只按这条能力**决定是否渲染任务面板、列表行
+  // 右侧计数与卡片新行：无此能力的旧连接器，手机整块不出现（界面与升级前逐屏一致）。
+  'jobs-roster',
+  // dir-mtimes: 连接器答 `_link/dirListing`——宿主 `workspaceFiles/list` 的同形副本，
+  // 在电脑本机对每个条目补一个 `mtimeMs`（宿主类型里没有时间字段，`stat` 的 version
+  // 是 opaque token，推不出时间）。手机**只按这条能力**决定要不要走新方法：没有它的
+  // 旧连接器仍走 `workspaceFiles/list`，文件页与升级前逐屏一致（只是没有时间），不报错。
+  'dir-mtimes',
   'device-subprotocol-auth', 'persistent-pair-code', 'account-state', 'account-state-push',
 ]
 

package/lib/history/compress.js

@@ -0,0 +1,40 @@
+/**
+ * `_link/sessionWindow` 的可选压缩（能力 `history-compression`）。
+ *
+ * 为什么在应用层压：中转的 WebSocket 关闭了 permessage-deflate（`compress=False`），
+ * iOS 的 `URLSessionWebSocketTask` 也不支持协商压缩。要在不动中转的前提下减少
+ * 公网字节，只能在连接器把 value 压成 DEFLATE、手机侧自己解（与 spec 021 的
+ * `_link/sessionDigest` 同一套信封与同一种编码）。
+ *
+ * 编码选 `deflate-raw`（RFC1951）而不是 gzip：Apple `Compression` 框架的
+ * `COMPRESSION_ZLIB` 直接解原始 DEFLATE，gzip 包装还得引 libz。
+ *
+ * 兼容：不传 `encoding` 或传了不认识的值时原样返回 JSON，老 App 行为不变；
+ * 新 App 只在 `_link/hello` 声明了 `history-compression` 时才请求压缩。
+ */
+
+import { deflateRawSync } from 'node:zlib'
+
+/// 与 `session-digest.js` 的 `DEFLATE_ENCODING` 同一词表（协议里只能有一个名字）。
+export const HISTORY_COMPRESSION_ENCODING = 'deflate-raw'
+
+/// 能力名：连接器在 `_link/hello` 里声明，手机据此决定要不要请求压缩。
+export const HISTORY_COMPRESSION_CAPABILITY = 'history-compression'
+
+/// 把一页的值包成 `{encoding, value(base64), rawBytes}` 信封。
+///
+/// `rawBytes` 是解压后的字节数：`compression_decode_buffer` 必须先知道输出多大，
+/// 让连接器一次给足，手机就不用"猜容量、失败再翻倍"。
+export function compressHistoryValue(value) {
+  const raw = Buffer.from(JSON.stringify(value ?? null), 'utf8')
+  return {
+    encoding: HISTORY_COMPRESSION_ENCODING,
+    value: deflateRawSync(raw).toString('base64'),
+    rawBytes: raw.length,
+  }
+}
+
+/// 按调用方要求决定压不压。只有明确要 `deflate-raw` 才压。
+export function maybeCompressHistoryValue(value, encoding) {
+  return encoding === HISTORY_COMPRESSION_ENCODING ? compressHistoryValue(value) : value
+}

package/lib/history/coverage.js

@@ -0,0 +1,21 @@
+/**
+ * 已知为空的推导：一次窗口回包里，哪些号确认没有内容。
+ *
+ * 只在"从最老一条返回到窗口上界"之间下结论：窗口下界到最老返回之间可能被
+ * 字节/条数截断，那一段没有被完整扫描，不能判空。上界取 `before - 1`。
+ */
+export function emptySpans(records, lower, upper) {
+  const seqs = (records ?? [])
+    .map((record) => record?.event?.seq)
+    .filter((seq) => Number.isInteger(seq) && seq >= lower && seq <= upper)
+    .sort((a, b) => a - b)
+  if (seqs.length === 0) return []
+  const spans = []
+  let cursor = seqs[0]
+  for (const seq of seqs) {
+    if (seq > cursor) spans.push([cursor, seq - 1])
+    cursor = seq + 1
+  }
+  if (upper >= cursor) spans.push([cursor, upper])
+  return spans
+}