forgeo-cli 0.8.0__tar.gz → 0.10.0__tar.gz

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-24
+
+### Added
+
+- `forgeo init` now asks for **backlog provider** (`file`/`github`/`gitlab`/`jira`/`http`). For `github` it auto-detects `owner/repo` from `git remote origin`, prompts for `token_env` (`GITHUB_TOKEN`) and can persist a pasted classic PAT (`ghp_...`, scope `repo`) to `~/.config/forgeo/github_token_env.sh` (600, wired to `~/.bashrc`). Same for `gitlab` (`GITLAB_TOKEN`, base URL) and `jira`/`http`. The wizard writes `backlog: https://api.github.com`, `backlog_provider: github`, `github: {repo, auth: {token_env}}` and `state_dir: .forgeo` automatically.
+- Web console now treats `jira`/`github`/`gitlab` as a **read-mostly mirror** instead of a replacement: the home page cards show `Open in Jira/GitHub/GitLab ↗` (via `external_board_url`/`external_board_label`), the instance page shows a top banner linking to the native board, and each task card/modal links to the native issue (`external_url`). Document backlogs (`file`/`http`) keep the existing primary-editor behaviour. Creating/editing still works through the dashboard, but triage is expected in the native tracker where Forgeo-specific state (BLOCKED/FAILED reasons, `agent_response`, retry budget) is now surfaced on the mirror.
+- Central API now exposes `backlog_provider`, `backlog`, `backlog_is_issue_provider`, `external_board_url`/`external_board_label` on `GET /api/instances` and `GET /api/instances/<name>/status`, and `external_url` per task on `GET /api/instances/<name>/tasks` (+ single-task) for issue providers. Covers `https://api.github.com` → `https://github.com` and `https://…/api/v3` → web base mapping for GitHub Enterprise, and `https://jira…/issues/?jql=` / `https://gitlab…/{repo}/-/issues` board links.
+
+### Fixed
+
+- GitHub provider now encodes `owner/repo` as two path segments (`quote` per segment, keeping `/`) instead of `quote(repo, safe='')` which produced `owner%2Frepo` and 404 on every `GET /repos/{owner%2Frepo}/issues`.
+
+### Changed
+
+- `README`, `docs/backlog.md`, `docs/getting-started.md` and `docs/web-console-api.md` document the mirror vs editor split and the new `external_*` API fields.
+- `src/forgeo/central.py` deduplicates provider metadata via `_backlog_meta()` and centralises GitHub web-base handling; `instance-card` is now a `div[role=link]` to allow nested external links without invalid HTML.
+- `README`, `docs/getting-started.md` and `docs/cli-reference.md` document the new backlog-provider step in `forgeo init` and the `GITHUB_TOKEN` PAT setup (`https://github.com/settings/tokens/new`, scope `repo`).
+
+## [0.9.0] - 2026-08-23
+
+### Added
+
+- GitHub Issues and GitLab Issues task providers. Set `backlog_provider: github`
+  or `gitlab` and point `backlog:` at the API base URL
+  (`https://api.github.com` or `https://github.example.com/api/v3` for
+  Enterprise; `https://gitlab.com` or a self-hosted root for GitLab). Issue
+  numbers/`iid`s become Forgeo task ids, `open`/`opened` vs `closed` maps to
+  `OPEN`/`COMPLETED`, and `forgeo-running`/`forgeo-blocked`/`forgeo-failed`
+  labels (configurable via `label_prefix`) represent the remaining states.
+  Engine state — blocker and failure reasons, retry counters, claim time,
+  dependencies, and bounded agent output — is stored in a hidden
+  `<!-- forgeo: {...} -->` block inside the issue body/description, so the
+  visible text stays human-readable and no custom fields or issue properties
+  are required.
+- `github` and `gitlab` config blocks: `repo` (`owner/repo` or project path/id),
+  `token_env` (PAT from an environment variable, never stored in the file),
+  `label_prefix`/`property_key`, pagination, timeouts, stale-claim recovery
+  via `claim_timeout_seconds`, and optional workflow/field mappings mirroring
+  the Jira provider.
+- Shared issue-provider helpers extracted to `backlog_issue_base` and a new
+  `DocumentBacklogStore` / `IssueBacklogBase` split in `backlog.py`,
+  unifying claim, label, and engine-state handling across Jira, GitHub, and
+  GitLab. `forgeo validate` now checks any remote backlog with a
+  provider-specific message, and `config/forgeo.yaml`, the README, and the
+  backlog/configuration docs list and document all five providers
+  (`file`, `http`, `jira`, `github`, `gitlab`).
+
 ## [0.8.0] - 2026-08-21
 
 ### Added
@@ -360,7 +407,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.8.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/lucaGazzola/forgeo/compare/v0.7.3...v0.8.0
 [0.7.3]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...v0.7.2

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.8.0
+Version: 0.10.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
@@ -110,6 +110,10 @@ forgeo init
 
 Guided wizard, run from your project root. Writes `forgeo.yaml` (the
 config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+The wizard asks for the backlog provider (`file` for a local JSON file, or
+`github`/`gitlab`/`jira`/`http` for an external tracker — for `github` it
+auto-detects `owner/repo` from `git remote` and can persist a pasted
+`GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`).
 
 The base flow is then three steps: fill the backlog, check the
 configuration, start the daemon.
@@ -121,8 +125,10 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
-# (see the Jira backlog documentation).
+# Or: pick github/gitlab/jira in forgeo init (or configure forgeo.yaml
+# manually): set backlog_provider: github and backlog: https://api.github.com
+# with github.repo + token_env, then export GITHUB_TOKEN and run
+# forgeo validate. See backlog docs for Jira/GitHub/GitLab.
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -211,15 +217,27 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the local backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL, or in Jira. HTTP backlogs
-exchange the complete task document; Jira issues are read and transitioned
-individually with workflow state and engine metadata stored on the issue (see
-[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. 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.
 
+The central dashboard (`forgeo web`) mirrors every instance: for `file`/`http` it is the primary editor; for
+`jira`/`github`/`gitlab` it is a read-mostly mirror of the native tracker — each task card and its detail modal link
+to the native issue (`Open in Jira/GitHub/GitLab ↗`), a top banner links to the native board, and the board surfaces
+Forgeo-specific state the native UI does not (BLOCKED/FAILED reasons, `agent_response`, retry budget) — triage stays in
+the tracker (see [Web console & HTTP API](docs/web-console-api.md)).
+
 ## Develop
 
 ```bash

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/README.md

@@ -56,6 +56,10 @@ forgeo init
 
 Guided wizard, run from your project root. Writes `forgeo.yaml` (the
 config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+The wizard asks for the backlog provider (`file` for a local JSON file, or
+`github`/`gitlab`/`jira`/`http` for an external tracker — for `github` it
+auto-detects `owner/repo` from `git remote` and can persist a pasted
+`GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`).
 
 The base flow is then three steps: fill the backlog, check the
 configuration, start the daemon.
@@ -67,8 +71,10 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
-# (see the Jira backlog documentation).
+# Or: pick github/gitlab/jira in forgeo init (or configure forgeo.yaml
+# manually): set backlog_provider: github and backlog: https://api.github.com
+# with github.repo + token_env, then export GITHUB_TOKEN and run
+# forgeo validate. See backlog docs for Jira/GitHub/GitLab.
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -157,15 +163,27 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
 Everything is stored in plain files: the local backlog, `forgeo.log`, and
-`BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL, or in Jira. HTTP backlogs
-exchange the complete task document; Jira issues are read and transitioned
-individually with workflow state and engine metadata stored on the issue (see
-[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. 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.
 
+The central dashboard (`forgeo web`) mirrors every instance: for `file`/`http` it is the primary editor; for
+`jira`/`github`/`gitlab` it is a read-mostly mirror of the native tracker — each task card and its detail modal link
+to the native issue (`Open in Jira/GitHub/GitLab ↗`), a top banner links to the native board, and the board surfaces
+Forgeo-specific state the native UI does not (BLOCKED/FAILED reasons, `agent_response`, retry budget) — triage stays in
+the tracker (see [Web console & HTTP API](docs/web-console-api.md)).
+
 ## Develop
 
 ```bash

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/docs/backlog.md

@@ -1,12 +1,24 @@
 # Backlog format
 
-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, or it can be sourced directly from [Jira](#a-jira-backlog).
+- [JSON file](#a-json-file-backlog)
+- [HTTP endpoint](#a-backlog-over-http)
+- [Jira](#a-jira-backlog)
+- [GitHub](#a-github-backlog)
+- [GitLab](#a-gitlab-backlog)
+
+The backlog is a **plain JSON document** — a list of tasks Forgeo works through
+one by one.
+
+## A JSON file backlog
+
+By default the backlog 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, or it
+can be sourced directly from [Jira](#a-jira-backlog),
+[GitHub](#a-github-backlog) or [GitLab](#a-gitlab-backlog).
 
 ```json
 {
@@ -132,6 +144,11 @@ You add, remove, or reopen tasks by editing the file directly — or use the
 the task detail modal's **Edit** button updates an existing task's fields
 (`PATCH /api/instances/<name>/tasks/<id>`), while its **Delete** button
 removes an `OPEN` or `BLOCKED` task (`DELETE /api/instances/<name>/tasks/<id>`).
+For `file`/`http` backlogs this is the primary editor; for `jira`/`github`/`gitlab` the web console is a
+read-mostly **mirror** of the native tracker — a top banner links to the external board, each task card/modal
+links to the native issue (`Open in Jira/GitHub/GitLab ↗`), and the board surfaces Forgeo-specific state
+(`blocker_reason`, `failure_reason`, `agent_response`, retry budget) that the tracker does not — triage stays in
+Jira/GitHub/GitLab, Forgeo reflects it (see [Web console & HTTP API](web-console-api.md)).
 
 ### Resolving a blocked task
 
@@ -424,3 +441,75 @@ If a process dies while holding a claim, a later cycle releases claims older
 than `claim_timeout_seconds` and returns them to the configured open status.
 An unavailable Jira endpoint fails the cycle; it is never treated as an empty
 backlog.
+
+## A GitHub backlog
+
+Set `backlog_provider: github` and point `backlog:` at the GitHub API base URL:
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+Use `https://api.github.com` for github.com or `https://github.example.com/api/v3` for Enterprise.
+
+### Mapping and lifecycle
+
+- GitHub issue numbers are Forgeo task ids.
+- `title`, `body` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `open` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` (prefix configurable via `label_prefix`) represent running, blocked, and failed tasks. An open issue carrying `forgeo-running` is considered claimed and filtered from picking.
+- Closing an issue completes its task; reopening it moves the task back to `OPEN`.
+
+Forgeo stores blocker reasons, failure reasons, retry counters, claim time, dependencies, and bounded agent output in a hidden JSON block inside the issue body: `<!-- forgeo: {...} -->`. The visible body remains human-readable; the hidden block is stripped on read and merged on write. No GitHub issue property or custom field is required. Set `github.property_key` only for symmetry; the marker key is `forgeo` by default.
+
+Dependencies are persisted via the hidden block's `dependencies` list; no GitHub issue links are required.
+
+### Authentication
+
+GitHub credentials are never stored in `forgeo.yaml`:
+
+- `token_env` names the environment variable holding a personal-access token (classic or fine-grained). The token is sent as `Authorization: Bearer <token>`.
+
+### Runtime behavior
+
+The daemon lists GitHub issues with paginated `GET /repos/{owner}/{repo}/issues?state=all`. A task is claimed by adding the `forgeo-running` label and persisting `claimed_at` in the hidden block. If a process dies while holding a claim, a later cycle releases claims older than `claim_timeout_seconds` and removes the running label. An unavailable GitHub endpoint fails the cycle.
+
+## A GitLab backlog
+
+Set `backlog_provider: gitlab` and point `backlog:` at the GitLab base URL:
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+
+gitlab:
+  repo: group/project   # or numeric project id
+  token_env: GITLAB_TOKEN
+  label_prefix: forgeo
+```
+
+GitLab base URL is the instance root (e.g. `https://gitlab.com`); the client appends `/api/v4`.
+
+### Mapping and lifecycle
+
+- GitLab issue `iid`s are Forgeo task ids.
+- `title`, `description` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `opened` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` represent running, blocked, and failed tasks, like GitHub. An `opened` issue with `forgeo-running` is filtered as claimed.
+- Closing/reopening via `state_event` transitions the task to `COMPLETED`/`OPEN`.
+
+Forgeo stores engine state the same way as GitHub: a hidden `<!-- forgeo: {...} -->` block inside `description`. Dependencies and other task attributes are kept there; no GitLab custom fields are required.
+
+### Authentication
+
+- `token_env` names the environment variable holding a personal-access token. Sent as `PRIVATE-TOKEN` and `Authorization: Bearer`.
+
+### Runtime behavior
+
+Paginated `GET /api/v4/projects/:id/issues?state=all`. Claiming adds `forgeo-running` and `claimed_at`; stale claims older than `claim_timeout_seconds` are released. An unavailable GitLab endpoint fails the cycle.

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/docs/cli-reference.md

@@ -23,6 +23,8 @@ Guided first-time setup: interactively write a `forgeo.yaml`.
 | <span style="white-space: nowrap">`--config <file>`</span> | Where to write the config (default `forgeo.yaml`). |
 | <span style="white-space: nowrap">`--force`</span> | Overwrite an existing config file. |
 
+The wizard asks for: Forgeo folder, backlog provider (`file`/`github`/`gitlab`/`jira`/`http` — for `github` it auto-detects `owner/repo` from `git remote` and can persist `GITHUB_TOKEN`), coding agent command, and refactor prompt.
+
 Exit codes:
 
 - `0` — config written.

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/docs/configuration.md

@@ -22,11 +22,13 @@ paths), so `forgeo restart` is still used for those.
 | <span style="white-space: nowrap">`interval_minutes`</span> | `60` | How often Forgeo runs (≥ 1). |
 | <span style="white-space: nowrap">`branch`</span> | `main` | The single branch everything is committed to. |
 | <span style="white-space: nowrap">`remote`</span> | — | Remote to push to (e.g. `origin`); omit to only commit locally. |
-| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file, an HTTP endpoint serving the same document, or a Jira base URL when `backlog_provider: jira`. |
-| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or Jira when a `jira` block is present; explicitly choose `file`, `http`, or `jira` when preferred. |
+| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file, an HTTP endpoint serving the same document, or a base URL for `jira`/`github`/`gitlab` providers. |
+| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or `jira`/`github`/`gitlab` when the corresponding block is present; explicitly choose `file`, `http`, `jira`, `github`, or `gitlab`. |
 | <span style="white-space: nowrap">`state_dir`</span> | — | Directory for Forgeo's runtime files (locks, run history, daemon state). Remote backlogs default this to the directory of `forgeo.yaml`. |
-| <span style="white-space: nowrap">`backlog_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). |
+| <span style="white-space: nowrap">`backlog_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). Only for `http` provider. |
 | <span style="white-space: nowrap">`jira`</span> | — | Jira REST, workflow, authentication, and custom-field settings. Required when `backlog_provider: jira`. |
+| <span style="white-space: nowrap">`github`</span> | — | GitHub REST settings. Required when `backlog_provider: github`. |
+| <span style="white-space: nowrap">`gitlab`</span> | — | GitLab REST settings. Required when `backlog_provider: gitlab`. |
 | <span style="white-space: nowrap">`blocker_file`</span> | `BLOCKER.md` | Where `BLOCKER.md` is written. Keep it outside the repo so it is never committed. |
 | <span style="white-space: nowrap">`agent_command`</span> | — | The coding agent: any shell command (string) or argv list. **Required.** |
 | <span style="white-space: nowrap">`agent_timeout_seconds`</span> | — | Optional: kill the agent after this many seconds (`null` = never). |
@@ -140,6 +142,55 @@ truth for human changes.
 | `jira.workflow` | defaults | Status ids or names for open, running, blocked, completed, and failed transitions. |
 | `jira.fields` | — | Optional custom-field ids for task attributes such as acceptance criteria and dependencies. |
 
+### GitHub backlog
+
+Forgeo can read and update GitHub issues directly. Set `backlog_provider: github` and make `backlog` the GitHub API base URL. Issue numbers become task ids. Labels and a hidden JSON block in the issue body hold Forgeo's engine state.
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `github.repo` | — | Required owner/repo. |
+| `github.auth` | — | Required PAT env var `token_env`. |
+| `github.label_prefix` | `forgeo` | Prefix for running/blocked/failed labels. |
+| `github.property_key` | `forgeo` | Marker key for hidden body block (symmetry). |
+| `github.page_size` | `30` | Issues per page. |
+| `github.max_issues` | `1000` | Max issues read. |
+| `github.timeout_seconds` | `30` | HTTP timeout. |
+| `github.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `github.workflow` | defaults | State/label mapping. |
+| `github.fields` | — | Optional field mappings. |
+
+### GitLab backlog
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+gitlab:
+  repo: group/project
+  token_env: GITLAB_TOKEN
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `gitlab.repo` | — | Required project path or numeric id. |
+| `gitlab.auth` | — | Required PAT env var `token_env`. |
+| `gitlab.label_prefix` | `forgeo` | Prefix for labels. |
+| `gitlab.property_key` | `forgeo` | Marker key. |
+| `gitlab.page_size` | `30` | Issues per page. |
+| `gitlab.max_issues` | `1000` | Max issues. |
+| `gitlab.timeout_seconds` | `30` | HTTP timeout. |
+| `gitlab.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `gitlab.workflow` | defaults | State mapping. |
+| `gitlab.fields` | — | Optional field mappings. |
+
 ## Key details
 
 ### `backlog_auth`

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/docs/getting-started.md

@@ -56,20 +56,29 @@ Run the guided wizard from your project root:
 forgeo init
 ```
 
-The wizard asks for three things:
+The wizard asks for:
 
 1. **Forgeo folder** — where the backlog, `BLOCKER.md` and the log live
    (default `.forgeo`). It is gitignored by default.
-2. **Coding agent command** — the bare command that launches your coding
+2. **Backlog provider** — where tasks live: `file` (local `.forgeo/backlog.json`),
+   `github` / `gitlab` / `jira` / `http`. For `github` it auto-detects
+   `owner/repo` from `git remote origin`, asks for `token_env` (default
+   `GITHUB_TOKEN`) and can persist a pasted classic PAT (`ghp_...`, scope `repo`)
+   to `~/.config/forgeo/github_token_env.sh` (600, wired to `~/.bashrc`). Same
+   for `gitlab` (`GITLAB_TOKEN`, base URL) and `jira`/`http`.
+3. **Coding agent command** — the bare command that launches your coding
    agent (default `opencode run --auto`). Forgeo appends the standard task
    prompt (which ends in `$FORGEO_TASK`) automatically, so you never type
    it. Enter a command that already references `$FORGEO_TASK` and it is
    kept verbatim.
-3. **Refactor prompt** — the instruction used when the backlog is empty; the
+4. **Refactor prompt** — the instruction used when the backlog is empty; the
    default is offered, or you can paste a custom one.
 
 `forgeo init` writes `forgeo.yaml`, creates Forgeo folder, and appends
-`<folder>/` to `.gitignore` (unless you opt out).
+`<folder>/` to `.gitignore` (unless you opt out). For `github`/`gitlab`/`jira`
+set `backlog_provider` + `backlog` URL + provider block is written automatically
+and `state_dir` is set to the Forgeo folder so runtime files stay beside the
+config.
 
 ```bash
 forgeo init --force    # overwrite an existing forgeo.yaml
@@ -77,18 +86,25 @@ forgeo init --force    # overwrite an existing forgeo.yaml
 
 ## 3. Create your first backlog
 
-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. (If your
-tasks already live in another application, `backlog:` also accepts an
-[HTTP endpoint](backlog.md#a-backlog-over-http) or a [Jira source](backlog.md#a-jira-backlog)
-instead of a file.)
-
-For Jira, set `backlog_provider: jira`, point `backlog:` at the Jira base URL,
-configure `jira.jql` and the workflow mappings, export the credentials named in
-`jira.auth`, and run `forgeo validate` before starting the daemon. See [Jira
-backlogs](backlog.md#a-jira-backlog) for the complete configuration.
+If you chose `file` in the wizard, the backlog is a plain JSON file (see
+[Backlog format](backlog.md)) — 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.
+
+If you chose `github`/`gitlab`/`jira`/`http` in the wizard, your `forgeo.yaml`
+already points at the provider (`backlog: https://api.github.com` etc.).
+For `github` create a classic PAT at `https://github.com/settings/tokens/new`
+(scope `repo`), `export GITHUB_TOKEN=ghp_...` (or let the wizard persist it),
+then `forgeo validate` before `forgeo start`. Same for `gitlab` (`GITLAB_TOKEN`)
+and `jira`. See [Backlog format](backlog.md) for provider details.
+
+For `jira`/`github`/`gitlab`, set `backlog_provider:` to the provider, point `backlog:` at its base URL
+(`https://jira.example.com`, `https://api.github.com` / `https://github.example.com/api/v3`,
+`https://gitlab.example.com`), configure the provider block (`jira.jql` / `github.repo` / `gitlab.repo` and auth),
+export the credentials named in `*_auth.token_env`, and run `forgeo validate` before starting the daemon.
+The dashboard for these providers is a read-mostly mirror: a banner links to the native board, each card links to
+the native issue, and Forgeo-specific state (BLOCKED/FAILED reasons, `agent_response`) is surfaced on the board — triage
+stays in Jira/GitHub/GitLab. See [Backlog: Jira/GitHub/GitLab](backlog.md) for the complete configuration.
 
 ```json
 {

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/docs/web-console-api.md

@@ -66,11 +66,20 @@ open-by-default behavior.
 
 - `GET /` — home page listing every registered instance: name, repository,
   daemon state (lock held), last outcome, next run, and per-status backlog
-  counts, each linking to its instance page.
+  counts, each linking to its instance page. For issue-backed instances
+  (`jira`/`github`/`gitlab`) the card also shows an **Open in Jira/GitHub/GitLab ↗**
+  link to the native board.
 - `GET /instances/<name>/` — one instance's page: a kanban backlog, a
   **Create** tab with a form to add tasks (including an optional *Run at*
   date/time input for a one-shot schedule), plus tabs for **logs**, **history**,
-  **blocker** and **config**. The header carries a **DAEMON** section with the
+  **blocker** and **config**. For document backlogs (`file`/`http`) this board
+  is the primary editor; for issue providers (`jira`/`github`/`gitlab`) it is a
+  read-mostly **mirror** of the native tracker: a banner at the top links to
+  the external board (`Jira`/`GitHub`/`GitLab`), each task card and its detail
+  modal carry an **Open in external ↗** link to the native issue, and the board
+  surfaces Forgeo-specific state that the native UI does not (BLOCKED/FAILED
+  reasons, `agent_response`, retry budget). Creating/editing still works via
+  the dashboard, but triage is expected in the native tool. The header carries a **DAEMON** section with the
   daemon status tag (`running`/`stopped`) and **Start**/**Stop**/**Restart**
   buttons that call `POST /api/instances/<name>/start|stop|restart`; the
   buttons reflect the current state (Start is disabled while running, Stop
@@ -152,15 +161,19 @@ 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 remote backlog could not be read. Its counts are zero in that
-case — the row reports a backlog it could not reach, not an empty one. One
-unreachable provider never fails the whole listing.
+Each row also carries `backlog_provider` (`file`/`http`/`jira`/`github`/`gitlab`),
+`backlog` (path or base URL), `backlog_is_issue_provider`, and for issue
+providers `external_board_url`/`external_board_label` (the native board link
+shown on the home cards). It also carries `backlog_error`: `null` normally,
+and the reason when that instance's remote backlog could not be read. Its
+counts are zero in that case — the row reports a backlog it could not reach,
+not an empty one. One unreachable provider never fails the whole listing.
 
 ### `GET /api/instances/<name>/tasks`
 
 List every task in that instance's backlog, in creation order. Each task
-carries extra `unsatisfied_dependencies` and retry fields (see below).
+carries extra `unsatisfied_dependencies`, retry fields (see below), and for
+issue providers `external_url` (link to the native Jira/GitHub/GitLab issue).
 
 ```bash
 curl http://127.0.0.1:8790/api/instances/my-repo/tasks
@@ -400,7 +413,10 @@ Errors:
 ### `GET /api/instances/<name>/status`
 
 Daemon status: name, repo, interval, `daemon_running` (whether the instance's
-lock is held), the recorded PID, `last_outcome`, and the `next_run_at`.
+lock is held), the recorded PID, `last_outcome`, and the `next_run_at`. Also
+carries `backlog_provider`, `backlog`, `backlog_is_issue_provider`,
+`external_board_url`/`external_board_label` so the instance page can render the
+issue-provider banner and per-task external links.
 
 ```bash
 curl http://127.0.0.1:8790/api/instances/my-repo/status
@@ -414,7 +430,12 @@ curl http://127.0.0.1:8790/api/instances/my-repo/status
   "daemon_running": true,
   "pid": 4242,
   "last_outcome": "task",
-  "next_run_at": "2026-08-01T12:00:00+00:00"
+  "next_run_at": "2026-08-01T12:00:00+00:00",
+  "backlog_provider": "github",
+  "backlog": "https://api.github.com",
+  "backlog_is_issue_provider": true,
+  "external_board_url": "https://github.com/owner/repo/issues",
+  "external_board_label": "GitHub"
 }
 ```
 

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/install.sh

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

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.8.0"
+version = "0.10.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.8.0 → forgeo_cli-0.10.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.8.0"
+    __version__ = "0.10.0"

{forgeo_cli-0.8.0 → forgeo_cli-0.10.0}/src/forgeo/agent.py

@@ -206,7 +206,26 @@ class ShellAgent(BaseAgent):
         except TimeoutError:
             timed_out = True
             _kill_process_group(proc)
-            await proc.wait()
+            # ``proc.wait()`` waits for both process exit *and* pipe closure
+            # (see ``BaseSubprocessTransport._try_finish``).  A grandchild that
+            # called ``setsid()`` and holds the write end of the pipe keeps it
+            # open forever, so the wait would hang past the drain deadline.
+            # Bound it by ``drain_timeout_seconds`` and force-close the
+            # transport if it still hangs.
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=self.drain_timeout_seconds)
+            except TimeoutError:
+                try:
+                    proc._transport.close()  # type: ignore[attr-defined]
+                except Exception:  # noqa: BLE001, S110 - close must not fail the task
+                    pass
+                try:
+                    await asyncio.wait_for(proc.wait(), timeout=1.0)
+                except TimeoutError:
+                    logs.append(
+                        f"[{self.name}] Process did not exit within "
+                        f"{self.drain_timeout_seconds:g}s after kill; proceeding."
+                    )
         # Always finish draining so lines already written (and any residual
         # after kill) are captured before we build the result. Bounded: a
         # grandchild that escaped the process group (daemonized agent, docker
@@ -215,6 +234,11 @@ class ShellAgent(BaseAgent):
         try:
             await asyncio.wait_for(readers, timeout=self.drain_timeout_seconds)
         except TimeoutError:
+            readers.cancel()
+            try:
+                await readers
+            except asyncio.CancelledError:
+                pass
             logs.append(
                 f"[{self.name}] Output streams stayed open beyond "
                 f"{self.drain_timeout_seconds:g}s; proceeding without them."