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

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

@@ -7,6 +7,27 @@ 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
+
+- Browser-based OAuth login for GitHub, GitLab, and Jira, with cached tokens and setup guidance.
+
+### Fixed
+
+- Stabilized the CI lint configuration.
+
 ## [0.11.0] - 2026-08-31
 
 ### Added
@@ -429,7 +450,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.11.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
 [0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.11.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` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+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.11.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` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+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.11.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.
@@ -166,6 +166,7 @@ Runtime files (`backlog.lock`, `runs.jsonl`, etc.) go in `state_dir` (defaults t
 ## A Jira backlog
 
 ```yaml
+# PAT:
 backlog_provider: jira
 backlog: https://jira.example.com
 jira:
@@ -173,26 +174,36 @@ jira:
   project_key: APP
   auth: {scheme: basic, username_env: JIRA_USER, token_env: JIRA_TOKEN}
   workflow: {open_statuses: ["10000", "10001"], open_status: "10000", running_status: "3", completed_status: "10002"}
+# OAuth 3LO (Cloud):
+# 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", flow: browser}
+# # then: forgeo auth login --provider jira --client-id xxxx
 ```
 
 - Jira keys → task IDs; `summary`/`description`/`created`/`updated` → task fields.
 - `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
 
 ```yaml
+# PAT:
 backlog_provider: github
 backlog: https://api.github.com   # or https://github.example.com/api/v3
-github: {repo: owner/repo, token_env: GITHUB_TOKEN}
+github: {repo: owner/repo, auth: {token_env: GITHUB_TOKEN}}
+# 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`:
@@ -204,12 +215,16 @@ GITHUB_TOKEN=... ./scripts/test-github-backlog-e2e.sh
 ## A GitLab backlog
 
 ```yaml
+# PAT:
 backlog_provider: gitlab
 backlog: https://gitlab.example.com   # instance root, /api/v4 appended
-gitlab: {repo: group/project, token_env: GITLAB_TOKEN}
+gitlab: {repo: group/project, auth: {token_env: GITLAB_TOKEN}}
+# 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.11.0 → forgeo_cli-1.12.1}/docs/cli-reference.md

@@ -125,6 +125,40 @@ Unregister (never touches config/repo). Errors if unknown.
 
 Table of all instances: name, daemon state, last outcome (from `runs.jsonl`). Exits `0` with hint if none.
 
+## `forgeo auth`
+
+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>`
+
+| Flag | Description |
+| --- | --- |
+| `--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` 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 the authorization URL instead of opening it automatically. Applies to browser and device flows. |
+
+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>`
+
+```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`
 
 Central dashboard aggregating every registered instance (reads files directly, works whether daemons are running).

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

@@ -70,6 +70,7 @@ Add `backlog_auth` for OAuth2-protected HTTP endpoints (see below). A failed HTT
 ### Jira
 
 ```yaml
+# PAT / basic (Server/DC):
 backlog_provider: jira
 backlog: https://jira.example.com
 state_dir: .forgeo
@@ -86,12 +87,30 @@ jira:
     open_status: "10000"
     running_status: "3"
     completed_status: "10002"
+# OAuth 3LO (Cloud, browser):
+# 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
+#       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. |
@@ -109,17 +128,36 @@ Status values can be names or IDs (IDs preferred). Jira keys become task IDs. En
 ### GitHub
 
 ```yaml
+# PAT:
 backlog_provider: github
 backlog: https://api.github.com   # or https://github.example.com/api/v3
 github:
   repo: owner/repo
-  token_env: GITHUB_TOKEN
+  auth:
+    token_env: GITHUB_TOKEN
+# OAuth / browser (device flow for CLI, browser PKCE):
+# github:
+#   repo: owner/repo
+#   auth:
+#     oauth:
+#       client_id: Iv1.xxxx
+#       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. |
@@ -127,21 +165,55 @@ 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
 
 ```yaml
+# PAT:
 backlog_provider: gitlab
 backlog: https://gitlab.example.com   # instance root, /api/v4 appended
 gitlab:
   repo: group/project
-  token_env: GITLAB_TOKEN
+  auth:
+    token_env: GITLAB_TOKEN
+# OAuth (browser PKCE, device if enabled):
+# gitlab:
+#   repo: group/project
+#   auth:
+#     oauth:
+#       client_id: abc123
+#       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.11.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`.
+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,13 +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. Export credentials and validate:
+**Remote providers** — `forgeo.yaml` already points at the provider. Authenticate with a PAT **or** browser OAuth:
 
 ```bash
-export GITHUB_TOKEN=ghp_...   # or GITLAB_TOKEN / JIRA_USER + JIRA_TOKEN
+# PAT:
+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.11.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.11.0 → forgeo_cli-1.12.1}/install.sh

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.11.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"
@@ -61,6 +61,9 @@ asyncio_default_fixture_loop_scope = "function"
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
 [tool.mypy]
 python_version = "3.11"
 mypy_path = "src"

{forgeo_cli-0.11.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.11.0"
+    __version__ = "1.12.1"

{forgeo_cli-0.11.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.11.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
 
@@ -57,11 +58,43 @@ class GithubClient:
     def __init__(self, base_url: str, config: GithubBacklogConfig) -> None:
         self.base_url = base_url.rstrip("/")
         self.config = config
+        self._oauth_provider: Any | None = None  # lazy GithubOAuthTokenProvider when oauth is used
+
+    def _oauth_token_provider(self) -> Any | None:
+        if self._oauth_provider is not None:
+            return self._oauth_provider
+        auth = self.config.auth
+        if auth.oauth is None:
+            return None
+        from forgeo.oauth_github import GithubOAuthTokenProvider, GithubTokenStore
+
+        token_file = auth.oauth.token_file
+        store = GithubTokenStore(path=token_file, api_base=self.base_url) if token_file is not None else GithubTokenStore(api_base=self.base_url)
+        provider = GithubOAuthTokenProvider(store)
+        self._oauth_provider = provider
+        return provider
 
     def _auth_header(self) -> str:
-        token = require_env_token(self.config.auth.token_env, "GitHub", GithubRequestError)
-        # GitHub accepts Bearer or token; use Bearer for consistency
-        return f"Bearer {token}"
+        auth = self.config.auth
+        if auth.token_env is not None:
+            token = require_env_token(auth.token_env, "GitHub", GithubRequestError)
+            return f"Bearer {token}"
+        if auth.oauth is not None:
+            provider = self._oauth_token_provider()
+            assert provider is not None
+            try:
+                token = provider.token()
+            except Exception as exc:
+                # Wrap file errors as GithubRequestError so callers surface a clear message
+                if isinstance(exc, GithubRequestError):
+                    raise
+                from forgeo.oauth_github import GithubOAuthError
+
+                if isinstance(exc, GithubOAuthError):
+                    raise GithubRequestError(str(exc)) from exc
+                raise GithubRequestError(str(exc)) from exc
+            return f"Bearer {token}"
+        raise GithubRequestError("GitHub auth is not configured (token_env or oauth required)")
 
     def _api_url(self, path: str, query: dict[str, Any] | None = None) -> str:
         url = f"{self.base_url}{path}"
@@ -77,23 +110,42 @@ class GithubClient:
         query: dict[str, Any] | None = None,
         payload: dict[str, Any] | None = None,
     ) -> Any:
-        body = None
-        if payload is not None:
-            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
-        request = urllib.request.Request(
-            self._api_url(path, query),
-            data=body,
-            method=method,
-            headers={
-                "Accept": "application/vnd.github+json",
-                "Authorization": self._auth_header(),
-                "X-GitHub-Api-Version": "2022-11-28",
-                **({"Content-Type": "application/json"} if body is not None else {}),
-            },
-        )
-        return execute_json_request(
-            request, self.config.timeout_seconds, GithubRequestError, method
-        )
+        # Retry once when GitHub rejects an OAuth token (revoked/expired)
+        for attempt in (0, 1):
+            body = None
+            if payload is not None:
+                body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            auth_header = self._auth_header()
+            request = urllib.request.Request(
+                self._api_url(path, query),
+                data=body,
+                method=method,
+                headers={
+                    "Accept": "application/vnd.github+json",
+                    "Authorization": auth_header,
+                    "X-GitHub-Api-Version": "2022-11-28",
+                    **({"Content-Type": "application/json"} if body is not None else {}),
+                },
+            )
+            try:
+                return execute_json_request(
+                    request, self.config.timeout_seconds, GithubRequestError, method
+                )
+            except GithubRequestError as exc:
+                # On 401/403 with OAuth, invalidate cache and retry once so a freshly
+                # written token (e.g. after `forgeo auth login`) is picked up.
+                if (
+                    attempt == 0
+                    and exc.status in (401, 403)
+                    and self.config.auth.oauth is not None
+                    and self._oauth_provider is not None
+                ):
+                    try:
+                        self._oauth_provider.invalidate()  # noqa: BLE001
+                    except Exception:  # noqa: BLE001
+                        pass
+                    continue
+                raise
 
     def _repo_path(self) -> str:
         # GitHub API expects owner/repo as two separate path segments;
@@ -520,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),
@@ -539,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")
@@ -568,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)