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

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 Notable changes per release. The format is loose; the version numbers are what
 the DSH compatibility gate reads.
 
+## 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,8 @@ 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.
+
 The package is a DSH *bundle*: installing it also adds its configuration layer, so no profile file needs hand-editing.
 
 ```powershell
@@ -50,7 +57,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,6 +125,7 @@ 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`. |
@@ -137,15 +145,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,8 @@
 
 **前置条件**：[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 的 **bundle**（自带配置层），装进去就自动挂载，**不需要手改 profile 文件**。
 
 ```powershell
@@ -49,7 +56,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,6 +124,7 @@ 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`。 |
@@ -136,15 +144,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/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.1",
   "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",
@@ -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/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",
     "validate:patch": "node test/validate-patch.mjs",
     "pack:check": "npm pack --dry-run"
   },