dsh-session-manager 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.7.2 — 2026-10-17
+
+- **fix(encoding)**: Correct session directory encoding and candidate matching for IM and non-UUID sessions (`encodeFsSessionSegment` matching DSH `encodeSegment` with `~XXXX` hex escapes). Support colons and non-alphanumeric characters in session IDs without directory traversal risks, distinguish project keys from session directory segments, and maintain multi-candidate fallback compatibility for existing sessions (#39).
+- **fix(ui)**: Scope custom dropdown interceptor to Session Manager elements only (`getTargetSmSelect`), preventing global interception of third-party plugin selects and DSH native dropdowns and eliminating unwanted `preventDefault` / `stopPropagation` calls (#36).
+- **fix(ui)**: Prevent scrolling within the custom select menu from closing the menu, enabling smooth wheel scrolling and scrollbar dragging across long option lists (PR #37).
+- **fix(ui)**: Improve sidebar footer layout compatibility when multiple plugins inject actions into `sidebar.footer.action`. Apply scoped `flex-wrap: wrap` on the footer actions container and update `.sm-footerBtn-wide` to `flex: 1 1 100%`, preventing overlapping buttons and horizontal squishing without fragile CSS module hashes or targeting other plugins' private classes (#38).
+- **compat**: Compatible with DSH Desktop V0.2.1-rc.2 (and V0.2.0-rc.2).
+
 ## 0.7.1 — 2026-10-15
 
 - **fix(cache)**: Decouple boot-time workspace session membership reconciliation from projection cache reconstruction, preventing background event-loop blocking and watchdog recovery timeouts on large session libraries (#32).

package/README.md

@@ -3,6 +3,7 @@
 English | [中文](README.zh.md)
 
 [![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-upstream-1082ff)](https://github.com/deepseek-ai/deepseek-harness)
 [![GitHub](https://img.shields.io/badge/GitHub-repository-blue)](https://github.com/hkkz9522/dsh-session-manager)
 [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
@@ -51,7 +52,7 @@ Verified with the official DSH Desktop client; see [5 Compatibility](#5-compatib
 - **Theme**: Automatically follows the active DSH theme (including third-party theme plugins). Dialogs, settings cards, title-bar buttons, menus, inputs, and all other UI elements seamlessly adapt to light and dark themes.
 - **Unified dropdown styling**: All select dropdowns (sort, filter, priority) use unified shadow-free rounded custom floating menus matching active themes, strictly aligned with trigger widths, eliminating Chromium duplicate native popups.
 
-### 1.5 Workspace Archiving and Management (new in v0.7.0)
+### 1.5 Workspace Archiving and Management
 
 - **Two-page tab switching**: Seamlessly switch between "Session Management" and "Workspace Management" in the dialog header, preserving each page's distinct search, filter, and sort states.
 - **Workspace list**: Displays all registered workspaces with title/name, physical path, session count, latest activity timestamp computed from member sessions, and right-side toggle switch.
@@ -140,21 +141,22 @@ After changing plugin dependencies, `package.json`, bundle configuration, or oth
 
 ## 5 Compatibility
 
-DSH versions are shown above plugin versions; each column represents a tested version combination.
-
-> Verification note: from 0.6.3 on, this plugin is verified with the official DSH Desktop client only (the Web UI shares the same Host/client code but is no longer covered by the verification matrix).
-
-| v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
-| --- | --- | --- |
-| 0.7.1, 0.7.0, 0.6.4, 0.6.3, 0.6.2, 0.5.4 | 0.5.3 | 0.5.2 |
-
-| v0.1.6-alpha.2 | v0.1.5-rc.2 | v0.1.5-rc.1 |
-| --- | --- | --- |
-| 0.5.1 | 0.4.11 | 0.4.10, 0.4.9, 0.4.7 |
-
-| v0.1.3-alpha.2 | v0.1.2-rc.1 | v0.1.0-rc.7 |
-| --- | --- | --- |
-| 0.4.6, 0.4.4, 0.4.1 | 0.4.0 | 0.1.2, 0.1.1, 0.1.0 |
+The table below lists verified version combinations between DeepSeek Harness (DSH) and `dsh-session-manager`.
+
+> **Verification note**: From version 0.6.3 onwards, this plugin is verified with the official DSH Desktop client only (the Web UI shares the same Host/client codebase but is no longer covered by the verification matrix).
+
+| DeepSeek Harness (DSH) | dsh-session-manager | Verified Environment |
+| :--- | :--- | :--- |
+| **v0.2.1-rc.2** | `0.7.2` | Desktop |
+| **v0.2.0-rc.2** | `0.7.1`, `0.7.0`, `0.6.4`, `0.6.3`, `0.6.2`, `0.5.4` | Desktop |
+| **v0.1.7-rc.2** | `0.5.3` | Desktop / Web UI |
+| **v0.1.7-rc.1** | `0.5.2` | Desktop / Web UI |
+| **v0.1.6-alpha.2** | `0.5.1` | Web UI |
+| **v0.1.5-rc.2** | `0.4.11` | Web UI |
+| **v0.1.5-rc.1** | `0.4.10`, `0.4.9`, `0.4.7` | Web UI |
+| **v0.1.3-alpha.2** | `0.4.6`, `0.4.4`, `0.4.1` | Web UI |
+| **v0.1.2-rc.1** | `0.4.0` | Web UI |
+| **v0.1.0-rc.7** | `0.1.2`, `0.1.1`, `0.1.0` | Web UI |
 
 The version combinations above have been tested with either the official Web UI or Desktop app. Other version combinations may also work but have not been individually verified.
 

package/README.zh.md

@@ -3,6 +3,7 @@
 [English](README.md) | 中文
 
 [![npm version](https://img.shields.io/npm/v/dsh-session-manager)](https://www.npmjs.com/package/dsh-session-manager)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-宿主-1082ff)](https://github.com/deepseek-ai/deepseek-harness)
 [![GitHub](https://img.shields.io/badge/GitHub-仓库-blue)](https://github.com/hkkz9522/dsh-session-manager)
 [![CI](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/hkkz9522/dsh-session-manager/actions/workflows/ci.yml)
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
@@ -42,14 +43,14 @@ DSH 会话与工作区管理——工作区：归档与显示。会话：跨工
 
 ### 1.4 插件更新与设置卡片
 
-- **检查更新**：会话管理窗口顶部增加 🐋（鲸鱼）图标按钮，点击可检查新版本并在有更新时展示小红点提示；点击弹出更新窗口，展示当前版本与最新版本，支持一键调用插件管理器安装更新。
+- **检查更新**：会话管理窗口顶部提供 🐋（鲸鱼）图标按钮，点击可检查新版本并在有更新时展示小红点提示；点击弹出更新窗口，展示当前版本与最新版本，支持一键调用插件管理器安装更新。
 - **设置卡片**：注册在 DSH 设置的插件配置页（`settings.plugin.item`）。展示当前安装版本、最新版本状态、卡片内检查更新与更新按钮、自动检查偏好开关以及 GitHub 仓库链接。
 - **安装源选择**：在设置卡片中可随时切换安装源，可选 **npm 官方源**（`registry.npmjs.org`，默认）与 **中国大陆镜像源**（`registry.npmmirror.com`）；检查更新与版本下载将直接请求所选源。
 - **弹窗透明度**：设置卡片「偏好设置」区域提供 50%–100% 滑块（步长 5%，默认 100%）与「恢复默认」按钮，支持调节插件弹窗的背景填充透明度，文字、按钮、输入框、标签与边框等内容保持不透明并即时生效。
 - **主题**：全面跟随 DSH 当前主题（包含第三方主题插件），弹窗、设置卡片、标题栏按钮、下拉菜单、输入框等界面元素自动适配浅色与深色主题。
 - **统一下拉样式**：所有下拉选择框（排序、筛选、优先级等）采用无四周阴影的统一圆角自定义浮层，严格对齐触发框宽度，并解决 Chromium 原生系统弹层与自定义浮层重叠的双层问题。
 
-### 1.5 工作区归档与管理（v0.7.0 新增）
+### 1.5 工作区归档与管理
 
 - **双页面切换**：在管理弹窗顶部可在「会话管理」与「工作区管理」之间无缝切换，保留各自的搜索与筛选状态。
 - **工作区列表**：完整展示全部已注册工作区，包含工作区名称、物理路径、所属会话数、基于所属会话计算的最近更新时间及状态开关。
@@ -138,21 +139,22 @@ dsh plugin --profile web add <本仓库路径>
 
 ## 5 兼容性
 
-DSH 版本在上，插件版本在下；每列表示一组已测试的版本组合。
-
-> 版本验证说明：自 0.6.3 起，本插件仅在官方 DSH Desktop 客户端上进行验证（Web UI 与本插件共用同一套 Host / 客户端代码，但不再纳入验证范围）。
-
-| v0.2.0-rc.2 | v0.1.7-rc.2 | v0.1.7-rc.1 |
-| --- | --- | --- |
-| 0.7.1, 0.7.0, 0.6.4, 0.6.3, 0.6.2, 0.5.4 | 0.5.3 | 0.5.2 |
-
-| v0.1.6-alpha.2 | v0.1.5-rc.2 | v0.1.5-rc.1 |
-| --- | --- | --- |
-| 0.5.1 | 0.4.11 | 0.4.10, 0.4.9, 0.4.7 |
-
-| v0.1.3-alpha.2 | v0.1.2-rc.1 | v0.1.0-rc.7 |
-| --- | --- | --- |
-| 0.4.6, 0.4.4, 0.4.1 | 0.4.0 | 0.1.2, 0.1.1, 0.1.0 |
+下表列出 DeepSeek Harness（DSH）与 `dsh-session-manager` 已验证的版本组合。
+
+> **版本验证说明**：自 0.6.3 起，本插件仅在官方 DSH Desktop 客户端上进行验证（Web UI 与本插件共用同一套 Host / 客户端代码，但不再纳入常规验证范围）。
+
+| DeepSeek Harness (DSH) | dsh-session-manager | 验证环境 |
+| :--- | :--- | :--- |
+| **v0.2.1-rc.2** | `0.7.2` | Desktop |
+| **v0.2.0-rc.2** | `0.7.1`, `0.7.0`, `0.6.4`, `0.6.3`, `0.6.2`, `0.5.4` | Desktop |
+| **v0.1.7-rc.2** | `0.5.3` | Desktop / Web UI |
+| **v0.1.7-rc.1** | `0.5.2` | Desktop / Web UI |
+| **v0.1.6-alpha.2** | `0.5.1` | Web UI |
+| **v0.1.5-rc.2** | `0.4.11` | Web UI |
+| **v0.1.5-rc.1** | `0.4.10`, `0.4.9`, `0.4.7` | Web UI |
+| **v0.1.3-alpha.2** | `0.4.6`, `0.4.4`, `0.4.1` | Web UI |
+| **v0.1.2-rc.1** | `0.4.0` | Web UI |
+| **v0.1.0-rc.7** | `0.1.2`, `0.1.1`, `0.1.0` | Web UI |
 
 以上版本组合已在官方 Web UI 或 Desktop 客户端中完成测试。其他版本组合可能同样兼容，但未逐一验证。
 

package/lib/client.js

@@ -862,7 +862,8 @@ function isTopmostDialog(z) {
       ".sm-bulkResultItemReason{color:var(--dsw-alias-state-error-primary);font-size:11px;line-height:16px;word-break:break-word}",
       ".sm-bulkResultItemReasonSkip{color:var(--dsw-alias-label-tertiary,#888)}",
       ".sm-bulkResultFooter{display:flex;justify-content:space-between;align-items:center;gap:8px;flex-wrap:wrap}",
-      ".sm-footerBtn-wide{flex:none;display:flex;align-items:center;gap:8px;width:calc(100% + 8px);height:34px;margin:4px -4px 4px;padding:6px 2px 6px 10px;box-sizing:border-box;border:none;border-radius:12px;cursor:pointer;overflow:hidden;font-size:14px;line-height:22px}",
+      "[class*=footerActions]:has(.sm-footerBtn-wide),[class*=footer-actions]:has(.sm-footerBtn-wide),[class*=footer]:has(> .sm-footerBtn-wide),[class*=footer] > div:has(> .sm-footerBtn-wide){flex-wrap:wrap;align-content:flex-start;height:auto}",
+      ".sm-footerBtn-wide{flex:1 1 100%;display:flex;align-items:center;gap:8px;width:calc(100% + 8px);height:34px;margin:4px -4px 4px;padding:6px 2px 6px 10px;box-sizing:border-box;border:none;border-radius:12px;cursor:pointer;overflow:hidden;font-size:14px;line-height:22px}",
       ".sm-footerBtn-wide:hover,.sm-footerBtn-wide:focus-visible{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}",
       ".sm-footerBtn-rail{width:36px;height:36px;padding:0;justify-content:center;border-radius:12px;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:0;display:inline-flex;align-items:center}",
       ".sm-footerBtn-rail:hover,.sm-footerBtn-rail:focus-visible{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}",
@@ -2100,6 +2101,18 @@ function isTopmostDialog(z) {
       }
     }
 
+    function getTargetSmSelect(target) {
+      if (!target || typeof target.closest !== "function") return null;
+      const direct = target.closest(SM_SELECT_SELECTOR);
+      if (direct && direct.tagName === "SELECT") return direct;
+      const container = target.closest(".sm-wsSortField, .sm-annotationPriority, .sm-viewField, .sm-moveSection, .sm-settingsRow, .sm-customSelectWrapper");
+      if (container) {
+        const sel = container.querySelector("select");
+        if (sel && sel.tagName === "SELECT") return sel;
+      }
+      return null;
+    }
+
     function installCustomDropdownInterceptor() {
       if (typeof document === "undefined" || typeof document.addEventListener !== "function") {
         return () => {};
@@ -2113,24 +2126,8 @@ function isTopmostDialog(z) {
         if (activeCustomMenu && activeCustomMenu.contains(e.target)) return;
         if (e.target?.closest?.("button, input, textarea, a")) return;
 
-        let select = null;
-        if (e.target?.matches?.("select")) {
-          select = e.target;
-        } else if (e.target?.closest?.("select")) {
-          select = e.target.closest("select");
-        } else {
-          const container = e.target?.closest?.(".sm-wsSortField, .sm-annotationPriority, .sm-viewField, .sm-moveSection, .sm-settingsRow, .sm-customSelectWrapper");
-          if (container) {
-            select = container.querySelector("select");
-          } else {
-            const nearest = e.target?.closest?.(SM_SELECT_SELECTOR);
-            if (nearest && nearest.tagName === "SELECT") {
-              select = nearest;
-            }
-          }
-        }
-
-        if (select && select.tagName === "SELECT") {
+        const select = getTargetSmSelect(e.target);
+        if (select) {
           e.preventDefault();
           e.stopPropagation();
           if (select.disabled) return;
@@ -2146,14 +2143,8 @@ function isTopmostDialog(z) {
 
       const onClick = (e) => {
         if (e.target?.closest?.("button, input, textarea, a")) return;
-        let select = null;
-        if (e.target?.matches?.("select")) {
-          select = e.target;
-        } else {
-          const container = e.target?.closest?.(".sm-wsSortField, .sm-annotationPriority, .sm-viewField, .sm-moveSection, .sm-settingsRow, .sm-customSelectWrapper");
-          if (container) select = container.querySelector("select");
-        }
-        if (select && select.tagName === "SELECT") {
+        const select = getTargetSmSelect(e.target);
+        if (select) {
           e.preventDefault();
           e.stopPropagation();
         }
@@ -2170,7 +2161,7 @@ function isTopmostDialog(z) {
         }
 
         const focused = document.activeElement;
-        const targetSelect = activeCustomSelect || (focused?.matches?.(SM_SELECT_SELECTOR) ? focused : null) || (focused?.closest?.(".sm-wsSortField, .sm-annotationPriority, .sm-viewField, .sm-moveSection, .sm-settingsRow")?.querySelector("select"));
+        const targetSelect = activeCustomSelect || getTargetSmSelect(focused);
         if (!targetSelect || targetSelect.tagName !== "SELECT") return;
 
         if (e.key === "Enter" || e.key === " ") {
@@ -2196,7 +2187,14 @@ function isTopmostDialog(z) {
         }
       };
 
-      const onResizeOrScroll = () => {
+      const onResizeOrScroll = (e) => {
+        // Ignore scrolls that originate inside the open menu: the listener is bound on
+        // window with capture=true, so scrolling the menu's own option list (wheel or
+        // scrollbar drag) would otherwise close it immediately.
+        // Reference: PR #37
+        if (activeCustomMenu && e && e.type === "scroll" && e.target && typeof activeCustomMenu.contains === "function" && activeCustomMenu.contains(e.target)) {
+          return;
+        }
         if (activeCustomMenu) closeCustomSelect();
       };
 
@@ -3749,7 +3747,7 @@ function isTopmostDialog(z) {
       ));
     }
 
-    const CURRENT_VERSION = "0.7.1";
+    const CURRENT_VERSION = "0.7.2";
 
     function compareSemver(v1, v2) {
       if (typeof v1 !== "string" || typeof v2 !== "string") return 0;
@@ -6856,6 +6854,7 @@ function isTopmostDialog(z) {
     exports.openCustomSelect = openCustomSelect;
     exports.closeCustomSelect = closeCustomSelect;
     exports.installCustomDropdownInterceptor = installCustomDropdownInterceptor;
+    exports.getTargetSmSelect = getTargetSmSelect;
     exports.SM_SELECT_SELECTOR = SM_SELECT_SELECTOR;
     return module.exports;
   }

package/lib/index.js

@@ -28,7 +28,7 @@ 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 { 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 +125,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 +156,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); }
@@ -170,7 +176,7 @@ const listSessionHeaders = async (persistence, dshHome) => (await scanSessionHea
 
 export function apply(ctx) {
   try {
-    const buildId = "dsh-session-manager v0.7.1 (workspace-archive)";
+    const buildId = "dsh-session-manager v0.7.2 (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 +1258,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,7 +2024,7 @@ ${rest}`, "utf8");
           return send(res, 200, { ok: true, result });
         }
         if (req.method === "GET" && path === "/update/check") {
-          const currentVersion = adapter.pluginVersion() || "0.7.1";
+          const currentVersion = adapter.pluginVersion() || "0.7.2";
           let latestVersion = currentVersion;
           let hasUpdate = false;
           try {
@@ -2111,4 +2122,4 @@ ${rest}`, "utf8");
   }), "session-manager: http api");
 }
 
-export { listSessionHeaders, scanSessionHeaders, encodeSessionSegment, compareSemver };
+export { listSessionHeaders, scanSessionHeaders, candidateSessionDirs, encodeFsSessionSegment, decodeFsSessionSegment, encodeProjectSegment, encodeSessionSegment, compareSemver };

package/lib/session-files.js

@@ -21,7 +21,7 @@ const MAX_HEADER_BYTES = 1024 * 1024;
 
 export function assertSessionId(id) {
   if (typeof id !== "string" || id.trim() === "" || id === "." || id === ".."
-    || /[\\/\x00-\x1f<>:"|?*]/.test(id) || /[. ]$/.test(id)) {
+    || /[\\/\x00-\x1f<>"|?*]/.test(id) || /[. ]$/.test(id)) {
     throw Object.assign(new Error("sessionId 必须是合法的会话标识，不能包含路径或特殊目录名"), { code: "bad-request" });
   }
   return id;
@@ -46,12 +46,56 @@ export function parseSessionGenerationFromFilename(filename) {
   return match[1] !== undefined ? Number(match[1]) : 0;
 }
 
-export function encodeSessionSegment(id) {
+/**
+ * Encode a session ID into its on-disk session directory name,
+ * matching DSH kernel's `encodeSegment` contract in
+ * packages/session/session-persistence-jsonl/src/format.ts:
+ * - "." -> "~002E"
+ * - ".." -> "~002E~002E"
+ * - Safe chars [A-Za-z0-9._-] (except "~") remain unchanged
+ * - Other characters (including ":", "~", non-ASCII) are escaped as ~XXXX (4-digit uppercase hex)
+ */
+export function encodeFsSessionSegment(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error("cannot encode an empty path segment");
+  }
+  if (raw === ".") return "~002E";
+  if (raw === "..") return "~002E~002E";
+  let out = "";
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    const ch = String.fromCharCode(code);
+    if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) {
+      out += ch;
+    } else {
+      out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+    }
+  }
+  return out;
+}
+
+/**
+ * Decode an on-disk session directory name back to raw session ID.
+ */
+export function decodeFsSessionSegment(encoded) {
+  if (typeof encoded !== "string" || encoded.length === 0) return encoded;
+  if (encoded === "~002E") return ".";
+  if (encoded === "~002E~002E") return "..";
+  return encoded.replace(/~([0-9A-Fa-f]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+
+/**
+ * Encode a project directory path (cwd) into its on-disk project directory key,
+ * matching DSH kernel's `projectKey` contract:
+ * Wrapping "--...--" markers with path separators collapsed into "-".
+ */
+export function encodeProjectSegment(path) {
+  if (typeof path !== "string") return "--root--";
   let readable = "";
   let separatorRun = false;
-  for (let i = 0; i < id.length; i++) {
-    const ch = id[i];
-    const code = id.charCodeAt(i);
+  for (let i = 0; i < path.length; i++) {
+    const ch = path[i];
+    const code = path.charCodeAt(i);
     if (ch === "/" || ch === "\\" || ch === ":") {
       if (!separatorRun) readable += "-";
       separatorRun = true;
@@ -66,6 +110,28 @@ export function encodeSessionSegment(id) {
   return "--" + (readable.replace(/^-+/, "") || "root").slice(0, 251) + "--";
 }
 
+/**
+ * Legacy alias for `encodeProjectSegment`.
+ * @deprecated Use `encodeProjectSegment` for project cwd keys, or `encodeFsSessionSegment` for session directories.
+ */
+export const encodeSessionSegment = encodeProjectSegment;
+
+/**
+ * Return strictly verified candidate directory names for a given session ID.
+ * - Primary: DSH's true `encodeFsSessionSegment(id)` (e.g. "im~003Afeishu...")
+ * - Raw `id`: matches when raw ID equals encoded ID (common UUIDs), or if raw dir was used
+ * - Legacy projectKey format: transitional compatibility for `--id--` created by older plugin versions
+ */
+export function candidateSessionDirs(id) {
+  assertSessionId(id);
+  const primary = encodeFsSessionSegment(id);
+  const candidates = [primary];
+  if (id !== primary) candidates.push(id);
+  const legacyProject = encodeProjectSegment(id);
+  if (legacyProject !== primary && legacyProject !== id) candidates.push(legacyProject);
+  return candidates;
+}
+
 /** Only an actual <sessions>/<project>/<session> directory may be mutated.
  * The root itself may be configured through a symlink, but neither child may
  * be a symlink/junction. Check again immediately before destructive cleanup.
@@ -79,8 +145,9 @@ export async function assertSessionDirectory(root, directory, id, { allowMissing
   const target = resolve(directory);
   const rel = relative(base, target);
   const parts = rel.split(sep);
+  const validDirs = candidateSessionDirs(id);
   if (isAbsolute(rel) || parts.length !== 2 || parts.some(p => p === ".." || p === "." || p === "")
-    || ![id, encodeSessionSegment(id)].includes(parts[1])) {
+    || !validDirs.includes(parts[1])) {
     throw new Error("会话目录超出允许范围，已停止文件操作");
   }
   const canonicalRoot = await fs.realpath(base);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-manager",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "DeepSeek Harness session and workspace manager —— Workspaces: archive and visibility. Sessions: move, migrate presets, delete, favorite, review later, prioritize, tag, and annotate. Batch operations. | DSH 会话与工作区管理——工作区：归档与显示。会话：跨工作区移动、预设迁移、删除；收藏、待回看、优先级、标签、备注。批量操作。",
   "license": "MIT",
   "keywords": [