@giamme/forge 0.8.0 → 0.10.0

package/docs/decomposed-runs.md

@@ -0,0 +1,310 @@
+# Decomposed runs
+
+[← README](../README.md) · [All docs](README.md)
+
+Split one goal into tasks, route each to a model by difficulty, and run them in parallel in isolated worktrees, merging only the tasks that pass review.
+
+`--decompose-level low|medium|high` turns one dwarf into many. Without the flag, nothing
+changes — one dwarf, one QA pass.
+
+## Two independent axes
+
+Easy to conflate, so: **decompose-level** is how finely the *goal* is split. **difficulty**
+is how hard each resulting *task* is.
+
+| `--decompose-level` | Split |
+|---|---|
+| `low` | only where the goal has obviously independent pieces; 2–3 coarse tasks |
+| `medium` | one task per coherent unit (module, feature slice); typically 4–6 |
+| `high` | finest split where each task is still independently reviewable *and* independently correct; typically 7–12 |
+
+| `difficulty` | Means |
+|---|---|
+| `low` | mechanical and local: rename, move, docs, a test for behaviour that already exists |
+| `medium` | self-contained implementation against a clear spec; bounded blast radius |
+| `high` | needs design judgment, cross-cutting behaviour, subtle edge cases, state or concurrency |
+
+Difficulty is about **judgment required, not diff size**. A five-hundred-line mechanical
+rename is `low`. A ten-line concurrency fix is `high`. Getting this backwards sends the cheap
+model at the subtle problem and the expensive one at the boilerplate — worse than not routing
+at all.
+
+## Routing dwarves to tasks
+
+Per-task assignment can't be expressed when you type the command, because the tasks don't
+exist yet. Naming a dwarf per task would mean guessing how the goal will split. So you map
+**model tiers to difficulty tiers**, once, in advance — three layers, each optional:
+
+```bash
+# 1. one dwarf for everything
+--dwarf sol:xhigh
+
+# 2. per-tier routing, with plain --dwarf as the fallback for any tier not named
+--dwarf-high sol:xhigh --dwarf-medium luna:high --dwarf-low gemini:low:antigravity
+--dwarf sonnet:medium
+
+# 3. pool several models within one tier — round-robined across tasks
+--dwarf-high sol:xhigh,terra:xhigh
+```
+
+`--qa`, `--qa-high`, `--qa-medium`, `--qa-low` mirror it exactly. QA has no tier rules by
+default and falls back to `opus`.
+
+Resolution order per task: **explicit column value → the tier's rule → plain `--dwarf` →
+`UNASSIGNED`**. An `UNASSIGNED` task makes `plan` exit `2` and `run` refuse outright. forge
+does not invent a model when you haven't said which one should spend your quota.
+
+Layer three is **the approval gate**: after decomposition, before any dispatch, you get the
+task table with each task's difficulty and resolved dwarf/qa. Retier a task ("2 is actually
+medium") and it re-routes per your rules, or override a single row's dwarf outright. This is
+also the cost gate — `high` on a large goal is 20+ dispatches, which should be visible before
+it's spent.
+
+**Exploration is on by default** (`--explore 0.2`):
+- **Which rows:** only rows left to forge, never one whose dwarf column you filled.
+- **What changes:** now and then such a row gets its *neighbouring* tier's spec from your own
+  pools: the next cheaper tier for medium and high rows, the next stronger for low rows.
+  Pools that differ only in effort (`--dwarf-low sol --dwarf-high sol:xhigh`) compare the
+  two efforts.
+- **How often:** about one row in ten at the default.
+- **What you see:** each explored row is marked `*` in the table, before anything is spent.
+- **What it's for:** `forge dataset routing` reads the draws back as pass rates per model and
+  effort. Pass `--explore 0` to turn it off.
+
+See [decompose.md](../references/decompose.md#exploratory-routing-on-by-default).
+
+## Waves, and what actually bounds parallelism
+
+A **wave** is the largest set of tasks whose dependencies are all satisfied by earlier waves
+**and** whose declared `files` sets are pairwise disjoint.
+
+Disjointness — not the task count — is the real bound. Two dwarves editing one file produce a
+conflict no reviewer can untangle and no merge can resolve honestly, so they land in different
+waves however the goal was decomposed. When that happens forge says so:
+
+```
+deferrals (serialized to protect the merge):
+  wave 1: lint deferred (file overlap with a task already in this wave)
+```
+
+That line matters. A decomposition that looks parallel but serializes at run time should
+announce it, rather than leaving you wondering why eight tasks took eight rounds. When most
+tasks overlap, the fix is a better split — not more parallelism.
+
+Waves are a planning preview. A Python 3 standard-library coordinator starts eligible tasks
+as prerequisites merge and capacity becomes available, while excluding overlapping active
+paths. Merges are serialized. Each task pins the integration commit at dispatch; retries keep
+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.
+
+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:
+
+```
+# forge run <run-id>
+Goal: <overall goal>
+You are doing ONE task of <N>. Do not do the others' work.
+
+## Your task
+tokens — Add the token model   difficulty: medium
+Files you own: src/auth/token.py
+
+## Run status
+id        diff     status       files
+middleware high    MERGED       src/auth/middleware.py
+tokens     medium  THIS ONE     src/auth/token.py
+docs       low     NOT IN BASE  README.md
+
+## Ground rules
+- Your branch already contains every MERGED task's work — do not reimplement it.
+- Files owned by other tasks are off limits; another dwarf is editing them now.
+- If your task truly needs a change in someone else's file, say so in your final
+  message instead of making it.
+```
+
+It's written **per task**, not once per run — tasks in a wave execute concurrently, so a
+single shared capsule file is a race in which each task overwrites it and reads back whichever
+sibling wrote last, handing a dwarf someone else's task description.
+
+For QA the capsule additionally scopes the review: code from `MERGED` tasks is already in the
+base and is not this task's bug. Without that, a wave-2 reviewer reports wave-1 code as
+defects in the diff it was handed.
+
+## Planning
+
+A dwarf that is handed only an objective plans its own approach, silently, inside its own
+run. Usually fine — but in a decomposed run the capsule prevents two dwarves editing one
+*file* and does nothing about them inventing incompatible *interfaces* at a shared seam.
+Both stay in their lane, both pass their own QA, and the mismatch surfaces at integration.
+
+So forge plans before it dispatches. By default the orchestrator does it and writes the
+approach into each task's prompt — no extra dispatch. `--planner <spec>` hands that stage to
+a named model instead:
+
+```bash
+/forge "migrate the API layer to gRPC" --decompose-level medium \
+  --planner sol:xhigh --dwarf-high sol:high --dwarf luna:high
+```
+
+**One planner dispatch per run, never one per task.** That is the whole point: a single mind
+designs both sides of every seam, where N independent planners would recreate the problem.
+Effort defaults to `xhigh`, since a bad plan is executed at full price by every dwarf
+downstream of it. The planner runs with QA's permission profile — it reads the repo and
+writes nothing to it.
+
+The approach shows up in the approval table under each task, which is the last moment it can
+be changed for free, and it is handed to QA as the *intended* approach — so a review can
+finally say "this works, but it abandons the planned shape" rather than only judging against
+the objective.
+
+## Plan, run, integrate
+
+```bash
+PLAN=/tmp/forge-auth
+
+# 1. plan and inspect the routing
+bash scripts/forge-parallel.sh plan "$PLAN" --repo ~/dev/api \
+  --dwarf-high sol:xhigh --dwarf-low gemini:low:antigravity --dwarf luna:high
+
+# 2. see exactly what will be dispatched, without dispatching
+bash scripts/forge-parallel.sh run "$PLAN" --dry-run
+
+# 3. run it, four dwarves at a time, implementers unsandboxed
+bash scripts/forge-parallel.sh run "$PLAN" --max-parallel 4 --yolo-dwarf
+
+# 4. after reading the results, deliver the passing work
+bash scripts/forge-parallel.sh integrate "$PLAN" --approved
+```
+
+`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
+all their child invocations and QA. See [decomposed Fractal execution](../references/decompose.md#fractal-within-decomposed-tasks).
+
+## Resuming an interrupted run
+
+Run `run` again to skip MERGED tasks, merge saved PASS results after fingerprint checks,
+and dispatch eligible pending tasks. Tasks paused on an infrastructure failure (`INFRA`) are
+dispatched again without any flag, since nothing was wrong with the work. Failed and
+interrupted tasks need an explicit `retry` (or `run --retry-failed N` for rejected ones).
+Their worktrees and pinned baselines remain available. Concurrent run/retry/integrate
+operations for the same plan are excluded by an advisory lock.
+
+For a Fractal-backed run, use `forge fractal resume RUN_ID` to recover recorded execution
+and pipeline checkpoints. A task/subtree selector resumes only that execution scope.
+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
+the rest of a run). When you still want independent work in separate plans — separate locks,
+separate integration branches, one verified at a time — these two make it a supported operation
+instead of hand-built git plumbing:
+
+- `split <plan> <new-plan> --tasks a,b` moves tasks **with their saved state** (attempts,
+  findings, reviewed commit, status) into a new plan: their branches and worktrees are renamed to
+  the new run (`forge/<new>/<id>`), the new integration branch starts at the source's accepted
+  tip, dependencies on already-merged tasks are dropped, and the source forgets the moved rows
+  (`split-<new>.txt` records them). It refuses — changing nothing — for a Fractal-backed plan, a
+  MERGED or RUNNING task, a selection that leaves a dependent behind, or a dependency that is
+  neither moving nor merged. Copy first, delete last; an interrupted split rolls back.
+- `combine <new-plan> <plan-a> <plan-b>…` joins plans whose tasks are **all `MERGED`** into one
+  plan: a new integration branch merges each source's, the per-task records are copied, and
+  `run <new-plan>` then only verifies (no model call) so `integrate` works unchanged. It refuses
+  different repositories, locked or dirty sources, duplicate task ids, and any task left behind;
+  a merge conflict exits `6` after removing everything it created. `--verify` sets the combined
+  plan's check; `--dry-run` previews and predicts conflicts. Task branches keep their original
+  names.
+
+## Scope drift
+
+After each dwarf, the runner compares what the task **declared** in `files` against what it
+actually touched (a declared directory covers the paths beneath it). Undeclared paths appear
+in the summary and in the QA prompt:
+
+```
+scope drift (touched files the task did not declare):
+  auth           src/db.py
+```
+
+Never a failure — a dwarf that genuinely needed one more file did the right thing. What it
+buys is that a merge `CONFLICT` two waves later arrives with its cause already named.
+
+## `tasks.tsv`
+
+Tab-separated, one row per task, written during decomposition:
+
+```
+# id  deps  difficulty  files  dwarf  qa  title
+middleware	-	high	src/auth/middleware.py	-	-	Auth middleware
+tokens	-	medium	src/auth/token.py	-	-	Token model
+route	middleware,tokens	medium	src/routes/login.py	-	-	Login route
+docs	-	low	README.md	-	-	Document the auth flow
+```
+
+| Column | Meaning |
+|---|---|
+| `id` | short unique slug; also the worktree and branch name |
+| `deps` | comma-list of task ids that must land first, or `-` |
+| `difficulty` | `low` \| `medium` \| `high` |
+| `files` | expected touch set, comma-separated — **drives disjointness** |
+| `dwarf` / `qa` | `-` to resolve from the routing rules; an explicit spec always wins |
+| `title` | one line, shown in the approval table and the capsule |
+
+Each task also needs `tasks/<id>/prompt.md`, written the same way a single-task forge goal is.
+
+`files` is a **promise, not a prediction**: it's what the wave planner trusts when deciding
+what may run concurrently, and what the capsule tells other dwarves not to touch. An
+understated `files` is how two dwarves end up in the same file.
+
+`plan` writes resolved specs back into the `dwarf`/`qa` columns, so `run` never consults the
+routing rules — and an explicit value survives a re-plan, which is what makes a gate override
+durable. (`UNASSIGNED` is treated as a leftover marker and re-resolved.)

package/docs/development.md

@@ -0,0 +1,95 @@
+# Development
+
+[← README](../README.md) · [All docs](README.md)
+
+The repository layout, the offline checks, and how forge measures its own runtime cost.
+
+## Repository layout
+
+```
+forge/
+├── SKILL.md                     the skill itself — what the orchestrating model reads
+├── registry.tsv                 alias → (harness, model, effort). Add a row to teach forge a model
+├── README.md                    the short overview
+├── docs/                        the full documentation, one page per topic
+├── LICENSE                      MIT
+├── package.json                 the npm package: its name, version and the files it ships
+├── forge                        launcher, on PATH from npm: `forge install`, `fractal`, `jev`, `dataset` and `ui`
+├── scripts/
+│   ├── forge-dispatch.sh        resolve a spec → run one role on one harness
+│   ├── forge-solo.sh            the whole single-task run: dwarf → diff → qa
+│   ├── forge-parallel.sh        plan / run / retry / integrate for decomposed runs
+│   ├── forge-parallel-options.sh flags shared by several forge-parallel.sh subcommands
+│   ├── forge-lib-task.sh        attempt log, infra stops, QA-only resume, guards, severity gate, report blocks
+│   ├── forge-lib-verify.sh      verify command lookup and the coverage report
+│   ├── forge-lib-plans.sh       accept / split / combine
+│   ├── forge-lib-review.sh      the opt-in whole-run review (review, integrate --final-review)
+│   ├── forge-schedule.py        readiness scheduler: in-run retries, infrastructure pauses
+│   ├── forge-contract.py        the shared QA/dwarf prompt contract and the severity gate
+│   ├── forge-guard.py           implementer guards: session wrapper, orphan reaping, promise scan
+│   ├── forge-verify-coverage.py suites the project defines that the verify command skips
+│   ├── forge-memory.sh          inject / note / record / spend project memory
+│   ├── forge-fractal.py         Fractal CLI and internal adapter entrypoint
+│   ├── forge-fractal-options.sh runner selection, limit flags and help
+│   ├── forge-fractal-dispatch.sh bridge entrypoint for existing pipelines
+│   ├── forge-install-fractal.sh isolated optional runtime installer
+│   ├── forge_fractal/           nested execution, recovery, inspection and dashboard
+│   ├── forge-ui.py              `forge ui open|status|stop`: the one shared forge-ui server
+│   ├── forge-ui-options.sh      `--ui|--no-ui` and the fail-open launch, sourced by the runners
+│   ├── forge_registry.py        the run registry: where run dirs are noted, read by forge-ui
+│   ├── forge-dataset.py         `forge dataset` entry point
+│   ├── forge_dataset/           the run dataset: capture hooks, readers, importer, status checks
+│   └── forge-install.sh         install into every harness that needs it (opencode and grok find it themselves)
+├── ui/                          forge-ui: read-only local run viewer (`forge_ui` package, tests, API contract)
+└── references/
+    ├── ui.md                    forge-ui: commands, env vars, shared server, state, privacy
+    ├── harnesses.md             per-harness invocation, ladders, failure modes
+    ├── decompose.md             tasks.tsv schema, difficulty criteria, wave algorithm
+    ├── fractal.md               opt-in backend, limits, recovery and observability
+    ├── memory.md                FORGE_LEARNING grammar, promotion and pruning rules
+    └── dataset.md               the run dataset: what is captured, where, and its invariants
+```
+
+## Offline checks
+
+Run `bash tests/check.sh` for offline regression checks. See [tests](../tests/README.md) for skill
+invocation scenarios and verification limits. There is currently no CI workflow.
+
+## Runtime efficiency and measurement
+
+Shell entrypoints require Python 3 (standard library only) in addition to Bash and Git.
+The [runtime helper decision](../references/runtime.md) records the module boundaries and tradeoffs.
+Solo and parallel runners default to `--output summary`; use `--output full` to include raw
+backend output. Direct dispatch keeps its full-output default. Read each `dwarf.last` and
+`qa.last` once, and retrieve `.log` or `.out` only when investigating a problem.
+
+QA receives complete requirements, approach, ownership, retry findings and distinct memory
+facts once, with review instructions separate from implementation instructions. Prompts and
+full binary diffs remain on disk. Review repositories receive self-contained tree object packs,
+create baseline/final commits, and check out the final tree once. Exact tree comparisons and
+all source, review and integration fingerprint checks remain acceptance boundaries.
+
+`FORGE_CAPABILITY_CACHE` optionally selects an offline help cache. Runners share a run-local
+`capabilities/` cache across preflights and dispatches. Keys cover the executable's resolved
+path, device/inode, size and modification/change timestamps, help command mode, registry
+contents and dispatch recipe. Every selected spec, effort and permission recipe is still
+validated; cached help never proves authentication or live model availability.
+
+Run `bash scripts/forge-dispatch.sh report <run-dir>` for JSON attempt records, including
+failures and timeouts, with project memory enabled or disabled. `attempts/<role>-<id>/`
+retains prompts, final responses, raw logs, resolution, command and `metrics.json` per dispatch.
+Pipeline records capture preparation, preflight, snapshot, verification and total time;
+dispatch records capture preparation, preflight, model and total time. Nested pipeline
+`dispatch` time includes dispatch overhead: do not add nested totals together. Timing uses
+monotonic seconds. A still-running or forcibly killed record has a null exit code and may
+have incomplete timings. A dispatch that stopped on an infrastructure failure records its class
+(`quota`, `auth`, `rate_limit`, `network`, `empty`) as `infra_class`, and keeps the `.infra` and
+`.orphans` files beside the other attempt artifacts.
+
+Prompt bytes are separate from native input, cached-input and output token counts. Codex
+uses `turn.completed` usage; Claude uses result usage (input includes uncached, cache-read
+and cache-creation tokens). Unsupported or absent usage stays null, never estimated from
+bytes. See [measurement and live evaluation](../tests/README.md).
+
+Measured results, including the live comparison's higher total token use and latency, are
+recorded in [the September 7 evaluation](../tests/benchmark-2026-09-07.md).

package/docs/forge-ui.md

@@ -0,0 +1,128 @@
+# forge-ui
+
+[← README](../README.md) · [All docs](README.md)
+
+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
+and the cloud remembers it.
+
+<p align="center">
+  <img src="../ui/docs/media/cloud.webp" width="880" alt="The run cloud: about seventy runs as blocks in five project spirals, orbited, then laid out as galaxies and as a timeline with one lane per project.">
+</p>
+
+<table>
+<tr>
+<td width="50%" valign="top"><img src="../ui/docs/media/run.png" alt="forge-ui's window: the runs list, a run's eight tasks on a 3D plate in their planned waves with dependency cables, finding marks and the finish nodes, and the run's inspector."><br><b>A run, as planned.</b> Tasks in their waves with dependency cables, ending in integration, verification and the final review. Click a task to open its attempts, dwarves and reviews.</td>
+<td width="50%" valign="top"><img src="../ui/docs/media/execution.png" alt="The same run on wall-clock time: one block per attempt, failed attempts in red with their finding marks, a plane marking now, the concurrency strip, and the inspector's timeline and critical path."><br><b>And as it ran.</b> One block per attempt in the lane it ran in, failed ones in red, against <code>--max-parallel</code>; the inspector names the critical path.</td>
+</tr>
+<tr>
+<td valign="top"><img src="../ui/docs/media/diff.png" alt="The diff a reviewer read, with a P1 finding pinned under the line comparing token digests and a P2 finding under the revoke function."><br><b>Findings on their lines.</b> Any diff of a task, or exactly the diff one reviewer read, with each P0–P3 finding under the line it names.</td>
+<td valign="top"><img src="../ui/docs/media/conversation.png" alt="A dwarf's conversation: its thinking, a search, the files it wrote, a test run that failed with exit 1 and the run that passed after the fix."><br><b>What each agent said and ran.</b> A dwarf's or reviewer's conversation from its CLI's log: commands with their exit and output, edits linked to the diff, its thinking; searchable, errors one key apart, live while it runs.</td>
+</tr>
+<tr>
+<td valign="top"><img src="../ui/docs/media/models.png" alt="The model leaderboard: per implementer, tasks, first-attempt pass rate with a 95% interval bar, retries, escalations, timeouts, accepts, median model time and tokens."><br><b>Models, measured on your runs.</b> First-attempt pass rate with a confidence interval, retries, escalations, time and tokens; reviewers' verdicts and shadow agreement.</td>
+<td valign="top"><img src="../ui/docs/media/files.png" alt="The files heatmap: files grouped by directory against tasks grouped by wave, with planned, touched, drift and same-wave overlap marks."><br><b>Who touched which file.</b> Planned, changed, drifted into or conflicted on, wave by wave; a cell opens that file's diff.</td>
+</tr>
+<tr>
+<td colspan="2" valign="top" align="center"><img width="50%" src="../ui/docs/media/map.png" alt="The map of every run: one block per run in a district per repo, green when done, amber while running, red with failures."><br><b>Every run, by repo.</b> One block per run with a lamp per task, filtered by state, repo, model, age or review verdict.</td>
+</tr>
+</table>
+
+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
+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
+task and model tables sort, reorder and hide columns. forge-ui remembers all of it in your browser.
+
+On the 3D stage every review finding stands over its block as a mark shaped by its severity, and
+a click opens the diff at that finding. A chosen task keeps its route lit, a hover shows its card
+(attempts, time, tokens, worst finding), and merges, failed attempts and escalations play over the
+plate as they happen or as a replay passes them. The *View* menu switches each part of the drawing
+on or off; the keys at the stage's edge fit, zoom, switch between perspective, isometric and
+top-down, open a legend of what is drawn, and `?` lists every key.
+
+Each dwarf's and reviewer's conversation opens from its attempt: what it said, what it ran and
+with what exit, what it changed (with a link into the diff), its thinking folded, and the final
+answer with tokens and cost, searchable, with its errors one key apart and, while it runs,
+following its log as it grows. It is read from the agent CLI's own log, whichever harness
+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
+prompts, diffs and local paths left out unless you choose them.
+
+Offline (it loads three.js from a CDN for the 3D view) the same page works in 2D. It is opt-in.
+The `/forge` skill asks "Open forge-ui to watch this run? [y/N]" at the start of every new
+interactive run, or you pass it yourself:
+
+```sh
+bash scripts/forge-solo.sh "$RUN" --repo "$REPO" --dwarf sol --ui
+bash scripts/forge-parallel.sh plan "$PLAN" --repo "$REPO" --decompose-level medium --ui
+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. 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:
+
+```sh
+python3 ui/tools/demo_runs.py /tmp/forge-demo
+(cd ui && python3 -m forge_ui --no-registry --root /tmp/forge-demo --open)
+```
+
+## `forge ui` command group
+
+| Command | Purpose |
+| --- | --- |
+| `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, and `FORGE_UI_READONLY=1` starts it read-only. State and
+`server.log` are in `${XDG_STATE_HOME:-~/.local/state}/forge/ui/`.