dsh-plugin-wsl-env 0.2.0 → 0.3.0

package/lib/index.js

@@ -43,7 +43,7 @@ import { LocalBashExecutor } from "@deepseek-ai/dsh-bash-local";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature, SandboxUnavailableError, writableRoots } from "@deepseek-ai/dsh-sandbox";
-import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix } from "./paths.js";
+import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { WslSandbox } from "./sandbox.js";
 import { armDistroWatcher } from "./watcher.js";
 import { WslAgent } from "./agent.js";
@@ -51,6 +51,9 @@ import { AgentUnavailableError } from "./agent-errors.js";
 import { publicationArgv } from "./fs-publish.js";
 import { agentExecutionHandle } from "./agent-exec.js";
 import { sharedAgent } from "./agent-shared.js";
+import { AgentSubstrate } from "./fs-substrate.js";
+import { FsCodedError } from "./fsio-text.js";
+import { confinedAgent } from "./agent-confined.js";
 // `runCapture` and distro discovery live in ./wsl.js so the directory picker
 // can use them without pulling this file's executor and filesystem peers in.
 import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
@@ -172,6 +175,20 @@ export class WslShellExecutor extends LocalBashExecutor {
      * unconfined and `sandboxMode` is `undefined`, so the model is told so.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands: its files cannot be read or
+     * exfiltrated and its executables cannot be launched through interop —
+     * the hole that lets a "sandboxed" command reach your full Windows token.
+     * A narrowing, not a closure (a command can still write an executable
+     * into the workspace and run it — binfmt dispatches on content, not
+     * location), so enforcement stays `partial` and the sandbox fact reports
+     * `windowsDrive: "masked"`. Costs: confined commands cannot read or touch
+     * anything under `/mnt`, and tools that probe the drive degrade. The
+     * complete closure is distro-level: `[interop] enabled=false` in
+     * `wsl.conf`.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Default workdir for a request that names none; accepts `/home/andy/proj`,
      * a UNC path, or `C:\...`. Empty — the default — means the distro user's
@@ -447,6 +464,7 @@ export class WslShellExecutor extends LocalBashExecutor {
         mode: facts.mode,
         denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
         enforcement: facts.enforcement,
+        ...(facts.windowsDrive ? { windowsDrive: facts.windowsDrive } : {}),
         ...(runnerFailed ? { runnerFailed } : {}),
       };
     }
@@ -552,6 +570,10 @@ export class WslShellExecutor extends LocalBashExecutor {
       cwd: toLinuxPath(resolved.workdir, { distro }),
       argv: confined !== undefined ? confined.argv : this.distroArgv(resolved, shell),
       timeoutMs: resolved.timeoutMs,
+      // The agent enforces the collect budget distro-side (the EXEC frame
+      // carries it); `maxSpillBytes` stays one-shot-only — the agent path has
+      // no spill files by design, its capture is bounded instead.
+      maxOutputBytes: this.config.maxOutputBytes,
       signal: resolved.signal,
       onStarted: confined !== undefined
         ? (proc) => {
@@ -562,6 +584,7 @@ export class WslShellExecutor extends LocalBashExecutor {
               runnerFailureRules: confined.runnerFailureRules,
               runnerProgram: confined.argv[0],
               workdir: resolved.workdir,
+              windowsDrive: confined.windowsDrive,
             });
           }
         : undefined,
@@ -571,7 +594,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       this.throwIfWorkdirMissing(result, resolved.workdir);
       if (this.sandbox === undefined) return result;
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
-      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
       const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
       if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
       return {
@@ -580,6 +603,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           mode,
           denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
           enforcement,
+          windowsDrive,
         },
       };
     }, (error) => {
@@ -635,6 +659,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           runnerFailureRules: confined.runnerFailureRules,
           runnerProgram: confined.argv[0],
           workdir: resolved.workdir,
+          windowsDrive: confined.windowsDrive,
         });
       },
     );
@@ -642,7 +667,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       this.throwIfDistroUnavailable(result, distro);
       this.throwIfWorkdirMissing(result, resolved.workdir);
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
-      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
       // Runner failure outranks denial because the command did not run at all.
       const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
       if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
@@ -652,6 +677,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           mode,
           denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
           enforcement,
+          windowsDrive,
         },
       };
     }, (error) => {
@@ -716,6 +742,14 @@ export class WslFileSystem extends LocalFileSystem {
      * operations are unconfined.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands — same meaning and same honest
+     * limits as the `wsl-shell` key of the same name (its doc carries the
+     * full story). Confined fs mutations publish through the masked resident;
+     * reads and the share substrate are unaffected.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Refuse any path that leaves the pinned distro. A WSL filesystem is a
      * whole-Linux view whose `/mnt/c` also reaches the Windows disk, so without
@@ -741,6 +775,19 @@ export class WslFileSystem extends LocalFileSystem {
      * only how many round trips it costs.
      */
     agent: z.boolean().default(true),
+    /**
+     * Which I/O substrate serves the file tools. `"agent"` (the default) —
+     * the resident in-distro agent (`lib/fs-substrate.js`): reads, writes,
+     * identities and watches run where the files live, symlinks and mode bits
+     * are native, and the mutation guard survives to the write's no-replace
+     * publication, kernel-enforced by the confined resident when the policy is
+     * confined. `"share"` — the opt-out: the Windows-side host filesystem
+     * stack over the distro's 9p share, with the symlink-retry and publication
+     * hooks that compensate for what the share cannot do. Both substrates
+     * fence writes with the same host-side policy check; neither changes
+     * `sandboxMode`'s honesty.
+     */
+    substrate: z.union(["share", "agent"]).default("agent"),
   });
 
   constructor(ctx, config) {
@@ -752,6 +799,10 @@ export class WslFileSystem extends LocalFileSystem {
     this.defaultMode = ctx.sandboxPolicy.defaultMode;
     /** targetKey -> canonical replacement target, for symlinked paths. */
     this.canonicalTargets = new Map();
+    /** The lazy agent-backed substrate, built on first use (see `agentSubstrate`). */
+    this.agentSubstrateInstance = undefined;
+    /** The distro-side bwrap usability probe, shared with the confined agents. */
+    this.sandbox = new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive });
     // `dsh-fs-local` takes a Windows branch whenever the destination already
     // exists — which is how it knows to preserve the replaced file's security
     // descriptor, and what makes every write to an existing file fail here:
@@ -846,6 +897,78 @@ export class WslFileSystem extends LocalFileSystem {
     return this.agentInstance;
   }
 
+  /**
+   * The agent-backed substrate for `substrate: "agent"`, built on first use
+   * over the same resident agent the publication path shares.
+   * @returns {Promise<AgentSubstrate|undefined>} the substrate, or undefined
+   *   when the share backend is configured.
+   */
+  async agentSubstrate() {
+    if (this.config.substrate !== "agent") return undefined;
+    if (this.agentSubstrateInstance === undefined) {
+      this.agentSubstrateInstance = new AgentSubstrate({
+        agent: await this.publicationAgent(),
+        distro: await this.distro(),
+        diffBasisMaxBytes: this.config.diffBasisMaxBytes,
+        agentFor: (policy) => this.mutationAgent(policy),
+      });
+    }
+    return this.agentSubstrateInstance;
+  }
+
+  /**
+   * The agent a MUTATION runs on under this resolved policy — stage-two
+   * routing. A confined policy addresses the confined resident whose bwrap
+   * profile binds exactly what the mode grants, so the kernel enforces what
+   * the check decided; an escalated write (`danger-full-access`) or a disabled
+   * sandbox addresses the plain resident, which is what those mean. A distro
+   * without a usable bwrap refuses confined mutations instead of downgrading
+   * them — the same closed failure the command path has.
+   * @param {{mode: string, workspaceRoot: string}|undefined} policy - the
+   *   resolved file-effect policy, or undefined when the caller pre-checked.
+   * @returns {Promise<WslAgent>} the agent to publish through.
+   */
+  async mutationAgent(policy) {
+    if (!policy || !this.config.sandbox || policy.mode === "danger-full-access") {
+      return this.publicationAgent();
+    }
+    const distro = await this.distro();
+    if (!(await this.sandbox.usable(distro))) {
+      throw new SandboxUnavailableError(
+        policy.mode,
+        `bwrap is not usable inside distro "${distro}". Install it with ` +
+          `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
+          `wsl.exe -d ${distro} -u root -- apt-get install -y bubblewrap`,
+      );
+    }
+    return confinedAgent({ distro, wslPath: this.config.wslPath, policy, maskWindowsDrive: this.config.maskWindowsDrive });
+  }
+
+  /**
+   * Map a substrate error onto the peer's `FsError`, so the tool layer reads
+   * the same refusal dialect on both substrates. An agent that is out becomes
+   * an I/O error naming the cause — the share backend's "distro is gone" case
+   * is the same availability, but the message says which substrate failed.
+   * @param error - what the substrate raised.
+   * @returns {FsError} the error to surface.
+   */
+  peerError(error) {
+    if (error instanceof FsCodedError) return new FsError(error.message, error.code, { cause: error });
+    if (error instanceof SandboxUnavailableError) return new FsError(error.message, "FS_IO_ERROR", { cause: error });
+    const message = error instanceof Error ? error.message : String(error);
+    return new FsError(`the distro file substrate is unavailable: ${message}`, "FS_IO_ERROR", { cause: error instanceof Error ? error : undefined });
+  }
+
+  /**
+   * One resolved target's Linux path — the substrate's coordinate — falling
+   * back to the display spelling when the identity is not a distro share path.
+   * @param target - the resolved target.
+   * @returns the absolute Linux path.
+   */
+  linuxOf(target) {
+    return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
+  }
+
   /**
    * The pinned distro, resolving WSL's default on first use.
    * @returns the distro name.
@@ -892,8 +1015,19 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the resolved `FsTarget`.
    */
   async resolve(path, opts) {
+    const world = await this.worldPath(path, opts?.cwd);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot serve "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.resolve(linux, opts?.signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const distro = await this.distro();
-    const target = await super.resolve(await this.worldPath(path, opts?.cwd), opts);
+    const target = await super.resolve(world, opts);
     return { targetKey: target.targetKey, displayPath: toDisplayPath(target.targetKey, distro) };
   }
 
@@ -1002,22 +1136,86 @@ export class WslFileSystem extends LocalFileSystem {
   }
 
   async stat(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.stat(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.stat(t, signal));
   }
 
+  /**
+   * No-follow stat one path. The agent substrate answers from the distro,
+   * where a symlink is a first-class entry; the share backend keeps the
+   * inherited host behaviour.
+   * @param path - a Linux, UNC or Windows path.
+   * @param opts - optional `cwd` override.
+   * @param signal - optional cancellation.
+   * @returns the path info, or undefined when absent.
+   */
+  async lstat(path, opts, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const world = await this.worldPath(path, opts?.cwd);
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot inspect "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.lstat(linux, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
+    return super.lstat(path, opts, signal);
+  }
+
   async readText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readText(t, signal));
   }
 
   async streamText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.streamText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.streamText(t, signal));
   }
 
   async readBytes(target, signal, maxBytes) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readBytes(target, signal, maxBytes);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readBytes(t, signal, maxBytes));
   }
 
   async readByteRange(target, range, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readByteRange(target, range, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readByteRange(t, range, signal));
   }
 
@@ -1031,6 +1229,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the directory rows.
    */
   async listDir(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The substrate's rows already carry Linux display paths and canonical
+      // identities, so no share-side rewrite follows.
+      try {
+        return await sub.listDir(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const entries = await this.withCanonicalRetry(target, signal, (t) => super.listDir(t, signal));
     const distro = await this.distro();
     return entries.map((entry) => ({
@@ -1111,9 +1319,25 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the write outcome.
    */
   async writeText(target, content, expected, signal, sandboxPolicy) {
+    // The policy resolves once: the fence and the confined routing must see
+    // the same grant, or the kernel would enforce something other than what
+    // was checked.
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
     // The fence runs first and its fresh target is the one checked and written,
     // so a refusal costs no I/O and cannot be raced by a swapped symlink.
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The agent substrate keeps the guard: the distro-side no-replace link
+      // is an atomic primitive, so the check-then-write window the share
+      // backend documents closes here, exactly as on a Linux host. The policy
+      // also selects the confined resident whose mount table matches it.
+      try {
+        return await sub.writeText(fenced, content, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     // The guard is deliberately not forwarded: the host backend would publish a
     // guarded creation with a hard link, which this filesystem rejects. Once
@@ -1133,7 +1357,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the edit outcome.
    */
   async editText(target, edit, expected, signal, sandboxPolicy) {
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.editText(fenced, edit, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     return super.editText(fenced, edit, undefined, signal);
   }

package/lib/sandbox.js

@@ -32,6 +32,12 @@ import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
 import { createProbeCache } from "./probe-cache.js";
 import { toLinuxPath } from "./paths.js";
 import { runCapture } from "./wsl.js";
+import { bwrapArgvPrefix, bwrapProfileArgs } from "./bwrap.js";
+
+// The profile and the argv prefix are also what `lib/agent-confined.js` builds
+// for its residents, so both live in the peer-free `lib/bwrap.js` and are
+// re-exported here, where the sandbox's callers have always found them.
+export { bwrapProfileArgs };
 
 /**
  * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
@@ -60,6 +66,22 @@ const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
  */
 const ENFORCEMENT = "partial";
 
+/**
+ * The one mitigation the profile can offer, and its honest ceiling.
+ *
+ * `maskWindowsDrive` mounts an empty tmpfs over `/mnt`: the Windows drive's
+ * files vanish from the command's view, which takes the drive's data off the
+ * table and makes the on-drive executables unreachable. It does NOT make the
+ * run `full`: binfmt interop dispatches on file CONTENT, so a command that can
+ * write the workspace (which `workspace-write` grants) can write a PE there
+ * and execute it — binfmt launches it as a Windows process outside the Linux
+ * sandbox regardless of where the file sits. The only complete closures are
+ * distro-level (`[interop] enabled=false` in `wsl.conf`, which costs every
+ * legitimate interop user their tooling) — so the provider reports `partial`
+ * either way, and the mask is a decision an operator makes to shrink the hole,
+ * recorded as the `windowsDrive: "masked"` fact the model can see.
+ */
+
 /**
  * Probe verdicts, keyed by `wslPath\0distro`. The policy — a success is durable, a
  * failure is re-probed, concurrent probes are shared — lives in `probe-cache.js`,
@@ -67,29 +89,6 @@ const ENFORCEMENT = "partial";
  */
 const probeVerdicts = createProbeCache();
 
-/**
- * Build the bwrap profile arguments for one file-effect policy, exactly as
- * upstream's `bwrapProfileArgs` does.
- *
- * `--ro-bind / /` makes the whole distro read-only, `--dev /dev` supplies the
- * `/dev/null` sink a shell needs, `--unshare-pid` keeps the sandbox's process
- * view its own, and `--proc /proc` gives it a matching `/proc`. Under
- * `workspace-write` the workspace is bound read-write and `/tmp` becomes an
- * ephemeral tmpfs — the temp area the mode promises, without exposing the
- * distro's real `/tmp`.
- *
- * @param policy - the policy to express as bwrap mounts.
- * @returns profile arguments, before the `--` separator and the command argv.
- */
-export function bwrapProfileArgs(policy) {
-  const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
-  if (policy.mode === "workspace-write") {
-    args.push("--tmpfs", "/tmp");
-    args.push("--bind", policy.workspaceRoot, policy.workspaceRoot);
-  }
-  return args;
-}
-
 /**
  * Confine commands inside one distro with `bwrap`.
  *
@@ -100,9 +99,14 @@ export function bwrapProfileArgs(policy) {
 export class WslSandbox {
   /**
    * @param config - the `wsl.exe` path, overridable for a non-standard install.
+   * @param config.maskWindowsDrive - shadow `/mnt` with an empty tmpfs in every
+   *   profile this sandbox builds, hiding the Windows drive from confined
+   *   commands (see the module doc above {@link ENFORCEMENT} for what that
+   *   does and does not close).
    */
   constructor(config = {}) {
     this.wslPath = config.wslPath ?? "wsl.exe";
+    this.maskWindowsDrive = config.maskWindowsDrive ?? false;
   }
 
   /**
@@ -123,8 +127,8 @@ export class WslSandbox {
   async usable(distro, signal) {
     const key = `${this.wslPath}\u0000${distro}`;
     return probeVerdicts.run(key, async () => {
-      const profile = bwrapProfileArgs({ mode: "read-only", workspaceRoot: "/" });
-      await runCapture([this.wslPath, "-d", distro, "--exec", "bwrap", ...profile, "--", "true"], signal);
+      const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
+      await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
       return true;
     });
   }
@@ -152,12 +156,13 @@ export class WslSandbox {
       );
     }
     const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
-    const profile = bwrapProfileArgs({ ...policy, workspaceRoot });
+    const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
     return {
-      argv: ["bwrap", ...profile, "--", ...argv],
+      argv: [...prefix, ...argv],
       enforcement: ENFORCEMENT,
       denialSignatures: DENIAL_SIGNATURES,
       runnerFailureRules: RUNNER_FAILURE_RULES,
+      windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
     };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -40,6 +40,8 @@
     "docs/CONFIGURATION.md",
     "docs/LIMITATIONS.md",
     "docs/PARITY.md",
+    "docs/PEER-PARITY.md",
+    "docs/UPSTREAM-FSIO-EXPORT.md",
     "docs/ARCHITECTURE.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -51,7 +53,7 @@
     "test": "npm run lint:style && npm run test:syntax && npm run test:unit",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs",
+    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",
@@ -64,6 +66,7 @@
     "probe:sandbox-shell": "bash test/probe/sandbox-shell.sh",
     "sync:windows": "bash test/probe/sync-to-windows.sh",
     "probe:watch": "bash test/probe/watch.sh",
+    "probe:substrate": "bash test/probe/substrate.sh",
     "probe:exec": "bash test/probe/exec.sh",
     "bootstrap": "bash scripts/bootstrap.sh"
   },