【缺陷】dsh-workspace 写盘时用「尽力而为的路径缓存」裁剪会话名册，会永久删除 cwd 一时解析不出的会话归属

[bringmichael]

（这是缺陷报告，不是提问。涉及包 @deepseek-ai/dsh-workspace，在 0.1.5-rc.2 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.2 均存在。）

一句话

WorkspaceEntity.mutate() 在每一次持久化写入时，用一份「启动时建一次、失败静默」的路径缓存去裁剪 sessionIds；结果是：cwd 在写盘那一刻解析不出来的会话，被从磁盘名册里永久删掉——不报错、不可逆。

影响

• 用户看到「我的历史会话不见了」。会话文件还在磁盘上，丢的是归属记录。
• 不需要用户做任何操作。 触发条件只是「对该工作区的任意一次 mutate」（改标题、调顺序、detach，以及应用自身的启动写入）。
• 我们一台机器上的实测：211 个会话中 79 个掉出分组。其中一次是冷启动——服务起来后、页面加载前，6 个工作区的 updatedAt 在 58 毫秒内被依次盖上、名册同时清空，用户全程零操作。
• 目录越常移动（如云盘迁移）的环境，损失越大。

最小复现

1. 把 /tmp/proj 注册为工作区，在其中建两条会话 → workspace.json 里 sessionIds = [s1, s2]
2. mv /tmp/proj /tmp/proj-moved（或卸载可移动卷 / 让网络盘未就绪）
3. 对该工作区做任意一次写入，例如 workspaceController.rename({ workspaceId, title: "x" })
4. workspace.json 里 sessionIds 变成 []，全程无异常

（注：attachSession 与 session.create 不会触发——它们先做 realpath 校验就抛错了。特意列出，免得复现走偏。）

根因

lib/types/entity.js 的 mutate()：

const sessionIds = changed.sessionIds.filter(id => this.host.sessionPath(id) === changed.path);

sessionPath(id) 取自一份进程启动时建一次的索引（lib/index.js 的 indexHeader）：对每个会话头做 fs.realpath + stat，失败就 catch {} 记入 invalidSessionPaths。此后只有 sessionKnown() 会刷新它——不是周期性、不是自动的。

为什么这是缺陷

同一个过滤条件在同一个文件里出现了两次，位置不同，性质相反：

位置	性质
读侧 getter（entity.js:52）	显示判断——算错了不丢东西，下次还能重算
写侧 mutate（entity.js:141）	销毁动作——一次算错，永久少一条归属

索引回答的是「启动那一刻这个路径能不能解析」，不是「这个会话还存在吗」。拿前者决定后者，等于把「暂时问不到」当成「不存在」。

另外，reportFilteredCandidates() 打的 warn 写的是 "filtered from membership"——读起来像显示过滤，实际是持久化删除；而多数部署里引擎 logger 的输出并不被收集（我们这边外壳日志里一条引擎行都没有），所以这条 warn 事实上没人看得见。

建议改法（最小 diff）

  const changed = fn(current);
- const sessionIds = changed.sessionIds.filter(id => this.host.sessionPath(id) === changed.path);
- if (changed === current && sessionIds.length === current.sessionIds.length) {
+ if (changed === current) {
      throw unchangedSentinel;
  }
- return { ...changed, sessionIds, updatedAt: new Date().toISOString() };
+ return { ...changed, updatedAt: new Date().toISOString() };

现有的 fn 实现都以「原样返回 current」表示无变化，所以哨兵条件依然准确。

若确实想保留清理，建议只清理「会话头在持久层里已不存在」这种确定性缺失，而不是「cwd 一时解析不出」这种不确定状态。

建议测试

给 sessionIds = [a, b]、sessionPath(a) = path、sessionPath(b) = undefined，调一次 setTitle()，断言 sessionIds 仍是 [a, b]。把「不裁剪」那行挖掉，此测试必须变红。

我们这边的现状

用了一个开机插件（只调 attachSession，只加不减）把掉出分组的会话尽量挂回去，但它救不回目录已被永久移走的那一类——恰恰是迁移期最常见的一类。因工作区路径指向的目录被改名，我们有 8 个工作区、79 条会话受影响，已通过改写会话头 cwd + 重命名项目目录修复。

（另：CONTRIBUTING.zh.md 说不接受外部 PR，所以这里只报缺陷、附上我们验证过的改法，供判断。）

---

薄云咨询

[argszero]

This is the second report of exactly this mechanism — the first is #7573 (with #8237 as a second sighting) — and your analysis matches the source I re-read at master (d743267388). Two things in this report are new and worth carrying into any upstream fix, plus one correction.

Confirmed at source

• Read side: packages/workspace/workspace/src/entity.ts:101-102 — the getter filters through the host's header index.
• Write side: entity.ts:202-221 — mutate() runs the same filter before handing the record to table().update. Your read/write asymmetry point is exactly right: the same predicate is a display judgement in one place and a durable deletion in the other.
• The index and its failure recording: packages/workspace/workspace/src/index.ts:179 (invalidSessionPaths), :808-820 (three ways a header is filed invalid — no cwd, not a directory, realpath failed). Note the last one is a transient answer to a permanent question, which is the heart of it.
• The only trace is reportFilteredCandidates() (:836-849), called once from init (:217) — i.e. before the damage, and never at the moment the prune actually lands.

What is new here

The measured cold start is the strongest evidence yet. You observed six workspaces' updatedAt stamped within 58 ms of each other and their rosters emptied simultaneously, with zero user interaction. #7573 named three triggers (rename/move, a transient realpath/stat failure at startup, symlink retarget) but could not show that the application's own startup write is itself a trigger. That turns the exposure window from "the user does something" into "the host boots", which is a much stronger argument for treating the write-side prune as the defect rather than as a cleanup that occasionally misfires.

Your diff is right, and it has a second effect worth stating. With the filter gone, changed.sessionIds already equals the intent, so the sentinel condition collapses to changed === current exactly as you wrote; a no-op then never rewrites the medium — which also removes the boot-time updatedAt stamping you measured. Residual: the record keeps ids whose headers are genuinely gone. The read-side getter still filters those (entity.ts:101-102), so nothing becomes visible that should not be; the record merely stops being compacted. If a compaction is still wanted, it should be driven by a determinate fact (header missing from the persistent store) rather than by a transient one (realpath failed right now).

Correction — the warning exists, but not where it matters

reportFilteredCandidates() does log, with a good reason string (workspace '<id>' filtered session '<id>' from membership: <reason>). The gap is not a missing message, it is that this runs at init, one time, before anything is pruned. The durable deletion at entity.ts:208 emits nothing at all. Your conclusion — that the warning is effectively invisible — holds in practice, for the extra reason you give: engine logger output is not surfaced in a typical deployment shell (you make the same point in #9615).

One boundary, so the repair path is not overshot

Re-attaching a session is validated against the existing directory: attachSession (entity.ts:113-146) reads the header, realpaths its cwd, and refuses if it does not resolve to the workspace path. So after a directory has actually been moved, re-attachment cannot work — the only repair is rewriting the session header's cwd (what you did) or moving the directory back. Rewriting workspace.path instead is not a repair: it would make the entire membership a candidate at once.

An existing plugin for the visibility half

We maintain one for this gap: @argszero/cordis-plugin-workspace-membership-doctor (npm install @argszero/cordis-plugin-workspace-membership-doctor, repo argszero/cordis-plugin-workspace-membership-doctor). It is diagnosis and repair-on-confirmation, and it is built around the distinction your report turns on:

• cause set — sessions whose cwd this process cannot resolve while the workspace still lists them. These are the ones the next write will delete; they are still members right now. This is the pre-damage view reportFilteredCandidates() gives once, at init.
• candidates — sessions whose cwd resolves to a workspace path that does not list them: already pruned.
• ungrouped — cwd is not any workspace path: not damage.

It never repairs automatically, deliberately: an intentional detachSession and a silent prune leave identical records, so an automatic repair would undo one while fixing the other. report → action:'repair' (plan only) → + confirm:true.

It does not stop the durable prune — that has to happen in mutate(). What it removes is the "my sessions quietly disappeared and nothing said so" half.

Source: this discussion (#9615); earlier reports #7573 and #8237.

[klzw12]

同样的问题（Windows 11，重命名工作区目录后 workspaceController is unavailable、全服务链 pending），昨天完整踩了一遍，按楼主的思路修复成功。补充三点排障时发现的细节，供参考：

1. corruption 会被静默吞掉，没有任何日志

listArtifacts 扫描会话时，SessionPersistenceCorruptionError 被 catch 后直接返回空 metadata 并 continue——不符合格式约定的会话会无声地从列表消失，不崩溃、不打日志。我第一次修复时把整个文件解压后重新压缩成单帧，就掉进了这个坑：文件在、服务正常、会话就是不出现，排查很久才意识到是被静默跳过。

2. bootstrap 只在首次初始化时执行

initialized === true 之后启动只刷新 header 索引，不会重新对账 sessionIds。也就是说会话归属一旦被裁剪，即使日志文件已经修好，重启也不会自动回到工作区，还需要手动把 session id 加回 workspace.json 对应工作区的 sessionIds。

3. 会话日志的 zstd 格式（手工修复时要注意）

session.v4.jsonl.zstd 是多帧拼接：第一帧 = 单行 header JSON + 换行符（记录 id / cwd），之后每个持久化批次各一帧，帧带 XXH64 checksum。读取端会单独解压第一帧并校验“恰好一行”，所以不能把整个文件解压再整体重压缩——那样会变成单帧，被上述第 1 点静默吞掉。

已验证的最小修复路径：

1. 物理扫描帧结构，找到第一帧的字节边界
2. 只解压第一帧，把 header 里的 cwd 改为新路径，按原参数（带 checksum）重新压缩这一帧
3. 新第一帧 + 原文件剩余字节原样拼接，覆盖回去
4. 停掉 DSH，手动把该 session id 加回 workspace.json 的 sessionIds，再启动

修完后 247 帧 / 407 事件全部完好，会话完整恢复——用户数据本身没有损坏，纯粹是元数据/注册一致性的问题。