dsh-session-curator 0.1.2 → 0.2.0

package/lib/host/fs-utils.js

@@ -7,6 +7,30 @@ export function messageOf(error) {
         return error.message;
     return String(error);
 }
+/**
+ * 最多 `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;
+}
 /** 跨卷 rename 会抛 EXDEV，退回 copy + rm。 */
 export async function moveDir(from, to) {
     await fsp.mkdir(dirname(to), { recursive: true });
@@ -21,17 +45,31 @@ export async function moveDir(from, to) {
     await fsp.cp(from, to, { recursive: true, force: true });
     await fsp.rm(from, { recursive: true, force: true });
 }
-/** 只统计顶层文件：会话目录里就是那几份日志。 */
+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 +82,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,104 @@
+/**
+ * 「复制路径 / 在资源管理器中显示」的宿主侧：**只认自己算出来的目录**。
+ *
+ * 安全边界（这一段是这个文件存在的全部理由）：
+ *   - 路径**不接受客户端传**：只吃 `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, trashRoot } 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()), resolve(trashRoot())];
+}
+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");
+    // 磁盘优先，其次回收站：同一个 id 不可能同时在两处（删除时目录被搬走了）。
+    const dirs = await host.scanSessionDirs();
+    let path = dirs.get(sessionId)?.dir ?? null;
+    if (path === null) {
+        const inTrash = resolve(trashRoot(), sessionId);
+        if (existsSync(inTrash))
+            path = inTrash;
+    }
+    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/retention.js

@@ -0,0 +1,24 @@
+/**
+ * 保留天数 → 截止时间戳：**严格早于**它的条目才算过期。
+ *
+ * 上限 3650 天（10 年）只是防呆：`days` 来自线协议，客户端算错、或有人手工构造请求时，
+ * 别让它退化成"把整个回收站清空"；`NaN` / 负数一律夹到 1 天（而不是 0：0 会让截止时间
+ * 变成"此刻"，语义上等于清空）。
+ */
+export function retentionCutoff(days) {
+    const safe = Number.isFinite(days) ? Math.min(Math.max(Math.floor(days), 1), 3650) : 1;
+    return Date.now() - safe * 24 * 60 * 60 * 1000;
+}
+/**
+ * 一条回收站条目该不该被"清理 N 天前"带走。
+ *
+ * 三个条件缺一不可：
+ *   - `restorable`：老版本留下的、没有 `__trash.json` 的条目连原 slug 都不知道，
+ *     `deletedAt` 也就无从谈起（`listTrash()` 会给它 0）。它们只能由用户在界面上
+ *     逐条「永久删除」，绝不能被一个按时间的批量操作顺手带走；
+ *   - `deletedAt > 0`：同上，缺删除时间的条目不参与时间判断；
+ *   - `deletedAt < cutoff`：**严格**早于截止时间，边界那一条留着。
+ */
+export function isExpired(row, cutoff) {
+    return row.restorable && row.deletedAt > 0 && row.deletedAt < cutoff;
+}

package/lib/host/routes.js

@@ -1,5 +1,5 @@
 /**
- * 传输 / 分发：九个端点 → 九条精确 Fetch 路由。
+ * 传输 / 分发：十一个端点 → 十一条精确 Fetch 路由。
  *
  * ── 为什么**不用** `ctx.connection.rpc.handle()`（踩过的坑，改回去之前先读）──
  *
@@ -31,6 +31,7 @@ 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 ?? []),
@@ -38,12 +39,32 @@ export const ENDPOINTS = {
     trash: (manager, payload) => manager.trash(payload.ids ?? []),
     restore: (manager, payload) => manager.restore(payload.ids ?? []),
     purge: (manager, payload) => manager.purge(payload.ids ?? []),
+    // 保留策略的两条都只吃 `days`（不是 id 列表）：预览只读，清理是永久删除。
+    "trash-stats": (manager, payload) => manager.trashStats(daysOf(payload)),
+    "purge-older-than": (manager, payload) => manager.purgeOlderThan(daysOf(payload)),
+    // 磁盘占用视图（只读）与"复制路径 / 在资源管理器中显示"。
+    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 传来的越权尝试。 */
 export function idsOf(payload) {
     return Array.isArray(payload.ids) ? payload.ids.filter((value) => typeof value === "string" && value !== "") : [];
 }
+/**
+ * 保留天数：越界 / 非数字一律退回 **30 天**（界面的默认值）。
+ *
+ * 这里只做"是不是个正常数字"的粗校验，真正的夹取在 `retention.ts` 的
+ * `retentionCutoff()`（预览与真删共用那一份）。为什么退回 30 而不是 0：`0` 会让截止时间
+ * 变成"此刻"，等于把整个回收站当成过期 —— 缺字段的请求绝不能有这种后果。
+ */
+export function daysOf(payload) {
+    const value = payload.days;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 30;
+    return Math.min(Math.max(Math.floor(value), 1), 3650);
+}
 /**
  * 一个端点处理器。返回 Connection 的固定信封：处理器自身的业务失败走
  * `{ok:false, error}`，端点内部的逐项失败则留在 `value.results` 里。

package/lib/host/session-manager.js

@@ -6,11 +6,25 @@
  */
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
-import { dirStats, messageOf, readProjectionFile } from "./fs-utils.js";
+import { dirStats, mapLimit, messageOf, readProjectionFile } from "./fs-utils.js";
 import { META_FILE, dshHomePath, projCacheFile, sessionsRoot, trashRoot } from "./paths.js";
 import { LOCAL_VERSION } from "./manifest.js";
 import { checkForUpdate } from "./update.js";
-import { purgeSessions, restoreSessions, trashSessions } from "./trash.js";
+import { purgeOlderThan, purgeSessions, restoreSessions, trashSessions } from "./trash.js";
+import { isExpired, retentionCutoff } from "./retention.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 +79,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,7 +105,8 @@ export class SessionManager {
             slug: info ? info.slug : null,
             onDisk: Boolean(info),
             bytes: stats.bytes,
-            files: stats.files
+            files: stats.files,
+            active
         };
     }
     async listTrash() {
@@ -92,10 +118,11 @@ export class SessionManager {
         catch {
             return [];
         }
-        const rows = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
+        // 每条都要读 `__trash.json` + 遍历目录：串行时条目一多就明显卡（回收站常驻几十条）。
+        // 这里**故意**用最宽松的读法（坏 JSON / 缺字段 / 连版本都比插件新，都只是"字段缺失"）：
+        // 一次列表不该因为某一条元数据坏了就整个炸掉。要按 schema 校验、并且会拒绝未知版本的是
+        // `trash.ts` 的 `readTrashMeta()`（恢复那条路，见那边的注释）。
+        const rows = await mapLimit(entries.filter((entry) => entry.isDirectory()), FS_CONCURRENCY, async (entry) => {
             const dir = join(root, entry.name);
             let meta = null;
             try {
@@ -105,7 +132,7 @@ export class SessionManager {
                 meta = null;
             }
             const stats = await this.dirStats(dir);
-            rows.push({
+            return {
                 sessionId: entry.name,
                 title: typeof meta?.title === "string" && meta.title !== "" ? meta.title : entry.name,
                 cwd: typeof meta?.cwd === "string" ? meta.cwd : null,
@@ -117,35 +144,43 @@ export class SessionManager {
                 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;
-        const dirs = await this.scanSessionDirs();
-        const trashed = await this.listTrash();
+        // 三个只读来源互不依赖：目录索引（哪些 id 在磁盘上）、回收站清单、registry 记账。
+        const [dirs, trashed] = await Promise.all([this.scanSessionDirs(), 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` 是**只增不减**的记账
             //（DSH 自己的注释：目录没了的条目照样留在集合里），而 DSH 的侧边栏只从会话清单里
             // 取行 —— 这种 id 在它那边本来就不显示。列出来只会得到一条 0 B、点不动的幽灵行。
             if (inTrash.has(sessionId) || !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))
                 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;
@@ -166,13 +201,83 @@ export class SessionManager {
                 pinned: pinned.length,
                 trashed: trashed.length,
                 trashBytes
-            }
+            },
+            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 之后触发、且**每次划过都会问**，所以这里刻意只做
+     * `listTrash()` + `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 [trashed, activeList] = await Promise.all([
+            this.listTrash().then((rows) => rows.find((row) => row.sessionId === sessionId)),
+            this.sessionActivity(sessionId)
+        ]);
+        const active = activeList.length > 0;
+        if (trashed) {
+            return {
+                sessionId,
+                title: trashed.title,
+                cwd: trashed.cwd,
+                workspaceId: trashed.workspaceId,
+                workspaceTitle: trashed.workspaceTitle,
+                slug: trashed.slug,
+                // `__trash.json` 只记删除时间，恢复时才用得上创建时间，所以这里不硬凑。
+                createdAt: null,
+                bytes: trashed.bytes,
+                files: trashed.files,
+                onDisk: false,
+                archived,
+                pinned,
+                // 回收站条目：目录已经搬走，谈不上"正在跑"。
+                active: false,
+                trashed: true,
+                deletedAt: trashed.deletedAt,
+                restorable: trashed.restorable
+            };
+        }
+        const dirs = await this.scanSessionDirs();
+        if (!dirs.has(sessionId))
+            throw new Error("找不到这个会话（日志目录不在磁盘上）");
+        const row = await this.describeSession(sessionId, dirs, active);
+        return {
+            ...row,
+            archived,
+            pinned,
+            trashed: false,
+            deletedAt: null,
+            restorable: false
+        };
+    }
     /** 逐个执行，单项失败只记录在 results 里，不影响其余项。 */
     async each(ids, action) {
         const results = [];
@@ -223,8 +328,150 @@ export class SessionManager {
     purge(ids) {
         return purgeSessions(this, ids);
     }
+    /**
+     * 回收站保留策略的**预览**（只读）：多少条、多少字节会被"清理 N 天前"带走。
+     *
+     * 只统计**真正能清掉**的条目 —— 老版本留下的、没有 `__trash.json`（`deletedAt` 为 0 或
+     * 缺 slug）的条目不算在内：它们连删除时间都不知道，`purge-older-than` 也一定会跳过，
+     * 预览要是把它们算进去，用户点确认后就会发现"说好的 5 条只删了 3 条"。
+     */
+    async trashStats(days) {
+        const rows = await this.listTrash();
+        const cutoff = retentionCutoff(days);
+        let count = 0;
+        let bytes = 0;
+        let totalBytes = 0;
+        for (const row of rows) {
+            totalBytes += row.bytes;
+            if (isExpired(row, cutoff)) {
+                count += 1;
+                bytes += row.bytes;
+            }
+        }
+        return { days, cutoff, count, bytes, totalCount: rows.length, totalBytes };
+    }
+    /** 「清理 N 天前」：与预览同一套判据，逐项失败不影响其余项。 */
+    purgeOlderThan(days) {
+        return purgeOlderThan(this, days);
+    }
+    /** 复制路径 / 在资源管理器中显示（实现在 `open.ts`，那边有完整的路径校验注释）。 */
+    open(ids, target) {
+        return openSession(this, ids, target);
+    }
+    /**
+     * 磁盘占用视图（只读）：整个 `<DSH_HOME>/sessions` 的占用合计 + 两个榜单。
+     *
+     * 与 `buildSnapshot()` 的关系：两者都读同一批目录，`dirStats()` 的 mtime 缓存让重复的
+     * 目录遍历只有第一次真的走磁盘；快照刚刚跑过的那批（归档 / 置顶）在这里直接命中缓存。
+     *
+     * 为什么要有这条端点而不是让客户端从快照里算：快照只有三个集合，**普通会话**（正在用的
+     * 那些）根本不在里面 —— 而"哪些会话最占地方"恰恰要问全部。
+     *
+     * 聚合按会话**当前所在的文件夹**（回收站条目用 `__trash.json` 里的原 cwd）：
+     * 与列表分组同一套键，用户看到的"工作区"是同一个东西。
+     */
+    async usage() {
+        const registry = this.registry;
+        const [dirs, trashed] = await Promise.all([this.scanSessionDirs(), this.listTrash()]);
+        // 磁盘上的会话 + 回收站里的会话 = 全部会话（两边 id 不会重合，删除时目录已经搬走了）。
+        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,
+                deletedAt: null,
+                archived: registry.archivedSessionIds.includes(sessionId),
+                pinned: registry.pinnedSessionIds.includes(sessionId),
+                trashed: false,
+                active: described.active
+            });
+        });
+        for (const row of trashed) {
+            push({
+                sessionId: row.sessionId,
+                title: row.title,
+                cwd: row.cwd,
+                workspaceTitle: row.workspaceTitle,
+                bytes: row.bytes,
+                files: row.files,
+                createdAt: null,
+                deletedAt: row.deletedAt > 0 ? row.deletedAt : null,
+                archived: registry.archivedSessionIds.includes(row.sessionId),
+                pinned: false,
+                trashed: true,
+                // 目录都搬进回收站了，谈不上"正在跑"。
+                active: false
+            });
+        }
+        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,
+            onDiskSessions: onDiskIds.length,
+            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 "";
+}