dsh-plugin-mobile-link 0.2.0 → 0.3.1

package/README.md

@@ -1,5 +1,12 @@
 # dsh-plugin-mobile-link
 
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![listed in awesome-deepseek-harness](https://img.shields.io/badge/listed%20in-awesome--deepseek--harness-4D6BFE?logo=awesomelists&logoColor=white)](https://github.com/Dominic789654/awesome-deepseek-harness)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-mobile-link)](https://www.npmjs.com/package/dsh-plugin-mobile-link)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+> 面向：使用者与实现者 · 状态：stable · 最近核对：2026-09-20
+
 **The computer half of [DSH Mobile](https://github.com/jayantTang/DSH_Mobile): it
 dials a relay over WSS, so the native iOS client reaches this DSH instance even
 though the computer has no public IP.**

package/lib/cli.js

@@ -26,6 +26,7 @@ import { rename, writeFile } from 'node:fs/promises'
 import { enrollAgent, inviteFrom } from './enroll.js'
 import { MobileLinkAgent } from './link.js'
 import { mintPairCode } from './pairing.js'
+import { qrTerminal } from './qr.js'
 import { INVITE_ENV, defaultStatePath, resolveIdentity } from './state.js'
 
 /** Atomic status snapshot so readers never observe a half-written file. */
@@ -89,7 +90,28 @@ async function main() {
       relayUrl: settled.relayUrl,
       stateFile: settled.stateFile,
     }, null, 2)}\n`)
-    process.stdout.write('这台电脑已登记。重启 DSH 后连接器会使用新的身份。\n')
+    // 登记只是第一步：还有两步（重启、扫码）不写在输出里，新用户就会以为"登记完就好了"。
+    // 第一位试用用户正是这样——登记了电脑，却没有配对手机。
+    //
+    // 反正人已经坐在终端前、手机就在手边，索性把配对码也申请出来、画成终端二维码：
+    // 扫这一屏等于在 App 里填「中转服务器 + 配对码」，少一次开页面找端口的往返。
+    // 申请失败不算失败——登记本身已经成功，退回到"去二维码页取"的说法。
+    process.stdout.write('这台电脑已登记。接下来还有两步：\n'
+      + '  1. 重启 DSH，让连接器用上这个身份；\n'
+      + '  2. 手机 App 底部「扫码配对」扫下面的二维码（等同于点开二维码页取码）。\n')
+    try {
+      const identity = await resolveIdentity({ stateFile: settled.stateFile })
+      const minted = await mintPairCode({ identity, ttlMs: 10 * 60 * 1000 })
+      const minutes = Math.round((minted.expiresAt - Date.now()) / 60000)
+      process.stdout.write('\n' + qrTerminal(minted.qrPayload) + '\n')
+      process.stdout.write(`配对码 ${minted.code}（约 ${minutes} 分钟有效，一次性）\n`)
+      process.stdout.write('也可以在这台电脑上打开 http://127.0.0.1:<DSH 端口>/mobile-link/qr 取新码；\n'
+        + '端口在 DSH 启动时打印，也在 ~/.dsh/desktop-shell/endpoint.json 里。\n')
+    } catch (error) {
+      process.stdout.write('（这次没能预先申请配对码：' + (error?.message ?? error) + '）\n'
+        + '重启 DSH 后，在这台电脑的浏览器里打开 http://127.0.0.1:<DSH 端口>/mobile-link/qr，'
+        + '用手机 App 的「扫码配对」扫它。\n')
+    }
     return 0
   }
 

package/lib/dlp.js

@@ -190,6 +190,15 @@ export class StreamTable {
     return this.byDlp.get(StreamTable.key(deviceId, dlpId))
   }
 
+  /** Every open entry for one device, in insertion order. */
+  byDevice(deviceId) {
+    const entries = []
+    for (const entry of this.byMux.values()) {
+      if (entry.deviceId === deviceId) entries.push(entry)
+    }
+    return entries
+  }
+
   entryOfMux(muxId) {
     return this.byMux.get(muxId)
   }

package/lib/git.js

@@ -0,0 +1,506 @@
+/**
+ * Git status, diffs and history, answered on the computer itself.
+ *
+ * The Host has no git endpoint — nothing in its 47 RPC methods runs a command —
+ * but the connector is already a process on the machine that holds the work
+ * tree, and the `_link/file*` upload path proved the shape: a reserved method
+ * name answered here instead of being forwarded. So git runs here, in the
+ * session's own directory, and the phone gets what a person wants to check
+ * before approving an agent's work: which files changed, what changed in them,
+ * and what the recent commits were.
+ *
+ * **Read-only by construction.** The command whitelist below is the entire
+ * surface: status, diff, log, show, rev-parse, numstat. There is no way to
+ * commit, stage, checkout or clean through this path, and every command runs
+ * with `GIT_OPTIONAL_LOCKS=0` so merely looking at a repository can never leave
+ * an `index.lock` behind for the agent to trip over.
+ */
+
+import { execFile } from 'node:child_process'
+import { statSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+
+/** Reserved method names this module answers; never forwarded to the Host. */
+export const GIT_STATUS = '_link/gitStatus'
+export const GIT_DIFF = '_link/gitDiff'
+export const GIT_LOG = '_link/gitLog'
+export const GIT_SHOW = '_link/gitShow'
+export const GIT_FILE = '_link/gitFile'
+
+const METHODS = new Set([GIT_STATUS, GIT_DIFF, GIT_LOG, GIT_SHOW, GIT_FILE])
+
+export function isGitMethod(method) {
+  return METHODS.has(method)
+}
+
+/** Output ceilings: a phone review, not a `git log | less`. */
+export const LIMITS = {
+  statusBytes: 1024 * 1024,
+  diffBytes: 256 * 1024,
+  logBytes: 512 * 1024,
+  fileBytes: 8 * 1024 * 1024,
+  logPage: 20,
+  statusTimeoutMs: 15_000,
+  readTimeoutMs: 15_000,
+}
+
+/** The environment every git call runs in. */
+function gitEnv() {
+  return {
+    ...process.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',
+    GIT_PAGER: 'cat',
+    GIT_EDITOR: 'true',
+    // Looking at a repository must not take its locks — the agent may be
+    // working in it at the same moment.
+    GIT_OPTIONAL_LOCKS: '0',
+    // Stable field order and dates; the parsers below depend on it.
+    LC_ALL: 'C',
+  }
+}
+
+/** A refusal the phone can branch on, rather than a string to match. */
+export class GitError extends Error {
+  constructor(code, message, details = {}) {
+    super(message)
+    this.code = code
+    this.details = details
+  }
+}
+
+/**
+ * Runs one git command in `cwd`.
+ *
+ * `okCodes` exists because `git diff` answers 1 when it found differences —
+ * which is the normal case here, not a failure.
+ */
+function runGit(cwd, argv, { timeoutMs, maxBytes, okCodes = [0] } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    execFile(
+      'git',
+      ['-C', cwd, '--no-pager', '-c', 'core.quotepath=false', ...argv],
+      {
+        timeout: timeoutMs ?? LIMITS.readTimeoutMs,
+        maxBuffer: (maxBytes ?? LIMITS.diffBytes) + 1024,
+        env: gitEnv(),
+        encoding: 'buffer',
+      },
+      (error, stdout, stderr) => {
+        const out = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? '')
+        if (error) {
+          // `execFile` reports a spawn failure (no git installed) as ENOENT.
+          if (error.code === 'ENOENT') {
+            reject(new GitError('git/unavailable', '这台电脑上没有找到 git'))
+            return
+          }
+          if (error.killed || error.signal) {
+            reject(new GitError('git/timed-out', 'git 命令超过时限，已中止'))
+            return
+          }
+          if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            reject(new GitError('git/too-large', '命令输出超过上限，请缩小范围'))
+            return
+          }
+          const code = typeof error.code === 'number' ? error.code : 1
+          if (okCodes.includes(code)) {
+            resolvePromise(out)
+            return
+          }
+          const text = (Buffer.isBuffer(stderr) ? stderr : Buffer.from(stderr ?? '')).toString('utf8')
+          reject(new GitError('git/failed', text.trim().split('\n').slice(-1)[0] || 'git 命令失败', {
+            exitCode: code,
+          }))
+          return
+        }
+        resolvePromise(out)
+      }
+    )
+  })
+}
+
+/** Resolves a directory that is inside a work tree, and that tree's root. */
+async function repository(cwd) {
+  const directory = String(cwd ?? '')
+  if (!directory || !isAbsolute(directory)) {
+    throw new GitError('git/bad-request', '需要一个绝对路径的工作目录')
+  }
+  let stats
+  try {
+    stats = statSync(resolve(directory))
+  } catch {
+    throw new GitError('git/not-found', `目录不在了：${directory}`)
+  }
+  if (!stats.isDirectory()) {
+    throw new GitError('git/bad-request', `不是一个目录：${directory}`)
+  }
+  let root
+  try {
+    root = (await runGit(directory, ['rev-parse', '--show-toplevel'], {
+      timeoutMs: LIMITS.statusTimeoutMs,
+    }))
+      .toString('utf8')
+      .trim()
+  } catch (error) {
+    // `rev-parse` exits 128 outside a work tree; that is a state to report, not
+    // a failure of the command.
+    if (error instanceof GitError && error.code === 'git/failed') {
+      throw new GitError('git/not-a-repo', '这个目录不在 git 仓库里', { path: directory })
+    }
+    throw error
+  }
+  if (!root) throw new GitError('git/not-a-repo', '这个目录不在 git 仓库里', { path: directory })
+  return { directory, root }
+}
+
+/** One repository-relative path, as the phone sends it. */
+function safePath(value, { required = true } = {}) {
+  const path = String(value ?? '').trim()
+  if (!path) {
+    if (!required) return ''
+    throw new GitError('git/bad-request', '缺少文件路径')
+  }
+  if (isAbsolute(path) || path.split('/').includes('..')) {
+    throw new GitError('git/bad-request', `路径必须是仓库内的相对路径：${path}`)
+  }
+  return path
+}
+
+/** Whether this revision exists at all (a fresh repository has no HEAD). */
+async function headExists(root) {
+  try {
+    await runGit(root, ['rev-parse', '--verify', 'HEAD'])
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ── status ─────────────────────────────────────────────────────────────────
+
+/**
+ * `git status --porcelain=v2 -z --branch`.
+ *
+ * Version 2 with NUL separators, not the human format: it names the index and
+ * worktree sides separately (so "staged" and "not staged" are facts, not
+ * guesses), reports renames with both paths, and survives newlines in file
+ * names — which the line-based format does not.
+ */
+export function parseStatus(buffer) {
+  const records = buffer.toString('utf8').split('\0')
+  const files = []
+  let branch = { head: null, oid: null, upstream: null, ahead: 0, behind: 0, detached: false }
+
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]
+    if (!record) continue
+    if (record.startsWith('# branch.oid ')) {
+      branch.oid = record.slice('# branch.oid '.length).trim()
+      if (branch.oid === '(initial)') branch.oid = null
+      continue
+    }
+    if (record.startsWith('# branch.head ')) {
+      const head = record.slice('# branch.head '.length).trim()
+      branch.detached = head === '(detached)'
+      branch.head = branch.detached ? null : head
+      continue
+    }
+    if (record.startsWith('# branch.upstream ')) {
+      branch.upstream = record.slice('# branch.upstream '.length).trim()
+      continue
+    }
+    if (record.startsWith('# branch.ab ')) {
+      // `# branch.ab +2 -1`: the counters are the third and fourth fields.
+      const parts = record.split(/\s+/)
+      branch.ahead = Number(String(parts[2] ?? '').replace('+', '')) || 0
+      branch.behind = Number(String(parts[3] ?? '').replace('-', '')) || 0
+      continue
+    }
+    if (record.startsWith('1 ')) {
+      const parts = record.split(' ')
+      // 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+      files.push(entry(parts[1], parts.slice(8).join(' '), null))
+      continue
+    }
+    if (record.startsWith('2 ')) {
+      const parts = record.split(' ')
+      // 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>
+      const path = parts.slice(9).join(' ')
+      // The original path is the next NUL-separated field.
+      const original = records[index + 1] ?? ''
+      index += 1
+      files.push(entry(parts[1], path, original))
+      continue
+    }
+    if (record.startsWith('u ')) {
+      const parts = record.split(' ')
+      // u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+      files.push({ ...entry(parts[1], parts.slice(10).join(' '), null), conflicted: true })
+      continue
+    }
+    if (record.startsWith('? ')) {
+      files.push({ path: record.slice(2), originalPath: null, index: '.', worktree: '?', kind: 'untracked', staged: false, unstaged: true, conflicted: false })
+      continue
+    }
+  }
+  return { branch, files }
+}
+
+function entry(xy, path, originalPath) {
+  const index = xy?.[0] ?? '.'
+  const worktree = xy?.[1] ?? '.'
+  return {
+    path,
+    originalPath: originalPath || null,
+    index,
+    worktree,
+    kind: kindOf(index, worktree),
+    staged: index !== '.' && index !== '?',
+    unstaged: worktree !== '.' && worktree !== '?',
+    conflicted: false,
+  }
+}
+
+function kindOf(index, worktree) {
+  const code = worktree !== '.' ? worktree : index
+  switch (code) {
+    case 'A': return 'added'
+    case 'D': return 'deleted'
+    case 'R': return 'renamed'
+    case 'C': return 'copied'
+    case 'T': return 'typechange'
+    case 'M': return 'modified'
+    default: return 'modified'
+  }
+}
+
+// ── log ────────────────────────────────────────────────────────────────────
+
+const LOG_FORMAT = '%H%x1f%h%x1f%an%x1f%aI%x1f%s%x1f%D'
+
+/** `git log -z --format=…`: one NUL-separated record per commit. */
+export function parseLog(buffer) {
+  return buffer
+    .toString('utf8')
+    .split('\0')
+    .map((record) => record.replace(/^\n+/, ''))
+    .filter((record) => record.trim())
+    .map((record) => {
+      const [sha, short, author, date, subject, refs] = record.split('\u001f')
+      return {
+        sha,
+        short,
+        author,
+        date,
+        subject,
+        refs: refs ? refs.split(', ').filter(Boolean) : [],
+      }
+    })
+}
+
+// ── show ───────────────────────────────────────────────────────────────────
+
+/**
+ * `--numstat`: additions, deletions and path per file; `-` means binary.
+ *
+ * Called with `-z`, so records are NUL-separated and a path may contain
+ * anything — including a newline. The `\n` fallback keeps the parser usable on
+ * captured output that was not produced with `-z`.
+ */
+export function parseNumstat(buffer) {
+  const text = buffer.toString('utf8')
+  return text
+    .split(text.includes('\0') ? '\0' : '\n')
+    .filter((line) => line.trim())
+    .map((line) => {
+      const [added, deleted, ...rest] = line.split('\t')
+      let path = rest.join('\t')
+      // A rename shows as `old => new` (or `dir/{old => new}/file`).
+      let originalPath = null
+      const brace = /\{(.*?) => (.*?)\}/.exec(path)
+      if (brace) {
+        originalPath = path.replace(/\{(.*?) => (.*?)\}/, '$1')
+        path = path.replace(/\{(.*?) => (.*?)\}/, '$2')
+      } else if (path.includes(' => ')) {
+        const [from, to] = path.split(' => ')
+        originalPath = from
+        path = to
+      }
+      return {
+        path,
+        originalPath,
+        additions: added === '-' ? null : Number(added),
+        deletions: deleted === '-' ? null : Number(deleted),
+        binary: added === '-' && deleted === '-',
+      }
+    })
+}
+
+// ── the bridge ─────────────────────────────────────────────────────────────
+
+export class GitBridge {
+  #logger
+
+  constructor(logger) {
+    this.#logger = logger
+  }
+
+  /** Answers one reserved call. Throws `GitError` for the router to report. */
+  async handle(method, args = {}) {
+    switch (method) {
+      case GIT_STATUS: return this.#status(args)
+      case GIT_DIFF: return this.#diff(args)
+      case GIT_LOG: return this.#log(args)
+      case GIT_SHOW: return this.#show(args)
+      case GIT_FILE: return this.#file(args)
+      default: throw new GitError('git/bad-request', `未知的 git 调用：${method}`)
+    }
+  }
+
+  async #status(args) {
+    const { directory, root } = await repository(args.cwd)
+    const buffer = await runGit(
+      directory,
+      ['status', '--porcelain=v2', '-z', '--branch', '--untracked-files=all'],
+      { timeoutMs: LIMITS.statusTimeoutMs, maxBytes: LIMITS.statusBytes }
+    )
+    const parsed = parseStatus(buffer)
+    this.#logger?.debug?.(`mobile-link: git status ${root} — ${parsed.files.length} 处改动`)
+    return {
+      root,
+      insideWorkTree: true,
+      hasHead: await headExists(root),
+      branch: parsed.branch,
+      files: parsed.files,
+      truncated: buffer.length >= LIMITS.statusBytes,
+    }
+  }
+
+  async #diff(args) {
+    const { directory, root } = await repository(args.cwd)
+    const path = safePath(args.path)
+    const staged = args.staged === true
+    // An untracked file has no baseline to diff against: `--no-index` against
+    // /dev/null renders it as the pure addition it is. Exit code 1 is "there
+    // were differences", which is the normal answer here.
+    const untracked = await this.#isUntracked(directory, path)
+    const argv = untracked
+      ? ['diff', '--no-color', '--no-index', `--unified=${clampContext(args.context)}`, '--', '/dev/null', path]
+      : ['diff', '--no-color', `--unified=${clampContext(args.context)}`, ...(staged ? ['--cached'] : []), '--', path]
+    const buffer = await runGit(directory, argv, {
+      maxBytes: LIMITS.diffBytes + 1024,
+      okCodes: [0, 1],
+    })
+    const text = buffer.toString('utf8')
+    const binary = /^Binary files .* differ$/m.test(text) || /^GIT binary patch$/m.test(text)
+    return {
+      root,
+      path,
+      staged,
+      untracked,
+      binary,
+      text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+      truncated: !binary && buffer.length > LIMITS.diffBytes,
+    }
+  }
+
+  async #isUntracked(directory, path) {
+    const buffer = await runGit(directory, ['status', '--porcelain=v1', '-z', '--', path], {
+      timeoutMs: LIMITS.statusTimeoutMs,
+    })
+    return buffer.toString('utf8').startsWith('?? ')
+  }
+
+  async #log(args) {
+    const { directory, root } = await repository(args.cwd)
+    if (!(await headExists(root))) {
+      throw new GitError('git/no-commits', '这个仓库还没有任何提交', { root })
+    }
+    const page = Math.min(Math.max(Number(args.limit) || LIMITS.logPage, 1), 50)
+    const skip = Math.max(Number(args.skip) || 0, 0)
+    const buffer = await runGit(
+      directory,
+      ['log', '-z', `--max-count=${page + 1}`, `--skip=${skip}`, `--format=${LOG_FORMAT}`],
+      { maxBytes: LIMITS.logBytes }
+    )
+    const all = parseLog(buffer)
+    const hasMore = all.length > page
+    return { root, commits: all.slice(0, page), hasMore, skip }
+  }
+
+  async #show(args) {
+    const { directory, root } = await repository(args.cwd)
+    const sha = String(args.sha ?? '').trim()
+    if (!/^[0-9a-fA-F]{4,40}$/.test(sha)) {
+      throw new GitError('git/bad-request', '需要一个提交号')
+    }
+    const path = safePath(args.path, { required: false })
+
+    if (path) {
+      const buffer = await runGit(
+        directory,
+        ['show', '--no-color', `--unified=${clampContext(args.context)}`, '--format=', sha, '--', path],
+        { maxBytes: LIMITS.diffBytes + 1024, okCodes: [0, 1] }
+      )
+      const text = buffer.toString('utf8')
+      const binary = /^Binary files .* differ$/m.test(text) || /^GIT binary patch$/m.test(text)
+      return {
+        root,
+        sha,
+        path,
+        binary,
+        text: binary ? '' : text.slice(0, LIMITS.diffBytes),
+        truncated: !binary && buffer.length > LIMITS.diffBytes,
+      }
+    }
+
+    const meta = parseLog(
+      await runGit(directory, ['show', '-s', '-z', `--format=${LOG_FORMAT}`, sha], { okCodes: [0, 1] })
+    )[0] ?? { sha }
+    const files = parseNumstat(
+      await runGit(directory, ['show', '--numstat', '--format=', '-z', sha], {
+        maxBytes: LIMITS.statusBytes,
+        okCodes: [0, 1],
+      })
+    )
+    return { root, commit: meta, files }
+  }
+
+  async #file(args) {
+    const { directory, root } = await repository(args.cwd)
+    const sha = String(args.rev ?? args.sha ?? '').trim()
+    if (!sha || !/^[0-9a-zA-Z._/^~-]{1,80}$/.test(sha)) {
+      throw new GitError('git/bad-request', '需要一个版本号')
+    }
+    const path = safePath(args.path)
+    const size = Number(
+      (await runGit(directory, ['cat-file', '-s', `${sha}:${path}`], { okCodes: [0, 1] }))
+        .toString('utf8')
+        .trim()
+    )
+    if (Number.isFinite(size) && size > LIMITS.fileBytes) {
+      throw new GitError('git/too-large', `这个版本的文件有 ${size} 字节，超过手机上直接打开的上限`, {
+        bytes: size,
+        limit: LIMITS.fileBytes,
+      })
+    }
+    const buffer = await runGit(directory, ['show', `${sha}:${path}`], {
+      maxBytes: LIMITS.fileBytes + 1024,
+      okCodes: [0, 1],
+    })
+    return {
+      root,
+      rev: sha,
+      path,
+      bytes: buffer.length,
+      data: buffer.toString('base64'),
+    }
+  }
+}
+
+function clampContext(value) {
+  const context = Number(value)
+  if (!Number.isFinite(context)) return 3
+  return Math.min(Math.max(Math.trunc(context), 0), 10)
+}

package/lib/hello.js

@@ -44,15 +44,44 @@ function readManifestVersion() {
  * - `qr-pairing`     this connector can render the pairing QR itself
  *                    (`GET /mobile-link/qr`), so the desktop needs no client
  * - `self-enroll`    this connector can register itself with an invite code
+ * - `git`            git status / diff / log / show can be read from the work
+ *                    tree on this computer (see git.js)
  */
 export const SERVER_CAPABILITIES = [
-  'file-transfer', 'events', 'session-streams', 'pair-code', 'qr-pairing', 'self-enroll',
+  'file-transfer', 'events', 'session-streams', 'pair-code', 'qr-pairing', 'self-enroll', 'git',
 ]
 
 export function isHelloMethod(method) {
   return method === HELLO_METHOD
 }
 
+/**
+ * What the phone says it is, out of the handshake arguments.
+ *
+ * The app sends this on every connection — the only place the *client's* build
+ * travels, since the relay's device row is otherwise written once at pairing and
+ * then never again. Older clients send `{}`, which yields nulls: reporting
+ * "unknown" beats reporting a version that may be days old.
+ *
+ * Exported for testing: what it returns ends up in a log line a person will read
+ * when they ask "did that phone update?".
+ */
+export function parseClientInfo(args) {
+  const text = (value) => (typeof value === 'string' && value.trim().length > 0 ? value.trim() : null)
+  const name = text(args?.clientName)
+  const version = text(args?.clientVersion)
+  const build = text(args?.clientBuild)
+  if (!name && !version && !build) return null
+  return {
+    name,
+    version,
+    build,
+    // `DSHMobile 1.0 (20260919.0005)`, skipping whatever is missing.
+    label: [name, version ? `${version}${build ? ` (${build})` : ''}` : build].filter(Boolean).join(' '),
+    at: Date.now(),
+  }
+}
+
 /** The answer to {@link HELLO_METHOD}. */
 export function helloPayload({ protocolVersion, agentId, name } = {}) {
   return {

package/lib/link.js

@@ -10,7 +10,10 @@ import { DshClient } from './dsh-client.js'
 import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { mintPairCode } from './pairing.js'
-import { EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf } from './router.js'
+import {
+  DEFAULT_EVENTS_BACKLOG, DEFAULT_EVENTS_GRACE_MS,
+  EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
+} from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
 import { MissingIdentity, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
@@ -28,12 +31,24 @@ function sleep(ms, signal) {
   })
 }
 
+/** Read a positive number from the environment; anything else falls back. */
+function numberFromEnv(raw, fallback) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
 export class MobileLinkAgent extends EventEmitter {
   constructor({
     relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile,
     logger = console, heartbeatMs = 20000, pongTimeoutMs = 60000, maxBackoffMs = 30000,
     random = Math.random, now = Date.now, dshClient, connectImpl = wsConnect, enabled = true,
     inviteCode, fetchImpl = fetch, env = process.env,
+    // 「手机不在时替它留着 $events 流」的宽限期与缓冲上限（见 router.js 的说明）；
+    // 环境变量给部署用，构造参数给测试用。
+    eventsGraceMs = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_GRACE_MS, DEFAULT_EVENTS_GRACE_MS),
+    eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
+    setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout,
   } = {}) {
     super()
     this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile, inviteCode }
@@ -56,6 +71,10 @@ export class MobileLinkAgent extends EventEmitter {
       logger,
       now,
       protocolVersion: PROTOCOL_VERSION,
+      eventsGraceMs,
+      eventsBacklog,
+      setTimeoutFn,
+      clearTimeoutFn,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
       onChange: () => this.emit('status'),
     })

package/lib/qr.js

@@ -573,4 +573,33 @@ export function qrSvg(text, { scale = 8, quietZone = 4, dark = '#111111', light
     + '</svg>'
 }
 
+/**
+ * The same symbol for a terminal, two matrix rows per line of text.
+ *
+ * Why bother: `enroll` is the one moment a person is already sitting at the
+ * terminal with the phone in hand, and a code printed there can be scanned
+ * straight off the screen — no page to open, no port to look up. Half blocks
+ * ('▀' = top dark, '▄' = bottom dark) keep the symbol roughly square in a
+ * terminal cell, which is twice as tall as it is wide. The quiet zone is the
+ * spec's four modules, not the two this first shipped with: at two, Vision —
+ * the same decoder iOS uses — refused to find the symbol at all.
+ */
+export function qrTerminal(text, { quietZone = 4, margin = '  ' } = {}) {
+  const matrix = qrMatrix(text)
+  const size = matrix.length
+  const blank = (row) => row < 0 || row >= size
+  const dark = (row, column) => !blank(row) && column >= 0 && column < size && matrix[row][column]
+  const lines = []
+  for (let row = -quietZone; row < size + quietZone; row += 2) {
+    let line = margin
+    for (let column = -quietZone; column < size + quietZone; column += 1) {
+      const top = dark(row, column)
+      const bottom = dark(row + 1, column)
+      line += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' '
+    }
+    lines.push(line)
+  }
+  return lines.join('\n')
+}
+
 export { TOTAL_CODEWORDS }

package/lib/router.js

@@ -13,11 +13,39 @@ import {
   StreamTable, WaterfallDedupe, deviceFrameError, deviceIdOf, nonEmptyString, resultFrame,
 } from './dlp.js'
 import { FileInbox, isFileMethod } from './files.js'
-import { isHelloMethod, helloPayload } from './hello.js'
+import { GitBridge, isGitMethod } from './git.js'
+import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 
 export const EVENTS_ENDPOINT = '$events'
 export const EVENTS_RESULT = '$events/result'
 
+/**
+ * 手机断了之后，这条 `$events` 流还替它留多久（毫秒）。
+ *
+ * 为什么需要：手机是唯一客户端时，它一断，DSH 那边就没人持有这条流了——
+ * 提问（waterfall）会随 Agent Context 释放被撤掉，用户回到手机再也看不到
+ * （根因见 maintainers/PENDING-WATERFALL-LOSS.md）。留着流就等于"代手机值班"：
+ * 这期间来的提问先攒着，手机回来补发。
+ *
+ * 代价是这段时间里 DSH 认为"设备还在"，会话的 Agent Context 不会因此释放；
+ * 所以必须有上限，不能无限留。
+ */
+export const DEFAULT_EVENTS_GRACE_MS = 15 * 60 * 1000
+
+/** 离线期间最多替一台设备攒多少条 `$events` 项（只攒 waterfall/cancel）。 */
+export const DEFAULT_EVENTS_BACKLOG = 50
+
+/**
+ * 手机不在时要攒下来的 `$events` 项：只有"待回答的提问"和"提问作废"两种。
+ *
+ * 别的一律不攒——emit 类的都是"某事刚发生"的通知，几分钟后补发只会让 App
+ * 对着旧事件发通知（例如一条早就结束的 turn）。
+ */
+export function isBufferedEvent(value) {
+  if (!value || typeof value !== 'object') return false
+  return value.type === 'waterfall' || value.type === 'cancel'
+}
+
 export function messageOf(error) {
   return error instanceof Error ? error.message : String(error)
 }
@@ -33,8 +61,16 @@ export class DeviceRouter {
    * @param {(deviceId: string, frame: object) => boolean} options.send  deliver one frame to one device
    * @param {() => void} [options.onChange]    called whenever the status snapshot changes
    */
-  constructor({ dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1 } = {}) {
+  constructor({
+    dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
+    eventsGraceMs = DEFAULT_EVENTS_GRACE_MS, eventsBacklog = DEFAULT_EVENTS_BACKLOG,
+    setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout,
+  } = {}) {
     this.dsh = dsh
+    this.eventsGraceMs = eventsGraceMs
+    this.eventsBacklog = eventsBacklog
+    this.setTimeoutFn = setTimeoutFn
+    this.clearTimeoutFn = clearTimeoutFn
     // Reported to the app so it can tell which wire revision it is talking to.
     this.protocolVersion = protocolVersion
     this.send = send
@@ -46,6 +82,7 @@ export class DeviceRouter {
     this.dedupe = new WaterfallDedupe({ now })
     this.lastError = undefined
     this.fileInbox = new FileInbox(logger)
+    this.git = new GitBridge(logger)
   }
 
   #changed() {
@@ -98,7 +135,20 @@ export class DeviceRouter {
   // ── device lifecycle ────────────────────────────────────────────────────
 
   async attachDevice(deviceId, info = {}) {
-    if (!nonEmptyString(deviceId) || this.devices.has(deviceId)) return
+    if (!nonEmptyString(deviceId)) return
+    const existing = this.devices.get(deviceId)
+    if (existing) {
+      // 回头客：宽限期内又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
+      if (existing.offlineSince !== undefined) {
+        this.clearTimeoutFn(existing.offlineTimer)
+        existing.offlineTimer = undefined
+        existing.offlineSince = undefined
+        this.logger.info?.(
+          `mobile-link: device ${deviceId} reattached with ${existing.eventsPending.size} unanswered question(s)`)
+        this.#changed()
+      }
+      return
+    }
     this.devices.set(deviceId, {
       deviceId,
       name: info?.name,
@@ -108,6 +158,13 @@ export class DeviceRouter {
       readyValue: undefined,
       eventsMuxId: undefined,
       dlpIds: new Set(),
+      // 手机不在时的"值班"状态：offlineSince 有值 = 这条流在替它留着；
+      // eventsPending 是**还没被回答**的提问（按 eventId 存）。
+      // 注意它不是一个"送一次就清空"的队列：送过也要留着，否则 App 再重启一次
+      // （或崩一次）这条提问就永远丢了——2026-09-22 验收时正是这么发现的。
+      offlineSince: undefined,
+      offlineTimer: undefined,
+      eventsPending: new Map(),
     })
     this.logger.info?.(`mobile-link: device ${deviceId} attached (${info?.name ?? 'unknown'})`)
     this.#changed()
@@ -117,9 +174,42 @@ export class DeviceRouter {
   async detachDevice(deviceId, reason) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 除了 `$events`，其它流（文件、会话流）立刻撤掉：它们没有"值班"的意义，
+    // 留着只会占资源。`$events` 留着，见 DEFAULT_EVENTS_GRACE_MS 的说明。
+    const keep = []
+    for (const entry of this.streams.byDevice(deviceId)) {
+      if (entry.endpoint === EVENTS_ENDPOINT) {
+        keep.push(entry)
+        continue
+      }
+      this.streams.removeByMux(entry.muxId)
+      this.dsh.cancelStream(entry.muxId)
+    }
+    record.dlpIds.clear()
+    for (const entry of keep) record.dlpIds.add(entry.dlpId)
+
+    if (record.offlineSince === undefined) {
+      record.offlineSince = this.now()
+      record.offlineTimer = this.setTimeoutFn(() => {
+        void this.#expireOfflineDevice(deviceId)
+      }, this.eventsGraceMs)
+      // 定时器不该把进程钉住（CLI 与测试里尤其明显）。
+      record.offlineTimer?.unref?.()
+    }
+    this.logger.info?.(
+      `mobile-link: device ${deviceId} detached (${reason ?? 'closed'})；`
+      + `$events 流替它留 ${Math.round(this.eventsGraceMs / 1000)} 秒，期间来的提问会攒着`)
+    this.#changed()
+  }
+
+  /** 宽限期到点：真的把这台设备放下（撤流、清缓冲）。 */
+  async #expireOfflineDevice(deviceId) {
+    const record = this.devices.get(deviceId)
+    if (!record || record.offlineSince === undefined) return
     for (const muxId of this.streams.removeDevice(deviceId)) this.dsh.cancelStream(muxId)
     this.devices.delete(deviceId)
-    this.logger.info?.(`mobile-link: device ${deviceId} detached (${reason ?? 'closed'})`)
+    this.logger.info?.(
+      `mobile-link: device ${deviceId} 宽限期结束，已放下（丢掉 ${record.eventsPending.size} 条没人回答的提问）`)
     this.#changed()
   }
 
@@ -146,6 +236,8 @@ export class DeviceRouter {
   teardownAll() {
     const muxIds = []
     for (const deviceId of [...this.devices.keys()]) {
+      const record = this.devices.get(deviceId)
+      this.clearTimeoutFn(record?.offlineTimer)
       muxIds.push(...this.streams.removeDevice(deviceId))
       this.devices.delete(deviceId)
     }
@@ -162,6 +254,23 @@ export class DeviceRouter {
     // What this connector is and can do. Answered here for the same reason as
     // the file calls: the HTTP status route exists only on the direct path.
     if (isHelloMethod(frame.method)) {
+      // Recorded before answering: this is the only frame in which the phone
+      // says which build it is, and the relay cannot see it from the pairing
+      // row it keeps.
+      const client = parseClientInfo(frame.args)
+      if (client) {
+        const record = this.devices.get(deviceId)
+        if (record) record.client = client
+        if (record?.client?.build !== client.build || record?.clientLogged !== client.build) {
+          if (record) record.clientLogged = client.build
+          // One line per build per connection: enough to answer "did they
+          // update?" from a log, without a line per reconnect.
+          this.logger?.info?.(
+            `mobile-link: device ${deviceId} is ${client.label}` +
+            `${record?.name ? ` (${record.name})` : ''}`
+          )
+        }
+      }
       const value = helloPayload({
         protocolVersion: this.protocolVersion,
         agentId: this.identity?.agentId,
@@ -182,6 +291,24 @@ export class DeviceRouter {
       return
     }
 
+    // Git also runs here, on the machine that holds the work tree: the Host has
+    // no endpoint that runs a command, and the review a person wants — what
+    // changed, what the diff says, what the last commits were — is all local.
+    // Read-only; see git.js for the command whitelist.
+    if (isGitMethod(frame.method)) {
+      let result
+      try {
+        result = { ok: true, value: await this.git.handle(frame.method, frame.args ?? {}) }
+      } catch (error) {
+        result = {
+          ok: false,
+          error: errorObject(error?.code ?? 'git/failed', messageOf(error), error?.details ?? {}),
+        }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     let result
     try {
       result = await this.dsh.rpc(frame.method, frame.args ?? {})
@@ -216,6 +343,17 @@ export class DeviceRouter {
       if (record.readyValue !== undefined) {
         this.send(deviceId, { t: 'item', id: frame.id, value: record.readyValue })
       }
+      // 还没被回答的提问在这里补发：ready 已经发过，所以 App 拿得到 clientId，
+      // 补发的提问是可以被回答的。**送出去不清空**——App 可能又崩/又重启，
+      // 只要还没人回答，下次连上还得再给一遍（App 侧按 eventId 去重）。
+      if (record.eventsPending.size > 0) {
+        const pending = [...record.eventsPending.values()]
+        this.logger.info?.(
+          `mobile-link: replaying ${pending.length} unanswered question(s) to ${deviceId}`)
+        for (const value of pending) {
+          this.send(deviceId, { t: 'item', id: frame.id, value })
+        }
+      }
       return
     }
     const muxId = `s:${deviceId}:${frame.id}`
@@ -265,6 +403,8 @@ export class DeviceRouter {
       })
       return
     }
+    // 答过了就不再是"待答"：删掉它，免得下次重连又把已经回答过的问题推给 App。
+    record.eventsPending.delete(eventId)
     // The clientId is always the one from *this device's* $events ready frame
     // (spec §4.1.5); any clientId the device echoed is ignored on purpose.
     if (!this.dedupe.claim(eventId)) return
@@ -302,6 +442,27 @@ export class DeviceRouter {
   forwardEvent(deviceId, value) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 只有"待回答的提问"值得留：别的都是"某事刚发生"的通知，补发只会让 App
+    // 对着几分钟前的事件发通知（例如一条早就结束的 turn）。
+    // 待答表：不管手机在不在都记下来，直到**有人回答**或 host 作废它。
+    // 只记在线时的转发是不够的——App 收下提问后崩一次/重启一次，那条提问就再也没人
+    // 记得了（host 认为已经投给这条流了，不会重发）。连接器记着，重连时再给一遍。
+    if (nonEmptyString(value?.eventId)) {
+      if (value.type === 'cancel') record.eventsPending.delete(value.eventId)
+      else if (value.type === 'waterfall') {
+        record.eventsPending.set(value.eventId, value)
+        if (record.eventsPending.size > this.eventsBacklog) {
+          // 超上限时丢最老的（Map 保持插入顺序）。
+          const oldest = record.eventsPending.keys().next().value
+          record.eventsPending.delete(oldest)
+        }
+      }
+    }
+    if (record.offlineSince !== undefined && isBufferedEvent(value)) {
+      this.logger.debug?.(
+        `mobile-link: kept ${value.type} ${value.event ?? value.eventId ?? ''} for offline ${deviceId}`)
+      return
+    }
     if (value && value.type === 'ready' && nonEmptyString(value.clientId)) {
       record.clientId = value.clientId
       record.readyValue = value
@@ -371,7 +532,11 @@ export class DeviceRouter {
       deviceId: record.deviceId,
       name: record.name,
       model: record.model,
+      // Which build that phone reported on its last handshake.
+      client: record.client ?? null,
       connectedAt: record.connectedAt,
+      offlineSince: record.offlineSince ?? null,
+      unansweredEvents: record.eventsPending.size,
       eventsReady: Boolean(record.clientId),
       openStreams: record.dlpIds.size,
     }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Put your PC's DeepSeek Harness in your pocket: dials a relay over WSS so the native iOS client reaches this machine even without a public IP.",
   "keywords": [
     "dsh",