dsh-any-agent 0.3.3 → 0.3.5

package/bin/dsh-any-agent-workspaces.mjs

@@ -15,7 +15,8 @@
  *   node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions [--dry-run] [--ids=a,b]
  *
  * 只有 --purge-test-sessions 会动磁盘上的会话文件，且规则很死：只删
- * "cwd 在系统临时目录下" 或 "cwd 在 Desktop\dsh-any-agent-test-*" 的会话，外加 --ids 显式指定的。
+ * "cwd 在 tmpdir()/dsh-any-agent-* 下" 或 "cwd 在 Desktop\dsh-any-agent-test-*" 的会话，
+ * 外加 --ids 显式指定的。**不会**删除用户在 %TEMP% 里自己的真实项目会话。
  */
 
 import {
@@ -45,7 +46,7 @@ const ids = (val('--ids') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
 
 // ── 清理测试会话（唯一会删文件的动作） ──────────────────────
 if (has('--purge-test-sessions')) {
-  const res = purgeTestSessions({ dryRun, ids });
+  const res = purgeTestSessions({ dryRun, ids, testOnly: true });
   console.log(`${flag}清理测试会话：${res.count} 个`);
   for (const v of res.victims) {
     console.log(`  - ${v.id}  [${v.reason}]${v.origin ? ` origin=${v.origin}` : ''}  cwd=${v.cwd}`);
@@ -59,6 +60,10 @@ if (has('--purge-test-sessions')) {
 // ── 回填 ────────────────────────────────────────────────────
 if (has('--backfill')) {
   const stats = backfillWorkspaces({ includeTemp: has('--include-temp'), dryRun });
+  if (stats.error) {
+    console.error(`${flag}回填失败（未写盘）：${stats.error}`);
+    process.exitCode = 1;
+  }
   console.log(`${flag}回填：`);
   console.log(`  扫描到会话            ${stats.sessions_scanned}`);
   console.log(`  新建工作区            ${stats.workspaces_created}`);
@@ -74,6 +79,10 @@ if (has('--backfill')) {
 // ── 清理临时工作区 ──────────────────────────────────────────
 if (has('--prune-temp')) {
   const res = pruneTempWorkspaces({ dryRun });
+  if (res.error) {
+    console.error(`${flag}清理失败（未写盘）：${res.error}`);
+    process.exitCode = 1;
+  }
   console.log(`${flag}清理临时工作区条目：${res.removed.length} 个`);
   for (const r of res.removed) console.log(`  - ${r.path}（含 ${r.sessions} 个会话条目）`);
   console.log('');
@@ -82,6 +91,10 @@ if (has('--prune-temp')) {
 // ── 清理空工作区 ────────────────────────────────────────────
 if (has('--prune-empty')) {
   const res = pruneEmptyWorkspaces({ dryRun });
+  if (res.error) {
+    console.error(`${flag}清理失败（未写盘）：${res.error}`);
+    process.exitCode = 1;
+  }
   console.log(`${flag}清理"无会话且路径已不存在"的工作区：${res.removed.length} 个`);
   for (const r of res.removed) console.log(`  - ${r.path}`);
   console.log('');
@@ -89,7 +102,13 @@ if (has('--prune-empty')) {
 
 // ── 列表（或什么都不传时默认） ──────────────────────────────
 if (has('--list') || argv.length === 0 || argv.every((a) => a === '--dry-run')) {
-  const list = listWorkspaces();
+  let list;
+  try {
+    list = listWorkspaces();
+  } catch (e) {
+    console.error(`读取工作区注册表失败: ${e.message}`);
+    process.exit(1);
+  }
   const temp = list.filter((w) => w.is_temp);
   console.log(`共 ${list.length} 个工作区（临时目录 ${temp.length} 个）——**这是文件里的内容**：`);
   for (const w of list.sort((a, b) => Number(a.is_temp) - Number(b.is_temp))) {

package/bin/dsh-any-agent.mjs

@@ -5,9 +5,10 @@
  * 环境变量：
  *   DSH_BIN                     DSH CLI 入口（默认探测 npx 缓存位置）
  *   DSH_MCP_PROFILE             驱动用的 DSH profile（默认 dsh-mcp）
- *   DSH_MCP_STATE               会话注册表路径（默认 <仓库>/.state/conversations.json）
+ *   DSH_MCP_STATE               会话注册表路径（默认 $DSH_HOME/.dsh-any-agent/conversations.json）
  *   DSH_MCP_PERMISSION          新建会话的默认权限档（默认 danger-full-access）
- *   DSH_MCP_IDLE_TTL_MS         空闲多久回收会话进程（默认 5 分钟）
+ *   DSH_MCP_APPROVAL            默认审批策略（非只读档默认 auto-allow；ask = 挂起待裁决）
+ *   DSH_MCP_IDLE_TTL_MS         空闲多久回收会话进程（默认 0 = 永不回收）
  *   DSH_MCP_PROMPT_TIMEOUT_MS   wait=true 时的等待上限（默认 0 = 不设超时）
  *   DSH_MCP_LOCK_STALE_MS       写锁登记多久没心跳算"持有者失联"（默认 90 秒）
  *   DSH_MCP_LOG                 silent(默认) | info | debug —— 日志级别

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",
@@ -36,6 +36,7 @@
     "USAGE-NOTES.en.md",
     "USAGE-NOTES.md",
     "USAGE-MIGRATION.md",
+    "CHANGELOG.md",
     "LICENSE",
     "DESIGN.md",
     "scripts/"

package/src/acp.mjs

@@ -11,7 +11,7 @@
 
 import { spawn } from 'node:child_process';
 import { ensureProfile } from './bootstrap.mjs';
-import { DSH_PROFILE, REQUEST_TIMEOUT_MS, resolveDshBin } from './config.mjs';
+import { DSH_PROFILE, PKG_VERSION, REQUEST_TIMEOUT_MS, resolveDshBin } from './config.mjs';
 
 /** ACP 协议版本（@agentclientprotocol/sdk 的 v1）。 */
 const PROTOCOL_VERSION = 1;
@@ -83,6 +83,22 @@ export class AcpProcess {
     });
 
     this.#child.stdout.on('data', (d) => this.#onData(d));
+    // ★ stdio 的 'error' 必须常驻监听：子进程退出与下一次写入之间存在竞态，
+    //   未监听的 EPIPE 会以未处理错误终止**整个 MCP 进程**（连带所有会话）。
+    const streamError = (e) => {
+      this.#log.info(`[acp] 子进程 stdio 错误: ${e.message}`);
+      const err = new Error(`DSH 进程 stdio 不可用: ${e.message}`);
+      for (const [, p] of this.#pending) {
+        clearTimeout(p.timer);
+        p.reject(err);
+      }
+      this.#pending.clear();
+      this.#child = null;
+      this.initialized = false;
+    };
+    this.#child.stdin.on('error', streamError);
+    this.#child.stdout.on('error', streamError);
+    this.#child.stderr.on('error', streamError);
     this.#child.stderr.on('data', (d) => {
       for (const line of d.toString('utf8').split(/\r?\n/)) {
         if (!line.trim()) continue;
@@ -205,7 +221,12 @@ export class AcpProcess {
             }, timeoutMs)
           : null;
       this.#pending.set(id, { resolve, reject, timer });
-      this.#write({ jsonrpc: '2.0', id, method, params });
+      const written = this.#write({ jsonrpc: '2.0', id, method, params });
+      if (!written) {
+        if (timer) clearTimeout(timer);
+        this.#pending.delete(id);
+        reject(new Error(`ACP 写入失败（子进程 stdin 不可写）: ${method}`));
+      }
     });
   }
 
@@ -227,7 +248,7 @@ export class AcpProcess {
     this.#initResult = await this.request('initialize', {
       protocolVersion: PROTOCOL_VERSION,
       clientCapabilities: {},
-      clientInfo: { name: 'dsh-any-agent', version: '0.1.0' },
+      clientInfo: { name: 'dsh-any-agent', version: PKG_VERSION },
     });
     this.initialized = true;
     return this.#initResult;

package/src/bootstrap.mjs

@@ -16,19 +16,15 @@
  *   自己的凭据服务在每次请求时解析（$DSH_HOME/.credentials.yaml > 继承环境 > .env），
  *   与 GUI 完全同一条路径。
  *
- * 幂等性：用户手改过 profile 就不覆盖（用内容指纹判断），只报告。
+ * 幂等性：用户手改过 profile（删掉 managed 标记）就不再覆盖，只报告。
  */
 
 import { createHash } from 'node:crypto';
-import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 
 import { BOOTSTRAP_ENABLED, DSH_HOME, DSH_PROFILE, ROUTE_SOURCE_PROFILE } from './config.mjs';
-
-/** server 包根目录（本文件位于 <server>/src/）。 */
-const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+import { load as yamlLoad, dump as yamlDump } from './yaml-lite.mjs';
 
 /** 与 dsh 内置 acp 模板一致的组合包列表。 */
 const PROFILE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-acp-app'];
@@ -47,25 +43,37 @@ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /** 一眼像密钥的值（防止有人把字面密钥写进 apiKeyEnv）。 */
 const LOOKS_LIKE_SECRET = /^(sk-|ak-|Bearer\s|eyJ)/i;
-
-/**
- * 载入 YAML 解析器。自包含导出包从兄弟 runtime 目录取（包内没有 node_modules），
- * 普通 npm 安装走正常的模块解析。
- */
-function loadYaml() {
-  const anchors = [
-    join(PKG_ROOT, 'src', 'anchor.mjs'),
-    join(PKG_ROOT, '..', 'runtime', 'node_modules', 'anchor.cjs'),
-    join(PKG_ROOT, '..', '..', 'runtime', 'node_modules', 'anchor.cjs'),
-  ];
-  for (const anchor of anchors) {
-    try {
-      return createRequire(anchor)('js-yaml');
-    } catch {
-      /* 换下一个锚点 */
+/** 任何层级都不复制的凭据字段（providers/models 的嵌套对象同样适用）。 */
+const SECRET_KEY = /^(?:api[_-]?key|apikey|authorization|proxy[_-]?authorization|cookie|set[_-]?cookie|password|passwd|secret|token|access[_-]?token|refresh[_-]?token|credentials?|headers|client[_-]?secret|private[_-]?key|access[_-]?key[_-]?id|oauth|env|environment)$/i;
+
+/** 递归剥掉凭据字段；baseURL 里的 userinfo 也一并清掉。 */
+function scrubSecrets(value, key = '') {
+  if (SECRET_KEY.test(key)) return undefined;
+  if (typeof value === 'string') {
+    if (key === 'baseURL') {
+      try {
+        const u = new URL(value);
+        if (u.username || u.password) {
+          u.username = '';
+          u.password = '';
+          return u.toString();
+        }
+      } catch {
+        /* 不是合法 URL：原样保留，让 DSH 自己报错 */
+      }
     }
+    return value;
   }
-  return null;
+  if (Array.isArray(value)) return value.map((item) => scrubSecrets(item));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const clean = scrubSecrets(v, k);
+      if (clean !== undefined) out[k] = clean;
+    }
+    return out;
+  }
+  return value;
 }
 
 /** profile 目录：$DSH_HOME/profiles/<name>。 */
@@ -96,29 +104,16 @@ function sanitizeProviders(raw) {
   const out = {};
   for (const [route, profile] of Object.entries(raw)) {
     if (!profile || typeof profile !== 'object' || Array.isArray(profile)) continue;
-    const clean = {};
-    for (const [k, v] of Object.entries(profile)) {
-      // apiKey 是适配器从不读取的字段；headers 里可能夹部署凭据。两者都不复制。
-      if (k === 'apiKey' || k === 'headers') continue;
-      clean[k] = v;
-    }
+    // 递归剥离：provider 层与 models[] 里的 headers/apiKey/clientSecret 等
+    // 都不会被抄进受管 profile（以前只处理顶层，模型级 headers 会漏过去）。
+    const clean = scrubSecrets(profile);
+    if (!clean || typeof clean !== 'object') continue;
     if (typeof clean.apiKeyEnv === 'string') {
       if (LOOKS_LIKE_SECRET.test(clean.apiKeyEnv) || !ENV_NAME.test(clean.apiKeyEnv)) {
         // 疑似把字面密钥写进了 apiKeyEnv：丢掉引用，而不是把密钥抄进新文件
         delete clean.apiKeyEnv;
       }
     }
-    if (Array.isArray(clean.models)) {
-      clean.models = clean.models.map((m) => {
-        if (!m || typeof m !== 'object') return m;
-        const copy = {};
-        for (const [k, v] of Object.entries(m)) {
-          if (k === 'apiKey') continue;
-          copy[k] = v;
-        }
-        return copy;
-      });
-    }
     out[route] = clean;
   }
   return Object.keys(out).length > 0 ? out : null;
@@ -165,7 +160,7 @@ function sanitizeDeepseek(config) {
 }
 
 /** 依次从候选来源里找第一份能用的路由。 */
-function findRouting(yaml) {
+function findRouting() {
   const candidates = ROUTE_SOURCE_PROFILE ? [ROUTE_SOURCE_PROFILE] : DEFAULT_SOURCES;
   const tried = [];
   for (const name of candidates) {
@@ -179,7 +174,7 @@ function findRouting(yaml) {
     }
     let entries;
     try {
-      entries = yaml.load(readFileSync(file, 'utf8'));
+      entries = yamlLoad(readFileSync(file, 'utf8'));
     } catch (e) {
       tried.push({ source: name, file, reason: '解析失败: ' + e.message });
       continue;
@@ -257,22 +252,42 @@ function buildEntries(routing) {
   //   - acp-app 包里把它写死成 deepseek-official/deepseek-v4-flash（会去找 DEEPSEEK_API_KEY）；
   //   - 若清成 {}，ACP 会话就没有初始模型选择，settings 里的 reasoning_effort 也就无处可设。
   //   所以这里显式指向本机自己的默认路由 —— 与 GUI 会话用的是同一个模型。
+  if (!defaultModel?.provider || !defaultModel?.model) {
+    throw new Error(
+      '找到的路由里没有可用的默认 provider/model：请先在 DSH GUI 的 Models 页面\n' +
+        '  配置一个带 models 列表的 provider（或在来源 profile 里写 agent-default-model）。',
+    );
+  }
   entries.push({
     id: 'acp',
     name: '@deepseek-ai/dsh-acp',
-    config: defaultModel ? { provider: defaultModel.provider, model: defaultModel.model } : {},
+    config: { provider: defaultModel.provider, model: defaultModel.model },
   });
+  entries.push({ id: 'agent-default-model', config: defaultModel });
 
-  if (defaultModel) entries.push({ id: 'agent-default-model', config: defaultModel });
+  // ★ 与 profile-example 对齐：显式声明三档预设，但**绝不写 defaultPreset**。
+  //   defaultPreset 会在会话创建时覆盖 DSH_PERMISSION_MODE，导致 read-only 被静默提权
+  //   （test/permission.mjs 实测抓到过）。不写它时，DSH 按 sandbox+approval 组合推断。
+  entries.push({
+    id: 'permission',
+    name: '@deepseek-ai/dsh-permission-presets',
+    config: {
+      presets: {
+        'read-only': { sandbox: 'read-only', approval: 'ask' },
+        'workspace-write': { sandbox: 'workspace-write', approval: 'ask' },
+        'danger-full-access': { sandbox: 'danger-full-access', approval: 'never' },
+      },
+    },
+  });
   return entries;
 }
 
-function renderDocument(yaml, entries, source) {
+function renderDocument(entries, source) {
   const where =
     source === '__home__' ? join(DSH_HOME, 'cordis.patch.yml') : 'profile "' + source + '"';
   const header = [
     '# ' + MANAGED_MARKER + ': 本文件由 dsh-any-agent 首次启动时自动生成，可安全删除后重建。',
-    '# 也可以手改：手改之后 dsh-any-agent 不会再覆盖它（用内容指纹判断）。',
+    '# 也可以手改：手改之后 dsh-any-agent 不会再覆盖它（用开头的 managed 标记判断）。',
     '#',
     '# 这里**不含任何密钥**：路由只声明 apiKeyEnv / baseURL / api / models，',
     '# 真正的凭据由 DSH 在每次请求时从 $DSH_HOME/.credentials.yaml（或环境变量）解析，',
@@ -281,7 +296,7 @@ function renderDocument(yaml, entries, source) {
     '# 路由来源: ' + where,
     '',
   ].join('\n');
-  return header + yaml.dump(entries, { lineWidth: 200, noRefs: true });
+  return header + yamlDump(entries);
 }
 
 /**
@@ -306,18 +321,8 @@ export function ensureProfile({ log } = {}) {
     return { ok: false, error: '创建 profile 目录失败: ' + e.message };
   }
 
-  const yaml = loadYaml();
-  if (!yaml) {
-    return {
-      ok: false,
-      error: '未找到 YAML 解析器（js-yaml）：无法从本机已有 profile 复制模型路由',
-      reason: '请在 server/ 下安装 js-yaml，或使用自包含导出包',
-    };
-  }
-
   const patchPath = join(dir, 'cordis.patch.yml');
   const existed = existsSync(patchPath);
-  const state = readManagedState();
 
   /**
    * 归属判断：**只看文件里有没有 MANAGED_MARKER**。
@@ -338,7 +343,7 @@ export function ensureProfile({ log } = {}) {
     return { ok: true, skipped: 'profile 由用户维护（无管理标记），保持原样' };
   }
 
-  const found = findRouting(yaml);
+  const found = findRouting();
   if (!found.routing) {
     if (existed) return { ok: true, skipped: '本机没有可复制的模型路由，且 profile 已存在' };
     return {
@@ -349,8 +354,13 @@ export function ensureProfile({ log } = {}) {
     };
   }
 
-  const entries = buildEntries(found.routing);
-  const text = renderDocument(yaml, entries, found.source);
+  let entries;
+  try {
+    entries = buildEntries(found.routing);
+  } catch (e) {
+    return { ok: false, error: e.message, reason: '未写入 profile' };
+  }
+  const text = renderDocument(entries, found.source);
   const hash = sha256(text);
 
   // 与磁盘上的实际内容比对（不用 state.hash：DSH 自己也会改写这个文件）
@@ -401,12 +411,11 @@ export function inspectProfile() {
   const dir = profileDir();
   const patchPath = join(dir, 'cordis.patch.yml');
   const state = readManagedState();
-  const yaml = loadYaml();
   let routes = [];
   let agentDefaultModel = null;
-  if (yaml && existsSync(patchPath)) {
+  if (existsSync(patchPath)) {
     try {
-      const routing = extractRouting(yaml.load(readFileSync(patchPath, 'utf8')));
+      const routing = extractRouting(yamlLoad(readFileSync(patchPath, 'utf8')));
       routes = Object.keys(routing?.providers || {});
       agentDefaultModel = routing?.agentDefaultModel || null;
     } catch {

package/src/clients.mjs

@@ -32,6 +32,7 @@ import {
 } from 'node:fs';
 import { platform } from 'node:os';
 import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** 写进每个客户端的条目名。同时也是 --remove 唯一的识别依据。 */
 export const ENTRY_NAME = 'dsh-any-agent';
@@ -652,7 +653,7 @@ export function existingShapeMode(client, file) {
 export function clientList(dirs) {
   const { home, appData } = dirs;
   return [
-    { ...jsonClient('claude-code', 'Claude Code', 'vscode', 'mcpServers', () => join(home, '.claude.json')), verifyCli: 'claude' },
+    jsonClient('claude-code', 'Claude Code', 'vscode', 'mcpServers', () => join(home, '.claude.json')),
     jsonClient(
       'claude-desktop', 'Claude Desktop', 'default', 'mcpServers',
       () => IS_WIN || IS_MAC
@@ -684,7 +685,9 @@ export function isPresent(client, dirs) {
 
 export function defaultLaunch() {
   // 与本模块相邻的 bin/dsh-any-agent.mjs 优先；否则退回 PATH 上的命令。
-  const here = dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
+  // ★ 必须用 fileURLToPath：new URL(...).pathname 会把路径里的空格/中文变成
+  //   %20 / 百分号编码，existsSync 失败后静默退回 PATH 命令，客户端随后连接失败。
+  const here = dirname(fileURLToPath(import.meta.url));
   const sibling = join(here, '..', 'bin', 'dsh-any-agent.mjs');
   if (existsSync(sibling)) return { command: process.execPath, args: [sibling], style: 'node + sibling entry' };
   return { command: ENTRY_NAME, args: [], style: 'PATH command' };
@@ -866,24 +869,16 @@ export function applyClient(plan, ctx, stamp) {
     if (originalMode !== null) {
       try { chmodSync(plan.path, originalMode); } catch { /* 尽力而为 */ }
     }
-    const base = {
+    // ★ 不再调用客户端 CLI 做验证。
+    //   Claude Code 的 `claude mcp get` 会让客户端**整体回写** ~/.claude.json
+    //   （实测会丢掉 projects[*].history、往顶层塞十几个键）。我们只承诺
+    //   "只改自己那一条"，因此验证只报告我们写入的字节与备份路径，不碰客户端。
+    return {
       ...plan,
       status: remove ? 'removed' : 'applied',
       summary: (remove ? 'entry removed' : 'entry written') + (originalMode !== null ? ' (read-only file overridden by --force)' : ''),
       backup,
     };
-    // 有的客户端自己维护这份文件（Claude Code 会缓存并回写 ~/.claude.json）。
-    // 有 CLI 时用它做一次只读确认，除了状态行不产生任何副作用。
-    if (client.verifyCli && which(client.verifyCli)) {
-      const probe = spawnSync(client.verifyCli, ['mcp', 'get', ENTRY_NAME], {
-        encoding: 'utf8', shell: IS_WIN, windowsHide: true,
-      });
-      const registered = probe.status === 0;
-      base.summary += registered
-        ? ' (confirmed by ' + client.verifyCli + ' mcp get)'
-        : ' (note: ' + client.verifyCli + ' mcp get does not see it yet; restart the client)';
-    }
-    return base;
   } catch (e) {
     if (originalMode !== null) {
       try { chmodSync(plan.path, originalMode); } catch { /* 尽力而为 */ }

package/src/config.mjs

@@ -5,7 +5,7 @@
  * 因为本服务是被 Codex/Claude 以未知环境拉起的。
  */
 
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,6 +13,15 @@ import { fileURLToPath } from 'node:url';
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const PKG_ROOT = join(HERE, '..');
 
+/** 包版本（与 package.json 单一来源；ACP clientInfo 也用它，避免硬编码漂移）。 */
+export const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
+
 /** 相对 DSH 包入口的固定尾巴。 */
 const DSH_ENTRY = join('@deepseek-ai', 'dsh', 'lib', 'bin.js');
 
@@ -105,9 +114,45 @@ export const ROUTE_SOURCE_PROFILE = (() => {
   return v === undefined || String(v).trim() === '' ? null : String(v).trim();
 })();
 
-/** 会话注册表（跨 MCP 服务重启存活）。 */
+/**
+ * 会话注册表（跨 MCP 服务重启存活）。
+ *
+ * ★ 默认放在 **$DSH_HOME/.dsh-any-agent/**，不再放在包安装目录里。
+ *   全局安装到只读位置（sudo / Program Files / 只读挂载）时，包目录不可写，
+ *   注册表、哨兵、锁登记会全部静默失败 —— 调用方等哨兵会永远等不到。
+ *   DSH_HOME 本身就是用户目录，天然可写，且与 DSH 自己的数据放在一起。
+ *
+ * 兼容：旧版本的 `<包目录>/.state/conversations.json` 会在首次启动时复制过来
+ * （只在没有显式设置 DSH_MCP_STATE 时做，见 LEGACY_STATE_FILE / USING_DEFAULT_STATE）。
+ */
+const DEFAULT_STATE_DIR = join(DSH_HOME, '.dsh-any-agent');
 export const STATE_FILE =
-  process.env.DSH_MCP_STATE ?? join(PKG_ROOT, '.state', 'conversations.json');
+  process.env.DSH_MCP_STATE ?? join(DEFAULT_STATE_DIR, 'conversations.json');
+/** 旧默认位置；仅用于一次性迁移。 */
+export const LEGACY_STATE_FILE = join(PKG_ROOT, '.state', 'conversations.json');
+/** 是否仍在使用默认状态路径（显式设置 DSH_MCP_STATE 时不做自动迁移）。 */
+export const USING_DEFAULT_STATE = !process.env.DSH_MCP_STATE;
+
+/**
+ * 确认一个目录可写；不可写就抛出可直接展示给用户的错误。
+ *
+ * 在 Hub.load() 启动时调用：宁可服务明确起不来，也不要"看起来正常、
+ * 哨兵永远不出现、锁也无法归因"的静默降级。
+ */
+export function assertWritableDir(dir, label = '目录') {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const probe = join(dir, `.write-probe-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    writeFileSync(probe, 'ok', 'utf8');
+    rmSync(probe, { force: true });
+  } catch (e) {
+    throw new Error(
+      `${label}不可写: ${dir}\n` +
+        `  ${e.message}\n` +
+        '  请用 DSH_MCP_STATE / DSH_MCP_RUNS_DIR / DSH_MCP_LOCKS_DIR 指向可写目录。',
+    );
+  }
+}
 
 /**
  * 异步派活"完成哨兵"文件的根目录。每个 run 终止时在这里写一个独立小文件，
@@ -134,9 +179,9 @@ export const SENTINEL_INCLUDE_REASONING = process.env.DSH_MCP_SENTINEL_INCLUDE_R
  *
  * 为什么要清理：哨兵内含完整正文，长期不清理会无声地堆积占用磁盘。
  */
-export const SENTINEL_TTL_MS = Number(
-  process.env.DSH_MCP_SENTINEL_TTL_MS ?? 7 * 24 * 60 * 60 * 1000,
-);
+const rawSentinelTtl = numEnv('DSH_MCP_SENTINEL_TTL_MS', 7 * 24 * 60 * 60 * 1000);
+/** ★ 负数/NaN 一律当作 0（关闭清理），绝不能把 cutoff 推到未来删光全部哨兵。 */
+export const SENTINEL_TTL_MS = Number.isFinite(rawSentinelTtl) && rawSentinelTtl > 0 ? rawSentinelTtl : 0;
 
 /**
  * 把 Windows 路径转成 Bash / MSYS 形式（`D:\a\b` → `/d/a/b`），非 Windows 原样返回。
@@ -234,7 +279,10 @@ export const LIST_PROBE_TTL_MS = numEnv('DSH_MCP_LIST_PROBE_TTL_MS', 10_000);
 
 /** 权限档 → 该档下的默认审批策略。 */
 export const PERMISSION_TIERS = ['read-only', 'workspace-write', 'danger-full-access'];
-export const DEFAULT_PERMISSION = process.env.DSH_MCP_PERMISSION ?? 'danger-full-access';
+/** 空串/非法值一律回落到 danger-full-access（保持旧默认），而不是让 Hub.create 每次都失败。 */
+export const DEFAULT_PERMISSION = PERMISSION_TIERS.includes(process.env.DSH_MCP_PERMISSION)
+  ? process.env.DSH_MCP_PERMISSION
+  : 'danger-full-access';
 
 /**
  * 审批处理策略：
@@ -260,7 +308,10 @@ export const DEFAULT_REASONING = 'hide';
  * ACP 默认值是空串（= Provider default），不是我们想要的；默认显式设成 max。
  */
 export const REASONING_EFFORTS = ['default', 'low', 'medium', 'high', 'xhigh', 'max'];
-export const DEFAULT_REASONING_EFFORT = process.env.DSH_MCP_REASONING_EFFORT ?? 'max';
+/** 空串/非法值回落到 max；否则 Hub.create 的合法性校验会让**所有** dsh_start 失败。 */
+export const DEFAULT_REASONING_EFFORT = REASONING_EFFORTS.includes(process.env.DSH_MCP_REASONING_EFFORT)
+  ? process.env.DSH_MCP_REASONING_EFFORT
+  : 'max';
 
 /**
  * 工作区登记模式：