forgeo-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/.github/workflows/ci.yml

@@ -35,7 +35,10 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-latest
+          # Linux is built on ubuntu-22.04 (glibc 2.35) so the binary also
+          # runs on older distros (Homebrew-on-Linux, Ubuntu 22.04+): a build
+          # on ubuntu-latest (24.04) would require glibc >= 2.38.
+          - os: ubuntu-22.04
             asset: forgeo-linux-amd64
             binary: dist/forgeo
           - os: macos-15-intel
@@ -90,6 +93,24 @@ jobs:
         with:
           path: binaries
           merge-multiple: true
+      - name: Extract release notes from CHANGELOG.md
+        id: notes
+        run: |
+          python - "${{ github.ref_name }}" <<'EOF'
+          import re
+          import sys
+          import pathlib
+
+          version = sys.argv[1].removeprefix("v")
+          text = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+          pattern = re.compile(
+              rf"^## \[{re.escape(version)}\] .*?\n(.*?)(?=^## \[|\Z)",
+              re.MULTILINE | re.DOTALL,
+          )
+          match = pattern.search(text)
+          notes = match.group(1).strip() if match else ""
+          pathlib.Path("release-body.md").write_text(notes, encoding="utf-8")
+          EOF
       - name: Publish GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -97,6 +118,44 @@ jobs:
             dist/*.whl
             dist/*.tar.gz
             binaries/*
+          body_path: release-body.md
+
+  publish-homebrew:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Download binary artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: binaries
+          merge-multiple: true
+      - name: Render the Homebrew formula
+        run: python scripts/render_homebrew_formula.py "${{ github.ref_name }}" binaries > /tmp/forgeo.rb
+      - name: Publish the formula to the homebrew-forgeo tap
+        env:
+          TAP_REPO_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          set -eu
+          if [ -z "$TAP_REPO_TOKEN" ]; then
+            echo "::error::HOMEBREW_TAP_TOKEN secret is not set. Create a PAT with write access to lucaGazzola/homebrew-forgeo and store it as HOMEBREW_TAP_TOKEN; without it the Homebrew tap is not updated for this release."
+            exit 1
+          fi
+          git clone "https://x-access-token:${TAP_REPO_TOKEN}@github.com/lucaGazzola/homebrew-forgeo.git" tap
+          cp /tmp/forgeo.rb tap/Formula/forgeo.rb
+          git -C tap config user.name "Forgeo release bot"
+          git -C tap config user.email "forgeo-releases@users.noreply.github.com"
+          if git -C tap diff --quiet; then
+            echo "Formula unchanged; nothing to push."
+          else
+            git -C tap add Formula/forgeo.rb
+            git -C tap commit -m "forgeo ${{ github.ref_name }}"
+            git -C tap push origin main
+          fi
 
   publish-pypi:
     if: startsWith(github.ref, 'refs/tags/v')

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/.gitignore

@@ -27,6 +27,7 @@ build/
 dist/
 
 # AI assistant context
+AGENTS.md
 CONTEXT.md
 
 # Local deploy script (server-specific paths)

forgeo_cli-0.6.0/CHANGELOG.md

@@ -0,0 +1,293 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.6.0] - 2026-08-14
+
+### Added
+
+- The backlog can now live in another application instead of a file: set
+  `backlog:` to an `http(s)` URL and Forgeo reads the whole document with
+  `GET` on every read and writes it back with `POST` on every change, using
+  the same JSON shape as `backlog.json`. The endpoint replaces its task list
+  with the body it receives. A request that fails (network error, 5xx,
+  malformed body) fails the cycle and is retried on the next interval — it is
+  never read as an empty backlog, which would start a refactoring pass and let
+  the next `POST` overwrite the remote task list with nothing.
+
+- `backlog_auth`: OAuth2 client-credentials access for a backlog URL behind an
+  identity provider such as Keycloak. Forgeo obtains an access token for a
+  confidential client (a service account, not a human login) and sends it as a
+  bearer on every backlog request; tokens are cached in memory, renewed before
+  they expire, and refreshed once with a retry when the endpoint answers 401 or
+  403. The client secret is never a config value: `client_secret_env` names the
+  environment variable holding it, so it stays out of `forgeo.yaml`.
+
+- `state_dir`: where Forgeo's own runtime files go (`backlog.lock`,
+  `backlog.run`, `backlog.state.json`, `backlog.update.json`, `runs.jsonl`).
+  It only matters with a backlog URL, where there is no backlog file for them
+  to sit beside; it then defaults to the directory holding `forgeo.yaml`. With
+  a backlog file those paths are unchanged.
+
+- `forgeo validate` now checks a backlog URL by fetching it once (a plain
+  `GET`, with `backlog_auth` credentials when configured), so an unreachable
+  endpoint or a rejected token is reported by the dry run instead of by the
+  first cycle. A file backlog is still read from disk, and nothing is written
+  either way.
+
+## [0.5.0] - 2026-08-14
+
+### Added
+
+- `forgeo validate` (and the pre-flight check before a detached
+  `forgeo start`) distinguishes a repository with no commits yet: a clean
+  tree is now a warning — the first cycle creates the initial commit — while
+  a non-clean tree is a problem that names the fix
+  (`git add -A && git commit -m "Initial commit"`), since every file is
+  untracked and every cycle would otherwise refuse as dirty. Previously
+  "no commits" was always a hard problem with a misleading message.
+
+- `forgeo start` now starts the daemon **detached in the background and
+  exits**, like `forgeo restart` and the web console's start button already
+  did; the daemon is managed with `forgeo stop`/`forgeo restart`/`forgeo
+  status`. `forgeo start -f` (`--foreground`) keeps the historical
+  foreground behavior. A detached start refuses while the per-forgeo lock is
+  held and runs the same read-only checks as `forgeo validate` first, so a
+  broken config fails fast instead of leaving a silently dead daemon.
+  `--interval-minutes` is forwarded to the detached daemon.
+
+- The daemon reloads `forgeo.yaml` on the next cycle boundary when the file
+  changes (or on `SIGHUP`): a valid change is revalidated, logged, and used
+  from the next cycle; an invalid change is logged and the last valid config
+  stays in use. The web console's config save reflects this
+  (`restart_required: false`). Path changes (`repo`, `backlog`,
+  `blocker_file`, `log_file`) stay pinned to the daemon's startup values and
+  still need `forgeo restart`, so the daemon's lock files are never detached
+  from the config.
+
+- Optional bearer-token auth for the central web dashboard (`forgeo web`):
+  `forgeo web --token` (or a `token` key in `~/.config/forgeo/web.toml`)
+  requires `Authorization: Bearer <token>` on every `/api/*` route and
+  answers `401` otherwise. `forgeo web --token` with no value generates a
+  token, prints it once on startup, and saves it (mode `0600`); a generated
+  token is only ever printed once. Static assets and the new token prompt
+  page (`/central/login.html`) stay reachable without a token, and a
+  `?token=...` URL signs the browser in automatically. With no flag and no
+  token file the dashboard keeps its historical open-by-default behavior.
+
+- `forgeo validate` — a read-only dry run that checks whether a forgeo is
+  ready to run before starting it: the config schema, the repository (exists,
+  is a git repo, `git` on PATH), the branch and remote resolution, the
+  backlog parsing, a non-blank agent command, and the run lock state. It
+  reports every problem at once, never invokes the agent, and makes no writes
+  (no lock, no backlog changes). Exit code `0` when healthy, `1` with a
+  summary of problems otherwise. Supports `--config` and `--name`.
+
+- `run_history_keep` config key: `runs.jsonl` is trimmed to that many records
+  on append (default `2000`), so a busy Forgeo's run history never grows
+  forever. Trimming is atomic (temp file + rename) and a failed trim is
+  logged and skipped, never fatal to the cycle; `run_history_keep: 0`
+  disables retention entirely (the previous grow-forever behavior).
+
+- Persisted agent output per run: each `RunRecord` now stores a bounded tail
+  of the agent's stdout/stderr (last `run_output_lines` lines, default `200`),
+  so failed and blocked runs keep the full tail of what the agent said. The
+  web console's **History** tab shows it in a read-only, monospace,
+  collapsible view; `run_output_lines: 0` disables persistence, and records
+  written before the field existed render as empty.
+
+- Backlog snapshots: before every agent run (and on daemon startup) Forgeo
+  copies the backlog to a rotating snapshot (`backlog.json.bak`,
+  `backlog.json.bak.1`, ... keeping the last 2 by default), and a read that
+  finds the backlog corrupt restores the newest valid snapshot in place —
+  with the corrupt file still preserved — instead of falling back to an
+  empty store. A missing backlog is a no-op.
+
+- Task dependencies are now enforced when picking the next task: Forgeo picks
+  the oldest `OPEN` task whose `dependencies` are all `COMPLETED` instead of
+  the plain oldest `OPEN` task, so a task never runs before the work it
+  depends on. Unsatisfied dependencies (including ids that don't exist in the
+  backlog) are surfaced on `forgeo status` (`waiting on:` line) and in the web
+  console's task detail modal (*Waiting on dependencies* banner); the
+  `GET /api/instances/<name>/tasks*` responses annotate each task with an
+  `unsatisfied_dependencies` field.
+
+- Homebrew install support: `brew install lucaGazzola/forgeo/forgeo`
+  installs the prebuilt binary on macOS (arm64/Intel) and Linux (Intel). The
+  `publish-homebrew` CI job re-renders the tap formula (sha256 + version)
+  from `scripts/render_homebrew_formula.py` on every release; it needs the
+  `HOMEBREW_TAP_TOKEN` repository secret (PAT with write access to
+  `lucaGazzola/homebrew-forgeo`). The update notification now also names
+  `brew upgrade lucaGazzola/forgeo/forgeo`.
+
+- Update notification: when `forgeo start` or `forgeo once` begins a cycle,
+  Forgeo checks PyPI at most once a day and, if a newer `forgeo-cli` release
+  exists, prints/logs a short notice with the upgrade command. The check is
+  best-effort (short timeout, failures logged and skipped), never modifies
+  the install, and can be disabled with `FORGEO_UPDATE_CHECK=0`.
+
+- Automatic retries for `FAILED` tasks: `failed_retry_max` config key (default
+  `0`, unchanged behavior) plus `failed_retry_wait_cycles` (default `1`) let a
+  transiently failed task move back to `OPEN` after a backoff and be run
+  again. A task that exhausts its budget stays `FAILED` with its original
+  `failure_reason`; a per-task `retries_left` field overrides the budget for
+  one task. `BLOCKED` tasks are never auto-retried. The retry count is
+  recorded in `runs.jsonl` (the run record that succeeds carries it), shown
+  in the web console (task cards/modal and a History-tab **retry** column),
+  and exposed by the tasks/runs API.
+
+### Fixed
+
+- The Linux prebuilt binary is now built on Ubuntu 22.04 (glibc 2.35) instead
+  of 24.04 (glibc 2.38), so it runs on older distros (e.g. Ubuntu 22.04,
+  Debian 12, Homebrew-on-Linux). The 0.4.0 `forgeo-linux-amd64` release
+  asset was rebuilt and re-uploaded with the same version number.
+
+## [0.4.0] - 2026-08-10
+
+### Added
+
+- Delete OPEN tasks from the web console: a Delete button (with
+  confirmation) in the task detail modal, backed by `DELETE
+  /api/instances/<name>/tasks/<id>` and `JSONBacklog.delete_task`.
+- Resolve BLOCKED tasks from the web console: the task modal shows the
+  blocker reason and can reopen the task (back to `OPEN`) via `POST
+  /api/instances/<name>/tasks/<id>/reopen`.
+- The web console stays usable with many tasks: non-OPEN columns collapse
+  behind count badges with an expand toggle, so a long backlog no longer
+  renders every task as a tall card up front.
+- The failure/block reason is shown prominently in the task detail modal.
+- Config editing from the web console: `PUT /api/instances/<name>/config`
+  validates and persists `forgeo.yaml` changes, and a new Config tab in the
+  instance page edits the fields in a form (with a restart hint).
+- Daemon control from the web console: start, stop, and restart an
+  instance's daemon from the top bar via `POST
+  /api/instances/<name>/{start,stop,restart}`.
+- `forgeo init` now asks only for the bare agent command and appends the
+  task prompt automatically.
+
+### Changed
+
+- Commit messages no longer carry the `forgeo: ` prefix.
+- The instance is registered before the run lock is taken, so a `--name`
+  lookup never fails while starting.
+- README revised for clarity and formatting.
+
+## [0.3.0] - 2026-08-07
+
+### Added
+
+- `forgeo web [--host HOST] [--port PORT]` — a standalone central dashboard
+  (default `0.0.0.0:8790`, foreground like `forgeo start`) that aggregates
+  every registered instance. It reads each instance's data straight from its
+  files (`backlog.json`, `runs.jsonl`, `forgeo.log`, `BLOCKER.md`), so it
+  works whether or not that instance's daemon is running. Home page at `/`,
+  per-instance pages at `/instances/<name>/` (kanban backlog plus logs,
+  runs, blocker and config tabs), and a per-instance API under
+  `/api/instances/<name>/`.
+- Shared web-server helpers (`forgeo.web_common`) used by the central
+  dashboard.
+- Task editing in the web console: the task detail modal gained an **Edit**
+  mode (Save/Cancel), backed by a new `PATCH
+  /api/instances/<name>/tasks/<id>` endpoint and `JSONBacklog.update_task`.
+- PyPI publishing: tagging a release now also publishes the `forgeo-cli`
+  wheel and sdist to PyPI via trusted publishing.
+
+### Changed
+
+- **The embedded per-daemon web server is gone.** `forgeo start` no longer
+  binds any port (`web_host`/`web_port` config keys are removed). The daemon
+  instead writes its live state (pid, started at, last outcome, next run) to
+  `daemon.state.json` next to the backlog after every cycle.
+- The central dashboard (`forgeo web`) is now the **only** web interface:
+  it reads the daemon state files for accurate status, and it gained the
+  instance backlog's write endpoints, `POST
+  /api/instances/<name>/tasks` (with the web form on each instance page) and
+  `PATCH /api/instances/<name>/tasks/<id>`, so no feature was lost.
+- `forgeo.web_common` docstring/API updated; `forgeo.server` module
+  removed.
+
+## [0.2.1] - 2026-08-05
+
+### Added
+
+- `web_host` config option: the web dashboard/API bind address. Default
+  `127.0.0.1` (unchanged behavior); set `0.0.0.0` to reach it from other
+  hosts on the local network.
+- `install.sh` now prefers a prebuilt standalone binary downloaded from the
+  matching GitHub Release for the host OS/arch — **no Python required**.
+  The pipx/pip fallback remains, used only when no prebuilt binary matches
+  the platform and a Python >= 3.11 is available.
+- Tag-triggered CI builds single-file executables with PyInstaller on
+  Linux (amd64), macOS (amd64/arm64), and Windows (amd64) and attaches them
+  to the GitHub Release (`forgeo.spec`).
+- Installer tests cover the binary-download path and the pipx/pip fallback
+  with stubs (no network).
+
+## [0.2.0] - 2026-08-04
+
+### Added
+
+- `CHANGELOG.md` in Keep a Changelog format, with the `0.1.0` history
+  backfilled.
+- Tag-triggered CI job that builds the wheel and sdist and attaches them to a
+  GitHub Release.
+- Release steps documented in `CONTRIBUTING.md`.
+- Web console frontend in `src/forgeo/web/`: a self-contained
+  HTML/CSS/JS dashboard (no framework, no build step, no external assets)
+  served at `/` showing the backlog grouped by status and daemon status,
+  auto-refreshing every 30 seconds.
+- `install.sh` is now hosted on the project's own server and served from
+  <https://forgeo.org/install.sh>; README and docs use it in the one-liner.
+
+## [0.1.0] - 2026-08-03
+
+Initial release of the scheduled, agent-driven software forgeo.
+
+### Added
+
+- `forgeo start` persistent daemon: every `interval_minutes` it picks the
+  oldest `OPEN` task, runs it through the configured agent command, and commits
+  and pushes the result directly on `main`.
+- Refactoring mode: when the backlog is empty, runs the agent with the
+  configured `refactor_prompt`.
+- Blocker flow: an agent exiting with `blocked_exit_code` commits partial work,
+  writes `BLOCKER.md`, and pauses Forgeo until the task is reopened.
+- Guided first-time setup: `forgeo init` wizard.
+- `forgeo once` command to run a single cycle and exit.
+- `forgeo status`, `forgeo stop`, and `forgeo restart` commands.
+- `--auto` flag for the agent command for unattended runs.
+- Local web dashboard and HTTP API served by the daemon.
+- Durable run history recorded to `runs.jsonl` and exposed through the API.
+- Telegram notification when a task is marked `BLOCKED`.
+- Curl-to-bash one-liner installer (`install.sh`), pipx-first.
+- MkDocs documentation website, published at <https://forgeo.org/>.
+- GitHub Actions CI running `pytest`, `ruff`, and `mypy` on Python 3.11-3.13.
+- Optional Docker sandbox for agent execution.
+- Per-task `agent_command` override for cheap/expensive model routing.
+- Project renamed to Forgeo, with MIT `LICENSE` and `CONTRIBUTING.md`.
+
+### Changed
+
+- Project slimmed down to a single-purpose scheduled worker; the interactive
+  backlog generator utility was removed.
+- Duplicated commit/blocker handling unified between task and refactor runs.
+- Agent stdout/stderr streamed into run logs instead of buffered.
+- Corrupt backlog files preserved instead of silently discarded.
+- Git command timeout made configurable; agent timeout made optional with
+  overlapping-run skipping.
+- Dogfooding docs removed; local configs kept out of the repository.
+
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...HEAD
+[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
+[0.4.0]: https://github.com/lucaGazzola/forgeo/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.3.0
+[0.2.1]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/lucaGazzola/forgeo/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/lucaGazzola/forgeo/releases/tag/v0.1.0

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/CONTRIBUTING.md

@@ -80,15 +80,20 @@ Human contributions use the normal GitHub flow:
 
 Releases are cut from `main` and published as GitHub Releases. Tagging the
 repo triggers CI, which builds the wheel, sdist, **and prebuilt standalone
-binaries** and attaches them to the release — there is no PyPI publishing yet,
-and `install.sh` downloads the matching prebuilt binary from the release
-(`pipx`/`pip` fallback only when no binary matches the platform).
+binaries** and attaches them to the release; `install.sh` downloads the
+matching prebuilt binary from the release (`pipx`/`pip` fallback only when no
+binary matches the platform), and the `publish-homebrew` job re-renders and
+pushes the formula of the `lucaGazzola/homebrew-forgeo` tap.
 
 > Patch and minor releases **must** include the built binaries, otherwise the
 > `install.sh` binary path (the default, no-Python install) breaks. The CI
 > `build-binaries` job builds them automatically on any `v*` tag, but make
 > sure the release actually carries them — the `forgeo-<os>-<arch>` assets
 > listed below are what the installer downloads.
+>
+> The `publish-homebrew` job needs the `HOMEBREW_TAP_TOKEN` repository secret
+> (a PAT with write access to `lucaGazzola/homebrew-forgeo`); a release cut
+> without it fails that job and leaves the tap outdated until re-run.
 
 1. Confirm the [quality gates](#quality-gates) are green on `main`.
 2. Bump the version in `pyproject.toml` (`version = "x.y.z"`) and in
@@ -114,6 +119,8 @@ and `install.sh` downloads the matching prebuilt binary from the release
    `forgeo-linux-amd64`, `forgeo-darwin-amd64`, `forgeo-darwin-arm64`,
    `forgeo-windows-amd64.exe` binaries) are listed under
    <https://github.com/lucaGazzola/forgeo/releases>.
+8. Confirm the `publish-homebrew` job updated the tap: `brew update` and
+   `brew upgrade lucaGazzola/forgeo/forgeo` should now install the new version.
 
 ## License
 

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -71,7 +71,10 @@ a backlog, and it decides what to work on next, runs your
 agent on it, and commits the result. Progress, pending decisions, and history
 are tracked in plain files you can inspect at any time, plus a web dashboard.
 Forgeo only interrupts you when a decision is genuinely yours to
-make, everything else happens autonomously.
+make, everything else happens autonomously. Transient failures (a network
+blip, a flaky test) are retried automatically when the retry policy is
+enabled, and only a task that keeps failing or genuinely needs a human
+decision ever reaches you.
 
 All you need is basic comfort with a terminal, a git repository, and any coding
 agent CLI.
@@ -81,29 +84,41 @@ agent CLI.
 The full walkthrough is in [Getting started](docs/getting-started.md).
 
 ```bash
-# 1. Install
-curl -fsSL https://forgeo.org/install.sh | bash
+# 1. Install (any one of these)
+
+# Homebrew (macOS / Linux)
+brew install lucaGazzola/forgeo/forgeo
 
-or
+# or: the one-liner (prebuilt binary, no Python required)
+curl -fsSL https://forgeo.org/install.sh | bash
 
+# or: pipx
 pipx install forgeo-cli
 
 # 2. Create your Forgeo (guided wizard, run from your project root)
 forgeo init
 
-# 3. Start Forgeo
-forgeo start   # run forever: every interval_minutes, implement the oldest OPEN task
+# 3. Start Forgeo (detached in the background; exits immediately)
+forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
+forgeo stop    # stop the daemon again
 ```
 
 `forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
 and logs. Fill the backlog with plain JSON tasks (see
 [Backlog format](docs/backlog.md)) or add them from the web console while
-it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>), or keep it always-on with `forgeo web -d` (stop it with `forgeo web stop`, check it with `forgeo web status`):
 
 ![Forgeo web console](docs/img/console.png)
 
+By default the dashboard is open to anyone who can reach the port. On a
+shared host, protect it with bearer-token auth: `forgeo web --token`
+generates a token (printed once, saved to `~/.config/forgeo/web.toml`) and
+requires `Authorization: Bearer <token>` on every `/api/*` route — see
+[Web console & HTTP API](docs/web-console-api.md).
+
 One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo stop`, `forgeo restart`, every command is in the
+`forgeo validate` (read-only dry run before starting), `forgeo stop`,
+`forgeo restart`, every command is in the
 [CLI reference](docs/cli-reference.md).
 
 You can run several factories at once, one per repository, each config is
@@ -125,7 +140,13 @@ central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending.
+`BLOCKER.md` whenever a decision is pending. The backlog can also live in
+another application behind an `http(s)` URL — Forgeo reads the whole task
+document with `GET` and writes it back with `POST`, with optional OAuth2
+client-credentials auth (see [Backlog format](docs/backlog.md)). A *file*
+backlog is snapshotted (rotating `backlog.json.bak` files) before every
+agent run and on daemon startup, and restored automatically if it is ever
+found corrupt — a bad write never loses your tasks.
 
 ## Develop
 

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/README.md

@@ -17,7 +17,10 @@ a backlog, and it decides what to work on next, runs your
 agent on it, and commits the result. Progress, pending decisions, and history
 are tracked in plain files you can inspect at any time, plus a web dashboard.
 Forgeo only interrupts you when a decision is genuinely yours to
-make, everything else happens autonomously.
+make, everything else happens autonomously. Transient failures (a network
+blip, a flaky test) are retried automatically when the retry policy is
+enabled, and only a task that keeps failing or genuinely needs a human
+decision ever reaches you.
 
 All you need is basic comfort with a terminal, a git repository, and any coding
 agent CLI.
@@ -27,29 +30,41 @@ agent CLI.
 The full walkthrough is in [Getting started](docs/getting-started.md).
 
 ```bash
-# 1. Install
-curl -fsSL https://forgeo.org/install.sh | bash
+# 1. Install (any one of these)
+
+# Homebrew (macOS / Linux)
+brew install lucaGazzola/forgeo/forgeo
 
-or
+# or: the one-liner (prebuilt binary, no Python required)
+curl -fsSL https://forgeo.org/install.sh | bash
 
+# or: pipx
 pipx install forgeo-cli
 
 # 2. Create your Forgeo (guided wizard, run from your project root)
 forgeo init
 
-# 3. Start Forgeo
-forgeo start   # run forever: every interval_minutes, implement the oldest OPEN task
+# 3. Start Forgeo (detached in the background; exits immediately)
+forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
+forgeo stop    # stop the daemon again
 ```
 
 `forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
 and logs. Fill the backlog with plain JSON tasks (see
 [Backlog format](docs/backlog.md)) or add them from the web console while
-it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>), or keep it always-on with `forgeo web -d` (stop it with `forgeo web stop`, check it with `forgeo web status`):
 
 ![Forgeo web console](docs/img/console.png)
 
+By default the dashboard is open to anyone who can reach the port. On a
+shared host, protect it with bearer-token auth: `forgeo web --token`
+generates a token (printed once, saved to `~/.config/forgeo/web.toml`) and
+requires `Authorization: Bearer <token>` on every `/api/*` route — see
+[Web console & HTTP API](docs/web-console-api.md).
+
 One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo stop`, `forgeo restart`, every command is in the
+`forgeo validate` (read-only dry run before starting), `forgeo stop`,
+`forgeo restart`, every command is in the
 [CLI reference](docs/cli-reference.md).
 
 You can run several factories at once, one per repository, each config is
@@ -71,7 +86,13 @@ central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending.
+`BLOCKER.md` whenever a decision is pending. The backlog can also live in
+another application behind an `http(s)` URL — Forgeo reads the whole task
+document with `GET` and writes it back with `POST`, with optional OAuth2
+client-credentials auth (see [Backlog format](docs/backlog.md)). A *file*
+backlog is snapshotted (rotating `backlog.json.bak` files) before every
+agent run and on daemon startup, and restored automatically if it is ever
+found corrupt — a bad write never loses your tasks.
 
 ## Develop
 

{forgeo_cli-0.4.0 → forgeo_cli-0.6.0}/docs/agent-contract.md

@@ -39,11 +39,37 @@ The exit code decides the outcome of the run:
 | Exit code | Outcome | What happens |
 | --- | --- | --- |
 | `0` | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
-| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> (#<id>) [partial]`, the agent's reason is persisted on the task (`blocker_reason`), an optional Telegram notification is sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
+| `no_changes_exit_code` (default `3`) | **SUCCESS, no changes** | The agent explicitly reports the task needs **no code change**: the task is marked `COMPLETED` without a commit (and the run record notes why). Only accepted when the working tree is clean. |
+| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> [partial]`, the agent's reason is persisted on the task (`blocker_reason`), optional Telegram and/or webhook notifications are sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
 | anything else | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
 
 The blocked exit code is configurable via `blocked_exit_code` in
-[forgeo.yaml](configuration.md).
+[forgeo.yaml](configuration.md), and the no-change exit code via
+`no_changes_exit_code`.
+
+A `FAILED` task stays `FAILED` until a human reopens it — unless the retry
+policy is enabled (`failed_retry_max`, see [Configuration](configuration.md)),
+in which case Forgeo moves the task back to `OPEN` after
+`failed_retry_wait_cycles` cycles and runs it again, incrementing its retry
+count. `BLOCKED` is never retried automatically: it always waits for a human.
+
+## The no-change contract
+
+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"*);
+- 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
+  instead.
+
+Refactoring passes are the exception: when the backlog is empty, a refactor
+that finds nothing to improve is a normal, successful run (the default
+refactor prompt already says "if nothing needs refactoring, make no
+changes").
 
 ## Timeouts
 
@@ -84,6 +110,8 @@ that, based on the exit code. The working contract is:
 - make your changes in the repository;
 - **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);
 - exit `blocked_exit_code` to have partial work preserved and a blocker
   written;
 - exit anything else to have your changes discarded.