agentic-dev-loop 1.0.0a16__tar.gz → 1.0.0a27__tar.gz

{agentic_dev_loop-1.0.0a16/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a16
+Version: 1.0.0a27
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -72,15 +72,31 @@ 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. |
 
 The fixed policies *are* the product: fail fast on missing config/secrets, no
 silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
-artifact hygiene, a single clean-worktree-gated commit point, and no default
-LLM timeout (agent runs are long).
+artifact hygiene, a single clean-worktree-gated commit point, no default LLM
+timeout (agent runs are long), and fail fast on a broken sandbox - daemon-side
+exec failures are classified and stop the run without an agent retry loop,
+while a startup reaper reclaims containers leaked by a crashed run.
+
+## Supported platforms
+
+The engine is plain Linux under the hood and runs wherever a compliant
+Docker engine does:
+
+| Platform | Support |
+| --- | --- |
+| **Linux** | Native. Docker Engine, OrbStack, Colima, or podman with docker compat. |
+| **macOS** | Native. Docker Desktop, OrbStack, or Colima. |
+| **Windows** | Via **WSL2** (Ubuntu distro). Enable Docker Desktop's WSL integration (or run Docker Engine inside the distro) and keep the repo on the WSL filesystem (`~/dev/...`), not `/mnt/c` - bind-mounting a 9p path into containers breaks permissions and is slow. |
+
+Native Windows (outside WSL2) is not supported: every Windows-specific code
+path and test was removed, and CI runs on Ubuntu only.
 
 ## Installation
 
@@ -89,20 +105,21 @@ LLM timeout (agent runs are long).
 | Requirement | Detail |
 | --- | --- |
 | Python | ≥ 3.12 |
-| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, Linux-containers mode is required. |
+| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, run under WSL2: the repo must live on the WSL filesystem, not /mnt/c. |
 | 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 +128,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,13 +228,16 @@ 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. |
 | `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. |
+| `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
+| `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 
@@ -231,7 +251,7 @@ secrets:                              # refs only - never values
     key: KINDIE_CLIENT_SECRET         # provider-specific locator
   r2-keys:
     from: env
-    key: YOSK_R2_KEYS
+    key: R2_KEYS
 
 steps:
   - name: qa
@@ -262,26 +282,176 @@ 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).
+
+### Sync-back conflicts (host edits during a run)
+
+Only declared-`rw` paths sync back to the real repo after a step. If the host
+also edits a declared-`rw` path while the step is running, sync-back prints
+`[isolation] sync-back conflict: ...` and raises `AE-SBX-016`; the host's
+version wins, the baseline is re-snapshotted, and the next step (even
+`echo hello`) runs clean instead of re-raising forever. For append-style logs
+edited by both sides (an audit log, say), declare them in the top-level
+`merge_on_conflict:` list: those paths are union-merged - the host keeps its
+lines, the sandbox's new lines are appended in order, both sides converge, and
+the run continues with `[isolation] merged concurrent edits: ...` on the
+console.
+
+
+## Authoring a loop for your own repo
+
+A consumer repo needs two things written by hand - a pipeline file and the
+agent files it names - both committed before the first run (the host-boundary
+check refuses dirty tooling, and the `commit` step never commits it). Two
+reference layouts ship today: this repo dogfoods the engine on itself
+(python + pytest, no frontend, CLI-only qa), and the consumer repo carries
+the wider shape (.NET + npm frontend + a networked browser-probing qa step).
+
+```
+<repo>/agentic-dev-loop/pipeline.yaml
+<repo>/agentic-dev-loop/sdk_agents/dev.agent.md
+<repo>/agentic-dev-loop/sdk_agents/review.agent.md
+<repo>/agentic-dev-loop/sdk_agents/qa.agent.md
+```
+
+### The agent files
+
+Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
+`name` matches a step's `agent:` value; `tools` lists the tool names the step
+may use (`terminal` always; a repo can add more via extensions, e.g.
+`figma`).
+
+```markdown
+---
+name: review                 # matches a step's `agent:` value
+tools: [terminal]
+---
+# Review Agent
+## WORKFLOW                   # numbered steps
+## RULES                      # absolute never/always rules
+## SANDBOX NOTES              # the sandbox truth for THIS step
+## OUTPUT                     # the verdict contract
+```
+
+Three roles, three contracts:
+
+| Role | Verdict contract | Typical sandbox |
+| --- | --- | --- |
+| dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
+| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
+| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+
+The conventions that make a good agent file - each one below exists because
+an agent burned budget learning it mid-run:
+
+- **State the sandbox truth in the prompt.** Every agent file carries a
+  `SANDBOX NOTES` section naming exactly what its step allows: mounts ro or
+  rw, network on or off, and which gates have already run. Never make the
+  agent discover it.
+- **Gates are the source of truth - cite the record, never re-run.** A
+  command the test gate, the editor-tests gate, or the dev summary reports
+  as run is coverage evidence, cited as `covered by <test>` or the gate
+  record. Review and qa never re-run builds or suites; qa maps every
+  acceptance criterion to existing coverage and probes only the remainder.
+- **dev enumerates its impossible set and stops at it.** The dev prompt
+  says: stop the moment your next step needs a command this sandbox cannot
+  run, and lists the set (package-manager fetches after a new pin, npm or
+  vitest offline, playwright downloads, database-category tests), one
+  attempt per command. That keeps the productive edit/build/test loop and
+  kills doomed retries. The set is toolchain-specific - write yours; this
+  repo's is a single bullet (no package managers), the consumer repo's is
+  four.
+- **Failure output returns as *Previous attempt feedback*.** Steps route
+  `on_fail: { goto: dev, retry: true }`, so gate failure output lands in
+  the dev agent's next context; the dev prompt makes every listed issue a
+  required fix.
+- **No git mutations, ever.** The `commit` step is the single commit point.
+- **`max_iterations` per role.** qa is bounded probing (60 in both
+  reference repos); dev is open-ended construction and stays uncapped
+  (the engine default).
+
+### The pipeline file
+
+The full field reference is above; this is the stage lineup and what to
+adapt per repo.
+
+| Stage | Kind | Typical shape | Why |
+| --- | --- | --- | --- |
+| dev | agent | rw, offline | does the work; edits are untracked |
+| restore | command | network + `presets: [package-registries]` | fetches what dev pinned (`deps_policy: open`) or the locked install; also the audit escalation point |
+| test | command | offline is fine (warm cache) | exit code is the verdict; the source of truth |
+| editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
+| conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
+| review | agent | ro, offline | static conformance verdict |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| commit | action | host-side | the single commit point |
+
+Adaptation checklist for a new repo:
+
+1. `llm:` - model, `base_url`, `api_key_env`.
+2. `isolation:` - toolchain image override (the consumer repo pins a
+   toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
+   only if a stage runs Chromium.
+3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+   (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
+   `frontend-editor/node_modules`); caches are never synced back.
+4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+5. `secrets:` - refs only, resolved from host env; each step opts in to the
+   refs it needs.
+6. `egress:` - `presets: [package-registries]` for fetch steps;
+   `class: browser` (broad-but-logged) for browser-tier qa only.
+7. `deps_policy:` and `lockfiles:` - see
+   [Dependency policy](#dependency-policy-locked-by-default).
+8. The dev prompt's impossible set - write it for your toolchain.
+9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+   docs: shared context for every agent step.
+
+Validate before the first run - dry-run loads and prints the resolved plan
+with no LLM, no Docker, no state writes:
+
+```bash
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run
+```
+
+Then commit the tooling and run for real.
 
 ## Dependency policy (locked by default)
 
@@ -407,7 +577,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
@@ -423,7 +593,7 @@ agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pi
 - The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
   its own repo** - dev → test → review → qa → commit, with the engine's own
   three agent definitions in `sdk_agents/`.
-- CI: `ci.yml` (unit + integration suite, ubuntu + windows),
+- CI: `ci.yml` (unit + integration suite, ubuntu),
   `publish-image.yml` (multi-arch dev image, amd64 + arm64), `release.yml`
   (PyPI publishing).
 

{agentic_dev_loop-1.0.0a16 → agentic_dev_loop-1.0.0a27}/README.md

@@ -30,15 +30,31 @@ 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. |
 
 The fixed policies *are* the product: fail fast on missing config/secrets, no
 silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
-artifact hygiene, a single clean-worktree-gated commit point, and no default
-LLM timeout (agent runs are long).
+artifact hygiene, a single clean-worktree-gated commit point, no default LLM
+timeout (agent runs are long), and fail fast on a broken sandbox - daemon-side
+exec failures are classified and stop the run without an agent retry loop,
+while a startup reaper reclaims containers leaked by a crashed run.
+
+## Supported platforms
+
+The engine is plain Linux under the hood and runs wherever a compliant
+Docker engine does:
+
+| Platform | Support |
+| --- | --- |
+| **Linux** | Native. Docker Engine, OrbStack, Colima, or podman with docker compat. |
+| **macOS** | Native. Docker Desktop, OrbStack, or Colima. |
+| **Windows** | Via **WSL2** (Ubuntu distro). Enable Docker Desktop's WSL integration (or run Docker Engine inside the distro) and keep the repo on the WSL filesystem (`~/dev/...`), not `/mnt/c` - bind-mounting a 9p path into containers breaks permissions and is slow. |
+
+Native Windows (outside WSL2) is not supported: every Windows-specific code
+path and test was removed, and CI runs on Ubuntu only.
 
 ## Installation
 
@@ -47,20 +63,21 @@ LLM timeout (agent runs are long).
 | Requirement | Detail |
 | --- | --- |
 | Python | ≥ 3.12 |
-| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, Linux-containers mode is required. |
+| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, run under WSL2: the repo must live on the WSL filesystem, not /mnt/c. |
 | 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 +86,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,13 +186,16 @@ 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. |
 | `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. |
+| `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
+| `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 
@@ -189,7 +209,7 @@ secrets:                              # refs only - never values
     key: KINDIE_CLIENT_SECRET         # provider-specific locator
   r2-keys:
     from: env
-    key: YOSK_R2_KEYS
+    key: R2_KEYS
 
 steps:
   - name: qa
@@ -220,26 +240,176 @@ 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).
+
+### Sync-back conflicts (host edits during a run)
+
+Only declared-`rw` paths sync back to the real repo after a step. If the host
+also edits a declared-`rw` path while the step is running, sync-back prints
+`[isolation] sync-back conflict: ...` and raises `AE-SBX-016`; the host's
+version wins, the baseline is re-snapshotted, and the next step (even
+`echo hello`) runs clean instead of re-raising forever. For append-style logs
+edited by both sides (an audit log, say), declare them in the top-level
+`merge_on_conflict:` list: those paths are union-merged - the host keeps its
+lines, the sandbox's new lines are appended in order, both sides converge, and
+the run continues with `[isolation] merged concurrent edits: ...` on the
+console.
+
+
+## Authoring a loop for your own repo
+
+A consumer repo needs two things written by hand - a pipeline file and the
+agent files it names - both committed before the first run (the host-boundary
+check refuses dirty tooling, and the `commit` step never commits it). Two
+reference layouts ship today: this repo dogfoods the engine on itself
+(python + pytest, no frontend, CLI-only qa), and the consumer repo carries
+the wider shape (.NET + npm frontend + a networked browser-probing qa step).
+
+```
+<repo>/agentic-dev-loop/pipeline.yaml
+<repo>/agentic-dev-loop/sdk_agents/dev.agent.md
+<repo>/agentic-dev-loop/sdk_agents/review.agent.md
+<repo>/agentic-dev-loop/sdk_agents/qa.agent.md
+```
+
+### The agent files
+
+Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
+`name` matches a step's `agent:` value; `tools` lists the tool names the step
+may use (`terminal` always; a repo can add more via extensions, e.g.
+`figma`).
+
+```markdown
+---
+name: review                 # matches a step's `agent:` value
+tools: [terminal]
+---
+# Review Agent
+## WORKFLOW                   # numbered steps
+## RULES                      # absolute never/always rules
+## SANDBOX NOTES              # the sandbox truth for THIS step
+## OUTPUT                     # the verdict contract
+```
+
+Three roles, three contracts:
+
+| Role | Verdict contract | Typical sandbox |
+| --- | --- | --- |
+| dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
+| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
+| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+
+The conventions that make a good agent file - each one below exists because
+an agent burned budget learning it mid-run:
+
+- **State the sandbox truth in the prompt.** Every agent file carries a
+  `SANDBOX NOTES` section naming exactly what its step allows: mounts ro or
+  rw, network on or off, and which gates have already run. Never make the
+  agent discover it.
+- **Gates are the source of truth - cite the record, never re-run.** A
+  command the test gate, the editor-tests gate, or the dev summary reports
+  as run is coverage evidence, cited as `covered by <test>` or the gate
+  record. Review and qa never re-run builds or suites; qa maps every
+  acceptance criterion to existing coverage and probes only the remainder.
+- **dev enumerates its impossible set and stops at it.** The dev prompt
+  says: stop the moment your next step needs a command this sandbox cannot
+  run, and lists the set (package-manager fetches after a new pin, npm or
+  vitest offline, playwright downloads, database-category tests), one
+  attempt per command. That keeps the productive edit/build/test loop and
+  kills doomed retries. The set is toolchain-specific - write yours; this
+  repo's is a single bullet (no package managers), the consumer repo's is
+  four.
+- **Failure output returns as *Previous attempt feedback*.** Steps route
+  `on_fail: { goto: dev, retry: true }`, so gate failure output lands in
+  the dev agent's next context; the dev prompt makes every listed issue a
+  required fix.
+- **No git mutations, ever.** The `commit` step is the single commit point.
+- **`max_iterations` per role.** qa is bounded probing (60 in both
+  reference repos); dev is open-ended construction and stays uncapped
+  (the engine default).
+
+### The pipeline file
+
+The full field reference is above; this is the stage lineup and what to
+adapt per repo.
+
+| Stage | Kind | Typical shape | Why |
+| --- | --- | --- | --- |
+| dev | agent | rw, offline | does the work; edits are untracked |
+| restore | command | network + `presets: [package-registries]` | fetches what dev pinned (`deps_policy: open`) or the locked install; also the audit escalation point |
+| test | command | offline is fine (warm cache) | exit code is the verdict; the source of truth |
+| editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
+| conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
+| review | agent | ro, offline | static conformance verdict |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| commit | action | host-side | the single commit point |
+
+Adaptation checklist for a new repo:
+
+1. `llm:` - model, `base_url`, `api_key_env`.
+2. `isolation:` - toolchain image override (the consumer repo pins a
+   toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
+   only if a stage runs Chromium.
+3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+   (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
+   `frontend-editor/node_modules`); caches are never synced back.
+4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+5. `secrets:` - refs only, resolved from host env; each step opts in to the
+   refs it needs.
+6. `egress:` - `presets: [package-registries]` for fetch steps;
+   `class: browser` (broad-but-logged) for browser-tier qa only.
+7. `deps_policy:` and `lockfiles:` - see
+   [Dependency policy](#dependency-policy-locked-by-default).
+8. The dev prompt's impossible set - write it for your toolchain.
+9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+   docs: shared context for every agent step.
+
+Validate before the first run - dry-run loads and prints the resolved plan
+with no LLM, no Docker, no state writes:
+
+```bash
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run
+```
+
+Then commit the tooling and run for real.
 
 ## Dependency policy (locked by default)
 
@@ -365,7 +535,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
@@ -381,7 +551,7 @@ agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pi
 - The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
   its own repo** - dev → test → review → qa → commit, with the engine's own
   three agent definitions in `sdk_agents/`.
-- CI: `ci.yml` (unit + integration suite, ubuntu + windows),
+- CI: `ci.yml` (unit + integration suite, ubuntu),
   `publish-image.yml` (multi-arch dev image, amd64 + arm64), `release.yml`
   (PyPI publishing).
 

{agentic_dev_loop-1.0.0a16 → agentic_dev_loop-1.0.0a27}/pyproject.toml

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