dsh-win-pwsh7 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.2.6 — loads on DSH 0.2.2-rc.1 again
+
+- **The plugin had gone silently inert on the 0.2.2 desktop build.** 0.2.5 declared
+  `engines.dsh: ">=0.2.1-rc.3 <0.2.2-0"`. The loader skips a bundle whose range the running build
+  does not satisfy, prints nothing, and reports it only as an entry in `skippedBundles`, so on
+  DSH 0.2.2-rc.1 both tools, the guard, the page and the UTF-8 console bridge were absent. The
+  only visible trace was `patch: entry "win-pwsh7" not found` on every recomposition, because the
+  bundle patch that inserts that row never applied.
+- `engines.dsh` is now `>=0.2.1-rc.3 <0.3.0-0` and `dsh.verifiedAgainst` is `0.2.2-rc.1`. The
+  upper bound follows the **minor** line: DSH ships fixes as prereleases of the next patch, so a
+  bound on the next patch's prerelease is a bound on "the next DSH update".
+- `tools/check-host.mjs` now fails when the range ends at a patch prerelease
+  (`<X.Y.Z-0`) instead of `<X.<minor+1>.0-0`; the check was mutation-tested by restoring the old
+  range (red) and putting the new one back (green).
+- `tools/check-native-contracts.mjs` follows the 0.2.2 split of `dsh-tools`: it accepts
+  `checkGuards` (0.2.2) or `guardReason` (0.2.1), reads the `Error: <reason>` materialization from
+  `lib/pipeline.js` when that file exists, asserts the pre-execute waterfall still runs **before**
+  the guards, and drops `ToolRuntime.prepareExecution` (removed upstream; this plugin never used it).
+  Green on 0.2.2-rc.1 in 37 checks.
+- `docs/native-contracts.md` records the new baseline, the per-package delta from 0.2.1-rc.4 and
+  the new guard symbols. `dsh-tool-pwsh` is byte-identical; `dsh-pwsh-local` only adds
+  `PYTHONIOENCODING: utf-8`, so `ENCODING_PREAMBLE` still carries no `chcp` and the UTF-8 bridge
+  stays.
+- No tool, prompt, install, gate or page behavior changed.
+
+## 0.2.5 — transitional Windows UTF-8 console bridge
+
+- Added `lib/utf8-console-bridge.js`, a removable layer that wraps the same `ctx.shell.execute`
+  the `pwsh` tool uses and prefixes Windows commands with `chcp.com 65001 > $null;`. A nested
+  `pwsh -File` / `powershell -File` otherwise inherits the console code page (936 on a Simplified
+  Chinese machine) and emits GBK, which the Host collector decodes as UTF-8 and renders as U+FFFD.
+- `utf8Console` (default `true`) gates the layer. It fails open when the shell service, the
+  executor shape or the config reader is unavailable, and restores the original executor when the
+  plugin unloads. No tool, prompt, install or gate behavior changed.
+- `tools/check-utf8-bridge.mjs` covers the prefix, opt-out, idempotence, restore and fail-open paths
+  with a fake executor; it runs in the `check` chain.
+- Removal contract: delete `lib/utf8-console-bridge.js`, its import and mount in `index.js`, the
+  `utf8Console` config field, the bridge gate and its `check` entry, plus the README section and
+  this note. The README records the exact steps and the `grep` acceptance check.
+
 ## 0.2.4 — plugin page aligned with the dsh-ops card language
 
 - Restyled both contributions after the installed dsh-ops 0.5.0 branch: a 0.5px hairline card on

package/README.en.md

@@ -18,7 +18,10 @@ default executor then chooses the runtime itself, and the plugin still never wri
 ## Verified environment
 
 - Windows 10/11.
-- Verified on DSH **0.2.1-rc.3** (see `dsh.verifiedAgainst` in `package.json`).
+- Verified on DSH **0.2.2-rc.1** (see `dsh.verifiedAgainst` in `package.json`).
+- Supported range: `>=0.2.1-rc.3 <0.3.0-0`. Ending the range at the next prerelease makes the
+  loader skip this bundle silently after every DSH patch release (no tools, no gate, no UTF-8
+  bridge), so the upper bound follows the **minor** line.
 - The script path needs Microsoft Store; the manual path only needs the Store page.
 - No administrator rights are required.
 
@@ -44,7 +47,7 @@ multi-session validation passed, so the switch is default-on again.
 ## Install this plugin
 
 ```powershell
-dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.4
+dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.6
 # or
 dsh plugin --profile desktop add dsh-win-pwsh7
 ```
@@ -83,6 +86,7 @@ The count lives in the current process and resets when DSH restarts.
 |---|---|---|
 | `overridePath` | unset | Priority ① explicit `pwsh.exe`. It must spawn and report PowerShell 7+; a failed validation falls back to auto-detection. **It only changes probing and recommendations, not executor wiring.** |
 | `dshOpsCompat` | `true` | Coexist with dsh-ops (on by default): writes and enables its Compatibility mode, hides duplicate official tools, and keeps `pwsh` + `ops_bash`. Requires a restart. |
+| `utf8Console` | `true` | Transitional: prefixes every `pwsh` tool command with `chcp.com 65001` on Windows, so a nested `pwsh -File` cannot emit GBK under code page 936 and be decoded as UTF-8. Removable once the Host ships the same fix. |
 
 `overridePath` is `volatile()`: the plugin-page configuration section saves it live; it can also be
 set in the profile patch:
@@ -129,6 +133,42 @@ The status section is a native card showing the state, runtime and executor path
 at the top right; the configuration section exposes `overridePath` and the default-on "Keep native
 pwsh alongside dsh-ops" native switch.
 
+## Windows UTF-8 console (transitional)
+
+The Host collector decodes `pwsh` output as UTF-8, but a `pwsh -File` / `powershell -File` started
+inside a tool command inherits the **console code page** (936 on a Simplified Chinese machine) and
+emits GBK, which then renders as `�`. The Host preamble pins the outer process's .NET encoding, not
+the console code page.
+
+0.2.5 adds a transitional layer: it wraps the same `ctx.shell.execute` the `pwsh` tool uses and
+prefixes every Windows command with `chcp.com 65001 > $null;`. It affects only this plugin's users,
+is on by default, can be disabled with `utf8Console: false`, and fails open when the Host shape
+does not match.
+
+### Removal contract
+
+After the Host ships the same fix, delete the layer whole:
+
+1. delete `lib/utf8-console-bridge.js`;
+2. delete the import and `mountUtf8ConsoleBridge(ctx, current)` call in `index.js`;
+3. delete `Config.utf8Console`;
+4. delete `tools/check-utf8-bridge.mjs` and its entry in the `package.json` `check` chain;
+5. delete this section and the 0.2.5 transitional note in CHANGELOG.
+
+Acceptance: `grep -rn "utf8-console-bridge\|utf8Console" index.js lib tools` returns nothing.
+
+### Deciding that the Host has fixed it
+
+Either signal is enough to start removing the layer:
+
+- `@deepseek-ai/dsh-pwsh-local`'s own `ENCODING_PREAMBLE` includes the `chcp.com 65001` switch
+  (check `packages/shell/pwsh-local/src/index.ts` upstream, or `lib/index.js` in the installed
+  package);
+- with this plugin absent or `utf8Console` off, a nested `pwsh -File` under a CP936 console already
+  prints UTF-8.
+
+Re-run the nested script in a real CP936 environment before deleting.
+
 ## Disable or uninstall
 
 Disabling the plugin removes the `pwsh` gate and the plugin page; it does not uninstall PowerShell 7.
@@ -143,6 +183,7 @@ to 5.1, uninstall the Store build or pin the executor to `powershell.exe` (not r
 | The Store page opens without an Install button | Confirm the VPN is off, fully quit and restart Microsoft Store, then retry; or use the manual path. |
 | `pwsh` still runs 5.1 | Run `pwsh7_status`, paste the reported `pwshPath` patch into the profile, and restart; or install the Store build. |
 | The plugin page is missing | Confirm `dsh-win-pwsh7` is enabled in the current profile, then restart DSH. |
+| Chinese turns into `�` when a command nests `pwsh` | 0.2.5 handles it through `utf8Console`; if you disabled it, turn it back on or prefix the command with `chcp.com 65001 > $null;`. |
 
 ## Verification
 
@@ -150,10 +191,11 @@ to 5.1, uninstall the Store build or pin the executor to `powershell.exe` (not r
 $env:DSH_APP_DIR = 'E:\FXS\APP\DSH NEXT\resources\app.asar'
 node tools/check-host.mjs
 node tools/check-client.mjs
+node tools/check-utf8-bridge.mjs
 node tools/check-native-contracts.mjs
 ```
 
-All three gates run offline against a packed installation (`resources/app.asar`); `DSH_APP_DIR`
+All four gates run offline against a packed installation (`resources/app.asar`); `DSH_APP_DIR`
 accepts the install root, `resources/app`, or `resources/app.asar`.
 
 ## Design constraints
@@ -163,7 +205,7 @@ accepts the install root, `resources/app`, or `resources/app.asar`.
 - No VPN auto-detection and no metered-connection preflight: the user confirms the VPN before an
   install, and a page-load failure asks again.
 - No automatic retries; the three-failure breaker ends the loop.
-- Run all three gates before publishing; end-to-end installation is release evidence, not part of
+- Run all four gates before publishing; end-to-end installation is release evidence, not part of
   the automated gate.
 
 ## License

package/README.md

@@ -13,7 +13,9 @@
 ## 验证环境
 
 - Windows 10/11。
-- 已在 DSH **0.2.1-rc.3** 上验证（见 `package.json` 的 `dsh.verifiedAgainst`）。
+- 已在 DSH **0.2.2-rc.1** 上验证（见 `package.json` 的 `dsh.verifiedAgainst`）。
+- 支持范围 `>=0.2.1-rc.3 <0.3.0-0`：收紧到"下一个预发布"会让 loader 在 DSH 每次小版本更新后**静默跳过**本插件
+  （不装、不报错、`pwsh` 失去 gate 和 UTF-8 过渡层），所以上界按**次版本**划。
 - 脚本安装需要 Microsoft Store 可用；手动安装只需要能打开 Store 页面。
 - 不需要管理员权限。
 
@@ -36,7 +38,7 @@
 
 ```powershell
 # 从 GitHub 安装（推荐锁定 tag）
-dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.4
+dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.6
 # 或 npm
 dsh plugin --profile desktop add dsh-win-pwsh7
 ```
@@ -70,6 +72,7 @@ dsh plugin --profile desktop add dsh-win-pwsh7
 |---|---|---|
 | `overridePath` | 未设 | 优先级①的显式 `pwsh.exe`。必须能启动并报告 PowerShell 7+；未通过校验就回落到自动探测。**只影响探测与推荐，不接线**。 |
 | `dshOpsCompat` | `true` | 与 dsh-ops 共存（默认开启）：自动写入并启用兼容模式，隐藏重复的官方工具，保留 `pwsh` + `ops_bash`。需要重启。 |
+| `utf8Console` | `true` | 过渡层：Windows 下给 `pwsh` 工具的每条命令前加 `chcp.com 65001`，避免嵌套 `pwsh -File` 按 936 输出 GBK 后被按 UTF-8 解码成乱码。宿主修复后可删除。 |
 
 `overridePath` 是 `volatile()`：插件页配置区保存即生效；也可以写进 profile 补丁：
 
@@ -107,6 +110,34 @@ The executor resolves to the version-stable Store family alias: … Nothing to c
 
 插件页的状态区是原生卡片，显示状态、运行时和执行器路径，右上角有「重新检测」；配置区有 `overridePath` 和默认开启的「与 dsh-ops 共存」原生开关。
 
+## Windows UTF-8 控制台（过渡层）
+
+DSH 的 `pwsh` 工具按 UTF-8 解码输出，但命令里再启动的 `pwsh -File` / `powershell -File` 会继承**控制台代码页**（简体中文机器通常是 936），输出 GBK，最终显示为 `�`。宿主的前缀只固定了外层进程的 .NET 编码，没有改控制台代码页。
+
+0.2.5 增加一个过渡层：包装 `pwsh` 工具使用的 `ctx.shell.execute`，在 Windows 上给每条命令前加 `chcp.com 65001 > $null;`。它只影响装了本插件的用户；默认开启，可用 `utf8Console: false` 关闭；宿主接口形状不符时 fail-open，不影响 `pwsh` 工具本身。
+
+### 删除契约
+
+宿主发布同样的修复后，按这五步整块删除：
+
+1. 删 `lib/utf8-console-bridge.js`；
+2. 删 `index.js` 的 import 和 `mountUtf8ConsoleBridge(ctx, current)` 调用；
+3. 删 `Config.utf8Console`；
+4. 删 `tools/check-utf8-bridge.mjs`，并从 `package.json` 的 `check` 链里移除；
+5. 删本节和 CHANGELOG 里的 0.2.5 过渡说明。
+
+验收：`grep -rn "utf8-console-bridge\|utf8Console" index.js lib tools` 无结果。
+
+### 判定上游已修复
+
+满足任一条件即可开始删除：
+
+- `@deepseek-ai/dsh-pwsh-local` 的 `ENCODING_PREAMBLE` 自己包含 `chcp.com 65001`（可查上游
+  `packages/shell/pwsh-local/src/index.ts`，或安装包里的 `lib/index.js`）；
+- 在 CP936 控制台下，不装/关闭本插件时，命令里嵌套的 `pwsh -File` 已经输出 UTF-8。
+
+删除前先在真实的 CP936 环境复跑一遍嵌套脚本，确认不再需要这层。
+
 ## 禁用或卸载
 
 禁用插件只移除 `pwsh` 的 gate 和插件页，不会卸载 PowerShell 7。只要机器上仍有 `pwsh.exe`，默认执行器仍会优先运行它（通常是 Store 版 PowerShell 7）；只有找不到 `pwsh.exe` 时才回退到 Windows PowerShell 5.1。要真正回到 5.1，需要卸载 Store 版或把执行器 pin 到 `powershell.exe`，不推荐这样做。
@@ -118,6 +149,7 @@ The executor resolves to the version-stable Store family alias: … Nothing to c
 | Store 页面打开但没有「安装」按钮 | 确认 VPN 已关闭，完全退出并重启 Microsoft Store 后重试；或改用手动安装。 |
 | `pwsh` 仍运行 5.1 | 运行 `pwsh7_status`，按报告把 `pwshPath` 补丁粘进 profile 并重启；或安装 Store 版。 |
 | 插件页看不到 | 确认当前 profile 已启用 `dsh-win-pwsh7`，然后重启 DSH。 |
+| 命令里嵌套 `pwsh` 时中文变 `�` | 0.2.5 默认已由 `utf8Console` 过渡层处理；若手动关掉，重新开启，或在命令前加 `chcp.com 65001 > $null;`。 |
 
 ## 验证
 
@@ -125,17 +157,18 @@ The executor resolves to the version-stable Store family alias: … Nothing to c
 $env:DSH_APP_DIR = 'E:\FXS\APP\DSH NEXT\resources\app.asar'
 node tools/check-host.mjs
 node tools/check-client.mjs
+node tools/check-utf8-bridge.mjs
 node tools/check-native-contracts.mjs
 ```
 
-三套门都可以在打包安装（`resources/app.asar`）上离线复跑；`DSH_APP_DIR` 接安装根目录、`resources/app` 或 `resources/app.asar`。
+四套门都可以在打包安装（`resources/app.asar`）上离线复跑；`DSH_APP_DIR` 接安装根目录、`resources/app` 或 `resources/app.asar`。
 
 ## 设计约束
 
 - 判定读执行器自己的 `ctx.shell.pwshPath`，不是扫配置行；`overridePath` 只影响探测与推荐。
 - 不做 VPN 自动检测、不做计量连接预检；VPN 由用户在安装前确认，页面加载失败时再提示。
 - 不自动重试；连续失败由熔断终止。
-- 提交前跑三套门；端到端安装是发布证据，不是自动化门的一部分。
+- 提交前跑四套门；端到端安装是发布证据，不是自动化门的一部分。
 
 ## License
 

package/index.js

@@ -51,6 +51,7 @@ import {
   mountDshOpsBridge,
   removeDshOpsCompatPatch,
 } from './lib/dsh-ops-bridge.js'
+import { mountUtf8ConsoleBridge } from './lib/utf8-console-bridge.js'
 
 export const name = 'dsh-win-pwsh7'
 export const inject = ['subprocess', 'tools', 'configEditor', 'systemPrompt']
@@ -70,6 +71,9 @@ export const Config = z.object({
   // Default-on after the multi-session validation of the pre-restriction bridge. Turning it
   // off removes the managed compatibility override; turning it on restores it.
   dshOpsCompat: z.boolean().default(true).volatile(),
+  // Transitional Windows console code page fix, owned by lib/utf8-console-bridge.js.
+  // Delete this field together with the bridge and its mount (see README removal contract).
+  utf8Console: z.boolean().default(true).volatile(),
 })
 
 /**
@@ -374,6 +378,10 @@ export function apply(ctx, config) {
 
   ctx.effect(() => mountDshOpsBridge(ctx, current), 'dsh-win-pwsh7: hide duplicate official tools while dsh-ops is compatible')
 
+  // Transitional, removable: delete this mount and lib/utf8-console-bridge.js once the Host
+  // pins the console code page itself. The README records the removal contract.
+  ctx.effect(() => mountUtf8ConsoleBridge(ctx, current), 'dsh-win-pwsh7: pin the Windows console code page for pwsh output')
+
   ctx.effect(() => {
     void activationSweep(ctx, current()).then((report) => {
       ctx.logger?.info?.('dsh-win-pwsh7: %s', flattenReport(report))
@@ -533,12 +541,14 @@ function readRowConfig(ctx, fallback) {
   const merged = {
     overridePath: typeof fallback?.overridePath === 'string' ? fallback.overridePath : undefined,
     dshOpsCompat: fallback?.dshOpsCompat !== false,
+    utf8Console: fallback?.utf8Console !== false,
   }
   try {
     const entry = ctx.configEditor.entries().find((candidate) => candidate?.options?.name === 'dsh-win-pwsh7')
     const values = entry?.options?.config
     if (isSet(values?.overridePath)) merged.overridePath = String(values.overridePath)
     if (values?.dshOpsCompat !== undefined) merged.dshOpsCompat = values.dshOpsCompat !== false
+    if (values?.utf8Console !== undefined) merged.utf8Console = values.utf8Console !== false
   } catch { /* fall back to the captured config */ }
   return merged
 }

package/lib/utf8-console-bridge.js

@@ -0,0 +1,104 @@
+/**
+ * Transitional Windows UTF-8 console bridge.
+ *
+ * The Host's `dsh-pwsh-local` collector decodes stdout as UTF-8, but a nested
+ * `pwsh -File` / `powershell -File` started by a tool command inherits the console
+ * code page (936 on a Simplified Chinese machine) and emits GBK. The Host preamble
+ * only pins the .NET output encoding of the outer process; it does not change the
+ * console code page. This module wraps the same `ctx.shell` executor the `pwsh` tool
+ * uses and prepends `chcp.com 65001` so the code page is right before the command
+ * runs.
+ *
+ * It is deliberately a leaf: no imports from the rest of the plugin, one mount in
+ * `index.js`, one config field, and a documented removal contract. Delete this file,
+ * the import/mount and the config field when the Host ships the same fix.
+ *
+ * REMOVE WHEN: the Host's `@deepseek-ai/dsh-pwsh-local` pins the console code page
+ * itself (its `ENCODING_PREAMBLE` carries the `chcp.com 65001` switch), or a nested
+ * `pwsh -File` under code page 936 already emits UTF-8 without this plugin. Follow
+ * the README removal contract in the same change.
+ */
+
+/** One line of the wrapper's own diagnostics. */
+const describe = (error) => (error instanceof Error ? error.message : String(error))
+
+/** Marks an executor this module already wrapped, so HMR or a second mount cannot stack. */
+export const UTF8_CONSOLE_PATCH = Symbol.for('dsh-win-pwsh7.utf8ConsoleBridge')
+
+/** A command that already selects UTF-8 must not be prefixed twice. */
+const ALREADY_UTF8 = /^\s*chcp(?:\.com)?\s+65001(?:\s|>|$)/iu
+
+/**
+ * Prefix a Windows command with the console code page switch.
+ *
+ * @param {unknown} command - the caller's command text.
+ * @returns the command, prefixed once when it is a string and not already pinned.
+ */
+export function utf8Command(command) {
+  if (typeof command !== 'string' || command.length === 0) return command
+  if (ALREADY_UTF8.test(command)) return command
+  return `chcp.com 65001 > $null; ${command}`
+}
+
+/**
+ * Wrap the live shell executor the `pwsh` tool resolves.
+ *
+ * Fails open: a missing service, a non-writable executor or a shape change leaves
+ * the plugin working exactly as before and logs one warning. The wrapper is removed
+ * with the plugin's fiber; it never writes files, config or profile state.
+ *
+ * @param ctx - the row's Host context.
+ * @param current - reads the live row configuration.
+ * @param platform - injectable for tests; defaults to `process.platform`.
+ * @returns void; the wrap is owned by the injected fiber.
+ */
+export function mountUtf8ConsoleBridge(ctx, current, platform = process.platform) {
+  if (platform !== 'win32') return
+  const warn = (message) => ctx.logger?.warn?.(`dsh-win-pwsh7: ${message}`)
+  if (typeof ctx.inject !== 'function') return
+  try {
+    ctx.inject(['shell'], (scoped) => {
+      try {
+        const viaGet = typeof scoped.get === 'function' ? scoped.get('shell') : undefined
+        const shell = viaGet ?? scoped.shell
+        if (shell === undefined || shell === null) return
+        if (shell[UTF8_CONSOLE_PATCH] === true) return
+        const original = shell.execute
+        if (typeof original !== 'function') {
+          warn('the shell service exposes no execute(); the UTF-8 console bridge stays off')
+          return
+        }
+        shell.execute = function executeWithUtf8Console(spec) {
+          try {
+            if (current?.()?.utf8Console === false) return original.call(this, spec)
+            if (spec === null || typeof spec !== 'object' || typeof spec.command !== 'string') {
+              return original.call(this, spec)
+            }
+            const command = utf8Command(spec.command)
+            if (command === spec.command) return original.call(this, spec)
+            return original.call(this, { ...spec, command })
+          } catch (error) {
+            warn(`the UTF-8 console bridge fell open: ${describe(error)}`)
+            return original.call(this, spec)
+          }
+        }
+        Object.defineProperty(shell, UTF8_CONSOLE_PATCH, { value: true, configurable: true })
+        const restore = () => {
+          try {
+            shell.execute = original
+          } catch { /* the executor was replaced by another owner */ }
+          try {
+            delete shell[UTF8_CONSOLE_PATCH]
+          } catch { /* non-configurable; the marker is advisory */ }
+        }
+        if (typeof scoped.effect === 'function') {
+          scoped.effect(() => restore, 'dsh-win-pwsh7: utf8 console bridge')
+        }
+      } catch (error) {
+        warn(`the UTF-8 console bridge could not attach: ${describe(error)}`)
+      }
+    })
+  } catch (error) {
+    warn(`the UTF-8 console bridge could not inject the shell service: ${describe(error)}`)
+  }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-win-pwsh7",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "description": "Detect and validate PowerShell 7 for the Harness pwsh tool on Windows, and install it on request through the Microsoft Store — scripted or manual — while the pwsh tool stays blocked until a PowerShell 7 runtime actually resolves.",
   "engines": {
-    "dsh": ">=0.2.1-rc.3 <0.2.2-0"
+    "dsh": ">=0.2.1-rc.3 <0.3.0-0"
   },
   "license": "MIT",
   "icon": "./icon.svg",
@@ -33,6 +33,7 @@
     "client.js",
     "lib/typert.host.js",
     "lib/dsh-ops-bridge.js",
+    "lib/utf8-console-bridge.js",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
@@ -51,12 +52,12 @@
     "windows"
   ],
   "scripts": {
-    "check": "node tools/check-host.mjs && node tools/check-client.mjs && node tools/check-native-contracts.mjs",
+    "check": "node tools/check-host.mjs && node tools/check-client.mjs && node tools/check-utf8-bridge.mjs && node tools/check-native-contracts.mjs",
     "check:contracts": "node tools/check-native-contracts.mjs",
     "prepublishOnly": "npm run check"
   },
   "dsh": {
-    "verifiedAgainst": "0.2.1-rc.3",
+    "verifiedAgainst": "0.2.2-rc.1",
     "bundle": {
       "patch": "./cordis.patch.yml"
     },

package/tools/check-host.mjs

@@ -830,6 +830,27 @@ check('client copy: every t() key is defined in both dictionaries', () => {
   }
 })
 
+// --- Manifest: the DSH range must not end at the next prerelease ---------------------------
+//
+// 0.2.5 declared `>=0.2.1-rc.3 <0.2.2-0` and the desktop moved to 0.2.2-rc.1: the loader skips a
+// bundle whose `engines.dsh` the running build does not satisfy, prints nothing, and the whole
+// plugin disappears (no tools, no gate, no UTF-8 bridge) until a new release ships. DSH patches
+// arrive as prereleases, so a bound on the next patch's prerelease is a bound on "the next DSH
+// update". The range therefore ends at the next minor: `<X.<minor+1>.0-0`.
+
+check('engines.dsh ends at the next minor, not at the next prerelease', () => {
+  const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  const [major, minor] = manifest.dsh.verifiedAgainst.split('.').map((part) => Number.parseInt(part, 10))
+  const terms = manifest.engines.dsh.trim().split(/\s+/u)
+  const upper = terms.find((term) => term.startsWith('<'))
+  assert.equal(
+    upper,
+    `<${major}.${minor + 1}.0-0`,
+    'a `<X.Y.Z-0` bound on the next patch prerelease makes the loader skip this bundle after the next DSH release',
+  )
+  assert.ok(terms.some((term) => term.startsWith('>=')), 'the range needs a lower bound')
+})
+
 // --- Verdict -----------------------------------------------------------------------------
 
 if (failures.length > 0) {

package/tools/check-native-contracts.mjs

@@ -72,6 +72,32 @@ function source(name) {
   throw new Error(`${name}: neither lib/types/index.js nor lib/index.js exists`)
 }
 
+/**
+ * Read one named file of an installed package, or '' when the build does not have it.
+ *
+ * A contract can move between files without being lost: 0.2.2 moved the tool pipeline out of
+ * `lib/index.js` into `lib/pipeline.js`. Reading a fixed list and joining what exists keeps the
+ * assertion on the behavior when the file split changes, instead of on a remembered path.
+ */
+function trySource(name, relative) {
+  try {
+    return readFileSync(join(packageDir(name), relative), 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/** The tool pipeline: one file up to 0.2.1, split into `lib/pipeline.js` from 0.2.2. */
+function pipeline() {
+  return ['lib/index.js', 'lib/pipeline.js'].map((relative) => trySource('dsh-tools', relative)).join('\n')
+}
+
+/** The single file that hosts the pre-execute waterfall in this build. */
+function pipelineFile() {
+  const split = trySource('dsh-tools', 'lib/pipeline.js')
+  return split === '' ? trySource('dsh-tools', 'lib/index.js') : split
+}
+
 let checks = 0
 /** One assertion with a stable label for the summary. */
 function check(label, assertion) {
@@ -109,11 +135,30 @@ async function run() {
 
   // ---- tool registry: guard is global, monotonic, and lands as an error --
   check('defineTool is exported', () => assert.equal(typeof tools.defineTool, 'function'))
-  for (const method of ['guard', 'guardReason', 'restrict', 'prepareExecution', 'execute']) {
+  for (const method of ['guard', 'restrict', 'execute']) {
     check(`ToolRuntime.${method} exists`, () => assert.equal(typeof tools.ToolRuntime.prototype[method], 'function'))
   }
-  check('guard denial is materialized as `Error: <reason>`', () => {
-    assert.match(source('dsh-tools'), /Error: \$\{denialReason\}/u)
+  // 0.2.1 read guards in `guardReason`; 0.2.2 renamed it `checkGuards` and moved the one who
+  // materializes the denial into `lib/pipeline.js`. The plugin only needs "guards are still read
+  // once, after pre-execute, and the reason reaches the model" — not a particular private name.
+  const GUARD_READERS = ['checkGuards', 'guardReason']
+  const guardReader = GUARD_READERS.find((name) => typeof tools.ToolRuntime.prototype[name] === 'function')
+  check('ToolRuntime reads its guards through one method', () => {
+    assert.ok(
+      guardReader !== undefined,
+      `neither ${GUARD_READERS.join(' nor ')} exists — the gate cannot tell whether guards still deny`,
+    )
+  })
+  check('a guard denial is materialized as `Error: <reason>`', () => {
+    assert.match(pipeline(), /Error: \$\{denialReason\}/u)
+    assert.ok(pipeline().includes(`.${guardReader}(`), `the denial pipeline never calls ${guardReader}`)
+  })
+  check('guards are read after the pre-execute waterfall', () => {
+    const text = pipelineFile()
+    const waterfall = text.search(/tools\/pre-execute/u)
+    const read = text.search(new RegExp(`${guardReader}\\(`, 'u'))
+    assert.ok(waterfall >= 0, 'the pre-execute waterfall is gone; the gate cannot be refreshed before a pwsh call')
+    assert.ok(read > waterfall, 'guards run before the pre-execute waterfall, so a stale reading would decide the call')
   })
   check('restrict refuses a plain-context caller', () => {
     assert.match(source('dsh-tools'), /tools\.restrict\(\) requires a scoped context/u)

package/tools/check-utf8-bridge.mjs

@@ -0,0 +1,148 @@
+/**
+ * Gate for the transitional Windows UTF-8 console bridge.
+ *
+ * The bridge wraps the Host's `ctx.shell.execute`; this suite drives it with a fake
+ * executor so the prefix, the opt-out, the fail-open paths and the restore are
+ * verifiable without a DSH installation.
+ */
+import assert from 'node:assert/strict'
+import { mountUtf8ConsoleBridge, utf8Command } from '../lib/utf8-console-bridge.js'
+
+let failures = 0
+function check(label, assertion) {
+  try {
+    assertion()
+  } catch (error) {
+    failures += 1
+    console.error(`FAIL — ${label}: ${error.message}`)
+  }
+}
+
+function fakeContext(shell, options = {}) {
+  const effects = []
+  const warnings = []
+  const injected = []
+  const scoped = {
+    get: () => shell,
+    effect(fn) { effects.push(fn()) },
+  }
+  const ctx = {
+    logger: { warn: (message) => warnings.push(message) },
+    inject(deps, callback) {
+      injected.push(deps)
+      callback(scoped)
+    },
+  }
+  return { ctx, effects, warnings, injected }
+}
+
+function fakeShell() {
+  const calls = []
+  const shell = {
+    execute(spec) {
+      calls.push({ spec, self: this })
+      return spec
+    },
+  }
+  return { shell, calls }
+}
+
+// --- The pure command transform -----------------------------------------------------------
+
+check('prefixes a bare command once', () => {
+  assert.equal(utf8Command('Get-Location'), 'chcp.com 65001 > $null; Get-Location')
+})
+check('leaves an already-pinned command alone', () => {
+  for (const command of [
+    'chcp 65001 > $null; Get-Location',
+    'chcp.com 65001 > $null; Get-Location',
+    '  chcp.com 65001 >$null; Get-Location',
+  ]) {
+    assert.equal(utf8Command(command), command)
+  }
+})
+check('leaves non-strings and empty strings alone', () => {
+  for (const value of [undefined, null, 42, '']) assert.equal(utf8Command(value), value)
+})
+
+// --- The executor wrapper ----------------------------------------------------------------
+
+check('wraps the shell executor and prefixes the command', () => {
+  const { shell, calls } = fakeShell()
+  const { ctx } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  const spec = { command: 'pwsh -NoProfile -File enc_test.ps1', cwd: 'C:\\work', timeoutMs: 1000 }
+  shell.execute(spec)
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0].spec.command, 'chcp.com 65001 > $null; pwsh -NoProfile -File enc_test.ps1')
+  assert.equal(calls[0].spec.cwd, 'C:\\work')
+  assert.equal(calls[0].spec.timeoutMs, 1000)
+  assert.equal(calls[0].self, shell)
+})
+check('passes through when the config field is off', () => {
+  const { shell, calls } = fakeShell()
+  const { ctx } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: false }), 'win32')
+  shell.execute({ command: 'Get-Location' })
+  assert.equal(calls[0].spec.command, 'Get-Location')
+})
+check('does not double-prefix a command that already selects UTF-8', () => {
+  const { shell, calls } = fakeShell()
+  const { ctx } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  shell.execute({ command: 'chcp.com 65001 > $null; Get-Location' })
+  assert.equal(calls[0].spec.command, 'chcp.com 65001 > $null; Get-Location')
+})
+check('is idempotent when mounted twice on the same executor', () => {
+  const { shell } = fakeShell()
+  const { ctx } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  const once = shell.execute
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  assert.equal(shell.execute, once)
+})
+check('restores the original executor when the fiber disposes', () => {
+  const { shell, calls } = fakeShell()
+  const original = shell.execute
+  const { ctx, effects } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  assert.notEqual(shell.execute, original)
+  effects.forEach((dispose) => dispose())
+  assert.equal(shell.execute, original)
+  shell.execute({ command: 'Get-Location' })
+  assert.equal(calls.at(-1).spec.command, 'Get-Location')
+})
+
+// --- Fail-open paths ---------------------------------------------------------------------
+
+check('does nothing on non-Windows', () => {
+  const { shell } = fakeShell()
+  const { ctx, injected } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'linux')
+  assert.deepEqual(injected, [])
+})
+check('warns and leaves a service without execute untouched', () => {
+  const { ctx, warnings } = fakeContext({})
+  mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32')
+  assert.equal(warnings.length, 1)
+  assert.match(warnings[0], /no execute/u)
+})
+check('warns instead of throwing on a frozen executor', () => {
+  const shell = Object.freeze({ execute(spec) { return spec } })
+  const { ctx, warnings } = fakeContext(shell)
+  assert.doesNotThrow(() => mountUtf8ConsoleBridge(ctx, () => ({ utf8Console: true }), 'win32'))
+  assert.equal(warnings.length, 1)
+})
+check('falls open when the config reader throws', () => {
+  const { shell, calls } = fakeShell()
+  const { ctx } = fakeContext(shell)
+  mountUtf8ConsoleBridge(ctx, () => { throw new Error('config unavailable') }, 'win32')
+  shell.execute({ command: 'Get-Location' })
+  assert.equal(calls[0].spec.command, 'Get-Location')
+})
+
+if (failures > 0) {
+  console.error(`utf8 bridge: ${failures} check(s) failed`)
+  process.exit(1)
+}
+console.log('ok — utf8 console bridge: prefix, opt-out, idempotence, restore and fail-open paths')