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

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 Notable changes per release. The format is loose; the version numbers are what
 the DSH compatibility gate reads.
 
+## 0.3.2 — 2026-10-13
+
+**DeepSeek Harness installation lookup**
+
+- The launcher no longer assumes DSH is installed in
+  `%LOCALAPPDATA%\Programs\DeepSeek Harness`. `koffi.node` ships *inside* the
+  installation, so a relocated DSH failed every command with "koffi native addon
+  not found". The new `lib/dsh-locate.mjs` finds the installation instead: the
+  interpreter's own path walked upwards (the host starts the launcher with the
+  Node the app ships, so that path points back at the installation), then the
+  installer's uninstall entry — `InstallLocation`, `DisplayIcon` and
+  `UninstallString` are all accepted, and it is found by display name because
+  the key is a GUID — then the conventional folders and `PATH`.
+- `DSH_SBIE_KOFFI` and `DSH_SBIE_KOFFI_ROOT` remain the explicit overrides, and
+  the failure message now says what it looked for and where.
+- New `test/dsh-locate.mjs` (18 offline checks) pins the source order and
+  includes a regression case for an installation outside every default folder.
+
+**Packaging**
+
+- `bin` no longer carries a leading `./`. npm's `@npmcli/package-json`
+  normalizes that away and then reports `"bin[dsh-sbie-run]" script name
+  bin/dsh-sbie-run.mjs was invalid and removed` on every publish; the emitted
+  path was already the normalized one, so this removes a misleading warning and
+  nothing else. `test/unit.mjs` pins the form.
+
+## 0.3.1 — 2026-10-12
+
+**Sandboxie installation lookup**
+
+- The engine is no longer looked for in a fixed four-path list. The new
+  `lib/sbie-locate.mjs` reads Sandboxie's own registry entries first — the
+  `SbieSvc` service's `ImagePath` above all, which every installation able to
+  create a box must have — then the driver service and the installer's uninstall
+  entry, then the conventional folders and `PATH`, and only as a last resort
+  walks well-known parent folders and fixed-drive roots for a directory named
+  after Sandboxie. An installation on another drive, in a per-user folder or in
+  a portable directory is now found instead of reported as "not installed".
+- `DSH_SBIE_DIR` still wins when set, and the "not installed" error now names it
+  as well as `SbieDll.dll`, so the remaining unusual cases are actionable.
+- `--manage list` prints the installation folder it resolved and how it found it
+  (registry / conventional folder / `PATH` / disk scan).
+- The registry is read through `koffi`/`advapi32` when available — exact wide
+  characters, no subprocess — and through `reg.exe` when it is not.
+- New `test/sbie-locate.mjs` (25 checks, no Sandboxie and no registry needed)
+  covers the registry value shapes, the candidate ordering, and the staged
+  resolution, including that the disk scan runs only when nothing cheap answers.
+  It is part of `npm test`.
+
 ## 0.3.0 — 2026-10-07
 
 The distribution changed shape, so this is a breaking release for the earlier

package/README.md

@@ -1,5 +1,10 @@
 # dsh-sandboxie-redirect
 
+[![npm version](https://img.shields.io/npm/v/@lone-wolf-akela/dsh-sandboxie-redirect?label=npm&color=cb3837)](https://www.npmjs.com/package/@lone-wolf-akela/dsh-sandboxie-redirect)
+[![CI](https://github.com/lone-wolf-akela/dsh-sandboxie-redirect/actions/workflows/ci.yml/badge.svg)](https://github.com/lone-wolf-akela/dsh-sandboxie-redirect/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platform: Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%2F11-0078d4.svg)](#installation)
+
 > **中文版**：[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.
@@ -35,6 +40,10 @@ A [DSH](https://github.com/deepseek-ai/deepseek-harness) bundle that adds a four
 
 **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.
 
+**Any installation folder works — there is nothing to configure.** The plugin does not assume Sandboxie lives in one fixed directory: it reads Sandboxie's own registry entries first (the `SbieSvc` service's `ImagePath` is the authority — an installation that can create a box always has it, followed by the driver service and the installer's uninstall entry), then the conventional folders and `PATH`, and only as a last resort sweeps well-known parent folders and each fixed drive's root for a folder named after Sandboxie that holds `SbieDll.dll`. Another drive, a per-user folder and a portable directory all work. Only when every one of those comes up empty does it report "not installed", and that message names `DSH_SBIE_DIR` (see [Environment](#environment)) as the way to point at it directly.
+
+**DSH's own installation folder is not assumed either.** The `koffi.node` the launcher needs ships *inside* DSH, under its `resources\app.asar.unpacked`, and the launcher is a plain Node process with no `process.resourcesPath`. So the plugin locates DSH itself: the Node running the launcher (the desktop app's own runtime lives inside the installation, so that path points back at it), then the installer's uninstall entry, then the conventional folders and `PATH`. DSH installed on another drive works too.
+
 The package is a DSH *bundle*: installing it also adds its configuration layer, so no profile file needs hand-editing.
 
 ```powershell
@@ -50,7 +59,7 @@ 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
+dsh plugin --profile <profile> add .\lone-wolf-akela-dsh-sandboxie-redirect-0.3.1.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.
@@ -118,11 +127,12 @@ All optional; each exists as an escape hatch rather than a configuration surface
 
 | Variable | Effect |
 |---|---|
+| `DSH_SBIE_DIR` | The Sandboxie installation folder (the one holding `SbieDll.dll`). Normally unnecessary: the automatic lookup reads Sandboxie's registry entries, the conventional folders and `PATH` first. Use it when Sandboxie lives somewhere unusual and that lookup misses it. |
 | `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_KOFFI` / `DSH_SBIE_KOFFI_ROOT` | A `koffi.node` (or a directory holding one) for the launcher. Normally unnecessary: DSH's own installation folder is located automatically (see [Installation](#installation)). |
 | `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.
@@ -137,15 +147,16 @@ Diagnostics: `provider.log`, `host.log`, `tool.log` under the log directory abov
 
 ## Development
 
-See [AGENTS.md](AGENTS.md) for the architecture and the hard-won constraints. The short version:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the development loop, and [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)
+npm test                         # unit + host projection + bundle-layer validation (no DSH, no Sandboxie)
+npm run test:acceptance          # acceptance: real boxes, real redirection (outside any box, medium IL)
+npm run pack:check               # what the published tarball would contain
 ```
 
+Security issues: see [SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -1,5 +1,10 @@
 # dsh-sandboxie-redirect
 
+[![npm version](https://img.shields.io/npm/v/@lone-wolf-akela/dsh-sandboxie-redirect?label=npm&color=cb3837)](https://www.npmjs.com/package/@lone-wolf-akela/dsh-sandboxie-redirect)
+[![CI](https://github.com/lone-wolf-akela/dsh-sandboxie-redirect/actions/workflows/ci.yml/badge.svg)](https://github.com/lone-wolf-akela/dsh-sandboxie-redirect/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platform: Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%2F11-0078d4.svg)](#安装)
+
 > **English**: [README.md](README.md)
 
 给 [DSH](https://github.com/deepseek-ai/deepseek-harness) 增加第四种权限预设 **「写时复制」** 的 bundle：shell 命令跑在本工作区专属的 Sandboxie 沙盒里，工作区内的写入照常落到真实磁盘；工作区外的写入、修改、删除不会失败，但只落进该沙盒的副本。原有三个预设（只读 / 仅工作区 / 完全权限）行为不变。
@@ -34,6 +39,10 @@
 
 **前置条件**：[Sandboxie-Plus](https://sandboxie-plus.com/)（[源码](https://github.com/sandboxie-plus/Sandboxie)）。安装后它的服务须在运行；本插件的所有沙盒都由 Sandboxie 创建与管理。
 
+**装在哪儿都行，不需要配置。** 插件不假设 Sandboxie 在某个固定目录：它先读 Sandboxie 自己的注册表项（`SbieSvc` 服务的 `ImagePath` 最权威——能建沙盒的安装必然有它，其次是驱动服务与卸载项），再看 `%ProgramFiles%\Sandboxie-Plus` 等常规位置与 `PATH`，最后才按名字扫一遍常见父目录与各固定磁盘根目录，找含 `SbieDll.dll` 的文件夹。装在别的盘、用户目录、便携目录都可以。只有全部落空时才会报 "not installed"，此时用 `DSH_SBIE_DIR` 直接指定（见[环境变量](#环境变量)）。
+
+**DSH 自己的安装目录同样不假定。** 启动器要用的 `koffi.node` 是随 DSH 一起装在它 `resources\app.asar.unpacked` 里的，而启动器是普通 Node 进程（没有 `process.resourcesPath`）。插件会自己定位 DSH：先看运行启动器的那个 node（桌面应用自带的运行时就在安装目录里，这条路径本身就指回安装位置），再看安装器留下的卸载项，最后才是常规目录与 `PATH`。DSH 装在别的盘也能正常工作。
+
 本包是 DSH 的 **bundle**（自带配置层），装进去就自动挂载，**不需要手改 profile 文件**。
 
 ```powershell
@@ -49,7 +58,7 @@ dsh --profile <profile>
 
 ```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
+dsh plugin --profile <profile> add .\lone-wolf-akela-dsh-sandboxie-redirect-0.3.1.tgz
 ```
 
 > **哪个 profile 用哪条路？** 正在运行的桌面应用独占的 profile（`desktop`）会被 CLI 拒绝操作（`profile "desktop" is managed exclusively by the Electron application`）。这种 profile 请在**应用内**装：**设置 → 插件 → 添加 bundle**，填上面的包名。其它 profile 用 CLI 即可。
@@ -117,11 +126,12 @@ node bin\dsh-sbie-run.mjs --manage delete-box <沙盒名>      # 删除指定沙
 
 | 变量 | 作用 |
 |---|---|
+| `DSH_SBIE_DIR` | Sandboxie 安装目录（含 `SbieDll.dll` 的那个文件夹）。通常不需要：上面的自动查找会先从注册表、常规位置与 `PATH` 里找。装在非常规目录且自动查找没命中时用它。 |
 | `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_KOFFI` / `DSH_SBIE_KOFFI_ROOT` | 启动器要用的 `koffi.node`（或含它的目录）。通常不需要：DSH 的安装位置会被自动定位（见[安装](#安装)）。 |
 | `DSH_SBIE_BOX` / `DSH_SANDBOX_ROOT` | **由插件在命令内注入**；"我在哪个盒里"以它们为准，永远不要用工作区路径去推导盒名。 |
 
 诊断文件：上述日志目录下的 `provider.log`、`host.log`、`tool.log`。`host.log` 上限 512 KB，只记状态迁移。
@@ -136,15 +146,16 @@ node bin\dsh-sbie-run.mjs --manage delete-box <沙盒名>      # 删除指定沙
 
 ## 开发
 
-架构与踩过的坑见 [AGENTS.md](AGENTS.md)。常用命令：
+环境准备与开发回路见 [CONTRIBUTING.md](CONTRIBUTING.md)，架构与踩过的坑见 [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）
+npm test                         # 单元 + 标题栏投影 + bundle 层校验（不需要 DSH、不需要 Sandboxie）
+npm run test:acceptance          # 验收：真沙盒、真重定向（须在盒外、Medium IL）
+npm run pack:check               # 看发布的 tarball 里会有什么
 ```
 
+安全问题见 [SECURITY.md](SECURITY.md)。
+
 ## 许可
 
 MIT —— 见 [LICENSE](LICENSE)。

package/lib/cli.mjs

@@ -8,7 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { boxNameCandidates, canonicalWorkspace, listManagedBoxes, managedBoxesFor, removeBox, rootFor } from "./boxes.mjs";
-import { boxExists, reloadConfig, sbieDir, sbieIni } from "./sbie.mjs";
+import { boxExists, reloadConfig, sbieDir, sbieDirSource, sbieIni, sbieNotInstalledError } from "./sbie.mjs";
 
 function print(line) {
   process.stdout.write(`${line}\n`);
@@ -62,10 +62,15 @@ function directorySize(dir) {
 }
 
 function list() {
-  if (sbieDir() === undefined) {
-    print("Sandboxie-Plus is not installed.");
+  const installDir = sbieDir();
+  if (installDir === undefined) {
+    print(sbieNotInstalledError().message);
     return 1;
   }
+  // Reported because "which Sandboxie is this plugin driving?" is the first
+  // question when a machine has more than one installation, and the answer is
+  // no longer a single fixed path.
+  print(`Sandboxie: ${installDir} (found via ${sbieDirSource()})`);
   const boxes = listManagedBoxes();
   if (boxes.length === 0) {
     print("No managed boxes (Dsh_* / Dshr_*) exist yet.");

package/lib/dsh-locate.mjs

@@ -0,0 +1,302 @@
+/**
+ * Find where DeepSeek Harness itself is installed.
+ *
+ * `koffi.node` does not come from npm: it ships *inside* the DSH installation,
+ * as an unpacked native addon under `resources\app.asar.unpacked`. The launcher
+ * that needs it is a plain Node process, so it has no `process.resourcesPath`
+ * and no idea where the app that started it lives. `lib/koffi.mjs` used to
+ * assume `%LOCALAPPDATA%\Programs\DeepSeek Harness` (and the two `%ProgramFiles%`
+ * spellings), which fails the moment DSH is installed anywhere else — exactly
+ * like the Sandboxie folder assumption this plugin already had to drop.
+ *
+ * Four sources, most trustworthy first:
+ *
+ *  1. `process.resourcesPath` — present when this runs inside Electron; the
+ *     direct answer.
+ *  2. `process.execPath` walked upwards. The host picks the launcher's Node
+ *     through `redirect.mjs`'s `resolveNodePath()`, which prefers the runtime
+ *     shipped *inside* the app; when that is what is running, its own path
+ *     points straight back at the installation.
+ *  3. The uninstall entry the installer writes. It lives under a generated key
+ *     (`…\Uninstall\<GUID>`), so it is found by searching that hive for the
+ *     display name, and `InstallLocation` / `DisplayIcon` / `UninstallString`
+ *     are all accepted as evidence — the per-user installer only guarantees
+ *     some of them.
+ *  4. The conventional folders and `PATH`, for an installation that was
+ *     unpacked by hand.
+ *
+ * WHY THIS MODULE IMPORTS ONLY NODE BUILTINS. `lib/koffi.mjs` imports it, and
+ * `lib/sbie-locate.mjs` imports `lib/koffi.mjs`; reaching back into either from
+ * here would close a cycle through the very loader this module exists to feed.
+ * The few small helpers it needs are therefore repeated rather than shared, and
+ * every side effect is injectable so the whole resolver is testable offline.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** The executable that names a DSH installation folder. */
+export const DSH_EXE = "DeepSeek Harness.exe";
+/** The name the installer's uninstall entry carries (`DeepSeek Harness 0.2.0-rc.2`). */
+export const DSH_DISPLAY_NAME = "DeepSeek Harness";
+/** The folder name an installation uses by default (`%LOCALAPPDATA%\Programs\DeepSeek Harness`). */
+export const DSH_DIR_NAME = "DeepSeek Harness";
+
+/**
+ * The uninstall hives an installer may have used. A per-user install lands in
+ * HKCU; a machine-wide one in HKLM, in the view matching the installer's
+ * bitness. Nothing fixed can be queried, because the subkey is a GUID.
+ */
+export const DSH_UNINSTALL_KEYS = [
+  "HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall",
+  "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall",
+  "HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall"
+];
+
+/** Environment lookup that is case-insensitive, like Windows' own. */
+function envLookup(env, name) {
+  if (env === undefined || env === null) return undefined;
+  const wanted = name.toLowerCase();
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() !== wanted) continue;
+    const value = env[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** Replace `%NAME%` references; unknown names are left alone (they simply fail validation later). */
+export function expandEnvRefs(value, env = process.env) {
+  return String(value).replace(/%([^%]+)%/g, (whole, name) => envLookup(env, name) ?? whole);
+}
+
+/** De-duplicate case-insensitively, keeping each first occurrence's spelling. */
+export function uniqueDirs(dirs) {
+  const seen = new Set();
+  const unique = [];
+  for (const dir of dirs ?? []) {
+    if (typeof dir !== "string" || dir.length === 0) continue;
+    const key = dir.replace(/[\\/]+$/, "").toLowerCase();
+    if (key.length === 0 || seen.has(key)) continue;
+    seen.add(key);
+    unique.push(dir);
+  }
+  return unique;
+}
+
+function existsWith(exists, candidate) {
+  try {
+    return exists(candidate) === true;
+  } catch {
+    return false;
+  }
+}
+
+const has = (exists, ...parts) => existsWith(exists, path.join(...parts));
+
+/**
+ * Whether `dir` is a DSH installation folder: it holds the app bundle (packed or
+ * unpacked) under `resources`, or the launcher executable itself.
+ */
+export function isDshInstallRoot(dir, options = {}) {
+  const exists = options.exists ?? fs.existsSync;
+  if (typeof dir !== "string" || dir.length === 0) return false;
+  return (
+    has(exists, dir, "resources", "app.asar") ||
+    has(exists, dir, "resources", "app.asar.unpacked") ||
+    has(exists, dir, DSH_EXE)
+  );
+}
+
+/**
+ * The folders under which the koffi addon may be searched, given either a DSH
+ * installation folder or DSH's `resources` folder (or its `app.asar.unpacked`
+ * itself). Empty when the candidate is neither — which is what makes an
+ * unvalidated guess safe.
+ *
+ * `app.asar.unpacked` comes first because that is where the addon actually is;
+ * the plain `resources` folder is included as well, because the search under it
+ * can still reach a payload that lives beside the packed bundle.
+ */
+export function resourcesDirsFor(candidate, options = {}) {
+  const exists = options.exists ?? fs.existsSync;
+  if (typeof candidate !== "string" || candidate.length === 0) return [];
+  const base = path.basename(candidate).toLowerCase();
+
+  // Already the unpacked payload — which is where the addon actually lives.
+  if (base === "app.asar.unpacked") return [candidate];
+
+  // Already DSH's `resources` folder.
+  if (base === "resources" && (has(exists, candidate, "app.asar") || existsWith(exists, path.join(candidate, "app.asar.unpacked")))) {
+    return [path.join(candidate, "app.asar.unpacked"), candidate];
+  }
+
+  // An installation folder — the packed bundle, the unpacked payload or the
+  // executable is evidence enough.
+  const resources = path.join(candidate, "resources");
+  const unpacked = path.join(resources, "app.asar.unpacked");
+  if (has(exists, resources, "app.asar") || existsWith(exists, unpacked)) return [unpacked, resources];
+  if (has(exists, candidate, DSH_EXE)) return [unpacked, resources];
+  return [];
+}
+
+/**
+ * Installation folders implied by the interpreter running this code: walk up
+ * from `node.exe` (or the Electron binary) and keep every ancestor that looks
+ * like a DSH installation. The app ships its Node under
+ * `resources\runtime\<pool>\dependencies\node\bin\node.exe`, so this is a
+ * pointer, not a guess, whenever the host chose that Node.
+ */
+export function execPathInstallRoots(execPath, options = {}) {
+  if (typeof execPath !== "string" || execPath.length === 0) return [];
+  const maxUp = options.maxUp ?? 8;
+  const roots = [];
+  let dir = path.dirname(path.resolve(execPath));
+  for (let index = 0; index < maxUp; index += 1) {
+    if (isDshInstallRoot(dir, options)) roots.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached the drive root
+    dir = parent;
+  }
+  return roots;
+}
+
+/** One `reg query` value line: `<name>\t<type>\t<data>`, tabs printed as two or more spaces. */
+export function parseRegValueLine(line) {
+  const match = /^\s{2,}(\S.*?)\s{2,}(REG_[A-Z_]+)\s{2,}(.*)$/.exec(String(line));
+  if (match === null) return undefined;
+  return { name: match[1].trim().toLowerCase(), type: match[2], value: match[3].trim() };
+}
+
+/** Strip the quotes Windows installers put around paths, and any trailing argument. */
+function unquoteExecutable(value) {
+  const text = String(value).trim();
+  if (text.startsWith('"')) {
+    const end = text.indexOf('"', 1);
+    if (end !== -1) return text.slice(1, end);
+  }
+  return text.replace(/\s+\/\S+$/, "");
+}
+
+/**
+ * Installation folders named by an uninstall hive's output.
+ *
+ * The search prints the whole matching key, so every value of interest is read
+ * by name rather than by position. `DisplayIcon` carries `,0` (the icon index)
+ * and `UninstallString` carries the uninstaller's switches, so both are reduced
+ * to a folder.
+ */
+export function parseUninstallPaths(stdout, env = process.env) {
+  const dirs = [];
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    const parsed = parseRegValueLine(line);
+    if (parsed === undefined) continue;
+    const value = expandEnvRefs(parsed.value, env);
+    if (parsed.name === "installlocation") {
+      dirs.push(value.replace(/^"(.*)"$/s, "$1").replace(/[\\/]+$/, ""));
+    } else if (parsed.name === "displayicon") {
+      const exe = unquoteExecutable(value.replace(/,\s*-?\d+\s*$/, ""));
+      if (/[\\/]/.test(exe)) dirs.push(path.dirname(exe));
+    } else if (parsed.name === "uninstallstring") {
+      const exe = unquoteExecutable(value);
+      if (/[\\/]/.test(exe)) dirs.push(path.dirname(exe));
+    }
+  }
+  return uniqueDirs(dirs);
+}
+
+/**
+ * Installation folders named by the uninstall hives, through `reg.exe`.
+ *
+ * One spawn per hive with a data-only search for the display name, which prints
+ * only matching keys; parsing needs no block structure because of that. Every
+ * failure (no entry, no reg.exe) means "this machine told us nothing", never an
+ * error.
+ */
+export function readDshRegistryRoots(options = {}) {
+  const env = options.env ?? process.env;
+  const spawn = options.spawnSync ?? spawnSync;
+  const dirs = [];
+  for (const key of DSH_UNINSTALL_KEYS) {
+    let result;
+    try {
+      result = spawn("reg.exe", ["query", key, "/s", "/f", DSH_DISPLAY_NAME, "/d"], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 10000
+      });
+    } catch {
+      continue;
+    }
+    if (result?.status !== 0) continue;
+    dirs.push(...parseUninstallPaths(result.stdout, env));
+  }
+  return uniqueDirs(dirs);
+}
+
+/**
+ * The folders a DSH installation conventionally occupies. A per-user install
+ * goes under `%LOCALAPPDATA%\Programs`; a machine-wide one under either
+ * `%ProgramFiles%` spelling, which is why all three are probed.
+ */
+export function defaultDshRoots(env = process.env) {
+  const roots = [];
+  const localAppData = envLookup(env, "LOCALAPPDATA");
+  if (localAppData !== undefined) roots.push(path.join(localAppData, "Programs", DSH_DIR_NAME));
+  for (const name of ["ProgramFiles", "ProgramFiles(x86)", "ProgramW6432"]) {
+    const base = envLookup(env, name);
+    if (base !== undefined) roots.push(path.join(base, DSH_DIR_NAME));
+  }
+  return roots;
+}
+
+/** `PATH` entries that name DeepSeek Harness; a portable install is often launched from one. */
+export function pathDshRoots(env = process.env) {
+  const raw = envLookup(env, "PATH");
+  if (raw === undefined) return [];
+  const roots = [];
+  for (const entry of raw.split(";")) {
+    const dir = entry.trim().replace(/^"(.*)"$/s, "$1").trim().replace(/[\\/]+$/, "");
+    if (dir.length === 0) continue;
+    if (!/deepseek[\s_-]*harness/i.test(dir)) continue;
+    roots.push(dir);
+  }
+  return roots;
+}
+
+/**
+ * Every installation folder worth probing, in trust order: what the running
+ * interpreter points at, what the installer recorded, then the conventional
+ * locations and `PATH`. Later entries are unvalidated on purpose — validation
+ * happens in `resourcesDirsFor`, so a wrong guess contributes nothing.
+ */
+export function dshInstallRoots(options = {}) {
+  const env = options.env ?? process.env;
+  return uniqueDirs([
+    ...execPathInstallRoots(options.execPath ?? process.execPath, options),
+    ...(options.registryRoots ?? readDshRegistryRoots(options)),
+    ...defaultDshRoots(env),
+    ...pathDshRoots(env)
+  ]);
+}
+
+/**
+ * The folders to hand to the koffi search, existing ones only, de-duplicated,
+ * in trust order.
+ *
+ * `process.resourcesPath` is consulted first when it exists: inside Electron it
+ * IS the answer, and it costs nothing to prefer it.
+ */
+export function dshResourcesRoots(options = {}) {
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? fs.existsSync;
+  const resourcesPath = typeof options.resourcesPath === "string"
+    ? options.resourcesPath
+    : (typeof process.resourcesPath === "string" ? process.resourcesPath : undefined);
+  const candidates = [];
+  if (resourcesPath !== undefined && resourcesPath.length > 0) candidates.push(resourcesPath);
+  candidates.push(...dshInstallRoots({ ...options, env }));
+  const dirs = [];
+  for (const candidate of candidates) dirs.push(...resourcesDirsFor(candidate, { exists }));
+  return uniqueDirs(dirs).filter((dir) => existsWith(exists, dir));
+}

package/lib/koffi.mjs

@@ -5,34 +5,56 @@
  * the harness install path differs per machine and per version, and the plain
  * `koffi` JS wrapper package is not always present. The addon itself is
  * self-contained, so we require the `.node` file directly.
+ *
+ * WHERE DSH ITSELF IS. The addon ships *inside* the installation, and this
+ * module runs in the launcher — a plain Node process with no
+ * `process.resourcesPath` — so the folder has to be discovered rather than
+ * known. `lib/dsh-locate.mjs` does that: the interpreter's own path walked
+ * upwards, the installer's uninstall entry, then the conventional locations and
+ * `PATH`. Hardcoding `%LOCALAPPDATA%\Programs\DeepSeek Harness` here is what
+ * made a relocated DSH report "koffi.node not found".
  */
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { dshResourcesRoots } from "./dsh-locate.mjs";
 
 const require = createRequire(import.meta.url);
 const here = path.dirname(fileURLToPath(import.meta.url));
 
 let cached;
 
-function candidateRoots() {
+/**
+ * The directories the addon search starts from, most specific first: an
+ * explicit override, a `vendor` folder beside the package, the DSH installation
+ * this process belongs to, then the managed runtime pool.
+ *
+ * Everything is injectable so the ordering can be tested offline; only the
+ * final directory check touches the real filesystem.
+ */
+export function koffiRootCandidates(options = {}) {
+  const env = options.env ?? process.env;
+  const isDirectory = options.isDirectory ?? ((candidate) => {
+    try {
+      return fs.statSync(candidate).isDirectory();
+    } catch {
+      return false;
+    }
+  });
   const roots = [];
   const push = (p) => {
     if (typeof p === "string" && p.length > 0 && !roots.includes(p)) roots.push(p);
   };
-  push(process.env.DSH_SBIE_KOFFI_ROOT);
+  push(env.DSH_SBIE_KOFFI_ROOT);
   push(path.join(here, "..", "vendor"));
-  push(process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Programs", "DeepSeek Harness", "resources", "app.asar.unpacked"));
-  push(process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Programs", "DeepSeek Harness", "resources"));
-  push(process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "DeepSeek Harness", "resources", "app.asar.unpacked"));
-  push(process.env["PROGRAMFILES(X86)"] && path.join(process.env["PROGRAMFILES(X86)"], "DeepSeek Harness", "resources", "app.asar.unpacked"));
-  push(process.env.DSH_HOME && path.join(process.env.DSH_HOME, "dsh-runtimes"));
-  push(path.join(os.homedir(), ".dsh", "dsh-runtimes"));
-  return roots.filter((r) => {
+  for (const dir of dshResourcesRoots({ ...options, env })) push(dir);
+  push(env.DSH_HOME && path.join(env.DSH_HOME, "dsh-runtimes"));
+  push(path.join(options.homeDir ?? os.homedir(), ".dsh", "dsh-runtimes"));
+  return roots.filter((root) => {
     try {
-      return fs.statSync(r).isDirectory();
+      return isDirectory(root) === true;
     } catch {
       return false;
     }
@@ -70,7 +92,7 @@ function findKoffiNode(root, maxDepth = 9) {
 }
 
 /** Resolve and load koffi once. Throws with an actionable message when absent. */
-export function loadKoffi() {
+export function loadKoffi(options = {}) {
   if (cached !== undefined) return cached;
   if (process.env.DSH_SBIE_KOFFI) {
     cached = require(process.env.DSH_SBIE_KOFFI);
@@ -81,7 +103,7 @@ export function loadKoffi() {
     return cached;
   } catch {}
   const tried = [];
-  for (const root of candidateRoots()) {
+  for (const root of koffiRootCandidates(options)) {
     tried.push(root);
     const found = findKoffiNode(root);
     if (found !== undefined) {
@@ -90,6 +112,6 @@ export function loadKoffi() {
     }
   }
   throw new Error(
-    `koffi native addon not found. Set DSH_SBIE_KOFFI to a koffi.node path. Searched: ${tried.join(", ") || "(no candidate roots)"}`
+    `koffi native addon not found. It ships inside the DeepSeek Harness installation (resources\\app.asar.unpacked), so this usually means DSH could not be located: set DSH_SBIE_KOFFI to a koffi.node path, or DSH_SBIE_KOFFI_ROOT to a folder to search. Searched: ${tried.join(", ") || "(no candidate roots)"}`
   );
 }

package/lib/run.mjs

@@ -30,7 +30,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { boxNameFor, canonicalWorkspace, ensureBox } from "./boxes.mjs";
 import { Frame, createFrameDecoder, encodeFrame, encodeJsonFrame } from "./protocol.mjs";
-import { runSandboxed, killProcess, sbieDir } from "./sbie.mjs";
+import { runSandboxed, killProcess, sbieDir, sbieNotInstalledError } from "./sbie.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const relayScript = path.join(here, "inner.mjs");
@@ -193,7 +193,7 @@ export async function run(argv, io = {}) {
   const box = options.box ?? process.env.DSH_SBIE_BOX ?? boxNameFor(workspace, mode);
   const log = options.verbose ? (message) => process.stderr.write(`dsh-sbie-run: ${message}\n`) : () => {};
 
-  if (sbieDir() === undefined) throw new Error("Sandboxie-Plus is not installed (SbieDll.dll not found)");
+  if (sbieDir() === undefined) throw sbieNotInstalledError();
 
   const ensured = ensureBox({ box, workspace, mode, logger: log });
   const env = { ...process.env, DSH_SANDBOX_ROOT: ensured.root, DSH_SBIE_BOX: ensured.box };

package/lib/sbie-locate.mjs

@@ -0,0 +1,464 @@
+/**
+ * Find where Sandboxie-Plus is installed.
+ *
+ * The engine is reached through `SbieDll.dll` and `SbieIni.exe`, both of which
+ * live in the installation folder — and that folder is NOT always the default
+ * `%ProgramFiles%\Sandboxie-Plus`. A user may install to another drive, to a
+ * per-user folder, or into a portable directory. Probing a fixed list of four
+ * paths therefore reports "Sandboxie-Plus is not installed" on machines where
+ * it plainly is.
+ *
+ * The authoritative source is Sandboxie's own service registration:
+ * `SbieDll_RunSandboxed` is only usable while `SbieSvc` runs, and the service
+ * key's `ImagePath` names the real installation folder. The driver service and
+ * the installer's uninstall entry name it too. Those are read first, then the
+ * conventional folders, then `PATH`, and only if all of that fails is the disk
+ * walked — a bounded, one-level scan of well-known parent folders and of each
+ * fixed drive's root, looking for a directory whose name names Sandboxie.
+ *
+ * Everything here is dependency-light on purpose: the module is imported by the
+ * launcher (a plain Node process) and is unit-testable with no Sandboxie, no
+ * registry, and no Windows at all, because every side effect is injectable.
+ * `koffi` is loaded lazily and only when the registry is actually consulted.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { loadKoffi } from "./koffi.mjs";
+
+/** The DLL whose presence in a folder is what makes it an installation folder. */
+export const SBIE_DLL = "SbieDll.dll";
+
+/** Windows' predefined `HKEY_LOCAL_MACHINE`. */
+const HKEY_LOCAL_MACHINE = 0x80000002;
+/** `RegGetValueW` restrictions: accept `REG_SZ` and `REG_EXPAND_SZ` (expanded for us). */
+const RRF_RT_REG_SZ = 0x00000002;
+const RRF_RT_REG_EXPAND_SZ = 0x00000004;
+/** The largest registry value this module bothers to hold (a path never comes close). */
+const REGISTRY_VALUE_BYTES = 4096;
+/** `GetDriveTypeW` answer for a fixed disk. */
+const DRIVE_FIXED = 3;
+
+/**
+ * Registry locations that name the installation folder, most authoritative
+ * first. `kind: "file"` means the value names a file inside the folder (so the
+ * folder is its directory); `kind: "dir"` means the value IS the folder.
+ *
+ * `HKLM\SYSTEM\CurrentControlSet\Services\SbieSvc` is the load-bearing one: a
+ * Sandboxie that cannot register that service cannot start a boxed process at
+ * all, so the folder it names is the folder this plugin must use whenever the
+ * plugin can work.
+ */
+export const SBIE_REGISTRY_SOURCES = [
+  {
+    key: "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SbieSvc",
+    values: [{ name: "ImagePath", kind: "file" }]
+  },
+  {
+    key: "HKLM\\SYSTEM\\CurrentControlSet\\Services\\SbieDrv",
+    values: [{ name: "ImagePath", kind: "file" }]
+  },
+  {
+    key: "HKLM\\SOFTWARE\\Sandboxie-Plus",
+    values: [
+      { name: "InstallDir", kind: "dir" },
+      { name: "InstallLocation", kind: "dir" },
+      { name: "SbieHome", kind: "dir" },
+      { name: "HomeDir", kind: "dir" }
+    ]
+  },
+  {
+    key: "HKLM\\SOFTWARE\\WOW6432Node\\Sandboxie-Plus",
+    values: [
+      { name: "InstallDir", kind: "dir" },
+      { name: "InstallLocation", kind: "dir" },
+      { name: "SbieHome", kind: "dir" },
+      { name: "HomeDir", kind: "dir" }
+    ]
+  },
+  {
+    // Sandboxie-Plus ships an Inno Setup installer; both registry views are read
+    // because the installer's bitness decides which one it wrote.
+    key: "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Sandboxie-Plus_is1",
+    values: [
+      { name: "InstallLocation", kind: "dir" },
+      { name: "Inno Setup: App Path", kind: "dir" },
+      { name: "DisplayIcon", kind: "file" }
+    ]
+  },
+  {
+    key: "HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Sandboxie-Plus_is1",
+    values: [
+      { name: "InstallLocation", kind: "dir" },
+      { name: "Inno Setup: App Path", kind: "dir" },
+      { name: "DisplayIcon", kind: "file" }
+    ]
+  }
+];
+
+/** Environment lookup that is case-insensitive, like Windows' own. */
+function envLookup(env, name) {
+  if (env === undefined || env === null) return undefined;
+  const wanted = name.toLowerCase();
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() !== wanted) continue;
+    const value = env[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Replace `%NAME%` references with the environment's values. Unknown names are
+ * left alone: a candidate that keeps an unresolved placeholder simply fails the
+ * `SbieDll.dll` check and costs nothing, whereas guessing a value could point
+ * at the wrong folder.
+ */
+export function expandEnvRefs(value, env = process.env) {
+  return String(value).replace(/%([^%]+)%/g, (whole, name) => envLookup(env, name) ?? whole);
+}
+
+/**
+ * Turn one registry value into the folder it names.
+ *
+ * Handles the shapes these keys actually hold: surrounding quotes, the
+ * `\??\`/`\\?\` prefixes the driver service uses, `%ProgramFiles%`-style
+ * references (already expanded on the `RegGetValueW` path, expanded here on the
+ * `reg.exe` one), and trailing separators. Returns `undefined` when the value
+ * cannot name a folder.
+ *
+ * @param raw - the registry value.
+ * @param kind - `"file"` (a file inside the folder) or `"dir"` (the folder).
+ * @param env - environment used to expand `%NAME%` references.
+ */
+export function directoryFromRegistryValue(raw, kind = "dir", env = process.env) {
+  if (typeof raw !== "string") return undefined;
+  let text = expandEnvRefs(raw, env).trim();
+  if (text.length === 0) return undefined;
+  const quoted = /^"(.*)"$/s.exec(text);
+  if (quoted !== null) text = quoted[1].trim();
+  // `\??\C:\…` (driver ImagePath), `\\?\C:\…` (long-path form), `\SystemRoot\…`.
+  text = text.replace(/^(?:\\\?\?\\|\\\\\?\\|\\SystemRoot\\)/i, "");
+  if (text.length === 0) return undefined;
+  const trimmed = text.replace(/[\\/]+$/, "");
+  if (trimmed.length === 0) return undefined;
+  if (kind !== "file") return trimmed;
+  // A file value must carry a directory; a bare name would resolve to ".".
+  if (!/[\\/]/.test(trimmed)) return undefined;
+  const dir = path.dirname(trimmed).replace(/[\\/]+$/, "");
+  return dir.length === 0 || dir === "." ? undefined : dir;
+}
+
+/**
+ * The value of one `reg query` line, or `undefined`.
+ *
+ * The format is fixed: `<value>\t<type>\t<data>`, with two or more spaces in
+ * place of tabs. A value name may itself contain spaces (`Inno Setup: App
+ * Path`), so the name/type split is found by the `REG_*` token rather than by
+ * splitting on the first run of whitespace.
+ *
+ * @param stdout - `reg query <key> /v <name>` output.
+ * @param name - the value name that was asked for.
+ */
+export function parseRegQueryValue(stdout, name) {
+  const wanted = String(name).toLowerCase();
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    const match = /^\s{2,}(\S.*?)\s{2,}(REG_[A-Z_]+)\s{2,}(.*)$/.exec(line);
+    if (match === null) continue;
+    if (match[1].trim().toLowerCase() !== wanted) continue;
+    return match[3].trim();
+  }
+  return undefined;
+}
+
+/** Read the registry through koffi/advapi32 (wide characters, no subprocess). */
+function readRegistryValuesNative() {
+  const koffi = loadKoffi();
+  const advapi = koffi.load("advapi32.dll");
+  const regGetValue = advapi.func("__stdcall", "RegGetValueW", "int32", [
+    "uintptr", // HKEY
+    "str16", // LPCWSTR lpSubKey
+    "str16", // LPCWSTR lpValue
+    "uint32", // DWORD dwFlags
+    "void *", // LPDWORD pdwType
+    "void *", // PVOID pvData
+    koffi.inout(koffi.pointer("uint32")) // LPDWORD pcbData
+  ]);
+  const found = [];
+  for (const source of SBIE_REGISTRY_SOURCES) {
+    const subkey = source.key.replace(/^HKLM\\/i, "");
+    for (const entry of source.values) {
+      const buffer = Buffer.alloc(REGISTRY_VALUE_BYTES);
+      const size = [buffer.length];
+      const status = regGetValue(HKEY_LOCAL_MACHINE, subkey, entry.name, RRF_RT_REG_SZ | RRF_RT_REG_EXPAND_SZ, null, buffer, size);
+      if (status !== 0) continue; // ERROR_FILE_NOT_FOUND / no such key: simply not this source
+      const value = buffer.toString("utf16le").replace(/\0[\s\S]*$/s, "").trim();
+      if (value.length > 0) found.push({ value, kind: entry.kind, source: source.key });
+    }
+  }
+  return found;
+}
+
+/**
+ * Read the registry through `reg.exe`; used only when koffi cannot be used at all.
+ *
+ * One spawn per KEY rather than per value: `reg query <key>` prints every value
+ * of the key, and the parser picks the ones that interest us. Spawning costs
+ * tens of milliseconds each, so this halves the fallback's latency.
+ */
+function readRegistryValuesRegExe() {
+  const found = [];
+  for (const source of SBIE_REGISTRY_SOURCES) {
+    let result;
+    try {
+      result = spawnSync("reg.exe", ["query", source.key], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 5000
+      });
+    } catch {
+      continue;
+    }
+    if (result?.status !== 0) continue;
+    for (const entry of source.values) {
+      const value = parseRegQueryValue(result.stdout, entry.name);
+      if (value !== undefined && value.length > 0) found.push({ value, kind: entry.kind, source: source.key });
+    }
+  }
+  return found;
+}
+
+/**
+ * Every registry value that names an installation folder, in source order.
+ *
+ * `koffi` is tried first because it decodes the wide-character values exactly
+ * and spawns nothing; `reg.exe` is the fallback, since a machine where the
+ * plugin works always has it even if koffi cannot be located.
+ */
+export function readSbieRegistryValues() {
+  try {
+    return readRegistryValuesNative();
+  } catch {
+    /* no koffi, or advapi32 unavailable: reg.exe still answers */
+  }
+  try {
+    return readRegistryValuesRegExe();
+  } catch {
+    return [];
+  }
+}
+
+/** Folders from registry values, in order, with `undefined`s dropped. */
+export function registryCandidateDirs(values, env = process.env) {
+  const dirs = [];
+  for (const entry of values ?? []) {
+    const dir = directoryFromRegistryValue(entry?.value, entry?.kind, env);
+    if (dir !== undefined) dirs.push(dir);
+  }
+  return dirs;
+}
+
+/**
+ * The conventional installation folders. `%ProgramFiles%` and friends cover a
+ * relocated Windows as well as a relocated Sandboxie; the literal last entry is
+ * the historical default, kept so a machine with no environment at all still
+ * gets the old behaviour.
+ */
+export function defaultSbieDirs(env = process.env) {
+  const dirs = [];
+  const under = (base) => {
+    if (typeof base !== "string" || base.length === 0) return undefined;
+    return path.join(base, "Sandboxie-Plus");
+  };
+  for (const name of ["ProgramFiles", "ProgramFiles(x86)", "ProgramW6432"]) {
+    const dir = under(envLookup(env, name));
+    if (dir !== undefined) dirs.push(dir);
+  }
+  const localAppData = envLookup(env, "LOCALAPPDATA");
+  if (localAppData !== undefined) dirs.push(path.join(localAppData, "Programs", "Sandboxie-Plus"));
+  const systemDrive = envLookup(env, "SystemDrive");
+  if (systemDrive !== undefined) dirs.push(path.join(systemDrive, "Sandboxie-Plus"));
+  dirs.push("C:\\Program Files\\Sandboxie-Plus");
+  return dirs;
+}
+
+/**
+ * Directories from `PATH` that are plausibly an installation folder. Only names
+ * that mention Sandboxie are considered, so a long `PATH` does not turn into a
+ * long list of candidates.
+ */
+export function pathCandidateDirs(env = process.env) {
+  const raw = envLookup(env, "PATH");
+  if (raw === undefined) return [];
+  const dirs = [];
+  for (const entry of raw.split(";")) {
+    const dir = entry.trim().replace(/^"(.*)"$/s, "$1").trim();
+    if (dir.length === 0) continue;
+    if (!/sbie|sandboxie/i.test(dir)) continue;
+    dirs.push(dir.replace(/[\\/]+$/, ""));
+  }
+  return dirs;
+}
+
+/** Parent folders whose immediate children may be an installation folder. */
+export function scanParentDirs(env = process.env) {
+  const dirs = [];
+  for (const name of ["ProgramFiles", "ProgramFiles(x86)", "ProgramW6432"]) {
+    const base = envLookup(env, name);
+    if (base !== undefined) dirs.push(base);
+  }
+  const localAppData = envLookup(env, "LOCALAPPDATA");
+  if (localAppData !== undefined) dirs.push(path.join(localAppData, "Programs"));
+  const systemDrive = envLookup(env, "SystemDrive");
+  if (systemDrive !== undefined) {
+    dirs.push(`${systemDrive}\\`);
+    dirs.push(path.join(systemDrive, "Programs"));
+    dirs.push(path.join(systemDrive, "Apps"));
+  }
+  return dirs;
+}
+
+/**
+ * Roots of the machine's fixed drives, so an installation on `D:` is found.
+ *
+ * Only `DRIVE_FIXED` disks are returned: probing a disconnected network drive,
+ * an empty optical drive or a card reader can block for seconds, and Sandboxie
+ * on such a volume is not a case worth that cost.
+ */
+export function fixedDriveRoots() {
+  try {
+    const koffi = loadKoffi();
+    const kernel32 = koffi.load("kernel32.dll");
+    const getLogicalDrives = kernel32.func("GetLogicalDrives", "uint32", []);
+    const getDriveType = kernel32.func("GetDriveTypeW", "uint32", ["str16"]);
+    const mask = getLogicalDrives();
+    const roots = [];
+    for (let index = 0; index < 26; index += 1) {
+      if ((mask & (1 << index)) === 0) continue;
+      const root = `${String.fromCharCode(65 + index)}:\\`;
+      if (getDriveType(root) === DRIVE_FIXED) roots.push(root);
+    }
+    return roots;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Walk the immediate children of `parents` (and of `drives`' roots) for a
+ * directory whose NAME names Sandboxie.
+ *
+ * One level only, and by name only: this is the last resort after the
+ * authoritative sources, so it must be cheap and must never wander into a
+ * user's tree. A directory that matches but holds no `SbieDll.dll` is simply
+ * filtered out by the caller's existence check. Junctions and symlinks count as
+ * directories, so a linked installation is not missed by the name sweep.
+ */
+export function scanSbieDirs(options = {}) {
+  const readdir = options.readdir ?? fs.readdirSync;
+  const parents = [...(options.parents ?? scanParentDirs(options.env)), ...(options.drives ?? [])];
+  const seen = new Set();
+  const found = [];
+  for (const parent of parents) {
+    if (typeof parent !== "string" || parent.length === 0) continue;
+    let entries;
+    try {
+      entries = readdir(parent, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const isDirectory = entry?.isDirectory?.() === true || entry?.isSymbolicLink?.() === true;
+      if (!isDirectory) continue;
+      const name = String(entry.name ?? "");
+      if (!/sandboxie/i.test(name)) continue;
+      const dir = path.join(parent, name);
+      const key = dir.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push(dir);
+    }
+  }
+  return found;
+}
+
+/** De-duplicate candidates case-insensitively, keeping the first occurrence's spelling. */
+export function uniqueDirs(dirs) {
+  const seen = new Set();
+  const unique = [];
+  for (const dir of dirs ?? []) {
+    if (typeof dir !== "string" || dir.length === 0) continue;
+    const key = dir.replace(/[\\/]+$/, "").toLowerCase();
+    if (key.length === 0 || seen.has(key)) continue;
+    seen.add(key);
+    unique.push(dir);
+  }
+  return unique;
+}
+
+/**
+ * Every cheap candidate, in the order they are trusted: the explicit override,
+ * then what Sandboxie's own registry entries say, then the conventional
+ * folders, then `PATH`. The disk scan is deliberately NOT part of this list —
+ * it is expensive and is only reached when nothing here holds `SbieDll.dll`.
+ *
+ * This is the same list `resolveSbieDir` walks (minus the scan), so the
+ * "not installed" message can be built from it and cannot claim to have looked
+ * somewhere the resolver never looks.
+ */
+export function sbieDirCandidates(options = {}) {
+  const env = options.env ?? process.env;
+  const override = typeof env?.DSH_SBIE_DIR === "string" && env.DSH_SBIE_DIR.length > 0 ? [env.DSH_SBIE_DIR] : [];
+  const registryValues = options.registryValues ?? readSbieRegistryValues();
+  return uniqueDirs([
+    ...override,
+    ...registryCandidateDirs(registryValues, env),
+    ...defaultSbieDirs(env),
+    ...pathCandidateDirs(env)
+  ]);
+}
+
+/**
+ * The installation folder, with the reason it was chosen.
+ *
+ * @param options.env - environment (default `process.env`).
+ * @param options.exists - existence probe (default `fs.existsSync`).
+ * @param options.registryValues - registry values to trust, when the caller has
+ *   them; the real registry is read only when this is omitted.
+ * @param options.readdir / options.parents / options.drives - the disk scan's
+ *   inputs, injectable so the whole resolver is testable off-Windows.
+ * @param options.scan - `false` disables the last-resort scan.
+ * @returns `{dir, source}` or `undefined`.
+ */
+export function resolveSbieDir(options = {}) {
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? fs.existsSync;
+  const hasDll = (dir) => {
+    try {
+      return exists(path.join(dir, SBIE_DLL)) === true;
+    } catch {
+      return false;
+    }
+  };
+
+  const override = typeof env?.DSH_SBIE_DIR === "string" && env.DSH_SBIE_DIR.length > 0 ? env.DSH_SBIE_DIR : undefined;
+  if (override !== undefined && hasDll(override)) return { dir: override, source: "DSH_SBIE_DIR" };
+
+  const registryValues = options.registryValues ?? readSbieRegistryValues();
+  for (const dir of registryCandidateDirs(registryValues, env)) {
+    if (hasDll(dir)) return { dir, source: "registry" };
+  }
+  for (const dir of defaultSbieDirs(env)) {
+    if (hasDll(dir)) return { dir, source: "default-folder" };
+  }
+  for (const dir of pathCandidateDirs(env)) {
+    if (hasDll(dir)) return { dir, source: "PATH" };
+  }
+
+  if (options.scan === false) return undefined;
+  const drives = options.drives ?? fixedDriveRoots();
+  for (const dir of scanSbieDirs({ ...options, env, drives })) {
+    if (hasDll(dir)) return { dir, source: "disk-scan" };
+  }
+  return undefined;
+}

package/lib/sbie.mjs

@@ -16,29 +16,62 @@
  *   Writing that file directly would need an administrator token.
  */
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 import { loadKoffi } from "./koffi.mjs";
+import { SBIE_DLL, resolveSbieDir, sbieDirCandidates } from "./sbie-locate.mjs";
 
-export const SBIE_DIR_CANDIDATES = [
-  process.env.DSH_SBIE_DIR,
-  process.env.ProgramFiles && path.join(process.env.ProgramFiles, "Sandboxie-Plus"),
-  process.env["ProgramFiles(x86)"] && path.join(process.env["ProgramFiles(x86)"], "Sandboxie-Plus"),
-  process.env.ProgramW6432 && path.join(process.env.ProgramW6432, "Sandboxie-Plus"),
-  "C:\\Program Files\\Sandboxie-Plus"
-].filter((value) => typeof value === "string" && value.length > 0);
+/**
+ * The resolver behind `sbieDir()`: `lib/sbie-locate.mjs` reads Sandboxie's own
+ * registry entries (the `SbieSvc` service's `ImagePath` above all), then the
+ * conventional folders, then `PATH`, and finally walks well-known parent
+ * folders and fixed-drive roots for a directory named after Sandboxie. A fixed
+ * four-path list used to live here, which reported "not installed" on every
+ * machine whose Sandboxie is not in `%ProgramFiles%\Sandboxie-Plus`.
+ *
+ * The result is memoized per process because `sbieExe()` resolves for every
+ * call; the launcher is a fresh process per command, so a Sandboxie installed
+ * while the host runs is picked up on the next command either way.
+ */
+let resolved;
 
-/** The Sandboxie installation directory, or undefined when not installed. */
+/** The Sandboxie installation directory, or undefined when it cannot be found. */
 export function sbieDir() {
-  for (const dir of SBIE_DIR_CANDIDATES) {
-    if (fs.existsSync(path.join(dir, "SbieDll.dll"))) return dir;
-  }
-  return undefined;
+  if (resolved === undefined) resolved = resolveSbieDir() ?? null;
+  return resolved === null ? undefined : resolved.dir;
+}
+
+/** How the installation directory was found (`"registry"`, `"disk-scan"`, …). `undefined` when it was not. */
+export function sbieDirSource() {
+  sbieDir();
+  return resolved === null ? undefined : resolved.source;
+}
+
+/** Forget the memoized lookup. For tests and for diagnostics. */
+export function resetSbieDirCache() {
+  resolved = undefined;
+}
+
+/**
+ * The one "not installed" error, naming what can be done about it.
+ *
+ * A fixed candidate list used to be the whole story, so the message could just
+ * say "not found". Now the search is broad, and the remaining case — a truly
+ * unusual installation, or one the machine's own registry does not describe —
+ * needs the escape hatch named in the message itself, because the user who hits
+ * it has no other way to learn it exists.
+ */
+export function sbieNotInstalledError() {
+  const tried = sbieDirCandidates();
+  const shown = tried.slice(0, 6).join(", ");
+  const more = tried.length > 6 ? `, … (${tried.length - 6} more)` : "";
+  return new Error(
+    `Sandboxie-Plus is not installed (${SBIE_DLL} not found). Searched the service and uninstall registry entries, ${shown}${more}, and the fixed drives' Sandboxie folders. Set DSH_SBIE_DIR to the folder containing ${SBIE_DLL} if Sandboxie lives somewhere unusual.`
+  );
 }
 
 export function sbieExe(name) {
   const dir = sbieDir();
-  if (dir === undefined) throw new Error("Sandboxie-Plus is not installed (SbieDll.dll not found)");
+  if (dir === undefined) throw sbieNotInstalledError();
   return path.join(dir, name);
 }
 
@@ -63,7 +96,7 @@ let api;
 export function sbieApi() {
   if (api !== undefined) return api;
   const dir = sbieDir();
-  if (dir === undefined) throw new Error("Sandboxie-Plus is not installed (SbieDll.dll not found)");
+  if (dir === undefined) throw sbieNotInstalledError();
   const koffi = loadKoffi();
   const kernel32 = koffi.load("kernel32.dll");
   const dll = koffi.load(path.join(dir, "SbieDll.dll"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lone-wolf-akela/dsh-sandboxie-redirect",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "DSH bundle adding a copy-on-write permission preset: shell commands run inside a per-workspace Sandboxie box, so writes outside the workspace land in the box's copy while the real disk is untouched.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "dsh-sbie-run": "./bin/dsh-sbie-run.mjs"
+    "dsh-sbie-run": "bin/dsh-sbie-run.mjs"
   },
   "files": [
     "lib",
@@ -76,9 +76,10 @@
     }
   },
   "scripts": {
-    "test": "node test/unit.mjs && node test/host-projection.mjs && node test/validate-patch.mjs",
+    "test": "node test/unit.mjs && node test/sbie-locate.mjs && node test/dsh-locate.mjs && node test/host-projection.mjs && node test/validate-patch.mjs",
     "test:acceptance": "node test/run-tests.mjs",
     "test:soak": "node test/soak.mjs 30",
+    "test:locate": "node test/sbie-locate.mjs && node test/dsh-locate.mjs",
     "validate:patch": "node test/validate-patch.mjs",
     "pack:check": "npm pack --dry-run"
   },