forgeo-cli 0.12.0__tar.gz → 1.12.1__tar.gz

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.1] - 2026-09-09
+
+### Fixed
+
+- GitHub/GitLab backlogs preserve per-task customization when a task is created.
+- OAuth issue-backlog login supports browser URLs, callback ports, and config-relative tokens.
+
+### Removed
+
+- Unused `github.fields`/`gitlab.fields` field mapping (GitHub/GitLab issues have no custom fields).
+
 ## [0.12.0] - 2026-09-03
 
 ### Added
@@ -439,7 +450,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.12.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v1.12.1...HEAD
+[1.12.1]: https://github.com/lucaGazzola/forgeo/compare/v0.12.0...v1.12.1
 [0.12.0]: https://github.com/lucaGazzola/forgeo/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...v0.10.0

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.12.0
+Version: 1.12.1
 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
@@ -99,7 +99,7 @@ pipx install forgeo-cli                          # Python 3.11+
 forgeo init
 ```
 
-Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github`/`gitlab`/`jira` it auto-detects `owner/repo` and offers `PAT` (`GITHUB_TOKEN` → `~/.config/forgeo/`) or browser OAuth (`forgeo auth login` → `~/.config/forgeo/tokens/`).
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For issue providers it offers a PAT or OAuth login (`forgeo auth login` → `~/.config/forgeo/tokens/`); GitHub repository detection is automatic when possible, while Jira asks for its URL and JQL.
 
 ### 3. Fill the backlog
 
@@ -129,7 +129,8 @@ Each cycle: pick task → run agent → commit/push (or `REVIEW` branch when `re
 forgeo status              # config, counts, next task, daemon state, last outcome
 forgeo once                # one cycle in foreground, no daemon
 forgeo run --task TASK-012 # run a specific OPEN task now
-forgeo stop / restart      # stop or restart daemon
+forgeo stop                # stop daemon
+forgeo restart             # restart daemon
 forgeo web                 # dashboard for all instances
 ```
 

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/README.md

@@ -45,7 +45,7 @@ pipx install forgeo-cli                          # Python 3.11+
 forgeo init
 ```
 
-Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github`/`gitlab`/`jira` it auto-detects `owner/repo` and offers `PAT` (`GITHUB_TOKEN` → `~/.config/forgeo/`) or browser OAuth (`forgeo auth login` → `~/.config/forgeo/tokens/`).
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For issue providers it offers a PAT or OAuth login (`forgeo auth login` → `~/.config/forgeo/tokens/`); GitHub repository detection is automatic when possible, while Jira asks for its URL and JQL.
 
 ### 3. Fill the backlog
 
@@ -75,7 +75,8 @@ Each cycle: pick task → run agent → commit/push (or `REVIEW` branch when `re
 forgeo status              # config, counts, next task, daemon state, last outcome
 forgeo once                # one cycle in foreground, no daemon
 forgeo run --task TASK-012 # run a specific OPEN task now
-forgeo stop / restart      # stop or restart daemon
+forgeo stop                # stop daemon
+forgeo restart             # restart daemon
 forgeo web                 # dashboard for all instances
 ```
 

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/docs/backlog.md

@@ -150,7 +150,7 @@ backlog: https://api.example.com/backlog
 | Every read | `GET <url>` returns `{"tasks": [...]}` |
 | Every write | `POST <url>` sends the full document |
 
-Add `backlog_auth` for OAuth2. Same schema and ordering. Endpoint must:
+Add `backlog_auth` for OAuth2 client-credentials access to an HTTP backlog. This is a service-account flow, not the human browser login described for issue providers below. Same schema and ordering. Endpoint must:
 
 - Return `{"tasks": [...]}`; non-object or non-list → empty.
 - Replace, not append — POST body is the complete list.
@@ -178,7 +178,7 @@ jira:
 # jira:
 #   jql: 'project = APP AND labels = forgeo'
 #   auth:
-#     oauth: {client_id: xxxx, client_secret_env: JIRA_CLIENT_SECRET, scope: "offline_access read:jira-user read:jira-work"}
+#     oauth: {client_id: xxxx, client_secret_env: JIRA_CLIENT_SECRET, scope: "offline_access read:jira-user read:jira-work", flow: browser}
 # # then: forgeo auth login --provider jira --client-id xxxx
 ```
 
@@ -186,7 +186,7 @@ jira:
 - `open_statuses` = pickable; `running_status` = claimed before agent runs; `completed_status`/`blocked_status`/`failed_status` = terminal (blocked/failed optional — labels `forgeo-blocked`/`forgeo-failed` always applied).
 - Engine state (`blocker_reason`, `retry_count`, `agent_response`, etc.) in Jira issue property `forgeo`.
 - Optional `jira.fields` maps custom fields for `acceptance_criteria`, `dependencies`, etc. Without `run_at` mapping, Jira `duedate` is used at midnight UTC. Dependencies also inferred from `blocks` issue links.
-- Auth from env vars: `basic` (username + token) or `bearer` (PAT). Uses REST API v3 (`/search/jql` + cursor) by default; set `api_version: 2` for older servers.
+- Auth is exactly one of PAT from environment variables (`basic` username + token or `bearer` token) or Jira Cloud OAuth 3LO (`oauth`). Uses REST API v3 (`/search/jql` + cursor) by default; set `api_version: 2` for older servers. OAuth browser login stores the token outside the config and discovers `cloud_id`; keep the configured client-secret environment variable available for refresh.
 - Daemon paginates JQL; stale claims released after `claim_timeout_seconds`. Unavailable Jira fails the cycle.
 
 ## A GitHub backlog
@@ -196,14 +196,14 @@ jira:
 backlog_provider: github
 backlog: https://api.github.com   # or https://github.example.com/api/v3
 github: {repo: owner/repo, auth: {token_env: GITHUB_TOKEN}}
-# OAuth (browser/device):
+# OAuth (device or browser):
 # github: {repo: owner/repo, auth: {oauth: {client_id: Iv1.xxxx, flow: device, scope: repo}}}
 # # then: forgeo auth login --provider github --client-id Iv1.xxxx
 ```
 
 - Issue numbers → task IDs; `title`/`body`/`created_at`/`updated_at` → task fields.
-- `open` → `OPEN`, `closed` → `COMPLETED`; labels `forgeo-running`/`blocked`/`failed` for the rest.
-- Engine state in hidden `<!-- forgeo: {...} -->` block inside the body.
+- `open` → `OPEN`, `closed` → `COMPLETED`; labels `forgeo-running`/`forgeo-blocked`/`forgeo-failed` for the rest.
+- Per-task customization (`agent_command`, `agent_timeout_seconds`, `acceptance_criteria`, `dependencies`, `files_to_modify`, `run_at`, `retries_left`, `review_required`) and engine state both live in a hidden `<!-- forgeo: {...} -->` block inside the body. There is no `github.fields` custom-field mapping — GitHub issues expose no custom fields on the REST issues API.
 - Paginated `GET /repos/{owner}/{repo}/issues?state=all`; claiming adds `forgeo-running` + `claimed_at`.
 
 Test live with `scripts/test-github-backlog-e2e.sh`:
@@ -219,12 +219,12 @@ GITHUB_TOKEN=... ./scripts/test-github-backlog-e2e.sh
 backlog_provider: gitlab
 backlog: https://gitlab.example.com   # instance root, /api/v4 appended
 gitlab: {repo: group/project, auth: {token_env: GITLAB_TOKEN}}
-# OAuth (browser PKCE):
+# OAuth (browser PKCE, device if enabled by the instance):
 # gitlab: {repo: group/project, auth: {oauth: {client_id: abc, flow: browser, scope: api}}}
 # # then: forgeo auth login --provider gitlab --client-id abc
 ```
 
-- `iid` → task ID; `opened`/`closed` → `OPEN`/`COMPLETED`; same hidden-block and label mechanics as GitHub.
+- `iid` → task ID; `opened`/`closed` → `OPEN`/`COMPLETED`; labels `forgeo-running`/`forgeo-blocked`/`forgeo-failed`; same hidden-block mechanics as GitHub (per-task customization and engine state in a hidden `<!-- forgeo: {...} -->` block in the description). OAuth is an alternative to `token_env` and supports browser PKCE (or device flow when enabled by the GitLab instance).
 - Paginated `GET /api/v4/projects/:id/issues?state=all`.
 
 ## Managing tasks

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/docs/cli-reference.md

@@ -127,7 +127,9 @@ Table of all instances: name, daemon state, last outcome (from `runs.jsonl`). Ex
 
 ## `forgeo auth`
 
-Browser/OAuth login for `github`/`gitlab`/`jira` (alternative to `*_TOKEN` PAT). Tokens stored `0600` in `~/.config/forgeo/tokens/` and read by `forgeo validate`/`start`/`once`.
+Browser/OAuth login for `github`/`gitlab`/`jira` (alternative to a PAT in an environment variable). This is separate from `backlog_auth`, which uses OAuth2 client credentials for an HTTP backlog. Tokens are stored `0600` in `~/.config/forgeo/tokens/` and read by `forgeo validate`/`start`/`once`.
+
+Create an OAuth application with the provider before logging in. GitHub defaults to the device flow, GitLab defaults to browser PKCE, and Jira Cloud supports browser PKCE only. Browser flows listen on `127.0.0.1`; the port is ephemeral unless `--callback-port` is supplied. If the provider requires an exact registered redirect URI, register `http://127.0.0.1:<port>/callback` and use that same port in the command.
 
 ### `forgeo auth login --provider <github|gitlab|jira>`
 
@@ -136,17 +138,26 @@ Browser/OAuth login for `github`/`gitlab`/`jira` (alternative to `*_TOKEN` PAT).
 | `--provider` | `github` (default) / `gitlab` / `jira`. |
 | `--config <file>` | `forgeo.yaml` to read `auth.oauth.client_id` (defaults to `./forgeo.yaml`). |
 | `--client-id <id>` | OAuth client ID (overrides config; required if not in `forgeo.yaml`). |
-| `--flow <device|browser>` | `device` (GitHub CLI) / `browser` (PKCE loopback `127.0.0.1:0/callback`). Defaults: `device` for GitHub, `browser` for GitLab/Jira. |
+| `--flow <device|browser>` | `device` for GitHub, `browser` for GitLab/Jira. GitLab device flow is available only when enabled by the GitLab instance; Jira is browser-only. |
 | `--scope <scope>` | Scope (default `repo` / `api` / `offline_access read:jira-user read:jira-work`). |
 | `--token-file <path>` | Where to store token (default per-provider per-host `~/.config/forgeo/tokens/<provider>.json`). |
+| `--callback-port <port>` | Fixed `127.0.0.1` port for browser callbacks. Default is an ephemeral port; use this when the OAuth app requires an exact callback URI. |
+| `--cloud-id <id>` | Jira Cloud ID (overrides `jira.auth.oauth.cloud_id`). |
 | `--api-base <url>` | Provider API base (default from `forgeo.yaml` backlog or `https://api.github.com`/`https://gitlab.com`). |
-| `--no-open-browser` | Print URL instead of `webbrowser.open()`. |
+| `--no-open-browser` | Print the authorization URL instead of opening it automatically. Applies to browser and device flows. |
 
-Device flow: prints `https://github.com/login/device` + `user_code`, polls `…/login/oauth/access_token`. Browser flow: opens `…/oauth/authorize` + PKCE `code_challenge`, listens on loopback, exchanges `code` for `access_token` (`refresh_token` for Jira). `forgeo init` with `browser` writes `auth.oauth` and offers `Run browser login now?`.
+Device flow: prints a verification URL and user code, then polls the provider token endpoint. Browser flow: opens (or prints) the provider authorization URL with a PKCE `code_challenge`, listens on loopback, and exchanges the callback code for an access token. Jira also discovers an Atlassian `cloud_id` and stores a refresh token when one is returned. If `client_secret_env` is configured for Jira, export that variable for token refreshes by the daemon. `forgeo init` with OAuth writes `auth.oauth` and offers to run login immediately.
 
 ### `forgeo auth status --provider <p>` / `forgeo auth logout --provider <p>`
 
-`status` masks token (`ghp_…1234`), shows `scope`/`expires_in`/`cloud_id` (Jira). `logout` removes the file. Both honour `--token-file`/`--api-base`/`--config`.
+```bash
+forgeo auth status --provider github
+forgeo auth status --provider gitlab
+forgeo auth status --provider jira
+forgeo auth logout --provider github
+```
+
+`status` masks the token and shows `scope`/`expires_in`/`cloud_id` (Jira). `logout` removes the file. Both honor `--token-file`/`--api-base`/`--config` and use the project-local `forgeo.yaml` when it exists; pass `--config` for a config elsewhere.
 
 ## `forgeo web`
 

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/docs/configuration.md

@@ -96,13 +96,21 @@ jira:
 #       client_secret_env: JIRA_CLIENT_SECRET
 #       scope: offline_access read:jira-user read:jira-work
 #       token_file: ~/.config/forgeo/tokens/jira.json  # optional
+#       callback_port: 8765                         # optional fixed loopback port
 # # then: forgeo auth login --provider jira --client-id xxxx
 ```
 
 | Key | Default | Description |
 | --- | --- | --- |
 | `jira.jql` | — | JQL scope — include all lifecycle states. |
-| `jira.auth` | — | `basic` (username + token) or `bearer` (token). |
+| `jira.auth` | — | Exactly one of PAT (`basic`/`bearer` with `token_env`) or `oauth` (Jira Cloud browser PKCE). |
+| `jira.auth.oauth.client_id` | — | Atlassian OAuth app client ID. Required for OAuth. |
+| `jira.auth.oauth.client_secret_env` | — | Optional environment variable containing the OAuth client secret; required for refresh when the app is confidential. |
+| `jira.auth.oauth.scope` | — | Requested scopes; `offline_access read:jira-user read:jira-work` by default. |
+| `jira.auth.oauth.token_file` | per-host path | Token JSON file, mode `0600`; relative paths resolve from `forgeo.yaml`. |
+| `jira.auth.oauth.cloud_id` | — | Atlassian site ID; auto-detected after login when omitted. |
+| `jira.auth.oauth.flow` | `browser` | Browser PKCE only. |
+| `jira.auth.oauth.callback_port` | ephemeral | Fixed loopback port for browser login when the app requires an exact callback URI. |
 | `jira.project_key` | — | Project for dashboard task creation. |
 | `jira.issue_type` | `Task` | Issue type for creation. |
 | `jira.api_version` | `3` | `3` = Cloud cursor pagination, `2` = offset. |
@@ -136,13 +144,20 @@ github:
 #       flow: device              # device | browser
 #       scope: repo
 #       token_file: ~/.config/forgeo/tokens/github.json
+#       callback_port: 8765       # optional fixed loopback port for browser flow
 # # then: forgeo auth login --provider github --client-id Iv1.xxxx
 ```
 
 | Key | Default | Description |
 | --- | --- | --- |
 | `github.repo` | — | `owner/repo`. |
-| `github.auth` | — | `token_env` for PAT. |
+| `github.auth` | — | Exactly one of `token_env` (PAT) or `oauth`. |
+| `github.auth.oauth.client_id` | — | OAuth app client ID. Required for OAuth. |
+| `github.auth.oauth.flow` | `device` | `device` or `browser`. |
+| `github.auth.oauth.scope` | `repo` | OAuth scope. |
+| `github.auth.oauth.token_file` | per-host path | Token JSON file, mode `0600`; relative paths resolve from `forgeo.yaml`. |
+| `github.auth.oauth.callback_port` | ephemeral | Fixed loopback port for browser login when the app requires an exact callback URI. |
+| `github.auth.oauth.client_secret_env` | — | Optional environment variable containing a confidential browser-flow client secret. |
 | `github.label_prefix` | `forgeo` | Label prefix. |
 | `github.property_key` | `forgeo` | Marker key for hidden body block. |
 | `github.page_size` | `30` | Issues per page. |
@@ -150,9 +165,8 @@ github:
 | `github.timeout_seconds` | `30` | HTTP timeout. |
 | `github.claim_timeout_seconds` | `86400` | Stale claim timeout. |
 | `github.workflow` | defaults | State/label mapping. |
-| `github.fields` | — | Field mappings for `acceptance_criteria`, `dependencies`, `files_to_modify`, `agent_command`, `agent_timeout_seconds`, `run_at`, `retries_left`. |
 
-Issue numbers become task IDs; `open`/`closed` maps to `OPEN`/`COMPLETED`; `forgeo-running`/`blocked`/`failed` labels cover the rest. Engine state is stored in a hidden `<!-- forgeo: {...} -->` block in the issue body.
+Issue numbers become task IDs; `open`/`closed` maps to `OPEN`/`COMPLETED`; `forgeo-running`/`blocked`/`failed` labels cover the rest. GitHub issues expose no custom-field mechanism on the REST issues API, so per-task customization (`agent_command`, `agent_timeout_seconds`, `acceptance_criteria`, `dependencies`, `files_to_modify`, `run_at`, `retries_left`, `review_required`) and engine state both live in a hidden `<!-- forgeo: {...} -->` block in the issue body. Engine-managed fields (`retry_count`, `agent_response`, `failure_reason`, ...) are written by Forgeo and not meant to be edited by hand.
 
 ### GitLab
 
@@ -173,10 +187,33 @@ gitlab:
 #       flow: browser             # browser | device
 #       scope: api
 #       token_file: ~/.config/forgeo/tokens/gitlab.json
+#       callback_port: 8765        # optional fixed loopback port for browser flow
 # # then: forgeo auth login --provider gitlab --client-id abc123
 ```
 
-Same keys as GitHub (`gitlab.*`), including `workflow` and `fields` for the same 7 mappings. Issue `iid` becomes task ID; `opened`/`closed` maps to `OPEN`/`COMPLETED`; hidden `<!-- forgeo: {...} -->` block for engine state.
+Same backlog and task keys as GitHub (`gitlab.*`). Its auth must contain exactly one of `token_env` (PAT) or `oauth`; OAuth supports `client_id`, `flow`, `scope`, `token_file`, `callback_port`, and optional `client_secret_env`. Issue `iid` becomes task ID; `opened`/`closed` maps to `OPEN`/`COMPLETED`; per-task customization and engine state live in a hidden `<!-- forgeo: {...} -->` block in the issue description, as with GitHub.
+
+### Browser OAuth details
+
+For GitHub and GitLab, OAuth is an alternative to the provider PAT. For Jira, OAuth is available for Jira Cloud and is browser-only. Do not configure both `token_env` and `oauth` in the same provider; validation requires exactly one.
+
+The token file is outside `forgeo.yaml`, is written with mode `0600`, and defaults to a provider/host-specific file under `~/.config/forgeo/tokens/`. A relative `token_file` is resolved relative to the config file. A `client_secret_env` value is only an environment variable name; the secret itself must be exported before login and kept available to the daemon for refreshes.
+
+Browser login uses a loopback callback at `http://127.0.0.1:<port>/callback`. The default port is ephemeral. If the provider requires a pre-registered exact URI, register a fixed port in the OAuth application and pass it to login:
+
+```bash
+forgeo auth login --provider github --client-id Iv1.xxx --flow browser --callback-port 8765
+forgeo auth login --provider gitlab --client-id abc123 --callback-port 8765
+export JIRA_CLIENT_SECRET=...
+forgeo auth login --provider jira --client-id xxxx --callback-port 8765
+```
+
+Use `--no-open-browser` to print the authorization URL without opening it. After login, verify the provider-specific token and start the daemon:
+
+```bash
+forgeo auth status --provider github   # or gitlab / jira
+forgeo validate
+```
 
 ## Key details
 

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/docs/getting-started.md

@@ -28,11 +28,11 @@ forgeo init
 The wizard asks for:
 
 1. **Forgeo folder** — where backlog/logs live (default `.forgeo`, gitignored).
-2. **Backlog provider** — `file` (local JSON), `github`/`gitlab`/`jira`/`http`. For `github` it auto-detects `owner/repo` from `git remote` and can persist a pasted `GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`.
+2. **Backlog provider** — `file` (local JSON), `github`/`gitlab`/`jira`/`http`. For GitHub it auto-detects `owner/repo` from `git remote` and can persist a pasted `GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`.
 3. **Agent command** — bare command for your agent (default `opencode run --auto`). Forgeo appends the task prompt (`$FORGEO_TASK`); if your command already references `$FORGEO_TASK` it is kept verbatim.
 4. **Refactor prompt** — used when the backlog is empty.
 
-Writes `forgeo.yaml`, creates the folder, and appends it to `.gitignore` (opt-out available). With `github`/`gitlab`/`jira` it also sets `backlog_provider`, `backlog` URL, provider block, and `state_dir`. For `github`/`gitlab`/`jira` you can pick `PAT` or `browser` (OAuth) — browser stores a token in `~/.config/forgeo/tokens/`.
+Writes `forgeo.yaml`, creates the folder, and appends it to `.gitignore` (opt-out available). With `github`/`gitlab`/`jira` it also sets `backlog_provider`, `backlog` URL, provider block, and `state_dir`. For `github`/`gitlab`/`jira` you can pick `PAT` or OAuth. GitHub defaults to device flow; GitLab and Jira use browser PKCE. Browser tokens are stored in `~/.config/forgeo/tokens/`.
 
 ```bash
 forgeo init --force    # overwrite existing config
@@ -58,17 +58,25 @@ forgeo init --force    # overwrite existing config
 
 You can also add tasks from the dashboard once Forgeo is running — no file editing needed.
 
-**Remote providers** — `forgeo.yaml` already points at the provider. Authenticate with PAT **or** browser:
+**Remote providers** — `forgeo.yaml` already points at the provider. Authenticate with a PAT **or** browser OAuth:
 
 ```bash
 # PAT:
-export GITHUB_TOKEN=ghp_...   # or GITLAB_TOKEN / JIRA_USER + JIRA_TOKEN
-# Browser OAuth (device flow preferred for CLI):
-forgeo auth login --provider github --client-id Iv1.xxx   # or gitlab/jira
-forgeo auth status   # forgeo auth logout to clear
+export GITHUB_TOKEN=ghp_...   # or GITLAB_TOKEN / JIRA_TOKEN
+# GitHub OAuth (device flow by default):
+forgeo auth login --provider github --client-id Iv1.xxx
+# GitLab OAuth (browser PKCE):
+forgeo auth login --provider gitlab --client-id abc123
+# Jira Cloud OAuth (browser PKCE; export the configured secret for refresh):
+export JIRA_CLIENT_SECRET=...
+forgeo auth login --provider jira --client-id xxxx
+forgeo auth status --provider github   # use gitlab or jira for those providers
+forgeo auth logout --provider github
 forgeo validate
 ```
 
+Browser login uses an ephemeral loopback port by default. If the OAuth application requires an exact registered callback URL, register `http://127.0.0.1:8765/callback` and add `--callback-port 8765` to the login command. Use `--no-open-browser` when you want to open the printed authorization URL yourself. For a config outside the current directory, add `--config /path/to/forgeo.yaml` to the auth command.
+
 See [Backlog format](backlog.md) for Jira/GitHub/GitLab details. The dashboard for issue providers is a read-mostly mirror — triage stays in the native tracker.
 
 !!! tip

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/docs/web-console-api.md

@@ -6,7 +6,8 @@ The **central dashboard** (`forgeo web`) is the only web interface. Daemons bind
 forgeo web               # 0.0.0.0:8790 foreground
 forgeo web --port 9000 --host 127.0.0.1
 forgeo web -d            # background
-forgeo web status / stop
+forgeo web status
+forgeo web stop
 forgeo web --token       # bearer auth for /api/*
 ```
 

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/install.sh

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

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/pyproject.toml

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

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

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/src/forgeo/agent.py

@@ -51,11 +51,19 @@ def _kill_process_group(proc: asyncio.subprocess.Process) -> None:
     own session (``start_new_session=True``), so ``proc.pid`` is its process
     group id and killing the group reaps the entire process tree. Falls back
     to killing just the direct child when the group is already gone.
+
+    Platforms without process groups (Windows) fall back to killing the
+    direct child only.
     """
-    try:
-        os.killpg(proc.pid, signal.SIGKILL)
-    except (ProcessLookupError, PermissionError):
-        proc.kill()
+    killpg = getattr(os, "killpg", None)
+    if killpg is not None:
+        sigkill = getattr(signal, "SIGKILL", signal.SIGTERM)
+        try:
+            killpg(proc.pid, sigkill)
+        except (ProcessLookupError, PermissionError):
+            proc.kill()
+        return
+    proc.kill()
 
 
 class SandboxUnavailableError(RuntimeError):

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/src/forgeo/backlog_github.py

@@ -39,6 +39,7 @@ from forgeo.backlog_issue_base import (
     parse_numeric_issue_id,
     parse_optional_datetime,
     require_env_token,
+    task_engine_state,
 )
 from forgeo.models import ExecutionResult, GithubBacklogConfig, Task, TaskStatus
 
@@ -571,14 +572,8 @@ class GithubBacklog(IssueBacklogBase):
             return task
 
     async def create_task(self, task: Task) -> Task:
-        engine: dict[str, Any] = {
-            "state": TaskStatus.OPEN.value,
-            "acceptance_criteria": task.acceptance_criteria,
-            "dependencies": task.dependencies,
-            "files_to_modify": task.files_to_modify,
-        }
-        if task.review_required is not None:
-            engine["review_required"] = task.review_required
+        engine: dict[str, Any] = {"state": TaskStatus.OPEN.value}
+        engine.update(task_engine_state(task))
         fields: dict[str, Any] = {
             "title": task.title,
             "body": embed_engine_state(task.description, engine),
@@ -590,7 +585,9 @@ class GithubBacklog(IssueBacklogBase):
             if not isinstance(number, int):
                 raise GithubRequestError("GitHub create response did not contain an issue number")
             issue_id = str(number)
-            await self.put_engine_state(issue_id, {"state": TaskStatus.OPEN.value})
+            # The full state (including the author-set per-task customization) is
+            # embedded in the body at creation; do not re-write the marker here,
+            # or a bare {"state": "OPEN"} would clobber those fields.
             result = await self.get_task(issue_id)
             if result is None:
                 raise GithubRequestError(f"Created GitHub issue {issue_id} could not be read back")
@@ -619,20 +616,7 @@ class GithubBacklog(IssueBacklogBase):
                 fields["title"] = candidate.title
             if not ENGINE_STATE_FIELDS.isdisjoint(updates):
                 state = await self.get_engine_state(task_id)
-                state.update(
-                    {
-                        "acceptance_criteria": candidate.acceptance_criteria,
-                        "dependencies": candidate.dependencies,
-                        "files_to_modify": candidate.files_to_modify,
-                        "agent_command": candidate.agent_command,
-                        "agent_timeout_seconds": candidate.agent_timeout_seconds,
-                        "run_at": candidate.run_at.isoformat() if candidate.run_at else None,
-                        "retries_left": candidate.retries_left,
-                        "review_required": candidate.review_required,
-                        "review_branch": candidate.review_branch,
-                        "review_commit_sha": candidate.review_commit_sha,
-                    }
-                )
+                state.update(task_engine_state(candidate))
                 fields["body"] = embed_engine_state(candidate.description, state)
             if fields:
                 await self._call(self.client.update_issue, number, fields)

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/src/forgeo/backlog_gitlab.py

@@ -39,6 +39,7 @@ from forgeo.backlog_issue_base import (
     parse_numeric_issue_id,
     parse_optional_datetime,
     require_env_token,
+    task_engine_state,
 )
 from forgeo.models import ExecutionResult, GitlabBacklogConfig, Task, TaskStatus
 
@@ -550,14 +551,8 @@ class GitlabBacklog(IssueBacklogBase):
             return task
 
     async def create_task(self, task: Task) -> Task:
-        engine: dict[str, Any] = {
-            "state": TaskStatus.OPEN.value,
-            "acceptance_criteria": task.acceptance_criteria,
-            "dependencies": task.dependencies,
-            "files_to_modify": task.files_to_modify,
-        }
-        if task.review_required is not None:
-            engine["review_required"] = task.review_required
+        engine: dict[str, Any] = {"state": TaskStatus.OPEN.value}
+        engine.update(task_engine_state(task))
         fields: dict[str, Any] = {
             "title": task.title,
             "description": embed_engine_state(task.description, engine),
@@ -569,7 +564,9 @@ class GitlabBacklog(IssueBacklogBase):
             if not isinstance(iid, int):
                 raise GitlabRequestError("GitLab create response did not contain an issue iid")
             issue_id = str(iid)
-            await self.put_engine_state(issue_id, {"state": TaskStatus.OPEN.value})
+            # The full state (including the author-set per-task customization) is
+            # embedded in the description at creation; do not re-write the marker
+            # here, or a bare {"state": "OPEN"} would clobber those fields.
             result = await self.get_task(issue_id)
             if result is None:
                 raise GitlabRequestError(f"Created GitLab issue {issue_id} could not be read back")
@@ -598,20 +595,7 @@ class GitlabBacklog(IssueBacklogBase):
                 fields["title"] = candidate.title
             if not ENGINE_STATE_FIELDS.isdisjoint(updates):
                 state = await self.get_engine_state(task_id)
-                state.update(
-                    {
-                        "acceptance_criteria": candidate.acceptance_criteria,
-                        "dependencies": candidate.dependencies,
-                        "files_to_modify": candidate.files_to_modify,
-                        "agent_command": candidate.agent_command,
-                        "agent_timeout_seconds": candidate.agent_timeout_seconds,
-                        "run_at": candidate.run_at.isoformat() if candidate.run_at else None,
-                        "retries_left": candidate.retries_left,
-                        "review_required": candidate.review_required,
-                        "review_branch": candidate.review_branch,
-                        "review_commit_sha": candidate.review_commit_sha,
-                    }
-                )
+                state.update(task_engine_state(candidate))
                 fields["description"] = embed_engine_state(candidate.description, state)
             if fields:
                 await self._call(self.client.update_issue, iid, fields)

{forgeo_cli-0.12.0 → forgeo_cli-1.12.1}/src/forgeo/backlog_issue_base.py

@@ -300,6 +300,31 @@ ENGINE_STATE_FIELDS: frozenset[str] = frozenset(
 )
 
 
+def task_engine_state(task: Any) -> dict[str, Any]:
+    """The author-controlled task fields stored in the hidden engine-state marker.
+
+    These are the per-task customization fields the human sets (as opposed to
+    engine-managed runtime state such as ``retry_count`` or ``agent_response``).
+    GitHub and GitLab issues expose no portable custom-field mechanism on their
+    REST issues API, so these fields travel in the hidden ``<!-- forgeo: ... -->``
+    marker; Jira maps them to custom fields instead. ``None`` values are kept
+    so a marker written by ``create_task`` and one refreshed by ``update_task``
+    stay identical, and absent values read back as ``None`` either way.
+    """
+    return {
+        "acceptance_criteria": task.acceptance_criteria,
+        "dependencies": task.dependencies,
+        "files_to_modify": task.files_to_modify,
+        "agent_command": task.agent_command,
+        "agent_timeout_seconds": task.agent_timeout_seconds,
+        "run_at": task.run_at.isoformat() if task.run_at is not None else None,
+        "retries_left": task.retries_left,
+        "review_required": task.review_required,
+        "review_branch": task.review_branch,
+        "review_commit_sha": task.review_commit_sha,
+    }
+
+
 # ------------------------------------------------------------------ #
 # Shared HTTP / auth helpers                                          #
 # ------------------------------------------------------------------ #