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

package/lib/core.mjs

@@ -0,0 +1,59 @@
+/**
+ * Reach the DSH core packages from a plugin that lives outside the app bundle.
+ *
+ * Plugins under `$DSH_HOME/plugins` get no module resolution into the harness:
+ * bare specifiers fail (measured). The harness's own modules live inside
+ * `app.asar`, which plain Node cannot read — but the Electron host can, because
+ * Electron patches `fs`. So: resolve from inside the asar with a `createRequire`
+ * rooted at the harness node_modules, then import the resulting file URL.
+ *
+ * Measured working inside the host (Electron 44 / Node 24.18): `resolve`,
+ * `import`, and even `readdirSync` inside `app.asar`.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+
+function resourcesRoot() {
+  if (typeof process.resourcesPath === "string" && process.resourcesPath.length > 0) return process.resourcesPath;
+  return path.join(path.dirname(process.execPath), "resources");
+}
+
+/** Candidate module roots, most specific first. */
+export function coreModuleRoots(resources = resourcesRoot()) {
+  return [
+    path.join(resources, "app.asar", "dsh", "node_modules"),
+    path.join(resources, "app.asar", "node_modules"),
+    path.join(resources, "app.asar.unpacked", "dsh", "node_modules")
+  ].filter((dir) => {
+    try {
+      return fs.statSync(dir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+const cache = new Map();
+
+/**
+ * Import one harness package by name from inside the app bundle.
+ * @param specifier - a bare package name (or subpath export) the harness ships.
+ */
+export async function importCore(specifier) {
+  const cached = cache.get(specifier);
+  if (cached !== undefined) return cached;
+  const failures = [];
+  for (const root of coreModuleRoots()) {
+    try {
+      const resolved = createRequire(path.join(root, "noop.js")).resolve(specifier);
+      const module = await import(pathToFileURL(resolved).href);
+      cache.set(specifier, module);
+      return module;
+    } catch (error) {
+      failures.push(`${root}: ${error?.code ?? ""} ${error?.message ?? error}`);
+    }
+  }
+  throw new Error(`cannot resolve harness package ${specifier} from ${resourcesRoot()} (${failures.join(" | ")})`);
+}

package/lib/host.mjs

@@ -0,0 +1,356 @@
+/**
+ * Host half of the "which sandbox is this conversation bound to?" surface.
+ *
+ * The browser half cannot derive the box name: it has no session→workspace
+ * path in any of its snapshots. So this half publishes one tiny session
+ * projection whose client view carries the name and root, and the browser
+ * reads it with the standard `useProjection` hook — no bespoke RPC.
+ *
+ * WHAT IT REPORTS — and why it is not simply the workspace's name:
+ *
+ * The name is only knowable once the box EXISTS. Collisions are resolved by
+ * walking `boxNameCandidates()` against Sandboxie's own state, so which of the
+ * candidates a workspace ends up owning cannot be decided from the path alone;
+ * and before the first copy-on-write command there is no box at all. Reporting
+ * a guess would put a name in the header that may never be used — worse than
+ * showing nothing, because the whole point of the chip is to say whether a
+ * sandbox is in play and which one it is.
+ *
+ * So the projection reports nothing until this workspace actually owns a box,
+ * and it re-checks on the session's own event drive: every committed event
+ * (the tool call and its result included) folds through `apply`, and returning
+ * a NEW state reference is what makes the harness recompute the client view.
+ * That is how the chip appears right after the first copy-on-write command —
+ * with no polling, and without writing anything into the log.
+ *
+ * THE ONE HARD RULE FOR THIS FILE: never call `session.append()`.
+ *
+ * An earlier version appended a per-session `sandbox/box` event. That is a hard
+ * error, not a style choice: the persistence read path refuses a stored event
+ * whose type this build does not know unless the envelope carries
+ * `ignorable: true`, and live `Session.append()` cannot set that marker — so
+ * every session this plugin touched failed to reload ("contains event type ...
+ * unknown to this harness and not marked ignorable"). The harness's own plugin
+ * practices say the same: "Do not append session events with a new `type`. …
+ * Derive state from existing events, or keep plugin-owned data in a storage
+ * service." Logs written by that version were repaired in place (see
+ * `tools/stamp-ignorable.mjs`) and still fold through the legacy branch below.
+ *
+ * Everything here is best-effort: a failure costs the header chip, never the
+ * sandbox itself, so nothing is allowed to throw.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { boxNameCandidates, boxNameFor, canonicalWorkspace, resolveBoxRoot } from "./naming.mjs";
+import { importCore } from "./core.mjs";
+import { logFile } from "./log.mjs";
+
+export const name = "dsh-sandboxie-redirect-host";
+export const inject = ["sessionProjections"];
+
+/** Projection key the browser half reads. */
+export const BOX_PROJECTION = "sandboxBox";
+/**
+ * The retired event type. Never appended — recognized only so logs written by
+ * the version that did append it keep folding to the box they recorded.
+ */
+export const LEGACY_BOX_EVENT = "sandbox/box";
+
+/** How many name candidates to consider, matching the launcher's resolution. */
+const CANDIDATE_LIMIT = 12;
+/** Re-reading the configuration file on every event would be rude; this is a hint, not an audit. */
+const INI_MEMO_MS = 1500;
+
+function report(line) {
+  try {
+    process.stderr.write(`dsh-sandboxie-redirect: ${line}\n`);
+  } catch {}
+}
+
+/**
+ * Diagnostics go to a file as well as to stderr, because the host's stderr is
+ * not readable anywhere later — and "why did the chip stop updating?" is
+ * precisely the question that cannot be answered without them. They live in the
+ * plugin's state directory, not inside the installed package.
+ */
+const HOST_LOG = logFile("host.log");
+/** Last view value written to the log, so only real changes are recorded. */
+let lastLoggedView;
+/** Whether this process already applied the size cap. */
+let logOpened = false;
+/** Keep the diagnostic file bounded: a session replay is thousands of lines. */
+const HOST_LOG_MAX_BYTES = 512 * 1024;
+function log(line) {
+  try {
+    if (logOpened === false) {
+      logOpened = true;
+      try { if (fs.statSync(HOST_LOG).size > HOST_LOG_MAX_BYTES) fs.rmSync(HOST_LOG, { force: true }); } catch {}
+    }
+    fs.appendFileSync(HOST_LOG, `${new Date().toISOString()} ${line}\n`);
+  } catch {}
+  report(line);
+}
+
+/** The Sandboxie configuration file whose box sections are the authority on "this box exists". */
+export function sandboxIniPath() {
+  const override = process.env.DSH_SBIE_INI;
+  if (typeof override === "string" && override.length > 0) return override;
+  return path.join(process.env.SystemDrive ?? "C:", "Windows", "Sandboxie.ini");
+}
+
+/**
+ * Parse a Sandboxie configuration file into `lowercased section name -> body`.
+ * The file is UTF-16LE; a plain `utf8` read yields interleaved NULs and every
+ * section header would be missed.
+ * @param text - the decoded file contents.
+ */
+export function parseIniSections(text) {
+  const sections = new Map();
+  let current;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("[") && line.endsWith("]") && line.length > 2) {
+      current = line.slice(1, -1).trim().toLowerCase();
+      if (!sections.has(current)) sections.set(current, []);
+      continue;
+    }
+    if (current !== undefined && line.length > 0) sections.get(current).push(line);
+  }
+  return sections;
+}
+
+/** Whether one box section grants this workspace read/write access. */
+export function sectionOwnsWorkspace(body, cwd) {
+  const needle = `${canonicalWorkspace(cwd)}\\*`.toLowerCase();
+  return body.some((line) => {
+    const lowered = line.toLowerCase();
+    return (lowered.startsWith("openfilepath=") || lowered.startsWith("readfilepath=")) && lowered.includes(needle);
+  });
+}
+
+/**
+ * The `FileRootPath` a box resolves to: the box's own setting, else the global
+ * one. `undefined` when Sandboxie declares neither (the common case), which
+ * leaves the caller on the default layout.
+ *
+ * `FileRootPath=` with an empty value counts as "not declared" — Sandboxie
+ * writes such lines itself, and treating one as a declaration would mask the
+ * `[GlobalSettings]` value that the machine is actually using.
+ * @param box - the box name.
+ * @param sections - parsed configuration sections.
+ */
+export function fileRootPathFor(box, sections) {
+  const read = (name) => {
+    const body = sections?.get?.(String(name).toLowerCase());
+    if (body === undefined) return undefined;
+    for (const line of body) {
+      const index = line.indexOf("=");
+      if (index === -1) continue;
+      if (line.slice(0, index).trim().toLowerCase() !== "filerootpath") continue;
+      const value = line.slice(index + 1).trim();
+      if (value.length > 0) return value;
+    }
+    return undefined;
+  };
+  return read(box) ?? read("GlobalSettings");
+}
+
+/**
+ * Where Sandboxie will actually keep this box's copy: its configured
+ * `FileRootPath` when there is one, else the default layout (or the override).
+ */
+export function rootForBox(box, sections = readIniSections()) {
+  return resolveBoxRoot(box, { template: fileRootPathFor(box, sections) });
+}
+
+/**
+ * The box this workspace actually owns, or null when it has none yet.
+ * Mirrors the launcher's resolution: walk the same candidates in the same
+ * order and accept the first that exists AND is ours, so another workspace's
+ * box is never reported as this one's.
+ * @param cwd - the session workspace.
+ * @param sections - parsed configuration sections.
+ */
+export function ownedBoxFor(cwd, sections) {
+  if (typeof cwd !== "string" || cwd.length === 0) return null;
+  for (const candidate of boxNameCandidates(cwd, "workspace-write", CANDIDATE_LIMIT)) {
+    const body = sections.get(candidate.toLowerCase());
+    if (body === undefined) continue;
+    if (!sectionOwnsWorkspace(body, cwd)) continue;
+    return { box: candidate, root: rootForBox(candidate, sections) };
+  }
+  return null;
+}
+
+let iniMemo;
+
+/**
+ * Drop the memo so the next read hits the file.
+ *
+ * Called by the shell provider the moment it decides a call will be redirected:
+ * the box may be about to be created, so a "no box yet" answer cached a moment
+ * earlier must not be the one the next committed event sees — otherwise the
+ * header chip would wait for the memo to expire. Also the test hook.
+ */
+export function invalidateBoxCache() {
+  iniMemo = undefined;
+}
+
+/** Read the configuration sections, memoized briefly. Null when unreadable. */
+export function readIniSections(now = Date.now()) {
+  if (iniMemo !== undefined && now - iniMemo.at < INI_MEMO_MS) return iniMemo.sections;
+  let sections = null;
+  try {
+    sections = parseIniSections(fs.readFileSync(sandboxIniPath(), "utf16le"));
+  } catch {
+    sections = null;
+  }
+  iniMemo = { at: now, sections };
+  return sections;
+}
+
+/** The workspace's owned box as of now, or null. */
+export function currentBoxFor(cwd) {
+  const sections = readIniSections();
+  if (sections === null) return null;
+  return ownedBoxFor(cwd, sections);
+}
+
+/** The name this workspace WOULD use; exported for the deterministic-name tests. */
+export function boxForHeader(header) {
+  const cwd = header?.cwd;
+  if (typeof cwd !== "string" || cwd.length === 0) return null;
+  try {
+    const box = boxNameFor(cwd, "workspace-write");
+    return { box, root: rootForBox(box) };
+  } catch (error) {
+    report(`could not derive the box for ${cwd}: ${error?.message ?? error}`);
+    return null;
+  }
+}
+
+// Re-exported for the resolution tests; keeps a single import from ./naming.mjs
+// so the bundle-free test loader only has one specifier to rewrite.
+export { boxNameCandidates };
+
+/** A stored legacy event's payload, when it is the shape this plugin wrote. */
+export function boxFromLegacyEvent(event) {
+  const data = event?.data;
+  if (typeof data?.box !== "string" || data.box.length === 0) return undefined;
+  return { box: data.box, root: typeof data.root === "string" && data.root.length > 0 ? data.root : rootForBox(data.box) };
+}
+
+/** Seed one session's projection state from its header, resolving any box that already exists. */
+export function seedState(header) {
+  const cwd = header?.cwd;
+  if (typeof cwd !== "string" || cwd.length === 0) return null;
+  const existing = currentBoxFor(cwd);
+  return { cwd, box: existing?.box ?? null, root: existing?.root ?? null };
+}
+
+export async function apply(ctx) {
+  // The schemas are validation for the wire. They must never be ABSENT: the
+  // projections service calls `wire.viewSchema.parse(...)` unconditionally when
+  // it publishes (and when it snapshots), so registering a wire with an
+  // undefined `viewSchema` throws on every publish — the chip then freezes at
+  // whatever `init` last built, which is exactly the "the name disappeared and
+  // never came back" failure. `importCore("zod")` is optional, so fall back to a
+  // pass-through schema rather than to nothing; either way the shape is small
+  // enough that validation adds little.
+  let z;
+  let schemaSource = "zod";
+  try {
+    ({ z } = await importCore("zod"));
+  } catch (error) {
+    z = undefined;
+    schemaSource = "pass-through";
+    log(`schemas unavailable, using a pass-through view schema: ${error?.message ?? error}`);
+  }
+  /** Minimal stand-in for a schema: keeps `.parse` callable when zod is missing. */
+  const PASS_THROUGH = { parse: (value) => value };
+  const stateSchema = z?.object({ cwd: z.string(), box: z.string().nullable(), root: z.string().nullable() }).nullable() ?? PASS_THROUGH;
+  const viewSchema = z?.object({ box: z.string().nullable(), root: z.string().nullable() }) ?? PASS_THROUGH;
+  // One source of truth for the version. A hardcoded copy inside a log line once
+  // sent me chasing a phantom "old build is still loaded" for two restarts.
+  const STATE_VERSION = 5;
+  log(`attaching projection registration (stateVersion ${STATE_VERSION}, schemas=${schemaSource})`);
+
+  // Register through `ctx.inject`, exactly as note.mjs does for the services it
+  // needs, so the registration lands on the LIVE registry once that service
+  // exists. This half is wired from the sandbox provider's CONSTRUCTOR, where
+  // `sessionProjections` may not resolve yet; a registration that lands anywhere
+  // else is never driven — no cell is created, `apply` is never called, no view
+  // is ever produced, and the chip silently never renders. That is exactly the
+  // observed signature: host.log had no `apply` and no `view` lines at all,
+  // while the box existed and the shipped units kept updating.
+  ctx.inject(["sessionProjections"], (scope) => {
+  try {
+    scope.sessionProjections.register({
+      key: BOX_PROJECTION,
+      // v5 forces every session's cell to be rebuilt from `init`. A v4 cell can
+      // FREEZE: the registry advances a cell by folding committed events into
+      // `apply`, and a cell that is ever built (or restored from the cache) while
+      // the box is absent stays at `{box:null}` — the symptom being a chip that
+      // vanished and never returned even though `init` reports the box. A version
+      // bump is the documented way to discard such cells; it is paired with
+      // per-call logging in `apply` so the next occurrence is recorded, not
+      // guessed at.
+      //   v1 stored an event-derived value
+      //   v2 froze the box at the session's first event
+      //   v3 carried the workspace so the box could be re-checked as it appears
+      //   v4 tolerates the retired event without trusting it
+      //   v5 rebuilds cells so a stale one cannot outlive a fix
+      stateVersion: STATE_VERSION,
+      stateSchema,
+      init: (header) => seedState(header),
+      apply: (state, event) => {
+        // The retired event is tolerated, never trusted. It is history: the name
+        // it recorded was that workspace's box AT THE TIME, so reporting it would
+        // make the chip claim a sandbox that may no longer exist — exactly what
+        // the chip must never do. Only the live check below decides, so a
+        // repaired log behaves identically to a clean one.
+        if (event.type === LEGACY_BOX_EVENT) return state;
+        const cwd = state?.cwd;
+        if (typeof cwd !== "string" || cwd.length === 0) return state;
+        // Re-verify in BOTH directions on every committed event. The box appears
+        // on the first redirected command, and it disappears when it is deleted
+        // (SandMan, or `--manage clean`) — exactly what a user who just removed
+        // the sandbox expects the chip to reflect. Latching the first non-null
+        // answer would leave the chip claiming a deleted box forever.
+        const sections = readIniSections();
+        // An unreadable configuration means "cannot tell", never "there is no
+        // box": clearing on a transient read failure would drop the chip for a
+        // box that still exists.
+        if (sections === null) return state;
+        const live = ownedBoxFor(cwd, sections);
+        const bound = state?.box ?? null;
+        // TRANSITIONS only. Logging every call is what finally located the
+        // frozen-chip bug — a registration that was never driven looked exactly
+        // like a fold that ran and found nothing — but one session replay is
+        // thousands of calls, so the evidence is kept where it is decisive.
+        if ((live === null ? null : live.box) === bound) return state;
+        log(`transition seq=${event.seq} type=${event.type} ${bound ?? "none"} -> ${live?.box ?? "none"}`);
+        if (live === null) return { cwd, box: null, root: null };
+        return { cwd, box: live.box, root: live.root };
+      },
+      wire: {
+        viewSchema,
+        // Logged only when the value actually changes: this runs for every
+        // publish AND every snapshot, and it is the last place the host can
+        // observe what the client is handed.
+        view: (state) => {
+          const view = { box: state?.box ?? null, root: state?.root ?? null };
+          if (view.box !== lastLoggedView) {
+            lastLoggedView = view.box;
+            log(`view box=${view.box ?? "none"}`);
+          }
+          return view;
+        }
+      }
+    });
+    log("projection registered");
+  } catch (error) {
+    log(`projection registration failed: ${error?.message ?? error}`);
+  }
+  });
+}

package/lib/inner.mjs

@@ -0,0 +1,116 @@
+/**
+ * The boxed half of the runner.
+ *
+ * Started by `SbieDll_RunSandboxed`, so this process already lives inside the
+ * Sandboxie box, but it starts with SbieSvc's handles rather than the
+ * launcher's. It therefore:
+ *   1. dials back to the launcher over loopback TCP (the one channel measured
+ *      to cross the box boundary — named pipes do not),
+ *   2. receives the exact argv/cwd/env,
+ *   3. spawns the real command with ordinary pipes. Because this process is
+ *      boxed, the child inherits the box: that is Sandboxie's core rule.
+ *
+ * If the launcher dies, the socket closes and the child is killed with it —
+ * the stand-in for bwrap's `--die-with-parent`.
+ */
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { Frame, createFrameDecoder, encodeFrame, encodeJsonFrame } from "./protocol.mjs";
+
+function parseArgs(argv) {
+  const out = { host: "127.0.0.1", port: 0, token: "" };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--port") out.port = Number(argv[++i]);
+    else if (argv[i] === "--token") out.token = argv[++i];
+    else if (argv[i] === "--host") out.host = argv[++i];
+  }
+  return out;
+}
+
+const options = parseArgs(process.argv.slice(2));
+if (!Number.isInteger(options.port) || options.port <= 0) {
+  process.stderr.write("dsh-sbie-relay: missing --port\n");
+  process.exit(2);
+}
+
+let child;
+let finished = false;
+
+const socket = net.connect({ host: options.host, port: options.port });
+socket.setNoDelay(true);
+
+function send(type, payload) {
+  if (socket.destroyed) return;
+  socket.write(encodeFrame(type, payload));
+}
+
+function finish(code) {
+  if (finished) return;
+  finished = true;
+  process.exitCode = code;
+  setTimeout(() => process.exit(code), 10).unref?.();
+}
+
+function startChild(spec) {
+  let childProcess;
+  try {
+    childProcess = spawn(spec.argv[0], spec.argv.slice(1), {
+      cwd: spec.cwd,
+      env: spec.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+  } catch (error) {
+    send(Frame.FAIL, `cannot spawn ${spec.argv[0]}: ${error.message}`);
+    socket.end();
+    finish(127);
+    return;
+  }
+  child = childProcess;
+  child.on("error", (error) => {
+    send(Frame.FAIL, `cannot spawn ${spec.argv[0]}: ${error.message}`);
+    socket.end();
+    finish(127);
+  });
+  child.stdout.on("data", (chunk) => send(Frame.STDOUT, chunk));
+  child.stderr.on("data", (chunk) => send(Frame.STDERR, chunk));
+  child.on("exit", (code, signal) => {
+    send(Frame.EXIT, JSON.stringify({ code: code === null ? null : code, signal: signal ?? null }));
+    socket.end();
+    finish(code === null ? 1 : code);
+  });
+}
+
+socket.on("connect", () => {
+  socket.write(encodeJsonFrame(Frame.HELLO, { token: options.token }));
+});
+
+const decode = createFrameDecoder((type, body) => {
+  switch (type) {
+    case Frame.SPEC:
+      startChild(JSON.parse(body.toString("utf8")));
+      break;
+    case Frame.STDIN:
+      if (child !== undefined && child.stdin.writable) child.stdin.write(body);
+      break;
+    case Frame.STDIN_EOF:
+      if (child !== undefined && child.stdin.writable) child.stdin.end();
+      break;
+    default:
+      break;
+  }
+});
+
+socket.on("data", decode);
+socket.on("error", (error) => {
+  process.stderr.write(`dsh-sbie-relay: channel error: ${error.message}\n`);
+  child?.kill();
+  finish(127);
+});
+socket.on("close", () => {
+  if (!finished) {
+    // The launcher went away (or finished): do not leave the command running.
+    child?.kill();
+    finish(child === undefined ? 127 : 0);
+  }
+});

package/lib/koffi.mjs

@@ -0,0 +1,95 @@
+/**
+ * Locate a usable koffi FFI binding without owning a dependency tree.
+ *
+ * DSH ships koffi as a prebuilt Node-API addon under `app.asar.unpacked`, but
+ * 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.
+ */
+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";
+
+const require = createRequire(import.meta.url);
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+let cached;
+
+function candidateRoots() {
+  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(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) => {
+    try {
+      return fs.statSync(r).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Depth-bounded search for a `koffi.node` under `root`. */
+function findKoffiNode(root, maxDepth = 9) {
+  const queue = [{ dir: root, depth: 0 }];
+  let best;
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isFile()) {
+        if (entry.name === "koffi.node") {
+          // Prefer a win32-x64 build over any other architecture artifact.
+          if (best === undefined || /win32[_-]?x64|x64/i.test(full)) best = full;
+        }
+      } else if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name.startsWith("@") || /koffi|win32|x64|dependencies|resources|dsh/i.test(entry.name) || depth === 0) {
+          queue.push({ dir: full, depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/** Resolve and load koffi once. Throws with an actionable message when absent. */
+export function loadKoffi() {
+  if (cached !== undefined) return cached;
+  if (process.env.DSH_SBIE_KOFFI) {
+    cached = require(process.env.DSH_SBIE_KOFFI);
+    return cached;
+  }
+  try {
+    cached = require("koffi");
+    return cached;
+  } catch {}
+  const tried = [];
+  for (const root of candidateRoots()) {
+    tried.push(root);
+    const found = findKoffiNode(root);
+    if (found !== undefined) {
+      cached = require(found);
+      return cached;
+    }
+  }
+  throw new Error(
+    `koffi native addon not found. Set DSH_SBIE_KOFFI to a koffi.node path. Searched: ${tried.join(", ") || "(no candidate roots)"}`
+  );
+}

package/lib/log.mjs

@@ -0,0 +1,62 @@
+/**
+ * Where the plugin's diagnostics live.
+ *
+ * NOT in the package directory. Once installed as a bundle the package sits in
+ * the profile's `node_modules` — and pnpm may serve it straight out of its
+ * content-addressed store — so appending logs there pollutes the install tree,
+ * trips store integrity checks and can fail outright when the tree is
+ * read-only. Diagnostics therefore go to a per-user state directory, with the
+ * OS temp directory as the last resort.
+ *
+ * Node builtins only: this module is imported at the top level of halves that
+ * must load in the Electron host (see the module-level import rule in
+ * AGENTS.md).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** State root: `$DSH_HOME/state`, which is `~/.dsh/state` by default. */
+function stateRoot() {
+  const home = process.env.DSH_HOME;
+  if (typeof home === "string" && home.length > 0) return path.join(home, "state");
+  return path.join(os.homedir(), ".dsh", "state");
+}
+
+/**
+ * Candidate directories, in order: an explicit override (used by the tests so
+ * they never touch a real user's state), the state root, then temp.
+ */
+function candidates() {
+  const override = process.env.DSH_SBIE_LOG_DIR;
+  const list = [];
+  if (typeof override === "string" && override.length > 0) list.push(override);
+  list.push(path.join(stateRoot(), "dsh-sandboxie-redirect"));
+  list.push(path.join(os.tmpdir(), "dsh-sandboxie-redirect"));
+  return list;
+}
+
+/**
+ * The absolute path of one diagnostic file, creating its directory on the way.
+ *
+ * Never throws: a plugin that cannot write a log still has to run. When every
+ * candidate directory is unusable the last path is returned anyway, so the
+ * caller's own try/catch around the write is what finally swallows the error.
+ */
+export function logFile(name) {
+  const tried = candidates();
+  for (const dir of tried) {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      if (fs.statSync(dir).isDirectory()) return path.join(dir, name);
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  return path.join(tried[tried.length - 1], name);
+}
+
+/** The directory the diagnostics currently land in, for docs and diagnostics. */
+export function logDirectory() {
+  return path.dirname(logFile("host.log"));
+}