dsh-gitbash-shell 0.39.4 → 0.40.1

package/CHANGELOG.md

@@ -3,6 +3,169 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.40.1 — 2026-10-15
+
+### 清理 gitbash_native 的两个死配置读取（chore）
+
+- 删除 `gitbash_native` 模块对 `config.enableRunInBackground`/`config.promoteOnTimeout` 的读取（[v0.40.0 已知项](#v0400--2026-10-15)就此销账）：该模块由 inline 接线**手动挂载在 agent scope**（`scope.ctx.plugin({...module})` 无参调用），行/执行器 Config 不可达，两个字段自 v0.40.0 起读到的恒为 undefined、按 `!== false` 恒开——是"没接线的开关面板"而非活门控。清理后行为一个字节不变：`background` 仅由 Jobs 注册表在场决定（这正是实际生效的逻辑），超时转 Job 跟随后台可用性；用户级开关仍是 `experimentalNative` 总闸（要关 native 后台只能整体关闭 native/path，官方 tool-bash 的同名活开关不受影响）。
+- 模块 `apply(ctx)` 签名不再收 config，并加注释说明挂载差异与官方 tool-bash 的区别；`tests/native-preview.mjs` 装置同步（装置曾以 `plugin(mod, { promoteOnTimeout })` 作为**测试注入点**参数化 promote——删除后装置不再传第二参；唯一的 promote 场景（jobs 在场断言 promoted）清理前后行为一致）。**preview 改动待 Windows 真机复验**（本机 Node 24 无法运行 preview 套件；`npm test` 普通回归 235 pass + 1 skip / 0 fail）。
+- 保留说明：`src/bash-tool.js` 的 `config?.enableRunInBackground ?? true` 防御式读取**不清理**——bash 工具是官方 tool-bash 的逐调用镜像物，这两个字段在官方行 Config 上真实存在且可关；我们的镜像接不到行 Config 时按 `?? true` 显式走官方默认，语义是"默认开"而非"假装可配"。
+- 相关：[PR #26](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26) 评审遗留清理。
+
+## v0.40.0 — 2026-10-15
+
+### PR #26 合并：实验原生执行 / fail-closed（feat / docs）
+
+- [KouzakiUmi 的实验性 RFC](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26)经维护者两步评审后 squash 合并（[74f0186](https://github.com/KannaKuron/dsh-gitbash-shell/commit/74f01865a1046f8d2fae053fd4b7d1dfd93694a0)）：
+  - **`experimentalNative` 开关（默认开，可实时关）**：开启时 Windows read-only/workspace-write/缺失策略的 Git Bash 在工作目录准备、Jobs admission 与 argv 解析之前拒绝（宿主真 `SandboxUnavailableError`，导出缺失仍拒绝）；关闭时实时注销 `gitbash_native`/`gitbash_to_native_path` 并恢复明确标注 `enforcement: 'unconfined'` 的旧 Bash（缺失策略保持旧版宿主委派）。拒绝文案指路设置开关与会话访问模式控件，Agent 不得自动换工具/模式绕过。
+  - **`gitbash_native`**：typed argv（literal/path 二值、4096 项 / 30000 字符、仅 `.exe`、已知解释器强制显式 `entrypoint: interpreter`）、逐流显式编码（utf8/gbk/utf16le/raw，无 auto，spawn 前 fatal 探测）、prepared capability（WeakMap，不可伪造 DTO）、8MiB/16MiB 输出预算（双流共享、UTF-8 游标对齐）、Jobs 提升（超时转 managed job，admission 不重试）、解码/存储失败绝不改写命令真实结局。仅 danger-full-access 策略放行。
+  - **`gitbash_to_native_path`**：显式整值 MSYS→Windows 转换（`msys_path` 刻意避开翻译层白名单）；无 I/O、无权限授予；无挂载映射时显式拒绝，绝不把 POSIX 拼写冒充 `native_path`。
+  - **共享注册入口**：每次开关/Jobs 刷新先注销自身再检查所有权（knownNames 含隐藏工具，旧宿主回退 schemas）；外部占名让位、注册失败不阻断其他 companion、OFF→ON 恢复。
+  - **路由提示**：`bash`/`run_code` 的提示块改为按实际工具面生成的可替换幂等块；PTC 只提「SDK 实际提供的 binding」。
+- 评审确认：拒绝时序、开关四态多点重读、与 v0.39.4 翻译层零交集（`msys_path`/`native_path`/`executable`/`argv`/`cwd` 均不在 `TRANSLATABLE_PATH_FIELDS`）、平台门控（POSIX 受限调用走父类真沙箱）。
+- 文档修正（维护者评审发现，合并后在 main 修正）：设计文档 §3 组合盲点句原写「同装 dsh-ops 的受限会话均无命令工具」，与 `inline-tools.js` 的 `hidePwsh && !opsPresent` 短路矛盾——`ops_*` 在场时 pwsh 不被遮蔽，官方执行器带真围栏，受限会话是「无 bash 但 pwsh 可用」。
+- 已知项（后续清理）：`gitbash_native` 的 Jobs 门控字段 `enableRunInBackground`/`promoteOnTimeout` 从 agent scope 读取，行 Config 不可达，实际恒开；行为无害，`experimentalNative` 总开关仍可整体关闭。
+- 验证：维护者本地（macOS/Node 24.21）`npm test` 235 pass + 1 skip（原有 macOS-only 项）/ 0 fail；贡献者 Windows（Node 24.13.0/Core 0.2.1-alpha.2）普通回归 236/236 + 实际 Core 完整 preview 86/86；分支 CI ubuntu+windows × Node 22/24 全绿。
+- 实验帽子保留：真实 Agent 自主选路、生产 GUI、维护者 Windows 全量验证、非 CRT 解释器矩阵四项门槛正式确认前，`experimentalNative` 命名与文档定位不变。
+- 相关：[PR #26](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26)、[评审评论](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26#issuecomment-6186822600)。感谢 @KouzakiUmi 的完整 RFC、隔离子代理自审与三轮收敛。
+
+### PR #26：第一轮设计评审后 rebase 到 v0.39.4（fix / test / docs）
+
+- 按[维护者第一轮设计评审](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26#issuecomment-6182031633)将实验分支 rebase 到[上游 v0.39.4 main（52da331）](https://github.com/KannaKuron/dsh-gitbash-shell/commit/52da331)；冲突集中在 CHANGELOG、smoke 的路由文本断言、index.js/client.js 的开关读法（`experimentalNative` 默认 true 读 `!== false`，`fastctxTools` 默认 OFF 读 `=== true`）。
+- 新增实际 Core 断言（评审①）：`fastctxTools` OFF（v0.39.4 默认值）且工具面无 `gb_*`/`ops_*` 的单装场景，companion 注册检测（knownNames/faceNames）照常挂载 `gitbash_native` 与 `gitbash_to_native_path`（设计文档 §10 语义）；禁用的桥走 unpublish 短路、不进入 publish（新增用例断言 disabled 日志；`createRequireFrom`/`msysToWin` 桩在 publish 路径上，门控移除时由该日志断言判负）。
+- 设计文档 §3 体验表补组合盲点一句（评审②）：同装 dsh-ops 的受限会话中本插件 bash fail-closed、ops_bash 只发 full-access、gb_* 默认关，但 **pwsh 不被遮蔽**（`ops_*` 在场时 hidePwsh 短路，官方执行器带真围栏）——受限会话不是「零命令工具」，可直接用 pwsh；bash 回归需切 danger-full-access 或关 experimentalNative。（合并前措辞误作「均无命令工具」，维护者评审时对照 `inline-tools.js` 的 `hidePwsh && !opsPresent` 短路修正，见 v0.40.0。）
+- session-workdir 双实现收敛（评审③）：保留模块化 `src/session-workdir.js`（`throwIfAborted` 更完整、diff 噪声更小），bash-tool.js 单行调用。
+- 相关：[PR #26](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26)。Windows / Node 24.13.0：普通完整回归 **236/236**、实际 Core（desktop-next host，0.2.0-rc.1）完整 preview **86/86**（较上轮 85 增本轮①断言一例），均 exit0、无 skip/cancel。PR 已为非 draft，按维护者第一轮评审（rebase + ①断言后声明 ready）视为 ready for review；真实 Agent 自主选路、生产 GUI、维护者 Windows 全量验证和非 CRT 矩阵正式确认仍待。
+
+### PR #26：工具所有权修复与独立复核（fix / test / docs）
+
+- 共用注册入口在每次开关或 Jobs 刷新时，先注销自身注册，再检查当前 agent 可见的工具所有权；外部全局或同 agent 的同名工具均让位。实际 Core 的 knownNames 检查也包含隐藏工具，旧宿主回退 schemas 检查。
+- 两个 companion 按 agent 创建注册模块，初始冲突仍保留待命 scope；外部所有者移除后，下次刷新可恢复。所有权检查或注册失败记录明确日志，不向 volatile 事件抛错，不阻断另一个 companion。
+- scope 就绪与工具注册成功分别记录，避免让位或关闭状态被报告为注册成功。Bash 的逐操作 policy 快照契约保持不变。
+- 新增实际 Core 回归覆盖 path/native × 全局/同 agent 的 OFF→ON 冲突、重复开关、所有者移除恢复、native Jobs 刷新以及隐藏的全局同名工具；普通回归覆盖单个注册失败的隔离与恢复。
+- Windows / Node 24.13.0 / Core 0.2.1-alpha.2：普通完整回归 **232/232**、实际 Core 完整 preview **85/85**，均 exit0、无 skip/cancel。隔离子代理独立复核原始所有权复现与新增专项 **9/9** 通过，未发现新的确认缺陷；专项与完整结果有重叠，不累加覆盖数。
+- 相关：[PR #26](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26)。继续保持 Draft/RFC；真实 Agent 自主选路、生产 GUI、维护者 Windows 全量验证和非 CRT 矩阵正式确认仍待。
+
+### PR #26：隔离子代理独立审查（review / 修复前复现记录）
+
+- 由未继承本次对话历史的子代理重新审查[当前实验提交](https://github.com/KouzakiUmi/dsh-gitbash-shell/commit/771c618dde5e509a80cb2b77733d1517fc7c89f2)
+  相对[上游基线](https://github.com/KannaKuron/dsh-gitbash-shell/commit/114dcde434b99755532cc402f13cecbfe86c9a67)的完整增量。
+  普通回归 231/231、实际 Core preview 79/79 均 exit0、无 skip/cancel；静态审查覆盖策略/开关、目录、注册/Jobs 生命周期、argv/编码/预算及文档证据。
+- 确认一项 P2：experimental-tools 的 refresh 仅在首次挂载之外直接重注册，不重查同名工具所有权。
+  OFF 期间外部注册全局同名 path 工具，ON 后真实 ToolRuntime 调用从 FOREIGN_OWNER 变为本插件 native_path 对象；
+  同 agent 层则同步抛 already registered，阻断本次后续 companion 激活。真实 Core/Cordis 与受控 sentinel 工具复现，未启动 native 进程。
+- 建议将冲突判定纳入每次 refresh 的共用注册入口；存在外部所有者时让位并明确日志，不向 volatile 事件抛 duplicate。
+  补 OFF→ON 的全局/同 agent 层及 native Jobs refresh 回归。产品源码尚未修改，未推送或发送 GitHub 评论。
+- 排除最初疑似的 Bash policy 时序问题：实际 sandboxPolicy 契约是逐操作快照、模式变更作用于下一次调用；
+  fixture 直接修改 header.policy 的反证不足以证明违约，且 base 已有此行为，因此撤回拟议 P1。反证脚本的失败数不等于缺陷数。
+- 无确认 P0/P1；继续保持 Draft/RFC。真实 Agent 自主选路、生产 GUI、维护者 Windows 全量验证和非 CRT 矩阵正式确认仍待，测试绿色不替代这些门槛。
+
+### PR #26：同步 v0.39.3 与旧宿主兼容（fix / docs / test）
+
+- 已 rebase 到[上游吸收 PR #28 改进后的 main](https://github.com/KannaKuron/dsh-gitbash-shell/commit/114dcde434b99755532cc402f13cecbfe86c9a67)，前置 PR #24 已合并；正式 v0.39.3 的记录完整保留。
+- Bash/native 共享可选 workingDirectory 读取：有服务保留官方 ensure 及其失败，缺服务使用 policy.workspaceRoot ?? session.header.cwd。native 不再硬 inject 缺失服务。
+- 两个 companion 的成功日志同样要求 apply 已执行及工具面回读；OFF 只报告 scope 就绪且工具关闭，避免 INACTIVE/关闭状态假阳性。
+- 设置开关的 21 份字典均完成本地化，新增文案护栏保留工具名、UNCONFINED 与 danger-full-access 事实；人工译文审阅仍欢迎维护者补充。
+- 新增旧宿主形状下的三工具挂载、双向开关与 cwd；native policy/header/服务失败；真实 cmd 字面 /c 和 PowerShell EncodedCommand + UTF16 输出。真实 Git Bash RO/WW 开关双向切换、未确定策略拒绝亦通过。
+- 当前普通完整回归 **231/231**、实际 Core 完整 preview **79/79**，均 exit0、无 skip/cancel；Windows / Node 24.13.0 / Core 0.2.1-alpha.2。语法、diff 和 npm pack dry-run 通过。
+- 已安装实验构建的[三入口实机报告](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26#issuecomment-6149607594)作为外部证据引用；报告未记录精确提交，不作为当前 rebase 构建的生产 GUI 验收。真实 LLM 自主选路、维护者 Windows 全量验证与完整非 CRT quoting 矩阵仍待。
+
+
+### PR #26：维护者裁决与运行时开关（fix / feat / docs / test）
+
+- docs：PR 描述和实验文档的提交引用使用可点击链接及说明性标签，避免明文提交 ID。
+
+- 行 Config 新增 volatile 布尔 `experimentalNative`，默认 true，旧配置缺键亦开启；设置卡即时编辑。
+  开启时 Windows 受限/未确定 Bash 拒绝；关闭恢复明确标注 `unconfined` 的旧版 Bash 与实例级日志，不提供真实 shell 写入围栏。
+- 两个新工具随开关实时注销/注册，既有会话无需重启；旧 SDK 引用关闭后拒绝。路径工具在翻译前检查；
+  native 在准备入口、异步准备后、执行入口和最终 spawn 重验。已启动后台 producer 保留生命周期。
+- 拒绝错误与 Bash 描述说明设置卡关闭路径，以及由用户在会话访问模式控件选择 danger-full-access 的路径。
+  21 份词典键齐备，中文/英文先行，其余 19 份暂用英文，合并前补本地化。
+- 实验已 rebase 到 [前置 PR 的最新修复提交](https://github.com/KouzakiUmi/dsh-gitbash-shell/commit/c79332ea2fb6da38042063f7b55046115de8e530)，保留其 promotion sandbox 警示回归，显式 OFF 验证旧行为。
+  当时 #24 仍 OPEN，到 main 的 rebase 尚待（已于本轮完成）；建议两步 review（fail-closed + 开关/UI；native/path/输出/路由），保留 Draft/RFC。
+- 长期跟踪：Core 开放对应 native/encoding/closed DTO API 后优先整体迁移并退役私有实现；artifact 自管，controller 缺失保持拒绝。
+  正式门槛仍为真实 Agent 选路、生产 GUI、维护者 win32 全量验证及非 CRT 矩阵抽测。
+- 本轮纠正：实际 Core 的 tools.restrict 只认全局工具，初版 agent-local mask 失败；改为拥有者动态注销/注册。
+  artifact 准备期间关闭的负例推动增加准备后检查，避免把拒绝落成 providerFailure；零 spawn、scope 释放及再次开启通过。
+- 验证：Windows / Node 24.13.0 / Core 0.2.1-alpha.2，普通完整回归 **226/226**、实际 Core 完整 preview **75/75**，
+  exit0、无 skip/cancel；syntax、diff、npm pack dry-run 通过。不等同于上述四项正式验收。
+- 相关：[PR #26 裁决](https://github.com/KannaKuron/dsh-gitbash-shell/pull/26#issuecomment-6146363513)、[前置 PR #24](https://github.com/KannaKuron/dsh-gitbash-shell/pull/24)。
+
+**类型**:feat(显式运行时路径/native typed argv/逐流解码) / fix(受限请求 fail-closed、生命周期与输出事实) / test / docs。
+
+### Agent 选工具指引补齐（Unreleased）
+
+- 移除“ALL commands都优先bash”的歧义；明确shell语法/管道/POSIX脚本、精确native argv/已知逐流
+  编码、完整值Node路径转换、真正PowerShell cmdlet/WMI四类场景。只按实际可见工具名称引导，
+  pwsh同时要求开关允许；缺native/helper不建议虚构名称，不自动换解释器/权限绕拒绝。
+- 路由与方言开关独立，替换幂等文案块随可见性变化；PTC-only run_code得到SDK决策说明，
+  native/path绑定自身描述在实际Core生成SDK中可见。未知混编码不猜，decoder失败不盲目重跑副作用。
+- 增加5项路由/可见性矩阵/重组/SDK-only/路径说明回归、2项实际Core普通/PTC提示与SDK送达验证。
+  普通全仓 **223/223**、完整实际Corepreview **72/72**，exit0、无skip；不是实际LLM自主选择验收，
+  不承诺每次选对。工具执行参数与Config/UI保持不变。
+
+### 实验性实现（Unreleased）
+
+- **策略变化**：Windows 自有 bash 与 native 在 read-only/workspace-write/缺失策略时拒绝，
+  实际 Core 返回 SANDBOX_UNAVAILABLE；工作目录准备、Jobs admission/promotion与spawn前不走旧
+  unconfined绕过，不自动换工具/权限。default full不放宽会话policy；root官方provider不变。
+  历史unconfined渲染保留仅为旧记录。不是恢复真实IPC/OS围栏，不覆盖minimal PTY/交互终端。
+- **完整值路径工具**：新增gitbash_to_native_path，参数msys_path、输出native_path，复用每调用
+  fresh共享mount；与自动方言/codePaths独立。未知映射、URL、空值/NUL拒绝，不访问文件或授权限。
+  实际ToolRuntime→NodePtcRuntime→LocalSubprocessRuntime→Node/fs读取自有中文/#输入，route/tag不变。
+- **原生工具**：新增gitbash_native，绝对typed executable/cwd、literal/path argv，逐流utf8/gbk/
+  utf16le/raw与replace/strict；只显式path转换，literal /all、/c、空串/引号保真。
+  拒绝bare command、model env、.cmd/.bat/隐式脚本；已知解释器需明确opt-in，非二进制鉴定或任意parser保证。
+- **托管与输出**：每execution私有scope复用真实executeArgv/provider/Jobs，不另造runner或依赖private
+  spawnSpec；decoder错误保真实exit，不诱导重跑。增量UTF8/BOM兼容、独立reader/cursor、raw/decoded产物
+  与payload预算；scope属agent，后台/promotion卸载工具后仍可结束、仅清自身资源。
+- **独立验证发现的问题与修正**：实证ownerdispose/direct kill曾错报completed/complete、artifact callback
+  可无限await、facts schema过宽；均修为operation-owned cause、中止/不完整事实、准备阶段abort/deadline
+  race与closed schemas。终态enum/callback三参同步；晚产物保留trusted retention，不伪称已清除。
+- **最后全仓结果**：普通回归 **218/218**，实际安装Core 0.2.1-alpha.2完整preview **70/70**，均exit0、
+  无skip/cancel。独立专项复跑unit41/41、preview55/55；与全仓结果重叠，不另加总数。
+  语法、diff检查和npm dry-run源码清单通过。
+- **测试整合纠正**：首全仓旧description断言还锁旧unconfined措辞，改为更严格拒绝/禁止绕行护栏。
+  首preview缺3项显式证据env；加test-only preview-env，operator目录优先，否则unique host temp。
+  路径夹具原硬编码D盘/安装bootstrap，改动态盘符/宿主自身bootstrap；C盘临时目录真实fs读复验通过。
+  所有失败尝试证据保留，不称失败观察为修复PASS。
+- **边界**：未知同流混编码不可普遍解码；legacy codePaths业务字符串猜测仍在，显式工具不改变其默认。
+  8MiB两流raw+decoded/16MiB自有payload不是RSS或跨任务硬quota，无自动purge；生产GUI/完整插件apply、
+  真受限token/ACL/IPC/VM负向权限、SSH/PTY与非CRT任意quoting尚未覆盖。未增加Config/UI文案字段。
+  公开讨论文档见[实验设计与接口](docs/experimental-native-execution.md)、
+  [验证分级与复现](docs/experimental-native-verification.md)。对应测试可随仓库复现。
+
+### 前置修复的历史验证（首次记录时未发布）
+
+- **重启后复测(2026-10-13)**:desktop Profile 的本地安装来源为
+  [PR #24](https://github.com/KannaKuron/dsh-gitbash-shell/pull/24) 的
+  [`4816cd8`](https://github.com/KouzakiUmi/dsh-gitbash-shell/commit/4816cd8848a52f73f5f054f761d3ec862cb87ade)
+  修复构建(包/插件清单0.39.2,不是额外发版);四个关键已安装源码与工作树逐字节一致、bundle开启。
+  当前实例status路由200/ok=true;真实前台、后台、超时转后台均输出预期sentinel,中文输出正常;
+  native `cmd //d //c echo`通过,未设置全局EXCL。原始固定GBK字节仍乱码,显式GBK→UTF-8通过,
+  说明编码边界仍在,没有把警示宣称为底层修复。再次执行普通回归 **166/166**、宿主preview **17/17**。
+  已安装包helper覆盖中文/#路径、EOF注释和tagged-template保护,描述包含参数/编码/安全提示;
+  独立render探针首轮误把stdout/stderr传为字符串,按真实stream DTO修正后通过,未修改产品代码。
+  本次复测未覆盖真实PTC引擎与生产受限会话；unconfined反馈仅由隔离Core/renderer测试核验。
+
+### 未修复问题研究(2026-10-13;不是产品实施或发版)
+
+- **原生参数/编码**:实际安装 Core 0.2.1-alpha.2 的隔离 argv/raw-pipe/私有 facade→executeArgv
+  与固定字节机制断言 **21/21**;可复用托管 provider,不需另造 runner。不同流显式解码可行,
+  已混在同流的未知编码不可可靠猜测;private spawnSpec 不当稳定接口。cmd 的前斜杠 executable
+  是另一个本机失败反例,反斜杠固定 echo 通过不代表任意 cmd/批处理 quoting 已验收。
+- **真实 PTC 补证**:ToolRuntime→真实 NodePtcRuntime→真实 LocalSubprocessRuntime→Node/fs
+  隔离实验 **8/8**，独立复跑 exit0。显式完整值 helper 配合 codePaths OFF 能读对动态路径,
+  并保留 `/c/users` 路由数据;legacy 字面量猜测仍误改。不是完整插件 apply/生产 GUI/受限 OS 证明。
+- **安全因果纠正**:现场 MSYS 3.6.10-5a1665c8 源码的 cygheap 使用 VirtualAlloc,signal pipe
+  显式 sec_user DACL 缺 restricting SID;当前 Core Flags=13 且 TokenDefaultDacl 已补 ACE。
+  因而历史笼统“用户-only cygheap 映射/只补默认 DACL/所有未来版本无解”不再作为当前根因依据。
+  私有 IPC 身份路线仅静态可行,SID 集合模型 **9/9**不是 AccessCheck 或新沙箱实测。
+- **研究提出的方向**：受限模式spawn前fail-closed、显式native typed argv/逐流decoder/path helper；
+  Core加法契约与隔离Windows VM中的IPC/AppContainer/LPAC/guest边界仍需进一步验收。
+  当前实现与验证见[实验设计](docs/experimental-native-execution.md)、
+  [验证矩阵](docs/experimental-native-verification.md)；前置兼容修复见[PR #24](https://github.com/KannaKuron/dsh-gitbash-shell/pull/24)。
+
 ## v0.39.4 — 2026-10-14
 
 **类型**:feat(dsh-ops 0.3.0 互通:gb_* 退役 + 统一方言桥) / fix(docs)。
@@ -34,7 +197,6 @@ opt-in)与跨平台(win/mac/linux)支持。本版把并存形态收敛为「各
   功能(boot 层侧栏终端 shell 默认)的前提下去除,README 已说明。
 - **测试**:新增 dsh-ops 互通矩阵(入参 root/operations/protect、出参 items/matches/root、失败 content/message、
   wrapper 门控源码断言、fastctxTools 默认关断言);全量 **172/172**(+1 win32-only skip)。
-
 ## v0.39.3 — 2026-10-14
 
 **类型**:fix(自有 bash 工具的宿主服务兼容 #27、MSYS 参数/编码提示、源码路径边界与 unconfined 可观测性) / test / docs。

package/README.md

@@ -4,6 +4,8 @@
 
 简体中文 | [English](README_EN.md)
 
+> **Unreleased／实验性实现讨论**：下述 fail-closed 与两个显式工具尚未正式发布，不是发布候选；安装公开 npm 包不保证包含这些变更。详见[设计、接口与待讨论决定](<docs/experimental-native-execution.md>)、[验证矩阵与复现](<docs/experimental-native-verification.md>)及 CHANGELOG。
+
 > 让 DeepSeek Harness (dsh) 在 Windows 上**默认用 Git Bash 跑命令**的官方风格插件
 > —— 不替换宿主执行器(官方 PowerShell 执行器原样保留):新增自有 bash 工具
 > (私有 Git Bash 执行器实例,不注册为服务),并为所有模式注册对应的 Git Bash 版
@@ -111,40 +113,31 @@ bundle patch(`cordis.patch.yml`)是**纯新增**(v0.39.0 起):只插入本插件
    任何目录**;旧版本遗留在磁盘上的物化树,启动时仅当 marker 判定为
    「未被用户改过」才单向清理,用户改过的绝不碰(清理不受开关影响)。
 
-**环境变量**:`bash.exe` 是 host 进程的直接子进程(不经 git-bash 登录壳),完整继承
-系统环境变量与 `DSH_*` 快照。
+**环境变量**：`bash.exe` 经 host 的托管 subprocess provider 直接启动（不经登录壳）；
+父环境经过宿主凭据清洗，再合入受保护的 `DSH_*` 快照，不提供完整未过滤环境或绕过凭据保护。
 
 ## 安全语义:Windows 上的受限模式
 
-**POSIX 宿主**:官方沙箱语义**完整保留**——受限令牌、工作区围栏、拒绝分类,
-与 `@deepseek-ai/dsh-bash-sandbox` 完全一致。本节只讲 Windows。
-
-**Windows 宿主上的事实**:`read-only` / `workspace-write` 权限预设下的 **shell 命令**,
-实际以**不受限(unconfined)方式执行**:
-
-- **为什么**:已验证的 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 隔离目录。
-
-**如果你需要 shell 也被硬性拦住**(例如不希望模型经 shell 写工作区外的任何路径),
-注意本插件的自有 bash 工具在 Windows 受限模式下同样 unconfined(见上)——不用
-它、或卸载本插件让它消失即可;官方 PowerShell 执行器从未被本插件触碰。
-`danger-full-access` 预设本来就不受限,装不装本插件行为一致。
-
-> 这一取舍的完整分析(含 0.6.0~0.13.1 的故障史与社区两派对比)见 CHANGELOG
-> v0.13.2 与 `src/shell.js` 头注释。
+**POSIX 宿主**：自有执行器的受限路径仍继承官方后端与拒绝分类。本节只讲 Windows。
+
+**Unreleased 的 Windows 自有 bash/native 工具在 experimentalNative 开启时（默认）采用 fail-closed**：`read-only`、
+`workspace-write` 或缺失/未解析的策略在执行前拒绝；仅真实解析为
+`danger-full-access` 的调用可以执行。受限请求不会登记/启动无围栏进程，也不会自动
+回退 pwsh/cmd/WSL、切模式或绕过文件工具拒绝。用户可在设置中关闭 experimentalNative，恢复明确标注 unconfined 的旧版 Bash 行为。
+
+- **拒绝不是沙箱修复**：当前仍无已验证的受限 Git Bash。历史失败为 Win32 error 5 /
+  0xC0000142；匹配本机 MSYS 源码后发现 signal pipe 显式 SD 缺 restricting SID，
+  现代 cygheap 使用 VirtualAlloc，Core 已补 TokenDefaultDacl。不能继续宣称
+  “只补默认DACL就修好”或“所有未来版本无解”；真正 IPC/OS 方案仍需隔离环境验收。
+- **策略按调用解析**：默认 full 不会放宽另一个只读会话；原生入口的准备、异步边界与
+  spawn seam 重验策略。取消、owner dispose 和主动 kill 会标输出不完整，不伪装自然完成。
+- **文件工具是另一层**：官方 write/edit 仍按其 policy 判断；读取不一定只限工作区。
+  路径 helper 只转换字符串，不检查存在性、不授予读写权。不得用任一工具绕过已发生的拒绝。
+- **范围**：此门控覆盖本插件自有 bash/native 工具；侧栏交互终端、minimal 的持久 PTY
+  和其他插件执行器不因此获得围栏。官方 root PowerShell 执行器没有被替换。
+
+旧 unconfined 记录/渲染兼容仍保留供历史结果使用，不代表新调用可降级。历史见 CHANGELOG
+v0.13.2，当前行为及验证见 Unreleased。
 
 ## 配置
 
@@ -399,6 +392,50 @@ PTC/创造及用户自建模式一律覆盖。
 都不再改写,文件工具收 Windows 路径。**bash 始终是 Git Bash,不受此开关影响**——它只决定
 跨工具的路径方言。
 
+## 显式工具（Unreleased）
+
+**运行时开关 `experimentalNative`（默认 true）：** 设置 → 插件 → dsh-gitbash-shell →「实验原生执行 / fail-closed」。开启时 Windows 受限/未确定模式拒绝 Bash，提供可用的两个显式工具；关闭立即注销并禁用两个工具，恢复明确标注 `unconfined` 的旧版 Bash（不执行 shell 文件写入限制）。修改作用于现有会话后续调用，无需重启，不终止已启动的任务。拒绝时用户也可在会话访问模式控件选择 `danger-full-access`；Agent 不得自行放宽权限。与路径方言及 codePaths 开关独立。
+
+
+两个工具随 Windows 的自有 bash 工具挂入同一 agent-owned scope；不替换官方工具或 root
+provider，已有同名工具不覆盖。旧 Core 缺少公开 native executor/OutputCollector 能力时不
+注册 native 工具，bash/path 不受影响；minimal 的持久终端不通过此补位通道。
+
+- **`gitbash_to_native_path`**：`{ msys_path: 完整值 } → { native_path }`，复用共享且新鲜的
+  挂载事实；Windows/cwd-relative 值可原样，未知 MSYS 根/缺 mount、URL、空值/NUL 显式拒绝。
+  独立于自动方言与 `codePaths` 开关，不猜程序字符串用途、不授文件权限。
+- **`gitbash_native`**：`description`、绝对 `executable: { kind: 'path', value }`、
+  `argv: [{ kind: 'literal'|'path', value }]`；literal 不经 MSYS 转换，path 明确转换并规范化。
+  可选绝对 typed `cwd`；不支持裸 command、model env、隐式脚本、`.cmd/.bat` 或 escalation。
+  已知解释器须显式 `entrypoint: 'interpreter'`；这不是二进制鉴定，也不保证任意 cmd/非CRT parser quoting。
+- 每流 `stdoutEncoding`/`stderrEncoding`：`utf8`（默认）、`gbk`、`utf16le`、`raw`；
+  `errors: 'replace'`（默认）或显式 `strict`。同流未知混合字节应选 raw，不能自动猜码。
+  解码/存储问题独立于真实 exitCode：命令已执行不等于输出可靠，不应因此重复副作用操作。
+- 现有 Jobs 提供后台与 timeout promotion（须有 controller）；缺能力明确拒绝，不静默忽略参数。
+  没有 Jobs 时为前台 kill deadline。准备阶段也有取消/有界预算；owner dispose/kill 标为中止。
+- 产物存放在 host 自有临时目录，不是 model cwd。默认两流 raw+decoded 总磁盘上限8MiB，
+  适配器自有载荷预算16MiB；不是OS/RSS或跨任务硬限。完成产物保留便于读取，无自动purge承诺。
+  `sourceComplete`、管线 `complete`、tail `lossy`、`artifact.complete` 是不同事实，须联合读取。
+
+**Agent 路由指引**：提示组装与工具说明会明确区分：shell语法/管道/重定向/POSIX脚本用
+`bash`；原生.exe精确argv或已知逐流编码用可见的 `gitbash_native`；Node I/O需要完整MSYS
+运行时路径时才用可见的 `gitbash_to_native_path`；真正cmdlet/服务/WMI用可见且开关允许的
+`pwsh`。按实际工具面引导，不推荐未注册/隐藏的工具，重复组装随可见性更新、不堆叠。
+权限拒绝必须停止，不能换工具/模式；解码失败不等于命令没执行，不能盲目重跑副作用。
+
+PTC 模式只直调 `run_code`，里面使用已提供的 `tools.gitbash_to_native_path` / `tools.gitbash_native`。
+run_code描述给出SDK选路规则，实际绑定各自说明适用场景；不编造未提供的绑定名称。
+已验证实际Core普通/PTC提示与SDK文案送达；未运行真实LLM自主选择验收，不保证每次选择正确。
+假设已取得完整 `inputPath`，直接 Node I/O 可写：
+
+```typescript
+const resolved = await tools.gitbash_to_native_path({ msys_path: inputPath });
+const fs = await import('node:fs/promises');
+return await fs.readFile(resolved.native_path, 'utf8');
+```
+
+若程序含路径状路由/搜索数据，选择 `codePaths: false` 避免 legacy 自动误改；工具参数翻译仍在。
+
 ## 原生 Windows 程序与 run_code 的兼容边界
 
 工具描述始终警示下面的参数、编码和安全限制;这些限制不随路径方言关闭而消失。
@@ -421,8 +458,7 @@ PTC/创造及用户自建模式一律覆盖。
   直接调用 Node fs/path 时优先明确的 Windows drive-letter 或 cwd-relative 路径;
   工具 path/file_path 字段仍走工具参数翻译。词法扫描不能识别路由、搜索数据或 shell
   command 的用途;此类字符串不要依赖自动重写,必要时关闭 `codePaths`(提示同步标为 OFF)。
-- **沙箱**:参见上方安全章节。警示可见性得到修复,但 Windows shell 的 unconfined
-  取舍未改变,文件工具的策略拒绝绝不授权 shell 重试。
+- **沙箱**：参见上方安全章节。Unreleased 在 experimentalNative 开启时改为受限请求执行前拒绝，不是恢复了真实围栏；文件工具拒绝不授权 shell/native 重试。
 
 ## 与 dsh-better-sidebar 联动
 

package/README_EN.md

@@ -4,6 +4,8 @@
 
 [简体中文](README.md) | English
 
+> **Experimental implementation discussion / Unreleased:** the fail-closed behaviour and two explicit tools below have not been officially released and are not a release candidate. Public npm installation does not guarantee these changes. See the [design, interfaces and open decisions](<docs/experimental-native-execution.md>), [verification matrix and reproduction](<docs/experimental-native-verification.md>) and Unreleased CHANGELOG.
+
 > Run **agent commands on Git Bash by default** on Windows with DeepSeek
 > Harness (dsh) — the plugin does NOT replace the host executor (the official
 > PowerShell executor stays untouched): it adds its own `bash` tool running
@@ -74,8 +76,7 @@ The old "replace the executor" three-step patch became runtime work:
    only when the marker proves the user never edited them (the cleanup
    ignores the switch).
 
-Environment: `bash.exe` is spawned as a direct child of the host, so it
-inherits the full system environment plus the `DSH_*` snapshot.
+Environment: `bash.exe` is a direct child of the host's managed subprocess provider, not a login launcher. Parent environment values pass through credential scrubbing before the protected `DSH_*` overlay; this does not expose an unfiltered host environment.
 
 ### Upgrading from 0.34.x
 
@@ -91,46 +92,40 @@ to bring old sessions back as-is, turn `variantPresets` on.
 
 ## 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**: 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.
-
-**If you need the shell itself hard-fenced too** (e.g. the model must not
-write anywhere outside the workspace through the shell), note that this
-plugin's own bash tool also runs confined commands UNCONFINED on Windows (see
-above) — avoid it there, or uninstall the plugin so the tool goes away; the
-official PowerShell executor was never touched by this plugin. 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.
+**POSIX hosts:** the executor's restricted path still inherits the official backend and denial classification. This section concerns Windows.
+
+**Unreleased Windows bash/native tools fail closed while experimentalNative is ON (default):** read-only, workspace-write or unresolved policy is refused before execution. Only an actually resolved danger-full-access call may run. Restricted requests never admit/start an unconfined process, automatically switch permissions/interpreters, or bypass file-tool denials. This changes the old labelled-bypass behaviour.
+
+- **Refusal is not restored confinement.** No verified confined Git Bash is provided. Historical failures were Win32 error 5 / 0xC0000142. The matched modern MSYS signal pipe uses an explicit SD without a restricting SID; cygheap uses VirtualAlloc, and Core already supplements TokenDefaultDacl. Neither a default-DACL-only fix nor permanent impossibility is established; IPC/OS solutions still require isolated-environment validation.
+- **Per-call authority:** a full-access deployment default cannot widen a read-only session. Native preparation, async boundaries and the spawn seam recheck authority. Cancellation, owner disposal and direct kill mark output incomplete instead of claiming natural success.
+- **Separate file policy:** official file tools retain their own checks; reads are not necessarily workspace-only. The path helper only converts strings: no existence check or permission grant. A refusal never authorizes another-tool workaround.
+- **Scope:** this gate covers this plugin's own bash/native tools. Sidebar interactive terminals, minimal's persistent PTY and other plugins' executors do not acquire confinement from it. The official root PowerShell executor stays untouched.
+
+Historical unconfined records/rendering remain readable; only the user’s explicit experimentalNative opt-out restores the legacy route. See CHANGELOG v0.13.2 for history and Unreleased for current behaviour/tests.
+
+## Explicit tools (Unreleased)
+
+**Runtime switch `experimentalNative` (default true):** Settings > Plugins > dsh-gitbash-shell > Experimental native execution / fail-closed. ON refuses restricted/unresolved Windows Bash and offers available companions. OFF immediately unregisters/disables both tools and restores legacy explicitly `unconfined` Bash, which does not enforce shell file-write restrictions. Changes affect subsequent calls in existing sessions without restart; already running jobs continue. Refusals also guide the user to select `danger-full-access` in the session access-mode control; agents must not relax permissions automatically. This switch is independent of path dialect/codePaths.
+
+Both companions join the Windows own-bash agent scope without replacing official tools/root providers. Existing names are not overwritten. Missing public native executor/OutputCollector capability skips native without breaking bash/path; minimal's persistent terminal does not use this inline patch.
+
+- **gitbash_to_native_path**: `{ msys_path: completeValue } → { native_path }`, using fresh shared mount facts. Native Windows/cwd-relative values may pass through; unknown MSYS roots/missing facts, URLs, empty/NUL values reject. Independent of automatic dialect/codePaths switches, with no filesystem access or permission grant.
+- **gitbash_native**: description, absolute `executable: {kind:'path',value}`, `argv: [{kind:'literal'|'path',value}]`, optional absolute typed cwd. Literals avoid MSYS conversion; only declared paths translate/normalize. No bare command, model env, implicit scripts, .cmd/.bat or escalation. Known interpreters require explicit `entrypoint:'interpreter'`; this is not executable attestation or a guarantee about arbitrary cmd/non-CRT parsers.
+- Independent stdoutEncoding/stderrEncoding: utf8 (default), gbk, utf16le or raw; errors defaults to replace, strict is opt-in. Unknown mixed bytes require raw rather than guessing. Decoding/storage failures retain actual exit facts; never blindly rerun side effects because display failed.
+- Existing Jobs supports background/promotion when its controller is attached. Missing capability rejects rather than ignoring fields. Without Jobs, foreground uses a kill deadline; preparation also has bounded cancellation. Owner disposal/direct kill marks interrupted output.
+- Host-owned temporary artifacts, not model cwd: default 8MiB combined raw+decoded disk cap and 16MiB adapter-owned payload budget, not OS/RSS or cross-task hard quotas. Completed files remain readable; no automatic purge is promised. sourceComplete, pipeline complete, tail lossy and artifact.complete are distinct facts.
+
+**Agent routing:** descriptions distinguish shell syntax/pipelines/redirection/POSIX scripts (bash), exact native .exe argv/known per-stream encoding (offered gitbash_native), complete MSYS runtime values before Node I/O (offered gitbash_to_native_path), and genuine cmdlets/services/WMI (offered, enabled pwsh). Guidance follows actual visibility and replaces its own block on reassembly. Permission denial means stop, not another-tool/mode retry; display failure never authorizes blindly repeating side effects.
+
+PTC directly calls only run_code; invoke the offered `tools.gitbash_to_native_path`/`tools.gitbash_native` inside it. The run_code description explains SDK selection without inventing absent names, while binding descriptions explain their purpose. Actual Core native/PTC prompt delivery is tested; autonomous LLM selection has not been tested or guaranteed. Given an already obtained complete inputPath:
+
+```typescript
+const resolved = await tools.gitbash_to_native_path({ msys_path: inputPath });
+const fs = await import('node:fs/promises');
+return await fs.readFile(resolved.native_path, 'utf8');
+```
+
+For route/search strings that resemble paths, choose codePaths:false to avoid legacy guessing; typed tool argument translation still works.
 
 ## Native Windows and run_code compatibility boundaries
 
@@ -163,8 +158,7 @@ output encodings.
   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.
+- **Security**: Unreleased refuses restricted calls before execution while experimentalNative is ON; this is not restored confinement. A file-tool policy denial never authorizes a shell/native retry.
 
 ## Config