agentic-dev-loop 1.0.0a31__tar.gz → 1.0.0a32__tar.gz

{agentic_dev_loop-1.0.0a31/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a31
+Version: 1.0.0a32
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -224,6 +224,8 @@ steps:
     agent: qa
     artifact: qa-report.md
     verdicts: { pass: PASS, fail: FAIL }
+    max_iterations: 100
+    finalize_nudge_turns: 10
     on_pass: commit
     on_fail: { goto: dev, retry: true }
 
@@ -239,6 +241,7 @@ steps:
 | `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `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. |
+| `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `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 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). |
@@ -421,9 +424,10 @@ an agent burned budget learning it mid-run:
   the dev agent's next context; the dev prompt makes every listed issue a
   required fix.
 - **No git mutations, ever.** The `commit` step is the single commit point.
-- **`max_iterations` per role.** qa is bounded probing (60 in both
-  reference repos); dev is open-ended construction and stays uncapped
-  (the engine default).
+- **`max_iterations` per role.** qa is bounded probing (100 in this
+  repo's dogfood loop, with `finalize_nudge_turns: 10` so it never ends
+  silently at the cap - both provisional); dev is open-ended construction
+  and stays uncapped (the engine default).
 
 ### The pipeline file
 
@@ -438,7 +442,7 @@ adapt per repo.
 | editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
 | conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
 | review | agent | ro, offline | static conformance verdict |
-| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 100` + `finalize_nudge_turns: 10` (provisional); inject secrets only if the probes need them |
 | commit | action | host-side | the single commit point |
 
 Adaptation checklist for a new repo:

{agentic_dev_loop-1.0.0a31 → agentic_dev_loop-1.0.0a32}/README.md

@@ -182,6 +182,8 @@ steps:
     agent: qa
     artifact: qa-report.md
     verdicts: { pass: PASS, fail: FAIL }
+    max_iterations: 100
+    finalize_nudge_turns: 10
     on_pass: commit
     on_fail: { goto: dev, retry: true }
 
@@ -197,6 +199,7 @@ steps:
 | `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `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. |
+| `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `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 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). |
@@ -379,9 +382,10 @@ an agent burned budget learning it mid-run:
   the dev agent's next context; the dev prompt makes every listed issue a
   required fix.
 - **No git mutations, ever.** The `commit` step is the single commit point.
-- **`max_iterations` per role.** qa is bounded probing (60 in both
-  reference repos); dev is open-ended construction and stays uncapped
-  (the engine default).
+- **`max_iterations` per role.** qa is bounded probing (100 in this
+  repo's dogfood loop, with `finalize_nudge_turns: 10` so it never ends
+  silently at the cap - both provisional); dev is open-ended construction
+  and stays uncapped (the engine default).
 
 ### The pipeline file
 
@@ -396,7 +400,7 @@ adapt per repo.
 | editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
 | conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
 | review | agent | ro, offline | static conformance verdict |
-| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 100` + `finalize_nudge_turns: 10` (provisional); inject secrets only if the probes need them |
 | commit | action | host-side | the single commit point |
 
 Adaptation checklist for a new repo:

{agentic_dev_loop-1.0.0a31 → agentic_dev_loop-1.0.0a32}/pyproject.toml

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

@@ -387,6 +387,7 @@ class StepConfig(BaseModel):
     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)
+    finalize_nudge_turns: int | None = Field(default=None, gt=0)  # agent steps only (035)
     brief_inputs: BriefInputsSpec | None = None  # agent steps only (033)
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
@@ -460,6 +461,21 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'stop_when' requires 'agent'"
             )
+        if self.finalize_nudge_turns is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'finalize_nudge_turns' requires 'agent'"
+            )
+        if self.finalize_nudge_turns is not None and self.max_iterations is None:
+            raise ValueError(
+                f"step {self.name!r}: 'finalize_nudge_turns' requires "
+                "'max_iterations'"
+            )
+        if (self.finalize_nudge_turns is not None
+                and self.finalize_nudge_turns >= self.max_iterations):
+            raise ValueError(
+                f"step {self.name!r}: 'finalize_nudge_turns' must be less "
+                "than 'max_iterations'"
+            )
         if self.brief_inputs is not None and self.agent is None:
             raise ValueError(
                 f"step {self.name!r}: 'brief_inputs' requires 'agent'"

{agentic_dev_loop-1.0.0a31 → agentic_dev_loop-1.0.0a32}/src/agentic_dev_loop/engine/stages.py

@@ -58,49 +58,79 @@ LAST_ERROR = "last-error.md"
 ARTIFACT_CONTEXT_CAP = 24_000  # chars per artifact injected into a step's context
 
 
-class _StopWhenController:
+class _TurnPauseController:
+    """Turn-level pause callback (032): pause the SDK run loop after every
+    agent-sourced event so the caller can drive one turn at a time. The
+    finalize nudge (035) reuses this hook without any stop-when state."""
+
+    def __init__(self) -> None:
+        self.conversation = None
+
+    def attach(self, conversation) -> None:
+        self.conversation = conversation
+
+    def on_event(self, event) -> None:
+        if self.conversation is None:
+            return
+        if getattr(event, "source", None) == "agent":
+            from openhands.sdk.conversation.state import (
+                ConversationExecutionStatus,
+            )
+            self.conversation.state.execution_status = (
+                ConversationExecutionStatus.PAUSED
+            )
+
+
+class _FinalizeNudgeController(_TurnPauseController):
+    """Finalize nudge (035): template text, never step-named. The turn loop
+    asks for the message when the conversation reaches the configured index;
+    ``nudged`` guards against re-injection on a same-turn retry."""
+
+    _TEMPLATE = "{n} turns remain: produce your final response now"
+
+    def __init__(self, turns: int) -> None:
+        super().__init__()
+        self.turns = turns
+        self.nudged = False
+
+    def message(self) -> str:
+        return self._TEMPLATE.format(n=self.turns)
+
+
+class _StopWhenController(_TurnPauseController):
     """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.
+    write, and (via the base pause) 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:
+        super().__init__()
         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:
+        super().on_event(event)
         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:
@@ -160,6 +190,10 @@ class Runtime:
             controller = None
             if step is not None and step.stop_when is not None:
                 controller = _StopWhenController(step.stop_when)
+            finalize_controller = None
+            if step is not None and step.finalize_nudge_turns is not None:
+                finalize_controller = _FinalizeNudgeController(
+                    step.finalize_nudge_turns)
 
             if self.sandbox is not None:
                 if step is not None:
@@ -182,15 +216,22 @@ class Runtime:
                     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
+            callbacks = []
+            if controller is not None:
+                callbacks.append(controller.on_event)
+            if finalize_controller is not None:
+                callbacks.append(finalize_controller.on_event)
             conv = Conversation(agent=agent, workspace=str(self.workspace),
                                 max_iteration_per_run=max_iterations,
-                                callbacks=callbacks)
+                                callbacks=callbacks or None)
             if controller is not None:
                 controller.attach(conv)
+            if finalize_controller is not None:
+                finalize_controller.attach(conv)
             conv.send_message(message)
-            if controller is not None:
-                self._run_stop_when_loop(conv, controller, max_iterations)
+            if controller is not None or finalize_controller is not None:
+                self._run_stop_when_loop(conv, controller, max_iterations,
+                                         finalize_controller)
             else:
                 conv.run()
 
@@ -231,15 +272,19 @@ 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."""
+    def _run_stop_when_loop(self, conv,
+                            controller: _StopWhenController | None,
+                            max_iterations: int,
+                            finalize_controller: _FinalizeNudgeController | None = None) -> None:
+        """Drive one turn at a time so turn-level hooks can inject their
+        nudges and enforce budgets. A 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
+        nudge_at = (max_iterations - finalize_controller.turns
+                    if finalize_controller is not None else None)
         while True:
             conv.run()
             status = conv.state.execution_status
@@ -253,17 +298,24 @@ class Runtime:
                 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
+            if (finalize_controller is not None and turns == nudge_at
+                    and not finalize_controller.nudged):
+                conv.send_message(finalize_controller.message())
+                finalize_controller.nudged = True
                 continue
 
-            if controller.nudged:
-                controller.post_nudge_turns += 1
-                if controller.post_nudge_turns >= controller.post_green_turns:
-                    break
+            if controller is not None:
+                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:

{agentic_dev_loop-1.0.0a31 → agentic_dev_loop-1.0.0a32/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a31
+Version: 1.0.0a32
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -224,6 +224,8 @@ steps:
     agent: qa
     artifact: qa-report.md
     verdicts: { pass: PASS, fail: FAIL }
+    max_iterations: 100
+    finalize_nudge_turns: 10
     on_pass: commit
     on_fail: { goto: dev, retry: true }
 
@@ -239,6 +241,7 @@ steps:
 | `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `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. |
+| `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `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 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). |
@@ -421,9 +424,10 @@ an agent burned budget learning it mid-run:
   the dev agent's next context; the dev prompt makes every listed issue a
   required fix.
 - **No git mutations, ever.** The `commit` step is the single commit point.
-- **`max_iterations` per role.** qa is bounded probing (60 in both
-  reference repos); dev is open-ended construction and stays uncapped
-  (the engine default).
+- **`max_iterations` per role.** qa is bounded probing (100 in this
+  repo's dogfood loop, with `finalize_nudge_turns: 10` so it never ends
+  silently at the cap - both provisional); dev is open-ended construction
+  and stays uncapped (the engine default).
 
 ### The pipeline file
 
@@ -438,7 +442,7 @@ adapt per repo.
 | editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
 | conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
 | review | agent | ro, offline | static conformance verdict |
-| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 100` + `finalize_nudge_turns: 10` (provisional); inject secrets only if the probes need them |
 | commit | action | host-side | the single commit point |
 
 Adaptation checklist for a new repo:

{agentic_dev_loop-1.0.0a31 → agentic_dev_loop-1.0.0a32}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ tests/test_028_declared_caches.py
 tests/test_029_merge_on_conflict.py
 tests/test_032_stop_when_green.py
 tests/test_033_brief_step.py
+tests/test_035_finalize_nudge.py
 tests/test_actions.py
 tests/test_agent_error_guide.py
 tests/test_agents.py

agentic_dev_loop-1.0.0a32/tests/test_035_finalize_nudge.py

@@ -0,0 +1,211 @@
+"""Finalize nudge (035): config surface, the turn-index injection, and the
+exactly-once guard on the shared 032 turn loop."""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import yaml
+from pydantic import ValidationError
+
+from openhands.sdk import LLM
+from openhands.sdk.conversation.state import ConversationExecutionStatus
+
+from agentic_dev_loop.core.config import PipelineConfig, load_config
+from agentic_dev_loop.engine.registry import default_registry
+from agentic_dev_loop.engine.stages import Runtime, _FinalizeNudgeController
+
+NUDGE = "3 turns remain: produce your final response now"
+
+
+def _base() -> dict:
+    return {
+        "name": "t",
+        "llm": {"model": "m", "api_key_env": "K"},
+        "agents_dir": "agents",
+        "lockfiles": ["uv.lock"],
+        "steps": [{"name": "dev", "agent": "dev", "on_pass": "success"}],
+    }
+
+
+def _load(tmp_path, data):
+    p = tmp_path / "pipeline.yaml"
+    p.write_text(yaml.safe_dump(data))
+    return load_config(p)
+
+
+def _verdict_step(**extra) -> dict:
+    step = {
+        "name": "qa",
+        "agent": "qa",
+        "artifact": "qa-report.md",
+        "verdicts": {"pass": "PASS", "fail": "FAIL"},
+        "max_iterations": 100,
+        "finalize_nudge_turns": 10,
+        "on_pass": "success",
+    }
+    step.update(extra)
+    return step
+
+
+class TestFinalizeNudgeConfig:
+    def test_valid_agent_step_round_trip(self, tmp_path):
+        data = _base()
+        data["steps"] = [_verdict_step()]
+        step = _load(tmp_path, data).steps[0]
+        assert step.finalize_nudge_turns == 10
+        assert step.max_iterations == 100
+
+    def test_absent_keeps_none(self, tmp_path):
+        data = _base()
+        assert _load(tmp_path, data).steps[0].finalize_nudge_turns is None
+
+    def test_requires_max_iterations(self, tmp_path):
+        data = _base()
+        data["steps"] = [_verdict_step(max_iterations=None)]
+        with pytest.raises(ValidationError, match="finalize_nudge_turns"):
+            _load(tmp_path, data)
+
+    def test_must_be_less_than_max_iterations(self, tmp_path):
+        data = _base()
+        data["steps"] = [_verdict_step(max_iterations=10,
+                                       finalize_nudge_turns=10)]
+        with pytest.raises(ValidationError, match="finalize_nudge_turns"):
+            _load(tmp_path, data)
+
+    @pytest.mark.parametrize("bad", [0, -1])
+    def test_nonpositive_rejected(self, tmp_path, bad):
+        data = _base()
+        data["steps"] = [_verdict_step(finalize_nudge_turns=bad)]
+        with pytest.raises(ValidationError, match="finalize_nudge_turns"):
+            _load(tmp_path, data)
+
+    @pytest.mark.parametrize("step", [
+        {"name": "test", "command": "true", "finalize_nudge_turns": 2},
+        {"name": "commit", "action": "commit", "finalize_nudge_turns": 2},
+    ])
+    def test_agent_only_rejected_on_non_agent(self, tmp_path, step):
+        data = _base()
+        data["steps"] = [step]
+        with pytest.raises(ValidationError, match="requires 'agent'"):
+            _load(tmp_path, data)
+
+
+class TestFinalizeNudgeLoop:
+    def _conv(self, finish_after):
+        class Fake:
+            def __init__(self):
+                self.state = SimpleNamespace(execution_status=None)
+                self.run_calls = 0
+                self.sent = []
+
+            def run(self):
+                self.run_calls += 1
+                self.state.execution_status = (
+                    ConversationExecutionStatus.FINISHED
+                    if self.run_calls >= finish_after
+                    else ConversationExecutionStatus.PAUSED)
+
+            def send_message(self, message):
+                self.sent.append((self.run_calls, message))
+
+        return Fake()
+
+    def test_nudge_at_configured_turn_and_only_once(self):
+        conv = self._conv(finish_after=9)
+        controller = _FinalizeNudgeController(3)
+        Runtime._run_stop_when_loop(None, conv, None, max_iterations=10,
+                                    finalize_controller=controller)
+        assert controller.nudged is True
+        assert conv.sent == [(7, NUDGE)]
+
+    def test_no_nudge_when_finished_before_threshold(self):
+        conv = self._conv(finish_after=3)
+        controller = _FinalizeNudgeController(3)
+        Runtime._run_stop_when_loop(None, conv, None, max_iterations=10,
+                                    finalize_controller=controller)
+        assert controller.nudged is False
+        assert conv.sent == []
+
+    def test_turn_cap_still_applies_when_nudge_ignored(self):
+        conv = self._conv(finish_after=999)
+        controller = _FinalizeNudgeController(3)
+        Runtime._run_stop_when_loop(None, conv, None, max_iterations=5,
+                                    finalize_controller=controller)
+        assert controller.nudged is True
+        assert conv.state.execution_status == ConversationExecutionStatus.ERROR
+        assert conv.sent == [(2, NUDGE)]
+
+
+class TestRunAgentFinalizeNudge:
+    def _runtime(self, tmp_path):
+        cfg = PipelineConfig.model_validate({
+            "name": "t",
+            "llm": {"model": "m", "api_key_env": "K"},
+            "agents_dir": "agents",
+            "lockfiles": ["uv.lock"],
+            "steps": [{
+                "name": "qa",
+                "agent": "qa",
+                "max_iterations": 10,
+                "finalize_nudge_turns": 3,
+                "on_pass": "success",
+            }],
+        })
+        state_dir = tmp_path / ".pr"
+        state_dir.mkdir()
+        agents_dir = tmp_path / "agents"
+        agents_dir.mkdir()
+        (agents_dir / "qa.agent.md").write_text(
+            "---\nname: qa\ntools: [terminal]\n---\nProbe.")
+        return Runtime(
+            cfg=cfg, registry=default_registry(),
+            llm=LLM(model="openai/test-model", api_key="sk-test"),
+            agents_dir=agents_dir, state_dir=state_dir,
+            workspace=tmp_path, sandbox=None)
+
+    def _fake_conv(self, finish_after):
+        class Fake:
+            def __init__(self):
+                self.state = SimpleNamespace(events=[], execution_status=None)
+                self.callbacks = []
+                self.messages = []
+                self.closed = False
+                self.run_calls = 0
+                self.finish_after = finish_after
+
+            def send_message(self, message):
+                self.messages.append(message)
+
+            def run(self):
+                self.run_calls += 1
+                self.state.execution_status = (
+                    ConversationExecutionStatus.FINISHED
+                    if self.run_calls >= self.finish_after
+                    else ConversationExecutionStatus.PAUSED)
+
+            def close(self):
+                self.closed = True
+
+        return Fake()
+
+    def test_run_agent_attaches_pause_and_sends_nudge(self, tmp_path, monkeypatch):
+        runtime = self._runtime(tmp_path)
+        conv = self._fake_conv(finish_after=9)
+
+        def factory(**kw):
+            conv.callbacks = kw.get("callbacks") or []
+            return conv
+
+        monkeypatch.setattr(
+            "agentic_dev_loop.engine.stages.Conversation", factory)
+
+        result = runtime.run_agent("qa", "the task", max_iterations=10,
+                                   step=runtime.cfg.steps[0])
+
+        assert result.ok is True
+        assert result.truncated is False
+        assert conv.callbacks
+        assert conv.messages == ["the task", NUDGE]
+        assert conv.run_calls == 9
+        assert conv.closed is True