agentic-dev-loop 1.0.0a11__tar.gz → 1.0.0a12__tar.gz

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a11
+Version: 1.0.0a12
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a11"
+version = "1.0.0a12"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/src/agentic_dev_loop/core/config.py

@@ -79,6 +79,13 @@ class IsolationConfig(BaseModel):
     cpus: float | None = None           # override exec container cpus
     allow_git_mutations: bool = False   # BR-6 knob
     state_dir: str = "~/.agentic-dev-loop/state"  # stamps + audit (host-only)
+    # 022 relocation opt-in: an out-of-workspace host dir that is bind-mounted
+    # at ``{ws}/.venv-sandbox`` (rw) in both the exec and provision containers,
+    # keeping the workspace free of container venv artifacts. Unset keeps the
+    # legacy workspace-local ``.venv-sandbox`` unchanged. Must resolve outside
+    # the workspace — validated at startup, not load (the workspace is unknown
+    # here).
+    sandbox_venv_dir: str | None = None
 
     @field_validator("memory")
     @classmethod

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/src/agentic_dev_loop/engine/isolation.py

@@ -7,10 +7,13 @@ concrete implementation (user directive 2026-10-19). Everything else here is
 either pure translation logic (the PBT-03 targets) or host-side audit/stamp
 helpers.
 
-Host-only vs sandboxed: the sandbox mount set is EXACTLY {workspace} (Q1).
-The isolation state dir (stamps + audit JSONL) and the pipeline run-state dir
-(checkpoint DB + last-error.md) are never mounted — sandboxed code cannot
-reach them.
+Host-only vs sandboxed: the sandbox mount set is {workspace} plus the
+host-only mask mounts (022): a read-only empty tmpfs at ``{ws}/.venv`` so the
+host's throwaway venv can never be written from inside the sandbox. When
+``isolation.sandbox_venv_dir`` relocates the sandbox venv, one extra rw bind
+mount at ``{ws}/.venv-sandbox`` is added (opt-in). The isolation state dir
+(stamps + audit JSONL) and the pipeline run-state dir (checkpoint DB +
+last-error.md) are never mounted — sandboxed code cannot reach them.
 """
 
 from __future__ import annotations
@@ -74,6 +77,10 @@ PROVISION_TIMEOUT_SECONDS = 3600
 # container, so it must be detected and re-provisioned there.
 SANDBOX_VENV_DIR = ".venv-sandbox"
 SANDBOX_VENV_PYTHON = ".venv-sandbox/bin/python"
+# Host-only dirs masked inside the sandbox (022): each gets a read-only empty
+# tmpfs submount at ``{ws}/<dir>`` so agents fail loudly on any write instead
+# of silently mutating a host-owned throwaway venv.
+HOST_ONLY_DIRS = (".venv",)
 
 
 class SandboxError(RuntimeError):
@@ -277,6 +284,27 @@ def translate_mount_path(path: str) -> str:
     return str(p)
 
 
+def resolve_sandbox_venv_dir(sandbox_venv_dir: str | None,
+                             workspace: str | Path) -> str | None:
+    """Resolve the opt-in relocated sandbox venv (022).
+
+    ``None`` keeps the legacy workspace-local ``.venv-sandbox`` (bit-compatible
+    default — payloads are unchanged). A set value is expanduser + absolute and
+    must resolve OUTSIDE the workspace: an in-workspace value defeats the whole
+    relocation and fails loud (AE-SBX-015).
+    """
+    if sandbox_venv_dir is None:
+        return None
+    resolved = Path(translate_mount_path(sandbox_venv_dir))
+    ws = Path(translate_mount_path(os.fspath(workspace)))
+    if resolved == ws or ws in resolved.parents:
+        raise SandboxError(
+            f"AE-SBX-015: isolation.sandbox_venv_dir {resolved!r} must resolve "
+            "outside the workspace — an in-workspace value defeats the 022 "
+            "relocation (docs/setup.md §3)")
+    return str(resolved)
+
+
 def setup_stamp_key(setup_cmd: str, lockfile_hashes: dict[str, str]) -> str:
     """sha256 hex of canonical JSON {setup_cmd, lockfiles: sorted hashes}."""
     canonical = {
@@ -323,10 +351,44 @@ def venv_probe_state(stdout: str, exit_code: int | None) -> str:
     return line if line in ("valid", "missing", "broken") else "unknown"
 
 
-def remove_sandbox_venv(workspace: str | Path) -> None:
-    """Remove the workspace's sandbox venv before re-provision (016 self-heal).
-    Fails loud when the venv exists but cannot be removed — a silent skip
-    would re-create the ENOENT failure the next run."""
+def _clear_dir_contents(path: Path) -> None:
+    """Delete every entry under ``path``, keeping ``path`` itself. The 022
+    relocated venv is the bind-mount source for the still-running execution
+    container, so the source dir must survive removal (deleting it would leave
+    the container pointed at a stale inode)."""
+    if not path.exists():
+        return
+    for child in path.iterdir():
+        if child.is_symlink() or child.is_file():
+            child.unlink()
+        elif child.is_dir():
+            shutil.rmtree(child)
+
+
+def remove_sandbox_venv(workspace: str | Path, *,
+                        sandbox_venv_dir: str | None = None) -> None:
+    """Remove the sandbox venv before re-provision (016 self-heal). Fails loud
+    when the venv exists but cannot be removed — a silent skip would re-create
+    the ENOENT failure the next run.
+
+    With the 022 relocation opt-in (``sandbox_venv_dir``), the venv lives at
+    that host path and is the source of a live bind mount in the execution
+    container — so only its CONTENTS are removed (the mount source dir stays),
+    leaving the container's ``{ws}/.venv-sandbox`` mount valid for re-provision.
+    The default (unset) path removes the whole workspace-local dir as before.
+    """
+    if sandbox_venv_dir is not None:
+        venv = Path(sandbox_venv_dir)
+        try:
+            if venv.is_symlink() or venv.is_file():
+                venv.unlink()
+            elif venv.is_dir():
+                _clear_dir_contents(venv)
+        except OSError as e:
+            raise SandboxError(
+                f"AE-SBX-014: cannot remove invalid sandbox venv at {venv}: {e} "
+                f"— remove it manually and re-run (docs/setup.md §5)") from e
+        return
     venv = Path(workspace) / SANDBOX_VENV_DIR
     try:
         if venv.is_symlink() or venv.is_file():
@@ -360,15 +422,34 @@ def exec_container_name(run_id: str, network: bool = False) -> str:
     return f"{run_id}-exec-net" if network else f"{run_id}-exec"
 
 
+def _sandbox_mounts(workspace: str, sandbox_venv_dir: str | None) -> list[str]:
+    """The mount segment shared by the exec and provision payloads (022).
+
+    ``{workspace}`` rw is always first; each host-only dir is then shadowed by
+    a read-only empty tmpfs submount (Docker cannot exclude a subdirectory of a
+    bind — a submount is the only way to hide it, and ``ro`` makes any write
+    attempt fail loudly instead of silently succeeding against a decoy). When
+    ``sandbox_venv_dir`` relocates the sandbox venv, one rw bind mount maps it
+    to the unchanged container path ``{ws}/.venv-sandbox``.
+    """
+    mounts = ["-v", f"{workspace}:{workspace}"]
+    for host_only in HOST_ONLY_DIRS:
+        mounts += ["--tmpfs", f"{workspace}/{host_only}:ro"]
+    if sandbox_venv_dir is not None:
+        mounts += ["-v", f"{sandbox_venv_dir}:{workspace}/{SANDBOX_VENV_DIR}"]
+    return mounts
+
+
 def docker_create_payload(*, run_id: str, image: str, profile: EffectiveProfile,
-                          workspace: str, network: bool = False) -> list[str]:
+                          workspace: str, network: bool = False,
+                          sandbox_venv_dir: str | None = None) -> list[str]:
     """Exact ``docker run -d --rm`` argv for the execution container (§3.3, KD-8).
-    Single mount {workspace} (Q1); ``--network none`` (bridge when ``network``
-    is true — 014 per-stage networking), --read-only, --cap-drop ALL; --user
-    host uid:gid (host-owned bind mounts, AE-SBX-009 root cause) with
-    HOME=/tmp (the rootfs is read-only; /tmp is a 1777 tmpfs). ``--rm`` lets the
-    daemon auto-remove the container the instant it exits, however it exits
-    (D1) — a SIGKILLed CLI never reaches close()."""
+    Mount set {workspace} + host-only masks (022); ``--network none`` (bridge
+    when ``network`` is true — 014 per-stage networking), --read-only,
+    --cap-drop ALL; --user host uid:gid (host-owned bind mounts, AE-SBX-009
+    root cause) with HOME=/tmp (the rootfs is read-only; /tmp is a 1777 tmpfs).
+    ``--rm`` lets the daemon auto-remove the container the instant it exits,
+    however it exits (D1) — a SIGKILLed CLI never reaches close()."""
     payload = [
         "docker", "run", "--detach", "--rm", "--name",
         exec_container_name(run_id, network),
@@ -380,8 +461,8 @@ def docker_create_payload(*, run_id: str, image: str, profile: EffectiveProfile,
     user = host_user_flag()
     if user is not None:
         payload.extend(["--user", user, "--env", "HOME=/tmp"])
+    payload.extend(_sandbox_mounts(workspace, sandbox_venv_dir))
     payload.extend([
-        "-v", f"{workspace}:{workspace}",
         "--workdir", workspace,
         image, "sleep", "infinity",
     ])
@@ -389,10 +470,12 @@ def docker_create_payload(*, run_id: str, image: str, profile: EffectiveProfile,
 
 
 def docker_provision_payload(*, run_id: str, image: str, workspace: str,
-                             setup_cmd: str) -> list[str]:
+                             setup_cmd: str,
+                             sandbox_venv_dir: str | None = None) -> list[str]:
     """Exact ``docker run --rm`` argv for the provision container (§3.4).
-    Network ON (default bridge), rw rootfs, --cap-drop ALL, single mount
-    {workspace} (Q1); --user host uid:gid (AE-SBX-009) with HOME=/tmp."""
+    Network ON (default bridge), rw rootfs, --cap-drop ALL, mount set
+    {workspace} + host-only masks (022); --user host uid:gid (AE-SBX-009) with
+    HOME=/tmp."""
     payload = [
         "docker", "run", "--rm", "--name", f"{run_id}-provision",
         "--network", "bridge", "--cap-drop", "ALL",
@@ -401,8 +484,8 @@ def docker_provision_payload(*, run_id: str, image: str, workspace: str,
     user = host_user_flag()
     if user is not None:
         payload.extend(["--user", user, "--env", "HOME=/tmp"])
+    payload.extend(_sandbox_mounts(workspace, sandbox_venv_dir))
     payload.extend([
-        "-v", f"{workspace}:{workspace}",
         "--workdir", workspace,
         image, "sh", "-c", setup_cmd,
     ])
@@ -502,7 +585,7 @@ class DockerBackend(Sandbox):
 
     def __init__(self, *, image: str, workspace: str, iso_state_dir: str,
                  profile: EffectiveProfile, runner: CommandRunner | None = None,
-                 network: bool = False):
+                 network: bool = False, sandbox_venv_dir: str | None = None):
         self._image = image
         self._workspace = workspace
         self._iso_state_dir = Path(iso_state_dir)  # host-only (audit)
@@ -512,6 +595,13 @@ class DockerBackend(Sandbox):
         self._container = exec_container_name(self._run_id, network=False)
         self._network_container = exec_container_name(self._run_id, network=True)
         self._network_enabled = network
+        self._sandbox_venv_dir = sandbox_venv_dir  # 022 relocated venv (opt-in)
+        if sandbox_venv_dir is not None:
+            # 022: the relocated venv dir is a bind-mount source. On native
+            # Linux, Docker auto-creates a missing source as root, which the
+            # --user uid:gid containers then cannot write (the AE-SBX-009
+            # ownership class). Pre-create it host-side so it is uid-owned.
+            Path(sandbox_venv_dir).mkdir(parents=True, exist_ok=True)
         self._started = False
         self._network_started = False
 
@@ -551,7 +641,8 @@ class DockerBackend(Sandbox):
         infrastructure work happens mid-run (014 per-stage networking)."""
         payload = docker_create_payload(
             run_id=self._run_id, image=self._image, profile=self._profile,
-            workspace=self._workspace, network=False)
+            workspace=self._workspace, network=False,
+            sandbox_venv_dir=self._sandbox_venv_dir)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             raise SandboxError(
@@ -562,7 +653,8 @@ class DockerBackend(Sandbox):
             return
         net_payload = docker_create_payload(
             run_id=self._run_id, image=self._image, profile=self._profile,
-            workspace=self._workspace, network=True)
+            workspace=self._workspace, network=True,
+            sandbox_venv_dir=self._sandbox_venv_dir)
         net_res = self._runner.run(net_payload, timeout=60)
         if net_res.exit_code != 0:
             # reclaim the already-started network-none container — never leak it.
@@ -587,12 +679,13 @@ class DockerBackend(Sandbox):
         """
         if not force and read_stamp(Path(stamp_dir), stamp_key):
             if self._probe_venv() == "broken":
-                remove_sandbox_venv(self._workspace)
+                remove_sandbox_venv(self._workspace,
+                                    sandbox_venv_dir=self._sandbox_venv_dir)
             else:
                 return
         payload = docker_provision_payload(
             run_id=self._run_id, image=self._image, workspace=self._workspace,
-            setup_cmd=setup_cmd)
+            setup_cmd=setup_cmd, sandbox_venv_dir=self._sandbox_venv_dir)
         res = self._runner.run(payload, timeout=PROVISION_TIMEOUT_SECONDS)
         if res.exit_code != 0:
             tail = (res.stdout or res.stderr or "")[-4000:]
@@ -846,9 +939,12 @@ def startup_sandbox(cfg: PipelineConfig, *, workspace: Path,
     image = resolve_image_ref(profile.image)
     iso_state_dir = isolation_state_dir(cfg)
     needs_network = any(step.network for step in cfg.steps)
+    sandbox_venv_dir = resolve_sandbox_venv_dir(
+        cfg.isolation.sandbox_venv_dir if cfg.isolation else None, workspace)
     backend = DockerBackend(
         image=image, workspace=str(workspace), iso_state_dir=str(iso_state_dir),
-        profile=profile, runner=runner, network=needs_network)
+        profile=profile, runner=runner, network=needs_network,
+        sandbox_venv_dir=sandbox_venv_dir)
     backend.ensure_image()
     backend.create_execution_container()
     if refresh is None:

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/src/agentic_dev_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a11
+Version: 1.0.0a12
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -63,5 +63,6 @@ tests/test_secrets_integration.py
 tests/test_secrets_pipeline.py
 tests/test_source_resolution.py
 tests/test_stages.py
+tests/test_trigger_script.py
 tests/test_verdict.py
 tests/test_viz.py

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/tests/test_config.py

@@ -402,6 +402,17 @@ class TestIsolationConfig:
         data = _base() | {"isolation": {"memory": memory}}
         assert _load(tmp_path, data).isolation.memory == memory
 
+    def test_sandbox_venv_dir_accepts_and_round_trips(self, tmp_path):
+        """022: `sandbox_venv_dir` is an optional relocation opt-in. It loads
+        verbatim here; the outside-workspace validation happens at startup
+        (where the workspace is known), not at config load."""
+        data = _base() | {"isolation": {"sandbox_venv_dir":
+                                        "~/.agentic-dev-loop/venvs/engine"}}
+        iso = _load(tmp_path, data).isolation
+        assert iso.sandbox_venv_dir == "~/.agentic-dev-loop/venvs/engine"
+        roundtripped = type(iso).model_validate(iso.model_dump())
+        assert roundtripped.sandbox_venv_dir == iso.sandbox_venv_dir
+
     @pytest.mark.parametrize("memory", ["8", "g", "8G", "8 g", ""])
     def test_invalid_memory_rejected(self, tmp_path, memory):
         data = _base() | {"isolation": {"memory": memory}}

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/tests/test_e2e_fixtures.py

@@ -27,10 +27,11 @@ EXAMPLE = Path(__file__).resolve().parent.parent / "agentic-dev-loop"
 
 
 # Scripted stand-in for the shipped example's mechanical test command. The
-# example runs `.venv/bin/python -m pytest tests/ -q`, which cannot run inside
-# the consumer-repo copy (no .venv, no tests/) — so this fixture scripts the
-# seam locally. The real subprocess path stays covered by test_stages.py and
-# test_graph.py. Behaviors: ("pass",) → (0, "", False); ("fail", output) →
+# example runs `.venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"`,
+# which cannot run inside the consumer-repo copy (no .venv-sandbox, no tests/)
+# — so this fixture scripts the seam locally. The real subprocess path stays
+# covered by test_stages.py and test_graph.py. Behaviors: ("pass",) →
+# (0, "", False); ("fail", output) →
 # (1, output, False); ("timeout", output) → (None, output, True); the last
 # behavior repeats; empty queue → default pass.
 _COMMAND_QUEUE: list[tuple] = []

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/tests/test_isolation.py

@@ -21,7 +21,8 @@ from agentic_dev_loop.engine.isolation import (
     clean_stamps, docker_create_payload, docker_provision_payload,
     exec_container_name, is_git_mutation, probe_docker, read_stamp,
     remove_sandbox_venv, resolve_effective_profile, resolve_image_ref,
-    resolve_sandbox_env, select_backend, setup_stamp_key, translate_mount_path,
+    resolve_sandbox_env, resolve_sandbox_venv_dir, select_backend,
+    setup_stamp_key, translate_mount_path,
     venv_probe_argv, venv_probe_command, venv_probe_state, write_stamp,
 )
 
@@ -303,6 +304,23 @@ class TestRemoveSandboxVenv:
         with pytest.raises(SandboxError, match="AE-SBX-014"):
             remove_sandbox_venv(ws)
 
+    def test_relocated_clears_contents_keeps_dir(self, tmp_path):
+        """022: a relocated venv is the bind-mount source for the still-running
+        exec container, so only its CONTENTS are removed — deleting the dir
+        would leave the container pointed at a stale inode."""
+        venv = tmp_path / "outside-venv"
+        (venv / "bin").mkdir(parents=True)
+        (venv / "bin" / "python").symlink_to("/opt/homebrew/opt/python/bin/python3.14")
+        (venv / "lib").mkdir(parents=True)
+        (venv / "lib" / "x.txt").write_text("x")
+        remove_sandbox_venv(tmp_path / "ws", sandbox_venv_dir=str(venv))
+        assert venv.is_dir()
+        assert not list(venv.iterdir())  # contents gone, mount source intact
+
+    def test_relocated_missing_is_noop(self, tmp_path):
+        remove_sandbox_venv(tmp_path / "ws",
+                            sandbox_venv_dir=str(tmp_path / "nope"))
+
 
 class TestPayloads:
     def _profile(self):
@@ -388,6 +406,74 @@ class TestPayloads:
         mounts = [p[i + 1] for i, a in enumerate(p) if a == "-v"]
         assert mounts == [f"{ws}:{ws}"]
 
+    def test_create_payload_masks_host_only_venv(self, tmp_path):
+        """022: `.venv` is host-only. It cannot be excluded from the workspace
+        bind, so it is shadowed by a read-only empty tmpfs submount — any
+        container-side write fails loudly instead of mutating the host venv."""
+        ws = str(tmp_path)
+        p = docker_create_payload(run_id="r1", image="img",
+                                  profile=self._profile(), workspace=ws)
+        mask = f"{ws}/.venv:ro"
+        assert mask in p
+        assert p[p.index(mask) - 1] == "--tmpfs"
+        # the mask comes after the workspace bind (submount shadows the bind)
+        assert p.index(mask) > p.index(f"{ws}:{ws}")
+
+    def test_provision_payload_masks_host_only_venv(self, tmp_path):
+        ws = str(tmp_path)
+        p = docker_provision_payload(run_id="r1", image="img", workspace=ws,
+                                     setup_cmd="make")
+        mask = f"{ws}/.venv:ro"
+        assert mask in p
+        assert p[p.index(mask) - 1] == "--tmpfs"
+        assert p.index(mask) > p.index(f"{ws}:{ws}")
+
+    def test_relocated_venv_mount_present_in_both_payloads(self, tmp_path):
+        """022: when ``sandbox_venv_dir`` is set, the outside dir is mounted rw
+        at the unchanged container path ``{ws}/.venv-sandbox`` in BOTH the exec
+        and provision payloads (the provision container runs the setup hook that
+        creates the venv)."""
+        ws = str(tmp_path)
+        venv = str(tmp_path / "outside-venv")
+        target = f"{venv}:{ws}/.venv-sandbox"
+        create = docker_create_payload(run_id="r1", image="img",
+                                       profile=self._profile(), workspace=ws,
+                                       sandbox_venv_dir=venv)
+        provision = docker_provision_payload(run_id="r1", image="img",
+                                             workspace=ws, setup_cmd="make",
+                                             sandbox_venv_dir=venv)
+        for payload in (create, provision):
+            assert target in payload
+            assert payload[payload.index(target) - 1] == "-v"
+            # the venv mount is a submount: it must come after the workspace bind
+            assert payload.index(target) > payload.index(f"{ws}:{ws}")
+
+
+class TestResolveSandboxVenvDir:
+    def test_none_returns_none(self, tmp_path):
+        assert resolve_sandbox_venv_dir(None, tmp_path) is None
+
+    def test_expanduser_and_absolute(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        out = resolve_sandbox_venv_dir("~/venvs/engine", tmp_path / "ws")
+        assert out == str(tmp_path / "venvs" / "engine")
+        assert os.path.isabs(out)
+
+    def test_outside_workspace_accepted(self, tmp_path):
+        ws = tmp_path / "ws"
+        out = resolve_sandbox_venv_dir(str(tmp_path / "venvs"), ws)
+        assert out == str(tmp_path / "venvs")
+
+    def test_in_workspace_fails_loud(self, tmp_path):
+        ws = tmp_path / "ws"
+        with pytest.raises(SandboxError, match="AE-SBX-015"):
+            resolve_sandbox_venv_dir(str(ws / "nested" / "venv"), ws)
+
+    def test_equals_workspace_fails_loud(self, tmp_path):
+        ws = tmp_path / "ws"
+        with pytest.raises(SandboxError, match="AE-SBX-015"):
+            resolve_sandbox_venv_dir(str(ws), ws)
+
 
 class TestExecContainerName:
     def test_default_is_network_none(self):
@@ -460,13 +546,35 @@ class TestResolveImageRef:
 
 
 def _backend(tmp_path, runner, *, image="img@sha256:abc", git_blocked=True,
-              network=False):
+              network=False, sandbox_venv_dir=None):
     return DockerBackend(
         image=image, workspace=str(tmp_path / "ws"),
         iso_state_dir=str(tmp_path / "state"),
         profile=EffectiveProfile(True, True, True, True, git_blocked,
                                  image, "4g", 2.0),
-        runner=runner, network=network)
+        runner=runner, network=network,
+        sandbox_venv_dir=sandbox_venv_dir)
+
+
+class TestRelocatedVenvDirCreation:
+    """022: the relocated venv dir is the bind-mount source. It must be
+    pre-created host-side so Docker never auto-creates a missing source as
+    root on native Linux (the --user uid:gid EACCES class, AE-SBX-009)."""
+
+    def test_missing_dir_created_on_construction(self, tmp_path):
+        venv_dir = tmp_path / "outside-venv"
+        assert not venv_dir.exists()
+        _backend(tmp_path, FakeRunner(), sandbox_venv_dir=str(venv_dir))
+        assert venv_dir.is_dir()
+
+    def test_nested_missing_dir_created(self, tmp_path):
+        venv_dir = tmp_path / "a" / "b" / "venv"
+        _backend(tmp_path, FakeRunner(), sandbox_venv_dir=str(venv_dir))
+        assert venv_dir.is_dir()
+
+    def test_unset_creates_nothing(self, tmp_path):
+        _backend(tmp_path, FakeRunner())
+        assert not (tmp_path / ".venv-sandbox").exists()
 
 
 class TestEnsureImage:
@@ -887,3 +995,49 @@ class TestStartupSandbox:
         sandbox2 = startup_sandbox(cfg, workspace=ws, runner=runner2, refresh=True)
         sandbox2.close()
         assert [c for c in runner2.calls if "python -m venv .venv-sandbox" in c]
+
+    def test_relocated_venv_dir_flows_into_payloads(self, tmp_path, monkeypatch):
+        """022: a set `sandbox_venv_dir` is resolved and threaded into BOTH the
+        exec and provision payloads; the workspace stays free of `.venv-sandbox`
+        noise (the outside dir is mounted at the unchanged container path)."""
+        from agentic_dev_loop.engine.isolation import startup_sandbox
+
+        ws = tmp_path / "ws"
+        ws.mkdir()
+        venv_dir = tmp_path / "outside-venv"
+        cfg = self._cfg(tmp_path, with_setup=True)
+        cfg.isolation.sandbox_venv_dir = str(venv_dir)
+        monkeypatch.setattr("agentic_dev_loop.engine.isolation.shutil.which",
+                            lambda *a: "/usr/bin/docker")
+        monkeypatch.setenv("AGENTIC_DEV_LOOP_DEV_IMAGE", "img:tag")
+        runner = FakeRunner(
+            ok("1.54"),           # probe version
+            ok("linux"),          # probe ostype
+            ok(""),               # image inspect
+            ok(""),               # docker run -d --rm (exec container)
+            ok(""),               # docker run provision
+        )
+        sandbox = startup_sandbox(cfg, workspace=ws, runner=runner)
+        try:
+            target = f"{venv_dir}:{ws}/.venv-sandbox"
+            for argv in runner.calls:
+                if argv[:2] == ["docker", "run"]:
+                    assert target in argv
+                    assert argv[argv.index(target) - 1] == "-v"
+                    assert f"{ws}/.venv:ro" in argv
+        finally:
+            sandbox.close()
+
+    def test_in_workspace_sandbox_venv_dir_fails_loud(self, tmp_path, monkeypatch):
+        from agentic_dev_loop.engine.isolation import startup_sandbox
+
+        ws = tmp_path / "ws"
+        ws.mkdir()
+        cfg = self._cfg(tmp_path, with_setup=False)
+        cfg.isolation.sandbox_venv_dir = str(ws / "nested")
+        monkeypatch.setattr("agentic_dev_loop.engine.isolation.shutil.which",
+                            lambda *a: "/usr/bin/docker")
+        monkeypatch.setenv("AGENTIC_DEV_LOOP_DEV_IMAGE", "img:tag")
+        runner = FakeRunner(ok("1.54"), ok("linux"))
+        with pytest.raises(SandboxError, match="AE-SBX-015"):
+            startup_sandbox(cfg, workspace=ws, runner=runner)

{agentic_dev_loop-1.0.0a11 → agentic_dev_loop-1.0.0a12}/tests/test_isolation_integration.py

@@ -215,3 +215,75 @@ class TestVenvSelfHealE2E:
         assert result.exit_code == 0, result.stderr
         assert "ok" in result.stdout
         assert read_stamp(stamp_dir, key)
+
+
+class TestRelocatedVenvE2E:
+    """022: `sandbox_venv_dir` relocates the sandbox venv outside the workspace.
+    The outside dir is bind-mounted at `{ws}/.venv-sandbox` in BOTH containers,
+    so the venv materializes there and stays absent from the repo dir — and the
+    probe/remove_sandbox_venv self-heal keeps operating at the unchanged
+    container path (the mount)."""
+
+    def _relocated_backend(self, tmp_path):
+        reason = _docker_available()
+        if reason is not None:
+            pytest.skip(reason)
+        inspect = SubprocessRunner().run(
+            ["docker", "image", "inspect", TEST_IMAGE, "--format", "{{.Id}}"],
+            timeout=30)
+        if inspect.exit_code != 0:
+            pytest.skip(f"integration image {TEST_IMAGE!r} not present locally")
+        ws = tmp_path / "ws"
+        ws.mkdir()
+        venv_dir = tmp_path / "outside-venv"
+        profile = resolve_effective_profile(IsolationConfig(image=TEST_IMAGE))
+        b = DockerBackend(image=TEST_IMAGE, workspace=str(ws),
+                          iso_state_dir=str(tmp_path / "state"), profile=profile,
+                          sandbox_venv_dir=str(venv_dir))
+        b.ensure_image()
+        b.create_execution_container()
+        return b, ws, venv_dir
+
+    def test_relocated_venv_materializes_outside_workspace(self, tmp_path):
+        b, ws, venv_dir = self._relocated_backend(tmp_path)
+        try:
+            b.provision("python -m venv .venv-sandbox", "k1",
+                        str(tmp_path / "stamps"), force=False)
+            assert (venv_dir / "bin" / "python").exists()
+            assert not (ws / ".venv-sandbox").exists()
+            req = SandboxExecutionRequest(
+                argv=[".venv-sandbox/bin/python", "-c", "import sys; print('ok')"],
+                cwd=ws,
+                env={"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": "/tmp"})
+            result = b.run(req)
+            assert result.exit_code == 0, result.stderr
+            assert "ok" in result.stdout
+        finally:
+            b.close()
+
+    def test_relocated_self_heal_reprovisions_broken_venv(self, tmp_path):
+        b, ws, venv_dir = self._relocated_backend(tmp_path)
+        try:
+            # Simulate a host-built venv broken inside the Linux container.
+            (venv_dir / "bin").mkdir(parents=True)
+            (venv_dir / "bin" / "python").symlink_to(
+                "/opt/homebrew/opt/python@3.14/bin/python3.14")
+            stamp_dir = tmp_path / "stamps"
+            key = "warm-stamp"
+            write_stamp(stamp_dir, key)
+
+            b.provision("python -m venv .venv-sandbox", key, str(stamp_dir),
+                        force=False)
+
+            # contents cleared (mount source dir kept) and re-provisioned.
+            assert venv_dir.is_dir()
+            req = SandboxExecutionRequest(
+                argv=[".venv-sandbox/bin/python", "-c", "import sys; print('ok')"],
+                cwd=ws,
+                env={"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": "/tmp"})
+            result = b.run(req)
+            assert result.exit_code == 0, result.stderr
+            assert "ok" in result.stdout
+            assert read_stamp(stamp_dir, key)
+        finally:
+            b.close()

agentic_dev_loop-1.0.0a12/tests/test_trigger_script.py

@@ -0,0 +1,111 @@
+"""Trigger-script contract tests.
+
+The trigger script must keep the pipx-managed engine install current:
+a stale install rejects newer pipeline configs at load time (e.g.
+`deps_policy` in a11 rejected by an a10 install), so an existing install
+is upgraded on every run. Tests drive the real script with stub
+executables on PATH — no network, no mocks of the script's logic.
+
+The script is bash, so it is executed through `bash` on every platform:
+Windows cannot CreateProcess a `.sh` file (shebangs are a POSIX concept)
+and its MSYS bash (git-bash, preinstalled on windows-latest runners)
+understands only POSIX-style paths (`/c/...`), so PATH entries and
+redirect targets inside stub bodies are converted accordingly.
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = REPO_ROOT / "trigger-agentic-dev-loop.sh"
+
+
+def _msys(path: Path) -> str:
+    """POSIX-style form of a Windows path (`C:\\x` -> `/c/x`).
+
+    MSYS bash splits PATH on `:` and treats backslashes as escapes, so a
+    native `C:\\...` entry would fragment into `C` + `\\...`. Pass the
+    mount-style form instead. On POSIX the path is returned unchanged.
+    """
+    if os.name != "nt":
+        return str(path)
+    drive, rest = os.path.splitdrive(str(path))
+    return "/" + drive[0].lower() + rest.replace("\\", "/")
+
+
+def _bash() -> str:
+    bash = shutil.which("bash")
+    if bash is None:
+        pytest.skip("bash is required to run the trigger script")
+    return bash
+
+
+def _run_script(*args: str, env: dict) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [_bash(), _msys(SCRIPT), *args],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def _make_stub(bin_dir: Path, name: str, body: str) -> None:
+    path = bin_dir / name
+    path.write_text(f"#!/bin/bash\n{body}\n")
+    path.chmod(0o755)
+    if not os.access(path, os.X_OK):
+        pytest.skip("tmp filesystem is mounted noexec; stub executables cannot run")
+
+
+def _env_with(bin_dir: Path | None = None) -> dict:
+    entries = ["/usr/bin", "/bin"]
+    if bin_dir is not None:
+        entries.insert(0, _msys(bin_dir))
+    return {**os.environ, "PATH": ":".join(entries)}
+
+
+def test_trigger_upgrades_existing_install(tmp_path):
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    pipx_log = tmp_path / "pipx.log"
+    _make_stub(
+        bin_dir,
+        "agentic-dev-loop",
+        'echo "cli-ran: $*"',
+    )
+    _make_stub(
+        bin_dir,
+        "pipx",
+        f'echo "$*" >> "{_msys(pipx_log)}"',
+    )
+
+    result = _run_script("--plan", "plan.md", env=_env_with(bin_dir))
+
+    assert result.returncode == 0, result.stderr
+    assert pipx_log.read_text().strip() == "upgrade --cooldown 0 --pip-args=--prerelease=allow agentic-dev-loop"
+    # The upgrade happens before the loop is launched.
+    assert "cli-ran:" in result.stdout
+
+
+def test_trigger_fails_fast_when_upgrade_fails(tmp_path):
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    _make_stub(bin_dir, "agentic-dev-loop", "echo should-not-run")
+    _make_stub(bin_dir, "pipx", "echo upgrade-broken >&2; exit 1")
+
+    result = _run_script(env=_env_with(bin_dir))
+
+    assert result.returncode != 0
+    assert "pipx upgrade" in result.stderr
+    assert "should-not-run" not in result.stdout
+
+
+def test_trigger_errors_when_cli_absent():
+    result = _run_script(env=_env_with())
+
+    assert result.returncode != 0
+    assert "pipx install" in result.stderr