agentic-dev-loop 1.0.0a26__tar.gz → 1.0.0a28__tar.gz

{agentic_dev_loop-1.0.0a26/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a26
+Version: 1.0.0a28
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -84,6 +84,20 @@ 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
 
 **Prerequisites**
@@ -91,7 +105,7 @@ while a startup reaper reclaims containers leaked by a crashed run.
 | 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
@@ -214,7 +228,7 @@ 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` lets a command/agent step reach the hosts its `egress:` allowlist names (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 before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `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). |
@@ -222,7 +236,7 @@ steps:
 | `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). |
+| `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); a `setup:` hook can warm them (the provision container carries the same cache mounts); `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
@@ -418,7 +432,8 @@ Adaptation checklist for a new repo:
    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.
+   `frontend-editor/node_modules`); caches are never synced back, and a
+   step's `setup:` hook runs with them mounted so it can warm them.
 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.
@@ -579,7 +594,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.0a26 → agentic_dev_loop-1.0.0a28}/README.md

@@ -42,6 +42,20 @@ 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
 
 **Prerequisites**
@@ -49,7 +63,7 @@ while a startup reaper reclaims containers leaked by a crashed run.
 | 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
@@ -172,7 +186,7 @@ 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` lets a command/agent step reach the hosts its `egress:` allowlist names (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 before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `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). |
@@ -180,7 +194,7 @@ steps:
 | `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). |
+| `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); a `setup:` hook can warm them (the provision container carries the same cache mounts); `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
@@ -376,7 +390,8 @@ Adaptation checklist for a new repo:
    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.
+   `frontend-editor/node_modules`); caches are never synced back, and a
+   step's `setup:` hook runs with them mounted so it can warm them.
 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.
@@ -537,7 +552,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.0a26 → agentic_dev_loop-1.0.0a28}/pyproject.toml

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

@@ -386,9 +386,9 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'timeout' requires 'command'"
             )
-        if self.setup is not None and self.command is None:
+        if self.setup is not None and self.command is None and self.agent is None:
             raise ValueError(
-                f"step {self.name!r}: 'setup' is only allowed on 'command' steps"
+                f"step {self.name!r}: 'setup' is only allowed on 'command' or 'agent' steps"
             )
         # `network` is NOT rejected here: the schema can't tell a host-side
         # built-in action (e.g. `commit`, which must never take egress) from

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/src/agentic_dev_loop/engine/isolation.py

@@ -699,11 +699,14 @@ 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,
-                             sandbox_venv_dir: str | None = None) -> list[str]:
+                             sandbox_venv_dir: str | None = None,
+                             cache_mounts: list[tuple[str, str, 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, mount set
-    {workspace} + host-only masks (022); --user host uid:gid (AE-SBX-009) with
-    HOME=/tmp."""
+    {workspace} + host-only masks (022) + the declared cache paths (028, rw
+    bind mounts so a ``setup:`` hook can warm them); --user host uid:gid
+    (AE-SBX-009) with HOME=/tmp."""
     payload = [
         "docker", "run", "--rm", "--name", f"{run_id}-provision",
         "--network", "bridge", "--cap-drop", "ALL",
@@ -713,6 +716,8 @@ def docker_provision_payload(*, run_id: str, image: str, workspace: str,
     if user is not None:
         payload.extend(["--user", user, "--env", "HOME=/tmp"])
     payload.extend(_sandbox_mounts(workspace, sandbox_venv_dir))
+    for source, target, _mode in (cache_mounts or []):
+        payload += ["-v", f"{source}:{target}"]
     payload.extend([
         "--workdir", workspace,
         image, "sh", "-c", setup_cmd,
@@ -995,7 +1000,8 @@ class DockerBackend(Sandbox):
                 return
         payload = docker_provision_payload(
             run_id=self._run_id, image=self._image, workspace=self._workspace,
-            setup_cmd=setup_cmd, sandbox_venv_dir=self._sandbox_venv_dir)
+            setup_cmd=setup_cmd, sandbox_venv_dir=self._sandbox_venv_dir,
+            cache_mounts=self._cache_mounts)
         res = self._runner.run(payload, timeout=PROVISION_TIMEOUT_SECONDS)
         if res.exit_code != 0:
             tail = (res.stdout or res.stderr or "")[-4000:]
@@ -1541,7 +1547,9 @@ def _file_digest(p: Path) -> str:
 def _declared_setups(cfg: PipelineConfig, workspace: Path):
     hashes = _lockfile_hashes(workspace)
     for step in cfg.steps:
-        if step.command is not None and step.setup is not None:
+        if step.setup is not None and (
+            step.command is not None or step.agent is not None
+        ):
             yield step.setup, setup_stamp_key(step.setup, hashes)
 
 

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/src/agentic_dev_loop/engine/proc.py

@@ -9,9 +9,7 @@ from __future__ import annotations
 
 import os
 import shlex
-import shutil
 import signal
-import subprocess
 from collections.abc import Mapping
 
 _SHELL_METACHARS = frozenset("&|;><$`~*?[]")
@@ -33,47 +31,21 @@ def split_command(command: str) -> list[str]:
     return shlex.split(command)
 
 
-def host_shell_execution(
-        command: str, *, nt: bool = os.name == "nt",
-        which=shutil.which) -> tuple[str | list[str], bool]:
-    """How the HOST (non-sandbox) path executes a shell-needing command.
-
-    POSIX: the raw string with ``shell=True`` (unchanged unit-2 behaviour).
-    Windows: ``shell=True`` is cmd.exe, which mangles ``$VAR`` expansion and
-    ``|`` pipelines (the CI-red hybrid failures) - prefer the discovered
-    POSIX ``sh`` (git-bash) via argv instead; fall back to ``shell=True``
-    only when no ``sh`` exists anywhere on PATH.
-    """
-    if not nt:
-        return command, True
-    sh = which("sh")
-    if sh:
-        return [sh, "-c", command], False
+def host_shell_execution(command: str) -> tuple[str, bool]:
+    """How the HOST (non-sandbox) path executes a shell-needing command:
+    the raw string with ``shell=True``. The engine targets Linux and WSL2
+    (which is plain Linux), so ``sh`` is always present."""
     return command, True
 
 
-def kill_process_tree(proc, *, nt: bool | None = None,
-                      run=subprocess.run) -> None:
+def kill_process_tree(proc) -> None:
     """Terminate `proc` and its descendants after a timeout.
 
-    POSIX: ``start_new_session`` made ``proc.pid`` the process-group id -
+    ``start_new_session`` made ``proc.pid`` the process-group id, so
     ``killpg`` reaps the whole group (a shell wrapper's children survive a
     plain ``kill``).
-
-    Windows: ``proc.kill()`` terminates only the direct child - a git-bash
-    ``sh -c`` wrapper's python child survives and keeps the pipes open, so
-    the follow-up ``communicate()`` blocks out the child's full lifetime.
-    ``taskkill /T`` walks the process tree while the parent is still alive,
-    then ``kill`` sweeps up anything left (CI-red: 9.5s timeout test).
     """
-    if nt is None:
-        nt = os.name == "nt"
-    if nt:
-        run(["taskkill", "/F", "/T", "/PID", str(proc.pid)],
-            capture_output=True, check=False)
-        proc.kill()
-    else:
-        os.killpg(proc.pid, signal.SIGKILL)
+    os.killpg(proc.pid, signal.SIGKILL)
 
 
 def is_pid_token(token: str) -> bool:

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/src/agentic_dev_loop/engine/stages.py

@@ -409,7 +409,7 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
                     update["artifacts"] = {step.name: result.response}
                 return update
             if verdict == "unverifiable":
-                print(f"[{subject}] {step.name} qa verdict: UNVERIFIABLE "
+                print(f"[{subject}] {step.name} verdict: UNVERIFIABLE "
                       f"(moves on).", flush=True)
                 update = {"step_verdicts": merged, "failed": False}
                 if captures and result.response is not None:

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a26
+Version: 1.0.0a28
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -84,6 +84,20 @@ 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
 
 **Prerequisites**
@@ -91,7 +105,7 @@ while a startup reaper reclaims containers leaked by a crashed run.
 | 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
@@ -214,7 +228,7 @@ 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` lets a command/agent step reach the hosts its `egress:` allowlist names (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 before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `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). |
@@ -222,7 +236,7 @@ steps:
 | `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). |
+| `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); a `setup:` hook can warm them (the provision container carries the same cache mounts); `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
@@ -418,7 +432,8 @@ Adaptation checklist for a new repo:
    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.
+   `frontend-editor/node_modules`); caches are never synced back, and a
+   step's `setup:` hook runs with them mounted so it can warm them.
 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.
@@ -579,7 +594,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.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_actions.py

@@ -375,9 +375,8 @@ class TestCommitNode:
 
     def test_add_excludes_live_checkpoint_db(self, tmp_path, monkeypatch):
         """The live checkpointer DB under state_dir stays open for the whole
-        run; on Windows an open SQLite file blocks other readers and
-        `git add -A` fails to hash it (CI-red gate failure). The add must
-        exclude sqlite files under the state dir on every OS."""
+        run, so `git add -A` cannot hash it. The add must exclude sqlite
+        files under the state dir."""
         repo = tmp_path / "repo"
         init_git_repo(repo)
         (repo / "feature.cs").write_text("// constructed by the pipeline")

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_config.py

@@ -489,15 +489,19 @@ class TestStepEnvAndSetup:
                           "on_pass": "success"}]
         assert _load(tmp_path, data).steps[0].setup is not None
 
-    @pytest.mark.parametrize("step", [
-        {"name": "x", "agent": "dev", "setup": "npm i"},
-        {"name": "x", "action": "commit", "setup": "npm i"},
-    ])
-    def test_setup_rejected_on_non_command_steps(self, tmp_path, step):
+    def test_setup_allowed_on_agent_step(self, tmp_path):
         data = _base()
-        data["steps"] = [step | {"on_pass": "success"}]
-        with pytest.raises(ValidationError,
-                           match="'setup' is only allowed on 'command' steps"):
+        data["steps"] = [{"name": "dev", "agent": "dev", "setup": "npm i",
+                          "on_pass": "success"}]
+        assert _load(tmp_path, data).steps[0].setup == "npm i"
+
+    def test_setup_rejected_on_action_step(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "x", "action": "commit", "setup": "npm i",
+                          "on_pass": "success"}]
+        with pytest.raises(
+                ValidationError,
+                match="'setup' is only allowed on 'command' or 'agent' steps"):
             _load(tmp_path, data)
 
     def test_env_round_trip(self, tmp_path):

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_isolation.py

@@ -2109,3 +2109,43 @@ class TestReaper:
         self._write(tmp_path / "state", [own, other])
         backend.close()
         assert self._read(tmp_path / "state") == [other]
+
+
+def test_declared_setups_includes_agent_steps(tmp_path):
+    import yaml
+
+    from agentic_dev_loop.core.config import load_config
+    from agentic_dev_loop.engine.isolation import _declared_setups
+
+    (tmp_path / "uv.lock").write_text("")
+    data = {
+        "name": "t",
+        "llm": {"model": "m", "api_key_env": "K"},
+        "agents_dir": "agents",
+        "lockfiles": ["uv.lock"],
+        "steps": [
+            {"name": "dev", "agent": "dev",
+             "setup": "cd frontend-editor && npm ci", "on_pass": "success"},
+            {"name": "t", "command": "make", "setup": "echo warm",
+             "on_pass": "success"},
+        ],
+    }
+    p = tmp_path / "pipeline.yaml"
+    p.write_text(yaml.safe_dump(data))
+    cfg = load_config(p)
+    assert set(dict(_declared_setups(cfg, tmp_path))) == {
+        "cd frontend-editor && npm ci", "echo warm"}
+
+
+def test_provision_payload_mounts_declared_caches():
+    payload = docker_provision_payload(
+        run_id="run1",
+        image="img",
+        workspace="/ws",
+        setup_cmd="cd frontend-editor && npm ci",
+        cache_mounts=[
+            ("/host/fe/node_modules", "/ws/frontend-editor/node_modules", "rw"),
+        ],
+    )
+    assert "-v" in payload
+    assert "/host/fe/node_modules:/ws/frontend-editor/node_modules" in payload

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_proc.py

@@ -5,11 +5,8 @@ stateless pure functions shared by the command-step and action-step
 surfaces; property tests exercise the invariants that keep the subprocess
 boundary fail-safe (BR-4, BR-5)."""
 
-import os
-import pytest
 import signal
 import string
-import subprocess
 
 from hypothesis import given, settings
 from hypothesis import strategies as st
@@ -45,23 +42,10 @@ class TestNeedsShell:
 
 
 class TestHostShellExecution:
-    """How the HOST (non-sandbox) path executes a shell-needing command.
-    Windows cannot rely on shell=True - cmd.exe mangles $VAR and pipelines
-    (the CI-red hybrid failures) - so it prefers the discovered POSIX sh."""
+    """How the HOST (non-sandbox) path executes a shell-needing command."""
 
-    def test_posix_uses_shell_true(self):
-        argv, shell = host_shell_execution("a && b", nt=False)
-        assert (argv, shell) == ("a && b", True)
-
-    def test_windows_prefers_discovered_sh(self):
-        which = lambda name: "C:/Program Files/Git/bin/sh.exe"  # noqa: E731
-        argv, shell = host_shell_execution("a && b", nt=True, which=which)
-        assert argv == ["C:/Program Files/Git/bin/sh.exe", "-c", "a && b"]
-        assert shell is False
-
-    def test_windows_without_sh_falls_back_to_shell_true(self):
-        argv, shell = host_shell_execution("a && b", nt=True,
-                                           which=lambda name: None)
+    def test_uses_shell_true(self):
+        argv, shell = host_shell_execution("a && b")
         assert (argv, shell) == ("a && b", True)
 
 
@@ -144,10 +128,8 @@ class TestChildEnv:
 
 
 class TestKillProcessTree:
-    """The timeout reap path. CI-red on Windows: `proc.kill()` terminates
-    only the direct child - a git-bash `sh -c` wrapper's python child
-    survives, keeps the pipes open, and the follow-up communicate() blocks
-    out the full sleep. The tree must be reaped root-to-leaves."""
+    """The timeout reap path: ``start_new_session`` made ``proc.pid`` the
+    process-group id, so ``killpg`` reaps the whole tree."""
 
     class _Proc:
         def __init__(self, log):
@@ -157,30 +139,14 @@ class TestKillProcessTree:
         def kill(self):
             self.log.append("kill")
 
-    @pytest.mark.skipif(not hasattr(os, "killpg"), reason="POSIX-only: os.killpg does not exist on Windows")
-    def test_posix_reaps_the_whole_process_group(self, monkeypatch):
+    def test_reaps_the_whole_process_group(self, monkeypatch):
         killed = []
         monkeypatch.setattr(
             "agentic_dev_loop.engine.proc.os.killpg",
             lambda pid, sig: killed.append((pid, sig)))
         proc = self._Proc([])
 
-        kill_process_tree(proc, nt=False)
+        kill_process_tree(proc)
 
         assert killed == [(99, signal.SIGKILL)]
         assert proc.log == []  # the wrapper needs no separate kill
-
-    def test_windows_taskkills_the_tree_then_kills_the_wrapper(self):
-        log = []
-        proc = self._Proc(log)
-
-        def fake_run(argv, **kwargs):
-            log.append("taskkill")
-            assert argv == ["taskkill", "/F", "/T", "/PID", "99"]
-            return subprocess.CompletedProcess(argv, 0, "", "")
-
-        kill_process_tree(proc, nt=True, run=fake_run)
-
-        # taskkill /T needs the parent alive to walk the tree - then the
-        # wrapper itself is swept up.
-        assert log == ["taskkill", "kill"]

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_stages.py

@@ -393,8 +393,8 @@ class TestCommandNode:
         """The host-path timeout must cut the WHOLE tree short, not just the
         direct child - a shell wrapper's grandchild that survives keeps the
         pipes open and the follow-up communicate() blocks out the full sleep
-        (CI-red 9.5s). kill_process_tree's per-OS branches are unit-pinned
-        in tests/test_proc.py::TestKillProcessTree."""
+        (CI-red 9.5s). kill_process_tree is unit-pinned in
+        tests/test_proc.py::TestKillProcessTree."""
         code, out, timed_out = _run_command(
             f'"{sys.executable}" -c "import time; time.sleep(30)"',
             tmp_path, 0.2)

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_sync_back.py

@@ -338,9 +338,9 @@ class TestMergeOnConflictPartition:
         exp = _export(tmp_path, ws)
         (ws / "src" / "audit.md").write_text("base\n")
         (exp / "src" / "audit.md").write_text("base\nexport\n")
-        # Baseline comes from the real workspace bytes: write_text translates
-        # \n to os.linesep on Windows, so a fabricated sha256(b"base\n") would
-        # never match and would misclassify the copy as a merge conflict.
+        # Baseline comes from the real workspace bytes, so a fabricated
+        # sha256(b"base\n") would never match and would misclassify the
+        # copy as a merge conflict.
         baseline = {"src/audit.md": _digest(ws / "src" / "audit.md")}
         report = sync_back(exp, ws, ["src"], baseline=baseline,
                            merge_on_conflict=["src/audit.md"])

{agentic_dev_loop-1.0.0a26 → agentic_dev_loop-1.0.0a28}/tests/test_trigger_script.py

@@ -6,11 +6,7 @@ a stale install rejects newer pipeline configs at load time (e.g.
 is upgraded on every run. Tests drive the real script with stub
 executables on PATH - no network, no mocks of the script's logic.
 
-The script is bash, so it is executed through `bash` on every platform:
-Windows cannot CreateProcess a `.sh` file (shebangs are a POSIX concept)
-and its MSYS bash (git-bash, preinstalled on windows-latest runners)
-understands only POSIX-style paths (`/c/...`), so PATH entries and
-redirect targets inside stub bodies are converted accordingly.
+The script is bash, so it is executed through `bash`.
 """
 
 import os
@@ -24,19 +20,6 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 SCRIPT = REPO_ROOT / "trigger-agentic-dev-loop.sh"
 
 
-def _msys(path: Path) -> str:
-    """POSIX-style form of a Windows path (`C:\\x` -> `/c/x`).
-
-    MSYS bash splits PATH on `:` and treats backslashes as escapes, so a
-    native `C:\\...` entry would fragment into `C` + `\\...`. Pass the
-    mount-style form instead. On POSIX the path is returned unchanged.
-    """
-    if os.name != "nt":
-        return str(path)
-    drive, rest = os.path.splitdrive(str(path))
-    return "/" + drive[0].lower() + rest.replace("\\", "/")
-
-
 def _bash() -> str:
     bash = shutil.which("bash")
     if bash is None:
@@ -46,7 +29,7 @@ def _bash() -> str:
 
 def _run_script(*args: str, env: dict) -> subprocess.CompletedProcess:
     return subprocess.run(
-        [_bash(), _msys(SCRIPT), *args],
+        [_bash(), str(SCRIPT), *args],
         capture_output=True,
         text=True,
         env=env,
@@ -64,7 +47,7 @@ def _make_stub(bin_dir: Path, name: str, body: str) -> None:
 def _env_with(bin_dir: Path | None = None) -> dict:
     entries = ["/usr/bin", "/bin"]
     if bin_dir is not None:
-        entries.insert(0, _msys(bin_dir))
+        entries.insert(0, str(bin_dir))
     return {**os.environ, "PATH": ":".join(entries)}
 
 
@@ -80,7 +63,7 @@ def test_trigger_upgrades_existing_install(tmp_path):
     _make_stub(
         bin_dir,
         "pipx",
-        f'echo "$*" >> "{_msys(pipx_log)}"',
+        f'echo "$*" >> "{str(pipx_log)}"',
     )
 
     result = _run_script("--plan", "plan.md", env=_env_with(bin_dir))