Preserve scheduler share for remote worker paths

Preserve an existing scheduler-side AGI_CLUSTER_SHARE when remote Workers Data Path names a separate worker-visible mount target.\n\nValidated with focused runtime misc support tests.

Author: jpmorard

docs/.docs_source_mirror_stamp.json

@@ -2,8 +2,8 @@
   "file_count": 276,
   "format_version": 1,
   "managed_target": "docs/source",
-  "source_digest_sha256": "8dd710f147ddc9b04c22300de5f726797ac7b477ad545bd3ee0ad21c7f0586fa",
+  "source_digest_sha256": "794fcdd8b7c212d91475c7734f42230331d760eea439a424cc10874055e73595",
   "source_hint": "../thales_agilab/docs/source",
   "sync_tool": "tools/sync_docs_source.py",
-  "target_digest_sha256": "8dd710f147ddc9b04c22300de5f726797ac7b477ad545bd3ee0ad21c7f0586fa"
+  "target_digest_sha256": "794fcdd8b7c212d91475c7734f42230331d760eea439a424cc10874055e73595"
 }

docs/source/distributed-workers.rst

@@ -41,6 +41,10 @@ Before configuring distributed workers, make sure the environment is ready:
   root is ``AGI_CLUSTER_SHARE``; remote workers can see the same backing storage
   through an SSHFS mount at **Workers Data Path**. In cluster mode, do not rely
   on ``AGI_LOCAL_SHARE`` as a fallback.
+- For remote workers, **Workers Data Path** is the worker-visible mount target,
+  not a request to rewrite the scheduler-side ``AGI_CLUSTER_SHARE``. If the
+  scheduler already points ``AGI_CLUSTER_SHARE`` at an absolute share root, AGILAB
+  keeps that root and passes the worker-side path separately.
 - The shared-path rule above applies to remote workers. For a local-only Dask
   cluster, where workers are ``127.0.0.1`` or ``localhost``, the scheduler and
   workers share the same local filesystem. ``AGI_CLUSTER_SHARE`` may therefore
@@ -306,7 +310,8 @@ Use these habits to keep distributed runs predictable:
   **Workers Data Path** as the worker-side SSHFS mount target. These paths may
   differ on mixed operating systems, for example a macOS scheduler path mounted
   under a Linux worker home directory, but they must expose the same backing
-  storage after SSHFS is mounted.
+  storage after SSHFS is mounted. Do not use **Workers Data Path** to replace a
+  preconfigured scheduler share root.
 - Keep local-only and remote-worker clusters distinct. Local-only clusters can
   use a local ``AGI_CLUSTER_SHARE`` path directly; remote-worker clusters need a
   worker-visible shared mount target in **Workers Data Path**.

docs/source/troubleshooting.rst

@@ -125,6 +125,9 @@ your server IP and adjust mount paths as needed. The default ``AGI_CLUSTER_SHARE
 ``clustershare/<user>`` under ``$HOME``. For cluster-enabled apps, that path must be mounted
 and writable on every node: ``AgiEnv`` now fails fast instead of silently falling back
 to ``AGI_LOCAL_SHARE`` or ``$HOME/localshare``. Ensure the chosen path exists and is writable.
+In remote-worker mode, keep ``AGI_CLUSTER_SHARE`` as the scheduler-side share root and
+use **Workers Data Path** for the worker-visible SSHFS mount target; AGILAB preserves an
+existing scheduler share when those paths intentionally differ.
 If you override the default in a multi-user setup, keep one exported share root per user
 instead of pointing several operators at the same writable cluster-share directory.
 The example export below uses a ``nobody:nogroup`` ownership policy so every

src/agilab/core/agi-cluster/src/agi_cluster/agi_distributor/runtime/runtime_misc_support.py

@@ -433,6 +433,22 @@ def _absolute_workers_data_share_root(
         return Path(os.path.normpath(str(share_root)))
 
 
+def _workers_data_path_can_rebind_env_share(
+    env: Any,
+    workers_data_path: str,
+) -> bool:
+    current_share = str(getattr(env, "AGI_CLUSTER_SHARE", "") or "").strip()
+    if not current_share:
+        return True
+    workers_share_abs = _absolute_workers_data_share_root(env, workers_data_path)
+    current_share_abs = _absolute_workers_data_share_root(env, current_share)
+    try:
+        workers_share_abs.relative_to(current_share_abs)
+    except ValueError:
+        return False
+    return True
+
+
 def _apply_workers_data_path_to_env(
     env: Any,
     workers_data_path: str | None,
@@ -442,6 +458,8 @@ def _apply_workers_data_path_to_env(
     share_text = str(workers_data_path).strip()
     if not share_text:
         return
+    if not _workers_data_path_can_rebind_env_share(env, share_text):
+        return
 
     share_root_abs = _absolute_workers_data_share_root(env, share_text)
     env.AGI_CLUSTER_SHARE = share_text

src/agilab/core/test/test_agi_distributor_runtime_misc_support.py

@@ -612,7 +612,7 @@ def test_initialize_runtime_state_rebinds_manager_share_root_to_workflow_session
         workers_data_path=session_root,
     )
 
-    expected_root = Path("/home/agi") / session_root
+    expected_root = (Path("/home/agi") / session_root).resolve(strict=False)
     assert agi_cls._workers_data_path == session_root
     assert env.AGI_CLUSTER_SHARE == session_root
     assert env.agi_share_path == session_root
@@ -624,6 +624,47 @@ def test_initialize_runtime_state_rebinds_manager_share_root_to_workflow_session
     assert env.envars["AGI_CLUSTER_SHARE"] == session_root
 
 
+def test_initialize_runtime_state_preserves_scheduler_share_for_remote_workers_path():
+    agi_cls = SimpleNamespace()
+    scheduler_share = Path("/home/agi/data")
+    env = SimpleNamespace(
+        manager_path=Path("/tmp/manager"),
+        target="flight_trajectory_project",
+        verbose=0,
+        home_abs=Path("/home/agi"),
+        AGI_CLUSTER_SHARE=str(scheduler_share),
+        agi_share_path=str(scheduler_share),
+        agi_share_path_abs=scheduler_share,
+        _share_root_cache=scheduler_share,
+        _share_target_name=lambda: "flight_trajectory",
+        share_target_name="scheduler",
+        app_data_rel=scheduler_share / "scheduler",
+        dataframe_path=scheduler_share / "scheduler" / "dataframe",
+        envars={"AGI_CLUSTER_SHARE": str(scheduler_share)},
+    )
+
+    runtime_misc_support.initialize_runtime_state(
+        agi_cls,
+        env,
+        workers={"192.168.20.15": 1},
+        verbose=0,
+        rapids_enabled=False,
+        args={"data_in": "flight_trajectory/dataset"},
+        worker_args={"data_in": "flight_trajectory/dataset"},
+        workers_data_path="clustershare",
+    )
+
+    assert agi_cls._workers_data_path == "clustershare"
+    assert env.AGI_CLUSTER_SHARE == str(scheduler_share)
+    assert env.agi_share_path == str(scheduler_share)
+    assert env.agi_share_path_abs == scheduler_share
+    assert env._share_root_cache == scheduler_share
+    assert env.share_target_name == "scheduler"
+    assert env.app_data_rel == scheduler_share / "scheduler"
+    assert env.dataframe_path == scheduler_share / "scheduler" / "dataframe"
+    assert env.envars["AGI_CLUSTER_SHARE"] == str(scheduler_share)
+
+
 def test_initialize_runtime_state_normalizes_windows_module_workers_data_path():
     agi_cls = SimpleNamespace()
     env = SimpleNamespace(