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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a27
+Version: 1.0.0a29
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -195,6 +195,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -227,8 +229,10 @@ 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. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `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). |
@@ -236,7 +240,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
@@ -432,7 +436,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.

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

@@ -153,6 +153,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -185,8 +187,10 @@ 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. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `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). |
@@ -194,7 +198,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
@@ -390,7 +394,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.

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

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

@@ -6,7 +6,8 @@ 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, MountSpec, EgressSpec)
+                     default_state_dir, TERMINALS, MountSpec, EgressSpec,
+                     StopWhenSpec)
 from .results import Result
 from .verdict import Verdict, VerdictError, parse_verdict, RETRY
 
@@ -14,5 +15,6 @@ __all__ = [
     "PipelineConfig", "StepConfig", "LlmConfig", "IsolationConfig",
     "VerdictSpec", "Route", "route_target", "load_config",
     "default_state_dir", "TERMINALS", "MountSpec", "EgressSpec",
+    "StopWhenSpec",
     "Result", "Verdict", "VerdictError", "parse_verdict", "RETRY",
 ]

{agentic_dev_loop-1.0.0a27 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/core/config.py

@@ -305,6 +305,36 @@ class EgressSpec(BaseModel):
         return [_validate_egress_target(t) for t in v]
 
 
+class StopWhenSpec(BaseModel):
+    """Optional ``stop_when:`` termination signal on an agent step (032).
+
+    ``green_command`` is a regex matched against the agent's terminal
+    observation command; a matching observation that exits 0 - and no
+    workspace writes since - triggers one nudge turn, then
+    ``post_green_turns`` further turns before the engine closes the
+    conversation. Absent ``stop_when`` keeps the current run-to-finish
+    behaviour unchanged.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    green_command: str
+    post_green_turns: int = Field(default=2, ge=0)
+
+    @field_validator("green_command")
+    @classmethod
+    def _valid_regex(cls, v: str) -> str:
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError(
+                "stop_when.green_command must be a non-empty string")
+        try:
+            re.compile(v)
+        except re.error as e:
+            raise ValueError(
+                f"stop_when.green_command is not a valid regex: {e}") from e
+        return v
+
+
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
     `agent`, `action`, or `command` - empty values do not count, anything
@@ -322,6 +352,8 @@ class StepConfig(BaseModel):
     verdicts: VerdictSpec | None = None
     max_iterations: int | None = None
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
+    terminal_timeout: float | None = Field(default=None, gt=0)  # seconds, agent steps only (032)
+    stop_when: StopWhenSpec | None = None  # agent steps only (032)
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
     network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
@@ -386,9 +418,17 @@ 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.terminal_timeout is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'terminal_timeout' requires 'agent'"
+            )
+        if self.stop_when is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'stop_when' requires 'agent'"
+            )
+        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.0a27 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/agents.py

@@ -66,7 +66,9 @@ class SandboxTerminalExecutor(ToolExecutor):
     def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
                  env: dict[str, str] | None = None,
                  pipeline: str | None = None, step: str | None = None,
-                 network: bool = False, mount_set=None, egress_policy=None):
+                 network: bool = False, mount_set=None, egress_policy=None,
+                 terminal_timeout: float | None = None,
+                 on_terminal_result=None):
         self._sandbox = sandbox
         self._workspace = workspace
         self._env = env or {}
@@ -75,6 +77,8 @@ class SandboxTerminalExecutor(ToolExecutor):
         self._network = network
         self._mount_set = mount_set
         self._egress_policy = egress_policy
+        self._terminal_timeout = terminal_timeout
+        self._on_terminal_result = on_terminal_result
 
     def __call__(self, action, conversation=None):
         from openhands.tools.terminal import TerminalObservation
@@ -92,9 +96,12 @@ class SandboxTerminalExecutor(ToolExecutor):
                 command=action.command, exit_code=None, timeout=False,
                 metadata=CmdOutputMetadata(exit_code=-1))
 
+        timeout = action.timeout
+        if timeout is None and self._terminal_timeout is not None:
+            timeout = self._terminal_timeout
         request = SandboxExecutionRequest(
             argv=command_argv(action.command), cwd=self._workspace,
-            env=self._env, timeout=action.timeout,
+            env=self._env, timeout=timeout,
             pipeline=self._pipeline, step=self._step, network=self._network,
             mount_set=self._mount_set, egress_policy=self._egress_policy)
         try:
@@ -112,6 +119,9 @@ class SandboxTerminalExecutor(ToolExecutor):
                     ConversationExecutionStatus.STUCK
                 )
             raise
+        if self._on_terminal_result is not None:
+            self._on_terminal_result(
+                action.command, result.exit_code, result.wrote_workspace)
         output = result.stdout + result.stderr
         return TerminalObservation.from_text(
             output, is_error=not result.succeeded and not result.is_timeout,
@@ -130,6 +140,8 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
                               step: str | None = None,
                               network: bool = False,
                               mount_set=None, egress_policy=None,
+                              terminal_timeout: float | None = None,
+                              on_terminal_result=None,
                               secrets: dict[str, str] | None = None) -> None:
     """Per-run re-registration of the `terminal` name (KD-4): a callable
     factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
@@ -147,6 +159,8 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
             executor=SandboxTerminalExecutor(
                 sandbox, workspace=workspace, env=resolved_env,
                 pipeline=pipeline, step=step, network=network,
-                mount_set=mount_set, egress_policy=egress_policy))
+                mount_set=mount_set, egress_policy=egress_policy,
+                terminal_timeout=terminal_timeout,
+                on_terminal_result=on_terminal_result))
 
     register_tool("terminal", factory)

{agentic_dev_loop-1.0.0a27 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/isolation.py

@@ -144,6 +144,7 @@ class SandboxExecutionResult:
     duration_seconds: float
     backend: str  # "docker"
     timed_out: bool = False
+    wrote_workspace: bool = False  # declared-rw paths changed (032)
 
     @property
     def succeeded(self) -> bool:
@@ -699,11 +700,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 +717,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 +1001,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:]
@@ -1062,8 +1069,15 @@ class DockerBackend(Sandbox):
                 "failing closed (BR-11.3): no networked execution runs "
                 "without egress enforcement")
         result = self._exec(request, prof.name)
+        report: SyncBackReport | None = None
         if mount_set.rw_paths() and self._export_root is not None:
-            self._sync_back(mount_set)
+            report = self._sync_back(mount_set)
+        if report is not None and (report.synced_paths or report.merged_paths):
+            result = SandboxExecutionResult(
+                exit_code=result.exit_code, stdout=result.stdout,
+                stderr=result.stderr, duration_seconds=result.duration_seconds,
+                backend=result.backend, timed_out=result.timed_out,
+                wrote_workspace=True)
         return result
 
     def _exec(self, request: SandboxExecutionRequest,
@@ -1155,7 +1169,7 @@ class DockerBackend(Sandbox):
         export_path.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(host_path, export_path, follow_symlinks=False)
 
-    def _sync_back(self, mount_set: MountSet) -> None:
+    def _sync_back(self, mount_set: MountSet) -> SyncBackReport | None:
         """Sync declared-rw export changes back to the real repo (BR-4/F1),
         git-aware, host-side, with the sandbox step already complete.
 
@@ -1221,6 +1235,7 @@ class DockerBackend(Sandbox):
             "synced_paths": list(report.synced_paths),
             "merged_paths": list(report.merged_paths),
         })
+        return report
 
     def close(self) -> None:
         """Best-effort stop + rm; idempotent (BR-8.3). With ``--rm`` the
@@ -1541,7 +1556,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.0a27 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/stages.py

@@ -20,6 +20,7 @@ pipeline config; the fixed policies stay here, not in config:
 from __future__ import annotations
 
 import os
+import re
 import subprocess
 import sys
 import traceback
@@ -54,6 +55,74 @@ LAST_ERROR = "last-error.md"
 ARTIFACT_CONTEXT_CAP = 24_000  # chars per artifact injected into a step's context
 
 
+class _StopWhenController:
+    """Turn-level stop-when-green observation (032).
+
+    Pure per-event state machine - no knowledge of how the conversation is
+    driven. ``on_event`` is a SDK conversation callback: it records the most
+    recent matching terminal observation and any subsequent file-editor
+    write, and pauses the conversation after every agent-sourced event so the
+    caller can drive one turn at a time.
+    """
+
+    NUDGE = "Step complete: produce your final response now"
+    _WRITE_COMMANDS = frozenset({"create", "str_replace", "insert", "undo_edit"})
+
+    def __init__(self, spec) -> None:
+        self._pattern = re.compile(spec.green_command)
+        self.post_green_turns = spec.post_green_turns
+        self.green_hit = False
+        self.writes_since_green = False
+        self.nudged = False
+        self.post_nudge_turns = 0
+        self.conversation = None
+
+    def attach(self, conversation) -> None:
+        self.conversation = conversation
+
+    @property
+    def green_signal(self) -> bool:
+        return self.green_hit and not self.writes_since_green
+
+    def on_event(self, event) -> None:
+        if self.conversation is None:
+            return
+        from openhands.sdk.event import ObservationEvent
+
+        if isinstance(event, ObservationEvent):
+            self._record_observation(event)
+        if getattr(event, "source", None) == "agent":
+            from openhands.sdk.conversation.state import (
+                ConversationExecutionStatus,
+            )
+            self.conversation.state.execution_status = (
+                ConversationExecutionStatus.PAUSED
+            )
+
+    def on_terminal_result(self, command: str | None, exit_code: int | None,
+                           wrote_workspace: bool) -> None:
+        """Feed the sandbox terminal result channel (032): a matching green
+        command is the signal; any other terminal write resets it."""
+        if command is not None and self._pattern.search(command):
+            self.green_hit = exit_code == 0
+            self.writes_since_green = False
+        elif wrote_workspace:
+            self.writes_since_green = True
+
+    def _record_observation(self, event) -> None:
+        observation = event.observation
+        tool_name = event.tool_name
+        if tool_name == "terminal":
+            command = getattr(observation, "command", None)
+            if command is not None and self._pattern.search(command):
+                self.green_hit = getattr(observation, "exit_code", None) == 0
+                self.writes_since_green = False
+        elif tool_name == "file_editor":
+            command = getattr(observation, "command", None)
+            if command in self._WRITE_COMMANDS and not observation.is_error:
+                self.writes_since_green = True
+
+
 @dataclass
 class Runtime:
     """Everything stage nodes need that isn't in LoopState: pipeline config,
@@ -85,6 +154,10 @@ class Runtime:
         try:
             from openhands.sdk.conversation.state import ConversationExecutionStatus
 
+            controller = None
+            if step is not None and step.stop_when is not None:
+                controller = _StopWhenController(step.stop_when)
+
             if self.sandbox is not None:
                 if step is not None:
                     cwd, mount_set, egress_policy = _step_sandbox(self, step)
@@ -99,13 +172,24 @@ class Runtime:
                     network=step.network if step is not None else False,
                     mount_set=mount_set,
                     egress_policy=egress_policy,
+                    terminal_timeout=(step.terminal_timeout
+                                      if step is not None else None),
+                    on_terminal_result=(controller.on_terminal_result
+                                        if controller is not None else None),
                     secrets=(step_secret_env(self.cfg, step, self.secrets)
                              if step is not None else None))
             agent = load_agent(self.agents_dir, agent_name, self.llm)
+            callbacks = [controller.on_event] if controller is not None else None
             conv = Conversation(agent=agent, workspace=str(self.workspace),
-                                max_iteration_per_run=max_iterations)
+                                max_iteration_per_run=max_iterations,
+                                callbacks=callbacks)
+            if controller is not None:
+                controller.attach(conv)
             conv.send_message(message)
-            conv.run()
+            if controller is not None:
+                self._run_stop_when_loop(conv, controller, max_iterations)
+            else:
+                conv.run()
 
             # 030, D1/D2: a sticky infra failure must fail the run with no
             # retry - check before any capture/verdict path would schedule an
@@ -144,6 +228,40 @@ class Runtime:
             if conv is not None:
                 conv.close()
 
+    def _run_stop_when_loop(self, conv, controller: _StopWhenController,
+                            max_iterations: int) -> None:
+        """Drive one turn at a time so a green signal can inject the nudge
+        and enforce the post-nudge turn budget. The controller's callback
+        pauses the SDK run loop after every agent-sourced event, so each
+        ``conv.run()`` here advances exactly one agent turn."""
+        from openhands.sdk.conversation.state import ConversationExecutionStatus
+
+        turns = 0
+        while True:
+            conv.run()
+            status = conv.state.execution_status
+            if status in (ConversationExecutionStatus.FINISHED,
+                          ConversationExecutionStatus.STUCK,
+                          ConversationExecutionStatus.ERROR):
+                break
+
+            turns += 1
+            if turns >= max_iterations:
+                conv.state.execution_status = ConversationExecutionStatus.ERROR
+                break
+
+            if not controller.nudged and controller.green_signal:
+                conv.send_message(controller.NUDGE)
+                controller.nudged = True
+                if controller.post_green_turns == 0:
+                    break
+                continue
+
+            if controller.nudged:
+                controller.post_nudge_turns += 1
+                if controller.post_nudge_turns >= controller.post_green_turns:
+                    break
+
 
 def prompt_dir(runtime: Runtime) -> str:
     """state_dir as agents must address it. Agents resolve prompt paths
@@ -409,7 +527,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.0a27 → agentic_dev_loop-1.0.0a29/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a27
+Version: 1.0.0a29
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -195,6 +195,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -227,8 +229,10 @@ 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. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `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). |
@@ -236,7 +240,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
@@ -432,7 +436,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.

{agentic_dev_loop-1.0.0a27 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ src/agentic_dev_loop/viz/__main__.py
 src/agentic_dev_loop/viz/server.py
 tests/test_028_declared_caches.py
 tests/test_029_merge_on_conflict.py
+tests/test_032_stop_when_green.py
 tests/test_actions.py
 tests/test_agents.py
 tests/test_aidlc.py