dsh-gitbash-shell 0.26.1 → 0.28.0

package/CHANGELOG.md

@@ -3,6 +3,80 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.28.0 — 2026-09-26
+
+**类型**:fix(issue #11 —— Git 没装在 `C:\Program Files\Git` 时,写死的默认 `bashPath` 让每条命令 `spawn … ENOENT`,而整个会话的命令能力归零且无提示)+ feat(fail-loud 引导:弹窗可填写路径 / 可跳转下载)
+
+> 报障:https://github.com/KannaKuron/dsh-gitbash-shell/issues/11(Windows 11,Git 装在 `Q:\Git`;作者是另一台 DSH agent「蓝鲸」,诊断准确、自带 workaround)。两条用户口径逐字确立:**"默认用设置里填的 空的就去默认路径 没有就去用户环境path 和 系统path找 还没有就报错,弹窗让他去下载或者去设置里填写路径,而且要支持点击转跳过去"**;**"绝对不能因为找不到就用pwsh … 绝对不能用wsl"**。
+
+### 一、默认值假设被推翻:解析链接管
+- **起因**:`cordis.patch.yml` 把 `gitbash-executor.config.bashPath` 写成 `C:/Program Files/Git/bin/bash.exe`;Git 装在别处 ⇒ 每条命令 ENOENT。更糟的是本插件撤掉 `pwsh-sandbox` 而 dsh 每进程只允许一个 `ctx.shell`,于是**连原本可用的 pwsh 也一并没了**,且没有任何提示。
+- **新解析链(`src/bash-path.js`,唯一实现;执行器 `src/shell.js` 与翻译层 `src/index.js` 共用同一 memo)**:
+  **设置里填的**(`gitbash-executor` 行 config > `gitbash-shell` 行/设置卡;用 `ctx.loader.resolve('gitbash-executor')` 让翻译层看到同一个显式值,显式值失败也不换别的) → **默认安装位置**(Program Files / Program Files (x86) / ProgramW6432 / LOCALAPPDATA) → **PATH 逐目录 `bash.exe`** → **PATH 上 `git.exe` 反推** → **注册表 `Path`**(HKCU + HKLM,`reg query` 走 argv 数组) → **失败**。
+  `cordis.patch.yml` 的 `bashPath` 默认改为**空串(=自动)**。
+- **只认 Git for Windows(用户第二条口径)**:黑名单先于探测(`system32`/`windowsapps`/`msys`/`cygwin`/`wsl`,归一化后逐段匹配 —— System32 是头号陷阱,它永远在 PATH 上);正向判据 = `<root>/cmd|bin/git.exe` + `<root>/usr/bin/bash.exe` + (`<root>/mingw64` 或 `usr/bin/msys-2.0.dll`);指纹 = `git --version` 含 `.windows.`;**一票否决** = 实跑候选 `bash -c "uname -s"` 必须是 `MINGW32_NT-*`/`MINGW64_NT-*`(`Linux`/`MSYS_NT-*`/`CYGWIN_NT-*` 一律不合格)。全部候选失败 ⇒ `{ ok:false, path:'' }`,**绝不返回替补 shell**。
+- **永不回退(用户第一条口径,写进 AGENTS §4h)**:`pwsh-sandbox` 仍是无条件 `disabled: true`(与 bash 健康无关);`src/shell.js` 每次 argv 都过 `requireBashPath()`,解析失败**直接 throw 带引导的错误**(不再让用户只看到裸 ENOENT);冒烟守卫断言 patch 里没有 `!!js` 条件、执行器源码不出现 `pwsh.exe`/`powershell.exe`/`cmd.exe`/`wsl.exe`/裸 `bash`。
+
+### 二、fail-loud 与可点击引导
+- **启动日志**:完整报告 —— 当前 `bashPath` 取到什么 / 按顺序探测过哪些位置(逐条 code+detail)/ 去哪里改 / 下载链接 / "本插件不会回退到 PowerShell"。
+- **客户端弹窗**(`shell.overlay`,仅 win32 且 `ok:false`;同 boot 一次、`sessionStorage` 记关闭;21 语言新增 6 个 `bashmiss.*` 键):探测清单 + **内联 bashPath 编辑框(写 `configForms` 的同一字段,保存落盘到 profile 的 `cordis.patch.yml`)** + **「去下载 Git for Windows」**(`window.open`,Electron 下走外部浏览器)+ 关闭。
+- **写入判定按宿主的布尔返回值(验收反馈修复,commit 见下)**:`ConfigForm.set()` 的契约是 `Promise<boolean>` = **Host 是否接受这次写入**。原先弹窗与设置卡的 bashPath 保存都**丢掉该返回值**、无条件显示「已保存」⇒ Host 拒绝时会**假成功**(与 §4h「绝不静默假成功」同一条纪律)。现在两处都按 `accepted === true` 决定成败,拒绝时显示 `bash.saveFailed`(21 语言,含"确认路径存在且是 Git for Windows 的 bash / 查看宿主日志"的下一步),并处理"没有 form 座位"这一同类情形(同样是拒绝而不是成功)。
+- **数据通道**:host 半注册 `GET /dsh-gitbash-shell/api/status`(`ctx.inject(['webServer'])` 可选服务,家族既有范式同 dsh-ide-git),客户端**在 effect 里 fetch**(不在 apply 取服务,避开客户端半的取服务竞态);`gitBash` capability 同时**加法**扩展为 `{ active, bashPath, ok, source, configured, tried, downloadUrl }`。
+- **深链实测结论**:官方设置页**没有**公开 API 能跳到指定插件的设置卡 —— `openSettings`/`openSection` 只发给 `settings.launcher`/`settings.onboarding` 占用者,面板开关状态是 `ui-settings-general` 私有的 store,`ctx.shortcuts` 也没有"按 id 执行命令"的入口。因此弹窗**自带编辑器**(用户不必去找设置页),文字指路作为兜底;上游若开放深链 API,这里可以直接换成按钮跳转。
+
+### 三、验证
+- `npm test` **93/93 绿**(新增 7 条:解析链显式优先且**失败不替换** / 默认→PATH 含陷阱拒绝 / 只认 Git(WSL+MSYS2+Cygwin+`.windows.`+`uname` 矩阵)/ 全落空报告含引导与下载链接 / **无回退守卫** / 弹窗形状与 21 语言 / 路由与 capability 形状);`tests/align-official.mjs` 四变体仍逐字节对齐。
+- **真机(隔离 `DSH_HOME` + 插件副本强制 win32 门 + 无头 Chrome/CDP,macOS)**:
+  - 启动日志打出完整报告(15 条探测记录,含 `missing`/`bad-shape` 分类);
+  - `curl /dsh-gitbash-shell/api/status` → `{"ok":false,"platform":"win32",…}`;
+  - **弹窗渲染**:标题「找不到 Git Bash —— 命令无法执行」+ 按钮 `[保存, 去下载 Git for Windows, 关闭]` + **12 条探测清单** + 输入框;
+  - **下载动作**:「去下载」点击后 `window.open` 收到 `https://git-scm.com/download/win`;
+  - **内联编辑**:填入 `Q:/Git/bin/bash.exe` → 保存 → 卡片显示「已保存」,**宿主侧落盘** `profiles/verif/cordis.patch.yml` 的 `bashPath: Q:/Git/bin/bash.exe`;
+  - **一次性**:关闭后刷新页面不再出现(会话内已记)。
+  - 过程中自查修掉一个真缺陷:一次性判定原先写在 render 里(设标志的那次渲染之后的**任何 re-render 都会让弹窗消失**),改为在 effect 中决定 + 本地 state 呈现。
+- **拒绝态实测(隔离实例 + 副本把 host 写入强制为 `false` + 无头 Chrome/CDP)**:`showsSaved=false`、`showsFailure=true`,界面显示
+  「写入失败: 保存未生效:宿主拒绝了这次写入 —— 确认路径存在且是 Git for Windows 的 bash,或查看宿主日志」,零 pageerror;
+  弹窗此时仍有「去下载 Git for Windows」与探测清单作为下一步。`npm test` **94/94**(新增第 8 条守卫:两处写入都必须看布尔返回值、不得出现无条件 `setBashSaved(true)`、21 语言失败文案齐)。
+- **未验证(如实标注,需 issue 作者在 Windows 真机复验)**:注册表 `Path` 兜底、真实 Git 安装布局、WSL/WindowsApps/MSYS2 实机路径的拒绝行为(均为 fake io 单测 + 静态核对);深链不可用是上游能力缺口。
+- 相关:issue #11 https://github.com/KannaKuron/dsh-gitbash-shell/issues/11
+
+## v0.27.0 — 2026-09-25
+
+**类型**:feat(新设置「子代理/队员是否也使用 Git Bash」,默认开启 —— 用户 2026-09-25 追加需求)
+
+### 需求与语义
+用户原话:「gitbash 插件也是专门给个设置是否让子代理或者子队员使用 gitbash,默认启动。」
+
+- **开关 `subagentDialect`(本插件行 Config 的 volatile 布尔,**默认 `true`**;旧宿主 ≤0.1.6 在 settings 命名空间 `gitbash-shell` 声明同名字段,**缺键 = true**)。
+- **开(默认)**:委托代理 —— 子代理(`subagent`/`subagent_fork`)、团队队员(`spawn_teammate` 走 continuable-subagent 的 `spawn`/`fork`)、**嵌套子代理** —— 与主代理享受同一条方言链路。
+- **关**:方言只对主代理生效,委托出去的请求回退官方 shell 语义(提示词不改写、路径参数不翻译、结果/报错不回显为 MSYS、`run_code` 程序字面量不翻译、不下发 `DSH_PATH_DIALECT`)。
+
+### 委托身份的判据(先查清链路,再动代码)
+- 用**会话头**判定:`origin === 'subagent' || delegationDepth > 0` —— 与 dsh 自己的 `packages/deliverables/workspace-changes/src/index.ts:59-60` 同一对字段;由子代理驱动在 `packages/subagent/subagent/src/child-agent.ts:139-155` (`childSessionMeta`) 打上,`spawn`/`fork` 两种 provider 与嵌套深度都走它。
+- 纯函数 `isDelegatedAgent(agent)` + 唯一判定点 `dialectApplies(dialect, agent)`;条件挂在 `assembleContext.agent`(`packages/core/agent/src/dispatch.ts:174` 的 `assembleContextFor` 传 `{ agent, scope }`)与 `exec.agent` / `execution.agent` 上。
+- **未知形状一律视为"非委托"**(保留方言):判定不出来时按主代理处理。
+
+### 覆盖到的五个消费点(全部接同一个 gate,避免"半方言")
+① `system-prompt/assemble` 的源头改写与 run_code 句;② 指令 context 的 `text(context)` provider;③ `tools/execute` 的入参翻译 + 成功面回显;④ `tools/post-execute` 的失败面 `content`/`error.message`;⑤ `shellEnv.resolve(execution)` 的 `DSH_PATH_DIALECT` 事实。
+
+### 能力边界(如实写明,写进 README/AGENTS)
+dsh **每个进程只有一个 shell 执行器**(`ctx.shell` 是单例服务),所以 **Git Bash 二进制本身仍是全局的**,本开关管的是**方言/翻译层**;关闭后委托代理见到与写出的是 Windows 形式路径,而 Git Bash 同样接受 `C:/...`,行为自洽。
+
+### 测试与证据
+- 冒烟 **86/86 绿**:新增 3 条(① `isDelegatedAgent`/`dialectApplies` 矩阵:origin、depth 1/2、root、未知/抛错/`agent` 缺失,以及卡片写入断言;② OFF 时主代理保留、委托代理被挡 + 五个消费点都接 gate 的源码断言;③ 旧宿主/老配置**缺键 = true** 的回退);`tests/align-official.mjs` 四变体仍全绿(本版不动组合)。
+- **真机两态(隔离 `DSH_HOME` + 新建 profile + 插件副本 `link:` 安装,真实 dsh 0.1.7-rc.2,本机 macOS)**:探针用 `ctx.agents.create()` 造**真**的 root / child(`origin:'subagent', delegationDepth:1`)/ nested(depth 2)三个 agent(实测会话头 `undefined` / `"subagent":1` / `"subagent":2`),再对每个 agent 调**真的** `ctx.systemPrompt.assemble({ agent, scope: agent })`:
+
+  | 开关 | main(root) | subagent | nested |
+  | --- | --- | --- | --- |
+  | **默认 ON** | 方言指令 = yes | **yes** | **yes** |
+  | **OFF**(行 Config `subagentDialect: false`) | yes | **no** | **no** |
+
+  ⇒ 两态下委托代理的方言确实不同(指令 context 出现/消失即 gate 的可观测面),主代理两态都保留。
+  **平台说明**:macOS 上方言/执行器面本来被 `process.platform === 'win32'` 门控,本次把**插件副本**的两处组装门(`system-prompt/assemble` 与指令 context)强制打开以取得请求级证据(报告中如实标注);**win32 真机仍未覆盖**(执行器是单例,与方言开关无关,不受本版影响)。
+- 设置卡:方言区新增一行(21 语言 `sub.label`/`sub.hint`),写入本行 `subagentDialect`;文案明确"二进制仍全局、此开关管方言/翻译层"。
+
+- 相关:用户需求(2026-09-25 追加);实现不变量见 AGENTS.md §4g,验证装置见「验证清单」第 8 条。
+
 ## v0.26.1 — 2026-09-25
 
 **类型**:fix(v0.26.0 的 workflow 互斥按「意图」而非「生效态」收敛:后端不可用时用户会白丢 workflow 能力)

package/README.md

@@ -101,6 +101,22 @@ dsh-ptc-cordis-preset 报告它的 `PTC 创造模式` 已经是 Git Bash 版。
 0.24.x 的四个变体逐字不变;判定细节、生效时机与两侧同步方式见下方
 [「与 dsh-ptc-cordis-preset 联动」](#与-dsh-ptc-cordis-preset-联动)。
 
+### 子代理/队员是否也用 Git Bash:`subagentDialect`(默认开,v0.27.0)
+
+```yaml
+- id: gitbash-shell
+  config:
+    subagentDialect: true   # 默认;false = 方言只对主代理生效
+```
+
+默认开启时,子代理、团队队员(含嵌套子代理)与主代理走**同一条**方言链路:提示词里的路径同样是 `/c/...` 形式、
+路径参数同样被翻译、结果与报错同样回显为 MSYS 形式、`run_code` 程序里的路径字面量同样被翻译,`DSH_PATH_DIALECT` 环境事实也照常下发。
+关闭后这些**只对主代理生效**:委托出去的请求保持官方 shell 语义(提示词不改写、路径参数原样传递),适合"子代理要跑原生 Windows 工具链"的场景。
+
+> 能力边界(如实说明):dsh **每个进程只有一个 shell 执行器**(`ctx.shell` 是单例服务),所以 Git Bash **二进制本身仍是全局的**,
+> 这个开关管的是**方言/翻译层**,不是"换一个 shell"。关闭后委托代理见到与写出的是 Windows 形式路径(`C:/...`),Git Bash 同样接受,行为自洽。
+> 委托身份的判据用会话头的 `origin === 'subagent'` / `delegationDepth > 0`(与 dsh 自身一致),判定不出来时按主代理处理(保留方言)。
+
 配合 `agent-presets` 的 `default`,新会话直接落在 Git Bash 模式,免去每次在
 模式选择器里翻找(原版 shipped 模式无法替换或隐藏——部署级、只读):
 
@@ -110,6 +126,27 @@ dsh-ptc-cordis-preset 报告它的 `PTC 创造模式` 已经是 Git Bash 版。
     default: ptc-cordis   # 或 standard-gitbash / minimal-gitbash
 ```
 
+## bash 从哪里来:解析链与失败引导(v0.28.0,issue #11)
+
+`bashPath` **默认留空 = 自动探测**;解析顺序就是契约:
+
+1. **设置里填的**(显式值优先,失败也不会被别的路径顶替):
+   `gitbash-executor` 行 config 的 `bashPath` > `gitbash-shell` 行 / 设置卡的「Git Bash 路径」;
+2. **默认安装位置**:`C:/Program Files/Git/bin/bash.exe`、`%ProgramFiles(x86)%\Git`、`%ProgramW6432%\Git`、
+   `%LOCALAPPDATA%\Programs\Git\bin\bash.exe`;
+3. **PATH**(用户 PATH + 系统 PATH,进程内已合并)逐目录找 `bash.exe`;
+4. **PATH 上的 `git.exe` 反推** `<gitdir>/../bin/bash.exe`;
+5. **注册表 `Path`**(`HKCU\Environment`、`HKLM\...\Session Manager\Environment`)——覆盖"GUI 启动时 PATH 快照过期";
+6. **全落空 ⇒ 报错 + 引导**(启动日志一份完整报告,客户端弹一次引导框)。
+
+> **只认 Git for Windows 的 bash。** WSL(`C:\Windows\System32\bash.exe`,永远在 PATH 且排序靠前)、
+> WindowsApps 别名、MSYS2、Cygwin 的 bash **一律拒绝**;候选还要通过 Git 布局(`usr/bin` + `cmd\git.exe` +
+> `mingw64`)、`git --version` 的 `.windows.` 指纹,以及**实跑 `bash -c "uname -s"` 必须是 `MINGW*_NT-*`**。
+>
+> **本插件不会回退到 PowerShell / cmd / 任何其它 shell。** 找不到 Git Bash 就是找不到:设计如此 ——
+> 装了本插件就是要用 Git Bash,偷偷换一个能跑的顶上是错的。失败时弹窗给两件事:在弹窗里**直接填 bashPath**
+> (写入设置卡同一字段)或**去下载 Git for Windows**;同一 boot 只弹一次,可关闭。
+
 ## 配置(执行器)
 
 `gitbash-executor` 行支持:

package/cordis.patch.yml

@@ -32,7 +32,11 @@
       disabled: !!js process.platform !== 'win32'
       config:
         timeoutMs: 60000
-        bashPath: "C:/Program Files/Git/bin/bash.exe"
+        # EMPTY = AUTO (v0.28.0, issue #11): the shared resolver walks
+        # setting > default install paths > PATH > registry PATH, and accepts
+        # ONLY Git for Windows' bash. A hard-coded C: path here made a Git
+        # installed elsewhere (e.g. Q:/Git) look like "dsh is broken".
+        bashPath: ""
 
     # Row id 'gitbash-shell' (was 'gitbash-presets' through v0.23.0): dsh >= 0.1.7
     # keys a plugin's live Config form and the one-shot legacy settings.yaml

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "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.26.1",
+  "version": "0.28.0",
   "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/bash-path.js

@@ -0,0 +1,371 @@
+/**
+ * dsh-gitbash-shell — Git for Windows bash RESOLUTION (issue #11).
+ *
+ * One resolver, used by BOTH the executor (src/shell.js) and the path-dialect
+ * translation layer (src/index.js). Before v0.28.0 the translation layer
+ * probed PATH on its own while the executor kept whatever `bashPath` the patch
+ * hard-coded, so a Git installed outside `C:/Program Files/Git` produced
+ * "translation works, the shell does not exist" — the split this module ends.
+ *
+ * THE TWO HARD RULES (user, 2026-09-25; see AGENTS.md §4h):
+ *   1. Never substitute another shell. No pwsh, no cmd, no WSL bash, no
+ *      "temporarily keep something runnable": an unresolved bash is a FAILURE
+ *      with guidance, never a silent downgrade.
+ *   2. Only Git for Windows' own bash counts. WSL's starter
+ *      (`C:\Windows\System32\bash.exe`, always on PATH), the WindowsApps
+ *      alias, MSYS2's and Cygwin's bash are REJECTED — they speak a different
+ *      path world, so using one is worse than finding none.
+ *
+ * The resolver is deliberately injectable: every filesystem/process fact
+ * arrives through `io`, so the whole chain is unit-testable off-Windows.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** The historical default — still the FIRST default-path candidate. */
+export const DEFAULT_GIT_BASH = 'C:/Program Files/Git/bin/bash.exe'
+
+/** Where a user without Git for Windows should go. */
+export const GIT_BASH_DOWNLOAD_URL = 'https://git-scm.com/download/win'
+
+/**
+ * Path fragments (on the NORMALIZED path) that disqualify a bash outright.
+ * `system32` and `windowsapps` are WSL's two delivery points; `msys`/`cygwin`
+ * are the sibling Unix emulations; `wsl` catches distro-installed shims.
+ */
+export const REJECTED_BASH_MARKERS = ['system32', 'windowsapps', 'msys', 'cygwin', 'wsl']
+
+/** `git version 2.54.0.windows.1` — only Git for Windows prints this. */
+export const GIT_WINDOWS_VERSION_MARKER = '.windows.'
+
+/** The final veto: what `bash -c 'uname -s'` must print on Git for Windows. */
+export const GIT_BASH_UNAME = /^MINGW(32|64)_NT-/
+
+/** Exit codes/sources reported back to the caller. */
+export const BASH_SOURCES = ['configured', 'default', 'path', 'path-git', 'registry']
+
+/**
+ * Normalize a Windows path for comparison: forward slashes, lowercase, no
+ * duplicate separators, no trailing separator. Short (8.3) names cannot be
+ * expanded without the filesystem, so callers on Windows pass the resolved
+ * path when they have one.
+ * @param {unknown} value - candidate path.
+ * @returns {string} the normalized form ('' for non-strings).
+ */
+export function normalizeBashPath(value) {
+  if (typeof value !== 'string') return ''
+  return value.replace(/\\/g, '/').replace(/\/+/g, '/').replace(/\/+$/, '').toLowerCase()
+}
+
+/**
+ * Does this path point at something that is NOT Git for Windows' bash? The
+ * blacklist runs BEFORE any filesystem probe, so a WSL starter on PATH is
+ * never even considered a candidate (issue #11's head trap: System32 is
+ * always on PATH and sorts first).
+ * @param {unknown} candidate - candidate path.
+ * @returns {string|undefined} the matched marker, or undefined when clean.
+ */
+export function rejectedBashMarker(candidate) {
+  const path = normalizeBashPath(candidate)
+  if (path === '') return undefined
+  const segments = path.split('/')
+  for (const marker of REJECTED_BASH_MARKERS) {
+    // Whole-segment matches only: "C:/tools/msys2/usr/bin/bash.exe" is caught by
+    // the `msys2` segment? No — by `msys` as a substring of that segment, which
+    // is exactly what we want (msys2, msys64, msys32). `system32`/`windowsapps`
+    // are full segments in practice; match the segment both ways.
+    for (const segment of segments) {
+      if (segment === marker || segment.includes(marker)) return marker
+    }
+  }
+  return undefined
+}
+
+/**
+ * The Git root a bash path implies (`<root>/bin/bash.exe` → `<root>`), or ''
+ * when the shape is wrong.
+ * @param {unknown} bashPath - candidate bash path.
+ * @returns {string} the normalized root, or ''.
+ */
+export function gitRootOfBash(bashPath) {
+  const path = normalizeBashPath(bashPath)
+  const parts = path.split('/')
+  if (parts.length < 2 || parts[parts.length - 1] !== 'bash.exe') return ''
+  return parts.slice(0, -2).join('/')
+}
+
+/**
+ * Validate one candidate as Git for Windows' bash. Every step is a hard
+ * requirement; the first failure decides the rejection code.
+ * @param {string} candidate - absolute candidate path.
+ * @param {object} io - injected facts (see {@link defaultIo}).
+ * @returns {{ok: true, path: string, root: string, gitExe: string}
+ *   | {ok: false, code: string, detail: string}} the verdict.
+ */
+export function classifyBashCandidate(candidate, io) {
+  const marker = rejectedBashMarker(candidate)
+  if (marker !== undefined) {
+    return { ok: false, code: 'rejected-shell', detail: 'path matches the "' + marker + '" exclusion (WSL/MSYS2/Cygwin are not Git Bash)' }
+  }
+  const root = gitRootOfBash(candidate)
+  if (root === '') return { ok: false, code: 'bad-shape', detail: 'not a <git-root>/bin/bash.exe shape' }
+  if (!io.exists(candidate)) return { ok: false, code: 'missing', detail: 'file does not exist' }
+  // Git for Windows layout: a git binary beside it AND the MSYS runtime.
+  const gitExe = [root + '/cmd/git.exe', root + '/bin/git.exe'].find((path) => io.exists(path))
+  if (gitExe === undefined) return { ok: false, code: 'no-git-exe', detail: 'no cmd/git.exe or bin/git.exe under ' + root }
+  if (!io.exists(root + '/usr/bin/bash.exe')) return { ok: false, code: 'no-usr-bin', detail: 'no usr/bin/bash.exe under ' + root }
+  if (!(io.exists(root + '/mingw64') || io.exists(root + '/usr/bin/msys-2.0.dll'))) {
+    return { ok: false, code: 'no-mingw', detail: 'no mingw64/ and no usr/bin/msys-2.0.dll under ' + root }
+  }
+  // Version fingerprint: only Git for Windows prints `.windows.`.
+  const version = io.gitVersion(gitExe)
+  if (typeof version !== 'string' || !version.includes(GIT_WINDOWS_VERSION_MARKER)) {
+    return { ok: false, code: 'not-windows-git', detail: (version === undefined ? 'git --version failed' : 'git --version = "' + version + '"') + ' (no "' + GIT_WINDOWS_VERSION_MARKER + '" marker)' }
+  }
+  // The final veto: run the candidate itself.
+  const uname = io.uname(candidate)
+  if (typeof uname !== 'string' || !GIT_BASH_UNAME.test(uname.trim())) {
+    return { ok: false, code: 'not-git-bash', detail: "bash -c 'uname -s' = " + (uname === undefined ? 'failed' : JSON.stringify(uname)) + ' (not MINGW*_NT-*)' }
+  }
+  return { ok: true, path: candidate, root, gitExe }
+}
+
+/**
+ * The ordered candidate chain for one resolution, WITHOUT validation. Order is
+ * the contract (issue #11): explicit setting → default install locations →
+ * PATH → git.exe reverse lookup → registry PATH (the last one only helps when
+ * the process PATH snapshot predates a user's PATH edit).
+ * @param {object} input - resolution input.
+ * @param {string} input.configured - explicit path ('' = none).
+ * @param {object} io - injected facts.
+ * @returns {{path: string, source: string}[]} the ordered candidates.
+ */
+export function bashCandidates({ configured }, io) {
+  const out = []
+  const explicit = typeof configured === 'string' ? configured.trim() : ''
+  if (explicit !== '') {
+    out.push({ path: explicit, source: 'configured' })
+    return out // an explicit setting is the user's answer; never substitute it
+  }
+  for (const path of io.defaults()) out.push({ path, source: 'default' })
+  for (const path of io.pathBashCandidates()) out.push({ path, source: 'path' })
+  for (const path of io.gitReverseCandidates()) out.push({ path, source: 'path-git' })
+  for (const path of io.registryBashCandidates()) out.push({ path, source: 'registry' })
+  return out
+}
+
+/**
+ * Resolve the Git for Windows bash to run. Pure w.r.t. every fact it needs —
+ * all of it arrives through `io`, which is why the whole chain (including the
+ * Windows-only registry step) is unit-testable anywhere.
+ * @param {object} [options] - resolution options.
+ * @param {string} [options.configured] - explicit `bashPath` from config.
+ * @param {object} [options.io] - injected facts; defaults to the real ones.
+ * @returns {{ok: boolean, path: string, root: string, gitExe: string, source: string,
+ *   tried: {path: string, source: string, code: string, detail: string}[],
+ *   configured: string}} the verdict, with the full probe list for guidance.
+ */
+export function resolveGitBash(options = {}) {
+  const io = options.io ?? defaultIo()
+  const configured = typeof options.configured === 'string' ? options.configured.trim() : ''
+  const tried = []
+  const rejected = []
+  for (const candidate of bashCandidates({ configured }, io)) {
+    let verdict
+    try {
+      verdict = classifyBashCandidate(candidate.path, io)
+    } catch (error) {
+      verdict = { ok: false, code: 'probe-failed', detail: String(error && error.message ? error.message : error) }
+    }
+    if (verdict.ok) {
+      return { ok: true, path: verdict.path, root: verdict.root, gitExe: verdict.gitExe, source: candidate.source, tried, rejected, configured }
+    }
+    tried.push({ path: candidate.path, source: candidate.source, code: verdict.code, detail: verdict.detail })
+    rejected.push(verdict.code)
+  }
+  return { ok: false, path: '', root: '', gitExe: '', source: '', tried, rejected, configured }
+}
+
+/**
+ * The fail-loud report for one resolution — the text a user reads in the host
+ * log when Git Bash could not be resolved. It states the design rather than
+ * blaming the environment: this plugin will NOT fall back to another shell.
+ * @param {object} resolution - a {@link resolveGitBash} result.
+ * @returns {string} the multi-line report.
+ */
+export function bashResolutionReport(resolution) {
+  const lines = []
+  if (resolution.ok) {
+    lines.push('Git Bash resolved from the ' + resolution.source + ' source: ' + resolution.path)
+    if (resolution.tried.length > 0) {
+      lines.push('  (probed first, rejected: ' + resolution.tried.map((row) => row.path + ' [' + row.code + ']').join(', ') + ')')
+    }
+    return lines.join('\n')
+  }
+  lines.push('Git Bash could NOT be resolved — the shell is unavailable by design, not broken: this plugin never falls back to PowerShell, cmd or a WSL/MSYS2/Cygwin bash.')
+  lines.push(resolution.configured === ''
+    ? '  bashPath is empty, so the automatic chain ran (setting > default install paths > PATH > registry PATH).'
+    : '  bashPath is set to "' + resolution.configured + '" and that value was rejected; nothing else is substituted.')
+  if (resolution.tried.length === 0) lines.push('  probed: (nothing — no candidate was produced)')
+  for (const row of resolution.tried) lines.push('  probed [' + row.source + '] ' + row.path + ' -> ' + row.code + ' (' + row.detail + ')')
+  lines.push('  fix: set the "Git Bash path" field in this plugin\'s settings, or install Git for Windows: ' + GIT_BASH_DOWNLOAD_URL)
+  lines.push('  note: only Git for Windows\' own bash is accepted; WSL (/Windows/System32/bash.exe), the WindowsApps alias, MSYS2 and Cygwin are refused on purpose.')
+  return lines.join('\n')
+}
+
+
+/**
+ * The explicit `bashPath` a SETTINGS row carries, read the era-aware way (the
+ * exact double shape src/index.js uses for better-sidebar's namespace): on
+ * dsh <= 0.1.6 through `settings.get(ns).bashPath`, on >= 0.1.7 through
+ * `settings.describe()`'s own row. Never throws; a missing service reads ''.
+ * @param {object} ctx - a context exposing `settings`.
+ * @param {string} [ns] - the settings namespace/row id (default this plugin's).
+ * @returns {string} the configured path, '' when unset or unreadable.
+ */
+export function settingsBashPath(ctx, ns = 'gitbash-shell') {
+  try {
+    const settings = ctx && typeof ctx.get === 'function' ? ctx.get('settings') : undefined
+    if (!settings) return ''
+    if (typeof settings.get === 'function') {
+      const value = settings.get(ns)
+      return value && typeof value === 'object' && typeof value.bashPath === 'string' ? value.bashPath : ''
+    }
+    if (typeof settings.describe === 'function') {
+      const entry = settings.describe().find((row) => row !== null && typeof row === 'object' && row.ns === ns)
+      const value = entry === undefined ? undefined : entry.value
+      return value && typeof value === 'object' && typeof value.bashPath === 'string' ? value.bashPath : ''
+    }
+    return ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Merge the explicit tiers of the chain: the row's OWN config wins over the
+ * settings row, which wins over empty (which means "run the automatic chain").
+ * The order is the contract (issue #11): an explicit answer is never
+ * substituted, and an empty one is not an answer at all.
+ * @param {unknown} ownRowValue - `gitbash-executor` row config's `bashPath`.
+ * @param {unknown} settingsValue - the `gitbash-shell` row/settings `bashPath`.
+ * @returns {string} the explicit path to resolve with.
+ */
+export function effectiveConfiguredBashPath(ownRowValue, settingsValue) {
+  const own = typeof ownRowValue === 'string' ? ownRowValue.trim() : ''
+  if (own !== '') return own
+  return typeof settingsValue === 'string' ? settingsValue.trim() : ''
+}
+
+
+/**
+ * The `gitbash-executor` ROW's own `bashPath` — the highest-priority tier.
+ * Read through the Loader's public `resolve(id)` (the row id is part of this
+ * plugin's own bundle patch), so the translation layer sees the same explicit
+ * value the executor row carries instead of quietly resolving a different
+ * one. Absent row / absent config / any loader shape change reads ''.
+ * @param {object} ctx - a context exposing `loader`.
+ * @returns {string} the row's configured path, '' when unset.
+ */
+export function executorConfiguredBashPath(ctx) {
+  try {
+    const entry = ctx && ctx.loader && typeof ctx.loader.resolve === 'function'
+      ? ctx.loader.resolve('gitbash-executor')
+      : undefined
+    const value = entry && entry.options ? entry.options.config : undefined
+    return value && typeof value.bashPath === 'string' ? value.bashPath : ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * The real `io`: filesystem probes, the Windows registry PATH read (argv
+ * arrays, never a shell string) and the two subprocess fingerprints.
+ * Every call is defensive — a probe that throws is a candidate that fails,
+ * never a crash.
+ * @returns {object} the production io.
+ */
+export function defaultIo() {
+  const run = (file, args) => {
+    try {
+      return String(execFileSync(file, args, { encoding: 'utf8', timeout: 5000, windowsHide: true })).trim()
+    } catch {
+      return undefined
+    }
+  }
+  const registryPath = (hive, key) => {
+    const out = run('reg', ['query', hive + '\\' + key, '/v', 'Path'])
+    if (typeof out !== 'string') return []
+    const match = /Path\s+REG_(?:EXPAND_)?SZ\s+(.*)/i.exec(out)
+    if (match === null) return []
+    return match[1].split(';').map((entry) => entry.trim()).filter((entry) => entry !== '')
+  }
+  const dirs = () => {
+    const out = []
+    for (const key of ['ProgramFiles', 'ProgramFiles(x86)', 'ProgramW6432']) {
+      const base = process.env[key]
+      if (typeof base === 'string' && base.trim() !== '') out.push(base.replace(/\\/g, '/') + '/Git/bin/bash.exe')
+    }
+    const local = process.env.LOCALAPPDATA
+    if (typeof local === 'string' && local.trim() !== '') out.push(local.replace(/\\/g, '/') + '/Programs/Git/bin/bash.exe')
+    return out
+  }
+  const pathDirs = () => String(process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').map((entry) => entry.trim()).filter((entry) => entry !== '')
+  return {
+    exists: (path) => {
+      try { return existsSync(path) } catch { return false }
+    },
+    defaults: () => [DEFAULT_GIT_BASH, ...dirs()],
+    pathBashCandidates: () => pathDirs().map((dir) => dir.replace(/\\/g, '/') + '/bash.exe'),
+    gitReverseCandidates: () => pathDirs()
+      .filter((dir) => /(^|[/\\])cmd$/i.test(dir) || /(^|[/\\])bin$/i.test(dir))
+      .flatMap((dir) => {
+        const parent = dirname(dir.replace(/\\/g, '/'))
+        return [parent + '/bin/bash.exe', dirname(parent) + '/bin/bash.exe']
+      }),
+    registryBashCandidates: () => [
+      ...registryPath('HKCU', 'Environment'),
+      ...registryPath('HKLM', 'SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment'),
+    ].flatMap((entry) => {
+      const dir = entry.replace(/%([^%]+)%/g, (whole, name) => {
+        const value = process.env[name] ?? process.env[name.toUpperCase()]
+        return typeof value === 'string' ? value : whole
+      })
+      return /bash\.exe$/i.test(dir) ? [dir] : [dir.replace(/\\/g, '/') + '/bash.exe']
+    }),
+    gitVersion: (gitExe) => run(gitExe, ['--version']),
+    uname: (bash) => run(bash, ['-c', 'uname -s']),
+  }
+}
+
+/**
+ * Process-wide memo of the resolution. The translation layer and the executor
+ * MUST agree — a split ("translation resolved Q:/Git, the executor still looks
+ * at C:/...") is exactly issue #11 — so both read this one cache. A failed
+ * resolution is cached too: re-probing on every command would spawn `reg` and
+ * `bash` repeatedly, and the diagnosed failure is stable within a boot.
+ * @param {object} [options] - as {@link resolveGitBash}, plus `fresh` to bypass.
+ * @returns {object} the memoized resolution.
+ */
+const memoized = new Map()
+
+export function resolveGitBashCached(options = {}) {
+  const key = (typeof options.configured === 'string' ? options.configured.trim() : '')
+    + '\u0000' + (options.platform ?? process.platform)
+  if (options.fresh === true || !memoized.has(key)) {
+    memoized.set(key, resolveGitBash(options))
+  }
+  return memoized.get(key)
+}
+
+/**
+ * Drop the memo. Keyed by the configured value already, so a settings edit
+ * resolves afresh without this; the reset exists for tests and for a caller
+ * that knows the environment changed (e.g. a fresh registry read).
+ */
+export function resetGitBashMemo() {
+  memoized.clear()
+}