@giamme/forge 0.8.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,13 +1,14 @@
 # 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.
 
 - **A map of every run**, one district per repo and one block per run, with a lamp per task.
   Filter it by state, repo, kind, model, age or review verdict; what does not match fades
   instead of disappearing.
-- **A run, as planned and as it ran.** *Planned waves* puts each task in its wave, with
+- **A run, as planned and as it ran.** *Plan* puts each task in its planned wave, with
   dependency cables, and ends in a *finish* line of three nodes: integration, verification
   and the whole-run **final review**. *Execution* lays the same work out on wall-clock time:
   one block per attempt, in the lane it really ran in, with its dwarf and review inside, the
@@ -26,12 +27,13 @@ blocks on a plate, with cables between them and lamps that light up as things ha
   with the primary and how sure Clef was that each task would pass.
 - **Beyond one run:** a full-screen **run cloud** of every run, grouped by project, in five
   layouts with filters and runs you can drag anywhere; **diffs** with each finding under the
-  line it names; a **model leaderboard**; a **files heatmap**; **Fractal** child-task trees;
+  line it names; each dwarf's and reviewer's **conversation**, read from its CLI's log; a
+  **model leaderboard**; a **files heatmap**; **Fractal** child-task trees;
   **quick jump** and **notifications**; and **export** of a run as one HTML file. See
   [What you see](#what-you-see).
 
 <p align="center">
-  <img src="docs/media/hero.webp" width="860" alt="A decomposed run on its 3D plate: eight tasks in their planned waves, then the same run on wall-clock time, where two first attempts that failed review show in red beside the retries that passed.">
+  <img src="docs/media/hero.webp" width="860" alt="A decomposed run on its 3D plate: eight tasks in their planned waves with a mark for each review finding, then the same run on wall-clock time, where two first attempts that failed review show in red beside the retries that passed.">
 </p>
 
 The 3D view loads three.js from a CDN the first time it is used (see [Privacy](#privacy)).
@@ -105,11 +107,21 @@ with the first source winning. Discovery and disk reads repeat on each API reque
 
 ## What you see
 
+forge-ui looks like a signal box's route-setting desk: the run is drawn on a panel, every heading
+is an engraved plate, every switch is a push button whose lamp lights when it is on, and lamps
+keep one meaning everywhere (amber running, green merged or passed, red failed, unlit pending).
+
+- **Layout:** the *Runs*, *Inspector* and *Tasks* modules sit around the stage. *Immersive* (the
+  default) floats them over a stage that fills the window; *Workbench* docks them beside it, and
+  the runs list folds to a rail of lamps. Switch with the two layout keys in the header; the
+  module keys beside them, or `1`, `2` and `3`, fold and open the runs, the inspector and the
+  tasks. On your first visit the inspector and the tasks start folded, so a run opens on its plate. Drag a module's inner edge, or focus it and use the arrow keys, to resize it. The header
+  also switches the theme (system, light or dark). All of this is remembered in this browser.
 - **Map (`#/`):** every discovered run, newest first, grouped by repo. By default the last
-  60 runs from the past 14 days; *older runs too* shows the rest. The sidebar list follows
-  the same filter.
+  60 runs from the past 14 days; *older runs too* shows the rest. The runs list follows the same
+  filter, and sorts by latest activity, state or repo.
 
-  <img src="docs/media/map.png" width="760" alt="The map: one block per run, in a district per repo, green when done, blue while running, red with failures.">
+  <img src="docs/media/map.png" width="760" alt="The map: one block per run, in a district per repo, green when done, amber while running, red with failures.">
 - **Run cloud (`#/cloud`):** every run at once, full screen, floating in 3D and grouped by project
   (repo). Pick a layout: *Helix* (one spiral per project, oldest at the bottom), *Sphere*,
   *Galaxy* (a disc per project, newest at the centre), *Timeline* (left to right by start time,
@@ -128,12 +140,38 @@ with the first source winning. Discovery and disk reads repeat on each API reque
   filtered runs and offers *Load 3D*.
 
   <img src="docs/media/cloud.webp" width="760" alt="The run cloud orbited, then laid out as galaxies and as a timeline with one lane per project.">
-- **Run (`#/runs/<key>`):** a header (goal, repo, counts, and *Run details*: settings, request,
-  waves, verification output), a toolbar (*Planned waves* / *Execution*, *3D* / *2D*, height
-  and colour overlays, *Critical path*, *Review marks*, *Projected*, *Replay*), the stage with
-  the inspector beside it, and the task table.
-
-  <img src="docs/media/run.png" width="49%" alt="Planned waves: a run's tasks on a 3D plate with dependency cables and the finish nodes, beside the run's inspector."> <img src="docs/media/execution.png" width="49%" alt="Execution: one block per attempt on wall-clock time, failed attempts in red, with the timeline and critical path in the inspector.">
+- **Run (`#/runs/<key>`):** a header with the goal, the repo, a describer (each state's count,
+  the wall time, how long since anything moved), a bank of push buttons (*Plan* /
+  *Execution* / *Files*, *3D* / *2D*, and *View*: height and colour overlays, the *Layers* that
+  switch each part of the 3D drawing on or off, and the *Marks*: *Critical path*, *Review marks*,
+  *Projected*) and the replay's time base; then the stage, the inspector and the
+  task table. The stage frames the run in the part of the window the modules leave free. The
+  inspector opens when you choose a task, an attempt or a finish node; with
+  nothing chosen it shows the run's timeline, finish and record (*Run details* in the header:
+  settings, request, waves, verification output).
+- **Stage (3D):** each review finding stands over its task's block as a mark shaped by its
+  severity (P0 spike, P1 diamond, P2 cone, P3 pin, a ring when it has none; a plausible one smaller
+  and paler); on an opened task it moves onto the review that raised it, and the final review's sit
+  on *Final review*. Hover one for its location and summary; click it to open the diff that
+  review read at that finding. Choosing a task keeps its route lit, what it waits on and what
+  waits on it (`I` switches this off). Hovering a task shows its card: status, attempts, busy
+  time, tokens, models, its worst finding and what waits on it. A block whose roof text is too
+  small to read gets its name on a tag that faces you. A merge sends a pulse to *Integration*, a
+  failed attempt a red ring across the plate, an escalation a hop with the two models, a final
+  review a ring in its verdict's colour, live and during a replay (with reduced motion the block
+  lights instead). The keys at the stage's edge fit what is shown (`F`), zoom (`+` `−`), change
+  the projection (`V`: perspective, true isometric, top-down), reset the view (`0`), open the
+  legend of what the stage draws now (`L`), go full screen, and list every key (`?`). The layers,
+  the projection and the route are remembered.
+- **Lamps:** green merged or passed, amber running, red failed, unlit pending. A hollow lamp is
+  that family's other case: passed or accepted without a merge (green), interrupted (amber), an
+  infrastructure failure, a timeout or blocked behind a failure (red). Review findings are never
+  a lamp: their severity is a shape (P0 spike, P1 diamond, P2 cone, P3 pin).
+- **Tables:** the task table and the leaderboard's tables sort by any column (click its header:
+  ascending, descending, off), reorder by dragging a header (or Alt+← → on it), and show or hide
+  columns from *Columns*, which also resets them. Each table remembers its columns.
+
+  <img src="docs/media/run.png" width="49%" alt="Planned waves: a run's tasks on a 3D plate with dependency cables, finding marks and the finish nodes, between the runs list and the run's inspector."> <img src="docs/media/execution.png" width="49%" alt="Execution: one block per attempt on wall-clock time, failed attempts in red, with the timeline and critical path in the inspector.">
 - **Inspector:** for the run, its timeline, critical path, peak concurrency and finish line;
   for a task, its models and routing, escalations, timings (busy, model time, overhead,
   queue wait after its dependencies merged), attempts and their executions, review findings
@@ -147,7 +185,7 @@ with the first source winning. Discovery and disk reads repeat on each API reque
   most tasks, and hide any kind of mark; a cell selects its task and offers that file's diff.
   Below: overlaps, drift, merge conflicts and deferrals as lists.
 
-  <img src="docs/media/files.png" width="560" alt="The files heatmap: files by directory against tasks by wave, with planned, touched, drift and same-wave overlap marks.">
+  <img src="docs/media/files.png" width="760" alt="The files heatmap: files by directory against tasks by wave, with planned, touched, drift and same-wave overlap marks.">
 - **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,
@@ -158,22 +196,35 @@ with the first source winning. Discovery and disk reads repeat on each API reque
   run cloud filtered to its runs.
 
   <img src="docs/media/models.png" width="760" alt="The implementers table: tasks, first-attempt pass rate with its 95% interval, retries, escalations, timeouts, accepts, median model time and tokens per model.">
-- **Diffs (`…/tasks/<id>/diff[/<source>][/file/<path>]`, `…/final-review/<name>/diff`):** a task's
+- **Diffs (`…/tasks/<id>/diff[/<source>][/file/<path> | /finding/<id>]`, `…/final-review/<name>/diff[/finding/<id>]`):** a task's
   `changes.diff`, its previous or committed diff, or exactly the diff one reviewer read (the last
   diff in that review's prompt), picked from a row of sources with each review's verdict; a final
   review's combined diff. Files are listed with their +/− counts and how many findings point
   into them; each finding is shown under the line it names, those on a line outside the changed
   hunks at the top of their file, and those whose file is not in the diff (or that name no
   location) in a section of their own. n and p move between findings, j and k between files.
-  Open it from a task, an attempt's review, an execution or the final review in the inspector.
+  Open it from a task, an attempt's review, an execution or the final review in the inspector, or
+  from a finding's mark on the stage (`/finding/<id>` scrolls to that finding and focuses it).
 
   <img src="docs/media/diff.png" width="760" alt="The diff a reviewer read, with a P1 finding under the line that compares token digests and a P2 finding under the revoke function.">
+- **Conversations (`…/tasks/<id>/executions/<dwarf-or-qa>/conversation`, `…/executions/<id>/conversation`):**
+  what one dwarf or reviewer said and did, read from its agent CLI's `<role>.log`, in the diff's
+  place: its messages, its thinking folded, each command with its exit and output, each edit with
+  its patch and a link to the file in the diff its review read, other tool calls, and the final
+  answer with the tokens and cost. Search it (`/`), keep only what it said, ran or changed, and
+  step through its errors (`E`). While the agent works the log is read again every few seconds and
+  *Follow* keeps the newest event in view. codex, grok, claude, openclaude and opencode logs are
+  read event by event; when a claude run logged only its final answer, the conversation comes from
+  Claude's own session file for that run, if it is still on this machine; any other log is shown
+  as it is. Open it from an attempt's dwarf or reviewer in the inspector.
+
+  <img src="docs/media/conversation.png" width="760" alt="A dwarf's conversation: its thinking, the files it wrote, a test run that failed with exit 1 and the run that passed after the fix.">
 - **Fractal child tasks:** when a run used Fractal, a task's inspector shows the tree it was split
   into (status, difficulty, model, phase, cost, the split decision), and the opened task in 3D
   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
@@ -192,14 +243,47 @@ with the first source winning. Discovery and disk reads repeat on each API reque
   while the tab is in the background, and a hidden tab checks the run list every 30 seconds
   (browsers may check less often after a while). Open tabs share one log and notify once. Runs
   that have not changed for two hours never notify.
-- **Keys on the stage:** ← → move between tasks, Esc closes, `e` switches plan and
-  execution. Drag to orbit, right-drag to pan, scroll to zoom once the stage is clicked.
+- **Keys on the stage:** with the stage focused, ← → move between tasks (on the map, between
+  runs; ↑ ↓ between repos, Enter opens the run), Esc closes, `e` switches plan and execution.
+  Anywhere on the page while the stage shows: `F`, `+` `−`, `V`, `0`, `L`, `I`, Shift+F (full
+  screen) and `?`. Drag to orbit, right-drag to pan, scroll to zoom once the stage is clicked.
 
 URLs such as `http://127.0.0.1:8765/#/runs/<key>/tasks/<id>` are shareable within the
 machine while this server is running and discovering that run dir. *Live refresh* pauses
 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.
@@ -210,12 +294,18 @@ notifications on. Failed requests keep the last good data and show a banner.
 - `forge_ui/__main__.py`: CLI options, local startup and optional browser opening.
 - `forge_ui/__init__.py`: package version and the build id `forge ui` compares to find a stale server.
 - `forge_ui/static/index.html`, `style.css`, `app.js`: the page shell, styles, routes, views and polling.
+- `forge_ui/static/theme.js`, `shell.js`, `icons.js`, `datatable.js`: the theme switch, the Immersive and
+  Workbench layouts with their modules, keys and splitters, the icon set, and the sortable tables
+  (their pure parts are node-tested). `D-DINCondensed-Bold.woff2` is the engraved labels' face.
 - `forge_ui/static/runmodel.js`: the pure run model (layouts, schedule projection, critical path, replay).
 - `forge_ui/static/panel.js`, `gantt.js`, `graph.js`: the inspector, the execution chart and strip, the 2D graph.
-- `forge_ui/static/map3d.js`, `scene3d.js`, `iso.js`: the 3D loader, scenes and engine (ported from archivision).
+- `forge_ui/static/map3d.js`, `scene3d.js`, `iso.js`: the 3D loader, scenes and engine (ported from archivision);
+  `findings3d.js` the findings' marks, `stagectl.js` the stage's keys, legend and keys sheet.
 - `forge_ui/static/cloudmodel.js`, `cloud3d.js`, `cloudui.js`: the run cloud's pure model (projects,
   filters, layouts, layout files), its scene on the shared stage, and its controls.
 - `forge_ui/static/diffview.js`: the diff viewer, with findings pinned to their lines.
+- `forge_ui/static/convo.js`, `forge_ui/transcripts.py`: an execution's conversation, and the
+  reader of each agent CLI's log format behind it.
 - `forge_ui/static/files.js`: the files heatmap (`matrix()` is pure and node-tested).
 - `forge_ui/export.py`: a run as one HTML file (the page's scripts and styles inlined, the API
   responses it reads, the 3D stage's modules as one module text, a hash-based policy).
@@ -267,7 +357,7 @@ skips otherwise. Its 3D tests need three.js: the CDN, or a local copy of the npm
 
 The pictures in this README and forge's come from `tools/readme_media.py`. After a change you
 can see, run it again: it builds the demo runs, serves them, and captures each view in
-Chromium with Playwright (three.js as for the browser tests; ffmpeg with libwebp and ImageMagick
+Chromium with Playwright (three.js as for the browser tests; libwebp's `img2webp` and ImageMagick
 to encode the animations and PNGs). `--only cloud diff` retakes some of them.
 
 ```sh
@@ -277,8 +367,11 @@ 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. Anyone with access to the local server can read the runs it discovers, and
+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.
 
 The 3D view loads three.js 0.160.0 from `cdn.jsdelivr.net` the first time it is shown in a

package/ui/THIRD_PARTY_NOTICES.md

@@ -67,3 +67,111 @@ SOFTWARE.
 
 three.js 0.160.0 (MIT, Copyright © 2010-2023 three.js authors) is not part of forge. The page
 loads it, with its `examples/jsm` add-ons, from `cdn.jsdelivr.net` when the 3D view is used.
+
+## D-DIN Condensed (font)
+
+`forge_ui/static/D-DINCondensed-Bold.woff2`, unmodified, is the D-DIN Condensed Bold face by Datto Inc.
+(https://www.datto.com/fonts/d-din), used for forge-ui's engraved labels. It is licensed under the SIL Open
+Font License 1.1; "D-DIN" and "D-DIN Condensed" are Reserved Font Names.
+
+```
+Copyright (C) 2017 Datto Inc. https://www.datto.com/fonts/d-din,
+with Reserved Font Names "D-DIN".
+
+Copyright (C) 2017 Datto Inc. https://www.datto.com/fonts/d-din,
+with Reserved Font Names "D-DIN Condensed".
+
+Copyright (C) 2017 Datto Inc. https://www.datto.com/fonts/d-din,
+with Reserved Font Names "D-DIN Expanded".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+```