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

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 Notable changes per release. The format is loose; the version numbers are what
 the DSH compatibility gate reads.
 
+## 0.3.5 — 2026-11-14
+
+**Programmatic tool calling + copy-on-write: every command failed**
+
+- PTC spawns its runtime with a deliberately scrubbed environment — only
+  `PATH`, `PATHEXT`, `SYSTEMROOT`, `WINDIR`, `TEMP` and `TMP`. The launcher
+  inherits it, and Sandboxie expands its `ProfileList` values
+  (`%SystemDrive%\ProgramData`, `%SystemDrive%\Users\…`) with
+  `ExpandEnvironmentStrings`, which only sees the *caller's* environment. Without
+  `SystemDrive` the expansion fails, the boxed relay dies during initialization
+  (`SBIE2306 Could not locate user directory: [C000003B / 33]` followed by
+  `SBIE2304`) and the launcher could only report `the boxed relay did not connect
+  within 15000 ms` — so *every* tool call in the session failed, including a
+  program that made none.
+- `lib/sandbox-env.mjs` now restores `SystemDrive` into the launcher's own
+  process environment before the boxed relay is started, deriving it from the
+  caller's environment, from `GetWindowsDirectoryW`, or from Node's own drive —
+  in that order. The command's spawn specification is built from a snapshot taken
+  *before* the restoration, so the boxed command still receives exactly the
+  environment its caller chose; `test/unit.mjs` pins both halves.
+- Reproduced offline by spawning the launcher through `CreateProcessW` with the
+  exact six-variable environment and no `SystemDrive`: the launcher timed out and
+  the boxed `node.exe` reported SBIE2306/SBIE2304. With the fix the same
+  invocation runs the command and returns its exit code.
+
+**PTC runtime: Sandboxie injected browser flags into Electron's Node mode**
+
+- Sandboxie classifies Electron images (DSH's executable included) as Chromium
+  and, for every non-child process of that image, prepends its
+  `CustomChromiumFlags` — by default `--disable-features=PrintCompositorLPAC` —
+  to the command line. The PTC runtime is Electron started with
+  `ELECTRON_RUN_AS_NODE=1`, so Node parses that browser flag as one of its own
+  options and exits 9 with `bad option: --disable-features=PrintCompositorLPAC`
+  before the program's first line runs.
+- Managed boxes now carry `SpecialImage=none,DeepSeek Harness.exe`, which
+  suppresses the classification for DSH's own executable only; other Chromium
+  applications in the same box keep Sandboxie's compatibility flags. Boxes
+  created by older versions are repaired on the next launch.
+- `test/unit.mjs` pins the box setting for both access modes.
+
+**PTC runtime: the inherited control channel never reached the box**
+
+- DSH hands the confined process a control channel on fd 7 (`SUBPROCESS_CONTROL_FD`,
+  an `overlapped` named pipe marked by `DSH_SUBPROCESS_CONTROL=pipe`). SbieSvc
+  ignores inherited handles, so the boxed relay started the command with only
+  stdin/stdout/stderr; the PTC runtime then died at startup with
+  `ERR_INVALID_FD_TYPE: Unsupported fd type: UNKNOWN` from
+  `openInheritedControlChannel()`.
+- The launcher now opens fd 7 itself, forwards its bytes over the relay's TCP
+  channel (new `CONTROL` / `CONTROL_EOF` frames) and the relay re-creates an
+  `overlapped` fd 7 for the boxed child. The command's environment is unchanged.
+- `test/run-tests.mjs` case 21 pins the roundtrip through a real box; case 20
+  remains the scrubbed-environment regression.
+
+## 0.3.4 — 2026-10-13
+
+**`sandbox_clear` mode `status` no longer answers in `inspect`'s words**
+
+- `render` gave every action except `clear` the inspect head line, so a status
+  query read `Sandbox copies for <workspace>: 0 found.` — which looks like "this
+  workspace has no copy" when the call says nothing about copies at all. `status`
+  now has its own head, `Session projection state for <workspace>.`, above the
+  projection detail that actually carries the information.
+- `test/tool-execute.mjs` pins the rendered text of all three actions, plus the
+  empty and truncated copy lines, so the wording cannot silently fall through
+  again.
+
 ## 0.3.3 — 2026-10-13
 
 **`sandbox_clear` mode `status` never worked**

package/lib/boxes.mjs

@@ -22,6 +22,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { DSH_EXE } from "./dsh-locate.mjs";
 import { boxNameCandidates, boxNameFor, boxRoot, canonicalWorkspace, isManagedBoxName, resolveBoxRoot, sbieSandboxRoot } from "./naming.mjs";
 import { boxExists, listBoxNames, queryBoxSetting, reloadConfig, sbieExe, sbieIni, setBoxSetting } from "./sbie.mjs";
 
@@ -69,6 +70,23 @@ export function rootFor(box) {
 /** How many name candidates to try before giving up on a collision. */
 const CANDIDATE_LIMIT = 12;
 
+/**
+ * Sandboxie classifies Electron images — including DSH's own executable — as
+ * Chromium and, for every non-child process of that image, injects its
+ * configured `CustomChromiumFlags` into the command line. The stock default is
+ * `--disable-features=PrintCompositorLPAC`, a browser compatibility flag.
+ *
+ * That is fatal for Electron's Node mode: the PTC runtime is started with
+ * `ELECTRON_RUN_AS_NODE=1`, so Node parses the injected flag as one of its own
+ * CLI options and exits 9 with `bad option: --disable-features=PrintCompositorLPAC`
+ * before the runtime can do anything — every programmatic tool call dies.
+ *
+ * Classifying the DSH executable as `none` in OUR boxes suppresses the
+ * compatibility path for that one image only; other Chromium applications
+ * started in the same box keep Sandboxie's default flags.
+ */
+export const SPECIAL_IMAGE_SETTING = `none,${DSH_EXE}`;
+
 /**
  * The settings a managed box carries. Anything not listed keeps Sandboxie's
  * default, which is "writes are redirected into the box" — the whole point.
@@ -86,7 +104,9 @@ export function boxSettings(workspace, mode) {
     ["AutoRecover", "n"],
     // Headless must never raise a modal "large file" prompt.
     ["CopyLimitKb", "131072"],
-    ["CopyLimitSilent", "y"]
+    ["CopyLimitSilent", "y"],
+    // Keep Sandboxie from injecting Chromium flags into DSH's Electron runtime.
+    ["SpecialImage", SPECIAL_IMAGE_SETTING]
   ];
 }
 
@@ -137,11 +157,21 @@ export function ensureBox(request) {
   const accessRule = `${workspace}\\*`;
 
   if (boxExists(box)) {
+    let changed = false;
     if (!boxOwnedBy(box, workspace, mode)) {
       log(`box ${box}: workspace access rule missing or stale, rewriting`);
       setBoxSetting(box, accessKey, accessRule);
-      reloadConfig();
+      changed = true;
+    }
+    // Boxes created by older plugin versions lack this entry; without it every
+    // PTC program fails before its first line (see SPECIAL_IMAGE_SETTING).
+    const specialImage = queryBoxSetting(box, "SpecialImage");
+    if (specialImage === undefined || !specialImage.toLowerCase().includes(SPECIAL_IMAGE_SETTING.toLowerCase())) {
+      log(`box ${box}: suppressing Chromium classification for ${DSH_EXE}`);
+      setBoxSetting(box, "SpecialImage", SPECIAL_IMAGE_SETTING);
+      changed = true;
     }
+    if (changed) reloadConfig();
     return { box, root, created: false, workspace, mode };
   }
 

package/lib/inner.mjs

@@ -34,6 +34,7 @@ if (!Number.isInteger(options.port) || options.port <= 0) {
 }
 
 let child;
+let control;
 let finished = false;
 
 const socket = net.connect({ host: options.host, port: options.port });
@@ -53,11 +54,22 @@ function finish(code) {
 
 function startChild(spec) {
   let childProcess;
+  // The harness's control channel reaches the launcher on fd 7 (DSH's
+  // SUBPROCESS_CONTROL_FD); SbieSvc cannot pass inherited handles into the box,
+  // so the launcher forwards the bytes and we re-create the same shape here: an
+  // `overlapped` named pipe at fd 7, which the PTC runtime opens with
+  // `net.Socket`. fds 3-6 stay unused (the Windows job runner reserves them),
+  // so the array must be padded rather than compacted.
+  const stdio = ["pipe", "pipe", "pipe"];
+  if (spec.control === true) {
+    while (stdio.length < 7) stdio.push("ignore");
+    stdio.push("overlapped");
+  }
   try {
     childProcess = spawn(spec.argv[0], spec.argv.slice(1), {
       cwd: spec.cwd,
       env: spec.env,
-      stdio: ["pipe", "pipe", "pipe"],
+      stdio,
       windowsHide: true
     });
   } catch (error) {
@@ -67,6 +79,13 @@ function startChild(spec) {
     return;
   }
   child = childProcess;
+  if (spec.control === true && childProcess.stdio[7] !== undefined && childProcess.stdio[7] !== null) {
+    control = childProcess.stdio[7];
+    control.on("data", (chunk) => send(Frame.CONTROL, chunk));
+    control.on("error", () => {
+      /* the launcher may close the channel first; the child's exit still decides */
+    });
+  }
   child.on("error", (error) => {
     send(Frame.FAIL, `cannot spawn ${spec.argv[0]}: ${error.message}`);
     socket.end();
@@ -96,6 +115,12 @@ const decode = createFrameDecoder((type, body) => {
     case Frame.STDIN_EOF:
       if (child !== undefined && child.stdin.writable) child.stdin.end();
       break;
+    case Frame.CONTROL:
+      if (control !== undefined && control.writable) control.write(body);
+      break;
+    case Frame.CONTROL_EOF:
+      if (control !== undefined) control.end();
+      break;
     default:
       break;
   }
@@ -108,6 +133,7 @@ socket.on("error", (error) => {
   finish(127);
 });
 socket.on("close", () => {
+  control?.destroy();
   if (!finished) {
     // The launcher went away (or finished): do not leave the command running.
     child?.kill();

package/lib/protocol.mjs

@@ -14,6 +14,10 @@ export const Frame = {
   SPEC: 2,
   STDIN: 3,
   STDIN_EOF: 4,
+  /** Raw bytes of the harness's inherited control channel, forwarded verbatim. */
+  CONTROL: 5,
+  /** The harness closed its control channel; the child's fd 7 ends. */
+  CONTROL_EOF: 6,
   STDOUT: 16,
   STDERR: 17,
   EXIT: 18,

package/lib/run.mjs

@@ -30,7 +30,8 @@ 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, sbieNotInstalledError } from "./sbie.mjs";
+import { restoreSandboxieEnvironment } from "./sandbox-env.mjs";
+import { runSandboxed, killProcess, sbieDir, sbieNotInstalledError, windowsDirectory } from "./sbie.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const relayScript = path.join(here, "inner.mjs");
@@ -186,6 +187,10 @@ export async function run(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
 
+  // The command keeps exactly the environment its caller chose (DSH trims it
+  // under programmatic tool calling); only Sandboxie's own bootstrap sees the
+  // system identity restored below.
+  const callerEnv = { ...process.env };
   const parsed = parseRunnerArgv(argv);
   const { options, command, workspace, mode } = parsed;
   if (command.length === 0) throw new Error(`no command after "--"\n${usage()}`);
@@ -195,8 +200,10 @@ export async function run(argv, io = {}) {
 
   if (sbieDir() === undefined) throw sbieNotInstalledError();
 
+  restoreSandboxieEnvironment(process.env, { windowsDirectory });
+
   const ensured = ensureBox({ box, workspace, mode, logger: log });
-  const env = { ...process.env, DSH_SANDBOX_ROOT: ensured.root, DSH_SBIE_BOX: ensured.box };
+  const env = { ...callerEnv, DSH_SANDBOX_ROOT: ensured.root, DSH_SBIE_BOX: ensured.box };
 
   if (options.dryRun) {
     stdout.write(
@@ -206,7 +213,11 @@ export async function run(argv, io = {}) {
   }
 
   const channel = await startRelay(ensured, options, log);
-  return await relay({ server: channel.server, socket: channel.socket }, { command, cwd: process.cwd(), env, stdin, stdout, stderr, box: ensured });
+  const control = openControlChannel(log);
+  return await relay(
+    { server: channel.server, socket: channel.socket },
+    { command, cwd: process.cwd(), env, stdin, stdout, stderr, box: ensured, control }
+  );
 }
 
 /**
@@ -259,15 +270,39 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * The harness hands the *launcher* the inherited control channel it would have
+ * handed the command: `DSH_SUBPROCESS_CONTROL=pipe` names an `overlapped`
+ * named pipe on fd 7 (DSH's `SUBPROCESS_CONTROL_FD`; the low fds belong to the
+ * Windows job runner). The boxed command is created by SbieSvc, which ignores
+ * inherited handles, so the bytes are pumped over the relay channel instead and
+ * the relay re-creates the same `overlapped` fd 7 for the child — the PTC
+ * runtime opens exactly that descriptor with `net.Socket`.
+ *
+ * Returns undefined when this launch has no control channel — the normal case
+ * for ordinary shell commands.
+ */
+function openControlChannel(log) {
+  if (process.env.DSH_SUBPROCESS_CONTROL !== "pipe") return undefined;
+  try {
+    const control = new net.Socket({ fd: 7, readable: true, writable: true });
+    return control;
+  } catch (error) {
+    log(`control channel unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    return undefined;
+  }
+}
+
 /** Pump one command's stdio through the channel and settle on its exit code. */
 function relay(channel, session) {
   const { socket, server } = channel;
-  const { stdin, stdout, stderr } = session;
+  const { stdin, stdout, stderr, control } = session;
   return new Promise((resolve, reject) => {
     let settled = false;
     const done = (code) => {
       if (settled) return;
       settled = true;
+      control?.destroy();
       server.close();
       socket.destroy();
       resolve(code);
@@ -275,6 +310,7 @@ function relay(channel, session) {
     const bail = (error) => {
       if (settled) return;
       settled = true;
+      control?.destroy();
       server.close();
       socket.destroy();
       reject(error);
@@ -300,6 +336,9 @@ function relay(channel, session) {
           stderr.write(`dsh-sbie-run: ${body.toString("utf8")}\n`);
           done(127);
           break;
+        case Frame.CONTROL:
+          if (control !== undefined && control.writable) control.write(body);
+          break;
         default:
           break;
       }
@@ -310,7 +349,19 @@ function relay(channel, session) {
       if (!settled) bail(new Error("the boxed relay closed the channel before reporting an exit code"));
     });
 
-    socket.write(encodeJsonFrame(Frame.SPEC, { argv: session.command, cwd: session.cwd, env: session.env }));
+    if (control !== undefined) {
+      control.on("data", (chunk) => {
+        if (!socket.destroyed) socket.write(encodeFrame(Frame.CONTROL, chunk));
+      });
+      control.on("error", () => {
+        /* the harness may close the channel first; the command's exit still settles the call */
+      });
+      control.on("close", () => {
+        if (!socket.destroyed) socket.write(encodeFrame(Frame.CONTROL_EOF));
+      });
+    }
+
+    socket.write(encodeJsonFrame(Frame.SPEC, { argv: session.command, cwd: session.cwd, env: session.env, control: control !== undefined }));
 
     const forward = (chunk) => {
       if (socket.destroyed) return;

package/lib/sandbox-env.mjs

@@ -0,0 +1,88 @@
+/**
+ * Keep Sandboxie able to resolve the user's profile folder when the launcher is
+ * started with a trimmed environment.
+ *
+ * Sandboxie derives the sandbox layout (`user\current`, `ProgramData`, the
+ * public profile, ...) from `HKLM\...\ProfileList`, whose `REG_EXPAND_SZ`
+ * values it expands with `ExpandEnvironmentStrings` — an API that only sees the
+ * *calling process's* environment. DSH's programmatic tool calling deliberately
+ * spawns its runtime with a credential-scrubbed environment that keeps only
+ * PATH, PATHEXT, SYSTEMROOT, WINDIR, TEMP and TMP. `%SystemDrive%\ProgramData`
+ * then cannot be expanded, Sandboxie logs
+ *
+ *   SBIE2306 Could not locate user directory: [C000003B / 33]
+ *   SBIE2304 Initialization of <program> process failed
+ *
+ * and the boxed relay dies during initialization, so the launcher only reports
+ * its connect timeout and every command in the session fails.
+ *
+ * `SystemDrive` is the one missing piece that is a *system* fact rather than a
+ * credential, so the launcher restores it for Sandboxie's bootstrap only. The
+ * command itself still receives exactly the environment its caller passed: the
+ * relay's spawn spec is built before this module touches `process.env`.
+ */
+
+/** `"C:"` / `"c:"` / `"c:\\"` → `"C:"`; anything else → undefined. */
+export function normalizeSystemDrive(value) {
+  if (typeof value !== "string") return undefined;
+  const match = /^\s*([A-Za-z]):\s*$/.exec(value);
+  return match === null ? undefined : `${match[1].toUpperCase()}:`;
+}
+
+/**
+ * Derive the system drive from environment values, a Windows directory path, or
+ * a fallback path, in that order.
+ *
+ * @param env - the environment to read (defaults to the process environment).
+ * @param windowsDirectory - a `C:\Windows`-shaped path, or a function returning
+ *   one (called only when the environment itself has no drive information).
+ */
+export function systemDriveFromEnv(env = process.env, windowsDirectory) {
+  const direct = normalizeSystemDrive(env.SystemDrive ?? env.SYSTEMDRIVE);
+  if (direct !== undefined) return direct;
+
+  const driveOf = (value) => {
+    if (typeof value !== "string") return undefined;
+    const match = /^\s*([A-Za-z]):[\\/]/.exec(value);
+    return match === null ? undefined : `${match[1].toUpperCase()}:`;
+  };
+
+  for (const key of ["SystemRoot", "SYSTEMROOT", "windir", "WINDIR"]) {
+    const drive = driveOf(env[key]);
+    if (drive !== undefined) return drive;
+  }
+
+  if (windowsDirectory !== undefined) {
+    let resolved;
+    try {
+      resolved = typeof windowsDirectory === "function" ? windowsDirectory() : windowsDirectory;
+    } catch {
+      resolved = undefined;
+    }
+    const drive = driveOf(resolved);
+    if (drive !== undefined) return drive;
+  }
+
+  // Last resort: the drive Node itself lives on (a system fact, not a caller
+  // credential) — only reached when even SystemRoot was stripped.
+  return driveOf(process.execPath);
+}
+
+/**
+ * Restore the environment Sandboxie needs to locate the user profile, without
+ * touching the command's own spawn specification.
+ *
+ * @param env - the launcher's process environment (mutated in place; on Windows
+ *   that updates the environment block `SbieSvc` reads for the boxed process).
+ * @param options.windowsDirectory - see {@link systemDriveFromEnv}.
+ * @returns the entries that were added, or undefined when nothing was missing.
+ */
+export function restoreSandboxieEnvironment(env, options = {}) {
+  if (env === undefined) return undefined;
+  if (normalizeSystemDrive(env.SystemDrive ?? env.SYSTEMDRIVE) !== undefined) return undefined;
+
+  const drive = systemDriveFromEnv(env, options.windowsDirectory);
+  if (drive === undefined) return undefined;
+  env.SystemDrive = drive;
+  return { SystemDrive: drive };
+}

package/lib/sbie.mjs

@@ -146,6 +146,7 @@ export function sbieApi() {
     queryBoxPath: dll.func("__stdcall", "SbieApi_QueryBoxPath", "int32", [
       "void *", "void *", "void *", "void *", "void *", "void *", "void *"
     ]),
+    getWindowsDirectory: kernel32.func("GetWindowsDirectoryW", "uint32", ["void *", "uint32"]),
     waitForSingleObject: kernel32.func("WaitForSingleObject", "uint32", ["void *", "uint32"]),
     getExitCodeProcess: kernel32.func("GetExitCodeProcess", "bool", ["void *", koffi.out(koffi.pointer("uint32"))]),
     closeHandle: kernel32.func("CloseHandle", "bool", ["void *"]),
@@ -171,6 +172,27 @@ export function startErrorText() {
   }
 }
 
+/**
+ * The Windows directory (`C:\Windows`) from the Win32 API.
+ *
+ * Used only when the launcher was started without any environment that names
+ * the system drive: Sandboxie expands profile paths like `%SystemDrive%\ProgramData`
+ * with the *caller's* environment, so a scrubbed caller would otherwise fail
+ * with `SBIE2306 ... [C000003B / 33]` before a boxed process can start.
+ */
+export function windowsDirectory() {
+  try {
+    const a = sbieApi();
+    const buffer = Buffer.alloc(520 * 2);
+    const length = a.getWindowsDirectory(buffer, 520);
+    if (typeof length !== "number" || length <= 0) return undefined;
+    const text = buffer.toString("utf16le", 0, length * 2);
+    return text.length > 0 ? text : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Start `commandLine` inside `box` through the Sandboxie service.
  *

package/lib/tool.mjs

@@ -208,10 +208,18 @@ export async function apply(ctx) {
               (copy) =>
                 `- ${copy.box}: ${copy.files} file(s), ${humanBytes(copy.bytes)}${copy.truncated ? " (counting stopped early)" : ""} at ${copy.root}`
             );
-            const head =
-              value.action === "clear"
-                ? `Cleared ${value.cleared.length} sandbox copy/copies for ${value.workspace}.`
-                : `Sandbox copies for ${value.workspace}: ${value.copies.length} found.`;
+            // Every action gets its OWN head line. `status` used to fall through
+            // to the inspect wording, so a status query answered "N found." —
+            // which reads as "this workspace has no copy" when the call says
+            // nothing about copies at all; the informative part is the note.
+            let head;
+            if (value.action === "clear") {
+              head = `Cleared ${value.cleared.length} sandbox copy/copies for ${value.workspace}.`;
+            } else if (value.action === "status") {
+              head = `Session projection state for ${value.workspace}.`;
+            } else {
+              head = `Sandbox copies for ${value.workspace}: ${value.copies.length} found.`;
+            }
             return [{ type: "text", text: [head, ...lines, value.note].join("\n") }];
           }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lone-wolf-akela/dsh-sandboxie-redirect",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",