@giamme/forge 0.9.0 → 0.11.0

package/ui/docs/api.md

@@ -13,14 +13,16 @@ forge_ui/diffs.py       unified diffs: parsing, the ```diff fence of a review pr
 forge_ui/models.py      per-run model facts (attempts and reviews) for the leaderboard, cached per run
 forge_ui/fractal.py     Fractal child tasks under $XDG_STATE_HOME/forge/fractal, read through dir fds
 forge_ui/transcripts.py an agent CLI's `<role>.log` read as one conversation, whichever harness wrote it
-forge_ui/server.py      serves those dicts as JSON plus the static page, 127.0.0.1 only
+forge_ui/server.py      serves those dicts as JSON plus the static page, 127.0.0.1 only; authenticates writes
+forge_ui/control.py     the write routes: each one is a forge CLI call (see Controls)
 forge_ui/static/        the page: index.html, app.js, style.css, graph.js and the scripts they load
 ```
 
 Python 3.9+ standard library only. No third-party packages, no build step. The server makes
 no network requests; the page loads three.js 0.160.0 from cdn.jsdelivr.net only when the 3D
-view is used, and falls back to the 2D graph when it can't. The UI is read-only: nothing in
-forge-ui writes to a run dir, a repo or forge's config.
+view is used, and falls back to the 2D graph when it can't. forge-ui never writes to a run dir,
+a repo or forge's config itself: every change is one call of the forge CLI (see Controls (write
+endpoints) below), and `--read-only` removes even that.
 
 ## What a forge plan dir looks like
 
@@ -48,17 +50,17 @@ written), and the reader must never raise because of one.
 | `deferrals.txt` | one line per task the wave planner deferred |
 | `integration.base`, `accepted.integration` | one commit each: where the integration branch started, the revision the run accepted |
 | `attempts/<role>-<uuid>/` | one *execution* (below) of the run itself: `parallel` (a `run`) or `verification` |
-| `final-review-<epoch>-<pid>/` | one whole-run review: `qa.input`, `qa.last`, `verdict` (`PASS FAIL UNKNOWN INVALIDATED ACCEPTED`; absent while it runs or when nothing was judged), `qa.infra`, `qa.gate`, `known_issues.md`, `review.meta` (`key=value`: `base tip source spec threshold`, `threshold=none` when unset), `tasks.summary`, `attempts/qa-<uuid>/` |
+| `final-review-<epoch>-<pid>/` | one whole-run review: `qa.input`, `qa.last`, `verdict` (`PASS FAIL UNKNOWN INVALIDATED ACCEPTED`; absent while it runs or when nothing was judged), `qa.infra`, `qa.gate`, `known_issues.md`, `review.meta` (`key=value`: `base tip source spec threshold integration`, `threshold=none` when unset; `integration` is the integration-branch commit the reviewed result contains and is absent on older runs), `tasks.summary`, `attempts/qa-<uuid>/` |
 | `final-review` | a symlink to the newest *published* review dir; `final-review.verdict` a copy of its verdict |
 | `integrate-<epoch>-<pid>/` | one `integrate`: `setup.log`, `merge.log`, `verification.*`, `attempts/verification-<uuid>/`, and `final-review/` (a review dir as above) when it ran one |
 | `tasks/<id>/merged` | exists when the task was merged; its mtime is when |
 | `tasks/<id>/status` | one word: `RUNNING PASS FAIL ERROR INFRA TIMEOUT UNKNOWN INVALIDATED BLOCKED INTERRUPTED NOCHANGES CONFLICT` |
 | `tasks/<id>/attempt` | the current attempt number |
 | `tasks/<id>/attempts.tsv` | `epoch<TAB>attempt<TAB>status<TAB>infra_class` per line, one per attempt entry; status may also be `MERGED`, `infra_class` may be empty, `-` or missing |
-| `tasks/<id>/escalations.tsv` | `epoch<TAB>attempt<TAB>from_spec<TAB>to_spec` per line |
+| `tasks/<id>/escalations.tsv` | `epoch<TAB>attempt<TAB>from_spec<TAB>to_spec[<TAB>source]` per line; `source` (who decided: `policy`, a human's `retry --dwarf` as `retry`, or a `pin`) is missing on older rows, which read as `policy` |
 | `tasks/<id>/qa.last` | the reviewer's final message; its last line matching `FORGE_VERDICT: PASS` or `FORGE_VERDICT: FAIL` is the verdict |
 | `tasks/<id>/prompt.md`, `approach.md`, `retry_findings.md` | free text |
-| `tasks/<id>/accepted.by` | who accepted a task over a reviewer's FAIL, and why (`key=value` lines in current forge; returned as text) |
+| `tasks/<id>/accepted.by` | who accepted a task over a reviewer's FAIL, and why (`key=value`: `task`, `status`, `reason`, `by`, `at`, `epoch`, `attempt`, `reviewed_commit`; older runs are free text; returned as text) |
 | `tasks/<id>/qa.gate` | `threshold<TAB>decision<TAB>worst<TAB>n_confirmed<TAB>n_unlabelled<TAB>n_below` (`decision` is `accept` or `keep`, `-` for none) |
 | `tasks/<id>/known_issues.md` | the confirmed findings a threshold tolerated |
 | `tasks/<id>/dwarf.input`, `qa.input` | the prompts forge assembled; `<role>.delivered`, `<role>.resolved` the live dispatch files |
@@ -178,8 +180,11 @@ class Catalog:
         fractal(self, key, task_id),
         fractal_node(self, key, task_id, node), fractal_node_diff(self, key, task_id, node) -> dict | None
     def models(self) -> dict            # Models, over every run
+    def locate(self, key) -> tuple[str, str] | None  # (run dir, 'plan' | 'solo'); None for an unknown key
 ```
 
+`Catalog.locate` is how a write finds its run: a client names a run by key and never by path.
+
 `Catalog` re-discovers and re-reads on every call: runs change while they are watched. Files
 that stop changing once written (`metrics.json`, `dataset.json`, `*.resolved` and `qa.last`
 copies, findings of a reply) are parsed once and kept by `(dev, inode, size, mtime_ns)`; a
@@ -221,12 +226,22 @@ its last 20,000 behind a leading `…`. Their `truncated` lists the field names
 | `GET /api/runs/<key>/findings` | `200 RunFindings` |
 | `GET /api/runs/<key>/executions/<qa-or-dwarf>/transcript` | `200 ExecutionTranscript` |
 | `GET /api/models` | `200 Models` |
+| `GET /api/health` | `200 {"app": "forge-ui", "version", "build", "pid", "controls": true\|false}`; `controls` is `false` in read-only mode |
+| `GET /api/runs/<key>/controls` | `200` the `forge control show --json` object of a plan run (see Controls); `404` for a solo or unknown run |
+| `POST /api/runs/<key>/controls` | change one control or pin; authenticated, see Controls (write endpoints) |
+| `GET /api/runs/<key>/issues?scope=run\|repo&offline=0\|1&plausible=0\|1&dismissed=0\|1&only=fp,fp` | `200` the `forge issues --json` listing, run fresh on every request (no cache); see Controls (write endpoints) |
+| `POST /api/runs/<key>/issues` | file GitHub issues for chosen findings; authenticated, 300 s timeout |
+| `POST /api/runs/<key>/issues/dismiss` | dismiss or (`undo`) restore findings; authenticated |
+| `POST /api/runs/<key>/delete` | dry-run or delete a run with `forge runs rm`; authenticated, 900 s timeout; later requests for the key answer `404` |
+| `GET /api/models/reviewers` | `200` the `forge dataset reviewers --json` report (how each reviewer's PASSed work held up); no parameters |
+| `GET /api/config?run=<key>` | `200` the `forge config show --json` of that run's repo |
+| `POST /api/config` | set or unset one allowed key (`repo.verify`, `repo.setup`, `repo.verify-subset`, `jev.enabled`); authenticated |
 | `GET /api/runs/<key>/export?texts=0\|1&paths=0\|1` | `200` the run as one HTML file (see Export), `Content-Disposition: attachment`, `Content-Security-Policy: default-src 'none'; sandbox`; `404` for an unknown run |
 | `GET /api/runs/<key>/tasks/<id>/fractal` | `200 TaskFractal` |
 | `GET /api/runs/<key>/tasks/<id>/fractal/nodes/<node>[/diff]` | `200 FractalNodeDetail`, or with `/diff` a `DiffDetail` of its `candidate.diff`; `<node>` matches `[A-Za-z0-9][A-Za-z0-9_-]{0,100}` |
 | `GET /` | `forge_ui/static/index.html` |
 | `GET /<name>` | that file from `forge_ui/static/` (`.html .js .css .svg` only, no subdirs) |
-| anything else | `404 {"error": "not found"}`; any method but GET or HEAD: `405` |
+| anything else | `404 {"error": "not found"}` (an unknown path or run); a method a path does not take (PUT, DELETE, OPTIONS, a POST to a read path): `405` with `Allow`, except that a GET to a path that only takes POST (`/api/runs/<key>/delete`, `/api/runs/<key>/issues/dismiss`) answers `404` |
 
 The lazy endpoints answer `404 {"error": "not found"}` for an unknown run, task,
 execution or review; the diff endpoints also for a `<which>` the run kind has not (`existing`
@@ -272,18 +287,20 @@ nothing when there is none. Every other response keeps
   "counts": {"MERGED": 3, "RUNNING": 1, "PENDING": 1},
   "verification_status": "PASS",
   "created": 1760619000.0,
-  "task_statuses": [{"id": "reader", "status": "MERGED", "difficulty": "high", "title": "Read plan dirs"},
-                    {"id": "page", "status": "RUNNING", "difficulty": "medium", "title": "Draw the page"}],
+  "task_statuses": [{"id": "reader", "status": "MERGED", "difficulty": "high", "title": "Read plan dirs", "accepted": true},
+                    {"id": "page", "status": "RUNNING", "difficulty": "medium", "title": "Draw the page", "accepted": false}],
   "models": ["opus", "sol:xhigh"],
   "dwarf_models": ["sol:xhigh"],
   "qa_models": ["opus"],
-  "final_review": "FAIL"
+  "final_review": "FAIL",
+  "final_review_outdated": false
 }
 ```
 
-- `task_statuses`: every task in `tasks.tsv` order, with its `difficulty` (`null` when empty) and
-  `title` (its first 160 characters, then `…`). A solo run: `[{"id": "solo", "status": <solo status>,
-  "difficulty": null, "title": <goal or "Solo run">}]`.
+- `task_statuses`: every task in `tasks.tsv` order, with its `difficulty` (`null` when empty),
+  `title` (its first 160 characters, then `…`) and `accepted` (`true` when `tasks/<id>/accepted.by`
+  is a non-empty file). A solo run: `[{"id": "solo", "status": <solo status>, "difficulty": null,
+  "title": <goal or "Solo run">, "accepted": false}]`. `accepted` does not change `status` or `counts`.
 - `created`: when the run began: the earliest birth time (else mtime) of the files a run writes
   once at its start (plan: `run_id`, `repo`, `request.md`, `goal.txt`, `tasks.tsv`; solo: `prompt.md`,
   `repo`, `request.md`, `goal.txt`), else `null`. These are stat'ed only, and never move `updated`.
@@ -292,6 +309,11 @@ nothing when there is none. Every other response keeps
   and `qa` specs as its task has them), nulls left out.
 - `final_review`: the first word of `final-review.verdict`, else `null`; always `null` for a
   solo run. (RunDetail replaces it with an object, below.)
+- `final_review_outdated`: `true`, `false` or `null`, for the published review only (the dir the
+  `final-review` link points to, when that link stays inside the plan). The same rule as
+  FinalReviewSummary `outdated`, below. `null` when there is no such review, it has no verdict, or
+  `accepted.integration` is missing; always `null` for a solo run. RunDetail keeps this field
+  (it is not replaced by the newest review's `outdated`).
 
 `kind` is `"plan"` or `"solo"`. `updated` is the newest mtime (epoch seconds, float) among
 the run dir and the files the reader read. Any field it cannot determine is `null`
@@ -302,7 +324,11 @@ are `null`, `task_count` is 1, and `counts` is `{<status>: 1}` using the solo st
 The summary reads only `repo`, `goal.txt`, `status`, `verdict`, `dwarf.spec`, `qa.spec` and,
 when a spec file is missing, `*.resolved`. It also stats `dwarf.log` and `qa.log` without
 reading them, so `updated` moves while a model is writing a log. A plan summary reads
-`final-review.verdict` besides the files it always read.
+`final-review.verdict` besides the files it always read. For `final_review_outdated` it also
+reads `accepted.integration` and, through the `final-review` link, that dir's `verdict` and
+`review.meta`, and stats each task's `merged` marker. Those reads count toward `updated`, the
+same way as every other file the summary reads, so a newer `accepted.integration` moves the
+run's activity time. It does not open a review's attempts or scan the other review dirs.
 
 ## RunDetail
 
@@ -356,7 +382,9 @@ Every RunSummary field, plus:
   path of its review dir or `null`, `ended` the latest end of its verification and review
   executions (`null` while one is unfinished or there is none).
 - `final_review` is the newest FinalReviewSummary (review and integrate dirs together, by the
-  epoch in the name), or `null`; `final_reviews` lists the newest 20, newest first.
+  epoch in the name), or `null`; `final_reviews` lists the newest 20, newest first. That newest
+  review's `outdated` is its own. `final_review_outdated` stays the published review's flag, so
+  the two differ when a newer review exists than the one `final-review` links to.
 - `deferrals`: the non-empty lines of `deferrals.txt`, `[]` when it is missing.
 - `findings_available`: whether `scripts/forge-contract.py` could be loaded.
 - `fractal`: `null` without `fractal-selection.json`, else `{"enabled", "run", "available", "reason"}`
@@ -386,9 +414,12 @@ Every RunSummary field, plus:
   "attempt": 2,
   "attempts": [{"at": 1760620000.0, "attempt": 1, "status": "FAIL", "infra": null},
                {"at": 1760621000.0, "attempt": 2, "status": "PASS", "infra": null}],
-  "escalations": [{"at": 1760620500.0, "attempt": 2, "from": "luna", "to": "sol"}],
+  "escalations": [{"at": 1760620500.0, "attempt": 2, "from": "luna", "to": "sol", "source": "policy"}],
   "verdict": "PASS",
   "accepted_by": null,
+  "accepted": false,
+  "accepted_attempt": null,
+  "accepted_over": null,
   "explored": true,
   "route": [{"at": 1760619000.0, "task": "reader", "tier": "high", "epsilon": 0.5,
              "candidates": ["astra", "opus"], "default": "opus", "chosen": "astra",
@@ -421,7 +452,16 @@ Every RunSummary field, plus:
 - `attempt`: integer from `tasks/<id>/attempt`, else the highest attempt in `attempts`,
   else `null`.
 - `infra` in an attempt: `null` for empty, `-` or missing.
+- `source` in an escalation: the 5th column of `escalations.tsv` (`policy`, `retry` or `pin`, as forge wrote it); `policy` when the row has only 4 columns or the cell is empty.
 - `verdict`: `"PASS"`, `"FAIL"` or `null`, from `qa.last` as described above.
+- `accepted`: `true` when `accepted.by` is a non-empty file, on `task_statuses` and on the task.
+  `status` stays what the merged marker or `status` file says (`MERGED` when the marker is there)
+  and `counts` do not change.
+- `accepted_attempt`: the integer `attempt=` of `accepted.by`, or `null` when the key is missing
+  or not an integer (not an integer is warned). On the task, not on `task_statuses`.
+- `accepted_over`: `"FAIL"` or `"UNKNOWN"` when `status=` in `accepted.by` says so; `null` for any
+  other or missing value, including `PASS` (the panel then says plain "accepted"). On the task,
+  not on `task_statuses`. A free-text `accepted.by` from an older forge has both null.
 - `dwarf_tail`: the last 4,000 characters of `dwarf.last` (`tasks/<id>/dwarf.last` for a
   plan task, the run dir's `dwarf.last` for a solo run), or `null` when the file is missing.
   Capped like `qa_tail`.
@@ -453,8 +493,9 @@ it is missing or `<harness default>`). `wave` is 1, `branch` is `null`, and `att
 from the run dir's `attempts.tsv`. `status` is the solo status; `attempt` is the highest `n`
 in `attempts.tsv`, or `null`. `escalations`, `route` and `shadow` are empty. `verdict` and
 `qa_tail` come from `qa.last`, and `prompt` comes from `prompt.md`. `deps` and `files` are
-`[]`; `difficulty`, `accepted_by`, `approach` and `retry_findings` are `null`; `explored` is
-false; `clef` is `{first_pass: null, retry_pass: {}}`. `request` on the detail is `request.md`.
+`[]`; `difficulty`, `accepted_by`, `approach` and `retry_findings` are `null`; `accepted` is
+false; `accepted_attempt` and `accepted_over` are `null`; `explored` is false; `clef` is
+`{first_pass: null, retry_pass: {}}`. `request` on the detail is `request.md`.
 
 ## Execution
 
@@ -523,6 +564,7 @@ block's 1-based line in the reply. Lists of Findings keep the first 200.
 ```json
 {"name": "final-review-1760622000-4242", "source": "review", "at": 1760622000.0, "published": true,
  "verdict": "FAIL", "state": "done", "spec": "opus", "threshold": "P2", "base": "1a2b...", "tip": "3c4d...",
+ "integration": "3c4d...", "outdated": false, "merged_since": [],
  "gate": {...}, "findings": FindingsSummary, "execution": "qa-...",
  "started": 1760622010.0, "ended": 1760622400.0, "duration_s": 390.0}
 ```
@@ -533,7 +575,29 @@ block's 1-based line in the reply. Lists of Findings keep the first 200.
   publishes nothing).
 - `state`: `done` with a verdict, `infra` with `qa.infra`, `running` when it is the newest
   review and has `qa.input`, else `orphaned`.
-- `spec`, `threshold`, `base`, `tip` come from `review.meta` (`threshold=none` is `null`).
+- `spec`, `threshold`, `base`, `tip`, `integration` come from `review.meta` (`threshold=none` is
+  `null`). `integration` is the integration-branch commit the reviewed result contains, or `null`
+  when missing, empty, or not a commit. A commit is the object name `git rev-parse` writes: 40
+  or 64 lowercase hex digits. Any other `integration=` value is warned on that
+  `review.meta` (`integration is not a commit`; the summary's read of the published dir
+  warns `final-review/review.meta`) and is not a known commit, so freshness uses the next rule.
+  `source` on this object is the dir kind, `review` or `integrate`, not `review.meta`'s
+  `source=` (a worktree path).
+- `outdated`: whether the plan's integration branch has moved since this review. `null` when the
+  review has no verdict, or when `accepted.integration` is missing. Otherwise the first rule that
+  applies:
+  1. `integration` is a commit: `true` when it differs from `accepted.integration`.
+  2. Else, for `source` `review`: `true` when `tip` differs from `accepted.integration`.
+  3. Else (an integrate review from an older forge, which has no `integration=` commit): `true`
+     when any task merged after the review started.
+- `merged_since`: the ids of tasks merged after the review started, oldest merge first. `[]` when
+  the review is not outdated. It may also be `[]` for an outdated review whose only later merge
+  fell inside the review's starting second.
+- A task merged after the review when the mtime of its `merged` marker is `>= at + 1`, where `at`
+  is the whole-second epoch in the review dir's name. A merge inside that starting second is
+  ambiguous and is not counted. The execution's `started` is not used.
+- `outdated` means tasks merged into the plan's integration branch since the review. Changes on
+  the user's own branch after an integrate are not tracked.
 - `execution` is its newest `attempts/qa-*`; `started`, `ended`, `duration_s` are that
   execution's.
 
@@ -647,13 +711,15 @@ lists, for all tasks and final reviews at once, without `text` or `line`.
             "verdict": "FAIL", "findings": [{"id": "qa-…:0", "severity": "P1", "status": "CONFIRMED",
                                              "location": "ui/reader.py:42", "summary": "…"}]}]}],
  "final_reviews": [{"name": "final-review-…", "execution": "qa-…", "spec": "sol", "verdict": "FAIL",
+                    "outdated": true, "merged_since": ["reader"],
                     "findings": [{"id": "qa-…:0", "severity": "P2", "status": "CONFIRMED", "location": null, "summary": "…"}]}],
  "truncated": [], "warnings": []}
 ```
 
 A task's `reviews` are every primary and shadow review of every attempt that listed a Finding
-(a solo run has one task, `solo`); `final_reviews` the newest 20 final reviews that did. A
-Finding's `id` is `<execution>:<n>`, `n` its 0-based place in the reply (`primary:<n>` or
+(a solo run has one task, `solo`); `final_reviews` the newest 20 final reviews that did. Each
+of those carries `outdated` and `merged_since`, the same values as that review's
+FinalReviewSummary. A Finding's `id` is `<execution>:<n>`, `n` its 0-based place in the reply (`primary:<n>` or
 `final:<n>` for a reply without an execution); the DiffDetail that pins it gives it the same
 `id`, so a mark on the stage opens that Finding in the diff. `available` is `false` without the
 contract module, and the lists are then empty.
@@ -892,10 +958,182 @@ difficulty paths deps model` each), `decomposition_history` (its newest 20, each
   style-src <sha256 of the style>; img-src data: blob:; font-src data:; connect-src 'none'; base-uri 'none';
   form-action 'none'; object-src 'none'`. Inside a script, `</script` and `<!--` are escaped; the
   JSON escapes `<`, `>` and `&`.
+- The write token (below) is never in an export: the file has no controls.
 - In the page, `app.js` reads the snapshot instead of the network, never polls, shows only the
   exported run (any other route goes to it) and a banner with the export's date and what it left
   out; the cloud, the leaderboard and notifications are not there.
 
+## Controls (write endpoints)
+
+forge-ui changes a run only by calling the forge CLI. The server holds no code that writes a run
+dir, a repo or config; a write route builds an argv, runs it, and answers with what the CLI said.
+`forge_ui/control.py` holds the route table (`ROUTES`: method, path pattern, handler), the body
+validation, the call and the exit-code mapping; `server.py` does the authentication and gives
+each authenticated POST to the table, so a new write route is one entry in it.
+
+**The call.** `[<forge root>/forge, ...]`, an argv list with no shell, `stdin` closed, in a process
+group of its own. `<forge root>` is two directories above `forge_ui/` and can be replaced as
+`forge_ui.server.forge_cli`. A call that outlives its timeout (60 s) gets SIGTERM for its whole
+group, SIGKILL 5 s later if anything is left, and is reaped, all before the run's lock is
+released; the answer is `504 {"error": "timeout", "detail": "the operation may have partly
+completed; reload to see the current state"}`.
+
+**Runs are named by key.** The path holds the 12-hex run key and nothing else; the server finds
+the run dir with `Catalog.locate(key)`. A body field never names a path, and a field the route does
+not know is a `400`.
+
+**Authentication.** Each server process makes a random token (`secrets.token_urlsafe(32)`). `GET /`
+(and `/index.html`) carries it as `<meta name="forge-ui-token" content="...">` as the first element
+of `<head>`; the page script reads it and sends it back. The page's CSP is unchanged (its hash
+covers only the import map). Every POST must pass all of these, checked in this order, or it is
+refused before any route or CLI runs:
+
+| Check | Refusal |
+|---|---|
+| `Host` is `127.0.0.1` or `localhost` (any port) | `403 {"error": "forbidden"}` |
+| server is not read-only | `405` (below) |
+| `X-Forge-UI-Token` equals the token (`hmac.compare_digest`) | `403` |
+| `Content-Type` is `application/json` (parameters allowed) | `400` |
+| `Origin`, when sent, is exactly `http://` + the `Host` header | `403` |
+| `Content-Length` present, a number, no `Transfer-Encoding` | `400` |
+| the body is at most 64 KiB | `413 {"error": "payload too large"}` |
+| the body is UTF-8 JSON and an object | `400 {"error": "bad request"}` |
+
+No response carries `Access-Control-*` headers and `OPTIONS` is a `405` (`Allow` lists the methods
+the path takes), so a page on another origin can neither preflight nor read an answer. The token is
+not in `/export`, in a log line or in any JSON response.
+
+**Read-only mode.** `python3 -m forge_ui --read-only`, or `FORGE_UI_READONLY=1` (also `true`, `yes`,
+`on`). Every POST (after the Host check) is `405 {"error": "method not allowed"}` with
+`Allow: GET, HEAD`, the page has no token, and `/api/health` says `"controls": false`
+(`true` otherwise). Reads, `GET .../controls` included, still work. `forge ui open` passes the mode
+to the server it starts, records it in `server.json` (`read_only`) and never reuses a running server
+of the other mode: it replaces it as it does one running other code. `forge ui status` shows the
+mode (`read_only` in its JSON).
+
+**The CLIs' configuration.** The server `forge ui open` starts runs without any `FORGE_*` variable
+of the shell it was started from. The CLIs its writes call still need the forge configuration, so
+`open` hands them these, as that shell has them (an empty value counts as unset; a relative
+`FORGE_REGISTRY` or `FORGE_DATA_HOME` is made absolute against the shell's directory):
+`FORGE_REGISTRY`, `FORGE_DATA_HOME`, `FORGE_DATASET`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME` and
+`XDG_STATE_HOME` (`control.CLI_ENV_NAMES`). It writes them to `cli-env.json` (mode `0600`) in its
+state dir, the server loads that file once when it starts (`_serve --cli-env FILE`) and every CLI
+call gets them on top of the server's own environment; the server's environment itself is not
+changed. No other variable is passed, and none of these is a secret. `server.json` records them as
+`cli_env`. A server started by hand (`python3 -m forge_ui`) passes its own environment unchanged.
+
+`open` never reuses a server whose recorded `cli_env` differs from the current shell's. It names
+each variable that differs and both values, says to run `forge ui stop` and then open again, exits
+`5`, prints no link and leaves the server running (it may be in the middle of another shell's
+write). A server
+running other code, in the other mode or reading another registry directory is still replaced, and
+the new one gets the current shell's configuration.
+
+**Serialization.** One write per run key at a time. A second write to a run whose write is still
+running is `409 {"error": "busy"}`, without reaching the CLI; other runs are not held up.
+
+**Errors.** For a CLI that exits non-zero the answer is `{"error", "detail", "result"?}`: `detail`
+is the last line of its stderr (at most 300 characters; the rest of stderr is not echoed) and
+`result` the object its stdout holds, when that parses as one.
+
+| CLI exit | Status | `error` |
+|---|---|---|
+| 0 | `200` | the CLI's stdout JSON object, as it is |
+| 2 (invalid input) | `400` | `invalid` |
+| 3 (refused: not live, MERGED, a Fractal plan, a pin that fails doctor, the control lock busy) | `409` | `refused` |
+| 4 (a failure the CLI reported) | `500` | `failed` |
+| anything else, a signal, a missing CLI, or a 0 with no JSON object | `502` | `bad gateway` |
+| timeout | `504` | `timeout` |
+
+For the controls routes, unknown run keys, solo runs (they have no controls) and runs the
+catalog does not hold are `404 {"error": "not found"}`. The issues, dismiss, delete and config
+routes below accept plan and solo runs alike (`forge issues` and `forge runs rm` take both);
+for them only unknown keys and runs the catalog does not hold are `404`. Every write that reaches a route logs
+`forge-ui: control <route> <run key> -> <status>` unless the server runs with `--quiet`.
+
+### `GET /api/runs/<key>/controls`
+
+`forge control show <plan dir> --json`: `200` with its object (`plan`, `run_id`, `live`, `fractal`,
+`run` (the plan-wide controls), `tasks` (per task: `status`, `dwarf`, `qa`, `qa_threshold`,
+`retry_budget`, `retries_used`, `pin`, `escalation_stop`, `escalation_next`) and `log`). No token
+is needed to read it.
+
+### `POST /api/runs/<key>/controls`
+
+One of these bodies. Every string is non-empty, at most 256 characters, has no control character
+and does not start with `-`; `400 {"error": "invalid", "detail": ...}` otherwise, and for a wrong
+shape or type, before the CLI is called. Whether a key exists, a value is in range, a task is
+known or a spec runs is for the CLI to say (its `400` or `409` comes back as above).
+
+| Body | CLI call (after `forge`) |
+|---|---|
+| `{"action": "set", "key": "qa-threshold", "value": "P2"}` | `control set <dir> qa-threshold P2 --actor ui --json` |
+| `{"action": "set", "key": "retry-budget", "value": "inherit", "task": "reader"}` | `control set <dir> retry-budget inherit --task reader --actor ui --json` |
+| `{"action": "pin", "task": "graph", "spec": "sol:high:codex"}` | `control pin <dir> graph sol:high:codex --actor ui --json` |
+| `{"action": "unpin", "task": "graph"}` | `control unpin <dir> graph --actor ui --json` |
+
+`value` is always a string. `task` is optional on `set`, and only for the keys the CLI allows it
+for. A success is `200 {"ok": true, "changed": {...}, "applies": "...", "controls": {...}}`, where
+`controls` is the `GET` object after the change.
+
+### `GET /api/runs/<key>/issues`
+
+`forge issues <dir> --json [flags]`: the findings the run left open. Query (all optional, an
+unknown or repeated parameter is a `400`): `scope=run|repo` (`repo` adds `--all-runs`),
+`offline=0|1` (`--offline`), `plausible=0|1` (`--include-plausible`), `dismissed=0|1`
+(`--include-dismissed`), `only=fp,fp` (`--only`; one to 25 fingerprints, each `^[0-9a-f]{12}$`).
+`200` with the CLI's object (`findings`, ...). **Never cached**: every request is one CLI call; the
+page asks for an `offline=1` listing first for speed and then for the full one. It takes no lock (a
+busy CLI is its own exit 3, `409`). No token is needed. Plan and solo runs. Timeout 120 s.
+
+### `POST /api/runs/<key>/issues`
+
+File issues for findings. Body: `{"scope": "run"|"repo" (default run), "fingerprints": [1 to 25 of
+^[0-9a-f]{12}$], "include_plausible": bool, "labels": [at most 5 texts of 1 to 50 characters, no
+control character, not starting with "-"]}`; any other field is a `400`. Runs `issues <dir> --only
+<fps> --max-issues <number of fps> --apply --json` plus `--all-runs`, `--include-plausible` and one
+`--label` per label. `200` with the CLI's object. Under the run's write lock (`409 busy`). Timeout
+300 s.
+
+### `POST /api/runs/<key>/issues/dismiss`
+
+Body: `{"fingerprints": [1 to 25], "reason"?: text of at most 500 characters without control characters (newline and tab are allowed), "undo"?: bool}`. Runs
+`issues <dir> --json --dismiss <fps> [--reason R]`, or `--undismiss <fps>` when `undo` is true
+(a reason with `undo` is a `400`). Under the run's write lock. Timeout 60 s.
+
+### `POST /api/runs/<key>/delete`
+
+Body: `{"dry_run": bool (false), "archive": bool (true), "worktrees": bool (false), "branches": bool
+(false)}`. Runs `runs rm <dir> --json` with `--dry-run` or `--yes`, plus `--no-archive` when
+`archive` is false, `--worktrees`, `--branches`. `200` with the CLI's object. The CLI prints its
+JSON on failure too, so a non-zero exit answers with that object as `result` (its `steps` show what
+completed): exit 2 `400`, exit 3 (busy or the run is active) `409`, exit 4 (failed during
+deletion) `500`. Deletion holds the run's write lock and a server-wide lock on the run's real
+directory (`409 busy` when either is held). The run key is looked up again under the lock, and
+once the directory is gone every later request for that key is `404`. Timeout 900 s.
+
+### `GET /api/models/reviewers`
+
+Runs `dataset reviewers --json` and answers with its object: `horizon_days`, `min_landed`,
+`survives_at`, `reviewers` (per reviewer alias: `landed`, `reverted`, `rewritten`,
+`did_not_hold`, `enough`, and `rate` and `ci` only when `enough`, else `null` with a `note`),
+`unattributed`, `skipped` and `other_horizons`. Any query parameter is a `400`. Not cached: every
+request runs the CLI, and the page asks once per change of `/api/models`. Advisory: it feeds the
+Reviewers table's Did not hold column and nothing else. Timeout 60 s.
+
+### `GET /api/config?run=<key>` and `POST /api/config`
+
+The repository is the run's own `repo` file (first line, an existing absolute directory; else
+`409`), never a client field. `GET` runs `config show --repo <repo> --json` and answers with its
+object. `POST` takes `{"run": <key>, "key": one of repo.verify, repo.setup, repo.verify-subset,
+jev.enabled, "value": text | "unset": true}` (exactly one of the two; any other field, `repo`
+included, is a `400`) and runs `config set <key> <value> --repo <repo> --json` or `config unset
+<key> --repo <repo> --json`. A value is a non-empty text of at most 4096 characters without
+control characters (newline and tab are allowed), not starting with `-`; `jev.enabled` takes
+`true` or `false` and cannot be unset; `repo.verify-subset` must contain `{files}`. `200` with the
+CLI's object (`ok`, `key`, `previous`, `value`). Writes serialize on one server-wide config lock
+(`409 busy`). Unknown run `404`. Timeout 60 s.
+
 ## Status vocabulary for the page and the graph
 
 Both the page and the graph mark a task by its status with the CSS class

package/ui/forge_ui/__main__.py

@@ -21,7 +21,7 @@ DEFAULT_PORT = 8765
 def _parser():
     parser = argparse.ArgumentParser(
         prog='python3 -m forge_ui',
-        description='A small, read-only local UI for forge runs. Listens on 127.0.0.1 only.')
+        description='A small local UI for forge runs. Listens on 127.0.0.1 only. Its changes to a run go through the forge CLI.')
     parser.add_argument('--plan', action='append', default=[], metavar='DIR',
                         help='a plan dir to show (repeatable)')
     parser.add_argument('--root', action='append', default=[], metavar='DIR',
@@ -35,11 +35,19 @@ def _parser():
     parser.add_argument('--idle-exit', type=int, default=0, metavar='SECONDS',
                         help='exit after SECONDS with no request (default 0, which never exits)')
     parser.add_argument('--quiet', action='store_true', help='do not log requests')
+    parser.add_argument('--read-only', action='store_true',
+                        help='answer no write at all (also FORGE_UI_READONLY=1); the page shows no controls')
     parser.add_argument('--open', action='store_true', help='open the page in the browser once started')
     parser.add_argument('--version', action='version', version=f'forge-ui {__version__}')
     return parser
 
 
+def read_only_requested(flag, environ=None):
+    """--read-only, or FORGE_UI_READONLY set to 1/true/yes/on."""
+    value = (os.environ if environ is None else environ).get('FORGE_UI_READONLY', '')
+    return bool(flag) or value.strip().lower() in ('1', 'true', 'yes', 'on')
+
+
 def _message(level, text):
     print(f'forge-ui: {level}: {text}', file=sys.stderr)
 
@@ -100,7 +108,7 @@ def main(argv=None):
     catalog = reader.Catalog(plans=args.plan, roots=args.root, registry=not args.no_registry,
                              registry_dir=args.registry_dir)
     try:
-        server = make_server(catalog, HOST, args.port, quiet=args.quiet)
+        server = make_server(catalog, HOST, args.port, quiet=args.quiet, read_only=read_only_requested(args.read_only))
     except OSError as exc:
         if exc.errno == errno.EADDRINUSE:
             _message('error', in_use)