dsh-gitbash-shell 0.32.1 → 0.33.1

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.33.1 — 2026-10-02
+
+**类型**:docs(issue #14:README「保留官方沙箱语义」与 Windows 受限模式的实际行为不一致)
+
+> 报告者 **SenkjM** 的五条观察(enforcement 元数据、完整性级别 Low→Medium、shell 越界写成功而文件工具被拒、一次性提示、README 关键词计数)**全部与设计一致**;他指出的是文档缺口——行为在代码层有如实标注(§1 红线「绝不静默假成功」守住的是结果元数据与运行期提示),但 README 层面除了「保留官方沙箱语义」这句误导性概括外零披露。本版补齐,并顺带修正 README 里残留的物化时代描述。
+
+- **README.md / README_EN.md 新增「安全语义:Windows 上的受限模式」章节**(置于「它做了什么」之后):POSIX 完整保留 / Windows 受限模式 shell 走 unconfined 的根因(MSYS2 vs restricted-token,OS 层冲突无插件内解)与取舍理由、如何标注(结果元数据 `enforcement: "unconfined"` + 每进程一次性日志)、**文件工具不受影响**(fs 沙箱另一层,边界不一致如实写明)、可观察对照(完整性级别不再压低 Low→Medium、TEMP 不再隔离)、以及「需要 shell 也被硬拦 ⇒ 本插件在 Windows 上不适合你,卸载即回 pwsh-sandbox,没有中间态」的明确选择提示;「它解决什么」的「保留官方沙箱语义」改为指向该章节。
+- **顺带清理 README 的物化时代残留描述**(行为未变,纯文档对齐 v0.32.0+ 现状):「它做了什么」第 3 条改为声明式注册(`ctx.agentPresets.register`,行集为已提交 JS 数据,不再物化目录,旧物化树按 marker 单向清理);删除「dsh 版本双适配」「dsh 0.1.6 适配」两个过时段落(era 机制已随 v0.32.0 删除),替换为「宿主要求与 preset 对齐」(下限 >=0.1.7-rc + smoke 锁对齐 + preset id 不变);「配置」/「ptc 联动」/「去重开关」段的「物化」措辞与旧宿主(≤0.1.6)双时代描述同步更新。
+- docs-only:src/ 零改动,冒烟 99 项不变(README 内容无 smoke 断言)。发 patch 版本而非仅推文档,是因为 README 随 npm 包分发——安全披露应让 `npm view` / 插件管理页看到的 README 同步更新。
+
+- 相关:issue #14(<https://github.com/KannaKuron/dsh-gitbash-shell/issues/14>)、CHANGELOG v0.13.2(取舍的完整分析)。
+
+## v0.33.0 — 2026-10-01
+
+**类型**:fix(issue #13:Scoop 安装 Git 时 `bashPath` 配置正确但每次启动仍报 could NOT be resolved 并弹引导框)+ feat(解析链新增 `git --exec-path` 与 GitForWindows 注册表两级发现)
+
+> 报告者 **ID-izlq-Github** 的定位是准确的:装配期冻结、两个读取器在 apply 时刻读空、自动链对 shim 布局盲区,三条全部成立。本条目按他的分析与建议落地(建议 1/2/3/4 全采纳)。
+
+### 修复一:显式层懒化,不再在装配期冻结(`src/index.js`)
+
+- **冻结点**(issue 引用的 `index.js:1813`):apply() 时 `effectiveConfiguredBashPath(executorConfiguredBashPath(ctx), settingsBashPath(ctx))` 算一次就定死。那一刻 `ctx.loader.resolve('gitbash-executor')` 因行未进 store 而 throw → 被吞成 `''`;settings 服务也可能尚未注入(0.1.7+ 只有 describe()/update())。两者皆空 ⇒ 误判「未配置」⇒ 跑自动链。执行器(`shell.js` 的 `get bashPath()` 懒解析)却正常 —— **同一次启动、两条路径、相反结论**,这正是 issue 的内核。
+- **修法**:冻结值换成两个读取器 `readConfiguredBashPath()` / `readBashResolution()`,**全部消费点逐次重读**:① `gitBash` capability 改 getter(bashPath/ok/source/configured/tried;ptc 侧只读静态 `active`,不受影响);② status 路由实时重读(弹窗因此不再误报 —— 行挂载完成后 `configured` 非空,解析成功,`ok:true`,弹窗根本不出现);③ pathmap 路由与 tools/execute / post-execute 的 `buildTranslateEnv`;④ 官方侧栏终端接管每次尝试重读;⑤ better-sidebar 接管改挂 settle 通知。
+- **settings 绕行退役**:`gitbash-shell` 行的 `bashPath` 直接从 apply() 的 `config` 参数读(新 `rowBashPath(config)`:volatile ref / 普通值 / 缺席三态,绝不抛)—— 这就是同一行的值,比绕 `settings.describe()` 更直接,且 volatile 意味着用户改设置下一读即生效。宿主半不再 import `settingsBashPath`(shell.js 侧保留:executor 行运行时读 describe() 实测正常)。
+- **启动日志 settle 化**:boot 打印一次;「失败且显式层为空」(行可能还在挂载)时轮询 250ms×20(仅 win32,5 秒封顶),显式层出现或解析翻转后补打 `(settled)` 段;成功或显式值被拒为最终态,不轮询。terminal 接管通过 `onBashSettled` 通知(better-sidebar 在 boot 失败→settled 成功时也能接管,无需重启)。
+
+### 修复一·续:executor 行读取在 0.2.0-rc.2 上恒断,不只是时序(`src/bash-path.js`)
+
+- **真机实测(隔离实例 + 探针插件,报告场景复现)**:dsh 0.2.0-rc.2 上 bundle-patch insert 的行(`gitbash-executor`)挂在**所属插件的 subtree** 里,`loader.resolve('gitbash-executor')` 从 root 树查找**恒 throw**(探针 apply 时刻与 12 秒后各 7 次采样全部 throw)——报告者以为的「启动时序问题」在这台宿主上实际是**永远读不到**。旧代码把 throw 吞成 `''` ⇒ 显式层整个失效:patch 写 `gitbash-executor.config.bashPath` 的用户(issue #11 起推荐、#13 报告者的实际配置方式)在 0.2.0 上 boot/status/翻译层全部看不到该值,而执行器自己读 `this.config.bashPath` 正常 —— 「命令能用但每次启动报错+弹框」的另一半根因。**并连带违反 §4h 契约**:显式值(哪怕被拒)不得被自动链顶替 —— 实测坏值 `Q:/nope/bin/bash.exe` 被自动链的 default 层「顶替成功」,boot 谎报 resolved。
+- **修法**:`executorConfiguredBashPath` 二段式 —— `resolve('gitbash-executor')` 先试(旧宿主行在 root 树,命中即返回,空串也是真实答案=自动链);throw 则 `loader.entries()` 迭代(**含 subtree**)按行自身 `options.id` 匹配(0.2.0 实测稳定可读,`bashPath` 值全程不变)。防回归用例锁死三种 loader 形状(root 命中 / subtree+entries / 行缺失)。
+- **修复后 A/B 真机读数**(隔离实例,patch 写 `gitbash-executor.config.bashPath`):
+  - 坏值 `Q:/nope/...`:boot `bashPath is set to "Q:/nope/bin/bash.exe" and that value was rejected; nothing else is substituted`(fail-loud、无轮询、default 层不再顶替);status `ok:false, configured:"Q:/nope/bin/bash.exe", tried[0]={source:'configured',code:'missing'}` —— boot/status/执行器三方一致;
+  - 好值:boot `Git Bash resolved from the configured source`;status `ok:true, source:"configured"` —— 弹窗不出现。
+
+### 修复二:解析链补 shim 布局的发现方式(`src/bash-path.js`)
+
+- **新 source `exec-path`**(位置:PATH 反推之后、注册表 PATH 之前):对 PATH 上第一个 `git.exe` 跑 `git --exec-path`(Scoop/choco 的 **shim 也能启动真身**,真身报告自己的家),从输出向上最多 5 级找「同时含 `cmd/git.exe` 与 `usr/bin/bash.exe`」的目录,产出 `<root>/bin/bash.exe`。纯函数 `execPathBashCandidates(execPath, exists)` 可测;`ucrt64`/`mingw64`/旧 flat `libexec` 三种布局全覆盖,MSYS2(`usr/libexec/git-core`,根上没有 `cmd/git.exe`)天然不产出候选。
+- **GitForWindows 注册表兜底**:`HKLM\SOFTWARE\GitForWindows`、`HKLM\SOFTWARE\WOW6432Node\GitForWindows`、`HKCU\Software\GitForWindows` 的 `InstallPath`(官方安装器写的;Scoop/便携通常没有,故排在 exec-path 之后),同样走 `exec-path` source。
+- **候选仍过全套判据**(黑名单 → 形状 → `cmd/git.exe`/`usr/bin/bash.exe` → mingw64/msys-2.0.dll → `.windows.` 版本指纹 → `uname -s` 一票否决):§4h 两条硬边界不变 —— 永不回退、只认 Git for Windows 的 bash。冒烟新增「WSL bash 经 exec-path 到达仍被拒」用例。
+- **顺带**:`defaultIo().run` 从 execFileSync 换 spawnSync(piped stdio)—— execFileSync 的同步家族在子进程失败时把 stderr 直接泄漏到宿主日志(reg 的 GBK 错误文本 = 乱码),v0.28.0 起每次失败探测都在漏;spawnSync 捕获进 result 由 catch 丢弃。本机实测乱码消除、探测结果不变(exec-path 层产出 `C:/Program Files/Git/bin/bash.exe`,mingw64 布局反推正确,全链仍 `source=default` 先命中,新层是后备)。
+
+### 冒烟与真机
+
+- 新增三组用例:①「exec-path covers Scoop layouts」(纯函数三布局 + MSYS2 不命中 + 全链 Scoop 场景 + WSL 否决);②「explicit tier is LAZY」(冻结模式防回归:断言 `const configuredBashPath = effectiveConfiguredBashPath(` 与 `const bashResolution = resolveGitBashCached(` 不得再现;懒读取器/status 实时重读/settle 通知必须存在;`rowBashPath` 三态);③「executor row lookup survives the subtree layout change」(loader 三形状:root 命中 / subtree+entries / 行缺失,空串=真实答案)。
+- **顺手修掉存量失败**(0.32.1 在 win32 上 latent):「full apply() mount on a stub ctx」的 settings stub 还停在 `settings.get(ns)` 时代,readShell 自 v0.25.1 起只认 `describe()` ⇒ stub 恒 null ⇒ 轮询 12×1500ms 后断言必挂。stub 补 `describe()`,与现役读法对齐。
+- 99 项全绿(96 存量 + 3 新增;toolchain PATH 用例的平台误判 v0.32.1 已修,本次全平台绿)。
+- **真机验证**(隔离 `DSH_HOME`(Temp 目录)+ profile 副本 `cp -rL` 解引用 + 插件目录换本仓源码 + 探针插件采 loader 形状;全程独占 3080 —— 用户实例当时未运行,验证后实例已杀、410M 副本与探针已删净,`~/.dsh` 零触碰):默认场景 boot `resolved from the default source`、status `ok:true`;坏值/好值 A/B 见上文「修复一·续」;官方侧栏终端接管懒读路径正常(`already uses this Git Bash ... (nothing written)` 幂等);ptc 联动正常(cordis-gitbash 去重、对方注册 Git Bash rows —— capability getter 无碍);spawnSync 改造后启动日志**零乱码**。**未覆盖**:settle 轮询分支的翻转真机时序(0.2.0-rc.2 上 entries() 在 apply 时刻即稳定可读,轮询多数情况下不触发;接线由源码断言锁定,行为留待真实慢宿主检验)。
+
+- 相关:issue #13(<https://github.com/KannaKuron/dsh-gitbash-shell/issues/13>)、issue #11(解析链的由来)、AGENTS.md §4h(顺序契约更新)。
+
 ## v0.32.1 — 2026-09-28
 
 **类型**:chore(清掉 v0.32.0 遗留的 legacy settings 死代码)+ fix(冒烟里 mac 平台误判的 toolchain 路径用例)

package/README.md

@@ -6,14 +6,16 @@
 
 > 让 DeepSeek Harness (dsh) 在 Windows 上**全部使用 Git Bash** 的官方风格插件
 > —— 以 Git for Windows 的 `bash.exe` 替换 PowerShell 执行器,并为所有模式
-> 物化对应的 Git Bash 版 agent preset。
+> 注册对应的 Git Bash 版 agent preset。
 
 ## 它解决什么
 
 官方 Windows 组合默认把 `dsh-pwsh-sandbox` 作为 `ctx.shell`(PowerShell 执行器),
 且各 preset 的 `tool-bash` 行在 win32 上被禁用——因为在 Windows 上裸 `bash`
 会解析到 `C:\Windows\System32\bash.exe`(WSL 占位),本插件直接指定
-`C:/Program Files/Git/bin/bash.exe` 并保留官方沙箱语义。
+`C:/Program Files/Git/bin/bash.exe`。沙箱语义在 POSIX 宿主上完整保留;
+**Windows 宿主上受限模式有一处重要例外——见下方
+[「安全语义:Windows 上的受限模式」](#安全语义windows-上的受限模式)**。
 
 安装本插件后:
 
@@ -28,29 +30,15 @@
 Git Bash host 下会拿到"暗示 PowerShell 语法的工具",请改用上面的变体;
 已装 dsh-ptc-cordis-preset 的话,`PTC 创造模式` 用户 preset 不受影响。
 
-### dsh 版本双适配(0.1.1 与 0.1.2+)
+### 宿主要求与 preset 对齐
 
-dsh 0.1.2 把内置 `code` preset 改名为 `ptc`(`mode: code` → `mode: ptc`,官方不做
-兼容别名),并给各内置 preset 新增 `command-goal` 等行。本插件为受影响的变体
-(standard/code/cordis)**同时携带两个 era 的已提交组合文本**,启动时探测内置
-roster 自动选择,并记进 `.plugin-managed.json` 的 `base` 字段;探测翻转(dsh
-升级前后)自动重物化。`minimal-gitbash` 的内置底稿跨版本未变,单文本服务两个
-era。**preset id 保持 `code-gitbash` 不变**(会话钉在 id 上,改名会让已固定的
-会话报 preset not found)。无论先升级插件还是先升级 dsh,都会自动收敛;用户改
-过的目录照旧不碰。
-
-### dsh 0.1.6 适配(工作流引擎行改名)
-
-dsh 0.1.6-alpha.1 把内置预设的工作流引擎行 `workflow-worker-thread` 改名为
-`workflow-ptc`,并**删除**了旧包。组合里一行 import 失败会拒绝**整棵 preset 挂载**,
-所以把旧名钉死在资产里的 preset 在新版上会直接不可用。本插件两个拼法都不钉:物化时
-**从宿主自己的内置 preset 现场抄**那一行的 id、包名与 `disabled` 状态
-(`rowFormsOf` / `alignEngineRow`),并让 `tool-ralph` 跟随新版默认的 `disabled: true`。
-改写是纯字符串手术(不解析 YAML,`!!js` 安全)且幂等;探测失败(旧宿主、无 roster)时
-资产保持逐字节原样——**一份资产通吃两个 era,升级顺序无关**。
-
-同一版还把 `LocalBashExecutor` 的受保护钩子改成了异步:插件的 `runArgv` 结果解包、
-`start` 的返回形态与 `confine` 的取消信号都按**加载期探测**自适应,新旧宿主行为一致。
+自 v0.32.0 起宿主下限为 **dsh >= 0.1.7-rc**(经 peer `@deepseek-ai/dsh` 声明,
+prerelease 含入求值;旧宿主不再支持)。四个变体的行集是 `src/compositions.js`
+里已提交的 JS 数据,镜像官方 0.1.7 的 standard/minimal/ptc/cordis 行切分并叠加
+Git Bash 增量;跟随 dsh 升级的对齐由冒烟测试
+`compositions: full variants mirror the official row split` 锁住。
+**preset id 保持 `code-gitbash` 不变**——会话钉在 id 上,dsh 0.1.2 把内置 `code`
+改名 `ptc` 时本插件的变体 id 就没有跟随(改名会让已固定的会话报 preset not found)。
 
 ## 安装(公开 npm 插件,推荐)
 
@@ -74,24 +62,59 @@ bundle patch(`cordis.patch.yml`)应用三个改动:
 2. 插入 `gitbash-executor`(`dsh-gitbash-shell/shell`):继承官方
    `@deepseek-ai/dsh-bash-sandbox`,仅把内层 argv 换成
    `<git-bash.exe> -c <command>`。沙箱策略/拒绝分类/后台任务/超时/设置节
-   全部沿用官方实现;full-access 分支单独接 Git Bash(父类那里硬编码裸 `bash`);
-3. 插入 `gitbash-presets`(`dsh-gitbash-shell/presets`):启动时把上表 4 个
-   preset 物化到首个 user-trust preset 根目录,并写
-   `.plugin-managed.json`(逐文件哈希)——未改动则随版本刷新;被用户改过就
-   不再碰;卸载时(且仅当未改动)会清理。
+   沿用官方实现;full-access 分支单独接 Git Bash(父类那里硬编码裸 `bash`);
+   **Windows 上受限分支有一处例外,见下一节**;
+3. 插入 `gitbash-shell`(`dsh-gitbash-shell`):以**声明式注册**
+   (`ctx.agentPresets.register`,v0.32.0 起)提供上表 4 个 preset 变体——
+   行集是仓库里已提交、可 diff 的 JS 数据(`src/compositions.js`),**不再物化
+   任何目录**;旧版本遗留在磁盘上的物化树,启动时仅当 marker 判定为
+   「未被用户改过」才单向清理,用户改过的绝不碰。
 
 **环境变量**:`bash.exe` 是 host 进程的直接子进程(不经 git-bash 登录壳),完整继承
 系统环境变量与 `DSH_*` 快照,和原来 pwsh 拿到的完全一致。
 
+## 安全语义:Windows 上的受限模式
+
+**POSIX 宿主**:官方沙箱语义**完整保留**——受限令牌、工作区围栏、拒绝分类,
+与 `@deepseek-ai/dsh-bash-sandbox` 完全一致。本节只讲 Windows。
+
+**Windows 宿主上的事实**:`read-only` / `workspace-write` 权限预设下的 **shell 命令**,
+实际以**不受限(unconfined)方式执行**:
+
+- **为什么**:MSYS2 运行时无法在 restricted-token 沙箱下启动——`msys-2.0.dll`
+  初始化时创建的 cygheap 映射与信号管道,DACL 只含用户 SID;而 WRITE_RESTRICTED
+  令牌的二次写检查要求 restricting-SID ACE → 初始化即死于 Win32 error 5 /
+  0xC0000142,**任何版本、任何参数都无解**(cmd/pwsh 走匿名管道不受影响)。
+  这是 OS 层冲突,插件内没有真正的修法,只有两个选择:**如实标注的绕过**(本插件,
+  v0.13.0 起)或**直接拒绝执行**。选了前者,是因为装这个插件的目的就是用 Git Bash——
+  静默换 pwsh 顶上、或让每条命令都失败,都不如把真相摆在结果里。
+- **如何标注(绝不静默)**:每条此类结果的元数据携带
+  `sandbox: { mode: "<请求的模式>", denied: false, enforcement: "unconfined" }`,
+  并在每个进程首次受限调用时打印一行说明日志(`File sandbox enforcement is
+  partial on this host.`)。
+- **文件工具不受影响**:read / write / edit / glob / grep 的沙箱是**另一层**
+  (fs-tool policy),照常拦截工作区外访问——也就是说 `workspace-write` 下
+  shell 能写出工作区、文件工具不能,**两者的边界并不一致**。
+- **可观察的对照**(相对 pwsh-sandbox 时代):会话进程的完整性级别不再被压低
+  (Low → Medium);`$env:TEMP` 不再被重定向到 per-session 隔离目录。
+
+**如果你需要 shell 也被硬性拦住**(例如不希望模型经 shell 写工作区外的任何路径),
+这个插件在 Windows 上不适合你——卸载即回到 `pwsh-sandbox` 的受限语义,没有中间态。
+`danger-full-access` 预设本来就不受限,装不装本插件行为一致。
+
+> 这一取舍的完整分析(含 0.6.0~0.13.1 的故障史与社区两派对比)见 CHANGELOG
+> v0.13.2 与 `src/shell.js` 头注释。
+
 ## 配置
 
 `gitbash-shell` 行(行 id 自 v0.24.0 起与设置命名空间同串;≤ v0.23.0 为 `gitbash-presets`)
-支持 `presets` 数组,只物化你常用的模式(未列出的旧物化目录、且未被用户修改过的,会自动清理):
+支持 `presets` 数组,只注册你常用的模式(未列出的变体不再进入名录;改动经
+volatile-update 触发重注册):
 
 ```yaml
 - id: gitbash-shell
   config:
-    presets: [standard-gitbash, minimal-gitbash]   # 默认物化全部 4 个
+    presets: [standard-gitbash, minimal-gitbash]   # 默认注册全部 4 个
     suppressPeerCordis: false                       # 与 dsh-ptc-cordis-preset 去重,默认关
 ```
 
@@ -126,7 +149,7 @@ dsh-ptc-cordis-preset 报告它的 `PTC 创造模式` 已经是 Git Bash 版。
     default: ptc-cordis   # 或 standard-gitbash / minimal-gitbash
 ```
 
-## bash 从哪里来:解析链与失败引导(v0.28.0,issue #11)
+## bash 从哪里来:解析链与失败引导(v0.28.0,issue #11;懒化与 exec-path 层 v0.33.0,issue #13)
 
 `bashPath` **默认留空 = 自动探测**;解析顺序就是契约:
 
@@ -136,8 +159,16 @@ dsh-ptc-cordis-preset 报告它的 `PTC 创造模式` 已经是 Git Bash 版。
    `%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. **全落空 ⇒ 报错 + 引导**(启动日志一份完整报告,客户端弹一次引导框)。
+5. **`git --exec-path` 反推 + GitForWindows 注册表**(v0.33.0):对 PATH 上的 `git.exe`(Scoop / choco 的
+   **shim** 也照常启动真身)跑 `--exec-path`,从输出向上找 Git 根 —— 兼容 `mingw64` / `ucrt64` 两种运行时
+   布局,补上「Scoop 安装、PATH 上只有 shims、没有 `bash.exe`」的盲区;随后兜底读注册表
+   `HKLM\SOFTWARE\GitForWindows` 的 `InstallPath`;
+6. **注册表 `Path`**(`HKCU\Environment`、`HKLM\...\Session Manager\Environment`)——覆盖"GUI 启动时 PATH 快照过期";
+7. **全落空 ⇒ 报错 + 引导**(启动日志一份完整报告,客户端弹一次引导框)。
+
+**解析结果是活的,不是启动时判一次**(v0.33.0,issue #13):启动那一刻插件行可能还没全部挂载,显式配置
+会被短暂读成空 —— 现在启动日志、状态接口、弹窗与侧栏终端接管都在**使用时实时重读**,执行器能用,
+它们就不会再说「解析失败」;启动日志也会在行挂载稳定后补一份最终结论。
 
 > **只认 Git for Windows 的 bash。** WSL(`C:\Windows\System32\bash.exe`,永远在 PATH 且排序靠前)、
 > WindowsApps 别名、MSYS2、Cygwin 的 bash **一律拒绝**;候选还要通过 Git 布局(`usr/bin` + `cmd\git.exe` +
@@ -211,14 +242,11 @@ preset 会被插件自动清理;宿主 shell 回退为 PowerShell。
 ## 与 dsh-ptc-cordis-preset 联动
 
 本插件在 host 上发布 `gitBash` 能力服务(`{ active, bashPath }`,仅 Windows 为 active)。
-[dsh-ptc-cordis-preset](https://github.com/KannaKuron/dsh-ptc-cordis-preset) v0.5.0+ 在物化
-`PTC 创造模式` 时会检测该信号:两个插件都安装时,**PTC 创造模式自动物化为 Git Bash 版**
+[dsh-ptc-cordis-preset](https://github.com/KannaKuron/dsh-ptc-cordis-preset) v0.5.0+ 在注册
+`PTC 创造模式` 时会检测该信号:两个插件都安装时,**PTC 创造模式自动注册为 Git Bash 版**
 (`tool-bash` 启用、`tool-pwsh` 禁用),无需新增模式、无需手工修改 preset;
 只装本插件时 PTC 创造模式保持原样(由它自己的插件管理)。
 
-> 切换生效后若 `ptc-cordis` 目录已存在且被旧版本物化,删除
-> `~/.dsh/.agent-presets/ptc-cordis` 并重启,即由新逻辑重新物化。
-
 ### 去重开关:`suppressPeerCordis`(默认关,v0.25.0)
 
 联动生效后,`创造模式 · Git Bash`(本插件的 `cordis-gitbash`)与对方已经 Git Bash 化的
@@ -237,14 +265,11 @@ preset 会被插件自动清理;宿主 shell 回退为 PowerShell。
 
 **生效时机**:
 
-- **新宿主(dsh ≥ 0.1.7)是实时的**:开关走行 Config 的 volatile 通道,对方的能力则经
+- **开关是实时的**:走行 Config 的 volatile 通道,对方的能力则经
   `ctx.inject(['ptcCordisPreset'])` 观察(**与插件行激活顺序无关**),两边任一变化都当场
   reconcile——摘掉打日志 `preset 'cordis-gitbash' retired (dsh-ptc-cordis-preset covers Creation
   mode on Git Bash)`,恢复打 `preset 'cordis-gitbash' registered declaratively`。已经挂载的会话
   钉在自己的组合快照上,不受影响;名录变化从新会话开始可见。
-- **旧宿主(dsh ≤ 0.1.6)是启动时判定一次**:旧宿主没有可观察的注册表,能力探测是有界的
-  (默认 1s,读不到即视为"对方不覆盖"),所以打开开关后,上一轮物化出来的 `cordis-gitbash`
-  目录会被清理;把开关关掉后,该变体要到**下一次启动**才重新物化。
 
 **两侧设置卡上是同一份状态**:权威值只有本插件这一行 Config 一份;对方的设置卡通过
 `ctx.configForms.get('gitbash-shell')` **绑定同一行**、写同一个字段(DSH 官方支持编辑另一个

package/README_EN.md

@@ -5,25 +5,20 @@
 [简体中文](README.md) | English
 
 > Run **every agent shell command through Git Bash** on Windows with DeepSeek
-> Harness (dsh) — replaces the PowerShell executor and materializes Git Bash
+> Harness (dsh) — replaces the PowerShell executor and registers Git Bash
 > variants of all four agent presets.
 
-### dsh 0.1.6: the workflow-engine row was renamed
+### Host requirement & preset alignment
 
-dsh 0.1.6-alpha.1 renamed the built-in presets' workflow-engine row from
-`workflow-worker-thread` to `workflow-ptc` and **deleted** the old package. One row
-that fails to import rejects the **whole preset mount**, so a composition pinning the
-old name simply stops working on the new host. This plugin pins neither spelling: at
-materialization it copies that row — id, package and `disabled` state — straight out
-of the host's own built-in preset (`rowFormsOf` / `alignEngineRow`), and aligns
-`tool-ralph` with the new `disabled: true` default. The rewrite is plain string
-surgery (no YAML round-trip, so `!!js` stays safe) and idempotent; a failed probe (old
-host, no roster) leaves the assets byte-for-byte untouched — **one set of assets serves
-both eras, in either upgrade order**.
-
-The same release made `LocalBashExecutor`'s protected hooks asynchronous: the
-`runArgv` result unwrapping, the `start` return shape and the `confine` cancellation
-signal are all probed at load time, so both host generations behave identically.
+Since v0.32.0 the host floor is **dsh >= 0.1.7-rc** (declared through the
+`@deepseek-ai/dsh` peer, prereleases included; older hosts are no longer
+supported). The four variants are committed JS row sets in
+`src/compositions.js`, mirroring the official 0.1.7 standard/minimal/ptc/cordis
+split plus the Git Bash delta; upgrade alignment is locked by the smoke test
+`compositions: full variants mirror the official row split`. **Preset ids
+never change** (`code-gitbash` kept its historical id when dsh 0.1.2 renamed
+the built-in `code` to `ptc` — sessions are pinned to ids, and a rename would
+orphan them).
 
 ## Install (public npm package)
 
@@ -35,19 +30,6 @@ dsh plugin --profile web add dsh-gitbash-shell
 `dsh.bundle` declaration, appends the package to `dsh.profile.bundles`.
 **Restart the profile's host to activate.**
 
-## Works with both dsh 0.1.1 and 0.1.2+
-
-dsh 0.1.2 renamed the built-in `code` preset to `ptc` (`mode: code` → `mode: ptc`,
-no compatibility aliases) and added new built-in rows (`command-goal`, …). For
-the affected variants (standard/code/cordis) this plugin **ships both committed
-era texts**, probes the built-in roster at every boot, records the choice in
-`.plugin-managed.json` (`base`), and re-materializes automatically when the
-detection flips. `minimal-gitbash`'s built-in base did not change across the
-rename, so one text serves both eras. **Preset ids never change**
-(`code-gitbash` keeps its historical id — sessions are pinned to ids, and a
-rename would orphan them). Either upgrade order converges automatically; directories
-you modified are still never touched.
-
 ## What it does
 
 The bundle patch (`cordis.patch.yml`):
@@ -56,17 +38,59 @@ The bundle patch (`cordis.patch.yml`):
 2. mounts `dsh-gitbash-shell/shell` — a subclass of the shipped
    `@deepseek-ai/dsh-bash-sandbox` whose inner argv is
    `<git-bash.exe> -c <command>` (sandbox policy, denial classification,
-   background jobs, and settings behavior all inherited);
-3. mounts `dsh-gitbash-shell/presets`, which materializes
-   `standard-gitbash`, `minimal-gitbash`, `code-gitbash`,
-   `cordis-gitbash` into the first user-trust preset root, guarded by
-   per-file `.plugin-managed.json` hashes (user edits are never overwritten;
-   unmodified trees are cleaned on uninstall).
+   background jobs, and settings behavior all inherited; **one Windows
+   exception for confined modes — see the next section**);
+3. mounts `dsh-gitbash-shell`, which registers the four preset variants
+   **declaratively** (`ctx.agentPresets.register`, v0.32.0+) — the row sets
+   are committed, diffable JS data (`src/compositions.js`) and **no directory
+   is ever materialized**; materialized trees left by older versions are
+   cleaned one-way at boot only when the marker proves the user never edited
+   them.
 
 Environment: `bash.exe` is spawned as a direct child of the host, so it
 inherits the full system environment plus the `DSH_*` snapshot, exactly like
 the pwsh executor did.
 
+## Security semantics: confined modes on Windows
+
+**POSIX hosts**: the official sandbox semantics are **fully preserved** —
+restricted tokens, workspace fencing, denial classification, identical to
+`@deepseek-ai/dsh-bash-sandbox`. This section is about Windows only.
+
+**On Windows**, shell commands under the `read-only` / `workspace-write`
+permission presets actually run **UNCONFINED**:
+
+- **Why**: the MSYS2 runtime cannot start under the restricted-token sandbox —
+  `msys-2.0.dll` creates its cygheap mapping and signal pipe with DACLs naming
+  only the user SID, while a WRITE_RESTRICTED token's pass-2 write check
+  demands a restricting-SID ACE, so init dies with Win32 error 5 / 0xC0000142
+  before argv ever runs — **every version, no workaround** (cmd/pwsh use
+  anonymous pipes and are unaffected). This is an OS-level conflict with no
+  in-plugin cure; the two options are **a labelled bypass** (this plugin,
+  since v0.13.0) or **refusing to run at all**. The former was chosen because
+  installing this plugin means wanting Git Bash — silently falling back to
+  pwsh, or failing every command, is worse than putting the truth in the result.
+- **How it is labelled (never silent)**: every such result carries
+  `sandbox: { mode: "<requested mode>", denied: false, enforcement: "unconfined" }`,
+  plus a one-time notice per process (`File sandbox enforcement is partial on
+  this host.`).
+- **File tools are NOT affected**: the read / write / edit / glob / grep
+  sandbox is a **separate layer** (the fs-tool policy) and still fences
+  out-of-workspace access. Under `workspace-write` the shell can write outside
+  the workspace while file tools cannot — **the two boundaries differ**.
+- **Observable differences** vs the pwsh-sandbox era: the session process's
+  integrity level is no longer lowered (Low → Medium), and `$env:TEMP` is no
+  longer redirected to a per-session directory.
+
+**If you need the shell itself hard-fenced too** (e.g. the model must not
+write anywhere outside the workspace through the shell), this plugin is not
+for you on Windows — uninstalling restores `pwsh-sandbox`'s confined
+semantics; there is no middle ground. The `danger-full-access` preset is
+unconfined by design either way.
+
+> The full analysis (the 0.6.0–0.13.1 failure history and the community's two
+> camps) is in the CHANGELOG under v0.13.2 and in the `src/shell.js` header.
+
 ## Config
 
 The `gitbash-shell` row (its id has matched the settings namespace since v0.24.0; it was
@@ -91,9 +115,16 @@ Executor config:
 
 ```yaml
 config:
-  bashPath: "D:/Tools/Git/bin/bash.exe"   # default C:/Program Files/Git/bin/bash.exe
+  bashPath: "D:/Tools/Git/bin/bash.exe"   # default '' (empty) = automatic chain
 ```
 
+The automatic chain (empty `bashPath`) probes, in order: explicit settings → default
+install locations → PATH → `git.exe` reverse lookup → `git --exec-path` (covers
+Scoop/choco shim layouts and the `ucrt64` runtime, v0.33.0) + the GitForWindows
+registry `InstallPath` → the registry `Path`. Resolution is re-read live per
+consumer (never frozen at boot, v0.33.0), and only Git for Windows' own bash
+counts — WSL / MSYS2 / Cygwin are refused with guidance, never substituted.
+
 ## Cooperation with dsh-ptc-cordis-preset
 
 This plugin publishes a `gitBash` host capability (`{ active, bashPath }`,

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.32.1",
+  "version": "0.33.1",
   "main": "./src/index.js",
   "description": "Windows 全模式 Git Bash:用 Git for Windows bash 替换 PowerShell 执行器,声明式注册 standard/minimal/code/cordis 的 Git Bash 变体 preset(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.32.1",
+  "version": "0.33.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/bash-path.js

@@ -20,7 +20,7 @@
  * arrives through `io`, so the whole chain is unit-testable off-Windows.
  */
 
-import { execFileSync } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname } from 'node:path'
 
@@ -44,7 +44,7 @@ export const GIT_WINDOWS_VERSION_MARKER = '.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']
+export const BASH_SOURCES = ['configured', 'default', 'path', 'path-git', 'exec-path', 'registry']
 
 /**
  * Normalize a Windows path for comparison: forward slashes, lowercase, no
@@ -132,11 +132,46 @@ export function classifyBashCandidate(candidate, io) {
   return { ok: true, path: candidate, root, gitExe }
 }
 
+/**
+ * Walk UP from a `git --exec-path` output looking for the Git for Windows
+ * root, and return its `<root>/bin/bash.exe` candidate (issue #13).
+ *
+ * Why this tier exists: package managers that SHIM Git (Scoop, and portable
+ * installs generally) put `git.exe` on PATH in a directory (`E:/Scoop/shims`)
+ * that is neither `<root>/cmd` nor `<root>/bin`, so the PATH reverse lookup
+ * never fires and there is no `bash.exe` on PATH at all. The REAL git still
+ * knows where it lives — `git --exec-path` prints
+ * `<root>/<mingw64|ucrt64>/libexec/git-core` (or `<root>/libexec/git-core`
+ * on old layouts) even when launched through a shim — so climbing ≤5 levels
+ * and demanding BOTH `cmd/git.exe` and `usr/bin/bash.exe` finds the root on
+ * every layout. That pair is also the discriminator: MSYS2's git reports
+ * `<msys64>/usr/libexec/git-core`, whose root has `usr/bin/bash.exe` but NO
+ * `cmd/git.exe`, so it never produces a candidate here (and even if it did,
+ * classifyBashCandidate's blacklist + fingerprints would refuse it).
+ * @param {string|undefined} execPath - raw `git --exec-path` output.
+ * @param {(path: string) => boolean} exists - filesystem probe.
+ * @returns {string[]} zero or one candidate.
+ */
+export function execPathBashCandidates(execPath, exists) {
+  if (typeof execPath !== 'string' || execPath.trim() === '') return []
+  let dir = execPath.replace(/\\/g, '/').replace(/\/+$/, '')
+  for (let i = 0; i < 5; i++) {
+    const parent = dirname(dir)
+    if (parent === dir || parent === '' || parent === '.') break
+    dir = parent
+    if (exists(dir + '/cmd/git.exe') && exists(dir + '/usr/bin/bash.exe')) {
+      return [dir + '/bin/bash.exe']
+    }
+  }
+  return []
+}
+
 /**
  * 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).
+ * PATH → git.exe reverse lookup → git --exec-path / GitForWindows registry
+ * (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.
@@ -152,6 +187,7 @@ export function bashCandidates({ configured }, io) {
   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.execPathBashCandidates()) out.push({ path, source: 'exec-path' })
   for (const path of io.registryBashCandidates()) out.push({ path, source: 'registry' })
   return out
 }
@@ -262,23 +298,50 @@ export function effectiveConfiguredBashPath(ownRowValue, settingsValue) {
 
 /**
  * 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
+ * Read through the Loader's public surface (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 ''.
+ *
+ * TWO access paths, because hosts differ (issue #13, measured on 0.2.0-rc.2):
+ * bundle-patched rows live in the OWNING PLUGIN'S SUBTREE there, so a bare
+ * `resolve('gitbash-executor')` throws from the root tree FOREVER (not just
+ * at boot) — the explicit tier silently read '' while the executor's own lazy
+ * `this.config.bashPath` worked, i.e. the two halves of this plugin disagreed
+ * about the user's explicit answer. `entries()` iterates subtrees as well, so
+ * it finds the row on both layouts; the direct resolve stays as the first try
+ * for older hosts where the row sits in the root tree.
  * @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 read = (entry) => {
     const value = entry && entry.options ? entry.options.config : undefined
     return value && typeof value.bashPath === 'string' ? value.bashPath : ''
-  } catch {
-    return ''
   }
+  const loader = ctx && ctx.loader
+  if (!loader) return ''
+  // Subtree walk: finds the row wherever the host nests bundle-patched rows.
+  const walk = () => {
+    try {
+      if (typeof loader.entries !== 'function') return undefined
+      for (const entry of loader.entries()) {
+        if (entry && entry.options && entry.options.id === 'gitbash-executor') return entry
+      }
+      return undefined
+    } catch {
+      return undefined
+    }
+  }
+  try {
+    // Direct resolve first: the row sits in the ROOT tree on older hosts, and
+    // an EMPTY string it may carry is a real answer (= run the automatic
+    // chain) — only a throw (subtree row, newer hosts) falls through.
+    if (typeof loader.resolve === 'function') {
+      return read(loader.resolve('gitbash-executor'))
+    }
+  } catch { /* not in the root tree — walk the subtrees below */ }
+  return read(walk())
 }
 
 /**
@@ -289,19 +352,29 @@ export function executorConfiguredBashPath(ctx) {
  * @returns {object} the production io.
  */
 export function defaultIo() {
+  // spawnSync (not execFileSync): the sync-exec family LEAKS a failing
+  // child's stderr straight onto the host log (reg's GBK error text showed
+  // up as mojibake on every failed probe), while spawnSync with piped stdio
+  // captures it into the result where the catch below can drop it.
   const run = (file, args) => {
     try {
-      return String(execFileSync(file, args, { encoding: 'utf8', timeout: 5000, windowsHide: true })).trim()
+      const result = spawnSync(file, args, { encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+      if (result.error !== undefined || result.status !== 0) return undefined
+      return String(result.stdout ?? '').trim()
     } catch {
       return undefined
     }
   }
+  const registryValue = (hive, key, name) => {
+    const out = run('reg', ['query', hive + '\\' + key, '/v', name])
+    if (typeof out !== 'string') return undefined
+    const match = new RegExp(name + '\\s+REG_(?:EXPAND_)?SZ\\s+(.*)', 'i').exec(out)
+    return match === null ? undefined : match[1].trim()
+  }
   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 value = registryValue(hive, key, 'Path')
+    if (typeof value !== 'string') return []
+    return value.split(';').map((entry) => entry.trim()).filter((entry) => entry !== '')
   }
   const dirs = () => {
     const out = []
@@ -314,6 +387,23 @@ export function defaultIo() {
     return out
   }
   const pathDirs = () => String(process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').map((entry) => entry.trim()).filter((entry) => entry !== '')
+  const gitForWindowsInstalls = () => {
+    const roots = []
+    // The official installer writes these (machine-wide / per-user); the
+    // 32-bit-on-64-bit install lives under WOW6432Node. Scoop/portable usually
+    // has none of them, which is why this rides behind `git --exec-path`.
+    for (const [hive, key] of [
+      ['HKLM', 'SOFTWARE\\GitForWindows'],
+      ['HKLM', 'SOFTWARE\\WOW6432Node\\GitForWindows'],
+      ['HKCU', 'Software\\GitForWindows'],
+    ]) {
+      const install = registryValue(hive, key, 'InstallPath')
+      if (typeof install === 'string' && install.trim() !== '') {
+        roots.push(install.replace(/\\/g, '/').replace(/\/+$/, '') + '/bin/bash.exe')
+      }
+    }
+    return roots
+  }
   return {
     exists: (path) => {
       try { return existsSync(path) } catch { return false }
@@ -326,6 +416,19 @@ export function defaultIo() {
         const parent = dirname(dir.replace(/\\/g, '/'))
         return [parent + '/bin/bash.exe', dirname(parent) + '/bin/bash.exe']
       }),
+    // issue #13: shimmed Git layouts (Scoop, portable) have no bash.exe on PATH
+    // and a shim directory that defeats the cmd/bin reverse lookup. The REAL
+    // git reports its own home through --exec-path even when launched via a
+    // shim, and the official installer's InstallPath backs it up.
+    execPathBashCandidates: () => {
+      const gitExe = pathDirs()
+        .map((dir) => dir.replace(/\\/g, '/') + '/git.exe')
+        .find((path) => { try { return existsSync(path) } catch { return false } })
+      const execPath = gitExe === undefined ? undefined : run(gitExe, ['--exec-path'])
+      return [...execPathBashCandidates(execPath, (path) => {
+        try { return existsSync(path) } catch { return false }
+      }), ...gitForWindowsInstalls()]
+    },
     registryBashCandidates: () => [
       ...registryPath('HKCU', 'Environment'),
       ...registryPath('HKLM', 'SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment'),

package/src/index.js

@@ -276,7 +276,7 @@ export function effectivePresetIds(configured, { suppress, peerGitBash } = {}) {
  */
 import {
   DEFAULT_GIT_BASH, GIT_BASH_DOWNLOAD_URL, bashResolutionReport,
-  effectiveConfiguredBashPath, executorConfiguredBashPath, resolveGitBashCached, settingsBashPath,
+  effectiveConfiguredBashPath, executorConfiguredBashPath, resolveGitBashCached,
 } from './bash-path.js'
 import { adoptTerminalShell, terminalAdoptReport } from './terminal-shell.js'
 import {
@@ -481,6 +481,24 @@ export function valueOf(value) {
   return value && typeof value.get === 'function' ? value.get() : value
 }
 
+/**
+ * This row's OWN live `bashPath` (issue #13): apply()'s `config` parameter IS
+ * the `gitbash-shell` row's resolved Config, so reading it here replaces the
+ * settings-service detour (`settingsBashPath`) that could read '' at apply
+ * time on hosts where the service is describe()/update()-only or not injected
+ * yet. Volatile refs mean a settings edit lands on the next read, no listener.
+ * @param {object|undefined} config - apply()'s resolved Config (may be absent).
+ * @returns {string} the row's `bashPath`, '' when unset or unreadable.
+ */
+export function rowBashPath(config) {
+  try {
+    const value = config && typeof config === 'object' ? valueOf(config.bashPath) : undefined
+    return typeof value === 'string' ? value.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Era-aware live settings reader for everything wired inside apply(): the
  * NEW era reads this plugin's own Config refs (no listener needed — every
@@ -1805,25 +1823,38 @@ export async function apply(ctx, config = {}) {
   // materialize: service present, 'active: true' on Windows, 'active: false'
   // where the bundle is installed but the platform stack stayed native.
   /* The explicit tier of the resolution chain, in its documented priority:
-     the `gitbash-executor` row's own config > the `gitbash-shell` row/settings
-     field > empty (= run the automatic chain). Both this layer and the
-     executor resolve from this same value, so an explicit answer is never
+     the `gitbash-executor` row's own config > the `gitbash-shell` row's
+     `bashPath` field > empty (= run the automatic chain). Both this layer and
+     the executor resolve from this same value, so an explicit answer is never
      substituted and never silently ignored.
-     (issue #11: the row config is where the reporter's workaround landed.) */
-  const configuredBashPath = effectiveConfiguredBashPath(executorConfiguredBashPath(ctx), settingsBashPath(ctx))
-  const bashResolution = resolveGitBashCached({ configured: configuredBashPath })
+     (issue #11: the row config is where the reporter's workaround landed.)
+     LAZY, never frozen (issue #13): at apply() time the loader store may not
+     hold the executor row yet — `loader.resolve()` throws and reads '' — and
+     the old settings-service detour could equally read '' before the service
+     was injected. A frozen '' then ran the automatic chain (which fails on
+     shimmed Git layouts) while the executor's own per-call lazy resolution
+     worked, i.e. the same boot gave OPPOSITE verdicts. Every consumer below
+     re-reads per use; the own row's value comes from apply()'s `config`
+     parameter (this row's live Config refs — volatile, so a settings edit is
+     visible on the next read without any listener). */
+  const readConfiguredBashPath = () => effectiveConfiguredBashPath(executorConfiguredBashPath(ctx), rowBashPath(config))
+  const readBashResolution = () => resolveGitBashCached({ configured: readConfiguredBashPath() })
   const gitBashCapability = {
     active: process.platform === 'win32',
     // Kept for existing consumers (peer plugins read `bashPath`): the resolved
     // interpreter. When resolution failed we report the explicit value (or the
     // historical default) so the ENOENT a consumer may hit names a real path —
-    // never a substitute shell.
-    bashPath: bashResolution.ok ? bashResolution.path : (configuredBashPath || DEFAULT_GIT_BASH),
+    // never a substitute shell. Getters keep the capability live (issue #13):
+    // a consumer reading it after the rows settle sees the settled verdict.
+    get bashPath() {
+      const resolution = readBashResolution()
+      return resolution.ok ? resolution.path : (readConfiguredBashPath() || DEFAULT_GIT_BASH)
+    },
     // Additive (v0.28.0): the full verdict, for the guided popup and peers.
-    ok: bashResolution.ok,
-    source: bashResolution.source,
-    configured: configuredBashPath,
-    tried: bashResolution.tried,
+    get ok() { return readBashResolution().ok },
+    get source() { return readBashResolution().source },
+    get configured() { return readBashResolution().configured },
+    get tried() { return readBashResolution().tried },
     downloadUrl: GIT_BASH_DOWNLOAD_URL,
   }
   const disposeGitBash = ctx.provide('gitBash', gitBashCapability)
@@ -1979,7 +2010,7 @@ export async function apply(ctx, config = {}) {
           // untouched and the result metadata is not echoed back in MSYS form.
           if (dialect.posixPaths && dialectApplies(dialect, exec && exec.agent)) {
             echo = true
-            const env = dialect.virtualMounts ? buildTranslateEnv(configuredBashPath) : null
+            const env = dialect.virtualMounts ? buildTranslateEnv(readConfiguredBashPath()) : null
             echoEnv = env
             if (exec && exec.arguments && typeof exec.arguments === 'object') {
               const translated = translateDispatch(exec, dialect, env)
@@ -2034,7 +2065,7 @@ export async function apply(ctx, config = {}) {
           if (!dialectApplies(dialect, exec && exec.agent)) return next()
           if (dialect.posixPaths && dialect.errorDialect && exec && result && typeof result === 'object'
             && result.isError === true && Array.isArray(result.content)) {
-            const env = dialect.virtualMounts ? buildTranslateEnv(configuredBashPath) : null
+            const env = dialect.virtualMounts ? buildTranslateEnv(readConfiguredBashPath()) : null
             if (exec.name === 'run_code') {
               // paths only — the /dev/null hint is for file tools
               const content = rewriteErrorContent(result.content, { nulHint: false, env })
@@ -2108,14 +2139,59 @@ export async function apply(ctx, config = {}) {
   // Now the boot log names the value, the whole probe chain and where to fix
   // it, and the client half reads the same verdict over HTTP to raise the
   // guided popup. Nothing here substitutes another shell — by design.
-  console.log(TAG + ' bash resolution: ' + bashResolutionReport(bashResolution).split('\n').join('\n' + TAG + ' '))
+  //
+  // issue #13: the boot verdict may legitimately be wrong for a few seconds —
+  // at apply() time the loader store may not hold the executor row yet, so
+  // the explicit tier reads '' while the executor's own per-call lazy
+  // resolution succeeds. A FAILURE with an EMPTY configured value is therefore
+  // not final: poll briefly for the explicit tier to appear as the rows
+  // settle, print the settled verdict when it changes, and notify the
+  // adoptions below (official terminal / better-sidebar) through
+  // `onBashSettled`. A failure with a NON-empty configured value IS final (the
+  // user's explicit answer was rejected), and so is any success.
+  let settledBashResolution = null
+  const bashSettleWaiters = []
+  const onBashSettled = (listener) => {
+    if (settledBashResolution !== null) listener(settledBashResolution)
+    else bashSettleWaiters.push(listener)
+  }
+  const settleBashResolution = (resolution) => {
+    settledBashResolution = resolution
+    for (const listener of bashSettleWaiters.splice(0)) {
+      try { listener(resolution) } catch { /* a waiter never blocks settling */ }
+    }
+  }
+  const printBashResolution = (phase, resolution) => {
+    console.log(TAG + ' bash resolution' + (phase === '' ? '' : ' (' + phase + ')') + ': '
+      + bashResolutionReport(resolution).split('\n').join('\n' + TAG + ' '))
+  }
+  const bootBashResolution = readBashResolution()
+  printBashResolution('boot', bootBashResolution)
+  // Non-win32 hosts settle immediately: resolution failure there is the
+  // designed state (nothing consumes the capability), so no poll.
+  if (bootBashResolution.ok || bootBashResolution.configured !== '' || process.platform !== 'win32') {
+    settleBashResolution(bootBashResolution)
+  } else {
+    let ticks = 0
+    const timer = setInterval(() => {
+      ticks += 1
+      if (readConfiguredBashPath() === '' && ticks < 20) return // rows still mounting
+      clearInterval(timer)
+      const settled = readBashResolution()
+      if (settled.ok || settled.configured !== '') printBashResolution('settled', settled)
+      settleBashResolution(settled)
+    }, 250)
+    ctx.effect(() => () => clearInterval(timer), 'dsh-gitbash-shell: bash resolution settle poll')
+  }
   if (process.platform === 'win32') {
     try {
       ctx.inject(['webServer'], (wctx) => {
         try {
           const route = '/dsh-gitbash-shell/api/status'
           const read = () => {
-            const resolution = resolveGitBashCached({ configured: configuredBashPath, fresh: true })
+            // LIVE re-read (issue #13): the popup must see what the executor
+            // actually resolves NOW, not a value frozen at apply() time.
+            const resolution = resolveGitBashCached({ configured: readConfiguredBashPath(), fresh: true })
             return {
               ok: resolution.ok,
               platform: process.platform,
@@ -2178,7 +2254,7 @@ export async function apply(ctx, config = {}) {
             send(res, 403, { error: 'forbidden', reason: fence.reason })
             return
           }
-          const env = buildTranslateEnv(configuredBashPath)
+          const env = buildTranslateEnv(readConfiguredBashPath())
           // 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 : '?'))
@@ -2304,10 +2380,14 @@ export async function apply(ctx, config = {}) {
           attempts += 1
           let result
           try {
+            // LAZY re-read per attempt (issue #13): the first try may run
+            // before the loader store holds the executor row, when the
+            // resolution legitimately still reads ''.
+            const resolution = readBashResolution()
             result = await adoptTerminalShell(editorCtx.configEditor, {
               platform: process.platform,
               enabled: liveSettings.autoTerminalShell(),
-              resolved: bashResolution.ok ? bashResolution.path : '',
+              resolved: resolution.ok ? resolution.path : '',
             })
           } catch (error) {
             // adoptTerminalShell reports expected conditions itself; reaching
@@ -2332,9 +2412,20 @@ export async function apply(ctx, config = {}) {
   // The sidebar resolves its terminal shell through the settings seam per
   // open; adopt it through that seam (see adoptSidebarShell for rationale).
   // Disable with `betterSidebarShell: false` in the plugin row config.
+  // Rides the settle notification (issue #13): a boot-time failure with an
+  // empty explicit tier may still settle into a success once the loader rows
+  // mount, and the adoption then happens without a restart.
   if (config.betterSidebarShell !== false && process.platform === 'win32') {
-    if (bashResolution.ok) adoptSidebarShell(ctx, bashResolution.path, () => liveSettings.adoptSidebar())
-    else console.log(TAG + ' sidebar terminal adoption skipped: no Git Bash resolved (nothing is substituted)')
+    let sidebarAdopted = false
+    onBashSettled((resolution) => {
+      if (resolution.ok) {
+        if (sidebarAdopted) return
+        sidebarAdopted = true
+        adoptSidebarShell(ctx, resolution.path, () => liveSettings.adoptSidebar())
+        return
+      }
+      console.log(TAG + ' sidebar terminal adoption skipped: no Git Bash resolved (nothing is substituted)')
+    })
   }
 
   // ── era split: declarative registration on dsh >= 0.1.7 ──────────────────