dsh-soul 0.7.2 → 0.9.0

package/index.mjs

@@ -29,13 +29,71 @@ import {
   LANGUAGE_VALUES,
   PERSONA_FIELDS,
   PERSONA_NAME_MAX,
+  PROMPT_INPUT_FIELDS,
   migrateConfig,
   sanitizeConfig,
   sanitizePersonaName
 } from './lib/config.mjs'
+import {
+  bindingsPathFor,
+  bindingRefusal,
+  compareKey,
+  MAX_BINDINGS,
+  MAX_PATH_LENGTH,
+  normalizeBindingEntry,
+  normalizeDirPath,
+  readBindingsFile,
+  resolveDirIdentity,
+  resolvePersonaForCwd,
+  writeBindingsFile
+} from './lib/bindings.mjs'
+import {
+  MAX_SESSION_ID_LENGTH,
+  ORPHAN_GRACE_MS,
+  SESSION_DIR_NAME,
+  SESSION_ENVELOPE_ONLY_FIELDS,
+  SESSION_OVERRIDE_FIELDS,
+  SESSION_SCOPE_VERSION,
+  createSessionScopeDoc,
+  decideSessionScopeFate,
+  isSessionId,
+  listSessionScopes,
+  quarantineSessionScope,
+  readSessionScope,
+  sanitizeSessionOverride,
+  sessionScopeDirFor,
+  sessionScopePathFor,
+  writeSessionScope
+} from './lib/session-scope.mjs'
+import {
+  MAX_WORKSPACE_SCOPES,
+  WORKSPACE_PERSONA_REF,
+  WORKSPACE_SCOPE_VERSION,
+  mergeWorkspaceOverride,
+  resolveWorkspaceOverride,
+  sanitizeWorkspaceScopes,
+  validateWorkspaceBinding
+} from './lib/workspace-scope.mjs'
 import { createInjectionSource } from './lib/injection.mjs'
-import { isBuiltinPersona, builtinPersonaNames, mergePersonas, personaMatches, resolvePersona, declaredPersonaKeys } from './lib/personas.mjs'
+import {
+  findDuplicatePersonas, isBuiltinPersona, builtinPersonaNames, mergePersonas, personaMatches, resolvePersona, declaredPersonaKeys } from './lib/personas.mjs'
 import { configWriteRefusal, describeConfigFailure, moveAsideConfigFile, readConfigFile, writeConfigFile } from './lib/store.mjs'
+import {
+  buildHistoryEntry,
+  clearHistoryFile,
+  createEntryId,
+  diffFields,
+  diffPersonas,
+  findEntryIndex,
+  hashConfig,
+  historyPathFor,
+  MAX_READ_LINES,
+  planRollback,
+  randomSuffix,
+  readHistoryFile,
+  recordHistoryEntry,
+  toHistoryResponse
+} from './lib/history.mjs'
 
 const name = 'soul'
 
@@ -44,6 +102,19 @@ function configPath() {
   return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'soul-config.json')
 }
 
+// 变更记录的落盘路径：配置文件的**兄弟文件**（soul-config.json → soul-config.history.jsonl）。
+// 与配置同目录而不塞进配置里，理由见 docs/DESIGN-audit-rollback.md §4.1。
+function historyPath() {
+  return historyPathFor(configPath())
+}
+
+// 最近一次「变更记录没能记下来」的原因（记成功则清空）。
+//
+// 审计失败绝不能连带配置写失败 —— 那会把「记不下来」升级成「改不了」，
+// 而配置写入是这个插件的核心功能。但也不能装作没发生：原因经
+// GET /api/soul/history 的 warning 字段回传，设置页会原样显示。
+let lastHistoryFailure = null
+
 // 版本号：唯一来源是 package.json。
 //
 // 刻意**不**在这里再写一个常量 —— 需要手工同步的版本号已经有三处
@@ -311,6 +382,36 @@ const MAX_BODY_BYTES = 64 * 1024
 // 内存中的配置缓存
 let configCache = null
 
+// 配置的**单调修订号**：每次配置真的被替换（读盘成功、写入成功、重置）+1。
+//
+// 为什么需要它：system prompt 的 section.text 是宿主**同步**调用的，每次装配都读
+// `configCache` —— 而 configCache 由写队列整体替换。若一次装配过程中间发生了写入，
+// 同一轮里 section 多次求值时可能拿到**两个不同版本**的配置，症状正是「System Prompt
+// Updated 已出现、模型却仍用旧昵称」这一类难以复现的问题。
+//
+// 有了修订号，装配侧可以：
+//   ① 先取一次快照再求值（见 snapshotConfig），保证一轮只用一份配置；
+//   ② 把「这一轮实际用了哪一版」记进诊断状态，事后能回答「进模型的是哪一版」。
+//
+// 刻意**不**做「装配期间禁止写入」：装配是纯读，写入走队列，加锁只会让保存变慢。
+// 单调号足以定位，不需要互斥。
+let configRevision = 0
+
+function bumpConfigRevision() {
+  configRevision += 1
+}
+
+// 取当前配置的不可变快照。装配路径上**只调用一次**，后续全部基于它。
+//
+// 返回的 revision 与 value 是同一时刻的配对：先读 revision 再读 value（或反过来）
+// 在单线程里等价，因为两者之间没有 await —— 一旦有 await，就又会读到两个版本。
+function snapshotConfig() {
+  return {
+    revision: configRevision,
+    value: configCache || DEFAULT_CONFIG
+  }
+}
+
 // 磁盘上的配置存在但不可用（读不出来 / 不是合法 JSON）时的记录。
 // 置位后 saveConfig 会拒绝写入，避免把损坏的配置静默清空成默认值。
 let configLoadFailure = null
@@ -336,6 +437,7 @@ async function loadConfig() {
   }
 
   configCache = exists ? migrateConfig(value) : { ...DEFAULT_CONFIG }
+  bumpConfigRevision()
   return configCache
 }
 
@@ -354,6 +456,7 @@ async function saveConfig(config) {
   delete clean.examples
   await writeConfigFile(configPath(), clean)
   configCache = clean
+  bumpConfigRevision()
   return clean
 }
 
@@ -371,26 +474,115 @@ function enqueueConfigWrite(task) {
   return run
 }
 
-// 纯客户端外观字段：变更它们不需要刷新系统提示词，也不需要向活动会话注入快照；
+// 不影响提示词的字段：变更它们不需要刷新系统提示词，也不需要向活动会话注入快照；
 // 但它们仍是实际配置变更，必须计入 changed（供调用方判断「已保存 / 无变化」并驱动前端 dirty）。
-const NON_PROMPT_FIELDS = new Set(['trailEnabled', 'trailColor', 'trailSpeed', 'trailWidth'])
+//
+// 由 DEFAULT_CONFIG 减去 PROMPT_INPUT_FIELDS **推导**，而不是手写清单。
+// 手写清单的代价已经发生过两次：trail* 四项之外，requireToolConfirmation 与
+// historyMaxEntries 都曾被漏在外面 —— 后果是改一次「保留条数」会重新注册 section
+// 并向所有活动会话注入一条配置更新消息，用户看到的是「我只调了个容量，Agent 却被
+// 通知了一遍配置变了」。这类「漏登记」不会报错，只会安静地多注入。
+//
+// 推导的安全前提是 compilePrompt 只读 PROMPT_INPUT_FIELDS 里的字段，该前提由
+// scripts/verify-config.mjs 的「编译源码读取的每个 config.X 都必须已登记」钉住。
+//
+// 未知键（不在 DEFAULT_CONFIG 里）会落在「影响提示词」一侧 —— 方向是安全的：
+// 最坏是多重启一次提示词，而不是改了不生效。
+const NON_PROMPT_FIELDS = new Set(
+  Object.keys(DEFAULT_CONFIG).filter((key) => !PROMPT_INPUT_FIELDS.includes(key))
+)
 
 // 在写队列中执行一次配置更新：mutate 收到当前配置的浅拷贝，返回新配置对象。
 // 注意 mutate 必须在队列任务内完成全部读取与合并，不要在队列外提前读取配置。
 // 返回 { config, changed, promptChanged }：
 //   - changed：实际发生变化的字段名数组（不含 personas 预设库），供调用方判断有无变更
 //   - promptChanged：changed 中会影响 Agent 行为的子集；为空时应跳过提示词刷新与会话注入
-async function commitConfig(mutate) {
+//
+// 第二参数 source 是**变更记录的归属**，形如 { source, action }：source 是渠道
+// （web / command / tool / service / persona / rollback / restorePersona），
+// action 是动作（save / set / use / …）。两个都是白名单枚举，写进条目与读回条目时各校验一次。
+//
+// 为什么必须由调用方显式给出：同一次「改了 style」可能是网页保存、斜杠命令、Agent 工具
+// 或其它插件调用，事后从配置差异里是**推不出来**的。审计的价值有一半在于回答
+// 「是谁改的」—— 默认值会让这半个价值静默消失，所以这里刻意不给默认值。
+async function commitConfig(mutate, source) {
   return enqueueConfigWrite(async () => {
     const current = await loadConfig()
-    const next = mutate({ ...current })
+    // mutate 允许返回 Promise：撤销要在「读记录 → 规划 → 写配置」之间保持原子，
+    // 而记录必须在**队列内**读。放在队列外读会有一个窗口——两次撤销并发时，
+    // 后者的规划建立在已被前者改过的配置上，指纹校验会给出看起来像「数据损坏」的
+    // diverged，排查方向完全跑偏。
+    const next = await mutate({ ...current })
     const changed = diffKeys(current, next)
     const promptChanged = changed.filter((key) => !NON_PROMPT_FIELDS.has(key))
     const config = await saveConfig(next)
-    return { config, changed, promptChanged }
+
+    // 差分必须在 saveConfig **之后**、且以它返回的配置为基准：saveConfig 会剔除
+    // tone / presets / examples 三个废弃字段，拿 mutate 的产物去比会把它们误报成变更。
+    const entry = await auditCommit(current, config, source, config.historyMaxEntries)
+
+    return { config, changed, promptChanged, entry }
   })
 }
 
+// 路由内主动拒绝：从队列任务里抛出即可中止本次提交（不写盘），由 handler 按状态码回话。
+// 不用返回一个「什么都没改」的配置来收场 —— 那会照样重写一次配置文件，
+// 让一次失败的操作在磁盘上留下痕迹。
+function httpError(status, message) {
+  const err = new Error(message)
+  err.httpStatus = status
+  return err
+}
+
+// 把一次成功的提交记进变更记录。
+//
+// 时机与失败处理（docs/DESIGN-audit-rollback.md §5）：调用点已在 saveConfig 之后，
+// 所以「配置写失败却留下记录」在结构上不可能。反过来「配置已写、记录没写成」是可能的
+// （磁盘只读、记录文件被占用）—— 此时把原因记进 lastHistoryFailure 并**继续返回成功**，
+// 因为配置确实已经改了。
+async function auditCommit(current, config, source, maxEntries) {
+  try {
+    const fields = diffFields(current, config)
+    const personas = diffPersonas(current.personas, config.personas)
+
+    // 「什么都没变」必须在构造条目**之前**判掉，不能靠 buildHistoryEntry 返回 null 来表达。
+    // 后者把两种情况混成了同一个返回值：真的没变，和条目因为 shape 不对被拒
+    // （例如某个调用点漏标 source）—— 后者是代码缺陷，混进来就会变成
+    // 「配置改了、记录里没有、也没有任何告警」。这条判据把缺陷从静默变响亮。
+    const changedAny =
+      Object.keys(fields.after).length > 0 ||
+      personas.added.length > 0 || personas.updated.length > 0 || personas.removed.length > 0
+    if (!changedAny) {
+      lastHistoryFailure = null
+      return null
+    }
+
+    const entry = buildHistoryEntry({
+      id: createEntryId(Date.now(), randomSuffix()),
+      at: new Date().toISOString(),
+      source: source && source.source,
+      action: source && source.action,
+      label: source && source.label,
+      configHash: hashConfig(config),
+      before: fields.before,
+      after: fields.after,
+      personas
+    })
+    if (!entry) {
+      // 有变化却构造不出条目 ⇒ 一定是调用点的 source/action 没标或标错。
+      // 报出来而不是当作「无变化」跳过：审计缺一条而没人知道，比留一条错的更糟。
+      lastHistoryFailure = `变更记录条目构造失败（source=${JSON.stringify(source)}），本次改动未被记录`
+      return null
+    }
+    await recordHistoryEntry(historyPath(), entry, maxEntries)
+    lastHistoryFailure = null
+    return entry
+  } catch (err) {
+    lastHistoryFailure = String((err && err.message) || err)
+    return null
+  }
+}
+
 // 比较两份配置的差异字段名（浅比较；soul 配置为扁平对象）。
 // personas（人设预设库）不属于活动配置：库的增删改不应触发提示词刷新与会话注入。
 function diffKeys(a, b) {
@@ -420,13 +612,16 @@ function defaultConfigPreservingPersonas(current) {
 //
 // 复用 commitConfig 的「读—改—写」，不另写一份；写入失败时恢复失败标记，
 // 避免把「文件仍然不可用」误报成正常状态。
-async function resetConfigWithEscape() {
+//
+// source 由调用方给（web 重置 / 斜杠命令重置 / 其它插件调用），穿透给 commitConfig
+// 用于变更记录 —— 三个入口都是「重置」，但来源不同，记录里要分得开。
+async function resetConfigWithEscape(source) {
   const failure = configLoadFailure
   const backupPath = failure ? await moveAsideConfigFile(configPath()) : null
   if (failure) configLoadFailure = null
 
   try {
-    const result = await commitConfig((current) => defaultConfigPreservingPersonas(current))
+    const result = await commitConfig((current) => defaultConfigPreservingPersonas(current), source)
     return { ...result, backupPath }
   } catch (err) {
     if (failure) configLoadFailure = failure
@@ -522,7 +717,9 @@ const deliveryState = {
   delivered: 0,            // 最近一次成功注入的会话数
   failed: 0,               // 最近一次注入抛错的会话数
   injectionProblem: null,  // 未能如实送达的原因；正常为 null
-  sectionRegisteredAt: null // section 最近一次注册成功的时间（ISO）
+  sectionRegisteredAt: null, // section 最近一次注册成功的时间（ISO）
+  lastAssembledRevision: null, // 最近一次装配实际使用的配置修订号（排查「改了没生效」用）
+  lastAssembledScope: null // 最近一次装配用的是哪一层：'workspace' | 'cwd'
 }
 
 // 同一原因只告一次警，避免每次保存都刷屏；一旦恢复正常则清掉记录，
@@ -587,14 +784,23 @@ function injectPromptToAllAgents(ctx, config) {
   }
 
   const T = promptTextOf(config)
-  const prompt = compilePrompt(config)
-  const snapshotText = prompt || T.injectDisabled
 
   let delivered = 0
   let failed = 0
   let lastError = null
 
   for (const agent of listed) {
+    // **每个会话各自编译**，不能共用一份文本。
+    //
+    // 工作区绑定让「配置」不再是全局唯一的：A 项目会话该拿到「资深架构师」，B 项目会话
+    // 该拿到「极简主义者」。若在这里算一份全局文本发给所有人，B 项目会收到 A 的人设 ——
+    // 这比不注入更糟（不注入时它至少还是全局配置，与用户以为的一致）。
+    //
+    // 拿不到 cwd（会话头无该字段）时 configForCwd 返回原配置，行为与绑定功能上线前一致。
+    const perAgent = configForCwd(config, cwdOfAgent(agent)).config
+    const prompt = compilePrompt(perAgent)
+    const snapshotText = prompt || T.injectDisabled
+
     try {
       agent.inject(createUserMessage({
         content: [{
@@ -643,6 +849,381 @@ function refreshPromptAndInject(ctx, config) {
   injectPromptToAllAgents(ctx, config)
 }
 
+// ==================== 工作区绑定：按目录解析人设 ====================
+//
+// 三层解析（docs/DESIGN-persona-scope.md §5）：会话显式覆盖 → 目录绑定（最长前缀）→ 全局配置。
+// 0.8.1-b 落地的是中间那层；会话覆盖（0.8.1-c/d）尚未接入，接入点见 resolveForCwd 的注释。
+//
+// 为什么绑定表要单独缓存而不是每次读盘：本节的两个消费者都在**每一轮装配**上 ——
+// system prompt section 的 text provider 每轮都被调用一次，活动会话注入每次保存各一次。
+// 读盘 + 200 次 realpath 放进这条路径是不可接受的，所以绑定表在加载时规范化一次。
+
+// 绑定文件路径（configPath() 的兄弟文件）。
+function bindingsPath() {
+  return bindingsPathFor(configPath())
+}
+
+// 绑定表读数。null = 还没读过（与「读过了、确实是空表」必须分得开，
+// 后者意味着「用户一条都没绑」，前者意味着「还没问过磁盘」）。
+let bindingsCache = null
+
+// 最近一次绑定加载失败 / 有坏条目的说明（无问题为 null）。
+let bindingsLoadFailure = null
+
+// 命中判定的比较表。
+//
+// 这里有两个键集合，都指向同一条绑定：
+//   · **展示键**：绑定表里原样存着的形式，UI 与用户看到的就是它；
+//   · **身份键**：`realpath` 解析后的形式（解掉符号链接 / Junction；Windows 上还会
+//     规范化盘符大小写）。
+//
+// 为什么要两个都进比较表 —— 两边各自可能缺席一次解析：
+//   · 会话 cwd 由 Node 的 `process.cwd()` 提供（`GetCurrentDirectory` 返回的是**规范**
+//     路径），而绑定目录是用户在选择器里点出来的，很可能是 Junction 路径。
+//     典型失配：cwd = `D:\真实目录`、绑定键 = `D:\junction入口`。
+//   · 反过来，用户手工粘贴的路径可能本就是规范路径，而会话 cwd 落在 Junction 里。
+// 两个键都留着，任一侧成立即命中；`bindingsDisplayOf` 负责把命中结果翻译回展示键，
+// 因为用户不认得 realpath 吐出来的那个名字。
+//
+// **不对 cwd 做 realpath**：text provider 必须是**同步**的（见 registerSystemPrompt），
+// 而 realpath 是异步 I/O。把身份解析全部放在**键**侧，这个约束就消失了 ——
+// 键在加载时算一次，之后每轮装配都只是字符串比较。
+let bindingsCompareTable = null
+
+// 身份键 → 展示键（仅当两者不同时才有一条）。
+let bindingsDisplayOf = null
+
+// 解析绑定表：读盘 + 为每条键算出身份形态。
+//
+// 失败时**以空表继续**并把原因记在 bindingsLoadFailure 上，绝不抛错：
+// 绑定是可选增强，读不出来不该让整个插件的装配流程崩掉（与 loadConfig 的策略不同，
+// 因为配置是用户唯一的数据副本，而绑定不是）。
+//
+// 失败时**不写 bindingsCache**，与 loadConfig 同款：用户把文件改对之后，下一次
+// 加载（绑定路由写完表之后总会重新加载）就能自动恢复，不必重启 DSH。
+// 此时比较表被清成空表 —— 宁可暂时不生效，也不能拿上一次的旧表继续命中。
+async function loadBindings() {
+  const filePath = bindingsPath()
+  const { bindings, dropped, failure } = await readBindingsFile(filePath)
+  bindingsLoadFailure = failure || (dropped.length > 0 ? `${dropped.length} 条绑定因格式问题被忽略。` : null)
+
+  if (failure) {
+    bindingsCompareTable = {}
+    bindingsDisplayOf = new Map()
+    return { bindings: {}, dropped, failure, filePath }
+  }
+
+  // 计算身份键。并发发起（最多 MAX_BINDINGS=200 条，realpath 很轻），
+  // 但 resolveDirIdentity 自身绝不抛错，所以这里不需要 per-item 的 try/catch。
+  const compareTable = { ...bindings }
+  const displayOf = new Map()
+  const keys = Object.keys(bindings)
+  const identities = await Promise.all(keys.map(dir => resolveDirIdentity(dir)))
+
+  for (let i = 0; i < keys.length; i++) {
+    const dir = keys[i]
+    const identity = identities[i]
+    // 只有真的不同才加别键：同一条绑定占两个键位会让 shadowed 出现重复项。
+    if (!identity || compareKey(identity) === compareKey(dir)) continue
+    // 身份键撞上另一条展示键时**不覆盖** —— 展示键是用户亲手写的那个，
+    // 优先级更高；被挡住的身份键只是少一条别名，判定方向安全。
+    if (hasOwn(compareTable, identity)) continue
+    compareTable[identity] = bindings[dir]
+    displayOf.set(identity, dir)
+  }
+
+  bindingsCompareTable = compareTable
+  bindingsDisplayOf = displayOf
+  bindingsCache = { bindings, dropped, failure: null, filePath }
+  return bindingsCache
+}
+
+// 按目录解析该用什么人设（三层解析的「目录层」）。
+//
+// 返回 null 表示没有可用绑定 ⇒ 调用方回落全局配置（这是绝大多数用户的常态）。
+// 返回对象时：
+//   · dir / persona —— 真正生效的那条绑定；
+//   · shadowed —— 命中了、但人设已不存在的更具体绑定（不生效，但必须能说出来）。
+//
+// 本函数是**同步**的：它每轮装配都被调用，且 text provider 不允许是异步的。
+// 因此读盘只能发生在装配之外（apply() 启动时、绑定路由写完之后），见 ensureBindings。
+async function ensureBindings() {
+  if (!bindingsCache) await loadBindings()
+  return bindingsCache
+}
+
+function resolveBindingForCwd(cwd, userPersonas) {
+  if (!bindingsCompareTable || !bindingsDisplayOf) return null
+  const normalized = normalizeDirPath(cwd)
+  if (!normalized) return null
+
+  const resolved = resolvePersonaForCwd(normalized, bindingsCompareTable, userPersonas)
+  if (!resolved) return null
+
+  // 命中身份键时回报展示键（用户认得的是他自己写的那个名字）。
+  const display = dir => (bindingsDisplayOf.get(dir) || dir)
+  const seen = new Set()
+  const shadowed = []
+  for (const item of resolved.shadowed) {
+    const dir = display(item.dir)
+    // 同一条绑定的展示键与身份键可能都命中，去重后 UI 才不会把一条失效绑定画两遍。
+    if (seen.has(dir)) continue
+    seen.add(dir)
+    shadowed.push({ ...item, dir })
+  }
+
+  return { dir: display(resolved.dir), persona: resolved.persona, shadowed }
+}
+
+// ==================== 三级作用域：Global → Workspace → Session ====================
+//
+// 解析链（docs/DESIGN-config-scope.md §2.2）：
+//
+//   workspaceId（索引命中） → 工作区覆盖 → 部分覆盖全局
+//        ↓ 索引未命中（服务重启 / 新会话 / 索引空）
+//   cwd 前缀匹配（lib/bindings.mjs 既有能力） → 目录绑定 → 部分覆盖全局
+//        ↓ 都没有
+//   Global
+//
+// **失败方向必须安全**：任何一环不可用，只能在「更精确」与「更宽松」之间移动，
+// 不能变成「错误的人设」。
+
+// sessionId → workspaceId 的**只读快照**。
+//
+// 为什么是快照而不是"每次问宿主"：`systemPrompt.section.text` 是宿主**同步**调用的，
+// 里面不能有 await、也不能做线性扫描（每次装配 × 每个工作区 × 每个 sessionIds getter）。
+// 所以索引在装配路径**之外**维护，装配时只查表。
+//
+// 键与值都用 String：宿主用品牌类型（WorkspaceId / SessionId），把它们当字符串比较
+// 是唯一稳定做法（品牌类型在运行时就是字符串，但对象比较会因代理包装而失配）。
+let sessionWorkspaceIndex = new Map()
+
+// 索引最后一次成功重建的时间（ISO）。诊断用：排查「工作区绑定为什么没生效」时，
+// 第一个要看的就是索引有没有建起来。
+let workspaceIndexBuiltAt = null
+
+// 重建索引。**同步且不做 I/O** —— workspaceRegistry.list() 是内存投影。
+//
+// `sessionIds` 是 getter，每次访问都会过滤一遍（宿主内部按 candidateMatches 校验），
+// 因此这里只遍历一次并把结果拍平成 Map，绝不把这个 getter 存下来反复问。
+function rebuildWorkspaceIndex(ctx) {
+  const registry = ctx.get('workspaceRegistry')
+  if (!registry || typeof registry.list !== 'function') {
+    // 服务缺席不是错误：没有它就只能走 cwd 回退，而那正是 0.8.1 的语义。
+    return false
+  }
+
+  let listed
+  try {
+    listed = registry.list()
+  } catch {
+    return false
+  }
+
+  const next = new Map()
+  for (const workspace of Array.isArray(listed) ? listed : []) {
+    const id = workspace && workspace.id !== undefined ? String(workspace.id) : ''
+    if (id === '') continue
+    let sessionIds
+    try {
+      sessionIds = workspace.sessionIds
+    } catch {
+      // 单个工作区的 getter 抛错不该让整张索引失败（宿主注释：候选会话可能已被移出）
+      continue
+    }
+    for (const sessionId of Array.isArray(sessionIds) ? sessionIds : []) {
+      next.set(String(sessionId), id)
+    }
+  }
+
+  sessionWorkspaceIndex = next
+  workspaceIndexBuiltAt = new Date().toISOString()
+  return true
+}
+
+// 从装配上下文里取 sessionId。
+//
+// `agent.id` **就是** sessionId —— 宿主注册 typert lookup 时用的正是
+// `wireTypeSymbol: "@deepseek-ai/dsh-session/types#SessionId"`，
+// `resolve: (sessionId) => this.get(sessionId)`。
+//
+// 诊断装配时 agent 缺席，返回 null。
+function sessionIdOfAgent(agent) {
+  const id = agent?.id
+  if (typeof id === 'string' && id.trim() !== '') return id
+  if (typeof id === 'number') return String(id)
+  return null
+}
+
+// 把「全局配置 + 一次作用域解析结果」合成为该会话实际生效的配置。
+//
+// 三层顺序固定：先工作区（或目录），再会话覆盖。后者能盖前者 —— 这正是
+// 「本次会话临时改用教学模式」的语义。
+//
+// 用预设的**部分覆盖**语义（与 /api/soul/personas/use 同一条规则）：只覆盖条目实际
+// 声明过的字段，未声明的保持上层值。这条复用不是巧合 —— 用户在设置页点「使用」
+// 一个预设时看到的效果，必须与他在该目录里自动拿到的效果**逐字段一致**，
+// 否则「绑定生效了吗」将无法用任何已有操作来验证。
+//
+// `enabled` 刻意**不在**任何覆盖范围内：全局总开关始终说话。
+//
+// `sessionOverride` 由调用方从**内存缓存**取（见 sessionOverrides）。这里不读盘：
+// 装配是同步的，读盘会把 Promise 塞进提示词。
+function configForScope(base, cwd, workspaceId, sessionOverride) {
+  // ① 工作区层：workspaceId 优先，cwd 回退。
+  const scopes = workspaceScopesOf(base)
+  const workspaceOverride = workspaceId ? resolveWorkspaceOverride(workspaceId, scopes) : null
+  let merged = base
+  let source = 'global'
+  let binding = null
+
+  if (workspaceOverride) {
+    merged = mergeWorkspaceOverride(base, workspaceOverride)
+    source = 'workspace'
+  } else {
+    // ② 目录回退（0.8.1 语义）：索引没命中时，目录仍是可信信息。
+    const resolved = resolveBindingForCwd(cwd, base.personas)
+    if (resolved) {
+      const persona = resolvePersona(resolved.persona, base.personas)
+      if (persona) {
+        const { patch } = sanitizeConfig(pickPersonaValues(persona))
+        merged = { ...base, ...patch }
+        source = 'directory'
+        binding = resolved
+      }
+    }
+  }
+
+  // ③ 会话层：最贴近用户当下意图，优先级最高。
+  //    它盖的是**字段**，不是整份配置 —— 只改 style 的会话覆盖，其余字段仍来自上层。
+  if (sessionOverride) {
+    merged = mergeSessionOverride(merged, sessionOverride)
+    source = 'session'
+  }
+
+  return { config: merged, source, workspaceId: workspaceId || null, binding }
+}
+
+// 兼容既有调用点：只按 cwd 解析（不含工作区层）。
+// 保留这个名字是因为 verify-*.mjs 与若干注释按它描述契约；新代码应直接用 configForScope。
+function configForCwd(base, cwd) {
+  const { config, binding } = configForScope(base, cwd, null, null)
+  return { config, binding }
+}
+
+// 读出配置里的工作区覆盖表（已校验过的形态）。
+function workspaceScopesOf(config) {
+  const raw = config && config.workspaces
+  if (!raw || typeof raw !== 'object') return {}
+  const { scopes } = sanitizeWorkspaceScopes(raw)
+  return scopes
+}
+
+// ==================== 会话级覆盖（0.9.0-c）====================
+//
+// 存储：`$DSH_HOME/soul-sessions/{sha256(sessionId)[:32]}.json`（与 soul-config.json 同级）。
+// 校验与回收状态机在 lib/session-scope.mjs；这里只负责**内存缓存**与合并。
+//
+// 为什么必须有缓存：装配路径是同步的（宿主 `section.text(context)` 同步调用），
+// 不能在里面 await 一次读盘。所以：
+//   · 缓存按需加载（首次遇到某个 sessionId 时排一个异步读盘）；
+//   · 读盘完成后写回缓存，下一轮装配即可命中；
+//   · 写入（用户改覆盖）时同步更新缓存，**不等**磁盘 —— 让「改完立刻生效」成立。
+//
+// 失效方向是安全的：缓存未命中 ⇒ 这一轮按上层配置（工作区/全局）走，
+// 最坏是"第一次生效慢一拍"，不会给出错误的人设。
+const sessionOverrides = new Map()   // sessionId → override（已校验）
+const sessionOverridesInFlight = new Set()
+// 读过的 sessionId（含"读过但确实没有覆盖"）：避免每轮都重新排一次读盘
+const sessionOverridesKnown = new Set()
+// sessionId → 用户实际点选的预设名（sidecar 里的 personaName）。
+//
+// 与 override 分开存：override 是**模型用的字段**，personaName 是**给人看的注解**。
+// 两者分开的好处是 —— 字段被手工改过、或多个预设字段相同时，
+// 界面仍能显示"你点的确实是这个"，而不是靠字段反查猜一个。
+const sessionPersonaNames = new Map()
+
+// 读出某个会话的覆盖（同步，只查缓存）。
+//
+// 未命中时排一次异步加载并返回 null —— 本轮按上层走，下一轮生效。
+function sessionOverridesOrNull(sessionId) {
+  if (sessionId === null) return null
+  if (sessionOverridesKnown.has(sessionId)) return sessionOverrides.get(sessionId) || null
+  // 首次遇到：排一次读盘。in-flight 集合防止同一会话在一轮里被排多次。
+  if (!sessionOverridesInFlight.has(sessionId)) {
+    sessionOverridesInFlight.add(sessionId)
+    void loadSessionOverride(sessionId).finally(() => {
+      sessionOverridesInFlight.delete(sessionId)
+    })
+  }
+  return null
+}
+
+// 读一个会话的 sidecar 进缓存。
+async function loadSessionOverride(sessionId) {
+  try {
+    const filePath = sessionScopePathFor(configPath(), sessionId)
+    const result = await readSessionScope(filePath, sessionId)
+    sessionOverridesKnown.add(sessionId)
+    if (result.override) sessionOverrides.set(sessionId, result.override)
+    else sessionOverrides.delete(sessionId)
+    // personaName 与 override 同一次读盘拿到 —— 不额外读一次磁盘。
+    if (result.personaName) sessionPersonaNames.set(sessionId, result.personaName)
+    else sessionPersonaNames.delete(sessionId)
+    return result.override
+  } catch {
+    // 读失败不记为"已知"：下次装配会重试（可能是临时权限问题）
+    return null
+  }
+}
+
+// 取某个会话"用户实际点选的预设名"（sidecar 里的 personaName）。
+//
+// 返回 null 有三种情况：没有 sidecar / 老版本 sidecar（没有这个字段）/
+// 读失败。调用方据此退回「按字段反查」—— 那条路不确定但可用。
+async function recordedSessionPersonaName(sessionId) {
+  const key = String(sessionId)
+  if (sessionPersonaNames.has(key)) return sessionPersonaNames.get(key)
+  // 缓存未命中：确保 sidecar 已被读过（loadSessionOverride 会填缓存）
+  await loadSessionOverride(sessionId)
+  return sessionPersonaNames.get(key) || null
+}
+
+// 清掉某个会话的缓存（写入后调用，或 GC 删文件后调用）。
+function forgetSessionOverride(sessionId) {
+  sessionOverrides.delete(sessionId)
+  sessionOverridesKnown.delete(sessionId)
+  sessionPersonaNames.delete(sessionId)
+}
+
+// 会话覆盖的合并：部分覆盖 + 白名单 + 包封字段保护。
+//
+// 与 mergeWorkspaceOverride 同一条语义（字段级、不整份替换），但两处独立实现 ——
+// 它们服务不同的数据来源，共享会让一处改动悄悄影响另一处。语义一致性由断言守住。
+function mergeSessionOverride(base, override) {
+  if (!override || typeof override !== 'object') return base
+  const patch = {}
+  for (const [key, value] of Object.entries(override)) {
+    if (SESSION_ENVELOPE_ONLY_FIELDS.includes(key)) continue
+    if (!SESSION_OVERRIDE_FIELDS.includes(key)) continue
+    patch[key] = value
+  }
+  if (Object.keys(patch).length === 0) return base
+  return { ...base, ...patch }
+}
+
+// 从装配上下文里取该会话的工作目录。
+//
+// 两个都必须容忍 undefined：
+//   · `ctx` —— 宿主在 diagnostics 装配时**不传 agent**（runtime-types.d.ts:14-19 的注释
+//     写明 `absent on diagnostics`）。此时回落全局配置，绝不抛错。
+//   · `cwd` —— 会话头里可能没有这个字段。取不到时任何绑定都不会命中，
+//     于是行为与「没有绑定功能」完全一致（失败方向安全）。
+function cwdOfAgent(agent) {
+  const cwd = agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd.trim() !== '' ? cwd : null
+}
+
 // ==================== HTTP 路由 ====================
 
 function registerRoutes(ctx) {
@@ -687,7 +1268,7 @@ function registerRoutes(ctx) {
             }
 
             // 写队列内「读—改—写」，只合并通过校验的字段（未知字段不落盘）
-            const { config: updated, changed, promptChanged } = await commitConfig(current => ({ ...current, ...patch }))
+            const { config: updated, changed, promptChanged } = await commitConfig(current => ({ ...current, ...patch }), { source: 'web', action: 'save' })
 
             // 仅影响 Agent 行为的字段变化才刷新提示词并注入会话；
             // 光轨等纯外观字段只更新配置，不向会话堆积注入快照
@@ -800,7 +1381,7 @@ function registerRoutes(ctx) {
           // 经由逃生口：配置损坏时这是设置页唯一还能成功的写操作。
           // backupPath 非 null 说明刚才确实丢弃了一份损坏的配置（已备份），
           // 客户端据此给出「备份在哪」的提示，而不是让用户以为数据凭空消失。
-          const { config, changed, promptChanged, backupPath } = await resetConfigWithEscape()
+          const { config, changed, promptChanged, backupPath } = await resetConfigWithEscape({ source: 'web', action: 'reset' })
 
           // 仅影响 Agent 行为的字段变化才刷新提示词并注入会话
           if (promptChanged.length > 0) {
@@ -852,7 +1433,18 @@ function registerRoutes(ctx) {
               // （不依赖任何缓存，见 scripts/verify-live-prompt.mjs）
               section: {
                 registered: deliveryState.sectionRegisteredAt !== null,
-                registeredAt: deliveryState.sectionRegisteredAt
+                registeredAt: deliveryState.sectionRegisteredAt,
+                // 当前内存里的配置修订号，以及最近一次装配实际用到的那个。
+                // 两者不相等是**正常**的（装配发生在写入之前）；但用户报告「改了没生效」
+                // 时，若 lastAssembledRevision 长期不前进，问题就锁定在装配没被触发，
+                // 而不是配置没写进去 —— 这正是过去只能靠猜的那一步。
+                configRevision,
+                lastAssembledRevision: deliveryState.lastAssembledRevision,
+                lastAssembledScope: deliveryState.lastAssembledScope,
+                // 工作区索引：有了它才能把 sessionId 换成 workspaceId。
+                // 为 null 表示从未重建成功 —— 此时一切解析都退化为 cwd 前缀匹配。
+                workspaceIndexBuiltAt,
+                workspaceIndexSize: sessionWorkspaceIndex.size
               },
               injection
             },
@@ -878,12 +1470,46 @@ let pendingPersonaProposal = null
 // 只遍历 PERSONA_FIELDS ⇒ **不含「关于你」（昵称 / 职业 / 介绍）**：预设是 Agent 的
 // 人格存档，不是使用者身份存档。切换预设不该把你的昵称职业一起换掉。
 // 输出语言在范围内（它决定 Agent 用什么语言作答）。
-function personaSnapshotOf(config) {
+//
+// draft（可选）：用户在设置页**改了但还没点保存**的草稿字段（0.9.0-r）。
+//
+// 为什么必须有这个参数：设置页表单是「本地草稿 + 保存才写回」的结构，而预设原先
+// 只快照**已保存的配置**。用户改完风格与自定义指令、没点「保存设置」直接点「存为预设」
+// 时，存下的是**旧值** —— 实测确认（存出来的预设还是上一个预设的内容）。
+// 传草稿后语义变成「存你眼前看到的这套」。
+//
+// 只有属于 PERSONA_FIELDS 的键会被采纳；「关于你」即使夹在草稿里也进不来
+// （第二道防线：预设永远不含使用者身份）。
+function personaSnapshotOf(config, draft = null) {
   const values = {}
-  for (const key of PERSONA_FIELDS) values[key] = config[key]
+  for (const key of PERSONA_FIELDS) {
+    values[key] = config[key]
+    // 草稿优先：字段存在且类型与正式配置一致才采纳（防脏数据）；
+    // 明确的空串是合法的草稿值（用户就是想清空自定义指令）。
+    if (draft && typeof draft === 'object' && key in draft && draft[key] !== undefined) {
+      const value = draft[key]
+      if (typeof value === typeof config[key] || config[key] === undefined) values[key] = value
+    }
+  }
   return values
 }
 
+// 保存预设前的**重复门禁**（0.9.0-q）。
+//
+// 为什么需要：预设是「部分覆盖」语义，两个内容相同的预设会让 ★ 归属产生歧义
+// （实测：自建预设与内置预设声明字段相同，点内置的「使用」后 ★ 标在自建的那个上
+// —— 配置本身没错，错的只是名字标注）。上轮的 activePersonaName 记忆机制已经能
+// 正确处理这种歧义，本门禁是**从源头减少重复条目**，不是修 ★ 的唯一手段。
+//
+// 判据见 lib/personas.mjs 的 samePersonaContent：声明集合必须一致 + 共同声明字段值相同。
+// 声明子集的预设**不算重复**（应用效果不同：它不动未声明字段）。
+//
+// 返回冲突的预设名（顿号连接）或 null。
+function duplicatePersonaConflict(candidateEntry, library, ignoreName = null) {
+  const dupes = findDuplicatePersonas(candidateEntry, library, ignoreName)
+  return dupes.length === 0 ? null : dupes.join('、')
+}
+
 // 从预设条目中挑出人设字段（忽略 updatedAt 等元数据与「关于你」）。
 // `if (key in persona)` 即「部分覆盖」语义：只应用条目**实际声明**的键，
 // 未声明的保持用户当前值；而遍历白名单本身则是第二道防线——即便磁盘上残留了
@@ -909,6 +1535,11 @@ function hasOwn(obj, key) {
 
 // 计算与当前活动配置匹配的预设名（多个命中时取名称排序最前）。
 // 匹配语义是「部分覆盖」而非全字段相等，理由见 lib/personas.mjs 的 personaMatches。
+//
+// ⚠️ 反查是**不确定**的：两个预设声明相同字段时（自建预设是内置预设的子集很常见），
+// 都会命中，然后按名称排序取首个 —— 实测 ★ 标在了没点的卡上。
+// 所以调用方应**优先用 config.activePersonaName**（用户实际点的名字，0.9.0-p），
+// 本函数只在没有记录（从没用过「使用预设」）或记录的预设已不存在时作兜底。
 function findActivePersonaName(config) {
   const view = mergePersonas(config.personas)
   for (const personaName of Object.keys(view).sort()) {
@@ -917,6 +1548,22 @@ function findActivePersonaName(config) {
   return null
 }
 
+// ★ 当前生效的预设名：优先用**记住的名字**，反查只作兜底。
+//
+// 三种情况退回反查：从没用过「使用预设」（activePersonaName 为 null）/
+// 记住的预设已被删除 / 记住的预设现在不再匹配（用户手改了特质 —— 此时按
+// 「改任何特质 ⇒ 不再属于该预设」的语义，★ 本来就该消失）。
+function resolveActivePersonaName(config) {
+  const recorded = typeof config.activePersonaName === 'string' && config.activePersonaName !== ''
+    ? config.activePersonaName
+    : null
+  if (recorded) {
+    const view = mergePersonas(config.personas)
+    if (view[recorded] && personaMatches(view[recorded], config)) return recorded
+  }
+  return findActivePersonaName(config)
+}
+
 // 应用一个预设条目：过白名单 → 写队列合并。
 //
 // **必须回报被丢弃的字段**：normalizePersonas 只按字段名过滤、不校验取值，所以磁盘上
@@ -928,10 +1575,25 @@ function findActivePersonaName(config) {
 // 语义选择：应用**合法部分**并如实回报被丢弃的字段，而不是整单拒绝 —— 后者会让一个
 // 只差一个字段的旧预设彻底不可用，代价更高；而「部分应用 + 明示」与 /api/soul/prompt/
 // preview 的 invalid 约定一致。
+//
+// 来源固定为 persona/use：两个调用入口（网页「使用」与 /soul use）是同一个动作，
+// 用户视角下「用了个预设」这件事本身比「从哪个入口点的」更重要，故不细分。
 async function applyPersonaEntry(ctx, entry) {
   const { patch, errors } = sanitizeConfig(pickPersonaValues(entry))
   const invalid = Object.keys(errors)
-  const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
+  // label 带上预设名：审计里「应用预设」这条记录光有字段差，缺「应用的是什么」——
+  // 用户问「昨晚我切到了哪个人设」时，字段差答不上来。
+  //
+  // 同时把**用户实际点的名字**写进配置（activePersonaName，0.9.0-p）：
+  // ★ 标记原先靠字段反查，两个预设声明相同字段时（自建预设是内置的子集很常见）
+  // 反查结果取决于名称排序 —— 实测 ★ 标在了没点的卡上。记名字把"猜"变成"知道"。
+  // 名字是注解不是人设字段（不进提示词），所以放在 patch 之外单独合并。
+  const personaName = entry && typeof entry.name === 'string' ? entry.name.trim() : ''
+  const namePatch = personaName ? { activePersonaName: personaName } : {}
+  const { config: updated, changed, promptChanged } = await commitConfig(
+    c => ({ ...c, ...patch, ...namePatch }),
+    { source: 'persona', action: 'use', label: personaName || undefined }
+  )
   if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
   // applied 是「通过校验的字段数」——与 changed（实际产生差异的字段）不同：
   // 全部非法时 applied 为 0，此时不能报「已应用」，也不能报「与当前配置一致」。
@@ -940,7 +1602,7 @@ async function applyPersonaEntry(ctx, entry) {
 
 // 预设库的对外视图（内置 + 用户）与当前命中项，供三个路由的响应复用。
 function personaLibrary(config) {
-  return { personas: mergePersonas(config.personas), activeName: findActivePersonaName(config) }
+  return { personas: mergePersonas(config.personas), activeName: resolveActivePersonaName(config) }
 }
 
 // 人设预设 HTTP 路由：列表 / 保存 / 使用 / 删除。
@@ -997,11 +1659,45 @@ function registerPersonaRoutes(ctx) {
             send(res, 400, { ok: false, error: `「${personaName}」是内置预设，请换一个名称` })
             return
           }
+          // 草稿字段（0.9.0-r）：用户在设置页改了但**还没点保存**的内容。
+          //
+          // 为什么要收它：设置页是「本地草稿 + 保存才写回」的结构，若预设只快照
+          // 已保存配置，用户改完风格/自定义指令后直接点「存为预设」，存下的是**旧值**
+          // —— 实测确认（存出来的预设仍是上一个预设的内容）。
+          //
+          // 只取人设字段（PERSONA_FIELDS）；「关于你」即使夹在草稿里也进不来。
+          const draft = (() => {
+            const raw = parsed.body && parsed.body.draft
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+            const picked = {}
+            for (const key of PERSONA_FIELDS) {
+              if (key in raw && raw[key] !== undefined) picked[key] = raw[key]
+            }
+            return Object.keys(picked).length > 0 ? picked : null
+          })()
+          // 重复门禁（0.9.0-q）：内容与已有预设完全相同则拒绝创建。
+          // 判据在 lib/personas.mjs 的 samePersonaContent —— 投影比较。
+          // ⚠️ 比对对象必须是**草稿构造的快照**（0.9.0-r）：否则用户改了草稿想存
+          // 新预设时，门禁看到的是旧配置 —— 会误判成"与某个内置重复"而拒绝。
+          // 「覆盖同名」时把同名条目排除在比对之外（那是更新，不是新增重复）。
+          {
+            const current = await loadConfig()
+            const candidate = personaSnapshotOf(current, draft)
+            const dupes = duplicatePersonaConflict(candidate, mergePersonas(current.personas), personaName)
+            if (dupes) {
+              send(res, 400, {
+                ok: false,
+                error: `已存在内容完全相同的预设「${dupes}」，请直接使用它，或先修改人设再保存`,
+                duplicates: dupes.split('、')
+              })
+              return
+            }
+          }
           const { config: updated } = await commitConfig((current) => {
             const personas = clonePersonas(current.personas)
-            personas[personaName] = { ...personaSnapshotOf(current), updatedAt: new Date().toISOString() }
+            personas[personaName] = { ...personaSnapshotOf(current, draft), updatedAt: new Date().toISOString() }
             return { ...current, personas }
-          })
+          }, { source: 'web', action: 'savePreset' })
           send(res, 200, { ok: true, ...personaLibrary(updated) })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
@@ -1080,7 +1776,7 @@ function registerPersonaRoutes(ctx) {
             const personas = clonePersonas(c.personas)
             delete personas[personaName]
             return { ...c, personas }
-          })
+          }, { source: 'web', action: 'deletePreset' })
           send(res, 200, { ok: true, ...personaLibrary(updated) })
         } catch (err) {
           send(res, 500, { ok: false, error: String(err.message || err) })
@@ -1129,91 +1825,1155 @@ function registerPersonaRoutes(ctx) {
   })
 }
 
-// ==================== 斜杠命令 ====================
+// ==================== 变更记录 ====================
 
-// 宿主端无 locale 服务（CommandInvocation 不携带 UI 语言，settings 中亦无语言字段），
-// 命令输出语言跟随 soul 配置的 language 字段，可在设置页切换。
-const COMMAND_MESSAGES = {
-  zh: {
-    showTitle: '🧠 个性化设置',
-    colon: '：',
-    statusLabel: '状态',
-    nicknameLabel: '昵称',
-    occupationLabel: '职业',
-    bioLabel: '介绍',
-    styleLabel: '风格语调',
-    styleNames: {
-      professional: '专业严谨',
-      casual: '轻松自然',
-      humorous: '幽默风趣',
-      roast: '吐槽达人',
-      efficient: '高效干练'
-    },
-    traitsLabel: '特质',
-    headingListsLabel: '标题和列表',
-    emojiLabel: '表情符号',
-    tablesLabel: '表格',
-    replyLengthLabel: '回复长度',
-    traitNames: {
-      default: '默认',
-      more: '增强',
-      less: '减弱'
-    },
-    replyLengthNames: {
-      concise: '简洁',
-      normal: '适中',
-      detailed: '详尽'
-    },
-    listSep: '，',
-    trailLabel: '输入框光轨',
-    trailLine: (status, color, speedName, widthName) => `${status}（${color} / ${speedName} / ${widthName}）`,
-    trailSpeedNames: {
-      slow: '慢',
-      normal: '中',
-      fast: '快'
-    },
-    trailWidthNames: {
-      thin: '细',
-      normal: '中',
-      thick: '粗'
-    },
-    instructionsLabel: '自定义指令',
-    enabled: '已启用',
-    disabled: '已禁用',
-    notSet: '未设置',
-    toolConfirmLabel: '确认模式',
-    onLabel: '开启',
-    offLabel: '关闭',
-    personasLabel: '人设预设',
-    // 提议是**内存态**（重启即失效）、也没有 TTL，所以必须让用户看到它是什么时候提出的，
-    // 否则一条陈旧提议会一直挂着而无法判断新鲜度（proposedAt 此前只写不读）。
-    pendingHint: (at) => `⚠ 有待确认的人设变更（提出于 ${at}）：/soul confirm 确认，/soul reject 拒绝`,
-    noPending: '没有待确认的人设变更',
-    confirmDone: (detail) => `✅ 已应用人设变更：${detail}`,
-    rejectDone: '✅ 已拒绝待确认的人设变更',
-    saveDone: (name) => `✅ 已保存预设「${name}」`,
-    // 内置预设（随插件发布、不落盘）：不可用同名保存，也不可删除
-    builtinName: '内置',
-    builtinSaveBlocked: (name) => `「${name}」是内置预设，请换一个名称`,
-    builtinDeleteBlocked: (name) => `「${name}」是内置预设，无法删除`,
-    useDone: (name) => `✅ 已应用预设「${name}」`,
-    useUnchanged: (name) => `ℹ 预设「${name}」与当前配置一致，无需变更`,
-    // 预设里部分字段的取值非法（历史值或手改）：合法字段照常应用，被跳过的必须说出来
-    usePartial: (name, fields) => `⚠ 预设「${name}」已部分应用，以下字段取值非法、已跳过：${fields}`,
-    useAllInvalid: (name, fields) => `✗ 预设「${name}」没有可应用的合法字段：${fields}`,
-    personaMissing: (name) => `预设「${name}」不存在`,
-    delDone: (name) => `✅ 已删除预设「${name}」`,
-    listTitle: '📋 人设预设',
-    listEmpty: '暂无人设预设，使用 /soul save <名称> 保存当前配置',
-    // 列表行报告预设实际覆盖的人格维度数量（取代 v0.7.1 起恒为空的「昵称」列）
-    listCovers: (n) => `覆盖 ${n} 项`,
-    saveUsage: '用法：/soul save <名称>（1-30 个字符）',
-    useUsage: '用法：/soul use <名称>',
-    delUsage: '用法：/soul del <名称>',
-    setUsage: '用法：/soul set key=value ...（可用字段：enabled / style / headingLists / emoji / tables / replyLength / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth）',
-    unknownField: '未知配置项',
-    invalidBoolean: (key, value) => `${key} 取值必须为 true / false（收到：${JSON.stringify(value)}）`,
-    setNoChanges: '配置无变化，未做修改',
+// 解析 ?limit=。非法值一律当作「没给」而不是报错：这是一个纯展示参数，
+// 为一个拼错的查询串返回 400 只会让客户端多写一段没必要的错误处理。
+function parseLimit(rawUrl) {
+  try {
+    const raw = new URL(String(rawUrl || ''), 'http://localhost').searchParams.get('limit')
+    if (raw === null) return null
+    const value = Number.parseInt(raw, 10)
+    if (!Number.isFinite(value) || value <= 0) return null
+    return Math.min(value, MAX_READ_LINES)
+  } catch {
+    return null
+  }
+}
+
+// 变更记录的四条路由：列表 / 撤销 / 恢复预设 / 清空。
+//
+// 一律先校验 req.method（同文件其余写路由的规矩，来自 /api/soul/config/reset
+// 曾经任何方法——包括 GET——都能触发破坏性写入的教训）。
+//
+// 撤销与恢复预设都走唯一漏斗 commitConfig，于是「我撤销过一次」本身也留下一条记录：
+// 审计因此是链条而不是快照，能看出「改了、撤了、又改回去」。
+function registerHistoryRoutes(ctx) {
+  ctx.inject(['webServer'], (wsCtx) => {
+    const send = (res, status, body) => {
+      res.writeHead(status, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(body))
+    }
+
+    // 列表（最新在前）
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/history',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'GET') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+          const read = await readHistoryFile(historyPath())
+          // max 必须来自**当前配置**（用户改了保留条数，UI 的「最多保留 N 条」就得跟着变）；
+          // 读配置失败时回退默认值 —— 列表读取不该因为配置层的抖动而 500。
+          let maxEntries
+          try {
+            maxEntries = (await loadConfig()).historyMaxEntries
+          } catch {
+            maxEntries = undefined
+          }
+          const payload = toHistoryResponse(read, lastHistoryFailure, maxEntries)
+          // ?limit= 只影响本次返回的条数，**不动 max** —— max 是容量上限（压实后保多少条），
+          // 拿它当「本次有多少条」用，客户端会在两种含义之间猜。
+          const limit = parseLimit(req.url)
+          if (limit !== null && payload.entries.length > limit) {
+            payload.entries = payload.entries.slice(0, limit)
+          }
+          send(res, 200, { ok: true, ...payload })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // 撤销：把配置退回到目标条目**发生之前**的状态（连带撤销它之后的所有改动）
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/history/rollback',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+          const id = typeof (parsed.body && parsed.body.id) === 'string' ? parsed.body.id : ''
+          if (!id) {
+            send(res, 400, { ok: false, error: '缺少要撤销的记录 id' })
+            return
+          }
+
+          let plan = null
+          const { config: updated, changed, promptChanged, entry } = await commitConfig(async (current) => {
+            // 记录必须在**队列内**读：放到队列外读会与并发写入形成窗口，规划建立在
+            // 已被别人改过的配置上，指纹校验随后报出一个看起来像「数据损坏」的
+            // diverged，把排查方向带偏。
+            const read = await readHistoryFile(historyPath())
+            if (read.error) throw httpError(500, read.error)
+            plan = planRollback(read.entries, current, id)
+            if (!plan.ok) {
+              if (plan.reason === 'missing') {
+                throw httpError(400, `找不到这条变更记录：${id}。它可能已被清空或压实淘汰。`)
+              }
+              // diverged：配置与记录不同步（有人手改过配置文件）。不给一个猜出来的结果。
+              throw httpError(409, '记录与当前配置对不上，无法撤销。可能有人手工改过配置文件。')
+            }
+            // 补丁为空是**合法**结果（目标那次改动已被后续改动改回来了），
+            // 此时不改任何字段、也不会留下记录，由 unchanged 告诉客户端「已经是最新」。
+            if (Object.keys(plan.patch).length === 0) return { ...current }
+            return { ...current, ...plan.patch }
+          }, { source: 'rollback', action: 'rollback' })
+
+          // 仅影响 Agent 行为的字段变化才刷新提示词注入（与其余写路径同一门控）
+          if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
+
+          send(res, 200, {
+            ok: true,
+            config: updated,
+            changed,
+            skipped: plan ? plan.skipped : [],
+            reversed: plan ? plan.reversed : [],
+            unchanged: changed.length === 0,
+            entry,
+            deliveryWarning: deliveryProblemText(updated)
+          })
+        } catch (err) {
+          const status = err && err.httpStatus ? err.httpStatus : 500
+          send(res, status, { ok: false, error: String((err && err.message) || err) })
+        }
+      }
+    })
+
+    // 恢复预设：只对「删除预设」这类条目有意义（条目里带着被删条目的内容）
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/history/restore-persona',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+          const id = typeof (parsed.body && parsed.body.id) === 'string' ? parsed.body.id : ''
+          if (!id) {
+            send(res, 400, { ok: false, error: '缺少记录 id' })
+            return
+          }
+
+          const restored = []
+          const skipped = []
+          const { config: updated, changed, entry } = await commitConfig(async (current) => {
+            const read = await readHistoryFile(historyPath())
+            if (read.error) throw httpError(500, read.error)
+            const index = findEntryIndex(read.entries, id)
+            if (index < 0) {
+              throw httpError(400, `找不到这条变更记录：${id}。它可能已被清空或压实淘汰。`)
+            }
+            const removed = read.entries[index].personas.removed
+            if (removed.length === 0) {
+              throw httpError(400, '这条记录里没有被删除的预设，无法恢复。')
+            }
+            const personas = clonePersonas(current.personas)
+            for (const item of removed) {
+              // 逐个校验、逐个说明为什么没恢复。**绝不静默覆盖同名条目**：
+              // 删掉「架构师」之后完全可能又新建了一个同名但内容不同的预设，
+              // 此时「恢复」若是直接写回，等于把用户后来的编辑悄悄扔掉。
+              const personaName = sanitizePersonaName(item.name)
+              if (!personaName) {
+                skipped.push({ name: item.name, reason: 'invalid-name' })
+                continue
+              }
+              if (isBuiltinPersona(personaName)) {
+                skipped.push({ name: personaName, reason: 'builtin' })
+                continue
+              }
+              if (hasOwn(personas, personaName)) {
+                skipped.push({ name: personaName, reason: 'exists' })
+                continue
+              }
+              personas[personaName] = { ...item.entry }
+              restored.push(personaName)
+            }
+            if (restored.length === 0) {
+              throw httpError(400, `没有可恢复的预设：${skipped.map((item) => item.name).join('、')}`)
+            }
+            return { ...current, personas }
+          }, { source: 'restorePersona', action: 'restorePreset' })
+
+          // 预设库变化不触发会话注入（diffKeys 本就跳过 personas），故此处不刷新提示词
+          send(res, 200, { ok: true, restored, skipped, changed, entry, ...personaLibrary(updated) })
+        } catch (err) {
+          const status = err && err.httpStatus ? err.httpStatus : 500
+          send(res, status, { ok: false, error: String((err && err.message) || err) })
+        }
+      }
+    })
+
+    // 清空：隐私出口（记录里有昵称 / 职业 / 介绍 / 自定义指令的原文）
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/history/clear',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+          // 借配置写队列串行：记录是在提交路径里写的，清空若不入队就会与并发的追加
+          // 撞在一起 —— 最坏的结果是「刚清完又冒出一条」，用户会以为清空没生效。
+          const removed = await enqueueConfigWrite(async () => {
+            const count = await clearHistoryFile(historyPath())
+            lastHistoryFailure = null
+            return count
+          })
+          send(res, 200, { ok: true, removed })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+  })
+}
+
+// ==================== 工作区绑定路由 ====================
+
+// 绑定表的写队列。与配置队列（enqueueConfigWrite）**刻意是两个实例**（设计 §4.3）：
+// 两套数据在因果上无关 —— 绑定的写入不依赖配置的当前值，反之亦然 —— 共用一个队列
+// 只会把两者的延迟叠在一起，一次慢写的绑定请求会挡住配置保存。
+let bindingsWriteQueue = Promise.resolve()
+
+function enqueueBindingsWrite(task) {
+  const run = bindingsWriteQueue.then(task)
+  bindingsWriteQueue = run.then(() => {}, () => {})
+  return run
+}
+
+// 活动会话的目录与解析结果，供设置页回答「我这个项目现在是谁」。
+//
+// 为什么必须由宿主算：设置页的槽位 scope 是 `root`（设计 §7.7），它**拿不到
+// sessionId**，也就拿不到会话 cwd。宿主遍历 agents.list() 是唯一权威的来源。
+//
+// 取 `session.header.cwd` 而不是工作区根：两者可能不同（工作区 D:\AliuProject、
+// 会话 cwd D:\AliuProject\dsh-plugin），显示错粒度会让用户绑错层级。
+function describeActiveSessions(ctx, config) {
+  const out = []
+  const agents = ctx.get('agents')
+  if (!agents || typeof agents.list !== 'function') return out
+
+  let listed
+  try {
+    listed = agents.list()
+  } catch {
+    // 列不出活动会话不是错误：设置页只是少一段「当前用的谁」，仍能管理绑定表。
+    return out
+  }
+
+  for (const agent of listed) {
+    const cwd = cwdOfAgent(agent)
+    const id = agent && typeof agent.id === 'string' ? agent.id : null
+
+    if (!cwd) {
+      // cwd 缺席是宿主允许的情况（会话没有工作目录）。必须如实说出来 ——
+      // 让用户对着空白猜「为什么绑了没生效」，不如直接告诉他这个会话没有目录。
+      out.push({ id, cwd: null, persona: resolveActivePersonaName(config), binding: null, shadowed: [] })
+      continue
+    }
+
+    const resolved = resolveBindingForCwd(cwd, config.personas)
+    // 生效人设走与真实装配**同一条路径**（configForCwd → 部分覆盖 → findActivePersonaName），
+    // 否则设置页显示的「生效人设」与实际注入的可能不一致 —— 那正是最难查的一类 bug。
+    const effective = configForCwd(config, cwd).config
+
+    let binding = null
+    if (resolved) {
+      // 「直接绑定」与「继承自上级」的判别**必须在宿主做**：客户端拿原始串比较时，
+      // Windows 上 `D:\项目A` 与 `d:\项目a` 会被判成不同目录，于是「就是本目录」
+      // 被显示成「继承自上级」，用户会去找一条并不存在的父级绑定。
+      const sameDir = compareKey(normalizeDirPath(resolved.dir)) === compareKey(normalizeDirPath(cwd))
+      binding = { dir: resolved.dir, persona: resolved.persona, inherited: !sameDir }
+    }
+
+    out.push({
+      id,
+      cwd,
+      persona: resolveActivePersonaName(effective),
+      binding,
+      shadowed: resolved ? resolved.shadowed : []
+    })
+  }
+
+  return out
+}
+
+// 绑定表的可读形态（列表 + 失效标注 + 解析结果）。
+async function bindingsView(ctx) {
+  const cache = await ensureBindings()
+  const config = await loadConfig()
+
+  // 失效引用：指向的人设已不存在。**不自动删除**（设计 §4.2）——用户可能只是临时
+  // 删了那个预设、打算重命名回来。但必须显式标注，否则用户在目录里等一个永远
+  // 不会来的人设。
+  const invalid = []
+  for (const dir of Object.keys(cache.bindings)) {
+    const name = cache.bindings[dir]
+    if (!resolvePersona(name, config.personas)) invalid.push({ dir, persona: name })
+  }
+
+  return {
+    bindings: cache.bindings,
+    invalid,
+    dropped: cache.dropped,
+    // warning 是「整表没读进来」或「有条目被丢弃」，与「一条都没绑」是两件事。
+    warning: bindingsLoadFailure,
+    max: MAX_BINDINGS,
+    maxPathLength: MAX_PATH_LENGTH,
+    sessions: describeActiveSessions(ctx, config)
+  }
+}
+
+function registerBindingRoutes(ctx) {
+  ctx.inject(['webServer'], (wsCtx) => {
+    const send = (res, status, body) => {
+      res.writeHead(status, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(body))
+    }
+
+    // 写完之后统一收尾：重载绑定表 → 刷新提示词并注入。
+    //
+    // 这是**第三类**会改变提示词的事实（设计 §6.4）：它不改 soul-config.json，
+    // 所以 commitConfig 的 promptChanged 门控看不见它。绑定路由必须自己触发，
+    // 否则「刚绑好，会话里却不生效，要新开会话才行」。
+    const afterBindingsWrite = async (config) => {
+      await loadBindings()
+      const fresh = config || (await loadConfig())
+      refreshPromptAndInject(ctx, fresh)
+    }
+
+    // GET = 读取（绑定表 + 当前活动会话的解析结果）；POST = 新增 / 改绑。
+    //
+    // 同一 (kind, path) 只能 register **一次**：宿主 dsh-host-webserver 的
+    // `register()` 对重复路径直接 `throw new Error('webserver: duplicate exact
+    // route "' + path + '"')`，而这里是 ctx.inject 回调 —— 一次重复注册会让
+    // 整个插件装配失败。故方法分派必须写在 handler 内，这也正是本文件其余
+    // 14 条路由的范式。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/bindings',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            send(res, 200, { ok: true, ...(await bindingsView(ctx)) })
+          } catch (err) {
+            send(res, 500, { ok: false, error: String(err.message || err) })
+          }
+          return
+        }
+        if (req.method !== 'POST') {
+          send(res, 405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+        try {
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+
+          const config = await loadConfig()
+          // 准入检查挑出三类拒绝（路径非法 / 过长 / 人设不存在），
+          // 原因文案可直接展示 —— 客户端不得再包一层前缀。
+          const refusal = bindingRefusal(parsed.body && parsed.body.dir, parsed.body && parsed.body.persona, config.personas)
+          if (refusal) {
+            send(res, 400, { ok: false, error: refusal })
+            return
+          }
+          const entry = normalizeBindingEntry(parsed.body && parsed.body.dir, parsed.body && parsed.body.persona, config.personas)
+          if (!entry) {
+            send(res, 400, { ok: false, error: '绑定内容不合法，未写入。' })
+            return
+          }
+
+          await enqueueBindingsWrite(async () => {
+            // 队列内读盘再合并：队列外读会与并发写入形成窗口，后写覆盖前写。
+            const read = await readBindingsFile(bindingsPath())
+            if (read.failure) throw httpError(500, read.failure)
+            const table = { ...read.bindings }
+            // 已存在的目录改绑不算新增，只有真新增才受条数上限约束 ——
+            // 否则满表之后连改绑都做不了，用户只能先删再绑。
+            const isNew = !hasOwn(table, entry.dir)
+            if (isNew && Object.keys(table).length >= MAX_BINDINGS) {
+              throw httpError(400, `绑定数量已达上限（${MAX_BINDINGS} 条），请先删除不再需要的绑定。`)
+            }
+            table[entry.dir] = entry.persona
+            await writeBindingsFile(bindingsPath(), table)
+          })
+
+          await afterBindingsWrite(config)
+          send(res, 200, { ok: true, ...(await bindingsView(ctx)) })
+        } catch (err) {
+          // 队列内抛出的 httpError 带状态码；其余按 500 处理。
+          send(res, err.httpStatus || 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // 解绑
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/bindings/delete',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'POST') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+          const target = normalizeDirPath(parsed.body && parsed.body.dir)
+          if (!target) {
+            send(res, 400, { ok: false, error: '需要一个绝对路径才能解绑。' })
+            return
+          }
+
+          const config = await loadConfig()
+          let removed = false
+          await enqueueBindingsWrite(async () => {
+            const read = await readBindingsFile(bindingsPath())
+            if (read.failure) throw httpError(500, read.failure)
+            const table = { ...read.bindings }
+            // 按**比较键**找：用户点了列表里那一行，但配置里存的可能是另一种写法
+            // （分隔符、尾分隔符、盘符大小写）。拿原串直接 delete 会「点了没反应」。
+            const key = Object.keys(table).find(dir => compareKey(dir) === compareKey(target))
+            if (key === undefined) return
+            delete table[key]
+            removed = true
+            await writeBindingsFile(bindingsPath(), table)
+          })
+
+          // 没删掉任何东西时**不刷新**：一次空解绑不该向所有活动会话注入快照。
+          if (removed) await afterBindingsWrite(config)
+          send(res, 200, { ok: true, removed, ...(await bindingsView(ctx)) })
+        } catch (err) {
+          send(res, err.httpStatus || 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+  })
+}
+
+// ==================== 工作区索引（sessionId → workspaceId）====================
+
+// 维护 sessionWorkspaceIndex 的三条时机（docs/DESIGN-config-scope.md §2.2）：
+//
+//   ① 首轮重建 —— 服务刚就绪时索引必然是空的；
+//   ② 宿主工作区变更 —— 加/删工作区、会话移入移出，都会改变映射；
+//   ③ 兜底重扫 —— 装配时发现「有 sessionId 但索引里没有」就标记，下一拍重建。
+//
+// ③ 是必需的：②依赖宿主的事件名（内部约定，可能改名）。没有兜底的话，
+// 事件一旦改名，索引会**静默停止更新** —— 表现为「工作区绑定时灵时不灵」，
+// 而 ③ 让它的失败形态退化成「多扫一次内存投影」，代价可以忽略。
+function registerWorkspaceIndex(ctx) {
+  const rebuild = () => rebuildWorkspaceIndex(ctx)
+
+  // ① 首轮：延后一拍，给宿主服务一个物化窗口。
+  const firstTimer = setTimeout(rebuild, 0)
+  if (typeof firstTimer.unref === 'function') firstTimer.unref()
+
+  // ② 事件：宿主工作区域变更。事件名取自 dsh-workspace 的 domain 事件。
+  //    订阅失败（宿主无该事件）不是错误 —— 还有 ③ 兜底。
+  try {
+    ctx.on('domain/changed', () => { rebuild() })
+  } catch {
+    // 事件名不存在时 ctx.on 可能直接抛错；吞掉，靠 ③。
+  }
+
+  // ③ 兜底：装配时未命中的 sessionId 会被记下来，这里周期性重扫。
+  //    用 5s 而不是每轮：索引是内存投影，重建本身很轻，但没必要每个 step 都做。
+  const sweepTimer = setInterval(() => {
+    if (pendingWorkspaceRescan === 0) return
+    pendingWorkspaceRescan = 0
+    rebuild()
+  }, 5000)
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref()
+
+  ctx.effect(() => () => {
+    clearTimeout(firstTimer)
+    clearInterval(sweepTimer)
+  }, 'dsh-soul: workspace index')
+}
+
+// 装配时发现「有 sessionId 但索引查不到」的次数。由 section.text 递增（同步、无副作用），
+// 由上面的定时器消费。刻意用计数器而不是 Set：装配是每轮都跑的，Set 会无限增长。
+let pendingWorkspaceRescan = 0
+
+// ==================== 工作区路由 ====================
+
+// 工作区覆盖的读写。与绑定路由**刻意分开**：绑定是独立的 soul-bindings.json，
+// 工作区覆盖是 soul-config.json 的一个字段 —— 后者必须走配置写队列与审计。
+function registerWorkspaceRoutes(ctx) {
+  ctx.inject(['webServer'], (wsCtx) => {
+    const send = (res, status, body) => {
+      res.writeHead(status, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(body))
+    }
+
+    // 一次性读全：宿主的工作区列表 + 当前配置里的覆盖表 + 每个工作区的解析结果。
+    //
+    // 全部由**宿主**算，设置页/详情页只负责画 —— 它们拿不到 workspaceRegistry
+    // （客户端侧是 `workspaces` 服务，是另一份投影）。
+    const workspaceView = async () => {
+      const config = await loadConfig()
+      const registry = ctx.get('workspaceRegistry')
+      const scopes = workspaceScopesOf(config)
+
+      const workspaces = []
+      let indexProblem = null
+      if (!registry || typeof registry.list !== 'function') {
+        indexProblem = 'workspaceRegistry 服务不可用：无法列出宿主的工作区。'
+      } else {
+        let listed = []
+        try {
+          listed = registry.list()
+        } catch (err) {
+          indexProblem = `列出工作区失败：${String((err && err.message) || err)}`
+        }
+        // 失效判断必须用**合并后的预设库**（0.9.0-v）：内置预设不在 config.personas 里
+        // （它们只存在于代码），若只查磁盘条目，绑定指向内置预设的会被误报
+        // 「人设已不存在」—— 实测「自驱型协作者」「头脑风暴伙伴」都中招。
+        const personaNames = mergePersonas(config.personas)
+        for (const workspace of Array.isArray(listed) ? listed : []) {
+          const id = workspace && workspace.id !== undefined ? String(workspace.id) : null
+          if (id === null) continue
+          const override = resolveWorkspaceOverride(id, scopes)
+          // 失效引用：覆盖指向的人设已不存在。**如实标出但不自动删除** ——
+          // 用户可能只是临时改名，删掉就再也找不回来了（与绑定表同一条约定）。
+          // 引用字段说明「当初绑的是谁」：预设被改名/删除后，覆盖的字段值仍在生效，
+          // 但界面必须能说出这条覆盖已经指向空气 —— 否则用户看到一堆陌生字段无从判断。
+          const refName = override && typeof override[WORKSPACE_PERSONA_REF] === 'string'
+            ? override[WORKSPACE_PERSONA_REF]
+            : null
+          const invalidPersona = refName !== null && !(refName in personaNames)
+          workspaces.push({
+            workspaceId: id,
+            title: typeof workspace.title === 'string' ? workspace.title : '',
+            path: typeof workspace.path === 'string' ? workspace.path : '',
+            sessionCount: Array.isArray(workspace.sessionIds) ? workspace.sessionIds.length : 0,
+            bound: override !== null,
+            // 绑的是哪个预设：界面要显示它，而不是只说"已绑定"。
+            // 失效时仍原样返回 —— 用户需要看到"它原本指向谁"才能判断怎么处理。
+            persona: refName,
+            invalidPersona
+          })
+        }
+      }
+
+      return {
+        workspaces,
+        indexProblem,
+        max: MAX_WORKSPACE_SCOPES,
+        // 供 UI 展示「当前有几条覆盖」。数字取自配置而非上面的列表：
+        // 覆盖可以指向一个已被删除的工作区，那种条目仍占着表。
+        boundCount: Object.keys(scopes).length
+      }
+    }
+
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/workspaces',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            send(res, 200, { ok: true, ...(await workspaceView()) })
+          } catch (err) {
+            send(res, 500, { ok: false, error: String(err.message || err) })
+          }
+          return
+        }
+        if (req.method !== 'POST') {
+          send(res, 405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+
+        try {
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+
+          const config = await loadConfig()
+          const verdict = validateWorkspaceBinding(parsed.body, config.personas)
+          if (!verdict.ok) {
+            send(res, 400, { ok: false, error: verdict.error })
+            return
+          }
+
+          // 走配置写队列：与 HTTP 保存 / 命令 / 工具共用同一条串行路径，
+          // 并自动获得变更审计（source = web, action = save）。
+          await commitConfig((current) => {
+            const scopes = workspaceScopesOf(current)
+            scopes[verdict.workspaceId] = verdict.override
+            const next = { ...current, workspaces: { version: WORKSPACE_SCOPE_VERSION, scopes } }
+            return next
+          }, { source: 'web', action: 'save' })
+
+          // 工作区改的是**人设**，必须重算提示词并注入 —— commitConfig 的
+          // promptChanged 看不见 workspaces（它不在 AUDIT_FIELDS / PROMPT_INPUT_FIELDS 里）。
+          const fresh = await loadConfig()
+          refreshPromptAndInject(ctx, fresh)
+
+          send(res, 200, { ok: true, ...(await workspaceView()) })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // 解绑：把某个工作区从覆盖表里删掉。与绑定路由的 /delete 同一形态。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/workspaces/delete',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          send(res, 405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+        try {
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+          const workspaceId = parsed.body && parsed.body.workspaceId
+          if (typeof workspaceId !== 'string' || workspaceId.trim() === '') {
+            send(res, 400, { ok: false, error: '缺少 workspaceId' })
+            return
+          }
+
+          let removed = false
+          await commitConfig((current) => {
+            const scopes = workspaceScopesOf(current)
+            if (!(workspaceId in scopes)) return current
+            removed = true
+            const next = { ...scopes }
+            delete next[workspaceId]
+            // 删空后把字段整个去掉：留一个 `{ version, scopes: {} }` 会让「从未设过」
+            // 与「设过又全删了」在磁盘上不可区分，排查时看不出真相。
+            const empty = Object.keys(next).length === 0
+            return { ...current, workspaces: empty ? undefined : { version: WORKSPACE_SCOPE_VERSION, scopes: next } }
+          }, { source: 'web', action: 'save' })
+
+          if (removed) {
+            const fresh = await loadConfig()
+            refreshPromptAndInject(ctx, fresh)
+          }
+          send(res, 200, { ok: true, removed, ...(await workspaceView()) })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+  })
+}
+
+// ==================== 会话级覆盖路由（0.9.0-c）====================
+
+// 会话覆盖的读写 + 回收。三条路由：
+//   GET  /api/soul/session-scope?sessionId=...   读该会话的覆盖与解析结果
+//   POST /api/soul/session-scope                 设置 / 清除该会话的覆盖
+//   POST /api/soul/session-scope/gc              回收（默认 dry-run）
+//
+// 与工作区覆盖的区别：工作区写**配置**（走 commitConfig、进审计、有变更历史）；
+// 会话写**状态**（sidecar、不进审计）。这不是疏漏：「改了这次会话用什么人设」是
+// 一次性的临时动作，记进变更历史只会把时间线淹没。
+function registerSessionScopeRoutes(ctx) {
+  ctx.inject(['webServer'], (wsCtx) => {
+    const send = (res, status, body) => {
+      res.writeHead(status, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(body))
+    }
+
+    // 会话覆盖的「当前值 + 解析结果」，供会话内 tab 显示。
+    //
+    // 全部在宿主算：客户端拿不到 sessionId → workspaceId 的权威映射（那是宿主侧索引）。
+    const sessionScopeView = async (sessionId) => {
+      const config = await loadConfig()
+      const override = await loadSessionOverride(sessionId)
+      const workspaceId = sessionWorkspaceIndex.get(String(sessionId)) || null
+      const resolved = configForScope(config, null, workspaceId, override)
+
+      // 生效人设名：走与真实装配**同一条路径**，否则 tab 上显示的与模型拿到的不一致。
+      //
+      // ⚠️ 但「按字段反查」是不确定的：多个预设声明相同字段时，名称排序决定谁命中
+      // （实测：自建「游戏策划与开发专家」与内置「自驱型协作者」字段一致时，
+      // 用户点了后者却显示前者）。所以**先看 sidecar 里记的 personaName** ——
+      // 那是用户实际点过的名字，确定无疑；没有它（老 sidecar / 手改字段）才退回反查。
+      const recordedName = await recordedSessionPersonaName(sessionId)
+      const activePersona = recordedName
+        || resolveActivePersonaName(resolved.config)
+      return {
+        sessionId,
+        workspaceId,
+        override: override || null,
+        source: resolved.source,
+        activePersona,
+        // 用户实际点的那个名字（可能与「按字段反查」的结论不同）。
+        // 客户端据此显示「你点的是 A，但字段与 B 相同」这类提示。
+        recordedPersona: recordedName,
+        // 全局层的人设名：客户端要显示「当前是谁」与「全局是谁」两者的关系
+        // （会话覆盖生效时，全局值仍在，但当前值不是它）。
+        globalPersona: resolveActivePersonaName(config),
+        workspaceTitle: (() => {
+          if (workspaceId === null) return null
+          const registry = ctx.get('workspaceRegistry')
+          if (!registry || typeof registry.list !== 'function') return null
+          try {
+            const hit = registry.list().find((w) => String(w.id) === workspaceId)
+            return hit && typeof hit.title === 'string' ? hit.title : null
+          } catch {
+            return null
+          }
+        })()
+      }
+    }
+
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/session-scope',
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            const url = new URL(req.url, 'http://localhost')
+            const sessionId = url.searchParams.get('sessionId') || ''
+            if (!isSessionId(sessionId)) {
+              send(res, 400, { ok: false, error: '缺少或非法的 sessionId' })
+              return
+            }
+            send(res, 200, { ok: true, ...(await sessionScopeView(sessionId)) })
+            return
+          }
+
+          if (req.method !== 'POST') {
+            send(res, 405, { ok: false, error: 'Method not allowed' })
+            return
+          }
+
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+
+          const sessionId = parsed.body && parsed.body.sessionId
+          if (!isSessionId(sessionId)) {
+            send(res, 400, { ok: false, error: '缺少或非法的 sessionId' })
+            return
+          }
+
+          const filePath = sessionScopePathFor(configPath(), sessionId)
+
+          // `clear: true` = 清除覆盖。显式动作而非"传空对象"，因为空对象与
+          // "只想改一个字段、其余保留"在语义上无法区分。
+          if (parsed.body && parsed.body.clear === true) {
+            // 删文件：用 quarantine 而不是 rm？—— 这里**必须是真删**：
+            // 用户主动清除覆盖，把一个 .bad 文件留在磁盘上只会污染 GC 的清单。
+            // 但删除失败要如实报告，不能假装成功。
+            let removed = false
+            try {
+              const { rm } = await import('node:fs/promises')
+              await rm(filePath, { force: true })
+              removed = true
+            } catch (err) {
+              send(res, 500, { ok: false, error: `清除失败：${String((err && err.message) || err)}` })
+              return
+            }
+            forgetSessionOverride(sessionId)
+            if (removed) refreshPromptAndInject(ctx, await loadConfig())
+            send(res, 200, { ok: true, ...(await sessionScopeView(sessionId)) })
+            return
+          }
+
+          // 设置覆盖：白名单过滤，enabled 等包封字段一律丢弃。
+          const { override, dropped } = sanitizeSessionOverride(parsed.body && parsed.body.overrides)
+          if (override === null) {
+            send(res, 400, {
+              ok: false,
+              error: dropped.length > 0
+                ? `没有可用的覆盖字段（被忽略：${dropped.join(', ')}）`
+                : '缺少 overrides'
+            })
+            return
+          }
+
+          // 保留原有的 createdAt 与孤儿标记：重写覆盖不等于"这个会话是新出现的"。
+          const previous = await readSessionScope(filePath, sessionId)
+          const now = Date.now()
+          // personaName：客户端告诉服务端"用户实际点了哪个预设"。
+          // 覆盖项只存字段，而「当前生效的是哪个预设」若靠字段反查，在两个预设字段
+          // 相同时会不确定（实测：自建「游戏策划与开发专家」与内置「自驱型协作者」
+          // 字段一致时，名称排序让自建的那个抢先命中，用户点了 A 却显示 B）。
+          // 记下名字就把"猜"变成"知道"。
+          const requestedName = parsed.body && typeof parsed.body.personaName === 'string'
+            ? parsed.body.personaName.trim()
+            : ''
+          const doc = {
+            ...createSessionScopeDoc(
+              sessionId,
+              override,
+              now,
+              requestedName || (previous.personaName ?? null)
+            ),
+            createdAt: (previous.doc && previous.doc.createdAt) || new Date(now).toISOString(),
+            ...(previous.orphan ? { orphan: previous.orphan } : {})
+          }
+          await writeSessionScope(filePath, doc)
+
+          // **先写缓存再刷新提示词**：缓存更新是同步的，保证紧接着的那一轮装配
+          // 一定能看到新值。若等磁盘异步完成再刷，装配可能先跑、读到旧缓存。
+          sessionOverrides.set(sessionId, override)
+          sessionOverridesKnown.add(sessionId)
+          // personaName 也同步进缓存：紧接着的 sessionScopeView 立刻能读到，
+          // 不必等下一次读盘。
+          if (requestedName) sessionPersonaNames.set(sessionId, requestedName)
+          else sessionPersonaNames.delete(sessionId)
+          refreshPromptAndInject(ctx, await loadConfig())
+
+          send(res, 200, { ok: true, dropped, ...(await sessionScopeView(sessionId)) })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // —— 当前会话的作用域（供输入框下方的标签显示）——
+    //
+    // 为什么需要它：全局 store 里的 activePersona 是**全局**匹配结果，
+    // 而三级隔离下会话可能有自己的覆盖或工作区绑定 —— 两者可以不同。
+    // 标签若显示全局值，就会出现「界面说 A、模型用 B」的割裂（实测踩过）。
+    //
+    // 这个端点**按 query 传 sessionId**：输入框左侧组件（conversation.input.left）
+    // 拿得到当前会话 id（它挂在会话里），而 settings.section 拿不到。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/session-scope/current',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') {
+          send(res, 405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+        try {
+          const url = new URL(req.url, 'http://localhost')
+          const sessionId = url.searchParams.get('sessionId') || ''
+          if (!isSessionId(sessionId)) {
+            send(res, 400, { ok: false, error: '缺少或非法的 sessionId' })
+            return
+          }
+          send(res, 200, { ok: true, ...(await sessionScopeView(sessionId)) })
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+
+    // —— 回收：默认 dry-run ——
+    //
+    // 判定依据是 `sessionPersistence.list()`（扫磁盘会话文件），**绝不是** `agents.list()`
+    // （那是 live registry，会话切走就消失，用它判定会误删正在使用的覆盖）。
+    wsCtx.webServer.register({
+      kind: 'exact',
+      path: '/api/soul/session-scope/gc',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          send(res, 405, { ok: false, error: 'Method not allowed' })
+          return
+        }
+        try {
+          const parsed = await readJsonBody(req)
+          if (!parsed.ok) {
+            send(res, parsed.status, { ok: false, error: parsed.error })
+            return
+          }
+          // 只有显式 apply:true 才会真的删。默认 dry-run。
+          const apply = parsed.body && parsed.body.apply === true
+
+          const plan = await planSessionGc(ctx)
+          const result = { ok: true, dryRun: !apply, ...plan }
+
+          if (apply && plan.collectable.length > 0) {
+            const removed = []
+            for (const item of plan.collectable) {
+              try {
+                const { rm } = await import('node:fs/promises')
+                await rm(item.path, { force: true })
+                forgetSessionOverride(item.sessionId)
+                removed.push(item.sessionId)
+              } catch (err) {
+                result.errors = result.errors || []
+                result.errors.push({ sessionId: item.sessionId, error: String((err && err.message) || err) })
+              }
+            }
+            result.removed = removed
+            if (removed.length > 0) refreshPromptAndInject(ctx, await loadConfig())
+          }
+
+          send(res, 200, result)
+        } catch (err) {
+          send(res, 500, { ok: false, error: String(err.message || err) })
+        }
+      }
+    })
+  })
+}
+
+// 规划一次回收：读全部 sidecar、比对磁盘会话清单、跑状态机。
+//
+// 关键：`scanComplete` 反映的是「本轮会话清单是否可信」。拿不到
+// `sessionPersistence` 时它必须是 false —— 那会让状态机对**所有**条目返回 keep，
+// 于是「服务不可用」不会演变成「把所有覆盖当孤儿删掉」。
+async function planSessionGc(ctx) {
+  const dir = sessionScopeDirFor(configPath())
+  const files = await listSessionScopes(dir)
+
+  // 磁盘上的会话清单。
+  let stored = null
+  let persistenceProblem = null
+  const persistence = ctx.get('sessionPersistence')
+  if (!persistence || typeof persistence.list !== 'function') {
+    persistenceProblem = 'sessionPersistence 服务不可用：无法确认哪些会话仍然存在，本轮不做任何判定'
+  } else {
+    try {
+      const listed = await persistence.list()
+      stored = new Set(
+        (Array.isArray(listed) ? listed : [])
+          .map((item) => (item && item.id !== undefined ? String(item.id) : ''))
+          .filter((id) => id !== '')
+      )
+    } catch (err) {
+      persistenceProblem = `列出会话失败：${String((err && err.message) || err)}；本轮不做任何判定`
+    }
+  }
+
+  const scanComplete = stored !== null && persistenceProblem === null
+  const now = Date.now()
+
+  const entries = []
+  for (const file of files) {
+    const item = {
+      file: file.name,
+      path: file.path,
+      sessionId: null,
+      action: 'keep',
+      reason: '',
+      graceDaysLeft: null,
+      failure: null
+    }
+
+    // 从内容里读 sessionId（文件名是哈希，无法反查）。读不出就只报告，不动它。
+    let doc
+    try {
+      doc = JSON.parse(await (await import('node:fs/promises')).readFile(file.path, 'utf8'))
+    } catch (err) {
+      item.action = 'quarantine'
+      item.reason = `sidecar 读不出来或不是合法 JSON：${String((err && err.message) || err)}`
+      entries.push(item)
+      continue
+    }
+
+    const sessionId = doc && typeof doc.sessionId === 'string' ? doc.sessionId : null
+    if (!isSessionId(sessionId)) {
+      item.action = 'quarantine'
+      item.reason = 'sidecar 内缺少合法的 sessionId（无法与文件名互相校验）'
+      entries.push(item)
+      continue
+    }
+    item.sessionId = sessionId
+
+    // 内容与文件名必须互相对应：改个文件名就能让某个会话读到另一个会话的覆盖。
+    const expectedName = sessionScopePathFor(configPath(), sessionId)
+    if (expectedName !== file.path) {
+      item.action = 'quarantine'
+      item.reason = `文件名与内容里的 sessionId 不符（期望 ${expectedName.split(/[\\/]/).pop()}）`
+      entries.push(item)
+      continue
+    }
+
+    const parsedDoc = (await readSessionScope(file.path, sessionId))
+    if (parsedDoc.failure) {
+      item.action = 'quarantine'
+      item.reason = parsedDoc.failure
+      entries.push(item)
+      continue
+    }
+
+    const decision = decideSessionScopeFate({
+      orphan: parsedDoc.orphan,
+      presentOnDisk: scanComplete ? stored.has(sessionId) : false,
+      scanComplete,
+      now
+    })
+    item.action = decision.action
+    item.reason = decision.reason
+    if (decision.orphan && decision.action === 'keep') {
+      const age = now - Date.parse(decision.orphan.firstSeenAt)
+      item.graceDaysLeft = Math.max(0, Math.ceil((ORPHAN_GRACE_MS - age) / (24 * 3600 * 1000)))
+    }
+
+    // 标记 / 撤销标记都要落盘 —— 但**只在扫描完整时**。扫描不完整时状态机返回 keep，
+    // 那时不该写任何东西（否则一次临时的服务故障会把所有条目刷上已扫描时间）。
+    if (decision.action === 'mark' || decision.action === 'clear-mark') {
+      try {
+        const nextDoc = decision.action === 'clear-mark'
+          ? { ...doc, orphan: undefined }
+          : { ...doc, orphan: decision.orphan }
+        if (decision.action === 'clear-mark') delete nextDoc.orphan
+        await writeSessionScope(file.path, nextDoc)
+      } catch (err) {
+        item.markError = String((err && err.message) || err)
+      }
+    }
+
+    entries.push(item)
+  }
+
+  return {
+    scanComplete,
+    persistenceProblem,
+    total: entries.length,
+    markable: entries.filter((e) => e.action === 'mark'),
+    collectable: entries.filter((e) => e.action === 'collect'),
+    quarantine: entries.filter((e) => e.action === 'quarantine'),
+    entries
+  }
+}
+
+// ==================== 斜杠命令 ====================
+
+// 宿主端无 locale 服务（CommandInvocation 不携带 UI 语言，settings 中亦无语言字段），
+// 命令输出语言跟随 soul 配置的 language 字段，可在设置页切换。
+const COMMAND_MESSAGES = {
+  zh: {
+    showTitle: '🧠 个性化设置',
+    colon: '：',
+    statusLabel: '状态',
+    nicknameLabel: '昵称',
+    occupationLabel: '职业',
+    bioLabel: '介绍',
+    styleLabel: '风格语调',
+    styleNames: {
+      professional: '专业严谨',
+      casual: '轻松自然',
+      humorous: '幽默风趣',
+      roast: '吐槽达人',
+      efficient: '高效干练'
+    },
+    traitsLabel: '特质',
+    headingListsLabel: '标题和列表',
+    emojiLabel: '表情符号',
+    tablesLabel: '表格',
+    replyLengthLabel: '回复长度',
+    traitNames: {
+      default: '默认',
+      more: '增强',
+      less: '减弱'
+    },
+    replyLengthNames: {
+      concise: '简洁',
+      normal: '适中',
+      detailed: '详尽'
+    },
+    listSep: '，',
+    trailLabel: '输入框光轨',
+    trailLine: (status, color, speedName, widthName) => `${status}（${color} / ${speedName} / ${widthName}）`,
+    trailSpeedNames: {
+      slow: '慢',
+      normal: '中',
+      fast: '快'
+    },
+    trailWidthNames: {
+      thin: '细',
+      normal: '中',
+      thick: '粗'
+    },
+    instructionsLabel: '自定义指令',
+    enabled: '已启用',
+    disabled: '已禁用',
+    notSet: '未设置',
+    toolConfirmLabel: '确认模式',
+    onLabel: '开启',
+    offLabel: '关闭',
+    personasLabel: '人设预设',
+    // 提议是**内存态**（重启即失效）、也没有 TTL，所以必须让用户看到它是什么时候提出的，
+    // 否则一条陈旧提议会一直挂着而无法判断新鲜度（proposedAt 此前只写不读）。
+    pendingHint: (at) => `⚠ 有待确认的人设变更（提出于 ${at}）：/soul confirm 确认，/soul reject 拒绝`,
+    noPending: '没有待确认的人设变更',
+    // 会话覆盖回收报告。
+    //
+    // 三种情形要给三种不同的说法，否则用户会误判：
+    //   · 扫描不完整（拿不到 sessionPersistence）→ 说清"没做任何判定"，并解释为什么；
+    //   · dry-run → 列出**将删**的清单，并告诉用户怎么真删；
+    //   · apply → 只报结果。
+    // 无论哪种，"没有被判定的条目"都要能从上一次输出里看出来。
+    sessionsGcReport: (plan, apply) => {
+      const lines = []
+      lines.push(apply ? '🧹 会话覆盖清理' : '🧹 会话覆盖清理（预演，未删除任何文件）')
+      lines.push(plan.scanComplete
+        ? '会话清单：完整'
+        : `会话清单：不可用 —— ${plan.persistenceProblem || '原因未知'}`)
+      lines.push(`共 ${plan.total} 个文件 · 待观察 ${plan.markable.length} 个 · 可回收 ${plan.collectable.length} 个 · 损坏 ${plan.quarantine.length} 个`)
+      if (!plan.scanComplete) {
+        lines.push('会话清单不可用时不会标记也不会删除 —— 「没看到」不等于「已删除」。')
+      }
+      for (const item of plan.collectable.slice(0, 20)) {
+        lines.push(`  ✕ ${item.sessionId} —— ${item.reason}`)
+      }
+      for (const item of plan.quarantine.slice(0, 20)) {
+        lines.push(`  ⚠ ${item.file} —— ${item.reason}`)
+      }
+      if (!apply && plan.collectable.length > 0) {
+        lines.push('执行 /soul sessions --apply 可删除上面列出的条目。')
+      }
+      return lines.join('\n')
+    },
+    confirmDone: (detail) => `✅ 已应用人设变更：${detail}`,
+    rejectDone: '✅ 已拒绝待确认的人设变更',
+    saveDone: (name) => `✅ 已保存预设「${name}」`,
+    // 内置预设（随插件发布、不落盘）：不可用同名保存，也不可删除
+    builtinName: '内置',
+    builtinSaveBlocked: (name) => `「${name}」是内置预设，请换一个名称`,
+  duplicateSaveBlocked: (names) => `已存在内容完全相同的预设「${names}」，请直接使用它，或先修改人设再保存`,
+    builtinDeleteBlocked: (name) => `「${name}」是内置预设，无法删除`,
+    useDone: (name) => `✅ 已应用预设「${name}」`,
+    useUnchanged: (name) => `ℹ 预设「${name}」与当前配置一致，无需变更`,
+    // 预设里部分字段的取值非法（历史值或手改）：合法字段照常应用，被跳过的必须说出来
+    usePartial: (name, fields) => `⚠ 预设「${name}」已部分应用，以下字段取值非法、已跳过：${fields}`,
+    useAllInvalid: (name, fields) => `✗ 预设「${name}」没有可应用的合法字段：${fields}`,
+    personaMissing: (name) => `预设「${name}」不存在`,
+    delDone: (name) => `✅ 已删除预设「${name}」`,
+    listTitle: '📋 人设预设',
+    listEmpty: '暂无人设预设，使用 /soul save <名称> 保存当前配置',
+    // 列表行报告预设实际覆盖的人格维度数量（取代 v0.7.1 起恒为空的「昵称」列）
+    listCovers: (n) => `覆盖 ${n} 项`,
+    saveUsage: '用法：/soul save <名称>（1-30 个字符）',
+    useUsage: '用法：/soul use <名称>',
+    delUsage: '用法：/soul del <名称>',
+    setUsage: '用法：/soul set key=value ...（可用字段：enabled / style / headingLists / emoji / tables / replyLength / language / nickname / occupation / bio / customInstructions / trailEnabled / trailColor / trailSpeed / trailWidth）',
+    unknownField: '未知配置项',
+    invalidBoolean: (key, value) => `${key} 取值必须为 true / false（收到：${JSON.stringify(value)}）`,
+    setNoChanges: '配置无变化，未做修改',
     setDone: (keys) => `✅ 已更新：${keys.join('、')}`,
     help: '使用 /soul show 查看详情\n使用 /soul set style=humorous 修改配置项\n使用 /soul save <名称> 保存预设；/soul use <名称> 应用；/soul list 查看；/soul del <名称> 删除\n使用 /soul confirm 或 /soul reject 处理待确认的人设变更\n使用 /soul reset 重置配置\n使用 /soul enable 启用；/soul disable 禁用\n使用 /soul 昵称xxx 设置昵称',
     resetDone: '✅ 配置已重置为默认值',
@@ -1284,11 +3044,34 @@ const COMMAND_MESSAGES = {
     // 否则一条陈旧提议会一直挂着而无法判断新鲜度（proposedAt 此前只写不读）。
     pendingHint: (at) => `⚠ Pending persona proposal (raised at ${at}): /soul confirm to apply, /soul reject to discard`,
     noPending: 'No pending persona proposal',
+    // 会话覆盖回收报告。格式与中文版逐项对应（两边都由同一次 planSessionGc 驱动）。
+    sessionsGcReport: (plan, apply) => {
+      const lines = []
+      lines.push(apply ? '🧹 Session-scope cleanup' : '🧹 Session-scope cleanup (dry run — nothing deleted)')
+      lines.push(plan.scanComplete
+        ? 'Session list: complete'
+        : `Session list: UNAVAILABLE — ${plan.persistenceProblem || 'unknown reason'}`)
+      lines.push(`Files: ${plan.total} · candidates: ${plan.markable.length} · collectable: ${plan.collectable.length} · corrupt: ${plan.quarantine.length}`)
+      if (!plan.scanComplete) {
+        lines.push('No entry is marked or deleted while the session list is unavailable — "not seen" is not "deleted".')
+      }
+      for (const item of plan.collectable.slice(0, 20)) {
+        lines.push(`  ✕ ${item.sessionId} — ${item.reason}`)
+      }
+      for (const item of plan.quarantine.slice(0, 20)) {
+        lines.push(`  ⚠ ${item.file} — ${item.reason}`)
+      }
+      if (!apply && plan.collectable.length > 0) {
+        lines.push('Run `/soul sessions --apply` to delete the entries listed above.')
+      }
+      return lines.join('\n')
+    },
     confirmDone: (detail) => `✅ Persona changes applied: ${detail}`,
     rejectDone: '✅ Pending persona proposal discarded',
     saveDone: (name) => `✅ Persona "${name}" saved`,
     builtinName: 'built-in',
     builtinSaveBlocked: (name) => `"${name}" is a built-in persona — pick another name`,
+  duplicateSaveBlocked: (names) => `A persona with identical content already exists: "${names}" — use it directly, or adjust the persona before saving`,
     builtinDeleteBlocked: (name) => `"${name}" is a built-in persona and cannot be deleted`,
     useDone: (name) => `✅ Persona "${name}" applied`,
     useUnchanged: (name) => `ℹ Persona "${name}" matches the current config`,
@@ -1330,7 +3113,7 @@ function commandMessages(config) {
 }
 
 // /soul 子命令关键字（命中走子命令；否则整体视为昵称）
-const COMMAND_KEYWORDS = new Set(['show', 'reset', 'enable', 'disable', 'save', 'use', 'list', 'del', 'delete', 'rm', 'set', 'confirm', 'reject'])
+const COMMAND_KEYWORDS = new Set(['show', 'reset', 'enable', 'disable', 'save', 'use', 'list', 'del', 'delete', 'rm', 'set', 'confirm', 'reject', 'sessions'])
 
 // /soul set 中按布尔解析的键；其余键以原始字符串交给 sanitizeConfig 校验
 const COMMAND_BOOLEAN_KEYS = new Set(['enabled', 'trailEnabled'])
@@ -1364,8 +3147,8 @@ function registerCommands(ctx) {
   ctx.inject(['commands'], (cmdCtx) => {
     cmdCtx.commands.register({
       name: 'soul',
-      description: '查看或管理个性化设置。用法：/soul [show|set|save|use|list|del|confirm|reject|reset|enable|disable|昵称]',
-      input: { hint: '[show|set k=v|save <名>|use <名>|list|del <名>|confirm|reject|reset|enable|disable|昵称]' },
+      description: '查看或管理个性化设置。用法：/soul [show|set|save|use|list|del|confirm|reject|reset|enable|disable|sessions|昵称]',
+      input: { hint: '[show|set k=v|save <名>|use <名>|list|del <名>|confirm|reject|reset|enable|disable|sessions [--apply]|昵称]' },
       async handler(invocation) {
         // 保留原始大小写用于昵称/预设名，仅关键字匹配时忽略大小写
         const raw = String(invocation.rawInput || '').trim()
@@ -1383,7 +3166,7 @@ function registerCommands(ctx) {
             if (errors.nickname) {
               return { kind: 'error', text: t.failed(errors.nickname) }
             }
-            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, nickname: patch.nickname }))
+            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, nickname: patch.nickname }), { source: 'command', action: 'nickname' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return { kind: 'success', text: t.nicknameDone(patch.nickname) }
           }
@@ -1427,7 +3210,7 @@ function registerCommands(ctx) {
           if (first === 'reset') {
             // 重置活动配置，但保留人设预设库。
             // 经由逃生口：配置损坏时这是唯一还能落盘的操作（先备份损坏文件）。
-            const { config: updated, promptChanged, backupPath } = await resetConfigWithEscape()
+            const { config: updated, promptChanged, backupPath } = await resetConfigWithEscape({ source: 'command', action: 'reset' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return backupPath
               ? { kind: 'success', text: t.resetRecovered(backupPath) }
@@ -1436,13 +3219,13 @@ function registerCommands(ctx) {
 
           if (first === 'enable') {
             // 写队列内「读—改—写」，不在队列外改写内存缓存对象；无变化时跳过注入
-            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, enabled: true }))
+            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, enabled: true }), { source: 'command', action: 'enable' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return { kind: 'success', text: t.enableDone }
           }
 
           if (first === 'disable') {
-            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, enabled: false }))
+            const { config: updated, promptChanged } = await commitConfig(c => ({ ...c, enabled: false }), { source: 'command', action: 'disable' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return { kind: 'success', text: t.disableDone }
           }
@@ -1453,11 +3236,19 @@ function registerCommands(ctx) {
             if (isBuiltinPersona(personaName)) {
               return { kind: 'error', text: t.builtinSaveBlocked(personaName) }
             }
+            // 重复门禁（0.9.0-q），与 HTTP 路径同一判据
+            {
+              const current = await loadConfig()
+              const dupes = duplicatePersonaConflict(
+                personaSnapshotOf(current), mergePersonas(current.personas), personaName
+              )
+              if (dupes) return { kind: 'error', text: t.duplicateSaveBlocked(dupes) }
+            }
             await commitConfig((current) => {
               const personas = clonePersonas(current.personas)
               personas[personaName] = { ...personaSnapshotOf(current), updatedAt: new Date().toISOString() }
               return { ...current, personas }
-            })
+            }, { source: 'command', action: 'savePreset' })
             return { kind: 'success', text: t.saveDone(personaName) }
           }
 
@@ -1493,7 +3284,7 @@ function registerCommands(ctx) {
             if (names.length === 0) {
               return { kind: 'success', text: `${t.listTitle}\n${t.listEmpty}` }
             }
-            const activeName = findActivePersonaName(config)
+            const activeName = resolveActivePersonaName(config)
             const lines = names.map((personaName) => {
               const entry = view[personaName]
               const styleText = STYLE_VALUES.includes(entry.style) ? (t.styleNames[entry.style] || entry.style) : (entry.style || '-')
@@ -1521,7 +3312,7 @@ function registerCommands(ctx) {
               const personas = clonePersonas(current.personas)
               delete personas[personaName]
               return { ...current, personas }
-            })
+            }, { source: 'command', action: 'deletePreset' })
             return { kind: 'success', text: t.delDone(personaName) }
           }
 
@@ -1555,7 +3346,7 @@ function registerCommands(ctx) {
             if (Object.keys(patch).length === 0) {
               return { kind: 'error', text: t.failed(droppedKeys.length > 0 ? `${t.unknownField}: ${droppedKeys.join(', ')}` : t.setUsage) }
             }
-            const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }))
+            const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...patch }), { source: 'command', action: 'set' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             return { kind: 'success', text: changed.length > 0 ? t.setDone(changed) : t.setNoChanges }
           }
@@ -1564,7 +3355,7 @@ function registerCommands(ctx) {
             if (!pendingPersonaProposal) return { kind: 'error', text: t.noPending }
             const proposal = pendingPersonaProposal
             pendingPersonaProposal = null
-            const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...proposal.patch }))
+            const { config: updated, changed, promptChanged } = await commitConfig(c => ({ ...c, ...proposal.patch }), { source: 'command', action: 'confirm' })
             if (promptChanged.length > 0) refreshPromptAndInject(ctx, updated)
             const detail = Object.keys(proposal.patch).map((key) => `${key}=${JSON.stringify(proposal.patch[key])}`).join(', ')
             return { kind: 'success', text: t.confirmDone(detail) }
@@ -1576,6 +3367,20 @@ function registerCommands(ctx) {
             return { kind: 'success', text: t.rejectDone }
           }
 
+          // —— 会话覆盖回收（0.9.0-f）——
+          //
+          // 刻意收敛成**一个子命令**（`/soul sessions`）而不是散落的 `gc` / `sessions`：
+          // 将来会话覆盖还会有别的运维动作（导出、清空全部），共用一个前缀才不会
+          // 让 `/soul` 的子命令表继续膨胀。
+          //
+          // 默认 dry-run：`/soul sessions` 只列清单，`/soul sessions --apply` 才真删。
+          // 删除是不可逆的，默认值必须站在"不删"那一侧。
+          if (first === 'sessions') {
+            const apply = /\B--apply\b/.test(rest)
+            const plan = await planSessionGc(ctx)
+            return { kind: 'success', text: t.sessionsGcReport(plan, apply) }
+          }
+
           // 理论不可达：关键字表与上方分支一一对应
           return { kind: 'error', text: t.help }
         } catch (err) {
@@ -1619,7 +3424,35 @@ function registerSystemPrompt(ctx) {
         // 代价为 0：我们不使用任何宿主提示词变量（需要上下文时，text 本身就是
         // provider）。关掉它同时让「预览所见」与「真实注入」逐字符一致。
         interpolate: false,
-        text: () => compilePrompt(configCache || DEFAULT_CONFIG)
+        text: (assembly) => {
+          // ⚠️ 必须同步：宿主以 `section.text(context)` 的形式**同步**调用
+          // （dsh-system-prompt 的装配：`typeof entry.text === 'function' ? entry.text(context) : entry.text`），
+          // 返回 Promise 会被当成 section 文本对象塞进提示词。所以这里只做纯字符串
+          // 比较——路径的身份解析（realpath）已在 loadBindings() 里对**键**做过一次。
+          //
+          // ⚠️ 也必须**只取一次快照**：configCache 由写队列整体替换。若这里分两次读
+          // （例如先 configCache、再在 configForCwd 里又读一遍），装配期间发生写入就会
+          // 让同一轮用上两个版本的配置。快照先取，之后全用它。
+          //
+          // `assembly.agent` 在诊断装配时缺席（宿主注释写明 `absent on diagnostics`），
+          // cwdOfAgent 对 undefined 返回 null ⇒ configForCwd 原样返回全局配置。
+          const snap = snapshotConfig()
+          const agent = assembly && assembly.agent
+          // 快照必须**整体**使用：连同索引一起，本轮只取一次。
+          // sessionId 走索引拿 workspaceId；拿不到就让 configForScope 回退到 cwd。
+          const sessionId = sessionIdOfAgent(agent)
+          const workspaceId = sessionId === null ? null : (sessionWorkspaceIndex.get(sessionId) || null)
+          // 会话层覆盖走**内存缓存**（同步），未命中时它会在后台排一次读盘，
+          // 本轮按上层配置走 —— 下一轮生效。装配里绝不能 await。
+          const sessionOverride = sessionOverridesOrNull(sessionId)
+          const resolved = configForScope(snap.value, cwdOfAgent(agent), workspaceId, sessionOverride)
+          const prompt = compilePrompt(resolved.config)
+          // 记下「这一轮实际用的是哪一版」：排查「改了却没生效」时，第一个要回答的就是它。
+          // 只写不读，不影响任何行为（deliveryState 由状态端点序列化给设置页）。
+          deliveryState.lastAssembledRevision = snap.revision
+          deliveryState.lastAssembledScope = resolved.source
+          return prompt
+        }
       })
 
       deliveryState.sectionRegisteredAt = new Date().toISOString()
@@ -1930,7 +3763,7 @@ function registerTools(ctx) {
                 next[key] = patch[key]
               }
               return next
-            })
+            }, { source: 'tool', action: 'setPersona' })
 
             if (changed.length === 0) {
               return { ok: true, message: promptTextOf(updated).toolNoChanges }
@@ -1958,6 +3791,13 @@ function registerTools(ctx) {
 export async function apply(ctx) {
   // 加载配置
   await loadConfig()
+
+  // 加载工作区绑定表。
+  //
+  // 必须在装配路径之外做完：system prompt section 的 text provider 是**同步**的
+  // （见 registerSystemPrompt 里的说明），不能在里面 await 读盘。这里读一次，
+  // 之后每轮装配只做纯字符串比较。失败不阻塞启动（绑定是可选增强）。
+  await ensureBindings()
   
   // 提供 soulConfig 服务
   ctx.provide('soulConfig', {
@@ -1970,7 +3810,7 @@ export async function apply(ctx) {
       if (Object.keys(errors).length > 0) {
         throw new Error('配置校验失败：' + formatFieldErrors(errors))
       }
-      const { config, promptChanged } = await commitConfig(current => ({ ...current, ...patch }))
+      const { config, promptChanged } = await commitConfig(current => ({ ...current, ...patch }), { source: 'service', action: 'update' })
       // 送达与另外三条写路径保持一致：服务调用方（其它插件）改配置后同样应当
       // 立即反映到活动会话，否则「改了配置不生效」会从服务这条路再次出现。
       if (promptChanged.length > 0) refreshPromptAndInject(ctx, config)
@@ -1982,7 +3822,7 @@ export async function apply(ctx) {
     },
     async resetConfig() {
       // 与 HTTP / 斜杠命令两条重置入口共用逃生口
-      const { config, promptChanged } = await resetConfigWithEscape()
+      const { config, promptChanged } = await resetConfigWithEscape({ source: 'service', action: 'reset' })
       if (promptChanged.length > 0) refreshPromptAndInject(ctx, config)
       return config
     }
@@ -1991,9 +3831,14 @@ export async function apply(ctx) {
   // 注册各模块
   registerRoutes(ctx)
   registerPersonaRoutes(ctx)
+  registerHistoryRoutes(ctx)
+  registerBindingRoutes(ctx)
+  registerWorkspaceRoutes(ctx)
+  registerSessionScopeRoutes(ctx)
   registerCommands(ctx)
   registerSystemPrompt(ctx)
   registerTools(ctx)
+  registerWorkspaceIndex(ctx)
 }
 
 export { name }