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

package/lib/naming.mjs

@@ -0,0 +1,159 @@
+/**
+ * Pure naming/geometry helpers. Deliberately free of koffi and of any DSH core
+ * import, so the harness host process can load this module safely (the host
+ * must not pull the FFI binding in just to render a system-prompt line).
+ *
+ * Box names are Docker-style word pairs derived deterministically from the
+ * workspace, so every consumer — the launcher, `--manage`, and the UI — derives
+ * the same name with no shared state file:
+ *
+ *   workspace-write / copy-on-write -> `dsh_<adjective>_<noun>`
+ *   read-only                       -> `dshr_<adjective>_<noun>`
+ *
+ * `boxNameCandidates()` walks a deterministic sequence so a collision between
+ * two workspaces resolves to the next pair instead of either sharing a box or
+ * falling back to hex.
+ */
+import path from "node:path";
+import { ADJECTIVES, NOUNS } from "./words.mjs";
+
+/** Canonical form of a workspace path used for hashing (no trailing separator). */
+export function canonicalWorkspace(workspace) {
+  let resolved = path.resolve(workspace);
+  if (resolved.length > 3 && resolved.endsWith(path.sep)) resolved = resolved.slice(0, -1);
+  return resolved;
+}
+
+/** 64-bit FNV-1a over the UTF-8 bytes of `text`. Same algorithm in host and browser. */
+export function fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= BigInt(text.charCodeAt(index));
+    hash = (hash * prime) & mask;
+  }
+  return hash;
+}
+
+/** The box-name prefix that encodes the workspace-access mode. */
+export function boxPrefix(mode) {
+  return mode === "read-only" ? "dshr" : "dsh";
+}
+
+function wordsFor(key, nonce) {
+  const hash = fnv1a64(nonce === 0 ? key : `${key}#${nonce}`);
+  const adjective = ADJECTIVES[Number(hash % BigInt(ADJECTIVES.length))];
+  const noun = NOUNS[Number((hash / BigInt(ADJECTIVES.length)) % BigInt(NOUNS.length))];
+  return `${adjective}_${noun}`;
+}
+
+/** The first-choice box name (no collision handling): `dsh_brisk_otter`. */
+export function boxNameFor(workspace, mode) {
+  return `${boxPrefix(mode)}_${wordsFor(`${mode === "read-only" ? "ro" : "rw"}:${canonicalWorkspace(workspace).toLowerCase()}`, 0)}`;
+}
+
+/** The deterministic fallback sequence for one workspace, first choice first. */
+export function boxNameCandidates(workspace, mode, count = 8) {
+  const key = `${mode === "read-only" ? "ro" : "rw"}:${canonicalWorkspace(workspace).toLowerCase()}`;
+  const prefix = boxPrefix(mode);
+  const names = [];
+  for (let nonce = 0; nonce < count; nonce += 1) {
+    const name = `${prefix}_${wordsFor(key, nonce)}`;
+    if (!names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Whether a box name is one this plugin manages — including the legacy
+ * `Dsh_<8 hex>` scheme, so boxes created before the word naming stay visible
+ * and cleanable in `--manage`.
+ */
+export function isManagedBoxName(name) {
+  return /^dshr?_[a-z]+_[a-z]+$/.test(name) || /^Dshr?_[0-9a-f]{8}$/.test(name);
+}
+
+/** Sandboxie's default sandbox root — the PARENT of every box directory. */
+export function defaultSandboxRoot(env = process.env) {
+  return path.join(env.SystemDrive ?? "C:", "Sandbox", env.USERNAME ?? "user");
+}
+
+/**
+ * Expand a Sandboxie `FileRootPath` into one box's own directory, for example
+ * `C:\Sandbox\%USER%\%SANDBOX%` → `C:\Sandbox\<user>\dsh_able_willow`.
+ *
+ * The setting names the BOX's folder, `%SANDBOX%` included, and that is why a
+ * template WITHOUT that placeholder is refused instead of followed: every box
+ * would resolve to one shared directory, and that directory is what `--manage`
+ * deletes. Returning `null` keeps the caller on the default layout — a wrong
+ * path costs a missed cleanup, never a deletion of the wrong tree.
+ *
+ * Also `null` for an empty template, an unknown placeholder (`%SID%`, …), a
+ * placeholder whose environment value is missing, or a relative result.
+ */
+export function expandFileRootPath(template, options = {}) {
+  const env = options.env ?? process.env;
+  const box = options.box;
+  if (typeof template !== "string" || template.trim().length === 0) return null;
+  if (typeof box !== "string" || box.length === 0) return null;
+  if (!template.toLowerCase().includes("%sandbox%")) return null;
+
+  const user = env.USERNAME ?? "user";
+  const values = {
+    "%USER%": user,
+    "%SANDBOX%": box,
+    "%SYSTEMDRIVE%": env.SystemDrive ?? "C:",
+    "%USERPROFILE%": env.USERPROFILE ?? path.join(env.SystemDrive ?? "C:", "Users", user),
+    "%WINDIR%": env.WINDIR ?? path.join(env.SystemDrive ?? "C:", "Windows")
+  };
+
+  let expanded = template.trim();
+  for (const [token, value] of Object.entries(values)) {
+    if (!expanded.toLowerCase().includes(token.toLowerCase())) continue;
+    if (value.length === 0) return null;
+    expanded = expanded.replace(new RegExp(token, "gi"), value);
+  }
+
+  // Any surviving placeholder belongs to Sandboxie's wider set (%SID%, %APPDATA%, …).
+  if (/%[A-Za-z_]+%/.test(expanded)) return null;
+  const resolved = path.normalize(expanded);
+  return path.isAbsolute(resolved) ? resolved : null;
+}
+
+/**
+ * The directory one box's copy lives in, in order: `DSH_SBIE_ROOT\<box>`, the
+ * expanded `FileRootPath`, the default layout's `<sandbox root>\<box>`.
+ *
+ * @param box - the box name.
+ * @param options.template - Sandboxie's `FileRootPath` for that box, when known.
+ */
+export function resolveBoxRoot(box, options = {}) {
+  const env = options.env ?? process.env;
+  const override = env.DSH_SBIE_ROOT;
+  if (typeof override === "string" && override.trim().length > 0) return path.join(path.resolve(override.trim()), box);
+  return expandFileRootPath(options.template, { box, env }) ?? path.join(defaultSandboxRoot(env), box);
+}
+
+/**
+ * The sandbox root for this machine as far as a caller with no access to
+ * Sandboxie's configuration can tell: the override, else the default layout.
+ */
+export function sbieSandboxRoot(env = process.env) {
+  const override = env.DSH_SBIE_ROOT;
+  if (typeof override === "string" && override.trim().length > 0) return path.resolve(override.trim());
+  return defaultSandboxRoot(env);
+}
+
+/**
+ * Where Sandboxie keeps a box's redirected (copy-on-write) tree.
+ *
+ * @param box - the box name.
+ * @param root - an already-resolved sandbox ROOT (the parent), for callers that
+ *   read Sandboxie's configuration themselves; defaults to
+ *   {@link sbieSandboxRoot}. Callers holding a `FileRootPath` want
+ *   {@link resolveBoxRoot} instead — that setting is the box directory itself.
+ */
+export function boxRoot(box, root) {
+  return path.join(root ?? sbieSandboxRoot(), box);
+}

package/lib/note.mjs

@@ -0,0 +1,43 @@
+/**
+ * Model-facing note for copy-on-write sessions.
+ *
+ * The stock policy line (`sandbox:policy`, rendered by `dsh-sandbox-policy`)
+ * describes the resolved MODE, which for this preset is truthfully
+ * `workspace-write`. What it cannot say is that shell commands additionally run
+ * inside a Sandboxie box whose out-of-workspace writes are redirected. This
+ * plugin contributes exactly that sentence, and nothing when the preset is not
+ * selected.
+ *
+ * No harness import is needed: the two services it uses arrive through cordis.
+ */
+import { REDIRECT_PRESET, redirectPolicyNote } from "./redirect.mjs";
+import { rootForBox } from "./host.mjs";
+import { boxNameFor } from "./naming.mjs";
+
+export const name = "dsh-sandboxie-redirect-note";
+export const inject = ["systemPrompt"];
+
+export function apply(ctx) {
+  ctx.inject(["systemPrompt", "sessionProjections"], (scope) => {
+    const noteFor = (session) => {
+      if (session === undefined) return "";
+      try {
+        const state = scope.get("sessionProjections").stateOf(session, "permissions");
+        if (state?.preset !== REDIRECT_PRESET) return "";
+        const cwd = session.header?.cwd;
+        if (typeof cwd !== "string" || cwd.length === 0) return "";
+        // Name the root Sandboxie is actually configured with, not the default
+        // layout: the model is told to trust the env vars over this prose, but
+        // the prose should not contradict them.
+        return redirectPolicyNote(cwd, rootForBox(boxNameFor(cwd, "workspace-write")));
+      } catch {
+        return "";
+      }
+    };
+    scope.systemPrompt.context({
+      name: "sandbox:copy-on-write",
+      order: scope.systemPrompt.getContextOrder("SANDBOX_POLICY") + 1,
+      text: (context) => noteFor(context?.agent?.session)
+    });
+  });
+}

package/lib/protocol.mjs

@@ -0,0 +1,63 @@
+/**
+ * Frame codec for the launcher <-> boxed-relay TCP channel.
+ *
+ * The relay runs *inside* the Sandboxie box, so it cannot be handed the
+ * launcher's stdio handles (SbieSvc creates it, not us — see M0 findings).
+ * A length-prefixed frame stream over a loopback socket is the transport that
+ * survives the box boundary (verified: named pipes do not, TCP loopback does).
+ *
+ * frame := u8 type | u32be length | length bytes
+ */
+
+export const Frame = {
+  HELLO: 1,
+  SPEC: 2,
+  STDIN: 3,
+  STDIN_EOF: 4,
+  STDOUT: 16,
+  STDERR: 17,
+  EXIT: 18,
+  FAIL: 19,
+  READY: 20
+};
+
+export const MAX_FRAME = 8 * 1024 * 1024;
+
+/** Encode one frame. `payload` may be a string (utf8) or a Buffer. */
+export function encodeFrame(type, payload = Buffer.alloc(0)) {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
+  const head = Buffer.allocUnsafe(5);
+  head.writeUInt8(type, 0);
+  head.writeUInt32BE(body.length, 1);
+  return Buffer.concat([head, body]);
+}
+
+/** Encode one frame carrying JSON. */
+export function encodeJsonFrame(type, value) {
+  return encodeFrame(type, JSON.stringify(value));
+}
+
+/**
+ * Incremental decoder: feed it socket chunks, receive complete frames.
+ * @param {(type: number, body: Buffer) => void} onFrame
+ * @param {(error: Error) => void} [onError]
+ */
+export function createFrameDecoder(onFrame, onError) {
+  let pending = Buffer.alloc(0);
+  return (chunk) => {
+    pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+    for (;;) {
+      if (pending.length < 5) return;
+      const type = pending.readUInt8(0);
+      const length = pending.readUInt32BE(1);
+      if (length > MAX_FRAME) {
+        onError?.(new Error(`frame too large: ${length}`));
+        return;
+      }
+      if (pending.length < 5 + length) return;
+      const body = pending.subarray(5, 5 + length);
+      pending = pending.subarray(5 + length);
+      onFrame(type, body);
+    }
+  };
+}

package/lib/provider.mjs

@@ -0,0 +1,210 @@
+/**
+ * Shell sandbox provider for DSH: stock behaviour everywhere, Sandboxie
+ * copy-on-write for sessions whose permission preset is `copy-on-write`.
+ *
+ * Why a subclass rather than more `runnerCommand` config: `runnerCommand`
+ * applies to EVERY mode (the seam early-returns as soon as it is set), so a
+ * configured runner cannot leave `read-only` / `workspace-write` on their
+ * original ACL restricted-token path. Overriding `confine` per call does.
+ *
+ * The preset — not the resolved mode — is what distinguishes copy-on-write.
+ * The preset deliberately bundles `sandbox: workspace-write`, so the mode stays
+ * a legal literal: the session projection schema, `SANDBOX_MODES`, the file
+ * fence (`writableRoots`) and the escalation tables are all untouched, and the
+ * model-visible mode string stays truthful for the file tools.
+ *
+ * Failure posture: everything about the preset lookup is best-effort, and any
+ * surprise falls back to `super.confine` (the stock behaviour). Only a failure
+ * to import the harness packages themselves is fatal, and that case still
+ * registers a provider that fails CLOSED instead of running commands
+ * unconfined.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { importCore } from "./core.mjs";
+import { invalidateBoxCache } from "./host.mjs";
+import { logFile } from "./log.mjs";
+import { canonicalWorkspace } from "./naming.mjs";
+import { REDIRECT_PRESET, isRedirectPresetState, redirectWrap, resolveNodePath } from "./redirect.mjs";
+// Imported, not mounted as their own loader rows: see wireCompanions().
+import { apply as applyHostHalf } from "./host.mjs";
+import { apply as applyNote } from "./note.mjs";
+import { apply as applyTool } from "./tool.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const launcherPath = path.resolve(here, "..", "bin", "dsh-sbie-run.mjs");
+// Diagnostics go to the plugin's state directory: an installed bundle lives in
+// the profile's node_modules (pnpm may serve it from its content-addressed
+// store), which is no place to append log lines.
+const LOG = logFile("provider.log");
+
+function log(line) {
+  try {
+    fs.appendFileSync(LOG, `${new Date().toISOString()} ${line}\n`);
+  } catch {}
+}
+
+let Core = null;
+let Base = null;
+let loadError;
+try {
+  Core = await importCore("@deepseek-ai/cordis");
+  Base = (await importCore("@deepseek-ai/dsh-sandbox-local")).default;
+  log(`loaded: cordis=${typeof Core.Service} base=${Base?.name} config=${Base?.Config !== undefined} launcher=${launcherPath}`);
+} catch (error) {
+  loadError = error;
+  log(`LOAD FAILED: ${error?.message ?? error}`);
+}
+
+/**
+ * Mount the rest of the plugin: the header chip's projection, the model-facing
+ * note, and the `sandbox_clear` tool.
+ *
+ * They used to be their own profile rows. They cannot be: the client-modules
+ * registry composes a `dsh.client` package only when exactly ONE of its loader
+ * entries is active, and it fails the whole boot otherwise —
+ *
+ *   client-modules: package dsh-sandboxie-redirect resolves from multiple
+ *   active Loader sources: "…/lib/host.mjs", "…/lib/tool.mjs"; remove one entry
+ *
+ * — with the app offering "disable third-party plugins" as the only way out.
+ * Which entries count depends on activation timing, so several rows into one
+ * package made every start a race. One entry, three imports: no race to lose.
+ *
+ * Each companion is isolated so a failure costs that feature and nothing else.
+ * `note.mjs` and `tool.mjs` inject their own dependencies inside their `apply`,
+ * so handing them this ctx is enough.
+ * @param ctx - the provider's context.
+ */
+function wireCompanions(ctx) {
+  const mount = (label, run) => {
+    try {
+      const result = run(ctx);
+      // tool.mjs's apply is async; a rejection must not become an unhandled one.
+      if (result !== undefined && typeof result.then === "function") {
+        result.then(undefined, (error) => log(`${label} failed: ${error?.stack ?? error}`));
+      }
+      log(`wired ${label}`);
+    } catch (error) {
+      log(`wiring ${label} FAILED: ${error?.stack ?? error}`);
+    }
+  };
+  mount("host half (header chip projection)", applyHostHalf);
+  mount("note (model-facing policy text)", applyNote);
+  mount("tool (sandbox_clear)", applyTool);
+}
+
+/** Last-resort provider: present (so the rest of the profile still loads) but refusing to run anything. */function makeFailClosedProvider(Service) {
+  return class FailClosedSandboxProvider extends Service {
+    constructor(ctx) {
+      super(ctx, "sandbox");
+      log("fail-closed provider constructed");
+      // The companions are pure-JS and do not depend on the harness packages
+      // that just failed to load, so they are still wired: a fail-closed sandbox
+      // must not also take the header chip or `sandbox_clear` down with it.
+      wireCompanions(ctx);
+    }
+    async confine() {
+      const error = new Error(
+        `sandbox: the copy-on-write provider could not load the harness packages (${loadError?.message ?? "unknown error"}); refusing to run the command unconfined. Switch the session to danger-full-access to run without confinement.`
+      );
+      error.code = "SANDBOX_UNAVAILABLE";
+      throw error;
+    }
+  };
+}
+
+function makeRedirectProvider(BaseClass) {
+  return class CopyOnWriteSandboxProvider extends BaseClass {
+    constructor(ctx, config) {
+      super(ctx, config);
+      log(`provider constructed (runnerCommand=${this.runnerCommand === undefined ? "unset" : "SET"})`);
+      // This class is the package's ONLY loader entry, and that is load-bearing.
+      // The client-modules registry refuses to compose a `dsh.client` package
+      // that resolves from more than one ACTIVE loader entry, and which entries
+      // are active depends on activation timing — so several rows pointing into
+      // this package made startup a race that eventually failed outright
+      // ("resolves from multiple active Loader sources; remove one entry").
+      // The other halves are imported modules now, wired here instead of by
+      // their own rows. Each registration is isolated: a broken one costs that
+      // feature, never the profile.
+      wireCompanions(ctx);
+    }
+
+    /**
+     * Whether this call belongs to a copy-on-write session. Any failure to read
+     * the imperative state answers `false`, which routes the call to the stock
+     * path — the safe direction, since the stock path is the original behaviour.
+     *
+     * Two independent readings, because only one of them may exist depending on
+     * load order: the permission service's own derivation (`current(session)`,
+     * which folds the `permission/preset` event and the knob state), and the
+     * raw `permissions` projection.
+     */
+    isCopyOnWrite(policy) {
+      const sessionId = policy?.sessionId;
+      if (sessionId === undefined) return false;
+      try {
+        const sessions = this.ctx.get("sessions");
+        if (sessions === undefined) return false;
+        const session = sessions.list().find((candidate) => String(candidate.id) === String(sessionId));
+        if (session === undefined) return false;
+
+        const presets = this.ctx.get("permissionPresets");
+        if (presets !== undefined && typeof presets.current === "function") {
+          if (presets.current(session) === REDIRECT_PRESET) return true;
+        }
+        const projections = this.ctx.get("sessionProjections");
+        if (projections !== undefined) return isRedirectPresetState(projections.stateOf(session, "permissions"));
+        return false;
+      } catch (error) {
+        log(`preset lookup failed, falling back to stock: ${error?.message ?? error}`);
+        return false;
+      }
+    }
+
+    async confine(argv, policy, signal) {
+      signal?.throwIfAborted();
+      if (!this.isCopyOnWrite(policy)) {
+        if (!this.loggedStock) {
+          this.loggedStock = true;
+          log(`stock path in use (mode=${policy?.mode}, sessionId=${policy?.sessionId ?? "none"})`);
+        }
+        return super.confine(argv, policy, signal);
+      }
+      const workspace = canonicalWorkspace(policy.workspaceRoot ?? process.cwd());
+      const nodePath = resolveNodePath();
+      if (nodePath === null) {
+        // No safe fallback exists: `process.execPath` in this host is the
+        // Electron binary, and handing it to the launcher would fail later,
+        // inside the box, where nothing can attribute the failure. Fail here,
+        // loudly, with the one thing the user can act on.
+        const error = new Error(
+          "sandbox: no genuine Node runtime found to run the Sandboxie launcher, so the copy-on-write preset cannot confine this command. Set DSH_SBIE_NODE to a node.exe path, or switch this session to another permission preset."
+        );
+        error.code = "SANDBOX_UNAVAILABLE";
+        log(`redirect refused: ${error.message}`);
+        throw error;
+      }
+      // The launcher may be about to CREATE this workspace's box. The host
+      // half's box lookup memoizes the Sandboxie configuration for a moment,
+      // so a "no box yet" answer cached before this command must not be the one
+      // the post-command event folds — otherwise the header chip would lag
+      // behind the box by up to the memo window. Same module instance, so this
+      // clears the cache the projection reads.
+      try {
+        invalidateBoxCache();
+      } catch {
+        /* a stale cache costs a delayed chip, never a broken command */
+      }
+      log(`redirect: node=${nodePath} workspace=${workspace} argv0=${argv[0]}`);
+      return redirectWrap({ nodePath, launcherPath, workspace, argv });
+    }
+  };
+}
+
+const Exported = Base === null ? makeFailClosedProvider(Core.Service) : makeRedirectProvider(Base);
+log(`exporting ${Exported.name}`);
+export default Exported;
+export { REDIRECT_PRESET, launcherPath };

package/lib/redirect.mjs

@@ -0,0 +1,167 @@
+/**
+ * The copy-on-write preset, as pure values and functions.
+ *
+ * No core import, no koffi: this module is unit-testable with plain Node and is
+ * the single source of truth for the preset id, the redirect argv shape, the
+ * node-path search, and the model-facing explanation.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { boxNameFor, boxRoot, canonicalWorkspace } from "./naming.mjs";
+
+/**
+ * The preset id that selects copy-on-write. It is written into the session log
+ * (`permission/preset` events and the `permissions` projection), so it is a
+ * compatibility surface: renaming it later makes existing sessions fall back to
+ * `custom` instead of matching.
+ */
+export const REDIRECT_PRESET = "copy-on-write";
+
+/** Signatures this runner's own failures speak (must match the profile's runnerFailureSignatures). */
+export const RUNNER_FATAL_SIGNATURE = "dsh-sbie-run: ";
+
+/**
+ * Whether a session's folded `permissions` state selects copy-on-write.
+ * Anything other than an exact preset match is NOT copy-on-write, so every
+ * unexpected shape fails back to the stock workspace-write behaviour.
+ */
+export function isRedirectPresetState(state) {
+  return state?.preset === REDIRECT_PRESET;
+}
+
+/**
+ * Every place a genuine `node.exe` may live, most specific first.
+ *
+ * `process.execPath` is deliberately NOT a candidate while the host is
+ * Electron: there it is the Electron binary, and starting the launcher with it
+ * would put the native Sandboxie work back into an Electron process — the very
+ * thing this design avoids. Under a plain-Node host (the source-execution path)
+ * it IS a genuine node and is used.
+ *
+ * Order matters. The desktop app ships its own Node under its `resources`
+ * directory, which is user-relocatable and therefore only reachable through
+ * `process.resourcesPath`. The managed-runtime pool under the DSH home comes
+ * second, because this build provisions it lazily, only when something asks for
+ * it — a fresh machine may not have it yet.
+ */
+export function nodeCandidates(options = {}) {
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? fs.existsSync;
+  const found = [];
+  const push = (candidate) => {
+    if (typeof candidate !== "string" || candidate.length === 0) return;
+    if (found.includes(candidate)) return;
+    try {
+      if (exists(candidate)) found.push(candidate);
+    } catch {
+      /* an unreadable candidate is simply not a candidate */
+    }
+  };
+
+  push(env.DSH_SBIE_NODE);
+
+  const resources = typeof options.resourcesPath === "string"
+    ? options.resourcesPath
+    : (typeof process.resourcesPath === "string" ? process.resourcesPath : undefined);
+  if (resources !== undefined) {
+    push(path.join(resources, "runtime", "primary-runtime", "dependencies", "node", "bin", "node.exe"));
+  }
+
+  const home = options.homeDir ?? os.homedir();
+  const dshHome = typeof env.DSH_HOME === "string" && env.DSH_HOME.length > 0 ? env.DSH_HOME : path.join(home, ".dsh");
+  const runtimes = path.join(dshHome, "dsh-runtimes");
+  let entries = [];
+  try {
+    entries = fs.readdirSync(runtimes);
+  } catch {
+    /* no runtime pool on this machine (yet) */
+  }
+  for (const entry of entries) {
+    push(path.join(runtimes, entry, "dependencies", "node", "bin", "node.exe"));
+  }
+
+  const electron = options.isElectron ?? (typeof process.versions?.electron === "string");
+  if (electron === false) push(options.execPath ?? process.execPath);
+
+  return found;
+}
+
+/**
+ * The one node to run the launcher with, or `null` when this machine offers
+ * none.
+ *
+ * `null` is a hard failure and the caller has to say so: there is NO safe
+ * fallback. An Electron binary is not a Node, and using it silently would fail
+ * later, inside the box, in a way nobody can attribute.
+ */
+export function resolveNodePath(options = {}) {
+  return nodeCandidates(options)[0] ?? null;
+}
+
+/**
+ * The redirect invocation DSH hands to the sandbox provider.
+ *
+ * Explicit flags rather than the bubblewrap dialect: the launcher then reads
+ * the workspace and the mode directly instead of inferring them from
+ * `--bind <ws> <ws>`.
+ */
+export function redirectArgv(request) {
+  const workspace = canonicalWorkspace(request.workspace);
+  return [
+    request.nodePath,
+    request.launcherPath,
+    "--workspace",
+    workspace,
+    "--mode",
+    "workspace-write",
+    "--",
+    ...request.argv
+  ];
+}
+
+/** The copy-on-write redirect facts reported to the sandbox seam. */
+export function redirectWrap(request) {
+  return {
+    argv: redirectArgv(request),
+    enforcement: "full",
+    denialSignatures: ["read-only file system", "permission denied"],
+    runnerFailureRules: [{ fatalSignatures: [RUNNER_FATAL_SIGNATURE] }]
+  };
+}
+
+/**
+ * The model-facing explanation for a copy-on-write session.
+ *
+ * This is the ONLY channel that reaches a future agent automatically: it is
+ * contributed as a per-session system-prompt context, so it is present on every
+ * request while the preset is selected and absent otherwise. It carries the
+ * operating rules an agent cannot infer from the sandbox's behaviour — the
+ * ones that otherwise cost a hung command or a wrong conclusion about whether
+ * the real disk changed. Full detail (and the reasoning) lives in README.zh.md.
+ *
+ * @param cwd - the session workspace; the box root shown to the model is derived from it.
+ * @param root - the copy root, when the caller could read Sandboxie's configured
+ *   sandbox folder; omitted, the default layout is named instead.
+ */
+export function redirectPolicyNote(cwd, root) {
+  const workspace = canonicalWorkspace(cwd ?? process.cwd());
+  const copyRoot = typeof root === "string" && root.length > 0 ? root : boxRoot(boxNameFor(workspace, "workspace-write"));
+  return [
+    "This session's file policy is copy-on-write (copy-on-write preset) for shell commands:",
+    `- Writes under the workspace (${JSON.stringify(workspace)}) go to the real disk as usual.`,
+    `- Writes, edits and deletes ANYWHERE ELSE still succeed, but only inside this workspace's Sandboxie copy at ${JSON.stringify(copyRoot)}; the real files outside the workspace are not touched.`,
+    "- Deletions outside the workspace leave the real file in place and only record a tombstone in that copy.",
+    "",
+    "Operating rules for this mode:",
+    "- Reading back an out-of-workspace write: read it WITH A SHELL COMMAND (the sandbox merges the copy for you). The harness read/write/edit file tools run OUTSIDE the sandbox, so they see the real disk and still refuse writes outside the workspace. Never conclude \"the write did not happen\" from a host-side read tool — and never conclude \"it leaked to the real disk\" from a shell `Test-Path`, which sees the merged view. Host tools see reality; shell commands see the copy.",
+    "- The box name and root are resolved against Sandboxie's own state (a name already owned by another workspace steps to the next candidate), so do NOT derive them from the workspace path. Inside a command, `$env:DSH_SBIE_BOX` and `$env:DSH_SANDBOX_ROOT` are authoritative.",
+    "- Escalation (`sandbox_permissions` together with `justification`) runs ONE call entirely OUTSIDE the box, against the real disk; the next call is back in the box.",
+    `- That parameter's own description — \"the narrowest wider sandbox mode for a one-shot retry of the exact command the sandbox just denied\" — is written for the ACL presets (read-only / workspace-write), where a denial comes first. Under copy-on-write nothing outside the workspace is ever denied: the write succeeds into the copy, no \`[sandbox: file access denied under … mode]\` marker appears, and there is no denied command to retry. So do not wait for such a marker before escalating, and do not read the absence of one as \"the real disk was written\". Choose escalation deliberately: it is the lever for a call that must genuinely act on the real disk (installing or configuring something outside the workspace, or replacing a stale copy with reality), it is never a way to make a single file real, and it is not needed to READ the real disk — the host-side file tools already read it.`,
+    "- The same redirection silently captures anything you INSTALL or CONFIGURE outside the workspace from a command — a plugin under `~/.dsh/plugins`, a profile file, any config edit. The write reports success, lands in the copy, and an in-box read-back confirms it, so the real file keeps its old contents while every check you can run from inside the box says otherwise. Judge such a change with a HOST-SIDE read, or make it through escalation; `tools/install.mjs` refuses to run inside a box for exactly this reason.",
+    "- Inside a command, never enumerate or walk `C:\\Sandbox\\`: that is the box's own storage, and walking it recurses into the redirection layer and hangs. Inspect the copy with host-side tools instead.",
+    "- `--manage` and any nested launch of `bin/dsh-sbie-run.mjs` need Sandboxie's API, and Sandboxie hides the box list from a process that is itself inside a box. Run those from a `danger-full-access` session (or a plain console), not from a shell command here.",
+    "",
+    "- The copy is not auto-recovered. It can be inspected, recovered or discarded from the Sandboxie SandMan window, or removed with `--manage clean`."
+  ].join("\n");
+}