dsh-session-manager 0.7.1 → 0.7.3

package/lib/index.js

@@ -22,13 +22,14 @@
  * The compatibility adapter normalizes service access and list snapshots.
  * Optional live-writer/coordinator internals are guarded before mutation.
  */
+import { existsSync, readFileSync, writeFileSync, rmSync, renameSync } from "node:fs";
 import { lstat, mkdir, readdir, realpath, rename, rm } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { createAnnotationStore } from "./annotation-store.js";
 import { createWorkspaceArchiveStore, assertWorkspaceId } from "./workspace-archive-store.js";
-import { createDshAdapter, normalizeSessionHeader, compareSemver } from "./compat/dsh-adapter.js";
-import { ARTIFACT_NAMES, assertSessionId, assertSessionDirectory, encodeSessionSegment, parseSessionGenerationFromFilename, readSessionHeader, readSessionFile, writeTempFile, replaceSessionFile } from "./session-files.js";
+import { createDshAdapter, normalizeSessionHeader, compareSemver, detectPluginSource, isHmrActive, resolveProfileDir } from "./compat/dsh-adapter.js";
+import { ARTIFACT_NAMES, assertSessionId, assertSessionDirectory, candidateSessionDirs, encodeFsSessionSegment, decodeFsSessionSegment, encodeProjectSegment, encodeSessionSegment, parseSessionGenerationFromFilename, readSessionHeader, readSessionFile, writeTempFile, replaceSessionFile } from "./session-files.js";
 
 export const name = "dsh-session-manager";
 
@@ -125,10 +126,16 @@ const scanSessionHeaders = async (persistence, dshHome) => {
   }
   const result = () => ({ headers, complete: listed && errors.length === 0, errors });
   // Skip known files before fopen; retain the orphan/raw-id compatibility path.
+  // Only add canonical session directories that do not start and end with "--"
+  // to avoid colliding with legacy projectKey candidates (e.g. "--s1--").
   const knownDirs = new Set();
   for (const id of seen) {
-    knownDirs.add(id);
-    knownDirs.add(encodeSessionSegment(id));
+    try {
+      const canonical = encodeFsSessionSegment(id);
+      if (!canonical.startsWith("--") || !canonical.endsWith("--")) {
+        knownDirs.add(canonical);
+      }
+    } catch (_) {}
   }
   if (typeof dshHome !== "function") return result();
   const root = dshHome("sessions");
@@ -150,7 +157,7 @@ const scanSessionHeaders = async (persistence, dshHome) => {
       for (const filename of ARTIFACT_NAMES) {
         try {
           const header = await readSessionHeader(join(root, proj.name, entry.name, filename));
-          if (![header.id, encodeSessionSegment(header.id)].includes(entry.name)) {
+          if (!candidateSessionDirs(header.id).includes(entry.name)) {
             throw new Error("会话目录与 header id 不一致");
           }
           if (!seen.has(header.id)) { seen.add(header.id); headers.push(header); }
@@ -168,9 +175,199 @@ const scanSessionHeaders = async (persistence, dshHome) => {
 
 const listSessionHeaders = async (persistence, dshHome) => (await scanSessionHeaders(persistence, dshHome)).headers;
 
+const UPDATE_STATUS_FILE = ".dsh-session-manager-update.json";
+const STALE_EXTERNAL_TASK_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes fallback for dead external processes
+const HEARTBEAT_STALE_TIMEOUT_MS = 3 * 60 * 1000; // 3 minutes without heartbeat for external processes
+
+const TRUSTED_REGISTRIES = new Set([
+  "https://registry.npmjs.org",
+  "https://registry.npmmirror.com",
+  "http://127.0.0.1:4873",
+  "http://localhost:4873"
+]);
+
+function normalizeRegistryUrl(url) {
+  if (!url || typeof url !== "string") return "";
+  const trimmed = url.trim();
+  if (!trimmed) return "";
+  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+
+function resolveTrustedRegistry(requested, envRegistry) {
+  const normEnv = normalizeRegistryUrl(envRegistry);
+  const normReq = normalizeRegistryUrl(requested);
+
+  if (normReq) {
+    if (TRUSTED_REGISTRIES.has(normReq) || (normEnv && normReq === normEnv)) {
+      return normReq;
+    }
+    return null;
+  }
+
+  if (normEnv && (TRUSTED_REGISTRIES.has(normEnv) || normEnv.length > 0)) {
+    return normEnv;
+  }
+
+  return "https://registry.npmjs.org";
+}
+
+const ACTIVE_UPDATE_TASK_KEY = Symbol.for("dsh-session-manager.activeUpdateTask");
+
+function getActiveTask() {
+  return globalThis[ACTIVE_UPDATE_TASK_KEY] || null;
+}
+
+function setActiveTask(task) {
+  if (task) {
+    globalThis[ACTIVE_UPDATE_TASK_KEY] = task;
+  } else {
+    delete globalThis[ACTIVE_UPDATE_TASK_KEY];
+  }
+}
+
+function releaseActiveTask(taskId) {
+  const cur = getActiveTask();
+  if (cur && (!taskId || cur.taskId === taskId)) {
+    setActiveTask(null);
+  }
+}
+
+function isPidAlive(pid) {
+  if (typeof pid !== "number" || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+function getUpdateStatusFilePath(profileDir) {
+  return profileDir ? join(profileDir, UPDATE_STATUS_FILE) : null;
+}
+
+function writeUpdateStatus(profileDir, statusObj) {
+  const filePath = getUpdateStatusFilePath(profileDir);
+  if (!filePath || !statusObj || typeof statusObj !== "object") return;
+  statusObj.updatedAt = Date.now();
+  try {
+    if (existsSync(filePath)) {
+      const existing = JSON.parse(readFileSync(filePath, "utf8"));
+      if (existing && existing.taskId && statusObj.taskId && existing.taskId !== statusObj.taskId) {
+        if (isDiskTaskActive(existing) && (existing.startedAt || 0) > (statusObj.startedAt || 0)) {
+          return;
+        }
+      }
+    }
+  } catch (_) {}
+  const tmpPath = filePath + ".tmp." + Date.now();
+  try {
+    writeFileSync(tmpPath, JSON.stringify(statusObj, null, 2), "utf8");
+    try {
+      renameSync(tmpPath, filePath);
+    } catch {
+      try { rmSync(filePath, { force: true }); } catch (_) {}
+      renameSync(tmpPath, filePath);
+    }
+  } catch (_) {
+    try { if (existsSync(tmpPath)) rmSync(tmpPath, { force: true }); } catch (_) {}
+  }
+}
+
+function readUpdateStatus(profileDir) {
+  const filePath = getUpdateStatusFilePath(profileDir);
+  if (!filePath) return null;
+  try {
+    if (existsSync(filePath)) {
+      return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+  } catch (_) { /* best-effort */ }
+  return null;
+}
+
+const ACTIVE_TASK_STATUSES = new Set([
+  "preparing",
+  "removing",
+  "removed",
+  "installing",
+  "verifying",
+  "rolling-back"
+]);
+
+function isDiskTaskActive(statusObj) {
+  if (!statusObj || typeof statusObj !== "object") return false;
+  if (!ACTIVE_TASK_STATUSES.has(statusObj.status)) return false;
+
+  // If status was recorded by the current process, consult in-memory task
+  if (statusObj.pid === process.pid) {
+    const inMem = getActiveTask();
+    if (!inMem || inMem.taskId !== statusObj.taskId) {
+      return false;
+    }
+    return true;
+  }
+
+  // If status was recorded by another process, check if PID is alive
+  if (typeof statusObj.pid === "number") {
+    if (!isPidAlive(statusObj.pid)) {
+      return false;
+    }
+  }
+
+  const lastActive = typeof statusObj.updatedAt === "number"
+    ? statusObj.updatedAt
+    : (typeof statusObj.startedAt === "number" ? statusObj.startedAt : 0);
+  if (Date.now() - lastActive > HEARTBEAT_STALE_TIMEOUT_MS) return false;
+  return true;
+}
+
+function isTaskActive(statusObj) {
+  return isDiskTaskActive(statusObj);
+}
+
+function verifyInstalledPackage(profileDir, expectedVersion) {
+  if (!profileDir) {
+    return { ok: false, error: "无法定位插件运行 profile 目录，无法进行安装校验" };
+  }
+  const pkgDir = join(profileDir, "node_modules", "dsh-session-manager");
+  const pkgFile = join(pkgDir, "package.json");
+  const entryIndex = join(pkgDir, "lib", "index.js");
+  const entryClient = join(pkgDir, "lib", "client.js");
+
+  if (!existsSync(pkgFile)) {
+    return { ok: false, error: "未找到安装目录或 package.json: " + pkgFile };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+  } catch (err) {
+    return { ok: false, error: "package.json 解析失败: " + safeErrorMessage(err) };
+  }
+  if (!pkg || typeof pkg !== "object") {
+    return { ok: false, error: "package.json 内容无效" };
+  }
+  if (pkg.name !== "dsh-session-manager") {
+    return { ok: false, error: "安装包名称不符: 预期 dsh-session-manager，实际 " + pkg.name };
+  }
+  if (expectedVersion && expectedVersion !== "latest" && pkg.version !== expectedVersion) {
+    return {
+      ok: false,
+      version: pkg.version,
+      error: "安装版本不匹配: 预期 " + expectedVersion + "，实际安装 " + pkg.version
+    };
+  }
+  if (!existsSync(entryIndex)) {
+    return { ok: false, version: pkg.version, error: "缺少服务端入口文件: lib/index.js" };
+  }
+  if (!existsSync(entryClient)) {
+    return { ok: false, version: pkg.version, error: "缺少客户端入口文件: lib/client.js" };
+  }
+  return { ok: true, version: pkg.version };
+}
+
 export function apply(ctx) {
   try {
-    const buildId = "dsh-session-manager v0.7.1 (workspace-archive)";
+    const buildId = "dsh-session-manager v0.7.3 (workspace-archive)";
     if (typeof ctx?.logger?.info === "function") ctx.logger.info(buildId);
     else if (typeof console !== "undefined" && console?.info) console.info(buildId);
   } catch (_) { /* ignore logging failures */ }
@@ -1252,14 +1449,19 @@ ${rest}`, "utf8");
       catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
       for (const proj of projects) {
         if (!proj.isDirectory() || proj.isSymbolicLink()) continue;
-        for (const candidate of [encodeSessionSegment(sessionId), sessionId]) {
+        for (const candidate of candidateSessionDirs(sessionId)) {
           const dir = join(root, proj.name, candidate);
           try { await assertSessionDirectory(root, dir, sessionId); }
           catch (error) { if (error.code === "ENOENT") continue; throw error; }
           for (const filename of ARTIFACT_NAMES) {
             try {
               const artifact = await read(join(dir, filename));
-              if (artifact.meta.id !== sessionId) throw new Error("会话工件 header id 与请求不一致");
+              if (artifact.meta.id !== sessionId) {
+                if (candidate === candidateSessionDirs(sessionId)[0]) {
+                  throw new Error("会话工件 header id 与请求不一致");
+                }
+                break;
+              }
               return artifact;
             } catch (error) { if (error.code !== "ENOENT") throw error; }
           }
@@ -2013,14 +2215,91 @@ ${rest}`, "utf8");
           return send(res, 200, { ok: true, result });
         }
         if (req.method === "GET" && path === "/update/check") {
-          const currentVersion = adapter.pluginVersion() || "0.7.1";
-          let latestVersion = currentVersion;
+          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          const runningVersion = currentVersion;
+          let installedVersion = runningVersion;
+          const profileDir = resolveProfileDir(adapter, ctx);
+          if (profileDir) {
+            const diskCheck = verifyInstalledPackage(profileDir);
+            if (diskCheck.ok && diskCheck.version) {
+              installedVersion = diskCheck.version;
+            }
+          }
+          const pm = adapter.pluginManager;
+          let bundles = [];
+          if (typeof pm?.listBundles === "function") {
+            try { bundles = await pm.listBundles(); } catch (_) {}
+          }
+          const source = detectPluginSource(adapter, ctx, bundles);
+          if (source === "linked") {
+            return send(res, 200, {
+              ok: true,
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion: runningVersion,
+                hasUpdate: false,
+                source: "linked",
+                message: "开发模式（本地链接），请手动修改或拉取代码"
+              }
+            });
+          }
+          if (source === "github") {
+            return send(res, 200, {
+              ok: true,
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion: runningVersion,
+                hasUpdate: false,
+                source: "github",
+                message: "通过 Git/GitHub 安装，请通过 DSH 插件市场或 git 更新"
+              }
+            });
+          }
+          if (source === "installation") {
+            return send(res, 200, {
+              ok: true,
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion: runningVersion,
+                hasUpdate: false,
+                source: "installation",
+                message: "系统内置插件，无法独立更新"
+              }
+            });
+          }
+          if (source === "unknown") {
+            return send(res, 200, {
+              ok: true,
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion: runningVersion,
+                hasUpdate: false,
+                source: "unknown",
+                message: "无法确认插件安装来源，为保证安全已禁止自动更新"
+              }
+            });
+          }
+          let latestVersion = installedVersion;
           let hasUpdate = false;
           try {
+            const envRegistry = process.env.NPM_CONFIG_REGISTRY?.trim();
             const requestedRegistry = url.searchParams.get("registry")?.trim();
-            const registry = (requestedRegistry && /^https?:\/\//i.test(requestedRegistry))
-              ? requestedRegistry
-              : (process.env.NPM_CONFIG_REGISTRY || "https://registry.npmjs.org");
+            const registry = resolveTrustedRegistry(requestedRegistry, envRegistry);
+            if (!registry) {
+              return send(res, 400, {
+                ok: false,
+                code: "untrusted-registry",
+                error: "不受信任的 npm 安装源: " + requestedRegistry
+              });
+            }
             const base = registry.endsWith("/") ? registry : registry + "/";
             const pkgUrl = new URL("dsh-session-manager/latest", base).toString();
             const controller = new AbortController();
@@ -2039,17 +2318,33 @@ ${rest}`, "utf8");
             } finally {
               clearTimeout(timer);
             }
-            hasUpdate = compareSemver(latestVersion, currentVersion) > 0;
+            hasUpdate = compareSemver(latestVersion, installedVersion) > 0;
+            const restartRequired = compareSemver(installedVersion, runningVersion) > 0;
             return send(res, 200, {
               ok: true,
-              result: { currentVersion, latestVersion, hasUpdate }
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion,
+                hasUpdate,
+                restartRequired,
+                source: "npm"
+              }
             });
           } catch (err) {
             return send(res, 200, {
               ok: false,
               code: "update-check-failed",
               error: "检查更新失败: " + safeErrorMessage(err),
-              result: { currentVersion, latestVersion: currentVersion, hasUpdate: false }
+              result: {
+                runningVersion,
+                currentVersion: runningVersion,
+                installedVersion,
+                latestVersion: installedVersion,
+                hasUpdate: false,
+                source: "npm"
+              }
             });
           }
         }
@@ -2058,38 +2353,650 @@ ${rest}`, "utf8");
           if (rawVersion && !/^[a-zA-Z0-9_.-]+$/.test(rawVersion)) {
             return send(res, 400, { ok: false, code: "bad-request", error: "Invalid version format" });
           }
-          const targetVersion = rawVersion || "latest";
-          const spec = "dsh-session-manager@" + targetVersion;
-          const registry = typeof body?.registry === "string" && /^https?:\/\//i.test(body.registry.trim()) ? body.registry.trim() : "";
+
           const pm = adapter.pluginManager;
-          if (pm && typeof pm.installBundle === "function") {
+          if (!pm || typeof pm.installBundle !== "function") {
+            return send(res, 501, {
+              ok: false,
+              code: "plugin-manager-unavailable",
+              error: "当前宿主环境未提供 PluginManager 安装服务，请通过 DSH 插件市场或命令行更新"
+            });
+          }
+
+          const profileDir = resolveProfileDir(adapter, ctx);
+
+          // P1-3: Concurrency Mutex check & immediate synchronous acquisition
+          const inMemoryTask = getActiveTask();
+          if (inMemoryTask) {
+            return send(res, 409, {
+              ok: false,
+              code: "update-in-progress",
+              error: "已有正在执行的更新任务 (" + inMemoryTask.taskId + ")，请勿重复操作",
+              taskId: inMemoryTask.taskId
+            });
+          }
+          const diskStatus = readUpdateStatus(profileDir);
+          if (isDiskTaskActive(diskStatus)) {
+            return send(res, 409, {
+              ok: false,
+              code: "update-in-progress",
+              error: "已有正在执行的更新任务 (" + diskStatus.taskId + ")，请勿重复操作",
+              taskId: diskStatus.taskId
+            });
+          }
+
+          const taskId = (typeof body?.taskId === "string" && body.taskId.trim())
+            ? body.taskId.trim()
+            : ("update-" + Date.now() + "-" + randomBytes(4).toString("hex"));
+
+          const taskStartedAt = Date.now();
+          const taskRecord = {
+            taskId,
+            startedAt: taskStartedAt,
+            profileDir,
+            pid: process.pid,
+            targetVersion: rawVersion || "latest"
+          };
+          setActiveTask(taskRecord);
+
+          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          let installedVersion = currentVersion;
+          if (profileDir) {
+            const pkgFile = join(profileDir, "node_modules", "dsh-session-manager", "package.json");
+            if (existsSync(pkgFile)) {
+              const diskCheck = verifyInstalledPackage(profileDir);
+              if (diskCheck.ok && diskCheck.version) {
+                installedVersion = diskCheck.version;
+              } else {
+                releaseActiveTask(taskId);
+                return send(res, 500, {
+                  ok: false,
+                  code: "disk-verify-failed",
+                  error: "无法确认已安装版本，磁盘插件目录异常: " + (diskCheck?.error || "package.json 校验失败"),
+                  taskId
+                });
+              }
+            }
+          }
+
+          const targetVersion = rawVersion || "latest";
+          let resolvedTargetVersion = (targetVersion !== "latest") ? targetVersion : null;
+          const envRegistry = process.env.NPM_CONFIG_REGISTRY?.trim();
+          const requestedRegistry = typeof body?.registry === "string" ? body.registry.trim() : "";
+          const registry = resolveTrustedRegistry(requestedRegistry, envRegistry);
+          if (!registry) {
+            releaseActiveTask(taskId);
+            return send(res, 400, {
+              ok: false,
+              code: "untrusted-registry",
+              error: "不受信任的 npm 安装源: " + requestedRegistry
+            });
+          }
+          const forwardRegistry = (requestedRegistry && requestedRegistry !== "https://registry.npmjs.org")
+            ? registry
+            : (envRegistry ? registry : "");
+          const isHmr = isHmrActive(adapter, ctx);
+          const prevRegistry = process.env.NPM_CONFIG_REGISTRY;
+
+          let heartbeatTimer = setInterval(() => {
             try {
-              const prevRegistry = process.env.NPM_CONFIG_REGISTRY;
-              if (registry) {
-                process.env.NPM_CONFIG_REGISTRY = registry;
+              const curStatus = readUpdateStatus(profileDir);
+              if (curStatus && curStatus.taskId === taskId && ACTIVE_TASK_STATUSES.has(curStatus.status)) {
+                curStatus.updatedAt = Date.now();
+                writeUpdateStatus(profileDir, curStatus);
+              }
+            } catch (_) {}
+          }, 10000);
+          if (typeof heartbeatTimer?.unref === "function") {
+            heartbeatTimer.unref();
+          }
+
+          try {
+            // P1-4: Source check
+            let bundles = [];
+            if (typeof pm?.listBundles === "function") {
+              try { bundles = await pm.listBundles(); } catch (_) {}
+            }
+            const source = detectPluginSource(adapter, ctx, bundles);
+            if (source === "linked" || source === "github" || source === "installation") {
+              releaseActiveTask(taskId);
+              return send(res, 400, {
+                ok: false,
+                code: "source-protected",
+                error: "当前插件为 " + source + " 安装来源，无法通过 npm 覆盖更新"
+              });
+            }
+            if (source === "unknown") {
+              releaseActiveTask(taskId);
+              return send(res, 400, {
+                ok: false,
+                code: "source-unknown",
+                error: "无法确认插件安装来源，已禁止自动更新以防破坏环境"
+              });
+            }
+
+            if (!resolvedTargetVersion) {
+              try {
+                const regUrl = registry || process.env.NPM_CONFIG_REGISTRY || "https://registry.npmjs.org";
+                const base = regUrl.endsWith("/") ? regUrl : regUrl + "/";
+                const pkgUrl = new URL("dsh-session-manager/latest", base).toString();
+                const ctrl = new AbortController();
+                const timer = setTimeout(() => ctrl.abort(), 4000);
+                try {
+                  const resp = await fetch(pkgUrl, { signal: ctrl.signal, headers: { accept: "application/json" } });
+                  if (resp.ok) {
+                    const d = await resp.json();
+                    if (d && typeof d.version === "string") {
+                      resolvedTargetVersion = d.version;
+                    }
+                  }
+                } finally {
+                  clearTimeout(timer);
+                }
+              } catch (_) { /* fallback to outcome.version after install */ }
+            }
+
+            const baselineVersion = installedVersion || currentVersion;
+
+            if (resolvedTargetVersion && baselineVersion && baselineVersion !== "unknown") {
+              const cmp = compareSemver(resolvedTargetVersion, baselineVersion);
+              if (cmp === 0) {
+                // If target equals baseline:
+                // Check if already installed on disk pending restart or refresh
+                if (compareSemver(installedVersion, currentVersion) > 0) {
+                  releaseActiveTask(taskId);
+                  const application = isHmr ? "refresh-required" : "restart-required";
+                  writeUpdateStatus(profileDir, {
+                    taskId,
+                    status: "completed",
+                    targetVersion: installedVersion,
+                    currentVersion,
+                    application,
+                    alreadyInstalled: true,
+                    pid: process.pid,
+                    completedAt: Date.now()
+                  });
+                  return send(res, 200, {
+                    ok: true,
+                    result: {
+                      application,
+                      spec: "dsh-session-manager@" + installedVersion,
+                      version: installedVersion,
+                      taskId,
+                      alreadyInstalled: true
+                    }
+                  });
+                }
+                // Target is equal to running & installed version -> not an upgrade
+                releaseActiveTask(taskId);
+                return send(res, 400, {
+                  ok: false,
+                  code: "not-upgrade",
+                  error: "目标版本 (" + resolvedTargetVersion + ") 不高于当前已安装版本 (" + baselineVersion + ")"
+                });
+              } else if (cmp < 0) {
+                releaseActiveTask(taskId);
+                return send(res, 400, {
+                  ok: false,
+                  code: "not-upgrade",
+                  error: "目标版本 (" + resolvedTargetVersion + ") 低于当前已安装版本 (" + baselineVersion + ")"
+                });
+              }
+            }
+            const spec = "dsh-session-manager@" + (resolvedTargetVersion || targetVersion);
+            const oldSpec = "dsh-session-manager@" + currentVersion;
+
+            writeUpdateStatus(profileDir, {
+              taskId,
+              status: "preparing",
+              targetVersion: resolvedTargetVersion || targetVersion,
+              currentVersion,
+              source: "npm",
+              pid: process.pid,
+              startedAt: taskStartedAt
+            });
+
+            if (forwardRegistry) {
+              process.env.NPM_CONFIG_REGISTRY = forwardRegistry;
+            }
+
+            // Capture locals before any potential scope teardown
+            const localProfileDir = profileDir;
+            const localSpec = spec;
+            const localOldSpec = oldSpec;
+            const localPm = pm;
+            const localTaskId = taskId;
+            const localTargetVersion = targetVersion;
+            const localCurrentVersion = currentVersion;
+            const localRegistry = forwardRegistry;
+            let localResolvedTargetVersion = resolvedTargetVersion;
+
+            // Helper: perform rollback and record state
+            const performRollback = async (triggerError, { newVersionInstalled = false } = {}) => {
+              // Restore registry environment first so rollback is not blocked by custom registry failure
+              if (forwardRegistry) {
+                if (prevRegistry !== undefined) {
+                  process.env.NPM_CONFIG_REGISTRY = prevRegistry;
+                } else {
+                  delete process.env.NPM_CONFIG_REGISTRY;
+                }
+              }
+
+              writeUpdateStatus(localProfileDir, {
+                taskId: localTaskId,
+                status: "rolling-back",
+                targetVersion: localResolvedTargetVersion || localTargetVersion,
+                currentVersion: localCurrentVersion,
+                error: triggerError,
+                pid: process.pid,
+                rollingBackAt: Date.now()
+              });
+
+              // P0-2: In HMR mode, if new version was already installed into profile,
+              // calling installBundle(oldSpec) directly throws "already-installed".
+              // Therefore, we must remove the new version first.
+              let cleanError = null;
+              if (isHmr && newVersionInstalled) {
+                if (typeof localPm.removeBundle === "function") {
+                  try {
+                    const rmOutcome = await localPm.removeBundle("dsh-session-manager");
+                    if (rmOutcome && (rmOutcome.application === "failed" || rmOutcome.application === "cancelled" || rmOutcome.ok === false)) {
+                      cleanError = rmOutcome.error?.message || rmOutcome.error?.code || safeErrorMessage(rmOutcome.error) || ("application: " + rmOutcome.application);
+                    }
+                  } catch (rmErr) {
+                    cleanError = safeErrorMessage(rmErr);
+                  }
+                }
               }
-              let outcome;
+
+              if (cleanError) {
+                const rbDetail = "清理安装失败的新版本失败: " + cleanError;
+                releaseActiveTask(localTaskId);
+                const actualCheck = verifyInstalledPackage(localProfileDir);
+                const installedState = actualCheck.ok ? (actualCheck.version || "unknown") : "unverified";
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "recovery-required",
+                  stage: "cleanup-new-version",
+                  targetVersion: localResolvedTargetVersion || localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  rolledBack: false,
+                  error: triggerError,
+                  rollbackError: rbDetail,
+                  installedState,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                if (!res.writableEnded) {
+                  return send(res, 500, {
+                    ok: false,
+                    code: "recovery-required",
+                    stage: "cleanup-new-version",
+                    error: "安装更新失败: " + triggerError + "（自动恢复旧版本失败: " + rbDetail + "，请手动重新安装插件）",
+                    rolledBack: false,
+                    rollbackError: rbDetail,
+                    originalVersion: localCurrentVersion,
+                    targetVersion: localResolvedTargetVersion || localTargetVersion,
+                    installedState,
+                    taskId: localTaskId
+                  });
+                }
+                return;
+              }
+
+              let rbOutcome = null;
+              let rbError = null;
               try {
-                outcome = await (registry ? pm.installBundle(spec, { registry }) : pm.installBundle(spec));
-              } finally {
-                if (registry) {
-                  if (prevRegistry !== undefined) {
-                    process.env.NPM_CONFIG_REGISTRY = prevRegistry;
-                  } else {
-                    delete process.env.NPM_CONFIG_REGISTRY;
+                rbOutcome = await (localRegistry ? localPm.installBundle(localOldSpec, { registry: localRegistry }) : localPm.installBundle(localOldSpec));
+              } catch (err) {
+                rbError = safeErrorMessage(err);
+                // Fallback to default installBundle without registry option if custom registry fails
+                if (localRegistry) {
+                  try {
+                    rbOutcome = await localPm.installBundle(localOldSpec);
+                    rbError = null;
+                  } catch (err2) {
+                    rbError = safeErrorMessage(err2);
                   }
                 }
               }
-              const application = outcome?.application || "restart-required";
-              return send(res, 200, { ok: true, result: { application, spec } });
+              let installOk = rbOutcome && rbOutcome.application !== "failed" && rbOutcome.application !== "cancelled" && rbOutcome.ok !== false && !rbError;
+
+              if (installOk && typeof localPm.selectBundle === "function") {
+                try { await localPm.selectBundle("dsh-session-manager", true); } catch (_) {}
+              }
+
+              let verifiedOk = false;
+              let verifyError = null;
+              if (installOk) {
+                const v = verifyInstalledPackage(localProfileDir, localCurrentVersion);
+                verifiedOk = v.ok;
+                if (!v.ok) verifyError = v.error;
+              }
+              releaseActiveTask(localTaskId);
+              if (installOk && verifiedOk) {
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "rolled-back",
+                  targetVersion: localResolvedTargetVersion || localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  rolledBack: true,
+                  error: triggerError,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                if (!res.writableEnded) {
+                  return send(res, 500, {
+                    ok: false,
+                    code: "install-failed",
+                    error: "安装更新失败: " + triggerError + "（已自动恢复旧版本 v" + localCurrentVersion + "）",
+                    rolledBack: true,
+                    originalVersion: localCurrentVersion,
+                    targetVersion: localResolvedTargetVersion || localTargetVersion,
+                    taskId: localTaskId
+                  });
+                }
+              } else {
+                const failureStage = !installOk ? "reinstall-old-version" : "verify-rollback";
+                const rbDetail = rbError || verifyError || (rbOutcome?.error ? safeErrorMessage(rbOutcome.error) : "回滚安装未成功");
+                const actualCheck = verifyInstalledPackage(localProfileDir);
+                const installedState = actualCheck.ok ? (actualCheck.version || "unknown") : "unverified";
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "recovery-required",
+                  stage: failureStage,
+                  targetVersion: localResolvedTargetVersion || localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  rolledBack: false,
+                  error: triggerError,
+                  rollbackError: rbDetail,
+                  installedState,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                if (!res.writableEnded) {
+                  return send(res, 500, {
+                    ok: false,
+                    code: "recovery-required",
+                    stage: failureStage,
+                    error: "安装更新失败: " + triggerError + "（自动恢复旧版本失败: " + rbDetail + "，请手动重新安装插件）",
+                    rolledBack: false,
+                    rollbackError: rbDetail,
+                    originalVersion: localCurrentVersion,
+                    targetVersion: localResolvedTargetVersion || localTargetVersion,
+                    installedState,
+                    taskId: localTaskId
+                  });
+                }
+              }
+            };
+
+            if (isHmr && typeof localPm.removeBundle === "function") {
+              // P0-1 & P0-2: Remove old bundle first in HMR
+              writeUpdateStatus(localProfileDir, {
+                taskId: localTaskId,
+                status: "removing",
+                targetVersion: localTargetVersion,
+                currentVersion: localCurrentVersion,
+                source: "npm",
+                pid: process.pid,
+                startedAt: taskStartedAt
+              });
+
+              let removeResult;
+              try {
+                removeResult = await localPm.removeBundle("dsh-session-manager");
+              } catch (rmErr) {
+                const failReason = safeErrorMessage(rmErr);
+                releaseActiveTask(localTaskId);
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "failed",
+                  stage: "removing",
+                  targetVersion: localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  error: "卸载旧版本失败: " + failReason,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                return send(res, 500, {
+                  ok: false,
+                  code: "remove-failed",
+                  error: "卸载旧版本失败: " + failReason,
+                  taskId: localTaskId
+                });
+              }
+
+              // P0-2: Strictly check removeBundle return value
+              if (removeResult && (removeResult.application === "failed" || removeResult.application === "cancelled" || removeResult.ok === false)) {
+                const failReason = removeResult.error?.message || removeResult.error?.code || safeErrorMessage(removeResult.error) || ("application: " + removeResult.application);
+                if (removeResult.changed && typeof localPm.selectBundle === "function") {
+                  try { await localPm.selectBundle("dsh-session-manager", true); } catch (_) {}
+                }
+                releaseActiveTask(localTaskId);
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "failed",
+                  stage: "removing",
+                  targetVersion: localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  error: "卸载旧版本失败: " + failReason,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                return send(res, 500, {
+                  ok: false,
+                  code: "remove-failed",
+                  error: "卸载旧版本失败: " + failReason,
+                  taskId: localTaskId
+                });
+              }
+
+              writeUpdateStatus(localProfileDir, {
+                taskId: localTaskId,
+                status: "removed",
+                targetVersion: localTargetVersion,
+                currentVersion: localCurrentVersion,
+                source: "npm",
+                pid: process.pid,
+                startedAt: taskStartedAt
+              });
+            }
+
+            // Install target bundle
+            writeUpdateStatus(localProfileDir, {
+              taskId: localTaskId,
+              status: "installing",
+              targetVersion: localResolvedTargetVersion || localTargetVersion,
+              currentVersion: localCurrentVersion,
+              source: "npm",
+              pid: process.pid,
+              startedAt: taskStartedAt
+            });
+
+            let outcome;
+            try {
+              outcome = await (localRegistry ? localPm.installBundle(localSpec, { registry: localRegistry }) : localPm.installBundle(localSpec));
             } catch (err) {
-              return send(res, 500, { ok: false, code: "install-failed", error: safeErrorMessage(err) });
+              const errMsg = safeErrorMessage(err);
+              if (isHmr) {
+                // In HMR, old bundle was removed -> execute rollback (new version was not installed)
+                return await performRollback(errMsg, { newVersionInstalled: false });
+              } else {
+                // In non-HMR, old bundle was not removed -> fail directly
+                releaseActiveTask(localTaskId);
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "failed",
+                  targetVersion: localResolvedTargetVersion || localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  error: errMsg,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                return send(res, 500, {
+                  ok: false,
+                  code: "install-failed",
+                  error: "安装更新失败: " + errMsg,
+                  taskId: localTaskId
+                });
+              }
+            }
+
+            // Check outcome application
+            if (outcome && (outcome.application === "failed" || outcome.application === "cancelled" || outcome.ok === false)) {
+              const failReason = outcome.error?.message || outcome.error || ("application: " + outcome.application);
+              if (isHmr) {
+                return await performRollback(failReason, { newVersionInstalled: false });
+              } else {
+                releaseActiveTask(localTaskId);
+                writeUpdateStatus(localProfileDir, {
+                  taskId: localTaskId,
+                  status: "failed",
+                  targetVersion: localResolvedTargetVersion || localTargetVersion,
+                  currentVersion: localCurrentVersion,
+                  error: failReason,
+                  pid: process.pid,
+                  failedAt: Date.now()
+                });
+                return send(res, 500, {
+                  ok: false,
+                  code: "install-failed",
+                  error: "安装更新失败: " + failReason,
+                  taskId: localTaskId
+                });
+              }
             }
+
+            if (!localResolvedTargetVersion && typeof outcome?.version === "string") {
+              localResolvedTargetVersion = outcome.version;
+            }
+            const concreteTargetVersion = localResolvedTargetVersion || (localTargetVersion !== "latest" ? localTargetVersion : null);
+
+            // P1-2: Strict post-install verification
+            writeUpdateStatus(localProfileDir, {
+              taskId: localTaskId,
+              status: "verifying",
+              targetVersion: concreteTargetVersion || localTargetVersion,
+              currentVersion: localCurrentVersion,
+              source: "npm",
+              pid: process.pid,
+              startedAt: taskStartedAt
+            });
+
+            const verifyResult = verifyInstalledPackage(localProfileDir, concreteTargetVersion);
+            if (!verifyResult.ok) {
+              const vError = "安装后校验失败: " + verifyResult.error;
+              return await performRollback(vError, { newVersionInstalled: true });
+            }
+
+            // Completed!
+            const application = outcome?.application || (isHmr ? "refresh-required" : "restart-required");
+            releaseActiveTask(localTaskId);
+            const finalInstalledVersion = verifyResult.version || concreteTargetVersion || localTargetVersion;
+            writeUpdateStatus(localProfileDir, {
+              taskId: localTaskId,
+              status: "completed",
+              targetVersion: finalInstalledVersion,
+              currentVersion: localCurrentVersion,
+              application,
+              pid: process.pid,
+              completedAt: Date.now()
+            });
+
+            if (!res.writableEnded) {
+              return send(res, 200, {
+                ok: true,
+                result: {
+                  application,
+                  spec: localSpec,
+                  version: finalInstalledVersion,
+                  taskId: localTaskId
+                }
+              });
+            }
+          } finally {
+            if (heartbeatTimer) clearInterval(heartbeatTimer);
+            releaseActiveTask(taskId);
+            if (forwardRegistry) {
+              if (prevRegistry !== undefined) {
+                process.env.NPM_CONFIG_REGISTRY = prevRegistry;
+              } else {
+                delete process.env.NPM_CONFIG_REGISTRY;
+              }
+            }
+          }
+        }
+        if (req.method === "GET" && path === "/update/status") {
+          const profileDir = resolveProfileDir(adapter, ctx);
+          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          let installedVersion = currentVersion;
+          if (profileDir) {
+            const diskCheck = verifyInstalledPackage(profileDir);
+            if (diskCheck.ok && diskCheck.version) {
+              installedVersion = diskCheck.version;
+            }
+          }
+          const updateStatus = readUpdateStatus(profileDir);
+          const queryTaskId = url.searchParams.get("taskId")?.trim();
+
+          if (queryTaskId) {
+            if (updateStatus && updateStatus.taskId === queryTaskId) {
+              return send(res, 200, {
+                ok: true,
+                result: {
+                  ...updateStatus,
+                  runningVersion: currentVersion,
+                  currentVersion,
+                  installedVersion
+                }
+              });
+            }
+            if (updateStatus && updateStatus.taskId && updateStatus.taskId !== queryTaskId) {
+              return send(res, 200, {
+                ok: true,
+                result: {
+                  status: "superseded",
+                  taskId: queryTaskId,
+                  activeTaskId: updateStatus.taskId,
+                  runningVersion: currentVersion,
+                  currentVersion,
+                  installedVersion
+                }
+              });
+            }
+            return send(res, 200, {
+              ok: true,
+              result: {
+                status: "idle",
+                taskId: queryTaskId,
+                runningVersion: currentVersion,
+                currentVersion,
+                installedVersion
+              }
+            });
           }
-          return send(res, 501, {
-            ok: false,
-            code: "plugin-manager-unavailable",
-            error: "当前宿主环境未提供 PluginManager 安装服务，请通过 DSH 插件市场或命令行更新"
+
+          const now = Date.now();
+          if (updateStatus && (now - (updateStatus.completedAt || updateStatus.failedAt || updateStatus.startedAt || 0) < 10 * 60 * 1000)) {
+            return send(res, 200, {
+              ok: true,
+              result: {
+                ...updateStatus,
+                runningVersion: currentVersion,
+                currentVersion,
+                installedVersion
+              }
+            });
+          }
+          return send(res, 200, {
+            ok: true,
+            result: {
+              status: "idle",
+              runningVersion: currentVersion,
+              currentVersion,
+              installedVersion
+            }
           });
         }
         return send(res, 404, { ok: false, error: "not found: " + req.method + " " + path });
@@ -2111,4 +3018,4 @@ ${rest}`, "utf8");
   }), "session-manager: http api");
 }
 
-export { listSessionHeaders, scanSessionHeaders, encodeSessionSegment, compareSemver };
+export { listSessionHeaders, scanSessionHeaders, candidateSessionDirs, encodeFsSessionSegment, decodeFsSessionSegment, encodeProjectSegment, encodeSessionSegment, compareSemver };