@giamme/forge 0.9.0 → 0.11.0

package/scripts/forge_dataset/reviewers.py

@@ -0,0 +1,145 @@
+"""`forge dataset reviewers`: how the work each reviewer passed held up afterwards.
+
+A report card per reviewer (qa) model. For every attempt a primary reviewer PASSed whose
+reviewed commit was integrated and then followed by `forge dataset outcomes`, the outcome
+at one horizon (default 14 days) says whether the work held: it did not if a later commit
+reverted it, or if fewer than 80% of the lines it added were still there (rewritten; the
+same rule as the export's `survives` label). The rate of work that did not hold has a
+95% Wilson interval, and is only given from MIN_LANDED outcomes on: below that the row
+says "not enough data" rather than a rate a handful of tasks would make up.
+
+Advisory only. Nothing that builds a prompt or routes a task reads this report, and it
+counts only what forge saw: survival is followed for parallel integrations
+(`integrate_advanced`), so solo runs and work merged by hand are not here. A row is keyed by
+the reviewer's alias, as the forge-ui Models view is, or by its model when no alias was recorded.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import defaultdict
+
+from . import connect, dataset_dir
+from .export import SURVIVES_AT, Runs, Store
+from .routing import wilson
+
+MIN_LANDED = 10
+HORIZON_DAYS = 14
+
+
+def _empty(horizon_days):
+    return dict(horizon_days=horizon_days, min_landed=MIN_LANDED, survives_at=SURVIVES_AT, reviewers=[],
+                unattributed=dict(not_passed=0, no_review=0), skipped=dict(lost=0, no_additions=0),
+                other_horizons=[])
+
+
+def report(runs: Runs, *, horizon_days: int = HORIZON_DAYS, repo: str = None) -> dict:
+    out = _empty(horizon_days)
+    paths = runs.store.repo_paths
+    # Which attempts reviewed each commit: a QA-only resume or a combined task can share one.
+    attempts_of = defaultdict(list)
+    for key, commit in runs.reviewed.items():
+        attempts_of[commit].append(key)
+    outcomes, horizons = {}, set()
+    for e in runs.store.of('outcome'):
+        d = e['d']
+        if d.get('name') != 'survival' or not d.get('reviewed'):
+            continue
+        if repo and paths.get(e['repo']) != repo:
+            continue
+        if d.get('horizon_days') != horizon_days:
+            horizons.add(d.get('horizon_days'))
+            continue
+        outcomes.setdefault(d['reviewed'], d)     # one outcome per commit and horizon
+    out['other_horizons'] = sorted(h for h in horizons if isinstance(h, int))
+    rows = {}
+    for commit, d in sorted(outcomes.items()):
+        if d.get('status') == 'lost':
+            out['skipped']['lost'] += 1
+            continue
+        if d.get('status') != 'ok' or not d.get('added'):
+            out['skipped']['no_additions'] += 1
+            continue
+        reviews = []
+        for run, task, attempt in attempts_of.get(commit, ()):
+            reviews += [r for r in runs.dispatches.get((run, task, 'qa'), ()) if r['attempt'] == attempt]
+        passed = {}
+        for r in sorted(reviews, key=lambda r: r['ts']):
+            name = r['d'].get('alias') or r['d'].get('model')
+            if r['d'].get('verdict') == 'PASS' and name:
+                passed[name] = r['d']
+        if not passed:
+            # Reviewed and FAILed, then accepted by the severity gate or a human; or no review recorded.
+            out['unattributed']['not_passed' if reviews else 'no_review'] += 1
+            continue
+        reverted = bool(d.get('reverted_by'))
+        rewritten = not reverted and d['surviving'] / d['added'] < SURVIVES_AT
+        for name, r in passed.items():
+            row = rows.setdefault(name, dict(reviewer=name, specs=set(), landed=0, reverted=0, rewritten=0))
+            spec = ':'.join(x for x in (r.get('model'), r.get('effort')) if x)
+            if spec:
+                row['specs'].add(spec)
+            row['landed'] += 1
+            row['reverted'] += reverted
+            row['rewritten'] += rewritten
+    for row in rows.values():
+        row['specs'] = sorted(row['specs'])
+        row['did_not_hold'] = row['reverted'] + row['rewritten']
+        row['enough'] = row['landed'] >= MIN_LANDED
+        if row['enough']:
+            row['rate'] = row['did_not_hold'] / row['landed']
+            row['ci'] = list(wilson(row['did_not_hold'], row['landed']))
+        else:
+            row['rate'], row['ci'] = None, None
+            row['note'] = 'not enough data (%d/%d)' % (row['landed'], MIN_LANDED)
+    out['reviewers'] = sorted(rows.values(), key=lambda r: (not r['enough'], -r['landed'], r['reviewer']))
+    return out
+
+
+def load(horizon_days: int = HORIZON_DAYS, repo: str = None) -> dict:
+    # Reading must not create a store: a fresh machine (or forge-ui asking) gets an empty report.
+    if not (dataset_dir() / 'dataset.sqlite').exists():
+        return _empty(horizon_days)
+    db = connect()
+    try:
+        runs = Runs(Store(db))
+    finally:
+        db.close()
+    return report(runs, horizon_days=horizon_days, repo=repo)
+
+
+def _pct(v):
+    return '%.0f%%' % (v * 100)
+
+
+def main(args) -> int:
+    if args.horizon_days < 1:
+        print('forge dataset reviewers: --horizon-days must be at least 1', file=sys.stderr)
+        return 2
+    rep = load(args.horizon_days, os.path.realpath(args.repo) if args.repo else None)
+    if args.json:
+        print(json.dumps(rep, indent=2, sort_keys=True))
+        return 0
+    print('reviewers: PASSed work that did not hold up %d days after integrate' % rep['horizon_days'])
+    print('  (reverted, or under %d%% of its added lines kept; advisory only, routing never reads it)'
+          % (SURVIVES_AT * 100))
+    if not rep['reviewers']:
+        print('  no PASSed work with a %d-day outcome yet; `forge dataset outcomes --horizon-days %d` records them'
+              % (rep['horizon_days'], rep['horizon_days']))
+    else:
+        print('  %-24s %6s %8s %9s  %s' % ('reviewer', 'landed', 'reverted', 'rewritten', 'did not hold'))
+    for r in rep['reviewers']:
+        held = r['note'] if not r['enough'] else '%s [%s-%s] (%d/%d)' % (
+            _pct(r['rate']), _pct(r['ci'][0]), _pct(r['ci'][1]), r['did_not_hold'], r['landed'])
+        print('  %-24s %6d %8d %9d  %s' % (r['reviewer'], r['landed'], r['reverted'], r['rewritten'], held))
+    u, s = rep['unattributed'], rep['skipped']
+    if u['not_passed'] or u['no_review']:
+        print('  not counted for any reviewer: %d landed after a FAIL (accepted by the gate or by hand), %d with no review'
+              % (u['not_passed'], u['no_review']))
+    if s['lost'] or s['no_additions']:
+        print('  skipped: %d lost (history rewritten past the integration), %d added no lines' % (s['lost'], s['no_additions']))
+    if rep['other_horizons']:
+        print('  outcomes also recorded at %s days: pass --horizon-days to see them'
+              % ', '.join(str(h) for h in rep['other_horizons']))
+    return 0

package/scripts/forge_dataset/routing.py

@@ -107,6 +107,7 @@ def tasks(runs: Runs, *, repo=None, since=None) -> list:
             out.append(dict(
                 run=run, task=tid, tier=row.get('declared_difficulty') or row.get('difficulty'),
                 ran=first['events'][0]['d'].get('dwarf') if first else None, model=model,
+                model_id=resolved.get('model'), effort=resolved.get('effort'),
                 first_pass=first['outcome'] if first else None,
                 censored=(first['reason'] if first and first['outcome'] is None else (None if first else 'not_run')),
                 passed=any(a['outcome'] for a in attempts) or (run, tid) in runs.accepted,

package/scripts/forge_jev/__init__.py

@@ -149,9 +149,13 @@ _runtime_spec.loader.exec_module(_runtime)
 
 
 def config_path() -> Path:
-    # An empty XDG_CONFIG_HOME counts as unset (XDG spec): taken literally it put jev.json
-    # below the current directory.
-    return Path(os.environ.get('XDG_CONFIG_HOME') or str(Path.home() / '.config')).expanduser() / 'forge/jev.json'
+    # An empty or relative XDG_CONFIG_HOME counts as unset (XDG spec): taken literally it put
+    # jev.json below the current directory. Same rule as forge_registry.registry_dir().
+    value = os.environ.get('XDG_CONFIG_HOME') or ''
+    base = Path(value).expanduser() if value else None
+    if base is None or not base.is_absolute():
+        base = Path.home() / '.config'
+    return base / 'forge/jev.json'
 
 
 def load_config() -> dict:

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,26 +23,45 @@ 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.
 
     Resolved the same way ``forge_jev.config_path()`` resolves ``jev.json``:
-    ``XDG_CONFIG_HOME`` when set and not empty, otherwise ``~/.config``, then
-    ``expanduser()``. An empty value counts as unset, as the XDG spec says and as
-    forge-ui's run list reads it; taken literally it named a directory below the
-    current one, usually the user's repo. ``config_path()`` is
-    ``<that>/forge/jev.json``; the registry is the sibling ``runs`` directory.
+    ``XDG_CONFIG_HOME`` (``~`` expanded) when it is an absolute path, otherwise
+    ``~/.config``. An empty or relative value counts as unset, as the XDG spec says
+    ("If an implementation encounters a relative path in any of these variables it
+    should consider the path invalid and ignore it") and as forge-ui's run list reads
+    it; taken literally it named a directory below the current one, usually the
+    user's repo. ``config_path()`` is ``<that>/forge/jev.json``; the registry is the
+    sibling ``runs`` directory.
     """
-    config = (Path(os.environ.get('XDG_CONFIG_HOME') or str(Path.home() / '.config')).expanduser()
-              / 'forge/jev.json')
-    return config.parent / 'runs'
+    value = os.environ.get('XDG_CONFIG_HOME') or ''
+    base = Path(value).expanduser() if value else None
+    if base is None or not base.is_absolute():
+        base = Path.home() / '.config'
+    return base / 'forge' / 'runs'
 
 
 def repo_key(repo) -> str:
@@ -51,40 +81,167 @@ 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
-        # `forge ui open`, usually the user's repo. Forge does not write into the user's tree.
+        # A relative HOME (registry_dir already ignores a relative XDG_CONFIG_HOME) would resolve
+        # below the current directory -- for a runner, usually the user's repo. Forge does not
+        # write into the user's tree.
         if not registry_dir().is_absolute():
             return
         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.
 
@@ -95,7 +96,7 @@ Sources are checked in this order:
 2. `--root DIR` itself, its children and grandchildren. Scanning stops when a plan
    directory is found; hidden children and symlinked child directories are skipped.
 3. Forge's registry: `*.txt` files in `$XDG_CONFIG_HOME/forge/runs/`, defaulting
-   to `~/.config/forge/runs/` when XDG_CONFIG_HOME is unset or empty. Each file
+   to `~/.config/forge/runs/` when XDG_CONFIG_HOME is unset, empty or relative. Each file
    supplies absolute paths, one per line; blank lines and `#` comments are ignored.
    `--registry-dir` replaces this location; `--no-registry` disables it.
 
@@ -188,8 +189,9 @@ keep one meaning everywhere (amber running, green merged or passed, red failed,
 - **Models (`#/models`):** a leaderboard of the models forge used. Implementers: tasks, first-attempt
   pass rate with its 95% Wilson interval, censored attempts, retries, escalations away from the
   model, timeouts, gate and human accepts, median model time and tokens. Reviewers: primary,
-  shadow and final reviews, the PASS/FAIL split, findings per review by severity, and how often a
-  shadow review agreed with the primary. Filter by project, difficulty, kind and period, or keep
+  shadow and final reviews, the PASS/FAIL split, findings per review by severity, how often a
+  shadow review agreed with the primary, and how often work it PASSed did not hold (later
+  reverted or rewritten, from `forge dataset reviewers`; "not enough data" below 10 outcomes). Filter by project, difficulty, kind and period, or keep
   only exploratory picks; open a difficulty for its own table. Routing is not random, so the
   numbers compare what happened, not what would have: the page says so. A model's name opens the
   run cloud filtered to its runs.
@@ -223,7 +225,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 +254,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 +368,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.