forgeo-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-08-18
+
+### Added
+
+- `no_changes_retry_max` config key: a task whose agent exits `0` without
+  producing any code changes is re-run immediately, in the same cycle, up to
+  that many extra times before it is marked `BLOCKED` for human review.
+
+### Changed
+
+- A silent no-change SUCCESS (agent exits `0` with an unchanged working tree)
+  now marks the task `BLOCKED` instead of `FAILED`: the only acceptable
+  outcome for a run that ends without code changes is a blocked task awaiting
+  human review. An agent that needs no code change must still opt in
+  explicitly with `no_changes_exit_code` to complete the task.
+
+## [0.7.1] - 2026-08-17
+
+### Added
+
+- An animated demo GIF in the README, showing Forgeo running a backlog task
+  end to end, plus an Open Graph social-preview image for the docs site.
+
+### Changed
+
+- The default agent prompt (used by `forgeo init`) now names `AGENTS.md` and
+  `CONTEXT.md` explicitly when telling the agent to keep project overview and
+  conventions up to date.
+
 ## [0.7.0] - 2026-08-16
 
 ### Added
@@ -308,7 +337,9 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...HEAD
+[0.7.2]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...v0.7.2
+[0.7.1]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/lucaGazzola/forgeo/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lucaGazzola/forgeo/compare/v0.4.0...v0.5.0

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.7.0
+Version: 0.7.2
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -64,6 +64,10 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/README.md

@@ -10,6 +10,10 @@
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/docs/agent-contract.md

@@ -69,8 +69,11 @@ Forgeo cannot tell "the agent deliberately made no changes" from "the agent
 did nothing". A `SUCCESS` exit that produces **no changes is therefore not a
 valid completion for a task**:
 
-- exiting `0` while leaving the working tree **unchanged** fails the task
-  (`FAILED`, reason: *"Agent exited 0 but produced no changes"*);
+- exiting `0` while leaving the working tree **unchanged** is retried
+  immediately (`no_changes_retry_max`, see [Configuration](configuration.md))
+  and, once that budget is spent, the task is marked `BLOCKED` — never
+  `FAILED` and never silently `COMPLETED`. The only acceptable outcome for a
+  run that ends without code changes is a blocked task awaiting human review;
 - to complete a task **without touching the code**, exit
   `no_changes_exit_code` (default `3`). The working tree must be clean — an
   agent that reports "no changes" while leaving uncommitted work behind fails
@@ -121,7 +124,7 @@ that, based on the exit code. The working contract is:
 - **do not** run `git add`, `git commit`, `git push`, or reset the tree;
 - exit `0` to have your changes committed and pushed as one commit;
 - exit `no_changes_exit_code` when the task needs no code change (never exit
-  `0` with an empty tree — that fails the task);
+  `0` with an empty tree — that run is retried and then marked `BLOCKED`);
 - exit `blocked_exit_code` to have partial work preserved and a blocker
   written;
 - exit anything else to have your changes discarded.
@@ -135,8 +138,9 @@ agent_command: >
   Make the code changes requested below and nothing else. Do NOT run
   git commit, git push, or git add -A — Forgeo commits your work.
   Verify with the test suite where applicable.
-  Read AGENTS.md (and CONTEXT.md if present) at the start of the session;
-  if your change materially affects the project overview, keep them updated.
+  Read AGENTS.md at the start of the session, and CONTEXT.md if present;
+  if your change materially affects the project overview or conventions,
+  update AGENTS.md and CONTEXT.md accordingly.
   $FORGEO_TASK"
 ```
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/docs/configuration.md

@@ -42,6 +42,7 @@ paths), so `forgeo restart` is still used for those.
 | <span style="white-space: nowrap">`run_output_lines`</span> | `200` | How many agent output lines each run record keeps in `runs.jsonl` (the bounded tail of the agent's stdout/stderr). `0` disables persisting agent output. |
 | <span style="white-space: nowrap">`failed_retry_max`</span> | `0` | How many times a `FAILED` task is retried automatically. `0` (default) = a `FAILED` task stays `FAILED` until a human reopens it, exactly as before. A task may override this budget per-task with `retries_left`. |
 | <span style="white-space: nowrap">`failed_retry_wait_cycles`</span> | `1` | How many cycles a retry-eligible `FAILED` task waits (backoff) before it is moved back to `OPEN`. |
+| <span style="white-space: nowrap">`no_changes_retry_max`</span> | `0` | How many times a task whose agent exits `0` without producing any code changes is re-run immediately, in the same cycle, before the task is marked `BLOCKED` for human review. `0` (default) = a silent no-change SUCCESS is marked `BLOCKED` on the first attempt. |
 | <span style="white-space: nowrap">`git_timeout_seconds`</span> | `120` | Kill a git subprocess after this many seconds. |
 | <span style="white-space: nowrap">`telegram_bot_token`</span> | — | Telegram bot token for blocked-run notifications (disabled unless `telegram_chat_id` is also set). |
 | <span style="white-space: nowrap">`telegram_chat_id`</span> | — | Chat ID that receives blocked-run notifications (disabled unless `telegram_bot_token` is also set). |
@@ -254,6 +255,28 @@ failed_retry_max: 3           # retry each FAILED task up to 3 times
 failed_retry_wait_cycles: 2   # back off 2 cycles before each retry
 ```
 
+### `no_changes_retry_max`
+
+An agent that exits `0` while leaving the working tree unchanged has not
+completed the task — the engine cannot tell "deliberately did nothing" from
+"did nothing". By default (`no_changes_retry_max: 0`) that run is marked
+`BLOCKED` on the first attempt: the only acceptable outcome for a no-change
+run is a blocked task awaiting human review, never a silent completion and
+never a `FAILED` task.
+
+Sometimes the agent needs a second chance (a flaky model, a transient context
+issue). Set a positive `no_changes_retry_max` and Forgeo re-runs the agent
+immediately, back-to-back in the **same cycle**, that many extra times; a run
+that finally produces changes completes the task, and one that still produces
+nothing after the budget is spent is marked `BLOCKED`.
+
+```yaml
+no_changes_retry_max: 2       # re-run the agent up to 2 extra times on a silent no-change
+```
+
+`BLOCKED` tasks are never auto-retried — a human decides whether to reopen,
+split, or drop the task (see [Backlog](backlog.md)).
+
 ### Telegram notifications
 
 Both `telegram_bot_token` **and** `telegram_chat_id` must be set for blocked

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/install.sh

@@ -14,7 +14,7 @@ set -eu
 
 REPO_OWNER="lucaGazzola"
 REPO_NAME="forgeo"
-DEFAULT_VERSION="0.7.0"
+DEFAULT_VERSION="0.7.2"
 MIN_PYTHON="3.11"
 PYPI_PACKAGE="forgeo-cli"
 PREFIX="${FORGEO_PREFIX:-${HOME:-}/.local}"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.7.0"
+version = "0.7.2"
 description = "A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input."
 readme = "README.md"
 requires-python = ">=3.11"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/__init__.py

@@ -7,4 +7,4 @@ try:
 
     __version__ = _pkg_version("forgeo-cli")
 except PackageNotFoundError:  # standalone binary: no installed package metadata
-    __version__ = "0.7.0"
+    __version__ = "0.7.2"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/central.py

@@ -623,10 +623,21 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
                 logger.exception("Web request failed: %s", urlparse(self.path).path)
                 self._send_json(500, {"error": "internal server error"})
 
-        def do_GET(self) -> None:
+        def _dispatch(self, handler: Callable[[], None]) -> None:
+            """Authorize, then run one request handler safely.
+
+            Shared by the five HTTP verbs: a request is authorized first (a
+            missing or wrong bearer token answers ``401`` without reaching the
+            handler), then the handler runs under :meth:`_run_safely` so a
+            failure is answered with a JSON 500 instead of crashing the
+            server thread.
+            """
             if not self._maybe_authorize(self.path):
                 return
-            self._run_safely(self._do_get)
+            self._run_safely(handler)
+
+        def do_GET(self) -> None:
+            self._dispatch(self._do_get)
 
         def _do_get(self) -> None:
             parsed = urlparse(self.path)
@@ -652,9 +663,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_POST(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_post)
+            self._dispatch(self._do_post)
 
         def _do_post(self) -> None:
             parsed = urlparse(self.path)
@@ -666,9 +675,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_PATCH(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_patch)
+            self._dispatch(self._do_patch)
 
         def _do_patch(self) -> None:
             parsed = urlparse(self.path)
@@ -680,9 +687,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_DELETE(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_delete)
+            self._dispatch(self._do_delete)
 
         def _do_delete(self) -> None:
             parsed = urlparse(self.path)
@@ -694,9 +699,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_PUT(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_put)
+            self._dispatch(self._do_put)
 
         def _do_put(self) -> None:
             parsed = urlparse(self.path)
@@ -1230,12 +1233,12 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
                     )
                     return
                 recorder = RunRecorder(runs_path(info.config))
-                records = recorder.read(limit=limit, offset=offset)
+                records, total = recorder.read_with_total(limit=limit, offset=offset)
                 self._send_json(
                     200,
                     {
                         "runs": [r.model_dump(mode="json") for r in records],
-                        "total": recorder.total(),
+                        "total": total,
                         "offset": offset,
                         "limit": limit,
                     },
@@ -1367,26 +1370,14 @@ def stop_web(timeout: float = WEB_STOP_TIMEOUT_SECONDS) -> None:
             f"The lock file {lock.lock_path} records no PID; find the dashboard "
             f"with `pgrep -af forgeo` and stop it manually."
         )
-    logger.info("Stopping central dashboard (pid %s)...", pid)
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except ProcessLookupError:
-        if not lock.is_held():
-            logger.info("Central dashboard stopped.")
-            return
-        raise WebLockError(
-            f"Recorded pid {pid} is gone but the lock file is still held; "
-            f"check with `pgrep -af forgeo`."
-        )
-    except PermissionError:
-        raise WebLockError(f"No permission to stop process {pid}.")
-    if daemon_control.wait_for_lock_release(lock.lock_path, timeout, is_held=lock.is_held):
-        lock.release()
-        logger.info("Central dashboard stopped.")
-        return
-    raise WebLockError(
-        f"Central dashboard is still shutting down after {timeout:.0f}s; giving up."
+    daemon_control.signal_and_wait_for_release(
+        pid,
+        name="central dashboard",
+        is_held=lock.is_held,
+        timeout=timeout,
+        error_cls=WebLockError,
     )
+    lock.release()
 
 
 def start_web_detached(

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/cli.py

@@ -317,9 +317,7 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _add_config_or_name(
-    parser: argparse.ArgumentParser, *, default_config: Path = DEFAULT_CONFIG
-) -> None:
+def _add_config_or_name(parser: argparse.ArgumentParser) -> None:
     """Add a mutually-exclusive ``--config``/``--name`` option pair.
 
     ``--config`` keeps its default so plain ``forgeo start`` (etc.) keeps
@@ -330,7 +328,7 @@ def _add_config_or_name(
     group.add_argument(
         "--config",
         type=Path,
-        default=default_config,
+        default=DEFAULT_CONFIG,
         help="Forgeo YAML file (default: forgeo.yaml).",
     )
     group.add_argument(
@@ -654,20 +652,37 @@ def _run_worker_with_lock(
     return result
 
 
-def cmd_once(args: argparse.Namespace) -> int:
-    """Handle ``forgeo once``: run exactly one cycle and exit."""
+def _run_worker_once(
+    args: argparse.Namespace,
+    runner: Callable[[Forgeo], Coroutine[Any, Any, int]],
+) -> int:
+    """Prepare the worker and run one cycle through ``runner``.
+
+    Shared plumbing of ``forgeo once`` and ``forgeo run``: resolve the config,
+    take the per-forgeo lock, run the optional update check, execute exactly
+    one cycle via ``runner``, and release the lock on the way out.
+    """
     prepared = _prepare_worker(args)
     if prepared is None:
         return 1
     _config_path, _config, forgeo, lock = prepared
 
-    async def _run_once() -> int:
+    async def _execute() -> int:
         check_for_update(update_state_path(_config), print_fn=console.print)
+        return await runner(forgeo)
+
+    return _run_worker_with_lock(lock, _execute)
+
+
+def cmd_once(args: argparse.Namespace) -> int:
+    """Handle ``forgeo once``: run exactly one cycle and exit."""
+
+    async def _cycle(forgeo: Forgeo) -> int:
         outcome = await forgeo.run_cycle()
         console.print(f"[green]Cycle finished: {outcome}[/green]")
         return 0
 
-    return _run_worker_with_lock(lock, _run_once)
+    return _run_worker_once(args, _cycle)
 
 
 def cmd_run(args: argparse.Namespace) -> int:
@@ -680,14 +695,9 @@ def cmd_run(args: argparse.Namespace) -> int:
     overlaps them; it refuses (exit 1) when the task does not exist or is
     not ``OPEN``.
     """
-    prepared = _prepare_worker(args)
-    if prepared is None:
-        return 1
-    _config_path, _config, forgeo, lock = prepared
     task_id = args.task
 
-    async def _run_one() -> int:
-        check_for_update(update_state_path(_config), print_fn=console.print)
+    async def _one(forgeo: Forgeo) -> int:
         try:
             outcome = await forgeo.run_task_id(task_id)
         except TaskNotRunnableError as exc:
@@ -696,7 +706,7 @@ def cmd_run(args: argparse.Namespace) -> int:
         console.print(f"[green]Cycle finished: {outcome}[/green]")
         return 0
 
-    return _run_worker_with_lock(lock, _run_one)
+    return _run_worker_once(args, _one)
 
 
 def cmd_init(args: argparse.Namespace) -> int:

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/daemon_control.py

@@ -14,7 +14,6 @@ Everything here is lock-file driven and never touches the config-save flow.
 
 from __future__ import annotations
 
-import functools
 import logging
 import os
 import signal
@@ -65,26 +64,49 @@ def wait_for_process_ready(
     return None
 
 
-def wait_for_lock_release(
-    lock_path: Path,
-    timeout: float,
+def signal_and_wait_for_release(
+    pid: int,
     *,
-    is_held: Callable[[], bool] | None = None,
-) -> bool:
-    """Poll until the lock is released; False on timeout.
-
-    ``is_held`` defaults to the flock-based :func:`is_lock_held`; pass a
-    custom predicate (e.g. a PID-alive check for the web-dashboard lock) to
-    reuse the same wait loop for other lock kinds.
+    name: str,
+    is_held: Callable[[], bool],
+    timeout: float,
+    error_cls: type[Exception],
+    timeout_hint: str = "",
+) -> None:
+    """SIGTERM ``pid`` and wait for the lock it holds to be released.
+
+    Shared by the daemon and the central-dashboard stop commands: SIGTERM the
+    recorded PID, tolerate a process that already exited (as long as its lock
+    is gone too), refuse without permission, and wait for the lock to drop
+    within ``timeout`` (a cycle in progress finishes first). Any failure
+    raises ``error_cls`` — each caller's own error type — with a user-facing
+    message; on success ``name`` is logged as stopped.
     """
-    if is_held is None:
-        is_held = functools.partial(is_lock_held, lock_path)
+    logger.info("Stopping %s (pid %s)...", name, pid)
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        if not is_held():
+            logger.info("%s stopped.", name)
+            return
+        raise error_cls(
+            f"Recorded pid {pid} is gone but the lock is still held; "
+            f"check with `pgrep -af forgeo`."
+        ) from None
+    except PermissionError:
+        raise error_cls(f"No permission to stop process {pid}.") from None
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
         if not is_held():
-            return True
+            logger.info("%s stopped.", name)
+            return
         time.sleep(_POLL_SECONDS)
-    return not is_held()
+    if not is_held():
+        logger.info("%s stopped.", name)
+        return
+    raise error_cls(
+        f"{name} is still shutting down after {timeout:.0f}s{timeout_hint}; giving up."
+    )
 
 
 def stop_daemon(
@@ -103,25 +125,13 @@ def stop_daemon(
             f"The lock file {lock_path} records no PID; find the daemon "
             f"with `pgrep -af forgeo` and stop it manually."
         )
-    logger.info("Stopping forgeo %r (pid %s)...", config.name, pid)
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except ProcessLookupError:
-        if not is_lock_held(lock_path):
-            logger.info("Forgeo %r stopped.", config.name)
-            return
-        raise DaemonError(
-            f"Recorded pid {pid} is gone but the lock is still held; "
-            f"check with `pgrep -af forgeo`."
-        )
-    except PermissionError:
-        raise DaemonError(f"No permission to stop process {pid}.")
-    if wait_for_lock_release(lock_path, timeout):
-        logger.info("Forgeo %r stopped.", config.name)
-        return
-    raise DaemonError(
-        f"Forgeo is still shutting down after {timeout:.0f}s "
-        f"(a cycle in progress finishes first); giving up."
+    signal_and_wait_for_release(
+        pid,
+        name=f"forgeo {config.name!r}",
+        is_held=lambda: is_lock_held(lock_path),
+        timeout=timeout,
+        error_cls=DaemonError,
+        timeout_hint=" (a cycle in progress finishes first)",
     )
 
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/forgeo.py

@@ -62,12 +62,12 @@ class TaskNotRunnableError(RuntimeError):
 
 
 def _execution_outcome(status: ExecutionStatus) -> RunOutcome:
-    """Map an agent execution status onto a run record outcome."""
-    return {
-        ExecutionStatus.SUCCESS: RunOutcome.SUCCESS,
-        ExecutionStatus.BLOCKED: RunOutcome.BLOCKED,
-        ExecutionStatus.ERROR: RunOutcome.ERROR,
-    }[status]
+    """Map an agent execution status onto a run record outcome.
+
+    The two enums share member names for the agent outcomes (SUCCESS, BLOCKED,
+    ERROR), so the mapping is a plain name lookup.
+    """
+    return RunOutcome[status.name]
 
 
 def _subject_label(task: Task, *, is_refactor: bool) -> str:
@@ -82,7 +82,6 @@ class BlockerEntry:
     task: Task
     result: ExecutionResult
     instruction: str
-    is_refactor: bool = False
 
 
 class Forgeo:
@@ -134,10 +133,7 @@ class Forgeo:
         tasks = await self.backlog.list_tasks()
         task = oldest_open_task(tasks)
         if task is not None:
-            if not await self._tree_clean_for(task):
-                return "dirty"
-            await self._run_task(task)
-            return "task"
+            return await self._run_task_clean(task)
 
         if self.config.blocker_file.exists():
             logger.info("Blocker file present; forgeo paused until it is resolved.")
@@ -182,10 +178,7 @@ class Forgeo:
                 f"Task {task_id!r} is {task.status.value}; only OPEN tasks can "
                 f"be run with `forgeo run`."
             )
-        if not await self._tree_clean_for(task):
-            return "dirty"
-        await self._run_task(task)
-        return "task"
+        return await self._run_task_clean(task)
 
     async def _begin_run(self) -> list[Task]:
         """Reset the run state and load the tasks for a new cycle."""
@@ -212,6 +205,18 @@ class Forgeo:
         )
         return False
 
+    async def _run_task_clean(self, task: Task) -> str:
+        """Run ``task`` when the working tree is clean; returns the outcome label.
+
+        Shared by the scheduled pick (:meth:`_run_cycle`) and the explicit
+        ``forgeo run`` (:meth:`_run_task_id`): a dirty tree is refused with a
+        ``dirty`` outcome, otherwise the task runs and the outcome is ``task``.
+        """
+        if not await self._tree_clean_for(task):
+            return "dirty"
+        await self._run_task(task)
+        return "task"
+
     # ------------------------------------------------------------------ #
     # Failed-task retries                                                 #
     # ------------------------------------------------------------------ #
@@ -354,31 +359,54 @@ class Forgeo:
     # ------------------------------------------------------------------ #
 
     async def _run_task(self, task: Task) -> None:
-        """Execute one task: agent run, then commit/push on the main branch."""
+        """Execute one task: agent run(s), then commit/push on the main branch.
+
+        A silent no-change SUCCESS (exit 0 with an empty tree) is re-run up to
+        ``no_changes_retry_max`` more times in the same cycle; once the retry
+        budget is spent the task is marked ``BLOCKED`` for human review — the
+        only acceptable outcome for a task that ends without code changes.
+        """
         logger.info("Running task %s (%s)", task.id, task.title)
-        result, ok = await self._run_agent(
-            task,
-            instruction=task.instruction,
-            success_message=task.title,
-            blocked_message=f"{task.title} [partial]",
-            command=task.agent_command,
-            timeout_seconds=task.agent_timeout_seconds,
-        )
+        max_retries = self.config.no_changes_retry_max
+        for attempt in range(max_retries + 1):
+            self._last_run_reason = None
+            result, ok = await self._run_agent(
+                task,
+                instruction=task.instruction,
+                success_message=task.title,
+                blocked_message=f"{task.title} [partial]",
+                command=task.agent_command,
+                timeout_seconds=task.agent_timeout_seconds,
+            )
 
-        if result.status is ExecutionStatus.BLOCKED:
-            await self.backlog.set_blocked(task.id, result.reason)
-            return
-        if result.status is ExecutionStatus.ERROR:
-            await self._mark_failed(task, self._failure_reason(result))
-            return
-        if not ok:
-            # SUCCESS whose commit (or no-change) path failed: already marked
-            # FAILED inside _handle_execution_result.
+            if result.status is ExecutionStatus.BLOCKED:
+                await self.backlog.set_blocked(task.id, result.reason)
+                return
+            if result.status is ExecutionStatus.ERROR:
+                await self._mark_failed(task, self._failure_reason(result))
+                return
+            if ok:
+                await self.backlog.update_status(task.id, TaskStatus.COMPLETED)
+                self.config.blocker_file.unlink(missing_ok=True)
+                self._notify_webhook("completed", task, "")
+                logger.info("Task %s completed.", task.id)
+                return
+            # Not ok: either the commit failed (the task is already marked
+            # FAILED inside _handle_execution_result) or the agent exited 0
+            # without producing changes (only the reason distinguishes them).
+            if self._last_run_reason != NO_CHANGES_REASON:
+                return
+            if attempt < max_retries:
+                logger.warning(
+                    "Task %s exited 0 but produced no changes "
+                    "(attempt %d/%d); retrying.",
+                    task.id,
+                    attempt + 1,
+                    max_retries,
+                )
+                continue
+            await self._block_no_changes(task)
             return
-        await self.backlog.update_status(task.id, TaskStatus.COMPLETED)
-        self.config.blocker_file.unlink(missing_ok=True)
-        self._notify_webhook("completed", task, "")
-        logger.info("Task %s completed.", task.id)
 
     async def _run_agent(
         self,
@@ -486,7 +514,10 @@ class Forgeo:
                 # Exited 0 but produced no changes: not a completion. The
                 # engine cannot tell "deliberately did nothing" from "did
                 # nothing", so the agent must opt into no-ops explicitly.
-                await self._fail_no_changes(task)
+                # The caller decides between an immediate re-run
+                # (``no_changes_retry_max``) and a BLOCKED outcome.
+                self._last_run_reason = NO_CHANGES_REASON
+                logger.warning("Task %s: %s.", task.id, NO_CHANGES_REASON)
                 return False
             return ok
 
@@ -496,7 +527,6 @@ class Forgeo:
                     task=task,
                     result=result,
                     instruction=instruction,
-                    is_refactor=is_refactor,
                 )
                 if is_refactor:
                     await self._write_blocker([entry])
@@ -541,22 +571,43 @@ class Forgeo:
         await self.backlog.set_failed(task.id, reason)
         self._notify_webhook("failed", task, "\n".join(reason))
 
-    async def _fail_no_changes(self, task: Task) -> None:
-        """Fail a task whose agent exited 0 without producing any changes.
+    async def _block_no_changes(self, task: Task) -> None:
+        """Mark a task whose agent exited 0 without producing any changes as
+        BLOCKED: the only acceptable outcome for a no-change run is a blocked
+        task awaiting human review.
 
         A no-change SUCCESS is indistinguishable from an agent that simply did
-        nothing, so it is not a valid completion: the task is marked FAILED
-        and the run record surfaces the reason instead of a silent null
-        commit.
+        nothing, so it is not a valid completion. After the retry budget is
+        spent the task is blocked (never FAILED), so the run record surfaces
+        the reason and the human decides whether to reopen, split, or drop the
+        task.
         """
         self._last_run_reason = NO_CHANGES_REASON
         logger.warning(
-            "Task %s exited 0 but produced no changes; marking FAILED.", task.id
+            "Task %s: %s; marking BLOCKED.", task.id, NO_CHANGES_REASON
         )
-        await self._fail(
-            task,
-            ExecutionResult(status=ExecutionStatus.ERROR, error=NO_CHANGES_REASON),
+        blocked = ExecutionResult(
+            status=ExecutionStatus.BLOCKED,
+            output_logs=(
+                self._last_agent_result.output_logs
+                if self._last_agent_result is not None
+                else []
+            ),
+            questions=[NO_CHANGES_REASON],
+            exit_code=(
+                self._last_agent_result.exit_code
+                if self._last_agent_result is not None
+                else None
+            ),
+        )
+        self._last_agent_result = blocked
+        await self.backlog.set_blocked(task.id, [NO_CHANGES_REASON])
+        entry = BlockerEntry(
+            task=task,
+            result=blocked,
+            instruction=task.instruction,
         )
+        self._notify_blocked(entry)
 
     async def _complete_without_changes(
         self, task: Task, *, is_refactor: bool = False

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/models.py

@@ -415,6 +415,11 @@ class ForgeoConfig(BaseModel):
             budget per-task with ``retries_left``.
         failed_retry_wait_cycles: How many cycles a retry-eligible ``FAILED``
             task waits (backoff) before it is moved back to ``OPEN``.
+        no_changes_retry_max: How many times a task whose agent exits ``0``
+            without producing any code changes is re-run immediately, in the
+            same cycle, before the task is marked ``BLOCKED`` for human
+            review. ``0`` (default) = a silent no-change SUCCESS is marked
+            ``BLOCKED`` on the first attempt.
         telegram_bot_token: Telegram bot token for blocked-run
             notifications. Disabled unless ``telegram_chat_id`` is also set.
         telegram_chat_id: Chat ID that receives blocked-run notifications.
@@ -453,6 +458,7 @@ class ForgeoConfig(BaseModel):
     run_output_lines: int = Field(default=DEFAULT_RUN_OUTPUT_LINES, ge=0)
     failed_retry_max: int = Field(default=0, ge=0)
     failed_retry_wait_cycles: int = Field(default=1, ge=1)
+    no_changes_retry_max: int = Field(default=0, ge=0)
     telegram_bot_token: str | None = None
     telegram_chat_id: str | None = None
     notify_webhook_url: str | None = None

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/runs.py

@@ -87,10 +87,36 @@ class RunRecorder:
         warning. ``limit=None`` returns every readable record after ``offset``
         (``offset=0`` starts at the newest).
         """
+        records, _ = self.read_with_total(limit, offset)
+        return records
+
+    def read_with_total(
+        self, limit: int | None = None, offset: int = 0
+    ) -> tuple[list[RunRecord], int]:
+        """Return ``(records, total)`` from a single pass over the history.
+
+        ``records`` are the newest ``limit`` records after skipping ``offset``
+        (same shape as :meth:`read`); ``total`` is the count of every readable
+        record, independent of the pagination. This is the pair the web API
+        needs, computed without reading and parsing the file twice.
+        """
+        records, total = self._read_all()
+        if offset > 0:
+            records = records[offset:]
+        if limit is None:
+            return records, total
+        return records[: max(0, limit)], total
+
+    def _read_all(self) -> tuple[list[RunRecord], int]:
+        """Parse the whole history once; returns records (newest first) and count.
+
+        A missing file yields ``([], 0)``; corrupt lines are skipped with a
+        warning, so they never count as records.
+        """
         try:
             text = self.path.read_text(encoding="utf-8", errors="replace")
         except OSError:
-            return []
+            return [], 0
         records: list[RunRecord] = []
         for line_no, line in enumerate(text.splitlines(), start=1):
             if not line.strip():
@@ -102,11 +128,7 @@ class RunRecorder:
                     "Skipping corrupt run record in %s on line %s", self.path, line_no
                 )
         records.sort(key=lambda record: record.finished_at, reverse=True)
-        if offset > 0:
-            records = records[offset:]
-        if limit is None:
-            return records
-        return records[: max(0, limit)]
+        return records, len(records)
 
     def total(self) -> int:
         """The number of readable records in the run history, or ``0``.
@@ -114,7 +136,8 @@ class RunRecorder:
         A missing, empty, or corrupt-only file counts as zero; corrupt lines
         are skipped with a warning, matching :meth:`read`.
         """
-        return len(self.read())
+        _, total = self._read_all()
+        return total
 
     def read_last(self) -> RunRecord | None:
         """Return the most recent record, or ``None`` when none exists."""

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/setup.py

@@ -57,9 +57,10 @@ DEFAULT_AGENT_PROMPT = (
     "Make the code changes requested below and nothing else. Do NOT run\n"
     "git commit, git push, or git add -A — the forgeo commits your work\n"
     "itself. Verify with the test suite where applicable and, if needed,\n"
-    "update readme, docs and landing page. Read AGENTS.md (and CONTEXT.md\n"
-    "if present) at the start of the session; if your change materially\n"
-    "affects the project overview, keep them updated.\n"
+    "update readme, docs and landing page. Read AGENTS.md at the start of\n"
+    "the session, and CONTEXT.md if present; if your change materially\n"
+    "affects the project overview or conventions, update AGENTS.md and\n"
+    "CONTEXT.md accordingly.\n"
     "$FORGEO_TASK"
 )
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/src/forgeo/web/central/central.js

@@ -1213,6 +1213,7 @@
     { key: "run_output_lines", label: "Run output lines", type: "number", min: 0, step: 1, hint: "How many agent output lines each run record keeps in runs.jsonl (bounded tail, shown in the History tab). 0 = don't persist agent output." },
     { key: "failed_retry_max", label: "Failed retry max", type: "number", min: 0, step: 1, hint: "How many times a FAILED task is retried automatically. 0 = disabled (a FAILED task stays FAILED until a human reopens it). A task can override this with its own retries_left." },
     { key: "failed_retry_wait_cycles", label: "Failed retry wait (cycles)", type: "number", min: 1, step: 1, hint: "How many cycles a FAILED task waits (backoff) before it is retried." },
+    { key: "no_changes_retry_max", label: "No-change retry max", type: "number", min: 0, step: 1, hint: "How many times a task whose agent exits 0 without producing any code changes is re-run immediately, in the same cycle, before it is marked BLOCKED for human review. 0 = block on the first attempt." },
     { key: "agent_sandbox", label: "Agent sandbox", type: "select", options: ["none", "docker"], hint: "none = run directly on the host; docker = run inside a container." },
     { key: "agent_sandbox_image", label: "Sandbox image", type: "text", optional: true, hint: "Container image used when agent_sandbox is docker. Required in that mode." },
     { key: "agent_sandbox_network", label: "Sandbox network", type: "text", hint: "Docker network for the sandboxed agent (--network). Default none = networking disabled." },

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/tests/test_factory.py

@@ -57,10 +57,10 @@ async def test_task_success_is_committed_on_main(git_repo, tmp_path):
     assert "forgeo" not in git(git_repo, "branch")
 
 
-async def test_task_success_without_changes_fails_task(git_repo, tmp_path):
-    """Exit 0 with an empty tree is not a valid completion: it is FAILED, so
-    a silent no-change SUCCESS can never quietly close a task (regression:
-    SELF-033 was closed without any work)."""
+async def test_task_success_without_changes_blocks_task(git_repo, tmp_path):
+    """Exit 0 with an empty tree is not a valid completion: the task is
+    BLOCKED (needs a human), so a silent no-change SUCCESS can never quietly
+    close a task (regression: SELF-033 was closed without any work)."""
     forgeo, agent, backlog = make_forgeo(git_repo, tmp_path)
     await backlog.create_task(make_task())
     agent.result = ExecutionResult(status=ExecutionStatus.SUCCESS)
@@ -69,12 +69,12 @@ async def test_task_success_without_changes_fails_task(git_repo, tmp_path):
 
     assert outcome == "task"
     task = await backlog.get_task("TASK-001")
-    assert task.status is TaskStatus.FAILED
-    assert task.failure_reason == [NO_CHANGES_REASON]
+    assert task.status is TaskStatus.BLOCKED
+    assert task.blocker_reason == [NO_CHANGES_REASON]
     assert git(git_repo, "rev-list", "--count", "HEAD") == "1"
 
 
-async def test_no_changes_failure_logs_warning(git_repo, tmp_path, caplog):
+async def test_no_changes_blocks_logs_warning(git_repo, tmp_path, caplog):
     """The no-change SUCCESS case is surfaced as a warning, never silent."""
     forgeo, agent, backlog = make_forgeo(git_repo, tmp_path)
     await backlog.create_task(make_task())
@@ -87,6 +87,52 @@ async def test_no_changes_failure_logs_warning(git_repo, tmp_path, caplog):
     assert any("produced no changes" in r.message for r in caplog.records)
 
 
+async def test_task_no_changes_is_retried_and_can_succeed(git_repo, tmp_path):
+    """With no_changes_retry_max, a silent no-change SUCCESS re-runs the agent
+    in the same cycle; a later run that produces changes completes the task."""
+    forgeo, agent, backlog = make_forgeo(git_repo, tmp_path, no_changes_retry_max=2)
+    await backlog.create_task(make_task())
+    agent.result = ExecutionResult(status=ExecutionStatus.SUCCESS)
+
+    def produce_changes() -> None:
+        (git_repo / "app.py").write_text("def answer():\n    return 7\n", encoding="utf-8")
+
+    calls = 0
+
+    def effect() -> None:
+        nonlocal calls
+        calls += 1
+        if calls >= 3:
+            produce_changes()
+
+    agent.effect = effect
+
+    outcome = await forgeo.run_cycle()
+
+    assert outcome == "task"
+    task = await backlog.get_task("TASK-001")
+    assert task.status is TaskStatus.COMPLETED
+    assert calls == 3
+    assert git(git_repo, "log", "-1", "--format=%s") == "Do the thing"
+
+
+async def test_task_no_changes_retries_exhausted_blocks_task(git_repo, tmp_path):
+    """Once the retry budget is spent, a silent no-change SUCCESS is marked
+    BLOCKED — never FAILED — so a human reviews the task."""
+    forgeo, agent, backlog = make_forgeo(git_repo, tmp_path, no_changes_retry_max=2)
+    await backlog.create_task(make_task())
+    agent.result = ExecutionResult(status=ExecutionStatus.SUCCESS)
+
+    outcome = await forgeo.run_cycle()
+
+    assert outcome == "task"
+    task = await backlog.get_task("TASK-001")
+    assert task.status is TaskStatus.BLOCKED
+    assert task.blocker_reason == [NO_CHANGES_REASON]
+    assert len(agent.calls) == 3
+    assert git(git_repo, "rev-list", "--count", "HEAD") == "1"
+
+
 async def test_task_explicit_no_changes_completes_task(git_repo, tmp_path):
     """Exit no_changes_exit_code is the explicit no-op contract: the task is
     COMPLETED without a commit, and the tree stays untouched."""
@@ -798,6 +844,10 @@ async def test_task_context_refreshed_each_run(git_repo, tmp_path):
     context_file.write_text("Version one.\n", encoding="utf-8")
     forgeo, agent, backlog = make_forgeo(git_repo, tmp_path, task_context=context_file)
     await backlog.create_task(make_task())
+    agent.result = ExecutionResult(status=ExecutionStatus.SUCCESS)
+    agent.effect = lambda: (git_repo / "app.py").write_text(
+        "def answer():\n    return 7\n", encoding="utf-8"
+    )
     await forgeo.run_cycle()
     context_file.write_text("Version two.\n", encoding="utf-8")
     await backlog.create_task(make_task(id="TASK-002", description="Build it again."))

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/tests/test_install.py

@@ -23,7 +23,7 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[1]
 INSTALL_SH = REPO_ROOT / "install.sh"
 PYPI_PACKAGE = "forgeo-cli"
-VERSION = "0.7.0"
+VERSION = "0.7.2"
 SH = shutil.which("sh")
 assert SH, "sh must be available to run install.sh"
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/tests/test_models.py

@@ -142,6 +142,7 @@ def test_config_defaults():
     assert config.notify_webhook_events == ["blocked"]
     assert config.failed_retry_max == 0
     assert config.failed_retry_wait_cycles == 1
+    assert config.no_changes_retry_max == 0
 
 
 def test_config_rejects_negative_retry_settings():
@@ -149,12 +150,16 @@ def test_config_rejects_negative_retry_settings():
         ForgeoConfig(agent_command="x", failed_retry_max=-1)
     with pytest.raises(ValidationError):
         ForgeoConfig(agent_command="x", failed_retry_wait_cycles=0)
+    with pytest.raises(ValidationError):
+        ForgeoConfig(agent_command="x", no_changes_retry_max=-1)
 
 
 def test_config_accepts_retry_settings():
     config = ForgeoConfig(agent_command="x", failed_retry_max=3, failed_retry_wait_cycles=2)
     assert config.failed_retry_max == 3
     assert config.failed_retry_wait_cycles == 2
+    config = ForgeoConfig(agent_command="x", no_changes_retry_max=5)
+    assert config.no_changes_retry_max == 5
 
 
 def test_config_rejects_unknown_webhook_events():

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/tests/test_runs.py

@@ -52,8 +52,8 @@ async def test_task_success_appends_run_record(git_repo, tmp_path):
 
 
 async def test_task_success_without_changes_has_reason(git_repo, tmp_path):
-    """A no-change SUCCESS is surfaced on the run record: outcome stays
-    SUCCESS (the agent did exit 0) but with an explicit reason, never a
+    """A no-change SUCCESS is surfaced on the run record: the run ends BLOCKED
+    (the only acceptable no-change outcome) with an explicit reason, never a
     silent null commit_sha."""
     forgeo, agent, backlog = make_forgeo(git_repo, tmp_path)
     await backlog.create_task(make_task())
@@ -62,10 +62,10 @@ async def test_task_success_without_changes_has_reason(git_repo, tmp_path):
     assert await forgeo.run_cycle() == "task"
 
     record = read_lines(runs_path(forgeo.config))[0]
-    assert record["outcome"] == "SUCCESS"
+    assert record["outcome"] == "BLOCKED"
     assert record["commit_sha"] is None
     assert record["reason"] == NO_CHANGES_REASON
-    assert (await backlog.get_task("TASK-001")).status is TaskStatus.FAILED
+    assert (await backlog.get_task("TASK-001")).status is TaskStatus.BLOCKED
 
 
 async def test_explicit_no_changes_record_has_reason(git_repo, tmp_path):
@@ -386,7 +386,7 @@ async def test_corrupt_runs_never_break_a_cycle(git_repo, tmp_path, caplog):
 
     records = RunRecorder(runs).read()
     assert len(records) == 1
-    assert records[0].outcome is RunOutcome.SUCCESS
+    assert records[0].outcome is RunOutcome.BLOCKED
     assert records[0].task_id == "TASK-001"
 
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.2}/tests/test_web.py

@@ -1524,6 +1524,7 @@ def test_retry_config_fields_editable_in_config_tab(web_env):
     assert status == 200
     assert "failed_retry_max" in body
     assert "failed_retry_wait_cycles" in body
+    assert "no_changes_retry_max" in body
 
 
 def test_tasks_endpoint_surfaces_run_at(registry, central_server):