dsh-gitbash-shell 0.29.0 → 0.29.2

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.29.2 — 2026-09-26
+
+**类型**:docs(纯文档 patch —— 更正复验判据:原先写成 `uname -r`,实为 `uname -s`;无任何代码/行为变更)
+
+> 用户在 Windows 上按 README 的"三步复验清单"跑 `uname -r`,得到 `3.6.9-b4195d69.x86_64` —— 按我们文档里写的判据
+> ("应出现 `MINGW64_NT-…`")会被**误判为失败**,实际它就是 Git Bash。事实:`MINGW64_NT-10.0-<build>` 是 **`uname -s`**
+> (system name)的输出;**`uname -r`**(release)在 Git Bash / MSYS2 下是 **MSYS 运行时版本**(形如 `3.6.9-<hash>.x86_64`),
+> 而 **WSL 的 `uname -r`** 才是 `6.x.y.z-microsoft-standard-WSL2`。两个都不能单独用来判定。
+
+- **README.md 三步复验第 ② 条**:判据改为 **`uname -s` ⇒ `MINGW64_NT-10.0-<build>`**(最硬)或 **`echo $MSYSTEM` ⇒ `MINGW64`**(最简),
+  并补一句"⚠️ 不要用 `uname -r` 判定"(附上两种 `uname -r` 的真实形态)。
+- **README_EN.md**:原文没有侧栏终端一节(英文 README 尚未跟进 v0.29.x),本次补上该节并把**同样更正过的**三步复验清单写进去,
+  使中英两处判据一致。
+- **AGENTS.md 验证清单第 10 条**:同一处错判据更正为 `uname -s`/`$MSYSTEM`,并写明为什么 `uname -r` 不能单独用;
+  同时明确**代码里的"一票否决"用的是 `bash -c "uname -s"`(`MINGW(32|64)_NT-*`),那一直是对的,未改动**。
+- **历史条目加指路**:v0.29.0 条目里留下的 `uname -r` 判据加"(判据有误,见 v0.29.2 更正)",不改写历史叙事。
+- **grep 复核**:全仓 `uname -r` 仅出现在 CHANGELOG 的历史条目(已加指路);`src/` 里只有 `uname -s`(`src/bash-path.js`
+  的一票否决与 `src/terminal-shell.js` 的注释),设置卡 21 语言文案与启动日志均未使用该判据。
+- 版本号 `0.29.1` → **`0.29.2`**(`package.json` 与 `dsh.plugin.json` 一致);`npm test` 101→102 全绿不受影响(纯文档)。
+
+## v0.29.1 — 2026-09-26
+
+**类型**:fix(用户实测:官方「新建终端」下拉里出现**两条 `bash`** —— 一条是 v0.29.0 写入的 Git Bash,另一条是官方 `shellCandidates` 解析到的 WSL,用户分不清)
+
+> 用户原话:**"改一下,新增的gitbash显示名称得是gitbash,不然回合wsl的混了,你反正自动检查说gitbash的给改名为gitbash,别叫bash"**
+> (现象:v0.29.0 写 `name: 'bash'`;官方 `shellCandidates` 那条 `bash` 在 PATH 命中 `C:\Windows\System32\bash.exe` 的机器上解析到 WSL)
+
+- **显示名改为 `Git Bash`**(`TERMINAL_SHELL_NAME`):`name` 只是 `TerminalShell.name` 这个**用户可见 profile 名**,解析与执行看 `path`/`args`
+  ⇒ 改它**不改变任何行为**,只让菜单里两项可区分;`args: ['-i']` 保留(官方 `profile()` 对 bash 的默认)。
+- **只迁移我们自己写的旧默认名**:`name` 恰为 `'bash'`(v0.29.0 的默认值)⇒ 新增 `rename` 动作,**只改 `name`**
+  (path/args 原样保留),同样**写回后读回校验**(路径与名字都对才成功),不符 ⇒ `write-failed` + fail-loud;
+  迁移后**再跑一次仍 `unchanged`**(幂等,patch md5 不变)。
+- **用户自起的名字绝不动(验收收窄,Lead 裁决)**:path 是我们的 Git Bash 但 `name` 是别的(`My Bash`/`Git`/空)
+  ⇒ 新状态 **`kept-user-name`,零写入**——用户显式起的名就是用户选择,而且自定义名本来也不会与 WSL 候选混淆。
+- **异值仍绝不覆盖**:path 指向别处(例如 WSL)⇒ 维持 `kept-user-choice`,只记日志。**`shellCandidates` 不动**
+  (与用户确认过的口径:改名即可区分;那条 WSL 候选仍会出现在菜单里,被区分开的是名字)。
+- 文案:README 的写入形状示例与 AGENTS §4i 同步为 `name: 'Git Bash'`;21 语言卡片文案无需改动(未提名字)。
+- **验证**:`npm test` **102/102**(新增「历史 `bash` 标签迁移 + 迁移后幂等 + 名字没落盘 ⇒ `write-failed [name mismatch]`」
+  与「用户自起名字 ⇒ `kept-user-name`、零写入、patch 不变(含 `My Bash`/`Git`/空名三态)」,
+  并把既有断言从 `name: 'bash'` 更新为 `name: 'Git Bash'`);`align-official` 四变体仍逐字节对齐。
+  真机(隔离 DSH_HOME + 副本强制 win32 门 + 伪装已解析 Git Bash):新建写入 ⇒ `--dump-config` 读出
+  `terminal-controller.config.shell.name = Git Bash`;预置历史 `name: bash` 的 patch ⇒ 日志 `renamed to "Git Bash"` 且
+  **只改这一行 name**、用户手写行与注释原样保留;二次启动 ⇒ patch **md5 未变**。
+- **未在 Windows 验证**:菜单里实际显示成 `Git Bash`(需用户复验;本次只验证到配置层的 `name` 与迁移行为)。
+
 ## v0.29.0 — 2026-09-26
 
 **类型**:feat(用户实测需求 —— DSH 原生「新建终端」落到 **WSL**,插件只接管了 agent 的 shell 工具,没有接管官方侧栏终端)
@@ -39,6 +84,7 @@
 - 新开关 `autoTerminalShell`(volatile,**默认开**;旧宿主 settings 命名空间同名字段,缺键 = 开)+ 21 语言卡片文案
   (`term.label`/`term.hint`);保留原 `dsh-better-sidebar` 通道(两条通道各自独立探测);不碰官方包、不手写用户 patch 文件。
 - README 新增该节 + **用户三步复验清单**(开关与日志 → 终端里 `uname -r` 判 `MINGW64_NT-*` → 回退办法)。
+  **(判据有误,见 v0.29.2 更正:Git Bash 的 `uname -r` 是 MSYS 运行时版本,应看 `uname -s` / `$MSYSTEM`。)**
   **回退语义写明**:关掉开关**只阻止以后的自动写入**,**不会**删除已经写进配置的 `shell` 字段;要彻底恢复原样需删掉
   profile patch 里 `terminal-controller` 行的 `shell` 字段并重启(21 语言卡片 hint 同步写上这一句)。
   **菜单如实说明**:未改 `shellCandidates` ⇒ 选择菜单里**仍可能列出**解析到 WSL 的候选 `bash`,被改的是**默认项/首项**。
@@ -53,7 +99,7 @@
   - 用户显式指向 `C:/Windows/System32/bash.exe` ⇒ `NOT adopted … an explicit choice is never overwritten`,patch **未变**;
   - `autoTerminalShell: false` ⇒ `adoption is off …`,patch **未变**;
   - 无头浏览器零 pageerror。
-- **未在 Windows 验证**:真实 PATH/注册表命中、菜单里 shell 项、新终端里 `uname -r` 是否 `MINGW64_NT-*`;
+- **未在 Windows 验证**:真实 PATH/注册表命中、菜单里 shell 项、新终端里 `uname -r` 是否 `MINGW64_NT-*`(判据有误,见 v0.29.2);
   设置卡新增开关行的截图级渲染(该行复用既有开关写法,21 语言键由冒烟 parity 覆盖)。需用户按 README 三步复验。
 - 相关:issue #11 后续(同一用户的 Windows 实测反馈)
 

package/README.md

@@ -154,9 +154,11 @@ DSH 自己的「新建终端」**不经过**本插件的执行器:它由官方
 新终端跑起来就是 Ubuntu。本插件现在会自动把它切过来:
 
 - 仅 **Windows**、且已解析出**通过验证**的 Git Bash 时;设置开关 **「自动接管侧栏终端」默认开启**(`autoTerminalShell`)。
-- 只在官方那一行**没有自己的 shell** 时写入 `{ path: <Git Bash>, name: bash, args: ['-i'] }`
-  (`-i` 就是官方对 bash 的默认参数)。**你已经手动指定过别的 shell(例如某个 WSL 配置)⇒ 绝不覆盖**,只在宿主日志里提示,
-  并告诉你如何交还给 Git Bash(清空该字段)。
+- 只在官方那一行**没有自己的 shell** 时写入 `{ path: <Git Bash>, name: 'Git Bash', args: ['-i'] }`
+  (`-i` 就是官方对 bash 的默认参数;**显示名固定为 `Git Bash`**,这样菜单里不会与那条解析到 WSL 的候选 `bash` 混淆)。
+  已经由 v0.29.0 写入过、名字还是 `bash` 的历史配置会在启动时**只改名字**(path/args 原样保留,幂等);
+  **只迁移我们自己写的那个旧默认名 `bash`** —— 你自己起的名字(例如 `My Bash`)一律不动(它本来也不会与 WSL 候选混淆)。
+  **你已经手动指定过别的 shell(例如某个 WSL 配置)⇒ 绝不覆盖**,只在宿主日志里提示,并告诉你如何交还给 Git Bash(清空该字段)。
 - 写入走**官方配置编辑器**(设置 UI 用的同一个 API),落到 profile 的 patch 层;**新终端立即生效**,已打开的终端保持原样。
 - **不需要重启**,也不会写坏「新建终端」:只写我们验证过存在的 Git Bash(官方对无法解析的路径没有回退,会直接启动失败)。
 - 失败时 **fail-loud**:日志写清原因,并通过**读回校验**确认值真的落进去了(不出现"假成功")。
@@ -167,7 +169,11 @@ DSH 自己的「新建终端」**不经过**本插件的执行器:它由官方
 **三步复验(Windows)**:
 1. 装好 Git for Windows,重启 DSH,打开本插件设置卡:开关「自动接管侧栏终端」为开;宿主日志出现
    `official sidebar terminal switched to Git Bash: …`。
-2. 新建终端,在终端里跑 `uname -r`:应看到 `MINGW64_NT-…`(WSL 会显示 Linux 内核版本如 `5.15…`)。
+2. 新建终端,在终端里确认**它确实是 Git Bash**(两条判据任选,**`uname -s` 最硬**):
+   - `uname -s` ⇒ `MINGW64_NT-10.0-<build>`(Git Bash 的 system name;WSL 这里是 `Linux`);
+   - `echo $MSYSTEM` ⇒ `MINGW64`(最简)。
+   ⚠️ **不要用 `uname -r` 判定**:Git Bash / MSYS2 下它是 **MSYS 运行时版本**(形如 `3.6.9-b4195d69.x86_64`,
+   真实用户实测就是这个值),而 **WSL 的 `uname -r`** 才是 `6.x.y.z-microsoft-standard-WSL2` —— 两者都不能单独用来判定。
 3. **回退**:⚠️ 关掉设置卡里的开关**只阻止以后的自动写入,不会删除已经写进配置的字段**。要彻底恢复原样,
    请把 profile 的 patch 里 `terminal-controller` 行的 `shell` 字段**删掉**,再重启 DSH(终端随即回到原来的 shell);
    只想让它别再自动改、但不介意保留现状的话,关开关即可。

package/README_EN.md

@@ -185,6 +185,26 @@ assembly, so zero prompt noise), path arguments and result metadata are no longe
 the file tools receive Windows paths. **Bash stays Git Bash either way** — the switch only
 governs the cross-tool path dialect.
 
+## Sidebar terminal (v0.29.0+): the official "new terminal" runs Git Bash
+
+dsh's own terminal is resolved by the official `terminal-controller` row, not by this plugin's executor. On a machine
+whose PATH `bash` is the WSL launcher, that terminal used to start Ubuntu. This plugin now writes the verified Git Bash
+into that row (only when the row has no shell of its own — an explicit choice is never overwritten; the display name is
+`Git Bash` so it cannot be confused with the WSL candidate, which is left in the menu). `shellCandidates` is untouched.
+
+**Three-step check (Windows)**
+
+1. Install Git for Windows, restart dsh, open this plugin's settings card: the "adopt the sidebar terminal" switch is on
+   and the host log shows `official sidebar terminal switched to Git Bash: …`.
+2. Open a new terminal and confirm it really is Git Bash (either check works; **`uname -s` is the hardest**):
+   - `uname -s` ⇒ `MINGW64_NT-10.0-<build>` (Git Bash's system name; WSL prints `Linux`);
+   - `echo $MSYSTEM` ⇒ `MINGW64` (simplest).
+   ⚠️ **Do not judge by `uname -r`**: under Git Bash / MSYS2 it is the **MSYS runtime version** (e.g.
+   `3.6.9-b4195d69.x86_64`), whereas WSL prints `6.x.y.z-microsoft-standard-WSL2` — neither can decide this alone.
+3. **Revert**: turning the switch off only stops FUTURE writes; it does not remove the `shell` field already written to
+   the profile config. To restore the original exactly, delete that field from the `terminal-controller` row in the
+   profile patch and restart dsh.
+
 ## Cooperation with dsh-better-sidebar
 
 When [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) (v0.15.2+) is installed, on Windows this plugin adopts its official runtime settings seam (`terminalShell` — by the sidebar's own contract, "settings-page overrides win for terminals opened afterwards"), so both the sidebar's UI terminal tabs and the model-facing `terminal_*` tools open Git Bash — no upstream change, new terminals pick it up immediately. In addition, this bundle's patch also sets `config.shell` on the sidebar's row (boot-time resolution, so the **tab label reads `bash` too**; the row edit is harmless-skipped when the sidebar is not installed). Rules:

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.29.0",
+  "version": "0.29.2",
   "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.29.0",
+  "version": "0.29.2",
   "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/terminal-shell.js

@@ -47,8 +47,18 @@ import { normalizeBashPath } from './bash-path.js'
 /** The Loader row id of the official terminal controller. */
 export const TERMINAL_ROW_ID = 'terminal-controller'
 
-/** Profile name written for Git Bash — matches the official `profile()` output. */
-export const TERMINAL_SHELL_NAME = 'bash'
+/**
+ * User-visible profile NAME written for Git Bash (v0.29.1).
+ *
+ * NOT `'bash'`: the official `shellCandidates` still contribute a `bash`
+ * candidate that resolves to the WSL launcher on machines whose PATH has
+ * `C:\Windows\System32\bash.exe`, and the new-terminal menu then showed TWO
+ * entries called `bash` — the user could not tell Git Bash from WSL ("改一下,
+ * 新增的gitbash显示名称得是gitbash,不然回合wsl的混了"). This is the
+ * `TerminalShell.name` display field only: resolution and execution use
+ * `path`/`args`, so renaming changes nothing but the label.
+ */
+export const TERMINAL_SHELL_NAME = 'Git Bash'
 
 /**
  * Arguments written for Git Bash. `['-i']` is not our invention: the official
@@ -58,6 +68,15 @@ export const TERMINAL_SHELL_NAME = 'bash'
  */
 export const TERMINAL_SHELL_ARGS = ['-i']
 
+/**
+ * The ONLY historical name we may rewrite (v0.29.1). v0.29.0 wrote `'bash'`,
+ * which is indistinguishable from the WSL candidate in the new-terminal menu —
+ * that entry is ours and we fix it. Any OTHER name (`My Bash`, `Git`, a hand
+ * edit) is a user decision and is left completely alone, exactly like a shell
+ * path pointing elsewhere: this plugin never rewrites what the user chose.
+ */
+export const LEGACY_TERMINAL_SHELL_NAME = 'bash'
+
 /**
  * The shell profile we write into `terminal-controller`'s config.
  * @param path - verified Git Bash path.
@@ -111,7 +130,28 @@ export function planTerminalAdopt({ platform, enabled, resolved, current }) {
     return { action: 'adopt', shell: terminalShellProfile(resolved.trim()), reason: 'the terminal has no shell configured; offering the verified Git Bash' }
   }
   if (normalizeBashPath(current.path) === normalizeBashPath(resolved)) {
-    return { action: 'unchanged', current, reason: 'the terminal already uses this Git Bash' }
+    if (current.name === TERMINAL_SHELL_NAME) {
+      return { action: 'unchanged', current, reason: 'the terminal already uses this Git Bash under the right name' }
+    }
+    // Only OUR OWN legacy default is migrated: v0.29.0 wrote `name: 'bash'`,
+    // and that is the entry the user cannot tell apart from the WSL candidate.
+    // Every other name is a user decision (or a hand edit) — left untouched.
+    if (current.name === LEGACY_TERMINAL_SHELL_NAME) {
+      return {
+        action: 'rename',
+        current,
+        shell: { ...current, name: TERMINAL_SHELL_NAME },
+        reason: 'the terminal runs this Git Bash under our own legacy label "'
+          + LEGACY_TERMINAL_SHELL_NAME + '" — renaming it to "' + TERMINAL_SHELL_NAME
+          + '" so it cannot be confused with the WSL candidate',
+      }
+    }
+    return {
+      action: 'kept-user-name',
+      current,
+      reason: 'the terminal runs this Git Bash but you named it "' + current.name
+        + '" — a chosen name is never rewritten (and a custom name cannot be confused with the WSL candidate)',
+    }
   }
   return {
     action: 'kept-user-choice',
@@ -143,9 +183,13 @@ export async function adoptTerminalShell(editor, { platform, enabled, resolved }
   }
   const current = currentTerminalShell(row)
   const plan = planTerminalAdopt({ platform, enabled, resolved, current })
-  if (plan.action !== 'adopt') {
+  if (plan.action !== 'adopt' && plan.action !== 'rename') {
     return { status: plan.action, current, detail: plan.reason }
   }
+  // `rename` keeps the profile the user already has and only rewrites the
+  // label; `adopt` writes the full profile. Both go through the same
+  // read-back verification below.
+  const renamed = plan.action === 'rename'
   if (typeof editor.edit !== 'function') {
     return { status: 'write-failed', current, detail: 'the config editor exposes no edit()' }
   }
@@ -163,14 +207,18 @@ export async function adoptTerminalShell(editor, { platform, enabled, resolved }
     return { status: 'write-failed', current, detail: 'the write succeeded but reading it back failed: ' + (error && error.message ? error.message : String(error)) }
   }
   const written = currentTerminalShell(after)
-  if (written === undefined || normalizeBashPath(written.path) !== normalizeBashPath(plan.shell.path)) {
+  const pathOk = written !== undefined && normalizeBashPath(written.path) === normalizeBashPath(plan.shell.path)
+  const nameOk = written !== undefined && written.name === plan.shell.name
+  if (!pathOk || !nameOk) {
     return {
       status: 'write-failed',
       current,
-      detail: 'the write did not stick: the terminal row reads ' + (written === undefined ? '(no shell)' : '"' + written.path + '"'),
+      detail: 'the write did not stick: the terminal row reads '
+        + (written === undefined ? '(no shell)' : '"' + written.path + '" as "' + written.name + '"')
+        + (pathOk ? '' : ' [path mismatch]') + (nameOk ? '' : ' [name mismatch]'),
     }
   }
-  return { status: 'adopted', path: plan.shell.path, current }
+  return { status: renamed ? 'renamed' : 'adopted', path: plan.shell.path, current, name: plan.shell.name }
 }
 
 /**
@@ -182,11 +230,16 @@ export async function adoptTerminalShell(editor, { platform, enabled, resolved }
 export function terminalAdoptReport(result) {
   switch (result.status) {
     case 'adopted':
-      return 'official sidebar terminal switched to Git Bash: ' + result.path + ' (name bash, args -i) — new terminals use it immediately, already-open ones keep their shell'
+      return 'official sidebar terminal switched to Git Bash: ' + result.path + ' (name "' + TERMINAL_SHELL_NAME + '", args -i) — new terminals use it immediately, already-open ones keep their shell'
+    case 'renamed':
+      return 'official sidebar terminal renamed to "' + TERMINAL_SHELL_NAME + '" (was displaying as "' + (result.current ? result.current.name : '?')
+        + '", same Git Bash path ' + result.path + ') — the entry is no longer confusable with the WSL candidate'
     case 'unchanged':
       return 'official sidebar terminal already uses this Git Bash: ' + (result.current ? result.current.path : '') + ' (nothing written)'
     case 'kept-user-choice':
       return 'official sidebar terminal NOT adopted: ' + result.detail
+    case 'kept-user-name':
+      return 'official sidebar terminal NOT renamed: ' + result.detail
     case 'write-failed':
       return 'official sidebar terminal adoption FAILED — ' + result.detail
         + ' | next steps: (1) the new-terminal shell is UNCHANGED, so dsh keeps its own resolution;'