dsh-session-conductor 1.3.8 → 1.3.10

package/lib/features/member-model/command.js

@@ -17,7 +17,7 @@
 //   就抛 ERR_MODULE_NOT_FOUND，连累整个插件加载失败（本项目在 defineTool / createUserMessage
 //   上踩过同类坑）。因此拿不到宿主能力时**跳过注册并如实留痕**，绝不影响插件其它功能。
 import { log } from "../../shared/log.js";
-import { findTargetAgent, pickTeamCaller } from "./locate.js";
+import { findTargetAgent, collectTeamMembers } from "./locate.js";
 import { getMemberModelOverride } from "./override.js";
 import { readLastRequestModel, registerSwitchWatch, switchAgentModel, peekLastRequestModel } from "./switch.js";
 
@@ -41,39 +41,9 @@ function memberLabel(found) {
   return name ? `${name}(${found.sessionId})` : String(found?.sessionId ?? "?");
 }
 
-/**
- * 名册：Team 成员（spawn_teammate 创建的队友，不在普通 agents 列表里）+ 普通 agents。
- * 两条来源都取不到时返回空数组（调用方据此给出可读提示）。
- */
-function collectMembers(ctx) {
-  const out = [];
-  const seen = new Set();
-  const push = (id, name, extra = {}) => {
-    if (!id || seen.has(id)) return;
-    seen.add(id);
-    out.push({ id, name: name ?? null, ...extra });
-  };
-  try {
-    const teams = ctx?.get?.("agentTeams");
-    const caller = pickTeamCaller(ctx);
-    if (teams?.listMembers && caller) {
-      for (const m of teams.listMembers(caller) ?? []) push(m?.id ?? m?.sessionId, m?.name, { provider: m?.provider, model: m?.model, source: "名册" });
-    }
-  } catch (error) {
-    log(ctx, `模型指令：读 Team 名册失败（跳过该来源）: ${String(error?.message ?? error)}`);
-  }
-  try {
-    const agents = ctx?.get?.("agents");
-    for (const a of agents?.list?.() ?? []) push(a?.session?.id ?? a?.id, a?.session?.title ?? null, { source: "agent" });
-  } catch (error) {
-    log(ctx, `模型指令：读 agents 列表失败（跳过该来源）: ${String(error?.message ?? error)}`);
-  }
-  return out;
-}
-
 /** 无参：列成员与各自模型（**便宜来源**：本插件 override → 进程内最近一次请求 → 名册记录值）。 */
-async function renderMemberList(ctx) {
-  const members = collectMembers(ctx);
+async function renderMemberList(ctx, invocation) {
+  const members = collectTeamMembers(ctx, { caller: invocation?.agent ?? null });
   if (members.length === 0) {
     return "没读到任何成员。可能当前不是 Team 成员、名册不可用，或确实还没有队友。";
   }
@@ -164,8 +134,8 @@ export async function handleModelSwitchCommand(ctx, invocation) {
   const raw = String(invocation?.rawInput ?? "").trim();
   const parts = raw.split(/\s+/).filter(Boolean);
   try {
-    if (parts.length === 0) return { kind: "success", text: await renderMemberList(ctx) };
-    const found = findTargetAgent(ctx, parts[0]);
+    if (parts.length === 0) return { kind: "success", text: await renderMemberList(ctx, invocation) };
+    const found = findTargetAgent(ctx, parts[0], { caller: invocation?.agent ?? null });
     if (found?.error) return { kind: "error", text: `找不到成员：${found.error}` };
     if (parts.length === 1) return { kind: "success", text: await renderMemberDetail(found) };
     const pair = splitPair(parts[1]);

package/lib/features/member-model/locate.js

@@ -8,9 +8,13 @@
  * agentTeams.listMembers(caller) 需要一个 Team 成员作为 caller 来解析名册。
  * @returns {object|null} 可用 agent，取不到返回 null
  */
-export function pickTeamCaller(ctx) {
+export function pickTeamCaller(ctx, preferred = null) {
   const agents = ctx.get("agents");
   if (!agents) return null;
+  // 0) 调用方显式给的发起方最可靠：命令/工具都能直接拿到 invocation.agent / exec.agent。
+  //    currentInitiator() 依赖「当前在某个 agent 的异步链里」，命令处理器里经常拿不到 ——
+  //    这正是「工具能切、聊天指令说找不到成员」的根因。
+  if (preferred) return preferred;
   try {
     const initiator = agents.currentInitiator?.();
     if (initiator) return initiator;
@@ -93,14 +97,14 @@ export async function validateModelPair(ctx, provider, model) {
  * ③ 标题子串匹配（sessionTitle 快照）。
  * @returns {{sessionId: string, agent: object|null, matched: string, member?: object} | {error: string}}
  */
-export function findTargetAgent(ctx, target) {
+export function findTargetAgent(ctx, target, { caller: explicitCaller = null } = {}) {
   const raw = String(target ?? "").trim();
   if (!raw) return { error: "target 不能为空（传 sessionId / 成员名 / 标题关键字）" };
   const agents = ctx.get("agents");
   const teams = ctx.get("agentTeams");
   // ① Team 名册：name 或 id 精确匹配优先
   if (teams?.listMembers && agents) {
-    const caller = pickTeamCaller(ctx);
+    const caller = pickTeamCaller(ctx, explicitCaller);
     if (caller) {
       let members = [];
       try {
@@ -155,3 +159,45 @@ export function findTargetAgent(ctx, target) {
   if (hits.length === 0) return { error: `没有匹配「${raw}」的活跃成员（可用 list_agents 看成员列表）` };
   return { error: `「${raw}」匹配到 ${hits.length} 个成员，请用 sessionId 精确指定：${hits.map((a) => a?.session?.id).join(", ")}` };
 }
+
+/**
+ * 统一名册：Team 成员（spawn_teammate 创建的队友，不在普通 agents 列表里）+ 普通 agents。
+ *
+ * 【为什么要抽公共】聊天指令与 AI 工具原先各写一份「谁是成员」：
+ * 命令版靠 `pickTeamCaller(ctx)` 猜发起方，在命令处理器里经常拿不到 ⇒ 名册为空 ⇒
+ * 报「没有匹配的活跃成员」，而同样的名字走 AI 工具（在 agent 异步链里调用）却能找到。
+ * 现在两处都调这一个函数，并且都显式把 invocation.agent / exec.agent 传进来。
+ *
+ * @param {object} ctx 插件上下文
+ * @param {{caller?: object}} [opts] caller = 发起方 agent（命令/工具里直接给，最可靠）
+ * @returns {Array<{id, name, provider?, model?, source}>} 去重后的成员列表（取不到返回空数组）
+ */
+export function collectTeamMembers(ctx, { caller: explicitCaller = null } = {}) {
+  const out = [];
+  const seen = new Set();
+  const push = (id, name, extra = {}) => {
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    out.push({ id, name: name ?? null, ...extra });
+  };
+  const teams = ctx?.get?.("agentTeams");
+  const caller = pickTeamCaller(ctx, explicitCaller);
+  if (teams?.listMembers && caller) {
+    try {
+      for (const m of teams.listMembers(caller) ?? []) {
+        push(m?.id ?? m?.sessionId, m?.name, { provider: m?.provider, model: m?.model, source: "名册" });
+      }
+    } catch {
+      // 名册不可用：继续用 agents 列表兜底
+    }
+  }
+  try {
+    const agents = ctx?.get?.("agents");
+    for (const a of agents?.list?.() ?? []) {
+      push(a?.session?.id ?? a?.id, a?.session?.title ?? null, { source: "agent" });
+    }
+  } catch {
+    // agents 不可用：保持已有结果
+  }
+  return out;
+}

package/lib/features/session-messaging/tools.js

@@ -68,7 +68,13 @@ export async function readListIndex(ctx) {
   const archived = new Set(
     (registry?.archivedSessionIds ?? []).filter((id) => typeof id === "string" && id !== ""),
   );
-  return Object.entries(entries).map(([id, e]) => ({
+  // 回收站里的会话同样从索引直读里排除（否则面板先读索引时又会把它显示出来）
+  let hidden = new Set();
+  try {
+    const { trashedIds } = await import("../features/trash.js");
+    hidden = trashedIds(ctx);
+  } catch { /* 回收站不可用不影响索引 */ }
+  return Object.entries(entries).filter(([id]) => !hidden.has(id)).map(([id, e]) => ({
     id,
     title: e?.title ?? null,
     cwd: e?.cwd ?? null,

package/lib/features/session-ops-routes.js

@@ -9,7 +9,8 @@
 import { log } from '../shared/log.js';
 import { MSG_NEED_SESSION_ID } from '../shared/constants.js';
 import { titleString, foldTitle, workspaceNameOf, archiveTitleWithWs, stripArchiveWsPrefix } from './rename/title.js';
-import { unarchiveSession, deleteSession, undoLastMessage, deleteBatchSessions, deleteByRule } from './session-ops.js';
+import { unarchiveSession, deleteSession, undoLastMessage, deleteBatchSessions, deleteByRule, emptyTrash, purgeExpiredTrash } from './session-ops.js';
+import { listTrash, latestBatch, restoreSessions, retentionDays, setRetentionDays, loadTrash } from './trash.js';
 
 /** 按规则删除时「超期未活跃天数」入参上限（约 10 年）：防离谱值把全部会话一起圈进去。 */
 const MAX_INACTIVE_DAYS = 3650;
@@ -229,3 +230,133 @@ export function registerSessionOpsRoutes({ webServer, ctx, send, readJson, inval
       },
     });
 }
+
+/**
+ * 注册回收站相关路由。
+ *
+ * 设计要点：删除只是「打标记」，所以还原几乎零成本（文件从没动过）；
+ * 真正删盘只发生在「到期清理」与「一键清空」，两者都要二次确认或由定时器触发。
+ * @param {object} deps
+ * @param {object} deps.webServer 宿主 webServer 服务
+ * @param {object} deps.ctx 插件 ctx
+ * @param {Function} deps.send 响应发送工具
+ * @param {Function} deps.readJson 请求体解析工具
+ * @param {Function} deps.invalidateSessionListCache 会话列表缓存失效（还原后要立刻重新出现）
+ */
+export function registerTrashRoutes({ webServer, ctx, send, readJson, invalidateSessionListCache }) {
+  const touchList = () => {
+    try { invalidateSessionListCache?.(); } catch { /* 失效失败不影响回收站操作 */ }
+  };
+
+  // ---------- GET /api/session-conductor/trash ----------
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash",
+    handler: async (req, res) => {
+      try {
+        if ((req.method ?? "GET") !== "GET") return send(res, 405, { ok: false, error: { code: "METHOD", message: "Method Not Allowed" } });
+        send(res, 200, {
+          ok: true,
+          retentionDays: retentionDays(ctx),
+          items: listTrash(ctx),
+          latestBatch: latestBatch(ctx),
+        });
+      } catch (error) {
+        send(res, 500, { ok: false, error: { code: "trash-list-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+
+  // ---------- POST /api/session-conductor/trash/restore ----------
+  // body: { sessionIds: string[] } → 还原指定会话（删标记，文件本来就在）
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash/restore",
+    handler: async (req, res) => {
+      try {
+        const body = await readJson(req);
+        const ids = Array.isArray(body?.sessionIds) ? body.sessionIds : [];
+        if (ids.length === 0) return send(res, 400, { ok: false, error: { code: "bad-request", message: "sessionIds 不能为空" } });
+        const result = restoreSessions(ctx, ids);
+        if (result.restored.length > 0) touchList();
+        send(res, 200, { ok: true, ...result });
+      } catch (error) {
+        send(res, 400, { ok: false, error: { code: "restore-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+
+  // ---------- POST /api/session-conductor/trash/restore-last-batch ----------
+  // 撤销：还原最近一个批次的全部删除（一次删除操作 = 一个 batchId）
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash/restore-last-batch",
+    handler: async (req, res) => {
+      try {
+        const batch = latestBatch(ctx);
+        if (!batch) return send(res, 200, { ok: true, batchId: null, restored: [], message: "回收站是空的" });
+        const result = restoreSessions(ctx, batch.ids);
+        if (result.restored.length > 0) touchList();
+        send(res, 200, { ok: true, batchId: batch.batchId, restored: result.restored });
+      } catch (error) {
+        send(res, 400, { ok: false, error: { code: "restore-batch-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+
+  // ---------- POST /api/session-conductor/trash/empty ----------
+  // 一键清空：立即真删（不可恢复），要求 body.confirm === true
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash/empty",
+    handler: async (req, res) => {
+      try {
+        const body = await readJson(req);
+        if (body?.confirm !== true) {
+          return send(res, 400, { ok: false, error: { code: "need-confirm", message: "清空回收站不可恢复，需传 confirm=true" } });
+        }
+        const result = await emptyTrash(ctx);
+        touchList();
+        send(res, 200, { ok: true, ...result });
+      } catch (error) {
+        send(res, 400, { ok: false, error: { code: "empty-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+
+  // ---------- POST /api/session-conductor/trash/retention ----------
+  // body: { days: number } → 设置保留天数（1~365）
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash/retention",
+    handler: async (req, res) => {
+      try {
+        const body = await readJson(req);
+        const days = Number(body?.days);
+        if (!Number.isFinite(days) || days < 1) {
+          return send(res, 400, { ok: false, error: { code: "bad-request", message: "days 必须是 ≥1 的数字" } });
+        }
+        const value = setRetentionDays(ctx, days);
+        send(res, 200, { ok: true, retentionDays: value });
+      } catch (error) {
+        send(res, 400, { ok: false, error: { code: "retention-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+
+  // ---------- POST /api/session-conductor/trash/purge ----------
+  // 手动触发到期清理（面板打开时也会自动触发一次；这里供脚本/排查用）
+  webServer.register({
+    kind: "exact",
+    path: "/api/session-conductor/trash/purge",
+    handler: async (req, res) => {
+      try {
+        const result = await purgeExpiredTrash(ctx);
+        if (result.deleted.length > 0) touchList();
+        send(res, 200, { ok: true, ...result });
+      } catch (error) {
+        send(res, 400, { ok: false, error: { code: "purge-failed", message: String(error?.message ?? error) } });
+      }
+    },
+  });
+}

package/lib/features/session-ops.js

@@ -18,6 +18,8 @@ import {
 } from "../core/config.js";
 import { sessionEventsOf } from "../sessions/events.js";
 import { detachSessionAgent } from "../sessions/detach.js";
+import { markDeleted, forgetTrashed, expiredIds, loadTrash, saveTrashNow } from "./trash.js";
+import { invalidateSessionListCache } from "../sessions/list-cache.js";
 import { buildSessionListCached } from "../sessions/list.js";
 
 // ---------- 插件开关配置（：落盘 <DSH_HOME>/session-conductor/config.json）----------
@@ -105,9 +107,10 @@ export async function unarchiveSession(ctx, sessionId) {
   });
 }
 
-/** 删除会话（per-session 串行锁）：拒绝运行中/续跑中 → detach → 取消归档 → 记账清理 → 删磁盘日志 → 清理遗留定时器。
- *  同一会话的并发删除请求排队串行执行（withDeleteLock），不做交错。 */
-export async function deleteSession(ctx, sessionId) {
+/** 真删（物理删除）：拒绝运行中/续跑中 → detach → 取消归档 → 记账清理 → 删磁盘日志 → 清理遗留定时器。
+ *  同一会话的并发删除排队串行执行（withDeleteLock），不做交错。
+ *  ⚠️ 只由回收站调用（到期清理 / 一键清空），面板上的「删除」走 deleteSession（只打标记）。 */
+export async function deleteSessionPhysically(ctx, sessionId) {
   return withDeleteLock(sessionId, async () => {
     const sessions = ctx.get("sessions");
     const workspaceRegistry = ctx.get("workspaceRegistry");
@@ -195,6 +198,68 @@ export async function deleteSession(ctx, sessionId) {
   });
 }
 
+// ---------- 删除 = 打回收站标记 ----------
+
+/**
+ * 会话快照（回收站列表展示用）：只查便宜来源（内存 live → 落盘索引），**不跑全量列表构建**。
+ * 预检/快照的成本上限是「读一次内存或索引」，不是「扫一遍所有会话日志」。
+ */
+async function describeForTrash(ctx, sessionId) {
+  try {
+    const live = ctx.get("sessions")?.get?.(sessionId);
+    if (live) {
+      return { title: live.title ?? null, cwd: live.header?.cwd ?? null, updatedAt: null, archived: false };
+    }
+    const { loadListDiskCache } = await import("../sessions/list-cache.js");
+    const entry = loadListDiskCache(ctx)?.entries?.[sessionId];
+    return { title: entry?.title ?? null, cwd: entry?.cwd ?? null, updatedAt: entry?.updatedAt ?? null, archived: false };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 删除会话 = **只打回收站标记**（会话文件原样保留）。
+ * 运行中/续跑中仍然拒绝（删一个正在跑的会话没有意义）。
+ * 真正删盘只发生在：回收站到期（保留天数可配，默认 7 天）或「一键清空」。
+ */
+export async function deleteSession(ctx, sessionId) {
+  const result = await deleteBatchSessions(ctx, [sessionId]);
+  if (result.deleted.length > 0) return { ok: true, trashed: true, batchId: result.batchId };
+  const reason = result.skipped[0]?.reason ?? "error";
+  const message = reason === "running" ? "会话正在运行，无法删除" : "删除失败：会话不存在或不可读";
+  return { ok: false, error: { code: reason, message } };
+}
+
+/** 到期真删：把超过保留天数的条目从磁盘上删掉（只由定时器/手动清理调用）。 */
+export async function purgeExpiredTrash(ctx, now = Date.now()) {
+  const ids = expiredIds(ctx, now);
+  const deleted = [];
+  for (const id of ids) {
+    try {
+      const result = await deleteSessionPhysically(ctx, id);
+      if (result?.ok) { forgetTrashed(ctx, [id]); deleted.push(id); }
+    } catch { /* 单条失败跳过，下次再试 */ }
+  }
+  if (deleted.length > 0) { saveTrashNow(ctx); invalidateSessionListCache(); }
+  return { deleted, remaining: ids.length - deleted.length };
+}
+
+/** 一键清空：立即真删回收站里的全部会话（不可恢复）。 */
+export async function emptyTrash(ctx) {
+  const ids = Object.keys(loadTrash(ctx).entries);
+  const deleted = [];
+  for (const id of ids) {
+    try {
+      const result = await deleteSessionPhysically(ctx, id);
+      if (result?.ok) { forgetTrashed(ctx, [id]); deleted.push(id); }
+    } catch { /* 单条失败跳过 */ }
+  }
+  saveTrashNow(ctx);
+  invalidateSessionListCache();
+  return { deleted, remaining: ids.length - deleted.length };
+}
+
 // ---------- 撤回最后一条用户消息 ----------
 
 /**
@@ -329,48 +394,33 @@ export async function deleteBatchSessions(ctx, sessionIds) {
   const ids = [...new Set(
     (Array.isArray(sessionIds) ? sessionIds : []).filter((id) => typeof id === "string" && id !== "")
   )];
-  const deleted = [];
   const skipped = [];
-  // 修复：预检会话是否存在（live 或已持久化），不存在的进 skipped(not-found)，
-  // 不再被误报为「已删除」。persistence 不可用/返回空（如测试 mock）时保守处理：
-  // 仅当「明确知道不存在」才跳过，否则交给 deleteSession 正常判定。
-  const persistence = ctx.get("sessionPersistence");
-  const persistIds = new Set();
-  let canCheckPersist = false;
-  try {
-    // 持久化会话权威来源 = persistence.list()。
-    // ⚠️ 宿主返回的是 **SessionPersistenceSnapshot**（`{ header, revision, ... }`），
-    // 不是裸 header —— 只认 `m.id` 会得到空集合，于是每个 id 都被判成 not-found，
-    // 批量删除「全部跳过」正是这么来的（列表侧早就按 `entry.header ?? entry` 兼容了）。
-    if (persistence?.list) {
-      const metas = await persistence.list();
-      if (Array.isArray(metas)) {
-        canCheckPersist = true;
-        for (const m of metas) {
-          const id = m?.id ?? m?.header?.id;
-          if (typeof id === "string" && id !== "") persistIds.add(id);
-        }
-      }
-    }
-  } catch { canCheckPersist = false; }
+  const targets = [];
   const sessionsSvc = ctx.get("sessions");
-  const liveIds = new Set(sessionsSvc?.list?.()?.map((s) => s.id) ?? []);
+  const { findSessionLogById, sessionsRootOf } = await import("../sessions/events.js");
   for (const id of ids) {
-    // 仅当列表查询可用且明确不在其中 → not-found；否则尝试删除
-    const knownMissing = canCheckPersist ? (!liveIds.has(id) && !persistIds.has(id)) : false;
-    if (knownMissing) {
-      skipped.push({ sessionId: id, reason: "not-found" });
-      continue;
-    }
-    try {
-      const deleteResult = await deleteSession(ctx, id);
-      if (deleteResult.ok) deleted.push(id);
-      else skipped.push({ sessionId: id, reason: deleteResult.error?.code ?? "error" });
-    } catch {
-      skipped.push({ sessionId: id, reason: "error" });
+    // 运行中 / 续跑中：拒绝（删一个正在跑的会话没有意义）
+    const live = sessionsSvc?.get?.(id);
+    if (live && hasOpenTurn(live.events)) { skipped.push({ sessionId: id, reason: "running" }); continue; }
+    if (continueJobs.has(id)) { skipped.push({ sessionId: id, reason: "running" }); continue; }
+    // 存在性：live 或磁盘上确实有日志；都没有才 not-found（避免往回收站里塞垃圾 id）
+    let exists = Boolean(live);
+    if (!exists) {
+      try { exists = Boolean(findSessionLogById(id, sessionsRootOf())); } catch { exists = false; }
     }
+    if (!exists) { skipped.push({ sessionId: id, reason: "not-found" }); continue; }
+    targets.push(id);
   }
-  return { requested: ids.length, deleted, skipped };
+  if (targets.length === 0) return { requested: ids.length, deleted: [], skipped, batchId: null };
+
+  // 快照（回收站列表要显示标题/目录/删除时间）+ 统一批次号
+  const metaById = {};
+  for (const id of targets) metaById[id] = await describeForTrash(ctx, id);
+  const { batchId, marked } = markDeleted(ctx, targets, metaById);
+
+  // 列表里立刻隐藏（面板/工具都读列表与索引，两处都要失效）
+  invalidateSessionListCache();
+  return { requested: ids.length, deleted: marked, skipped, batchId };
 }
 
 /**

package/lib/features/trash.js

@@ -0,0 +1,206 @@
+// 会话回收站：删除只打标记，文件原样保留；到期或手动清空才真正删盘。
+//
+// 【为什么这么设计】删除是不可逆操作，而会话日志动辄几十 MB。把「删除」降级为
+// 「在索引里打一个标记」，就同时得到三件事：
+//   ① 还原是秒级且零风险（文件从没动过）；
+//   ② 误删可撤销（按批次整批还原）；
+//   ③ 真正删盘集中在两个可控时机 —— 到期（保留天数可配，默认 7 天）或一键清空。
+//
+// 【落盘】<DSH_HOME>/storages/dsh-session-conductor/trash.json，原子写（tmp + rename）。
+//   条目：{ [sessionId]: { deletedAt, batchId, title, cwd, updatedAt, archived } }
+//   不存在/损坏都按「空回收站」处理，绝不影响列表与删除本身。
+
+import { cfg } from "../core/config.js";
+import { getSection, setSection, saveStoreNow } from "../core/index-store.js";
+
+const TRASH_VERSION = 1;
+const DEFAULT_RETENTION_DAYS = 7;
+const MAX_RETENTION_DAYS = 365;
+const DAY_MS = 24 * 3600 * 1000;
+
+let trashCache = null;
+
+/** 读回收站（进程内只读一次；索引不可用按空处理）。
+ *  落盘统一走 <DSH_HOME>/storages/dsh-session-conductor/index.json 的 trash section。 */
+export function loadTrash(ctx) {
+  if (trashCache !== null) return trashCache;
+  trashCache = { version: TRASH_VERSION, entries: {} };
+  try {
+    const section = getSection(ctx, "trash");
+    if (section?.entries && typeof section.entries === "object") {
+      trashCache = { version: TRASH_VERSION, entries: section.entries };
+      if (Number.isFinite(section.retentionDays)) trashCache.retentionDays = section.retentionDays;
+    }
+  } catch {
+    // 索引不可用：按空回收站继续
+  }
+  return trashCache;
+}
+
+/** 立即落盘（交给统一索引存储做原子写）。失败只丢内存态，不抛。 */
+export function saveTrashNow(ctx) {
+  if (trashCache === null) return;
+  try {
+    setSection(ctx, "trash", {
+      entries: trashCache.entries,
+      ...(Number.isFinite(trashCache.retentionDays) ? { retentionDays: trashCache.retentionDays } : {}),
+    });
+    saveStoreNow(ctx);
+  } catch {
+    // 写盘失败：下次再试，不影响「已标记」的内存态
+  }
+}
+
+/**
+ * 保留天数：**优先取回收站文件里存的值**（面板上改的就是它），
+ * 没设置过才回落到配置 trashRetentionDays / 默认 7 天。范围 1~365。
+ */
+export function retentionDays(ctx) {
+  const stored = ctx ? Number(loadTrash(ctx).retentionDays) : NaN;
+  if (Number.isFinite(stored) && stored >= 1) return Math.min(MAX_RETENTION_DAYS, Math.round(stored));
+  const days = Number(cfg?.trashRetentionDays);
+  if (!Number.isFinite(days) || days < 1) return DEFAULT_RETENTION_DAYS;
+  return Math.min(MAX_RETENTION_DAYS, Math.round(days));
+}
+
+/** 设置保留天数（写回收站文件，立即生效）。 */
+export function setRetentionDays(ctx, days) {
+  const value = Math.min(MAX_RETENTION_DAYS, Math.max(1, Math.round(Number(days) || DEFAULT_RETENTION_DAYS)));
+  const trash = loadTrash(ctx);
+  trash.retentionDays = value;
+  saveTrashNow(ctx);
+  return value;
+}
+
+/** 当前被标记删除的会话 id 集合（列表/搜索据此隐藏）。 */
+export function trashedIds(ctx) {
+  return new Set(Object.keys(loadTrash(ctx).entries));
+}
+
+/** 单个会话是否在回收站里。 */
+export function isTrashed(ctx, sessionId) {
+  return typeof sessionId === "string" && sessionId !== "" && sessionId in loadTrash(ctx).entries;
+}
+
+/**
+ * 回收站列表（按删除时间倒序），附带到期时间与剩余天数。
+ * @returns {Array<{sessionId,title,cwd,updatedAt,archived,deletedAt,batchId,expiresAt,remainingDays}>}
+ */
+export function listTrash(ctx) {
+  const ttl = retentionDays(ctx) * DAY_MS;
+  const now = Date.now();
+  return Object.entries(loadTrash(ctx).entries)
+    .map(([sessionId, entry]) => {
+      const deletedAt = typeof entry?.deletedAt === "number" ? entry.deletedAt : 0;
+      const expiresAt = deletedAt + ttl;
+      return {
+        sessionId,
+        title: entry?.title ?? null,
+        cwd: entry?.cwd ?? null,
+        updatedAt: entry?.updatedAt ?? null,
+        archived: entry?.archived === true,
+        deletedAt,
+        batchId: entry?.batchId ?? "",
+        expiresAt,
+        remainingDays: Math.max(0, Math.ceil((expiresAt - now) / DAY_MS)),
+      };
+    })
+    .sort((a, b) => b.deletedAt - a.deletedAt);
+}
+
+/** 生成一个批次号（一次删除操作 = 一个批次，撤销按批次整批还原）。 */
+export function newBatchId() {
+  return `b${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/**
+ * 标记删除（不碰文件）。
+ * @param {object} ctx
+ * @param {Array<string>} sessionIds
+ * @param {object} [metaById] 会话快照（title/cwd/updatedAt/archived），用于回收站列表展示
+ * @param {string} [batchId] 指定批次（批量删除传同一个）
+ * @returns {{batchId:string, marked:string[]}}
+ */
+export function markDeleted(ctx, sessionIds, metaById = {}, batchId = newBatchId()) {
+  const trash = loadTrash(ctx);
+  const marked = [];
+  const now = Date.now();
+  for (const id of Array.isArray(sessionIds) ? sessionIds : []) {
+    if (typeof id !== "string" || id === "") continue;
+    const meta = metaById?.[id] ?? {};
+    trash.entries[id] = {
+      deletedAt: now,
+      batchId,
+      title: meta.title ?? null,
+      cwd: meta.cwd ?? null,
+      updatedAt: typeof meta.updatedAt === "number" ? meta.updatedAt : null,
+      archived: meta.archived === true,
+    };
+    marked.push(id);
+  }
+  if (marked.length > 0) saveTrashNow(ctx);
+  return { batchId, marked };
+}
+
+/**
+ * 还原指定会话（删标记，文件本来就在）。
+ * @returns {{restored:string[], missing:string[]}}
+ */
+export function restoreSessions(ctx, sessionIds) {
+  const trash = loadTrash(ctx);
+  const restored = [];
+  const missing = [];
+  for (const id of Array.isArray(sessionIds) ? sessionIds : []) {
+    if (typeof id !== "string" || id === "") continue;
+    if (id in trash.entries) {
+      delete trash.entries[id];
+      restored.push(id);
+    } else {
+      missing.push(id);
+    }
+  }
+  if (restored.length > 0) saveTrashNow(ctx);
+  return { restored, missing };
+}
+
+/** 最近一个批次（撤销用）。空回收站返回 null。 */
+export function latestBatch(ctx) {
+  const entries = Object.entries(loadTrash(ctx).entries);
+  if (entries.length === 0) return null;
+  let best = null;
+  for (const [sessionId, entry] of entries) {
+    const at = typeof entry?.deletedAt === "number" ? entry.deletedAt : 0;
+    if (best === null || at > best.deletedAt) {
+      best = { sessionId, deletedAt: at, batchId: entry?.batchId ?? "" };
+    }
+  }
+  if (best === null) return null;
+  const ids = entries.filter(([, e]) => (e?.batchId ?? "") === best.batchId).map(([id]) => id);
+  return { batchId: best.batchId, deletedAt: best.deletedAt, ids };
+}
+
+/** 已到期（超过保留天数）的会话 id。 */
+export function expiredIds(ctx, now = Date.now()) {
+  const ttl = retentionDays(ctx) * DAY_MS;
+  return Object.entries(loadTrash(ctx).entries)
+    .filter(([, entry]) => {
+      const at = typeof entry?.deletedAt === "number" ? entry.deletedAt : 0;
+      return at > 0 && now - at >= ttl;
+    })
+    .map(([id]) => id);
+}
+
+/** 从回收站移除条目（真删完成后调用；不落盘，由调用方统一保存）。 */
+export function forgetTrashed(ctx, sessionIds) {
+  const trash = loadTrash(ctx);
+  let removed = 0;
+  for (const id of Array.isArray(sessionIds) ? sessionIds : []) {
+    if (id in trash.entries) { delete trash.entries[id]; removed += 1; }
+  }
+  return removed;
+}
+
+/** 测试钩子：清空内存态。 */
+export function resetTrashForTest() {
+  trashCache = null;
+}