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

{forgeo_cli-0.4.0 → forgeo_cli-0.5.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.5.0}/.gitignore

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

{forgeo_cli-0.4.0 → forgeo_cli-0.5.0}/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -142,7 +250,8 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.5.0...HEAD
+[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

{forgeo_cli-0.4.0 → forgeo_cli-0.5.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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.4.0
+Version: 0.5.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,10 @@ 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 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.5.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,10 @@ 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 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.5.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.