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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a10
+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
@@ -35,6 +35,7 @@ Requires-Dist: langgraph-checkpoint-sqlite>=3.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pip-audit>=2.0; extra == "dev"
 Dynamic: license-file
 
 # agentic-dev-loop
@@ -213,6 +214,8 @@ steps:
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 | `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+| `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
+| `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` — a `locked` pipeline with no lockfiles fails fast at load. |
 
 ### Secrets (`secrets:`) — refs only, never values
 
@@ -278,6 +281,76 @@ steps:
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Dependency policy (locked by default)
+
+The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by
+default**. The engine injects the policy into every agent step's context —
+the rule lives in the engine, not in hand-authored `dev.agent.md` prose (the
+class of rule that deadlocked the NuGet cache).
+
+```yaml
+deps_policy: locked    # or: open    (default: locked)
+lockfiles: [uv.lock]   # or: [packages.lock.json, package-lock.json]
+```
+
+- **`locked`** — the human-owned lockfile is the source of truth; the agent
+  may not add dependencies. The injected rule says *"You may only use
+  dependencies already present in `<lockfile>`. If the design requires a
+  dependency that is not present, declare it in your final response under the
+  fixed header `## Missing dependencies` (one `name==version` per line) and
+  finish what you can. Do not add it to the manifest."* A non-empty
+  `## Missing dependencies` declaration **fails the run fast** with
+  `Extend <lockfile> with these pins and re-run: …` — one human lockfile edit,
+  not a retry loop. The declaration is advisory to the human; the engine never
+  auto-fetches the declared packages.
+- **`open`** — the bootstrap protocol (018): the agent may add exact-pinned
+  manifest entries directly (never a package-manager `add` command); the
+  network-on restore step fetches them. The engine injects the same rule
+  canonically. Nothing about `open` is default.
+
+The **restore step** runs the toolchain's locked mode and fails when the
+manifest and lockfile disagree:
+
+| Toolchain | Locked restore | Lockfile |
+| --- | --- | --- |
+| .NET | `dotnet restore --locked-mode` | `packages.lock.json` (set `RestorePackagesWithLockFile=true`) |
+| node | `npm ci` | `package-lock.json` |
+| python | `uv sync --locked` (or pip-tools `pip-sync requirements.lock`) | `uv.lock` — pip has no native lockfile; `uv` is the canonical locked-install tool |
+
+### Audit escalation in the restore step
+
+The restore step also fails on known-CVE findings, at a per-toolchain
+threshold:
+
+| Toolchain | Audit (fails the step) |
+| --- | --- |
+| .NET | `NuGetAudit` at `error` — any audit finding fails the restore |
+| node | `npm audit --audit-level=high` |
+| python | `pip-audit` — any finding fails |
+
+Under `locked`, a failing audit means the lockfile pins a vulnerable version:
+the run fails and the human regenerates the lockfile at a patched version.
+Under `open`, the failure routes to `dev` like any restore failure — the dev
+agent can bump the pin, but that pin is audited again on the next pass, so
+the loop self-corrects.
+
+### Generating a lockfile
+
+A human generates the lockfile once, on a network machine, and commits it —
+the engine never fetches on the agent's behalf:
+
+```bash
+uv lock                 # python — writes uv.lock from pyproject.toml
+uv sync --locked        # installs exactly uv.lock; fails on any drift
+npm install --package-lock-only   # node — writes package-lock.json
+npm ci                  # installs exactly package-lock.json
+dotnet restore --use-lock-file   # .NET — writes packages.lock.json
+dotnet restore --locked-mode      # installs exactly packages.lock.json
+```
+
+Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
+to prove it holds from a clean cache before setting `deps_policy: locked`.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a10 → agentic_dev_loop-1.0.0a12}/README.md

@@ -174,6 +174,8 @@ steps:
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 | `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+| `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
+| `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` — a `locked` pipeline with no lockfiles fails fast at load. |
 
 ### Secrets (`secrets:`) — refs only, never values
 
@@ -239,6 +241,76 @@ steps:
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Dependency policy (locked by default)
+
+The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by
+default**. The engine injects the policy into every agent step's context —
+the rule lives in the engine, not in hand-authored `dev.agent.md` prose (the
+class of rule that deadlocked the NuGet cache).
+
+```yaml
+deps_policy: locked    # or: open    (default: locked)
+lockfiles: [uv.lock]   # or: [packages.lock.json, package-lock.json]
+```
+
+- **`locked`** — the human-owned lockfile is the source of truth; the agent
+  may not add dependencies. The injected rule says *"You may only use
+  dependencies already present in `<lockfile>`. If the design requires a
+  dependency that is not present, declare it in your final response under the
+  fixed header `## Missing dependencies` (one `name==version` per line) and
+  finish what you can. Do not add it to the manifest."* A non-empty
+  `## Missing dependencies` declaration **fails the run fast** with
+  `Extend <lockfile> with these pins and re-run: …` — one human lockfile edit,
+  not a retry loop. The declaration is advisory to the human; the engine never
+  auto-fetches the declared packages.
+- **`open`** — the bootstrap protocol (018): the agent may add exact-pinned
+  manifest entries directly (never a package-manager `add` command); the
+  network-on restore step fetches them. The engine injects the same rule
+  canonically. Nothing about `open` is default.
+
+The **restore step** runs the toolchain's locked mode and fails when the
+manifest and lockfile disagree:
+
+| Toolchain | Locked restore | Lockfile |
+| --- | --- | --- |
+| .NET | `dotnet restore --locked-mode` | `packages.lock.json` (set `RestorePackagesWithLockFile=true`) |
+| node | `npm ci` | `package-lock.json` |
+| python | `uv sync --locked` (or pip-tools `pip-sync requirements.lock`) | `uv.lock` — pip has no native lockfile; `uv` is the canonical locked-install tool |
+
+### Audit escalation in the restore step
+
+The restore step also fails on known-CVE findings, at a per-toolchain
+threshold:
+
+| Toolchain | Audit (fails the step) |
+| --- | --- |
+| .NET | `NuGetAudit` at `error` — any audit finding fails the restore |
+| node | `npm audit --audit-level=high` |
+| python | `pip-audit` — any finding fails |
+
+Under `locked`, a failing audit means the lockfile pins a vulnerable version:
+the run fails and the human regenerates the lockfile at a patched version.
+Under `open`, the failure routes to `dev` like any restore failure — the dev
+agent can bump the pin, but that pin is audited again on the next pass, so
+the loop self-corrects.
+
+### Generating a lockfile
+
+A human generates the lockfile once, on a network machine, and commits it —
+the engine never fetches on the agent's behalf:
+
+```bash
+uv lock                 # python — writes uv.lock from pyproject.toml
+uv sync --locked        # installs exactly uv.lock; fails on any drift
+npm install --package-lock-only   # node — writes package-lock.json
+npm ci                  # installs exactly package-lock.json
+dotnet restore --use-lock-file   # .NET — writes packages.lock.json
+dotnet restore --locked-mode      # installs exactly packages.lock.json
+```
+
+Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
+to prove it holds from a clean cache before setting `deps_policy: locked`.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a10 → 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.0a10"
+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"
@@ -55,6 +55,7 @@ agentic-dev-loop = "agentic_dev_loop.engine.cli:main"
 dev = [
     "hypothesis>=6.0",
     "pytest>=8.0",
+    "pip-audit>=2.0",
 ]
 
 [tool.setuptools.packages.find]

{agentic_dev_loop-1.0.0a10 → 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
@@ -214,6 +221,27 @@ class PipelineConfig(BaseModel):
     max_attempts: int = 3
     agents_dir: str
     steps: list[StepConfig] = Field(min_length=1)
+    # 021 supply-chain dependency dial: `locked` (default) = the human-owned
+    # lockfile is the source of truth and the agent may not add dependencies;
+    # `open` = the bootstrap protocol (the agent may add exact-pinned manifest
+    # entries for the restore step to fetch). `lockfiles` names the pipeline's
+    # declared lockfile(s) — injected into agent context and named by the
+    # missing-dependency fail-fast.
+    deps_policy: str = "locked"
+    lockfiles: list[str] = []
+
+    @field_validator("deps_policy")
+    @classmethod
+    def _known_deps_policy(cls, v: str) -> str:
+        if v not in ("locked", "open"):
+            raise ValueError(
+                f"deps_policy must be 'locked' or 'open', got {v!r}")
+        return v
+
+    @field_validator("lockfiles", mode="before")
+    @classmethod
+    def _coerce_lockfiles(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
 
     @field_validator("secrets", mode="before")
     @classmethod
@@ -232,6 +260,15 @@ class PipelineConfig(BaseModel):
                     "values never belong in the pipeline yaml")
         return v
 
+    @model_validator(mode="after")
+    def _locked_requires_lockfiles(self) -> "PipelineConfig":
+        if self.deps_policy == "locked" and not self.lockfiles:
+            raise ValueError(
+                "deps_policy 'locked' requires at least one entry in "
+                "'lockfiles:' — name the lockfile(s) the locked boundary "
+                "enforces, or set 'deps_policy: open'")
+        return self
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]

agentic_dev_loop-1.0.0a12/src/agentic_dev_loop/engine/deps.py

@@ -0,0 +1,77 @@
+"""Supply-chain dependency dial (021): canonical policy injection and
+missing-dependency declaration parsing.
+
+The rule text lives HERE, in the engine, not in consumer `dev.agent.md` prose
+— the hand-authored rule is exactly the class that deadlocked the NuGet cache
+in 018. `deps_policy: locked` (the default) bounds the agent to the
+human-owned lockfile and fails a run fast when an agent declares a missing
+dependency; `deps_policy: open` injects the bootstrap protocol (the agent may
+add exact-pinned manifest entries for the restore step to fetch).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentic_dev_loop.core.config import PipelineConfig
+
+MISSING_DEPS_HEADER = "## Missing dependencies"
+
+_LOCKED_TEMPLATE = (
+    "You may only use dependencies already present in {lockfiles}. If the "
+    "design requires a dependency that is not present, declare it in your "
+    "final response under the fixed header `{header}` (one `name==version` "
+    "per line) and finish what you can. Do not add it to the manifest."
+)
+
+_OPEN_TEXT = (
+    "If the design needs a dependency that is not already present, add the "
+    "exact-pinned entry to the dependency manifest directly (do not run a "
+    "package-manager `add` command — it may need the network). Your offline "
+    "builds may fail until the restore step fetches it — that is expected; "
+    "write the code to match and leave the manifest entry in place."
+)
+
+
+def _lockfile_label(cfg: "PipelineConfig") -> str:
+    if cfg.lockfiles:
+        return ", ".join(f"`{name}`" for name in cfg.lockfiles)
+    return "the lockfile"
+
+
+def policy_injection(cfg: "PipelineConfig") -> str:
+    """The canonical dependency-policy paragraph injected into every agent
+    step's context, keyed on ``deps_policy`` and the declared lockfiles."""
+    if cfg.deps_policy == "open":
+        return _OPEN_TEXT
+    return _LOCKED_TEMPLATE.format(
+        lockfiles=_lockfile_label(cfg), header=MISSING_DEPS_HEADER)
+
+
+def parse_missing_dependencies(text: str | None) -> list[str]:
+    """Parse a final agent response for the fixed ``## Missing dependencies``
+    section. Returns the declared pins (one non-empty line each) beneath the
+    header, until the next ``## `` section or end of text. An absent header or
+    an empty/malformed section yields an empty list — only a non-empty
+    declaration triggers the fail-fast."""
+    if not text:
+        return []
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if line.strip() == MISSING_DEPS_HEADER:
+            pins: list[str] = []
+            for rest in lines[i + 1:]:
+                if rest.startswith("## "):
+                    break
+                stripped = rest.strip()
+                if stripped:
+                    pins.append(stripped)
+            return pins
+    return []
+
+
+def extension_message(cfg: "PipelineConfig", pins: list[str]) -> str:
+    """The fail-fast message naming the lockfile(s) and the declared pins."""
+    return (f"Extend {_lockfile_label(cfg)} with these pins and re-run:\n\n"
+            + "\n".join(pins))

{agentic_dev_loop-1.0.0a10 → 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.0a10 → agentic_dev_loop-1.0.0a12}/src/agentic_dev_loop/engine/stages.py

@@ -32,6 +32,7 @@ from openhands.sdk import Conversation
 
 from .agents import load_agent, register_sandbox_terminal
 from agentic_dev_loop.core.config import TERMINALS, PipelineConfig, Route, StepConfig, route_target
+from .deps import extension_message, parse_missing_dependencies, policy_injection
 from .isolation import SandboxExecutionRequest, command_argv, resolve_sandbox_env
 from .outputs import CapturedOutput
 from .secrets import redact_values, step_secret_env
@@ -198,11 +199,13 @@ def _run_command(command: str, workspace: Path, timeout: float,
 def build_context(runtime: Runtime, docs: dict[str, str], subject: str,
                   notes: list[str] | None = None) -> str:
     """Assemble the attempt's shared message: subject, doc bundle, the
-    expected-output-paths section generated from step defs (a prompt merely
-    naming files lets agents skip them), and previous-attempt notes."""
+    canonical dependency-policy paragraph (021), the expected-output-paths
+    section generated from step defs (a prompt merely naming files lets agents
+    skip them), and previous-attempt notes."""
     parts = [f"You are working on {subject}.\n"]
     for name, content in docs.items():
         parts.append(f"## {name}\n\n{content}")
+    parts.append("## Dependency policy\n\n" + policy_injection(runtime.cfg))
     lines = []
     for step in runtime.cfg.steps:
         if step.agent is None:
@@ -301,6 +304,22 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
                                             result.truncated, max_iterations)],
                     "retry_target": _unclear_target(runtime, step)}
 
+        # 021: under `locked`, a declared missing dependency is a fail-fast —
+        # one human lockfile edit, never a retry loop. The extension message
+        # is written to last-error.md (the run-failure channel) and printed.
+        if (runtime.cfg.deps_policy == "locked"
+                and result.response is not None):
+            pins = parse_missing_dependencies(result.response)
+            if pins:
+                msg = extension_message(runtime.cfg, pins)
+                runtime.state_dir.mkdir(parents=True, exist_ok=True)
+                (runtime.state_dir / LAST_ERROR).write_text(
+                    f"# Missing dependencies\n\n```\n{msg}\n```\n",
+                    encoding="utf-8")
+                print(redact_values(msg, runtime.secrets.values()),
+                      file=sys.stderr, flush=True)
+                return {"failed": True, "failed_step": step.name}
+
         if verdicts_map is None:
             merged = {**state["step_verdicts"], step.name: "pass"} if captures else \
                 state["step_verdicts"]