dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/shared/workspace-guard.js

@@ -0,0 +1,127 @@
+'use strict'
+
+// 空清单守卫（工作区 / 会话列表共用）。
+//
+// 「没取到」与「真的什么都没有」在单份快照上长得一模一样：都是
+// `{ ok: true, items: [] }`。因此读取侧必须**如实报错**（见 lib/mobile/workspaces.js
+// 的 `host-workspace-list-degraded` 与 lib/mobile/sessions.js 的
+// `host-session-list-degraded`），守卫则负责兜住「宿主确实回了合法空列表」这种情况
+// ——它和真实删除无法区分，所以按时间兜底。
+//
+// 后果（真机缺陷）：一份空快照会一路通过推送路径的 `.ok` 判定，被当成权威清单推给
+// 中转冻结下来。中转只在响应上附一个 `stale` 标记，而 App 根本不读它，于是下一次 15s
+// 轮询就把好数据覆盖成空 —— 侧边栏工作区整行消失、其下所有会话塌进「未分组」，
+// 设备仍显示「在线」（那是另一条独立的 /status 探测线），点不开，且全程零错误提示。
+//
+// 「用户真的把工作区/会话全删了」同样表现为空列表，单看一份快照区分不了，所以按时间兜底：
+// 距上一次确认过的非空清单还不到 graceMs 时拒绝空清单、保留上一份镜像；超过 graceMs
+// 则放行，让真实删除也能收敛，不会把侧边栏永久钉死在旧数据上。
+//
+// 抽成独立模块是为了能被真正单测（早期版本把这段逻辑内联在 lib/index.js 的闭包里，
+// 只能靠 grep 源码做契约测试，行为本身一次都跑不到）。
+
+const fs = require('node:fs')
+
+/** 空清单宽限：距上一次非空清单不到这么久，就不承认「被清空」。 */
+const EMPTY_LIST_GRACE_MS = 15000
+const EMPTY_WORKSPACE_GRACE_MS = EMPTY_LIST_GRACE_MS
+const EMPTY_SESSION_LIST_GRACE_MS = EMPTY_LIST_GRACE_MS
+
+/** 读回上次进程留下的非空基准；文件不存在/损坏都按「没有基准」处理。 */
+function readPersistedBaseline(persistPath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(persistPath, 'utf8'))
+    const value = Number(raw && raw.lastNonEmptyAt)
+    return Number.isFinite(value) && value > 0 ? value : 0
+  } catch {
+    return 0
+  }
+}
+
+/** 持久化非空基准。插件会随桌面 harness 频繁重启，基准只存在内存里的话，
+ *  重启后的第一份空快照（往往正好撞上桌面刚起来的忙乱期）会畅通无阻。 */
+function persistBaseline(persistPath, lastNonEmptyAt) {
+  if (!persistPath) return
+  try {
+    fs.writeFileSync(persistPath, JSON.stringify({ lastNonEmptyAt }), 'utf8')
+  } catch {
+    // 落盘只是加固，失败不影响本次判定。
+  }
+}
+
+/**
+ * 造一个空清单守卫（`{ ok:true, items:[...] }` 形状的快照）。
+ *
+ * @param {object} [options]
+ * @param {string} [options.label] 阻断理由里的清单名称，默认「列表」
+ * @param {string} [options.persistPath] 基准落盘路径（可选，单槽位一个文件）
+ * @param {number} [options.graceMs] 宽限窗口，默认 EMPTY_LIST_GRACE_MS
+ * @param {() => number} [options.now] 时钟，测试可注入
+ * @returns {{ check: (body: unknown) => string|null, peek: () => { lastNonEmptyAt: number } }}
+ *   `check` 返回 null 表示这份快照可用；否则返回阻断理由（可直接喂给 recordMirrorPush）。
+ */
+function createEmptyListGuard(options) {
+  const label = (options && typeof options.label === 'string' && options.label) ? options.label : '列表'
+  const graceMs = options && Number.isFinite(options.graceMs)
+    ? Number(options.graceMs)
+    : EMPTY_LIST_GRACE_MS
+  const now = (options && typeof options.now === 'function') ? options.now : Date.now
+  const persistPath = (options && typeof options.persistPath === 'string') ? options.persistPath : ''
+  let lastNonEmptyAt = persistPath ? readPersistedBaseline(persistPath) : 0
+
+  return {
+    check(body) {
+      if (!body || typeof body !== 'object' || body.ok !== true) {
+        return `${label} 快照不可用，本次未推送`
+      }
+      const count = Array.isArray(body.items) ? body.items.length : 0
+      if (count > 0) {
+        lastNonEmptyAt = now()
+        persistBaseline(persistPath, lastNonEmptyAt)
+        return null
+      }
+      // 显式空态（`emptyConfirmed: true`）：读取侧已经断言「上游回了一份合法且为空的
+      // 清单」——形状异常会走错误通道（见 sessions/workspaces 的 build*Body），能带上这个
+      // 标记就说明这不是「没取到」。此时不该再被时间窗挡住：用户真的把侧栏清空时，时间
+      // 窗正好是「手机侧永远看不到清空」的来源。时间兜底只留给没有这个标记的旧快照。
+      if (body.emptyConfirmed === true) {
+        if (lastNonEmptyAt) {
+          lastNonEmptyAt = 0
+          persistBaseline(persistPath, 0)
+        }
+        return null
+      }
+      if (lastNonEmptyAt && now() - lastNonEmptyAt < graceMs) {
+        return `${label}快照为空且距上次非空清单不足 ${graceMs / 1000}s，本次未推送`
+          + `（防止把「没取到」广播成「你没有${label}」）`
+      }
+      // 从来没有过非空清单（本来就没有），或已经空过整个宽限窗口（真的删光了）：
+      // 两种都认下来。放行后清基准，否则后续空快照会被同一基准一直挡着。
+      if (lastNonEmptyAt) {
+        lastNonEmptyAt = 0
+        persistBaseline(persistPath, 0)
+      }
+      return null
+    },
+    peek() {
+      return { lastNonEmptyAt }
+    },
+  }
+}
+
+function createWorkspaceGuard(options) {
+  return createEmptyListGuard({ ...(options || {}), label: '工作区' })
+}
+
+function createSessionListGuard(options) {
+  return createEmptyListGuard({ ...(options || {}), label: '会话' })
+}
+
+module.exports = {
+  EMPTY_LIST_GRACE_MS,
+  EMPTY_WORKSPACE_GRACE_MS,
+  EMPTY_SESSION_LIST_GRACE_MS,
+  createEmptyListGuard,
+  createWorkspaceGuard,
+  createSessionListGuard,
+}

package/lib/sidecar-facade-worker.cjs

@@ -0,0 +1,353 @@
+'use strict'
+
+/**
+ * sidecar worker：真正持有「中转隧道 + 局域网代理」的那个子进程。
+ *
+ * 宿主不自己开 WebSocket、也不自己监听局域网端口，而是 fork 出这个 worker，用环回
+ * HTTP + Bearer 令牌对话（见 lib/sidecar-facade.cjs）。这样隧道崩了、原生模块加载
+ * 失败都只死一个子进程，宿主仍能如实把状态报给 /api/relay/status。
+ *
+ * 三条不能忘的语义：
+ *  1. 状态既要在 `/status` 上按需可查，也要在**变化的那一刻**主动 `process.send` 给宿主
+ *     （publishState）：宿主的健康轮询是 10s 一次，只靠轮询的话隧道真断后它最多 10s
+ *     仍以为连着、继续往一条死隧道推镜像；而「断又连」整段落在两次轮询之间时，宿主
+ *     连一次「刚连上」都观测不到，那次全量补推就永远不来。
+ *  2. `/tunnel/send` 先把镜像快照留在本地（localSnapshot）再尝试真发：局域网直连的手机
+ *     走 snapshotRead 读这份快照，隧道断了也不至于读到一份过期镜像。
+ *  3. 请求体一律先量后读（readBody + 显式上限）：`/configure` 与镜像帧都有字节上限，
+ *     超限立刻 413，别让一个畸形请求把内存吃光。
+ */
+
+const http = require('node:http')
+const { RelayTunnel } = require('./relay/tunnel.js')
+const { T } = require('./relay/protocol.js')
+const { createLanProxy } = require('./relay/lan-proxy.js')
+const { lanUrls } = require('./relay/lan-network.cjs')
+const core = require('./relay/core.js')
+const { createReconnectScheduler } = require('./reconnect-scheduler.cjs')
+const { isMirrorSnapshotFresh } = require('./mirror-snapshot.cjs')
+
+const parentPort = Number(process.env.DSH_SIDECAR_PARENT_PORT)
+const token = process.env.DSH_SIDECAR_TOKEN
+const authorization = `Bearer ${token}`
+let config = {}
+const sockets = new Set()
+let tunnel = null
+let lan = null
+let tunnelState = 'off'
+let tunnelError = null
+let lanState = 'off'
+let lanError = null
+// 局域网代理**实际**在监听的端口。0 = 还没起来。首选端口被占时会退到内核分配的
+// 空闲端口（见 lib/relay/port-allocator.cjs 与 lan-proxy 的 bind 兜底），所以凡是要
+// 对外报地址的地方都必须用 lanUrlPort()，不能用 config.lanPort。
+let lanBoundPort = 0
+function lanUrlPort() { return lanBoundPort || config.lanPort }
+/**
+ * 隧道/局域网状态一变就**立刻**经 IPC 推给宿主，别等宿主那 10s 一次的健康轮询。
+ *
+ * 轮询仍然是权威（只有它能发现「worker 整个死了」——那时 IPC 也断了，没人会推），
+ * 但它是滞后的：隧道真断之后宿主最多 10s 仍认为已连接，期间照常推镜像，每次撞
+ * sidecar-facade 的 5s 超时，该会话的单飞门被占住，事件只能合并成一次补推。反过来，
+ * 隧道「断又连」若整段落在两次轮询之间，宿主看不到跳变，onTunnelUp 那次全量补推会被漏掉。
+ *
+ * 所以：轮询继续做权威兜底，状态跳变由这里即时上报（见 lib/sidecar-lifecycle.cjs 的
+ * applyTunnelState —— 两条来源共用一个边沿判定，不会重复触发补推）。
+ */
+function publishState() {
+  process.send?.({
+    type: 'state',
+    tunnel: { state: tunnelState, error: tunnelError },
+    lan: { enabled: Boolean(config.lanEnabled), port: lanUrlPort(), requestedPort: config.lanPort, state: lanState, error: lanError },
+  })
+}
+let networkTimer = null
+let configuring = Promise.resolve()
+let localSnapshot = null // 桌面 pushSync 推来的移动端镜像快照（本机保留供读取隔离）
+const NETWORK_POLL_MS = 5000
+// 隧道重连间隔。onClose 与 start().catch 两条失败路径共用这个幂等调度器，
+// 否则每次失败会排两个定时器（重连风暴）；幂等性由
+// test/reconnect-scheduler.test.cjs 精确验证。
+const RECONNECT_DELAY_MS = 5000
+const reconnect = createReconnectScheduler({ delayMs: RECONNECT_DELAY_MS, onFire: () => startTunnel() })
+
+function send(res, code, value) {
+  if (res.headersSent) return res.end()
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(value))
+}
+function authorized(req) { return typeof token === 'string' && token.length >= 64 && req.headers.authorization === authorization }
+// 请求体超限要能和外层异常区分开：它是请求本身的问题（4xx），不是服务不可用。
+// 旧实现在这里一律 reject(new Error('request too large'))，最后被 catch-all 兜成 503，
+// 宿主侧记下来的就是一条没头没尾的「sidecar facade request failed: 503」。
+class BodyTooLarge extends Error {}
+/** /tunnel/send 的请求体上限。
+ *
+ * 这个接口收的是桌面推给移动端的镜像：整份会话列表 + 工作区 + 当前会话的完整消息、
+ * 统计与模型。实测桌面一次推送就超过 1MB，而中转清洗后真正留下的只有 ~114KB——
+ * 旧的 1MB 上限是在把有用的东西挡在门外。
+ *
+ * 上限的依据是**中转那侧的帧上限**，不是「估个够大的数」：
+ * dsh-mobile-server/lib/config.js 的 MAX_FRAME_BYTES 默认 8MB，一帧超过它，
+ * 中转会以 1009 'frame too large' 直接关掉隧道（lib/protocol.js → onError）。
+ * 丢一次镜像可以恢复，隧道被关掉要等重连、期间手机端全瞎——所以宁可拒也不能赌。
+ * 留 64KB 余量给帧头。推得再大也只是这一次 413，隧道安然无恙。
+ */
+const TUNNEL_SEND_MAX_BODY = 8 * 1024 * 1024 - 64 * 1024
+// /configure 只送 relay.json 那几十个字段，给 64KB 绰绰有余；放宽只会让误用更难发现。
+const CONFIGURE_MAX_BODY = 64 * 1024
+function readBody(req, limit) {
+  return new Promise((resolve, reject) => {
+    let raw = ''
+    let size = 0
+    let over = false
+    req.on('data', chunk => {
+      if (over) return
+      size += chunk.length
+      if (size > limit) {
+        // 关键：拒了之后必须停止累积。旧实现在 reject 之后继续往 raw 上拼，
+        // 一个已被判定超限的请求照样把整个 body 读进内存——上限反倒成了放大器。
+        over = true
+        raw = ''
+        return reject(new BodyTooLarge(`request body too large (${size} > ${limit} bytes)`))
+      }
+      raw += chunk
+    })
+    req.on('end', () => { if (over) return; try { resolve(JSON.parse(raw || '{}')) } catch (error) { reject(error) } })
+    req.on('error', reject)
+  })
+}
+function parentRequest(path, body, signal) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port: parentPort, path, method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, timeout: 10000 }, resolve)
+    req.on('error', reject)
+    signal?.addEventListener('abort', () => req.destroy(), { once: true })
+    req.end(JSON.stringify(body))
+  })
+}
+async function parentJson(path, body, signal) {
+  const res = await parentRequest(path, body, signal)
+  let raw = ''; res.setEncoding('utf8'); for await (const chunk of res) raw += chunk
+  let value; try { value = JSON.parse(raw || '{}') } catch { throw new Error('invalid parent RPC response') }
+  if (res.statusCode !== 200) throw new Error(value.error?.message || value.error || `parent RPC failed: ${res.statusCode}`)
+  return value.data ?? value
+}
+function upstream() { return `http://127.0.0.1:${config.upstreamPort}` }
+// 读取隔离：把移动端高频读请求（sessions/workspaces/messages/stats）从本地快照直接回，
+// 不再打扰主进程。快照缺失或路径不在清单内时返回 null → 调用方回源主进程。
+function snapshotRead(info) {
+  // 镜像只在中转连着时才会有新版本推来（原因见 mirror-snapshot.cjs 的说明）：冻结的快照必须
+  // 回源主进程，否则中转一断、局域网仍健康时，新建的会话/工作区在 App 里永远不出现。
+  if (!isMirrorSnapshotFresh(localSnapshot)) return null
+  let url
+  try { url = new URL(String((info && info.path) || ''), 'http://127.0.0.1') } catch { return null }
+  const pathname = url.pathname
+  const body =
+    pathname === '/api/mobile/v1/sessions' ? localSnapshot.sessions
+    : pathname === '/api/mobile/v1/workspaces' ? localSnapshot.workspaces
+    : pathname === '/api/mobile/v1/session/messages' ? (localSnapshot.messages || {})[url.searchParams.get('sessionId') || '']
+    : pathname === '/api/mobile/v1/session/stats' ? (localSnapshot.stats || {})[url.searchParams.get('sessionId') || '']
+    : null
+  if (!body || typeof body !== 'object' || body.ok !== true) return null
+  if (pathname === '/api/mobile/v1/session/messages') {
+    const afterSeqRaw = url.searchParams.get('afterSeq')
+    if (afterSeqRaw !== null && afterSeqRaw !== '' && /^\d+$/.test(afterSeqRaw)) {
+      const after = Number(afterSeqRaw)
+      const items = Array.isArray(body.items) ? body.items.filter((it) => (typeof it?.seq === 'number' ? it.seq > after : true)) : body.items
+      const lastSeq = items && items.length ? Math.max(...items.map((it) => it?.seq || 0)) : after
+      return { ...body, items, lastSeq }
+    }
+  }
+  return body
+}
+function stopNetworkMonitor() {
+  if (networkTimer) { clearInterval(networkTimer); networkTimer = null }
+}
+function scheduleReconnect() { reconnect.schedule() }
+function stopTunnel() {
+  reconnect.cancel()
+  if (tunnel) tunnel.stop()
+  tunnel = null; tunnelState = 'off'; tunnelError = null
+  publishState()
+}
+function startNetworkMonitor() {
+  stopNetworkMonitor()
+  if (!config.enabled || !config.relayUrl || !config.lanEnabled) return
+  let previous = lanUrls(lanUrlPort())
+  networkTimer = setInterval(() => {
+    const current = lanUrls(lanUrlPort())
+    if (JSON.stringify(current) === JSON.stringify(previous)) return
+    previous = current
+    // lanUrls is sent during register; reconnect only after a real change.
+    startTunnel()
+  }, NETWORK_POLL_MS)
+}
+function stopLan() {
+  if (lan) lan.stop()
+  lan = null; lanState = 'off'; lanError = null; lanBoundPort = 0
+  publishState()
+}
+async function stopServices() { stopNetworkMonitor(); stopTunnel(); stopLan() }
+function startTunnel() {
+  if (!config.enabled || !config.relayUrl || !config.upstreamPort) return
+  stopTunnel(); tunnelState = 'connecting'
+  publishState()
+  const current = new RelayTunnel({
+    relayUrl: core.tunnelWsUrl(config.relayUrl), instanceId: config.instanceId, pairingCode: config.pairingCode,
+    name: config.name, upstream: upstream(),
+    registerSecret: config.registerSecret,
+    lanUrls: config.lanEnabled ? lanUrls(lanUrlPort()) : [],
+    readSnapshot: snapshotRead,
+    // 实例身份守卫：只有还活着的那个隧道实例才许改状态。onClose / onPairRequest /
+    // start().catch 都有这道闸，只有 onRegistered 漏了——而它恰恰是最容易迟到的一个
+    // （注册帧是在 ws 上异步回来的）。漏掉的后果是：configure() 或网络监视器重建隧道后，
+    // 旧实例迟到的 registered 帧把 tunnelState 写成 'connected'，可此刻 tunnel 指向的
+    // 是新实例、它的 ws 还停在 CONNECTING。于是 /status 报「已连接」、宿主据此放行镜像
+    // 推送，worker 却按真值回 503，镜像一条也发不出去（现场：host.log 里
+    // 「bg queue: sidecar facade request failed: 503」刷屏，而隧道其实在正常转发会话）。
+    onRegistered: () => { if (tunnel !== current) return; tunnelState = 'connected'; tunnelError = null; publishState() },
+    onClose: () => { if (tunnel === current && config.enabled) { tunnelState = 'error'; tunnelError = '连接断开'; publishState(); scheduleReconnect() } },
+    onPairRequest: async (message) => {
+      try {
+        const result = await parentJson('/api/relay/internal/approval', { device: message.device || {} })
+        if (tunnel !== current) return
+        if (result.approved) current.sendPairConfirm(message.requestId, true, core.signLanToken(config.lanSecret, config.instanceId, core.MOBILE_BEARER_TTL_SEC))
+        else current.sendPairConfirm(message.requestId, false)
+      } catch { if (tunnel === current) current.sendPairConfirm(message.requestId, false) }
+    },
+    onLog: (...args) => process.stderr.write(`[dsh-ai-hub sidecar] ${args.join(' ')}\n`),
+  })
+  tunnel = current
+  current.start().catch(error => { if (tunnel === current) { tunnelState = 'error'; tunnelError = error instanceof Error ? error.message : String(error); publishState(); scheduleReconnect() } })
+}
+function startLan() {
+  // 总开关关闭时不能只停隧道：旧实现漏了 `config.enabled`，于是 /api/relay/toggle
+  // 关掉远程连接后，局域网代理仍监听 0.0.0.0:lanPort 继续接受配对。
+  if (!config.enabled || !config.lanEnabled || !config.upstreamPort) return
+  stopLan(); lanState = 'connecting'
+  publishState()
+  const current = createLanProxy({
+    lanPort: config.lanPort, pairingCode: config.pairingCode, instanceId: config.instanceId, lanSecret: config.lanSecret,
+    upstreamPort: config.upstreamPort,
+    readSnapshot: snapshotRead,
+    onLog: (...args) => process.stderr.write(`[dsh-ai-hub sidecar] ${args.join(' ')}\n`),
+    onApprove: async (device) => {
+      try {
+        const result = await parentJson('/api/relay/internal/approval', { device: device || {} })
+        return { approved: Boolean(result.approved), token: result.approved ? core.signLanToken(config.lanSecret, config.instanceId, core.MOBILE_BEARER_TTL_SEC) : null }
+      } catch { return { approved: false, token: null } }
+    },
+  })
+  lan = current
+  current.start().then(() => {
+    if (lan !== current) return
+    lanState = 'listening'
+    const bound = typeof current.port === 'function' ? current.port() : 0
+    const changed = bound > 0 && bound !== lanBoundPort
+    if (bound > 0) lanBoundPort = bound
+    publishState()
+    // 实际端口和首选端口不同时，中转侧那份 lanUrls（注册时随 metadata 上报的）
+    // 带的就是首选端口，手机从公网拿到的局域网候选全是死地址。重连一次隧道，让
+    // 中转拿到真正的端口。
+    if (changed && config.enabled && config.relayUrl) startTunnel()
+  }).catch(error => { if (lan === current) { lanState = 'error'; lanError = error instanceof Error ? error.message : String(error); publishState() } })
+}
+async function configure(next) {
+  if (!next || typeof next !== 'object' || Array.isArray(next)) throw new Error('invalid configuration')
+  const allowed = ['enabled', 'relayUrl', 'instanceId', 'pairingCode', 'name', 'upstreamPort', 'lanPort', 'lanEnabled', 'lanSecret', 'registerSecret']
+  if (Object.keys(next).some(key => !allowed.includes(key))) throw new Error('unknown configuration field')
+  if (typeof next.instanceId !== 'string' || next.instanceId.length > 128) throw new Error('invalid instanceId')
+  if (typeof next.pairingCode !== 'string' || !/^\d{6}$/.test(next.pairingCode)) throw new Error('invalid pairingCode')
+  if (typeof next.upstreamPort !== 'number' || !Number.isInteger(next.upstreamPort) || next.upstreamPort < 1 || next.upstreamPort > 65535) throw new Error('invalid upstreamPort')
+  if (next.lanPort !== undefined && (!Number.isInteger(next.lanPort) || next.lanPort < 1024 || next.lanPort > 65535)) throw new Error('invalid lanPort')
+  if (next.registerSecret !== undefined && (typeof next.registerSecret !== 'string' || next.registerSecret.length > 512)) throw new Error('invalid registerSecret')
+  await stopServices()
+  config = { ...next }
+  if (config.enabled) {
+    startTunnel()
+    startNetworkMonitor()
+    if (config.lanEnabled) startLan()
+  }
+  return status()
+}
+function status() {
+  return { ok: true, sidecar: true, enabled: Boolean(config.enabled), relayUrl: config.relayUrl || '', instanceId: config.instanceId, name: config.name, localPort: config.upstreamPort, tunnel: { state: tunnelState, error: tunnelError }, lan: { enabled: Boolean(config.lanEnabled), port: lanUrlPort(), requestedPort: config.lanPort, state: lanState, error: lanError } }
+}
+const server = http.createServer(async (req, res) => {
+  try {
+    if (!authorized(req)) return send(res, 401, { ok: false, error: 'unauthorized' })
+    if (req.method === 'GET' && req.url === '/health') return send(res, 200, { ok: true, service: 'dsh-ai-hub-relay-sidecar', capabilities: ['relay-tunnel', 'lan-proxy', 'pairing-approval-rpc'] })
+    if (req.method === 'GET' && req.url === '/status') return send(res, 200, status())
+    if (req.method === 'POST' && req.url === '/configure') { const next = await readBody(req, CONFIGURE_MAX_BODY); configuring = configuring.then(() => configure(next)); return send(res, 200, await configuring) }
+    if (req.method === 'POST' && req.url === '/tunnel/send') {
+      const body = await readBody(req, TUNNEL_SEND_MAX_BODY);
+      // 桌面→relay 主动推送（移动端镜像缓存）：复用隧道立即 sendJson；同时在本地保留快照供读取隔离。
+      if (body && typeof body === 'object' && body.kind === 'sync') localSnapshot = body;
+      if (tunnel && tunnel.connected) {
+        tunnel.sendJson(T.sync, 0, body && typeof body === 'object' ? body : { kind: 'raw', data: body });
+        return send(res, 202, { ok: true });
+      }
+      return send(res, 503, { ok: false, error: 'tunnel not connected' });
+    }
+    if (req.method === 'POST' && req.url === '/revoke-all') {
+      // 清除所有授权：请求中转清空本实例全部设备授权（先于本机密钥轮换调用）。
+      if (!(tunnel && tunnel.connected)) return send(res, 503, { ok: false, error: 'tunnel not connected' });
+      try {
+        const result = await tunnel.requestRevokeAll()
+        return send(res, 200, { ok: true, revoked: result?.revoked || 0 })
+      } catch (error) { return send(res, 502, { ok: false, error: error instanceof Error ? error.message : String(error) }) }
+    }
+    return send(res, 404, { ok: false, error: 'not found' })
+  } catch (error) {
+    // 体积超限归 4xx：它是请求本身装不下，不是这个服务不可用。兜成 503 的代价是
+    // 宿主侧把「body 太大」和「隧道没连上」记成同一条错，两者都长得一模一样。
+    if (error instanceof BodyTooLarge) return send(res, 413, { ok: false, error: error.message })
+    return send(res, 503, { ok: false, error: error instanceof Error ? error.message : String(error) })
+  }
+})
+server.on('connection', socket => { sockets.add(socket); socket.once('close', () => sockets.delete(socket)) })
+server.listen(0, '127.0.0.1', () => { const address = server.address(); process.send?.({ type: 'ready', port: address.port }) })
+const shutdown = () => {
+  reconnect.cancel()
+  server.close()
+  for (const socket of sockets) socket.destroy()
+  void stopServices()
+  setTimeout(() => process.exit(0), 1000).unref()
+}
+process.once('SIGTERM', shutdown); process.once('SIGINT', shutdown)
+
+/**
+ * 父进程（宿主）没了就自己退出：否则这里会变成一具握着隧道的尸体。
+ *
+ * ~~Node 的 fork 子进程不会随父进程退出~~。宿主被 Cmd+Q / 被系统内存压力清掉 / 被
+ * SIGKILL 时，没有任何人会给这里发 SIGTERM，IPC 通道也只是**静默 EOF**（Node 不会
+ * 替我们发 disconnect）。于是 worker 继续活着、继续握着那条 `register` 成功过的中转
+ * 隧道、继续如实回答 `/api/mobile/v1/status`（它知道的宿主身份还是那一份），中转的
+ * `instances` 里那条记录就永不删除 —— 手机侧栏的设备「在线」从此再也灭不掉，正文
+ * 镜像也停在最后一帧。2026-10-10 真机故障，根因就在这里。
+ *
+ * 两道判据都留着，互相兜底：
+ *  - `disconnect`：宿主正常退出 / 主动销毁 IPC 时立刻触发，退出最快；
+ *  - ppid 巡检：宿主被 SIGKILL 时**不发** disconnect（实测只看到 ppid 变成 1），
+ *    只能靠定时对账。启动时记下 ppid，之后对不上就退出；间隔与宿主那边的健康轮询
+ *    同量级（10s），2s 只是让「关掉桌面 → 手机显示离线」快一点。
+ *
+ * 为什么是整进程退出而不是只 `stopServices()`：隧道一关，中转最多 60s（心跳 pong
+ * 超时）才删掉实例，这段时间手机仍显示在线；而孤儿进程本来就没有存在的理由，退出是
+ * 最快的收敛路径（也让 `ps` 里不再留下一行认不出归属的 node 进程）。
+ */
+const PARENT_WATCH_INTERVAL_MS = 2000
+const parentPidAtStart = process.ppid
+let parentWatchTimer = null
+function watchParent() {
+  if (parentWatchTimer) return
+  parentWatchTimer = setInterval(() => {
+    if (process.ppid === parentPidAtStart) return
+    process.stderr.write('[dsh-mobile-plugin] parent process gone, sidecar shutting down\n')
+    shutdown()
+  }, PARENT_WATCH_INTERVAL_MS)
+  // 看护本身不该把进程按在这里：宿主正常退出时靠 disconnect 收尾。
+  if (typeof parentWatchTimer.unref === 'function') parentWatchTimer.unref()
+}
+process.once('disconnect', () => { process.stderr.write('[dsh-mobile-plugin] parent IPC closed, sidecar shutting down\n'); shutdown() })
+watchParent()

package/lib/sidecar-facade.cjs

@@ -0,0 +1,141 @@
+'use strict'
+
+/**
+ * SidecarFacade：宿主 ⇄ sidecar worker 的环回 HTTP 客户端 + 生命周期看守。
+ *
+ * fork worker、等 ready、把它的 stdout/stderr 转发到宿主 stderr（诊断只有这一条通道），
+ * 之后按需 request('/status' | '/configure' | '/tunnel/send' | '/revoke-all')。
+ * 两条上报通道都是「宿主必须立刻知道」的事：onDown（worker 意外退出，否则宿主的隧道/
+ * 局域网快照会永远冻在临死前那一帧，比状态难看危险得多）与 onState（worker 在状态
+ * 变化那一刻主动推的一帧，比 10s 轮询早得多）。
+ *
+ * 刻意不做重试：request 超时就是超时，由调用方（sidecar-lifecycle）决定是否重启；
+ * 在这里偷偷重试会把「隧道已死」拖成「偶尔能通」，反而更难诊断。
+ */
+
+const http = require('node:http')
+const { fork } = require('node:child_process')
+const { join } = require('node:path')
+
+const worker = join(__dirname, 'sidecar-facade-worker.cjs')
+
+class SidecarFacade {
+  constructor(options) {
+    this.parentPort = options.parentPort
+    this.token = options.token
+    this.child = null
+    this.port = null
+    this.pending = new Map()
+    this.nextId = 1
+    // worker 意外死掉时通知宿主。宿主那边有一份 sidecarSnapshot（隧道/局域网的
+    // 最近一次快照），如果没人告诉它 worker 已经没了，这份快照就永远冻在临死前
+    // 那一帧：/api/relay/status 会继续报 tunnel: connected、lan: listening，
+    // 而局域网端口上早就没人监听了。状态乐观比状态难看危险得多——它会让宿主
+    // 继续按「隧道是通的」去推镜像，然后一路 503。
+    this.onDown = typeof options.onDown === 'function' ? options.onDown : null
+    // 隧道/局域网状态**跳变**的即时上报（worker 侧 publishState()）。健康轮询仍然是权威
+    // （只有它能发现「worker 整个没了」——那时 IPC 也断了），但轮询是 10s 一次的滞后快照：
+    // 隧道真断之后宿主最多 10s 仍认为已连接，期间照推镜像、每次撞 5s 超时，该会话的单飞门
+    // 被占住；反过来「断又连」整段落在两次轮询之间时，宿主看不到跳变，全量补推会被漏掉。
+    // 这里只做转发，边沿判定在宿主侧（lib/sidecar-lifecycle.cjs 的 applyTunnelState），
+    // 与轮询共用同一个判定，所以不会把一次重连算成两次补推。
+    this.onState = typeof options.onState === 'function' ? options.onState : null
+  }
+
+  async start() {
+    if (this.child) return
+    const child = fork(worker, [], { env: { ...process.env, DSH_SIDECAR_PARENT_PORT: String(this.parentPort), DSH_SIDECAR_TOKEN: this.token }, stdio: ['ignore', 'pipe', 'pipe', 'ipc'] })
+    this.child = child
+    // 意外退出必须立刻反映到宿主，不能等下一次健康轮询。这里带身份守卫：stop() 先把
+    // this.child 置空，紧接着 start() 会产生新 child，旧 child 迟到的 exit 绝不能把
+    // 刚起来的新实例又拉下水（和 worker 侧 tunnel 的 `tunnel === current` 同一道理）。
+    child.once('exit', (code, signal) => {
+      if (this.child !== child) return
+      this.child = null
+      // port 也要清：留着它的话后续 request 会对着一个已经没人监听的端口发，
+      // 报出来的是 ECONNREFUSED 之类天书，而不是「sidecar 已经不在了」。
+      this.port = null
+      if (this.onDown) this.onDown(new Error(signal ? `sidecar facade killed by ${signal}` : `sidecar facade exited ${code}`))
+    })
+    // 子进程的 stdout/stderr 必须有人消费。旧实现只给 stderr 开了 pipe 却从不读，
+    // 于是隧道与局域网代理的全部诊断输出被静默丢弃（排障时表现为「宿主日志里
+    // 什么都没有，连崩溃都看不见」）；写入量涨过管道缓冲后，worker 的事件循环
+    // 还会被写阻塞卡死。这里原样转发到宿主自己的 stderr（systemd 收进 host.log）。
+    child.stdout?.on('data', (chunk) => process.stderr.write(chunk))
+    child.stderr?.on('data', (chunk) => process.stderr.write(chunk))
+    // 状态帧必须用常驻监听：下面 ready 用的是 child.once('message')，它会把第一条消息吃掉。
+    // 状态上报与 ready 恰好都在启动窗口里发，用 once 会漏掉第一条（而且 after ready 的
+    // 那些也永远收不到）。
+    child.on('message', message => {
+      if (!this.onState || !message || message.type !== 'state') return
+      try { this.onState(message) } catch { /* 状态回写不能反过来弄挂 facade */ }
+    })
+    const ready = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('sidecar facade startup timeout')), 5000)
+      child.once('message', message => {
+        if (message?.type === 'ready') { clearTimeout(timer); this.port = message.port; resolve(message) }
+      })
+      child.once('error', reject)
+      child.once('exit', code => { if (code !== 0) reject(new Error(`sidecar facade exited ${code}`)) })
+    })
+    await ready
+    await this.request('/health')
+  }
+
+  // `timeoutMs` 可覆盖：隧道侧的 `/revoke-all` 需要给中转 10s 去逐个断开设备，
+  // 而这里旧实现硬编码 5s，慢中转下宿主永远先超时、`/api/relay/revoke-all` 只好
+  // 报 revoked:0（看起来像「撤销成功但一台都没撤」）。
+  request(pathname, method = 'GET', body, timeoutMs = 5000) {
+    if (!this.port) return Promise.reject(new Error('sidecar facade is not running'))
+    return new Promise((resolve, reject) => {
+      const headers = { authorization: `Bearer ${this.token}` }
+      if (body !== undefined) headers['content-type'] = 'application/json'
+      const req = http.request({ host: '127.0.0.1', port: this.port, path: pathname, method, headers }, res => {
+        let raw = ''; res.setEncoding('utf8'); res.on('data', chunk => { raw += chunk }); res.on('end', () => {
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            // 把 worker 侧返回的 error 原文带进异常。raw 这时已经在手上，却一直被丢掉，
+            // 于是「请求体太大」「隧道没连上」「帧太大」在宿主侧全长成同一句
+            // `sidecar facade request failed: 503`——排查时无从下手，只能反过来去
+            // 读 worker 进程的 stderr。这一行是把整个镜像 503 查出来的关键。
+            let detail = ''
+            try {
+              const parsed = JSON.parse(raw || '{}')
+              if (parsed && typeof parsed.error === 'string' && parsed.error) detail = ` (${parsed.error})`
+            } catch { /* 非 JSON 响应就只能留状态码 */ }
+            return reject(new Error(`sidecar facade request failed: ${res.statusCode}${detail}`))
+          }
+          try { resolve(JSON.parse(raw || '{}')) } catch { reject(new Error('invalid sidecar facade response')) }
+        })
+      })
+      const timer = setTimeout(() => req.destroy(new Error('sidecar facade request timeout')), timeoutMs)
+      req.once('close', () => clearTimeout(timer))
+      req.on('error', reject)
+      if (body !== undefined) req.end(JSON.stringify(body)); else req.end()
+    })
+  }
+
+  /** 桌面→relay 主动推送（移动端镜像缓存）：复用隧道 sendJson(T.sync)。 */
+  pushSync(payload) {
+    return this.request('/tunnel/send', 'POST', payload)
+  }
+
+  async configure(config) {
+    return this.request('/configure', 'POST', config)
+  }
+
+  async stop() {
+    const child = this.child
+    this.child = null
+    this.port = null
+    if (!child) return
+    await new Promise(resolve => {
+      let settled = false
+      const finish = () => { if (!settled) { settled = true; clearTimeout(timer); resolve() } }
+      const timer = setTimeout(() => { child.kill('SIGKILL'); finish() }, 1500)
+      child.once('exit', finish)
+      child.kill('SIGTERM')
+    })
+  }
+}
+
+module.exports = { SidecarFacade }