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

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

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -250,7 +283,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.5.0...HEAD
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.5.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
@@ -140,10 +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. 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.
+`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.5.0 → forgeo_cli-0.6.0}/README.md

@@ -86,10 +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. 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.
+`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.5.0 → forgeo_cli-0.6.0}/docs/backlog.md

@@ -1,10 +1,12 @@
 # Backlog format
 
-The backlog is a **plain JSON file** you edit by hand. It lives wherever
-`backlog:` points in [forgeo.yaml](configuration.md) — by default
-`backlog.json` at the project root, and `.forgeo/backlog.json` when generated
-by `forgeo init`. Keep it outside the repository if you can so the agent never
-touches it.
+The backlog is a **plain JSON document**. By default it is a file you edit by
+hand, living wherever `backlog:` points in [forgeo.yaml](configuration.md) —
+`backlog.json` at the project root, or `.forgeo/backlog.json` when generated by
+`forgeo init`. Keep it outside the repository if you can so the agent never
+touches it. It can also be [served over HTTP](#a-backlog-over-http) by another
+application, in which case the document below is exactly what that endpoint
+exchanges with Forgeo.
 
 ```json
 {
@@ -258,8 +260,9 @@ The backlog is the single source of truth, so it is guarded on both ends:
 
 - a missing file is treated as an empty backlog (and is created on first
   write);
-- a corrupt file is renamed to `backlog.json.corrupt-<timestamp>` and the
-  forgeo starts from an empty store — nothing is silently discarded;
+- a corrupt file is renamed to `backlog.json.corrupt-<timestamp>` and replaced
+  by the newest valid snapshot, or by an empty store when there is none —
+  nothing is silently discarded;
 - an unparsable task row is kept as a `FAILED` task rather than killing the
   whole store;
 - before every agent run (and on daemon startup) the current backlog is
@@ -282,3 +285,66 @@ in place automatically and the corrupt file is preserved under
 favor of an older valid one; when no snapshot exists, the forgeo falls back to
 an empty store exactly as before. A missing backlog is a no-op — no snapshot
 is created for a file that does not exist.
+
+This whole section is about a backlog *file*. A backlog URL is owned by the
+application serving it, which keeps its own history, so Forgeo neither
+snapshots nor repairs it — see below.
+
+## A backlog over HTTP
+
+Setting `backlog:` to an `http(s)` URL moves the backlog into another
+application — typically one that already displays and edits work items. Forgeo
+then treats that endpoint exactly like the file:
+
+| When | Request |
+| --- | --- |
+| Every read | `GET <url>` returns the whole document |
+| Every write | `POST <url>` sends the whole document back |
+
+```yaml
+backlog: https://api.example.com/api/forgeo/backlog
+```
+
+Add [`backlog_auth`](configuration.md#backlog_auth) when the endpoint requires
+a token. Everything else is unchanged: the same task schema, the same
+oldest-first ordering, the same status transitions.
+
+### What the endpoint must do
+
+- **Return the document under `tasks`**, as above. A response that is not a
+  JSON object, or whose `tasks` is not a list, reads as an empty backlog.
+- **Replace, never append.** The POST body is the complete task list as it
+  should be after the change; an endpoint that appends will duplicate every
+  task on every cycle.
+- **Send dates as ISO-8601 strings**, not epoch numbers. Jackson (and several
+  other serializers) emit `java.time` values as numeric timestamps by default;
+  Forgeo would read those as Unix timestamps, dating every task to 1970 and
+  inverting the oldest-first ordering.
+- **Never send `null` for a list field.** `dependencies`,
+  `acceptance_criteria`, `files_to_modify`, `blocker_reason` and
+  `failure_reason` accept a list or nothing at all — an explicit `null` makes
+  that row unparsable, and it comes back as a `FAILED` placeholder task.
+- **Preserve `agent_command`'s shape.** A string is run through a shell, a list
+  is executed directly; turning `"claude -p ..."` into `["claude -p ..."]`
+  makes Forgeo look for a binary with that entire name.
+- **Store the engine-managed fields it receives** (`status`, `updated_at`,
+  `blocker_reason`, `blocked_count`, `failure_reason`) and hand them back
+  unchanged. That is how a blocked task keeps its explanation.
+
+### When the endpoint is down
+
+A failed request **fails the cycle**: the daemon logs the error and retries on
+the next interval, leaving the remote backlog untouched. It is never read as an
+empty backlog — that would start a refactoring pass and let the POST at the end
+of the cycle overwrite the real task list with nothing. `forgeo status` and
+`forgeo once` report `Backlog unavailable: ...` and exit `1`; the web console
+answers `502` for that instance's tasks and flags it on the home page instead
+of showing an empty board.
+
+### Runtime files
+
+There is no backlog file for Forgeo's own runtime files to sit beside, so
+`backlog.lock`, `backlog.run`, `backlog.state.json`, `backlog.update.json` and
+`runs.jsonl` go into `state_dir`, which defaults to the directory holding
+`forgeo.yaml`. No snapshots are written: the document belongs to the remote
+application, so rolling it back is that application's job, not Forgeo's.

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/docs/configuration.md

@@ -22,7 +22,9 @@ paths), so `forgeo restart` is still used for those.
 | `interval_minutes` | `60` | How often Forgeo runs (≥ 1). |
 | `branch` | `main` | The single branch everything is committed to. |
 | `remote` | — | Remote to push to (e.g. `origin`); omit to only commit locally. |
-| `backlog` | `backlog.json` | The task backlog JSON. Keep it outside the repo if you can. |
+| `backlog` | `backlog.json` | The task backlog: the path of a JSON file (keep it outside the repo if you can), or an `http(s)` URL serving the same document — see [a backlog over HTTP](backlog.md#a-backlog-over-http). |
+| `state_dir` | — | Directory for Forgeo's runtime files (locks, run history, daemon state). Only meaningful with a backlog URL, where it defaults to the directory of `forgeo.yaml`. |
+| `backlog_auth` | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). |
 | `blocker_file` | `BLOCKER.md` | Where `BLOCKER.md` is written. Keep it outside the repo so it is never committed. |
 | `agent_command` | — | The coding agent: any shell command (string) or argv list. **Required.** |
 | `agent_timeout_seconds` | — | Optional: kill the agent after this many seconds (`null` = never). |
@@ -64,6 +66,49 @@ refactor_prompt: >
 
 ## Key details
 
+### `backlog_auth`
+
+Credentials for a backlog URL behind an identity provider. Forgeo requests an
+access token with the OAuth2 **client-credentials grant** and sends it as a
+bearer on every backlog request, so it authenticates as a service rather than
+as a person:
+
+```yaml
+backlog: https://api.example.com/api/forgeo/backlog
+backlog_auth:
+  token_url: https://keycloak.example.com/realms/dev/protocol/openid-connect/token
+  client_id: forgeo
+  client_secret_env: FORGEO_BACKLOG_CLIENT_SECRET
+  scope: forgeo-backlog       # optional
+  timeout_seconds: 10         # optional
+```
+
+| Key | Meaning |
+| --- | --- |
+| `token_url` | The provider's token endpoint. |
+| `client_id` | The confidential client requesting the token. |
+| `client_secret_env` | **Name of the environment variable** holding that client's secret. |
+| `scope` | Optional scope requested with the token. |
+| `timeout_seconds` | Timeout for the token request (default `10`). |
+
+The secret itself is never a config value: `client_secret_env` names the
+environment variable the daemon reads it from, so the secret stays out of
+`forgeo.yaml` (which the web console serves to your browser) and out of any
+copy or backup of it. A missing variable fails the cycle with a message naming
+the variable.
+
+Tokens are cached in memory and renewed shortly before they expire; nothing is
+written to disk. If the endpoint rejects a token Forgeo believed to be valid
+(HTTP 401/403), it requests a fresh one and retries the request once, so a key
+rotation does not cost a cycle.
+
+With Keycloak, this means a client with *Client authentication* on and
+*Service accounts roles* enabled: the resulting `service-account-<client-id>`
+user is what your backend authorizes.
+
+`backlog_auth` is rejected when `backlog` is a file — that combination is
+almost always a typo in the backlog value.
+
 ### `agent_command`
 
 Any shell command (string) or argv list. It is run with the repository as its
@@ -281,11 +326,13 @@ Manage instances with `forgeo instance add|rm|list` and `forgeo list` — see
 ## Per-instance isolation
 
 Each registered instance is fully independent: every instance owns its own
-**backlog** file, **logs** (`log_file`), **run history** (`runs.jsonl` next
-to the backlog), **locks** (`backlog.lock` and the per-iteration run lock),
-and a **`daemon.state.json`** with its live state. Because relative paths
-resolve against each config file's own directory, two configs in different
-directories can never share state.
+**backlog**, **logs** (`log_file`), **run history** (`runs.jsonl`), **locks**
+(`backlog.lock` and the per-iteration `backlog.run`), and a
+**`backlog.state.json`** with its live state. Those runtime files sit next to
+the backlog file, or — when the backlog is a URL — in `state_dir`, which
+defaults to the directory of that instance's `forgeo.yaml`. Because relative
+paths resolve against each config file's own directory, two configs in
+different directories can never share state.
 
 The daemons bind no ports. The central dashboard (`forgeo web`, default port
 `8790`) reads every instance's data straight from its files, so it works

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/docs/getting-started.md

@@ -80,7 +80,9 @@ forgeo init --force    # overwrite an existing forgeo.yaml
 The backlog is a plain JSON file (see [Backlog format](backlog.md)). Create
 the file configured as `backlog:` in your `forgeo.yaml` — by default
 `.forgeo/backlog.json`. Once Forgeo is running you can also add tasks
-from the [web console](web-console-api.md) — no file editing needed:
+from the [web console](web-console-api.md) — no file editing needed. (If your
+tasks already live in another application, `backlog:` also accepts an
+[HTTP endpoint](backlog.md#a-backlog-over-http) instead of a file.)
 
 ```json
 {

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/docs/index.md

@@ -102,11 +102,12 @@ forgeo.yaml ──► forgeo start (daemon)
 ## Where state lives
 
 - `forgeo.yaml` — the config (see [Configuration](configuration.md)).
-- `backlog.json` (configurable) — the task backlog (see
-  [Backlog format](backlog.md)).
-- `backlog.json.bak`, `backlog.json.bak.1`, ... — rotating snapshots of the
-  backlog, written before every agent run and on daemon startup so a bad
-  write can always be rolled back (see [Backlog format](backlog.md)).
+- `backlog.json` (configurable) — the task backlog, a file or an HTTP
+  endpoint (see [Backlog format](backlog.md)).
+- `backlog.json.bak`, `backlog.json.bak.1`, ... — rotating snapshots of a
+  *file* backlog, written before every agent run and on daemon startup so a
+  bad write can always be rolled back (see [Backlog format](backlog.md)). A
+  URL backlog is owned by the remote application and is never snapshotted.
 - `BLOCKER.md` (configurable) — written when a human decision is needed; keep
   it outside the repo so it is never committed.
 - `forgeo.log` — rotating daemon log (5 MB × 3), also served over HTTP.
@@ -119,6 +120,10 @@ forgeo.yaml ──► forgeo start (daemon)
   token (`forgeo web --token`): when present, every `/api/*` route requires
   `Authorization: Bearer <token>`; with no file the dashboard stays open.
 
+The three runtime files above (and `runs.jsonl`) sit next to the backlog file;
+with a backlog URL they go in `state_dir`, which defaults to the directory
+holding `forgeo.yaml`.
+
 ## Next steps
 
 - [Getting Started](getting-started.md) — install and run your first cycle.

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/docs/web-console-api.md

@@ -6,7 +6,9 @@ just schedules cycles and writes its live state to `daemon.state.json`. The
 dashboard reads every registered instance's data straight from its files
 (`backlog.json`, `runs.jsonl`, `forgeo.log`, `BLOCKER.md`,
 `daemon.state.json`), so it works whether or not each instance's daemon is
-running.
+running. An instance whose `backlog` is an HTTP endpoint is the exception: its
+tasks are fetched from there, and an endpoint that cannot be reached answers
+`502` rather than showing an empty board.
 
 ```bash
 forgeo web               # default 0.0.0.0:8790, foreground
@@ -150,6 +152,12 @@ outcome, next run, and backlog counts.
 curl http://127.0.0.1:8790/api/instances
 ```
 
+Each row also carries `backlog_error`: `null` normally, and the reason when
+that instance's backlog could not be read (only possible for a backlog served
+over HTTP). Its counts are zero in that case — the row reports a backlog it
+could not reach, not an empty one. One unreachable endpoint never fails the
+whole listing.
+
 ### `GET /api/instances/<name>/tasks`
 
 List every task in that instance's backlog, in creation order. Each task
@@ -180,6 +188,9 @@ curl http://127.0.0.1:8790/api/instances/my-repo/tasks
 ]
 ```
 
+A backlog served over HTTP is fetched on each request; when the endpoint is
+unreachable the response is `502` with the reason in `error`.
+
 ### `GET /api/instances/<name>/tasks/{id}`
 
 Fetch a single task by id.
@@ -464,9 +475,11 @@ a restart (via the **Restart** button or `POST .../restart`). Errors:
 `forgeo.yaml`) and is forced to the registered name — sending a different value
 is rejected. `telegram_bot_token` is not editable through the web console: an
 explicit change is rejected with `400`, and the current value is preserved when
-the field is omitted, so a partial payload never wipes it. Everything else
-`GET .../config` returns (including `agent_env`, which can carry credentials
-the agent needs) is editable.
+the field is omitted, so a partial payload never wipes it. `backlog_auth` and
+`state_dir` are likewise preserved when the payload omits them — the config
+form does not render them, and a save must not drop what it never showed.
+Everything else `GET .../config` returns (including `agent_env`, which can
+carry credentials the agent needs) is editable.
 
 ### `POST /api/instances/<name>/start`, `/stop`, `/restart`
 

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/install.sh

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

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.5.0"
+version = "0.6.0"
 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.5.0 → forgeo_cli-0.6.0}/src/forgeo/__init__.py

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

{forgeo_cli-0.5.0 → forgeo_cli-0.6.0}/src/forgeo/backlog.py

@@ -1,16 +1,23 @@
-"""The backlog: a single human-readable JSON file of tasks.
+"""The backlog: the list of tasks Forgeo works through.
 
 Forgeo pulls the oldest ``OPEN`` task whose dependencies are all ``COMPLETED``
 from here (an optional ``run_at`` one-shot schedule overrides the oldest-first
-order). Edit this file directly to add, remove, or reopen tasks (e.g. set a
-``BLOCKED`` task back to ``OPEN`` once the human input has been provided).
-Writes are atomic and serialized through an asyncio lock.
+order). The tasks live in a single JSON document — ``{"tasks": [...]}`` — which
+is either a local file you can edit by hand (add, remove, or set a ``BLOCKED``
+task back to ``OPEN`` once you have provided the input it needed) or an HTTP
+endpoint owned by another application, see :mod:`forgeo.backlog_http`.
 
-The backlog is the single source of truth, so it is guarded against bad
+Everything above the storage layer is shared: :class:`BacklogStore` holds all
+the task manipulation and the asyncio lock that serializes writes, and leaves
+exactly two operations to its subclasses — load the document, store the
+document.
+
+A file backlog is the single source of truth, so it is guarded against bad
 writes: before every agent run (and on daemon startup) a rotating snapshot is
 written next to it (``backlog.json.bak``, ``backlog.json.bak.1``, ...) and a
 read that finds a corrupt store restores the newest valid snapshot in place
-instead of silently starting from an empty one.
+instead of silently starting from an empty one. A URL backlog is owned by the
+remote application, which keeps its own history, so it is never snapshotted.
 """
 
 from __future__ import annotations
@@ -19,6 +26,7 @@ import asyncio
 import json
 import logging
 import os
+from abc import ABC, abstractmethod
 from collections import Counter
 from collections.abc import Callable
 from datetime import UTC, datetime
@@ -28,7 +36,7 @@ from typing import Any
 from pydantic import ValidationError
 
 from forgeo.io import atomic_write_text
-from forgeo.models import Task, TaskStatus
+from forgeo.models import ForgeoConfig, Task, TaskStatus
 
 logger = logging.getLogger(__name__)
 
@@ -168,23 +176,52 @@ def snapshot_paths_for(
     ]
 
 
-class JSONBacklog:
-    """A backlog stored in a single JSON document on disk."""
+class BacklogUnavailableError(RuntimeError):
+    """The backlog document could not be retrieved or stored.
 
-    def __init__(
-        self,
-        path: str | Path,
-        *,
-        snapshot_count: int = DEFAULT_SNAPSHOT_COUNT,
-    ) -> None:
-        self.path = Path(path)
-        self.snapshot_count = max(0, snapshot_count)
+    Raised by a storage backend that cannot reach the backlog at all, which
+    is categorically different from a backlog that holds no tasks: callers
+    must never let the two look the same.
+    """
+
+
+def normalize_store(data: Any) -> dict[str, Any]:
+    """Coerce a decoded backlog document into the internal store shape.
+
+    Deliberately forgiving about *shape* (anything that is not an object with
+    a list of tasks reads as an empty backlog) and silent about it, because
+    the document is hand-editable. It says nothing about whether the document
+    could be *retrieved*: a storage backend must raise for that, so an
+    unreachable backlog is never mistaken for an empty one.
+    """
+    if not isinstance(data, dict):
+        return {"tasks": []}
+    tasks = data.get("tasks")
+    return {"tasks": tasks if isinstance(tasks, list) else []}
+
+
+class BacklogStore(ABC):
+    """A backlog of tasks, independent of where the document is kept.
+
+    Subclasses implement :meth:`_read` and :meth:`_write`; everything else —
+    the task transitions, their validation, and the lock that serializes
+    concurrent mutations within one process — lives here.
+    """
+
+    def __init__(self) -> None:
         self._lock = asyncio.Lock()
 
-    @property
-    def snapshot_paths(self) -> list[Path]:
-        """The rotating snapshot paths for this backlog, newest (``.bak``) first."""
-        return snapshot_paths_for(self.path, count=self.snapshot_count)
+    @abstractmethod
+    async def _read(self) -> dict[str, Any]:
+        """Load the whole document as ``{"tasks": [...]}``.
+
+        Must raise when the document cannot be retrieved, and return an empty
+        store only when the backlog genuinely holds no tasks.
+        """
+
+    @abstractmethod
+    async def _write(self, store: dict[str, Any]) -> None:
+        """Persist the whole document; must raise when it cannot be stored."""
 
     async def list_tasks(self) -> list[Task]:
         """Return all tasks, in the order they were created."""
@@ -197,26 +234,13 @@ class JSONBacklog:
         return oldest_open_task(await self.list_tasks(), now=now)
 
     async def snapshot(self) -> None:
-        """Copy the current store to a rotating snapshot (``backlog.json.bak``).
+        """Take a rollback copy of the backlog before it is written to.
 
-        Called before every agent run and on daemon startup so a bad write to
-        the backlog (a hostile agent, a half-written file, an accidental
-        manual edit) can always be rolled back to the newest valid snapshot.
-        The newest snapshot is always ``<backlog>.bak``; existing snapshots
-        are rotated up by one index and the oldest beyond ``snapshot_count``
-        is dropped. A missing backlog is a no-op and a failure is logged
-        without raising, so snapshotting can never break a cycle.
+        A no-op by default: only a backend that *owns* the document can
+        meaningfully snapshot it. :class:`JSONBacklog` overrides this; a
+        backlog served over HTTP belongs to the remote application, which
+        keeps its own history, so Forgeo does not shadow-copy it.
         """
-        if not self.path.exists() or self.snapshot_count <= 0:
-            return
-        async with self._lock:
-            try:
-                store = await self._read()
-                self._rotate_snapshots()
-                self._write_snapshot(store)
-                logger.info("Backlog snapshot written to %s", self.snapshot_paths[0])
-            except OSError as exc:
-                logger.warning("Could not snapshot backlog at %s: %s", self.path, exc)
 
     async def get_task(self, task_id: str) -> Task | None:
         """Return a task by id, or ``None`` if it does not exist."""
@@ -418,7 +442,7 @@ class JSONBacklog:
             return task
 
     # ------------------------------------------------------------------ #
-    # Internal persistence helpers                                        #
+    # Internal task helpers                                               #
     # ------------------------------------------------------------------ #
 
     async def _update_entry(
@@ -449,6 +473,60 @@ class JSONBacklog:
                 return entry
         return None
 
+    @staticmethod
+    def _to_task(entry: dict[str, Any]) -> Task:
+        """Validate a stored dictionary back into a Task, skipping corrupt rows."""
+        try:
+            return Task.model_validate(entry)
+        except ValidationError:
+            return Task(
+                id=str(entry.get("id", "<unknown>")),
+                title="<unparsable task>",
+                description="<unparsable task>",
+                status=TaskStatus.FAILED,
+            )
+
+
+class JSONBacklog(BacklogStore):
+    """A backlog stored in a single JSON document on disk."""
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        snapshot_count: int = DEFAULT_SNAPSHOT_COUNT,
+    ) -> None:
+        super().__init__()
+        self.path = Path(path)
+        self.snapshot_count = max(0, snapshot_count)
+
+    @property
+    def snapshot_paths(self) -> list[Path]:
+        """The rotating snapshot paths for this backlog, newest (``.bak``) first."""
+        return snapshot_paths_for(self.path, count=self.snapshot_count)
+
+    async def snapshot(self) -> None:
+        """Copy the current store to a rotating snapshot (``backlog.json.bak``).
+
+        Called before every agent run and on daemon startup so a bad write to
+        the backlog (a hostile agent, a half-written file, an accidental
+        manual edit) can always be rolled back to the newest valid snapshot.
+        The newest snapshot is always ``<backlog>.bak``; existing snapshots
+        are rotated up by one index and the oldest beyond ``snapshot_count``
+        is dropped. A missing backlog is a no-op and a failure is logged
+        without raising, so snapshotting can never break a cycle.
+        """
+        if not self.path.exists() or self.snapshot_count <= 0:
+            return
+        async with self._lock:
+            try:
+                store = await self._read()
+                self._rotate_snapshots()
+                self._write_snapshot(store)
+                logger.info("Backlog snapshot written to %s", self.snapshot_paths[0])
+            except OSError as exc:
+                logger.warning("Could not snapshot backlog at %s: %s", self.path, exc)
+
     async def _read(self) -> dict[str, Any]:
         """Load the store from disk, tolerating a missing or corrupt file.
 
@@ -540,15 +618,13 @@ class JSONBacklog:
             json.dumps(store, indent=2, ensure_ascii=False) + "\n",
         )
 
-    @staticmethod
-    def _to_task(entry: dict[str, Any]) -> Task:
-        """Validate a stored dictionary back into a Task, skipping corrupt rows."""
-        try:
-            return Task.model_validate(entry)
-        except ValidationError:
-            return Task(
-                id=str(entry.get("id", "<unknown>")),
-                title="<unparsable task>",
-                description="<unparsable task>",
-                status=TaskStatus.FAILED,
-            )
+
+def open_backlog(config: ForgeoConfig) -> BacklogStore:
+    """The backlog store ``config`` points at: a JSON file or an HTTP endpoint."""
+    if config.backlog_is_url:
+        # Imported here: the HTTP backend builds on BacklogStore, so importing
+        # it at module level would close an import cycle.
+        from forgeo.backlog_http import HttpBacklog
+
+        return HttpBacklog(str(config.backlog), auth=config.backlog_auth)
+    return JSONBacklog(Path(config.backlog))