dsh-session-curator 0.1.2 → 0.3.0

package/lib/host/delete.js

@@ -0,0 +1,77 @@
+/**
+ * 危险操作：**物理删除**（不可恢复）。
+ *
+ * 为什么不再是"软删除到回收站"：回收站与归档在做同一件事（把会话从侧边栏藏起来、之后还能
+ * 找回来），而归档是 DSH 自带的机制、不动磁盘、随时可逆。所以删除就做成**真正的删除**：
+ * 删掉 `<DSH_HOME>/sessions/<slug>/<sessionId>/` 与它的投影缓存，不可撤销。想留退路的
+ * 用户在确认弹窗里会被明确提示改用归档。
+ *
+ * 顺序不能随便改（与旧 `purge` 同一条教训）：**先把记账清干净，再删目录**。
+ *   - `archivedSessionIds` / `pinnedSessionIds` 是持久化的集合，删除后还留着 id 就是一条
+ *     "DSH 一直以为它归档着、界面上又找不到"的永久幽灵；
+ *   - 工作区记账（`sessionIds`）同样要摘掉，否则侧边栏的"未分组"里会留一条点不开的幽灵行；
+ *   - 目录最后删。万一 `rm` 失败（占用 / 权限），这一项在 `results[]` 里报失败，会话还在
+ *     磁盘上，只是已经被取消归档 —— 用户仍然看得到它，可以重试，不会凭空丢数据。
+ *
+ * 正在跑的会话与**当前正在使用的会话**一律拒绝删除：前者由官方的
+ * `workspace/session-activity` 判定（与官方归档同一条判据），后者是
+ * `process.env.DSH_SESSION_ID`。
+ */
+import { promises as fsp } from "node:fs";
+import { messageOf } from "./fs-utils.js";
+import { projCacheFile } from "./paths.js";
+/**
+ * 逐项物理删除：会话目录 + 投影缓存，并把归档 / 置顶 / 工作区三处记账清干净。
+ *
+ * 单项失败只留在 `results[]` 里，不影响其余项（`each()` 的语义）。
+ */
+export async function deleteSessions(host, ids) {
+    const dirs = await host.scanSessionDirs();
+    return host.each(ids, async (sessionId) => {
+        const steps = [];
+        if (sessionId === process.env.DSH_SESSION_ID) {
+            throw new Error("这是当前正在使用的会话，不能删除");
+        }
+        const activity = await host.sessionActivity(sessionId);
+        if (activity.length > 0)
+            throw new Error("会话正在运行，请先停止它");
+        const info = dirs.get(sessionId);
+        if (!info)
+            throw new Error("找不到会话日志目录（可能已被删除）");
+        // 三处记账先清：见文件头"顺序不能随便改"。
+        if (host.registry.archivedSessionIds.includes(sessionId)) {
+            await host.registry.unarchiveSession(sessionId);
+            steps.push("unarchive");
+        }
+        if (host.registry.pinnedSessionIds.includes(sessionId)) {
+            await host.registry.unpinSession(sessionId);
+            steps.push("unpin");
+        }
+        const workspace = host.findWorkspaceOf(sessionId);
+        if (workspace) {
+            try {
+                if (typeof workspace.detachSession === "function") {
+                    await workspace.detachSession(sessionId);
+                    steps.push("detach");
+                }
+            }
+            catch (error) {
+                // 摘不掉记账不该阻止删除：目录没了之后 DSH 自己也会把它清掉。
+                steps.push(`detach-failed:${messageOf(error)}`);
+            }
+        }
+        // 会话目录整个删掉（这是唯一不可逆的一步）。
+        await fsp.rm(info.dir, { recursive: true, force: true });
+        steps.push("delete");
+        // 投影缓存是 DSH 自己的文件（`storages/session_projcache/sessions/<id>.json`）：
+        // 会话都没了，留着一份标题 / cwd 的缓存只会在下次重建列表时对不上。
+        try {
+            await fsp.rm(projCacheFile(sessionId), { force: true });
+            steps.push("projcache");
+        }
+        catch {
+            // 缓存删不掉不影响会话本身
+        }
+        return steps;
+    });
+}

package/lib/host/fs-utils.js

@@ -1,37 +1,61 @@
 /** 文件系统小工具 + 错误消息归一化。 */
 import { promises as fsp } from "node:fs";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 /** 任何抛出物 → 一句人话（宿主 logger 与端点错误信封都用它）。 */
 export function messageOf(error) {
     if (error instanceof Error)
         return error.message;
     return String(error);
 }
-/** 跨卷 rename 会抛 EXDEV，退回 copy + rm。 */
-export async function moveDir(from, to) {
-    await fsp.mkdir(dirname(to), { recursive: true });
-    try {
-        await fsp.rename(from, to);
-        return;
-    }
-    catch (error) {
-        if (error?.code !== "EXDEV")
-            throw error;
-    }
-    await fsp.cp(from, to, { recursive: true, force: true });
-    await fsp.rm(from, { recursive: true, force: true });
+/**
+ * 最多 `limit` 个任务同时在跑；返回值**按入参顺序**排列。
+ *
+ * 为什么不用 `Promise.all(items.map(...))`：快照要一次给上百个目录做 `readdir` + `stat`，
+ * 无上限并发会把磁盘打成一锅粥（Windows 上尤其明显，还会跟 DSH 自己的会话扫描抢 IO）。
+ * 这里只做"有上限的并发"，超出的任务排队，单项抛错照原样往外冒（由调用方决定怎么办）。
+ */
+export async function mapLimit(items, limit, worker) {
+    const size = items.length;
+    const results = new Array(size);
+    if (size === 0)
+        return results;
+    const width = Math.max(1, Math.min(Math.floor(limit) || 1, size));
+    let next = 0;
+    const run = async () => {
+        while (next < size) {
+            const index = next;
+            next += 1;
+            results[index] = await worker(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: width }, run));
+    return results;
+}
+const DIR_STATS_CACHE = new Map();
+/** 缓存上限：超过就整个清掉。磁盘目录数远小于它，这里只是防止长期运行无限增长。 */
+const DIR_STATS_CACHE_LIMIT = 2000;
+/** 给自检用：清掉缓存后重新统计（`scripts/smoke.mjs` 要断言"同一次快照内命中缓存"）。 */
+export function forgetDirStats() {
+    DIR_STATS_CACHE.clear();
 }
-/** 只统计顶层文件：会话目录里就是那几份日志。 */
+/** 只统计顶层文件：会话目录里就是那几份日志。目录 mtime 没变就直接回缓存。 */
 export async function dirStats(dir) {
-    let bytes = 0;
-    let files = 0;
+    let mtimeMs;
     let entries;
     try {
+        const info = await fsp.stat(dir);
+        mtimeMs = info.mtimeMs;
         entries = await fsp.readdir(dir, { withFileTypes: true });
     }
     catch {
         return { bytes: 0, files: 0 };
     }
+    const cached = DIR_STATS_CACHE.get(dir);
+    if (cached !== undefined && cached.mtimeMs === mtimeMs && cached.entryCount === entries.length) {
+        return { bytes: cached.bytes, files: cached.files };
+    }
+    let bytes = 0;
+    let files = 0;
     for (const entry of entries) {
         if (!entry.isFile())
             continue;
@@ -44,6 +68,9 @@ export async function dirStats(dir) {
             // 竞态：文件刚好消失，忽略
         }
     }
+    if (DIR_STATS_CACHE.size >= DIR_STATS_CACHE_LIMIT)
+        DIR_STATS_CACHE.clear();
+    DIR_STATS_CACHE.set(dir, { mtimeMs, entryCount: entries.length, bytes, files });
     return { bytes, files };
 }
 export async function readProjectionFile(file) {

package/lib/host/open.js

@@ -0,0 +1,98 @@
+/**
+ * 「复制路径 / 在资源管理器中显示」的宿主侧：**只认自己算出来的目录**。
+ *
+ * 安全边界（这一段是这个文件存在的全部理由）：
+ *   - 路径**不接受客户端传**：只吃 `sessionId`，由宿主自己按 `<DSH_HOME>/sessions/<slug>/<id>`
+ *     拼出来。客户端就算传了别的路径也没用 —— 入参里根本没有路径字段。
+ *   - 拼出来之后再 `resolve()` 一次并断言它落在**允许的根**（`<DSH_HOME>/sessions`）
+ *     之下。这一道是为了挡住 `../` 之类的 id（线协议的 `idsOf()` 只保证是
+ *     非空字符串，不保证它不是一个相对路径）。
+ *   - 只有 `target: "reveal"` 才会真的去叫系统文件管理器，而且只用**固定的可执行名**
+ *     （`explorer.exe` / `open` / `xdg-open`），参数是那个已经校验过的目录。不拼 shell 字符串，
+ *     走 `spawn` + 参数数组，所以路径里的空格 / 引号 / `&` 都不会被解释成命令。
+ *
+ * 为什么不用 `shell.openPath`（Electron 的 API）：宿主半区跑在 DSH 的 Electron 主进程里，
+ * 但插件是普通 ESM 模块，拿不到 `electron` 模块（那是 DSH 自己的依赖，junction 挂载下
+ * Node 按 realpath 解析根本找不到 —— 与 AGENTS.md §5 禁止裸导入 `@deepseek-ai/*` 同一条
+ * 理由）。所以这里退到"用平台自带的文件管理器命令"，零依赖。
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { messageOf } from "./fs-utils.js";
+import { sessionsRoot } from "./paths.js";
+/** `path` / `reveal`：`reveal` 之外的任何值都当成 `path`（只读，最保守的那条）。 */
+export function openTargetOf(value) {
+    return value === "reveal" ? "reveal" : "path";
+}
+/**
+ * 允许的根：整个会话目录。`resolve()` 之后比较，且要求"相等或以 `<root>+分隔符`
+ * 开头" —— 单比 `startsWith(root)` 会把 `<DSH_HOME>/sessions-evil` 放进来。
+ */
+function allowedRoots() {
+    return [resolve(sessionsRoot())];
+}
+function inside(root, target) {
+    return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/** 平台对应的文件管理器命令；不支持的平台返回 null（`path` 仍然可用）。 */
+function revealCommand() {
+    if (process.platform === "win32")
+        return { command: "explorer.exe", args: [] };
+    if (process.platform === "darwin")
+        return { command: "open", args: [] };
+    if (process.platform === "linux")
+        return { command: "xdg-open", args: [] };
+    return null;
+}
+/**
+ * 把文件管理器叫起来。**不等它退出**：`explorer.exe` 会立刻返回、`xdg-open` 可能一直活着，
+ * 等它就会把端点请求挂住。所以 `detached` + `stdio: "ignore"` + `unref()`，
+ * 只监听 `error`（命令不存在那种）；真正"有没有打开"由用户自己看得到。
+ */
+function reveal(path) {
+    const command = revealCommand();
+    if (command === null)
+        return { ok: false, reason: `不支持的平台：${process.platform}` };
+    try {
+        const child = spawn(command.command, [...command.args, path], { detached: true, stdio: "ignore" });
+        child.on("error", () => {
+            // 没有文件管理器（无头环境）不该让请求失败：路径已经回了，界面提示用户手动打开。
+        });
+        child.unref();
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, reason: messageOf(error) };
+    }
+}
+/**
+ * `open` 端点：算路径 → 校验 → （可选）叫文件管理器。
+ *
+ * `sessionId` 必须能在磁盘上找到；找不到就抛错，由信封兜住（与 `describe` 一致）。
+ */
+export async function openSession(host, ids, target) {
+    const sessionId = ids[0];
+    if (typeof sessionId !== "string" || sessionId === "")
+        throw new Error("缺少会话 id");
+    const dirs = await host.scanSessionDirs();
+    const path = dirs.get(sessionId)?.dir ?? null;
+    if (path === null)
+        throw new Error("找不到这个会话的日志目录（磁盘上不存在）");
+    const resolved = resolve(path);
+    const roots = allowedRoots();
+    if (!roots.some((root) => inside(root, resolved))) {
+        // 到不了这里才说明 id 里有 `../` 之类的东西 —— 直接拒绝，别去碰根目录外面的路径。
+        throw new Error("拒绝打开：这个路径不在 DSH 的会话目录里");
+    }
+    if (!existsSync(resolved))
+        throw new Error("日志目录已经不在了");
+    if (target !== "reveal")
+        return { sessionId, path: resolved, revealed: false };
+    const opened = reveal(resolved);
+    return opened.ok
+        ? { sessionId, path: resolved, revealed: true }
+        : { sessionId, path: resolved, revealed: false, reason: opened.reason };
+}
+/** 允许的根（导出给自检断言"路径校验真的挡得住 `../`"）。 */
+export { allowedRoots, inside as insideRoot };

package/lib/host/paths.js

@@ -25,20 +25,12 @@ export function dshHomePath(...segments) {
     return join(resolveDshHome(), ...segments);
 }
 /**
- * 回收站根目录：`<DSH_HOME>/storages/session-manager/trash`。
- *
- * 这里的 `session-manager` 是**故意不改的旧名**：插件从 `dsh-session-manager` 改名成
- * `dsh-session-curator` 时，回收站里可能还躺着用户已经删掉的会话（本机就有一个）——
- * 改路径会把它们变成孤儿。数据目录用历史名、其余 id 用新名，是权衡后的结果。
+ * 历史遗留：本插件 0.2.0 之前把"软删除"的会话搬到
+ * `<DSH_HOME>/storages/session-manager/trash`（目录名 `session-manager` 是更早的包名）。
+ * 回收站功能已在 0.3.0 移除，删除改成物理删除，所以插件**不再读写**那个目录：
+ * 里面可能还有用户当年软删除的会话，插件不主动迁移也不删除它们；需要时人工把
+ * `trash/<sessionId>/` 搬回 `sessions/<slug>/<sessionId>/` 即可。
  */
-export const TRASH_SUBPATH = ["storages", "session-manager", "trash"];
-/** 回收站条目的元数据：原 slug / cwd / 标题 / 删除时间 / 删除前是否已归档。 */
-export const META_FILE = "__trash.json";
-/** 从投影缓存搬进来的那份文件（恢复时要搬回原位）。 */
-export const PROJ_FILE = "__projcache.json";
-export function trashRoot() {
-    return dshHomePath(...TRASH_SUBPATH);
-}
 export function sessionsRoot() {
     return dshHomePath("sessions");
 }

package/lib/host/routes.js

@@ -1,5 +1,5 @@
 /**
- * 传输 / 分发：九个端点 → 九条精确 Fetch 路由。
+ * 传输 / 分发：十个端点 → 十条精确 Fetch 路由。
  *
  * ── 为什么**不用** `ctx.connection.rpc.handle()`（踩过的坑，改回去之前先读）──
  *
@@ -31,13 +31,17 @@ const ROUTE_METHODS = ["POST"];
 /** 一个频道（`/api/session-curator`）：精确路由表按完整 pathname 命中，所以每个端点一条。 */
 export const ENDPOINTS = {
     snapshot: (manager) => manager.snapshot(),
+    describe: (manager, payload) => manager.describe(payload.ids ?? []),
     archive: (manager, payload) => manager.archive(payload.ids ?? [], payload.stopActivity),
     unarchive: (manager, payload) => manager.unarchive(payload.ids ?? []),
     pin: (manager, payload) => manager.pin(payload.ids ?? []),
     unpin: (manager, payload) => manager.unpin(payload.ids ?? []),
-    trash: (manager, payload) => manager.trash(payload.ids ?? []),
-    restore: (manager, payload) => manager.restore(payload.ids ?? []),
-    purge: (manager, payload) => manager.purge(payload.ids ?? []),
+    // 物理删除：不可恢复，确认弹窗由客户端把关（见 components/dialog-host.ts）。
+    delete: (manager, payload) => manager.delete(payload.ids ?? []),
+    // 磁盘占用视图（只读）与"复制路径 / 在资源管理器中显示"。
+    usage: (manager) => manager.usage(),
+    // `target` 只认字面量 `"reveal"`；其余一律当 `"path"`（只读，最保守的那条）。
+    open: (manager, payload) => manager.open(payload.ids ?? [], payload.target === "reveal" ? "reveal" : "path"),
     "check-update": (manager, payload) => manager.checkUpdate(payload.force === true)
 };
 /** 只接受字符串数组；其余一律忽略，避免把宿主路径当 id 传来的越权尝试。 */

package/lib/host/session-manager.js

@@ -1,16 +1,29 @@
 /**
  * 会话管理器：**只读投影**（快照 / 标题 / 体积）+ 归档 / 置顶这类轻量变更。
  *
- * 危险操作（软删除 / 恢复 / 永久删除）在 `trash.ts` 里，那边带完整的事故注释；
+ * 危险操作（物理删除）在 `delete.ts` 里，那边带完整的事故注释；
  * 这里只负责把磁盘与 registry 的事实汇总成快照，以及逐项执行的框架 `each()`。
  */
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
-import { dirStats, messageOf, readProjectionFile } from "./fs-utils.js";
-import { META_FILE, dshHomePath, projCacheFile, sessionsRoot, trashRoot } from "./paths.js";
+import { dirStats, mapLimit, messageOf, readProjectionFile } from "./fs-utils.js";
+import { dshHomePath, projCacheFile, sessionsRoot } from "./paths.js";
 import { LOCAL_VERSION } from "./manifest.js";
 import { checkForUpdate } from "./update.js";
-import { purgeSessions, restoreSessions, trashSessions } from "./trash.js";
+import { deleteSessions } from "./delete.js";
+import { openSession } from "./open.js";
+/**
+ * 文件系统侧的并发上限。快照一次要给上百个目录做 `readdir` + `stat`，串行 await 会让
+ * 每次变更都慢一拍；无上限并发又会跟 DSH 自己的会话扫描抢 IO。8 是"够快且不过分"的折中。
+ */
+const FS_CONCURRENCY = 8;
+/**
+ * 活动判定的并发上限。每个会话问一次官方的 `workspace/session-activity`（瀑布钩子，
+ * 可能被别的插件挂成异步 IO），所以给得比文件系统小一些。
+ */
+const ACTIVITY_CONCURRENCY = 4;
+/** `usage` 的两个榜单各回几条（客户端的文案按同一个数字算）。 */
+export const USAGE_TOP_LIMIT = 5;
 export class SessionManager {
     ctx;
     constructor(ctx) {
@@ -65,11 +78,22 @@ export class SessionManager {
         }
         return undefined;
     }
-    async describeSession(sessionId, dirs) {
+    /**
+     * 一个会话的完整只读事实。
+     *
+     * 两件事互不依赖（投影缓存、磁盘体积），所以并发拿：单条的耗时从"两次串行 IO"
+     * 降到"最慢的那一次"。`findWorkspaceOf()` 是纯内存遍历，不必并发。
+     *
+     * `active` 由调用方注入（快照会先把整批活动判定并发算完）——`sessionActivity()` 是
+     * 瀑布钩子，逐行现问会让"有没有别的插件挂了这个钩子"直接变成列表的延迟。
+     */
+    async describeSession(sessionId, dirs, active) {
         const info = dirs.get(sessionId);
-        const projection = await this.readProjection(sessionId);
+        const [projection, stats] = await Promise.all([
+            this.readProjection(sessionId),
+            info ? this.dirStats(info.dir) : Promise.resolve({ bytes: 0, files: 0 })
+        ]);
         const workspace = this.findWorkspaceOf(sessionId);
-        const stats = info ? await this.dirStats(info.dir) : { bytes: 0, files: 0 };
         return {
             sessionId,
             title: projection.title ?? (workspace ? workspace.title : null) ?? sessionId,
@@ -80,99 +104,96 @@ export class SessionManager {
             slug: info ? info.slug : null,
             onDisk: Boolean(info),
             bytes: stats.bytes,
-            files: stats.files
+            files: stats.files,
+            active
         };
     }
-    async listTrash() {
-        const root = trashRoot();
-        let entries;
-        try {
-            entries = await fsp.readdir(root, { withFileTypes: true });
-        }
-        catch {
-            return [];
-        }
-        const rows = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const dir = join(root, entry.name);
-            let meta = null;
-            try {
-                meta = JSON.parse(await fsp.readFile(join(dir, META_FILE), "utf8"));
-            }
-            catch {
-                meta = null;
-            }
-            const stats = await this.dirStats(dir);
-            rows.push({
-                sessionId: entry.name,
-                title: typeof meta?.title === "string" && meta.title !== "" ? meta.title : entry.name,
-                cwd: typeof meta?.cwd === "string" ? meta.cwd : null,
-                slug: typeof meta?.slug === "string" ? meta.slug : null,
-                // 与 describeSession 对齐：客户端按"原来的工作区文件夹"分组要用到这两个字段。
-                workspaceId: typeof meta?.workspaceId === "string" ? meta.workspaceId : null,
-                workspaceTitle: typeof meta?.workspaceTitle === "string" ? meta.workspaceTitle : null,
-                deletedAt: typeof meta?.deletedAt === "number" ? meta.deletedAt : 0,
-                bytes: stats.bytes,
-                files: stats.files,
-                restorable: typeof meta?.slug === "string" && meta.slug !== ""
-            });
-        }
-        rows.sort((left, right) => right.deletedAt - left.deletedAt);
-        return rows;
-    }
-    /** 当前归档 / 置顶 / 回收站的完整快照，附带目录位置。 */
+    /** 当前归档 / 置顶的完整快照，附带目录位置。 */
     async buildSnapshot() {
         const registry = this.registry;
+        // 目录索引（哪些 id 真的在磁盘上）是唯一的只读来源；registry 记账可能包含已经删掉的 id。
         const dirs = await this.scanSessionDirs();
-        const trashed = await this.listTrash();
-        // 回收站条目**只**归回收站页签。删除时我们故意让 id 留在归档集合里（那是 DSH
-        // 唯一"从所有分组面消失"的机制，见 trash.ts），所以这里必须把交集滤掉：
-        // 否则同一个会话会同时出现在"已归档"和"回收站"，而"已归档"那条还是没有目录的幽灵行。
-        const inTrash = new Set(trashed.map((row) => row.sessionId));
-        const archived = [];
+        const archivedIds = [];
         for (const sessionId of registry.archivedSessionIds) {
-            // 顺带把"目录已经不在了"的 id 也滤掉：`archivedSessionIds` 是**只增不减**的记账
+            // 把"目录已经不在了"的 id 滤掉：`archivedSessionIds` 是**只增不减**的记账
             //（DSH 自己的注释：目录没了的条目照样留在集合里），而 DSH 的侧边栏只从会话清单里
             // 取行 —— 这种 id 在它那边本来就不显示。列出来只会得到一条 0 B、点不动的幽灵行。
-            if (inTrash.has(sessionId) || !dirs.has(sessionId))
+            if (!dirs.has(sessionId))
                 continue;
-            archived.push(await this.describeSession(sessionId, dirs));
+            archivedIds.push(sessionId);
         }
-        const pinned = [];
+        const pinnedIds = [];
         for (const sessionId of registry.pinnedSessionIds) {
-            if (inTrash.has(sessionId) || !dirs.has(sessionId))
+            if (!dirs.has(sessionId))
                 continue;
-            pinned.push(await this.describeSession(sessionId, dirs));
+            pinnedIds.push(sessionId);
         }
+        // 活动判定：两个集合一起去重问一遍（同一个 id 可能既归档又置顶）。结果既写进每行的
+        // `active`，也平铺成 `activeSessionIds` 给客户端的跨页签批量用。
+        const activeIds = await this.activeAmong([...new Set(archivedIds.concat(pinnedIds))]);
+        // 逐条取事实：并发上限里跑，顺序仍按 registry 给的顺序（行不会整片跳位）。
+        const [archived, pinned] = await Promise.all([
+            mapLimit(archivedIds, FS_CONCURRENCY, (sessionId) => this.describeSession(sessionId, dirs, activeIds.has(sessionId))),
+            mapLimit(pinnedIds, FS_CONCURRENCY, (sessionId) => this.describeSession(sessionId, dirs, activeIds.has(sessionId)))
+        ]);
         let archivedBytes = 0;
         for (const row of archived)
             archivedBytes += row.bytes;
-        let trashBytes = 0;
-        for (const row of trashed)
-            trashBytes += row.bytes;
         return {
             dshHome: dshHomePath(),
             version: LOCAL_VERSION,
-            trashDir: trashRoot(),
             sessionsDir: sessionsRoot(),
             archived,
             pinned,
-            trashed,
             totals: {
                 archived: archived.length,
                 archivedBytes,
-                pinned: pinned.length,
-                trashed: trashed.length,
-                trashBytes
-            }
+                pinned: pinned.length
+            },
+            activeSessionIds: [...activeIds]
         };
     }
+    /** 一批 id 里哪些正在跑（有上限地并发问 `workspace/session-activity`）。 */
+    async activeAmong(sessionIds) {
+        const flags = await mapLimit(sessionIds, ACTIVITY_CONCURRENCY, async (sessionId) => (await this.sessionActivity(sessionId)).length > 0);
+        const active = new Set();
+        sessionIds.forEach((sessionId, index) => {
+            if (flags[index] === true)
+                active.add(sessionId);
+        });
+        return active;
+    }
     // ── 变更操作 ─────────────────────────────────────────────────────────
     snapshot() {
         return this.buildSnapshot();
     }
+    /**
+     * **单个**会话的完整事实（侧边栏 hover 卡片用）。
+     *
+     * 入参复用 `ids`（线协议的 `idsOf()` 只接受字符串数组）：取第一条，其余忽略 ——
+     * hover 卡片一次只问一个会话，把它做成批量端点没有意义。
+     *
+     * 客户端的 hover 会在 800ms 之后触发、且**每次划过都会问**，所以这里刻意只做
+     * `scanSessionDirs()` + 单条 `dirStats()`，不做全量快照；端到端的节流由客户端那份
+     * 带 TTL 的缓存负责（`src/client/detail.ts`）。
+     */
+    async describe(ids) {
+        const sessionId = ids[0];
+        if (typeof sessionId !== "string" || sessionId === "")
+            throw new Error("缺少会话 id");
+        const registry = this.registry;
+        const archived = registry.archivedSessionIds.includes(sessionId);
+        const pinned = registry.pinnedSessionIds.includes(sessionId);
+        const dirs = await this.scanSessionDirs();
+        if (!dirs.has(sessionId))
+            throw new Error("找不到这个会话（日志目录不在磁盘上）");
+        const row = await this.describeSession(sessionId, dirs, (await this.sessionActivity(sessionId)).length > 0);
+        return {
+            ...row,
+            archived,
+            pinned
+        };
+    }
     /** 逐个执行，单项失败只记录在 results 里，不影响其余项。 */
     async each(ids, action) {
         const results = [];
@@ -213,18 +234,107 @@ export class SessionManager {
             return [];
         }
     }
-    // ── 危险操作：实现在 trash.ts（那边有完整的事故注释） ─────────────────
-    trash(ids) {
-        return trashSessions(this, ids);
+    // ── 危险操作：物理删除，实现在 delete.ts（那边有完整的事故注释） ─────
+    delete(ids) {
+        return deleteSessions(this, ids);
     }
-    restore(ids) {
-        return restoreSessions(this, ids);
+    /** 复制路径 / 在资源管理器中显示（实现在 `open.ts`，那边有完整的路径校验注释）。 */
+    open(ids, target) {
+        return openSession(this, ids, target);
     }
-    purge(ids) {
-        return purgeSessions(this, ids);
+    /**
+     * 磁盘占用视图（只读）：整个 `<DSH_HOME>/sessions` 的占用合计 + 两个榜单。
+     *
+     * 与 `buildSnapshot()` 的关系：两者都读同一批目录，`dirStats()` 的 mtime 缓存让重复的
+     * 目录遍历只有第一次真的走磁盘；快照刚刚跑过的那批（归档 / 置顶）在这里直接命中缓存。
+     *
+     * 为什么要有这条端点而不是让客户端从快照里算：快照只有两个集合，**普通会话**（正在用的
+     * 那些）根本不在里面 —— 而"哪些会话最占地方"恰恰要问全部。
+     *
+     * 聚合按会话**当前所在的文件夹**（投影缓存里的 cwd）：与列表分组同一套键，用户看到的
+     * "工作区"是同一个东西。
+     */
+    async usage() {
+        const registry = this.registry;
+        const dirs = await this.scanSessionDirs();
+        const onDiskIds = [...dirs.keys()];
+        const activeIds = await this.activeAmong(onDiskIds);
+        const rows = [];
+        const push = (row) => {
+            rows.push(row);
+        };
+        await mapLimit(onDiskIds, FS_CONCURRENCY, async (sessionId) => {
+            const described = await this.describeSession(sessionId, dirs, activeIds.has(sessionId));
+            push({
+                sessionId,
+                title: described.title,
+                cwd: described.cwd,
+                workspaceTitle: described.workspaceTitle,
+                bytes: described.bytes,
+                files: described.files,
+                createdAt: described.createdAt,
+                archived: registry.archivedSessionIds.includes(sessionId),
+                pinned: registry.pinnedSessionIds.includes(sessionId),
+                active: described.active
+            });
+        });
+        let totalBytes = 0;
+        const groups = new Map();
+        for (const row of rows) {
+            totalBytes += row.bytes;
+            const key = groupKeyOfRow(row);
+            const group = groups.get(key);
+            if (group === undefined) {
+                groups.set(key, { key, title: groupTitleOf(row), count: 1, bytes: row.bytes });
+            }
+            else {
+                group.count += 1;
+                group.bytes += row.bytes;
+            }
+        }
+        // 榜单按"体积 / 时间"取前 N 条：客户端只画这几条，"最占地方"也不该把 191 行都发过去。
+        const largest = [...rows].sort((left, right) => right.bytes - left.bytes).slice(0, USAGE_TOP_LIMIT);
+        const oldest = [...rows]
+            // 没有创建时间的沉底（`createdAt: null`）：`0` 会让它们排到最前面，看起来像"最老的"。
+            .sort((left, right) => (left.createdAt ?? Number.POSITIVE_INFINITY) - (right.createdAt ?? Number.POSITIVE_INFINITY))
+            .slice(0, USAGE_TOP_LIMIT);
+        return {
+            totalSessions: rows.length,
+            totalBytes,
+            groups: [...groups.values()].sort((left, right) => right.bytes - left.bytes),
+            largest,
+            oldest
+        };
     }
     /** 更新检查：只读，结果在模块级缓存（见 update.ts）。 */
     checkUpdate(force) {
         return checkForUpdate(force);
     }
 }
+/**
+ * 聚合用的分组键：与客户端 `groups.ts` 的 `groupKeyOf()` **同一套语义**（cwd 归一化后优先，
+ * 其次 workspaceId，最后"未知目录"）。两边各写一份是因为客户端那份在浏览器里、这份在宿主，
+ * 但规则必须一致 —— 否则"磁盘占用"里的工作区名会和列表分组对不上。
+ */
+function groupKeyOfRow(row) {
+    if (typeof row.cwd === "string" && row.cwd.trim() !== "") {
+        return `cwd:${row.cwd
+            .trim()
+            .replace(/[\\/]+$/, "")
+            .replace(/\\/g, "/")
+            .toLowerCase()}`;
+    }
+    return "unknown";
+}
+/** 分组标题：workspaceTitle 优先，其次路径尾段，最后交给客户端填"未知目录"。 */
+function groupTitleOf(row) {
+    if (typeof row.workspaceTitle === "string" && row.workspaceTitle !== "")
+        return row.workspaceTitle;
+    if (typeof row.cwd === "string" && row.cwd !== "") {
+        const parts = row.cwd.split(/[\\/]/).filter((part) => part !== "");
+        if (parts.length > 0)
+            return parts[parts.length - 1];
+        return row.cwd;
+    }
+    return "";
+}