dsh-gitbash-shell 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## 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(用户报告:点开对话里的文件链接,原生右侧栏显示「文件不存在,可能已被移动或删除」)

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.31.0",
+  "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.31.0",
+  "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/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'

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 {