@giamme/forge 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.11] - 2026-10-26
+
+Reviews now remember the last round: a retry's review starts from the previous findings, and a repeated whole-run review from the last report. forge dataset can forecast a plan before it runs and grade how often each reviewer's PASS held, and forge-ui shows a superseded final review as OUTDATED instead of FAIL.
+
+### Highlights
+
+- `forge dataset reviewers`: a report card for reviewer models. For each reviewer, how often work it PASSed was later reverted or mostly rewritten within the outcome horizon (14 days by default), with a 95% interval, or "not enough data" below 10 outcomes. forge-ui's Models view shows it as the Reviewers table's Did not hold column. Advisory only: it never changes routing.
+- `forge dataset forecast <plan>` estimates a plan from past tasks at the same tier and model: median and p90 tokens and time, and the first-try PASS rate with a 95% interval, per task and in total, flagging tasks unlikely to pass first time. `forge-parallel.sh run` prints it before dispatching and records it for later checks (`--no-forecast` turns it off). It is advisory only.
+- On a retry, the per-task reviewer now first checks the previous round's findings, sees the diff between the two attempts and reads the implementer's reply, instead of starting cold. This applies on every harness, so a finding that was fixed is confirmed as fixed and one that was not is raised again.
+- A final review that later merges superseded now shows as OUTDATED in the forge-ui run view and on the cloud map, not as the run's verdict, and tasks merged with `accept` show as accepted instead of failed. `forge issues` and the Open-findings view mark the findings of an outdated review, and accepted findings get their own origin and issue text.
+
+### Added
+
+- `plan --reviewer-session` is an opt-in experiment that continues the reviewer's own session across rounds on claude, openclaude and codex, and falls back to a fresh session whenever it cannot. Those reviews are tagged in the dataset and kept out of the reviewer statistics, so the experiment does not skew the independence numbers.
+
+### Changed
+
+- A mistyped command now says which one you most likely meant, for example `forge rnus` answers "Did you mean `forge runs`?" above the usage.
+- A repeated whole-run review now carries the previous final review's report and the diff since it, so it checks what the earlier review found rather than reviewing the run from scratch.
+
+### Fixed
+
+- forge-ui started directly (`python3 -m forge_ui`) now finds forge's run registry the way forge writes it: an `XDG_CONFIG_HOME` that starts with `~` lists your runs instead of none.
+- A grok dwarf or reviewer that runs its tests in the background no longer ends as an error after 10 minutes: grok now waits for that work as long as forge's own time limit allows, and `forge-dispatch.sh doctor` checks that the installed grok supports this.
+- A relative `XDG_CONFIG_HOME` now counts as unset, as the XDG spec says, so forge registers runs and keeps `jev.json` in `~/.config` instead of recording nothing. Before, `forge ui open` printed a link to a run that forge-ui then did not list.
+- The dataset now imports the traces from the archive of a run whose directory name starts with `review-`; before, nothing from it was imported.
+- An escalation pin, or any escalation, no longer writes through a symlinked `escalations.tsv`.
+- The run summary, and `escalation.next` in the router's `--check`, no longer say a pin waits for a QA-only re-run when the next retry will really be a full attempt.
+- A relative `XDG_DATA_HOME` now counts as unset, as the XDG spec says, so the run dataset, run archives and exports stay in `~/.local/share/forge` instead of a folder inside whichever repo forge ran from. `forge config show` reports the same place.
+
+## [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>] [--reviewer-session] [--explore <0..0.5>] [--fail-first]'
 allowed-tools: [Bash, Read]
 ---
 
@@ -43,8 +43,9 @@ For explanation requests, explain the workflow without spending model quota.
   separate authorization and `integrate --approved`. Never push automatically.
 - Show the decomposed task/model table and wait for approval before dispatch. Retry only
   when requested; preserve failed task branches and worktrees. `run --retry-failed N`,
-  `--infra-retries M`, `--qa-threshold Pn` and `plan --shadow-qa` (a second review of a
-  sampled share of attempts, never read, to measure reviewer agreement) are opt-in: offer
+  `--infra-retries M`, `--qa-threshold Pn`, `plan --shadow-qa` (a second review of a
+  sampled share of attempts, never read, to measure reviewer agreement) and
+  `plan --reviewer-session` (continue the reviewer's session across rounds) are opt-in: offer
   them, never add them unprompted. So is `--fail-first` (solo or `plan`): the change's new
   tests also run without its non-test changes, and the reviewer is asked to report any that
   still pass as P2; it needs `.forge/verify-subset` and never changes a result by itself. `plan` explores by default (`--explore 0.2`: now and then
@@ -55,10 +56,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.11

package/docs/artifacts.md

@@ -17,6 +17,8 @@ as if the dwarf had written it.
   <role>.last         the final message — read this first
   <role>.infra        only after an infrastructure failure: class, retry_after, detail
   <role>.orphans      only when processes were left running after the harness exited
+  <role>.session      session id reported by claude, openclaude or codex; absent when the dispatch published none
+  <role>.continue     only when the dispatch was asked to continue a reviewer session: requested=, mode=continued|failed, reason=
   changes.diff        the dwarf's real diff, which is qa's input
 ```
 
@@ -48,9 +50,25 @@ 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_findings.commit     commit the carried review judged
+  tasks/<id>/retry_findings.session    session id of that review, when it recorded one
+  tasks/<id>/retry_findings.resolved   that review's resolution (harness=, model=, effort=)
+  tasks/<id>/changes.since.diff        diff from that commit to the one under review; omitted when there is no such range
+  tasks/<id>/changes.since.range       the two commits, full hashes
+  tasks/<id>/changes.since.stat        diff --stat of that range
+  tasks/<id>/review_sessions.tsv       one row per review round while plan --reviewer-session is on: round, attempt, mode, reason, session id
+  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)
+  reviewer_session                     holds on; present while plan --reviewer-session is on
+  <final-review-dir>/review.meta       final-review-<epoch>-<pid>/ or integrate-*/final-review/; base=, tip=, source=, spec=, threshold=, integration=, previous=, since=; session= and session_reason= while reviewer_session is set
+  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 +83,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,65 @@ 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 (origin
+`tolerated`), the CONFIRMED ones a person accepted with `accept` (origin `accepted`, with
+their own issue text: a person accepted the work over the reviewer's verdict), PLAUSIBLE
+ones with `--include-plausible`, and what the whole-run review left open. A whole-run
+review the integration branch has moved past is outdated: the issue says so and names the
+tasks that merged after it. 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 (`tolerated`, `accepted`, `review` or `plausible`), task, `review`, `filed` state and `dismissed` mark. A whole-run finding's `review` is `{name, outdated, merged_since}` (`outdated` is null when the review has no verdict or the plan has no accepted integration commit; `merged_since` is empty unless the review is outdated). Every other finding has `review` null |
+| `--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
 
 ```
@@ -270,6 +324,7 @@ Bash 3.2 entrypoints use a Python standard-library coordinator to schedule eligi
 ```
 forge-parallel.sh plan      <plan-dir> --repo <dir> [routing flags] [--planner <spec>] [--no-memory]
                                      [--decompose-level L] [--shadow-qa <spec>[,..]|none] [--shadow-rate R]
+                                     [--reviewer-session | --no-reviewer-session]
                                      [--explore E] [--ui | --no-ui] [--fail-first | --no-fail-first]
 forge-parallel.sh run       <plan-dir> [--max-parallel N] [--yolo-dwarf] [--yolo-qa] [--dry-run]
                                      [--verify <cmd>] [--setup <cmd>] [--timeout S]

package/docs/dataset.md

@@ -14,7 +14,29 @@ forge dataset status            # size, counts, and anything that looks incomple
 forge dataset import ~/.local/share/forge/legacy   # runs that predate live capture
 forge dataset export            # labeled decision cases for benchmarks and fine-tuning
 forge dataset outcomes          # which integrated lines survived, read from git history
+forge dataset reviewers         # how often work each reviewer PASSed was later reverted or rewritten
+forge dataset forecast <plan>   # likely tokens, time and first-try PASS rate for a plan's tasks
 ```
 
+`forge dataset reviewers` is a report card for reviewer models, built on those outcomes. It is
+advisory only and never changes routing, and it shows "not enough data" below 10 outcomes per
+reviewer rather than a rate a handful of tasks would make up. See
+[the reviewer report card](../references/dataset.md#reviewer-report-card).
+
+`forge dataset forecast <plan>` estimates a plan from past tasks at the same tier and model:
+median and p90 tokens and time, and the first-try PASS rate with a 95% interval, per task and in
+total. It flags tasks below 50% and says "not enough history" under 5 past tasks. `run` prints
+the same block before it dispatches (`--no-forecast` turns it off) and records it, so its accuracy
+can be checked later. It is advisory only. See [plan forecast](../references/dataset.md#plan-forecast).
+
+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

@@ -99,8 +99,9 @@ that baseline, and QA sees only baseline membership recorded for that task.
 ## Fresh session per task, plus a capsule
 
 Every dispatch is a **clean slate** — forge never passes `--continue`, `--resume`, or
-`codex exec resume`. One task's confused turn can't poison another, and each task's context
-stays small.
+`codex exec resume`, except the opt-in `plan --reviewer-session` experiment (it continues
+a reviewer's session across rounds on claude, openclaude and codex). One task's confused
+turn can't poison another, and each task's context stays small.
 
 Clean slates alone would leave every dwarf blind to the wider run, so a short `capsule.md` is
 generated from the task's pinned baseline and preserved for both implementation and QA:
@@ -181,6 +182,10 @@ bash scripts/forge-parallel.sh run "$PLAN" --max-parallel 4 --yolo-dwarf
 bash scripts/forge-parallel.sh integrate "$PLAN" --approved
 ```
 
+`run` starts by printing a forecast for the plan from the dataset: likely tokens, time and
+first-try PASS rate per task, with tasks unlikely to pass first time flagged. It is advisory only,
+and `--no-forecast` turns it off. See [plan forecast](../references/dataset.md#plan-forecast).
+
 `integrate` refuses without `--approved`, and refuses on a dirty working tree.
 For Fractal execution, pass tier pools to `plan` and backend/limit flags to `run`.
 `--max-parallel` limits task pipelines; the shared `--fractal-concurrency` limit includes
@@ -200,6 +205,53 @@ 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. That row is never written through a symlink: if `escalations.tsv`, or any directory
+  from the plan down to it, is one, the pin stays and nothing is retried. The run summary
+  says a pin waits (`pinned; after the QA-only re-run`) only when the next entry really
+  re-runs QA: a `resume` marker, or an unreviewed verdict, that still matches the
+  worktree. A marker the next retry will discard is reported as `pinned`.
+  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
@@ -32,7 +32,10 @@ and the cloud remembers it.
 
 The page reads like a signal box's desk: engraved plates for headings, push buttons with lamps
 for switches, and lamps that keep one meaning everywhere (amber running, green merged, red failed,
-unlit pending). Two layouts share it. *Immersive*, the default, floats the runs, the inspector and the tasks
+unlit pending). Tasks merged with `accept` show as accepted (hollow green) rather than failed.
+A final review superseded by tasks merged into the integration branch shows as OUTDATED
+(hollow unlit) instead of as the run's verdict; changes on the user's own branch after an
+integrate are not tracked. Two layouts share it. *Immersive*, the default, floats the runs, the inspector and the tasks
 over a full-window stage (on a first visit the inspector and the tasks start folded, so a run
 opens on its plate); *Workbench* docks them beside it with splitters. `1`, `2` and
 `3` fold each module away, the header switches layout and theme (system, light or dark), and the
@@ -52,6 +55,43 @@ 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.
+  Findings of an outdated review carry an "outdated review" marker, and findings a person
+  accepted have origin `accepted`. 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 +108,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 +124,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/memory.md

@@ -4,8 +4,10 @@
 
 What forge learns about a repository, where it keeps it, what each role is told, and what forge has spent there.
 
-Every forge dispatch is a clean slate, so without help the tenth run in a repo rediscovers
-what the first one learned. forge keeps that in the repo, in two files:
+Every forge dispatch is a clean slate — the opt-in `plan --reviewer-session` experiment,
+which continues a reviewer's session across rounds, is the exception — so without help the
+tenth run in a repo rediscovers what the first one learned. forge keeps that in the repo,
+in two files:
 
 ```
 .forge/memory.md     small, capped, injected into every prompt

package/docs/reviews.md

@@ -51,7 +51,20 @@ Two things it deliberately does:
   from — not just the fix. Reviewing the fix alone would let the first attempt's code through
   unread.
 - **Refuses to re-review identical code.** If the retry produces a byte-identical diff, the
-  task fails again without spending a QA dispatch.
+  task fails again without spending a QA dispatch. A retry that only rejects the findings,
+  and leaves that diff unchanged, is still this identical retry: it writes
+  `tasks/<id>/noretry` and QA is not dispatched.
+
+When the diff did change, QA on that retry is handed the previous round as well as the
+cumulative diff. The report goes under **Findings from the previous review round**. The
+diff between the two attempts goes under **Changes since that review**, and is kept as
+`tasks/<id>/changes.since.diff`, `changes.since.range` and `changes.since.stat` (the
+range is omitted when the earlier commit is missing, unknown or not an ancestor, or when
+nothing changed; a diff over 100 KB is replaced in the prompt by its stat). The
+implementer's reply goes under **The implementer's reply (its own account; verify
+every claim against the code)**. The prompt tells the reviewer to restate only findings that are still
+open, as `- [Px][CONFIRMED|PLAUSIBLE]` lines, and to mention a fixed or rejected finding
+only in a plain sentence. The gate and `forge issues` count every labelled line.
 
 `retry` is something you run. Forge never loops a dwarf against its own reviewer on its own
 initiative — unless you ask a *run* to with `--retry-failed N`, see
@@ -120,6 +133,30 @@ 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.
+Findings a person merged with `accept` are origin `accepted`: the CONFIRMED lines under
+`## Accepted by a human despite the reviewer's <status> verdict` in `known_issues.md`.
+Their issue says a person accepted the work over that verdict, and gives the recorded
+reason. Findings above that heading, which a threshold tolerated, stay origin
+`tolerated`. A whole-run review whose integration branch has moved since it is outdated.
+Its findings stay listed, and the issue says the review is outdated and names the tasks
+that merged after it. In `--json` each whole-run finding carries `review`: `name`,
+`outdated` and `merged_since`. `outdated` is null when the review has no verdict or the
+plan has no accepted integration commit, and `merged_since` is empty unless the review
+is outdated. Every other finding has `review` null.
+
 ## Accepting a task despite its reviewer
 
 ```bash
@@ -135,7 +172,9 @@ it on its own. It accepts only a `FAIL` or `UNKNOWN` task whose reviewed work is
 the branch is still at the reviewed commit and the worktree still has the saved fingerprint —
 otherwise it exits `3` and says to `retry` for a fresh review (accepting would sign off on code
 nobody reviewed). It writes `tasks/<id>/known_issues.md` (your reason, who and when, and the
-reviewer's reply copied verbatim) and `accepted.by`, merges through the same checks as any other
+reviewer's reply copied verbatim, under
+`## Accepted by a human despite the reviewer's <status> verdict`) and `accepted.by`,
+merges through the same checks as any other
 task, and puts everything back if the merge conflicts (exit `6`). Dependents are not touched;
 `run` continues them.
 
@@ -165,6 +204,52 @@ the one remembered in `final_qa`, else the single spec every task shares (otherw
 Tasks that are not merged are not in the result, and it says so. `integrate` also names unmerged
 tasks even without a review.
 
+A later whole-run review carries the previous one's report, under **Findings from the
+previous final review**, and the diff since it, under **Changes since that review**
+(inlined up to 200 KB, otherwise its stat). `review.meta` records `integration=` (the
+accepted integration commit, or `none`), `previous=` (that review's directory, or
+`none`) and `since=` (its tip, when that commit is an ancestor of this review;
+otherwise `none`, and the prompt says the range cannot be shown). When the two reviews
+share a commit, `since=` is that commit and the prompt says nothing changed. The same
+labelled-line rule applies: restate only what is still open, because every labelled line
+is filed.
+
+## Reviewer session (opt-in experiment)
+
+`plan --reviewer-session` continues the same reviewer's session across rounds. It is off
+unless you pass it; `--no-reviewer-session` turns it off again and removes the plan's
+`reviewer_session` marker. While the marker is present, per-task QA and a repeated
+whole-run review continue the previous round's session on claude, openclaude and codex,
+when the resolved harness, model and effort are unchanged. The approval table names it.
+Dispatch details are in
+[continuing a reviewer session](../references/harnesses.md#continuing-a-reviewer-session).
+
+Any round that cannot continue starts a fresh session. That is the first round, a missing
+or malformed session id, a resolution that is missing or different, any harness other
+than those three, a Fractal plan, and a continue that the harness refuses or that fails
+(dispatch exit **9**). Exit 9 means the session was not continued. Forge sends the same
+prompt again as a fresh session, and that dispatch decides the round. One row per round
+is appended to `tasks/<id>/review_sessions.tsv`: round, attempt, `continued` or `fresh`,
+the reason, and the session id the round considered (empty when there was none). The
+row describes the dispatch whose result counts, so a failed continue is a single
+`fresh` row. Reasons are `same-spec`, `first-round`, `no-session`, `invalid-session`,
+`spec-changed`, `harness-unsupported`, `fractal`, `continue-unsupported` and
+`continue-failed`. A final review records the same outcome as `session=` and
+`session_reason=` in `review.meta`.
+
+A shadow review never continues a session. It stays a separate fresh review of a copy of
+the prompt.
+
+A review that was asked to continue is tagged `session_continue` in the dataset
+(`continued`, or `failed` when the continue did not succeed) and left out of the
+reviewer slices and the agreement rate. The fresh dispatch after exit 9 is not tagged,
+so it still counts. See [the dataset](../references/dataset.md).
+
+This is separate from a QA-only resume, the re-run after an infrastructure stop. That
+re-run is the `tasks/<id>/resume` marker: forge revalidates it against the worktree,
+then asks QA again about unchanged work, and no attempt is spent. The reviewer session
+continues the reviewer's conversation into a later round, and only when you opt in.
+
 ## Shadow reviews: how much of a verdict is the reviewer?
 
 `plan --shadow-qa <spec>[,<spec>...] [--shadow-rate R]` (default R = 0.1) sends a sampled