dsh-session-manager 0.7.2 → 0.7.4

package/lib/index.js

@@ -22,12 +22,13 @@
  * 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 { 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";
@@ -100,6 +101,12 @@ function rebindLiveWriter(persistence, sessionId, newHeader) {
  * disk fallback semantics are preserved -- the orphan is the whole
  * reason this loop exists.
  *
+ * The result carries two completeness flags: "persisted" reports whether the
+ * persistence index itself listed successfully (its rows are authoritative),
+ * while "complete" additionally requires the disk sweep to finish without
+ * errors. Callers that only add validated memberships may run on "persisted";
+ * callers that remove records must wait for "complete".
+ *
  * @param {object|undefined} persistence  DSH's sessionPersistence service
  * @param {((segment: string) => string)|undefined} dshHome  Resolver for
  *   DSH home sub-paths; only "sessions" is read.
@@ -109,6 +116,7 @@ const scanSessionHeaders = async (persistence, dshHome) => {
   const headers = [];
   const errors = [];
   let listed = false;
+  let persisted = false;
   if (typeof persistence?.list === "function") {
     try {
       const rows = await persistence.list();
@@ -121,9 +129,10 @@ const scanSessionHeaders = async (persistence, dshHome) => {
         if (!seen.has(header.id)) { seen.add(header.id); headers.push(header); }
       }
       listed = true;
+      persisted = true;
     } catch (error) { errors.push(error); }
   }
-  const result = () => ({ headers, complete: listed && errors.length === 0, errors });
+  const result = () => ({ headers, persisted, 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--").
@@ -174,9 +183,209 @@ const scanSessionHeaders = async (persistence, dshHome) => {
 
 const listSessionHeaders = async (persistence, dshHome) => (await scanSessionHeaders(persistence, dshHome)).headers;
 
+/** Canonicalize a directory path the way DSH's workspace registry does
+ * (fs.realpath on a fully qualified path). Returns undefined when the path
+ * cannot be resolved so callers skip instead of guessing; DSH stores
+ * workspace paths canonicalized, so canonical equality is the only safe
+ * membership comparison on Windows (case, separators, 8.3 names, junctions). */
+const canonicalizeDirectory = async (path) => {
+  if (typeof path !== "string" || path === "") return undefined;
+  try { return await realpath(path); } catch { return undefined; }
+};
+
+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.2 (workspace-archive)";
+    const buildId = "dsh-session-manager v0.7.4 (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 */ }
@@ -208,10 +417,26 @@ export function apply(ctx) {
   const safeGetAgent = (sessionId) => {
     try { return ctx.agents?.get?.(sessionId); } catch { return undefined; }
   };
+  /** Durable workspace membership for one entity. The record account is the
+   * authoritative persisted list on DSH 0.2.x (registry entities expose it as
+   * the private `record` field); the runtime `sessionIds` getter is filtered
+   * by the canonical-cwd index and may hide members whose index entry is
+   * stale, so it is only a fallback for hosts without a readable record. */
+  const workspaceMemberIds = (entity) => {
+    if (entity === null || entity === undefined) return [];
+    const record = entity.record;
+    if (record !== null && record !== undefined && Array.isArray(record.sessionIds)) return record.sessionIds;
+    const ids = entity.sessionIds;
+    if (Array.isArray(ids)) return ids;
+    if (typeof ids === "function") {
+      try { const value = ids(); if (Array.isArray(value)) return value; } catch { /* ignore */ }
+    }
+    return [];
+  };
   const assertAnnotatable = id => {
     const registry = adapter.workspaceRegistry;
     if (adapter.getSession(id) !== undefined || registry?.headers?.has?.(id)
-      || adapter.workspaceList().some(ws => (ws.record?.sessionIds ?? ws.sessionIds ?? []).includes(id))) return;
+      || adapter.workspaceList().some(ws => workspaceMemberIds(ws).includes(id))) return;
     throw Object.assign(new Error("会话不存在或尚未加载，请先打开该会话后重试"), { code: "session-not-found" });
   };
   const operations = new Map();
@@ -376,7 +601,9 @@ export function apply(ctx) {
   const detachFromWorkspaces = async (sessionId) => {
     const registry = ctx.get("workspaceRegistry") ?? ctx.workspaceRegistry ?? adapter.workspaceRegistry;
     for (const entity of registry.list()) {
-      if (entity.sessionIds.includes(sessionId)) {
+      // Durable record, not the runtime-filtered getter: deleting a session
+      // must purge its account even when the cwd index is stale.
+      if (workspaceMemberIds(entity).includes(sessionId)) {
         await entity.detachSession(sessionId);
       }
     }
@@ -385,9 +612,7 @@ export function apply(ctx) {
   /** Ordered workspace projection for the client. */
   const listWorkspaces = () => {
     return ctx.workspaceRegistry.list().map((entity) => {
-      const rawIds = Array.isArray(entity.record?.sessionIds)
-        ? [...entity.record.sessionIds]
-        : [...entity.sessionIds];
+      const rawIds = [...workspaceMemberIds(entity)];
       const selfUpdatedAt = entity.updatedAt ?? entity.record?.updatedAt ?? null;
       return {
         id: entity.id,
@@ -643,6 +868,182 @@ ${rest}`, "utf8");
       return false;
     };
 
+    /**
+     * Attach one session to the registered workspace that owns its cwd.
+     * Returns true only when a new durable membership was written.
+     *
+     * DSH's own create/fork flow attaches through workspaceRegistry, but a
+     * session created outside that flow (cwd-only create, an attach the host
+     * declined, or a session that predates this plugin load) stays
+     * unaccounted even though its cwd names a registered workspace. The
+     * official entity API re-validates the stored header cwd against the
+     * canonical workspace path and persists through the domain table, so a
+     * wrong match can never be written. Subagent sessions never join a
+     * workspace account, and a session any workspace already accounts for is
+     * left untouched (no session is ever registered twice).
+     */
+    const attachSessionToOwningWorkspace = async (header) => {
+      const registry = adapter.workspaceRegistry;
+      if (registry === void 0 || typeof registry.list !== "function") return false;
+      if (header === void 0 || typeof header.id !== "string") return false;
+      if (header.origin === "subagent") return false;
+      if (typeof header.cwd !== "string" || header.cwd === "") return false;
+      const run = async () => {
+        const entities = registry.list();
+        for (const entity of entities) {
+          if (workspaceMemberIds(entity).includes(header.id)) return false;
+        }
+        const byPath = new Map();
+        for (const entity of entities) {
+          if (typeof entity.path === "string" && !byPath.has(entity.path)) byPath.set(entity.path, entity);
+        }
+        let target = byPath.get(header.cwd);
+        if (target === void 0 && typeof registry.resolveByPath === "function") {
+          try { target = await registry.resolveByPath(header.cwd); } catch { target = void 0; }
+        }
+        if (target === void 0) {
+          const canonical = await canonicalizeDirectory(header.cwd);
+          if (canonical !== void 0) target = byPath.get(canonical);
+        }
+        if (target === void 0 || typeof target.attachSession !== "function") return false;
+        await target.attachSession(header.id);
+        return true;
+      };
+      if (typeof registry.enqueueOperation === "function") return await registry.enqueueOperation(run);
+      return await run();
+    };
+
+    /**
+     * Resolve the header the official attachSession() will validate against.
+     * WorkspaceEntity.readSessionHeader prefers the live session, then the
+     * registry's own header index, and only then a fresh persistence listing.
+     * Mirroring that order lets the repair predict a rejection instead of
+     * attempting an attach that cannot succeed.
+     */
+    const effectiveSessionHeader = (sessionId, storedHeader) => {
+      try {
+        const live = ctx.sessions?.get?.(sessionId);
+        if (live !== undefined && live !== null && live.header !== undefined) return live.header;
+      } catch { /* fall through to the index */ }
+      try {
+        const indexed = adapter.workspaceRegistry?.headers?.get?.(sessionId);
+        if (indexed !== undefined) return indexed;
+      } catch { /* fall through to the stored header */ }
+      return storedHeader;
+    };
+
+    /**
+     * Complete the durable workspace membership of a session whose artifact
+     * already lives under the target workspace path (same-path move). DSH 0.2.x
+     * keeps "cwd matches the workspace path" and "the workspace accounts for
+     * the session" as separate facts, so a matching cwd alone must not be
+     * reported as success.
+     *
+     * Conservative policy. The official domain offers no cross-record
+     * transaction (single-record updates on one serialized storage unit), and
+     * attachSession() validates the session cwd against the workspace path --
+     * so an account held by a DIFFERENT workspace can never be restored
+     * through the official API once it is removed. Automatic migration would
+     * therefore risk destroying the only remaining account if the target
+     * attach then failed. Hence:
+     *   - no workspace accounts for the session: complete the target
+     *     membership through attachSession(), after pre-checking every
+     *     condition it validates so a predictable rejection fails before any
+     *     write;
+     *   - already accounted by the target and by nobody else: idempotent
+     *     no-op, no write;
+     *   - accounted by another workspace: refuse with a membership-conflict
+     *     error; no automatic cross-record migration;
+     *   - membership state cannot be confirmed: refuse.
+     *
+     * No artifact is rewritten, no cwd is touched, and no live session is
+     * restarted. A true cross-workspace move re-homes the artifact first and
+     * is a separate, unchanged path.
+     *
+     * @returns {status: "already-member"|"attached", attached: boolean}
+     * @throws with code workspace-membership-unknown | workspace-membership-conflict |
+     *   workspace-attach-unavailable | workspace-repair-unsafe | workspace-repair-failed.
+     */
+    const repairWorkspaceMembership = async (target, sessionId, storedHeader) => {
+      const registry = ctx.get("workspaceRegistry") ?? ctx.workspaceRegistry ?? adapter.workspaceRegistry;
+      const run = async () => {
+        // Confirm the current accounting from a fresh, readable listing. An
+        // unreadable registry must never be guessed at.
+        let entities;
+        let inTarget;
+        let stale;
+        try {
+          if (typeof registry?.list !== "function") throw new Error("workspace registry 不可用");
+          const listed = registry.list();
+          if (!Array.isArray(listed)) throw new Error("workspace registry 返回了无效数据");
+          entities = listed;
+          inTarget = workspaceMemberIds(target).includes(sessionId);
+          stale = entities.filter((entity) =>
+            entity !== target && entity.id !== target.id && workspaceMemberIds(entity).includes(sessionId));
+        } catch (cause) {
+          const error = new Error("无法确认会话当前的工作区归属状态（" + safeErrorMessage(cause) + "），已拒绝修复操作");
+          error.code = "workspace-membership-unknown";
+          throw error;
+        }
+
+        if (stale.length > 0) {
+          // Membership conflict: the session is accounted by a workspace whose
+          // path differs from its cwd. That account cannot be restored through
+          // the official API once removed, so an automatic migration could
+          // destroy the only remaining account if the target attach failed.
+          // Refuse and let the operator resolve the conflict.
+          const names = stale.map((entity) => entity.title || entity.id).join("、");
+          const error = new Error(
+            "会话当前登记在其他工作区（" + names + "），与其 cwd 指向的目标工作区不一致。"
+            + "为避免修复失败造成数据损失，已拒绝自动迁移；请先处理该归属冲突，或使用真正的跨工作区移动"
+          );
+          error.code = "workspace-membership-conflict";
+          throw error;
+        }
+        if (inTarget) return { status: "already-member", attached: false };
+        if (typeof target.attachSession !== "function") {
+          const error = new Error("当前 DSH 宿主未提供官方工作区归属接口（attachSession），无法补全会话归属");
+          error.code = "workspace-attach-unavailable";
+          throw error;
+        }
+
+        // Pre-check every condition attachSession() validates so a predictable
+        // rejection fails before any write. The header it reads is the live
+        // session first, then the registry index, then a fresh persistence
+        // listing -- not necessarily the header this request was validated
+        // against.
+        const effective = effectiveSessionHeader(sessionId, storedHeader);
+        if (effective === void 0 || typeof effective.cwd !== "string" || effective.cwd === "") {
+          const error = new Error("拒绝补全归属：会话没有可校验的 cwd，官方接口无法登记");
+          error.code = "workspace-repair-unsafe";
+          throw error;
+        }
+        const canonical = await canonicalizeDirectory(effective.cwd);
+        if (canonical === void 0 || canonical !== target.path) {
+          const error = new Error(
+            "拒绝补全归属：会话当前 cwd（" + effective.cwd + "）解析后与目标工作区（" + target.path
+            + "）不一致，官方接口会拒绝登记；未做任何修改"
+          );
+          error.code = "workspace-repair-unsafe";
+          throw error;
+        }
+        try {
+          await target.attachSession(sessionId);
+        } catch (cause) {
+          // Nothing has been written yet, so the previous state (no account) is
+          // intact; surface the failure with its cause.
+          const error = new Error("补全归属失败：" + safeErrorMessage(cause));
+          error.code = "workspace-repair-failed";
+          throw error;
+        }
+        return { status: "attached", attached: true };
+      };
+      if (registry !== void 0 && typeof registry.enqueueOperation === "function") {
+        return await registry.enqueueOperation(run);
+      }
+      return await run();
+    };
+
     /**
      * TRUE cross-workspace move. See the module docstring for the full design:
      * re-home the stored cwd, migrate the artifact, then swap accounting.
@@ -705,7 +1106,25 @@ ${rest}`, "utf8");
         let currentCanonical;
         try { currentCanonical = await realpath(storedHeader.cwd); } catch { /* re-home below */ }
         if (currentCanonical === targetPath) {
-          return { ok: true, sessionId, moved: false, message: "会话已属于目标工作区" };
+          // The artifact already lives under the target workspace path, but on
+          // DSH 0.2.x "cwd matches" and "the workspace accounts for the
+          // session" are separate facts: a matching cwd with a missing
+          // registration used to return a silent no-op success. Repair the
+          // durable membership through the official entity API (idempotent,
+          // no artifact rewrite, no live-session restart) and report what
+          // actually happened. A repair that cannot be completed fails loudly
+          // instead of reporting success.
+          const repair = await repairWorkspaceMembership(target, sessionId, storedHeader);
+          return {
+            ok: true,
+            sessionId,
+            moved: false,
+            attached: repair.attached,
+            membership: repair.status,
+            message: repair.attached
+              ? "会话已归属目标工作区（已补全归属记录）"
+              : "会话已属于目标工作区"
+          };
         }
       }
 
@@ -812,7 +1231,7 @@ ${rest}`, "utf8");
         const oldIndexedPath = registry.sessionPaths?.get?.(sessionId);
         const oldInvalidPath = registry.invalidSessionPaths?.get?.(sessionId);
         const fromWorkspaceIds = registry.list()
-          .filter((entity) => entity.id !== target.id && (entity.record?.sessionIds ?? entity.sessionIds).includes(sessionId))
+          .filter((entity) => entity.id !== target.id && workspaceMemberIds(entity).includes(sessionId))
           .map((entity) => entity.id);
         let targetAttached = false;
         const detachedFrom = [];
@@ -977,8 +1396,7 @@ ${rest}`, "utf8");
             throw error;
           }
           allowedIds = new Set();
-          const ids = typeof ws.sessionIds === "function" ? ws.sessionIds() : ws.sessionIds;
-          if (Array.isArray(ids)) for (const id of ids) allowedIds.add(id);
+          for (const id of workspaceMemberIds(ws)) allowedIds.add(id);
         }
       }
       const requestedSessionId = filter !== void 0 && typeof filter === "object" && typeof filter.sessionId === "string"
@@ -1627,43 +2045,103 @@ ${rest}`, "utf8");
     if (typeof persistence?.list !== "function" || typeof registry?.list !== "function") return;
 
     try {
-      // Remember only ids that existed before the async scan. Concurrently
-      // attached ids must never be removed using this older disk snapshot.
-      const initialIds = new Map(registry.list().map(ws => [ws.id, new Set(ws.record?.sessionIds ?? [])]));
-      const scan = await scanSessionHeaders(persistence, adapter.homePath);
-      if (!scan.complete) {
-        ctx.logger.warn("session-manager: incomplete session scan; workspace reconciliation skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+      // Snapshot durable membership BEFORE the async scan. Only ids that
+      // already existed here may ever be pruned later; ids attached
+      // concurrently must never be removed using an older disk snapshot.
+      let entities;
+      try { entities = registry.list(); }
+      catch (error) {
+        ctx.logger.warn("session-manager: workspace registry unavailable; workspace reconciliation skipped: " + safeErrorMessage(error));
         return;
       }
-      const headers = scan.headers;
-      const validIds = new Set(headers.map(header => header.id));
+      const initialIds = new Map(entities.map(ws => [ws.id, new Set(workspaceMemberIds(ws))]));
+      const scan = await scanSessionHeaders(persistence, adapter.homePath);
+      const headers = Array.isArray(scan.headers) ? scan.headers : [];
+
+      // Step 1a: attach sessions whose cwd names a registered workspace but
+      // that no workspace accounts for (issue #41). Every candidate is
+      // re-validated by the official entity API, which persists through the
+      // domain table and is idempotent for already-accounted ids -- so this
+      // pass can only add well-formed memberships, never corrupt records.
+      // It runs whenever the persistence index listed successfully
+      // (scan.persisted); a partial disk sweep cannot make a listed header
+      // invalid.
+      let added = 0;
+      if (scan.persisted) {
+        const assigned = new Set();
+        for (const ws of entities) for (const id of initialIds.get(ws.id)) assigned.add(id);
+        const candidates = headers.filter(header =>
+          typeof header.cwd === "string" && header.cwd !== ""
+          && header.origin !== "subagent"
+          && !assigned.has(header.id));
+        if (candidates.length > 0) {
+          const byPath = new Map();
+          for (const ws of entities) {
+            if (typeof ws.path === "string" && !byPath.has(ws.path)) byPath.set(ws.path, ws);
+          }
+          const attach = async () => {
+            // Re-read membership inside the registry write queue: a concurrent
+            // move may have accounted an id after the snapshot above.
+            const current = typeof registry.list === "function" ? registry.list() : entities;
+            const assignedNow = new Set();
+            for (const ws of current) for (const id of workspaceMemberIds(ws)) assignedNow.add(id);
+            for (const header of candidates) {
+              if (assignedNow.has(header.id)) continue;
+              let target = byPath.get(header.cwd);
+              if (target === void 0) {
+                const canonical = await canonicalizeDirectory(header.cwd);
+                if (canonical !== void 0) target = byPath.get(canonical);
+              }
+              if (target === void 0 || typeof target.attachSession !== "function") continue;
+              try {
+                await target.attachSession(header.id);
+                assignedNow.add(header.id);
+                added += 1;
+              } catch (error) {
+                ctx.logger.warn("session-manager: boot attach of session '" + header.id + "' to workspace '" + target.id + "' failed: " + safeErrorMessage(error));
+              }
+            }
+          };
+          if (typeof registry.enqueueOperation === "function") await registry.enqueueOperation(attach);
+          else await attach();
+        }
+      }
 
-      // Step 1: Immediate Workspace Member Reconciliation (isolated from projection rebuild)
+      // Step 1b: prune record entries whose session no longer exists. Only a
+      // fully complete scan (persistence index plus disk sweep, no errors)
+      // may remove anything; live sessions and ids attached after the
+      // snapshot are always kept. Durable records are read through
+      // workspaceMemberIds so a stale runtime index cannot hide a dead entry.
       let removed = 0;
-      let added = 0;
-      await registry.enqueueOperation(async () => {
-        const state = registry.requireState();
-        const pathById = new Map(registry.list().map(ws => [ws.id, ws.path]));
-        const assignedIds = new Set((state.workspaces ?? []).flatMap(ws => ws.sessionIds ?? []));
-        const workspaces = (state.workspaces ?? []).map(ws => {
-          const original = ws.sessionIds ?? [];
-          const sessionIds = original.filter(id => validIds.has(id)
-            || !initialIds.get(ws.id)?.has(id) || adapter.getSession(id) !== undefined);
-          const removedHere = original.length - sessionIds.length;
-          removed += removedHere;
-          for (const header of headers) {
-            if (header.cwd === undefined || header.cwd !== pathById.get(ws.id) || assignedIds.has(header.id)) continue;
-            sessionIds.unshift(header.id);
-            assignedIds.add(header.id);
-            added += 1;
+      if (scan.complete) {
+        const validIds = new Set(headers.map(header => header.id));
+        const prune = async () => {
+          for (const ws of (typeof registry.list === "function" ? registry.list() : entities)) {
+            const initial = initialIds.get(ws.id);
+            // Snapshot: detachSession replaces the record array while we walk it.
+            for (const id of [...workspaceMemberIds(ws)]) {
+              if (validIds.has(id)) continue;
+              if (initial === void 0 || !initial.has(id)) continue;
+              if (adapter.getSession(id) !== undefined) continue;
+              if (typeof ws.detachSession !== "function") continue;
+              await ws.detachSession(id);
+              removed += 1;
+            }
           }
-          if (sessionIds.length === original.length && sessionIds.every((id, i) => id === original[i])) return ws;
-          return { ...ws, sessionIds, updatedAt: new Date().toISOString() };
-        });
-        if (removed || added) await registry.setState({ ...state, workspaces });
-      });
-      if (removed || added) {
-        ctx.logger.info('session-manager: post-boot workspace reconcile removed ' + removed + ' orphans, attached ' + added + ' disk-only sessions');
+        };
+        if (typeof registry.enqueueOperation === "function") await registry.enqueueOperation(prune);
+        else await prune();
+      }
+      if (added || removed) {
+        ctx.logger.info('session-manager: post-boot workspace reconcile attached ' + added + ' unaccounted sessions, removed ' + removed + ' orphans');
+      }
+      if (!scan.persisted) {
+        ctx.logger.warn("session-manager: incomplete session scan; workspace reconciliation skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+        return;
+      }
+      if (!scan.complete) {
+        ctx.logger.warn("session-manager: incomplete disk sweep; workspace membership pruning skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+        return;
       }
 
       // Step 2: Budgeted Background Projection Cache Rebuild
@@ -1727,6 +2205,32 @@ ${rest}`, "utf8");
     }
   }, "session-manager: post-boot re-fold stale projection cache rows");
 
+  /**
+   * Runtime membership repair (issue #41): DSH's own create/fork flow attaches
+   * a session to its workspace, but a session created outside that flow -- or
+   * one whose host-side attach failed -- stays unaccounted even though its
+   * cwd names a registered workspace, and would otherwise only be repaired on
+   * the next DSH restart. Repair it as soon as the session is announced.
+   *
+   * The listener must never throw synchronously: a throwing session/created
+   * listener rolls back session creation in DSH. Everything is contained and
+   * fire-and-forget; failures are logged only.
+   */
+  if (typeof ctx.on === "function") ctx.on("session/created", (session) => {
+    void (async () => {
+      try {
+        const header = session?.header ?? session;
+        if (header === void 0 || typeof header.id !== "string") return;
+        const attached = await attachSessionToOwningWorkspace(header);
+        if (attached) {
+          ctx.logger.info("session-manager: attached new session '" + header.id + "' to its cwd workspace");
+        }
+      } catch (error) {
+        ctx.logger.warn("session-manager: session/created membership repair failed: " + safeErrorMessage(error));
+      }
+    })();
+  });
+
   /** Build a normalized annotation patch from one bulk action + payload.
    * Returns null when the payload is missing or malformed so the caller can
    * surface a 400 instead of letting the store throw on a bad value.
@@ -2024,14 +2528,91 @@ ${rest}`, "utf8");
           return send(res, 200, { ok: true, result });
         }
         if (req.method === "GET" && path === "/update/check") {
-          const currentVersion = adapter.pluginVersion() || "0.7.2";
-          let latestVersion = currentVersion;
+          const currentVersion = adapter.pluginVersion() || "0.7.4";
+          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();
@@ -2050,17 +2631,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"
+              }
             });
           }
         }
@@ -2069,38 +2666,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.4";
+          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);
+                  }
+                }
+              }
+
+              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 outcome;
+
+              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.4";
+          let installedVersion = currentVersion;
+          if (profileDir) {
+            const diskCheck = verifyInstalledPackage(profileDir);
+            if (diskCheck.ok && diskCheck.version) {
+              installedVersion = diskCheck.version;
             }
           }
-          return send(res, 501, {
-            ok: false,
-            code: "plugin-manager-unavailable",
-            error: "当前宿主环境未提供 PluginManager 安装服务，请通过 DSH 插件市场或命令行更新"
+          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
+              }
+            });
+          }
+
+          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 });
@@ -2108,7 +3317,9 @@ ${rest}`, "utf8");
         ctx.logger.warn("session-manager: api error: " + safeErrorMessage(error) + "; json=" + safeJson(error));
         const status = error?.code === "bad-request" ? 400 : error?.code === "body-too-large" ? 413
           : error?.code === "annotation-conflict" || error?.code === "annotations-busy" ? 409
-          : error?.code === "session-not-found" ? 404 : error?.code?.startsWith("annotations-") ? 503 : 500;
+          : error?.code === "session-not-found" ? 404 : error?.code?.startsWith("annotations-") ? 503
+          : error?.code === "workspace-membership-conflict" ? 409
+          : error?.code === "workspace-attach-unavailable" ? 501 : 500;
         return send(res, status, {
           ok: false,
           error: safeErrorMessage(error),