dsh-gitbash-shell 0.39.2 → 0.39.3

package/CHANGELOG.md

@@ -3,6 +3,68 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.39.3 — 2026-10-14
+
+**类型**:fix(自有 bash 工具的宿主服务兼容 #27、MSYS 参数/编码提示、源码路径边界与 unconfined 可观测性) / test / docs。
+
+### issue #27:自有 bash 工具在无 `workingDirectory` 服务的宿主上永不注册
+
+- **根因(route B 镜像的契约盲区)**:自有 bash 工具镜像的是新版宿主(`0.2.1-alpha.x`)官方 tool-bash
+  的 `inject` 列表(含 `workingDirectory`),而兼容矩阵声明的 `0.2.0-rc.2` 上**没有该服务**——cordis 对
+  无法满足的 inject 让模块 fiber **永久 INACTIVE**:`apply()` 从不执行、工具永不注册、零错误日志,且
+  inline-tools 的激活日志照打(`await` 一个 INACTIVE fiber 会正常 resolve)——**假阳性成功**。
+  与 v0.24.0 settingsScope、v0.24.3 静态 peer import 同一失败类(静默失效、宿主日志全绿)。
+- **修复**:① `inject` 收敛为 `['tools', 'systemPrompt', 'shellEnv']`(服务最小面,`workingDirectory`
+  改为使用点 `ctx.get()` 可选读取);② cwd 接缝双向兼容——有 `workingDirectory` 的宿主走
+  `ensure()`(与新版官方一致),没有的宿主退回 rc.2 时代官方 `resolveWorkdir` 的同一条接缝
+  (`policy.workspaceRoot ?? session.header.cwd`),**不再落到宿主进程目录**;③ 激活日志必须经
+  `tools.schemas(agent)` 回读确认 `bash` 真正在册,不在册打显式失败行(点名 INACTIVE 可能性 +
+  请携带 dsh 版本报告)——**消除假阳性**。
+- **教训(§4l 追记⑧)**:镜像宿主模块时,`inject` 面是**契约面**——必须取兼容矩阵内**最老宿主**的
+  形状,或一律可选读取;「宿主新版本有」不等于「矩阵内都有」。
+- 报告者 largoalladonzella 提供了完整根因链(asar 字节级取证 + cordis `_refresh`/`_setEpoch` 源码 +
+  官方两版 inject 对照)与本机验证补丁;本仓库按其建议实现并补真断言。
+- 新增回归:无 `workingDirectory` 的最小 ctx 上 `apply()` 照常注册 + cwd 回退正确;有服务的宿主
+  `ensure()` 接缝不变;源码断言锁死硬 inject 列表与「回读门控激活日志」。本地全量 **168/168**(+1
+  win32-only skip)。
+
+### PR #24:超时转后台的独立 sandbox 警示
+
+- promoted 返回值显式携带可选 sandbox facts，输出 schema 保持闭合；defineTool 与 JSON-schema 回退共用此契约。
+- `renderPromoted` 自行追加 sandbox notes，不再依赖 output 预先含警示；promotion 输出保留丢失/spill 提示，
+  避免重复追加 sandbox 警示。无 sandbox/full-access 的原反馈保持不变，denied/runnerFailed 分支继续保留。
+- 纯回归改用不含警示的原始文本，覆盖空输出、full-access、拒绝与 runner failure。
+  新增实际 ToolRuntime→私有执行器→内存 provider 的 promotion 回归（Jobs wait/read 为受控桩），
+  验证 RO/WW 警示各出现一次、full 无警示、DTO 与最终模型文本分离、丢失/spill 提示及 root 服务不变。
+- 验证：普通完整回归 **166/166**、实际安装Core完整preview **18/18**，均exit0，无skip/cancel；
+  语法与diff检查通过。不等同于生产GUI或真实Jobs时钟验收。
+
+### MSYS 兼容边界尝试修复
+
+- **范围**:从 [`6b26ded`](https://github.com/KouzakiUmi/dsh-gitbash-shell/commit/6b26ded6cc3a2a6113579149286047629b433c48)
+  开出 `fix/msys-compatibility-boundaries`;不改 root PowerShell、market patch、生产 Profile、
+  安全默认或版本号。原生参数转换/混合编码/Windows shell confinement 不能在这层安全地普遍修好,
+  因此修工具提示与可观测性,不全局 EXCL=*、不猜码、不将警示冒充沙箱修复。
+- **源码路径**:run_code 的完整 Unicode 字母/组合字符/数字和含 `#` 文件名字面量走共享挂载表;
+  合法 EOF 行注释不再让整份重写弃权;tagged templates(含 String.raw、调用/索引 tag)保持原样,
+  避免 raw 设备路径被错误转义;of/await/yield 等上下文词可作 tag 时保守不改。
+  未闭合/不确定正则与除法仍整份 no-op,未扩展插值或动态表达式猜测。
+  词法层仍无法识别非路径数据的业务用途,提示明确建议直接 Node fs/path 用 native/cwd-relative 路径。
+- **提示门控**:真实 prompt listener 读取 live codePaths;OFF 不再承诺程序字符串会被翻译,
+  ON 改为 best-effort 并指出模板、动态/非路径数据限制。关闭 codePaths 不改变工具路径字段翻译。
+- **原生互操作**:登记的 bash 描述无条件说明 `/all`/`/c` 转换、双斜杠/单命令 EXCL 前缀及其
+  对 `/c/...` 的影响;检查预期效果而非只看 exit0。说明 UTF-8 捕获与 CP936/GBK 不匹配,
+  显式转码须在字节捕获前且保持退出状态;locale 与全流猜码不是普遍修复。
+- **unconfined 可见性**:执行句柄在等待 result() 前带 sandbox facts;前台正文、后台 outcome/
+  增量嵌入与超时转后台显示警示。后台登记输出联合新增可选 sandbox facts,指出计划执行边界,
+  不把未启动的 job 宣称为已经执行。保留原请求 mode,不把 unconfined 当 denial/escalation,
+  并明确不得通过 shell 绕过文件工具策略拒绝。双语说明区分文件读能力与 write/edit 围栏,
+  删除“所有未来版本都无解”的过度结论。
+- **验证**:新增9项兼容回归和1项后台登记回归,普通全量 **166/166**;新增3项实际 Core
+  ToolRuntime/执行句柄/run_code transport 回归,完整无头 preview **17/17**。旧护栏保留;打包 dry-run、语法和 diff
+  检查通过。新增 preview 使用实际宿主 API 与内存 subprocess,已有 preview 保留真实 Git Bash/
+  PowerShell 进程验收;不等同于生产 GUI、真实 PTC 引擎或新 confinement 方案验证。
+
 ## v0.39.2 — 2026-10-13
 
 **类型**:fix(route B 工具/预设生命周期、动态配置与客户端回归) / test。

package/README.md

@@ -118,20 +118,19 @@ bundle patch(`cordis.patch.yml`)是**纯新增**(v0.39.0 起):只插入本插件
 **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 能写出工作区、文件工具不能,**两者的边界并不一致**。
+- **为什么**:已验证的 Git Bash/MSYS 组合在现有 restricted-token 后端下初始化失败,
+  历史复现为 `msys-2.0.dll` 的 cygheap/signal-pipe 对象权限与 restricting-SID
+  二次写检查不兼容(Win32 error 5 / 0xC0000142)。当前没有提供可用的受限 Git Bash
+  实现,不声称所有未来运行时或隔离方案都无解。本插件保留**如实标注的绕过**;
+  没有静默回退 pwsh/cmd/WSL,本次兼容修复也没有恢复 shell 写入围栏。
+- **如何标注**:结果元数据保留
+  `sandbox: { mode: "<请求的模式>", denied: false, enforcement: "unconfined" }`;
+  工具描述、前台正文、后台登记及结果摘要、超时转后台反馈都明确警示 shell 写限制未生效。
+  后台登记标明的是计划采用的执行边界,不代表命令已经运行;实例首次调用另有日志。
+- **文件工具是另一层**:官方 fs-tool policy 对 write/edit 保留策略检查:
+  `read-only` 拒绝修改,`workspace-write` 只允许声明的工作区和平台临时可写根。
+  read/glob/grep 等读取并非一律限制在工作区内。shell 进程不受这些工具检查约束,
+  **两者的边界并不一致**;绝不能用 shell 绕过文件工具已返回的策略拒绝。
 - **可观察的对照**(相对 pwsh-sandbox 时代):会话进程的完整性级别不再被压低
   (Low → Medium);`$env:TEMP` 不再被重定向到 per-session 隔离目录。
 
@@ -396,6 +395,31 @@ PTC/创造及用户自建模式一律覆盖。
 都不再改写,文件工具收 Windows 路径。**bash 始终是 Git Bash,不受此开关影响**——它只决定
 跨工具的路径方言。
 
+## 原生 Windows 程序与 run_code 的兼容边界
+
+工具描述始终警示下面的参数、编码和安全限制;这些限制不随路径方言关闭而消失。
+插件**不会自动改写 command、全局关闭 MSYS 参数转换或猜测输出编码**。
+
+- **斜杠开关**:MSYS 在启动原生 Windows 程序时可能把 `/all`、`/c` 当路径。
+  本机已验证 `ipconfig //all`、`cmd //c` 或单命令
+  `MSYS2_ARG_CONV_EXCL='/all' ipconfig /all` 可保留开关。
+  排除值是前缀:排除 `/c` 也会影响真正的 `/c/...` 路径,该次原生调用应明确用
+  Windows drive-letter 路径。不要全局设置 `MSYS2_ARG_CONV_EXCL='*'`。
+  `cmd /c` 被转换后可能 exit0 却没有执行所需命令,应检查预期效果而非只看退出码。
+- **输出编码**:宿主按 UTF-8 解码;原生 Windows 程序可能输出 CP936/GBK 或其他代码页。
+  先使用程序自己的 UTF-8 输出选项,或在捕获前按已知编码显式转换字节,保持原退出状态。
+  `LANG/LC_ALL` 不保证改变原生程序的代码页。不要全流默认 GBK 或依替换字符数自动猜码:
+  同一 Bash 调用可能混合 UTF-8/GBK,已有乱码字符串也不能可靠恢复原字节。
+- **run_code**:`codePaths` 默认开,与 `posixPaths`/委托 gate 同时生效时,完整、可判定的
+  普通路径字面量按共享挂载表尽力转换,包括中文/组合字符/空格/`#` 文件名。
+  EOF 行注释不再阻止转换;tagged template(包括 String.raw)保持原样,避免破坏 raw/tag 语义。
+  插值模板、转义路径、不确定的正则/除法语法仍可能不改;不确定时整份 no-op。
+  直接调用 Node fs/path 时优先明确的 Windows drive-letter 或 cwd-relative 路径;
+  工具 path/file_path 字段仍走工具参数翻译。词法扫描不能识别路由、搜索数据或 shell
+  command 的用途;此类字符串不要依赖自动重写,必要时关闭 `codePaths`(提示同步标为 OFF)。
+- **沙箱**:参见上方安全章节。警示可见性得到修复,但 Windows shell 的 unconfined
+  取舍未改变,文件工具的策略拒绝绝不授权 shell 重试。
+
 ## 与 dsh-better-sidebar 联动
 
 装了 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)(v0.15.2+) 时,Windows 上本插件会通过**它的官方设置补丁口**(运行时 `terminalShell` 设置,对方文档明示"settings-page overrides win for terminals opened afterwards")把它打开的终端 shell 指向 Git Bash——**UI 终端标签与模型侧 `terminal_*` 工具统一生效**,不改对方一行代码、新开的终端即生效。此外,**本插件的 bundle patch 还会给对方的行补上 `config.shell`**(启动期解析,连 **tab 标题也会显示 bash**;对方未安装时该行无害跳过)。规则:

package/README_EN.md

@@ -93,24 +93,26 @@ restricted tokens, workspace fencing, denial classification, identical to
 **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**.
+- **Why**: tested Git Bash/MSYS combinations failed to initialize under the
+  existing restricted-token backend. Historical reproduction found cygheap/
+  signal-pipe object permissions incompatible with the restricting-SID write
+  check (Win32 error 5 / 0xC0000142). No working confined Git Bash implementation
+  is provided here; this is not a claim that every future runtime or isolation
+  design is impossible. The plugin retains its **labelled bypass**, with no
+  silent fallback to pwsh/cmd/WSL. Compatibility fixes do not restore confinement.
+- **How it is labelled**: results retain
+  `sandbox: { mode: "<requested mode>", denied: false, enforcement: "unconfined" }`.
+  The tool description, foreground text, initial background registration,
+  background outcome and timeout-promotion feedback warn that shell write
+  restrictions are not enforced. Initial registration describes the planned
+  boundary, not a claim that the command has already run; there is also a
+  one-time notice per executor instance.
+- **Official file tools have a separate policy**: write/edit still reject
+  mutations under `read-only`; `workspace-write` checks the declared workspace
+  and platform writable temp roots. Reads such as read/glob/grep are not all
+  limited to the workspace. Shell processes are not governed by these tool
+  checks — **the two boundaries differ**. Never bypass a file-tool policy
+  denial through shell.
 - **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.
@@ -125,6 +127,40 @@ official PowerShell executor was never touched by this plugin. The
 > 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.
 
+## Native Windows and run_code compatibility boundaries
+
+The tool description always warns about these argument, encoding and security
+boundaries, independently of the path-dialect switch. The plugin does not
+silently rewrite command source, globally disable argument conversion or guess
+output encodings.
+
+- **Slash options**: MSYS can treat native Windows `/all` and `/c` as paths.
+  Tested alternatives are `ipconfig //all`, `cmd //c`, or a per-command
+  `MSYS2_ARG_CONV_EXCL='/all' ipconfig /all`. Exclusions match prefixes: excluding
+  `/c` also excludes `/c/...` file paths, so explicitly use native drive-letter
+  paths for those arguments. Do not set `MSYS2_ARG_CONV_EXCL='*'` globally.
+  A converted `cmd /c` may exit0 without performing the intended action; verify
+  the expected effect, not only the exit code.
+- **Output encodings**: the host decodes UTF-8. Native programs may emit CP936/GBK
+  or another code page. Prefer a program's UTF-8 option, or explicitly convert
+  known-encoding bytes before capture while preserving the original exit state.
+  Locale variables do not guarantee native UTF-8. Do not decode all Bash output
+  as GBK or infer encoding from replacement-character counts: one call can mix
+  UTF-8 and GBK, and an already-corrupted string cannot recover the original bytes.
+- **run_code**: `codePaths` defaults ON and follows the total/delegate dialect
+  gates. Complete compatible plain path literals are rewritten best-effort with
+  the shared mount table, including Unicode letters/marks, spaces and `#` names.
+  Legal EOF line comments no longer prevent rewriting; tagged templates (such
+  as String.raw) retain their data and raw semantics. Interpolation, escapes,
+  uncertain regex/division syntax may remain unchanged; uncertainty abandons the
+  entire rewrite. Prefer native drive-letter or cwd-relative paths for direct
+  Node fs/path APIs; typed tool path arguments remain translated separately.
+  Lexical scanning cannot distinguish routes/search data/shell command strings
+  from paths. Do not rely on rewriting those values; disable `codePaths` when
+  needed (the model hint now accurately states OFF).
+- **Security**: warnings are now visible, but Windows unconfined behavior is
+  unchanged. A file-tool policy denial never authorizes a shell retry.
+
 ## Config
 
 The `gitbash-shell` row (its id has matched the settings namespace since v0.24.0; it was

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.39.2",
+  "version": "0.39.3",
   "main": "./src/index.js",
   "description": "Windows 全模式 Git Bash:自带 bash 工具(私有 Git Bash 执行器实例,官方 PowerShell 执行器原样保留),官方四个模式经行内工具补位直接获得 Git Bash(v0.35.0 起;v0.39.0 起不再替换宿主执行器),四个 *·Git Bash 变体 preset 可开关;官方 pwsh 工具默认隐藏、开关可见(真 PowerShell);附带 gb_* FastCtx 文件工具,检测到 dsh-ops 自动让位。联动:dsh-ptc-cordis-preset(PTC 创造模式带 Git Bash 行且可去重)+ dsh-better-sidebar(终端标签自动切 Git Bash)。",
   "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gitbash-shell",
-  "version": "0.39.2",
+  "version": "0.39.3",
   "description": "Windows 上给 agent 一个真正的 Git Bash 命令工具:私有 Git Bash 执行器实例(官方 PowerShell 执行器原样保留),统一 MSYS 盘根路径方言,官方 pwsh 工具默认隐藏可开关,物化四个内置预设的 Git Bash 变体,侧栏终端接管可开关。· Give agents a real Git Bash tool on Windows: a private Git Bash executor instance (the official PowerShell executor stays untouched), a unified MSYS drive-root path dialect, an opt-in official pwsh tool, and four Git Bash preset variants.",
   "type": "module",
   "repository": {
@@ -52,7 +52,7 @@
     "icon.svg"
   ],
   "scripts": {
-    "test": "node --test tests/smoke.mjs tests/private-executor.mjs tests/client-regressions.mjs tests/bridge-regressions.mjs tests/runtime-regressions.mjs tests/host-regressions.mjs",
+    "test": "node --test tests/smoke.mjs tests/private-executor.mjs tests/client-regressions.mjs tests/bridge-regressions.mjs tests/runtime-regressions.mjs tests/host-regressions.mjs tests/compatibility-regressions.mjs",
     "test:preview": "node --import ./tests/host-loader.mjs --test tests/preview.mjs tests/bridge-preview.mjs tests/runtime-preview.mjs tests/host-preview.mjs",
     "version": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('dsh.plugin.json','utf8'));const v=JSON.parse(fs.readFileSync('package.json','utf8')).version;m.version=v;fs.writeFileSync('dsh.plugin.json',JSON.stringify(m,null,2)+'\\n')\" && git add dsh.plugin.json"
   },

package/src/bash-render.js

@@ -7,7 +7,7 @@
  * here). Instead the plugin ships its OWN bash tool whose executor is a private
  * `GitBashSandboxExecutor` instance (never registered as a service), and this
  * file mirrors the official tool's rendering contract call-for-call so the
- * model sees byte-identical output shapes:
+ * model sees the official output shapes, with an explicit unconfined warning:
  *
  *   - `render.ts` of `@deepseek-ai/dsh-tool-bash` (result / promoted / job-read
  *     text shaping), and
@@ -28,6 +28,17 @@ export function sandboxDenialMarker(mode) {
   return `[sandbox: file access denied under ${mode} mode]`
 }
 
+/** A capability warning, not a denial or permission to bypass another denial. */
+export function sandboxUnconfinedMarker(mode) {
+  return `[sandbox: Git Bash is unconfined on Windows — shell file-write restrictions are NOT enforced (requested mode: ${mode}); official file-tool write/edit policy still applies; never bypass its denial through shell]`
+}
+
+/** Include the planned execution boundary even before the job has spawned. */
+export function renderBackground(jobId, sandbox) {
+  const notes = sandboxNotes(sandbox, [])
+  return `started background job ${jobId}${notes.length ? '\n' + notes.join('\n') : ''}`
+}
+
 /** The official same-turn escalation hint (escalation.ts:84). */
 export function escalationHintMarker(subject) {
   return `[sandbox: escalation available — retry this exact ${subject} once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`
@@ -84,6 +95,7 @@ export function renderResult(result, escalationModes = []) {
     markers.push(sandboxDenialMarker(result.sandbox.mode))
     if (escalationModes.length > 0) markers.push(escalationHintMarker('command'))
   }
+  if (result.sandbox?.enforcement === 'unconfined') markers.push(sandboxUnconfinedMarker(result.sandbox.mode))
   // A command may trap SIGTERM and exit 0 after timeout; still report interruption.
   if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
   // A kill from outside the call (the human stopping its job) is not a
@@ -103,16 +115,19 @@ export function renderResult(result, escalationModes = []) {
 /**
  * Shape a foreground call that stopped waiting into the text the model sees.
  * Mirrors the official `renderPromoted` (tool-bash render.ts:77).
- * @param {{ jobId: string, timeoutMs: number, output: string }} promoted
+ * @param {{ jobId: string, timeoutMs: number, output: string, sandbox?: object }} promoted
+ * @param {string[]} [escalationModes]
  * @returns {string}
  */
-export function renderPromoted(promoted) {
+export function renderPromoted(promoted, escalationModes = []) {
   const body = promoted.output.length > 0
     ? (promoted.output.endsWith('\n') ? promoted.output : `${promoted.output}\n`)
     : ''
-  return `${body}[still running after ${promoted.timeoutMs}ms; moved to background job ${promoted.jobId}]\n`
+  const text = `${body}[still running after ${promoted.timeoutMs}ms; moved to background job ${promoted.jobId}]\n`
     + 'The command keeps running in the background. You will be notified when it finishes; '
     + 'read newer output with job_output, stop it with job_kill.'
+  const notes = sandboxNotes(promoted.sandbox, escalationModes)
+  return notes.length > 0 ? `${text}\n${notes.join('\n')}` : text
 }
 
 /**
@@ -129,6 +144,7 @@ function sandboxNotes(sandbox, escalationModes) {
     if (escalationModes.length > 0) notes.push(escalationHintMarker('command'))
     return notes
   }
+  if (sandbox?.enforcement === 'unconfined') return [sandboxUnconfinedMarker(sandbox.mode)]
   return []
 }
 
@@ -192,12 +208,7 @@ export function renderJobRead(delta, lossy, spillPaths, sandbox, escalationModes
     const paths = Array.isArray(spillPaths) ? spillPaths : []
     notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
   }
-  if (sandbox && sandbox.runnerFailed) {
-    notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`)
-  } else if (sandbox && sandbox.denied) {
-    notices.push(sandboxDenialMarker(sandbox.mode))
-    if (escalationModes.length > 0) notices.push(escalationHintMarker('command'))
-  }
+  notices.push(...sandboxNotes(sandbox, escalationModes))
   if (notices.length === 0) return delta
   return `${delta}${delta.length > 0 && !delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
 }

package/src/bash-tool.js

@@ -43,6 +43,7 @@
 import {
   ESCALATION_TARGETS,
   parseExitStatus,
+  renderBackground,
   renderJobRead,
   renderPromoted,
   renderResult,
@@ -86,7 +87,7 @@ export async function resolveHostModule(ctx, name) {
 }
 
 /**
- * The official bash description (tool-bash index.ts:90), verbatim.
+ * The official bash description plus unavoidable Git for Windows boundaries.
  * @returns {string}
  */
 export function bashDescription() {
@@ -97,7 +98,11 @@ export function bashDescription() {
     + 'Provide `description` before `command` in the arguments. '
     + 'Before any delete or move, verify that the resolved absolute target path is the intended one; never run it against a computed path you have not checked. '
     + 'An unset variable expands to an empty string, so guard variables in such paths with `${VAR:?}`. '
-    + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]`, a policy denial: do not retry another way.'
+    + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]`, a policy denial: do not retry another way. '
+    + 'Git for Windows (MSYS) converts path-looking arguments when invoking native Windows programs: ipconfig /all and cmd /c may break; use ipconfig //all or cmd //c, or a per-command MSYS2_ARG_CONV_EXCL prefix. '
+    + 'Exclusions are prefixes: excluding /c also excludes /c/... paths, so use native drive-letter paths for those arguments; do not disable conversion globally. Verify the expected effect as well as the exit code. '
+    + 'Output is decoded as UTF-8; native Windows programs may emit OEM/ANSI bytes (for example CP936/GBK) and display garbled text. Use a program UTF-8 option or explicit known-encoding conversion before capture; locale variables alone do not fix native output, and mixed streams cannot safely be guessed or decoded globally as GBK. '
+    + 'On Windows, this Git Bash route does NOT enforce shell file-write restrictions in read-only/workspace-write mode (unconfined). Official file-tool write/edit policy is separate; never use shell to bypass its denial.'
 }
 
 /** The official foreground/present call view (index.ts:108). */
@@ -187,9 +192,17 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
   kind: { type: 'string', required: true, const: 'background' },
   jobId: { type: 'string', required: true },
   cwd: { type: 'string', required: true },
+  sandbox: {
+    type: 'object', additionalProperties: false,
+    properties: {
+      mode: { type: 'string', required: true },
+      denied: { type: 'boolean', required: true },
+      enforcement: { type: 'string' },
+    },
+  },
 }
 
-/** The official output union in the spec dialect defineTool consumes (index.ts:402). */
+/** The official output union, with optional background sandbox facts. */
 function outputSchemaSpec() {
   return {
     oneOf: [
@@ -203,6 +216,10 @@ function outputSchemaSpec() {
           jobId: { type: 'string', required: true },
           timeoutMs: { type: 'number', required: true },
           output: { type: 'string', required: true },
+          sandbox: {
+            ...BACKGROUND_OUTPUT_PROPERTIES.sandbox,
+            properties: { ...BACKGROUND_OUTPUT_PROPERTIES.sandbox.properties, runnerFailed: { type: 'boolean' } },
+          },
         },
       },
       {
@@ -319,7 +336,12 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
     : (subject) => `The narrowest wider sandbox mode for a one-shot retry of the exact ${subject} the sandbox just denied; the retry asks the user for approval.`
 
   return {
-    inject: ['tools', 'systemPrompt', 'shellEnv', 'workingDirectory'],
+    // workingDirectory is NOT a service on every host this plugin claims
+    // compatibility with (0.2.0-rc.2 has none — issue #27). A missing hard
+    // inject leaves the whole module fiber permanently INACTIVE: apply() never
+    // runs, the tool never registers, and cordis logs nothing. Read it
+    // optionally at the use site (below) instead of injecting it.
+    inject: ['tools', 'systemPrompt', 'shellEnv'],
     apply(ctx, config = {}) {
       const backgroundEnabled = config?.enableRunInBackground ?? true
       const promoteOnTimeout = (config?.promoteOnTimeout ?? true) && backgroundEnabled
@@ -424,14 +446,17 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
           }
           if (view.status === 'running' || view.status === 'stopping') {
             const read = registry.read(attached.id, owner)
+            const sandbox = attached.process()?.sandbox
             return {
               kind: 'promoted',
               cwd: spec.workdir,
               jobId: attached.id,
               timeoutMs,
+              // Preserve ring/spill notices; sandbox notes belong to the final renderer.
               output: renderJobRead(
-                ringDelta(read.chunks), read.lossy, read.job.output.spillPaths ?? [], attached.process()?.sandbox, escalationModes,
+                ringDelta(read.chunks), read.lossy, read.job.output.spillPaths ?? [], undefined, escalationModes,
               ),
+              ...(sandbox === undefined ? {} : { sandbox }),
             }
           }
           registry.remove(attached.id, owner)
@@ -486,7 +511,16 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
           const policy = approvedMode === undefined
             ? standingPolicy
             : { ...standingPolicy, mode: approvedMode }
-          const cwd = exec.agent === undefined ? undefined : await ctx.workingDirectory.ensure(exec.agent, exec.signal)
+          // Optional read (issue #27): on hosts that provide workingDirectory
+          // this is the same ensure() seam the modern official tool-bash uses;
+          // on hosts without it, fall back to the session cwd exactly the way
+          // the rc.2-era official resolveWorkdir did (policy root ?? header).
+          const workingDirectory = ctx.get !== undefined ? ctx.get('workingDirectory') : undefined
+          const cwd = exec.agent === undefined
+            ? undefined
+            : workingDirectory !== undefined
+              ? await workingDirectory.ensure(exec.agent, exec.signal)
+              : (standingPolicy?.workspaceRoot ?? exec.agent?.session?.header?.cwd)
           const workdir = resolveWorkdir(args.workdir, cwd)
           const dshEnv = ctx.shellEnv.collect(exec)
           const request = {
@@ -505,7 +539,15 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
             }
             if (exec.signal.aborted) throw toolAborted(llmModule?.HarnessError)
             const spec = executor.resolve({ ...request, onExpiry: 'none' })
-            return { kind: 'background', jobId: startJob(jobs, args, exec, spec).id, cwd: spec.workdir }
+            // The job may still be preparing: expose the planned route, not a
+            // claim that the command has already run or been confined.
+            const route = typeof executor.gitBashRoute === 'function' ? executor.gitBashRoute(spec) : undefined
+            const sandbox = route === undefined ? undefined : {
+              mode: route.mode, denied: false,
+              ...(route.unconfined ? { enforcement: 'unconfined' } : {}),
+            }
+            return { kind: 'background', jobId: startJob(jobs, args, exec, spec).id, cwd: spec.workdir,
+              ...(sandbox === undefined ? {} : { sandbox }) }
           }
           if (jobs !== undefined && promote) {
             const spec = executor.resolve({ ...request, onExpiry: 'none' })
@@ -534,9 +576,9 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
               render: (_args, value) => [{
                 type: 'text',
                 text: value.kind === 'background'
-                  ? `started background job ${value.jobId}`
+                  ? renderBackground(value.jobId, value.sandbox)
                   : value.kind === 'promoted'
-                    ? renderPromoted(value)
+                    ? renderPromoted(value, escalationModes)
                     : renderResult(value, escalationModes),
               }],
               presentationMeta: (_args, value) => ({ cwd: value.cwd }),
@@ -564,9 +606,9 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
             render: (_args, value) => [{
               type: 'text',
               text: value.kind === 'background'
-                ? `started background job ${value.jobId}`
+                ? renderBackground(value.jobId, value.sandbox)
                 : value.kind === 'promoted'
-                  ? renderPromoted(value)
+                  ? renderPromoted(value, escalationModes)
                   : renderResult(value, escalationModes),
             }],
             presentationMeta: (_args, value) => ({ cwd: value.cwd }),

package/src/index.js

@@ -612,15 +612,15 @@ const POSIX_DIRECTIVE_TEXT_STRICT = 'The working shell is Git for Windows bash:
  * write paths into, so the sentence would be pure noise there. Cheap and
  * honest: the tool list of the very assembly being rendered decides.
  */
-const RUN_CODE_DIRECTIVE_TEXT = ' Path literals written inside a run_code program are translated the same way before the program runs; shell expansion is not available there, so spell paths out instead of relying on $VARS.'
-const RUN_CODE_DIRECTIVE_STRICT_TEXT = ' Path literals written inside a run_code program are translated before the program runs.'
+const RUN_CODE_DIRECTIVE_TEXT = ' In a run_code program, compatible plain MSYS path literals are translated on a best-effort basis; interpolated or tagged templates and uncertain syntax are not rewritten. For direct native Node fs/path APIs, prefer explicit Windows drive-letter or cwd-relative paths. Do not rely on literal rewriting for dynamic paths, shell command strings, routes or search data; tool path arguments are translated separately. Shell expansion is unavailable in program strings, so do not rely on $VARS.'
+const RUN_CODE_DIRECTIVE_OFF_TEXT = ' In a run_code program, automatic path-literal rewriting is OFF. Direct native Node fs/path APIs require Windows drive-letter or cwd-relative paths, not MSYS /c/... strings. Tool path arguments are still translated separately; program strings do not perform shell expansion.'
 
 /** The run_code sentence for this assembly, or '' when the tool is not offered. */
-export function runCodeHintFor(tools) {
+export function runCodeHintFor(tools, codePaths = true) {
   if (!Array.isArray(tools)) return ''
   for (const tool of tools) {
     const name = tool && typeof tool.name === 'string' ? tool.name : ''
-    if (name === 'run_code') return RUN_CODE_DIRECTIVE_TEXT
+    if (name === 'run_code') return codePaths === true ? RUN_CODE_DIRECTIVE_TEXT : RUN_CODE_DIRECTIVE_OFF_TEXT
   }
   return ''
 }
@@ -1155,15 +1155,15 @@ export function translatePathArguments(args, env) {
 // sees it (see AGENTS.md 4c). The same mount table is therefore applied to the
 // program's string literals — but ONLY when the whole program scans cleanly and
 // a literal's ENTIRE content is an absolute MSYS path. Anything unclear — an
-// unterminated literal, a template with ${} interpolation, a regex we cannot
-// place — turns the whole rewrite into a no-op: a half-rewritten program would
+// unterminated literal or a regex we cannot place — turns the whole rewrite
+// into a no-op. Interpolated/tagged templates are skipped as data. A partial guess would
 // be far worse than an untranslated one, and this layer never guesses.
 //
 // Deliberately NOT translated: shell-style '$VAR/x' (a JS literal is data, not
 // a shell word) and anything carrying a scheme ('http://...').
 
 /** Source text allowed inside a rewritten literal: no escapes, no dollar sign. */
-const CODE_LITERAL_SAFE = /^[A-Za-z0-9._@+~\-/ ]+$/
+const CODE_LITERAL_SAFE = /^[\p{L}\p{M}\p{N}._@+~#\-/ ]+$/u
 
 /** Previous significant character that lets a '/' start a regex literal. */
 function regexCanStart(previous) {
@@ -1309,7 +1309,8 @@ export function scanCodeLiterals(code) {
     const next = code[i + 1]
     if (c === '/' && next === '/') {
       const nl = code.indexOf('\n', i)
-      if (nl === -1) return null
+      // A line comment may legally terminate at EOF (outside interpolation).
+      if (nl === -1) break
       i = nl
       continue
     }
@@ -1330,7 +1331,12 @@ export function scanCodeLiterals(code) {
     if (c === '`') {
       const template = skipTemplateLiteral(code, i)
       if (template === null) return null
-      if (template.plain) spans.push({ start: i + 1, end: template.end - 1 })
+      // A preceding expression can be a tag (String.raw, fn(), obj[key], ...).
+      // Tags own raw/cooked semantics: never rewrite their template data.
+      // Contextual words can also be identifiers/tags; skip rather than guess.
+      if (template.plain && regexCanStart(last) && !['of', 'await', 'yield'].includes(last)) {
+        spans.push({ start: i + 1, end: template.end - 1 })
+      }
       i = template.end
       last = 'x'
       continue
@@ -1489,7 +1495,12 @@ export function translateGlobArguments(args, env) {
 // captured and restored on disposal (reload/update/uninstall), so removing
 // this plugin returns the sidebar to what it was before.
 
-const SIDEBAR_NS = 'dsh-better-sidebar'
+// The settings namespace is the row id in dsh-better-sidebar's own bundle
+// patch (`- id: better-sidebar`; verified against the published 0.25.0
+// tarball) — NOT the npm package name. Using the package name made
+// settings.describe() never match and every takeover silently no-op with one
+// "unavailable" log line (issue #25, Bug 3).
+const SIDEBAR_NS = 'better-sidebar'
 const SIDEBAR_TRIES = 12
 const SIDEBAR_RETRY_MS = 1500
 
@@ -2179,7 +2190,7 @@ export async function apply(ctx, config = {}) {
             // v0.20.1: the run_code sentence rides the SAME context entry, but
             // only when this assembly actually offers the tool (see
             // runCodeHintFor) — every other mode stays quiet.
-            const hint = runCodeHintFor(assembly.tools)
+            const hint = runCodeHintFor(assembly.tools, dialect.codePaths === true)
             if (hint !== '') {
               for (const assembled of Array.isArray(assembly.contexts) ? assembly.contexts : []) {
                 if (assembled && assembled.name === 'gitbash-shell:posix-paths' && typeof assembled.text === 'string') {

package/src/inline-tools.js

@@ -286,7 +286,18 @@ export function mountInlineTools(ctx, deps) {
       await untilDisposed(fiber, state.controller.signal)
       if (!isLive(agent, state)) return
       retained = true
-      log('own bash tool activated for this agent (Git Bash execution; official pwsh tool real but hidden by default)')
+      // An INACTIVE fiber resolves its await() without ever running apply()
+      // (issue #27): awaiting the plugin proves nothing, so read the registry
+      // back before claiming success. A miss gets an explicit failure line —
+      // never a silent no-tool session behind a success-shaped log.
+      const registeredNames = scope.ctx.get !== undefined
+        ? ((scope.ctx.get('tools')?.schemas?.(agent) ?? []).map((schema) => schema && typeof schema.name === 'string' ? schema.name : ''))
+        : []
+      if (registeredNames.includes('bash')) {
+        log('own bash tool activated for this agent (Git Bash execution; official pwsh tool real but hidden by default)')
+      } else {
+        log('own bash tool did NOT register for this agent: the module fiber likely went INACTIVE (this host lacks an injected service the module requires) or the tools read-back is unavailable — bash is NOT available in this session; please report this with your dsh version (issue #27 pattern)')
+      }
     } catch (error) {
       if (isLive(agent, state)) log(`own bash tool activation failed for this agent: ${error?.message ?? error}`)
     } finally {

package/src/shell.js

@@ -10,25 +10,23 @@
  * and hands it to the plugin's OWN bash tool (src/bash-tool.js). The class
  * body is unchanged from its executor-row era:
  *
- *   - extends @deepseek-ai/dsh-bash-sandbox so every confined-mode
- *     (read-only / workspace-write) call keeps the exact sandbox policy,
- *     denial, and runner-failure semantics of the shipped stack;
+ *   - extends @deepseek-ai/dsh-bash-sandbox to inherit policy, denial and
+ *     lifecycle semantics EXCEPT the explicit Windows unconfined route below;
  *   - overrides `confine` so the inner argv is [git-bash, -c, command];
  *   - overrides run/start ONLY for danger-full-access (the parent's
  *     full-access branch calls LocalBashExecutor.run, which hardcodes the
  *     bare `bash` name), routing through runArgv/startArgv with the same
  *     argv as the confined branch;
  *   - on Windows ALSO overrides the confined branch itself (issue #1):
- *     MSYS2 cannot start under the restricted-token sandbox — msys-2.0.dll
- *     init creates its cygheap mapping and signal pipe with DACLs naming
- *     only the user SID, 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 (silent fake-success or a hard
- *     crash, every version since 0.6.0; cmd/pwsh are unaffected —
- *     anonymous pipes). OS-level conflict with no in-plugin cure, so
- *     confined Windows calls run Git Bash UNCONFINED, labelled as such in
- *     the result (sandbox.enforcement === 'unconfined') plus a one-time
- *     notice. The fs-tool sandbox policy still applies to file tools.
+ *     historical MSYS2/restricted-token tests failed during msys-2.0.dll
+ *     cygheap/signal-pipe initialization (Win32 error 5 / 0xC0000142;
+ *     restricting-SID object permissions, CHANGELOG v0.13.2). No working
+ *     confined Git Bash implementation is provided here; this is not a claim
+ *     that every future runtime/isolation design is impossible. Windows calls
+ *     retain the explicit UNCONFINED route, labelled on the handle/result and
+ *     in model-facing foreground/background text, plus a one-time notice.
+ *     Official file-tool write/edit policy remains separate; it does not
+ *     constrain shell code and its denials must never be bypassed through shell.
  *
  * Environment inheritance: bash.exe is spawned as a direct child of the host
  * process (never through the git-bash.exe login launcher), so it inherits the
@@ -262,6 +260,8 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
    * @returns the same handle, with `result()` mapped.
    */
   static decorateExecution(ex, sandbox) {
+    // Background reads/outcomes inspect the handle before result() settles.
+    ex.sandbox = sandbox
     const base = ex.result.bind(ex)
     let decorated
     ex.result = () => {
@@ -407,7 +407,7 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
   warnConfinedUnconfined(mode) {
     if (this._warnedUnconfined) return
     this._warnedUnconfined = true
-    console.log(TAG + ' Windows: MSYS2 cannot start under the restricted-token sandbox (msys-2.0.dll init: cygheap/signal-pipe DACLs carry no restricting-SID ACE -> Win32 error 5 / 0xC0000142; issue #1). Confined call (' + mode + ') ran Git Bash UNCONFINED; the fs-tool sandbox policy still applies.')
+    console.log(TAG + ' Windows: confined Git Bash is not provided by this restricted-token backend (issue #1). Requested mode ' + mode + ' will use an UNCONFINED Git Bash route: shell file-write restrictions are NOT enforced. Official file-tool write/edit policy is separate; never bypass its denial through shell.')
   }
 }