agentic-dev-loop 1.0.0a17__tar.gz → 1.0.0a19__tar.gz

{agentic_dev_loop-1.0.0a17/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a17
+Version: 1.0.0a19
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -72,7 +72,7 @@ flowchart LR
 | Feature | What it gives you |
 | --- | --- |
 | **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates - looping back with full context when one fails. |
-| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** - authors opt specific stages in](#per-stage-networking), no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** - authors opt specific stages in](#per-stage-networking), writes only to declared `mounts:`, and no access to `.git` (steps run against a fresh export). No sandbox available → the run stops instead of degrading. |
 | **Crash-safe resume** | Interrupt a run at any time and pick it up later - finished stages stay finished, and you resume from exactly where it stopped. |
 | **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
 | **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
@@ -93,16 +93,17 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. |
 
 ```bash
-pip install "agentic-dev-loop==1.0.0a9"
+pip install "agentic-dev-loop==1.0.0a17"
 agentic-dev-loop --version
 ```
 
 The canonical consumer install is **pipx**, which puts the engine's venv
-*outside* the workspace - the sandbox mount set is exactly `{workspace}`, so an
-out-of-workspace install is unmounted and never agent-writable:
+*outside* the workspace - the sandbox mounts only the step's declared `mounts:`
+from a fresh export, so an out-of-workspace install is unmounted and never
+agent-writable:
 
 ```bash
-pipx install "agentic-dev-loop==1.0.0a9"
+pipx install "agentic-dev-loop==1.0.0a17"
 ```
 
 If you install with `uv` shortly after a release, pass `--refresh` - PyPI
@@ -111,7 +112,7 @@ reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
 "no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
 
 ```bash
-uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+uv pip install --refresh "agentic-dev-loop==1.0.0a17"
 ```
 
 On the first run the engine pulls the **digest-pinned** dev image
@@ -211,7 +212,8 @@ steps:
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
-| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) - see [Per-stage networking](#per-stage-networking). |
+| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
+| `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only - never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox - image override, resource caps, `allow_git_mutations`, `seccomp_profile`. It can never disable it. See [browser sandbox](docs/browser-sandbox.md). |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` - artifacts and checkpoints live outside the sandbox mount. |
@@ -262,26 +264,45 @@ steps:
 
 The sandbox is network-off by default. A step that legitimately needs egress -
 a QA step that curls a service it booted, an agent that must hit an API or
-fetch package metadata mid-conversation - declares it explicitly:
+fetch package metadata mid-conversation - declares it explicitly, and names
+exactly what it may reach:
 
 ```yaml
 steps:
   - name: fetch-docs
     command: curl -fsSL https://example.com/spec.json -o spec.json
-    network: true            # egress for this step only
+    mounts: [{ path: ".", mode: rw }]      # the cwd + a place to write spec.json
+    network: true                          # egress for this step only
+    egress: { targets: [example.com] }     # ...and only these hosts
+
+  - name: restore
+    command: .venv-sandbox/bin/pip install -e ".[dev]"
+    mounts: [{ path: ".", mode: rw }]
+    network: true
+    egress: { presets: [package-registries] }   # pypi/npm/NuGet/cargo + VCS
 ```
 
 - **Default off.** Every step runs with `--network none` unless it declares
-  `network: true`. A networked step runs in a second, otherwise-identical
-  sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
-  on the Docker bridge network - the default network-none container is always
-  created too, so no infrastructure work happens mid-run.
+  `network: true`.
+- **A networked step that writes output must also declare a writable mount.**
+  `mounts:` is strict-by-default: with no `mounts:` a step mounts nothing, so
+  a command like `curl ... -o spec.json` has no writable cwd to write into.
+  Declare `mounts: [{ path: ".", mode: rw }]` (or a narrower rw path) for any
+  networked step that needs to produce files.
+- **`network: true` is now scoped by the `egress:` allowlist.** A networked
+  step's traffic is forced through an engine-run per-policy egress proxy
+  (injected via `HTTP_PROXY`/`HTTPS_PROXY` and reached through the
+  `host.docker.internal` host-gateway); a request to an undeclared host is
+  denied and logged as an enforcement event. The engine never adds an
+  undeclared target. `egress: { class: browser }` is the explicit
+  broad-but-logged class (every connection logged, nothing filtered); command
+  and agent steps default to a strict allowlist.
 - **Command, agent, and sandbox-action steps** may declare it. The host-side
   built-in `commit` action never takes it (refused once the registry is known).
-- **Author opt-in is the control.** A networked step gives its agent raw
-  egress for that stage; the default stays network-off everywhere. Reserve it
-  for stages that need it (QA, integration). The residual risk is documented
-  in [docs/setup.md](docs/setup.md).
+- **Author opt-in is the control.** A networked step grants its agent egress
+  to exactly the declared hosts for that stage; the default stays network-off
+  everywhere. Reserve it for stages that need it (QA, integration). The
+  residual risks are documented in [docs/setup.md](docs/setup.md).
 
 ## Dependency policy (locked by default)
 
@@ -407,7 +428,7 @@ the loop is building.
 ```bash
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
-pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
+pipx install "agentic-dev-loop==1.0.0a17"   # engine venv OUTSIDE the workspace (self-check)
 export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
 python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests

{agentic_dev_loop-1.0.0a17 → agentic_dev_loop-1.0.0a19}/README.md

@@ -30,7 +30,7 @@ flowchart LR
 | Feature | What it gives you |
 | --- | --- |
 | **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates - looping back with full context when one fails. |
-| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** - authors opt specific stages in](#per-stage-networking), no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** - authors opt specific stages in](#per-stage-networking), writes only to declared `mounts:`, and no access to `.git` (steps run against a fresh export). No sandbox available → the run stops instead of degrading. |
 | **Crash-safe resume** | Interrupt a run at any time and pick it up later - finished stages stay finished, and you resume from exactly where it stopped. |
 | **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
 | **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
@@ -51,16 +51,17 @@ LLM timeout (agent runs are long).
 | LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. |
 
 ```bash
-pip install "agentic-dev-loop==1.0.0a9"
+pip install "agentic-dev-loop==1.0.0a17"
 agentic-dev-loop --version
 ```
 
 The canonical consumer install is **pipx**, which puts the engine's venv
-*outside* the workspace - the sandbox mount set is exactly `{workspace}`, so an
-out-of-workspace install is unmounted and never agent-writable:
+*outside* the workspace - the sandbox mounts only the step's declared `mounts:`
+from a fresh export, so an out-of-workspace install is unmounted and never
+agent-writable:
 
 ```bash
-pipx install "agentic-dev-loop==1.0.0a9"
+pipx install "agentic-dev-loop==1.0.0a17"
 ```
 
 If you install with `uv` shortly after a release, pass `--refresh` - PyPI
@@ -69,7 +70,7 @@ reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
 "no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
 
 ```bash
-uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+uv pip install --refresh "agentic-dev-loop==1.0.0a17"
 ```
 
 On the first run the engine pulls the **digest-pinned** dev image
@@ -169,7 +170,8 @@ steps:
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
-| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) - see [Per-stage networking](#per-stage-networking). |
+| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
+| `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only - never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox - image override, resource caps, `allow_git_mutations`, `seccomp_profile`. It can never disable it. See [browser sandbox](docs/browser-sandbox.md). |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` - artifacts and checkpoints live outside the sandbox mount. |
@@ -220,26 +222,45 @@ steps:
 
 The sandbox is network-off by default. A step that legitimately needs egress -
 a QA step that curls a service it booted, an agent that must hit an API or
-fetch package metadata mid-conversation - declares it explicitly:
+fetch package metadata mid-conversation - declares it explicitly, and names
+exactly what it may reach:
 
 ```yaml
 steps:
   - name: fetch-docs
     command: curl -fsSL https://example.com/spec.json -o spec.json
-    network: true            # egress for this step only
+    mounts: [{ path: ".", mode: rw }]      # the cwd + a place to write spec.json
+    network: true                          # egress for this step only
+    egress: { targets: [example.com] }     # ...and only these hosts
+
+  - name: restore
+    command: .venv-sandbox/bin/pip install -e ".[dev]"
+    mounts: [{ path: ".", mode: rw }]
+    network: true
+    egress: { presets: [package-registries] }   # pypi/npm/NuGet/cargo + VCS
 ```
 
 - **Default off.** Every step runs with `--network none` unless it declares
-  `network: true`. A networked step runs in a second, otherwise-identical
-  sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
-  on the Docker bridge network - the default network-none container is always
-  created too, so no infrastructure work happens mid-run.
+  `network: true`.
+- **A networked step that writes output must also declare a writable mount.**
+  `mounts:` is strict-by-default: with no `mounts:` a step mounts nothing, so
+  a command like `curl ... -o spec.json` has no writable cwd to write into.
+  Declare `mounts: [{ path: ".", mode: rw }]` (or a narrower rw path) for any
+  networked step that needs to produce files.
+- **`network: true` is now scoped by the `egress:` allowlist.** A networked
+  step's traffic is forced through an engine-run per-policy egress proxy
+  (injected via `HTTP_PROXY`/`HTTPS_PROXY` and reached through the
+  `host.docker.internal` host-gateway); a request to an undeclared host is
+  denied and logged as an enforcement event. The engine never adds an
+  undeclared target. `egress: { class: browser }` is the explicit
+  broad-but-logged class (every connection logged, nothing filtered); command
+  and agent steps default to a strict allowlist.
 - **Command, agent, and sandbox-action steps** may declare it. The host-side
   built-in `commit` action never takes it (refused once the registry is known).
-- **Author opt-in is the control.** A networked step gives its agent raw
-  egress for that stage; the default stays network-off everywhere. Reserve it
-  for stages that need it (QA, integration). The residual risk is documented
-  in [docs/setup.md](docs/setup.md).
+- **Author opt-in is the control.** A networked step grants its agent egress
+  to exactly the declared hosts for that stage; the default stays network-off
+  everywhere. Reserve it for stages that need it (QA, integration). The
+  residual risks are documented in [docs/setup.md](docs/setup.md).
 
 ## Dependency policy (locked by default)
 
@@ -365,7 +386,7 @@ the loop is building.
 ```bash
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
-pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
+pipx install "agentic-dev-loop==1.0.0a17"   # engine venv OUTSIDE the workspace (self-check)
 export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
 python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests

{agentic_dev_loop-1.0.0a17 → agentic_dev_loop-1.0.0a19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a17"
+version = "1.0.0a19"
 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.0a17 → agentic_dev_loop-1.0.0a19}/src/agentic_dev_loop/core/__init__.py

@@ -6,13 +6,13 @@ test fails if this package imports engine/viz or heavy deps.
 
 from .config import (PipelineConfig, StepConfig, LlmConfig, IsolationConfig,
                      VerdictSpec, Route, route_target, load_config,
-                     default_state_dir, TERMINALS)
+                     default_state_dir, TERMINALS, MountSpec, EgressSpec)
 from .results import Result
 from .verdict import Verdict, VerdictError, parse_verdict, RETRY
 
 __all__ = [
     "PipelineConfig", "StepConfig", "LlmConfig", "IsolationConfig",
     "VerdictSpec", "Route", "route_target", "load_config",
-    "default_state_dir", "TERMINALS",
+    "default_state_dir", "TERMINALS", "MountSpec", "EgressSpec",
     "Result", "Verdict", "VerdictError", "parse_verdict", "RETRY",
 ]

{agentic_dev_loop-1.0.0a17 → agentic_dev_loop-1.0.0a19}/src/agentic_dev_loop/core/config.py

@@ -12,6 +12,99 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 TERMINALS = frozenset({"success", "failure"})
 KNOWN_SECRET_PROVIDERS = frozenset({"env"})
+MOUNT_MODES = frozenset({"rw", "ro"})
+# Host-only dirs a mount path may never name (022): they are masked in
+# the sandbox with a read-only tmpfs, so declaring them would be a decoy.
+HOST_ONLY_MOUNT_DIRS = frozenset({".venv"})
+# The egress preset names the engine ships (BR-9). Config validates the
+# name here; the target data lives in engine/presets.py (preset data,
+# never mechanism - D-2).
+KNOWN_EGRESS_PRESETS = frozenset({"package-registries"})
+EGRESS_CLASSES = frozenset({"allowlist", "browser"})
+
+
+def _validate_mount_path(path: str) -> str:
+    """Validate one repo-relative mount path (BR-1.3).
+
+    Rejects (loudly) an empty path, an absolute path, ``..`` traversal,
+    any ``.git`` component, and any host-only dir (``.venv``). The path
+    is normalised to forward-slash form and returned.
+    """
+    if not isinstance(path, str) or not path.strip():
+        raise ValueError("mount path must be a non-empty string")
+    p = path.strip()
+    if p.startswith(("/", "\\")) or (len(p) > 1 and p[1] == ":"):
+        raise ValueError(
+            f"mount path {path!r} must be repo-relative (no absolute paths)")
+    parts = [seg for seg in p.replace("\\", "/").split("/")
+             if seg not in ("", ".")]
+    for seg in parts:
+        if seg == "..":
+            raise ValueError(
+                f"mount path {path!r} escapes the repo (no '..' traversal)")
+        if seg == ".git":
+            raise ValueError(
+                f"mount path {path!r} must never name '.git'")
+        if seg in HOST_ONLY_MOUNT_DIRS:
+            raise ValueError(
+                f"mount path {path!r} names the host-only dir {seg!r}")
+    return "/".join(parts) if parts else "."
+
+
+def parse_egress_target(spec: str) -> tuple[str, int | None]:
+    """Parse ``host``, ``host:port``, or ``scheme://host[:port]`` into
+    ``(host, port)``. Malformed entries that can never match fail loud
+    (BR-6.3)."""
+    value = spec.strip()
+    if "://" in value:
+        value = value.split("://", 1)[1]
+    if "/" in value or value == "":
+        raise ValueError(
+            f"malformed egress target {spec!r}: expected host or host:port")
+    # IPv6 literal: [::1]:443
+    if value.startswith("["):
+        end = value.find("]")
+        if end == -1:
+            raise ValueError(f"malformed egress target {spec!r}: bad IPv6 literal")
+        host = value[1:end]
+        rest = value[end + 1:]
+        if rest.startswith(":"):
+            return host, parse_egress_port(spec, rest[1:])
+        if rest:
+            raise ValueError(f"malformed egress target {spec!r}")
+        return host, None
+    if value.count(":") == 1:
+        host, port = value.rsplit(":", 1)
+        return host, parse_egress_port(spec, port)
+    if value.count(":") > 1:
+        raise ValueError(f"malformed egress target {spec!r}: ambiguous port")
+    return value, None
+
+
+def parse_egress_port(spec: str, port: str) -> int | None:
+    """Validate a target port: numeric and within 1-65535 (BR-6.3)."""
+    if port == "":
+        raise ValueError(f"malformed egress target {spec!r}: empty port")
+    if not port.isdigit():
+        raise ValueError(f"malformed egress target {spec!r}: port {port!r} not numeric")
+    n = int(port)
+    if not 1 <= n <= 65535:
+        raise ValueError(f"malformed egress target {spec!r}: port {n} out of range")
+    return n
+
+
+def _validate_egress_target(target: str) -> str:
+    """Validate and canonicalise one egress target (BR-6.3/BR-8.4): non-empty,
+    scheme stripped, host or host:port shape, port 1-65535. Malformed entries
+    fail loud at load, so ``--dry-run`` is a true load-and-validate pass."""
+    if not isinstance(target, str) or not target.strip():
+        raise ValueError("egress target must be a non-empty string")
+    host, port = parse_egress_target(target)
+    if port is None:
+        return host
+    if ":" in host:  # IPv6 literal needs brackets before a port
+        return f"[{host}]:{port}"
+    return f"{host}:{port}"
 
 
 class VerdictSpec(BaseModel):
@@ -113,6 +206,70 @@ class IsolationConfig(BaseModel):
         return v
 
 
+class MountSpec(BaseModel):
+    """One declared mount entry (unit-5): a repo-relative path plus its
+    mode. ``ro`` is the default (BR-1.2: only declared outputs and caches
+    are ``rw``); validation at construction rejects traversal, ``.git``,
+    and host-only dirs (BR-1.3)."""
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    mode: str = "ro"
+
+    @field_validator("path")
+    @classmethod
+    def _valid_path(cls, v: str) -> str:
+        return _validate_mount_path(v)
+
+    @field_validator("mode")
+    @classmethod
+    def _valid_mode(cls, v: str) -> str:
+        if v not in MOUNT_MODES:
+            raise ValueError(
+                f"mount mode must be 'rw' or 'ro', got {v!r}")
+        return v
+
+
+class EgressSpec(BaseModel):
+    """One declared egress policy (unit-5): an explicit class plus preset
+    references and/or explicit targets. ``class: browser`` is the explicit
+    broad-but-logged browser class (BR-7); the default is a strict
+    allowlist (BR-8). Unknown preset names fail at load (BR-8.4)."""
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    class_: str | None = Field(default=None, alias="class")
+    presets: list[str] = []
+    targets: list[str] = []
+
+    @field_validator("presets", "targets", mode="before")
+    @classmethod
+    def _coerce_list(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
+
+    @field_validator("class_")
+    @classmethod
+    def _known_class(cls, v: str | None) -> str | None:
+        if v is not None and v not in EGRESS_CLASSES:
+            raise ValueError(
+                f"egress class must be 'allowlist' or 'browser', got {v!r}")
+        return v
+
+    @field_validator("presets")
+    @classmethod
+    def _known_presets(cls, v: list[str]) -> list[str]:
+        for name in v:
+            if name not in KNOWN_EGRESS_PRESETS:
+                raise ValueError(
+                    f"unknown egress preset {name!r} (known: "
+                    f"{sorted(KNOWN_EGRESS_PRESETS)})")
+        return v
+
+    @field_validator("targets")
+    @classmethod
+    def _valid_targets(cls, v: list[str]) -> list[str]:
+        return [_validate_egress_target(t) for t in v]
+
+
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
     `agent`, `action`, or `command` - empty values do not count, anything
@@ -133,6 +290,12 @@ class StepConfig(BaseModel):
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
     network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
+    # unit-5: per-step mount granularity + egress policy. Empty mounts =
+    # strict-by-default (BR-1.1); egress None = strict empty allowlist
+    # (BR-8.3). Host-side built-in actions are refused these at registry
+    # time (the schema cannot tell host-side from sandbox actions).
+    mounts: list[MountSpec] = []
+    egress: EgressSpec | None = None
     secrets: list[str] = []  # declared ref names; action steps reject
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
@@ -281,6 +444,26 @@ class PipelineConfig(BaseModel):
                 "enforces, or set 'deps_policy: open'")
         return self
 
+    @model_validator(mode="after")
+    def _mounts_avoid_state_dir(self) -> "PipelineConfig":
+        """BR-1.3: the host-only run-state dir is never a mount path.
+        A relative ``state_dir`` (e.g. ``.pr``) lives inside the
+        workspace and must be refused as a mount; the default relocated
+        state_dir is absolute/outside the workspace, so relative mount
+        paths can never collide with it.
+        """
+        sd = self.state_dir.strip().rstrip("/\\")
+        if not sd or sd in ("/", "."):
+            return self
+        for step in self.steps:
+            for m in step.mounts:
+                mp = m.path.rstrip("/")
+                if mp == sd or mp.startswith(sd + "/"):
+                    raise ValueError(
+                        f"step {step.name!r}: mount path {m.path!r} names "
+                        f"the host-only state_dir {self.state_dir!r}")
+        return self
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]

{agentic_dev_loop-1.0.0a17 → agentic_dev_loop-1.0.0a19}/src/agentic_dev_loop/engine/agents.py

@@ -65,13 +65,15 @@ class SandboxTerminalExecutor(ToolExecutor):
     def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
                  env: dict[str, str] | None = None,
                  pipeline: str | None = None, step: str | None = None,
-                 network: bool = False):
+                 network: bool = False, mount_set=None, egress_policy=None):
         self._sandbox = sandbox
         self._workspace = workspace
         self._env = env or {}
         self._pipeline = pipeline
         self._step = step
         self._network = network
+        self._mount_set = mount_set
+        self._egress_policy = egress_policy
 
     def __call__(self, action, conversation=None):
         from openhands.tools.terminal import TerminalObservation
@@ -92,7 +94,8 @@ class SandboxTerminalExecutor(ToolExecutor):
         request = SandboxExecutionRequest(
             argv=command_argv(action.command), cwd=self._workspace,
             env=self._env, timeout=action.timeout,
-            pipeline=self._pipeline, step=self._step, network=self._network)
+            pipeline=self._pipeline, step=self._step, network=self._network,
+            mount_set=self._mount_set, egress_policy=self._egress_policy)
         result = self._sandbox.run(request)
         output = result.stdout + result.stderr
         return TerminalObservation.from_text(
@@ -111,6 +114,7 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
                               workspace: str = "", pipeline: str | None = None,
                               step: str | None = None,
                               network: bool = False,
+                              mount_set=None, egress_policy=None,
                               secrets: dict[str, str] | None = None) -> None:
     """Per-run re-registration of the `terminal` name (KD-4): a callable
     factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
@@ -127,6 +131,7 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
             conv_state,
             executor=SandboxTerminalExecutor(
                 sandbox, workspace=workspace, env=resolved_env,
-                pipeline=pipeline, step=step, network=network))
+                pipeline=pipeline, step=step, network=network,
+                mount_set=mount_set, egress_policy=egress_policy))
 
     register_tool("terminal", factory)

{agentic_dev_loop-1.0.0a17 → agentic_dev_loop-1.0.0a19}/src/agentic_dev_loop/engine/dryrun.py

@@ -18,7 +18,7 @@ from .loaders import resolve_docs
 from .isolation import (isolation_state_dir, resolve_effective_profile,
                         resolve_image_ref, resolved_seccomp_profile)
 from .registry import (Registry, default_registry, load_extensions,
-                       validate_action_network)
+                       validate_action_mounts_egress, validate_action_network)
 from .secrets import scan_env_files
 
 
@@ -46,6 +46,8 @@ def _validate_actions(cfg: PipelineConfig, registry: Registry) -> None:
                 f"step {step.name!r}: unknown action {step.action!r} "
                 f"(registered: {sorted(known)})")
         validate_action_network(step.name, step.action, step.network, registry)
+        validate_action_mounts_egress(step.name, step.action, step.mounts,
+                                      step.egress, registry)
 
 
 def _resolved_image(cfg: PipelineConfig) -> tuple[str, str, float]:

agentic_dev_loop-1.0.0a19/src/agentic_dev_loop/engine/egress_policy.py

@@ -0,0 +1,120 @@
+"""Egress policy assembly and target matching (unit-5).
+
+The pure half of the egress model: ``assemble_egress_policy`` expands preset
+references into a resolved ``EgressPolicy`` and classifies its class;
+``match_target`` decides one connection (BR-6). The proxy (egress_proxy.py) is
+the enforcement point that calls these; both are Docker-free and portable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentic_dev_loop.core.config import (
+    EgressSpec, parse_egress_port, parse_egress_target,
+)
+from .presets import expand_presets
+
+ALLOWLIST = "allowlist"
+# The explicit broad-but-logged browser class (BR-7): no target filtering,
+# every connection logged host-side.
+BROWSER = "browser"
+
+
+@dataclass(frozen=True)
+class TargetEntry:
+    """One resolved allowlist target (BR-6.1): a domain-shaped host with an
+    optional port constraint. ``host`` may also be a stable IP literal (the
+    Q2 exception); it is never resolved to an IP at assembly."""
+
+    host: str
+    port: int | None = None
+
+    @classmethod
+    def from_spec(cls, spec: str) -> "TargetEntry":
+        host, port = parse_egress_target(spec)
+        return cls(host=host, port=port)
+
+    def to_spec(self) -> str:
+        if self.port is None:
+            return self.host
+        return f"{self.host}:{self.port}"
+
+
+@dataclass(frozen=True)
+class EgressPolicy:
+    """The resolved egress policy: an expanded target set plus its class.
+    ``browser`` (broad-but-logged) allows everything; ``allowlist`` denies
+    everything not named (BR-6.2)."""
+
+    targets: tuple[TargetEntry, ...] = ()
+    policy_class: str = ALLOWLIST
+
+    def to_spec(self) -> EgressSpec:
+        cls = None if self.policy_class == ALLOWLIST else BROWSER
+        return EgressSpec(
+            class_=cls,
+            presets=[],
+            targets=[t.to_spec() for t in self.targets],
+        )
+
+
+def assemble_egress_policy(egress: EgressSpec | None) -> EgressPolicy:
+    """Resolve the step's egress declaration into a policy (Q9/BR-7/BR-8).
+
+    ``None`` yields a strict empty allowlist (deny all - the engine never
+    adds an undeclared target, BR-8.3). ``class: browser`` yields the explicit
+    broad-but-logged class with no target filtering. Anything else expands
+    presets then explicit targets, deterministically, and classifies strict.
+    """
+    if egress is None:
+        return EgressPolicy()
+    cls = egress.class_ or ALLOWLIST
+    if cls == BROWSER:
+        return EgressPolicy(policy_class=BROWSER)
+    entries: list[TargetEntry] = []
+    if egress.presets:
+        for spec in expand_presets(egress.presets):
+            entries.append(TargetEntry.from_spec(spec))
+    for spec in egress.targets:
+        entries.append(TargetEntry.from_spec(spec))
+    return EgressPolicy(targets=tuple(entries), policy_class=ALLOWLIST)
+
+
+def _split_host_port(hostname: str) -> tuple[str, int | None]:
+    """Split a CONNECT target into (host, port). Bare hostnames carry no port."""
+    value = hostname.strip()
+    if value.startswith("["):
+        end = value.find("]")
+        if end == -1:
+            return value, None
+        host = value[1:end]
+        rest = value[end + 1:]
+        if rest.startswith(":"):
+            return host, parse_egress_port(hostname, rest[1:])
+        return host, None
+    if value.count(":") == 1:
+        host, port = value.rsplit(":", 1)
+        if port.isdigit():
+            return host, int(port)
+        return value, None
+    return value, None
+
+
+def match_target(hostname: str, policy: EgressPolicy) -> bool:
+    """Deny-by-default hostname match against the expanded allowlist (BR-6).
+
+    The browser class allows everything (BR-7). An allowlist entry matches on
+    exact hostname; an entry carrying a port also constrains the connection
+    port, taken from the ``host:port`` CONNECT-target form when present.
+    """
+    if policy.policy_class == BROWSER:
+        return True
+    host, port = _split_host_port(hostname)
+    for entry in policy.targets:
+        if entry.host != host:
+            continue
+        if entry.port is not None and entry.port != port:
+            continue
+        return True
+    return False