@giamme/forge 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and versions follow the format `{major}.{minor}[.{patch}]` ([...] parts appear only when non-zero).
 
+## [0.10] - 2026-10-23
+
+forge-ui can now change a run: live QA threshold, retries and timeout, a one-shot model pin, open findings filed as GitHub issues, deleting runs while the dataset keeps them, and every config source in one view. Each control is also a forge CLI: forge control, forge runs rm, forge config and new forge issues modes.
+
+### Highlights
+
+- After a run, review findings nobody would act on can become GitHub issues: forge offers once to file the findings `--qa-threshold` tolerated, the PLAUSIBLE ones and whatever a whole-run review left open. Where the gh-proman skill is set up for the repository they go on the project board through it; anywhere else forge files them itself with plain `gh` (`forge issues <plan-dir>`). A finding is never filed twice. `--file-issues auto` files them without asking, `--file-issues off` never offers.
+- `forge control show|set|pin|unpin <plan-dir>` changes a plan while it runs: the QA threshold (read once per attempt, per task too, and `none` exempts a task), the timeout, `--escalate-after`, verify retries, and, while a scheduler is live, the retry and infrastructure-retry budgets. The budgets keep their per-invocation rule: a live scheduler publishes them for the length of the run and re-reads them at every decision. Every change is validated, logged in `control.log` and recorded in the dataset as a `control` event.
+- forge-ui has an Open findings view: the findings a run, or every run of its repository, left open, with their filed state. Select some to file as GitHub issues or dismiss ones that need no work. `forge issues` gains `--offline`, `--only`, `--all-runs`, `--dismiss`/`--undismiss` (with `--reason`), `--include-dismissed` and a `findings` list in its JSON; the whole-run review's findings are now collected, and filing and dismissal take a repository lock (exit 3 when busy).
+- `forge runs rm <run-dir>` deletes a run while the dataset keeps what it taught: a strict import, a self-describing archive (`FORGE_ARCHIVE.json`), and `run_delete_started` and `run_deleted` events, all under the run's own lock. `--worktrees` and `--branches` also remove the run's clean worktrees and its unchecked-out branches (foreign and dirty worktrees and UNMERGED branches are reported); `--dry-run` previews. forge-ui has a matching delete dialog. The dataset also imports `escalations.tsv` and `control.log`.
+- forge-ui is no longer read-only: it gains write endpoints and Controls panels for a run and for each task (QA threshold, timeout, escalate-after, verify retries, budgets, threshold override, retry budget, model pin). It only ever calls forge's own CLIs, and every change must carry a per-launch token and pass the Host and Origin checks. `--read-only` (or `FORGE_UI_READONLY=1`) turns writing off, and `forge ui open` never reuses a server running in the other mode.
+
+### Added
+
+- `forge control pin <plan-dir> <task> <spec>` sets the model a task's next full retry uses, once: the spec is checked with `forge-dispatch.sh doctor` (no quota), applied at the retry and written to `tasks.tsv`, and `escalations.tsv` gains a `source` column (`policy`, `retry` or `pin`) saying who decided. `forge control unpin` drops it; Fractal plans never apply pins.
+- `forge config show|set|unset` shows every config source in one view (the registry, Jev, a repository's `.forge/verify`, `setup` and `verify-subset`, the dataset and `FORGE_*` variables with secrets hidden) and edits the per-repo files and `jev.enabled`. forge-ui shows the same view as Settings.
+
+### Changed
+
+- A repeated `forge ui open` for a run that already has a browser tab no longer looks like it did nothing: it prints the link as before and says on stderr that no new tab was opened, so you know to use the link.
+
+### Fixed
+
+- `forge ui open DIR` now reads only the first line of the run's `repo` file, as the runners do, so a run whose `repo` file has extra lines is listed under its real repo instead of under a path that does not exist.
+- A forge-ui export no longer leaks a local path spelled another way: the run, repository and home paths are also scrubbed in their real form (on macOS, `/private/var/...` and `/var/...`).
+
 ## [0.9] - 2026-10-21
 
 forge-ui has a new look and layout, a 3D stage that marks every review finding on its task, and each dwarf's and reviewer's conversation, which runs on claude, openclaude and opencode now keep in full. Also new: `forge runs` and a first screen that says how to get runs; npm installations now hear about new releases.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: forge
 description: Dispatch implementation and independent diff review to user-selected models through local agent CLIs. Use for /forge or explicit requests to delegate coding or review; explanation-only questions do not authorize dispatch.
-argument-hint: '"<goal>" --dwarf <alias>[:effort[:harness]] [--qa <alias>] [--planner <alias>] [--yolo-dwarf] [--yolo-qa] [--decompose-level low|medium|high] [--fractal|--no-fractal|--fractal-auto-decompose] [--fractal-planner <spec>] [--jev|--no-jev] [--jev-shadow] [--no-memory] [--no-ripwire] [--ui|--no-ui] [--timeout <seconds>] [--retry-failed <n>] [--escalate-after <n>] [--qa-threshold P0|P1|P2|P3] [--shadow-qa <spec>[,<spec>]] [--shadow-rate <0..1>] [--explore <0..0.5>] [--fail-first]'
+argument-hint: '"<goal>" --dwarf <alias>[:effort[:harness]] [--qa <alias>] [--planner <alias>] [--yolo-dwarf] [--yolo-qa] [--decompose-level low|medium|high] [--fractal|--no-fractal|--fractal-auto-decompose] [--fractal-planner <spec>] [--jev|--no-jev] [--jev-shadow] [--no-memory] [--no-ripwire] [--ui|--no-ui] [--timeout <seconds>] [--retry-failed <n>] [--escalate-after <n>] [--qa-threshold P0|P1|P2|P3] [--file-issues ask|auto|off] [--shadow-qa <spec>[,<spec>]] [--shadow-rate <0..1>] [--explore <0..0.5>] [--fail-first]'
 allowed-tools: [Bash, Read]
 ---
 
@@ -55,10 +55,28 @@ For explanation requests, explain the workflow without spending model quota.
   (`--escalate-after N`, `0` = off); an explicit `retry --dwarf` overrides it. `accept`
   overrides a reviewer, so run it (with the user's `--reason` and
   `--approved`) only on the user's explicit instruction; never self-accept.
+- When you report a run, read `<plan>/control.log` and mention any human change made mid-run
+  (a threshold, a budget, a model pin; `forge control show <plan>` lists them). Never set a
+  control, pin or delete a run with `forge control` / `forge runs rm` unless the user asks.
 - Exit `8` / status `INFRA` is a quota, auth or network stop, not a task failure and no
   attempt was spent: report it, say what to fix, and re-run only when told. For a multi-task
   plan, offer the opt-in whole-run review (`review`, or `integrate --final-review <qa-spec>`);
   it spends QA quota, so never run it unprompted.
+- **Leftover findings become issues.** A run can finish with review findings nobody will act on:
+  - CONFIRMED findings that `--qa-threshold` tolerated (`tasks/<id>/known_issues.md`);
+  - PLAUSIBLE findings in a passed task's `qa.last`;
+  - whatever a whole-run review left open.
+
+  When there are any, act on the user's `--file-issues` choice with one filer:
+  - **gh-proman**, only when it is installed and set up for the repository: `gh-proman -C <repo> config show` exits 0. It also puts the issues on the team's board with a priority. Run `gh-proman findings --from <plan or run dir> --include-plausible --json`, then follow the gh-proman skill's review-findings steps.
+  - **forge's own filer** otherwise (gh-proman missing, or not configured for this repo; never configure it yourself): `python3 <skill_dir>/scripts/forge-issues.py <plan or run dir> --include-plausible --json`, plain `gh issue create`. Pass `--lang` matching the repo's existing issues, and `--label bug` when the repo has that label. If `gh` is missing, unauthenticated or the repo has no GitHub remote, list the findings in the report and say why none were filed.
+
+  The choice:
+  - `ask` (the default): show the dry-run summary (count by severity, titles, anything already filed) and ask once: **"File these N findings as GitHub issues? [all / CONFIRMED only / none]"**. Then re-run with `--apply`, adding `--include-plausible` only for "all".
+  - `auto`: file them without asking (`--apply`, PLAUSIBLE included as "to verify" issues) and report what was created and skipped.
+  - `off`: never offer.
+
+  `--file-issues` is an instruction to you: never forward it to a runner. Skip INFRA, interrupted and still-failing runs. Both filers mark each issue with the same finding fingerprint and skip a finding either one already filed, so offering again after a retry only brings up new ones. A draft flagged as a possible duplicate is skipped on `--apply`: show it, and file it (`--confirm-new`) only if the user says it is different.
 - Jev is optional, off unless configured and enabled, and always advisory: it never
   changes a task's tier, never selects a model, and never substitutes for QA acceptance
   or repository verification (`--jev-act` is still accepted and changes nothing). Read

package/VERSION

@@ -1 +1 @@
-0.9
+0.10

package/docs/artifacts.md

@@ -48,9 +48,16 @@ A decomposed run adds:
   tasks/<id>/known_issues.md, qa.gate  findings tolerated by --qa-threshold, and the gate's decision
   tasks/<id>/guard.txt                 what forge observed about the implementer (self-commit, orphans, promises)
   tasks/<id>/infra.txt, resume, noretry  infrastructure stop record; QA-only resume marker; no-progress marker
-  tasks/<id>/qa_threshold              optional per-task blocking threshold
+  tasks/<id>/qa_threshold              optional per-task blocking threshold: P0-P3, or none (exempt from the plan's)
+  tasks/<id>/escalations.tsv           epoch, attempt, from-spec, to-spec, source (policy|retry|pin); older rows have 4 columns
+  tasks/<id>/escalation.pin            a human's one-shot model for the next full retry: one dwarf spec on one line
+  tasks/<id>/escalation.pin.applying   the pin while a retry has claimed it; removed once the retry is recorded
+  tasks/<id>/retry_budget, retries.used   live per-task retry budget (a number); retries spent (kept after the run)
   results.tsv                          id  status  branch
-  timeout, qa_threshold, verify_retries  options remembered from run/retry flags
+  timeout, qa_threshold, verify_retries  options remembered from run/retry flags (also escalate_after)
+  control.log                          one JSON line per human change made with forge control
+  scheduler.live, control.lock         only while a scheduler runs: {"pid", "started"}; the lock serialises forge control
+  retry_budget, infra_budget           only while a scheduler runs: its live budgets (a number each)
   integration.base                     commit the integration branch started from
   verification.{status,exit,log,command,fingerprint}   the combined verification
   verification.{flaky,retry.log}       only when a failing command passed on rerun
@@ -65,5 +72,13 @@ forge/<run-id>/<task-id>                         task branch
 forge/<run-id>-integration                       integration branch
 ```
 
+`control.log` lines look like
+`{"at": 1761200000.5, "actor": "ui", "action": "set", "task": null, "key": "qa-threshold", "value": "P2", "previous": "P1"}`
+(`actor` is `cli` or `ui`; `action` is `set`, `pin` or `unpin`; `key` is the control's name, or `pin`; `task` is null for a plan-wide
+control). `scheduler.live`, `retry_budget`, `infra_budget` and the per-task `retry_budget` exist
+only while the scheduler is live: it publishes the flags it was given when it starts, re-reads them
+at every decision and removes them when it stops, which is why `forge control` refuses a budget
+change outside a live run. See [live controls](decomposed-runs.md#changing-a-run-while-it-works).
+
 The worktree root is a **sibling of the repo, never `TMPDIR`**. Isolated worktrees are never
 pushed, so a temp root that gets cleaned takes the only copy of that work with it.

package/docs/commands.md

@@ -16,11 +16,61 @@ harness (`/forge`); this command installs forge and drives its optional tools.
 | `forge version [--check]` | the installed version, and whether a newer release is out |
 | `forge fractal …` | opt-in Fractal execution; see [the command group](fractal.md#forge-fractal-command-group) |
 | `forge runs [--repo DIR \| --all] [--limit N] [--json]` | this repo's recent runs, newest first: run id, kind, age, task states, verification and final review, goal, and the run dir. Read-only; the same summaries forge-ui shows |
+| `forge control show\|set\|pin\|unpin PLAN_DIR …` | change a live plan: `set` takes `qa-threshold`, `timeout`, `escalate-after`, `verify-retries`, `retry-budget` or `infra-retries` (the last two only while a scheduler runs; `--task ID` for `qa-threshold` and `retry-budget`, value `inherit` drops the override); `pin PLAN_DIR TASK SPEC` sets the model the task's next full retry uses once, `unpin` drops it; `--json`. Every change is logged in `control.log`. See [live controls](decomposed-runs.md#changing-a-run-while-it-works) |
+| `forge config show\|set\|unset [--repo DIR] [--json]` | one view of every config source (registry, Jev, the repo's `.forge/verify`, `setup` and `verify-subset`, dataset, `FORGE_*` variables with secrets hidden); `set KEY VALUE` / `unset KEY` edit `repo.verify`, `repo.setup`, `repo.verify-subset` (must contain `{files}`) and, for `set`, `jev.enabled true\|false`. `-` as a value reads stdin. Exit 2 on invalid input |
+| `forge runs rm RUN_DIR [--dry-run] [--yes] [--no-archive] [--worktrees] [--branches] [--json]` | delete a run directory but keep what it taught the dataset; see [below](#forge-runs-rm) |
+| `forge issues RUN [--apply] …` | file the review findings a run left open as GitHub issues; see [below](#forge-issues) |
 | `forge ui open\|status\|stop` | forge-ui, the run viewer; see [the command group](forge-ui.md#forge-ui-command-group) |
 | `forge dataset …` | every run's inputs and outcomes; see [run dataset](dataset.md) |
 | `forge jev …` | optional Jev advice: setup, status, doctor, enable, disable, backtest; see [Jev](add-ons.md#jev) |
 | `forge --help` | list the commands; `forge <command> --help` shows each one's options |
 
+### `forge runs rm`
+
+Deletes a run directory (a plan dir or a solo run dir) without losing its traces. It holds the
+run's own lock from the first step to the last (`schedule.lock` of a plan, `pipeline.lock` of a
+solo run), so a run started meanwhile fails to start instead of racing the delete. In order:
+
+1. **preserve**: a strict dataset import of the run; every event must be stored, or nothing is deleted;
+2. **archive**: a self-describing `.tar.gz` under `<data home>/archive/` (`--no-archive` skips it);
+3. **intent**: the dataset event `run_delete_started`;
+4. `--worktrees` removes the run's clean worktrees; `--branches` runs `git branch -D` on its
+   branches that no worktree has checked out;
+5. the run directory is removed, `run_deleted` is recorded and the run leaves the registry.
+
+What counts as the run's is decided from the run id, not read from the run directory: a worktree
+under `<repo>/../.forge-worktrees/<run id>/` on `forge/<run id>/<task>` or
+`forge/<run id>-integration`. Any other worktree there is `foreign`, one with uncommitted changes
+is `dirty`; neither is touched, and a dirty one keeps the run directory too. Branches are reported
+`merged` or `UNMERGED`, so you see what deleting them would lose. `--dry-run` changes nothing and
+reports; `--yes` skips the prompt for the run id (needed without a terminal); `--json` prints one
+object, on failure too. Exit 0 ok, 2 refused input, 3 busy or the run is active, 4 failed during
+deletion or the run directory was kept (the same command finishes the job).
+
+### `forge issues`
+
+`forge issues <plan dir, task dir, review dir, known_issues.md or qa.last>` drafts one GitHub
+issue per finding the run left open (`--group task|run` for fewer) and files them only with
+`--apply`. The findings are the CONFIRMED ones `--qa-threshold` tolerated, PLAUSIBLE ones with
+`--include-plausible`, and what the whole-run review left open. Each issue carries a hidden
+fingerprint, so a finding is never filed twice, by this command or by gh-proman. Also:
+`--min-severity`, `--repo`, `--lang`, `--label`, `--confirm-new`, `--max-issues` (default 10; pass
+the size of a `--only` selection).
+
+| Flag | Does |
+|---|---|
+| `--json` | machine-readable output; `findings` lists each one with its fingerprint, severity, origin, task, `filed` state and `dismissed` mark |
+| `--offline` | never run `gh`: no filed state, commit publication judged from local refs |
+| `--only FP` | keep only these 12-hex fingerprints (repeatable or comma-separated) |
+| `--all-runs` | read `RUN` as a repository (or a plan dir naming one) and collect every run in its registry; the newest plan wins for a finding in several |
+| `--dismiss FP`, `--undismiss FP`, `--reason TEXT` | mark findings as needing no work (or take it back), then exit; no network. The marks live outside the repo, in `${XDG_STATE_HOME:-~/.local/state}/forge/findings/<repo key>.json` |
+| `--include-dismissed` | draft dismissed findings too |
+
+Two filers for one repository at once would both see a finding as unfiled, so `--apply` takes a
+repository lock from the issue lookup to the last `gh issue create`, and each dismissal takes it
+around its write. A busy lock is retried for 10 s, then exit 3. Exit 0 ok, 2 usage or a `gh` or
+dismissal-store error, 3 busy.
+
 ## The `/forge` slash command
 
 ```

package/docs/dataset.md

@@ -16,5 +16,14 @@ forge dataset export            # labeled decision cases for benchmarks and fine
 forge dataset outcomes          # which integrated lines survived, read from git history
 ```
 
+Deleting a run keeps what it taught the dataset. `forge runs rm <run-dir>` first imports the run
+**strictly** (every event must be stored, or nothing is deleted), then writes a self-describing
+archive under `<data home>/archive/`: a `.tar.gz` whose `FORGE_ARCHIVE.json` records the run
+dir's original path, run id and dataset uid, so `forge dataset import` maps it back to the same
+run later. It records `run_delete_started` and `run_deleted` events around the removal. The same
+import also reads a plan's `escalations.tsv` (with who decided: `policy`, `retry` or `pin`) and
+`control.log`, so human interventions made with `forge control` are in the dataset as
+`control` events. See [forge runs rm](commands.md#forge-runs-rm).
+
 Capture is fail-open and never read by anything that builds a prompt. See
 [references/dataset.md](../references/dataset.md) for the event schema and its invariants.

package/docs/decomposed-runs.md

@@ -200,6 +200,48 @@ and pipeline checkpoints. A task/subtree selector resumes only that execution sc
 Explicit `retry` retains the backend and frozen pools; a replacement dwarf must already
 belong to that pool. See [recovery](../references/fractal.md#limits-and-lifecycle).
 
+## Changing a run while it works
+
+`forge control` changes a plan's knobs without stopping it (forge-ui calls the same command):
+
+```bash
+forge control show <plan-dir> [--json]                    # every control, per-task overrides, pins, recent changes
+forge control set <plan-dir> qa-threshold P2              # also --task <id>; P0-P3, none, or inherit (task only)
+forge control set <plan-dir> retry-budget 3 [--task <id>] # automatic retries; live scheduler only
+forge control set <plan-dir> infra-retries 2              # infrastructure waits; live scheduler only
+forge control set <plan-dir> timeout|escalate-after|verify-retries <n>
+forge control pin <plan-dir> <task> sol:high:codex        # the model the next full retry uses, once
+forge control unpin <plan-dir> <task>
+```
+
+Each change is validated, written under `control.lock`, and says when it applies:
+
+- **The QA threshold is read once per attempt**, at the start of the task's next attempt; the
+  attempt already running keeps the one it began with, so a verdict is never judged by a bar that
+  moved under it. A per-task `none` exempts that task from the plan's threshold; `inherit` drops
+  the override. A plan-level `none` clears the threshold.
+- **Budgets stay "per invocation".** `run --retry-failed N` and `--infra-retries M` still apply
+  only to the invocation that was given them and are not remembered; the next `run` starts
+  from its own flags. A rule that came back from an old file would silently spend money nobody
+  asked for. While a scheduler is live it mirrors them into the plan (`retry_budget`,
+  `infra_budget`, `tasks/<id>/retry_budget`) and re-reads them at every decision, which is what
+  `forge control` edits. When the scheduler stops it removes them; so a budget can only be changed
+  while a run is live (exit 3 otherwise), and the change dies with the run.
+  `tasks/<id>/retries.used` counts the retries spent and stays after the run for forge-ui.
+- **A pin is one-shot.** `pin` makes the task's next *full* retry use that spec (checked with
+  `forge-dispatch.sh doctor`, which spends no quota). A QA-only resume spends no implementer
+  attempt and leaves the pin for later. The retry applies it, writes it into `tasks.tsv`, records
+  an `escalations.tsv` row with `source` `pin`, clears any `split.suggested` stop and consumes
+  it. Fractal plans never apply pins, and a MERGED task refuses one.
+- **Who decided an escalation.** The last column of `tasks/<id>/escalations.tsv` is `policy`
+  (`--escalate-after`), `retry` (a typed `retry --dwarf`) or `pin`; rows from before it was added
+  have four columns and read as `policy`.
+
+Every change is appended to `control.log` (one JSON line: `at`, `actor` `cli` or `ui`, `action`,
+`task`, `key`, `value`, `previous`) and recorded in the dataset as a `control` event, so a run's
+human interventions are on the record next to what the policy did. Setting a control to the
+value it already has changes and logs nothing.
+
 ## Splitting and combining plans
 
 `run --retry-failed N` removes most of the reason to split a plan (a failed task no longer holds

package/docs/forge-ui.md

@@ -2,7 +2,7 @@
 
 [← README](../README.md) · [All docs](README.md)
 
-forge-ui is a small read-only local web page that shows runs live, as a 3D isometric map
+forge-ui is a small local web page that shows runs live and, when you ask, changes them, as a 3D isometric map
 ported from [archivision](https://github.com/Giamme/archivision). Its **run cloud** puts every
 run in one full-screen view, grouped by project, in five layouts (helix, sphere, galaxy,
 timeline, constellation), filtered down to exactly the runs you want; drag any run anywhere
@@ -52,6 +52,41 @@ following its log as it grows. It is read from the agent CLI's own log, whicheve
 wrote it (as plain text for those that log no events yet), or for an older claude run from
 Claude's session file on this machine.
 
+### Controls
+
+forge-ui reads everything, and it changes things only by calling forge's own commands: it
+never writes a run file, a repo or a config itself. That keeps one set of rules (validation,
+locks, the audit log) whichever way you change something, and a change from the page is
+indistinguishable from the same command typed in a terminal, except that `control.log` says
+`ui` instead of `cli`. Every change asks you to confirm and says when it takes effect.
+
+- **Run controls** (a plan's inspector): the QA threshold, the per-attempt timeout, how many
+  failures before escalating, verification retries, and, while a scheduler is live, the retry
+  and infrastructure-retry budgets. A task has its own panel for a threshold override
+  (including *None*, which exempts it from the run's threshold), its own retry budget, and a
+  **model pin**: the model its next full retry uses, once. Each is `forge control`; see
+  [decomposed runs](decomposed-runs.md#changing-a-run-while-it-works). A control that cannot
+  apply (a budget with no live scheduler, a merged task) is disabled and says why.
+- **Open findings:** the review findings a run left open (tolerated by `--qa-threshold`,
+  PLAUSIBLE, or left by the whole-run review), for this run or every run of its repository.
+  Select some and file them as GitHub issues, or dismiss the ones that need no work (and take
+  that back). It runs `forge issues`, so a finding is never filed twice.
+- **Delete a run:** a dialog that first shows a dry run, then deletes the run directory
+  through `forge runs rm`. The dataset keeps the run's traces, and by default a `.tar.gz` of
+  them too; you can also remove its clean worktrees and its branches that nothing has checked
+  out. Anything that is not the run's own, or has uncommitted changes, is listed and left alone.
+- **Settings:** every config source in one view (`forge config show`) and edits for the
+  per-repo ones (`repo.verify`, `repo.setup`, `repo.verify-subset`, and Jev on or off). The
+  registry stays read-only: the skill directory is often a live symlink to a checkout.
+
+Writing is protected, because anything that can reach the server could otherwise change your
+runs. The server makes a random token each time it starts and puts it in the page it serves;
+the page sends it with every change, and the server also checks the `Host` and `Origin`
+headers, so another website open in your browser cannot make your browser change a run. Reading
+needs no token. `--read-only` (or `FORGE_UI_READONLY=1`) turns writing off altogether: no
+token is issued and every change is refused. `FORGE_UI_READONLY=1 forge ui open` starts such a
+server, and the launcher never reuses a server running in the other mode; it replaces it.
+
 Also: replay, critical path, Fractal child-task trees, quick jump (Ctrl K, ⌘K on a Mac, or
 `/`), a bell for runs that finish or fail, failed tasks and final-review verdicts (with opt-in
 browser notifications), and a run exported as one HTML file that opens without forge-ui, with
@@ -68,8 +103,9 @@ forge ui open [DIR]     # an existing run dir, or the run list
 ```
 
 All runs share one detached server on `127.0.0.1:8765` (`FORGE_UI_PORT`) that exits after
-four idle hours (`FORGE_UI_IDLE_S`). A UI that cannot start never fails the run. It has no
-token: any local process can read the prompts and diffs of the runs it shows. See
+four idle hours (`FORGE_UI_IDLE_S`). A UI that cannot start never fails the run. Reading needs
+no token: any local process can read the prompts and diffs of the runs it shows; only changes
+need the token (see [Controls](#controls)). See
 [references/ui.md](../references/ui.md) and [ui/README.md](../ui/README.md).
 
 To look around before your first run, point it at made-up runs (the ones in these pictures), from a git checkout:
@@ -83,10 +119,10 @@ python3 ui/tools/demo_runs.py /tmp/forge-demo
 
 | Command | Purpose |
 | --- | --- |
-| `open [DIR] [--no-browser] [--port N]` | start or reuse the shared forge-ui server; print `forge-ui: <url>` for the plan or solo run dir `DIR` (the run list without it) and open a browser the first time |
-| `status [--json]` | exit 0 and describe the server when it runs, 1 when not |
+| `open [DIR] [--no-browser] [--port N]` | start or reuse the shared forge-ui server (never one in the other mode); print `forge-ui: <url>` for the plan or solo run dir `DIR` (the run list without it) and open a browser the first time (a later `open` of the same run says on stderr that it opened none) |
+| `status [--json]` | exit 0 and describe the server (and whether it is read-only) when it runs, 1 when not |
 | `stop` | stop the server |
 
 `FORGE_UI=off` makes `--ui` on a runner start nothing (it does not stop a running server or block `forge ui open`; use `forge ui stop`), `FORGE_UI_BROWSER=off` never opens a browser,
-`FORGE_UI_PORT` (8765) and `FORGE_UI_IDLE_S` (14400, `0` = never) tune the server. State and
+`FORGE_UI_PORT` (8765) and `FORGE_UI_IDLE_S` (14400, `0` = never) tune the server, and `FORGE_UI_READONLY=1` starts it read-only. State and
 `server.log` are in `${XDG_STATE_HOME:-~/.local/state}/forge/ui/`.

package/docs/reviews.md

@@ -120,6 +120,20 @@ lists them. The literal status stays `PASS`, so nothing downstream needed a new
 It fails safe: an unlabelled CONFIRMED finding, or a FAIL with no CONFIRMED finding at all,
 is never tolerated, and without a threshold nothing changes.
 
+Tolerated findings are recorded, not fixed. After a run, the skill offers once to file them as
+GitHub issues, together with PLAUSIBLE findings of passed tasks and whatever a whole-run review
+left open (`--file-issues ask|auto|off`, `ask` by default). Where the
+[gh-proman](https://github.com/Giamme/gh-proman) skill is set up for the repository, it files
+them on the team's project board; anywhere else forge files them itself with plain `gh`:
+
+```sh
+./forge issues <plan-dir>                       # drafts only: titles, severity, already filed
+./forge issues <plan-dir> --include-plausible --apply --label bug
+```
+
+Each issue gets the finding, its severity, the task, reviewer and a code link at the merged
+commit. A hidden fingerprint, shared with gh-proman, keeps a finding from being filed twice.
+
 ## Accepting a task despite its reviewer
 
 ```bash

package/forge

@@ -21,8 +21,11 @@ usage() {
     '  fractal   opt-in Fractal execution: install, doctor, runs, status, tree, logs, open, report, ...' \
     '  jev       optional Jev advice: setup, status, doctor, enable, disable, backtest' \
     '  dataset   every run'"'"'s inputs and outcomes: status, dump, import, export, outcomes, ...' \
+    '  issues    file the review findings a run left open as GitHub issues (plain gh)' \
     '  ui        forge-ui, the run viewer: open [DIR], status, stop' \
     '  runs      this repo'"'"'s recent runs in the terminal: state, verdicts and run dirs' \
+    '  control   a plan'"'"'s live controls: show, set (QA threshold, retries, timeouts), pin, unpin' \
+    '  config    every config source: show, and set/unset the per-repo .forge files and Jev on/off' \
     '  update    fast-forward this checkout and refresh every harness installation' \
     '  version   the installed version, and whether a newer release is out' \
     '' \
@@ -47,6 +50,10 @@ case "${1:-}" in
     shift
     exec python3 "$ROOT/scripts/forge-dataset.py" "$@"
     ;;
+  issues)
+    shift
+    exec python3 "$ROOT/scripts/forge-issues.py" "$@"
+    ;;
   ui)
     shift
     exec python3 "$ROOT/scripts/forge-ui.py" "$@"
@@ -55,6 +62,14 @@ case "${1:-}" in
     shift
     exec python3 "$ROOT/scripts/forge-runs.py" "$@"
     ;;
+  control)
+    shift
+    exec python3 "$ROOT/scripts/forge-control.py" "$@"
+    ;;
+  config)
+    shift
+    exec python3 "$ROOT/scripts/forge-config.py" "$@"
+    ;;
   update)
     shift
     exec /bin/bash "$ROOT/scripts/forge-update.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giamme/forge",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Multi-model coding with a reviewer that reads the code: plan, build in parallel worktrees, review every real diff, merge only what passes.",
   "keywords": ["claude-code", "codex", "opencode", "agent-skill", "code-review", "multi-model"],
   "license": "MIT",

package/references/dataset.md

@@ -35,7 +35,9 @@ time order: an attempt that PASSed, then a merge that CONFLICTed, then a human `
 | `run_end` | `run` | results per task, the accepted integration commit, `memory.md` |
 | `invocation` | user-facing `forge-parallel.sh` subcommand | argv, exit, duration, plus final review, accept, integrate and split/combine payloads |
 | `event` | point event | `merge` (MERGED, CONFLICT with the files, INVALIDATED and why), `integrate_advanced`, `integrate_conflict`, `combine_conflict`, `sched_terminal`, `subset_run` (every outcome), `memory_record`, `memory_prune` |
-| `event` `escalation` | `retry --dwarf` | the model a retry escalated from and to, recorded at the rewrite, before the retried attempt begins |
+| `event` `escalation` | retry that changes the model | the model a retry escalated from and to, `after_attempt`, and `source` (`policy`, `retry` for an explicit `--dwarf`, or `pin`), recorded at the rewrite, before the retried attempt begins |
+| `event` `control` | `forge control` change | a human's live change: `at`, `actor` (`cli`/`ui`), `action` (`set`, `pin`, `unpin`), `key`, `value`, `previous`; task events carry the task id. Also read back from `control.log` by `import` |
+| `event` `run_delete_started` / `run_deleted` | `forge runs rm` | written strictly around a run's deletion: `path`, `run_id`, `archive`, and for `run_deleted` the bytes freed |
 | `event` `shadow_review` | shadow review | how an opt-in second review ended (`done`, `invalid`, `overtime`, `orphaned`, ...), with the reviewed commit and both specs. Its dispatch is recorded with role `qa_shadow` |
 | `jev` | Jev request | site, answers, usage, latency, mode. Blob: the **full request** (state and questions). Its original sha is `jev.jsonl`'s `key` |
 | `fractal_step` / `fractal_node` | Fractal step, node state | decomposition decision, iteration, resolved model, cost, tokens, candidate diff |
@@ -297,6 +299,21 @@ so the importer will not guess which execution wrote a mutable file:
 - Archives are extracted to a temp dir and mapped back to their original path. The legacy
   run id hashes that original path, so the archive and the original dir agree on it.
 
+- **Import is strict when a caller must know.** `importer.import_run` is strict by default and
+  `forge runs rm` relies on it: it stores through `record_strict`, which raises (and the deletion
+  stops) if any event, blob included, was not stored, or any part of the run could not be read,
+  instead of treating an unreadable file as absent. Live capture stays fail-open. Interventions import by content, not by time of capture:
+  `tasks/<id>/escalations.tsv` (four or five columns; a missing `source` reads as `policy`) and
+  `control.log` produce the same event ids as live capture, so a re-import fills gaps without
+  duplicating. A line that does not parse is reported as failed.
+- **Archives describe themselves.** `archive_run` writes `FORGE_ARCHIVE.json` first
+  (`format`, `original_path`, `run_id`, `dataset_uid`, `created`), then `FORGE_ARCHIVE_EXCLUDED.txt`, then
+  the run dir under its basename. Symlinks, files over 50 MB, `review-*` snapshots and what the
+  importer never reads are left out and listed in the excluded file. Importing such an archive maps
+  it back to `original_path`, so its run id and uid match the original dir's; an unreadable path
+  during archiving is an error, not a silent omission. The archive is written to a temp name, fsynced
+  and renamed.
+
 `~/.local/share/forge/legacy/` holds archives of run dirs taken before live capture, with a
 `MANIFEST.tsv`. Passing that dir to `import` reads every archive, plus the ledger copies
 listed in `ledgers/REPOS.tsv`.

package/references/decompose.md

@@ -390,7 +390,7 @@ realistic input or a broken existing contract; P2 edge-case bug, unusual-timing
 hardening; P3 minor. Severity is impact; CONFIRMED/PLAUSIBLE is confidence.
 
 `run`/`retry --qa-threshold Pn` (remembered in `<plan>/qa_threshold`; `none` clears it) sets
-the **least severe level that still blocks**. `tasks/<id>/qa_threshold` overrides it per task —
+the **least severe level that still blocks**. `tasks/<id>/qa_threshold` overrides it per task (the value `none` exempts the task from a plan threshold; `forge control set ... qa-threshold` writes both and takes effect at the next attempt) —
 the way to give a dev-tooling or investigation task a looser bar than production code,
 which otherwise gets a new finding in a new corner of a non-default option every round and
 only a human decision ends it. The orchestrator decides *deterministically* (`forge-contract.py gate`),
@@ -470,6 +470,24 @@ turns it off):
 History cannot yet say whether escalating rescues a task (31% of the 29 later attempts on a
 changed spec passed, mostly effort bumps); the attempts this policy makes are what will.
 
+**Live controls.** `forge control show|set|pin|unpin <plan>` changes a run while it works:
+`qa-threshold` (read once per attempt, so an attempt keeps the bar it started with; per task, `none`
+exempts it and `inherit` drops the override), `timeout`, `escalate-after`, `verify-retries`, and,
+only while a scheduler is live, `retry-budget` (plan or `--task`) and `infra-retries`. The budgets
+keep the **per invocation** rule: the flags of `run` are not remembered, and a live scheduler only
+mirrors them into `retry_budget`, `infra_budget` and `tasks/<id>/retry_budget` (re-read at every
+decision, removed when it stops; `tasks/<id>/retries.used` stays), so a change dies with the
+run. `pin <task> <spec>` sets the model the task's next full retry uses, once (checked with
+`forge-dispatch.sh doctor`, no quota): `prepare_retry` claims `escalation.pin` as
+`escalation.pin.applying`, rewrites `tasks.tsv`, appends the `escalations.tsv` row with
+`source=pin`, clears `escalation.stop`/`split.suggested`, then consumes the pin. A QA-only resume
+leaves it for the next full retry; Fractal plans never apply pins; a MERGED task refuses one.
+The last column of `escalations.tsv` says who decided: `policy`, `retry` (an explicit
+`--dwarf`) or `pin`; four-column rows read as `policy`. Every change goes to `control.log` (JSON lines:
+`at`, `actor` `cli|ui`, `action`, `task`, `key`, `value`, `previous`) and to the dataset as a
+`control` event. Exit 2 invalid input, 3 refused (not live, MERGED, Fractal, failing doctor,
+lock busy over 5 s). Report them; never set one yourself unless asked.
+
 **Ordinary execution resume:** run `run` again. Tasks already `MERGED` are skipped. A saved PASS is fingerprint-checked and merged without
 redispatch. PENDING, `INFRA` (paused by an infrastructure failure) and newly unblocked tasks run
 when eligible. Failed or interrupted tasks

package/references/ui.md

@@ -1,6 +1,6 @@
 # forge-ui
 
-forge-ui is a read-only local web page that shows a forge run live: a decomposed plan or a
+forge-ui is a local web page that shows a forge run live and can change it: a decomposed plan or a
 solo run. It is opt-in per run. The orchestrator asks "Open forge-ui to watch this run?
 [y/N]" once at the start of every new interactive run and passes the answer as `--ui` or
 `--no-ui`. Nothing about the run depends on it: a UI that cannot start prints a note and the
@@ -23,6 +23,15 @@ run goes on, with the same exit code.
   review's combined diff, with every P0–P3 finding shown under the line it names.
 - **Fractal child tasks:** the tree a Fractal task was split into, in the inspector and above
   the opened task in 3D, each node with its decision, cost, output and candidate diff.
+- **Controls:** change a live plan from its inspector: QA threshold, timeout, escalate-after,
+  verify retries, and (while a scheduler is live) the retry and infra-retry budgets; per task, a
+  threshold override (`None` exempts it), a retry budget and a one-shot model pin. Each is one
+  `forge control` call; the change is confirmed first and logged in `control.log`.
+- **Open findings and issues:** the findings a run (or all of its repository's runs) left open,
+  filed as GitHub issues or dismissed through `forge issues`.
+- **Delete a run:** a dry run, then `forge runs rm`: the dataset keeps the traces, an archive is
+  written unless declined, and clean worktrees and unchecked-out branches can go with it.
+- **Settings:** `forge config show` in one view, with edits for the per-repo files and Jev.
 - **Export a run:** one HTML file to share that opens without forge-ui; prompts, diffs, reports
   and local paths stay out unless chosen.
 - **Quick jump and notifications:** Ctrl K (⌘K) or `/` searches every run, task, project and
@@ -96,10 +105,23 @@ how the map shows all of a repo's runs. `forge-parallel.sh run` also records the
 
 ## Privacy
 
-The server binds only `127.0.0.1` and serves read-only. It has **no token**: any process on
-the machine, under any user who can reach loopback, can read every run it knows, including
-prompts, diffs and review text from private repos. A running server keeps serving them,
-including runs that were later rerun with `--no-ui`.
+The server binds only `127.0.0.1`. **Reading needs no token**: any process on the machine,
+under any user who can reach loopback, can read every run it knows, including prompts, diffs and
+review text from private repos. A running server keeps serving them, including runs that were
+later rerun with `--no-ui`.
+
+**Changing needs one.** The server never writes a run file, a repo or a config itself: every
+change is a call of forge's own CLI (`forge control`, `forge issues`, `forge runs rm`,
+`forge config`), so validation, locks and the audit log are the CLI's. Each server start makes a
+random token and puts it in the page it serves; every change must send it back, from a `Host` of
+`127.0.0.1` or `localhost` and with an `Origin` equal to that host when the browser sends one, or
+it is refused before any CLI runs. There are no CORS headers, so another site in your browser
+can neither send nor read a change. Any process that can fetch the page can read the token, as
+it can read the runs, so on a shared machine start the server **read-only**: `--read-only`
+(`python3 -m forge_ui`) or `FORGE_UI_READONLY=1` (also for `forge ui open`). A read-only server
+issues no token and answers every change with 405; its `/api/health` says `"controls": false`.
+`forge ui open` never reuses a server in the other mode: it replaces it, as it does one running
+old code, and `forge ui status` shows the mode.
 
 Every run is registered, so a running server shows every run on the machine, not only those
 opened with `--ui`. The 3D view fetches three.js from cdn.jsdelivr.net (no run data is sent;