@exagone313/dsh-podman 0.2.0-rc.4 → 0.2.0

package/dist/containers.test.js

@@ -3,8 +3,8 @@
 // SPDX-License-Identifier: MIT
 import test from "node:test";
 import assert from "node:assert/strict";
-import { WORKSPACE_ID, fakeToolContext, guestExecRecorder, guestFileRecorder, secretBearingResolver } from "./test-support.js";
-import { TOOLS, podmanRuntimeSection, resolveGuestCwd, resolveGuestPath, toolHandlers, } from "./index.js";
+import { fakeToolContext, guestExecRecorder, guestFileRecorder, secretBearingResolver, WORKSPACE_ID, } from "./test-support.js";
+import { podmanRuntimeSection, resolveGuestCwd, resolveGuestPath, toolHandlers, TOOLS, } from "./index.js";
 test("container start/recreate/bash accept an env map schema", () => {
     for (const name of ["container_start", "container_recreate", "container_bash"]) {
         const tool = TOOLS.find((entry) => entry.name === name);
@@ -96,11 +96,34 @@ test("container tools never expose internal fields in their results", async () =
     const cases = [
         [toolHandlers.container_start, { container: "default", image: "img-1" }],
         [toolHandlers.container_recreate, { container: "default" }],
-        [toolHandlers.container_mount_add, { container: "default", kind: "volume", volume: "v", destination: "/data" }],
-        [toolHandlers.container_mount_remove, { container: "default", kind: "volume", volume: "v", destination: "/data" }],
-        [toolHandlers.container_mount_update, { container: "default", kind: "volume", volume: "v", destination: "/data", mode: "read_only" }],
-        [toolHandlers.container_secret_add, { container: "default", env: "DB_PASS", secret: "db-pass" }],
-        [toolHandlers.container_secret_remove, { container: "default", env: "DB_PASS" }],
+        [toolHandlers.container_mount_add, {
+                container: "default",
+                kind: "volume",
+                volume: "v",
+                destination: "/data",
+            }],
+        [toolHandlers.container_mount_remove, {
+                container: "default",
+                kind: "volume",
+                volume: "v",
+                destination: "/data",
+            }],
+        [toolHandlers.container_mount_update, {
+                container: "default",
+                kind: "volume",
+                volume: "v",
+                destination: "/data",
+                mode: "read_only",
+            }],
+        [toolHandlers.container_secret_add, {
+                container: "default",
+                env: "DB_PASS",
+                secret: "db-pass",
+            }],
+        [toolHandlers.container_secret_remove, {
+                container: "default",
+                env: "DB_PASS",
+            }],
     ];
     for (const [handler, input] of cases) {
         const out = await handler(secretBearingResolver(), input, exec);
@@ -148,7 +171,11 @@ test("container start and recreate forward PATH additions", async () => {
         getConfig: () => ({ projectsRoot: "/projects" }),
         control: async (method, request) => {
             calls.push([method, request]);
-            return { containerName: "default", status: "running", paths: ["/opt/bin"] };
+            return {
+                containerName: "default",
+                status: "running",
+                paths: ["/opt/bin"],
+            };
         },
     };
     const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
@@ -159,6 +186,97 @@ test("container start and recreate forward PATH additions", async () => {
     assert.deepEqual(calls[1][1].paths, ["/usr/local/bin"]);
     assert.deepEqual(recreated.paths, ["/opt/bin"]);
 });
+test("container_start seeds the default environment into a new container", async () => {
+    const calls = [];
+    const resolver = {
+        registry: { resolveByPath: async () => ({ id: WORKSPACE_ID }) },
+        getConfig: () => ({
+            projectsRoot: "/projects",
+            containerEnv: { GIT_AUTHOR_NAME: "John Doe" },
+        }),
+        control: async (method, request) => {
+            calls.push([method, request]);
+            if (method === "listContainers")
+                return { containers: [] };
+            return { containerName: "web", status: "running" };
+        },
+    };
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    await toolHandlers.container_start(resolver, { container: "web", image: "img-1" }, exec);
+    assert.deepEqual(calls.map(([method]) => method), ["listContainers", "startContainer"]);
+    const start = calls.find(([method]) => method === "startContainer");
+    assert.deepEqual(start[1].env, { GIT_AUTHOR_NAME: "John Doe" });
+});
+test("container_start keeps an existing container's environment", async () => {
+    const calls = [];
+    const resolver = {
+        registry: { resolveByPath: async () => ({ id: WORKSPACE_ID }) },
+        getConfig: () => ({
+            projectsRoot: "/projects",
+            containerEnv: { GIT_AUTHOR_NAME: "John Doe" },
+        }),
+        control: async (method, request) => {
+            calls.push([method, request]);
+            if (method === "listContainers") {
+                return {
+                    containers: [
+                        {
+                            workspaceSlug: WORKSPACE_ID,
+                            containerName: "web",
+                            env: { KEEP: "1" },
+                        },
+                    ],
+                };
+            }
+            return { containerName: "web", status: "running" };
+        },
+    };
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    await toolHandlers.container_start(resolver, { container: "web", image: "img-1" }, exec);
+    const start = calls.find(([method]) => method === "startContainer");
+    assert.equal("env" in start[1], false, "a stored environment must survive a start");
+});
+test("container_start lets the caller's environment win over the defaults", async () => {
+    const calls = [];
+    const resolver = {
+        registry: { resolveByPath: async () => ({ id: WORKSPACE_ID }) },
+        getConfig: () => ({
+            projectsRoot: "/projects",
+            containerEnv: {
+                GIT_AUTHOR_NAME: "John Doe",
+                GIT_AUTHOR_EMAIL: "john.doe@git.example",
+            },
+        }),
+        control: async (method, request) => {
+            calls.push([method, request]);
+            return { containerName: "web", status: "running" };
+        },
+    };
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    await toolHandlers.container_start(resolver, { container: "web", image: "img-1", env: { GIT_AUTHOR_NAME: "Other" } }, exec);
+    assert.deepEqual(calls.map(([method]) => method), ["startContainer"]);
+    assert.deepEqual(calls[0][1].env, {
+        GIT_AUTHOR_NAME: "Other",
+        GIT_AUTHOR_EMAIL: "john.doe@git.example",
+    });
+});
+test("container_recreate never injects the default environment", async () => {
+    const calls = [];
+    const resolver = {
+        registry: { resolveByPath: async () => ({ id: WORKSPACE_ID }) },
+        getConfig: () => ({
+            projectsRoot: "/projects",
+            containerEnv: { GIT_AUTHOR_NAME: "John Doe" },
+        }),
+        control: async (method, request) => {
+            calls.push([method, request]);
+            return { containerName: "default", status: "running" };
+        },
+    };
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    await toolHandlers.container_recreate(resolver, { container: "default" }, exec);
+    assert.equal("env" in calls[0][1], false, "a recreate stores what it is given");
+});
 test("resolveGuestPath resolves relative paths and refuses traversal", () => {
     assert.equal(resolveGuestPath("/abs/file", "/projects/team"), "/abs/file");
     assert.equal(resolveGuestPath("README.md", "/projects/team"), "/projects/team/README.md");
@@ -207,10 +325,21 @@ test("container_read reports a missing file and records it as absent", async ()
 test("container_edit requires a unique match unless replace_all is set", async () => {
     const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
     const duplicate = guestFileRecorder("a a a");
-    await assert.rejects(() => toolHandlers.container_edit(duplicate.resolver, { container: "default", file_path: "f", old_string: "a", new_string: "b" }, exec, fakeToolContext(duplicate.resolver)), /matched 3 times/);
+    await assert.rejects(() => toolHandlers.container_edit(duplicate.resolver, {
+        container: "default",
+        file_path: "f",
+        old_string: "a",
+        new_string: "b",
+    }, exec, fakeToolContext(duplicate.resolver)), /matched 3 times/);
     assert.deepEqual(duplicate.writes, [], "a non-unique match must not be written");
     const all = guestFileRecorder("a a a");
-    await toolHandlers.container_edit(all.resolver, { container: "default", file_path: "f", old_string: "a", new_string: "b", replace_all: true }, exec, fakeToolContext(all.resolver));
+    await toolHandlers.container_edit(all.resolver, {
+        container: "default",
+        file_path: "f",
+        old_string: "a",
+        new_string: "b",
+        replace_all: true,
+    }, exec, fakeToolContext(all.resolver));
     assert.equal(all.writes[0].content, "b b b");
 });
 test("container command and file tools mirror the built-in arguments", () => {
@@ -249,8 +378,9 @@ test("container_bash enforces timeoutMs", async () => {
             return {
                 on(event, handler) {
                     (handlers[event] ??= []).push(handler);
-                    if (event === "data")
+                    if (event === "data") {
                         queueMicrotask(() => handler({ processId: "42" }));
+                    }
                 },
                 write() { },
                 end() { },
@@ -269,7 +399,12 @@ test("container_bash enforces timeoutMs", async () => {
             defaultCwd: "/projects/team",
         }),
     };
-    await assert.rejects(() => toolHandlers.container_bash(resolver, { container: "default", command: "sleep", description: "x", timeoutMs: 10 }, exec), /timed out/);
+    await assert.rejects(() => toolHandlers.container_bash(resolver, {
+        container: "default",
+        command: "sleep",
+        description: "x",
+        timeoutMs: 10,
+    }, exec), /timed out/);
     assert.equal(signaled.processId, "42");
     assert.equal(signaled.signal, "SIGTERM");
 });
@@ -314,17 +449,34 @@ test("container_grep resolves its search path like a shell would", async () => {
     // With a search path, it is relative to the session directory.
     const plain = guestExecRecorder("/projects/team");
     await toolHandlers.container_grep(plain.resolver, { container: "default", pattern: "TODO", path: "src" }, exec);
-    assert.deepEqual(plain.starts[0].argv, ["/usr/bin/rg", "-n", "TODO", "/projects/team/src"]);
+    assert.deepEqual(plain.starts[0].argv, [
+        "/usr/bin/rg",
+        "-n",
+        "TODO",
+        "/projects/team/src",
+    ]);
     // An include filter maps to ripgrep's --glob.
     const filtered = guestExecRecorder("/projects/team");
     await toolHandlers.container_grep(filtered.resolver, { container: "default", pattern: "TODO", path: "src", include: "*.ts" }, exec);
-    assert.deepEqual(filtered.starts[0].argv, ["/usr/bin/rg", "-n", "--glob", "*.ts", "TODO", "/projects/team/src"]);
+    assert.deepEqual(filtered.starts[0].argv, [
+        "/usr/bin/rg",
+        "-n",
+        "--glob",
+        "*.ts",
+        "TODO",
+        "/projects/team/src",
+    ]);
     assert.equal(filtered.starts[0].cwd, "/projects/team");
     const none = guestExecRecorder("/projects/team");
     await toolHandlers.container_grep(none.resolver, { container: "default", pattern: "TODO" }, exec);
     // No path searches the session workspace explicitly: ripgrep would otherwise
     // read its (non-TTY) stdin instead of the working directory.
-    assert.deepEqual(none.starts[0].argv, ["/usr/bin/rg", "-n", "TODO", "/projects/team"]);
+    assert.deepEqual(none.starts[0].argv, [
+        "/usr/bin/rg",
+        "-n",
+        "TODO",
+        "/projects/team",
+    ]);
     assert.equal(none.starts[0].cwd, "/projects/team");
 });
 test("container_glob passes the pattern as a glob and scopes the search", async () => {
@@ -360,7 +512,8 @@ test("container_glob passes the pattern as a glob and scopes the search", async
 });
 test("container_glob caps its result at 100 files", async () => {
     const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
-    const lines = (count) => Array.from({ length: count }, (_, index) => `file-${index}.ts`).join("\n") + "\n";
+    const lines = (count) => Array.from({ length: count }, (_, index) => `file-${index}.ts`).join("\n") +
+        "\n";
     const small = guestExecRecorder("/projects/team", lines(3));
     const few = (await toolHandlers.container_glob(small.resolver, { container: "default", pattern: "*" }, exec));
     assert.equal(few.files.length, 3);
@@ -401,7 +554,9 @@ test("podmanRuntimeSection names only the tools the agent has", () => {
     assert.doesNotMatch(full, /plugin/i);
     // The Podman operator preset mounts none of them, so the wording must not
     // name a tool the agent cannot call.
-    const containerOnly = podmanRuntimeSection({ tools: { get: () => undefined } });
+    const containerOnly = podmanRuntimeSection({
+        tools: { get: () => undefined },
+    });
     const short = containerOnly.text({ scope: "agent" });
     for (const tool of ["bash", "read", "write", "edit", "glob", "grep"]) {
         assert.doesNotMatch(short, new RegExp("`" + tool + "`"));
@@ -416,6 +571,27 @@ test("podmanRuntimeSection names only the tools the agent has", () => {
     assert.match(short, /daemon_\*/);
     assert.match(short, /share the host kernel/);
 });
+test("podmanRuntimeSection guides the model to custom images and named volumes", () => {
+    const variants = [
+        podmanRuntimeSection({ tools: { get: () => ({}) } }),
+        podmanRuntimeSection({ tools: { get: () => undefined } }),
+    ];
+    for (const section of variants) {
+        const text = section.text({ scope: "agent" });
+        // Software installs belong in an image, not a running container.
+        assert.match(text, /custom image/);
+        assert.match(text, /`image_build`/);
+        assert.match(text, /`container_start`/);
+        assert.match(text, /`container_recreate`/);
+        // Persistence belongs in a named volume, not a tmpfs.
+        assert.match(text, /named `volume`/);
+        assert.match(text, /`tmpfs`/);
+        assert.match(text, /\/tmp/);
+        assert.match(text, /clears tmpfs contents/);
+        // The guidance stays free of plugin lore: the section reads as facts.
+        assert.doesNotMatch(text, /plugin/i);
+    }
+});
 test("container_grep fails loudly when ripgrep reports an error", async () => {
     const guest = {
         exec: () => {
@@ -427,7 +603,9 @@ test("container_grep fails loudly when ripgrep reports an error", async () => {
                 write() { },
                 end() {
                     for (const handler of handlers.data ?? []) {
-                        handler({ stderrChunk: Buffer.from("rg: error parsing glob '[bad'\n") });
+                        handler({
+                            stderrChunk: Buffer.from("rg: error parsing glob '[bad'\n"),
+                        });
                         handler({ exit: { exitCode: 2, signaled: false } });
                     }
                 },

package/dist/daemons.test.js

@@ -4,7 +4,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { DAEMON_TOOLS } from "./test-support.js";
-import { TOOLS, publicDaemon, toolHandlers } from "./index.js";
+import { publicDaemon, toolHandlers, TOOLS } from "./index.js";
 test("daemon_start accepts optional uid, gid and groups", () => {
     const tool = TOOLS.find((entry) => entry.name === "daemon_start");
     assert.ok(tool, "daemon_start registered");
@@ -69,10 +69,20 @@ test("daemon tools require no approval and are valid object-rooted schemas", ()
     }
 });
 test("publicDaemon omits the exit code while the daemon runs", () => {
-    const running = publicDaemon({ name: "web", argv: ["sleep", "600"], running: true, exitCode: 0 });
+    const running = publicDaemon({
+        name: "web",
+        argv: ["sleep", "600"],
+        running: true,
+        exitCode: 0,
+    });
     assert.equal(running.running, true);
     assert.equal("exitCode" in running, false);
-    const exited = publicDaemon({ name: "web", argv: ["sleep", "600"], running: false, exitCode: 3 });
+    const exited = publicDaemon({
+        name: "web",
+        argv: ["sleep", "600"],
+        running: false,
+        exitCode: 3,
+    });
     assert.equal(exited.running, false);
     assert.equal(exited.exitCode, 3);
 });
@@ -111,7 +121,11 @@ test("daemon_start returns a daemon info object", async () => {
         }),
     };
     const exec = { agent: { session: { header: { cwd: "/proj" } } } };
-    const out = await toolHandlers.daemon_start(resolver, { container: "default", argv: ["python3", "-m", "http.server", "8000"], name: "web" }, exec);
+    const out = await toolHandlers.daemon_start(resolver, {
+        container: "default",
+        argv: ["python3", "-m", "http.server", "8000"],
+        name: "web",
+    }, exec);
     assert.deepEqual(out, {
         name: "web",
         running: true,

package/dist/dsh-version.js

@@ -20,7 +20,8 @@ export function dshVersion() {
 function resolveDshVersion() {
     let searchPaths;
     try {
-        searchPaths = createRequire(import.meta.url).resolve.paths("@deepseek-ai/dsh") ?? [];
+        searchPaths =
+            createRequire(import.meta.url).resolve.paths("@deepseek-ai/dsh") ?? [];
     }
     catch {
         return undefined;

package/dist/env-rows.d.ts

@@ -0,0 +1,14 @@
+export interface EnvDraft {
+    key: string;
+    value: string;
+}
+export interface EnvRow extends EnvDraft {
+    pending: boolean;
+}
+export declare function emptyEnvDraft(): EnvDraft;
+export declare function envRows(env: Record<string, string>, draft: EnvDraft | undefined): EnvRow[];
+export declare function envKeyAvailable(env: Record<string, string>, key: string): boolean;
+export declare function commitEnvDraft(env: Record<string, string>, draft: EnvDraft): Record<string, string> | undefined;
+export declare function renameEnvKey(env: Record<string, string>, index: number, key: string): Record<string, string>;
+export declare function setEnvValue(env: Record<string, string>, index: number, value: string): Record<string, string>;
+export declare function removeEnvRow(env: Record<string, string>, index: number): Record<string, string>;

package/dist/env-rows.js

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+export function emptyEnvDraft() {
+    return { key: "", value: "" };
+}
+export function envRows(env, draft) {
+    const rows = Object.entries(env).map(([key, value]) => ({
+        key,
+        value,
+        pending: false,
+    }));
+    if (draft !== undefined)
+        rows.push({ ...draft, pending: true });
+    return rows;
+}
+// Whether a draft's key can become a variable: non-empty and not already used.
+export function envKeyAvailable(env, key) {
+    return key !== "" && !Object.prototype.hasOwnProperty.call(env, key);
+}
+// commitEnvDraft appends the draft to the record once its key is usable, or
+// returns undefined so the caller keeps the row open instead of inventing a
+// placeholder variable name.
+export function commitEnvDraft(env, draft) {
+    if (!envKeyAvailable(env, draft.key))
+        return undefined;
+    return { ...env, [draft.key]: draft.value };
+}
+// Every mutation rebuilds the record in order, so a renamed key stays in place
+// instead of jumping to the end.
+export function renameEnvKey(env, index, key) {
+    const next = {};
+    Object.entries(env).forEach(([current, value], at) => {
+        next[at === index ? key : current] = value;
+    });
+    return next;
+}
+export function setEnvValue(env, index, value) {
+    const next = {};
+    Object.entries(env).forEach(([key, current], at) => {
+        next[key] = at === index ? value : current;
+    });
+    return next;
+}
+export function removeEnvRow(env, index) {
+    const next = {};
+    Object.entries(env).forEach(([key, value], at) => {
+        if (at !== index)
+            next[key] = value;
+    });
+    return next;
+}

package/dist/env-rows.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/env-rows.test.js

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { commitEnvDraft, emptyEnvDraft, envKeyAvailable, envRows, removeEnvRow, renameEnvKey, setEnvValue, } from "./env-rows.js";
+test("envRows lists the committed entries and then the pending draft", () => {
+    assert.deepEqual(envRows({}, undefined), []);
+    assert.deepEqual(envRows({ A: "1" }, undefined), [
+        { key: "A", value: "1", pending: false },
+    ]);
+    assert.deepEqual(envRows({ A: "1", B: "2" }, emptyEnvDraft()), [
+        { key: "A", value: "1", pending: false },
+        { key: "B", value: "2", pending: false },
+        { key: "", value: "", pending: true },
+    ]);
+});
+test("envKeyAvailable accepts only a new, non-empty key", () => {
+    assert.equal(envKeyAvailable({}, ""), false);
+    assert.equal(envKeyAvailable({ A: "1" }, "A"), false);
+    assert.equal(envKeyAvailable({ A: "1" }, "B"), true);
+    // A key inherited from the prototype is not an existing variable.
+    assert.equal(envKeyAvailable({}, "toString"), true);
+});
+test("commitEnvDraft refuses an empty or duplicate key", () => {
+    assert.equal(commitEnvDraft({}, { key: "", value: "x" }), undefined);
+    assert.equal(commitEnvDraft({ A: "1" }, { key: "A", value: "x" }), undefined);
+});
+test("commitEnvDraft appends an accepted key with its value", () => {
+    assert.deepEqual(commitEnvDraft({ A: "1" }, { key: "B", value: "2" }), {
+        A: "1",
+        B: "2",
+    });
+    assert.deepEqual(commitEnvDraft({}, { key: "B", value: "" }), { B: "" });
+});
+test("env transformations keep row order", () => {
+    const env = { A: "1", B: "2", C: "3" };
+    assert.deepEqual(renameEnvKey(env, 1, "BB"), { A: "1", BB: "2", C: "3" });
+    assert.deepEqual(setEnvValue(env, 2, "33"), { A: "1", B: "2", C: "33" });
+    assert.deepEqual(removeEnvRow(env, 0), { B: "2", C: "3" });
+    // The input record is never mutated.
+    assert.deepEqual(env, { A: "1", B: "2", C: "3" });
+});

package/dist/fs-provider.d.ts

@@ -19,5 +19,6 @@ export interface FilesystemProvider {
     mkdir(target: any, parents?: boolean): Promise<any>;
     remove(target: any, recursive?: boolean): Promise<any>;
     editText(target: any, edit: any, expected?: any, signal?: AbortSignal): Promise<any>;
+    watch(target: any, changed: (error?: Error) => void, signal?: AbortSignal): Promise<() => Promise<void>>;
 }
 export declare function createFilesystemProvider(resolver: WorkspaceResolver): FilesystemProvider;

package/dist/fs-provider.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
 //
 // SPDX-License-Identifier: MIT
-import { DIFF_BASIS_MAX_BYTES, detectLineEndings, fsError, guestChunks, guestStat, guestStatResponse, guestTextChunks, guestVersion, normalizeLineEndings, readDiffBasis, readGuestText, resolveGuestPath, restoreLineEndings, throwIfAborted, unaryGuest, writeGuestFile, } from "./guest-rpc.js";
+import { detectLineEndings, DIFF_BASIS_MAX_BYTES, fsError, guestChunks, guestStat, guestStatResponse, guestTextChunks, guestVersion, normalizeLineEndings, readDiffBasis, readGuestText, resolveGuestPath, restoreLineEndings, throwIfAborted, unaryGuest, writeGuestFile, } from "./guest-rpc.js";
 import { isAbsolute, join, resolve as resolvePath } from "node:path";
 export function createFilesystemProvider(resolver) {
     return {
@@ -10,10 +10,12 @@ export function createFilesystemProvider(resolver) {
             const resolved = resolveGuestPath(path, opts?.cwd);
             // An explicit container targets that container's guest; the harness's own
             // tools never pass one and keep the session workspace's default.
-            const container = typeof opts?.container === "string" ? opts.container : "";
+            const container = typeof opts?.container === "string"
+                ? opts.container
+                : "";
             const binding = container !== "" && container !== "default"
-                ? await resolver.containerBinding(opts?.cwd, container)
-                : await resolver.resolveForPath(resolved, opts?.cwd);
+                ? await resolver.containerBinding(opts?.cwd, container, opts?.signal)
+                : await resolver.resolveForPath(resolved, opts?.cwd, opts?.signal);
             return {
                 targetKey: resolved,
                 displayPath: resolved,
@@ -55,7 +57,7 @@ export function createFilesystemProvider(resolver) {
         lstat: async (path, opts, signal) => {
             throwIfAborted(signal, "lstat");
             const resolved = resolveGuestPath(path, opts?.cwd);
-            const binding = await resolver.resolveForPath(resolved, opts?.cwd);
+            const binding = await resolver.resolveForPath(resolved, opts?.cwd, signal);
             const result = await unaryGuest({ binding }, "stat", { path: resolved, noFollow: true }, signal);
             if (!result?.exists)
                 return undefined;
@@ -90,16 +92,18 @@ export function createFilesystemProvider(resolver) {
             else if (expected?.kind === "createIfAbsent" && current.exists) {
                 throw fsError("FS_NOT_OBSERVED", `cannot overwrite existing "${target.displayPath}" without reading it first`);
             }
-            // The basis is gated on the incoming content, like the local backend:
-            // either side at/above the limit yields `before: null` and the consumer
-            // falls back to a whole-file diff. Both sides are LF-normalized so a CRLF
-            // overwrite does not read as every line changed.
+            // The basis is gated on both sides: an incoming or existing file at or
+            // above the limit yields `before: null` and the consumer falls back to a
+            // whole-file diff, so writing one byte into a huge file does not read the
+            // whole file back just for presentation. Both sides are LF-normalized so
+            // a CRLF overwrite does not read as every line changed.
             const rawBasis = current.exists &&
-                Buffer.byteLength(content, "utf8") < DIFF_BASIS_MAX_BYTES
+                Buffer.byteLength(content, "utf8") < DIFF_BASIS_MAX_BYTES &&
+                Number(current.size ?? 0) < DIFF_BASIS_MAX_BYTES
                 ? await readDiffBasis(target, signal)
                 : null;
             const before = rawBasis === null ? null : normalizeLineEndings(rawBasis);
-            await writeGuestFile({ guest: target.binding.guest, token: target.binding.token }, target.targetKey, content, { create: true, truncate: true }, signal);
+            await writeGuestFile(target.binding, target.targetKey, content, { create: true, truncate: true }, signal);
             const after = await guestStatResponse(target, signal);
             return {
                 operation: current.exists ? "update" : "create",
@@ -172,7 +176,7 @@ export function createFilesystemProvider(resolver) {
                 throw fsError("FS_AMBIGUOUS_EDIT", `old_string matched ${occurrences} times in "${target.displayPath}"; provide a more specific old_string or set replace_all to true`);
             }
             const after = before.split(oldNorm).join(newNorm);
-            await writeGuestFile({ guest: target.binding.guest, token: target.binding.token }, target.targetKey, restoreLineEndings(after, lineEndings), { create: true, truncate: true }, signal);
+            await writeGuestFile(target.binding, target.targetKey, restoreLineEndings(after, lineEndings), { create: true, truncate: true }, signal);
             const afterInfo = await guestStatResponse(target, signal);
             return {
                 version: guestVersion(afterInfo),
@@ -180,5 +184,15 @@ export function createFilesystemProvider(resolver) {
                 after,
             };
         },
+        // Watching would need a watcher inside each workspace's container (inotify
+        // in the guest, or host-side polling of every open tree node), and every
+        // container here is remote and disposable. Report the seam's typed
+        // "unsupported" failure instead, as the harness's SSH provider does: the
+        // workspace file tree then refreshes on demand rather than live. `changed`
+        // is never called — the promise rejects before a watcher becomes active.
+        watch: (_target, _changed, signal) => {
+            throwIfAborted(signal, "watch");
+            return Promise.reject(fsError("FS_IO_ERROR", "Filesystem watching is not supported by this provider."));
+        },
     };
 }