[yanzhaohui1999]

三条 issue 一次修掉：worktree 会话的根选择与地址基准

同一场「会话 header cwd 是主检出、agent 在 linked git worktree 里干活」下暴露出来的三条：

issue	症状	失败模式
#947	聊天链接 / 改动页打开 worktree 内文件 → 路径被二次拼接，cannot read "…/wt/frontend/.worktrees/wt/CLAUDE.md": ENOENT	响亮
#950	同一相对路径经不同入口 → 两个检出的同名文件，两次都成功、无任何提示	静默，且可保存写回
#952	工作区内部嵌套仓库的 linked worktree 被当成「活动 worktree」→ explorer 被静默重定根到该子目录，兄弟目录消失	静默

根因

1. 地址的基准是会话 header cwd，宿主两端自洽：宿主构造端 ui-chat 用 fileAddressFor(sessionId, sessions.list.byId[sid].cwd, path)，解析端 api-workspace-files 用 sessions.get(sid).header.cwd —— 同一个值，所以地址里的相对路径只在那个基准下成立。
2. 插件读的一端换成了活动 worktree 根（feat(sidebar): 文件树跟随会话实际所在的 git worktree（含跨仓库 linked worktree） #802）：fs 路由与原生 tab 体跟随活动 worktree，于是同一会话有两个基准。地址里 header 相对的拼写被活动根再拼一次 → 翻倍 ENOENT；两个检出都有同名文件时静默读到另一份。只有「worktree 嵌在 header cwd 之下」才翻倍，所以 feat(sidebar): 文件树跟随会话实际所在的 git worktree（含跨仓库 linked worktree） #802 的跨仓库场景（工作区之外）没暴露它。
3. 同一插件里还有第三、第四个基准：openSidebarFile 用冻结的 summary?.cwd，service.openTab → surface.fileAddress 用调用方手上的 scope.cwd（多数是活动根）→ 同一文件可能拿到两个地址（页签不合并），同一相对路径在不同入口落到不同检出。
4. 根选择判定只看拓扑：activeRootFromEvents 的判据是「top ≠ base 且是 linked worktree」，不区分「会话搬到别的检出」与「工作区里本来就有另一个仓库的 worktree」（bare 仓库的 main/local 检出、容器工作区里的子项目），于是 explorer 被抢根。

口径（决策记录）

工作区内部的 linked worktree 只有属于同一仓库（--git-common-dir 相等）才算「会话搬走了」；工作区外的任何 linked worktree 照旧采纳（#802 的跨仓库场景）。

理由：.worktrees/<branch> 是 DSH 自己的约定，也是 #947 报告者的布局（他三个建议修法里两个假设它继续跟随）；而「工作区里嵌套的另一个仓库」是工作区普通内容，采纳它只会把其它兄弟目录藏起来。另一条候选口径「工作区内一律不采纳」虽然更小，但会连带关掉 .worktrees/ 的跟随，故未采纳。

实现（四条 commit）

commit 1（#952） fix(active-worktree): 工作区内的 linked worktree 只在同仓库时采纳

• 新增 gitIdentityOf(dir)（rev-parse --absolute-git-dir --git-common-dir → {gitDir, commonDir}，进程级缓存，相对拼写按被探测目录归一化）；
• isLinkedWorktree 改走该身份，新增 isAdoptableTop(top, base)：工作区外一律采纳，工作区内只有 commonDir 与 base 相等才采纳，base 是文件系统根时跳过该判定（免得关掉整条功能）。

commit 2（#947 / #950） fix(sidebar): 会话地址的基准统一到会话 header cwd

• 新增 src/client/address-base.ts 的 addressBaseOf(ctx, sessionId)（会话列表里的 header cwd）；
• 消费边界：fileParamsOf(info, base?) 在切 path:line 规格之前把地址路径解析成绝对路径；native 的 editor 类型注入 paramsOf: (info) => fileParamsOf(info, addressBaseOf(ctx, fileSessionIdOf(info))) —— 下游（viewer 的 fs.read、编辑器、目录 watch）只见绝对路径，活动根再无法重定基；
• 构造边界：surface.fileAddress 与 openClaimedNativeFile 都以 addressBaseOf 优先，调用方 cwd 只作回退 → 同一文件只有一个地址（与宿主聊天路径的地址一致，页签照旧合并）；
• 意图侧：openSidebarFile(ctx, sessionId, path, { line?, cwd? }) 的 cwd 是调用方手上的活根（EditorHost / 改动页 / markdown 面板传 useSessionRoot 的结果），相对路径按它解析，缺省才回退 header cwd。

commit 3 文档：docs/plans/2026-10-14-worktree-root-and-address-base.md（含口径 A/B 决策表与实测真值表）、AGENTS §3.4 第 13 条、接入指南 §10 同名条目（消费插件自己也解析文件地址时照同一条规则）。

commit 4（Windows，CI 抓出来的） fix(sidebar): 地址路径按基的分隔符拼写

• 新增 resolveAddressPath(base, path)（在 address-base.ts）：在地址边界把结果折叠成 base 的分隔符风格 —— Windows 上同一文件只有一个拼写（也就只有一个页签身份）；POSIX 原样保留（那里 \ 是合法文件名字符，这也是 resolveSidebarPath 从不在 POSIX 折叠的原因）。
• fileParamsOf 与 openSidebarFile 都改走它；resolveSidebarPath 与其既有断言（tests/paths.spec.ts 钉住的混合拼写）逐字未动。

验证

• 修前复现（真 git worktree + 真函数）：宿主地址构造 → 插件解析 → 真实 /sidebar/api/fs.read 返回
  cannot read "…/.worktrees/947-click-demo/.worktrees/947-click-demo/IN-WORKTREE.md": ENOENT；本机 3080 上真机点击同样命中。
  真值表（三种布局 × 三种口径）逐条实测。
• 判别力：把新用例搬到未改动的 origin/dev 上跑 → tests/active-worktree.spec.ts 挂 2/7（正好是 [Bug] 容器工作区里嵌套仓库的 linked worktree 被当成「活动 worktree」：文件树被静默重定根到该子目录（0.25.0 / 0.26.0 同样存在） #952 的两个场景）、
  tests/worktree-address.spec.ts 挂 4/5（基准相关全部）；本分支 7/7 与 6/6 全绿。
• CI 全绿（run 38592034074）：
  ci 3m04s / ci-windows 8m17s / plugin-mount 3m38s。
  第一次 CI ci-windows 红，是本 PR 新加的 tests/worktree-address.spec.ts 3/5 挂（其余 205 个文件全绿）：
  地址语法在所有平台都是 / 分隔，而 resolveSidebarPath 把它原样拼到 Windows 基上得到 C:\repo\src/a.ts 的混合拼写 ——
  文件树 / git 面板 / 一切 join 来源拼的是 C:\repo\src\a.ts，而编辑器的 tab id 与 dedupeKey 都是路径派生的，
  两种拼写就是两个页签身份。已修在 commit 4（并补了一条平台无关的断言钉住它）。
• 本地门禁：typecheck / lint 干净；pnpm test 2465 passed（唯一失败是 smoke.spec.ts:939 往 $HOME 写被沙箱 EPERM 拒，
  同一条在无关 worktree 上也红，与本 PR 无关）；挂载 lane 本机 8 passed，另 2 条
  （mount.e2e.ts:689 底部终端 .xterm 60s 未挂上、tree-scroll.e2e.ts:253 的 git config not in a git directory）
  在未改动的 origin/dev 上逐条同样失败，已另记、不进本 PR。

评审指引

• 读的顺序：src/active-worktree.ts（commit 1，判定）→ src/client/address-base.ts 与 native/index.ts 的 paramsOf 注入
  （commit 2，基准）→ commit 4 的分隔符折叠；口径 A/B 的决策表与实测真值表在
  docs/plans/2026-10-14-worktree-root-and-address-base.md。
• 唯一公开签名变更：openSidebarFile(ctx, sessionId, path, line?) → openSidebarFile(ctx, sessionId, path, { line?, cwd? })
  （4 个调用点 + 1 条既有用例同步）。
• 一个 PR 关三条 issue（[Bug] worktree 内文件的聊天链接路径被二次拼接（ENOENT）；相对路径会静默打开另一个 worktree 的同名文件 #947 / [Bug] 客户端入口与文件路由使用不同工作区根：同一相对路径静默解析到另一检出的同名文件（worktree 场景） #950 / [Bug] 容器工作区里嵌套仓库的 linked worktree 被当成「活动 worktree」：文件树被静默重定根到该子目录（0.25.0 / 0.26.0 同样存在） #952）：根因是同一处根选择判定 + 同一条地址基准链路，分开发布会出现
  「修了 A 让 B 的复现条件消失或变形」的中间态。若维护者偏好一 issue 一 PR，可按 commit 拆开：
  commit 1 = [Bug] 容器工作区里嵌套仓库的 linked worktree 被当成「活动 worktree」：文件树被静默重定根到该子目录（0.25.0 / 0.26.0 同样存在） #952；commit 2 + 4 = [Bug] worktree 内文件的聊天链接路径被二次拼接（ENOENT）；相对路径会静默打开另一个 worktree 的同名文件 #947 / [Bug] 客户端入口与文件路由使用不同工作区根：同一相对路径静默解析到另一检出的同名文件（worktree 场景） #950；commit 3 = 文档。

残留（本版不做）

worktree 会话里一条裸相对路径的聊天链接（[x](docs/README.md)）由宿主按 header cwd 构造并解析 → 打主检出的同名文件。宿主两端一致，插件无法在不猜的前提下区分「agent 指的是 worktree」；绝对路径修复后已无 ENOENT、也不再静默重定基。要可见性可在页签标题显示解析后的绝对路径，根因属上游 worktree 无感的聊天漏斗。

Refs #947 #950 #952（按仓库惯例，合入 dev 不自动关，等发版后关）