pycastle 0.1.3.9.dev0__tar.gz → 0.1.3.11.dev0__tar.gz

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/CONTEXT.md

@@ -37,6 +37,7 @@
 | **CLI default** | The behavior when no `--model` or `--effort` flag is injected — triggered by an empty string in STAGE_OVERRIDES | default model, unset |
 | **validate_config** | Public function in the config validator module; takes a `Config` and a `ClaudeService`, resolves model shorthands to full model IDs, validates all stage overrides, and returns a new immutable `Config`; raises `ConfigValidationError` on any invalid entry | config validation, startup check |
 | **ConfigValidationError** | Error raised by validate_config when a model shorthand or effort level is unrecognised; includes the invalid value, closest valid suggestion, and full list of valid options | validation error, config error |
+| **auto_push** | Boolean config entry (default `True`) that controls whether `merge_phase` pushes local main to the remote after any merges produce commits; set to `False` to disable automatic pushing | push_after_merge, AUTO_PUSH |
 
 ## GitHub Integration
 
@@ -73,6 +74,12 @@
 | **clean merge** | A `git merge --no-edit` that exits zero and requires no conflict resolution | conflict-free merge, successful merge |
 | **conflicting branch** | A branch whose `git merge --no-edit` exits non-zero; `git merge --abort` is run immediately and the branch is collected for the Merger | failed merge branch |
 | **RALPH** | The required commit message prefix for all Implementer commits (e.g. `RALPH: fix auth bug`) | — |
+| **RALPH: Review -** | The required commit message prefix for all Reviewer commits (e.g. `RALPH: Review - improve error handling`); distinguished from Implementer commits by the `Review -` infix; each agent produces exactly one commit per branch | — |
+| **in-flight issue** | An open issue that has an existing `pycastle/issue-<n>` branch or worktree from a previous interrupted iteration; signals that implement or review work is already partially or fully complete | mid-flight issue, resumed issue |
+| **merge-time preflight skip** | The behavior when the Merger's Pre-flight phase returns failures: `merge_phase` logs a diagnostic, skips the Merger, and returns normally with conflict issues still pending; the next iteration's pre-planning preflight detects the broken baseline and recovers via the preflight-fix path | merge preflight abort |
+| **planning skip** | The behavior in `run_iteration` when at least one open issue is in-flight: the Planner is not invoked and only the in-flight issues are used as the working set for the current iteration; issues with neither a branch nor a worktree are deferred | plan bypass |
+| **implement skip** | The behavior in `run_issue` when a branch already has a `RALPH:` (non-review) commit: the Implementer is not spawned and the Reviewer runs directly via the existing-branch path | — |
+| **review skip** | The behavior in `run_issue` when a branch already has a `RALPH: Review -` commit: both the Implementer and Reviewer are skipped and the issue is counted as completed immediately | — |
 | **plan** | The structured JSON output by the Planner listing which issues to work on and the branch name for each; after parsing, `plan_phase()` sorts issues by ascending issue number so the orchestrator always processes older issues first | plan output, plan JSON |
 | **issue** | A GitHub issue labeled for agent processing, representing one unit of work | ticket, task, card |
 | **AFK issue** | An issue the Planner assigns to an Implementer because it can be resolved autonomously; labeled `ready-for-agent` | agent issue, auto issue |
@@ -85,7 +92,7 @@
 | **merge-sandbox worktree** | A temporary named-branch worktree (`pycastle/merge-sandbox`) created by `merge_phase` from HEAD after clean merges complete; the Merger runs inside it to resolve conflicting branches; always removed in a `try/finally` by `merge_phase` regardless of state; on success `merge_phase` fast-forwards `main` from the branch before cleanup; located at `.pycastle/.worktrees/merge-sandbox` | merger worktree, conflict worktree |
 | **branch** | A git branch name assigned to an issue inside the plan; follows the pattern `pycastle/issue-<n>-<slug>` | feature branch, issue branch |
 | **orphan worktree** | A worktree directory under `.pycastle/.worktrees/` no longer registered in git, typically left by a crashed agent run | stale worktree, leftover worktree |
-| **orphan sweep** | Startup operation that cross-references `.pycastle/.worktrees/` against `git worktree list --porcelain` and deletes unregistered directories | worktree cleanup, stale cleanup |
+| **orphan sweep** | Startup operation that cross-references `.pycastle/.worktrees/` against `git worktree list --porcelain`, deletes unregistered directories, and removes the `.worktrees` parent directory if no active children remain | worktree cleanup, stale cleanup |
 | **collision detection** | Mechanism that prevents two parallel agents from simultaneously creating worktrees for the same branch, implemented as a per-branch async lock | — |
 
 ## Prompts
@@ -156,8 +163,8 @@
 | **new-branch path** | The `git worktree add -b <branch> <path> <safe-SHA>` form used when the branch does not yet exist; always branched from the pinned safe SHA rather than HEAD | — |
 | **existing-branch path** | The `git worktree add <path> <branch>` form used when the branch already exists | — |
 | **worktree contents check** | Guard step run after `git worktree add` that verifies `pyproject.toml` or `requirements.txt` is present; fails with the worktree path and directory listing if absent | checkout guard, file check |
-| **`detached_worktree`** | Async context manager in `worktree.py` that creates a detached checkout at a given SHA, yields the path, and guarantees removal in `__aexit__` regardless of outcome; used by `planning_phase` and `preflight_phase` for their sandbox worktrees | managed_worktree |
-| **`branch_worktree`** | Async context manager in `worktree.py` that creates a named-branch worktree at a given SHA, yields the path, and on exit removes the worktree and optionally deletes the branch; used by `merge_phase` for the merge-sandbox worktree | managed_worktree |
+| **`detached_worktree`** | Async context manager in `worktree.py` that creates a detached checkout at a given SHA, yields the path, and guarantees removal in `__aexit__` regardless of outcome; also removes the `.worktrees` parent directory if no other worktrees remain after cleanup; used by `planning_phase` and `preflight_phase` for their sandbox worktrees | managed_worktree |
+| **`branch_worktree`** | Async context manager in `worktree.py` that creates a named-branch worktree at a given SHA, yields the path, and on exit removes the worktree, optionally deletes the branch, and removes the `.worktrees` parent directory if no other worktrees remain; used by `merge_phase` for the merge-sandbox worktree | managed_worktree |
 | **`_agent_worktree`** | Async context manager in `implement.py` that owns the full Implementer and Reviewer worktree lifecycle; accepts a branch name, SHA, `CancellationToken`, and `Deps`; on entry creates the worktree and gitdir overlay; on exit conditionally removes the worktree based on `token.wants_worktree_preserved` and working-tree cleanliness, and always removes the gitdir overlay; used by `run_issue` twice per issue — once for the Implementer (new-branch path) and once for the Reviewer (existing-branch path); defined in `implement.py` not `worktree.py` because its cleanup policy depends on agent-lifecycle state (`CancellationToken`) rather than being unconditional | managed_worktree |
 | **`worktree_name_for_branch`** | Function in `worktree.py` that derives a short directory name from a branch string: extracts `issue-N` from `pycastle/issue-N-slug` or falls back to a sanitised slug; single authoritative definition replacing duplicated regex in `agent_runner` and `merge_phase` | — |
 | **`worktree_path`** | Function in `worktree.py` that constructs the host filesystem path for a named worktree at `<repo_root>/<pycastle_dir>/.worktrees/<name>`; single authoritative path expression replacing duplication across all phase modules | — |
@@ -187,11 +194,12 @@
 | **GithubService** | Service that encapsulates `gh` CLI calls for GitHub issue operations: closing issues, querying parent issues, listing open sub-issues, and reading issue labels | GitHub wrapper, gh provider |
 | **Logger** | Injectable abstraction that owns all structured log output for one iteration; exposes named channels (`log_error`, `log_agent_output`) each writing to a dedicated file under `logs/`; injected via `Deps` so tests never touch the filesystem | log writer, output handler |
 | **RecordingLogger** | Test double for `Logger` that records every call in memory; tests assert on recorded calls rather than capturing stderr or reading log files | mock logger, spy logger |
-| **StatusDisplay** | Injectable abstraction that owns the live terminal status panel and all formatted terminal output; exposes `register(caller, startup_message="started", work_body="")`, `update_phase`, `reset_idle_timer`, `remove(caller, shutdown_message="finished", shutdown_style="success")`, and `print(caller, message, style=None)` methods; backed by a `rich` `Live` display in production and a `PlainStatusDisplay` in tests; injected via `Deps` as a separate concern from `Logger`; defined in `status_display` module | terminal display, status bar |
-| **caller** | The identity string passed as the first argument to `StatusDisplay.register`, `remove`, and `print`; rendered as a `[Caller]` prefix on every terminal output line; empty string `""` is the anonymous caller — no brackets are printed and the message is output as-is; a blank line is inserted before any output call (`register`, `remove`, or `print`) when the caller differs from the previous one, or unconditionally when the caller is `""` (anonymous outputs always stand alone); canonical callers — phase rows: `"Preflight"`, `"Plan"`, `"Implement"`, `"Merge"`; agents: `"Preflight Agent"`, `"Plan Agent"`, `"Implement Agent #N"`, `"Review Agent #N"`, `"Merge Agent"` | source, label |
-| **work_body** | The caller-constructed string passed as the third argument to `register`; displayed in the body column of the status row during the Work phase; empty string for callers that do not reach Work | — |
-| **PlainStatusDisplay** | Plain-terminal adapter for `StatusDisplay` defined in `status_display` module; panel methods (`update_phase`, `reset_idle_timer`) are no-ops; `register` and `remove` print their startup/shutdown messages; `print(caller, message, style=None)` formats output as `[Caller] message` with no ANSI colour codes, no bold, and style ignored; used in tests so assertions can match the full formatted line | NullStatusDisplay |
-| **status row** | One headerless line in the `StatusDisplay` live panel; created by `register` and removed by `remove`; two kinds: **agent rows** (one per active agent — `"Preflight Agent"`, `"Plan Agent"`, `"Implement Agent #N"`, `"Review Agent #N"`, `"Merge Agent"`) and **phase rows** (one per active phase — `"Preflight"`, `"Plan"`, `"Implement"`, `"Merge"`); phase rows and agent rows within the same phase coexist; format: `elapsed \| Name \| idle \| body`; elapsed is dim and right-justified; name is bold with any numeric part styled bold cyan; idle is dim; body shows the current lifecycle phase name for all non-Work states, or the `work_body` string during Work; elapsed counts up from `register` and never resets; idle resets on each Docker stream chunk; the live panel is preceded by one blank line to visually separate it from scrollback; ordered by orchestration phase (plan → implement → review → merge) then by issue number | agent status row, status entry, agent row |
+| **StatusDisplay** | Injectable abstraction that owns the live terminal status panel and all formatted terminal output; exposes `register(caller, startup_message="started", work_body="", initial_phase="Setup")`, `update_phase`, `reset_idle_timer`, `remove(caller, shutdown_message="finished", shutdown_style="success")`, and `print(caller, message, style=None)` methods; `shutdown_message` and `message` may contain `\n` — each line is emitted separately with the `[Caller]` prefix and the same style applied to every line; `shutdown_style` accepts `"success"` (green), `"error"` (red), or `"warning"` (yellow); backed by a `rich` `Live` display in production and a `PlainStatusDisplay` in tests; injected via `Deps` as a separate concern from `Logger`; defined in `status_display` module | terminal display, status bar |
+| **caller** | The identity string passed as the first argument to `StatusDisplay.register`, `remove`, and `print`; rendered as a `[Caller]` prefix on every terminal output line; empty string `""` is the anonymous caller — no brackets are printed and the message is output as-is; a blank line is inserted before any output call (`register`, `remove`, or `print`) when the caller differs from the previous one, unconditionally when the caller is `""` (anonymous outputs always stand alone), or before the very first output call (when no previous call has occurred); canonical callers — phase rows: `"Preflight"`, `"Plan"`, `"Implement"`, `"Merge"`; agents: `"Preflight Agent"`, `"Plan Agent"`, `"Implement Agent #N"`, `"Review Agent #N"`, `"Merge Agent"` | source, label |
+| **work_body** | The caller-constructed string passed as the third argument to `register`; applies to agent rows only; displayed in the body column during the Work phase; empty string for agent rows that do not reach Work; unused by phase rows (which use `initial_phase` for their fixed body label) | — |
+| **PlainStatusDisplay** | Plain-terminal adapter for `StatusDisplay` defined in `status_display` module; panel methods (`update_phase`, `reset_idle_timer`) are no-ops; `register` and `remove` print their startup/shutdown messages; `print(caller, message, style=None)` formats output as `[Caller] message` with no ANSI colour codes, no bold, and style ignored; multi-line messages are split and each line prefixed with `[Caller]`; used in tests so assertions can match the full formatted line | NullStatusDisplay |
+| **phase_row** | Async context manager in `iteration/` that owns the `StatusDisplay` register/remove lifecycle for a single phase row; on entry calls `register(caller)`; yields a `PhaseRow` whose `close(shutdown_message, shutdown_style="success")` method calls `remove()` and marks the row as closed; if `close()` is never called before exit (exception path), automatically calls `remove(caller, "failed", shutdown_style="error")`; the canonical way to manage phase row lifecycle — replaces hand-rolled active-flag patterns | — |
+| **status row** | One headerless line in the `StatusDisplay` live panel; created by `register` and removed by `remove`; two kinds: **agent rows** (one per active agent — `"Preflight Agent"`, `"Plan Agent"`, `"Implement Agent #N"`, `"Review Agent #N"`, `"Merge Agent"`) and **phase rows** (one per active phase — `"Preflight"`, `"Plan"`, `"Implement"`, `"Merge"`); phase rows and agent rows within the same phase coexist; format: `elapsed \| Name \| idle \| body`; elapsed is dim and right-justified; name is bold with any numeric part styled bold cyan; idle is dim; body column: for **agent rows**, shows the current agent lifecycle phase name for all non-Work states, or `work_body` during Work; for **phase rows**, shows the fixed `initial_phase` label passed at registration (`"Running"` for Preflight and Implement, `"Planning"` for Plan, `"Merging"` for Merge); elapsed counts up from `register` and never resets; idle resets on each Docker stream chunk; the live panel is preceded by one blank line to visually separate it from scrollback; ordered by orchestration phase (plan → implement → review → merge) then by issue number | agent status row, status entry, agent row |
 | **IterationOutcome** | Sealed return type of `run_iteration()`; one of four variants: `Continue` (iteration completed, keep looping), `Done` (no issues found, stop cleanly), `AbortedHITL` (HITL verdict — carries `issue_number`; orchestrator exits non-zero), `AbortedUsageLimit` (token ceiling hit — worktrees preserved; orchestrator sleeps until 2 minutes past the next local-time full hour, then continues the loop to retry the current issue from scratch; repeats indefinitely on consecutive hits) | iteration result, loop result |
 
 ## Test Anti-Patterns (Red Flags)
@@ -216,6 +224,8 @@
 - The **HITL verdict** is read by the orchestrator from the GitHub issue label after the **preflight-issue agent** completes; `ready-for-agent` triggers the **preflight-fix path**, `ready-for-human` aborts with a non-zero exit code.
 - On the **preflight-fix path**, the Planner is skipped; one Implementer is spawned for the preflight issue, followed by one Reviewer, then a merge; a new iteration then begins.
 - The **Planner** and all **Implementer** worktrees are created from the pinned **safe SHA**, never from HEAD directly; this guarantees every agent sees the same verified-clean committed state regardless of external commits that land on main after preflight passes.
+- The **planning skip** is checked before every Planner invocation; it takes priority over normal planning when any open issue is **in-flight**. The **implement skip** and **review skip** are checked inside `run_issue` before any worktree is created; they are mutually exclusive with normal agent spawning for that phase. Both skips are triggered by commit prefix detection (`RALPH: Review -` → review skip; `RALPH:` without `Review -` → implement skip only).
+- A **merge-time preflight skip** leaves conflict issues open; they become **in-flight issues** on the next iteration, triggering the **planning skip** and then the **implement skip** or **review skip** as appropriate once the baseline is fixed.
 - In **sequential mode** (`max_parallel = 1`), the iteration processes issues one by one: after each issue's merge the safe SHA is re-pinned to the new HEAD, and the next Implementer starts from that SHA; a failed issue is skipped (remains `ready-for-agent`) and the queue continues; the Merger remains available as a fallback for unexpected conflicts; no additional pre-flight checks run between issues.
 - The **Pre-flight phase** (agent lifecycle) runs quality checks inside the container and returns a list of failure tuples to the orchestrator; it never spawns agents internally.
 - An **orphan sweep** runs once at orchestrator startup; **collision detection** uses a per-branch `asyncio.Lock` held in `implement_phase` for the full duration of each `run_issue` call — from first worktree creation to final worktree teardown.
@@ -223,8 +233,8 @@
 - Host mounts per container: host repo → RO at `/home/agent/repo`; worktree → RW at `/home/agent/workspace`; `<host-repo>/.git` → RW at `/.pycastle-parent-git`; on Windows, gitdir overlay → RO over `/home/agent/workspace/.git`.
 - A **Service** defines a Custom exception hierarchy so callers never handle raw subprocess exceptions; tests inject Default implementations from a test fixture and override per-test for error paths.
 - **StatusDisplay** is a separate injectable in `Deps` alongside `Logger`; `Logger` owns file I/O, `StatusDisplay` owns the live terminal UI — they never overlap.
-- Rich markup (e.g. `[red]...[/red]`) must never be embedded in a `StatusDisplay.print` message string; colouring is expressed exclusively via the `style` parameter (`"error"`, `"success"`).
-- A **status row** is created by `StatusDisplay.register` and removed by `StatusDisplay.remove`; phase rows are registered at the start of each orchestration phase and removed at its end; agent rows are registered at container Setup and removed when the agent finishes or errors; the `rich` `Live` display is started on the first `register` call and stopped after the last `remove` call.
+- Rich markup (e.g. `[red]...[/red]`) must never be embedded in a `StatusDisplay.print` message string; colouring is expressed exclusively via the `style` parameter (`"error"`, `"success"`, `"warning"`).
+- A **status row** is created by `StatusDisplay.register` and removed by `StatusDisplay.remove`; phase rows are managed via the **`phase_row`** context manager — registered on entry and removed (with the phase outcome as the shutdown message) via `PhaseRow.close()`; agent rows are registered at container Setup and removed when the agent finishes or errors; the `rich` `Live` display is started on the first `register` call and stopped after the last `remove` call.
 - All orchestrator-level terminal output (e.g. "Planning complete…") is routed through `StatusDisplay.print()` so `rich` can coordinate it with the live panel; bare `print()` calls are not used while a `StatusDisplay` is active.
 - During the Work phase the container runner owns byte chunking, byte-to-line splitting, log writing, and idle timeout detection; it passes the decoded NDJSON line stream and an **`on_turn` callback** to **`process_stream`**, which assembles assistant turns (invoking the callback for each), detects usage limit lines and raises `UsageLimitError` immediately, unwraps the result envelope, and returns a typed `AgentOutput`; phases receive `AgentOutput` directly from `AgentRunner.run()` — no phase calls `parse()` or `assert_complete()`. Setup, Pre-flight, and Prepare phases produce no console output — their activity is reflected only in the body column of the agent status row.
 

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycastle
-Version: 0.1.3.9.dev0
+Version: 0.1.3.11.dev0
 Summary: Python orchestrator for autonomous Claude Code agents in Docker
 License: MIT License
         

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/agent_runner.py

@@ -1,151 +1,151 @@
-import dataclasses
-from pathlib import Path
-from typing import Any, Protocol
-
-from .agent_output_protocol import AgentOutput, AgentRole
-from .agent_result import CancellationToken, PreflightFailure
-from .config import Config
-from .container_runner import ContainerRunner
-from .errors import AgentTimeoutError, UsageLimitError
-from .services import GitService
-from .status_display import PlainStatusDisplay
-
-
-@dataclasses.dataclass
-class RunRequest:
-    name: str
-    prompt_file: Path
-    mount_path: Path
-    role: AgentRole = AgentRole.IMPLEMENTER
-    prompt_args: dict[str, str] | None = None
-    skip_preflight: bool = False
-    model: str = ""
-    effort: str = ""
-    stage: str = ""
-    token: CancellationToken | None = None
-    status_display: Any = None
-    issue_title: str = ""
-    work_body: str = ""
-
-
-class AgentRunnerProtocol(Protocol):
-    async def run(self, request: RunRequest) -> AgentOutput | PreflightFailure: ...
-
-    async def run_preflight(
-        self,
-        *,
-        name: str,
-        mount_path: Path,
-        stage: str = "",
-        status_display=None,
-        work_body: str = "",
-    ) -> list[tuple[str, str, str]]: ...
-
-
-class AgentRunner:
-    def __init__(
-        self,
-        env: dict[str, str],
-        cfg: Config,
-        git_service: GitService,
-        docker_client=None,
-    ) -> None:
-        self._env = env
-        self._cfg = cfg
-        self._git_service = git_service
-        self._docker_client = docker_client
-
-    async def run(self, request: RunRequest) -> AgentOutput | PreflightFailure:
-        name = request.name
-        prompt_file = request.prompt_file
-        mount_path = request.mount_path
-        prompt_args = request.prompt_args
-        skip_preflight = request.skip_preflight
-        model = request.model
-        effort = request.effort
-        token = request.token
-        status_display = request.status_display
-        work_body = request.work_body
-
-        if status_display is None:
-            status_display = PlainStatusDisplay()
-
-        _token = token if token is not None else CancellationToken()
-        if _token.is_cancelled:
-            raise UsageLimitError("Agent cancelled due to usage limit")
-
-        runner = ContainerRunner(
-            name,
-            mount_path,
-            self._env,
-            model=model,
-            effort=effort,
-            docker_client=self._docker_client,
-            status_display=status_display,
-            cfg=self._cfg,
-        )
-        try:
-            git_name = self._git_service.get_user_name()
-            git_email = self._git_service.get_user_email()
-            await runner.setup(git_name, git_email, work_body)
-            await runner.prepare(prompt_file, prompt_args or {})
-            if not skip_preflight:
-                failures = await runner.preflight(list(self._cfg.preflight_checks))
-                if failures:
-                    return PreflightFailure(failures=tuple(failures))
-            retries_left = self._cfg.timeout_retries
-            while True:
-                try:
-                    output = await runner.work(request.role)
-                    return output
-                except AgentTimeoutError:
-                    if retries_left <= 0:
-                        raise
-                    restart_num = self._cfg.timeout_retries - retries_left + 1
-                    status_display.print(
-                        name,
-                        f"Timeout — restarting"
-                        f" (attempt {restart_num}/{self._cfg.timeout_retries})",
-                    )
-                    retries_left -= 1
-                except UsageLimitError:
-                    _token.cancel(preserve_worktree=True)
-                    raise
-        finally:
-            status_display.remove(name)
-            try:
-                runner.__exit__(None, None, None)
-            except Exception:
-                pass
-
-    async def run_preflight(
-        self,
-        *,
-        name: str,
-        mount_path: Path,
-        stage: str = "",
-        status_display=None,
-        work_body: str = "",
-    ) -> list[tuple[str, str, str]]:
-        if status_display is None:
-            status_display = PlainStatusDisplay()
-
-        git_name = self._git_service.get_user_name()
-        git_email = self._git_service.get_user_email()
-        runner = ContainerRunner(
-            name,
-            mount_path,
-            self._env,
-            docker_client=self._docker_client,
-            status_display=status_display,
-            cfg=self._cfg,
-        )
-        try:
-            await runner.setup(git_name, git_email, work_body)
-            return await runner.preflight(list(self._cfg.preflight_checks))
-        finally:
-            status_display.remove(name)
-            try:
-                runner.__exit__(None, None, None)
-            except Exception:
-                pass
+import dataclasses
+from pathlib import Path
+from typing import Any, Protocol
+
+from .agent_output_protocol import AgentOutput, AgentRole
+from .agent_result import CancellationToken, PreflightFailure
+from .config import Config
+from .container_runner import ContainerRunner
+from .errors import AgentTimeoutError, UsageLimitError
+from .services import GitService
+from .status_display import PlainStatusDisplay
+
+
+@dataclasses.dataclass
+class RunRequest:
+    name: str
+    prompt_file: Path
+    mount_path: Path
+    role: AgentRole = AgentRole.IMPLEMENTER
+    prompt_args: dict[str, str] | None = None
+    skip_preflight: bool = False
+    model: str = ""
+    effort: str = ""
+    stage: str = ""
+    token: CancellationToken | None = None
+    status_display: Any = None
+    issue_title: str = ""
+    work_body: str = ""
+
+
+class AgentRunnerProtocol(Protocol):
+    async def run(self, request: RunRequest) -> AgentOutput | PreflightFailure: ...
+
+    async def run_preflight(
+        self,
+        *,
+        name: str,
+        mount_path: Path,
+        stage: str = "",
+        status_display=None,
+        work_body: str = "",
+    ) -> list[tuple[str, str, str]]: ...
+
+
+class AgentRunner:
+    def __init__(
+        self,
+        env: dict[str, str],
+        cfg: Config,
+        git_service: GitService,
+        docker_client=None,
+    ) -> None:
+        self._env = env
+        self._cfg = cfg
+        self._git_service = git_service
+        self._docker_client = docker_client
+
+    async def run(self, request: RunRequest) -> AgentOutput | PreflightFailure:
+        name = request.name
+        prompt_file = request.prompt_file
+        mount_path = request.mount_path
+        prompt_args = request.prompt_args
+        skip_preflight = request.skip_preflight
+        model = request.model
+        effort = request.effort
+        token = request.token
+        status_display = request.status_display
+        work_body = request.work_body
+
+        if status_display is None:
+            status_display = PlainStatusDisplay()
+
+        _token = token if token is not None else CancellationToken()
+        if _token.is_cancelled:
+            raise UsageLimitError("Agent cancelled due to usage limit")
+
+        runner = ContainerRunner(
+            name,
+            mount_path,
+            self._env,
+            model=model,
+            effort=effort,
+            docker_client=self._docker_client,
+            status_display=status_display,
+            cfg=self._cfg,
+        )
+        try:
+            git_name = self._git_service.get_user_name()
+            git_email = self._git_service.get_user_email()
+            await runner.setup(git_name, git_email, work_body)
+            await runner.prepare(prompt_file, prompt_args or {})
+            if not skip_preflight:
+                failures = await runner.preflight(list(self._cfg.preflight_checks))
+                if failures:
+                    return PreflightFailure(failures=tuple(failures))
+            retries_left = self._cfg.timeout_retries
+            while True:
+                try:
+                    output = await runner.work(request.role)
+                    return output
+                except AgentTimeoutError:
+                    if retries_left <= 0:
+                        raise
+                    restart_num = self._cfg.timeout_retries - retries_left + 1
+                    status_display.print(
+                        name,
+                        f"Timeout — restarting"
+                        f" (attempt {restart_num}/{self._cfg.timeout_retries})",
+                    )
+                    retries_left -= 1
+                except UsageLimitError:
+                    _token.cancel(preserve_worktree=True)
+                    raise
+        finally:
+            status_display.remove(name)
+            try:
+                runner.__exit__(None, None, None)
+            except Exception:
+                pass
+
+    async def run_preflight(
+        self,
+        *,
+        name: str,
+        mount_path: Path,
+        stage: str = "",
+        status_display=None,
+        work_body: str = "",
+    ) -> list[tuple[str, str, str]]:
+        if status_display is None:
+            status_display = PlainStatusDisplay()
+
+        git_name = self._git_service.get_user_name()
+        git_email = self._git_service.get_user_email()
+        runner = ContainerRunner(
+            name,
+            mount_path,
+            self._env,
+            docker_client=self._docker_client,
+            status_display=status_display,
+            cfg=self._cfg,
+        )
+        try:
+            await runner.setup(git_name, git_email, work_body)
+            return await runner.preflight(list(self._cfg.preflight_checks))
+        finally:
+            status_display.remove(name)
+            try:
+                runner.__exit__(None, None, None)
+            except Exception:
+                pass

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/config/loader.py

@@ -46,6 +46,7 @@ class Config:
             "pytest",
         )
     )
+    auto_push: bool = True
     timeout_retries: int = 1
     usage_limit_patterns: tuple[str, ...] = dataclasses.field(
         default_factory=lambda: ("You've hit your", "Credit balance is too low")

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/defaults/config.py

@@ -5,6 +5,7 @@ from pycastle import StageOverride
 # max_parallel = 1
 # worktree_timeout = 30
 # idle_timeout = 300
+# auto_push = True
 
 # --- Docker ---
 # Name for the Docker image built by `pycastle build`.

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/defaults/prompts/implement-prompt.md

@@ -1,15 +1,5 @@
 # Workflow
 
-### 0. Prior Run Detection
-
-Before starting, check whether prior RALPH work exists on this branch.
-
-Run `git log main..HEAD --oneline`. If any commits are present, prior RALPH work is already done — emit `<promise>COMPLETE</promise>` and stop.
-
-Otherwise, run `git status`. If the working tree is dirty, review the existing uncommitted changes and continue from the current state rather than starting over.
-
-If both checks show a clean, empty branch, fall through to step 1 and proceed normally.
-
 ### 1. Task
 
 Fix issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}

pycastle-0.1.3.11.dev0/src/pycastle/iteration/__init__.py

@@ -0,0 +1,130 @@
+import dataclasses
+from typing import TypeAlias
+
+from ..agent_result import CancellationToken, PreflightFailure
+from ..worktree import worktree_name_for_branch, worktree_path
+from ._deps import Deps
+from ._phase_row import PhaseRow, phase_row
+from .implement import branch_for, implement_phase
+from .merge import merge_phase
+from .preflight import PreflightAFK, PreflightHITL, PreflightReady, preflight_phase
+from .planning import PlanReady, planning_phase
+
+
+@dataclasses.dataclass(frozen=True)
+class Continue:
+    pass
+
+
+@dataclasses.dataclass(frozen=True)
+class Done:
+    pass
+
+
+@dataclasses.dataclass(frozen=True)
+class AbortedHITL:
+    issue_number: int
+
+
+@dataclasses.dataclass(frozen=True)
+class AbortedUsageLimit:
+    pass
+
+
+IterationOutcome: TypeAlias = Continue | Done | AbortedHITL | AbortedUsageLimit
+
+
+def _is_in_flight(issue: dict, deps: Deps) -> bool:
+    branch = branch_for(issue["number"])
+    if deps.git_svc.verify_ref_exists(branch, deps.repo_root):
+        return True
+    name = worktree_name_for_branch(branch)
+    return worktree_path(name, deps).exists()
+
+
+async def run_iteration(deps: Deps) -> IterationOutcome:
+    deps.status_display.register("Preflight", initial_phase="Running")
+    try:
+        preflight_result = await preflight_phase(deps)
+    finally:
+        deps.status_display.remove("Preflight")
+
+    if isinstance(preflight_result, PreflightHITL):
+        deps.status_display.print(
+            "Preflight",
+            f"Preflight issue #{preflight_result.issue_number} requires human intervention. Exiting.",
+        )
+        return AbortedHITL(issue_number=preflight_result.issue_number)
+
+    if isinstance(preflight_result, PreflightReady):
+        if not preflight_result.issues:
+            return Done()
+        sha = preflight_result.sha
+        open_issues = preflight_result.issues
+        in_flight = [i for i in open_issues if _is_in_flight(i, deps)]
+        if in_flight:
+            issues = in_flight
+        elif len(open_issues) >= 2:
+            async with phase_row(deps.status_display, "Plan", initial_phase="Planning") as row:
+                plan_result = await planning_phase(deps, sha, open_issues)
+                issue_lines = [
+                    f"  #{i['number']}: {i['title']} → {branch_for(i['number'])}"
+                    for i in plan_result.issues
+                ]
+                row.close(
+                    "\n".join(
+                        [f"Planning complete, {len(plan_result.issues)} issue(s):"] + issue_lines
+                    )
+                )
+                sha = plan_result.worktree_sha
+                issues = plan_result.issues
+        else:
+            issues = open_issues
+    elif isinstance(preflight_result, PreflightAFK):
+        sha = preflight_result.worktree_sha
+        issues = preflight_result.issues
+
+    issues = issues[: deps.cfg.max_parallel]
+
+    token = CancellationToken()
+    async with phase_row(deps.status_display, "Implement", initial_phase="Running") as row:
+        impl_result = await implement_phase(issues, sha, deps, token=token)
+
+        if impl_result.usage_limit_hit:
+            row.close("finished")
+            return AbortedUsageLimit()
+
+        for issue, error in impl_result.errors:
+            match error:
+                case PreflightFailure(failures=fs):
+                    deps.status_display.print(
+                        "Implement",
+                        f"  ✗ #{issue['number']} ({branch_for(issue['number'])}) pre-flight failed:",
+                    )
+                    for check_name, command, output in fs:
+                        deps.status_display.print(
+                            "Implement",
+                            f"    ✗ {check_name} ({command}): {output}",
+                        )
+                case _:
+                    deps.status_display.print(
+                        "Implement",
+                        f"  ✗ #{issue['number']} ({branch_for(issue['number'])}) failed: {error}",
+                    )
+
+        completed = impl_result.completed
+
+        if not completed:
+            row.close("No commits produced. Nothing to merge.", shutdown_style="warning")
+            return Continue()
+
+        branch_lines = [f"  {branch_for(i['number'])}" for i in completed]
+        row.close(
+            "\n".join(
+                [f"Execution complete, {len(completed)} branch(es) with commits:"] + branch_lines
+            )
+        )
+
+    await merge_phase(completed, deps)
+
+    return Continue()

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/iteration/_deps.py

@@ -34,8 +34,8 @@ class RecordingStatusDisplay:
     def __init__(self) -> None:
         self.calls: list[tuple] = []
 
-    def register(self, caller: str, startup_message: str = "started", work_body: str = "") -> None:
-        self.calls.append(("register", caller, startup_message, work_body))
+    def register(self, caller: str, startup_message: str = "started", work_body: str = "", initial_phase: str = "Setup") -> None:
+        self.calls.append(("register", caller, startup_message, initial_phase))
 
     def update_phase(self, name: str, phase: str) -> None:
         self.calls.append(("update_phase", name, phase))

pycastle-0.1.3.11.dev0/src/pycastle/iteration/_phase_row.py

@@ -0,0 +1,30 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from ..status_display import StatusDisplay
+
+
+class PhaseRow:
+    def __init__(self, status_display: StatusDisplay, caller: str) -> None:
+        self._status_display = status_display
+        self._caller = caller
+        self._closed = False
+
+    def close(self, shutdown_message: str, shutdown_style: str = "success") -> None:
+        if self._closed:
+            return
+        self._status_display.remove(self._caller, shutdown_message, shutdown_style)
+        self._closed = True
+
+
+@asynccontextmanager
+async def phase_row(
+    status_display: StatusDisplay, caller: str, initial_phase: str = "Setup"
+) -> AsyncGenerator[PhaseRow, None]:
+    status_display.register(caller, initial_phase=initial_phase)
+    row = PhaseRow(status_display, caller)
+    try:
+        yield row
+    finally:
+        if not row._closed:
+            status_display.remove(caller, "failed", shutdown_style="error")

{pycastle-0.1.3.9.dev0 → pycastle-0.1.3.11.dev0}/src/pycastle/iteration/_utils.py

@@ -3,13 +3,14 @@ import asyncio
 from ._deps import Deps
 
 
-async def _wait_for_clean_working_tree(deps: Deps, phase: str = "merge") -> None:
+async def _wait_for_clean_working_tree(deps: Deps, caller: str, phase: str = "") -> None:
     if deps.git_svc.is_working_tree_clean(deps.repo_root):
         return
+    phase_name = phase or caller.lower()
     deps.status_display.print(
-        "",
+        caller,
         "Working tree has uncommitted changes. "
-        f"Please commit or revert all local changes before the {phase} phase can proceed.",
+        f"Please commit or revert all local changes before the {phase_name} phase can proceed.",
         style="error",
     )
     while not deps.git_svc.is_working_tree_clean(deps.repo_root):