@stackstackstack/dsh-fs-sandbox 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/fs/fs-sandbox/README.md
+README.md: 73df31d0f98b602c57a3e86340c3dfe0ee836cd0
+README.zh.md: f4000b200979e951f7e10d452a11773114484185

package/README.md

@@ -0,0 +1,45 @@
+# dsh-fs-sandbox — the sandbox-enforcing filesystem backend
+
+English | [中文](README.zh.md)
+
+`SandboxedFileSystem` extends [`LocalFileSystem`](../fs-local/README.md) and registers as `ctx.fs`. It inherits every text-storage mechanic verbatim (resolve, stat, read/stream, list, the atomic write, the read-match-write edit critical section) and adds only a per-call MODE fence on `writeText`/`editText`. Reads always pass through — every mode permits reading.
+
+Its plugin config is the local backend config unchanged: `cwd` remains the relative-path resolution default, and `diffBasisMaxBytes` bounds the optional overwrite contextual-diff basis.
+
+Loading it INSTEAD OF `dsh-fs-local`, together with a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/README.md), is the whole swap; the model-facing tools (`dsh-tool-fs`) are untouched. The tool layer resolves the calling session's mode and cwd into the SAME per-call policy bash receives, so the two families never confine to different roots.
+
+## The fence
+
+The per-call policy carries the effective mode (session override or escalation grant) together with the calling session's immutable cwd root, falling back to deployment policy only for calls without one:
+
+- `read-only` — denies every mutation with the structured `FS_SANDBOX_DENIED`.
+- `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. Canonical spellings use a lexical fast path; an identity-based ancestor fallback recognizes alias-equivalent roots such as Windows long names and 8.3 names without treating unrelated prefixes as contained. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
+- `danger-full-access` — delegates unfenced.
+
+## Threat model: a policy fence, not a kernel boundary
+
+The fence is a check in TRUSTED code over a MODEL-CONTROLLED path — the operations are the seam's own (open, rename), only the target path is untrusted, so canonicalize-then-contain is the complete answer to this surface. This mirrors the `code-runtime` stance: containment, not a security boundary. Kernel-grade isolation of untrusted CODE stays `ctx.shell`'s job ([`dsh-bash-sandbox`](../../shell/bash-sandbox/README.md)). The residual TOCTOU (an ancestor symlink swapped between the containment re-check and the syscall) is narrowed by re-canonicalizing immediately before the write and is accepted for this threat model; a kernel-tight boundary needs `openat2`-class primitives not worth their portability cost here.
+
+A denial is a structured `FsError` (`FS_SANDBOX_DENIED`, carrying the effective mode) — no stderr text inference (unlike bash's kernel denials), because an in-process fence knows exactly what it refused. The model-facing `[sandbox: file access denied under <mode> mode]` marker and the one-approved-wider retry live in the tool layer (`dsh-tool-fs`), exactly as bash's do. See [the cross-family fs sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
+
+## Model Experience
+
+### Filesystem policy and refusals
+
+#### What the model sees
+
+The policy owner contributes capability-neutral `sandbox:policy` context. Indirectly, `dsh-tool-fs` renders this backend's `FS_SANDBOX_DENIED` refusals as the `[sandbox: file access denied under <mode> mode]` marker plus the same-turn escalation hint.
+
+#### Token effect
+
+The current-policy clause adds a small runtime-context message while this backend is mounted; a denial adds the bounded marker and escalation hint to conversation history.
+
+#### KV Cache effect
+
+A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; operation results remain append-only.
+
+## Known Limitations and Deferred Work
+
+- **A policy fence, not a kernel boundary** — the check is trusted code over a model-controlled path, so the residual resolve-to-syscall TOCTOU is narrowed (by the in-place re-canonicalization) but not eliminated; adversarial host processes are out of scope. Kernel-grade isolation of untrusted code stays `ctx.shell`'s.
+- **Fence-vs-runner parity is derived from one owner** — the writable set comes from `writableRoots`, shared with the Seatbelt profile; a runner profile that defines its writable set elsewhere would drift.
+- **Requires `ctx.sandboxPolicy`** — tools use it to resolve each session policy and the backend uses it for agentless-call fallbacks; the backend does not confine without it composed.

package/README.zh.md

@@ -0,0 +1,45 @@
+# dsh-fs-sandbox：强制沙箱的文件系统后端
+
+[English](README.md) | 中文
+
+`SandboxedFileSystem` 扩展 [`LocalFileSystem`](../fs-local/README.md) 并注册为 `ctx.fs`。它逐字继承全部文本存储机制（解析、stat、读取／流式读取、列出、原子写入、按读取、匹配、写入顺序执行的编辑临界区），只为 `writeText`/`editText` 增加按调用的模式围栏。读取始终直接通过：所有模式都允许读取。
+
+它原样复用本地后端配置：`cwd` 仍是相对路径的解析默认值，`diffBasisMaxBytes` 则限制可选的覆写上下文 diff 基础。
+
+只需加载它来替代 `dsh-fs-local`，并同时加载 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/README.md)，即可完成替换；面向模型的工具（`dsh-tool-fs`）无需改动。工具层把调用会话的模式和 cwd 解析为与 bash 相同的按调用策略，因此两个能力族绝不会约束到不同根目录。
+
+## 围栏
+
+按调用策略携带有效模式（会话覆盖值或升级授权）和调用会话不可变的 cwd 根目录；只有没有会话的调用才回退到部署策略：
+
+- `read-only`：以结构化 `FS_SANDBOX_DENIED` 拒绝所有变更；
+- `workspace-write`：只有目标规范化后位于可写根目录下，才允许变更。可写根包括工作区根目录和平台临时区域（`/tmp`、`os.tmpdir()`），与 Seatbelt profile 授权的集合相同；该集合由唯一的 [`writableRoots`](../../sandbox/README.md) 函数派生，使 fs 围栏与 bash runner 不会漂移。规范拼写使用词法快速路径；基于身份的祖先回退可以识别 Windows 长名称和 8.3 名称等别名等价根目录，而不会把无关前缀视为包含关系。委托前会立即重新规范化目标，因此工具解析后被替换的祖先符号链接也会被发现；
+- `danger-full-access`：不加围栏直接委托。
+
+## 威胁模型：策略围栏，而非内核边界
+
+围栏是在可信代码中检查模型控制的路径。操作本身属于 seam（open、rename），只有目标路径不可信，因此「规范化后检查包含关系」就是该接口的完整答案。这与 `code-runtime` 的立场相同：提供约束，但不是安全边界。不可信代码的内核级隔离仍由 `ctx.shell` 负责（[`dsh-bash-sandbox`](../../shell/bash-sandbox/README.md)）。剩余 TOCTOU（在包含关系复查与系统调用之间替换祖先符号链接）会通过写入前立即重新规范化来缩小，并为该威胁模型所接受；内核严密边界需要 `openat2` 一类原语，其可移植性成本在此不值得。
+
+拒绝是结构化 `FsError`（`FS_SANDBOX_DENIED`，携带有效模式），不通过 stderr 文本推断（不同于 bash 的内核拒绝），因为进程内围栏准确知道自己拒绝了什么。面向模型的 `[sandbox: file access denied under <mode> mode]` 标记以及唯一一次获批的更宽权限重试位于工具层（`dsh-tool-fs`），与 bash 完全相同。见[跨能力族 fs 沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
+
+## 模型体验
+
+### 文件系统策略与拒绝
+
+#### 模型看到的内容
+
+策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。作为间接影响，`dsh-tool-fs` 会把本后端的 `FS_SANDBOX_DENIED` 拒绝渲染为 `[sandbox: file access denied under <mode> mode]` 标记和同轮次升级提示。
+
+#### Token 影响
+
+该后端挂载期间，当前策略条款会增加一条简短的运行时上下文消息；拒绝则会把有界标记和升级提示追加到对话历史。
+
+#### KV Cache 影响
+
+常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；操作结果保持仅追加。
+
+## 已知限制与暂缓事项
+
+- **策略围栏，而非内核边界**：该检查是可信代码处理模型控制的路径，因此解析到系统调用之间残留的 TOCTOU 会被原位重新规范化缩小，但不会消除；对抗性宿主进程不在范围内。不可信代码的内核级隔离仍属于 `ctx.shell`。
+- **围栏与 runner 的一致性由单一所有方派生**：可写集合来自 `writableRoots`，该函数与 Seatbelt profile 共享；在其他位置定义可写集合的 runner profile 会发生漂移。
+- **要求 `ctx.sandboxPolicy`**：工具使用它解析每个会话策略，后端用它处理无 agent（智能体）调用的回退；未组合该服务时，后端不会实施约束。

package/lib/index.js

@@ -0,0 +1,173 @@
+import { LocalFileSystem } from "@stackstackstack/dsh-fs-local";
+import { FsError } from "@stackstackstack/dsh-fs";
+import { writableRoots } from "@stackstackstack/dsh-sandbox";
+import { stat } from "node:fs/promises";
+import { dirname, sep } from "node:path";
+//#region lib/types/containment.js
+/**
+* Path-containment mechanics for the filesystem sandbox. Canonical spellings
+* take the fast lexical path; filesystem identity supplies the conservative
+* fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+* @module @stackstackstack/dsh-fs-sandbox/containment
+*/
+const MISSING_CODES = new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		/* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */
+		if (isMissing(error)) return void 0;
+		/* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `SandboxedFileSystem`: the sandbox-enforcing implementation of the
+* `@stackstackstack/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
+* text-storage mechanics — resolve, stat, read/stream, list, the atomic
+* write and the read-match-write edit critical section — are the local
+* implementation's, verbatim; this package adds only the per-call POLICY fence
+* on the two mutations. Reads pass through untouched: every mode permits
+* reading.
+*
+* The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+* NOT a kernel boundary — the operations are the seam's own (open, rename),
+* and only the target path is untrusted, so canonicalize-then-contain is the
+* complete answer to this surface. Kernel-grade isolation of untrusted CODE
+* stays `ctx.shell`'s job (`@stackstackstack/dsh-bash-sandbox`). This mirrors the
+* `code-runtime` stance: containment, not a security boundary. The residual
+* TOCTOU (an ancestor symlink swapped between the containment re-check and the
+* syscall) is narrowed by re-canonicalizing immediately before delegating and
+* is accepted for this threat model.
+*
+* Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+* a mutation only when the target canonicalizes under the policy's workspace
+* root or a platform temp area (the SAME writable-root set Seatbelt grants,
+* derived from the one `writableRoots` function so bash and fs cannot drift);
+* `danger-full-access` delegates unfenced. A denial throws the structured
+* `FS_SANDBOX_DENIED` — no text inference is needed (unlike bash's kernel
+* stderr), because an in-process fence knows exactly what it refused. The
+* escalation retry lives in the tool layer (`@stackstackstack/dsh-tool-fs`),
+* exactly as bash's does.
+*
+* @module @stackstackstack/dsh-fs-sandbox
+*/
+/**
+* Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
+* INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
+* swap — the model-facing tools are untouched). Its configured default mode is
+* the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+* each session's mode and cwd into a policy for every mutation, while an
+* approved escalation may stamp a strictly wider mode for one call.
+*/
+var SandboxedFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy"];
+	defaultMode;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* Fence the write by the per-call policy, then delegate to the inherited
+	* atomic write. See {@link checkedTarget}.
+	* @param target - the resolved target to write.
+	* @param content - the full new file content.
+	* @param expected - the write intent guarding the write; omit for unconditional.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the write outcome from the inherited backend.
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* Fence the edit by the per-call policy, then delegate to the inherited
+	* atomic edit. See {@link checkedTarget}.
+	* @param target - the resolved target to edit.
+	* @param edit - the literal search/replace request.
+	* @param expected - the version guard; omit for an unconditional edit.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the edit outcome from the inherited backend.
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the EXACT target the
+	* mutation must use, so the checked identity is the mutated one (no
+	* check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+	* re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
+	* reflecting a concurrently swapped symlink), requires containment under a
+	* writable root, and returns THAT fresh target; `danger-full-access` returns
+	* the caller's target unfenced. Throws the structured `FS_SANDBOX_DENIED` on
+	* refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
+	* and the escalation hint.
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await this.resolve(target.displayPath);
+		let contained = false;
+		for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey, root)) {
+			contained = true;
+			break;
+		}
+		if (!contained) throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+		return fresh;
+	}
+};
+//#endregion
+export { SandboxedFileSystem, SandboxedFileSystem as default };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-fs-sandbox`.
+* @module @stackstackstack/dsh-fs-sandbox/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-fs-sandbox";
+/** Cordis companion plugin name. */
+const name = "fs-sandbox-invariant";
+/** Services required before the companion can register. */
+const inject = ["invariants"];
+/** No runtime invariant: this stateless adapter delegates policy and filesystem relations to their owning seams. */
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/containment.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Path-containment mechanics for the filesystem sandbox. Canonical spellings
+ * take the fast lexical path; filesystem identity supplies the conservative
+ * fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+ * @module @stackstackstack/dsh-fs-sandbox/containment
+ */
+/**
+ * Determine whether a canonical target is a writable root or lies beneath it.
+ * The lexical fast path handles normal canonical spellings. When spellings
+ * differ, walk the target's existing ancestors and compare filesystem identity
+ * with the root; this recognizes Windows long-name/8.3 aliases and casing
+ * without weakening containment to a textual approximation.
+ * @param path - canonical target key, which may end in a missing suffix.
+ * @param root - canonical writable root.
+ * @param caseSensitive - whether lexical comparison preserves case; defaults
+ *   to the host filesystem convention used by supported platforms.
+ * @returns whether the target is the root or a descendant of it.
+ */
+export declare function isPathUnder(path: string, root: string, caseSensitive?: boolean): Promise<boolean>;
+//# sourceMappingURL=containment.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `SandboxedFileSystem`: the sandbox-enforcing implementation of the
+ * `@stackstackstack/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
+ * text-storage mechanics — resolve, stat, read/stream, list, the atomic
+ * write and the read-match-write edit critical section — are the local
+ * implementation's, verbatim; this package adds only the per-call POLICY fence
+ * on the two mutations. Reads pass through untouched: every mode permits
+ * reading.
+ *
+ * The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+ * NOT a kernel boundary — the operations are the seam's own (open, rename),
+ * and only the target path is untrusted, so canonicalize-then-contain is the
+ * complete answer to this surface. Kernel-grade isolation of untrusted CODE
+ * stays `ctx.shell`'s job (`@stackstackstack/dsh-bash-sandbox`). This mirrors the
+ * `code-runtime` stance: containment, not a security boundary. The residual
+ * TOCTOU (an ancestor symlink swapped between the containment re-check and the
+ * syscall) is narrowed by re-canonicalizing immediately before delegating and
+ * is accepted for this threat model.
+ *
+ * Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+ * a mutation only when the target canonicalizes under the policy's workspace
+ * root or a platform temp area (the SAME writable-root set Seatbelt grants,
+ * derived from the one `writableRoots` function so bash and fs cannot drift);
+ * `danger-full-access` delegates unfenced. A denial throws the structured
+ * `FS_SANDBOX_DENIED` — no text inference is needed (unlike bash's kernel
+ * stderr), because an in-process fence knows exactly what it refused. The
+ * escalation retry lives in the tool layer (`@stackstackstack/dsh-tool-fs`),
+ * exactly as bash's does.
+ *
+ * @module @stackstackstack/dsh-fs-sandbox
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { LocalFileSystem } from '@stackstackstack/dsh-fs-local';
+import type { Config as LocalConfig } from '@stackstackstack/dsh-fs-local';
+import type { FsEditOutcome, FsEditRequest, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from '@stackstackstack/dsh-fs';
+import type { SandboxExecutionPolicy, SandboxMode } from '@stackstackstack/dsh-sandbox';
+/**
+ * Plugin config: the local backend's knobs verbatim (`cwd` resolution default
+ * and `diffBasisMaxBytes` overwrite-presentation bound). The sandbox default
+ * (mode + `workspace-write` fallback root) is NOT here — `ctx.sandboxPolicy`
+ * resolves each calling session for every enforcing capability.
+ */
+export type Config = LocalConfig;
+/**
+ * Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
+ * INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
+ * swap — the model-facing tools are untouched). Its configured default mode is
+ * the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+ * each session's mode and cwd into a policy for every mutation, while an
+ * approved escalation may stamp a strictly wider mode for one call.
+ */
+export declare class SandboxedFileSystem extends LocalFileSystem {
+    static inject: string[];
+    private readonly defaultMode;
+    constructor(ctx: Context, config: Config);
+    /** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+    get sandboxMode(): SandboxMode;
+    /**
+     * Fence the write by the per-call policy, then delegate to the inherited
+     * atomic write. See {@link checkedTarget}.
+     * @param target - the resolved target to write.
+     * @param content - the full new file content.
+     * @param expected - the write intent guarding the write; omit for unconditional.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+     *   the deployment fallback.
+     * @returns the write outcome from the inherited backend.
+     */
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /**
+     * Fence the edit by the per-call policy, then delegate to the inherited
+     * atomic edit. See {@link checkedTarget}.
+     * @param target - the resolved target to edit.
+     * @param edit - the literal search/replace request.
+     * @param expected - the version guard; omit for an unconditional edit.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+     *   the deployment fallback.
+     * @returns the edit outcome from the inherited backend.
+     */
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    /**
+     * Enforce the per-call policy against `target` and return the EXACT target the
+     * mutation must use, so the checked identity is the mutated one (no
+     * check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+     * re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
+     * reflecting a concurrently swapped symlink), requires containment under a
+     * writable root, and returns THAT fresh target; `danger-full-access` returns
+     * the caller's target unfenced. Throws the structured `FS_SANDBOX_DENIED` on
+     * refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
+     * and the escalation hint.
+     */
+    private checkedTarget;
+}
+export default SandboxedFileSystem;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-fs-sandbox`.
+ * @module @stackstackstack/dsh-fs-sandbox/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "fs-sandbox-invariant";
+/** Services required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stackstackstack/dsh-fs-sandbox",
+  "description": "Sandbox-enforcing implementation of the DeepSeek Harness filesystem seam: fences write/edit by the per-call sandbox mode (read-only denies mutation, workspace-write contains it to the workspace + temp roots) while reads pass through",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/fs/fs-sandbox"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-fs": "^0.1.5",
+    "@stackstackstack/dsh-fs-local": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-sandbox": "^0.1.5",
+    "@stackstackstack/dsh-sandbox-policy": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-fs-local": "^0.1.5",
+    "@stackstackstack/dsh-fs": "^0.1.5",
+    "@stackstackstack/dsh-sandbox-policy": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-sandbox": "^0.1.5"
+  }
+}