dsh-any-agent 0.3.1 → 0.3.2

package/README.md

@@ -13,7 +13,7 @@ An MCP server that drives DSH as a **long-lived agent runtime** instead of wrapp
 
 **Works with any MCP client.** Nothing here is Codex- or Claude-specific: the server speaks plain MCP over stdio and uses only the four standard methods (`initialize`, `ping`, `tools/list`, `tools/call`). Verified against a bare-bones client that negotiates an older protocol version and never sends `notifications/initialized`.
 
-🧪 632 offline checks green on 0.3.0 (619 of them in the client-registration suites) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
+🧪 660 offline checks green on 0.3.2 (619 of them in the client-registration suites) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
 
 > 📌 **Read the [Usage Notes](USAGE-NOTES.en.md) first** — the practical gotchas that will actually bite you: the ACP model-config trap, external MCP tools bypassing DSH's sandbox, the workspace/GUI registry cache, cost control, and a troubleshooting table.
 >
@@ -210,6 +210,14 @@ Removal is not accepted because it *looks* right: the check is that **taking our
 Afterwards every JSON config still parses and `codex mcp list` still reads the file; no client needs hand repair.
 
 
+**`cwd` is optional: it defaults to the project the client has open**
+
+The client already knows which folder the user is working in (MCP roots). `dsh_start` without `cwd` now sends one `roots/list` request and converts the returned `file://` URI into a path, so "DSH works where the client is looking" is the default - which also removes the usual way to end up on the home directory by building the path by hand. A client that does not advertise roots, or does not answer in time, gets an actionable error instead of a guessed directory.
+
+**Do not use the home directory as `cwd`**
+
+DSH's own ACL sandbox requires its temp directory to be **outside** the workspace. On Windows `%TEMP%` is `C:/Users/<you>/AppData/Local/Temp`, inside the home directory, so `cwd` set to home makes the first shell command fail with `Windows ACL: temp root must be outside the workspace`. `dsh_start` now rejects that combination and names both escapes: a narrower project directory, or `permission=read-only` / `danger-full-access`.
+
 **Backups and rollback**
 
 Both registering and removing snapshot the file first: `<config>.bak-dsh-<timestamp>`, holding the exact pre-operation bytes. Both directions, because the state you want back differs — the pre-register backup undoes a bad install, the pre-remove backup reinstalls after a bad removal.
@@ -518,7 +526,7 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `permission` | 11 | ★ **whether the permission tiers actually take effect** (a safety property): it ignores our own return values (the very thing that used to lie) and reads **the session's own record** (`permissions.preset` / `sandboxMode` in the projection cache), checking all three tiers and that their recorded values differ. **This suite caught a silent privilege escalation**: a `defaultPreset` in the profile overrides `DSH_PERMISSION_MODE` at session creation |
 | `list` | 13 | **the cost of `dsh_list`** (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while **repeated calls hit a cache and drop to single-digit milliseconds**; `only_running=true` and `include_closed=false` **skip the probe** with equivalent semantics (unopened on-disk sessions are simply excluded) |
 
-**The offline half is 632 checks, all green on 0.3.0** — `guards` 31, `prune` 11, `approval-details` 24, `sandbox-guard` 18, `setup` 41, `removal-scope` 24, `config-safety` 403, `real-configs` 66, `package-check` 14. Every suite exited 0; none needs a model, a DSH install or a provider.
+**The offline half is 660 checks, all green on 0.3.2** — `guards` 31, `prune` 11, `approval-details` 24, `sandbox-guard` 18, `setup` 41, `removal-scope` 24, `config-safety` 403, `real-configs` 66, `package-check` 14, `roots` 12, `workspace-titles` 15. Every suite exited 0; none needs a model, a DSH install or a provider.
 
 That is **619 assertions in the client-registration suites alone** (`setup`, `removal-scope`, `config-safety`, `real-configs`), which is where the 0.3 work actually is.
 

package/README.zh.md

@@ -13,7 +13,7 @@
 
 **任何 MCP 客户端都能用。** 这里没有任何 Codex 或 Claude 专属的东西：服务端只讲标准 MCP over stdio，只用四个标准方法（`initialize`、`ping`、`tools/list`、`tools/call`）。已用一个"原始"客户端验证过——它协商更旧的协议版本、且从不发 `notifications/initialized`。
 
-🧪 0.3.0 离线 632 项检查全绿（其中 619 项属于客户端注册器套件） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
+🧪 0.3.2 离线 660 项检查全绿（其中 619 项属于客户端注册器套件） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
 
 > 📌 **建议先读 [使用注意事项](USAGE-NOTES.md)** —— 会真正踩到的坑：ACP 模型配置陷阱、**外部 MCP 工具的副作用不受 DSH 沙箱约束**、工作区与 GUI 的注册表缓存、成本控制、以及一张故障速查表。
 >
@@ -225,6 +225,14 @@ Codex 的 `config.toml` 同理，是按行处理的：其它 `[表]` 及其注
 撤销后所有 JSON 仍可解析、`codex mcp list` 仍能正常读取配置，客户端不需要人工修复。
 
 
+**`cwd` 可以省略：默认用客户端当前打开的项目**
+
+客户端本来就知道用户在哪个目录干活（MCP roots）。现在 `dsh_start` 不传 `cwd` 时，会向客户端发一次 `roots/list`，把返回的 `file://` URI 转成路径直接用。于是「客户端里看到哪个项目，DSH 就在哪个项目干活」成了默认行为，也顺带堵掉了「手拼路径拼到家目录」这条最常见的翻车路径。客户端不声明 roots、或者超时没回，就退回一条能照着改的报错，而不是猜一个目录。
+
+**cwd 不要选家目录本身**
+
+DSH 自己的 ACL 沙箱要求临时目录在工作区**之外**。Windows 上 `%TEMP%` 是 `C:/Users/<你>/AppData/Local/Temp`，就在家目录里面，所以 `cwd` 取家目录时，第一条 shell 命令会失败并报 `Windows ACL: temp root must be outside the workspace`。现在 `dsh_start` 会直接拒绝这个组合并给出两条出路：换一个具体项目目录，或改用 `permission=read-only` / `danger-full-access`。
+
 **备份与回滚**
 
 注册和删除**都会**在动文件之前先存一份：`<配置文件>.bak-dsh-<时间戳>`，内容就是操作前的原始字节。两个方向都存，因为要退回的状态不同——注册前那份用来「装错了退回原样」，删除前那份用来「删错了装回去」。
@@ -538,7 +546,7 @@ node test/cleanup.mjs      # 单独跑收尾清理（只针对临时目录；--d
 | `permission` | 11 | ★ **权限档是否真的生效**（安全属性）：不看我们的返回值（那正是会说谎的地方），而是读**会话自己记录的事实**（投影缓存里的 `permissions.preset` / `sandboxMode`），三档逐一核对且三档记录值互不相同。**这条测试抓到过无声提权**：profile 里 `defaultPreset` 会在会话创建时盖掉 `DSH_PERMISSION_MODE` |
 | `list` | 13 | **`dsh_list` 的开销**（实测驱动）：含磁盘探测的默认调用约 1 秒（要 spawn 一个 DSH 进程），**连续调用命中缓存降到个位数毫秒**；`only_running=true` 与 `include_closed=false` **跳过探测**且语义等价（不把磁盘上的未打开会话算进来） |
 
-**离线那半边是 632 项检查，0.3.0 上全绿** —— `guards` 31、`prune` 11、`approval-details` 24、`sandbox-guard` 18、`setup` 41、`removal-scope` 24、`config-safety` 403、`real-configs` 66、`package-check` 14。九套全部退出码 0，都不需要模型、不需要装 DSH、也不需要 provider。
+**离线那半边是 660 项检查，0.3.2 上全绿** —— `guards` 31、`prune` 11、`approval-details` 24、`sandbox-guard` 18、`setup` 41、`removal-scope` 24、`config-safety` 403、`real-configs` 66、`package-check` 14、`roots` 12、`workspace-titles` 15。九套全部退出码 0，都不需要模型、不需要装 DSH、也不需要 provider。
 
 其中 **619 项属于客户端注册器套件**（`setup`、`removal-scope`、`config-safety`、`real-configs`）—— 0.3 的活其实都在这里。
 

package/bin/dsh-any-agent.mjs

@@ -53,6 +53,7 @@ const { createLogger } = await import('../src/config.mjs');
 const { Hub } = await import('../src/hub.mjs');
 const { createMcpServer } = await import('../src/mcp.mjs');
 const { listOrphans, pruneDeadMarkers } = await import('../src/locks.mjs');
+const { createHandlers } = await import('../src/tools.mjs');
 
 const log = createLogger();
 
@@ -78,7 +79,9 @@ if (deadMarkers.removed || orphans.length) {
 }
 if (orphans.length) log.info(`[dsh-any-agent] 孤儿持有者会话: ${orphans.map((o) => o.conversation_id).join(', ')}`);
 
-const server = createMcpServer({ hub, log });
+// dsh_start 不传 cwd 时，用客户端当前打开的项目目录（MCP roots）。
+// 这样「客户端里看到哪个项目，DSH 就在哪个项目干活」是默认行为。
+const server = createMcpServer({ hub, log, handlers: createHandlers(hub, { projectDir: () => server.projectDir() }) });
 server.start();
 
 log.info(`[dsh-any-agent] 已启动（注册表载入 ${hub.conversations.size} 个会话，日志级别 ${log.level}）`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Drive DeepSeek Harness (DSH) as a long-lived coding agent from any MCP client — Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Zed, Gemini CLI, opencode, VS Code. Resume-aware, interruptible, approval-capable, and it only ever touches the one config entry it owns.",
   "type": "module",
   "license": "MIT",

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,
@@ -236,6 +237,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,
@@ -915,6 +923,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();
@@ -1126,7 +1171,13 @@ export class Hub {
 
   /** 新建一个会话：拉起进程 + 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}（请先创建它）`);
@@ -1145,6 +1196,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,

package/src/mcp.mjs

@@ -39,7 +39,8 @@ DSH 自己有文件读写、shell、搜索、技能、子代理等全套工具
 - cursor —— dsh_read 的增量游标，用来观察某个会话当前吐出的内容。
 
 【标准流程】
-1. dsh_start(cwd, ...)                        建会话。cwd 必须是**已存在**的绝对路径。
+1. dsh_start(cwd?, ...)                       建会话。cwd 省略时自动用客户端当前打开的项目目录
+                                              （MCP roots）；给了就必须是**已存在**的绝对路径，别传家目录本身。
 2. dsh_send(conversation_id, prompt)          **默认不阻塞**：立刻返回 run_id + sentinel_file。
                                               想原地等结果才传 wait=true。
 3. 之后按需：
@@ -96,10 +97,70 @@ dsh_interject —— 一个回合 = 一个哨兵，没有例外）。dsh_send
 - 不要把 DSH 内部的工具名（read/pwsh/glob 等）当成本服务的工具——本服务只有 dsh_* 这些。
 - 不要假设回合秒回。长任务请走 wait=false + 事后验收。`;
 
+/**
+ * 把 MCP root 的 file:// URI 转成本地路径。
+ * 只接受 file 协议；其它（http/内嵌工作区等）一律当作“用不了”，
+ * 宁可退回要求显式 cwd，也不要把一个奇怪的字符串当成目录。
+ */
+function fileURLToPathSafe(uri) {
+  try {
+    if (!uri.startsWith('file:')) return null;
+    return fileURLToPath(uri);
+  } catch {
+    return null;
+  }
+}
+
 export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHandlers(hub), log }) {
   const write = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
   let buffer = '';
   let initialized = false;
+  let clientCapabilities = {};
+  let rootsSeq = 0;
+  const pendingRoots = new Map();
+  /** 客户端当前打开的项目目录（来自 MCP roots）。null 表示还没有/不支持。 */
+  let clientRoots = null;
+  let rootsRequested = false;
+
+  /**
+   * 主动向客户端要一次 roots。
+   * 这不是 JSON-RPC 的“请求-响应”对称用法：MCP 的服务端可以反向发请求，
+   * 客户端用同一个 stdout 回响应。所以这里带 id 发出去，再等 onData 收到
+   * 对应 id 的消息来完成 promise。超时/不支持都必须安静降级 —— roots 只是
+   * 一个更聪明的默认值，拿不到就让调用方显式传 cwd。
+   */
+  function requestRoots(timeoutMs = 1500) {
+    if (rootsRequested) return Promise.resolve(clientRoots);
+    rootsRequested = true;
+    const caps = clientCapabilities?.roots;
+    if (!caps) return Promise.resolve(null);
+    const id = 'roots-' + (rootsSeq++);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        pendingRoots.delete(id);
+        resolve(null);
+      }, timeoutMs);
+      timer.unref?.();
+      pendingRoots.set(id, (roots) => {
+        clearTimeout(timer);
+        clientRoots = roots;
+        resolve(roots);
+      });
+      write({ jsonrpc: '2.0', id, method: 'roots/list', params: {} });
+    });
+  }
+
+  /** 从 roots 里挑一个最像“项目目录”的路径。 */
+  function pickRoot(roots) {
+    if (!Array.isArray(roots) || !roots.length) return null;
+    const uris = roots.map((r) => r && typeof r.uri === 'string' ? r.uri : null).filter(Boolean);
+    if (!uris.length) return null;
+    for (const uri of uris) {
+      const asPath = fileURLToPathSafe(uri);
+      if (asPath) return asPath;
+    }
+    return null;
+  }
 
   const ok = (id, result) => write({ jsonrpc: '2.0', id, result });
   const fail = (id, code, message) => write({ jsonrpc: '2.0', id, error: { code, message } });
@@ -107,6 +168,14 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
   async function handle(msg) {
     const { id, method, params } = msg;
 
+    // 客户端对我们反向请求（roots/list）的响应：没有 method，只有 result/error。
+    if (method === undefined && pendingRoots.has(id)) {
+      const done = pendingRoots.get(id);
+      pendingRoots.delete(id);
+      done(msg.error ? [] : (msg.result?.roots ?? []));
+      return;
+    }
+
     // 通知（无 id）：不需要回包
     if (id === undefined) {
       if (method === 'notifications/initialized') initialized = true;
@@ -116,6 +185,11 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
     switch (method) {
       case 'initialize': {
         const requested = params?.protocolVersion;
+        // 记住客户端声明了哪些能力：有 roots 的客户端（Claude Code / Cursor /
+        // VS Code 等）会告诉我们它当前打开的项目目录，那是 dsh_start 最合理的
+        // 默认 cwd —— 用户在客户端里看到哪个项目，就在这里干活。
+        const caps = params?.capabilities;
+        clientCapabilities = caps && typeof caps === 'object' ? caps : {};
         ok(id, {
           protocolVersion: typeof requested === 'string' ? requested : FALLBACK_PROTOCOL,
           capabilities: { tools: { listChanged: false } },
@@ -124,6 +198,11 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
         });
         return;
       }
+      case 'roots/list': {
+        // 有的客户端会主动问；我们不需要“暴露自己的根”，回空即可。
+        ok(id, { roots: [] });
+        return;
+      }
       case 'ping':
         ok(id, {});
         return;
@@ -190,8 +269,13 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
       process.stdin.on('end', () => log?.debug('[mcp] stdin 结束'));
       return this;
     },
+    /** 客户端当前打开的项目目录；不支持 roots 的客户端返回 null。 */
+    async projectDir() {
+      const roots = await requestRoots();
+      return pickRoot(roots);
+    },
     get initialized() {
       return initialized;
     },
   };
-}
+}

package/src/tools.mjs

@@ -34,7 +34,13 @@ export const TOOL_DEFS = [
       '返回 conversation_id 与对话标题。建好后用 dsh_send 派活。',
     inputSchema: S(
       {
-        cwd: { type: 'string', description: '工作区绝对路径。决定 agent 的工作目录、AGENTS.md/技能的发现范围、以及沙箱可写根。' },
+        cwd: {
+          type: 'string',
+          description:
+            '工作区绝对路径。决定 agent 的工作目录、AGENTS.md/技能的发现范围、以及沙箱可写根。' +
+            '**省略时自动用客户端当前打开的项目目录**（MCP roots），这样客户端里看到哪个项目就在这里干活；' +
+            '客户端不支持 roots 时才会要求你显式传入。别传用户家目录本身 —— 那里会让 DSH 的 ACL 沙箱起不来。',
+        },
         permission: {
           type: 'string',
           enum: PERMISSION_TIERS,
@@ -48,7 +54,12 @@ export const TOOL_DEFS = [
           enum: APPROVAL_POLICIES,
           description: `审批处理策略。默认 read-only → auto-deny，其余 → ${process.env.DSH_MCP_APPROVAL ?? 'auto-allow'}。ask 会把审批挂起，需用 dsh_approval_decide 裁决。`,
         },
-        title_hint: { type: 'string', description: '可选的标题提示（DSH 的标题由首条消息自动生成，这里只是兜底显示）。' },
+        title_hint: {
+          type: 'string',
+          description:
+            '可读的会话标签。注意 DSH 自己的标题是首条消息的截断前缀（约 13–15 字），会优先显示；' +
+            '这里给的值不会被覆盖，而是在 dsh_get / dsh_start 里作为「标题提示」一并返回。',
+        },
         reasoning_effort: {
           type: 'string',
           enum: REASONING_EFFORTS,
@@ -57,7 +68,8 @@ export const TOOL_DEFS = [
         provider: { type: 'string', description: '模型提供方名（如 deepseek-official）。留空用 profile 默认。' },
         model: { type: 'string', description: '模型名（如 deepseek-flash）。指定时必须同时给 provider。' },
       },
-      ['cwd'],
+      // cwd 不再是必填：有 MCP roots 的客户端会自动带上当前项目目录。
+      [],
     ),
   },
   {
@@ -319,11 +331,30 @@ function backgroundReceipt(hub, conv, res) {
   };
 }
 
-export function createHandlers(hub) {
+/**
+ * @param {object} hub
+ * @param {{projectDir?: () => Promise<string|null>}} [opts]
+ *   projectDir：客户端当前打开的项目目录（MCP roots）。不传 cwd 时用它兜底 ——
+ *   让「在客户端里看到哪个项目，就在哪个项目干活」成为默认行为，而不是让
+ *   调用方每次都自己拼绝对路径（拼错了就落到家目录，撞上 ACL 沙箱那个坑）。
+ */
+export function createHandlers(hub, opts = {}) {
+  const projectDir = typeof opts.projectDir === 'function' ? opts.projectDir : null;
+
   return {
     async dsh_start(args) {
+      let cwd = args.cwd;
+      let cwdSource = cwd ? 'explicit' : null;
+      if (!cwd && projectDir) {
+        // 客户端声明了 roots 才有；拿不到就照旧要求显式传，不猜。
+        const fromClient = await projectDir();
+        if (fromClient) {
+          cwd = fromClient;
+          cwdSource = 'client-root';
+        }
+      }
       const conv = await hub.create({
-        cwd: args.cwd,
+        cwd,
         permission: args.permission ?? DEFAULT_PERMISSION,
         onApproval: args.on_approval,
         titleHint: args.title_hint,
@@ -336,10 +367,11 @@ export function createHandlers(hub) {
       const lines = [
         '已创建会话。',
         `conversation_id: ${snap.conversation_id}`,
-        `工作区: ${snap.cwd}`,
+        `工作区: ${snap.cwd}` + (cwdSource === 'client-root' ? '（取自客户端当前打开的项目）' : ''),
         `权限档: ${snap.permission}（审批策略 ${snap.on_approval}）`,
         `思考深度: ${snap.reasoning_effort}`,
-        `对话名: ${snap.title ?? '(DSH 尚未生成，发出第一条消息后自动生成)'}`,
+        `对话名: ${snap.title ?? '(DSH 尚未生成，发出第一条消息后自动生成)'}` +
+        (snap.title_hint && snap.title !== snap.title_hint ? `（你给的标题提示: ${snap.title_hint}）` : ''),
         `工作区登记: ${snap.workspace_registered ? '已写入 DSH 工作区注册表（GUI 里能看到）' : '未登记'}`,
       ];
       if (snap.config_failed?.length) lines.push(`⚠️ 配置未完全套用: ${snap.config_failed.join('; ')}`);
@@ -451,7 +483,9 @@ export function createHandlers(hub) {
       const snap = conv.snapshot();
       let run = null;
       const meta = [];
-      meta.push(`对话名: ${snap.title ?? '(尚未生成)'}（DSH 自动生成）`);
+      // DSH 的自动标题是首条消息的截断前缀，信息量低；调用方给过 title_hint 就一并显示。
+      meta.push(`对话名: ${snap.title ?? '(尚未生成)'}（DSH 自动生成）` +
+        (snap.title_hint && snap.title !== snap.title_hint ? ` / 标题提示: ${snap.title_hint}` : ''));
       meta.push(`工作区: ${snap.cwd}`);
       meta.push(`状态: ${snap.busy ? '忙' : snap.alive ? '空闲(进程活着)' : '未打开(可用 resume 复活)'}`);
       meta.push(`权限档: ${snap.permission} / 审批 ${snap.on_approval}`);
@@ -620,4 +654,4 @@ export function createHandlers(hub) {
       };
     },
   };
-}
+}