dsh-plugin-pwsh7 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin-pwsh7 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# dsh-plugin-pwsh7
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-pwsh7.svg)](https://www.npmjs.com/package/dsh-plugin-pwsh7)
+[![license](https://img.shields.io/npm/l/dsh-plugin-pwsh7.svg)](LICENSE)
+
+Windows DeepSeek Harness (DSH) bundle that routes the model-facing **`pwsh` tool to PowerShell 7**
+(`pwsh.exe`, major version >= 7) instead of falling back to Windows PowerShell 5.1.
+
+- The executor inherits every behavior of the stock `dsh-pwsh-sandbox` executor: sandbox modes,
+  `sandbox_permissions` escalation, denial/runner-failure facts, background jobs, output caps, and
+  exit markers. It only replaces executable resolution.
+- When PowerShell 7 is missing, a model-facing **`shell_router`** tool reports status, diagnoses
+  sandbox problems, and installs PowerShell 7 per-user (no administrator required).
+
+English | [中文说明](README.zh.md)
+
+---
+
+## Why
+
+On Windows, DSH mounts `pwsh-sandbox` as `ctx.shell`, but the resolved executable can end up being
+Windows PowerShell 5.1 in some environments. This bundle keeps the stock PowerShell executor and
+overrides only its `pwshPath` resolution:
+
+1. **Replace the `pwsh-sandbox` row** with `RouterPwshExecutor extends SandboxPwshExecutor`. An
+   explicit `config.pwshPath` still wins; otherwise the plugin-resolved PowerShell 7 is used.
+2. **Register the `shell_router` tool** (`status` / `diagnose` / `install`) plus a small system-prompt
+   section describing the routing.
+
+## Requirements
+
+- Windows 10/11.
+- A DSH profile that supports bundles (`@deepseek-ai/dsh-base` / Web profile). Tested against
+  DSH desktop 0.2.1-rc.2.
+- Node.js >= 22 is only needed to run the repository test suite.
+
+## Installation
+
+Install from npm through the DSH plugin manager:
+
+```
+plugin_manager action=install_bundle target=dsh-plugin-pwsh7@0.1.0
+```
+
+Or install from a local checkout (a directory install links the checkout, which is convenient while
+developing):
+
+```
+plugin_manager action=install_bundle target=D:\path\to\dsh-plugin-pwsh7
+```
+
+The new bundle is applied through HMR immediately. After changing the plugin's source, restart DSH
+to load a fresh module generation.
+
+## Usage
+
+The model-facing `shell_router` tool:
+
+| Action | What it does |
+|---|---|
+| `status` (default) | Resolved PowerShell 7 path and version, config file, current sandbox policy, shipped-package resolution. |
+| `diagnose` | Runs real PowerShell 7 commands under the **current sandbox policy** (version + workspace write) and reports exit codes, stdout/stderr, denial/runner-failure classification, and concrete hints. |
+| `install` | Ensures PowerShell 7 exists. `method: "auto"` (default) prefers the per-user portable zip, then falls back to winget; `portable`/`winget` force one strategy. Existing working installations are reused instead of downloading again. |
+
+### Explicit paths
+
+Resolution order for the pwsh executable:
+
+1. `DSH_PWSH_PATH` environment variable
+2. `pwshPath` in `%LOCALAPPDATA%\dsh\pwsh7\config.json`
+3. `%ProgramFiles%\PowerShell\7\pwsh.exe`
+4. `%LOCALAPPDATA%\dsh\pwsh7\powershell7\…\pwsh.exe` (portable installs, newest first)
+5. `%LOCALAPPDATA%\Programs\PowerShell\7\pwsh.exe`
+6. every `PATH` entry
+7. `%LOCALAPPDATA%\Microsoft\WindowsApps\pwsh.exe` (Store alias)
+8. `%ProgramFiles(x86)%\PowerShell\7\pwsh.exe`
+
+The stock `pwsh-sandbox` row still accepts its official `pwshPath` config field; an explicit config
+value takes precedence over automatic detection.
+
+### Config file
+
+`%LOCALAPPDATA%\dsh\pwsh7\config.json`:
+
+```json
+{
+  "version": 1,
+  "pwshPath": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+  "installed": {
+    "pwsh": {
+      "path": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+      "version": "7.6.7",
+      "method": "existing",
+      "at": "2026-10-17T00:00:00.000Z"
+    }
+  },
+  "updatedAt": "2026-10-17T00:00:00.000Z"
+}
+```
+
+## Automatic installation
+
+Per-user, no administrator rights:
+
+| Component | Source | Destination |
+|---|---|---|
+| PowerShell 7 | Latest `PowerShell/PowerShell` GitHub release, `PowerShell-*-win-x64.zip` | `%LOCALAPPDATA%\dsh\pwsh7\powershell7\<version>\` |
+
+- HTTPS streaming download into `%LOCALAPPDATA%\dsh\pwsh7\tmp`, with progress callbacks and
+  cancellation.
+- Extraction uses the Windows built-in `tar.exe` (bsdtar). No downloaded installer is ever executed.
+- After extraction the new `pwsh.exe` is executed once to verify a major version >= 7 before it is
+  written into `config.json`.
+- `auto` falls back to `winget install Microsoft.PowerShell`; when elevation would be required the
+  result carries the exact manual elevated command instead of hanging on UAC.
+- No writes outside the router root and its temp directory.
+- Live-tested on Windows: 106,364,316-byte zip downloaded in ~31 s, extracted to 244.8 MB, verified
+  `7.6.7`.
+
+## Sandbox behavior
+
+- The executor runs through `ctx.sandbox.confine()` and the Windows ACL restricted-token runner, with
+  the same `workspace-write` / `read-only` / `danger-full-access` semantics as the stock executor.
+- PowerShell 7 works in all three modes (verified: `workspace-write` can write inside the workspace
+  and is denied outside it; `danger-full-access` is unconfined).
+- If the Windows sandbox reports `SetNamedSecurityInfoW failed (Win32 5)` / `grantWrite(<workspace>)`,
+  the workspace DACL is missing rights. Run DSH's bundled **`diagnose-windows-sandbox-acl`** skill
+  against the workspace root (it backs up and verifies), or temporarily switch the session to full
+  access.
+
+## Troubleshooting
+
+1. Run `shell_router action="status"` and check the resolved path/version.
+2. Run `shell_router action="diagnose"` to execute real commands under the current sandbox policy.
+3. Common causes:
+   - **Still Windows PowerShell 5.1** — detection did not find PowerShell 7. Set `DSH_PWSH_PATH` or
+     the `pwshPath` config entry, then check `status` again.
+   - **PowerShell 7 installed in a custom location** — set `DSH_PWSH_PATH` or `config.json`.
+   - **Sandbox/ACL failure** — see the sandbox section above.
+
+## Architecture
+
+| Path | Role |
+|---|---|
+| `index.js` | Plugin entry: `shell_router` tool, system-prompt section, state refresh on config reload |
+| `lib/shipped.mjs` | Loads the shipped `@deepseek-ai/*` packages from the running DSH installation (`app.asar`) |
+| `lib/paths.mjs` | PowerShell 7 detection, version probing, `config.json` IO |
+| `lib/install.mjs` | Per-user portable install (official zip) + winget fallback |
+| `lib/state.mjs` | Process-wide resolution cache shared by the executor and the tool |
+| `lib/status.mjs` | `status` / `diagnose` implementations |
+| `lib/executors/pwsh.mjs` | PowerShell 7 executor (extends the official `SandboxPwshExecutor`) |
+| `cordis.patch.yml` | Bundle patch: replaces `pwsh-sandbox` and inserts the plugin row (Windows only) |
+| `locale/en.json`, `locale/zh.json`, `icon.svg` | Plugin-manager display metadata |
+
+`package.json` `files` ships only the runtime pieces; `test/` stays in the repository.
+
+## Development
+
+```powershell
+# Plain Node tests (no running DSH required)
+node --test test/paths.test.mjs test/install.test.mjs
+```
+
+- 49 tests: 48 pass, 0 fail, 1 skipped (network-gated by default).
+- `DSH_PWSH7_NETWORK_TESTS=1` enables the live GitHub release / HEAD checks: 30/30 pass.
+- The environment override prefix is `DSH_PWSH7_*` (`APP_ROOT`, `TAR`, `NETWORK_TESTS`).
+
+## Versioning note
+
+`0.1.0` is the first public release. Earlier internal iterations (0.2.x/0.3.x) included MSYS2 bash
+routing and used a different package name; that scope was removed because MSYS2/Cygwin cannot start
+under the DSH Windows ACL sandbox. The historical evidence stays in the build workspace
+(`sandbox-recon/FINDINGS.md`), not in this package.
+
+## Uninstall
+
+```
+plugin_manager action=remove_bundle target=dsh-plugin-pwsh7
+```
+
+The native Windows preset is restored and `pwsh` returns to DSH's default resolution. The per-user
+directory `%LOCALAPPDATA%\dsh\pwsh7\` is not deleted automatically.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,176 @@
+# dsh-plugin-pwsh7
+
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-pwsh7.svg)](https://www.npmjs.com/package/dsh-plugin-pwsh7)
+[![license](https://img.shields.io/npm/l/dsh-plugin-pwsh7.svg)](LICENSE)
+
+Windows 上的 DeepSeek Harness（DSH）插件：把模型侧的 **`pwsh` 工具路由到 PowerShell 7**
+（`pwsh.exe`，主版本 >= 7），不再落到 Windows PowerShell 5.1。
+
+- 执行器继承 DSH 自带 `dsh-pwsh-sandbox` 的全部行为：沙箱模式、`sandbox_permissions` 升权、
+  拒绝/runner 失败标记、后台任务、输出上限与 exit marker；本插件只替换可执行文件解析。
+- 找不到 PowerShell 7 时，提供模型可调用的 **`shell_router`** 工具做检测、诊断和
+  **用户级自动下载安装**（默认不需要管理员权限）。
+
+[English](README.md) | 中文
+
+---
+
+## 它做什么
+
+Windows 预设把 `pwsh-sandbox` 行挂到 `ctx.shell`，但可执行文件解析在部分环境里会落到
+Windows PowerShell 5.1。本插件保留官方执行器，只覆盖 `pwshPath` 解析：
+
+1. **替换 `pwsh-sandbox` 行**：`RouterPwshExecutor extends SandboxPwshExecutor`。显式
+   `config.pwshPath` 优先；否则使用插件检测到的 PowerShell 7。
+2. **注册 `shell_router` 工具**（`status` / `diagnose` / `install`），并附一段描述路由与安装方式的
+   系统提示小节。
+
+## 环境要求
+
+- Windows 10/11。
+- 支持 bundle 的 DSH profile（`@deepseek-ai/dsh-base` / Web profile）。已在 DSH desktop
+  0.2.1-rc.2 上验证。
+- Node.js >= 22 仅运行仓库测试时需要。
+
+## 安装
+
+通过 DSH 插件管理器从 npm 安装：
+
+```
+plugin_manager action=install_bundle target=dsh-plugin-pwsh7@0.1.0
+```
+
+或从本地目录安装（目录安装会链接源码，便于开发）：
+
+```
+plugin_manager action=install_bundle target=D:\path\to\dsh-plugin-pwsh7
+```
+
+新 bundle 通过 HMR 立即生效；之后修改插件源码需要重启 DSH 才会加载新模块。
+
+## 使用
+
+模型工具 `shell_router`：
+
+| 动作 | 说明 |
+|---|---|
+| `status`（默认） | 报告解析到的 PowerShell 7 路径与版本、配置文件、当前沙箱策略、`@deepseek-ai/*` 加载状态。 |
+| `diagnose` | 在**当前沙箱策略**下真实运行 PowerShell 7 命令（版本 + 工作区写入），输出退出码、stdout/stderr、拒绝/runner 失败判定与具体修复建议。 |
+| `install` | 确保 PowerShell 7 可用。`method: "auto"`（默认）优先用户级便携 zip，失败回退 winget；`portable`/`winget` 强制单一方式。已有可用安装时只刷新配置，不会重复下载。 |
+
+### 显式指定路径
+
+`pwsh` 可执行文件解析顺序：
+
+1. 环境变量 `DSH_PWSH_PATH`
+2. `%LOCALAPPDATA%\dsh\pwsh7\config.json` 的 `pwshPath`
+3. `%ProgramFiles%\PowerShell\7\pwsh.exe`
+4. `%LOCALAPPDATA%\dsh\pwsh7\powershell7\…\pwsh.exe`（便携安装，新版本优先）
+5. `%LOCALAPPDATA%\Programs\PowerShell\7\pwsh.exe`
+6. `PATH` 各目录
+7. `%LOCALAPPDATA%\Microsoft\WindowsApps\pwsh.exe`（Store 别名）
+8. `%ProgramFiles(x86)%\PowerShell\7\pwsh.exe`
+
+官方 `pwsh-sandbox` 行本身仍支持 `pwshPath` 配置字段；显式配置优先于自动检测。
+
+### 配置文件
+
+`%LOCALAPPDATA%\dsh\pwsh7\config.json`：
+
+```json
+{
+  "version": 1,
+  "pwshPath": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+  "installed": {
+    "pwsh": {
+      "path": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+      "version": "7.6.7",
+      "method": "existing",
+      "at": "2026-10-17T00:00:00.000Z"
+    }
+  },
+  "updatedAt": "2026-10-17T00:00:00.000Z"
+}
+```
+
+## 自动安装
+
+默认用户级、无管理员权限：
+
+| 组件 | 来源 | 安装位置 |
+|---|---|---|
+| PowerShell 7 | GitHub `PowerShell/PowerShell` 最新 release 的 `PowerShell-*-win-x64.zip` | `%LOCALAPPDATA%\dsh\pwsh7\powershell7\<version>\` |
+
+- HTTPS 流式下载到 `%LOCALAPPDATA%\dsh\pwsh7\tmp`，支持进度回调与取消。
+- 解包使用 Windows 自带 `tar.exe`（bsdtar）；不会执行任何下载来的安装器。
+- 解包后先真实运行一次新 `pwsh.exe` 验证主版本 >= 7，再写入 `config.json`。
+- `auto` 失败回退 `winget install Microsoft.PowerShell`；需要 UAC 提升时返回明确的手动命令，
+  不会卡在提权提示上。
+- 不写入安装目录与临时目录以外的位置。
+- 已在本机实测：下载 106,364,316 字节（约 31s），解压后 244.8 MB，验证为 `7.6.7`。
+
+## 沙箱
+
+- 执行器通过 `ctx.sandbox.confine()` 走 Windows ACL restricted-token runner，
+  `workspace-write` / `read-only` / `danger-full-access` 与官方执行器一致。
+- PowerShell 7 在三种模式下都可用（已实测：`workspace-write` 下工作区内可写、工作区外写入被拒；
+  `danger-full-access` 不受限）。
+- 若出现 `SetNamedSecurityInfoW failed (Win32 5)` / `grantWrite(<workspace>)`，说明工作区 DACL
+  缺少权限。可运行 DSH 内置的 **`diagnose-windows-sandbox-acl`** skill 对工作区根目录做诊断+修复
+  （先备份、再校验），或临时把会话切到完全权限。
+
+## 故障排查
+
+1. 先跑 `shell_router action="status"`：确认 PowerShell 7 的解析路径与版本。
+2. 再跑 `shell_router action="diagnose"`：在当前沙箱模式下真实执行命令并分类失败。
+3. 常见原因：
+   - **仍然是 Windows PowerShell 5.1**：检测没找到 PowerShell 7。设置 `DSH_PWSH_PATH` 或
+     `config.json` 的 `pwshPath`，再查看 `status`。
+   - **PowerShell 7 装在自定义位置**：设置 `DSH_PWSH_PATH` 或 `config.json`。
+   - **沙箱 / ACL 失败**：见上一节。
+
+## 结构
+
+| 路径 | 作用 |
+|---|---|
+| `index.js` | 插件入口：`shell_router` 工具、系统提示小节、配置热重载时刷新检测 |
+| `lib/shipped.mjs` | 从运行中的 DSH 安装（Electron `app.asar`）加载 `@deepseek-ai/*` 包 |
+| `lib/paths.mjs` | PowerShell 7 路径探测、版本探测、`config.json` 读写 |
+| `lib/install.mjs` | 用户级便携安装（官方 zip）+ winget 回退 |
+| `lib/state.mjs` | 进程内解析缓存（executor 与工具共用） |
+| `lib/status.mjs` | `status` / `diagnose` 实现 |
+| `lib/executors/pwsh.mjs` | PowerShell 7 执行器（继承官方 `SandboxPwshExecutor`） |
+| `cordis.patch.yml` | bundle patch：Windows 上替换 `pwsh-sandbox` 并插入插件行 |
+| `locale/en.json`, `locale/zh.json`, `icon.svg` | 插件管理页显示元数据 |
+
+`package.json` 的 `files` 只打包运行所需文件；`test/` 保留在仓库中，不进入 npm 包。
+
+## 开发
+
+```powershell
+# 纯 Node 单元测试（不需要 DSH 运行）
+node --test test/paths.test.mjs test/install.test.mjs
+```
+
+- 49 tests：48 pass，0 fail，1 skipped（网络用例默认跳过）。
+- 设置 `DSH_PWSH7_NETWORK_TESTS=1` 会启用真实 GitHub release / HEAD 校验：30/30 pass。
+- 环境变量覆盖前缀为 `DSH_PWSH7_*`（`APP_ROOT`、`TAR`、`NETWORK_TESTS`）。
+
+## 版本说明
+
+`0.1.0` 是第一个公开发布版本。更早的内部迭代（0.2.x/0.3.x）曾包含 MSYS2 bash 路由并使用过
+不同的包名；由于 MSYS2/Cygwin 无法在 DSH Windows ACL 沙箱中启动，该部分已被移除。历史实测证据
+保留在构建工作区的 `sandbox-recon/FINDINGS.md`，不在本包内。
+
+## 卸载
+
+```
+plugin_manager action=remove_bundle target=dsh-plugin-pwsh7
+```
+
+卸载后原生 Windows 预设恢复，`pwsh` 回到 DSH 原有解析。用户级目录
+`%LOCALAPPDATA%\dsh\pwsh7\` 不会自动删除，可按需手动清理。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# dsh-plugin-pwsh7 — bundle patch.
+#
+# Windows only:
+#   Replace the host pwsh executor with one that resolves PowerShell 7 explicitly, keeping the
+#   stock sandbox executor behavior (escalation, denial facts, jobs, output caps).
+#
+# On other platforms the rows are disabled: the stock POSIX composition stays untouched.
+
+- id: pwsh-sandbox
+  name: 'dsh-plugin-pwsh7/pwsh-executor'
+  disabled: !!js process.platform !== 'win32'
+
+- insert:
+    - id: pwsh7-router
+      name: 'dsh-plugin-pwsh7'
+      disabled: !!js process.platform !== 'win32'

package/icon.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="PowerShell 7 Router">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#071b30"/>
+      <stop offset="1" stop-color="#0f4f72"/>
+    </linearGradient>
+    <linearGradient id="seven" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#ffe28f"/>
+      <stop offset="1" stop-color="#efa62b"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="5" y="5" width="118" height="118" rx="26" fill="url(#bg)"/>
+  <path d="M22 24h84M22 96h84" stroke="#7fd8ff" stroke-opacity="0.10" stroke-width="2"/>
+
+  <!-- Terminal window: PowerShell prompt chevron + cursor. -->
+  <rect x="18" y="30" width="54" height="40" rx="9" fill="#0a2942" stroke="#5fd2ff" stroke-width="3"/>
+  <path d="M29 43l10 8-10 8" fill="none" stroke="#a6ecff" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M45 59h13" stroke="#a6ecff" stroke-width="5" stroke-linecap="round"/>
+
+  <!-- PowerShell 7 numeral, drawn as a path so no font is required. -->
+  <path d="M76 30h36L94 90H83l15-50H76z" fill="url(#seven)"/>
+
+  <!-- Routing line: the prompt path leads to PowerShell 7. -->
+  <circle cx="24" cy="105" r="4" fill="#5fd2ff"/>
+  <path d="M30 105h58" fill="none" stroke="#ffcf5c" stroke-width="4" stroke-linecap="round"/>
+  <path d="M83 100l7 5-7 5" fill="none" stroke="#ffcf5c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -0,0 +1,126 @@
+// dsh-plugin-pwsh7 — host plugin entry.
+//
+// Routes the model-facing `pwsh` tool to PowerShell 7 and exposes a `shell_router` tool for
+// status, diagnosis, and per-user installation. The executor class lives in
+// ./lib/executors/pwsh.mjs and is mounted by ./cordis.patch.yml.
+
+import { defineTool } from './lib/shipped.mjs';
+import { configPath, getRouterState, refreshRouterState } from './lib/state.mjs';
+import { ensurePwsh } from './lib/install.mjs';
+import { describeStatus, runDiagnosis } from './lib/status.mjs';
+
+export const name = 'pwsh7-router';
+export const inject = ['tools', 'systemPrompt'];
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B';
+  if (bytes >= 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+  return `${bytes} B`;
+}
+
+/**
+ * Build the `shell_router` tool definition. Exported so tests/smoke harnesses can compile and
+ * inspect it without registering a second copy in the live tool registry.
+ */
+export function createToolDefinition(ctx) {
+  return defineTool({
+    name: 'shell_router',
+    description: [
+      'Inspect or repair how this Windows deployment routes the `pwsh` tool.',
+      '`status` (default) reports the resolved PowerShell 7 executable and version, the config file, and the active sandbox policy.',
+      '`diagnose` runs real PowerShell 7 commands under the current sandbox policy and reports failures with concrete hints.',
+      '`install` downloads and installs PowerShell 7 per-user under %LOCALAPPDATA%\\dsh\\pwsh7 (no admin), or falls back to winget.',
+      'Use it when `pwsh` reports that PowerShell 7 is missing, or when the user asks to set up PowerShell 7.',
+    ].join(' '),
+    parameters: {
+      action: {
+        type: 'string',
+        enum: ['status', 'diagnose', 'install'],
+        description: 'Operation to perform; omit for `status`.',
+      },
+      method: {
+        type: 'string',
+        enum: ['auto', 'portable', 'winget'],
+        description: 'For `install`: installation strategy. `auto` prefers the per-user portable zip.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true, description: 'Whether the requested operation succeeded.' },
+          summary: { type: 'string', required: true, description: 'Human-readable status or diagnosis.' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.summary }],
+    },
+    async execute(args, exec) {
+      const action = args.action ?? 'status';
+      if (action === 'status') {
+        const state = await refreshRouterState();
+        return { ok: true, summary: await describeStatus(ctx, state, exec) };
+      }
+      if (action === 'diagnose') {
+        const state = await refreshRouterState();
+        const result = await runDiagnosis(ctx, state, exec);
+        return { ok: result.ok, summary: result.summary };
+      }
+      const progress = [];
+      let lastProgressAt = 0;
+      const installed = await ensurePwsh({
+        method: args.method ?? 'auto',
+        onProgress: (bytes, totalBytes) => {
+          const at = Date.now();
+          if (at - lastProgressAt < 4000) return;
+          lastProgressAt = at;
+          if (Number.isFinite(totalBytes) && totalBytes > 0) {
+            progress.push(`download progress: ${formatBytes(bytes)} / ${formatBytes(totalBytes)} (${Math.round((bytes / totalBytes) * 100)}%)`);
+          } else if (Number.isFinite(bytes) && bytes > 0) {
+            progress.push(`downloaded ${formatBytes(bytes)}`);
+          }
+        },
+        signal: exec.signal,
+      });
+      const state = await refreshRouterState();
+      const result = installed.result ?? {};
+      const resultLine = result.ok
+        ? `pwsh: ok (${result.method ?? 'unknown'}${result.version === undefined ? '' : `, ${result.version}`}${result.path === undefined ? '' : ` at ${result.path}`})`
+        : `pwsh: failed — ${result.message ?? installed.message ?? 'unknown error'}`;
+      const summary = [
+        installed.ok ? 'PowerShell 7 install completed.' : 'PowerShell 7 install finished with problems.',
+        resultLine,
+        ...(Array.isArray(installed.notes) ? installed.notes : []),
+        ...progress.slice(-8),
+        '',
+        await describeStatus(ctx, state, exec),
+      ].join('\n');
+      return { ok: installed.ok === true, summary };
+    },
+  });
+}
+
+export function apply(ctx) {
+  ctx.systemPrompt.section({
+    name: 'tool:pwsh7-router',
+    order: ctx.systemPrompt.getSectionOrder('TOOL_PWSH') + 1,
+    text: [
+      'On Windows this deployment routes the `pwsh` tool to PowerShell 7.',
+      'If PowerShell 7 is missing or misconfigured, call `shell_router`: action `status` reports the resolved executable,',
+      '`diagnose` runs real commands under the current sandbox policy, and `install` downloads a per-user copy into',
+      '%LOCALAPPDATA%\\dsh\\pwsh7 (no administrator rights) with a winget fallback.',
+      'A shell installed this way becomes usable without restarting the app.',
+    ].join(' '),
+  });
+
+  ctx.tools.register(createToolDefinition(ctx));
+
+  ctx.on('app-boot/config-reload', () => {
+    // Detection is cheap and must never break the host reload path.
+    refreshRouterState().catch(() => {});
+  });
+}
+
+export { configPath, getRouterState };

package/lib/executors/pwsh.mjs

@@ -0,0 +1,20 @@
+// PowerShell 7 executor row for Windows.
+//
+// The shipped SandboxPwshExecutor keeps every sandbox behavior (escalation fields, denial
+// facts, jobs, output caps) but resolves its executable once from config/well-known locations.
+// This subclass replaces only that resolution: an explicit row `config.pwshPath` still wins,
+// otherwise the shared router state resolves PowerShell 7 (and raises a setup hint when absent).
+
+import { shipped } from '../shipped.mjs';
+import { requirePwshPath } from '../state.mjs';
+
+const { SandboxPwshExecutor } = shipped('@deepseek-ai/dsh-pwsh-sandbox');
+
+export default class WindowsRouterPwshExecutor extends SandboxPwshExecutor {
+  /** @returns {string} resolved PowerShell 7 executable. */
+  get pwshPath() {
+    const declared = this.config?.pwshPath?.get?.();
+    if (typeof declared === 'string' && declared.trim().length > 0) return declared;
+    return requirePwshPath();
+  }
+}