dsh-any-agent 0.3.4 → 0.3.5

package/src/hub.mjs

@@ -14,6 +14,8 @@
  */
 
 import {
+  copyFileSync,
+  cpSync,
   mkdirSync,
   readFileSync,
   writeFileSync,
@@ -41,13 +43,17 @@ import {
   SENTINEL_INCLUDE_REASONING,
   SENTINEL_TTL_MS,
   STATE_FILE,
+  LEGACY_STATE_FILE,
+  USING_DEFAULT_STATE,
   DSH_HOME,
+  assertWritableDir,
   defaultApprovalPolicy,
 } from './config.mjs';
 import { AcpProcess } from './acp.mjs';
 import { readConversationMeta } from './titles.mjs';
 import { registerWorkspace, findSessionHeader } from './workspace.mjs';
 import {
+  LOCKS_DIR,
   classifyHolder,
   describeLeaseConflict,
   heartbeat as lockHeartbeat,
@@ -240,13 +246,18 @@ export function sanitizeResultForSentinel(result) {
   if (!result || typeof result !== 'object') return result ?? null;
   if (SENTINEL_INCLUDE_REASONING) return result;
   const { thinking, ...rest } = result;
+  // 正文/错误/标题同样可能夹带密钥；哨兵是落盘副本，统一套脱敏。
+  for (const key of ['answer', 'error', 'title']) {
+    if (typeof rest[key] === 'string') rest[key] = sanitizeApprovalContext(rest[key], key);
+  }
   // 工具输入里会有完整命令、路径，甚至写入的文件内容。哨兵会保留 7 天，
   // 所以按审批上下文同一套规则脱敏（密钥/令牌/密码类字段与常见内联字面量）。
   if (Array.isArray(rest.tools_used)) {
     rest.tools_used = rest.tools_used.map((t) => {
       if (!t || typeof t !== 'object') return t;
       const { input, ...meta } = t;
-      return input === undefined ? meta : { ...meta, input: sanitizeApprovalContext(input) };
+      const safeMeta = sanitizeApprovalContext(meta);
+      return input === undefined ? safeMeta : { ...safeMeta, input: sanitizeApprovalContext(input) };
     });
   }
   // 始终给出布尔值：调用方才能区分“思考被剥离”与“本来没有思考”。
@@ -271,6 +282,8 @@ export class Conversation {
       model: state.model ?? null,
     };
     this.lastConfigApplied = null;
+    /** 是否已回读并确认会话记录的权限档（null=尚未核对，true/false=结果）。 */
+    this.permissionVerified = null;
     /** 工作区登记结果（决定你的 DSH GUI 里能不能看到这个会话）。 */
     this.workspace = state.workspace ?? null;
     this.#hub = hub;
@@ -350,6 +363,8 @@ export class Conversation {
       title_hint: this.titleHint ?? null,
       cwd: this.cwd,
       permission: this.permission,
+      /** true=已回读会话记录且一致；false/null=缓存暂时没有记录（read-only 仍由审批层兜底）。 */
+      permission_verified: this.permissionVerified,
       on_approval: this.onApproval,
       alive: !!this.proc?.alive,
       busy: this.busy,
@@ -418,6 +433,8 @@ export class Conversation {
       // 新进程不记得会话级配置（思考深度/模型），resume 后必须重套
       this.lastConfigApplied = await applySessionConfig(proc, this.id, this.cfg);
       for (const f of this.lastConfigApplied.failed) this.#hub.log.info(`[conv ${this.id}] ${f}`);
+      // ★ 回读会话自己的权限记录，防止 profile defaultPreset 无声提权。
+      await this.verifyPermissionRecorded();
       // 锁到手了，这时才登记；从此别人能查到"锁在我们手上"
       writeMarker(this.id, { childPid: proc.pid, cwd: this.cwd });
       this.lockConflict = null; // 拿到锁了，之前的撞锁记录作废
@@ -465,6 +482,39 @@ export class Conversation {
     }
   }
 
+  /**
+   * 核对**会话自己记录**的权限档是否与请求一致。
+   *
+   * 为什么不能只信入参：DSH profile 里的 `permission.defaultPreset` 会在
+   * session/new 时覆盖 `DSH_PERMISSION_MODE`（test/permission.mjs 实测抓到过
+   * read-only 被静默提升）。投影缓存可能稍后才刷盘，所以短轮询；读不到时
+   * 不阻断（read-only 仍有审批层的硬拒绝兜底），但读到不一致就立刻失败。
+   */
+  async verifyPermissionRecorded({ attempts = 6, delayMs = 250 } = {}) {
+    for (let i = 0; i < attempts; i++) {
+      const meta = readConversationMeta(this.id);
+      const recorded = meta?.permissions?.preset;
+      if (recorded) {
+        if (!PERMISSION_TIERS.includes(recorded) || recorded !== this.permission) {
+          throw new Error(
+            `会话实际权限档为 ${JSON.stringify(recorded)}，与请求的 ${this.permission} 不一致。\n` +
+              '  这通常意味着 DSH profile 里写了 permission.defaultPreset，覆盖了启动时传入的权限档。\n' +
+              `  请检查 ${join(DSH_HOME, 'profiles', process.env.DSH_MCP_PROFILE ?? 'dsh-mcp', 'cordis.patch.yml')}，` +
+              '删掉 permission.defaultPreset 后重试。',
+          );
+        }
+        this.permissionVerified = true;
+        return recorded;
+      }
+      if (i < attempts - 1) await new Promise((r) => setTimeout(r, delayMs));
+    }
+    this.permissionVerified = false;
+    this.#hub.log.info(
+      `[conv ${this.id}] 投影缓存里暂时没有权限记录，跳过运行期核对（read-only 仍由审批层强制拒绝）`,
+    );
+    return null;
+  }
+
   /**
    * 抢占写锁。
    *
@@ -806,7 +856,9 @@ export class Conversation {
         //   之前只在"调用方没在原地等"时才写，于是插话那一轮没有哨兵 —— 调用方的
         //   等待逻辑（等文件出现）就永远空等，即使 run 早已 status=done（真实事故）。
         //   统一规则也消除了整类"有 run_id 却没有哨兵"的坑。
-        this.#hub.writeRunSentinel(this.id, runRecord);
+        const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
+        result.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
+        if (!sentinelFile) result.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
         return result;
       } catch (e) {
         this.#hub.log.info(`[conv ${this.id}] 回合收尾异常（已兜底）: ${e.message}`);
@@ -830,7 +882,9 @@ export class Conversation {
         runRecord.status = 'error';
         runRecord.error = fallback.error;
         runRecord.result = fallback;
-        this.#hub.writeRunSentinel(this.id, runRecord);
+        const sentinelFile = this.#hub.writeRunSentinel(this.id, runRecord);
+        fallback.sentinel_file = sentinelFile ?? this.#hub.runSentinelPath(this.id, runRecord.run_id);
+        if (!sentinelFile) fallback.sentinel_error = runRecord.sentinel_error ?? '哨兵文件写入失败';
         return fallback;
       }
     };
@@ -1051,8 +1105,17 @@ export class Conversation {
 
 /** 收集当前工作区的 git 变更摘要（非 git 目录返回 null）。 */
 export function gitStatus(cwd) {
+  if (process.env.DSH_MCP_GIT_STATUS === '0') return null;
   try {
-    const r = spawnSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8', timeout: 8000 });
+    // ★ 在不可信仓库里 `git status` 可能触发仓库配置的 fsmonitor/filter；这些
+    //   命令发生在 DSH 沙箱与审批层之外。禁用可选锁与 fsmonitor，并允许用
+    //   DSH_MCP_GIT_STATUS=0 完全关掉。
+    const r = spawnSync('git', ['-c', 'core.fsmonitor=false', 'status', '--porcelain', '--no-optional-locks'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 8000,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+    });
     if (r.status !== 0 || !r.stdout) return null;
     const lines = r.stdout.split('\n').filter(Boolean);
     if (!lines.length) return null;
@@ -1120,7 +1183,10 @@ export class Hub {
   constructor({ log } = {}) {
     this.conversations = new Map();
     this.log = log ?? NOOP_LOG;
-    this.approvalTimeoutMs = Number(process.env.DSH_MCP_APPROVAL_TIMEOUT_MS ?? 5 * 60 * 1000);
+    const rawApprovalTimeout = Number(process.env.DSH_MCP_APPROVAL_TIMEOUT_MS ?? 5 * 60 * 1000);
+    // 空串会变成 0 / NaN → setTimeout(0) 会把 ask 审批立刻取消；统一回落到 5 分钟。
+    this.approvalTimeoutMs =
+      Number.isFinite(rawApprovalTimeout) && rawApprovalTimeout > 0 ? rawApprovalTimeout : 5 * 60 * 1000;
     this.#reaper = null;
   }
 
@@ -1129,6 +1195,30 @@ export class Hub {
   #probeCache = null;
 
   load() {
+    // ★ 启动即确认三个关键目录可写。以前"写失败只记 silent 日志"会让服务
+    //   看起来正常，但注册表/哨兵/锁登记全部丢失，异步等待永远醒不过来。
+    assertWritableDir(dirname(STATE_FILE), '状态目录');
+    assertWritableDir(RUNS_DIR, '哨兵目录');
+    assertWritableDir(LOCKS_DIR, '锁登记目录');
+
+    // 旧版本的默认状态文件在包安装目录里；一次性迁移到新的用户可写目录。
+    // 只在没有显式设置 DSH_MCP_STATE 时做，避免覆盖用户指定的路径。
+    if (USING_DEFAULT_STATE && !existsSync(STATE_FILE) && existsSync(LEGACY_STATE_FILE)) {
+      try {
+        copyFileSync(LEGACY_STATE_FILE, STATE_FILE);
+        this.log.info(`[hub] 已迁移旧状态文件: ${LEGACY_STATE_FILE} → ${STATE_FILE}`);
+        // 侧车元数据（审批策略/思考深度/标题/轮数）也一并搬过来；
+        // 否则旧会话按 id 重建时会悄悄回落到默认值。
+        const legacyMeta = join(dirname(LEGACY_STATE_FILE), 'meta');
+        if (existsSync(legacyMeta) && !existsSync(META_DIR)) {
+          cpSync(legacyMeta, META_DIR, { recursive: true });
+          this.log.info(`[hub] 已迁移旧元数据侧车: ${legacyMeta} → ${META_DIR}`);
+        }
+      } catch (e) {
+        this.log.info(`[hub] 旧状态文件迁移失败（继续用新路径）: ${e.message}`);
+      }
+    }
+
     const stale = pruneStaleTombstones();
     if (stale) this.log.info(`[hub] 清理 ${stale} 个失效的 forget 墓碑`);
     if (!existsSync(STATE_FILE)) return;
@@ -1186,24 +1276,34 @@ export class Hub {
     return join(RUNS_DIR, conversationId, `${runId}.json`);
   }
 
-  /** 写完成哨兵（原子）。失败只记日志，绝不影响主流程。 */
+  /**
+   * 写完成哨兵（原子）。
+   * @returns {string|null} 成功返回文件路径；失败返回 null，并把原因记进 run.sentinel_error。
+   *
+   * 失败不阻断回合收尾，但**必须让调用方看得见**：以前只记 silent 日志，
+   * 调用方会拿着一个永远不会出现的路径一直等。
+   */
   writeRunSentinel(conversationId, run) {
+    const file = this.runSentinelPath(conversationId, run.run_id);
     try {
-      const file = this.runSentinelPath(conversationId, run.run_id);
       mkdirSync(dirname(file), { recursive: true });
       const payload = {
         conversation_id: conversationId,
         run_id: run.run_id,
         status: run.status ?? 'unknown',
         ended_at: run.ended_at ?? Date.now(),
-        error: run.error ?? run.result?.error ?? null,
+        error: sanitizeApprovalContext(run.error ?? run.result?.error ?? null, 'error'),
         result: sanitizeResultForSentinel(run.result ?? null),
       };
       const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
       writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
       renameSync(tmp, file);
+      return file;
     } catch (e) {
-      this.log.info(`[hub] 写完成哨兵失败: ${e.message}`);
+      const msg = `写完成哨兵失败（${file}）: ${e.message}`;
+      run.sentinel_error = msg;
+      this.log.info(`[hub] ${msg}`);
+      return null;
     }
   }
 
@@ -1287,12 +1387,15 @@ export class Hub {
         const recordedPreset = meta?.permissions?.preset;
         const recordedPermission = PERMISSION_TIERS.includes(recordedPreset) ? recordedPreset : null;
         // 安全优先：会话记录说 read-only 就绝不能被侧车“提升”为可写档。
+        // ★ 档位未知（没有投影缓存、也没有本服务侧车）时 **fail-closed 到 read-only**。
+        //   以前回落到 DEFAULT_PERMISSION（danger-full-access），等于把一个可能是
+        //   只读的外部会话悄悄提升为完全访问。宁可让用户显式新建会话，也不要无声提权。
         const permission =
           recordedPermission === 'read-only'
             ? 'read-only'
             : PERMISSION_TIERS.includes(persisted?.permission)
               ? persisted.permission
-              : (recordedPermission ?? DEFAULT_PERMISSION);
+              : (recordedPermission ?? 'read-only');
         const recordedApproval = meta?.permissions?.approval;
         let onApproval = APPROVAL_POLICIES.includes(persisted?.onApproval)
           ? persisted.onApproval
@@ -1452,6 +1555,8 @@ export class Hub {
             `  请检查 ${provider}/${model} 是否在 profile 中声明；不传这两个参数可使用 profile 默认模型。`,
         );
       }
+      // ★ 回读会话自己的权限记录；不一致会在这里失败并走 catch（停进程、删登记）。
+      await conv.verifyPermissionRecorded();
       // 登记工作区，否则这些会话在你的 DSH GUI 里看不到。
       // ★ 必须容错：registerWorkspace 会写 workspace.json（磁盘满/被占时会抛），
       //   而它在 this.conversations.set 之前 —— 抛出去就会**丢掉这个会话并泄漏进程**。
@@ -1619,10 +1724,17 @@ export class Hub {
    * 场景：默认"永不回收"下每个用过的会话会常驻一个 DSH 进程（实测约 300-480MB ✗）。
    * 一批活干完了就调它，内存立刻归零 ✓；下次派活按需 resume ✓。
    */
-  async releaseAll() {
+  async releaseAll({ force = false } = {}) {
     const released = [];
+    const skippedBusy = [];
     for (const c of this.conversations.values()) {
       if (!c.proc?.alive) continue;
+      // ★ 默认不打断正在跑的回合：all=true 是"腾内存"，不是"取消任务"。
+      //   确实要连跑着的也停掉时传 force=true。
+      if (c.busy && !force) {
+        skippedBusy.push(c.id);
+        continue;
+      }
       const proc = c.proc;
       c.proc = null;
       await proc.stop().catch(() => {});
@@ -1630,7 +1742,7 @@ export class Hub {
       released.push(c.id);
     }
     this.save();
-    return { released: released.length, conversations: released };
+    return { released: released.length, conversations: released, skipped_busy: skippedBusy };
   }
 
   async shutdown() {

package/src/tools.mjs

@@ -45,7 +45,7 @@ export const TOOL_DEFS = [
           type: 'string',
           enum: PERMISSION_TIERS,
           description:
-            `权限档。默认 ${DEFAULT_PERMISSION}。read-only 适合分析不信任样本（如恶意软件）；workspace-write 越界操作会冒泡为待决审批。` +
+            `权限档。默认 ${DEFAULT_PERMISSION}。read-only 适合分析不信任样本（如恶意软件）；workspace-write 由 DSH 沙箱限制可写范围，越界请求默认 auto-allow，想在调用方挂起审批请传 on_approval=ask。` +
             '**档位在创建时定下**：DSH 设计上"resume 的会话保留它自己记录的权限"，所以事后改这个参数不会改变已有会话，要换档需新建。' +
             '（本档位是**真实生效**的 —— 由启动时传入的 env 决定，并有 test/permission.mjs 对着会话自己的记录逐档核验。）',
         },
@@ -188,7 +188,7 @@ export const TOOL_DEFS = [
           enum: REASONING_MODES,
           description: `思考内容展示档位，默认 ${DEFAULT_REASONING}。`,
         },
-        timeout_ms: { type: 'number', description: '新回合的**等待**上限（毫秒），**默认 0 = 一直等**；queue 模式也用它限制等待上一轮结束。到期转后台，不取消回合。' },
+        timeout_ms: { type: 'number', description: '新回合的**等待**上限（毫秒），**默认 0 = 一直等**；queue 模式也用它限制等待上一轮结束。忙时等待超时会报错（本次插话未发送，会话不受损）；空闲时到期只转后台，不取消回合。' },
       },
       ['conversation_id', 'message'],
     ),
@@ -229,14 +229,19 @@ export const TOOL_DEFS = [
       '会话本体留在磁盘上，之后仍可 resume；**forget=true 会写墓碑**：从注册表移除，此后按 id 查询明确报“已被 forget”' +
       '（想恢复可按错误里的路径删除墓碑文件，默认在 `$DSH_HOME/.dsh-any-agent-forgotten/<id>.json`）。' +
       '★ 用完了想一次性腾内存就传 all=true（每个会话约 300-480MB；默认 `MAX_LIVE=8` 会回收最久未用者，' +
-      'all=true 可立即全部释放，之后随时 resume）。',
+      'all=true 会释放**空闲**会话，正在跑回合的默认跳过；确实要连跑着的也停掉请传 force=true）。' +
+      '对单个会话 release 会停掉其 DSH 进程；若它正在跑回合，该回合会被中断。',
     inputSchema: S(
       {
         conversation_id: CONV_ID,
         forget: { type: 'boolean', description: '同时从本服务的注册表里移除，默认 false。' },
         all: {
           type: 'boolean',
-          description: '忽略 conversation_id，释放**所有**活着的会话进程（腾内存用）。默认 false。',
+          description: '忽略 conversation_id，释放所有**空闲**会话进程（腾内存用）。正在跑回合的默认跳过。默认 false。',
+        },
+        force: {
+          type: 'boolean',
+          description: '仅配合 all=true：连正在跑回合的会话也停掉（会中断那些回合）。默认 false。',
         },
       },
       [],
@@ -587,12 +592,15 @@ export function createHandlers(hub, opts = {}) {
       // ★ all=true：一次性放掉所有活着的会话进程（腾内存）。
       //   无损：会话日志都在磁盘上，之后照样 resume。
       if (args.all === true) {
-        const r = await hub.releaseAll();
+        const r = await hub.releaseAll({ force: args.force === true });
         return {
-          structured: { released: r.released, conversations: r.conversations },
+          structured: { released: r.released, conversations: r.conversations, skipped_busy: r.skipped_busy },
           text:
-            `已释放 ${r.released} 个会话进程（写锁全部让出，内存立刻回收）。` +
-            `\n会话日志都在磁盘上，之后派活会自动 resume；其中一个都没在跑时 released=0。`,
+            `已释放 ${r.released} 个空闲会话进程（写锁让出，内存回收）。` +
+            (r.skipped_busy.length
+              ? `\n跳过 ${r.skipped_busy.length} 个正在跑回合的会话；要连它们一起停掉请传 force=true。`
+              : '') +
+            `\n会话日志都在磁盘上，之后派活会自动 resume；没有一个可释放时 released=0。`,
         };
       }
       const conv = hub.get(args.conversation_id);

package/src/workspace.mjs

@@ -17,7 +17,7 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, readdirSync, rmSync, realpathSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { tmpdir } from 'node:os';
 import { zstdDecompressSync } from 'node:zlib';
 import { DSH_HOME, REGISTER_WORKSPACE } from './config.mjs';
@@ -42,11 +42,46 @@ export function canonicalPath(p) {
   }
 }
 
-/** 路径是否位于系统临时目录下（这类"工作区"不该出现在 GUI 里）。 */
+/** `child` 是否真的在 `parent` 里面（按路径分段，不能用字符串前缀）。 */
+function isInside(parent, child) {
+  try {
+    const rel = relative(parent, child);
+    if (!rel) return true;
+    return rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 路径是否位于系统临时目录下（这类"工作区"不该出现在 GUI 里）。
+ *
+ * ★ 必须按路径分段判断，不能用 `startsWith(tmpdir())`：那样
+ *   `/tmpfoo`、`%LOCALAPPDATA%\Temporary\proj` 都会被当成临时目录，
+ *   而清理逻辑会据此**递归删除真实会话目录**（真实数据丢失级 bug）。
+ */
 export function isTempPath(p) {
   try {
-    const t = normPath(tmpdir());
-    return normPath(p).startsWith(t);
+    return Boolean(p) && isInside(tmpdir(), p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 是否是本仓库测试自己造的临时工作区。
+ *
+ * 只认系统临时目录下、第一段目录名以 `dsh-any-agent-` 开头的路径
+ * （测试统一用 `mkdtempSync(join(tmpdir(), 'dsh-any-agent-...'))`）。
+ * 这不是"所有临时目录"——用户完全可能把真实项目放在 %TEMP% 的同级目录里。
+ */
+export function isTestTempPath(p) {
+  try {
+    if (!p || !isTempPath(p)) return false;
+    const rel = relative(tmpdir(), p);
+    if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) return false;
+    const first = rel.split(/[\\/]/).filter(Boolean)[0] ?? '';
+    return /^dsh-any-agent-/.test(first);
   } catch {
     return false;
   }
@@ -87,16 +122,25 @@ function emptyDoc() {
   };
 }
 
+/**
+ * 读取工作区注册表。
+ *
+ * ★ 解析失败必须 **fail-closed**：以前会静默回落到空结构，下一次 register/prune
+ *   就会把 GUI 的整个工作区列表覆盖掉（不可恢复）。现在抛错，并且绝不写盘；
+ *   调用方（register/backfill/prune）各自把错误返回给上层。
+ */
 function readDoc() {
-  let doc = emptyDoc();
-  if (existsSync(WORKSPACE_FILE)) {
-    try {
-      const parsed = JSON.parse(readFileSync(WORKSPACE_FILE, 'utf8'));
-      if (parsed && typeof parsed === 'object') doc = parsed;
-    } catch {
-      /* 坏文件就用空结构重建，避免把 GUI 的注册表彻底写坏 */
-    }
+  if (!existsSync(WORKSPACE_FILE)) return emptyDoc();
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(WORKSPACE_FILE, 'utf8'));
+  } catch (e) {
+    throw new Error(`workspace.json 无法解析，已保持原样不写入: ${WORKSPACE_FILE}（${e.message}）`);
   }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`workspace.json 结构异常（不是对象），已保持原样不写入: ${WORKSPACE_FILE}`);
+  }
+  const doc = parsed;
   doc.global ??= emptyDoc().global;
   doc.global.workspaceIds ??= [];
   doc.global.archivedSessionIds ??= [];
@@ -108,9 +152,17 @@ function readDoc() {
 
 function writeDoc(doc) {
   mkdirSync(dirname(WORKSPACE_FILE), { recursive: true });
-  const tmp = `${WORKSPACE_FILE}.dshmcp.tmp`;
-  writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8');
-  renameSync(tmp, WORKSPACE_FILE);
+  // 临时文件名必须唯一：固定 `.dshmcp.tmp` 会让两个实例/CLI 并发写互相覆盖。
+  const tmp = `${WORKSPACE_FILE}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8');
+    renameSync(tmp, WORKSPACE_FILE);
+  } catch (e) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    throw e;
+  }
 }
 
 /** 在已读入的 doc 里找到（或新建）某路径对应的工作区条目。 */
@@ -172,10 +224,17 @@ function readHeader(file) {
   }
 }
 
-/** 扫描磁盘上所有会话，按 header.cwd 归组。数据源是会话头，不是目录名（目录名有损）。 */
+/**
+ * 扫描磁盘上所有会话，按 header.cwd 归组。数据源是会话头，不是目录名（目录名有损）。
+ *
+ * 会话根目录**不可读时抛错**，而不是返回空 Map —— 否则 backfill 的
+ * `pruneMissing` 会以为"所有会话都消失了"，把工作区注册表里的 sessionIds 清空。
+ */
 export function scanSessions() {
   const byCwd = new Map();
-  if (!existsSync(SESSIONS_ROOT)) return byCwd;
+  if (!existsSync(SESSIONS_ROOT)) {
+    throw new Error(`会话目录不存在或不可读: ${SESSIONS_ROOT}`);
+  }
   for (const bucket of readdirSync(SESSIONS_ROOT)) {
     const bucketPath = join(SESSIONS_ROOT, bucket);
     let dirs;
@@ -210,7 +269,13 @@ export function scanSessions() {
 export function findSessionHeader(sessionId) {
   if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]{4,80}$/.test(sessionId)) return null;
   if (!existsSync(SESSIONS_ROOT)) return null;
-  for (const bucket of readdirSync(SESSIONS_ROOT)) {
+  let buckets;
+  try {
+    buckets = readdirSync(SESSIONS_ROOT);
+  } catch {
+    return null;
+  }
+  for (const bucket of buckets) {
     const f = join(SESSIONS_ROOT, bucket, sessionId, 'session.v4.jsonl.zstd');
     if (!existsSync(f)) continue;
     const header = readHeader(f);
@@ -224,9 +289,6 @@ export function findSessionHeader(sessionId) {
  * 用于修复"本功能上线前创建的会话在 GUI 里看不到"。
  */
 export function backfillWorkspaces({ includeTemp = false, dryRun = false, pruneMissing = true } = {}) {
-  const byCwd = scanSessions();
-  const doc = readDoc();
-  const nowIso = new Date().toISOString();
   const stats = {
     workspaces_created: 0,
     workspaces_existing: 0,
@@ -236,7 +298,19 @@ export function backfillWorkspaces({ includeTemp = false, dryRun = false, pruneM
     temp_skipped_workspaces: 0,
     /** 磁盘上已不存在、被从注册表摘掉的 sessionId 数量。 */
     sessions_pruned: 0,
+    /** 读取失败时的说明；非空表示**没有写盘**。 */
+    error: null,
   };
+  let byCwd;
+  let doc;
+  try {
+    byCwd = scanSessions();
+    doc = readDoc();
+  } catch (e) {
+    // 看不到会话存储 / 注册表坏了时绝不做对账：那会把所有 sessionIds 清空。
+    return { ...stats, error: e.message };
+  }
+  const nowIso = new Date().toISOString();
 
   /** 磁盘上真实存在的会话 id 全集。 */
   const live = new Set();
@@ -286,12 +360,14 @@ export function backfillWorkspaces({ includeTemp = false, dryRun = false, pruneM
  *   3) ids 里显式指定的
  *
  * @param {object} opts
- * @param {boolean} [opts.tempOnly] 只删临时目录下的。自动清理（测试套件收尾）用这条，
- *   绝不动桌面或真实项目里的任何会话。
- * @param {boolean} [opts.idsOnly] **只删 ids 里点名的**，忽略上面两条规则。
+ * @param {boolean} [opts.testOnly] 只删**本仓库测试造的**临时目录（`tmpdir()/dsh-any-agent-*`）
+ *   与桌面 `dsh-any-agent-test-*`。自动清理（测试套件收尾）必须用这条。
+ * @param {boolean} [opts.tempOnly] 删除**所有** cwd 在系统临时目录下的会话。
+ *   只给显式人工命令用；不要放进自动清理 —— 用户完全可能把真实项目放在临时目录。
+ * @param {boolean} [opts.idsOnly] **只删 ids 里点名的**，忽略上面三条规则。
  *   要精确删某几个会话时用这条（否则一条临时目录规则会把别的也一起带走 —— 真实踩过）。
  */
-export function purgeTestSessions({ dryRun = false, ids = [], tempOnly = false, idsOnly = false } = {}) {
+export function purgeTestSessions({ dryRun = false, ids = [], testOnly = false, tempOnly = false, idsOnly = false } = {}) {
   const explicit = new Set(ids);
   const victims = [];
   if (existsSync(SESSIONS_ROOT)) {
@@ -304,12 +380,15 @@ export function purgeTestSessions({ dryRun = false, ids = [], tempOnly = false,
         continue;
       }
       for (const d of dirs) {
-        if (!d.isDirectory()) continue;
+        // 符号链接一律不碰：rmSync 对链接的行为依赖平台，且链接目标可能不在会话目录内。
+        if (!d.isDirectory() || d.isSymbolicLink()) continue;
         const dir = join(bucketPath, d.name);
+        // 兜底：只允许删 SESSIONS_ROOT 下面的目录（结构上已经如此，防未来改动）。
+        if (!isInside(SESSIONS_ROOT, dir)) continue;
         const header = readHeader(join(dir, 'session.v4.jsonl.zstd'));
         if (!header?.id) continue;
         const cwd = header.cwd ?? '';
-        const isTemp = isTempPath(cwd);
+        const isTemp = testOnly ? isTestTempPath(cwd) : isTempPath(cwd);
         const isTestDesktop = !tempOnly && /[\\/]Desktop[\\/]dsh-any-agent-test-[AB]([\\/]|$)/i.test(cwd);
         const isExplicit = explicit.has(header.id);
         // idsOnly：只认点名，别的规则全部作废
@@ -318,7 +397,7 @@ export function purgeTestSessions({ dryRun = false, ids = [], tempOnly = false,
           id: header.id,
           dir,
           cwd,
-          reason: isExplicit ? '显式指定' : isTemp ? '临时目录' : '验收测试目录',
+          reason: isExplicit ? '显式指定' : isTestDesktop ? '验收测试目录' : testOnly ? '测试临时目录' : '临时目录',
           origin: header.origin ?? null,
         });
       }
@@ -339,12 +418,14 @@ export function purgeTestSessions({ dryRun = false, ids = [], tempOnly = false,
       }
     }
     // 清掉因删空而残留的空分桶目录（每个工作区一个桶，空桶会一直堆着）
-    for (const bucket of readdirSync(SESSIONS_ROOT)) {
-      const p = join(SESSIONS_ROOT, bucket);
-      try {
-        if (readdirSync(p).length === 0) rmSync(p, { recursive: true, force: true });
-      } catch {
-        /* 桶被占用或权限问题就跳过 */
+    if (existsSync(SESSIONS_ROOT)) {
+      for (const bucket of readdirSync(SESSIONS_ROOT)) {
+        const p = join(SESSIONS_ROOT, bucket);
+        try {
+          if (readdirSync(p).length === 0) rmSync(p, { recursive: true, force: true });
+        } catch {
+          /* 桶被占用或权限问题就跳过 */
+        }
       }
     }
     // 删完之后把注册表里对应的 id 也摘掉
@@ -355,7 +436,12 @@ export function purgeTestSessions({ dryRun = false, ids = [], tempOnly = false,
 
 /** 清掉"没有会话且路径已不存在"的空工作区条目。 */
 export function pruneEmptyWorkspaces({ dryRun = false } = {}) {
-  const doc = readDoc();
+  let doc;
+  try {
+    doc = readDoc();
+  } catch (e) {
+    return { removed: [], error: e.message };
+  }
   const removed = [];
   for (const id of Object.keys(doc.tables.workspaces)) {
     const ws = doc.tables.workspaces[id];
@@ -379,13 +465,20 @@ export function pruneEmptyWorkspaces({ dryRun = false } = {}) {
  * 启发式，实测不一定兜住）。这里按**路径模式**确定性清理，绝不碰真实项目目录。
  */
 export function pruneTestWorkspaces({ dryRun = false } = {}) {
-  const doc = readDoc();
+  let doc;
+  try {
+    doc = readDoc();
+  } catch (e) {
+    return { removed: [], error: e.message };
+  }
   const removed = [];
   for (const id of Object.keys(doc.tables.workspaces)) {
     const ws = doc.tables.workspaces[id];
     const p = ws?.path ?? '';
     if (!p) continue;
-    if (!isTempPath(p) && !isTestDesktopPath(p)) continue;
+    // ★ 只删测试自己造的临时目录（dsh-any-agent-*）与桌面测试目录。
+    //   以前用 isTempPath(p) 会把用户在 %TEMP% 里的真实项目登记也删掉。
+    if (!isTestTempPath(p) && !isTestDesktopPath(p)) continue;
     removed.push({ id, path: p, sessions: ws?.sessionIds?.length ?? 0 });
     delete doc.tables.workspaces[id];
     doc.global.workspaceIds = (doc.global.workspaceIds ?? []).filter((x) => x !== id);
@@ -397,7 +490,12 @@ export function pruneTestWorkspaces({ dryRun = false } = {}) {
 
 /** 清理：把系统临时目录下的工作区条目从注册表移除（**不动磁盘上的会话**）。 */
 export function pruneTempWorkspaces({ dryRun = false } = {}) {
-  const doc = readDoc();
+  let doc;
+  try {
+    doc = readDoc();
+  } catch (e) {
+    return { removed: [], error: e.message };
+  }
   const removed = [];
   for (const id of Object.keys(doc.tables.workspaces)) {
     const ws = doc.tables.workspaces[id];
@@ -411,7 +509,7 @@ export function pruneTempWorkspaces({ dryRun = false } = {}) {
   return { removed };
 }
 
-/** 列出当前注册表里的工作区。 */
+/** 列出当前注册表里的工作区。解析失败时抛错（由 CLI 显示可操作的错误）。 */
 export function listWorkspaces() {
   const doc = readDoc();
   return Object.entries(doc.tables.workspaces).map(([id, w]) => ({