@giamme/forge 0.9.0 → 0.10.0

package/scripts/forge_registry.py

@@ -5,6 +5,17 @@ run-dir path per line, with a ``#`` header on a new file. ``forge jev``, ``forge
 dataset import --registry`` and the forge-ui launcher all use it, so it does not
 live inside the Jev package.
 
+Two writers change those files: ``register_run_dir`` (every runner, on every start) and
+``unregister_run_dir`` (``forge runs rm``). Both take an flock on ``<registry dir>/.lock``,
+a stable sibling file that is never replaced. Register never blocks: it waits at most
+``REGISTER_LOCK_WAIT_S`` for the lock and then appends anyway, because a rare duplicate
+line is harmless and a lost run is not. An unlocked append can then land in the file an
+unregister has read and is about to replace, so the two meet halfway: unregister, once it
+has replaced a file, copies onto the new one whatever was appended to the old one after
+its read, and register, once it has appended, checks that the file it wrote is still the
+registry and appends again to the new one if it is not. Either the append reached the old
+file before unregister looked at it again, or register sees the replacement.
+
 Run as a script, ``forge_registry.py register <run-dir>`` records a run dir from the
 shell runners (forge-ui-options.sh ``forge_ui_register``): every plan, run and solo run
 is registered, not only the ones opened with ``--ui``, because forge-ui's map of a
@@ -12,12 +23,27 @@ repo's runs reads this registry. ``FORGE_RUN_REGISTRY=off`` turns that off.
 """
 from __future__ import annotations
 
+import contextlib
+import errno
+import fcntl
 import hashlib
 import os
 import stat
 import sys
+import tempfile
+import time
 from pathlib import Path
 
+# register_run_dir runs before forge ui open's own timeouts: it waits this long for the lock,
+# then appends without it. unregister_run_dir is only ever called by `forge runs rm`, which
+# can afford to wait for a busy lock, but not for ever.
+REGISTER_LOCK_WAIT_S = 0.5
+UNREGISTER_LOCK_WAIT_S = 10.0
+# How many times an unlocked register appends again after an unregister replaced the file
+# under it. One is enough unless unregisters keep finishing back to back.
+REGISTER_TRIES = 5
+LOCK_NAME = '.lock'
+
 
 def registry_dir() -> Path:
     """The ``runs`` directory under forge's config home.
@@ -51,11 +77,45 @@ def runs_registry(repo) -> Path:
     return registry_dir() / (repo_key(repo) + '.txt')
 
 
+@contextlib.contextmanager
+def _registry_lock(wait_s: float):
+    """Hold an exclusive flock on ``<registry dir>/.lock`` for the ``with`` body.
+
+    The lock is on a file of its own and never on a registry file, because unregister
+    replaces those: a lock on a file that is renamed over locks nothing. Polls without
+    blocking for up to ``wait_s`` seconds, then raises BlockingIOError; raises OSError if
+    the lock file cannot be opened or is not a regular file (a FIFO would block a reader).
+    A filesystem that cannot flock at all (ENOLCK, EOPNOTSUPP) gets no locking, as it
+    would anywhere else in forge, rather than a registry nobody can change.
+    """
+    fd = os.open(registry_dir() / LOCK_NAME, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise OSError(errno.EINVAL, 'the registry lock is not a regular file', LOCK_NAME)
+        deadline = time.monotonic() + wait_s
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except OSError as error:
+                if error.errno not in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                    break
+                if time.monotonic() >= deadline:
+                    raise BlockingIOError(errno.EWOULDBLOCK, 'the run registry is locked', LOCK_NAME) from error
+                time.sleep(0.01)
+        yield
+    finally:
+        os.close(fd)
+
+
 def register_run_dir(repo: Path, run_dir: Path) -> None:
     """Record an absolute run-dir path for this repo, deduplicated.
 
     Never raises and never blocks: failing to note where a run lives must not fail the run,
-    and ``forge ui open`` calls this before any of its own timeouts.
+    and ``forge ui open`` calls this before any of its own timeouts. The registry lock is
+    tried for at most ``REGISTER_LOCK_WAIT_S``; if it stays busy the line is appended without
+    it (see the module docstring), and appended again if an unregister replaced the file
+    it went to.
     """
     try:
         # A relative XDG_CONFIG_HOME resolves below the current directory -- for a runner or
@@ -65,26 +125,118 @@ def register_run_dir(repo: Path, run_dir: Path) -> None:
         registry = runs_registry(repo)
         registry.parent.mkdir(parents=True, exist_ok=True)
         line = str(Path(run_dir).resolve())
-        existing = []
-        if registry.is_file():
-            existing = [x.strip() for x in registry.read_text(errors='replace').splitlines()]
-        if line in existing:
-            return
-        header = [] if existing else ['# forge run dirs for ' + str(Path(repo).resolve())]
-        # O_NONBLOCK: a FIFO with no reader fails at once (ENXIO) instead of blocking the
-        # open, and anything that is not a regular file is left alone.
-        fd = os.open(registry, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NONBLOCK, 0o644)
-        with os.fdopen(fd, 'a') as handle:
-            if not stat.S_ISREG(os.fstat(fd).st_mode):
-                return
-            for entry in header:
-                handle.write(entry + '\n')
-            handle.write(line + '\n')
+        with contextlib.ExitStack() as held:
+            try:
+                held.enter_context(_registry_lock(REGISTER_LOCK_WAIT_S))
+            except OSError:
+                pass   # busy past the wait, or no lock file to be had: append unlocked
+            for _ in range(REGISTER_TRIES):
+                existing = []
+                if registry.is_file():
+                    existing = [x.strip() for x in registry.read_text(errors='replace').splitlines()]
+                if line in existing:
+                    return
+                header = [] if existing else ['# forge run dirs for ' + str(Path(repo).resolve())]
+                # O_NONBLOCK: a FIFO with no reader fails at once (ENXIO) instead of blocking the
+                # open, and anything that is not a regular file is left alone.
+                fd = os.open(registry, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NONBLOCK, 0o644)
+                with os.fdopen(fd, 'a') as handle:
+                    written = os.fstat(fd)
+                    if not stat.S_ISREG(written.st_mode):
+                        return
+                    handle.write(''.join(entry + '\n' for entry in header + [line]))
+                    handle.flush()
+                # Still the registry: the line is in it, or in the old file an unregister copies
+                # from once it has replaced it. Replaced already: the line may be in neither.
+                try:
+                    current = os.lstat(registry)
+                except FileNotFoundError:
+                    continue
+                if (current.st_dev, current.st_ino) == (written.st_dev, written.st_ino):
+                    return
     except (OSError, ValueError, RuntimeError):
         # ValueError: a NUL byte in a path; RuntimeError: a symlink loop (pathlib before 3.13)
         pass
 
 
+def _rewrite_without(path: Path, wanted: set) -> bool:
+    """Atomically drop the lines of one registry file that name a path in ``wanted``.
+
+    Every other byte is kept as it was. Returns whether the file changed. A registry file
+    that is not a regular file is skipped, and read without blocking.
+
+    The caller holds the registry lock, but a register that gave up waiting for it appends
+    anyway, possibly to this file after it was read. So the old file stays open across the
+    replace, and whatever it gained since the read is appended to the new one.
+    """
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW)
+    except OSError as error:
+        if error.errno in (errno.ENOENT, errno.ELOOP):
+            return False
+        raise
+    with os.fdopen(fd, 'rb') as old:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            return False
+        data = old.read()
+        lines = data.splitlines(keepends=True)
+        kept = [line for line in lines if os.fsdecode(line).strip() not in wanted]
+        if len(kept) == len(lines):
+            return False
+        content = b''.join(kept)
+        temporary = None
+        try:
+            out, temporary = tempfile.mkstemp(dir=str(path.parent), prefix='.' + path.name + '.', suffix='.tmp')
+            with os.fdopen(out, 'wb') as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.chmod(temporary, stat.S_IMODE(info.st_mode))
+            os.replace(temporary, path)
+            temporary = None
+        finally:
+            if temporary is not None:
+                try:
+                    os.unlink(temporary)
+                except OSError:
+                    pass
+        # An append that comes later still is register's to notice: the path no longer
+        # names the file it wrote.
+        late = old.read()
+    if late:
+        extra = [line for line in late.splitlines(keepends=True) if os.fsdecode(line).strip() not in wanted]
+        if extra:
+            if content and not content.endswith(b'\n'):
+                extra.insert(0, b'\n')
+            out = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_NOFOLLOW | os.O_NONBLOCK)
+            with os.fdopen(out, 'ab') as handle:
+                handle.write(b''.join(extra))
+    return True
+
+
+def unregister_run_dir(run_dir) -> list:
+    """Remove a run dir from every registry file that lists it; return the files rewritten.
+
+    The reverse of ``register_run_dir``, for ``forge runs rm``, so unlike it this reports
+    failure: it raises OSError (BlockingIOError when the registry lock stays busy) and the
+    caller says the registry needs repair. Each file is rewritten atomically under the
+    registry lock, so a concurrent register loses nothing. ``run_dir`` need not exist any
+    more: entries were written resolved, so the path is resolved the same way, and the
+    path as given is matched too.
+    """
+    directory = registry_dir()
+    if not directory.is_absolute() or not directory.is_dir():
+        return []
+    wanted = {os.path.realpath(run_dir), os.path.abspath(run_dir)}
+    changed = []
+    with _registry_lock(UNREGISTER_LOCK_WAIT_S):
+        for path in sorted(directory.glob('*.txt')):
+            if _rewrite_without(path, wanted):
+                changed.append(path)
+    return changed
+
+
 # A path, not a file's worth of data: the first line of <run-dir>/repo is all that is read.
 _REPO_LINE_MAX = 64 * 1024
 

package/ui/README.md

@@ -1,6 +1,7 @@
 # forge-ui
 
-forge-ui is a small, read-only local web UI for forge runs. It draws them the way
+forge-ui is a small local web UI for forge runs. It reads everything, and changes things only by
+calling forge's own commands (see [Controls](#controls)). It draws them the way
 [archivision](https://github.com/Giamme/archivision) draws a codebase: a 3D isometric map of
 blocks on a plate, with cables between them and lamps that light up as things happen.
 
@@ -223,7 +224,7 @@ keep one meaning everywhere (amber running, green merged or passed, red failed,
   carries the same tree floating above it. A node (`…/tasks/<id>/fractal/<node>`) shows its goal,
   paths, timings, cost and tokens, its decomposition and the children it admitted, its last
   messages, and its candidate diff. Fractal's state is read under `$XDG_STATE_HOME/forge/fractal`
-  (default `~/.local/state`), read-only, without following symlinks.
+  (default `~/.local/state`), only read, without following symlinks.
 - **Export:** *Export…* in a run's header downloads the run as one HTML file that opens in any
   browser without forge-ui, offline included (in 2D; in 3D when cdn.jsdelivr.net is reachable).
   It asks each time: by default prompts, reviewer reports, logs, finding details and diffs are
@@ -252,6 +253,37 @@ machine while this server is running and discovering that run dir. *Live refresh
 polling; a hidden tab polls only the run list, every 30 seconds, and only with browser
 notifications on. Failed requests keep the last good data and show a banner.
 
+## Controls
+
+The page can change a run, and every change is one call of a forge CLI; the server writes
+nothing itself, so a change is validated, locked and logged exactly as if typed in a terminal
+(`control.log` records `ui` as the actor). Each change is confirmed first and says when it
+takes effect. The routes are in [docs/api.md](docs/api.md).
+
+- **Run and task controls (`forge control`):** in a plan's inspector, the QA threshold,
+  timeout, escalate-after and verify retries, and while a scheduler is live the retry and
+  infra-retry budgets. A task has a threshold override (`Inherit`, P0–P3 or `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. A control that cannot apply (no live scheduler, a merged
+  task, a Fractal plan's pin) is disabled and says why.
+- **Open findings (`forge issues`):** the findings a run, or every run of its repository,
+  left open. The list opens from a quick offline listing and then fills in what is already
+  filed; select findings to file as GitHub issues, or dismiss them (and undo that).
+- **Delete a run (`forge runs rm`):** a dry run first, then the deletion. Its traces stay in
+  the dataset; an archive is written unless you decline it; `worktrees` and `branches` remove
+  the run's clean worktrees and its branches that nothing has checked out. Foreign or dirty
+  worktrees are listed and left.
+- **Settings (`forge config`):** the registry, Jev, the repository's `.forge` files, the
+  dataset and `FORGE_*` variables (secrets shown as `<set>`), with edits for `repo.verify`,
+  `repo.setup`, `repo.verify-subset` and `jev.enabled`.
+
+**Protection.** Each server start makes a random token and serves it in the page; every change
+must send it, from a `Host` of `127.0.0.1` or `localhost`, with an `Origin` equal to the host
+when one is sent, as JSON of at most 64 KiB, or it is refused before any CLI runs. There are no
+CORS headers. One write per run at a time (`409 busy`). `--read-only` or `FORGE_UI_READONLY=1`
+turns all of it off: no token is issued, every change is a 405, and the controls say the page cannot change the run.
+`forge ui open` never reuses a server running in the other mode.
+
 ## Layout of the code
 
 - `forge_ui/reader.py`: discover runs, parse their files and produce summaries and details.
@@ -335,8 +367,9 @@ python3 tools/readme_media.py                  # writes docs/media/
 ## Privacy
 
 Run dirs can contain prompts, diffs and review text from private repos. The server binds
-only `127.0.0.1`, makes no network requests, and writes nothing to run dirs, repositories or
-forge's config. Outside the runs it reads one kind of file: for a claude execution whose log
+only `127.0.0.1` and makes no network requests. It writes nothing itself; a change you
+confirmed in the page is a call of forge's own CLI, protected by a per-launch token
+(`--read-only` turns that off). Outside the runs it reads one kind of file: for a claude execution whose log
 holds only its final answer, that run's session file, `<session id>.jsonl` under
 `~/.claude/projects/` (or `$CLAUDE_CONFIG_DIR/projects/`). Anyone with access to the local server can read the runs it discovers, and
 forge now registers every run, so that is every run on the machine.

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
 
@@ -55,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) |
@@ -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,21 @@ 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/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`
@@ -386,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,
@@ -421,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.
@@ -892,10 +907,173 @@ 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/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)