@giamme/forge 0.8.0 → 0.10.0

package/ui/docs/api.md

@@ -12,14 +12,17 @@ forge_ui/findings.py    QA findings and gate lines, parsed by scripts/forge-cont
 forge_ui/diffs.py       unified diffs: parsing, the ```diff fence of a review prompt, pinning findings, cached reads
 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/server.py      serves those dicts as JSON plus the static page, 127.0.0.1 only
+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; 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
 
@@ -54,7 +57,7 @@ written), and the reader must never raise because of one.
 | `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) |
@@ -85,7 +88,8 @@ one of `task dwarf qa solo verification parallel` and `<uuid>` 32 lowercase hex
 | `dataset.json` | may be absent: `parent` (the execution that started this one, e.g. `task-<uuid>`), `trigger`, `attempt_start` and `resume` (task executions) |
 | `<role>.resolved`, `.prompt`, `.last`, `.timedout` | copies made when it finished: the model resolution (`key=value`), the prompt, the final message, the timeout marker |
 
-The reader never opens an execution's `.log` or `.cmd`.
+Only the transcript endpoint opens an execution's `.log` (a `dwarf`'s or `qa`'s, see
+ExecutionTranscript); no read opens a `.cmd`.
 
 **Task status** is `MERGED` if `tasks/<id>/merged` exists, otherwise the first word of
 `tasks/<id>/status`, otherwise `PENDING`.
@@ -158,6 +162,8 @@ def task_diff(path, task_id, which='current', source='plan') -> dict | None  # a
 def execution_diff(path, name, source='plan') -> dict | None       # a DiffDetail
 def final_review_diff(path, name, source='plan') -> dict | None    # a DiffDetail
 def files_detail(path, source='plan') -> dict | None               # Files
+def run_findings(path, source='plan') -> dict | None               # RunFindings
+def execution_transcript(path, name, source='plan') -> dict | None # an ExecutionTranscript
 def fractal_detail(path, task_id, source='plan') -> dict | None    # a TaskFractal
 def fractal_node(path, task_id, node, source='plan') -> dict | None       # a FractalNodeDetail
 def fractal_node_diff(path, task_id, node, source='plan') -> dict | None  # a DiffDetail
@@ -170,11 +176,15 @@ class Catalog:
     def execution(self, key, name) -> dict | None
     def final_review(self, key, name) -> dict | None
     def diff(self, key, task_id, which='current'), execution_diff(self, key, name),
-        final_review_diff(self, key, name), files(self, key), fractal(self, key, task_id),
+        final_review_diff(self, key, name), files(self, key), findings(self, key), transcript(self, key, name),
+        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
@@ -213,17 +223,29 @@ its last 20,000 behind a leading `…`. Their `truncated` lists the field names
 | `GET /api/runs/<key>/executions/<qa-or-dwarf>/diff` | `200 DiffDetail` of the diff that review read (a dwarf: its attempt's primary review) |
 | `GET /api/runs/<key>/final-reviews/<name>/diff` | `200 DiffDetail` |
 | `GET /api/runs/<key>/files` | `200 Files` |
+| `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/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`
-of a plan task, `prev` of a solo run) and for an execution that is not `qa` or `dwarf`; the
+of a plan task, `prev` of a solo run), the diff and transcript endpoints for an execution that is
+not `qa` or `dwarf`; the
 Fractal node endpoints for an unknown node or a task whose Fractal state is not `available`. A
 diff that is not there yet is a `200` with `available: false`. An execution is looked for only where executions are written:
 `attempts/`, `tasks/<id>/attempts/`, `shadow/<id>/<a>-<k>/attempts/`,
@@ -378,7 +400,7 @@ 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,
   "explored": true,
@@ -413,6 +435,7 @@ 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.
 - `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.
@@ -577,7 +600,7 @@ of Findings, in place of the summary), `truncated` and `warnings`.
             "additions": 5, "deletions": 1, "truncated": false,
             "hunks": [{"old_start": 38, "old_lines": 7, "new_start": 38, "new_lines": 10,
                        "section": "def _tasks(reader):", "lines": [" ctx", "-old", "+new"]}]}],
- "findings": [{"review": {"kind": "primary", "execution": "qa-…", "attempt": 2, "spec": "opus"},
+ "findings": [{"id": "qa-…:0", "review": {"kind": "primary", "execution": "qa-…", "attempt": 2, "spec": "opus"},
                "severity": "P1", "status": "CONFIRMED", "location": "ui/reader.py:42",
                "summary": "…", "text": "…",
                "pin": {"file": 0, "path": "ui/reader.py", "line": 42, "side": "new", "hunk": 0, "index": 5},
@@ -597,7 +620,7 @@ of Findings, in place of the summary), `truncated` and `warnings`.
 | `truncated` | the read stopped at 8 MiB (at a line end), the fence never closed, more than 300 files, or a file is `truncated` |
 | `files[]` | per file of the diff: `old` (`null` when added), `new` (`null` when deleted), `status` `modified added deleted renamed copied`, `binary` (`Binary files … differ` or a `GIT binary patch`, whose body is skipped), `additions`, `deletions` (of the whole file, even when cut), `truncated`, `hunks` |
 | `hunks[]` | `old_start`, `old_lines`, `new_start`, `new_lines` (a count left out is 1), `section` (after the second `@@`, or `null`), `lines`: each raw line with its marker (` `, `-`, `+`, `\` for ``) |
-| `findings[]` | the Findings (as above, without `line`) of the reviews attached, each with its `review` (`kind` `primary` `shadow` `final`, `execution`, `attempt`, `spec`), `pin` and `off_diff` |
+| `findings[]` | the Findings (as above, without `line`) of the reviews attached, each with its `id` (see RunFindings), its `review` (`kind` `primary` `shadow` `final`, `execution`, `attempt`, `spec`), `pin` and `off_diff` |
 | `pin` | `file` (index in `files`), `path`, `line`, `side` (`new`; `old` for a deleted file or a renamed file's old path), `hunk` and `index` (into that hunk's `lines`), or `null` |
 | `off_diff` | `null` when pinned to a line, else `no location`, `file not in this diff`, `ambiguous path` or `line outside the changed hunks` (then `pin` has `file`, `line`, `side` and `hunk`/`index` `null`) |
 
@@ -628,6 +651,77 @@ Reads stay inside the run dir after symlinks are resolved, open regular files on
 never opened) and read at most 8 MiB; parses are kept by `(dev, inode, size, mtime_ns)` as
 other parses are.
 
+## RunFindings
+
+Every review's Findings in one read, for the stage's marks: what a TaskDetail or DiffDetail
+lists, for all tasks and final reviews at once, without `text` or `line`.
+
+```json
+{"run": "3f9a0c1d2e4b", "available": true,
+ "tasks": [{"id": "reader", "reviews": [{"kind": "primary", "execution": "qa-…", "attempt": 1, "spec": "opus",
+            "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",
+                    "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
+`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.
+
+## ExecutionTranscript (`forge_ui/transcripts.py`)
+
+What the agent of one `dwarf` or `qa` execution said and did, read from its `<role>.log`: the
+copy in its execution dir once it has finished, the owner dir's log while it runs (up to its
+last whole line, so the page can poll it). The format is told from the log itself:
+
+| Log | Written by | Read as |
+|---|---|---|
+| one JSON event per line: `thread.started`, `item.*`, `turn.*` | codex `--json` | `format` `codex` |
+| one message per line in Claude's shape: `system`, `assistant`, `user`, `result` | grok `--output-format streaming-messages-json`; claude and openclaude `--output-format stream-json` | `claude` |
+| one event per line: `text`, `reasoning`, `tool_use`, `step_finish`, `error` | opencode `--format json` | `opencode` |
+| one `result` object with a `session_id` | claude `--output-format json` | the session file, see below |
+| other JSON lines | e.g. agy `--output-format stream-json` (its `{"event": "result"}` is read as the result) | `json`: each line shown as it is |
+| anything else | antigravity's printed output; openclaude and opencode runs from before forge streamed them | `text`: one event |
+
+A claude log that holds only its result names the session the conversation is in. That one
+file is read, `<config dir>/projects/<one dir>/<session id>.jsonl`, the config dir being
+`$CLAUDE_CONFIG_DIR` then `~/.claude`, and only when the id is a UUID; it is the one file
+outside the run dir forge-ui reads. Its subagent (`isSidechain`) and meta lines are left out.
+Without it, the result alone is shown with a warning.
+
+```json
+{"run": "3f9a0c1d2e4b", "execution": "dwarf-…", "role": "dwarf", "state": "done", "attempt": 1, "spec": "luna",
+ "harness": "codex", "repo": "/work/worktrees/reader", "owner": {"kind": "task", "id": "reader"},
+ "format": "codex", "source": "log", "session": "0199…", "model": null, "cost": null,
+ "tokens": {"input": 12000, "cached": 9000, "output": 800},
+ "events": [{"kind": "reasoning", "text": "…"},
+            {"kind": "command", "command": "rg -n status ui/reader.py", "output": "…", "exit": 0},
+            {"kind": "edit", "files": ["/repo/ui/reader.py"], "patch": "-old\n+new"},
+            {"kind": "message", "text": "…"}],
+ "truncated": false, "warnings": []}
+```
+
+`attempt`, `spec` and `owner` are the Execution's; `harness` and `repo` (the worktree the agent ran
+in, so the page can make its absolute paths relative) come from `<role>.resolved`. `source` is
+`log`, `session` (claude's session file) or `none` (no log). An event has `kind`
+and the keys that kind uses: `prompt` (`text`: the task as a session file holds it), `message`,
+`reasoning`, `command` (`command`, `output`, `exit`), `edit` (`files`, `patch`: `-`/`+` lines,
+or `input` when there are none), `tool` (`tool`, `input`, `output`), `result` (`text`, left out
+with `same: true` when the last message said it; `tokens`), `error` (`text`), `text` (`text`,
+`stream: "stderr"` for lines between JSON events) and `gap` (`count` events left out). Any event
+may have `t` (epoch seconds), `id` (the harness's call id), `error` (`true` for a failed call or a
+non-zero exit, `false` for a call answered without one) and `running: true` (a call not finished yet). `tokens` are the run's totals
+(`input` counts cached input too). A message, a reasoning or a result keeps 20,000 characters, a
+command, an input or an output its first two thirds and last third of 8,000 around `… n
+characters …` (`<key>_cut` holds n). A log over 32 MB is read from its end; past 5,000 events or
+4,000,000 characters the middle is left out (a `gap` event, `truncated: true`). Parses are kept by
+the log's `(path, size, mtime_ns)` and the session file's.
+
 ## Files
 
 `GET /api/runs/<key>/files`: who planned, changed, drifted into or conflicted on each file.
@@ -785,21 +879,23 @@ difficulty paths deps model` each), `decomposition_history` (its newest 20, each
 `GET /api/runs/<key>/export` answers one self-contained HTML file named
 `forge-run-<run_id>.html` (the run id with anything but `[A-Za-z0-9._-]` made `-`).
 
-- It holds `style.css` and the classic scripts the run view uses (`runmodel.js cloudmodel.js
-  graph.js gantt.js panel.js diffview.js files.js map3d.js search.js app.js`), inline; the import
-  map; a `<script type="application/json" id="forge-snapshot">` with `{meta, api}`; and a
-  `<script type="text/plain" id="forge-stage">` holding `iso.js`, `cloud3d.js` and `scene3d.js`
-  bundled into one module (each module in its own scope, relative imports bound to the earlier
-  ones' exports, `createStage` exported), which `map3d.js` imports from a `blob:` URL.
+- It holds `style.css` (with the labels' face, `D-DINCondensed-Bold.woff2`, inlined as a `data:`
+  URL) and the classic scripts the run view uses (`theme.js icons.js datatable.js shell.js
+  runmodel.js cloudmodel.js graph.js gantt.js panel.js diffview.js convo.js files.js map3d.js search.js
+  app.js`), inline; the import map; a `<script type="application/json" id="forge-snapshot">` with
+  `{meta, api}`; and a `<script type="text/plain" id="forge-stage">` holding `iso.js`,
+  `cloud3d.js`, `findings3d.js`, `stagectl.js` and `scene3d.js` bundled into one module (each
+  module in its own scope, relative imports bound to the earlier ones' exports, `createStage`
+  exported), which `map3d.js` imports from a `blob:` URL.
 - `api` maps each path the page requests to that endpoint's response as the server would answer
   it (server.api_get): `/api/runs` (this run only), the RunDetail, every TaskDetail, every
-  ExecutionDetail the RunDetail names, every FinalReviewDetail, Files, and the Fractal trees and
-  nodes. With `texts=1` also every diff the page can open (each task's diff and its `sources`,
-  each final review's, each Fractal node's).
+  ExecutionDetail the RunDetail names, every FinalReviewDetail, Files, RunFindings, and the
+  Fractal trees and nodes. With `texts=1` also every diff the page can open (each task's diff and its `sources`,
+  each final review's, each Fractal node's) and every `dwarf` and `qa` ExecutionTranscript (at most 2 MB each).
 - `texts=0` (the default) nulls these keys wherever they hold a string, list or object: `prompt
   last request log_tail dwarf_tail qa_tail qa_last qa_input tasks_summary known_issues texts text
-  planning_last approach retry_findings dwarf_input error`, and stores no diff. A finding keeps its
-  `summary`.
+  planning_last approach retry_findings dwarf_input error`, and stores no diff and no transcript. A
+  finding keeps its `summary`.
 - `paths=0` (the default) makes every string that is a whole absolute path (but `/api/…` and
   `url`s) its last component, and replaces the run dir, the repo and the home dir inside other
   strings with their last component (`~` for home).
@@ -808,13 +904,176 @@ difficulty paths deps model` each), `decomposition_history` (its newest 20, each
   `generated`, `texts`, `paths`, `omitted`.
 - The page's `<meta http-equiv="Content-Security-Policy">`: `default-src 'none'; script-src
   <sha256 of the import map and each inline script> blob: https://cdn.jsdelivr.net/npm/three@0.160.0/;
-  style-src <sha256 of the style>; img-src data: blob:; connect-src 'none'; base-uri 'none';
+  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/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
@@ -860,6 +1119,7 @@ Plain scripts unless noted; each defines one global and none parses API text as
 | `gantt.js` | `ForgeGantt` | `render(container, run, {now, onSelect, sel, replay, critical, ghosts})`: attempts on wall-clock time in lanes; `strip(container, run, {now, replay})`: busy attempts and model calls against `max_parallel` |
 | `panel.js` | `ForgePanel` | `render(host, ctx)`: the inspector for a run, task, execution, final review, verification, integration or Fractal node; fetches the lazy endpoints once per node; `ctx.diffHash(spec)` links into the diff viewer, `ctx.onFractal(task, TaskFractal)` hands a task's tree to the stage |
 | `diffview.js` | `ForgeDiff` | `render(host, {run, spec, fetchJSON, rerender, href, closeHref})`: a DiffDetail with its findings under their lines; `spec` is `{kind: task, task, source, file}`, `{kind: final, name, file}` or `{kind: fractal, task, node, file}` |
+| `convo.js` | `ForgeConvo` | `render(host, {run, spec: {task, exec}, brief, live, fetchJSON, rerender, diffHash, closeHref})`: an ExecutionTranscript as a timeline, with search, the errors and, while the execution runs, a read of its log every 2.5 s |
 | `files.js` | `ForgeFiles` | `matrix(data, run, opts)` (pure: Files as rows of dirs and files against task columns by wave) and `render(host, data, {run, sel, onSelectTask, diffHref, prefs, savePrefs})`: the run's Files mode. Also a CommonJS module |
 | `cloudmodel.js` | `ForgeCloudModel` | pure: projects, per-run facts, the cloud's filters, its five layouts (anchors from every run, dragged runs kept), label picking, layout files. Also a CommonJS module |
 | `cloudui.js` | `ForgeCloudUI` | `create(root, ctx)`: the cloud's filter panel, layout and shape switches, position tools, legend and run card; a list of the same runs without 3D |

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)