@giamme/forge 0.9.0 → 0.11.0

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' \
     '' \
@@ -30,6 +33,18 @@ usage() {
     'Runs start from your agent harness (/forge "<goal>" --dwarf <model>); see README.md.'
 }
 
+# suggest WORD — the listed command WORD most likely meant (a unique prefix or a close
+# spelling), read from usage so the two never drift apart; prints nothing when none is close
+# or python3 is missing. -I keeps a stray module in the current directory out of it.
+suggest() {
+  usage | python3 -I -c 'import difflib, re, sys
+word = sys.argv[1].lower()
+names = re.findall(r"^  ([a-z]+) ", sys.stdin.read(), re.M)
+prefixed = [name for name in names if len(word) >= 2 and name.startswith(word)]
+hit = prefixed if len(prefixed) == 1 else difflib.get_close_matches(word, names, 1, 0.6)
+print(hit[0] if hit else "")' "$1" 2>/dev/null
+}
+
 case "${1:-}" in
   install)
     shift
@@ -47,6 +62,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 +74,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" "$@"
@@ -72,7 +99,10 @@ case "${1:-}" in
     exit 2
     ;;
   *)
-    printf 'forge: unknown command: %s\n\n' "$1" >&2
+    printf 'forge: unknown command: %s\n' "$1" >&2
+    GUESS="$(suggest "$1")"
+    [ -n "$GUESS" ] && printf 'Did you mean `forge %s`?\n' "$GUESS" >&2
+    printf '\n' >&2
     usage >&2
     exit 2
     ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giamme/forge",
-  "version": "0.9.0",
+  "version": "0.11.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

@@ -14,6 +14,8 @@ ${FORGE_DATA_HOME:-${XDG_DATA_HOME:-~/.local/share}/forge}/dataset/
   errors.log            capture failures
 ```
 
+An empty or relative `XDG_DATA_HOME` counts as unset, as the XDG spec says.
+
 Capture is on by default and costs a few milliseconds per execution. `FORGE_DATASET=off`
 turns it off for one invocation.
 
@@ -28,20 +30,36 @@ time order: an attempt that PASSed, then a merge that CONFLICTed, then a human `
 | kind | one per | what it holds |
 |---|---|---|
 | `start` | execution | a receipt written by `begin()`. A start with no matching end is an execution that was killed or is still running |
-| `dispatch` | model call | role, alias, harness, **resolved** model, effort after clamping, timeout and its source, delivery (custom or native review), phase timings, exit, timeout, infra class, tokens, parsed verdict and findings, `FORGE_LEARNING` lines. Blobs: the delivered prompt and the final message |
+| `dispatch` | model call | role, alias, harness, **resolved** model, effort after clamping, timeout and its source, delivery (custom or native review), phase timings, exit, timeout, infra class, tokens, parsed verdict and findings, `FORGE_LEARNING` lines, `session_id`, `session_continue`. Blobs: the delivered prompt and the final message |
 | `attempt` | task attempt or solo run | status, attempt number (with refund and resume flags), trigger (`initial`, `auto`, `human`), dwarf and qa spec, declared vs changed files, numstat, drift, guard notes, gate line, patch key, the files this execution wrote and the ones it only carried. Blobs: the diff, retry findings, memory slices, capsule, Jev task files |
 | `verification` / `verify_run` | verify, and each command execution | command and its source (flag, `.forge/verify`, Jev), status, flaky, Jev triage. One `verify_run` per execution, each with its own log |
-| `plan` | `plan` | goal, original request, decompose level, exploratory routing decisions (`tasks[id].route`, with their odds), author (orchestrator or planner), per-task declared vs executed difficulty and who set it, pools, waves, Jev routing and coupling. Blobs: both task tables, prompts, approaches, excerpts of the declared files at plan time, the file inventory, `memory.md` |
+| `plan` | `plan` | goal, original request, decompose level, exploratory routing decisions (`tasks[id].route`, with their odds), author (orchestrator or planner), per-task declared vs executed difficulty and who set it, pools, waves, Jev routing and coupling, options (including `reviewer_session` when that file is present). Blobs: both task tables, prompts, approaches, excerpts of the declared files at plan time, the file inventory, `memory.md` |
 | `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 |
 | `ledger` | ledger row | imported `.forge/ledger.tsv` rows |
+| `forecast` | forecast shown by `run` | the plan forecast printed before dispatch (see [plan forecast](#plan-forecast)), once per run and content. Also in the plan as `forecast.json` |
 | `outcome` | integrated task, per horizon | written by `forge dataset outcomes`, never by a run: how many of the lines a task added survive N days after `integrate`, and what reverted it |
 
+A dispatch carries `session_id` and `session_continue`. `session_id` comes from the attempt
+dir's `<role>.session`, and from `metrics.json` when that file is absent. `session_continue`
+is null when the attempt dir has no `<role>.continue`. That file is written only when the
+dispatch was asked to continue a reviewer session: `mode=continued` is `continued`, and
+`mode=failed`, a missing mode or any other mode is `failed`. The file's presence means
+continuing was requested, so a failed continue that still printed a verdict is tagged too.
+The `attempt` event's `resumed` flag is a different fact: a QA-only re-run after an
+infrastructure stop (the `tasks/<id>/resume` marker).
+
+`plan --reviewer-session` writes `$PLAN/reviewer_session` (`on`). The plan event records
+it in `options`. The file joins the plan id only when it is present, so every plan already
+in a store keeps its id, and turning the experiment on stores a new plan event.
+
 Each blob reference carries `sha` (the stored bytes), `original_sha`, `n` (the original
 size), `kept`, and `cut`. A cut keeps the head and the tail, because a QA prompt ends with
 the diff and a log ends with the failure. Caps: prompt 1 MiB, diff 2 MiB, message 256 KiB,
@@ -115,6 +133,8 @@ forge still running keeps writing.
 ./forge dataset export [--slice S]... [--limit N] [--seed N] [--out DIR]   # labeled decision cases
 ./forge dataset outcomes [--horizon-days 14] [--repo PATH] [--dry-run]     # what integrated work became
 ./forge dataset routing [--repo PATH] [--since DAYS] [--json]   # pass rate and runtime per tier and model
+./forge dataset reviewers [--horizon-days 14] [--repo PATH] [--json]   # how each reviewer's PASSed work held up
+./forge dataset forecast <plan> [--repo PATH] [--json]   # likely cost and first-try PASS rate per task
 ```
 
 `status` runs a different completeness check for each mode, because each mode
@@ -183,6 +203,18 @@ finished on an untouched snapshot and reviewed the same commit counts. The prima
 labels never change, because `qa_shadow` dispatches are not reviews of record.
 `./forge dataset status` prints the agreement rate, overall and per model pair.
 
+A dispatch with `session_continue` set is left out of every slice built from QA rows
+(review cases, citation cases) and out of the shadow agreement pairs. That covers a
+continue that succeeded and one that failed after printing a verdict. A fresh fallback
+dispatch in the same round has `session_continue` null and stays in. The slices have no
+switch that puts the continued reviews back, so a group never mixes the two. Agreement
+still selects the attempt's last verdict-bearing primary, and then drops the pair when
+that primary continued a session: an earlier fresh verdict does not stand in for it.
+`./forge dataset status` prints the number of continued reviews and the number of failed
+continues on their own lines whenever either is non-zero, including in a store with no
+shadow review. The experiment's comparison reads the `dispatch` events (`session_continue`,
+tokens, verdicts, attempts), not these slices.
+
 `meta.jsonl` records each case's slice, run, repo and label source. It also holds hosted
 Jev's own answers where forge recorded them, as baselines that are never part of a case.
 Routing and retry cases add:
@@ -278,6 +310,56 @@ exporter attaches it to that diff's review.
 Each verification event also records the commit it verified (`verification.commit`, named
 before any early return), so a FAIL or UNVERIFIED result can be joined to its code too.
 
+## Reviewer report card
+
+`forge dataset reviewers` joins the survival outcomes above to the reviews that let the work
+through. For each reviewed commit with an outcome at the horizon (`--horizon-days`, default 14,
+only outcomes recorded at exactly that horizon), every primary reviewer (role `qa`) that gave
+that attempt a PASS is credited with one landed outcome. A row is keyed by the reviewer's alias,
+or its model when no alias was recorded, as the forge-ui Models view keys it. A landed outcome
+**did not hold** when a later commit reverted it, or when under 80% of its added lines were kept
+(rewritten): the export's `survives` rule.
+
+- The rate of work that did not hold has a Wilson 95% interval, shown only from 10 landed
+  outcomes on. Below that the row reads `not enough data (n/10)`, and the JSON has
+  `enough: false` with `rate` and `ci` null.
+- A shadow review's PASS decided nothing, so it is not credited. Work that landed after a FAIL
+  (the severity gate or a human accepted it) and work with no recorded review are counted as
+  unattributed. `lost` and `no_additions` outcomes are skipped.
+- Survival is only followed for parallel integrations, so solo runs and hand merges are not here.
+- It only advises: nothing that routes a task or builds a prompt reads it.
+
+forge-ui shows the rate as the Reviewers table's **Did not hold** column, through
+`GET /api/models/reviewers`, which runs this command with `--json`.
+
+## Plan forecast
+
+`forge dataset forecast <plan>` reads the plan's `tasks.tsv` (the declared tier from
+`tasks.declared.tsv` when there is one) and, for each task not yet MERGED, looks up past tasks
+that ran at the same tier on the same resolved model. The effort must match too when the task's
+spec names one. It uses the same task history as `forge dataset routing`, without the plan's own
+run.
+
+- Tokens are input plus output (cached input is not added again), summed over every implement
+  and review dispatch of the task, retries included. Time is the sum of those dispatches'
+  durations. Both show median and p90 (nearest rank).
+- The first-try PASS rate has a Wilson 95% interval. Tasks below 50% are flagged as likely to
+  need a retry. Under 5 past tasks the row reads `not enough history (n/5)` and the JSON has
+  `enough: false` with no rate.
+- Totals add up the per-task medians and p90s, the wall time by wave (the slowest task of each
+  wave), and the expected number of first-try passes.
+- It never creates the store, and prints nothing when the store is missing or has no history.
+
+`forge-parallel.sh run` prints the same block before it dispatches. It runs with a time budget
+(`FORGE_FORECAST_BUDGET_S`, default 3 seconds), prints one line and moves on if reading the
+history takes longer, never prints errors and never changes the exit code. `--no-forecast` or
+`FORGE_FORECAST=off` turn it off. The block is written to the plan as `forecast.json` and
+recorded once as a `forecast` event, so it can later be compared to what the run did.
+
+The history is observational: harder tasks tend to go to stronger models, so a rate describes
+what happened to similar tasks, not what a model would do on this one. It only advises: nothing
+that routes a task or builds a prompt reads it.
+
 ## Importing old runs
 
 `import` reads run dirs that predate live capture through the same readers. An execution
@@ -297,6 +379,22 @@ 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. `<role>.session` and `<role>.continue` are plain files in the attempt dir, so a
+  run archive carries them and import tags the dispatch from those files.
+
 `~/.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`.
@@ -308,7 +406,8 @@ listed in `ledgers/REPOS.tsv`.
 - **Never read by a prompt builder.** Memory inject, the capsule and Ripwire must not read
   the store. A reviewer that could see earlier runs' verdicts would not be independent.
   `tests/test_dataset.py` enforces that outside its own package, the dataset is only
-  imported for capture.
+  imported for capture. The one read is `run`'s [plan forecast](#plan-forecast), which goes to
+  the operator's terminal and `forecast.json`, never into a prompt.
 - **Read-only in your repos.** Capture and the harvester run only object-store git queries
   in a repo: `rev-parse`, `rev-list`, `log`, `show`, `ls-tree`, `cat-file`, `diff` between
   commits and `blame` at a commit. All run with `GIT_OPTIONAL_LOCKS=0`. None takes the

package/references/decompose.md

@@ -266,8 +266,10 @@ So:
 ## The capsule
 
 Every dispatch is a clean slate — forge never passes `--continue`, `--resume`, or
-`codex exec resume`. That keeps one task's confused turn from poisoning another and keeps
-each task's context small, but it also leaves each dwarf blind to the wider run.
+`codex exec resume`, except the opt-in `plan --reviewer-session` experiment (it continues
+a reviewer's session across rounds on claude, openclaude and codex). That keeps one task's
+confused turn from poisoning another and keeps each task's context small, but it also
+leaves each dwarf blind to the wider run.
 
 `tasks/<id>/capsule.md` records ownership and baseline context. `baseline.capsule` preserves
 the implementation-time capsule for QA. MERGED means the reviewed commit is an ancestor of
@@ -275,7 +277,8 @@ this task's pinned baseline, not merely that another task finished while QA was
 Complete requirements, approach, retry findings and distinct memory facts are assembled once
 per role; implementation and review instructions are separate.
 
-It exists to prevent two specific failures that clean slates create:
+It exists to prevent two specific failures that clean slates create, which the opt-in
+`--reviewer-session` experiment does not change:
 
 - a dwarf reimplementing a helper an earlier task already merged, because nothing told it
   that task was done;
@@ -390,7 +393,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`),
@@ -425,7 +428,8 @@ Two details that are load-bearing rather than incidental:
   diff.
 - **An identical retry is not re-reviewed.** If the diff comes back byte-identical to the
   previous attempt, the task fails again without a QA dispatch. Paying a reviewer to read
-  the same code twice buys nothing.
+  the same code twice buys nothing. A retry that only rejects the findings, and leaves
+  that diff unchanged, is still this identical retry.
 
 `retry` is a command a human types. Forge does not loop a dwarf against its own reviewer on
 its own initiative; the one exception is the opt-in `run --retry-failed N` below.
@@ -437,6 +441,14 @@ work: no dwarf, no new commit, no attempt spent. A `tasks/<id>/resume` marker re
 revalidated against the branch tip and the saved source fingerprint before it is trusted; if the
 worktree changed, the full task runs. Findings are carried only from a real review.
 
+On a retry whose diff changed, QA receives the previous round under **Findings from the
+previous review round**, the diff since that round (`tasks/<id>/changes.since.diff`,
+`changes.since.range` and `changes.since.stat`; omitted when the earlier commit is
+missing or not an ancestor, or when nothing changed) and the implementer's reply. It is
+told to restate only findings that are still open, as `- [Px][CONFIRMED|PLAUSIBLE]`
+lines, because every labelled line is counted. That is the retry's review, not the
+QA-only re-run above.
+
 **In-run retries.** `run <plan> --retry-failed N` re-queues a task whose reviewer said
 `FAIL`/`UNKNOWN` as soon as it ends, up to `N` more times in that run, preparing the retry exactly
 as `retry` does (same findings carry-forward, same pinned base, same cumulative review). Other
@@ -466,10 +478,34 @@ turns it off):
   QA-only resume, which spends no implementer attempt.
 - **Reporting:** the policy's state is decided after every attempt, so a run whose retry budget ran out
   still reports `its next retry goes to <spec>` or the split suggestion under the results.
+  A pending pin is reported ahead of both, as `its next retry goes to <spec> (pinned)`, or
+  `(pinned; after the QA-only re-run)` only when the next entry really re-runs QA (the
+  `resume` marker, or an unreviewed verdict, still matches the worktree). A marker the
+  next retry will discard is not that wait.
 
 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 symlinked
+`escalations.tsv`, or a symlink in any directory from the plan down to it, is not written:
+the pin stays and nothing is retried. 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/harnesses.md

@@ -22,6 +22,7 @@ provider test. See [Fractal execution](fractal.md).
 - [opencode](#opencode)
 - [antigravity (agy)](#antigravity-agy)
 - [grok](#grok)
+- [Continuing a reviewer session](#continuing-a-reviewer-session)
 - [Adding a harness](#adding-a-harness)
 
 ## At a glance
@@ -265,7 +266,8 @@ passes 30m and exposes `--agy-timeout` to change it.
 
 ```
 grok --model <model> --prompt-file <prompt> --output-format streaming-messages-json \
-  --reasoning-effort <effort> (--permission-mode acceptEdits --allow Bash [--deny Edit --deny Write] | --always-approve)
+  --reasoning-effort <effort> --background-wait-timeout <limit> \
+  (--permission-mode acceptEdits --allow Bash [--deny Edit --deny Write] | --always-approve)
 ```
 
 The xAI Grok Build CLI, signed in with `grok login` (or `XAI_API_KEY`); `grok models` lists
@@ -294,6 +296,15 @@ GitHub Copilot) as a second row.
   - **Untested:** whether `--permission-mode dontAsk` (deny without cancelling) together with
     explicit Edit/Write/Bash allows would avoid the cancel. Nothing changes until that is
     proven live.
+- **Background work waits as long as forge's limit allows.** After its last turn a headless run
+  waits for the background jobs it started (a test suite run in the background, say) and wakes
+  the model with each result. By default it waits only 600 s, then stops the work and exits 1:
+  a real dwarf whose full suite ran longer ended as an error. forge passes the role's own limit
+  as `--background-wait-timeout`, or a day when the limit is off (`--timeout 0`; grok refuses
+  0). grok counts from the last turn and forge from the start, so forge's watchdog always fires
+  first and the run ends as a timeout. The flag is missing from `grok --help`; preflight checks
+  it with `grok --background-wait-timeout 1 --help` instead, because grok rejects an unknown flag
+  that comes before `--help` (exit 2).
 - The prompt goes by `--prompt-file`, never argv, and stdin is `/dev/null`.
 
 Verified live on 2026-10-19 with a `FORGE_OK` dispatch: exit 0, `permissionMode` acceptEdits,
@@ -301,6 +312,37 @@ the answer extracted from the `result` line, tokens recorded, nothing left runni
 day, grok-4.7 dwarfs implemented and passed review on real tasks (the forge-ui integration run).
 A grok reviewer has not been proven live yet.
 
+## Continuing a reviewer session
+
+`forge-dispatch.sh qa <spec> ... --continue-session <id>` continues an earlier reviewer session instead of
+starting a fresh one. `<id>` is the session or thread id a dispatch left in `<run-dir>/<role>.session`
+(8 to 128 characters of `[A-Za-z0-9-]`, not starting with `-`). It is accepted for the `qa` role on claude,
+openclaude and codex in custom-prompt mode only; any other role, harness, `--native-review` or a malformed id
+is a usage error (exit 2). Nothing in forge asks for it by default.
+
+Probed 2026-10-22 (claude 2.1.307, codex 0.162.0):
+
+| Harness | Argv | Notes |
+|---|---|---|
+| claude, openclaude | the fresh QA argv plus `--resume <id>` | Continues from a different working directory and keeps the same session id. Permission flags and the read-only restriction stay; the prompt is still on stdin. |
+| codex | `codex exec resume <id> --json -m MODEL --skip-git-repo-check -o LAST [-c model_reasoning_effort=…] -c 'sandbox_mode="read-only"' -` | Continues from a different working directory. `exec resume` has **no `-C/--cd` and no `-s/--sandbox`**, so the dispatch's own `cd "$REPO"` sets the directory and the sandbox is passed as a config override (the quotes are TOML). The first turn's sandbox was inherited when probed (read-only); the override makes it explicit. Under `--yolo` the bypass flag replaces the override. |
+
+The prompt is preceded by a short fixed preamble (this continues your earlier review, the work has changed,
+the working directory is now `<repo>`, re-read files, this round's instructions win). `<role>.prompt` includes
+it. `<role>.continue` records the attempt as `requested=<id>`, then `mode=continued` or `mode=failed` with
+`reason=<one line>`, and is archived with the attempt.
+
+**Exit 9** means the session was not continued and the caller may dispatch fresh. Dispatch never retries fresh
+itself, so each dispatch keeps its own honest record. It happens when:
+
+- the harness does not advertise the flags continuing needs (`codex exec resume --help`, or `--resume` in
+  claude's help) but would pass preflight for a fresh QA dispatch: `reason=unsupported`, before any model call;
+  a harness that fails the fresh preflight too keeps exit 3;
+- the harness ran and exited non-zero: `reason=` the log's last error line.
+
+A timeout stays exit 7 and an infrastructure stop stays exit 8; both still write `mode=failed`. `doctor --spec`
+without `--continue-session` is unchanged.
+
 ## Installing forge into a harness
 
 Each harness discovers skills differently, and the differences are not guessable — verify

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,13 +23,25 @@ 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
   model; the bell tells you when a run finishes or fails, a task fails or a final review gives its
   verdict, and can raise browser notifications while the tab is in the background.
 - **Plan run:** tasks in their planned waves with dependency cables, then the finish line:
-  integration, verification and the whole-run final review, each a node with its status. The
+  integration, verification and the whole-run final review, each a node with its status. Tasks
+  merged with `accept` show as accepted (hollow green), not failed. A final review superseded
+  by later task merges 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. The
   *Execution* view shows the same run on wall-clock time, one block per attempt in the lane it
   ran in, with projected blocks for what has not started and a strip of busy slots against
   `--max-parallel`.
@@ -96,10 +108,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;