fix(e2b): address review feedback on volume mounts

- Keep E2bSandboxState forward compatible with
  @JsonIgnoreProperties(ignoreUnknown = true) so states written with
  mounts load on older builds instead of falling back to fresh create
- Fix tarExcludeArgsForAbsolutePaths for workspaceRoot "/" and
  collapse duplicate slashes, matching E2bVolumeMount normalization
- Keep E2bCloudBucketMountStrategy as @deprecated for one transition
  release instead of removing the public interface outright
- Centralize distinct-mount-path validation in E2bVolumeMount and
  enforce it in E2bSandboxState.setVolumeMounts as well
- Add unit tests for the volume-critical branches (persist no-op,
  empty hydrate, destroy skip), "/" excludes, state validation and
  unknown-field serde so CI catches regressions
- Fix misplaced javadoc on requireAbsoluteWorkspaceRoot and enforce
  the absolute-root check in resume() too
- Require E2B_VOLUME_NAME for live tests instead of a hardcoded
  default volume
- Document read-write/multi-mount/no-locking volume semantics

Refs: #3155

Author: chcodex

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/main/java/io/agentscope/extensions/sandbox/e2b/E2bSandboxClient.java

@@ -88,6 +88,7 @@ public Sandbox resume(SandboxState state) {
             throw new IllegalArgumentException(
                     "Expected E2bSandboxState but got: " + state.getClass().getName());
         }
+        requireAbsoluteWorkspaceRoot(e2b.getWorkspaceRoot());
         E2bSandboxClientOptions resumed = copy(defaultOptions);
         resumed.setCodec(e2b.getCodec());
         resumed.setEnvdSandboxUrl(e2b.getEnvdSandboxUrl());
@@ -175,10 +176,10 @@ private E2bSandboxClientOptions merge(E2bSandboxClientOptions call) {
     }
 
     /**
-     * Returns whether the workspace root lives on one of the configured volume mounts.
+     * Rejects blank or relative workspace roots fail-fast; every E2B operation assumes an
+     * absolute in-sandbox path.
      *
-     * @param opt merged client options
-     * @return true when a mount covers the workspace root
+     * @param workspaceRoot workspace root to check
      */
     private static void requireAbsoluteWorkspaceRoot(String workspaceRoot) {
         if (workspaceRoot == null
@@ -190,6 +191,12 @@ private static void requireAbsoluteWorkspaceRoot(String workspaceRoot) {
         }
     }
 
+    /**
+     * Returns whether the workspace root lives on one of the configured volume mounts.
+     *
+     * @param opt merged client options
+     * @return true when a mount covers the workspace root
+     */
     private static boolean isWorkspaceOnVolume(E2bSandboxClientOptions opt) {
         String root = opt.getWorkspaceRoot();
         if (root == null || root.isBlank() || opt.getVolumeMounts() == null) {

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/main/java/io/agentscope/extensions/sandbox/e2b/E2bSandboxClientOptions.java

@@ -17,7 +17,6 @@
 
 import io.agentscope.harness.agent.sandbox.SandboxClient;
 import io.agentscope.harness.agent.sandbox.SandboxClientOptions;
-import io.agentscope.harness.agent.sandbox.SandboxException;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -235,7 +234,7 @@ public void setVolumeMounts(List<E2bVolumeMount> volumeMounts) {
                 checked.add(new E2bVolumeMount(m.getName(), m.getPath()));
             }
         }
-        requireDistinctMountPaths(checked);
+        E2bVolumeMount.requireDistinctMountPaths(checked);
         this.volumeMounts = checked;
     }
 
@@ -253,18 +252,6 @@ public E2bSandboxClientOptions addVolumeMount(E2bVolumeMount mount) {
         return addVolumeMount(mount.getName(), mount.getPath());
     }
 
-    private static void requireDistinctMountPaths(List<E2bVolumeMount> mounts) {
-        for (int i = 0; i < mounts.size(); i++) {
-            for (int j = i + 1; j < mounts.size(); j++) {
-                if (mounts.get(i).getPath().equals(mounts.get(j).getPath())) {
-                    throw new SandboxException.SandboxConfigurationException(
-                            "E2B volume mounts must use distinct paths, duplicated: "
-                                    + mounts.get(i).getPath());
-                }
-            }
-        }
-    }
-
     public int getConnectTimeoutSeconds() {
         return connectTimeoutSeconds;
     }

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/main/java/io/agentscope/extensions/sandbox/e2b/E2bSandboxState.java

@@ -15,11 +15,13 @@
  */
 package io.agentscope.extensions.sandbox.e2b;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import io.agentscope.harness.agent.sandbox.SandboxState;
 import java.util.ArrayList;
 import java.util.List;
 
 /** Serializable state for an E2B-backed sandbox. */
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class E2bSandboxState extends SandboxState {
 
     private String sandboxId;
@@ -166,6 +168,7 @@ public void setVolumeMounts(List<E2bVolumeMount> volumeMounts) {
                 checked.add(new E2bVolumeMount(m.getName(), m.getPath()));
             }
         }
+        E2bVolumeMount.requireDistinctMountPaths(checked);
         this.volumeMounts = checked;
     }
 

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/main/java/io/agentscope/extensions/sandbox/e2b/E2bVolumeMount.java

@@ -16,6 +16,7 @@
 package io.agentscope.extensions.sandbox.e2b;
 
 import io.agentscope.harness.agent.sandbox.SandboxException;
+import java.util.List;
 import java.util.Objects;
 
 /**
@@ -130,6 +131,31 @@ public static boolean coversWorkspaceRoot(String workspaceRoot, String mountPath
         return root.equals(mount) || root.startsWith(mount + "/");
     }
 
+    /**
+     * Validates that no two mounts share the same in-sandbox path.
+     *
+     * @param mounts mounts to check (null entries are ignored)
+     * @throws SandboxException.SandboxConfigurationException when a path is duplicated
+     */
+    public static void requireDistinctMountPaths(List<E2bVolumeMount> mounts) {
+        if (mounts == null) {
+            return;
+        }
+        for (int i = 0; i < mounts.size(); i++) {
+            if (mounts.get(i) == null) {
+                continue;
+            }
+            for (int j = i + 1; j < mounts.size(); j++) {
+                if (mounts.get(j) != null
+                        && mounts.get(i).getPath().equals(mounts.get(j).getPath())) {
+                    throw new SandboxException.SandboxConfigurationException(
+                            "E2B volume mounts must use distinct paths, duplicated: "
+                                    + mounts.get(i).getPath());
+                }
+            }
+        }
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) {

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/main/java/io/agentscope/extensions/sandbox/e2b/mounts/E2bCloudBucketMountStrategy.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.agentscope.extensions.sandbox.e2b.mounts;
+
+/**
+ * Placeholder for E2B cloud bucket mount configuration.
+ *
+ * @deprecated Superseded by {@link io.agentscope.extensions.sandbox.e2b.E2bVolumeMount}
+ *     attach-at-create mounts. Kept for one transition release so downstream consumers
+ *     referencing this type keep compiling; it carries no behavior and will be removed
+ *     afterwards.
+ */
+@Deprecated
+public interface E2bCloudBucketMountStrategy {
+    // intentionally empty — extend when wiring E2B volume mounts from Harness workspace specs
+}

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/test/java/io/agentscope/extensions/sandbox/e2b/E2bVolumeMountLiveTest.java

@@ -41,8 +41,8 @@
 import org.slf4j.LoggerFactory;
 
 // Live E2B volume tests: run only when E2B_API_KEY is set in the environment.
-// Volume name comes from E2B_VOLUME_NAME (defaults to probe-ws-test1, so set it when your
-// account uses a different volume).
+// E2B_VOLUME_NAME must name an existing volume on the account (no default:
+// the platform answers an unknown name with an opaque 400).
 // Each test kills every sandbox it creates, even on failure.
 @EnabledIfEnvironmentVariable(named = "E2B_API_KEY", matches = ".+")
 class E2bVolumeMountLiveTest {
@@ -409,7 +409,11 @@ void nestedMountContentSurvivesNativeSnapshotRestoreUnchanged() throws Exception
 
     private static String volumeName() {
         String v = System.getenv("E2B_VOLUME_NAME");
-        return v != null && !v.isBlank() ? v : "probe-ws-test1";
+        if (v == null || v.isBlank()) {
+            throw new IllegalStateException(
+                    "E2B_VOLUME_NAME must be set to an existing E2B volume name for live tests");
+        }
+        return v;
     }
 
     private static E2bSandboxClientOptions baseOptions() {

agentscope-extensions/agentscope-extensions-sandbox/agentscope-extensions-sandbox-e2b/src/test/java/io/agentscope/extensions/sandbox/e2b/E2bVolumeMountTest.java

@@ -305,6 +305,61 @@ void tarCommandQuotesExcludeArgs() throws Exception {
                 "exclude with spaces must be shell-quoted, got: " + script);
     }
 
+    @Test
+    void workspaceOnVolumeBranchesAreNoOpsWithoutEnvd() throws Exception {
+        E2bSandboxState state = new E2bSandboxState();
+        state.setWorkspaceSpec(workspaceSpec());
+        state.setWorkspaceRoot("/mnt/data/ws");
+        state.setVolumeMounts(List.of(new E2bVolumeMount("vol-a", "/mnt/data")));
+        state.setWorkspaceOnVolume(true);
+        // No sandboxId and no reachable envd: any backend call would fail,
+        // proving the no-op branches short-circuit before touching envd.
+        E2bSandbox sandbox = new E2bSandbox(state, options());
+
+        try (java.io.InputStream archive = sandbox.persistWorkspace()) {
+            assertEquals(0, archive.readAllBytes().length);
+        }
+        sandbox.hydrateWorkspace(java.io.InputStream.nullInputStream());
+        invokeDoDestroyWorkspace(sandbox);
+    }
+
+    @Test
+    void stateRejectsDuplicateMountPaths() {
+        E2bSandboxState state = new E2bSandboxState();
+        assertThrows(
+                SandboxException.SandboxConfigurationException.class,
+                () ->
+                        state.setVolumeMounts(
+                                List.of(
+                                        new E2bVolumeMount("vol-a", "/mnt/data"),
+                                        new E2bVolumeMount("vol-b", "/mnt/data/"))));
+    }
+
+    @Test
+    void serdeIgnoresUnknownFieldsForForwardCompat() {
+        E2bSandboxClient client = new E2bSandboxClient();
+        E2bSandboxState read =
+                (E2bSandboxState)
+                        client.deserializeState(
+                                "{\"type\":\"e2b\",\"sessionId\":\"fwd\",\"workspaceRoot\":\"/home/user\","
+                                    + "\"someFutureField\":1}");
+        assertEquals("fwd", read.getSessionId());
+        assertTrue(read.getVolumeMounts().isEmpty());
+    }
+
+    private static void invokeDoDestroyWorkspace(E2bSandbox sandbox) throws Exception {
+        java.lang.reflect.Method m = E2bSandbox.class.getDeclaredMethod("doDestroyWorkspace");
+        m.setAccessible(true);
+        try {
+            m.invoke(sandbox);
+        } catch (java.lang.reflect.InvocationTargetException e) {
+            if (e.getCause() instanceof Exception cause) {
+                throw cause;
+            }
+            throw e;
+        }
+    }
+
     private E2bSandboxClientOptions options() {
         E2bSandboxClientOptions opt = new E2bSandboxClientOptions();
         opt.setApiBaseUrl(server.url("/").toString());

agentscope-harness/src/main/java/io/agentscope/harness/agent/sandbox/WorkspaceMountSupport.java

@@ -95,21 +95,35 @@ public static List<String> tarExcludeArgsForAbsolutePaths(
                 || absoluteMountPaths.isEmpty()) {
             return List.of();
         }
-        String root = stripTrailingSlash(workspaceRoot.replace('\\', '/'));
+        String root = normalizeAbsolutePath(workspaceRoot);
         List<String> args = new ArrayList<>();
         for (String raw : absoluteMountPaths) {
             if (raw == null || raw.isBlank()) {
                 continue;
             }
-            String mount = stripTrailingSlash(raw.replace('\\', '/'));
-            if (!mount.startsWith("/") || mount.equals(root) || !mount.startsWith(root + "/")) {
+            String mount = normalizeAbsolutePath(raw);
+            if (!mount.startsWith("/") || mount.equals(root) || !isBeneath(root, mount)) {
                 continue;
             }
-            args.add("--exclude=./" + mount.substring(root.length() + 1));
+            args.add("--exclude=./" + mount.substring(root.equals("/") ? 1 : root.length() + 1));
         }
         return args;
     }
 
+    private static boolean isBeneath(String root, String mount) {
+        if (root.equals("/")) {
+            return mount.length() > 1;
+        }
+        return mount.startsWith(root + "/");
+    }
+
+    private static String normalizeAbsolutePath(String s) {
+        // Collapse repeated slashes first, then drop the (single) trailing slash: the other
+        // order leaves a trailing slash behind for inputs like "//mnt//data//".
+        String normalized = stripTrailingSlash(s.replace('\\', '/').replaceAll("/+", "/"));
+        return normalized.isEmpty() ? "/" : normalized;
+    }
+
     private static String stripTrailingSlash(String s) {
         if (s.length() > 1 && s.endsWith("/")) {
             return s.substring(0, s.length() - 1);

agentscope-harness/src/test/java/io/agentscope/harness/agent/sandbox/WorkspaceMountSupportTest.java

@@ -96,4 +96,20 @@ void tarExcludeArgsForAbsolutePaths_onlyNestedMounts() {
                         "/home/user/", List.of("/home/user/a/b/")));
         assertEquals(List.of(), WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths(null, null));
     }
+
+    @Test
+    void tarExcludeArgsForAbsolutePaths_rootSlashAndNormalization() {
+        assertEquals(
+                List.of("--exclude=./mnt/data"),
+                WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths("/", List.of("/mnt/data")));
+        assertEquals(
+                List.of("--exclude=./mnt/data"),
+                WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths(
+                        "//", List.of("//mnt//data//")));
+        assertEquals(
+                List.of(), WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths("/", List.of("/")));
+        assertEquals(
+                List.of(),
+                WorkspaceMountSupport.tarExcludeArgsForAbsolutePaths("/", List.of("mnt/data")));
+    }
 }

docs/v2/en/docs/harness/filesystem.md

@@ -224,11 +224,12 @@ Platform 400s (no beta access, unknown volume name) propagate with the response
 
 When `workspaceRoot` sits on a volume mount, TAR workspace persistence becomes a no-op
 (the bytes are already durable) and destroy skips `rm -rf`; native snapshots still run so
-the software environment (installed deps, system state) is preserved. Volume lifecycle
+the software environment (installed deps, system state) is preserved. E2B volumes are
+read-write and can be mounted by multiple sandboxes at once with no locking guarantees —
+treat the workspace-on-volume layout as single-writer. Volume lifecycle
 management (create/delete/list) stays in the E2B dashboard/SDK — this covers attach-at-create
 only.
 
-
 #### Daytona sandbox
 
 ```java