dsh-plugin-mobile-link 0.7.0 → 0.8.1

package/lib/link.js

@@ -5,9 +5,10 @@
  */
 
 import { EventEmitter } from 'node:events'
+import { dirname, join } from 'node:path'
 
 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, qrPayload } from './dlp.js'
 
 /**
  * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
@@ -18,7 +19,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,11 +31,17 @@ 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, writeState } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
 const PROTOCOL_VERSION = 1
 
+// WebSocket 关闭码：中转据此区分"计划内重连"和"需要处理的异常"（SR-08.08）。
+// 4002 已用于中转协议错误；这里补上两类自愈失败的码，不要再把 1000 复用给它们。
+const CLOSE_NORMAL = 1000
+const CLOSE_WATCHDOG = 4003
+const CLOSE_HEARTBEAT = 4004
+
 
 function sleep(ms, signal) {
   return new Promise((resolve) => {
@@ -54,6 +61,55 @@ function numberFromEnv(raw, fallback) {
   return Number.isFinite(value) && value >= 0 ? value : fallback
 }
 
+// ── 持久码缓存 ──────────────────────────────────────────────────────────
+
+/**
+ * 上次铸出来的持久码放在身份文件旁边（0600）。
+ *
+ * 中转只存码的哈希，铸码接口不会把同一张码再给一次，所以「小窗复用同一张持久码」
+ * （docs/PAIRING.md「二维码」一行）只能由连接器自己记住：面板每次打开都会请求一次码，
+ * 没有这份缓存就变成每开一次、每重载一次都多一张永久有效的码。
+ */
+function pairCodeCachePath(config) {
+if (config?.pairCodePath) return config.pairCodePath
+return join(dirname(config?.stateFile || defaultStatePath()), 'pair-code.json')
+}
+
+async function rememberPairCode(config, minted) {
+if (!minted?.code) return
+try {
+  await writeState(pairCodeCachePath(config), {
+    code: minted.code,
+    agentId: minted.agentId,
+    relayUrl: minted.relayUrl,
+    maxPairedDevices: minted.maxPairedDevices ?? null,
+    pairedDevices: Number(minted.pairedDevices ?? 0),
+    savedAt: Date.now(),
+  })
+} catch (error) {
+  // 缓存写不进去只影响"下次还会不会换码"，不该让这次取码失败。
+  config?.logger?.warn?.(`mobile-link: could not remember the pairing code: ${messageOf(error)}`)
+}
+}
+
+async function readRememberedPairCode(config, identity) {
+const file = await readState(pairCodeCachePath(config))
+if (!file || typeof file.code !== 'string' || !file.code) return null
+// 身份变了（重新登记、换了中转）就不是同一台电脑的码，不能拿来复用。
+if (file.agentId !== identity.agentId || file.relayUrl !== identity.relayUrl) return null
+return {
+  code: file.code,
+  expiresAt: null,
+  ttlMs: null,
+  persistent: true,
+  maxPairedDevices: Number(file.maxPairedDevices ?? 0) || null,
+  pairedDevices: Number(file.pairedDevices ?? 0),
+  relayUrl: identity.relayUrl,
+  agentId: identity.agentId,
+  qrPayload: qrPayload({ relay: identity.relayUrl, code: file.code }),
+}
+}
+
 export class MobileLinkAgent extends EventEmitter {
   constructor({
     relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl,
@@ -64,7 +120,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 +132,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
@@ -138,6 +194,9 @@ export class MobileLinkAgent extends EventEmitter {
     /// 历史读取（spec 007）：宿主 `sessionQuery` 就绪后由插件挂上；没挂上时
     /// 路由回 `link/unsupported`，手机继续走 `session/page`。
     this.setHistoryService = (service) => { this.router.history = service }
+    /// 图片两变体（预览 + 可选原图）：宿主 `attachments` / `fileUploads` 就绪后由插件挂上；
+    /// 没挂上时三个 `_link/image*` 方法回 `link/unsupported`（手机显示"原图不可用"）。
+    this.setImageVariants = (service) => { this.router.bindImageVariants(service) }
     /// 活动名单与 `link/jobs` 推帧（spec 018）：帧由 router 广播给在线设备，
     /// 订阅与去抖都在 roster 里。宿主服务由 `setJobsServices` 挂上。
     this.jobsRoster = createJobsRoster({
@@ -147,6 +206,9 @@ export class MobileLinkAgent extends EventEmitter {
     })
     this.router.bindJobsRoster(this.jobsRoster)
     this.setJobsServices = (services) => this.jobsRoster.bindServices(services)
+    /// 提醒口径（SR-02.08）：只报正式会话。宿主 `ctx.sessions` / `ctx.workspaceRegistry`
+    /// 由插件在 `wireSessionScope` 里挂上；缺一个就维持旧行为（全报）。
+    this.setSessionScopeServices = (services) => this.router.bindSessionScope(services)
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -173,6 +235,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 +349,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 +394,6 @@ export class MobileLinkAgent extends EventEmitter {
     }).finally(() => {
       this._loopActive = false
     })
-    return this
   }
 
   async stop() {
@@ -397,7 +479,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 +494,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 +646,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, {
@@ -518,7 +743,7 @@ export class MobileLinkAgent extends EventEmitter {
         this.lastError = `relay 超过 ${Math.round(idle / 1000)}s 没有动静（看门狗拆连接）`
         this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_HEARTBEAT, 'heartbeat timeout')
         this._lastProgressAt = this.now()
         return
       }
@@ -526,7 +751,7 @@ export class MobileLinkAgent extends EventEmitter {
         this.lastError = `链路 ${Math.round(idle / 1000)}s 没有进展（看门狗重建连接）`
         this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_WATCHDOG, 'watchdog timeout')
         this._lastProgressAt = this.now()
       }
     }, every)
@@ -544,7 +769,7 @@ export class MobileLinkAgent extends EventEmitter {
       if (this.now() - this._lastPong > this.pongTimeoutMs) {
         this.lastError = `relay stopped answering pings (>${this.pongTimeoutMs}ms)`
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_HEARTBEAT, 'heartbeat timeout')
         return
       }
       this.#rawSend({ t: 'ping', ts: this.now() })
@@ -557,14 +782,14 @@ export class MobileLinkAgent extends EventEmitter {
     this._heartbeat = undefined
   }
 
-  #teardownSocket(reason) {
+  #teardownSocket(reason, closeCode = CLOSE_NORMAL, closeReason = 'reconnecting') {
     this.#stopHeartbeat()
     const socket = this.socket
     const from = this.state
     this.socket = undefined
     if (socket) {
       try {
-        socket.close(1000, 'reconnecting')
+        socket.close(closeCode, closeReason)
       } catch {
         /* already gone */
       }
@@ -581,6 +806,7 @@ export class MobileLinkAgent extends EventEmitter {
     // connectedForMs 用来区分"刚连上就掉"和"挂了很久才掉"。
     this.journal.record('link.close', {
       reason,
+      closeCode,
       from,
       connectedForMs: this.connectedAt === undefined ? undefined : this.now() - this.connectedAt,
       // 有系统错误才带这个字段（正常关闭时不该凭空多一个 null）。
@@ -686,6 +912,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)
   }
@@ -702,7 +949,7 @@ export class MobileLinkAgent extends EventEmitter {
     this.router.onMuxDown(reason)
   }
 
-  // ── relay-side helpers ──────────────────────────────────────────────────
+// ── relay-side helpers ──────────────────────────────────────────────────
 
   /**
    * Ask the relay to mint a pairing code for this agent (relay NOTES.md §2).
@@ -711,13 +958,23 @@ export class MobileLinkAgent extends EventEmitter {
    */
   async mintPairCode({ ttlMs = null, fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
-    return mintPairCode({ identity, ttlMs, fetchImpl })
+    // 持久码：手上已经有一张就直接给它。中转那边只有哈希，重铸只会多出一张有效码。
+    if (ttlMs == null) {
+      const remembered = await readRememberedPairCode(this.config, identity)
+      if (remembered) return remembered
+    }
+    const minted = await mintPairCode({ identity, ttlMs, fetchImpl })
+    if (minted.persistent) await rememberPairCode(this.config, minted)
+    return minted
   }
 
   /** 用户点「重新生成」：作废旧码、铸新的，**不碰已配对设备**（032）。 */
   async regeneratePairCode({ fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
-    return regeneratePairCode({ identity, fetchImpl })
+    const minted = await regeneratePairCode({ identity, fetchImpl })
+    // 中转已经把旧码全部作废，这里换成新的那张。
+    await rememberPairCode(this.config, minted)
+    return minted
   }
 
   /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */

package/lib/router.js

@@ -16,9 +16,11 @@ import { FileInbox, FILE_BEGIN, FILE_CHUNK, FILE_END, isFileMethod } from './fil
 import { FileFetcher, FSGET_CANCEL } from './files-out.js'
 import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
+import { isImageVariantMethod } from './image-variants.js'
 import { isHistoryMethod } from './history.js'
 import { trimRecordsForWire } from './history/records.js'
 import { isJobsMethod } from './jobs-roster.js'
+import { createSessionScope } from './session-scope.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -176,6 +178,12 @@ export class DeviceRouter {
     // 「跑完了 / 待你回应」这类事件到了就报一声（见 `notifyFor`）。默认空函数，
     // 测试与不关心提醒的调用方可以不管它。帧由 link.js 发（router 不发帧）。
     this.notify = notify
+    /**
+     * 提醒口径（SR-02.08）：只报正式会话。`undefined` = 宿主服务还没绑上，按旧行为
+     * 全报；绑上之后由 `session-scope.js` 判定。列表顶部的待答计数在 App 侧另算，
+     * 走同一份「正式会话」定义。
+     */
+    this.sessionScope = undefined
     // 生命周期事件（设备 attach/detach 等）的去处，由 link.js 接到流水（journal.js）。
     // 默认空函数，所以 router 单独用时（单测、本地脚本）不需要日志设施。
     this.onEvent = onEvent
@@ -204,6 +212,15 @@ export class DeviceRouter {
     // 活动名单与 `link/jobs` 推帧（spec 018）。订阅与去抖都在 roster 里，router 只负责
     // 转交设备生命周期与把帧广播出去。
     this.jobsRoster = undefined
+    // 图片的两变体能力（预览 + 可选原图）：由 index.js 注入宿主 `attachments` /
+    // `fileUploads` 后挂上。没挂上时三个保留方法回 `link/unsupported`，
+    // 手机显示"原图不可用"，预览照旧。
+    this.imageVariants = undefined
+  }
+
+  /** 挂上图片变体能力；`undefined` 表示宿主服务缺失（如实报不支持）。 */
+  bindImageVariants(service) {
+    this.imageVariants = service
   }
 
   /**
@@ -218,6 +235,21 @@ export class DeviceRouter {
     for (const deviceId of this.devices.keys()) roster.addDevice(deviceId)
   }
 
+  /**
+   * 挂上提醒口径所需的宿主账本（`ctx.sessions` / `ctx.workspaceRegistry`）。
+   *
+   * 传 `undefined` 摘掉：宿主换代或插件卸载后不能拿着失效服务对象去判定。
+   */
+  bindSessionScope(services) {
+    this.sessionScope = services === undefined ? undefined : createSessionScope(services)
+  }
+
+  /** 这条会话是否值得报一声（只看正式会话；服务未绑上时保持旧行为）。 */
+  #shouldNotify(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') return false
+    return this.sessionScope === undefined || this.sessionScope.isFormal(sessionId)
+  }
+
   #changed() {
     this.onChange()
   }
@@ -658,9 +690,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 +701,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) }
       }
@@ -754,6 +787,30 @@ export class DeviceRouter {
       return
     }
 
+    // 图片变体（预览 + 原图）：手机先经 `_link/file*` 把字节落进收件箱，再来这里
+    // 让连接器把它们交给 Host 附件服务并登记关联。自己回答而不是转发：Host
+    // 没有对应的 RPC，而这正是保留方法存在的理由。
+    if (isImageVariantMethod(frame.method)) {
+      let result
+      try {
+        if (this.imageVariants === undefined) {
+          result = {
+            ok: false,
+            error: errorObject('link/unsupported', 'image variants are unavailable on this connector'),
+          }
+        } else {
+          result = { ok: true, value: await this.imageVariants.handle(frame.method, frame.args ?? {}) }
+        }
+      } catch (error) {
+        result = {
+          ok: false,
+          error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}),
+        }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      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.
@@ -1017,6 +1074,9 @@ export class DeviceRouter {
    * `api-session/error`（`:3150`）**有意不推**：它不一定是"跑完了"（也可能是一轮中途
    * 报错后继续），拿它当"跑完了"会发出一堆噪音提醒。这是决定，不是漏做。
    *
+   * **只报正式会话**（SR-02.08）：未分组、子会话与已归档的运行结束和待确认不报。
+   * 这就是 `#shouldNotify` 的唯一判据来源；主机服务绑上之前维持旧行为。
+   *
    * 不做去抖、不做队列、不做重试：一轮才一条，发失败（中转断了）就丢。`turnEnd` 丢一条
    * 不值得为它做重试；`attention` 丢不了，它同时被记账，手机回来会补发。
    */
@@ -1024,11 +1084,13 @@ export class DeviceRouter {
     if (!value || typeof value !== 'object') return
     if (value.type === 'emit' && value.event === 'api-session/status' && value.args?.[1] === false) {
       const sid = String(value.args[0] ?? '')
-      if (sid) this.notify({ kind: 'turnEnd', sid })
+      if (this.#shouldNotify(sid)) this.notify({ kind: 'turnEnd', sid })
       return
     }
     if (value.type === 'waterfall') {
-      this.notify({ kind: 'attention', sid: value.agentId, eid: value.eventId })
+      if (this.#shouldNotify(value.agentId)) {
+        this.notify({ kind: 'attention', sid: value.agentId, eid: value.eventId })
+      }
     }
   }