dsh-remote 0.8.23 → 0.8.25

package/README.md

@@ -20,6 +20,48 @@ Manage several SSH machines, then pick a **remote workspace** (or a **local** on
 
 The harness Web UI intentionally binds `127.0.0.1` (the CLI rejects `--host 0.0.0.0` for safety). This plugin goes the other way: **you connect out** to the machines you maintain, pick a workspace, and work in it through the normal DSH workspace + agent fs flows — no changes to `dsh-workspace` or the harness core.
 
+## Data collection / telemetry
+
+dsh-remote sends **one anonymous heartbeat per launch** (at most once every 6 hours) so the author can measure real usage: daily active installs, which version is actually running, and platform distribution. npm download counts cannot answer this (they are release-driven and include mirrors/crawlers), and GitHub clones include CI.
+
+**What is sent** — exactly five fields, and nothing else:
+
+| Field | Example | Purpose |
+|---|---|---|
+| `idHash` | `872bd8cf…` (32 hex) | `HMAC-SHA256('dsh-remote/telemetry/v1', installId)` — a pseudonym for this install |
+| `version` | `0.8.24` | which version is actually running |
+| `platform` | `win32` / `darwin` / `linux` | platform distribution |
+| `arch` | `x64` / `arm64` | architecture |
+| `node` | `24.14.0` | Node version |
+
+**What is never sent** — hostnames, usernames, file paths, IP addresses, SSH hosts/ports/keys, your machine list, conversation content, or anything from your remote sessions. The original `installId` **never leaves your machine**: only its HMAC is transmitted, so the server cannot correlate it with anything else and cannot reverse it.
+
+**Where the identity lives** — a random UUID in `<DSH_HOME>/.dsh-remote-install-id` (e.g. `~/.dsh/`). It is deliberately **not** stored in the plugin directory, which npm/pnpm overwrites on every upgrade; keeping it in `DSH_HOME` means an upgrade does not make you look like a new user. Delete that file to reset the identity.
+
+The heartbeat is **fire-and-forget**: it never blocks loading, never logs noise, and any failure (offline, blocked, endpoint change) is swallowed silently — it can never affect any plugin feature.
+
+<!--中文-->
+
+## 数据采集 / 遥测
+
+dsh-remote 每次启动会发送**一次匿名心跳**（同一安装最多每 6 小时一次），用于统计真实使用量：去重日活、实际在跑的版本、平台分布。npm 下载量回答不了这些问题（由发版驱动、且含镜像与爬虫），GitHub clone 也混有 CI。
+
+**发送的内容** —— 严格只有 5 个字段：
+
+| 字段 | 示例 | 用途 |
+|---|---|---|
+| `idHash` | `872bd8cf…`（32 位 hex） | `HMAC-SHA256('dsh-remote/telemetry/v1', installId)`，本安装的伪名 |
+| `version` | `0.8.24` | 实际在运行的版本 |
+| `platform` | `win32` / `darwin` / `linux` | 平台分布 |
+| `arch` | `x64` / `arm64` | 架构 |
+| `node` | `24.14.0` | Node 版本 |
+
+**绝不发送** —— 主机名、用户名、文件路径、IP、SSH 主机/端口/密钥、你的机器列表、会话内容、任何远程工作区数据。原始 `installId` **不离开本机**：只有它的 HMAC 被传出，服务端无法与其他数据关联，也无法反推。
+
+**身份存放位置** —— `<DSH_HOME>/.dsh-remote-install-id`（如 `~/.dsh/`）中的一个随机 UUID。刻意**不放在插件目录**（npm/pnpm 每次升级都会覆盖），放 `DSH_HOME` 才能保证升级后不会把你算成新用户。删除该文件即重置身份。
+
+心跳是**尽力而为**的旁路：不阻塞加载、不产生日志噪音、任何失败（离线/被拦截/端点变更）都静默吞掉，绝不影响插件的任何功能。
+
 ## Screen previews
 
 Settings → **远程工作区** — a multi-machine SSH registry (add / edit / delete / set-current, password stored locally):

package/README.zh.md

@@ -41,6 +41,26 @@ Desktop 安装器还可能要求明确配置 `ssh2` / `cpu-features` 可选构
 
 DSH 的 Web 界面刻意只监听 `127.0.0.1`（CLI 为安全拒绝 `--host 0.0.0.0`）。本插件反过来：**由你主动连出**到你维护的机器，选一个工作区，然后通过 DSH 原生的工作区 + 文件流来工作——**不改动 `dsh-workspace` 核心**。
 
+## 数据采集 / 遥测
+
+dsh-remote 每次启动会发送**一次匿名心跳**（同一安装最多每 6 小时一次），用于统计真实使用量：去重日活、实际在跑的版本、平台分布。npm 下载量回答不了这些问题（由发版驱动、且含镜像与爬虫），GitHub clone 也混有 CI。
+
+**发送的内容** —— 严格只有 5 个字段，一个都不多：
+
+| 字段 | 示例 | 用途 |
+|---|---|---|
+| `idHash` | `872bd8cf…`（32 位 hex） | `HMAC-SHA256('dsh-remote/telemetry/v1', installId)`，本安装的伪名 |
+| `version` | `0.8.24` | 实际在运行的版本 |
+| `platform` | `win32` / `darwin` / `linux` | 平台分布 |
+| `arch` | `x64` / `arm64` | 架构 |
+| `node` | `24.14.0` | Node 版本 |
+
+**绝不发送** —— 主机名、用户名、文件路径、IP、SSH 主机/端口/密钥、你的机器列表、会话内容、任何远程工作区数据。本插件恰恰能拿到这些信息，所以边界在这里划得很硬：原始 `installId` **不离开本机**，只有它的 HMAC 被传出，服务端无法与其他数据关联，也无法反推身份。
+
+**身份存放位置** —— `<DSH_HOME>/.dsh-remote-install-id`（如 `~/.dsh/`）中的一个随机 UUID。刻意**不放在插件目录**：npm/pnpm 每次升级都会覆盖插件目录，放那里会让同一台机器每次升级都换身份，把 1 个用户算成 N 个。删除该文件即重置身份。
+
+心跳是**尽力而为**的旁路：不阻塞加载、不产生日志噪音、任何失败（离线/被拦截/端点变更）都静默吞掉，绝不影响插件的任何功能。
+
 ## 界面预览
 
 设置 → **远程工作区** —— 多机 SSH 列表（增/删/改/设为当前，密码本地保存、不回显）：

package/lib/client.js

@@ -139,8 +139,10 @@ window.__ModuleLoader__.load({
         'settings.updateFail': '检查更新失败',
         'settings.updateAvailable': '发现新版本 v{version}',
         'settings.updateLatest': '已是最新版本（v{version}）',
-        'settings.updateConfirm': '将更新 dsh-remote 到 v{version}，替换本机插件文件。更新后需重启 Harness 生效。继续？',
-        'settings.updateApplied': '✅ 已更新到 v{to}（{from} → {to}）。重启 Harness 生效。',
+        'settings.updateConfirm': '将更新 dsh-remote 到 v{version}，替换本机插件文件并在线热切换宿主半（不重启 Harness）。继续？',
+        'settings.updateApplied': '✅ 已更新到 v{to}（{from} → {to}），宿主半已在线热切换。',
+'settings.updateAppliedNoReload': '✅ 已更新到 v{to}（{from} → {to}）。重启 Harness 生效。',
+'settings.updatePendingReload': '⚠️ 磁盘已是 v{disk}，运行中的仍是 v{loaded}；点「立即更新」或重启 Harness 完成切换。',
         'settings.updateFailed': '更新失败',
         'settings.updateFailedMsg': '更新失败: {msg}',
         'settings.registryUnreachable': '无法连接 npm registry',
@@ -363,8 +365,10 @@ window.__ModuleLoader__.load({
         'settings.updateFail': 'Failed to check for updates',
         'settings.updateAvailable': 'New version found: v{version}',
         'settings.updateLatest': 'Already up to date (v{version})',
-        'settings.updateConfirm': 'Update dsh-remote to v{version}? This replaces the local plugin files and requires a Harness restart to take effect. Continue?',
-        'settings.updateApplied': '✅ Updated to v{to} ({from} → {to}). Restart Harness to apply.',
+        'settings.updateConfirm': 'Update dsh-remote to v{version}? This replaces the local plugin files and hot-swaps the host half in place (no Harness restart). Continue?',
+        'settings.updateApplied': '✅ Updated to v{to} ({from} → {to}); the host half hot-swapped in place.',
+'settings.updateAppliedNoReload': '✅ Updated to v{to} ({from} → {to}). Restart Harness to apply.',
+'settings.updatePendingReload': '⚠️ v{disk} is on disk but v{loaded} is still running; update again or restart Harness to switch.',
         'settings.updateFailed': 'Update failed',
         'settings.updateFailedMsg': 'Update failed: {msg}',
         'settings.registryUnreachable': 'Cannot reach the npm registry',
@@ -836,9 +840,13 @@ window.__ModuleLoader__.load({
         setUpdBusy(true); setUpdMsg('')
         api('POST', '/dsh-remote/update-apply', { version: upd.latest })
           .then((r) => {
-            if (r && r.ok) setUpdMsg(tr('settings.updateApplied', { to: r.to, from: (r.from || '') }))
+            if (r && r.ok) setUpdMsg(tr(r.reloadScheduled ? 'settings.updateApplied' : 'settings.updateAppliedNoReload', { to: r.to, from: (r.from || '') }))
             else setUpdMsg((r && r.error) || tr('settings.updateFailed'))
-            checkUpdate(true)
+            // The host half swaps itself ~300ms after answering, so the panel
+            // must not re-check immediately: it would still be talking to the
+            // outgoing fiber and report the pre-swap version, i.e. "update
+            // available" right after a successful update.
+            window.setTimeout(() => checkUpdate(true), 2000)
           })
           .catch((e) => setUpdMsg(tr('settings.updateFailedMsg', { msg: String((e && e.message) || e) })))
           .finally(() => setUpdBusy(false))
@@ -1127,6 +1135,10 @@ window.__ModuleLoader__.load({
               }, m === 'manual' ? tr('settings.modeManual') : m === 'auto' ? tr('settings.modeAuto') : tr('settings.modeOff')),
             ),
           ),
+          upd && upd.pendingReload
+            ? React.createElement('div', { style: { marginTop: 6, fontSize: 12, color: T.warn } },
+                tr('settings.updatePendingReload', { disk: upd.disk, loaded: upd.loaded }))
+            : null,
           updMsg ? React.createElement('div', { style: { marginTop: 6, fontSize: 12, color: updMsg.startsWith('✅') ? T.ok : 'inherit', opacity: 0.9 } }, updMsg) : null,
         ),
         React.createElement('div', { style: { display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap', fontSize: 11, opacity: 0.65, borderTop: '1px solid ' + T.border, paddingTop: 10, marginTop: 4 } },

package/lib/index.js

@@ -21,7 +21,7 @@
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { execFile } from 'node:child_process'
-import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, appendFileSync, watch } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync, statSync, renameSync, copyFileSync, appendFileSync, watch, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import iconv from 'iconv-lite'
@@ -41,7 +41,8 @@ import { searchRemote } from './search.js'
 import { resolveMirror, poolKey, lookupSessionCwd, encodeSegmentSafe, readSessionHeaderCwd, requestSessionHint } from './binding.js'
 import { TaskManager } from './tasks.js'
 import { ForwardManager } from './forwards.js'
-import { selfDir, readVersion, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode } from './update.js'
+import { selfDir, diskVersion, LOADED_VERSION, gtVersion, fetchLatestVersion, applyUpdate, persistUpdateMode, readUpdateMode, reloadSelf, scheduleSelfReload } from './update.js'
+import { sendHeartbeat, pseudonym, heartbeatUrl, hasPersistedId, installIdPath } from './telemetry.js'
 import { loadMachines as _loadMachines, saveMachines as _saveMachines, sanitizeMachine as _sanitizeMachine, applyMachine as _applyMachine, machineId as _machineId } from './registry.js'
 import { registerHttpTransports } from './http-transport.js'
 import { SshPool } from './pool.js'
@@ -130,6 +131,10 @@ export const Config = z.object({
   updateMode: z.string().default('manual'),
   /** How often (ms) auto mode checks the npm registry for a newer release. */
   updateCheckIntervalMs: z.number().step(1).min(60000).default(6 * 3600 * 1000),
+  /** Whether a landed update also hot-swaps the running host half (default
+   *  true). With `false` an update only takes effect on the next process start
+   *  and `/dsh-remote/update-check` reports `pendingReload: true` meanwhile. */
+  updateAutoReload: z.boolean().default(true),
 })
 
 // ── shell / path helpers (pure implementations in lib/paths.js) ───────────
@@ -258,6 +263,21 @@ export async function apply(ctx, config) {
 
   migrateLegacyData()
 
+  // ── 安装心跳（日活统计）─────────────────────────────────────────────────
+  // 旁路：不 await、不阻塞加载、失败静默（见 lib/telemetry.js 的隐私与失败策略）。
+  // 无配置开关（按作者要求默认开启）；上报的是本插件专属 HMAC 伪名，
+  // 原始安装 id 与任何机器信息都不离开本机。
+  void sendHeartbeat(dshBase(), LOADED_VERSION)
+
+  // The update marker means "a newer version landed on disk but is not the code
+  // running yet". Reaching apply() with a marker naming the version we just
+  // loaded means the swap already happened (or this is a plain boot into the
+  // updated files) → clear it, so the UI's "restart to finish" hint stays true.
+  try {
+    const marker = path.join(selfDir(), '.dsh-remote-updated')
+    if (existsSync(marker) && readFileSync(marker, 'utf8').trim() === LOADED_VERSION) rmSync(marker, { force: true })
+  } catch {}
+
   // ── machine registry (multi-host) ─────────────────────────────────────────
   const store = loadMachines()
   const machines = store.list
@@ -2765,17 +2785,26 @@ export async function apply(ctx, config) {
       path: '/dsh-remote/update-check',
       handler: async (req, res) => {
         if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
-        const current = readVersion()
-        const latest = await fetchLatestVersion()
-        if (latest === null) return sendJson(res, 200, { ok: false, current, error: '无法连接 npm registry' })
+        // `loaded` is the code actually running; `disk` may already be newer.
+        // They differ between an applied update and its hot swap (or a boot).
+        const loaded = LOADED_VERSION
+        const disk = diskVersion()
         const rawMode = readUpdateMode() || config.updateMode || 'manual'
+        const base = {
+          current: loaded,
+          loaded,
+          disk,
+          pendingReload: gtVersion(disk, loaded),
+          updateMode: ['manual', 'auto', 'off'].includes(rawMode) ? rawMode : 'manual',
+          updatedMarker: existsSync(path.join(selfDir(), '.dsh-remote-updated')),
+        }
+        const latest = await fetchLatestVersion()
+        if (latest === null) return sendJson(res, 200, { ok: false, ...base, error: '无法连接 npm registry' })
         return sendJson(res, 200, {
           ok: true,
-          current,
+          ...base,
           latest,
-          updateAvailable: gtVersion(latest, current),
-          updateMode: ['manual', 'auto', 'off'].includes(rawMode) ? rawMode : 'manual',
-          updatedMarker: existsSync(path.join(selfDir(), '.dsh-remote-updated')),
+          updateAvailable: gtVersion(latest, loaded),
         })
       },
     },
@@ -2785,16 +2814,45 @@ export async function apply(ctx, config) {
       handler: async (req, res) => {
         if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
         try {
+          // Capture the outgoing version BEFORE the swap: reading it afterwards
+          // reports the version we just installed, not the one we replaced.
+          const from = diskVersion()
+          const loaded = LOADED_VERSION
           const body = JSON.parse((await readBody(req)) || '{}')
           const target = String(body.version || '')
           if (!target) return sendJson(res, 400, { ok: false, error: 'version is required' })
           const result = await applyUpdate(target)
-          return sendJson(res, 200, { ok: true, from: readVersion(), ...result })
+          const wantReload = body.reload !== false && config.updateAutoReload !== false
+          // Answer first, then swap: the swap disposes the fiber serving this
+          // very request, so nothing may touch the plugin after it.
+          if (wantReload) scheduleSelfReload(ctx.loader, 300)
+          return sendJson(res, 200, {
+            ok: true,
+            from,
+            loadedBefore: loaded,
+            ...result,
+            reloadScheduled: wantReload,
+            // what the swap will land on, for a caller that wants to verify
+            loadedAfterReload: wantReload ? result.to : loaded,
+          })
         } catch (err) {
           return sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
         }
       },
     },
+    {
+      kind: 'exact',
+      path: '/dsh-remote/update-reload',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+        // Hot-swap the host half to whatever is on disk now. Answers first (with
+        // what was loaded and what it is about to become), then swaps.
+        const loaded = LOADED_VERSION
+        const disk = diskVersion()
+        scheduleSelfReload(ctx.loader, 300)
+        return sendJson(res, 200, { ok: true, scheduled: true, loaded, disk, willReloadTo: disk })
+      },
+    },
     {
       kind: 'exact',
       path: '/dsh-remote/update-mode',
@@ -2821,12 +2879,24 @@ export async function apply(ctx, config) {
   const rawMode = readUpdateMode() || config.updateMode || 'manual'
   const effectiveUpdateMode = ['manual', 'auto', 'off'].includes(rawMode) ? rawMode : 'manual'
   if (effectiveUpdateMode === 'auto') {
-    const currentVersion = readVersion()
     const checkAndApply = async () => {
       const latest = await fetchLatestVersion()
-      if (latest && gtVersion(latest, currentVersion)) {
-        try { await applyUpdate(latest) } catch {}
+      if (!latest) return
+      // The version in flight is whichever of "already on disk" / "already
+      // loaded" is newer. Pinning it once outside this closure (as v0.8.23 did)
+      // made every later interval re-download and re-apply the same tarball,
+      // because the pinned value never moves past the version it installed.
+      const disk = diskVersion()
+      const current = gtVersion(disk, LOADED_VERSION) ? disk : LOADED_VERSION
+      if (!gtVersion(latest, current)) return
+      try {
+        await applyUpdate(latest)
+      } catch {
+        return
       }
+      // Landed: swap the running host half too, otherwise the code being served
+      // and the code being run stay one version apart until the next boot.
+      if (config.updateAutoReload !== false) scheduleSelfReload(ctx.loader, 500)
     }
     void checkAndApply()
     const updateTimer = setInterval(checkAndApply, Math.max(config.updateCheckIntervalMs, 60000))

package/lib/telemetry.js

@@ -0,0 +1,163 @@
+// dsh-remote — 安装级心跳（日活统计）。
+//
+// 目的：npm 下载量只能证明"有人下载"，GitHub clone 里混着 CI 与爬虫，
+// 都无法回答"多少人真的在用、用的是哪一版、留在哪个平台"。这里上报一个
+// **最小字段的心跳**，让作者能算出去重日活 / 版本分布 / 平台分布 / 留存。
+//
+// ── 隐私边界（改这个文件前先读）──────────────────────────────────────────
+// 1) 上报的是伪名：`idHash = HMAC-SHA256(SALT, installId)[:32]`。
+//    原始 installId **绝不出机器**，服务端拿到的是本插件专属伪名，
+//    无法与其他数据交叉关联（installId 本身是随机 UUID，不含任何机器信息）。
+// 2) installId 存在 `<DSH_HOME>/.dsh-remote-install-id`，**不在插件目录**：
+//    插件目录会被 pnpm 重装覆盖，放在那里会让同一台机器每次升级都换身份，
+//    把 1 个人算成 N 个。DSH_HOME 跨重装稳定。
+// 3) 字段白名单固定为 {idHash, version, platform, arch, node}。
+//    本插件能拿到 SSH 主机、路径、机器列表——**这些一律不上报**。
+//
+// ── 失败策略 ─────────────────────────────────────────────────────────────
+// 全程静默：任何异常（网络不可达、磁盘只读、端点变更）都只吞掉，
+// 绝不阻塞加载、绝不写日志噪音、绝不重试轰炸。心跳是"尽力而为"，
+// 它失败不能影响用户任何真实功能。
+
+import { createHmac, randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+/** 上报端点（CloudBase HTTP 访问服务）。改域名只需改这一行。 */
+const HEARTBEAT_URL = 'https://gitbolg-d7gmnsrw46e011706-1256429518.ap-shanghai.app.tcloudbase.com/dsh-hb/heartbeat'
+/** 伪名盐：服务端无法反推身份，且换盐即可切断历史关联。 */
+const SALT = 'dsh-remote/telemetry/v1'
+const ID_FILE = '.dsh-remote-install-id'
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+/** 上报超时：心跳是旁路，不能拖慢启动；但也不能太短 —— 实测端点本身
+ *  250~520ms，而 **DSH 启动瞬间的并发初始化会把首帧 fetch 饿到 5s 以上**
+ *  （曾以 5s 超时稳定失败在首启，靠下次启动才补上，等于丢掉当天最早的那批用户）。
+ *  15s 覆盖启动抖动，且因为不 await，慢也不会影响加载。 */
+const TIMEOUT_MS = 15000
+/** 启动后延迟多久再发：避开启动高峰（插件树/路由/服务都在抢事件循环）。
+ *  仍不 await——延迟是为了让心跳真的成功，不是为了让用户等待。 */
+const STARTUP_DELAY_MS = 3000
+/** 两次上报之间的最小间隔（同一天内重复启动不再上报）。 */
+const MIN_INTERVAL_MS = 6 * 60 * 60 * 1000
+
+/** 安装身份的进程内缓存，**按身份文件路径分键**。
+ *  ★ 不能只用一个全局变量：同一进程内出现第二个 DSH_HOME（隔离沙箱、
+ *  测试夹具、desktop 与 cli 并存）时会串号，把 A 的 id 当成 B 的，
+ *  日活与装机量一起失真。DSH 官方的 anonymous-user-id 同样是按路径 memo。 */
+const idCache = new Map()
+
+/**
+ * 读取或创建本安装的随机身份（稳定 UUID，存 DSH_HOME）。
+ * 磁盘只读等异常时返回内存生成的临时身份：日活会多算一次，但绝不报错。
+ * @param home - DSH_HOME 绝对路径。
+ */
+export function installId(home) {
+  const file = path.join(home, ID_FILE)
+  const cached = idCache.get(file)
+  if (cached) return cached
+
+  try {
+    const existing = readFileSync(file, 'utf8').trim()
+    if (UUID_RE.test(existing)) {
+      idCache.set(file, existing)
+      return existing
+    }
+  } catch { /* 不存在或不可读 → 下面创建 */ }
+  const created = randomUUID()
+  try {
+    mkdirSync(home, { recursive: true })
+    writeFileSync(file, `${created}\n`, 'utf8')
+  } catch { /* 只读也不影响本次运行 */ }
+  idCache.set(file, created)
+  return created
+}
+
+/** 稳定的匿名伪名（32 位 hex）。原始 id 不离开本进程。 */
+export function pseudonym(home) {
+  return createHmac('sha256', SALT).update(installId(home)).digest('hex').slice(0, 32)
+}
+
+/** 是否到该上报了（进程内节流，避免每次工具调用都发）。 */
+let lastSentAt = 0
+
+/**
+ * 发送一次心跳。**永不抛出**，也永不返回可导致分支的失败态：
+ * 调用方不需要 try/catch，心跳成功与否都不应改变任何行为。
+ * @param home - DSH_HOME 绝对路径。
+ * @param version - 运行中的插件版本（用 LOADED_VERSION，即真正在跑的代码版本）。
+ * @param options.delayMs - 发送前延迟（默认 {@link STARTUP_DELAY_MS}）；
+ *   避开启动高峰。测试可传 0。
+ * @returns 是否真的发出了请求（仅用于测试与自检）。
+ */
+export async function sendHeartbeat(home, version, options = {}) {
+  const now = Date.now()
+  if (now - lastSentAt < MIN_INTERVAL_MS) return false
+
+  const delayMs = options.delayMs === undefined ? STARTUP_DELAY_MS : Math.max(0, options.delayMs)
+  // 先占位，防止并发触发重复上报（本插件是单进程，够用）
+  lastSentAt = now
+  try {
+    if (delayMs) await new Promise((r) => {
+      const t = setTimeout(r, delayMs)
+      if (typeof t.unref === 'function') t.unref()
+    })
+    const body = JSON.stringify({
+      idHash: pseudonym(home),
+      version: String(version || '0.0.0'),
+      platform: process.platform,
+      arch: process.arch,
+      node: process.versions.node,
+    })
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+    try {
+      await fetch(HEARTBEAT_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: controller.signal,
+      })
+    } finally {
+      clearTimeout(timer)
+    }
+    return true
+  } catch {
+    // 网络不可达 / 端点变更 / 被拦截：一律忽略。
+    // 允许下次重试：回滚节流，避免一次失败就把身份静默六个小时。
+    lastSentAt = 0
+    return false
+  }
+}
+
+/** 清空节流与缓存（仅测试用）。 */
+export function _resetForTest() {
+  lastSentAt = 0
+  idCache.clear()
+}
+
+/** 心跳是否已配置（供设置页显示；不含端点本身）。 */
+export function heartbeatEnabled() {
+  return typeof HEARTBEAT_URL === 'string' && HEARTBEAT_URL.startsWith('https://')
+}
+
+/** 供自检/文档使用的端点（不涉密，可公开）。 */
+export function heartbeatUrl() {
+  return HEARTBEAT_URL
+}
+
+/** 身份文件是否已存在（自检用，不创建）。 */
+export function hasPersistedId(home) {
+  try {
+    return UUID_RE.test(readFileSync(path.join(home, ID_FILE), 'utf8').trim())
+  } catch {
+    return false
+  }
+}
+
+/** 供自检：确认 installId 落盘位置（不创建）。 */
+export function installIdPath(home) {
+  return path.join(home, ID_FILE)
+}
+
+// existsSync 仅用于自检导出，避免被 tree-shake 掉误报
+export { existsSync as _existsSync }

package/lib/update.js

@@ -8,15 +8,24 @@
 //   • checkLatestVersion() — query the npm registry for the `latest` dist-tag;
 //   • applyUpdate() — download the tarball, extract package/{lib,package.json,
 //     cordis.patch.yml} with a minimal tar reader, verify the version, then
-//     atomically copy over the installed files. A `.dsh-remote-updated` marker
-//     is written so the UI can tell the user to reload.
+//     replace the installed files atomically (temp file + rename, never a
+//     half-written lib/*.js). A `.dsh-remote-updated` marker records the version
+//     that landed; the host half removes it once that version is the code it is
+//     actually running (see LOADED_VERSION), so the marker means "restart still
+//     required" rather than "an update once happened".
+//   • reloadSelf() — swap the RUNNING host half to the code now on disk: drop
+//     Node's module caches for this package's own files, then dispose + re-init
+//     the loader entry so apply() runs again from the fresh module. Without it
+//     an update only takes effect on the next process start, which is what left
+//     the served client half newer than the loaded host half.
 //
 // Every failure aborts without touching the installed files (a bad download or
 // a version mismatch must never break the running plugin).
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const NPM_PACKAGE = 'dsh-remote'
 const REGISTRY_URL = 'https://registry.npmjs.org/' + NPM_PACKAGE + '/latest'
@@ -40,6 +49,17 @@ export function readVersion() {
   }
 }
 
+/** Version of the code this process actually loaded (snapshot at import time).
+ *  `readVersion()` reads package.json from disk, so after an update lands it
+ *  reports the NEW version while the running module is still the old one —
+ *  comparing the two is the only way to tell "applied" from "active". */
+export const LOADED_VERSION = readVersion()
+
+/** Package version currently on disk (may be newer than {@link LOADED_VERSION}). */
+export function diskVersion() {
+  return readVersion()
+}
+
 /** Compare dotted versions; returns true when a > b. */
 export function gtVersion(a, b) {
   const pa = String(a || '').split('.').map((n) => parseInt(n, 10) || 0)
@@ -96,9 +116,10 @@ function parseTar(buf) {
  * installed files untouched).
  * @param targetVersion - exact npm version to install (e.g. "0.8.0").
  */
-export async function applyUpdate(targetVersion) {
+export async function applyUpdate(targetVersion, options = {}) {
   const tarballUrl = `https://registry.npmjs.org/${NPM_PACKAGE}/-/${NPM_PACKAGE}-${targetVersion}.tgz`
-  const dir = selfDir()
+  const dir = options.dir || selfDir()
+  const doFetch = options.fetchImpl || fetch
   const tmpRoot = path.join(dir, `.dsh-remote-update-${Date.now()}`)
   const tmpPkg = path.join(tmpRoot, 'package')
   try {
@@ -106,7 +127,7 @@ export async function applyUpdate(targetVersion) {
     const timer = setTimeout(() => controller.abort(), 60000)
     let res
     try {
-      res = await fetch(tarballUrl, { signal: controller.signal })
+      res = await doFetch(tarballUrl, { signal: controller.signal })
     } finally {
       clearTimeout(timer)
     }
@@ -135,20 +156,34 @@ export async function applyUpdate(targetVersion) {
     // break the next boot — check the file size and that it is not empty).
     const newIndex = path.join(tmpPkg, 'lib', 'index.js')
     if (!existsSync(newIndex) || statSize(newIndex) < 100) throw new Error('tarball missing lib/index.js')
-    // Atomically swap: copy fresh files over the installed ones.
+    // Swap the installed files one at a time: atomic, and idempotent.
+    //
+    // Atomicity (temp file + rename) is not cosmetic here — since the browser
+    // half is hot-swapped by dsh-client-hmr, which stat-polls lib/client.js
+    // every 500 ms, a torn write would be re-hashed and served mid-copy.
+    // Skipping byte-identical files keeps a re-apply of the same version from
+    // churning mtimes (and the host half from reloading for nothing).
     const installLib = path.join(dir, 'lib')
     const tmpLib = path.join(tmpPkg, 'lib')
+    const changed = []
+    const install = (src, dest) => {
+      const bytes = readFileSync(src)
+      if (sameFileContent(dest, bytes)) return
+      try { mkdirSync(path.dirname(dest), { recursive: true }) } catch {}
+      writeFileAtomic(dest, bytes)
+      changed.push(path.relative(dir, dest).split(path.sep).join('/'))
+    }
     for (const name of readdirSafe(tmpLib)) {
       if (!name.endsWith('.js')) continue
       const src = path.join(tmpLib, name)
-      if (existsSync(src)) copyFileSync(src, path.join(installLib, name))
+      if (existsSync(src)) install(src, path.join(installLib, name))
     }
     for (const rel of ['package.json', 'cordis.patch.yml']) {
       const src = path.join(tmpPkg, rel)
-      if (existsSync(src)) copyFileSync(src, path.join(dir, rel))
+      if (existsSync(src)) install(src, path.join(dir, rel))
     }
     writeFileSync(path.join(dir, '.dsh-remote-updated'), String(targetVersion))
-    return { ok: true, to: targetVersion }
+    return { ok: true, to: targetVersion, changed }
   } catch (err) {
     throw new Error('update failed: ' + ((err && err.message) || err))
   } finally {
@@ -174,6 +209,145 @@ function readdirSafe(dir) {
   }
 }
 
+/**
+ * Write `data` to `dest` atomically: the bytes land in a sibling temp file and
+ * are then renamed over the target, so a concurrent reader (the client-half HMR
+ * poll, or the next boot) never observes a truncated file. Falls back to an
+ * in-place copy if the platform refuses the replace, and never leaves the temp
+ * file behind.
+ * @param dest - absolute destination path.
+ * @param data - bytes to write.
+ */
+export function writeFileAtomic(dest, data) {
+  const tmp = `${dest}.dsh-tmp-${process.pid}-${Date.now().toString(36)}`
+  writeFileSync(tmp, data)
+  try {
+    renameSync(tmp, dest)
+    return
+  } catch {
+    try {
+      copyFileSync(tmp, dest)
+    } finally {
+      try { rmSync(tmp, { force: true }) } catch {}
+    }
+  }
+}
+
+/** Whether the file at `p` already holds exactly `bytes` (missing/short → false). */
+function sameFileContent(p, bytes) {
+  try {
+    return readFileSync(p).equals(bytes)
+  } catch {
+    return false
+  }
+}
+
+// ── hot swap of the running host half ─────────────────────────────────────
+
+/** Loader entry ids this package can own. */
+const SELF_ENTRY_NAMES = ['dsh-remote']
+
+/**
+ * Find our own loader entry (by id, then by module specifier). Returns undefined
+ * when the tree does not contain us (e.g. a test loader, or a renamed row).
+ * @param loader - the cordis Loader service (`ctx.loader`).
+ */
+function findSelfEntry(loader) {
+  let entries = []
+  try {
+    entries = [...(loader?.entries?.() ?? [])]
+  } catch {
+    return undefined
+  }
+  for (const want of SELF_ENTRY_NAMES) {
+    const byId = entries.find((entry) => entry?.options?.id === want)
+    if (byId) return byId
+  }
+  for (const want of SELF_ENTRY_NAMES) {
+    const byName = entries.find((entry) => entry?.options?.name === want)
+    if (byName) return byName
+  }
+  return undefined
+}
+
+/**
+ * Drop Node's module caches for this package's own files, so the next import of
+ * the plugin actually re-reads disk instead of handing back the cached module.
+ * Both caches matter: the ESM `loadCache` (a plain Map on Node 22/23, a
+ * `LoadCache extends Map` on Node 24 — hence the explicit `Map.prototype` calls)
+ * and, for CJS modules pulled in through `import()`, `require.cache`.
+ * @param loader - the cordis Loader service.
+ * @param dir - package directory whose `lib/` to evict (defaults to this
+ *   package's own install dir; overridable so the swap can be exercised against
+ *   a fixture install).
+ * @returns how many ESM entries were dropped.
+ */
+export function clearSelfModuleCache(loader, dir = selfDir()) {
+  const libDir = path.join(dir, 'lib')
+  const loadCache = loader?.internal?.loadCache
+  const req = (() => {
+    try { return createRequire(import.meta.url) } catch { return undefined }
+  })()
+  let cleared = 0
+  for (const name of readdirSafe(libDir)) {
+    if (!name.endsWith('.js')) continue
+    const url = pathToFileURL(path.join(libDir, name)).href
+    try {
+      if (loadCache && Map.prototype.has.call(loadCache, url)) {
+        Map.prototype.delete.call(loadCache, url)
+        cleared += 1
+      }
+    } catch {}
+    try {
+      const file = fileURLToPath(url)
+      if (req?.cache && req.cache[file]) delete req.cache[file]
+    } catch {}
+  }
+  return cleared
+}
+
+/**
+ * Swap the RUNNING host half to the code now on disk: clear the module caches
+ * for our own files, dispose our loader entry (tools, JSON routes, SSH pools and
+ * every `ctx.effect` disposer go with the fiber), then re-init it so `apply()`
+ * runs again from the freshly imported module.
+ *
+ * Callers must not depend on this plugin after a successful reload — the fiber
+ * that served the current request is gone. Schedule it (see
+ * {@link scheduleSelfReload}) rather than awaiting it from a request handler.
+ * @param loader - the cordis Loader service (`ctx.loader`).
+ * @returns a small result object; never throws.
+ */
+export async function reloadSelf(loader) {
+  const entry = findSelfEntry(loader)
+  if (!entry) return { ok: false, reason: 'own loader entry not found' }
+  try {
+    const cleared = clearSelfModuleCache(loader)
+    if (typeof entry._dispose === 'function') await entry._dispose()
+    else if (typeof entry.dispose === 'function') await entry.dispose()
+    else return { ok: false, reason: 'entry exposes no dispose hook' }
+    await entry.init()
+    return { ok: true, cleared }
+  } catch (err) {
+    return { ok: false, reason: String((err && err.message) || err) }
+  }
+}
+
+/**
+ * Fire-and-forget {@link reloadSelf} after a short delay, so the caller can
+ * finish answering an HTTP request (or an update check) before its own module is
+ * torn down. Failures are swallowed: a failed swap leaves the running code in
+ * place, which is the pre-hot-update behaviour, not a crash.
+ * @param loader - the cordis Loader service.
+ * @param delayMs - grace period before the swap (default 300 ms).
+ * @returns true when the swap was scheduled.
+ */
+export function scheduleSelfReload(loader, delayMs = 300) {
+  const timer = setTimeout(() => { void reloadSelf(loader).catch(() => {}) }, Math.max(0, delayMs))
+  if (typeof timer.unref === 'function') timer.unref()
+  return true
+}
+
 /** Write the persisted update-mode override (settings UI). */
 export function persistUpdateMode(mode) {
   if (!['manual', 'auto', 'off'].includes(mode)) return false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "description": "Remote-work assistant for DeepSeek Harness: connect SSH (password/key/agent/keyboard-interactive/proxy jump), pick a remote workspace, operate on it with 20 rw_* tools (incl. rw_edit/rw_stat/rw_mkdir/rw_remove/rw_move/rw_forward), conflict-aware mirror sync, port forwarding, optional side-bar remote file editing, audit log, keychain passwords.",
   "license": "MIT",
   "author": "flymysql <flyphp@outlook.com>",