fix(claude): resume 预检跨桶兜底，修复 /cd 空窗重启后静默丢上下文

[xu4wang]

问题

Claude 家族 CLI 的 transcript 按 cwd 分桶存（<dataDir>/projects/<slug(realpath(cwd))>/<sid>.jsonl），且 /cd 只改未来写入的落点、不回迁已有文件。于是存在一个竞态：会话 /cd 之后、写下任何 turn 之前发生重启（挂起后续起 / daemon 重启 / crash），旧 transcript 孤儿在旧 cwd 的桶里，而 checkResumeTargetExists 只探当前 cwd 的桶 → 判 false（"provably absent"）→ worker 丢弃 --resume、静默新开会话，用户看到：

⚠️ 历史会话（xxx）无法恢复，已为你新起一个干净会话（原因：adapter confirmed resume target does not exist on disk）

整段上下文丢失，且历史文件其实还完好地躺在磁盘上（另一个桶里）。现网已两次踩中（角色切换后的空窗重启是最常见触发路径）。

修法

<sid>.jsonl 在同一 dataDir 下全局唯一。预检当前桶未命中时，扫 projects/ 下兄弟桶，命中则把孤儿 transcript 迁移进当前桶（claude --resume 只认当前 cwd 的桶，迁移是唯一能让它找到文件的方式），随后放行 resume。要点：

• 移动而非拷贝：旧桶留 stale 副本会在日后 /cd 回旧目录时被预检直接命中、resume 到过期上下文，静默丢掉其后的所有 turn（正是本修复要防的形态）。renameSync 失败（EXDEV/权限）降级 copy 后同样尝试 unlinkSync 源文件，删不掉打 stderr 告警（stderr 由 daemon 的 worker-stderr 排水进日志）。
• 多桶命中取 mtime 最新（claude 自身 /cd 后重写会在旧桶留副本）。
• sid 过 UUID 校验才允许动文件（该函数会做 rename，防路径插值）。
• 语义零漂移：rescue 全败时回滚自建的目标桶目录 + probe 侧预先快照 projectDir 存在性，原有 false（干净降级 fresh）/undefined（可能 mid-session 轮换，交给 secondary guard）的分支判定一字不变。
• 迁移成功/失败均有 stderr 日志可排障。

只在 miss 路径触发（每次 spawn 至多一次），每桶一次 statSync，满足接口 "synchronous, cheap" 的要求。

测试

• 新增 test/claude-resume-cross-bucket.test.ts 12 用例：bug 场景复现（A 桶有 transcript、探 B 桶，修复前返回 false）、迁移语义（move 不留源）、当前桶命中不迁移、多桶取最新、copy 降级、全败回滚目录、UUID/穿越拒绝等。12 passed (12)。
• 全量 unit 套件与上游基线对比零回归（失败文件均为基线内环境依赖型集成测试：vc-meeting-daemon-session、v3-distillation-*、v2-run-archive；浮动项单跑均过，属并发 flaky）。
• 真机端到端（真 claude 2.1.210 + 本分支 dist）两轮：
  1. dirA 种暗号 → 用 dist 的 checkResumeTargetExists 探 dirB（触发迁移，返回 true，文件从 A 桶移入 B 桶）→ dirB claude --resume 正确答出暗号。
  2. 最坏场景：Bash 工具飞行中 kill -9 claude，transcript 尾部悬空 tool_use → 跨桶迁移到 dirB → claude --resume 依然完整续回上下文并答出暗号。

关联

与 xu4wang:fix/role-switch-respawn（角色切换改 respawn+resume）配套：该 PR 的 respawn 在新 cwd 探桶，硬依赖本修复接住旧桶 transcript。本 PR 可独立合并（对现有 /cd 冷启动路径本身就是修复）；对方 PR 必须晚于或与本 PR 同时合并。

🤖 Generated with Claude Code

[xu4wang]

状态总结（2026-07-26）

本 PR 的核心场景已被上游独立实现覆盖，不再需要按原样合并。

• 上游 f67940a（「fix(session): 切换目录后保留 Claude 历史会话」，已随 v3.5.2 发布）引入 syncClaudeResumeTargetToCwd：每次冷 resume 前在 worker 层扫描全部 cwd 桶、把该 sessionId 最新的 transcript 镜像进当前桶，随后 adapter 探针 / --resume 才执行。与本 PR 要修的「/cd 空窗重启后 transcript 滞留旧桶 → 上下文静默丢失」是同一场景，且调用点更靠前（worker spawn 预检，覆盖所有 claude-family 路径）。
• 因此 fix(role-switch): 角色切换从会话内注入 /cd 改为带 --resume 的进程 respawn #507（角色切换 respawn+resume）原先「必须与本 PR 配套部署」的依赖也随之解除——上游机制天然接住 respawn 后的跨桶 resume（fix(role-switch): 角色切换从会话内注入 /cd 改为带 --resume 的进程 respawn #507 那边已附评论说明）。
• 本分支未 rebase 到当前 master：改动与上游实现落在同一区域（claude-code.ts），直接 rebase 即冲突，也没有再 rebase 的必要。

两个实现的语义差异（供参考）：上游是 copy + 每次取最新（旧桶留副本，靠 newest-wins 防止旧副本复活）；本 PR 是 move + 迁移相邻 <sid>/ sidecar（tool-results）+ UUID 门 + lstat 不跟随符号链接 + realpath 包含性校验。

上游版仍存在的差量（如维护者有兴趣，可拆成独立小 PR，本 PR 关闭不影响）：

1. sidecar 不随迁：<sid>/（tool-results 等会话侧目录）留在旧桶，切目录 resume 后对旧工具结果的引用可能解析不到——轻度退化，不丢上下文；
2. 符号链接加固：扫描候选用 existsSync/statSync（跟随符号链接）、无 realpath 包含性校验，被植入的 <sid>.jsonl 软链可把 dataDir 外的文件镜像进桶（copy 语义下危害低于 move，威胁模型内属低危）；
3. copy 语义会在走过的每个桶累积 transcript 副本（同 bot 自己的 dataDir 内，磁盘冗余、非泄漏面）。

综上：本 PR 建议关闭，价值收敛为上面 3 点差量的候选改进。

[deepcoldy]

首次 Review（Claude）— 结论：bug 真实、实现扎实，但已被 master 抢先修复；建议 port 增量后 close，不宜按现状合并

先说白话，这个 PR 到底在干什么、为什么冲突。

一、这个 PR 修的是什么（白话）

Claude Code 的对话记录（transcript，<sid>.jsonl）是按“当时的工作目录”分桶存的：~/.claude/projects/<cwd 的 hash>/<sid>.jsonl。botmux 的 /cd（比如角色切换换记忆桶）只改以后写到哪个桶，不搬已经写好的旧文件。

于是有个竞态：/cd 之后、还没写下任何一条新 turn 之前如果发生重启（挂起后重起 / daemon 重启 / crash），旧 transcript 就孤零零留在旧目录的桶里；而 resume 预检（checkResumeTargetExists）只看新目录的桶，一看是空的 → 判 “provably absent” → worker 丢掉 --resume、静默新开一个干净会话，用户看到「⚠️ 历史会话无法恢复」——整段上下文丢了，可文件其实还好端端躺在另一个桶里。

本 PR 的修法：<sid>.jsonl 在同一个 dataDir 下全局唯一，所以当前桶没命中时，去扫兄弟桶，命中就把孤儿 transcript **搬（move）**进当前桶。做得很细致：

• move 而非 copy：旧桶不留 stale 副本，避免日后 /cd 回旧目录时预检直接命中过期 transcript、静默丢掉其间新写的 turn。
• lstat + realpath 包含性校验：拒绝跟随植入的软链，防止把 dataDir 外的文件搬进桶当 transcript。
• 随迁相邻 <sid>/ sidecar 目录（tool-results 等），否则 resume 后工具结果引用取不到。
• UUID 门 + 全败回滚 mkdir 的目录，语义零漂移。

诊断是准的，代码质量高，测试也扎实（15 个单测，我本地 build + 跑通 13 pass / 2 root-skip；master 的既有测试也全绿）。

二、关键问题：master 已经用另一种策略修了同一个 bug

本 PR base 是 0279e160（2026-07-17），但 master 在 1 天后的 f67940ad（2026-07-18，经 #510 窗口合入）已经修了同一个 bug，函数叫 syncClaudeResumeTargetToCwd（claude-code.ts:102），wired 在 worker.ts:6656——每次 resume、在 probe 之前跑，策略是 copy 最新的那份（按 mtime/size/path 排序）跨桶到新 cwd，并保留源。

两者文本冲突（imports 行 + 紧挨 claudeProjectDir 的同一插入点）+ 语义冲突（copy-retain vs move）。我实际 test-merge 到当前 master → CONFLICT。

三、合并态实测：本 PR 的 rescue 会变成死代码

我把 master + 本 PR 手工合并（保留两个函数）、build 通过、双方测试全绿，然后写 harness 复现了合并后的 worker 真实执行顺序：

1. worker.ts:6656 先跑 master 的 syncClaudeResumeTargetToCwd，把孤儿 copy 进目标桶；
2. worker.ts:6679 再跑 probe，首行 if (existsSync(p)) return true（claude-code.ts:699）就短路返回了；
3. 本 PR 的 rescueOrphanClaudeTranscript（claude-code.ts:711）对 canonical /cd 场景永远走不到。

也就是说：本 PR 真正的价值（lstat 软链硬化、sidecar 迁移、move 语义）在合并树里全部失效，只有当 master 的 sync 抛异常且目标文件仍缺失（例如磁盘满——此时 rename 免新 inode 会赢过 copyFileSync）这种极窄路径才轮得到 rescue。合并树会同时留下两套语义相冲的“修复器”，弱的那个（sync）占主导，是明显的维护隐患。

实测佐证：种一个软链 <sid>.jsonl 指向 dataDir 外的文件，master 的 sync 会跟随并把外部文件 copy 进桶（copied:true）；本 PR 的 rescue 单独测会拒绝（lstat + realpath）——但在合并树里这层保护被 sync 抢跑 shadow 掉，等于 ~0 防护。

四、8-agent 对抗复核（供参考）

我跑了一轮对抗验证（3 独立 skeptic + bug-hunt + synthesis），核心结论：

• dead-code / shadowing：UPHELD（sync 与 probe 用的是同一个 sid，不存在 sid 分叉逃逸；唯一 reachable 是 sync 抛异常留空目标）。
• 软链严重度：PARTIAL / low——硬化 delta 真实，但合并树被 shadow；沙盒 bot 下 claudeDataDir=<BOT_HOME>/claude 真绑可写、而 sync 跑在非沙盒 worker，理论上 symlink→denied-file 可成 read-confinement 绕过，但需 adversarial CLI + /cd 窗口；非隔离同 UID 下直接种个普通文件本就能达到同效 → bounded。
• move vs copy：PARTIAL / low——实测 copyFileSync 不保留源 mtime（设为 copy-time），所以在反向时钟步进（NTP step-back / VM 快照恢复）下，master 的 copy-newest 确实可能选中陈旧兄弟丢 turn，move 能避免；但需要“时钟倒退”这一前提，很窄。
• rescue 自身 3 个 nit（mtime 无 size/path tiebreak、containment 只校验 winner 不 fallback runner-up、rename 的 TOCTOU）——仅当 rescue 被扶正为主修复器才会 live。

天花板全是 low，没有 high/medium 阻塞项。

五、关于 companion PR #507

#507 描述里写「本 PR 硬依赖 #506 的 rescueOrphanClaudeTranscript 接住旧桶 transcript，否则每次切角色 100% 丢上下文」。这个硬 gate 依赖其实已被 master 的 sync 满足：#507 现已 rebase 到 master、分支包含 f67940ad、代码里引用 rescueOrphanClaudeTranscript 0 次、引用 syncClaudeResumeTargetToCwd 2 次。所以 #506「不合就必丢上下文」的说法被夸大了（与我对 #507 的 review 同结论）。

六、建议

不建议按现状合并（会引入两套重叠、语义相冲的修复器，且本 PR 的增量被 shadow 到失效）。真正有价值的是把本 PR 的两个 master 缺失的增量移植进 syncClaudeResumeTargetToCwd，然后 close #506：

1. lstat + realpath 包含性校验（claude-code.ts:115-118 那段 candidate 扫描）→ 堵住 master sync 的“跟随软链”洞；
2. sidecar <sid>/ 目录随迁 → 补 master sync 不迁 sidecar 的功能缺口（resume 后 tool-result 引用可能悬空）。
3. move 语义可选（仅“反向时钟”窄收益，可作为一个判断题留给维护者）。

以上是我的首次 review。在 @申晗 明确确认前不合码。 现 @ codex 做独立复审，请把复审结论回给我（Claude）。

---

验证：本地 test-merge（CONFLICT，手工解冲突保留两函数）+ pnpm build 通过；test/claude-resume-cross-bucket.test.ts 13 pass / 2 root-skip、test/claude-code-cwd.test.ts 6 pass；harness 复现合并态 sync-先于-probe 使 rescue 不可达、软链跟随、copyFileSync 不保留 mtime。

[deepcoldy]

Codex 独立复审（2026-07-26）

结论：赞成 port-deltas-to-master + 保持 #506 closed，不建议把两套修复器一起合入。 首审的主判断成立，但“死代码”应精确表述为：canonical /cd 冷恢复路径被完全 shadow；函数并非字面意义上的绝对不可达。

1. sync → probe 的 shadow 判定

我在当前 origin/master（f2c34eee）上手工解冲突保留两函数，确认 worker 与 adapter 使用完全相同的：

• sid：effectiveCliSessionId ?? effectiveAdapterSessionId
• cwd：cfg.workingDir
• dataDir：claudeDataDir

正常孤儿 transcript 场景中：

1. worker.ts 先调用 syncClaudeResumeTargetToCwd；
2. copy 成功后目标 <sid>.jsonl 已存在；
3. adapter probe 首个 existsSync(p) 直接返回 true；
4. rescueOrphanClaudeTranscript 不会执行，所以 move、source 软链拒绝和 sidecar 迁移都没有效果。

合并树 harness 也锁住了这一点：sync 后 source/sidecar 仍留在旧桶，target 只有 jsonl，随后 rescue 返回 undefined。

2. 仍然 reachable-with-effect 的路径

不是严格 0 可达。主要例外是：sync 在目标文件生成前抛错，worker catch 后继续 probe，而 rescue 使用不同的文件操作成功。

我给合并树的 copyFileSync 注入 EIO：sync 抛错、target 仍不存在；随后 probe 中 rescue 通过同文件系统 renameSync 成功，jsonl 与 sidecar 都迁到目标桶，probe 返回 true。现实映射包括 copy 读失败但 rename 权限满足、ENOSPC 下 rename 仍可完成等窄路径。另有极短的扫描竞态（sync stat 时消失/失败、probe 重扫时又可见）。

所以推荐措辞：“正常功能与安全增量被 shadow，rescue 只剩异常兜底价值”，而不是“整函数绝对死代码”。这不改变“不合入双实现”的结论。

3. port 增量的方向合理，但不宜原样搬 rescue 代码

建议把逻辑收敛在唯一的 syncClaudeResumeTargetToCwd，并在单独 follow-up 中一起定义：

• source candidate：UUID gate、lstat 拒绝 final symlink、realpath containment；
• destination 也要 no-follow 校验，不能只加 source 侧硬化；
• sidecar 应与 master 的 copy/retain 策略一致，设计成 copy/merge，而非直接照搬 move；还要处理目标 sidecar 已存在、历史上多个桶已经分裂的情况。PR 当前的 !existsSync(dstSidecar) 整目录搬迁逻辑直接移植会跳过这些状态；
• 落盘最好采用临时文件 + 原子替换/并发校验，避免 scan→copy/rename 的 TOCTOU 与半成品 target。

move vs copy 仍属独立策略选择；当前证据不足以为少量反向时钟风险改掉 master 的 native-history 保留语义。

4. 补充发现：master 的 destination symlink 写穿

首审验证了 sibling source symlink 会被 sync 跟随读取；我另外验证了更强的一侧：如果目标桶的 <sid>.jsonl 是指向 dataDir 外既有文件的 symlink，且 sibling 正常 transcript 更新，master 的 copyFileSync(source, target) 会沿目标 symlink 覆写外部文件。随后 probe 仍首行返回 true，rescue 完全无机会介入。

这说明 follow-up 的软链硬化必须同时覆盖 source 和 target。该问题是 master 现存 delta，不是合入 #506 的理由；#506 自己的 probe 首个 existsSync(target) 也没有完整解决 existing-target-symlink。

验证

• test-merge：当前 master + fix(claude): resume 预检跨桶兜底，修复 /cd 空窗重启后静默丢上下文 #506，文本冲突属实；手工保留两函数。
• pnpm build：通过。
• pnpm exec vitest run test/claude-code-cwd.test.ts test/claude-resume-cross-bucket.test.ts：2 files passed，19 passed / 2 root-skip。
• 合并语义 harness：4/4 passed（canonical shadow、source symlink 跟随、destination symlink 写穿、sync-copy-failure 后 rescue 有效）。

综上，保持 #506 关闭是正确状态；另开小 PR 加固 master 的单一 sync 实现更清晰。未执行任何合码操作。

[deepcoldy]

双审收敛 + PR 已 close（记录）

作者已于 2026-07-26 自行 close 本 PR，与两轮 review 结论一致：本 PR 修的 bug 已被 master 的 syncClaudeResumeTargetToCwd（f67940ad，经 #510 合入）以另一种策略（copy-newest）修复，直接合并会引入两套语义相冲的修复器。

Claude（首审）与 codex（复审）完全收敛：保持 #506 closed，把有价值增量收敛进 master 的单一 sync 实现，不合两套。复审补充/修正三点：

1. canonical /cd 场景的 shadow 判定成立（sync 先于 probe、首行 existsSync 短路，rescue 不触达）。
2. “死代码”措辞收窄为正常路径完全被 shadow，仅异常兜底可达——codex 在合并树注入 copyFileSync=EIO，worker catch 后 probe 中 rescue 用 rename 成功兜底（对齐首审对抗复核里的 disk-full edge）。
3. port 方向正确但不能原样搬：sidecar 要匹配 master 的 copy/retain 语义做 copy/merge 并处理已存在/跨桶分裂；安全校验须同时覆盖 source 和 destination。

并发现 master 现存两个软链洞（均已实测复现，与本 PR 无关，属 master 独立 follow-up）：

• source-side read-follow（首审）：sibling 桶里名为 <sid>.jsonl 的软链指向 dataDir 外文件时，existsSync+statSync 跟随，把外部文件 copy 进桶 当 transcript。
• destination-side write-through（复审，我已独立实测 write-through=true 确认）：目标桶的 <sid>.jsonl 若是指向 dataDir 外既有文件的软链，copyFileSync(source, target) 会跟随并写穿、覆写那个外部文件。

后续若硬化 master syncClaudeResumeTargetToCwd，应同时做 source + destination no-follow（lstat）+ realpath 包含性校验 + 原子落盘（临时文件 + rename）+ sidecar 随迁。是否推进由维护者决定。