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

{agentic_dev_loop-1.0.0a30/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.0a30
+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:
@@ -541,6 +545,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a30 → 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:
@@ -499,6 +503,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a30 → 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.0a30"
+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"
@@ -68,6 +68,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+"agentic_dev_loop.engine" = ["*.md"]
 "agentic_dev_loop.engine.seccomp" = ["*.json"]
 
 [tool.pytest.ini_options]

{agentic_dev_loop-1.0.0a30 → 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.0a32/src/agentic_dev_loop/engine/agent_error_guide.md

@@ -0,0 +1,6 @@
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-008 | The sandbox refused a git mutation command. Only the single commit step may change git state; agents never commit, branch, tag, or otherwise mutate git. | Do not run the command or any git mutation again. Continue without touching git and leave committing to the commit step. |
+| AE-SBX-010 | The sandbox could not create the execution container for the command, so the command did not run. | The command is not the problem: retry once; if it persists, mention the code in your final response and stop. |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+| AE-SBX-018 | The network egress proxy for this step stopped, so the sandbox refused the command rather than run without enforcement. | The command is not the problem: do not retry it, mention the code in your final response, and stop. |

agentic_dev_loop-1.0.0a32/src/agentic_dev_loop/engine/agent_error_guide.py

@@ -0,0 +1,26 @@
+"""Bundled agent-facing error guide (034).
+
+The guide table is an engine-owned resource, versioned with the engine so the
+codes and their guidance cannot drift. Every agent step's task context gets
+the table injected at assembly time; command and action steps never do (no
+agent reads them).
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+GUIDE_RESOURCE = "agent_error_guide.md"
+GUIDE_HEADING = "Agent-facing error guide"
+
+
+def load_guide() -> str:
+    """The bundled guide table text."""
+    return (files("agentic_dev_loop.engine")
+            .joinpath(GUIDE_RESOURCE)
+            .read_text(encoding="utf-8"))
+
+
+def guide_section() -> str:
+    """The guide block injected into an agent step's task context."""
+    return f"## {GUIDE_HEADING}\n\n{load_guide()}"

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

@@ -32,6 +32,7 @@ from typing import TYPE_CHECKING
 from langgraph.graph import END
 from openhands.sdk import Conversation
 
+from .agent_error_guide import guide_section
 from .agents import load_agent, register_sandbox_terminal
 from agentic_dev_loop.core.config import TERMINALS, PipelineConfig, Route, StepConfig, route_target
 from agentic_dev_loop.core.paths import _has_wildcards
@@ -57,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:
@@ -159,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:
@@ -181,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()
 
@@ -230,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
@@ -252,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:
@@ -364,12 +417,12 @@ def _artifact_file(runtime: Runtime, step_name: str) -> str | None:
 def build_context(runtime: Runtime, docs: dict[str, str], subject: str,
                   notes: list[str] | None = None,
                   artifacts: dict[str, str] | None = None) -> str:
-    """Assemble the attempt's shared message: subject, doc bundle, the
-    canonical dependency-policy paragraph (021), the expected-output-paths
-    section generated from step defs (a prompt merely naming files lets agents
-    skip them), accumulated stage artifacts (027), and previous-attempt
-    notes."""
-    parts = [f"You are working on {subject}.\n"]
+    """Assemble the attempt's shared message: the always-on agent-facing error
+    guide (034), subject, doc bundle, the canonical dependency-policy paragraph
+    (021), the expected-output-paths section generated from step defs (a prompt
+    merely naming files lets agents skip them), accumulated stage artifacts
+    (027), and previous-attempt notes."""
+    parts = [f"You are working on {subject}.\n", guide_section()]
     for name, content in docs.items():
         parts.append(f"## {name}\n\n{content}")
     if artifacts:
@@ -541,13 +594,14 @@ def brief_inputs_hash(runtime: Runtime, step: StepConfig,
 def build_brief_context(runtime: Runtime, step: StepConfig,
                         docs: dict[str, str],
                         doc_sources: dict[str, str] | None = None) -> str:
-    """Assemble the brief agent's task message (033): the resolved unit/plan
-    docs (re-read from disk where sources are known), the closed
-    ``brief_inputs.include`` file set, and the env-facts block. Prior verdicts
-    and feedback are deliberately absent - the notes channel delivers them per
-    attempt."""
+    """Assemble the brief agent's task message (033): the always-on
+    agent-facing error guide (034), the resolved unit/plan docs (re-read from
+    disk where sources are known), the closed ``brief_inputs.include`` file
+    set, and the env-facts block. Prior verdicts and feedback are deliberately
+    absent - the notes channel delivers them per attempt."""
     sections, env_facts = _brief_sections(runtime, step, docs, doc_sources)
-    parts = [f"## {name}\n\n{content}" for name, content in sections.items()]
+    parts = [guide_section()]
+    parts += [f"## {name}\n\n{content}" for name, content in sections.items()]
     if env_facts:
         parts.append("## Environment facts\n\n"
                      + "\n".join(f"- {fact}" for fact in env_facts))

{agentic_dev_loop-1.0.0a30 → 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.0a30
+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:
@@ -541,6 +545,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

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

@@ -16,6 +16,8 @@ src/agentic_dev_loop/core/results.py
 src/agentic_dev_loop/core/verdict.py
 src/agentic_dev_loop/engine/__init__.py
 src/agentic_dev_loop/engine/actions.py
+src/agentic_dev_loop/engine/agent_error_guide.md
+src/agentic_dev_loop/engine/agent_error_guide.py
 src/agentic_dev_loop/engine/agents.py
 src/agentic_dev_loop/engine/cli.py
 src/agentic_dev_loop/engine/deps.py
@@ -47,7 +49,9 @@ 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
 tests/test_aidlc.py
 tests/test_cli.py