agentic-dev-loop 1.0.0a39__tar.gz → 1.0.0a41__tar.gz

{agentic_dev_loop-1.0.0a39/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a39
+Version: 1.0.0a41
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -160,6 +160,16 @@ agentic-dev-loop pipeline.yaml --resume <thread-id> --max-attempts 5
 
 Exit code is `0` on pipeline success, `1` otherwise.
 
+`agentic-dev-loop containers` inspects the engine's sandbox containers and
+networks from the host: the default list is read-only and resolves each
+engine-owned object to its owning run and a `live`, `orphaned`,
+`stale-entry`, or `unregistered` verdict; `containers --reap` removes only
+registry-owned orphans whose owner pid is dead (never unregistered names).
+A SIGTERM to a running pipeline still closes the sandbox (the graph's
+`finally` runs); SIGKILL is unhandleable, so its containers are reclaimed by
+the startup reaper on the next run or by `containers --reap`. Pass
+`--state-dir` to point at a custom `isolation.state_dir`.
+
 **What a run looks like** (the shipped self-loop example):
 
 ![The live graph view - pipeline stages with verdict badges, retry cycles, and per-stage consoles](docs/viz-screenshot.png)

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/README.md

@@ -118,6 +118,16 @@ agentic-dev-loop pipeline.yaml --resume <thread-id> --max-attempts 5
 
 Exit code is `0` on pipeline success, `1` otherwise.
 
+`agentic-dev-loop containers` inspects the engine's sandbox containers and
+networks from the host: the default list is read-only and resolves each
+engine-owned object to its owning run and a `live`, `orphaned`,
+`stale-entry`, or `unregistered` verdict; `containers --reap` removes only
+registry-owned orphans whose owner pid is dead (never unregistered names).
+A SIGTERM to a running pipeline still closes the sandbox (the graph's
+`finally` runs); SIGKILL is unhandleable, so its containers are reclaimed by
+the startup reaper on the next run or by `containers --reap`. Pass
+`--state-dir` to point at a custom `isolation.state_dir`.
+
 **What a run looks like** (the shipped self-loop example):
 
 ![The live graph view - pipeline stages with verdict badges, retry cycles, and per-stage consoles](docs/viz-screenshot.png)

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/pyproject.toml

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

@@ -148,6 +148,7 @@ class VerdictSpec(BaseModel):
     pass_: str = Field(alias="pass")
     fail: str = Field(alias="fail")
     unverifiable: str | None = None
+    env: str | None = None
 
 
 class Route(BaseModel):
@@ -404,6 +405,7 @@ class StepConfig(BaseModel):
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
     on_unverifiable: RouteTarget | None = None
+    on_env: RouteTarget | None = None
 
     @property
     def kind(self) -> str:
@@ -794,7 +796,8 @@ class PipelineConfig(BaseModel):
                 raise ValueError(f"step name {n!r} collides with a reserved terminal")
         valid = set(names) | TERMINALS
         for step in self.steps:
-            for route in (step.on_pass, step.on_fail, step.on_unverifiable):
+            for route in (step.on_pass, step.on_fail, step.on_unverifiable,
+                          step.on_env):
                 target = route_target(route)
                 if target is not None and target not in valid:
                     raise ValueError(

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/src/agentic_dev_loop/engine/cli.py

@@ -6,16 +6,47 @@ extension is listed in that pipeline's YAML."""
 
 import argparse
 import importlib.metadata
+import json
+import os
+import signal
 import sys
 from pathlib import Path
 
 from agentic_dev_loop.core.config import PipelineConfig, load_config
-from .dryrun import dry_run
-from .isolation import clean_stamps, isolation_state_dir
+from .containers import containers_report
+from .isolation import (clean_stamps, isolation_state_dir,
+                        reap_orphaned_containers)
 from .loaders import mark_plan_completed
 from .registry import Registry, default_registry, load_extensions
 
 
+_sigterm_in_progress = False
+
+
+def _handle_sigterm(signum, frame) -> None:
+    """First SIGTERM raises SystemExit(143) so the graph ``finally`` runs
+    close(); a second SIGTERM while already terminating hard-exits (D4)."""
+    global _sigterm_in_progress
+    if _sigterm_in_progress:
+        os._exit(143)
+    _sigterm_in_progress = True
+    raise SystemExit(143)
+
+
+def _install_sigterm_handler():
+    """Install the graceful-shutdown handler; returns the prior handler."""
+    global _sigterm_in_progress
+    _sigterm_in_progress = False
+    return signal.signal(signal.SIGTERM, _handle_sigterm)
+
+
+def _restore_sigterm_handler(previous) -> None:
+    """Restore the prior SIGTERM handler and reset the in-progress flag."""
+    global _sigterm_in_progress
+    _sigterm_in_progress = False
+    signal.signal(signal.SIGTERM, previous)
+
+
 def _version() -> str:
     """The installed distribution version - the single source of truth."""
     try:
@@ -77,6 +108,53 @@ def _registry_for(cfg_path: Path) -> tuple[Registry, PipelineConfig]:
     return registry, cfg
 
 
+def _containers_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentic-dev-loop containers",
+        description="Inspect engine sandbox containers and networks.")
+    parser.add_argument("--reap", action="store_true",
+                        help="reap orphaned registry-owned containers and "
+                             "networks and print their names")
+    parser.add_argument("--json", action="store_true",
+                        help="emit the report or reap result as JSON")
+    parser.add_argument("--state-dir", default="~/.agentic-dev-loop/state",
+                        help="isolation state dir "
+                             "(default: ~/.agentic-dev-loop/state)")
+    return parser
+
+
+def _run_containers(argv: list[str]) -> int:
+    args = _containers_parser().parse_args(argv)
+    state_dir = Path(args.state_dir).expanduser()
+    if args.reap:
+        names = reap_orphaned_containers(state_dir, announce=False)
+        if args.json:
+            print(json.dumps({"reaped": names}, sort_keys=True))
+        else:
+            for name in names:
+                print(name)
+        return 0
+    report = containers_report(state_dir)
+    if args.json:
+        print(json.dumps(report, sort_keys=True))
+    else:
+        _print_containers_report(report)
+    return 0
+
+
+def _print_containers_report(report) -> None:
+    rows = report["containers"] + report["unregistered"]
+    if not rows:
+        print("no engine containers or networks found")
+        return
+    for item in rows:
+        run = item.get("run_id") or "-"
+        pid = item.get("pid")
+        pid_s = str(pid) if pid is not None else "-"
+        print(f"{item['verdict']:12} {item['kind']:9} {item['name']} "
+              f"run={run} pid={pid_s}")
+
+
 def build_parser(cfg_path) -> argparse.ArgumentParser:
     """The full parser for one pipeline: core flags + loader-contributed."""
     registry, _ = _registry_for(cfg_path)
@@ -87,6 +165,12 @@ def build_parser(cfg_path) -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    else:
+        argv = list(argv)
+    if argv and argv[0] == "containers":
+        return _run_containers(argv[1:])
     probe = argparse.ArgumentParser(add_help=False)
     probe.add_argument("pipeline", type=Path, nargs="?")
     _add_version_flag(probe)
@@ -108,16 +192,24 @@ def main(argv: list[str] | None = None) -> int:
               f"{state / 'stamps'}", flush=True)
         return 0
     if args.dry_run:
+        from .dryrun import dry_run
         return dry_run(args.pipeline, args, registry)
-    # The run path alone needs the heavy graph/SDK imports - defer so a
-    # dry run, --clean-stamps, and --help stay side-effect free.
-    from .graph import run_pipeline
-    success, _attempts = run_pipeline(args.pipeline, args, registry=registry)
-    if success and args.plan is not None:
-        # Only a completed run earns the stamp - failed runs leave the plan
-        # as-is. AI-DLC runs never pass --plan, so aidlc docs stay untouched.
-        mark_plan_completed(args.plan)
-    if not success:
-        print("agentic-dev-loop: pipeline failed - exiting with code 1",
-              file=sys.stderr)
-    return 0 if success else 1
+    # The run path alone needs the heavy graph/SDK imports, and --dry-run
+    # needs the dryrun import chain in-branch; defer both so `containers`,
+    # --clean-stamps, --help, and --version stay side-effect free. 042 D4: a
+    # SIGTERM here raises SystemExit(143) so graph.run_pipeline's finally
+    # still closes the sandbox; a second SIGTERM hard-exits.
+    previous = _install_sigterm_handler()
+    try:
+        from .graph import run_pipeline
+        success, _attempts = run_pipeline(args.pipeline, args, registry=registry)
+        if success and args.plan is not None:
+            # Only a completed run earns the stamp - failed runs leave the plan
+            # as-is. AI-DLC runs never pass --plan, so aidlc docs stay untouched.
+            mark_plan_completed(args.plan)
+        if not success:
+            print("agentic-dev-loop: pipeline failed - exiting with code 1",
+                  file=sys.stderr)
+        return 0 if success else 1
+    finally:
+        _restore_sigterm_handler(previous)

agentic_dev_loop-1.0.0a41/src/agentic_dev_loop/engine/containers.py

@@ -0,0 +1,81 @@
+"""Host-side container inspection and reaping (042 D5/D6).
+
+Reads the engine's isolation-state container registry plus the labeled
+engine-owned daemon objects, and resolves each entry to a verdict without
+ever removing anything whose ownership is unproven. The only mutating path is
+``reap_orphaned_containers`` (registry-only, pid-gated), which the CLI's
+``containers --reap`` flag invokes explicitly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .isolation import (CommandRunner, _default_runner, _pid_alive_matches,
+                        _read_registry)
+
+
+def _labeled_names(runner: CommandRunner, kind: str) -> set[str]:
+    """The engine-owned object names currently visible to the daemon."""
+    if kind == "network":
+        argv = ["docker", "network", "ls", "--filter",
+                "label=agentic-dev-loop=true", "--format", "{{.Name}}"]
+    else:
+        argv = ["docker", "ps", "-a", "--filter",
+                "label=agentic-dev-loop=true", "--format", "{{.Names}}"]
+    res = runner.run(argv, timeout=60)
+    if res.exit_code != 0:
+        return set()
+    return {line.strip() for line in res.stdout.splitlines() if line.strip()}
+
+
+def containers_report(state_dir: str | Path,
+                      runner: CommandRunner | None = None) -> dict[str, Any]:
+    """Resolve registry entries and labeled-but-unregistered engine objects
+    to verdicts (042 D5). Read-only: never removes anything.
+
+    Registry entries become ``live`` (object present + owner pid alive with
+    start-time match), ``orphaned`` (object present + owner pid dead), or
+    ``stale-entry`` (entry present, object gone). Labeled objects with no
+    registry entry become ``unregistered`` - ownership is unproven, so they
+    are surfaced, never auto-reaped (D6)."""
+    runner = runner or _default_runner
+    entries = _read_registry(Path(state_dir))
+    container_names = _labeled_names(runner, "container")
+    network_names = _labeled_names(runner, "network")
+    registry_names = {e.get("name") for e in entries
+                      if isinstance(e.get("name"), str)}
+    containers: list[dict[str, Any]] = []
+    for entry in entries:
+        name = entry.get("name")
+        if not isinstance(name, str):
+            continue
+        kind = entry.get("kind", "container")
+        present = name in (network_names if kind == "network" else container_names)
+        if not present:
+            verdict = "stale-entry"
+        else:
+            pid = entry.get("pid")
+            if isinstance(pid, int) and _pid_alive_matches(
+                    pid, entry.get("process_start")):
+                verdict = "live"
+            else:
+                verdict = "orphaned"
+        containers.append({
+            "name": name,
+            "run_id": entry.get("run_id"),
+            "kind": kind,
+            "pid": entry.get("pid") if isinstance(entry.get("pid"), int) else None,
+            "process_start": entry.get("process_start"),
+            "created_at": entry.get("created_at"),
+            "verdict": verdict,
+        })
+    unregistered: list[dict[str, Any]] = []
+    for name in sorted(container_names - registry_names):
+        unregistered.append({"name": name, "kind": "container",
+                             "verdict": "unregistered"})
+    for name in sorted(network_names - registry_names):
+        unregistered.append({"name": name, "kind": "network",
+                             "verdict": "unregistered"})
+    return {"containers": containers, "unregistered": unregistered}

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/src/agentic_dev_loop/engine/graph.py

@@ -163,15 +163,19 @@ def run_pipeline(cfg_path, args, *, viz_bus=None,
     # Eager startup (Q2): probe -> image -> create+start exec container ->
     # pre-provision all declared setups, BEFORE the graph builds. Zero infra
     # operations mid-run; the only sandbox call during steps is run(request).
-    sandbox = startup_sandbox(cfg, workspace=Path.cwd(),
-                               refresh=getattr(args, "refresh", False),
-                               state_dir=state_dir)
+    # 042 D3: startup is close-protected - a post-create provision failure
+    # must still reach close() and reap the container it created.
+    sandbox = None
     try:
+        sandbox = startup_sandbox(cfg, workspace=Path.cwd(),
+                                  refresh=getattr(args, "refresh", False),
+                                  state_dir=state_dir)
         return _run_pipeline(cfg, base, registry, state_dir, max_attempts,
                              args, viz_bus, sandbox, resolved_secrets,
                              tooling_paths)
     finally:
-        sandbox.close()
+        if sandbox is not None:
+            sandbox.close()
 
 
 def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/src/agentic_dev_loop/engine/isolation.py

@@ -1053,12 +1053,12 @@ class DockerBackend(Sandbox):
             workspace=self._workspace, network=False,
             sandbox_venv_dir=self._sandbox_venv_dir,
             seccomp_profile=self._seccomp_profile)
+        self._register_container(self._container)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             raise SandboxError(
                 f"AE-SBX-010: container run failed: "
                 f"{res.stderr.strip() or res.stdout.strip()}")
-        self._register_container(self._container)
         self._started = True
         if not self._network_enabled:
             return
@@ -1068,6 +1068,7 @@ class DockerBackend(Sandbox):
             network_name=self._run_net,
             sandbox_venv_dir=self._sandbox_venv_dir,
             seccomp_profile=self._seccomp_profile)
+        self._register_container(self._network_container)
         net_res = self._runner.run(net_payload, timeout=60)
         if net_res.exit_code != 0:
             # reclaim the already-started network-none container - never leak it.
@@ -1076,13 +1077,13 @@ class DockerBackend(Sandbox):
             raise SandboxError(
                 f"AE-SBX-013: networked container run failed: "
                 f"{net_res.stderr.strip() or net_res.stdout.strip()}")
-        self._register_container(self._network_container)
         self._network_started = True
 
     def _ensure_run_network(self) -> None:
         """Create the per-run internal network once (038, D1/D6)."""
         if self._network_created:
             return
+        self._register_network(self._run_net)
         res = self._runner.run(
             ["docker", "network", "create", "--internal",
              "--label", "agentic-dev-loop=true",
@@ -1093,10 +1094,12 @@ class DockerBackend(Sandbox):
                 f"AE-SBX-021: internal network create failed: "
                 f"{res.stderr.strip() or res.stdout.strip()}")
         self._network_created = True
-        self._register_network(self._run_net)
 
     def _register_network(self, name: str) -> None:
-        """Record the per-run network for the orphan reaper (038, D6)."""
+        """Record the per-run network for the orphan reaper (038 D6, 042 D1).
+        Appended BEFORE the create command so any object that exists is
+        registered; the reaper tolerates a stale entry (a dead owner whose
+        create never happened gets a no-op rm and a pruned entry)."""
         _append_registry_record(self._iso_state_dir, {
             "run_id": self._run_id,
             "name": name,
@@ -1117,12 +1120,12 @@ class DockerBackend(Sandbox):
             seccomp_profile=self._seccomp_profile,
             mount_set=base, export_root=self._export_root,
             cache_mounts=self._cache_mounts)
+        self._register_container(self._container)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             raise SandboxError(
                 f"AE-SBX-010: container run failed: "
                 f"{res.stderr.strip() or res.stdout.strip()}")
-        self._register_container(self._container)
         self._started = True
         if not self._baseline:
             self._baseline = _snapshot(Path(self._export_root),
@@ -1297,6 +1300,7 @@ class DockerBackend(Sandbox):
             mount_set=mount_set, export_root=self._export_root,
             cache_mounts=self._cache_mounts, egress_proxy=proxy_url_value,
             name=name)
+        self._register_container(name)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             if proxy_name is not None:
@@ -1304,7 +1308,6 @@ class DockerBackend(Sandbox):
             raise SandboxError(
                 f"AE-SBX-010: container run failed: "
                 f"{res.stderr.strip() or res.stdout.strip()}")
-        self._register_container(name)
         return _ProfileContainer(name=name, mount_set=mount_set,
                                  egress_policy=policy, proxy_name=proxy_name,
                                  started=True)
@@ -1334,6 +1337,7 @@ class DockerBackend(Sandbox):
             egress_proxy_host_path=str(Path(egress_proxy_module.__file__)),
             egress_policy_host_path=str(Path(egress_policy_module.__file__)),
             bind_host=bind_host, port=EGRESS_PROXY_PORT)
+        self._register_container(name)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             raise SandboxError(
@@ -1353,7 +1357,6 @@ class DockerBackend(Sandbox):
                 f"AE-SBX-021: egress proxy failed to bind "
                 f"{bind_host}:{EGRESS_PROXY_PORT} after "
                 f"{PROXY_READY_ATTEMPTS} readiness probes")
-        self._register_container(name)
         self._proxy_containers.append(name)
 
     def _proxy_internal_ip(self) -> str:
@@ -1521,12 +1524,14 @@ class DockerBackend(Sandbox):
             self._runner.run(["docker", "network", "rm", self._run_net], timeout=60)
             self._network_created = False
         merge_egress_events(self._iso_state_dir, self._egress_events_path)
-        self._prune_registry()
+        self._verify_and_prune_registry()
 
     def _register_container(self, name: str) -> None:
-        """Record one successfully created exec container in the host registry
-        (030, D4). Best-effort: a broken registry only disables reaping, it
-        never fails the run."""
+        """Record one exec/proxy container in the host registry (030 D4, 042
+        D1). Appended BEFORE the create command so any object that exists is
+        registered. Best-effort: a broken registry only disables reaping, it
+        never fails the run; the reaper tolerates a stale entry (a dead owner
+        whose create never happened gets a no-op rm and a pruned entry)."""
         _append_registry_record(self._iso_state_dir, {
             "run_id": self._run_id,
             "name": name,
@@ -1535,15 +1540,50 @@ class DockerBackend(Sandbox):
             "created_at": datetime.now(timezone.utc).isoformat(),
         })
 
-    def _prune_registry(self) -> None:
-        """Drop this run's registry entries after close() removed the
-        containers (030, D4). Tolerates a missing registry file."""
+    def _verify_and_prune_registry(self) -> None:
+        """Prune this run's registry entries only after the daemon confirms
+        the object is gone (042 D2). A surviving object (daemon down, rm
+        failure) keeps its entry so the next startup reaper retries. Never
+        raises."""
         entries = _read_registry(self._iso_state_dir)
         if not entries:
             return
-        remaining = [e for e in entries if e.get("run_id") != self._run_id]
+        remaining: list[dict] = []
+        for entry in entries:
+            if entry.get("run_id") != self._run_id:
+                remaining.append(entry)
+                continue
+            name = entry.get("name")
+            if not isinstance(name, str):
+                remaining.append(entry)
+                continue
+            if entry.get("kind") == "network":
+                gone = self._network_gone(name)
+            else:
+                gone = self._container_gone(name)
+            if not gone:
+                remaining.append(entry)
         _write_registry(self._iso_state_dir, remaining)
 
+    def _container_gone(self, name: str) -> bool:
+        """True only when the daemon confirms the container no longer exists.
+        A nonzero daemon exit keeps the entry."""
+        res = self._runner.run(
+            ["docker", "ps", "-a", "--filter", f"name={name}",
+             "--format", "{{.Names}}"], timeout=30)
+        if res.exit_code != 0:
+            return False
+        return name not in res.stdout.splitlines()
+
+    def _network_gone(self, name: str) -> bool:
+        """True only when the daemon reports the network is missing. Any
+        other inspect failure (daemon unreachable) keeps the entry."""
+        res = self._runner.run(
+            ["docker", "network", "inspect", name], timeout=30)
+        if res.exit_code == 0:
+            return False
+        return "No such network" in f"{res.stderr} {res.stdout}"
+
     # -- internal -----------------------------------------------------------
 
     def _verify_digest(self) -> None:
@@ -1777,7 +1817,8 @@ def _pid_alive_matches(pid: int, recorded_start: str | None) -> bool:
 
 
 def reap_orphaned_containers(state_dir: str | Path,
-                             runner: CommandRunner | None = None) -> None:
+                             runner: CommandRunner | None = None,
+                             *, announce: bool = True) -> list[str]:
     """Startup orphan reaper (030/038, D4/D6): remove exec/proxy containers
     and the per-run internal network whose owning CLI process is gone (crashed
     before close()). Exact by construction - only engine registry names are
@@ -1786,8 +1827,9 @@ def reap_orphaned_containers(state_dir: str | Path,
     runner = runner or _default_runner
     entries = _read_registry(Path(state_dir))
     if not entries:
-        return
+        return []
     remaining: list[dict] = []
+    reaped: list[str] = []
     for entry in entries:
         name = entry.get("name")
         kind = entry.get("kind", "container")
@@ -1801,7 +1843,9 @@ def reap_orphaned_containers(state_dir: str | Path,
                 remaining.append(entry)
                 continue
             runner.run(["docker", "network", "rm", name], timeout=60)
-            _announce(f"reaped orphaned sandbox network {name}")
+            if announce:
+                _announce(f"reaped orphaned sandbox network {name}")
+            reaped.append(name)
             continue
         if not isinstance(name, str) or not _CONTAINER_NAME_RE.match(name):
             # Defense in depth: a corrupted registry entry is never an engine
@@ -1814,8 +1858,11 @@ def reap_orphaned_containers(state_dir: str | Path,
             remaining.append(entry)
             continue
         runner.run(["docker", "rm", "-f", name], timeout=60)
-        _announce(f"reaped orphaned sandbox container {name}")
+        if announce:
+            _announce(f"reaped orphaned sandbox container {name}")
+        reaped.append(name)
     _write_registry(Path(state_dir), remaining)
+    return reaped
 
 
 # ---------------------------------------------------------------------------
@@ -1961,17 +2008,23 @@ def startup_sandbox(cfg: PipelineConfig, *, workspace: Path,
         sync_excludes=list(cfg.sync_excludes),
         merge_on_conflict=list(cfg.merge_on_conflict),
         dial_rewrites=dial_rewrites)
-    _announce(f"preparing sandbox image {image} (first pull can take a while)")
-    backend.ensure_image()
-    _announce("sandbox image ready")
-    _announce("starting execution container...")
-    backend.create_execution_container()
-    _announce("execution container started")
-    if refresh is None:
-        refresh = bool(cfg.isolation and cfg.isolation.refresh)
-    for setup_cmd, stamp_key in _declared_setups(cfg, workspace):
-        _announce(f"provisioning setup (stamp {stamp_key[:8]})")
-        backend.provision(setup_cmd, stamp_key, str(iso_state_dir / "stamps"),
-                          force=refresh)
-    _announce("sandbox ready")
-    return backend
+    try:
+        _announce(f"preparing sandbox image {image} (first pull can take a while)")
+        backend.ensure_image()
+        _announce("sandbox image ready")
+        _announce("starting execution container...")
+        backend.create_execution_container()
+        _announce("execution container started")
+        if refresh is None:
+            refresh = bool(cfg.isolation and cfg.isolation.refresh)
+        for setup_cmd, stamp_key in _declared_setups(cfg, workspace):
+            _announce(f"provisioning setup (stamp {stamp_key[:8]})")
+            backend.provision(setup_cmd, stamp_key,
+                              str(iso_state_dir / "stamps"), force=refresh)
+        _announce("sandbox ready")
+        return backend
+    except BaseException:
+        # 042 D3: a post-create startup failure (e.g. a setup hook) must still
+        # reap the exec container it created, never leak it to the reaper.
+        backend.close()
+        raise

{agentic_dev_loop-1.0.0a39 → agentic_dev_loop-1.0.0a41}/src/agentic_dev_loop/engine/stages.py

@@ -683,13 +683,13 @@ def _unclear_note(runtime: Runtime, step: StepConfig, attempt: int,
     captured response when it exists, so real findings are never swallowed."""
     expected = ""
     if step.verdicts is not None:
+        keywords = [f"`VERDICT: {step.verdicts.pass_}`",
+                    f"`VERDICT: {step.verdicts.fail}`"]
         if step.verdicts.unverifiable is not None:
-            expected = (f" (expected `VERDICT: {step.verdicts.pass_}`, "
-                        f"`VERDICT: {step.verdicts.fail}`, or "
-                        f"`VERDICT: {step.verdicts.unverifiable}` on its own line)")
-        else:
-            expected = (f" (expected `VERDICT: {step.verdicts.pass_}` or "
-                        f"`VERDICT: {step.verdicts.fail}` on its own line)")
+            keywords.append(f"`VERDICT: {step.verdicts.unverifiable}`")
+        if step.verdicts.env is not None:
+            keywords.append(f"`VERDICT: {step.verdicts.env}`")
+        expected = f" (expected {' or '.join(keywords)} on its own line)"
     if truncated:
         lead = (f"{step.name} agent was cut short on attempt {attempt} "
                 f"(hit the {max_iterations}-turn limit or was stopped "
@@ -718,6 +718,8 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
         verdicts_map = {step.verdicts.pass_: "pass", step.verdicts.fail: "fail"}
         if step.verdicts.unverifiable is not None:
             verdicts_map[step.verdicts.unverifiable] = "unverifiable"
+        if step.verdicts.env is not None:
+            verdicts_map[step.verdicts.env] = "env"
     captures = step.artifact is not None or bool(step.produces)
 
     def node(state: dict) -> dict:
@@ -787,6 +789,21 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
                 if captures and result.response is not None:
                     update["artifacts"] = {step.name: result.response}
                 return update
+            if verdict == "env":
+                print(f"[{subject}] {step.name} verdict: ENV "
+                      f"(environmental, halting).", flush=True)
+                if step.on_env is None:
+                    runtime.state_dir.mkdir(parents=True, exist_ok=True)
+                    (runtime.state_dir / LAST_ERROR).write_text(
+                        f"# Environmental failure (verdict: ENV)\n\n"
+                        f"{result.response or 'no captured response'}\n",
+                        encoding="utf-8")
+                    return {"step_verdicts": merged,
+                            "failed": True, "failed_step": step.name}
+                update = {"step_verdicts": merged, "failed": False}
+                if captures and result.response is not None:
+                    update["artifacts"] = {step.name: result.response}
+                return update
             print(f"[{subject}] {step.name} verdict: fail on attempt {attempt}.",
                   flush=True)
             update = {"step_verdicts": merged,
@@ -1115,6 +1132,8 @@ def make_router(runtime: Runtime, step: StepConfig):
             if step.on_unverifiable is not None:
                 return resolve(step.on_unverifiable)
             return resolve(step.on_pass)
+        if verdict == "env":
+            return resolve(step.on_env) if step.on_env is not None else END
         if verdict == "fail":
             if step.on_fail is None:
                 return END