dsh-any-agent 0.3.1 → 0.3.3

package/src/hub.mjs

@@ -23,7 +23,8 @@ import {
   rmSync,
   readdirSync,
 } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import {
   APPROVAL_POLICIES,
@@ -40,6 +41,7 @@ import {
   SENTINEL_INCLUDE_REASONING,
   SENTINEL_TTL_MS,
   STATE_FILE,
+  DSH_HOME,
   defaultApprovalPolicy,
 } from './config.mjs';
 import { AcpProcess } from './acp.mjs';
@@ -59,6 +61,92 @@ import {
 const now = () => Date.now();
 const NOOP_LOG = { info: () => {}, debug: () => {}, dshStderr: () => {} };
 
+/**
+ * 会话元数据侧车（`.state/meta/<id>.json`）。
+ *
+ * 为什么需要：`forget=true` 只从注册表移除；之后按 id 查询时，`Hub.get()` 会从
+ * DSH 会话存储重建会话（这是多实例恢复的刻意设计）。但 DSH 的会话记录里**没有**
+ * 本服务选择的 `onApproval` / `reasoning_effort` / `title_hint` / 轮数，
+ * 重建就会悄悄回落到默认值（实测 auto-allow→ask、low→max）。这个侧车保存
+ * **仅元数据**（不含任何对话/思考正文），让重建后仍与原会话一致。
+ */
+const META_DIR = join(dirname(STATE_FILE), 'meta');
+const metaFilePath = (id) => join(META_DIR, `${id}.json`);
+
+function writeConversationMeta(conv) {
+  try {
+    mkdirSync(META_DIR, { recursive: true });
+    const file = metaFilePath(conv.id);
+    const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(conv.toMeta(), null, 2), 'utf8');
+    renameSync(tmp, file);
+  } catch {
+    /* 元数据侧车只是辅助信息，写失败不影响主流程 */
+  }
+}
+
+function readConversationMetaFile(id) {
+  try {
+    return JSON.parse(readFileSync(metaFilePath(id), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * forget 墓碑：`release(forget=true)` 之后，按 id 查询必须**明确失败**，
+ * 而不是从 DSH 会话存储里悄悄复活。墓碑只含 id 与时间，不含任何内容；
+ * 删除 `.state/forgotten/<id>.json` 即可恢复按 id 找回（手动、可审计）。
+ */
+// 墓碑放在 DSH home 下而不是注册表旁边：不同实例即使注册表路径不同，
+// 也应该对同一个会话的 forget 达成一致（forget 是会话级终态，不是注册表级）。
+const FORGOTTEN_DIR = process.env.DSH_MCP_FORGOTTEN_DIR ?? join(DSH_HOME, '.dsh-any-agent-forgotten');
+const forgottenPath = (id) => join(FORGOTTEN_DIR, `${id}.json`);
+
+function writeTombstone(id) {
+  try {
+    mkdirSync(FORGOTTEN_DIR, { recursive: true });
+    const file = forgottenPath(id);
+    const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify({ id, forgottenAt: Date.now() }, null, 2), 'utf8');
+    renameSync(tmp, file);
+  } catch {
+    /* 墓碑写失败时 forget 仍从注册表移除；下次 get 可能仍会复活，但不影响主流程 */
+  }
+}
+
+function isForgotten(id) {
+  try {
+    return existsSync(forgottenPath(id));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 启动时清掉“会话文件已经不存在”的墓碑：它们不再阻止任何 resurrection，
+ * 留着只会让测试/临时会话在 `$DSH_HOME/.dsh-any-agent-forgotten` 里堆积。
+ * 会话文件还在的墓碑必须保留 —— 那正是 forget 的效力所在。
+ */
+function pruneStaleTombstones() {
+  let removed = 0;
+  try {
+    if (!existsSync(FORGOTTEN_DIR)) return 0;
+    for (const f of readdirSync(FORGOTTEN_DIR)) {
+      if (!f.endsWith('.json')) continue;
+      const id = f.slice(0, -5);
+      if (findSessionHeader(id)) continue;
+      try {
+        rmSync(join(FORGOTTEN_DIR, f), { force: true });
+        removed++;
+      } catch {}
+    }
+  } catch {
+    /* 清理失败不影响启动 */
+  }
+  return removed;
+}
+
 /** 运行期输出环形缓冲的条目上限（仅内存，超出丢最旧的）。 */
 const MAX_OUT_ENTRIES = 500;
 /** 记录用户发话时的截断长度（避免一条把缓冲撑爆）。 */
@@ -148,11 +236,21 @@ async function applySessionConfig(proc, sessionId, cfg) {
  * 默认剥离以维持"思考不落盘"的保证，并留下 thinking_omitted 标记，
  * 免得调用方以为字段是意外丢失的。
  */
-function sanitizeResultForSentinel(result) {
+export function sanitizeResultForSentinel(result) {
   if (!result || typeof result !== 'object') return result ?? null;
   if (SENTINEL_INCLUDE_REASONING) return result;
   const { thinking, ...rest } = result;
-  return thinking ? { ...rest, thinking_omitted: true } : rest;
+  // 工具输入里会有完整命令、路径，甚至写入的文件内容。哨兵会保留 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) };
+    });
+  }
+  // 始终给出布尔值：调用方才能区分“思考被剥离”与“本来没有思考”。
+  return { ...rest, thinking_omitted: Boolean(thinking) };
 }
 
 export class Conversation {
@@ -193,6 +291,8 @@ export class Conversation {
      */
     this.out = [];
     this.outSeq = 0;
+    /** 输出缓冲的**修订号**：每次追加（含合并进已有条目）都 +1，供游标式增量读使用。 */
+    this.outRev = 0;
     this.turnOutChars = 0;
     this.currentTurn = 0;
     this.turnStartedAt = 0;
@@ -228,6 +328,11 @@ export class Conversation {
     };
   }
 
+  /** 侧车元数据：与注册表同字段，但独立落盘，forget 之后仍可恢复。 */
+  toMeta() {
+    return { version: 1, ...this.toState() };
+  }
+
   /** 合规的公开快照（含磁盘上的元信息）。 */
   snapshot() {
     const meta = readConversationMeta(this.id);
@@ -236,6 +341,13 @@ export class Conversation {
       conversation_id: this.id,
       /** 对话名来自 DSH 的 session/title 事件（自动生成）；未生成时用建会话提示兜底。 */
       title: nativeTitle ?? this.titleHint ?? null,
+      /**
+       * DSH 自动生成的标题是**首条消息的截断前缀**（实测 13–15 个字符，
+       * 例如「这是一次连通性冒烟测试，请」），信息量很低。
+       * 所以调用方给了 title_hint 时，把两者分开返回，由调用方自己选：
+       * 想按 DSH 原生标题认会话就看 title，想要可读标签就看 title_hint。
+       */
+      title_hint: this.titleHint ?? null,
       cwd: this.cwd,
       permission: this.permission,
       on_approval: this.onApproval,
@@ -487,11 +599,33 @@ export class Conversation {
 
   async onPermissionRequest(params) {
     const options = params?.options ?? [];
-    const toolCall = params?.toolCall ?? {};
+    const rawToolCall = params?.toolCall ?? {};
+    // 真实 DSH 的 request_permission 只带 toolCallId，不带 rawInput；
+    // 同一 toolCallId 的参数通常已经在 tool_call 更新里记录过，按 id 关联回来，
+    // 否则审批详情里没有命令/路径，调用方无法裁决。
+    const known = this.collector?.tools?.get(rawToolCall.toolCallId) ?? null;
+    const toolCall = known
+      ? {
+          ...rawToolCall,
+          name: rawToolCall.name ?? known.name,
+          title: rawToolCall.title ?? known.title,
+          kind: rawToolCall.kind ?? known.kind,
+          rawInput: rawToolCall.rawInput ?? rawToolCall.input ?? known.input,
+          locations: rawToolCall.locations ?? known.locations,
+        }
+      : rawToolCall;
     const desc = sanitizeApprovalContext(String(toolCall.title ?? toolCall.name ?? toolCall.toolCallId ?? '未知操作'));
     const allowId = pickOption(options, 'allow');
     const rejectId = pickOption(options, 'reject');
 
+    // ★ read-only 是硬边界：即使会话被旧版本/显式参数配成 auto-allow，
+    //   这里也绝不放行任何审批 —— DSH 会借审批把 sandbox 提权到可写。
+    if (this.permission === 'read-only') {
+      this.#hub.log.info(`[conv ${this.id}] read-only 强制拒绝审批: ${desc}`);
+      return rejectId
+        ? { outcome: { outcome: 'selected', optionId: rejectId } }
+        : { outcome: { outcome: 'cancelled' } };
+    }
     if (this.onApproval === 'auto-allow') {
       this.#hub.log.info(`[conv ${this.id}] 审批放行: ${desc}`);
       return allowId
@@ -624,6 +758,14 @@ export class Conversation {
         this.busy = false;
         this.collector = null;
         this.currentTool = null;
+        // 回合结束后，任何仍挂着的审批都已失效：统一取消并清空，避免状态里
+        // 留下一个 dsh_approval_decide 只会回"没有待决审批"的幽灵。
+        for (const [, p] of this.pendingApprovals) {
+          try {
+            p.resolve({ outcome: { outcome: 'cancelled' } });
+          } catch {}
+        }
+        this.pendingApprovals.clear();
         this.pushOut('turn', `第 ${this.currentTurn} 轮结束（${stopReason ?? 'unknown'}）`, {
           phase: 'end',
           stop_reason: stopReason,
@@ -756,17 +898,24 @@ export class Conversation {
     if (last && last.kind === kind && last.turn === this.currentTurn && text) {
       last.text += text;
       last.at = now();
+      // ★ 合并进已有条目也必须推进修订号。否则游标已经读过这条的调用方
+      //   会永远看不到后续追加的正文（旧实现用 seq 当游标，seq 不变 = 漏读）。
+      last.rev = ++this.outRev;
     } else {
-      this.out.push({ seq: ++this.outSeq, kind, turn: this.currentTurn, text: text ?? '', at: now(), ...extra });
+      this.out.push({ seq: ++this.outSeq, rev: ++this.outRev, kind, turn: this.currentTurn, text: text ?? '', at: now(), ...extra });
       if (this.out.length > MAX_OUT_ENTRIES) this.out.shift();
     }
     if (kind === 'text') this.turnOutChars += text?.length ?? 0;
   }
 
-  /** 读输出：游标式增量。返回 seq > cursor 的条目 + 新游标。 */
+  /** 读输出：**按修订号**的游标式增量。条目被追加时会再次返回（按 seq 替换全文）。 */
   readOut({ cursor = 0, includeReasoning = false, limit = 200 } = {}) {
-    const entries = this.out.filter((e) => e.seq > cursor).slice(0, limit);
-    const next = entries.length ? entries[entries.length - 1].seq : cursor;
+    const cur = Number.isFinite(cursor) ? cursor : 0;
+    // limit 必须清洗：负数会被 slice 解释成“从头到尾少一条”，0 会让调用方原地空转。
+    const n = Number.isFinite(limit) ? Math.max(1, Math.min(Math.floor(limit), MAX_OUT_ENTRIES)) : 200;
+    const revOf = (e) => (typeof e.rev === 'number' ? e.rev : e.seq);
+    const entries = this.out.filter((e) => revOf(e) > cur).slice(0, n);
+    const next = entries.length ? revOf(entries[entries.length - 1]) : cur;
     const res = {
       conversation_id: this.id,
       state: this.state(),
@@ -774,9 +923,9 @@ export class Conversation {
       current_tool: this.currentTool,
       entries,
       cursor: next,
-      has_more: this.out.some((e) => e.seq > next),
+      has_more: this.out.some((e) => revOf(e) > next),
       /** 缓冲被环形覆盖时会为 true，表示你错过了中间一段。 */
-      gap: entries.length > 0 && this.out.length > 0 && this.out[0].seq > cursor + 1,
+      gap: entries.length > 0 && this.out.length > 0 && revOf(this.out[0]) > cur + 1,
     };
     // 思考内容只在显式要求时、且只针对"当前正在跑的回合"返回；不保留、不进缓冲
     if (includeReasoning && this.collector?.reasoning) {
@@ -816,24 +965,27 @@ export class Conversation {
     return this.runs.length ? this.runs[this.runs.length - 1] : null;
   }
 
-  /** 等到当前回合结束（不忙则立即返回 true；超时返回 false）。 */
+  /** 等到当前回合结束（不忙则立即返回 true；`timeoutMs <= 0` 一直等；超时返回 false）。 */
   async waitIdle(timeoutMs = 30 * 60 * 1000) {
     if (!this.busy) return true;
     return await new Promise((resolve) => {
       let settled = false;
+      let timer = null;
       const done = () => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (timer) clearTimeout(timer);
         resolve(true);
       };
-      const timer = setTimeout(() => {
-        if (settled) return;
-        settled = true;
-        const i = this.idleWaiters.indexOf(done);
-        if (i >= 0) this.idleWaiters.splice(i, 1);
-        resolve(false);
-      }, timeoutMs);
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          const i = this.idleWaiters.indexOf(done);
+          if (i >= 0) this.idleWaiters.splice(i, 1);
+          resolve(false);
+        }, timeoutMs);
+      }
       this.idleWaiters.push(done);
     });
   }
@@ -860,7 +1012,8 @@ export class Conversation {
     if (mode === 'interject') {
       this.proc?.notify('session/cancel', { sessionId: this.id });
     }
-    const idle = await this.waitIdle();
+    // 排队等待的时长跟随调用方的 timeout_ms（0 = 一直等），不再固定 30 分钟。
+    const idle = await this.waitIdle(timeoutMs);
     const waited = now() - t0;
     if (!idle) throw new Error('等待当前回合结束超时，插话未发送');
     const r = await this.prompt(message, { reasoning, timeoutMs });
@@ -877,10 +1030,21 @@ export class Conversation {
       } catch {}
       await proc.stop();
     }
+    // 回合已经结束/进程正在关闭，任何仍挂着的审批都不再可裁决。
+    for (const [, p] of this.pendingApprovals) {
+      try {
+        p.resolve({ outcome: { outcome: 'cancelled' } });
+      } catch {}
+    }
+    this.pendingApprovals.clear();
     // 进程没了 → 写锁也释放了，登记必须跟着删（否则会把"孤儿持有者"误报给抢占逻辑）
     removeMarker(this.id);
-    if (forget) this.#hub.remove(this.id);
-    else this.#hub.save();
+    if (forget) {
+      // 先写墓碑再从注册表移除：之后按 id 查询会明确报"已 forget"，
+      // 而不是从 DSH 会话存储把它重建回来（否则 forget 形同虚设）。
+      writeTombstone(this.id);
+      this.#hub.remove(this.id);
+    } else this.#hub.save();
     return { closed: true, forgotten: forget };
   }
 }
@@ -915,6 +1079,43 @@ export function formatReasoning(c, mode) {
 
 // ── 注册表 ────────────────────────────────────────────────────────
 
+/**
+ * 工作区能不能用在家目录本身？
+ *
+ * DSH 自己的 ACL 沙箱要求临时目录在工作区**之外**。Windows 上 %TEMP% 是
+ * C:/Users/<name>/AppData/Local/Temp，正好在用户家目录里面，所以把家目录
+ * 当作工作区时，沙箱初始化会失败：
+ *   Windows ACL: temp root must be outside the workspace
+ * 症状出现在第一次起 shell 的时候，看起来像这个服务坏了，其实只是 cwd
+ * 选得太大。read-only 档不写盘、也不起 ACL 沙箱，所以不受影响。
+ *
+ * @returns {string|null} null 表示没问题，否则返回一段可直接抛出的说明。
+ */
+export function homeWorkspaceProblem(cwd, permission) {
+  if (permission === 'read-only') return null;
+  const home = homedir();
+  if (!home) return null;
+  const norm = (p) => {
+    const r = resolve(p);
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+  };
+  if (norm(cwd) !== norm(home)) return null;
+
+  const temp = tmpdir();
+  const tempInside = norm(temp) === norm(home) || norm(temp).startsWith(norm(home) + sep);
+  const lines = ['cwd 不能是用户家目录本身: ' + cwd];
+  if (tempInside) lines.push('  临时目录 ' + temp + ' 就在它里面，');
+  lines.push(
+    '  DSH 的 ACL 沙箱要求临时目录在工作区之外，否则第一次起 shell 就会报:',
+    '    Windows ACL: temp root must be outside the workspace',
+    '',
+    '  换个具体项目目录最省事，或者改权限档：',
+    '    permission=read-only           不写盘，不需要该沙箱',
+    '    permission=danger-full-access  不受该沙箱约束',
+  );
+  return lines.join('\n');
+}
+
 export class Hub {
   constructor({ log } = {}) {
     this.conversations = new Map();
@@ -928,11 +1129,14 @@ export class Hub {
   #probeCache = null;
 
   load() {
+    const stale = pruneStaleTombstones();
+    if (stale) this.log.info(`[hub] 清理 ${stale} 个失效的 forget 墓碑`);
     if (!existsSync(STATE_FILE)) return;
     try {
       const doc = JSON.parse(readFileSync(STATE_FILE, 'utf8'));
       for (const s of doc.conversations ?? []) {
         if (!s?.id || !s?.cwd) continue;
+        if (isForgotten(s.id)) continue;
         this.conversations.set(s.id, new Conversation(s, this));
       }
       this.log.info(`[hub] 载入 ${this.conversations.size} 个会话`);
@@ -955,6 +1159,9 @@ export class Hub {
       const tmp = `${STATE_FILE}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
       writeFileSync(tmp, JSON.stringify(doc, null, 2), 'utf8');
       renameSync(tmp, STATE_FILE);
+      // 侧车元数据独立于注册表：forget 移除注册表条目后仍然保留，
+      // 让按 id 重建的会话不会丢掉审批策略/思考深度/标题/轮数。
+      for (const c of this.conversations.values()) writeConversationMeta(c);
     } catch (e) {
       this.log.info(`[hub] 状态保存失败: ${e.message}`);
     }
@@ -1052,6 +1259,14 @@ export class Hub {
   }
 
   get(id) {
+    // ★ forget 是终态：墓碑存在时，任何按 id 的查询都必须明确失败，
+    //   否则 DSH 会话存储里的记录会让它悄悄复活（"forget 不持久"）。
+    if (isForgotten(id)) {
+      throw new Error(
+        `会话已被 forget（永久移除）: ${id}\n` +
+          `  它不会再被按 id 自动恢复。确实要恢复的话，删除墓碑文件 ${forgottenPath(id)} 后重试。`,
+      );
+    }
     let c = this.conversations.get(id);
     if (!c) {
       // 多实例常见情形：这个会话是**另一个 dsh-any-agent 实例**刚建的，我们内存里的注册表还没有。
@@ -1068,18 +1283,39 @@ export class Hub {
         //   一个当初用 read-only 建的会话，若注册表丢了、被我们以默认档接管，
         //   resume 时 DSH_PERMISSION_MODE 会把档位写进会话 —— 等于**悄悄提权**。
         const meta = readConversationMeta(id);
+        const persisted = readConversationMetaFile(id);
         const recordedPreset = meta?.permissions?.preset;
-        const permission = PERMISSION_TIERS.includes(recordedPreset) ? recordedPreset : DEFAULT_PERMISSION;
+        const recordedPermission = PERMISSION_TIERS.includes(recordedPreset) ? recordedPreset : null;
+        // 安全优先：会话记录说 read-only 就绝不能被侧车“提升”为可写档。
+        const permission =
+          recordedPermission === 'read-only'
+            ? 'read-only'
+            : PERMISSION_TIERS.includes(persisted?.permission)
+              ? persisted.permission
+              : (recordedPermission ?? DEFAULT_PERMISSION);
         const recordedApproval = meta?.permissions?.approval;
-        const onApproval = APPROVAL_POLICIES.includes(recordedApproval)
-          ? recordedApproval
-          : defaultApprovalPolicy(permission);
+        let onApproval = APPROVAL_POLICIES.includes(persisted?.onApproval)
+          ? persisted.onApproval
+          : APPROVAL_POLICIES.includes(recordedApproval)
+            ? recordedApproval
+            : defaultApprovalPolicy(permission);
+        if (permission === 'read-only' && onApproval !== 'auto-deny') onApproval = 'auto-deny';
         c = new Conversation(
           {
             id,
-            cwd: header.cwd,
+            cwd: persisted?.cwd ?? header.cwd,
             permission,
             onApproval,
+            titleHint: persisted?.titleHint ?? null,
+            reasoningEffort: REASONING_EFFORTS.includes(persisted?.reasoningEffort)
+              ? persisted.reasoningEffort
+              : DEFAULT_REASONING_EFFORT,
+            provider: persisted?.provider ?? null,
+            model: persisted?.model ?? null,
+            createdAt: persisted?.createdAt,
+            lastUsedAt: persisted?.lastUsedAt,
+            turnCount: persisted?.turnCount,
+            workspace: persisted?.workspace ?? null,
           },
           this,
         );
@@ -1108,6 +1344,7 @@ export class Hub {
       const doc = JSON.parse(readFileSync(STATE_FILE, 'utf8'));
       for (const s of doc.conversations ?? []) {
         if (!s?.id || !s?.cwd) continue;
+        if (isForgotten(s.id)) continue;
         if (this.conversations.has(s.id)) continue;
         this.conversations.set(s.id, new Conversation(s, this));
         added++;
@@ -1121,15 +1358,26 @@ export class Hub {
 
   remove(id) {
     this.conversations.delete(id);
+    // 注意：**不删侧车元数据**。forget 的语义是“从注册表移除”，
+    // 之后按 id 重建（多实例恢复）时，侧车让审批策略/思考深度/标题/轮数不漂移。
     this.save();
   }
 
   /** 新建一个会话：拉起进程 + ACP 初始化 + session/new。 */
   async create({ cwd, permission = DEFAULT_PERMISSION, onApproval, titleHint, reasoningEffort, provider, model } = {}) {
-    if (!cwd) throw new Error('必须提供 cwd（工作区绝对路径）');
+    if (!cwd) {
+      throw new Error(
+        '没有可用的工作目录。你既没传 cwd，客户端也没有提供当前打开的项目（MCP roots）。\n' +
+          '  传一个项目目录即可，例如 cwd: "D:/code/my-project"。\n' +
+          '  不要传用户家目录本身 —— 那会让 DSH 的 ACL 沙箱起不来。',
+      );
+    }
     if (!isAbsolute(cwd)) throw new Error(`cwd 必须是绝对路径: ${cwd}`);
-    if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
-      throw new Error(`工作区不存在或不是目录: ${cwd}（请先创建它）`);
+    if (!existsSync(cwd)) {
+      throw new Error(`工作区不存在或不是目录: ${cwd}（请先创建这个目录）`);
+    }
+    if (!statSync(cwd).isDirectory()) {
+      throw new Error(`工作区不存在或不是目录: ${cwd}（这是一个文件路径，请传目录）`);
     }
     if (!PERMISSION_TIERS.includes(permission)) {
       throw new Error(`permission 必须是 ${PERMISSION_TIERS.join(' | ')} 之一`);
@@ -1138,6 +1386,14 @@ export class Hub {
     if (!APPROVAL_POLICIES.includes(policy)) {
       throw new Error(`on_approval 必须是 ${APPROVAL_POLICIES.join(' | ')} 之一`);
     }
+    // ★ read-only 是硬边界：显式 auto-allow/ask 会放行 DSH 的 sandbox 提权，
+    //   实测能把文件写进工作区而会话记录仍显示 read-only。直接拒绝这个组合。
+    if (permission === 'read-only' && policy !== 'auto-deny') {
+      throw new Error(
+        'permission=read-only 强制要求 on_approval=auto-deny（或不传）。' +
+          ' auto-allow/ask 会放行 DSH 的 sandbox 提权，使只读档失效。',
+      );
+    }
     const effort = reasoningEffort ?? DEFAULT_REASONING_EFFORT;
     if (!REASONING_EFFORTS.includes(effort)) {
       throw new Error(`reasoning_effort 必须是 ${REASONING_EFFORTS.join(' | ')} 之一`);
@@ -1145,6 +1401,10 @@ export class Hub {
     if (model && !provider) {
       throw new Error('指定 model 时必须同时给 provider（ACP 的模型标识是 [provider, model] 二元组）');
     }
+    // 家目录当选工作区 → DSH 的 ACL 沙箱起不来，第一次起 shell 才暴露。
+    // 与其让用户以为服务坏了，不如在这里把原因和出路一起说清楚。
+    const homeProblem = homeWorkspaceProblem(cwd, permission);
+    if (homeProblem) throw new Error(homeProblem);
     const proc = new AcpProcess({
       cwd,
       permission,
@@ -1153,9 +1413,11 @@ export class Hub {
       onPermissionRequest: () => ({ outcome: { outcome: 'cancelled' } }),
     });
     proc.start();
+    let createdSessionId = null;
     try {
       await proc.initialize();
       const res = await proc.request('session/new', { cwd, mcpServers: [] });
+      createdSessionId = res.sessionId;
       const conv = new Conversation(
         {
           id: res.sessionId,
@@ -1180,6 +1442,16 @@ export class Hub {
       });
       // 套用会话级配置（思考深度默认 max；ACP 自己的默认是 Provider default）
       conv.lastConfigApplied = await applySessionConfig(proc, res.sessionId, conv.cfg);
+      // ★ 无效的 provider/model 必须 fail fast：旧行为是建出会话、静默回退
+      //   profile 默认模型，调用方以为指定模型已生效。这里在外层 catch 停止进程，
+      //   不注册会话，直接报错（不传 provider/model 才走 profile 默认）。
+      const modelFailure = (conv.lastConfigApplied.failed ?? []).find((f) => String(f).includes('模型='));
+      if (modelFailure) {
+        throw new Error(
+          `指定的 provider/model 无效，会话未创建：${modelFailure}\n` +
+            `  请检查 ${provider}/${model} 是否在 profile 中声明；不传这两个参数可使用 profile 默认模型。`,
+        );
+      }
       // 登记工作区，否则这些会话在你的 DSH GUI 里看不到。
       // ★ 必须容错：registerWorkspace 会写 workspace.json（磁盘满/被占时会抛），
       //   而它在 this.conversations.set 之前 —— 抛出去就会**丢掉这个会话并泄漏进程**。
@@ -1197,6 +1469,10 @@ export class Hub {
       );
       return conv;
     } catch (e) {
+      // 失败路径也要清掉写锁登记：session/new 可能已经成功、登记已写入，
+      // 但会话最终没有注册（例如无效 provider/model 被 fail-fast）。留下 marker
+      // 会被 dsh_list/dsh_takeover 误报成“孤儿持有者”，也会在 locks 目录里积垃圾。
+      if (createdSessionId) removeMarker(createdSessionId);
       await proc.stop().catch(() => {});
       throw e;
     }
@@ -1207,6 +1483,7 @@ export class Hub {
     const out = new Map();
     for (const c of this.conversations.values()) {
       if (cwd && c.cwd !== cwd) continue;
+      if (isForgotten(c.id)) continue;
       out.set(c.id, c.snapshot());
     }
     if (!includeClosed) return [...out.values()];
@@ -1239,6 +1516,7 @@ export class Hub {
     }
     for (const s of sessions) {
       if (out.has(s.sessionId)) continue;
+      if (isForgotten(s.sessionId)) continue;
       const meta = readConversationMeta(s.sessionId);
       out.set(s.sessionId, {
         conversation_id: s.sessionId,