@lone-wolf-akela/dsh-sandboxie-redirect 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+Notable changes per release. The format is loose; the version numbers are what
+the DSH compatibility gate reads.
+
+## 0.3.0 — 2026-10-07
+
+The distribution changed shape, so this is a breaking release for the earlier
+hand-mounted installations.
+
+**Distribution**
+
+- The package is now a DSH **bundle**: `dsh.bundle.patch` points at a root
+  `cordis.patch.yml` whose rows name the package instead of an absolute Windows
+  path. Install with `dsh plugin --profile <name> add @lone-wolf-akela/dsh-sandboxie-redirect`
+  (or the in-app Plugins page for the profile a running desktop app owns); the
+  profile no longer needs hand-editing.
+- `exports["."]` now resolves to `lib/provider.mjs`. It used to be `lib/host.mjs`,
+  which would have mounted the wrong half of the plugin under a package row.
+- Added `LICENSE`, `files`, `publishConfig.access`, `repository`/`author`/`bugs`,
+  `os: ["win32"]`, keywords and the peer ranges the compatibility gate reads
+  (`@deepseek-ai/dsh-* ^0.2.0-rc.2`, `@deepseek-ai/cordis ^4.0.4`).
+- Removed the `cordis.patch.yml.new` template: with the bundle channel it was the
+  one file that could not survive publication (it carried an absolute path).
+
+**Configuration layer**
+
+- The `permission` row's preset list is computed at load time (`!!js`) from the
+  layers before it, instead of restating the three shipped presets. A preset
+  another bundle contributes is no longer silently dropped, and an unreadable
+  earlier layer falls back to the literal stock three.
+- The preset's display name and description are bilingual:
+  `❐ Copy-on-write 写时复制`.
+
+**Behaviour**
+
+- Diagnostics moved out of the package directory into
+  `$DSH_HOME/state/dsh-sandboxie-redirect` (`DSH_SBIE_LOG_DIR` overrides). An
+  installed bundle lives in the profile's `node_modules`, possibly served from
+  pnpm's content-addressed store, where appending logs is both rude and fragile.
+- The launcher's Node runtime is now located through `process.resourcesPath`
+  (the desktop app's own Node) before the `$DSH_HOME/dsh-runtimes` pool, and
+  `process.execPath` is only accepted on a non-Electron host. Finding no genuine
+  Node now fails loudly with `SANDBOX_UNAVAILABLE` instead of silently spawning
+  the Electron binary inside the box.
+- The copy root follows Sandboxie's configured `FileRootPath` (box setting, then
+  `[GlobalSettings]`), with `%USER%`/`%SANDBOX%`/`%SystemDrive%`/`%USERPROFILE%`/
+  `%WINDIR%` expanded; `DSH_SBIE_ROOT` still overrides it. A template without
+  `%SANDBOX%`, or one that cannot be fully expanded, is refused — the plugin then
+  keeps the default layout rather than pointing its cleanup at a shared folder.
+- `--manage list` derives the sandbox root from the boxes it lists, and
+  `--manage show` resolves a box's own directory the same way.
+- The model-facing note names the same resolved root.
+
+**Tooling and docs**
+
+- `tools/install.mjs` (the manual channel) derives its copy list from
+  `package.json`'s `files`.
+- `test/validate-patch.mjs` accepts both row shapes (package name for bundles,
+  absolute path for the manual channel), reads js-yaml from the devDependency /
+  `asar-yaml/` / an installed profile, and now EXECUTES the computed preset
+  expression against a stub context.
+- The module-level import pin for `lib/tool.mjs` follows relative siblings
+  recursively instead of banning them.
+- GitHub Actions runs the Sandboxie-free tests; `npm test`, `npm run
+  test:acceptance` and `npm run pack:check` are wired up. The READMEs are
+  rewritten around the bundle install.
+
+## 0.2.1
+
+The last hand-mounted release: copy the tree into
+`~/.dsh/plugins/dsh-sandboxie-redirect` and add three rows to the profile's
+`cordis.patch.yml`. Functionally it already had the copy-on-write preset, the
+title-bar box name, the permission-dropdown icon and the `sandbox_clear` tool.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-sandboxie-redirect 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

@@ -0,0 +1,151 @@
+# dsh-sandboxie-redirect
+
+> **中文版**：[README.zh.md](README.zh.md)
+
+A [DSH](https://github.com/deepseek-ai/deepseek-harness) bundle that adds a fourth permission preset, **Copy-on-write (写时复制)**: shell commands run inside a Sandboxie box dedicated to the workspace, so writes inside the workspace land on the real disk as usual, while writes, edits and deletions anywhere else keep succeeding — but only inside that box's copy. The three shipped presets (read-only, workspace-write, danger-full-access) behave exactly as before.
+
+```
+┌─ your DSH session ────────────────┐
+│  file policy: copy-on-write       │
+│                                   │
+│  shell command ──▶ Sandboxie box ─┼──▶ workspace writes    → real disk
+│  (inside the box)  (per workspace)┼──▶ writes elsewhere    → box copy
+│                                   │    deletes elsewhere   → tombstone in copy
+│  read/write/edit ──▶ host process ┼──▶ unchanged: writable inside the
+│  (outside the box)                │    workspace, refused outside it
+└───────────────────────────────────┘
+```
+
+- Windows only, and it needs [Sandboxie-Plus](https://sandboxie-plus.com/) installed (the sandbox service must be running).
+- It is a permission **preset**, not a patch to the DSH application: nothing inside the app is modified.
+- Its purpose is accident prevention, undo, and keeping system directories clean. It is **not** a defence against malicious programs — Sandboxie itself makes no such promise, and a plugin runs with the same access as the app hosting it.
+
+## Terminology
+
+| Term | Meaning |
+|---|---|
+| Real disk | Where files actually live (for example `C:\Users\…`). |
+| Sandbox / box | The isolated environment Sandboxie creates. This plugin creates one per workspace. |
+| Copy | The box's private storage for changes to files outside the workspace (under the sandbox root), kept apart from the real files. |
+| Inside / outside the box | Under Copy-on-write, shell commands run inside the box; the DSH app and its file tools (read/write/edit) run outside it. |
+| Merged view | What a command inside the box sees: the copy's content overlaid on the real file. |
+| SandMan | Sandboxie-Plus's GUI, for inspecting, recovering and deleting sandboxes. |
+
+## Installation
+
+**Prerequisite:** [Sandboxie-Plus](https://sandboxie-plus.com/) ([source](https://github.com/sandboxie-plus/Sandboxie)). The installer must have created its service; every box this plugin uses is created and managed by Sandboxie.
+
+The package is a DSH *bundle*: installing it also adds its configuration layer, so no profile file needs hand-editing.
+
+```powershell
+# install into a profile (the CLI creates it if needed and appends this bundle)
+dsh plugin --profile <profile> add @lone-wolf-akela/dsh-sandboxie-redirect
+
+# check the layer without booting, then start
+dsh --profile <profile> --dump-config      # expect a "# == @lone-wolf-akela/dsh-sandboxie-redirect" layer
+dsh --profile <profile>
+```
+
+Other supported sources, for a local checkout or an offline machine:
+
+```powershell
+dsh plugin --profile <profile> add C:\path\to\dsh-sandboxie-redirect   # a checkout (linked)
+dsh plugin --profile <profile> add .\lone-wolf-akela-dsh-sandboxie-redirect-0.3.0.tgz
+```
+
+> **Which command for which profile?** The CLI refuses to touch a profile that a running desktop app owns (`profile "desktop" is managed exclusively by the Electron application`). For that profile, install from inside the app: **Settings → Plugins → add a bundle**, and give the package name above. For any other profile, the CLI works normally.
+
+Then restart the client, open the permission dropdown, and select **❐ Copy-on-write 写时复制**. The preset appears once per session as needed; the title bar shows the box name after the first shell command.
+
+### Migrating from a hand-mounted copy
+
+Earlier revisions were installed by copying the tree into `~/.dsh/plugins/dsh-sandboxie-redirect` and adding rows to `~/.dsh/profiles/<profile>/cordis.patch.yml`. If your profile still carries those rows, **remove them** before switching to the bundle channel: two active rows into the same `dsh.client` package fail the boot ("resolves from multiple active Loader sources"). The rows to delete are the ones whose `name` is an absolute path ending in `lib\provider.mjs`, plus the `sandbox` and `permission` rows this plugin added. `tools/install.mjs` remains in the repository for that manual channel, and it must be run outside the sandbox.
+
+## What it does
+
+### The Copy-on-write preset
+
+| Location | Behavior |
+|---|---|
+| Writes, edits, deletions **inside** the workspace | Applied directly to the real disk |
+| Writes, edits **outside** the workspace | The command reports success, but the change lands in that workspace's box copy; the real disk is untouched |
+| Deletions **outside** the workspace | The real file survives; the copy records only a deletion marker |
+
+DSH's own file tools (read/write/edit) run outside the box and keep the workspace-write rule: writable inside the workspace, refused outside it. To read a file *as the sandbox sees it*, read it with a shell command — see [Read-side divergence](#read-side-divergence).
+
+Under this preset the session's policy text gains a paragraph that tells the model how the mode behaves and what to watch for, so an agent does not have to infer it.
+
+### Sandbox name in the title bar
+
+Under Copy-on-write the title bar shows the box name (for example `dsh_able_willow`; hover for the copy's root). It appears only when both hold: this session's preset is Copy-on-write, and this workspace really owns a box — so it shows up after the first command, and disappears when the preset changes or the box is cleaned.
+
+### Permission dropdown icon
+
+The preset carries an icon (two overlapping sheets) in the dropdown and the bottom button, following the active theme. The preset's display name starts with `❐` for the same reason: the shipped dropdown takes icons from a closed id→icon map, so the name is the one surface that always renders.
+
+### The `sandbox_clear` tool
+
+In-session, `sandbox_clear` inspects or discards this workspace's copy: `mode: "inspect"` reports (file count, size), `mode: "clear"` deletes the copy and its configuration. It works in every permission mode, and can only ever touch boxes Sandboxie attributes to *this* workspace.
+
+## Notes for users
+
+- **The `sandbox_permissions` parameter description is not written for this preset.** DSH generates that one text for every preset, and it reads as "the retry after a denial" — under Copy-on-write an out-of-workspace write is never denied (it succeeds into the copy), so no denial marker appears and there is nothing to retry. The session's policy text says so explicitly; escalation is a deliberate "run this one call on the real disk" lever, not a follow-up to a failure.
+- **Read-side divergence (important)**: one path can look different depending on who reads it.
+  - Shell commands run inside the box and may see the merged view — if an earlier command wrote that file outside the workspace, the command sees the copy's version.
+  - DSH's file tools run outside the box and always see the real disk.
+  - So: to see "what a command wrote outside the workspace", read with a shell command; to see "was the real disk changed", read with DSH's file tools (or File Explorer).
+- **Copy location**: ordinary paths at `<sandbox root>\drive\<drive>\<path>`; paths under the user profile at `<sandbox root>\user\current\<relative path>`. Sandboxie's own sandbox folder is followed automatically (its `FileRootPath`, box setting or `[GlobalSettings]`, with `%USER%`/`%SANDBOX%` expanded); `DSH_SBIE_ROOT` overrides that if you need it (see [Environment](#environment)).
+- **Disk usage**: copies are not reclaimed automatically and keep growing.
+- **`C:\Windows\Temp`**: modifying an *existing* file there may be refused — native Sandboxie behavior, not this plugin's. Creating and deleting files there works.
+- **Concurrency**: concurrent commands in one workspace share one box and see each other's changes.
+- **Escalation**: if a command escalates for wider permissions, that single call runs entirely outside the box; the next command returns to the box. Escalation is not a way to make one file real.
+- **Write-back**: copy changes are not merged back automatically. Recover files in SandMan; `sandbox_clear` only deletes.
+- **Uninstalling** the bundle removes the preset and the rows, but the boxes and their copies stay on disk. Clean them first (`sandbox_clear`, or `--manage clean`) if you want the space back.
+
+## Managing boxes manually
+
+```powershell
+node bin\dsh-sbie-run.mjs --manage list                  # list managed boxes
+node bin\dsh-sbie-run.mjs --manage clean "<workspace>"    # clean one workspace's boxes
+node bin\dsh-sbie-run.mjs --manage delete-box <box>      # delete one box
+```
+
+`--manage` must run outside the box (an ordinary terminal, or a `danger-full-access` session): a process inside a box cannot see Sandboxie's box list. The same operations are available in SandMan.
+
+## Environment
+
+All optional; each exists as an escape hatch rather than a configuration surface.
+
+| Variable | Effect |
+|---|---|
+| `DSH_SBIE_NODE` | The `node.exe` that runs the launcher. Set it if the plugin cannot find one (the desktop app's own runtime, then `$DSH_HOME/dsh-runtimes`, are searched automatically). |
+| `DSH_SBIE_ROOT` | Overrides the sandbox root. Normally unnecessary: Sandboxie's configured `FileRootPath` is followed. Default `%SystemDrive%\Sandbox\%USERNAME%`. |
+| `DSH_SBIE_LOG_DIR` | Where diagnostics land. Default `$DSH_HOME/state/dsh-sandboxie-redirect`. |
+| `DSH_SBIE_INI` | The Sandboxie configuration file to read. Default `%SystemDrive%\Windows\Sandboxie.ini`. |
+| `DSH_SBIE_KOFFI` / `DSH_SBIE_KOFFI_ROOT` | A `koffi.node` (or a directory holding one) for the launcher, when the app's copy cannot be found. |
+| `DSH_SBIE_BOX` / `DSH_SANDBOX_ROOT` | **Set by the plugin** inside a command; authoritative for "which box am I in" — never derive the name from the workspace path. |
+
+Diagnostics: `provider.log`, `host.log`, `tool.log` under the log directory above. The host log is capped at 512 KB and records only state transitions.
+
+## How it works (short)
+
+- The bundle layer disables the stock `sandbox` row (`@deepseek-ai/dsh-sandbox-local`) and inserts this package's provider, which subclasses it: only the Copy-on-write *preset* is diverted, every other mode delegates to the stock ACL path. A configured `runnerCommand` cannot do this — it would apply to every mode.
+- The same layer merges `copy-on-write` into the `permission` preset list, keeping whatever the layers before it contributed.
+- Shell commands are then run through `bin/dsh-sbie-run.mjs`, a plain-Node child process that holds the Sandboxie FFI. Sandboxie builds processes through its service and drops the standard handles, so stdio is relayed over a loopback TCP channel with length-prefixed frames.
+- Box names are a deterministic word pair derived from the workspace path (`dsh_<adjective>_<noun>`), so no state file is needed to find a workspace's box; a collision steps to the next candidate, and a name is only adopted when Sandboxie's own configuration says that workspace owns it.
+- Only a failure to load the harness packages is fatal, and that case registers a provider that fails **closed** — refusing to run commands rather than running them unconfined.
+
+## Development
+
+See [AGENTS.md](AGENTS.md) for the architecture and the hard-won constraints. The short version:
+
+```powershell
+node test\unit.mjs               # pure logic
+node test\host-projection.mjs    # the title-bar projection, without the harness bundle
+node test\validate-patch.mjs     # this bundle's layer: structure, and the preset merge actually evaluated
+node test\run-tests.mjs          # acceptance: real boxes, real redirection (outside any box, medium IL)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,150 @@
+# dsh-sandboxie-redirect
+
+> **English**: [README.md](README.md)
+
+给 [DSH](https://github.com/deepseek-ai/deepseek-harness) 增加第四种权限预设 **「写时复制」** 的 bundle：shell 命令跑在本工作区专属的 Sandboxie 沙盒里，工作区内的写入照常落到真实磁盘；工作区外的写入、修改、删除不会失败，但只落进该沙盒的副本。原有三个预设（只读 / 仅工作区 / 完全权限）行为不变。
+
+```
+┌─ 你的 DSH 会话 ───────────────────┐
+│  文件策略：写时复制                │
+│                                   │
+│  shell 命令 ──▶ Sandboxie 沙盒 ───┼──▶ 工作区内写入   → 真实磁盘
+│  （在沙盒内）   （每工作区一个）    ┼──▶ 其它位置写入   → 沙盒副本
+│                                   │    其它位置删除   → 副本里只留删除标记
+│  读/写/编辑 ──▶ 宿主进程（盒外）    ┼──▶ 规则不变：工作区内可写，区外拒绝
+└───────────────────────────────────┘
+```
+
+- 仅 Windows，且需要先装 [Sandboxie-Plus](https://sandboxie-plus.com/)（其服务须在运行）。
+- 接入方式是权限**预设**，不修改 DSH 应用本体。
+- 用途是防误写、可撤销、保持系统目录干净。**不用于防御恶意程序**——Sandboxie 不提供该保证，而插件与承载它的应用拥有同等权限。
+
+## 术语
+
+| 词 | 含义 |
+|---|---|
+| 真实磁盘 | 系统里实际存放文件的地方（例如 `C:\Users\…`）。 |
+| 沙盒 / 盒 | Sandboxie 创建的隔离环境；本插件为每个工作区创建一个。 |
+| 副本 | 沙盒对"工作区外文件改动"的私有存储（位于沙盒根下），与真实文件分开。 |
+| 盒内 / 盒外 | 写时复制下，shell 命令在盒内运行；DSH 应用本体与它的文件工具（读/写/编辑）在盒外。 |
+| 合并视图 | 盒内命令读文件时，沙盒把副本内容叠加到真实文件上呈现。 |
+| SandMan | Sandboxie-Plus 自带的图形管理界面，可查看、恢复、删除沙盒。 |
+
+## 安装
+
+**前置条件**：[Sandboxie-Plus](https://sandboxie-plus.com/)（[源码](https://github.com/sandboxie-plus/Sandboxie)）。安装后它的服务须在运行；本插件的所有沙盒都由 Sandboxie 创建与管理。
+
+本包是 DSH 的 **bundle**（自带配置层），装进去就自动挂载，**不需要手改 profile 文件**。
+
+```powershell
+# 装进某个 profile（不存在会创建），并自动加入该 profile 的 bundle 列表
+dsh plugin --profile <profile> add @lone-wolf-akela/dsh-sandboxie-redirect
+
+# 先不启动，核对配置层，再启动
+dsh --profile <profile> --dump-config      # 应看到一行 "# == @lone-wolf-akela/dsh-sandboxie-redirect"
+dsh --profile <profile>
+```
+
+也支持本地目录 / 离线 tarball：
+
+```powershell
+dsh plugin --profile <profile> add C:\path\to\dsh-sandboxie-redirect   # 本地 checkout（link 方式）
+dsh plugin --profile <profile> add .\lone-wolf-akela-dsh-sandboxie-redirect-0.3.0.tgz
+```
+
+> **哪个 profile 用哪条路？** 正在运行的桌面应用独占的 profile（`desktop`）会被 CLI 拒绝操作（`profile "desktop" is managed exclusively by the Electron application`）。这种 profile 请在**应用内**装：**设置 → 插件 → 添加 bundle**，填上面的包名。其它 profile 用 CLI 即可。
+
+装完重启客户端，在权限下拉里选择 **❐ Copy-on-write 写时复制**。沙盒名称会在第一条 shell 命令之后出现在标题栏。
+
+### 从"手工挂载"迁移
+
+早期版本是"把目录拷到 `~/.dsh/plugins/dsh-sandboxie-redirect` + 在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里加行"。切到 bundle 通道前**必须先删掉那些行**：同一个 `dsh.client` 包有两个活动 loader 行会让启动直接失败（"resolves from multiple active Loader sources"）。要删的是：`name` 为绝对路径、以 `lib\provider.mjs` 结尾的那一行，以及本插件加的 `sandbox`、`permission` 两行。仓库里的 `tools/install.mjs` 仍然保留给手工通道使用，且必须在沙盒外运行。
+
+## 功能
+
+### 写时复制预设
+
+| 位置 | 行为 |
+|---|---|
+| 工作区**内**的写入、修改、删除 | 直接作用于真实磁盘 |
+| 工作区**外**的写入、修改 | 命令报成功，但改动只落在该工作区的副本里；真实磁盘不受影响 |
+| 工作区**外**的删除 | 真实文件保留；副本中只记录删除标记 |
+
+DSH 的文件工具（读/写/编辑）在盒外运行，仍按「仅工作区」判定：工作区内可写、区外拒绝。想读"沙盒视角"的文件，用 shell 命令读（见下文「读侧分歧」）。
+
+该预设下，会话的策略文本会追加一段说明，告知模型本模式的行为与注意事项，不必让模型自己推断。
+
+### 标题栏的沙箱名称
+
+写时复制模式下，标题栏显示当前沙盒名称（如 `dsh_able_willow`，悬停可见副本根路径）。它只在两个条件同时满足时出现：该会话的预设是写时复制，且该工作区确已创建沙盒。因此第一条命令后才出现，切换预设或清理沙盒后消失。
+
+### 权限下拉图标
+
+「写时复制」在下拉与底部按钮中带有图标（复制双矩形），随主题配色。预设名以 `❐` 开头也是同一个原因：出厂下拉的图标来自一张封闭的 id→图标表，自定义预设没有图标，而名字是唯一一定渲染的表面。
+
+### sandbox_clear 工具
+
+会话内可用 `sandbox_clear` 查看或清除本工作区的副本：`mode: "inspect"` 仅查看（文件数、占用），`mode: "clear"` 删除副本与配置。任何权限模式下都可用，且只能操作 Sandboxie 认定属于**本工作区**的沙盒。
+
+## 用户注意事项
+
+- **`sandbox_permissions` 的参数描述不是为本预设写的。** 那段文字由 DSH 统一生成、所有预设共用，读起来像"被拒之后的补救"——而写时复制下区外写入**不会被拒**（它会成功落进副本），所以既不会出现拒绝标记，也没有"被拒的命令"可重试。会话的策略文本会明确说明这一点：升权是"这一次调用直接作用于真实磁盘"的主动手段，不是失败的后续动作。
+- **读侧分歧（重要）**：同一个路径，不同工具看到的内容可能不同。
+  - shell 命令在盒内运行，读到的是合并视图：如果之前有命令在工作区外写过该文件，命令看到的是副本里的版本。
+  - DSH 的文件工具在盒外运行，读到的一直是真实磁盘上的版本。
+  - 因此：验证"命令在工作区外写了什么"用 shell 命令读；验证"真实磁盘有没有被改动"用 DSH 的文件工具（或资源管理器）读。
+- **副本位置**：普通路径在 `<沙盒根>\drive\<盘符>\<路径>`；用户目录下的路径在 `<沙盒根>\user\current\<相对路径>`。Sandboxie 自己配置的沙盒目录会被自动跟随（`FileRootPath`，盒级或 `[GlobalSettings]`，含 `%USER%`/`%SANDBOX%` 展开）；需要时可用 `DSH_SBIE_ROOT` 覆盖（见[环境变量](#环境变量)）。
+- **磁盘占用**：副本不自动回收，会持续累积。
+- **`C:\Windows\Temp`**：修改其中**已存在**的文件可能被拒（Sandboxie 原生行为，非本插件所致）；新建与删除不受影响。
+- **并发**：同一工作区的并发命令共用一个沙盒，互相可见。
+- **升权**：写时复制下，若某命令需要更大权限而发起升权，该次调用会整体在盒外运行；下一条命令回到盒内。升权不是"把某个文件变真"的手段。
+- **写回**：副本改动默认不回灌真实磁盘。需要恢复时在 SandMan 中查看并恢复；`sandbox_clear` 只做删除，不做写回。
+- **卸载** bundle 只会移除预设与配置行，**沙盒与副本仍留在磁盘上**。想收回空间就先清理（`sandbox_clear`，或 `--manage clean`）。
+
+## 手动管理沙盒
+
+```powershell
+node bin\dsh-sbie-run.mjs --manage list                    # 列出受管沙盒
+node bin\dsh-sbie-run.mjs --manage clean "<工作区>"         # 清理某工作区的沙盒
+node bin\dsh-sbie-run.mjs --manage delete-box <沙盒名>      # 删除指定沙盒
+```
+
+`--manage` 必须在盒外运行（普通终端，或 `danger-full-access` 会话）：盒内进程看不到沙盒列表。同样的操作也可以在 SandMan 里做。
+
+## 环境变量
+
+全部可选，都是"逃生阀"而非配置面。
+
+| 变量 | 作用 |
+|---|---|
+| `DSH_SBIE_NODE` | 跑启动器的 `node.exe`。插件会自动去找（桌面应用自带的运行时，其次 `$DSH_HOME/dsh-runtimes`），找不到时用它指定。 |
+| `DSH_SBIE_ROOT` | 覆盖沙盒根。通常不需要：Sandboxie 配置的 `FileRootPath` 会被自动跟随。默认 `%SystemDrive%\Sandbox\%USERNAME%`。 |
+| `DSH_SBIE_LOG_DIR` | 诊断日志目录。默认 `$DSH_HOME/state/dsh-sandboxie-redirect`。 |
+| `DSH_SBIE_INI` | 要读取的 Sandboxie 配置文件。默认 `%SystemDrive%\Windows\Sandboxie.ini`。 |
+| `DSH_SBIE_KOFFI` / `DSH_SBIE_KOFFI_ROOT` | 启动器要用的 `koffi.node`（或含它的目录），当找不到应用自带的那份时使用。 |
+| `DSH_SBIE_BOX` / `DSH_SANDBOX_ROOT` | **由插件在命令内注入**；"我在哪个盒里"以它们为准，永远不要用工作区路径去推导盒名。 |
+
+诊断文件：上述日志目录下的 `provider.log`、`host.log`、`tool.log`。`host.log` 上限 512 KB，只记状态迁移。
+
+## 实现要点（简述）
+
+- bundle 层禁用原 `sandbox` 行（`@deepseek-ai/dsh-sandbox-local`）并插入本包的 provider，它继承原 provider：只把「写时复制」这一预设分流，其余模式一律委托原 ACL 路径。用 `runnerCommand` 做不到这件事——那会作用于所有模式。
+- 同一层把 `copy-on-write` **合并**进 `permission` 的预设目录，保留之前各层贡献的条目。
+- shell 命令经 `bin/dsh-sbie-run.mjs`——一个持有 Sandboxie FFI 的纯 Node 子进程。Sandboxie 由服务创建进程并丢弃标准句柄，因此 stdio 走回环 TCP + 长度前缀帧回传。
+- 盒名由工作区路径确定性派生成词对（`dsh_<形容词>_<名词>`），不需要状态文件；冲突时按候选序列顺延，且只有当 Sandboxie 配置表明该工作区确实拥有某盒时才采用它。
+- 只有"加载 harness 包失败"是致命错误，此时注册的 provider 会**失败关闭**：拒绝执行命令，而不是不加限制地执行。
+
+## 开发
+
+架构与踩过的坑见 [AGENTS.md](AGENTS.md)。常用命令：
+
+```powershell
+node test\unit.mjs               # 纯逻辑
+node test\host-projection.mjs    # 标题栏投影（不依赖 harness 包）
+node test\validate-patch.mjs     # 本 bundle 的层：结构 + 真的执行预设合并表达式
+node test\run-tests.mjs          # 验收：真沙盒、真重定向（须在盒外、Medium IL）
+```
+
+## 许可
+
+MIT —— 见 [LICENSE](LICENSE)。

package/bin/dsh-sbie-run.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * dsh-sbie-run — DSH sandbox runner backed by Sandboxie-Plus.
+ *
+ * Wire it into DSH by pointing the `sandbox` plugin row at this file:
+ *
+ *   - id: sandbox
+ *     name: '@deepseek-ai/dsh-sandbox-local'
+ *     config:
+ *       runnerCommand: ['<node.exe>', '<plugin>/bin/dsh-sbie-run.mjs']
+ *       runnerFailureSignatures: ['dsh-sbie-run: ']
+ *
+ * See README.zh.md for the full wiring block and the semantics.
+ */
+import { manage } from "../lib/cli.mjs";
+import { main } from "../lib/run.mjs";
+
+const argv = process.argv.slice(2);
+if (argv[0] === "--manage") {
+  process.exitCode = manage(argv.slice(1));
+} else {
+  await main(argv);
+}

package/cordis.patch.yml

@@ -0,0 +1,79 @@
+# dsh-sandboxie-redirect — the bundle layer.
+#
+# `dsh plugin --profile <name> add @lone-wolf-akela/dsh-sandboxie-redirect` appends this package
+# to the profile's `dsh.profile.bundles`; the next profile boot applies THIS
+# layer. Rows reference the package by NAME, not by path: Node resolution finds
+# the installed code through the profile's package graph, so the same file works
+# from npm, a tarball, a `link:` checkout or `github:` install.
+#
+# Two consequences of the patch vocabulary, both load-bearing:
+#
+#   * On a NON-insert patch, `name` is a GUARD rather than a reassignment:
+#     applyEntryPatches keeps `id` plus the remaining overrides and skips the
+#     whole patch when `name` does not equal the target row's name. The stock
+#     provider row therefore cannot be re-pointed in place — it is DISABLED
+#     here, and ours is inserted as its own row.
+#
+#   * A patch replaces a row's entire `config` (no deep merge). Restating the
+#     stock presets as literals would therefore silently DISCARD any preset a
+#     later DSH version or another bundle contributes. So `presets` is computed:
+#     it reads whatever the layers before this one composed and merges ours in,
+#     falling back to the literal stock three when that composition cannot be
+#     read. The failure mode is the old behaviour — never a preset directory
+#     that is missing the shipped presets.
+#
+# The plugin's own README documents what the preset does; the reasoning behind
+# this file's shape lives in AGENTS.md.
+
+# The stock shell-sandbox provider is replaced by ours. `runnerCommand` cannot
+# do this job: a configured runner applies to EVERY mode, whereas only the
+# copy-on-write *preset* should be diverted.
+- id: sandbox
+  name: "@deepseek-ai/dsh-sandbox-local"
+  disabled: true
+
+- id: permission
+  name: "@deepseek-ai/dsh-permission-presets"
+  config:
+    # The leading glyph in the display name is deliberate and load-bearing: the
+    # shipped dropdown takes its icons from a CLOSED id->icon map, so a custom
+    # preset renders with none, and the label span is not a stable handle for a
+    # DOM shim (its shape changes when the row is selected). The name is host
+    # config rendered verbatim in every surface, so the glyph belongs here.
+    # The preset also deliberately bundles the LEGAL `workspace-write` mode: the
+    # preset identity is what selects the redirect, so the session projection
+    # schema, SANDBOX_MODES, the file fence and the escalation tables all stay
+    # untouched.
+    presets: !!js >-
+      (() => {
+      const copyOnWrite = {
+      sandbox: "workspace-write",
+      approval: "ask",
+      name: "❐ Copy-on-write 写时复制",
+      description: "Writes inside the workspace go to the real disk; writes, edits and deletes anywhere else still succeed but land in this workspace's Sandboxie copy, which SandMan can inspect, recover or discard. 工作区内的写入照旧落到真实磁盘；工作区外的写入、修改、删除不会失败，改落到本工作区的 Sandboxie 副本里。"
+      };
+      const stock = {
+      "read-only": { sandbox: "read-only", approval: "ask" },
+      "workspace-write": { sandbox: "workspace-write", approval: "ask" },
+      "danger-full-access": { sandbox: "danger-full-access", approval: "never" }
+      };
+      let base;
+      try {
+      base = [...ctx.loader.entries()].find((entry) => entry.options?.id === "permission")?.options?.config?.presets;
+      } catch {}
+      const usable = base !== undefined && base !== null && ["read-only", "workspace-write", "danger-full-access"].every((key) => base[key] !== undefined);
+      const source = usable ? base : stock;
+      const keys = Object.keys(source).filter((key) => key !== "copy-on-write");
+      const after = keys.indexOf("workspace-write");
+      keys.splice(after === -1 ? keys.length : after + 1, 0, "copy-on-write");
+      return Object.fromEntries(keys.map((key) => [key, key === "copy-on-write" ? copyOnWrite : source[key]]));
+      })()
+
+# ONE row into this package, and that is a hard requirement: the client-modules
+# registry composes a `dsh.client` package only while exactly ONE of its loader
+# entries is active, and it fails the whole boot otherwise. The header chip, the
+# policy note and the `sandbox_clear` tool are plain imports wired from this
+# row's constructor (see wireCompanions() in lib/provider.mjs).
+- insert:
+    - id: sandbox-copy-on-write
+      name: "@lone-wolf-akela/dsh-sandboxie-redirect"