dsh-plugin-mobile-link 0.7.0 → 0.8.0

package/lib/link.js

@@ -7,7 +7,7 @@
 import { EventEmitter } from 'node:events'
 
 import { DshClient } from './dsh-client.js'
-import { agentEndpoint, decodeFrame, encodeFrameChecked, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
+import { agentEndpoint, decodeFrame, deviceListEndpoint, deviceRevokeEndpoint, encodeFrameChecked, isPlaceholderRelayUrl, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 
 /**
  * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
@@ -18,7 +18,7 @@ import { agentEndpoint, decodeFrame, encodeFrameChecked, nextBackoff, normalizeR
  * 挂在 `globalThis` 上是因为模块重载会把模块作用域清掉，只有进程级才留得住。
  */
 const LIVE_AGENT = Symbol.for('dsh.mobile-link.live-agent')
-import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
+import { EnrollError, enrollAgent, enrollCommand, inviteFrom, reportMachineAddress } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
 import { LinkJournal, defaultJournalPath } from './journal.js'
 import { LogSpool, defaultLogsRoot } from './logs.js'
@@ -30,7 +30,7 @@ import {
 } from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
 import { createJobsRoster } from './jobs-roster.js'
-import { MissingIdentity, resolveIdentity } from './state.js'
+import { MissingIdentity, defaultStatePath, readState, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
 const PROTOCOL_VERSION = 1
@@ -64,7 +64,7 @@ export class MobileLinkAgent extends EventEmitter {
     slowRequestMs = DEFAULT_SLOW_REQUEST_MS,
     // 关掉手机推送的接收（回退闸）；见 contracts/connector-diagnostics-method.md §4。
     diagnostics = true,
-    inviteCode, fetchImpl = fetch, env = process.env,
+    inviteCode, defaultRelayUrl, fetchImpl = fetch, env = process.env,
     // 生命周期流水（见 journal.js）：`journal` 传实例（测试注入），`journalPath`
     // 传路径（`defaultJournalPath()` 之外的位置），false 表示只留内存不落盘。
     journal, journalPath,
@@ -76,7 +76,7 @@ export class MobileLinkAgent extends EventEmitter {
     eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
   } = {}) {
     super()
-    this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, inviteCode }
+    this.config = { relayUrl, defaultRelayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, inviteCode }
     this.logger = logger
     this.heartbeatMs = heartbeatMs
     this.pongTimeoutMs = pongTimeoutMs
@@ -173,6 +173,8 @@ export class MobileLinkAgent extends EventEmitter {
     this._lastPong = 0
     this._loop = undefined
     this._loopActive = false
+    /** Single-flight guard for panel enrollment: two clicks redeem one code. */
+    this._enrolling = undefined
     this._watchdog = undefined
     this._lastProgressAt = 0
     this._abort = new AbortController()
@@ -285,7 +287,26 @@ export class MobileLinkAgent extends EventEmitter {
       }
     }
     globalThis[LIVE_AGENT] = this
-    if (this._loop) return this
+    // 只认"正在跑"的 loop：loop 可能因为未登记而结束，此时 `_loop` 还留着已完成的
+    // promise；拿它当"已在运行"会让面板登记完之后再也起不来。
+    if (this._loopActive) return this
+    // 显式 start 表示"要跑"：把 stop() 留下的栅栏放下来；不要靠 #launch 里
+    // 那个"正在停止就别启动"的保护来代劳。
+    this._stopping = false
+    this.#launch()
+    return this
+  }
+
+  /**
+   * Start one run of the reconnect loop.
+   *
+   * The single owner of "how a loop starts": `start()` calls it on boot and
+   * `enroll()` calls it after the identity is written. Never copy the loop
+   * bootstrapping into a second path — a divergent copy would skip the watchdog,
+   * the journal entry or the LIVE_AGENT bookkeeping.
+   */
+  #launch() {
+    if (this._stopping) return
     this._stopping = false
     this._abort = new AbortController()
     this.startedAt = this.now()
@@ -311,7 +332,6 @@ export class MobileLinkAgent extends EventEmitter {
     }).finally(() => {
       this._loopActive = false
     })
-    return this
   }
 
   async stop() {
@@ -397,7 +417,13 @@ export class MobileLinkAgent extends EventEmitter {
    * starts) and because `status()` reports whether it is still outstanding.
    */
   async enrollNow() {
-    const relayUrl = this.config.relayUrl
+    // A packaged install may pin only `defaultRelayUrl` (the panel prefill) and
+    // leave `relayUrl` at the placeholder; boot-time enrollment should still use
+    // the default rather than dial example.com.
+    const configured = this.config.relayUrl
+    const relayUrl = configured && !isPlaceholderRelayUrl(configured)
+      ? configured
+      : (this.config.defaultRelayUrl || configured)
     const settled = await enrollAgent({
       relayUrl,
       inviteCode: inviteFrom({ inviteCode: this.config.inviteCode, env: this.env }),
@@ -406,15 +432,151 @@ export class MobileLinkAgent extends EventEmitter {
       fetchImpl: this.fetchImpl,
       logger: this.logger,
     })
+    this.identity = settled
     this.needsEnroll = false
     this.lastError = undefined
     this.emit('status')
     return settled
   }
 
+  /**
+   * Redeem an invite code supplied by the panel, then start the link in place.
+   *
+   * This is the only path that may enroll *while the process is running*. It is
+   * single-flight (a double click must not consume two codes), refuses to replace
+   * an existing identity, and writes nothing on failure. On success the loop is
+   * relaunched here, so the person does not have to restart DSH.
+   *
+   * @param {{inviteCode: string, relayUrl: string, agentName?: string}} options
+   */
+  enroll({ inviteCode, relayUrl, agentName } = {}) {
+    if (this._enrolling) return this._enrolling
+    this._enrolling = this.#enrollOnce({ inviteCode, relayUrl, agentName })
+      .finally(() => { this._enrolling = undefined })
+    return this._enrolling
+  }
+
+  async #enrollOnce({ inviteCode, relayUrl, agentName }) {
+    if (this.enabled === false) {
+      throw new EnrollError('enroll/disabled', 'mobile-link: the connector is disabled; enable it before enrolling')
+    }
+    if (this._stopping) {
+      throw new EnrollError('enroll/unavailable', 'mobile-link: the connector is stopping; try again')
+    }
+    const stateFile = this.config.stateFile || defaultStatePath()
+    const existing = await readState(stateFile)
+    if (existing?.agentId && existing?.agentSecret) {
+      // Never replace a working identity behind the user's back: that would
+      // silently unpair every phone that is already attached.
+      throw new EnrollError('enroll/already-registered',
+        `mobile-link: this computer is already registered (${existing.agentId}); refusing to replace it`,
+        { status: 409 })
+    }
+
+    const settled = await enrollAgent({
+      relayUrl,
+      inviteCode,
+      name: agentName,
+      stateFile,
+      fetchImpl: this.fetchImpl,
+      logger: this.logger,
+    })
+
+    // Publish the fresh identity before relaunching: `#enrollPending()` consults
+    // `this.identity`, and a stale value would make the new loop redeem the
+    // configured/env invite a second time on top of what the panel just wrote.
+    this.identity = settled
+    this.needsEnroll = false
+    this.lastError = undefined
+    this.reconnectAttempts = 0
+    this.emit('status')
+
+    if (this.enabled !== false && !this._stopping) {
+      // If the previous loop is unwinding, let it finish before starting a new
+      // one; two loops would fight over the same relay agent session.
+      if (this._loopActive) await this._loop?.catch(() => {})
+      if (!this._loopActive && !this._stopping) this.#launch()
+    }
+    return settled
+  }
+
+  /**
+   * List every paired device for this agent, including ones that are offline.
+   * The router only knows attached devices; the panel needs the full roster so
+   * "已配对 N/M" and the visible rows describe the same set.
+   */
+  async listPairedDevices() {
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    let response
+    try {
+      response = await this.fetchImpl(deviceListEndpoint(identity.relayUrl), {
+        method: 'GET',
+        headers: { authorization: `Bearer ${identity.agentSecret}` },
+        signal: AbortSignal.timeout?.(15_000),
+      })
+    } catch (error) {
+      throw new Error(`mobile-link: cannot reach the relay to list devices: ${messageOf(error)}`)
+    }
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /devices`)
+    }
+    if (!response.ok || body?.ok !== true) {
+      throw new Error(body?.error?.message ?? `mobile-link: the relay rejected the device list (HTTP ${response.status})`)
+    }
+    return {
+      devices: Array.isArray(body.devices) ? body.devices : [],
+      maxPairedDevices: body.maxPairedDevices ?? null,
+      pairedDevices: body.pairedDevices ?? null,
+    }
+  }
+
+  /**
+   * Revoke one paired device through the relay, authenticated with this agent's
+   * secret. The relay enforces that the device belongs to this agent and drops
+   * its socket; the local router learns about it via `deviceDetach`.
+   *
+   * @param {string} deviceId
+   */
+  async revokeDevice(deviceId) {
+    const id = typeof deviceId === 'string' ? deviceId.trim() : ''
+    if (!id) throw new Error('mobile-link: a deviceId is required')
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    let response
+    try {
+      response = await this.fetchImpl(deviceRevokeEndpoint(identity.relayUrl), {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${identity.agentSecret}`,
+        },
+        body: JSON.stringify({ deviceId: id }),
+        signal: AbortSignal.timeout?.(15_000),
+      })
+    } catch (error) {
+      throw new Error(`mobile-link: cannot reach the relay to revoke ${id}: ${messageOf(error)}`)
+    }
+    let body
+    try {
+      body = await response.json()
+    } catch {
+      throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /devices/revoke`)
+    }
+    if (!response.ok || body?.ok !== true) {
+      throw new Error(body?.error?.message ?? `mobile-link: the relay rejected the revoke (HTTP ${response.status})`)
+    }
+    return { deviceId: body.deviceId ?? id }
+  }
+
   /** What a person has to run to register this computer. */
   enrollHint() {
-    return enrollCommand(this.config.relayUrl, this.config.agentName)
+    const configured = this.config.relayUrl
+    const relay = configured && !isPlaceholderRelayUrl(configured)
+      ? configured
+      : (this.config.defaultRelayUrl || configured)
+    return enrollCommand(relay, this.config.agentName)
   }
 
   /** One relay connection: resolves when the socket closes. */
@@ -422,6 +584,7 @@ export class MobileLinkAgent extends EventEmitter {
     const identity = await resolveIdentity(this.config)
     this.identity = identity
     this.needsEnroll = false
+    this.#backfillMachine(identity)
     this.relay = normalizeRelayUrl(identity.relayUrl)
     const url = `${agentEndpoint(identity.relayUrl)}?agentId=${encodeURIComponent(identity.agentId)}`
     const socket = await this.connectImpl(url, {
@@ -686,6 +849,27 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── mux-event delegates ─────────────────────────────────────────────────
 
+  /// 老身份在登记时还没有 MAC 字段：连接成功后补一次。只填一次，失败下轮再试，
+  /// 旧中转 404 视为不支持而不是链路故障。
+  #backfillMachine(identity) {
+    if (this._machineReportedFor === identity.agentId || this._machineReporting) return
+    this._machineReporting = true
+    void reportMachineAddress({
+      relayUrl: identity.relayUrl,
+      agentSecret: identity.agentSecret,
+      fetchImpl: this.fetchImpl,
+    }).then((result) => {
+      if (result.ok || result.unsupported) this._machineReportedFor = identity.agentId
+      if (result.ok && result.updated) {
+        this.logger.info?.(`mobile-link: recorded machine MAC ${result.macAddress}`)
+      }
+    }).catch((error) => {
+      this.logger.debug?.(`mobile-link: machine MAC backfill deferred: ${messageOf(error)}`)
+    }).finally(() => {
+      this._machineReporting = false
+    })
+  }
+
   onStreamItem(muxId, value) {
     this.router.onStreamItem(muxId, value)
   }

package/lib/router.js

@@ -658,9 +658,10 @@ export class DeviceRouter {
         const since = typeof args.since === 'string' ? args.since : null
         this.digestCursors ??= new Map()
         const previous = since ? this.digestCursors.get(deviceId) : null
-        // 版本对得上才发增量；对不上（首次、连接器重启、设备被清理）发全量。
-        const incremental = Boolean(previous && previous.version === since)
-        const delta = digestDelta(incremental ? previous.fingerprints : null, items)
+        // 版本对得上才认那份指纹表；对不上（首次、连接器重启、设备被清理）就当没有历史。
+        // 能不能当增量发由 digestDelta 决定：它持有指纹，也只有它能判断身份是否可识别。
+        const usable = previous && previous.version === since ? previous : null
+        const delta = digestDelta(usable ? usable.fingerprints : null, items)
         this.digestCursors.set(deviceId, { version: delta.version, fingerprints: delta.fingerprints })
         if (this.digestCursors.size > 32) {
           const oldest = this.digestCursors.keys().next().value
@@ -668,10 +669,10 @@ export class DeviceRouter {
         }
         const value = {
           ...trimmed,
-          items: incremental ? delta.changed : items,
-          removed: incremental ? delta.removed : [],
+          items: delta.changed,
+          removed: delta.removed,
           version: delta.version,
-          full: !incremental,
+          full: delta.full,
         }
         payload = { ok: true, value: encodeDigest(value, args.encoding) }
       }

package/lib/routes.js

@@ -86,6 +86,31 @@ function ttlFrom(value, fallbackMs) {
     : fallbackMs
 }
 
+/** Map an enrollment error code onto the HTTP status the panel sees. */
+export function enrollStatus(code) {
+  switch (code) {
+    case 'enroll/already-registered':
+    case 'enroll/disabled':
+      return 409
+    case 'enroll/timeout':
+      return 504
+    case 'enroll/rate-limited':
+      return 429
+    case 'enroll/state-write':
+    case 'enroll/internal':
+      return 500
+    case 'enroll/bad-request':
+    case 'enroll/invalid-relay':
+    case 'enroll/placeholder-relay':
+    case 'enroll/unknown':
+    case 'enroll/used':
+    case 'enroll/expired':
+      return 400
+    default:
+      return 502
+  }
+}
+
 /**
  * Register the routes.
  * @returns {Array<() => void>} disposers (already wrapped by the caller in ctx.effect).
@@ -93,6 +118,9 @@ function ttlFrom(value, fallbackMs) {
 export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, history }) {
   const guard = makeGuard(ctx, logger)
   const STATUS_ROUTE = '/mobile-link/status'
+  const ENROLL_ROUTE = '/mobile-link/enroll'
+  const REVOKE_ROUTE = '/mobile-link/devices/revoke'
+  const DEVICES_ROUTE = '/mobile-link/devices'
   const PAIR_ROUTE = '/mobile-link/pair-code'
   const REGENERATE_ROUTE = '/mobile-link/pair-code/regenerate'
   const disposers = []
@@ -116,6 +144,125 @@ export function registerMobileLinkRoutes(ctx, { agent, logger, config = {}, hist
     },
   }))
 
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: ENROLL_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('allow', 'POST')
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      if (body === undefined) {
+        sendJson(res, 400, { ok: false, code: 'enroll/bad-request', message: 'invalid JSON body' })
+        return
+      }
+      const relayUrl = typeof body.relayUrl === 'string' ? body.relayUrl.trim() : ''
+      const inviteCode = typeof body.inviteCode === 'string' ? body.inviteCode.trim() : ''
+      const agentName = typeof body.agentName === 'string' ? body.agentName.trim() : ''
+      if (!relayUrl) {
+        sendJson(res, 400, {
+          ok: false,
+          code: 'enroll/bad-request',
+          message: 'relayUrl is required',
+        })
+        return
+      }
+      try {
+        // 开放登记：不需要邀请码；旧调用方仍可带（历史兼容）。
+        const settled = await agent.enroll({
+          inviteCode: inviteCode || undefined,
+          relayUrl,
+          agentName: agentName || undefined,
+        })
+        logger.info?.(`mobile-link: panel enrollment succeeded for ${settled.agentId}`)
+        // Never return `agentSecret`: the browser has no use for it, and one
+        // XSS in the panel would otherwise hand over the machine's credential.
+        sendJson(res, 200, {
+          ok: true,
+          agentId: settled.agentId,
+          agentName: settled.agentName,
+          relayUrl: settled.relayUrl,
+        })
+      } catch (error) {
+        // Read the code off the error rather than using `instanceof`: a hot
+        // reload can leave the route and the link on different module
+        // generations, and an identity check would then downgrade a precise
+        // "already registered" into a generic 500.
+        const code = typeof error?.code === 'string' && error.code.startsWith('enroll/')
+          ? error.code
+          : 'enroll/internal'
+        const status = enrollStatus(code)
+        if (code === 'enroll/internal') {
+          logger.warn?.(`mobile-link: panel enrollment failed: ${String(error?.message ?? error)}`)
+        }
+        sendJson(res, status, { ok: false, code, message: String(error?.message ?? error) })
+      }
+    },
+  }))
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: DEVICES_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'GET') {
+        res.statusCode = 405
+        res.setHeader('allow', 'GET')
+        res.end()
+        return
+      }
+      try {
+        const result = await agent.listPairedDevices()
+        sendJson(res, 200, { ok: true, ...result })
+      } catch (error) {
+        sendJson(res, 502, {
+          ok: false,
+          code: 'devices/list-failed',
+          message: String(error?.message ?? error),
+        })
+      }
+    },
+  }))
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: REVOKE_ROUTE,
+    handler: async (req, res) => {
+      if (guard(req, res, { requireFence: true })) return
+      if (req.method !== 'POST') {
+        res.statusCode = 405
+        res.setHeader('allow', 'POST')
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      if (body === undefined) {
+        sendJson(res, 400, { ok: false, code: 'request/bad-request', message: 'invalid JSON body' })
+        return
+      }
+      const deviceId = typeof body.deviceId === 'string' ? body.deviceId.trim() : ''
+      if (!deviceId) {
+        sendJson(res, 400, { ok: false, code: 'request/device-id', message: 'deviceId is required' })
+        return
+      }
+      try {
+        const result = await agent.revokeDevice(deviceId)
+        logger.info?.(`mobile-link: revoked device ${result.deviceId}`)
+        sendJson(res, 200, { ok: true, deviceId: result.deviceId })
+      } catch (error) {
+        sendJson(res, 502, {
+          ok: false,
+          code: 'devices/revoke-failed',
+          message: String(error?.message ?? error),
+        })
+      }
+    },
+  }))
+
   disposers.push(ctx.webServer.register({
     kind: 'exact',
     path: PAIR_ROUTE,

package/lib/session-digest.js

@@ -133,11 +133,16 @@ export function digestFingerprint(item) {
   }
 }
 
-/** 一批会话的指纹表（id → 指纹）。 */
+/**
+ * 一批会话的指纹表（sessionId → 指纹）。
+ *
+ * 键是宿主 `SessionSummary.sessionId`——会话身份在宿主只有这一个名字。
+ * 这里不认 `id`：多认一个名字就是第二份身份，正是它让指纹表恒为空（2026-10-27）。
+ */
 export function digestFingerprints(items) {
   const map = new Map()
   for (const item of items ?? []) {
-    if (item && typeof item.id === 'string') map.set(item.id, digestFingerprint(item))
+    if (item && typeof item.sessionId === 'string') map.set(item.sessionId, digestFingerprint(item))
   }
   return map
 }
@@ -153,20 +158,29 @@ export function fingerprintsVersion(map) {
 /**
  * 相对上一次指纹表的增量。
  *
- * 入参 `previous` 为 Map 或 null；返回 changed（新增或内容变化的项）、
- * removed（消失的 id）与新版本。`previous` 为空时调用方应按全量处理。
+ * 入参 `previous` 为 Map 或 null。返回：
+ *   - `full`：能不能把这份结果当增量发；
+ *   - `changed`：新增或内容变化的项（`full` 时为整份 items）；
+ *   - `removed`：消失的 sessionId（`full` 时为空）；
+ *   - `version` / `fingerprints`：下一次比较用的版本与指纹表。
+ *
+ * **身份不可识别时退化为全量**：摘要是优化，不是事实来源。只要有一项没有 `sessionId`，
+ * 就没法证明其余项没变；此时宁可多发一份全量，也不能回空增量——后者不报错、不更新，
+ * 界面看起来正常却永远冻结（2026-10-27 的现场）。
  */
 export function digestDelta(previous, items) {
   const list = Array.isArray(items) ? items : []
+  const identifiable = list.every((item) => item && typeof item.sessionId === 'string')
   const next = digestFingerprints(list)
+  const version = fingerprintsVersion(next)
+  if (previous === null || !identifiable) {
+    return { full: true, changed: list, removed: [], version, fingerprints: next }
+  }
   const changed = []
   for (const item of list) {
-    if (!item || typeof item.id !== 'string') continue
-    if (!previous || previous.get(item.id) !== next.get(item.id)) changed.push(item)
+    if (previous.get(item.sessionId) !== next.get(item.sessionId)) changed.push(item)
   }
   const removed = []
-  if (previous) {
-    for (const id of previous.keys()) if (!next.has(id)) removed.push(id)
-  }
-  return { changed, removed, version: fingerprintsVersion(next), fingerprints: next }
+  for (const sessionId of previous.keys()) if (!next.has(sessionId)) removed.push(sessionId)
+  return { full: false, changed, removed, version, fingerprints: next }
 }

package/lib/state.js

@@ -106,9 +106,9 @@ export async function resolveIdentity({ stateFile, agentId, agentSecret, relayUr
   }
   if (!resolved.agentId || !resolved.agentSecret) {
     throw new MissingIdentity(
-      `mobile-link: this computer is not registered yet. Run "dsh-mobile-link enroll`
-      + ` --invite <code> --relay <relay-url>" with the invite code you were given, or set`
-      + ` ${INVITE_ENV} and restart DSH. (Provisioning by hand is still possible:`
+      `mobile-link: this computer is not registered yet. Open the "移动端连接" panel`
+      + ` and click 登记, or run "dsh-mobile-link enroll --relay <relay-url>".`
+      + ` (Provisioning by hand is still possible:`
       + ` "dsh-relay admin agent-register --account <acc> --name <name>`
       + ` --write-config ${path}".)`,
       { stateFile: path },

package/lib/status.js

@@ -6,6 +6,7 @@
  * 函数只读 agent 的字段，不持有状态，因此可以直接被单测调用。
  */
 
+import { isPlaceholderRelayUrl } from './dlp.js'
 import { SERVER_CAPABILITIES, SERVER_VERSION, hostVersion } from './hello.js'
 
 const PROTOCOL_VERSION = 1
@@ -81,6 +82,26 @@ const STATUS_JOURNAL_ENTRIES = 20
  */
 export function statusSnapshot(agent) {
   const hostEntry = HOST_HINTS[agent.hostForm] ?? HOST_HINTS.unknown
+  // One resolved view of the relay address, shared by the form and the panel:
+  // a configured address outranks the identity, but the repository placeholder
+  // is "unset", never a value to prefill. `relayLocked` says the address came
+  // from config/env, so the form must be read-only — otherwise the panel would
+  // enroll with one address and the next boot would dial another.
+  const configuredRelay = typeof agent.config?.relayUrl === 'string' ? agent.config.relayUrl : ''
+  const realConfiguredRelay = configuredRelay && !isPlaceholderRelayUrl(configuredRelay)
+    ? configuredRelay
+    : null
+  // `defaultRelayUrl` is a *form default*, not a dialing override: it only
+  // prefills the input, so the user can replace it and the identity file still
+  // wins on the next boot. A real `relayUrl` is the operator pin and locks it.
+  const configuredDefault = typeof agent.config?.defaultRelayUrl === 'string'
+    ? agent.config.defaultRelayUrl
+    : ''
+  const defaultRelay = configuredDefault && !isPlaceholderRelayUrl(configuredDefault)
+    ? configuredDefault
+    : null
+  const effectiveRelay = agent.identity?.relayUrl ?? realConfiguredRelay ?? null
+  const relayPrefill = realConfiguredRelay ?? defaultRelay ?? agent.identity?.relayUrl ?? null
   return {
     ok: true,
     enabled: agent.enabled !== false,
@@ -102,11 +123,18 @@ export function statusSnapshot(agent) {
       // computer half is installed but not yet registered, and what to run.
       registered: !agent.needsEnroll,
       needsEnroll: agent.needsEnroll,
+      // `panel` is a host-UI capability, not a phone capability: an older
+      // connector omits it, and the panel falls back to the command. It is
+      // deliberately not in SERVER_CAPABILITIES (that list is what the app asks
+      // for over `_link/hello`; the phone has no use for a panel form).
+      panel: true,
       stateFile: agent.identity?.stateFile ?? agent.config.stateFile ?? null,
-      relayUrl: agent.config.relayUrl ?? null,
+      relayUrl: effectiveRelay,
+      relayPrefill,
+      relayLocked: Boolean(realConfiguredRelay),
       command: agent.needsEnroll ? agent.enrollHint() : null,
       hint: agent.needsEnroll
-        ? '这台电脑还没有登记到中转。请带上邀请码运行一次登记命令，然后重启 DSH。'
+        ? '这台电脑还没有登记到中转。在「移动端连接」面板里确认中转地址，然后点「登记」。'
         : null,
     },
     state: agent.state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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",