devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/executors/mini_swe.py

@@ -2,11 +2,14 @@ import logging
 import subprocess
 import sys
 from pathlib import Path
+
+from devcouncil.executors.transient_retry import run_subprocess_with_transient_retry
 from rich.console import Console
 from devcouncil.domain.task import Task
 from devcouncil.domain.requirement import Requirement
 from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.telemetry.stages import log_step
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -17,7 +20,12 @@ class MiniSWEExecutor(Executor):
 
     def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
         builder = PromptBuilder(self.project_root)
+        from devcouncil.planning.correction_manifest import repair_prompt_prefix
+
         task_prompt = builder.build_task_prompt(task, requirements)
+        prefix = repair_prompt_prefix(self.project_root, task.id)
+        if prefix:
+            task_prompt = f"{prefix}{task_prompt}"
         
         # Write temporary instruction file for mini-SWE-agent
         instruction_file = self.project_root / ".devcouncil" / f"{task.id}-mini-swe-task.md"
@@ -25,6 +33,11 @@ class MiniSWEExecutor(Executor):
         instruction_file.write_text(task_prompt, encoding="utf-8")
         
         logger.info("mini-SWE-agent starting for %s", task.id)
+        log_step(
+            f"executor/mini-swe: starting task {task.id}",
+            project_root=self.project_root,
+            task_id=task.id,
+        )
         console.print(f"Starting [bold]mini-SWE-agent[/bold] for task {task.id}...")
         
         # In a real implementation, we'd invoke the agent CLI
@@ -42,24 +55,53 @@ class MiniSWEExecutor(Executor):
         console.print("[yellow]Note: mini_swe_agent must be installed in the environment.[/yellow]")
         
         try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                cwd=self.project_root,
-                timeout=1800,
+            def _run_once():
+                return subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    cwd=self.project_root,
+                    timeout=1800,
+                )
+
+            result = run_subprocess_with_transient_retry(
+                self.project_root,
+                label="mini-SWE-agent",
+                task_id=task.id,
+                run_once=_run_once,
             )
             self._write_log(task.id, result)
             if result.returncode != 0:
                 logger.error("mini-SWE-agent exited %s for %s", result.returncode, task.id)
+                log_step(
+                    f"executor/mini-swe: finished task {task.id}",
+                    project_root=self.project_root,
+                    task_id=task.id,
+                    returncode=result.returncode,
+                    success=False,
+                )
                 console.print(f"[red]mini-SWE-agent exited with {result.returncode}.[/red]")
                 return ExecutionResult(success=False, message='Execution failed')
             logger.info("mini-SWE-agent finished for %s", task.id)
+            log_step(
+                f"executor/mini-swe: finished task {task.id}",
+                project_root=self.project_root,
+                task_id=task.id,
+                returncode=0,
+                success=True,
+            )
             return ExecutionResult(success=True, message='Execution successful')
         except Exception as e:
             logger.exception("mini-SWE-agent error for %s: %s", task.id, e)
+            log_step(
+                f"executor/mini-swe: finished task {task.id}",
+                project_root=self.project_root,
+                task_id=task.id,
+                success=False,
+                error=str(e),
+            )
             console.print(f"[red]Error running mini-SWE-agent: {e}[/red]")
             return ExecutionResult(success=False, message='Execution failed')
 

package/src/devcouncil/executors/native/agent.py

@@ -1,4 +1,4 @@
-from typing import List, Dict, Any
+from typing import Any, Coroutine, Dict, List, Optional, Tuple, TypeVar
 import asyncio
 import logging
 from rich.console import Console
@@ -12,6 +12,7 @@ from devcouncil.execution.context_builder import ContextBuilder
 from devcouncil.execution.prompt_builder import PromptBuilder
 from devcouncil.execution.paths import resolve_project_path
 from devcouncil.app.errors import ExecutionError
+from devcouncil.telemetry.stages import log_step
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -20,6 +21,12 @@ logger = logging.getLogger(__name__)
 MAX_AGENT_STEPS = 10
 MAX_STRUCTURED_FAILURES = 2          # model can't produce a valid action -> give up cleanly
 MAX_CONSECUTIVE_PATCH_FAILURES = 3   # stop spinning on a patch the model can't fix
+# How many times the agent may signal "finish", get BLOCKED by verification, and be
+# handed the shared next-actions repair contract before we stop the closed loop. Mirrors
+# the bounded self-repair budget the MCP/dev-go loops apply so native cannot spin forever.
+MAX_VERIFY_ROUNDS = 3
+
+_T = TypeVar("_T")
 
 class ToolCall(BaseModel):
     tool: str
@@ -31,33 +38,206 @@ class AgentAction(BaseModel):
     finish: bool = False
 
 class NativeAgent(Executor):
-    def __init__(self, router: ModelRouter, task_runner: TaskRunner):
+    def __init__(self, router: ModelRouter, task_runner: TaskRunner, *, sandbox: str = "local"):
         self.router = router
         self.task_runner = task_runner
+        # Writes and verification are now routed through the SAME lease-gated policy path
+        # the MCP surface uses (execution/gated_write.py + HookPolicy, verification via the
+        # shared verify payload), so the native executor no longer bypasses the lease/scope
+        # gate with direct TaskRunner writes. task_runner is retained for run_command (which
+        # already honors execution.command_timeout).
+        self.project_root = task_runner.project_root
+        self.sandbox = sandbox
         # ContextBuilder is retained only for the cheap list_files file listing; the
         # implementation context itself uses the budgeted PromptBuilder so the native
         # executor gets the same repo-map orientation, symbol outlines, dependents and
         # context-window budgeting as the CLI executors (rather than a flat JSON dump).
         self.context_builder = ContextBuilder(task_runner.project_root)
         self.prompt_builder = PromptBuilder(task_runner.project_root)
+        self._lease_token: Optional[str] = None
 
     def run_task(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
         """Run the preview native executor behind the normal synchronous executor contract."""
-        return asyncio.run(self._run_task_async(task, requirements))
+        root = self.task_runner.project_root
+        log_step(
+            f"executor/native: starting task {task.id}",
+            project_root=root,
+            task_id=task.id,
+        )
+        result = self._run_coroutine_from_sync(self._run_task_async(task, requirements))
+        log_step(
+            f"executor/native: finished task {task.id}",
+            project_root=root,
+            task_id=task.id,
+            success=result.success,
+        )
+        return result
+
+    @staticmethod
+    def _run_coroutine_from_sync(coro: Coroutine[Any, Any, _T]) -> _T:
+        """Run async work from sync code without breaking nested event loops.
+
+        ``asyncio.run()`` fails when a loop is already running (pytest-asyncio,
+        Jupyter). With no running loop we use ``asyncio.run()``; otherwise we run
+        the coroutine on a fresh loop in a worker thread.
+        """
+        import concurrent.futures
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(coro)
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+            return executor.submit(asyncio.run, coro).result()
+
+    # ------------------------------------------------------------------ lease-gated I/O
+    def _acquire_lease(self, task: Task) -> dict:
+        """Acquire a task lease so writes/verify run through the shared gated path."""
+        from devcouncil.execution.lease_ops import checkout_task_payload
+
+        return checkout_task_payload(self.project_root, task_id=task.id, client_id="native")
+
+    def _release_lease(self, task: Task, lease_token: str) -> None:
+        from devcouncil.execution.lease_ops import release_task_payload
+
+        try:
+            release_task_payload(self.project_root, task_id=task.id, lease_token=lease_token)
+        except Exception as exc:  # a failed release only costs a TTL wait; never fail the run
+            logger.debug("Native lease release failed for %s: %s", task.id, exc)
+
+    def _gated_apply_patch(self, task: Task, patch: str) -> None:
+        """Apply a unified diff through execution/gated_write.py (lease + scope + HookPolicy).
+
+        Raises ExecutionError on rejection so the loop's existing patch-failure handling
+        (retry guidance, consecutive-failure abort) applies unchanged.
+        """
+        from devcouncil.execution.gated_write import apply_patch_payload
+
+        payload = apply_patch_payload(
+            self.project_root,
+            task_id=task.id,
+            lease_token=self._lease_token or "",
+            unified_diff=patch,
+        )
+        if not payload.get("ok"):
+            raise ExecutionError(self._write_rejection_reason(payload))
+
+    def _gated_write_file(self, task: Task, path: str, content: str) -> None:
+        """Write a whole file through execution/gated_write.py (lease + scope + HookPolicy)."""
+        from devcouncil.execution.gated_write import write_file_payload
+
+        payload = write_file_payload(
+            self.project_root,
+            task_id=task.id,
+            lease_token=self._lease_token or "",
+            rel_path=path,
+            content=content,
+        )
+        if not payload.get("ok"):
+            raise ExecutionError(self._write_rejection_reason(payload))
+
+    @staticmethod
+    def _write_rejection_reason(payload: dict) -> str:
+        rejected = payload.get("rejected_files") or []
+        if rejected:
+            first = rejected[0]
+            return f"Write to {first.get('path')} rejected: {first.get('reason')}"
+        return payload.get("error") or "Write rejected by the lease/scope gate."
+
+    def _verify_task(
+        self, task: Task, requirements: List[Requirement]
+    ) -> Tuple[bool, List[dict], List[dict]]:
+        """Verify through the shared surface and return (passed, blocking, advisory).
+
+        Local sandbox uses the same ``verify_task_payload`` the MCP verify loop uses, so the
+        ``split_next_actions`` repair contract is byte-for-byte identical across surfaces.
+        docker/nix run through ``verification/sandbox.py`` for coding-CLI parity.
+        """
+        if self.sandbox in {"docker", "nix"}:
+            return self._verify_via_sandbox(task, requirements)
+        from devcouncil.execution.task_gate_ops import verify_task_payload
+
+        payload = verify_task_payload(
+            self.project_root,
+            task_id=task.id,
+            lease_token=self._lease_token or "",
+            sandbox="local",
+        )
+        if not payload.get("ok"):
+            # A verification setup error (e.g. lease lost) is treated as "not passed" with the
+            # error surfaced as the single next action, so the loop can react rather than crash.
+            return False, [{"action": payload.get("error", "Verification failed to run.")}], []
+        return (
+            bool(payload.get("passed")),
+            list(payload.get("next_actions") or []),
+            list(payload.get("advisory_actions") or []),
+        )
+
+    def _verify_via_sandbox(
+        self, task: Task, requirements: List[Requirement]
+    ) -> Tuple[bool, List[dict], List[dict]]:
+        """Run the task's expected commands in a docker/nix sandbox (command_timeout-bounded)."""
+        from devcouncil.verification.sandbox import get_sandbox
+
+        commands = task.expected_tests or task.allowed_commands
+        result = get_sandbox(self.sandbox, self.project_root).run(task, commands, requirements)
+        if result.status == "unsupported":
+            reason = f"Sandbox '{self.sandbox}' is unavailable in this environment."
+            return False, [{"action": reason}], []
+        return result.status == "passed", [], []
+
+    @staticmethod
+    def _format_next_actions(blocking: List[dict], advisory: List[dict]) -> str:
+        """Render the shared next-actions contract into the repair message fed back to the
+        model — the same guidance an MCP agent reads from devcouncil_verify_task."""
+        lines = ["[Verification BLOCKED] The change did not pass. Address these before finishing:"]
+        for i, action in enumerate(blocking, 1):
+            text = action.get("action") or action.get("gap_type") or "Resolve the blocking gap."
+            loc = action.get("file")
+            if loc and action.get("line"):
+                loc = f"{loc}:{action['line']}"
+            suffix = f" ({loc})" if loc else ""
+            cmd = action.get("suggested_command")
+            cmd_txt = f" Suggested command: {cmd}" if cmd else ""
+            lines.append(f"{i}. {text}{suffix}{cmd_txt}")
+        if advisory:
+            lines.append("Advisory (non-blocking) signals worth addressing:")
+            for action in advisory:
+                lines.append(f"- {action.get('action') or action.get('gap_type')}")
+        lines.append(
+            "Apply the fix through apply_patch, then set finish=true again to re-verify."
+        )
+        return "\n".join(lines)
 
     async def _run_task_async(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
         logger.info("Native agent starting for %s (max_steps=%d)", task.id, MAX_AGENT_STEPS)
         console.print(f"Starting [bold]Native Executor[/bold] for task {task.id}...")
         console.print("[yellow]Native executor is preview quality; DevCouncil verification remains the completion gate.[/yellow]")
-        
+
+        # Acquire a lease so every write and verify runs through the same lease/scope gate
+        # as the MCP surface. Without a lease the gated write path refuses the write.
+        lease = self._acquire_lease(task)
+        if not lease.get("ok"):
+            message = lease.get("error", "Could not acquire a task lease.")
+            logger.error("Native agent could not lease %s: %s", task.id, message)
+            console.print(f"[red]Native agent could not acquire a lease for {task.id}: {message}[/red]")
+            return ExecutionResult(success=False, message=f"Lease unavailable: {message}")
+        self._lease_token = lease["lease_token"]
+        try:
+            return await self._run_agent_loop(task, requirements)
+        finally:
+            token = self._lease_token
+            self._lease_token = None
+            if token:
+                self._release_lease(task, token)
+
+    async def _run_agent_loop(self, task: Task, requirements: List[Requirement]) -> ExecutionResult:
         # 1. Gather rich context (budgeted; includes repo-map orientation + symbol outlines)
         context_block = self.prompt_builder.build_task_prompt(task, requirements)
-        from devcouncil.planning.correction_manifest import load_latest_correction_manifest
+        from devcouncil.planning.correction_manifest import repair_prompt_prefix
 
-        correction = load_latest_correction_manifest(self.task_runner.project_root, task.id)
-        correction_block = ""
-        if correction is not None:
-            correction_block = f"\nCorrection Manifest:\n{correction.model_dump_json(indent=2)}\n"
+        prefix = repair_prompt_prefix(self.task_runner.project_root, task.id)
+        correction_block = f"\n{prefix}" if prefix else ""
 
         system_prompt = f"""
 You are the DevCouncil Native Agent. Your goal is to implement the provided task.
@@ -78,7 +258,7 @@ Rules:
 4. Set 'finish' to true when you believe the task is complete and verified.
 """
         messages = [{"role": "system", "content": system_prompt}]
-        
+
         # Initial task prompt
         messages.append({"role": "user", "content": f"Begin implementing task {task.id} based on the context provided."})
 
@@ -87,6 +267,7 @@ Rules:
         # unfixable patch.
         structured_failures = 0
         consecutive_patch_failures = 0
+        verify_rounds = 0
         for step in range(MAX_AGENT_STEPS):
             try:
                 action = await self.router.complete_structured(
@@ -131,9 +312,33 @@ Rules:
             messages.append({"role": "assistant", "content": action.model_dump_json()})
 
             if action.finish:
-                logger.info("Native agent signaled completion for %s at step %d", task.id, step + 1)
-                console.print("[green]Native agent signaled completion.[/green]")
-                return ExecutionResult(success=True, message="Agent signaled completion; pending DevCouncil verification")
+                # Closed loop: instead of trusting the agent's self-report, verify through the
+                # same gate as MCP and, when BLOCKED, feed the shared next-actions repair
+                # contract back so the agent can self-repair and re-verify.
+                logger.info("Native agent signaled completion for %s at step %d; verifying", task.id, step + 1)
+                console.print("[green]Native agent signaled completion; verifying...[/green]")
+                # verify_task_payload runs the verifier via asyncio.run(); run it in a worker
+                # thread so it gets its own event loop instead of nesting inside this one.
+                passed, blocking, advisory = await asyncio.to_thread(
+                    self._verify_task, task, requirements
+                )
+                if passed:
+                    logger.info("Native agent %s verified after %d repair round(s)", task.id, verify_rounds)
+                    console.print("[green]Verification passed.[/green]")
+                    return ExecutionResult(success=True, message="Native agent completed and verification passed.")
+                verify_rounds += 1
+                if verify_rounds >= MAX_VERIFY_ROUNDS:
+                    logger.error("Native agent %s still blocked after %d verify round(s)", task.id, verify_rounds)
+                    return ExecutionResult(
+                        success=False,
+                        message=(
+                            f"Verification still blocked after {verify_rounds} repair round(s): "
+                            f"{len(blocking)} blocking gap(s)."
+                        ),
+                    )
+                console.print(f"[yellow]Verification blocked ({len(blocking)} gap(s)); handing back repair guidance.[/yellow]")
+                messages.append({"role": "user", "content": self._format_next_actions(blocking, advisory)})
+                continue
 
             if not action.tool_calls:
                 # No action and not finished — nudge instead of silently burning a step.
@@ -169,10 +374,10 @@ Rules:
                     elif tool_call.tool == "apply_patch":
                         if "path" in tool_call.args and "content" in tool_call.args:
                             # Fallback for when the model can't produce a valid unified
-                            # diff. Routes through write_file, which enforces the same
-                            # planned-files permission check — no widening of scope.
-                            self.task_runner.write_file(
-                                tool_call.args["path"], tool_call.args["content"], task
+                            # diff. Routes through the lease-gated write path, which enforces
+                            # the same planned-files/scope policy — no widening of scope.
+                            self._gated_write_file(
+                                task, tool_call.args["path"], tool_call.args["content"]
                             )
                             consecutive_patch_failures = 0
                             result_summary = f"Wrote {tool_call.args['path']} via path+content fallback."
@@ -184,7 +389,7 @@ Rules:
                                     "'diff --git a/<path> b/<path>', then '--- a/<path>' (or "
                                     "'--- /dev/null' for a new file), '+++ b/<path>', and '@@' hunks."
                                 )
-                            self.task_runner.apply_patch(patch, task)
+                            self._gated_apply_patch(task, patch)
                             consecutive_patch_failures = 0
                             result_summary = "Successfully applied patch."
                     elif tool_call.tool == "run_command":
@@ -192,7 +397,7 @@ Rules:
                         result_summary = f"Command finished with exit code {cmd_result.exit_code}."
                     else:
                         raise ValueError(f"Unknown tool: {tool_call.tool}")
-                    
+
                     messages.append({"role": "user", "content": f"[Tool Result] '{tool_call.tool}': {result_summary}"})
                 except Exception as e:
                     logger.warning("Native agent tool %s failed for %s: %s", tool_call.tool, task.id, e)

package/src/devcouncil/executors/openhands.py

@@ -1,11 +1,14 @@
 import logging
 import subprocess
 from pathlib import Path
+
+from devcouncil.executors.transient_retry import run_subprocess_with_transient_retry
 from rich.console import Console
 from devcouncil.domain.task import Task
 from devcouncil.domain.requirement import Requirement
 from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.telemetry.stages import log_step
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -16,9 +19,19 @@ class OpenHandsExecutor(Executor):
 
     def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
         builder = PromptBuilder(self.project_root)
+        from devcouncil.planning.correction_manifest import repair_prompt_prefix
+
         task_prompt = builder.build_task_prompt(task, requirements)
+        prefix = repair_prompt_prefix(self.project_root, task.id)
+        if prefix:
+            task_prompt = f"{prefix}{task_prompt}"
         
         logger.info("OpenHands starting for %s", task.id)
+        log_step(
+            "executor/openhands: starting task %s" % task.id,
+            project_root=self.project_root,
+            task_id=task.id,
+        )
         console.print(f"Starting [bold]OpenHands[/bold] for task {task.id}...")
         
         # OpenHands often expects a workspace mount and an instruction.
@@ -40,24 +53,53 @@ class OpenHandsExecutor(Executor):
         console.print("[yellow]Note: OpenHands must be installed and configured in the environment.[/yellow]")
         
         try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                cwd=self.project_root,
-                timeout=1800,
+            def _run_once():
+                return subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    cwd=self.project_root,
+                    timeout=1800,
+                )
+
+            result = run_subprocess_with_transient_retry(
+                self.project_root,
+                label="OpenHands",
+                task_id=task.id,
+                run_once=_run_once,
             )
             self._write_log(task.id, result)
             if result.returncode != 0:
                 logger.error("OpenHands exited %s for %s", result.returncode, task.id)
+                log_step(
+                    "executor/openhands: finished task %s" % task.id,
+                    project_root=self.project_root,
+                    task_id=task.id,
+                    returncode=result.returncode,
+                    success=False,
+                )
                 console.print(f"[red]OpenHands exited with {result.returncode}.[/red]")
                 return ExecutionResult(success=False, message=f"Exited with code {result.returncode}")
             logger.info("OpenHands finished for %s", task.id)
+            log_step(
+                "executor/openhands: finished task %s" % task.id,
+                project_root=self.project_root,
+                task_id=task.id,
+                returncode=0,
+                success=True,
+            )
             return ExecutionResult(success=True, message="Completed successfully")
         except Exception as e:
             logger.exception("OpenHands error for %s: %s", task.id, e)
+            log_step(
+                "executor/openhands: finished task %s" % task.id,
+                project_root=self.project_root,
+                task_id=task.id,
+                success=False,
+                error=str(e),
+            )
             console.print(f"[red]Error running OpenHands: {e}[/red]")
             return ExecutionResult(success=False, message=str(e))
 

package/src/devcouncil/executors/transient_retry.py

@@ -0,0 +1,99 @@
+"""Shared transient-failure detection and retry for subprocess executors."""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Output signatures of failures caused by the NETWORK/PROVIDER, not the task.
+# Matched case-insensitively against stderr plus the tail of stdout.
+TRANSIENT_FAILURE_MARKERS = (
+    "connection closed",
+    "connection reset",
+    "connection refused",
+    "connection error",
+    "connection aborted",
+    "econnreset",
+    "econnrefused",
+    "etimedout",
+    "socket hang up",
+    "mid-response",
+    "network error",
+    "fetch failed",
+    "temporarily unavailable",
+    "service unavailable",
+    "internal server error",
+    "bad gateway",
+    "gateway timeout",
+    "overloaded",
+    "rate limit",
+    "too many requests",
+    "request timed out",
+    "timeout awaiting",
+    "tls handshake",
+    "dns",
+)
+
+
+def transient_failure_reason(result: subprocess.CompletedProcess[str]) -> str | None:
+    """Return the matched transient marker when a failed run looks provider-caused."""
+    haystack = f"{result.stderr or ''}\n{(result.stdout or '')[-4000:]}".lower()
+    for marker in TRANSIENT_FAILURE_MARKERS:
+        if marker in haystack:
+            return marker
+    return None
+
+
+def transient_error_in_text(text: str) -> str | None:
+    """Return a transient marker found in an exception message, else None."""
+    haystack = (text or "").lower()
+    for marker in TRANSIENT_FAILURE_MARKERS:
+        if marker in haystack:
+            return marker
+    return None
+
+
+def transient_retry_limit(project_root: Path, *, default: int = 2) -> int:
+    """Max transient-failure retries from ``execution.transient_retry_attempts``."""
+    try:
+        from devcouncil.app.config import load_config
+
+        return max(0, int(load_config(project_root).execution.transient_retry_attempts))
+    except Exception:
+        return default
+
+
+def run_subprocess_with_transient_retry(
+    project_root: Path,
+    *,
+    label: str,
+    task_id: str,
+    run_once: Callable[[], subprocess.CompletedProcess[str]],
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess callable, retrying on known transient failure signatures."""
+    result = run_once()
+    retry_limit = transient_retry_limit(project_root)
+    retries = 0
+    while result.returncode != 0 and retries < retry_limit:
+        reason = transient_failure_reason(result)
+        if reason is None:
+            break
+        retries += 1
+        delay = min(30.0, 5.0 * retries)
+        logger.warning(
+            "%s failed with a transient error for %s (%s); retrying %d/%d in %.0fs",
+            label,
+            task_id,
+            reason,
+            retries,
+            retry_limit,
+            delay,
+        )
+        time.sleep(delay)
+        result = run_once()
+    return result

package/src/devcouncil/gating/checks/clean_git.py

@@ -1,6 +1,7 @@
 import subprocess
 import logging
 from devcouncil.domain.gap import Gap
+from devcouncil.utils.proc import GIT_TIMEOUT
 
 logger = logging.getLogger(__name__)
 
@@ -15,7 +16,9 @@ class CleanGitCheck:
     
     def check(self, project_root, task_id: str) -> list[Gap]:
         try:
-            status = subprocess.check_output(["git", "status", "--porcelain"], cwd=project_root).decode()
+            status = subprocess.check_output(
+                ["git", "status", "--porcelain"], cwd=project_root, timeout=GIT_TIMEOUT
+            ).decode()
             dirty_lines = [line for line in status.splitlines() if line.strip() and not self._is_runtime_state(line)]
             if dirty_lines:
                 return [Gap(
@@ -38,7 +41,7 @@ class CleanGitCheck:
                 recommended_fix="Install git and ensure it is in your PATH.",
                 blocking=True
             )]
-        except subprocess.CalledProcessError as e:
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
             logger.warning("Git status check failed: %s", e)
             return [Gap(
                 id=f"GAP-{task_id}-GIT-ERROR",