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

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 Notable changes per release. The format is loose; the version numbers are what
 the DSH compatibility gate reads.
 
+## 0.3.3 — 2026-10-13
+
+**`sandbox_clear` mode `status` never worked**
+
+- `execute` referenced `workspace` in the `status` early return while the
+  `const workspace = …` that names it was declared below, in the same function
+  body. A `const` in its temporal dead zone throws on *any* earlier reference, so
+  `mode: "status"` failed on every call with `ReferenceError: Cannot access
+  'workspace' before initialization`. The declaration now precedes every use,
+  which is also what `status` was always meant to report: the canonical workspace
+  alongside the projection registry's state for the calling session.
+- The defect came in with the 0.2.1 import, so it shipped in 0.3.0, 0.3.1 and
+  0.3.2; `inspect` and `clear` were unaffected, because they use `workspace`
+  after the declaration.
+- New `test/tool-execute.mjs` drives all three modes of the real tool offline
+  (only the harness loader, the Node lookup and `spawnSync` are redirected), so
+  this — and any future runtime failure in a mode nobody exercises by hand — is a
+  failed test rather than a report from a user. It reproduces the
+  `ReferenceError` on the pre-fix source.
+
+## 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**

package/README.md

@@ -42,6 +42,8 @@ A [DSH](https://github.com/deepseek-ai/deepseek-harness) bundle that adds a four
 
 **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
@@ -92,7 +94,7 @@ The preset carries an icon (two overlapping sheets) in the dropdown and the bott
 
 ### The `sandbox_clear` tool
 
-In-session, `sandbox_clear` inspects or discards this workspace's copy: `mode: "inspect"` reports (file count, size), `mode: "clear"` deletes the copy and its configuration. It works in every permission mode, and can only ever touch boxes Sandboxie attributes to *this* workspace.
+In-session, `sandbox_clear` inspects or discards this workspace's copy: `mode: "inspect"` reports (file count, size), `mode: "clear"` deletes the copy and its configuration. It works in every permission mode, and can only ever touch boxes Sandboxie attributes to *this* workspace. A diagnostic `mode: "status"` reports what the session projection registry holds for the calling session — it separates "the fold never ran" from "the client never got it", so it is the first thing to look at when the title-bar box name is missing (it only actually worked from 0.3.3 on).
 
 ## Notes for users
 
@@ -130,7 +132,7 @@ All optional; each exists as an escape hatch rather than a configuration surface
 | `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.

package/README.zh.md

@@ -41,6 +41,8 @@
 
 **装在哪儿都行，不需要配置。** 插件不假设 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
@@ -91,7 +93,7 @@ DSH 的文件工具（读/写/编辑）在盒外运行，仍按「仅工作区
 
 ### sandbox_clear 工具
 
-会话内可用 `sandbox_clear` 查看或清除本工作区的副本：`mode: "inspect"` 仅查看（文件数、占用），`mode: "clear"` 删除副本与配置。任何权限模式下都可用，且只能操作 Sandboxie 认定属于**本工作区**的沙盒。
+会话内可用 `sandbox_clear` 查看或清除本工作区的副本：`mode: "inspect"` 仅查看（文件数、占用），`mode: "clear"` 删除副本与配置。任何权限模式下都可用，且只能操作 Sandboxie 认定属于**本工作区**的沙盒。另有诊断用的 `mode: "status"`：它报告本会话投影登记的状态，用来分辨"投影没被驱动"和"客户端没收到"——标题栏的沙箱名称不显示时先看它（0.3.3 起才真正可用）。
 
 ## 用户注意事项
 
@@ -129,7 +131,7 @@ node bin\dsh-sbie-run.mjs --manage delete-box <沙盒名>      # 删除指定沙
 | `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，只记状态迁移。

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/tool.mjs

@@ -220,6 +220,13 @@ export async function apply(ctx) {
           if (typeof cwd !== "string" || cwd.length === 0) {
             throw new Error("sandbox_clear needs the calling session's workspace, and this caller has none");
           }
+          // Declared before ANY use. It used to sit below the `status` early
+          // return, inside the same function body — a temporal dead zone, so
+          // `mode: "status"` threw `ReferenceError: Cannot access 'workspace'
+          // before initialization` on every single call. test/tool-execute.mjs
+          // drives all three modes, so this class of failure is now a failed
+          // test rather than a bug report from a user.
+          const workspace = naming.canonicalWorkspace(cwd);
           if (args.mode === "status") {
             // Ask the projection registry what it holds for THIS session. The
             // header chip reads that value, so this separates "the fold never
@@ -236,7 +243,8 @@ export async function apply(ctx) {
             }
             log(`status: ${detail}`);
             return Promise.resolve({ action: "status", workspace, copies: [], cleared: [], note: detail });
-          }          const workspace = naming.canonicalWorkspace(cwd);
+          }
+
           const before = copiesFor(host, naming, workspace);
           if (before === null) {
             throw new Error(`cannot read ${host.sandboxIniPath()}, so the sandbox state is unknown; refusing to act`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lone-wolf-akela/dsh-sandboxie-redirect",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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,10 +76,11 @@
     }
   },
   "scripts": {
-    "test": "node test/unit.mjs && node test/sbie-locate.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/tool-execute.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",
+    "test:locate": "node test/sbie-locate.mjs && node test/dsh-locate.mjs",
+    "test:tool": "node test/tool-execute.mjs",
     "validate:patch": "node test/validate-patch.mjs",
     "pack:check": "npm pack --dry-run"
   },