dsh-gitbash-shell 0.30.1 → 0.31.1

package/CHANGELOG.md

@@ -3,6 +3,184 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.31.1 — 2026-09-27
+
+**类型**:fix(issue #12:0.29.1 在 DSH 0.1.7-rc.2 上仍解析到 profile 里的 schemastery 3.18.2,每次 shell 调用报
+`TypeError: config.timeoutMs.get is not a function`)
+
+> 报告者 **tkhs101** 的分析是准确的(根因、复现步骤、建议方向都对)。本条目按他的复现步骤逐条核对后落地。
+
+### 结论:是「我们解析到哪一份 schemastery」的问题,不是用户的配置问题
+
+`@deepseek-ai/schemastery` 在本插件里是 **peer**,由环境提供 —— Node 从**插件文件向上**找 `node_modules`,
+在 hoisted profile 里会先撞上**被其他依赖提升到 profile 根**的旧副本(报告者机器实测:3.18.2,**没有 `volatile()`**),
+而宿主 dsh 自己用的是安装目录里与 shell 包放在一起的 3.18.4(有)。
+
+**用户什么都没做错**:hoisted 布局是 pnpm 的正常产物,旧副本被提升也是其他依赖的正常行为,不需要改任何配置。
+
+### 影响
+
+插件把 `pwsh-sandbox` 关掉、把 `ctx.shell` 换成 Git Bash 之后,它的 Config 因为探测不到 `volatile()`
+退化成普通值,基类随即在 `.get()` 上抛错:
+
+```
+TypeError: config.timeoutMs.get is not a function
+```
+
+**每一次 shell 调用都失败**(包括 `echo hi`),等于 agent 完全没有命令行能力;而**宿主日志全绿**
+(插件行加载成功),报错信息也指不到插件 —— 只能靠卸载插件来确认。卸载即恢复。
+
+### 根因链(每层都有代码位置)
+
+1. `src/shell.js:46` 静态 `import z from '@deepseek-ai/schemastery'` —— 自 v0.24.4 起**一字未改**,
+   所以 **0.29.1 与 0.31.0 带的是同一个缺陷**(报告者不是"版本旧",升级插件修不了)。
+2. Node 解析 → 插件所在 profile 的 `node_modules/@deepseek-ai/schemastery` = **3.18.2**。
+3. `live(schema)` 的判据是 `typeof schema.volatile === 'function'` → 3.18.2 没有 → 返回普通 schema。
+4. 宿主 dsh 0.1.7 的 `LocalBashExecutor` 把这六个字段声明为 `.volatile()`
+   (`packages/shell/bash-local/src/index.ts:100-107`),并在 `assertServiceableBashConfig`(line 80)
+   与 `resolve`(line 124/132)里调 `.get()`。
+5. ⇒ 崩。
+
+**v0.24.4(issue #6)的探测只在「我们碰巧解析到的那份恰好有 `volatile()`」时有效** —— 报告者指出的正是这个软肋。
+
+### 修复
+
+新增 **`src/schemastery.js`**:不再让解析顺序决定用哪份,而是**问宿主**。
+
+- **`hostWantsVolatileRefs(ParentConfig)`** —— 直接调用**宿主自己**的 `SandboxBashExecutor.Config({})`,
+  看 `timeoutMs` 解析成 `{ get() }` 还是普通值。这正是"这个宿主会不会调 `.get()`"的直接读数
+  (0.1.7+ → `true`;≤0.1.6 → `false`),读的是**行为**,不碰任何私有 schema 结构。
+- **候选顺序**:shell 包自己的解析域(权威,与执行器同源)→ 插件自身域。
+- **`chooseCopy` 纯函数**(可测)的判定:
+  - 宿主要 volatile 且**自己的副本能服务** → 保持自己那份(**能服务就不换**)。
+  - 宿主要 volatile 而自己的副本**不能** → **重定向到 shell 包那份**(#12 的修法),并打一行日志说明取自哪里。
+  - 宿主读普通值(≤0.1.6)→ 保持自己那份,**绝不**递一个它不会 `.get()` 的 ref(#12 的镜像错误)。
+  - 宿主答不上来 → 保持 v0.31.0 行为(逐字段探测),**不替宿主猜**。
+  - 宿主明确要而哪儿都没有 → 保留自己那份(**不改变其它行为**)但**大声说明原因**,
+    不再留一个与插件看不出关系的神秘 TypeError。
+- **两个消费点共用同一份缓存解析**(`src/shell.js` 的执行器 Config ↔ `src/index.js` 的行 Config 与旧时代
+  settings 命名空间)—— 否则两处可能拿到不同的 schemastery,设置项与执行器就会各说各话。
+- **静态 peer import 全部消除**(它会让一行加载失败静默杀掉整行 —— v0.24.3 的教训),改由
+  `src/schemastery.js` 内**动态**加载。
+
+### 验证
+
+- `npm test` **123/123**(新增 5 项):宿主行为的三种回答(`true`/`false`/无法判定)、`hasVolatile` 的边界
+  (含抛错的 getter)、`chooseCopy` 的完整矩阵(含"能服务就不换"与"顺序不决定结果")、共享加载器的
+  缓存一致性、两个半都不得静态 import peer。
+- **临时拓扑复现 + 修复对照**(插件域真装 `@deepseek-ai/schemastery@3.18.2`,shell 包域真装 `3.18.4`,
+  且 shell 包用真的 `.volatile()` 声明 Config —— 与 issue 描述逐条对应):
+
+  | 场景 | 修复前 v0.31.0 | 修复后 |
+  |---|---|---|
+  | 新宿主 + 根目录被提升的旧副本(**#12 原场景**) | `timeoutMs = 120000`、`.get` 不存在 → **DISAGREE**(即报告者的崩溃) | `timeoutMs = {}`、`.get` 是函数 → **AGREE**;日志 `schemastery taken from the shell packages instead of this plugin's own resolution (host-volatile-redirected)` |
+  | 旧宿主 ≤0.1.6(读普通值) | — | 两边都是普通值 → **AGREE**(即使 shell 包那份 capable,也**没有被误用**) |
+
+  **判据是「插件与宿主的解析结果是否一致」,不是「有没有 `.get()`」** —— 后者在旧宿主上会给出反向的错误结论
+  (旧宿主拿到 ref 同样是崩)。
+- **第三种组合(宿主要 volatile 而两边都没有)在现实中不可达**:宿主能正常跑,就说明它自己解析到了配套副本,
+  而"shell 包域"正是宿主的域。该分支仍保留 fail-loud 日志作为防御,并由单元测试覆盖。
+
+### 相关
+
+- issue #12(报告者 tkhs101,含完整复现步骤与修复建议)
+- issue #6 / v0.24.4:同一崩溃的**另一方向**(当时是完全没有 volatile 探测)
+
+## v0.31.0 — 2026-09-27
+
+**类型**:fix + feat(用户报告:点开对话里的文件链接,原生右侧栏显示「文件不存在,可能已被移动或删除」)
+
+> 用户原话:**"dsh原生的右侧边栏不支持这种/c/ 路径? 让我们的gitbash插件能不能修复一下这个bug?"**
+> 截图里 tab 标题是 `/c/Users/kanna/sandbox/dsh-remote-app/AGENTS.md`,内容区是那句 not-found。
+
+### 结论:不是 dsh 的 bug,是本插件引入的方言在 UI 侧没有闭环
+
+dsh **设计上只有两种路径拼写**(POSIX 与 Windows 盘符/UNC,见 `dsh-util-workspace-path` 的
+`isAbsoluteWorkspacePath`);MSYS 盘根是本插件教会模型与工具的东西,**官方核心不认识它**。
+修的责任因此在本插件这边 —— 而且这是本插件第一次把方言边界延伸到**浏览器 UI**。
+
+### 根因链(逐层定位,每一层都有代码位置)
+
+1. 右侧栏是官方包 `ui-sidebar-documentpreview`,它的失败文案按错误码 `workspace-file/not-found`
+   映射(locales.ts:27,与截图逐字一致)。
+2. 读文件的宿主实现在 `packages/api/workspace-files/src/index.ts`:所有路径都经
+   `this.ctx.fs.resolve(path, { cwd: workspaceRoot })` / `fs.lstat(path, { cwd })`。
+3. `packages/fs/fs-local/src/fsio.ts:148-150` 在 win32 上就是 **`node:path.resolve(cwd, path)`**。
+4. `/c/Users/...` **不是** node 眼中的绝对路径(`isAbsolute` 只认 `C:\`、`\\server`、posix 根),
+   于是它被解析成 **`<当前盘符>:\c\Users\...`** —— 一个不存在的路径 ⇒ not-found。
+5. 那个 `/c/...` 是从哪来的:对话里的文件链接文本来自 **shell 输出**,而本插件让 shell 说 MSYS 方言。
+   链接打开走 `ui-chat` 的 `openFile` → `fileAddressFor(sessionId, cwd, path)`
+   (`packages/util/workspace-path`):它用 `cwd` 前缀判断"工作区内→转相对路径"。本机实测 session 目录名是
+   `--C-Users-kanna-sandbox--`,即 **cwd 是 Windows 拼写**(`C:/Users/kanna/sandbox`),而链接文本是
+   `/c/Users/kanna/sandbox/...` —— 前缀不匹配 ⇒ 原样保留绝对 MSYS 拼写 ⇒ 第 4 步必然失败。
+
+### 改动
+
+**宿主半(`src/index.js`)**:新增只读路由 `GET /dsh-gitbash-shell/api/pathmap`,返回
+`{ platform, home, tmpDir, gitRoot, mounts }` —— 就是既有翻译层 `buildTranslateEnv()` 的同一份事实
+(挂载表直接从 `GIT_MOUNTS` 生成,不另抄一份),加 `process.platform` 供客户端判断。与工具链路由同款
+loopback + same-origin fence(`fenceToolRequest`;GET 只需 loopback),因为 web 服务器可能绑在 `0.0.0.0`,
+而这个路由会报出账号自己的目录。
+
+**客户端半(`src/client.js`)**:包装 `ctx.sidebarRight` 的 `openResource` 与 `openResourceIn` ——
+官方文档写明**"每一种进入右侧栏的方式都是这两者之一的调用"**(对话文件链接、工具行行号引用、
+文件树的每一行),所以一个包装点覆盖全部入口,**不碰任何 dsh 源码**。
+
+- 地址语法按官方 `file-address.ts` 实现:解析 `dsh-resource://file/{session/<id>|<absolute>}/<path>`
+  (逐段 `encodeURIComponent`、`:` 保留、UNC 空首段),改写后按同一编码规则重建,`?`/`#` 后缀原样保留。
+- **未改变即原样转发原字符串**(不是"重建后看起来一样"),所以没有翻译过的地址绝不会被 URL 往返改动。
+- 转换语义与宿主 `translateMsysPath` 逐例对齐(盘根 → `X:/`、`~` → home、`/tmp` → 用户 TEMP、
+  `/dev/null` → `\\.\NUL`、`/usr` 系 → Git 根);**不实现宿主的 `$VAR` 展开** —— 对话里的路径是文本不是 shell 词。
+- **门是宿主的事实,不是猜测**:`pathRescueActive()` 要求 `/api/pathmap` 已应答且 `platform === 'win32'`。
+  macOS/Linux 宿主**永不**翻译(客户端的 user agent 说明不了路径属于谁的文件系统);fact 未到时也不翻译
+  (退化为打补丁前的行为,而不是赌一把)。
+- **可选注入**:`ctx.inject(["sidebarRight"], …)` 而非写进 `exports.inject` —— 硬注入一个本插件不拥有的服务
+  会让 fiber 在缺该服务的宿主上永久 PENDING(v0.24.0 的 settingsScope 教训)。
+- 包装挂在服务实例上,经 `sctx.effect` 随插件 fiber 卸载并还原原方法。
+
+### 验证
+
+- `npm test` **118/118 全绿**(新增 6 项):
+  - 驱动**真实 bundle**(fake cordis ctx + fake `sidebarRight` 记录收到的地址)覆盖地址语法:
+    盘根 / `~` / `/tmp` / `/usr` / `/etc`、absolute scope、`?line=12` 后缀、UNC 原样、非 file 地址原样、
+    非法转义原样、边界不误伤(`/tmpfoo`、`/usrx`、`/Tmp`、`/ab/c`)、已是 Windows 拼写原样、相对路径原样。
+  - **宿主事实门**:`platform: 'linux'` 与"fetch 未应答"两种情况下地址逐字节原样。
+  - **可逆性**:disposer 还原原方法;`exports.inject` 不得含 `sidebarRight`(静态断言)。
+  - **浏览器镜像与宿主翻译器逐例比对**:23 个输入跑 `_internal.translateMsysPath` 与客户端实现,结果必须相同
+    —— 锁死两边语义漂移。
+  - **真实文件系统实测(win32)**:用本仓库 `package.json` 造 `/c/...` 形式,断言
+    `path.resolve(cwd, msys)` 指向**不存在**的路径(这就是用户看到的 not-found),而救回后的
+    `C:/...` **existsSync 为真** —— bug 与修复都在真文件上量了一遍。
+  - **路由实测**:驱动真实 `apply()`,断言路由注册为 `prefix`、loopback GET 返回 200 且
+    `platform` 等于 `process.platform`、mounts 键序与客户端遍历序一致、非 loopback 返回 403 `not-loopback`。
+- **真机验证(隔离实例,未碰用户正在运行的实例)**:把用户 web profile 复制到一个独立 `DSH_HOME`
+  (Windows 上 `cp -rL` 解引用 pnpm 链接,97M → 366M,5 秒),把插件目录换成**本仓源码**,独立端口起
+  `dsh web`,然后:
+  - 宿主侧:`GET /dsh-gitbash-shell/api/pathmap` 实测 **HTTP 200**,返回
+    `{"platform":"win32","home":"C:/Users/kanna","tmpDir":"C:/Users/kanna/AppData/Local/Temp",
+    "gitRoot":"c:/program files/git","mounts":{…7 项,键序与客户端遍历序一致}}`
+    —— 启动日志出现 `MSYS path map route active at /dsh-gitbash-shell/api/pathmap`。
+  - 客户端侧:首页 `window.__DSH_BOOT__` 里 `dsh-gitbash-shell` 出现 5 次(启动图含本插件);
+    `curl` 它实际会取的 combo URL(`/plugins/??dsh-gitbash-shell/client.js&rev=…`)返回 **200**,
+    内容含完整新代码段且**语法有效**。
+  - **真实浏览器(CDP 驱动 driver 自己的隔离 Chromium,不动用户的浏览器)控制台实测出现**
+    `[gitbash-shell/client] right-sidebar path rescue armed (host spelling restored on open)`
+    —— 这一行在 `ctx.inject(["sidebarRight"], …)` 的回调内部,所以它同时证明:client 半在真实浏览器
+    里 apply、**`sidebarRight` 客户端服务可见、inject 回调被调用、`openResource` 是函数且已被包装**。
+  - 宿主日志随后出现 `path map read by <loopback>` —— **浏览器真的拉到了那份宿主事实**,
+    即 `pathRescueActive()` 在生产链路里会返回 true。
+  - 路由新增一行访问日志(`path map read by <addr>`),既是诊断手段,也是上面这条验证的观测点。
+- **仍未覆盖**:真实 UI 里"点击 `/c/...` 链接 → tab 显示出文件内容"这最后一跳(需要先构造一个带
+  MSYS 路径的会话)。这一跳的两端都被验证过 —— 地址重写(单元矩阵)与宿主可读性(真实文件
+  `existsSync`);用户在重启客户端后即可实测确认。
+
+### 已知边界(如实记录)
+
+- 只有"整体就是一条路径"的链接能被救:`/c/Users/x` 成立;而 shell 输出里**被文本截断/拼接**的路径、
+  以及 `/c` 之外的 MSYS 虚拟根(若宿主探测不到 Git 根,tmpDir/gitRoot 为 null)保持原样 ——
+  退化行为与修复前一致,**不会**产生错误路径。
+- `/dev/null` 这类设备路径即使被点开也没有可读内容(与文件工具一致,EINVAL 如实报错)。
+
 ## v0.30.1 — 2026-09-26
 
 **类型**:fix(用户实测反馈 v0.30.0 的工具列表:点了按钮看不到进度、看不到在装哪一个、看不到报错、还能连点)

package/README.md

@@ -316,7 +316,14 @@ PTC/创造及用户自建模式一律覆盖。
   用户 TEMP 下的路径回显为 `/tmp/...`(与 bash 的 `$TMP` 一致);文件内容与错误结果不动;
   `grep` 的 `matches[].path`)改写回 MSYS 形式;文件内容与错误结果不动;
 - **运行时事实**:向官方 `dsh-shell-env` 注册表贡献 `DSH_PATH_DIALECT=msys`,模型可在执行时
-  核验(随开关实时生效)。
+  核验(随开关实时生效);
+- **右侧栏文件链接(v0.31.0)**:对话里的文件链接带着 `/c/...` 拼写进入 dsh **原生右侧栏**
+  (`ui-sidebar-documentpreview`),而宿主文件系统只认 Windows 盘符/UNC 拼写 —— `/c/...` 会被
+  解析成 `<当前盘符>:\c\...`,于是显示「文件不存在,可能已被移动或删除」。插件在右侧栏的**唯一
+  入口**(`ctx.sidebarRight.openResource`)上把地址还原成宿主拼写,`~` / `/tmp` / `/dev/null` /
+  `/usr` 等挂载点按与工具参数翻译**同一张表**处理;宿主事实经只读路由
+  `GET /dsh-gitbash-shell/api/pathmap` 提供,**只有宿主自报 `win32` 时才改写**
+  (macOS/Linux 宿主永不翻译,事实未到时也不翻译)。**没有改动任何 dsh 源码**,包装随插件卸载还原。
 
 关闭后回到 dsh 原生行为:指示文本为空(组装期直接丢弃,零提示噪声),路径参数与结果元数据
 都不再改写,文件工具收 Windows 路径。**bash 始终是 Git Bash,不受此开关影响**——它只决定

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "main": "./src/index.js",
   "description": "Windows 全模式 Git Bash:用 Git for Windows bash 替换 PowerShell 执行器,并物化 standard/minimal/code/cordis 的 Git Bash 变体 preset。双 era 适配 dsh <= 0.1.1(内置 id 'code')与 >= 0.1.2(改名 'ptc'),启动探测自动选择,preset id 永不变。联动:dsh-ptc-cordis-preset(两者同装时 PTC 创造模式自动物化为 Git Bash 版)+ dsh-better-sidebar(终端 UI 标签与模型 terminal_* 工具自动切到 Git Bash)。",
   "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gitbash-shell",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "description": "Windows 上让 agent 的每条 shell 命令改经 Git for Windows bash 执行;物化四个内置预设的 Git Bash 变体,统一 MSYS 盘根路径方言,侧栏终端接管可开关。· Run every agent shell command through Git for Windows bash on Windows; materialize Git Bash variants of the built-in presets, unify the MSYS drive-root path dialect, and adopt the sidebar terminal behind a switch.",
   "type": "module",
   "repository": {

package/src/client.js

@@ -2452,6 +2452,185 @@ window.__ModuleLoader__.load({
 			);
 		}
 
+		// ── native right-sidebar path rescue (v0.31.0) ───────────────────────
+		//
+		// WHY: while the POSIX dialect is on, the conversation shows MSYS drive
+		// roots (/c/Users/...), and dsh's OWN file links carry that spelling into
+		// the right Sidebar. The Host resolves the path with node:path against
+		// the session cwd, so '/c/Users/x' becomes '<current drive>:\c\Users\x'
+		// and the preview answers "file not found". The plugin introduced that
+		// spelling, so the plugin restores its meaning — at the ONE point every
+		// way into the column passes through: `ctx.sidebarRight.openResource`
+		// (conversation file links, tool-row line references, the file tree).
+		//
+		// SAFETY: the rewrite is driven by the HOST's own platform fact, never by
+		// a guess: nothing is rewritten until `/api/pathmap` reports win32, so a
+		// macOS/Linux Host can never see its paths translated. A path already in
+		// the Host's spelling is returned unchanged, so with the dialect off the
+		// wrapper is a pure pass-through. The wrapper lives on the service
+		// instance and is removed with this plugin's own fiber.
+		var FILE_ADDRESS_PREFIX = "dsh-resource://file/";
+		var PATHMAP_URL = "dsh-gitbash-shell/api/pathmap";
+		/** The Host's MSYS facts, or null until /api/pathmap has answered. */
+		var pathMap = null;
+		var pathMapRequested = false;
+
+		/** Read the Host's platform + mount facts once; never blocks a click. */
+		function loadPathMap() {
+			if (pathMapRequested) return;
+			pathMapRequested = true;
+			try {
+				Promise.resolve(fetch(PATHMAP_URL, { headers: { accept: "application/json" } }))
+					.then(function (response) { return response && response.ok ? response.json() : null; })
+					.then(function (body) {
+						if (body && typeof body === "object" && typeof body.platform === "string") pathMap = body;
+						else console.warn(TAG + " path map unavailable: no rewrite until the host answers");
+					})
+					.catch(function (error) {
+						console.warn(TAG + " path map fetch failed:", error && error.message ? error.message : error);
+					});
+			} catch (error) {
+				console.warn(TAG + " path map fetch threw:", error && error.message ? error.message : error);
+			}
+		}
+
+		/** Whether the Host is a Windows one whose filesystem needs the rewrite. */
+		function pathRescueActive() {
+			return pathMap !== null && pathMap.platform === "win32";
+		}
+
+		/**
+		 * '/c/Users/x' -> 'C:/Users/x', plus the Git Bash mounts the Host's own
+		 * translation layer resolves (~, /tmp, /dev/null, /usr & friends). Mirrors
+		 * src/index.js translateMsysPath WITHOUT its `$VAR` expansion: a path
+		 * rendered in the transcript is text, not a shell word.
+		 */
+		function msysToHostPath(value, env) {
+			if (typeof value !== "string" || value === "") return value;
+			var facts = env || {};
+			if (facts.home && (value === "~" || value.slice(0, 2) === "~/")) {
+				return value === "~" ? facts.home : facts.home + "/" + value.slice(2);
+			}
+			var drive = /^\/([a-z])\/(.*)$/i.exec(value);
+			if (drive) return drive[1].toUpperCase() + ":/" + drive[2];
+			var bare = /^\/([a-z])$/i.exec(value);
+			if (bare) return bare[1].toUpperCase() + ":/";
+			if (value === "/dev/null") return "\\\\.\\NUL";
+			if (facts.tmpDir && (value === "/tmp" || value.slice(0, 5) === "/tmp/")) {
+				return value === "/tmp" ? facts.tmpDir : facts.tmpDir + value.slice(4);
+			}
+			if (facts.gitRoot && facts.mounts) {
+				var mounts = facts.mounts;
+				for (var mount in mounts) {
+					if (!Object.prototype.hasOwnProperty.call(mounts, mount)) continue;
+					if (value === mount || value.slice(0, mount.length + 1) === mount + "/") {
+						return facts.gitRoot + "/" + mounts[mount] + (value === mount ? "" : value.slice(mount.length));
+					}
+				}
+			}
+			return value;
+		}
+
+		/** Component-encode one path segment, keeping ':' literal for drive letters. */
+		function encodeAddressSegment(segment) {
+			return encodeURIComponent(segment).replace(/%3A/gi, ":");
+		}
+
+		/** Encode a '/'-separated path the way dsh's own address builder does. */
+		function encodeAddressPath(path) {
+			return path.split("/").map(encodeAddressSegment).join("/");
+		}
+
+		/**
+		 * Rewrite one `dsh-resource://file/...` address so its path uses the
+		 * Host's spelling. Anything that is not a file address, does not decode,
+		 * or does not change comes back untouched — the caller then forwards the
+		 * ORIGINAL string, so no URL round trip can alter a path we never
+		 * translated.
+		 * @param address - the resource address the Sidebar is about to open.
+		 * @param env - the Host's mount facts, or null.
+		 * @returns the address to open.
+		 */
+		function rescueFileAddress(address, env) {
+			if (typeof address !== "string" || address.slice(0, FILE_ADDRESS_PREFIX.length) !== FILE_ADDRESS_PREFIX) return address;
+			var tail = address.slice(FILE_ADDRESS_PREFIX.length);
+			var cut = tail.search(/[?#]/);
+			var suffix = cut === -1 ? "" : tail.slice(cut);
+			var parts = (cut === -1 ? tail : tail.slice(0, cut)).split("/");
+			var scope = parts.shift();
+			if (scope !== "session" && scope !== "absolute") return address;
+			var sessionId = null;
+			if (scope === "session") {
+				sessionId = parts.shift();
+				if (sessionId === undefined || sessionId === "" || parts.length === 0) return address;
+			}
+			var segments;
+			try {
+				segments = parts.map(decodeURIComponent);
+			} catch (error) {
+				return address;   // a malformed escape is not ours to repair
+			}
+			// '//server/share' keeps an empty first segment; a UNC path is never an
+			// MSYS drive root, so it is left exactly as the Host spelled it.
+			if (scope === "absolute" && segments[0] === "" && segments.length > 1) return address;
+			var path = scope === "absolute" ? "/" + segments.join("/") : segments.join("/");
+			var translated = msysToHostPath(path, env);
+			if (translated === path) return address;
+			var rebuilt = scope === "session"
+				? FILE_ADDRESS_PREFIX + "session/" + encodeAddressSegment(sessionId) + "/" + encodeAddressPath(translated)
+				: FILE_ADDRESS_PREFIX + "absolute/" + encodeAddressPath(translated.replace(/^\/+/, ""));
+			return rebuilt + suffix;
+		}
+
+		/**
+		 * Wrap the navigation controller's ONE address-taking entry point. Every
+		 * way into the right column calls `openResource` (or its per-session twin),
+		 * so one wrapper covers the conversation links, the tool rows and the file
+		 * tree at once — no dsh source is touched, and the wrapper is removed when
+		 * this plugin's fiber is.
+		 */
+		function installPathRescue(ctx) {
+			loadPathMap();
+			try {
+				ctx.inject(["sidebarRight"], function (sctx) {
+					try {
+						var controller = sctx && sctx.sidebarRight;
+						if (!controller || controller.gbPathRescue === true) return;
+						var openResource = controller.openResource;
+						if (typeof openResource !== "function") return;
+						var openResourceIn = controller.openResourceIn;
+						var rescue = function (address) {
+							return pathRescueActive() ? rescueFileAddress(address, pathMap) : address;
+						};
+						controller.openResource = function (address, options) {
+							return openResource.call(this, rescue(address), options);
+						};
+						if (typeof openResourceIn === "function") {
+							controller.openResourceIn = function (sessionId, address, options) {
+								return openResourceIn.call(this, sessionId, rescue(address), options);
+							};
+						}
+						controller.gbPathRescue = true;
+						var restore = function () {
+							try {
+								controller.openResource = openResource;
+								if (typeof openResourceIn === "function") controller.openResourceIn = openResourceIn;
+								delete controller.gbPathRescue;
+							} catch (error) { /* a frozen instance keeps the wrapper; harmless */ }
+						};
+						if (typeof sctx.effect === "function") {
+							sctx.effect(function () { return restore; }, "dsh-gitbash-shell: sidebar path rescue");
+						}
+						console.log(TAG + " right-sidebar path rescue armed (host spelling restored on open)");
+					} catch (error) {
+						console.warn(TAG + " right-sidebar path rescue failed:", error && error.message ? error.message : error);
+					}
+				});
+			} catch (error) {
+				console.warn(TAG + " right-sidebar path rescue wiring failed:", error && error.message ? error.message : error);
+			}
+		}
+
 		// ── plugin ────────────────────────────────────────────────────────────
 
 		exports.name = "dsh-gitbash-shell/client";
@@ -2579,6 +2758,11 @@ window.__ModuleLoader__.load({
 			} catch (error) {
 				console.warn(TAG + " settings card registration failed:", error && error.message ? error.message : error);
 			}
+
+			// The native right Sidebar consumes the very dialect this card gates,
+			// so the rescue is armed on the same mount — and independently of the
+			// card, which must never be taken down by it.
+			installPathRescue(ctx);
 		};
 
 		return module.exports;

package/src/index.js

@@ -55,6 +55,25 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { PRESET_META, minimalPluginsFor, pluginsFor } from './compositions.js'
+import { loadSchemastery } from './schemastery.js'
+
+/**
+ * The executor base class's own Config schema, when this deployment has it.
+ *
+ * Dynamic and optional on purpose: `@deepseek-ai/dsh-bash-sandbox` belongs to
+ * another row of THIS plugin, and a deployment that cannot resolve it must
+ * still mount every other face (the static-peer-import lesson, v0.24.3). What
+ * we need it for is the host's OWN behavioural answer to "do you read your
+ * shell limits through `.get()`?" — see src/schemastery.js.
+ */
+async function executorConfigSchema() {
+  try {
+    const mod = await import('@deepseek-ai/dsh-bash-sandbox')
+    return (mod.SandboxBashExecutor ?? mod.default)?.Config
+  } catch {
+    return undefined
+  }
+}
 
 /**
  * The schemastery module, resolved LAZILY (v0.24.3): `@deepseek-ai/schemastery`
@@ -69,10 +88,15 @@ import { PRESET_META, minimalPluginsFor, pluginsFor } from './compositions.js'
  * verified with a fixture plugin whose only difference was the static peer
  * import. Deferring the import hides the schema where the module is absent
  * instead of killing the row.
+ *
+ * WHICH copy is resolved is no longer left to our own resolution order
+ * (v0.31.1, issue #12): src/schemastery.js asks the host what it expects and
+ * picks a copy that agrees with it. Both call sites share the one cached
+ * answer, so the settings namespace and the executor can never disagree.
  */
 let Schema = null
 try {
-  Schema = (await import('@deepseek-ai/schemastery')).default
+  Schema = (await loadSchemastery({ parentConfig: await executorConfigSchema() })).z ?? null
 } catch (error) {
   Schema = null
   console.warn(
@@ -2415,11 +2439,14 @@ export async function apply(ctx, config = {}) {
   })()
   if (legacySettings) try {
     ctx.inject(['settings'], (sctx) => {
-      Promise.all([import('@deepseek-ai/dsh-settings'), import('@deepseek-ai/schemastery')])
-        .then(([ds, sm]) => {
+      Promise.resolve(import('@deepseek-ai/dsh-settings'))
+        .then((ds) => {
           const settings = sctx && sctx.settings
           if (!settings || typeof settings.register !== 'function') return
-          const Schema = sm.default
+          // The SAME copy the executor and the row Config were built from
+          // (issue #12): one resolution per process, so the two faces of this
+          // plugin can never disagree about the schema vocabulary.
+          if (!Schema) return
           // Era probe: newer dsh register() takes a plain string; the older
           // one accepted the branded helper — one call satisfies both.
           const ns = typeof ds.settingsNamespace === 'function'
@@ -2776,6 +2803,62 @@ export async function apply(ctx, config = {}) {
     }
   }
 
+  // ── MSYS path facts for the browser half (v0.31.0) ───────────────────────
+  // The native right Sidebar receives the path spelling the CONVERSATION
+  // shows. While this plugin's POSIX dialect is on, that spelling is an MSYS
+  // drive root (/c/Users/...), and the Host filesystem resolves it against the
+  // current drive instead — '<drive>:\c\Users\...' — so every file link in the
+  // transcript opens onto "file not found". The browser half rewrites the
+  // resource address before opening it; this route is the fact bag that
+  // rewrite needs. It reports the SAME env the tool-argument translation
+  // already resolves against, plus the platform, so a non-Windows client never
+  // rewrites anything. Read-only and loopback-fenced (a GET needs no Origin),
+  // because the web server may be bound to 0.0.0.0.
+  try {
+    ctx.inject(['webServer'], (wctx) => {
+      try {
+        const route = '/dsh-gitbash-shell/api/pathmap'
+        const mounts = {}
+        for (const [mount, target] of GIT_MOUNTS) mounts[mount] = target
+        const send = (res, code, payload) => {
+          const text = JSON.stringify(payload)
+          res.writeHead(code, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            'content-length': Buffer.byteLength(text),
+          })
+          res.end(text)
+        }
+        const handler = (req, res) => {
+          const fence = fenceToolRequest(req)
+          if (!fence.ok) {
+            console.log(TAG + ' path map request refused (' + fence.reason + ')')
+            send(res, 403, { error: 'forbidden', reason: fence.reason })
+            return
+          }
+          const env = buildTranslateEnv(configuredBashPath)
+          // One line per read: the browser half fetches this once per page load,
+          // so its presence in the log is how a user can tell the rescue is live.
+          console.log(TAG + ' path map read by ' + (req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : '?'))
+          send(res, 200, {
+            platform: process.platform,
+            home: env.home ?? null,
+            tmpDir: env.tmpDir ?? null,
+            gitRoot: env.gitRoot ?? null,
+            mounts,
+          })
+        }
+        const dispose = wctx.webServer.register({ kind: 'prefix', path: route, handler })
+        wctx.effect(() => dispose, 'dsh-gitbash-shell: path map route')
+        console.log(TAG + ' MSYS path map route active at ' + route + ' (read by the browser half)')
+      } catch (error) {
+        console.log(TAG + ' path map route failed: ' + (error?.message ?? error))
+      }
+    })
+  } catch (error) {
+    console.log(TAG + ' path map route wiring failed: ' + (error?.message ?? error))
+  }
+
   // ── winget toolchain route (v0.30.0) ─────────────────────────────────────
   // The settings card's "install / upgrade" buttons. Installing software is a
   // real side effect, so src/tool-runner.js fences the route: only a loopback

package/src/schemastery.js

@@ -0,0 +1,178 @@
+/**
+ * dsh-gitbash-shell/schemastery — resolve the ONE schemastery copy whose
+ * semantics match the executing host, instead of whichever copy Node finds
+ * first.
+ *
+ * WHY THIS MODULE EXISTS (issue #12). `@deepseek-ai/schemastery` is a peer, so
+ * it is resolved by walking UP from this plugin's own file. In a hoisted
+ * profile that walk can land on an OLDER copy another dependency hoisted to the
+ * profile root — measured on the reporter's machine: 3.18.2, which has no
+ * `volatile()` — while the host itself runs the copy installed beside its own
+ * shell packages (3.18.4). The executor's base class comes from the HOST's copy
+ * of `@deepseek-ai/dsh-bash-sandbox`: on dsh 0.1.7+ it declares its limits with
+ * `.volatile()` and reads every one of them through `.get()`
+ * (`packages/shell/bash-local/src/index.ts:100-107`, `assertServiceableBashConfig`).
+ * A subclass whose Config was built from a `volatile`-less schemastery
+ * therefore yields PLAIN values and the first shell call dies with
+ * `TypeError: config.timeoutMs.get is not a function`, taking the whole
+ * `ctx.shell` down with it. Issue #6 was the same crash from the other
+ * direction (an unconditional plain Config); v0.24.4 fixed that with a
+ * per-field `schema.volatile` probe, which only helps when the copy we happen
+ * to resolve HAS `volatile()`.
+ *
+ * The choice is therefore driven by the HOST'S BEHAVIOUR, never by our own
+ * resolution order. Asking the base class what it resolves `timeoutMs` to is a
+ * direct read of "does this host call `.get()`?" — true on 0.1.7+, false on
+ * <= 0.1.6 where plain values are the correct answer. Only when the host wants
+ * Volatile refs do we insist on a copy that provides them, and only then do we
+ * try the parent package's own resolution domain first. An unreadable parent
+ * Config keeps the historical behaviour (our own copy, per-field probe), so an
+ * unknown host is never made worse.
+ */
+
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+/** The peer whose copy must agree with the host. */
+export const SCHEMASTERY_PEER = '@deepseek-ai/schemastery'
+
+/** The package whose resolution domain is authoritative — the executor we extend. */
+export const SCHEMASTERY_PARENT = '@deepseek-ai/dsh-bash-sandbox'
+
+const TAG = '[gitbash-shell]'
+
+/** Node's own answer for `specifier` as seen from `base`, or `''` when it fails. */
+export function resolveFrom(base, specifier) {
+  try {
+    return createRequire(base).resolve(specifier)
+  } catch {
+    return ''
+  }
+}
+
+/** Whether one loaded module looks like a usable schemastery. */
+export function isSchemastery(z) {
+  return !!z && typeof z.object === 'function'
+}
+
+/** Whether one loaded schemastery can produce Volatile refs. */
+export function hasVolatile(z) {
+  if (!isSchemastery(z)) return false
+  try {
+    return typeof z.string().volatile === 'function'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Ask the executing host whether it reads its shell limits through `.get()`.
+ *
+ * `SandboxBashExecutor.Config({})` is the host's OWN schema, built from the
+ * host's own schemastery: it resolves `timeoutMs` to a `Volatile` ref exactly
+ * when the host declares volatile fields. Behaviour, not internals — no private
+ * schema shape is read.
+ *
+ * @param ParentConfig - the base class's `static Config`, if it has one.
+ * @returns `true`/`false` when the host answered, `undefined` when it could not.
+ */
+export function hostWantsVolatileRefs(ParentConfig) {
+  if (typeof ParentConfig !== 'function') return undefined
+  try {
+    const resolved = ParentConfig({})
+    if (!resolved || typeof resolved !== 'object') return undefined
+    return typeof resolved.timeoutMs?.get === 'function'
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Pick one already-loaded copy. Pure, so the matrix is testable without a
+ * filesystem: the caller supplies the candidates and their resolution order.
+ *
+ * @param options - the host's answer, our own entry path, and the loaded copies in priority order.
+ * @returns the chosen copy (or undefined) and why, for the log line.
+ */
+export function chooseCopy({ needsVolatile, ownEntry, copies }) {
+  const own = copies.find((copy) => copy.entry === ownEntry)
+  if (copies.length === 0) return { chosen: undefined, reason: 'unresolved' }
+  if (needsVolatile === false) {
+    // <= 0.1.6 reads plain values: the historical answer is the correct one.
+    return { chosen: own ?? copies[0], reason: 'host-plain' }
+  }
+  if (needsVolatile === true) {
+    // Our own copy is the historical answer: keep it whenever it can serve, and
+    // redirect ONLY when it cannot (that redirection is the whole point of #12).
+    if (own !== undefined && hasVolatile(own.z)) return { chosen: own, reason: 'host-volatile' }
+    const capable = copies.find((copy) => hasVolatile(copy.z))
+    return capable
+      ? { chosen: capable, reason: 'host-volatile-redirected' }
+      : { chosen: own ?? copies[0], reason: 'no-volatile-anywhere' }
+  }
+  // The host could not answer: keep the pre-#12 behaviour (our own copy) rather
+  // than guessing a semantics change on its behalf.
+  return { chosen: own ?? copies[0], reason: 'host-unknown' }
+}
+
+/** Load one module by absolute entry path. */
+async function loadAt(entry) {
+  const mod = await import(pathToFileURL(entry).href)
+  return mod?.default ?? mod
+}
+
+/** One process-wide answer: the module graph does not change under us. */
+let cached = null
+
+/**
+ * Resolve, load, and cache the schemastery copy that matches the executing host.
+ *
+ * @param options - `parentConfig` is the executor base class's `static Config`.
+ * @returns the chosen module (or undefined), where it came from, the host's answer, and the reason.
+ */
+export async function loadSchemastery({ parentConfig } = {}) {
+  if (cached !== null) return cached
+  const needsVolatile = hostWantsVolatileRefs(parentConfig)
+  const ownEntry = resolveFrom(import.meta.url, SCHEMASTERY_PEER)
+
+  const wanted = []
+  const parentEntry = resolveFrom(import.meta.url, SCHEMASTERY_PARENT)
+  if (parentEntry !== '') {
+    const beside = resolveFrom(parentEntry, SCHEMASTERY_PEER)
+    if (beside !== '' && beside !== ownEntry) wanted.push({ where: 'the shell packages', entry: beside })
+  }
+  if (ownEntry !== '') wanted.push({ where: 'this plugin', entry: ownEntry })
+
+  const copies = []
+  for (const candidate of wanted) {
+    try {
+      const z = await loadAt(candidate.entry)
+      if (isSchemastery(z)) copies.push({ where: candidate.where, entry: candidate.entry, z })
+    } catch { /* try the next domain */ }
+  }
+
+  const { chosen, reason } = chooseCopy({ needsVolatile, ownEntry, copies })
+  const result = { z: chosen?.z, source: chosen?.where ?? '', entry: chosen?.entry ?? '', needsVolatile, reason }
+  cached = result
+
+  if (result.z === undefined) {
+    console.warn(`${TAG} ${SCHEMASTERY_PEER} is not resolvable from this plugin or from ${SCHEMASTERY_PARENT}; the row Config surface is absent`)
+  } else if (reason === 'no-volatile-anywhere') {
+    // The one case the plugin cannot paper over: the host calls `.get()` on
+    // plain values, so every shell call would fail. Say so where the user will
+    // see it, instead of leaving a mystery TypeError.
+    console.warn(
+      `${TAG} this host reads its shell limits through .get() but NO resolvable ${SCHEMASTERY_PEER} provides volatile()`
+      + ` (tried: ${wanted.map((w) => `${w.where} -> ${w.entry}`).join('; ') || 'nothing resolved'}).`
+      + ' Shell calls will fail with "config.timeoutMs.get is not a function"; install a dsh whose schemastery matches its own shell packages.',
+    )
+  } else if (chosen.where === 'the shell packages') {
+    console.log(`${TAG} ${SCHEMASTERY_PEER} taken from the shell packages instead of this plugin's own resolution (${reason}): ${chosen.entry}`)
+  }
+  return result
+}
+
+/** Test seam: forget the cached answer. */
+export function resetSchemasteryCache() {
+  cached = null
+}

package/src/shell.js

@@ -43,7 +43,7 @@ import { DEFAULT_GIT_BASH, bashResolutionReport, effectiveConfiguredBashPath, re
 
 /** Re-exported for callers that historically read it here (the value now lives in bash-path.js). */
 export { DEFAULT_GIT_BASH }
-import z from '@deepseek-ai/schemastery'
+import { loadSchemastery } from './schemastery.js'
 
 
 /** Log prefix, matching src/index.js. */
@@ -77,7 +77,10 @@ const SETTINGS_NAMESPACE = 'gitbash-shell'
  * ones. Published schemastery 3.18.2 has no `volatile()`, which is exactly why
  * the probe (not an unconditional call) is required.
  */
-function live(schema) {
+function live(schema, needsVolatile) {
+  // A <=0.1.6 host reads plain values: never hand it a ref it will not `.get()`
+  // (issue #12 — the host's own answer wins over what our copy happens to offer).
+  if (needsVolatile === false) return schema
   return typeof schema.volatile === 'function' ? schema.volatile() : schema
 }
 
@@ -86,16 +89,19 @@ function live(schema) {
  * the smoke test can drive BOTH eras with a recording stand-in instead of
  * depending on which schemastery happens to be installed here.
  * @param z schemastery module (real one, or the test's recorder).
+ * @param needsVolatile - the host's OWN answer from src/schemastery.js: `true`
+ *   forces Volatile refs, `false` forces plain values, `undefined` keeps the
+ *   per-field probe (the historical behaviour, kept for an unreadable host).
  * @returns the object schema for the `gitbash-executor` row.
  */
-export function gitBashShellConfig(z) {
+export function gitBashShellConfig(z, needsVolatile) {
   return z.object({
-    cwd: live(z.string()),
-    timeoutMs: live(z.number().default(120000)),
-    maxTimeoutMs: live(z.number().default(600000)),
-    maxOutputBytes: live(z.number().default(64000)),
-    maxSpillBytes: live(z.number().default(64 * 1024 * 1024)),
-    graceMs: live(z.number().default(3000)),
+    cwd: live(z.string(), needsVolatile),
+    timeoutMs: live(z.number().default(120000), needsVolatile),
+    maxTimeoutMs: live(z.number().default(600000), needsVolatile),
+    maxOutputBytes: live(z.number().default(64000), needsVolatile),
+    maxSpillBytes: live(z.number().default(64 * 1024 * 1024), needsVolatile),
+    graceMs: live(z.number().default(3000), needsVolatile),
     // Our own knob: the base class neither declares nor `.get()`s it, and
     // `get bashPath()` below reads it as a plain value, so it stays plain.
     //
@@ -107,8 +113,21 @@ export function gitBashShellConfig(z) {
   })
 }
 
+/**
+ * The schemastery copy that matches the executing host (see src/schemastery.js).
+ * Resolving our own way can land on an OLDER copy another dependency hoisted to
+ * the profile root — one without `volatile()` — and the executor then declares
+ * plain limits for a base class that calls `.get()` on them: every shell call
+ * dies with `config.timeoutMs.get is not a function` (issue #12).
+ *
+ * Deliberately ONE line, and the ONLY top-level await in this module: the smoke
+ * harness evaluates this body inside `new Function`, where an await cannot
+ * appear, so it swaps exactly this expression for a stub.
+ */
+const schema = await loadSchemastery({ parentConfig: SandboxBashExecutor.Config })
+
 /** Resolved configuration: the local executor's knobs, plus the Git Bash path. */
-export const Config = gitBashShellConfig(z)
+export const Config = schema.z ? gitBashShellConfig(schema.z, schema.needsVolatile) : undefined
 
 /** Git Bash executor — mirrors the shipped bash/pwsh sandbox executors. */
 export class GitBashSandboxExecutor extends SandboxBashExecutor {