dsh-mobile-plugin 0.1.65 → 0.1.67

package/lib/relay/core.js

@@ -1,3 +1,8 @@
+/**
+ * relay.json 的状态形状与读写，外加实例 ID / 配对码 / 隧道地址这几个纯函数。
+ *
+ * 内存里的 `state` 是本进程唯一真值，这里只负责落盘与还原（见 A3-20 的坑）。
+ */
 'use strict';
 
 const fs = require('node:fs');
@@ -29,6 +34,9 @@ function defaultState() {
     // 中转侧 TUNNEL_REGISTER_SECRET 的对偶值。为空时隧道注册会被中转以
     // close(1008, 'bad registration secret') 拒掉（除非中转根本没开校验）。
     registerSecret: '',
+    // 手机优先用哪条地址（空 = 不指定）。它是 `RemoteControlSettingsSchema` 里的一项，
+    // 写它不碰 sidecar（那份配置是 `impl.js` 的 `buildConfig` 逐字段拼的，不带它）。
+    preferredLanAddress: '',
     // 首次接入引导走完没有。**刻意不进 RemoteControlSettingsSchema**：它不是一项
     // 「远程控制设置」，改它不该触发 sidecar 重配（那条链上每加一个字段都要同步改
     // schema、worker 的 allowed 数组与 buildConfig，漏一处就抛 unknown field）。

package/lib/relay/lan-network.cjs

@@ -1,3 +1,8 @@
+/**
+ * 网卡枚举与候选地址：私网 / 公网两份清单，外加「用户选中的那条排最前」。
+ *
+ * 收口在这一个文件里，是因为 App 只认「按顺序挨个试」这一种语义 —— 顺序就是优先级。
+ */
 'use strict'
 
 const os = require('node:os')
@@ -158,6 +163,33 @@ function advertisedCandidates(port, interfaces = os.networkInterfaces()) {
   }
 }
 
+/**
+ * 把用户选中的那条排到最前面（面板上的「手机优先用这条」，存在设置项 `preferredLanAddress`）。
+ *
+ * 为什么只能是「排前面」：App 拿到候选之后是**按顺序挨个试**的，顺序就是唯一的表达方式
+ * （见 `impl.js` 的 `pairingPayload` 与 `routes/mobile-api.js` 的 `/connection-info`）。
+ * 所以这里刻意只挪位置：
+ *
+ *  - **不删任何东西**：其余的照旧跟在后面当兜底。用户选错了（比如选了一块手机根本到不了的
+ *    网卡）、或者那条以后不通了，手机还能顺着试下去，不会因为一次选择就把整条局域网路走死；
+ *  - **匹配不上就原样返回**：换了网段、拔了网卡之后，用户当初选的那个 IP 就不在清单里了，
+ *    这时必须退回宿主自己的网卡优先级排序。绝不能因为「选过一条现在没有的地址」把候选清空；
+ *  - 比对的是**地址**而不是整条 URL —— URL 里带着端口，用户改端口不该让这次选择失效。
+ */
+function orderCandidates(list, preferred) {
+  if (!Array.isArray(list)) return []
+  if (list.length < 2) return list
+  const want = String(preferred || '').trim()
+  if (!want) return list
+  const index = list.findIndex(item => item && item.address === want)
+  // 已经在首位（宿主的排序正好就是它），或者压根没有这条：原样返回。
+  if (index <= 0) return list
+  const ordered = list.slice()
+  const [picked] = ordered.splice(index, 1)
+  ordered.unshift(picked)
+  return ordered
+}
+
 module.exports = {
   ipv4Number,
   isPrivateLanAddress,
@@ -172,4 +204,5 @@ module.exports = {
   publicUrls,
   publicCandidates,
   advertisedCandidates,
+  orderCandidates,
 }

package/lib/relay/lan-proxy.js

@@ -503,6 +503,13 @@ document.getElementById('f').addEventListener('submit', async (e) => {
             res.end('ok');
             return;
           }
+          // 地址体检要和 /healthz 一样在鉴权之前放行：手机在配对之前就要问「这个地址上
+          // 是宿主还是中转」，那时候它没有任何 token（上游那一条也没有 guarded）。
+          // 它只回服务名与版本，不是能力面。
+          if (url.pathname === '/api/mobile/v1/health') {
+            proxyToUpstream(req, res);
+            return;
+          }
           if (!authorized(req)) {
             // API 请求必须回 JSON 401（见 isApiRequest 注释）；只有浏览器导航才给配对页。
             if (isApiRequest(req, url)) sendUnauthorized(res);

package/lib/relay/port-allocator.cjs

@@ -47,11 +47,26 @@ function freePort(host) {
 
 /**
  * 解析出本次真正要监听的端口。
- * @returns {Promise<{port: number, adjusted: boolean, requested: number}>}
- *   `adjusted=true` 表示首选端口被占、换了一个。
+ *
+ * @param {number} requested 首选端口（不合法就回落 18787）。
+ * @param {string} [host] 试绑地址。
+ * @param {object} [options]
+ * @param {number} [options.ours] 我们**自己占着**的端口（= 最近一次下发给局域网代理的那个号），
+ *   没有给 0。试绑一个自己占着的端口必然失败，但那不是「被别人占了」——调用方给这个值时，
+ *   等于告诉我们「这个号是我的」，于是原样保留、连试绑都不做。
+ *   **这一条不认，只读动作也会改落盘状态**：插件面板上「看一眼二维码」那条路由也会解析
+ *   一次端口，代理已经在那个号上之后每次解析都会判它「被占」、换一个内核随手给的空闲端口
+ *   回传，而调用方会把它写回 relay.json——于是状态里记的端口与真实监听分叉，平时看不出来，
+ *   **下次重启按漂过的值去绑，手机里存的地址就废了**。判据怎么来的见 sidecar-lifecycle 的
+ *   getOwnLanPort：**不能**用「快照说它在 listening」，那个在重绑窗口里还是上一个号。
+ * @returns {Promise<{port: number, adjusted: boolean, requested: number, ours?: boolean}>}
+ *   `adjusted=true` 表示首选端口被占、换了一个；`ours=true` 表示这个号本来就是自己的。
  */
-async function resolvePort(requested, host = '0.0.0.0') {
+async function resolvePort(requested, host = '0.0.0.0', options = {}) {
   const wanted = Number.isInteger(requested) && requested >= 1024 && requested <= 65535 ? requested : 18787
+  if (Number.isInteger(options.ours) && options.ours === wanted) {
+    return { port: wanted, adjusted: false, requested: wanted, ours: true }
+  }
   if (await canListen(wanted, host)) return { port: wanted, adjusted: false, requested: wanted }
   const port = await freePort(host)
   return { port: port > 0 ? port : wanted, adjusted: true, requested: wanted }

package/lib/routes/control-plane.js

@@ -13,6 +13,9 @@
  * 取值器/函数注入，不捕获对象——闭包里那些 `let`（sidecarSnapshot、lanPortAdjusted、
  * sidecarState…）会被整体替换或重新赋值。`getSidecar` 尤其重要：sidecar 会被自重启换掉，
  * 拿到实例本身就等于拿到一份指向旧 facade 的快照。
+ *
+ * 插件更新那两条：`check` 自己问 npm 注册表（不要求外壳在场），`apply` 只委托外壳的
+ * `apply`（判定 / 装 / 换代 / 落账同一层）——各自的取舍写在路由头上。
  */
 
 const fs = require('node:fs');
@@ -36,7 +39,7 @@ const desktopHalf = require('../desktop-half-stats.cjs');
 // 「查有没有新版」与「装新版」这两格都归插件自己：查直接问 npm 注册表，装在 profile 里跑
 // 它自己的包管理器（见 `../update-registry.cjs` / `../update-install.cjs`）。不再借道市场。
 const { checkForUpdate } = require('../update-registry.cjs');
-const { installLatestIfNeeded, declaredSource } = require('../update-install.cjs');
+const { declaredSource } = require('../update-install.cjs');
 const { clearCompletionForAllDevices, invalidateSessionList } = require('../mobile/session-cache.js');
 
 /** 一次 desktop-read 上报最多带多少个会话 id（防灌爆；客户端半边一次最多也就几个）。 */
@@ -216,11 +219,15 @@ function registerControlPlaneRoutes(deps) {
   // 面板的「手机该填哪个地址」：把检测到的网卡地址按**局域网 / 公网**分成两份报出来，
   // 用户不用自己去 `ipconfig`，界面也能一眼看出该填哪个（引导第三、四页用它）。
   //
-  // 只给面板看：移动端那份候选契约（二维码里带的 `lanUrls`）**一个字都没动**，那边的
+  // 只给面板看：移动端那份候选契约（二维码里带的 `lanUrls`）的**取舍**一个字都没动，那边的
   // 私网/公网取舍见 `../relay/lan-network.cjs` 的 `advertisedCandidates`。
+  //
+  // `preferred` 是用户在这两份地址里选中的那条（设置项 `preferredLanAddress`）：界面靠它回显
+  // 「现在选的是这条」。选中的地址要真生效在二维码与 `/connection-info` 里，不在这一条上。
   registerRoute({ kind: 'exact', path: '/api/relay/addresses', handler: localOnly('GET', async (_req, res) => {
     const port = lanPortInUse()
-    sendJson(res, 200, { ok: true, port, lan: lanCandidates(port), public: publicCandidates(port) })
+    const preferred = typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : ''
+    sendJson(res, 200, { ok: true, port, preferred, lan: lanCandidates(port), public: publicCandidates(port) })
   }) })
   registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), ...mobileActivity() })) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
@@ -391,6 +398,11 @@ function registerControlPlaneRoutes(deps) {
     if (body?.pairingPolicy === 'code' || body?.pairingPolicy === 'deny') patch.pairingPolicy = body.pairingPolicy
     // 注册密钥：只接受字符串，过长拒绝；写空串等于关掉（回到"中转开了校验就连不上"）。
     if (typeof body?.registerSecret === 'string' && body.registerSecret.length <= 512) patch.registerSecret = body.registerSecret
+    // 手机优先用哪条地址。**空串是合法值**（= 不指定，回到宿主的网卡优先级），所以这里
+    // 只挡类型和长度，不像 name 那样要求非空——那是「清掉这次选择」的唯一方式。
+    if (typeof body?.preferredLanAddress === 'string' && body.preferredLanAddress.length <= 64) {
+      patch.preferredLanAddress = body.preferredLanAddress.trim()
+    }
     await settings.update(patch)
     await syncSidecar().catch(() => undefined)
     sendJson(res, 200, status())
@@ -440,20 +452,6 @@ function registerControlPlaneRoutes(deps) {
       return null
     }
   }
-  /**
-   * 取一个宿主服务，拿不到就当没有。
-   *
-   * 更新这条路要用两个：`profileContext`（宿主发布的包管理器调用方式，装的时候必须优先用它）
-   * 与 `agents`（「有对话在跑就别换插件文件」那道闸的判据）。宿主没提供某个服务时如实降级，
-   * **不许让路由因此抛错** —— 服务不存在时 `ctx.get` 本身可能就不在。
-   */
-  const hostService = key => {
-    try {
-      return ctx && typeof ctx.get === 'function' ? ctx.get(key) ?? null : null
-    } catch {
-      return null
-    }
-  }
   const runtimeUnavailable = { ok: false, error: { code: 'update_unavailable', message: '这一版没有可换代的外壳（插件是被直接挂载的），装完没法就地生效，所以这里不装：无头部署请 rsync 源码后重启' } }
   registerRoute({ kind: 'exact', path: '/api/relay/update/status', handler: localOnly('GET', async (_req, res) => {
     const runtime = pluginRuntime()
@@ -489,15 +487,21 @@ function registerControlPlaneRoutes(deps) {
       })
     }
   }) })
-  // 「更新并立即生效」：插件**自己**去 profile 里装新版（`../update-install.cjs`），装完请外壳
-  // 就地换代。不再问市场 —— 装这一半也是插件自己的事了（查在同一条路上的 `check`）。
+  // 「更新并立即生效」：**交给外壳去做**（`runtime.apply`）。它在 profile 里跑插件自己的包
+  // 装器装新版、装完就地换代，并把这次结果写进它那本 `lastApply` 账 —— 面板「最近一次更新」
+  // 与那颗「强制更新」按钮的「上次没装成」判据读的都是这本账。
+  //
+  // 为什么这条路由不再自己去装（2026-10-12 改）：从前它自己调 `installLatestIfNeeded` 再
+  // `reload`，判定确实和自动更新是同一套（外壳那条路最后也走盘上那一代的同一个函数），
+  // **但结果没人落账** —— 手动（含强制）更新装完，外壳的账一动不动，面板那一行永远停在上一次
+  // 自动更新的结果上。判定与记账必须是同一个动作，所以这里只负责传参、把外壳记完账的状态
+  // 原样回给面板（`status` 必须是 apply **之后**的快照，拿 apply 之前那份等于没落账）。
   //
-  // 只在有外壳时才装：盘上换了版本、运行中的实现换不掉，等于「装了个用不上的东西」，不如
-  // 直说办不了。装失败一律回 200 + 如实的结果（面板照着 `failure` 说人话），只有我们这边
-  // 出了意料之外的错才回 500。
+  // 只在有外壳时才装（没外壳回 409）：盘上换了版本、运行中的实现换不掉，等于白装。装没装成
+  // 一律回 200 + 如实的结果（面板照着 `failure` 说人话）；只有外壳**抛错**才是意料之外，回 500。
   registerRoute({ kind: 'exact', path: '/api/relay/update/apply', handler: localOnly('POST', async (req, res) => {
     const runtime = pluginRuntime()
-    if (!runtime) return sendJson(res, 409, runtimeUnavailable)
+    if (!runtime || typeof runtime.apply !== 'function') return sendJson(res, 409, runtimeUnavailable)
     let body = {}
     try {
       body = (await readJson(req)) || {}
@@ -507,64 +511,56 @@ function registerControlPlaneRoutes(deps) {
     const force = body.force === true
     const snapshot = runtime.status()
     const beforeVersion = snapshot.installedVersion ?? snapshot.version ?? generationVersion()
-    const outcome = {
-      installed: false,
-      skipped: false,
-      state: 'failed',
-      beforeVersion,
-      installedVersion: beforeVersion,
-      swapped: false,
-      // 更新后绝不重启 DSH（外壳就地换代），这两格只为如实上报。
-      restartRequired: false,
-      refreshRequired: false,
-      failure: null,
-    }
-    const answer = (extra = {}) => Object.assign(outcome, extra)
-
-    const profileNodeModules = snapshot.profileNodeModules ?? null
-    if (!profileNodeModules) {
-      answer({ failure: { code: 'profile-unknown', message: '宿主没给出 profile 的 node_modules 路径，装不了' } })
-      return sendJson(res, 500, { ok: false, error: { code: 'update_apply_failed', message: outcome.failure.message }, data: { ...outcome, status: snapshot } })
-    }
+    const beforeOnDisk = snapshot.installedVersion ?? null
 
-    // 查一次（有没有新版）、可不可能被「有 agent 在跑」挡住、装不装，全在 `installLatestIfNeeded`
-    // 里一起判：面板那颗按钮与外壳的自动更新必须走同一套判定，否则会出现「手动说有新版、
-    // 自动说没有」这种最难查的偏差。
-    let result
+    let applied
     try {
-      result = await installLatestIfNeeded({
-        profileNodeModules,
-        force,
-        // 宿主发布的包管理器调用方式（`{command, args, env?}`）。**必须优先用它**：PATH 上
-        // 那个 pnpm 的版本可能和 profile 的 store 对不上（实测 10.x 装 11.x 的 profile 直接
-        // `ERR_PNPM_UNEXPECTED_STORE`）。市场也是这么取的（`profileContext.packageManager`）。
-        packageManager: hostService('profileContext')?.packageManager ?? null,
-        // 「有对话在跑就先别换插件文件」那道闸的判据。force 由用户点按钮时显式带上。
-        agents: hostService('agents'),
-      })
+      applied = await runtime.apply({ force })
     } catch (error) {
-      result = { installed: false, installedVersion: beforeVersion, command: null, output: '', failure: { code: 'install_failed', message: String(error?.message || error) } }
-    }
-    outcome.installedVersion = result.installedVersion ?? beforeVersion
-    outcome.failure = result.failure ?? null
-    outcome.command = result.command ?? null
-    outcome.output = result.output ?? ''
-    outcome.retryable = result.retryable === true
-    // `skipped` 也要如实带出去：已经是最新那一条**不是失败**，面板照着它说「没有改动任何文件」。
-    outcome.skipped = result.skipped === true
-    outcome.state = result.installed || result.skipped ? 'succeeded' : 'failed'
-    if (!result.installed) {
-      return sendJson(res, 200, { ok: result.skipped === true, data: { ...outcome, check: result.check ?? null, status: runtime.status() } })
+      // 外壳抛错只有两类：装的那步就炸了（网络 / 权限 / 注册表），或者装上了、换代码那步炸了。
+      // 必须分开说 —— 后者盘上的版本已经变了，回一句「装上了但没换过来」比笼统报失败有用得多。
+      const after = runtime.status()
+      const landed = beforeOnDisk !== null && (after.installedVersion ?? null) !== beforeOnDisk
+      const failure = landed
+        ? { code: 'swap_failed', message: `新版已经装到盘上（${after.installedVersion}），但换代码没成：${String(error?.message || error)}` }
+        : { code: 'install_failed', message: String(error?.message || error) }
+      return sendJson(res, 500, {
+        ok: false,
+        error: { code: 'update_apply_failed', message: failure.message },
+        data: {
+          installed: landed,
+          skipped: false,
+          state: landed ? 'installed-not-swapped' : 'failed',
+          beforeVersion,
+          installedVersion: after.installedVersion ?? beforeVersion,
+          swapped: false,
+          // 更新后绝不重启 DSH（外壳就地换代），这两格只为如实上报。
+          restartRequired: false,
+          refreshRequired: false,
+          failure,
+          status: after,
+        },
+      })
     }
 
-    // 装上了才换代：换代码是外壳的事，失败要如实报（回滚由外壳负责，见 shell/runtime.js）。
-    try {
-      const status = await runtime.reload()
-      answer({ installed: true, state: 'succeeded', swapped: true, installedVersion: status?.version ?? outcome.installedVersion, refreshRequired: status?.shellChanged === true })
-    } catch (error) {
-      answer({ installed: true, state: 'installed-not-swapped', failure: { code: 'swap_failed', message: `新版已经装到盘上，但换代码没成：${String(error?.message || error)}` } })
+    // `ok` 只有「装上了」与「已经最新、什么都没动」算真；其余（含「有对话在跑」）都是没成。
+    const outcome = {
+      installed: applied.installed === true,
+      skipped: applied.skipped === true,
+      state: applied.state ?? (applied.installed || applied.skipped ? 'succeeded' : 'failed'),
+      beforeVersion: applied.beforeVersion ?? beforeVersion,
+      installedVersion: applied.installedVersion ?? beforeVersion,
+      swapped: applied.swapped === true,
+      restartRequired: applied.restartRequired === true,
+      refreshRequired: applied.refreshRequired === true,
+      failure: applied.failure ?? null,
+      retryable: applied.retryable === true,
+      command: applied.command ?? null,
+      check: applied.check ?? null,
+      // 外壳自己记完账后的状态（`lastApply` / `appliedAt` 就在这里面）。
+      status: applied.status ?? runtime.status(),
     }
-    return sendJson(res, 200, { ok: true, data: { ...outcome, status: runtime.status() } })
+    return sendJson(res, 200, { ok: outcome.installed || outcome.skipped, data: outcome })
   }) })
   // 自动更新开关（默认关）。开=外壳每 10 分钟问一次有没有新版，有就自己装并就地切换
   // （轮询住在外壳里，因为「没人看着也要发生」；装与换代用的就是上面这两条同一套实现）。

package/lib/routes/mobile-api.js

@@ -20,6 +20,7 @@
  */
 
 const { sendJson } = require('../http/routing.js');
+const { orderCandidates } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
 const agentPresets = require('../mobile/agent-presets.js');
@@ -34,6 +35,8 @@ const mobileCredentials = require('../mobile/credentials.js');
 const subagents = require('../mobile/subagents.js');
 const references = require('../mobile/references.js');
 const plugins = require('../mobile/plugins.js');
+// 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
+const pkg = require('../../package.json');
 const desktopView = require('../desktop-view.cjs');
 
 const API_VERSION = '1';
@@ -78,6 +81,20 @@ function registerMobileRoutes(deps) {
       ...hostMetadata(),
     })
   }) })
+  // 地址体检：手机在**配对之前**就要问「这个地址上到底是谁」，那时它手上没有任何
+  // 凭据，所以这条刻意不包 guarded（豁免与理由见 test/mobile-routes.test.cjs 的
+  // PUBLIC_ROUTES）。它能说的话只有服务名与版本——没有实例信息、没有任何能力面。
+  // 中转侧在 server.js 的同名路径上回 'dsh-mobile-relay'，App 靠这个字段分辨
+  // 「填的是宿主还是中转」（消费方 app/src/services/addressProbe.ts）。
+  //
+  // ⚠️ 签名必须是 `(req, res)` **两个**参数：宿主 webServer 就是 `handler(req, res)` 调的，
+  // 上面那条 `guarded(...)` 之所以能收 `(ctx, req, res)`，是因为那三个参数由 guarded 自己补。
+  // 这里曾写成 `(_ctx, _req, res)`，于是 `res` 是 undefined，而 `sendJson` 的 catch 会把
+  // TypeError 当成「连接已关闭」吞掉——既没报错也没回包，请求**永久挂住**；手机 5s 超时后
+  // 退回探活接口拿到 ok，报「能连上但不是 DSH 移动端服务」。纯文本的路由表测试抓不到这类错。
+  registerRoute({ kind: 'exact', path: '/api/mobile/v1/health', handler: async (_req, res) => {
+    sendJson(res, 200, { ok: true, service: 'dsh-mobile-plugin', apiVersion: API_VERSION, version: pkg.version })
+  } })
   // 局域网/中转连接信息。公网配对时由中转在 `/api/mobile/v1/connection-info`
   // 代答宿主上报的镜像数据；但纯局域网配对（App 只扫到局域网二维码、完全不经
   // 中转）需要宿主自己回答同一个地址，否则 App 拿不到 lanCandidates，换网卡后
@@ -86,7 +103,11 @@ function registerMobileRoutes(deps) {
     // 端口取「手机该拨的那个」（sidecar 真 bind 成的），不是配置里的首选端口：
     // 两者不一致时这里报出去的候选是死地址，手机只能退回公网中转。
     const port = typeof lanPortInUse === 'function' ? lanPortInUse() : state.lanPort
-    const candidates = state.lanEnabled ? safeLanCandidates(port) : []
+    // 用户在面板上选过的「手机优先用这条」（设置项 `preferredLanAddress`）在这里同样兑现：
+    // 手机是按顺序挨个试的，所以只挪顺序、不删候选。选的那条不在了就退回宿主排序。
+    const candidates = state.lanEnabled
+      ? orderCandidates(safeLanCandidates(port), state.preferredLanAddress)
+      : []
     const lanUpdatedAt = getSidecarSnapshot()?.lan?.updatedAt || Date.now()
     sendJson(res, 200, {
       ok: true,

package/lib/sidecar-lifecycle.cjs

@@ -100,9 +100,13 @@ function createSidecarLifecycle(deps) {
   // 请求复用同一个在飞 Promise，并记录一次待重跑，确保最终下发的是最新配置。
   let syncInFlight = null
   let syncQueued = false
+  // 我们最近一次**下发给 worker** 的局域网端口（0 = 还没下发过）。它是 getOwnLanPort 的判据。
+  let configuredLanPort = 0
   const applySidecarConfig = async () => {
     await resolveLanPort()
-    sidecarSnapshot = await sidecar.configure(buildConfig(lanPortInUse()))
+    const config = buildConfig(lanPortInUse())
+    configuredLanPort = Number.isInteger(config.lanPort) ? config.lanPort : 0
+    sidecarSnapshot = await sidecar.configure(config)
     sidecarState = 'healthy'
     return sidecarSnapshot
   }
@@ -239,6 +243,20 @@ function createSidecarLifecycle(deps) {
       if (Number.isInteger(reported) && reported > 0) return reported
       return lanPortInUse()
     },
+    /**
+     * 「这个局域网端口是我们自己占着的」——就是**最近一次下发给 worker 的那个号**；没下发过是 0。
+     *
+     * 为什么不用快照来判：`lan.port` 走的是 worker 上报的状态帧，是**另一条消息**。刚
+     * `configure` 完的那个窗口里快照还是上一个号（或还没绑完），此刻去试绑刚下发的号必然
+     * 失败——那是自己占着自己，不是被别人占了。只认快照的话，紧接着的第二次同步就会把这个
+     * 号判成「被占」、换个内核随手给的端口写回 relay.json，监听也跟着挪走（`/api/relay/config`
+     * 改端口那条路由**一次会同步两遍**，第二遍正好落在这个窗口里；2026-10-11 真机实测，
+     * 落盘端口 18787→22779→33091→17079→28223 一路漂，手机里存的地址就是这么废的）。
+     *
+     * 代价照实说：真的被别的程序占着时，这里也认这个号。那没关系——worker 自己 bind 失败会
+     * 退到内核给的空闲端口并按**实绑值**上报，对外报的地址（getAdvertisedLanPort）跟着它走。
+     */
+    getOwnLanPort: () => configuredLanPort,
     markSidecarDown,
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",