@giamme/forge 0.8.0 → 0.9.0

package/scripts/forge_dataset/harvest.py

@@ -28,7 +28,7 @@ from . import SCRIPTS, put_blob, put_file, sha256
 DISPATCH_ROLES = ('dwarf', 'qa', 'planner')
 PIPELINE_ROLES = ('task', 'solo', 'verification', 'parallel')
 TASKS_COLS = ('id', 'deps', 'difficulty', 'files', 'dwarf', 'qa', 'title')
-STRUCTURED = ('codex', 'claude', 'grok')
+STRUCTURED = ('codex', 'claude', 'openclaude', 'grok', 'opencode')   # as forge-runtime.py's: .last is the message, not the log
 # Plan files that change what a plan decides, added to its rid only when present (see plan_event).
 PLAN_RID_LATER = ('decompose_level', 'shadow_qa', 'shadow_rate', 'explore')
 

package/scripts/forge_dataset/importer.py

@@ -347,7 +347,7 @@ def main(args) -> int:
                 if line.strip() and not line.startswith('#') and Path(line.strip()).is_dir():
                     targets.append(Path(line.strip()))
     if args.fractal:
-        state = Path(os.environ.get('XDG_STATE_HOME', str(Path.home() / '.local' / 'state'))).expanduser()
+        state = Path(os.environ.get('XDG_STATE_HOME') or str(Path.home() / '.local' / 'state')).expanduser()
         targets.append(state / 'forge' / 'fractal' / 'runs')
     ledgers = [(Path(r).expanduser() / '.forge' / 'ledger.tsv', str(Path(r).expanduser().resolve())) for r in args.ledger]
     archives = []

package/scripts/forge_fractal/__init__.py

@@ -18,7 +18,8 @@ DEFAULTS = dict(depth=2, children=3, nodes=12, iterations=6, concurrency=3, dead
 
 
 def state_root() -> Path:
-    return Path(os.environ.get('XDG_STATE_HOME', str(Path.home() / '.local/state'))).expanduser().resolve() / 'forge/fractal'
+    # An empty XDG_STATE_HOME counts as unset; Path('') would be the working directory.
+    return Path(os.environ.get('XDG_STATE_HOME') or str(Path.home() / '.local/state')).expanduser().resolve() / 'forge/fractal'
 
 
 def runtime_python() -> Path:

package/ui/README.md

@@ -7,7 +7,7 @@ blocks on a plate, with cables between them and lamps that light up as things ha
 - **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 +26,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 +106,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 +139,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 +184,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,16 +195,29 @@ 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,
@@ -192,8 +242,10 @@ 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
@@ -210,12 +262,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 +325,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
@@ -278,7 +336,9 @@ python3 tools/readme_media.py                  # writes docs/media/
 
 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
+forge's config. 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.
+```

package/ui/docs/api.md

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

package/ui/forge_ui/export.py

@@ -26,10 +26,11 @@ from forge_ui import __version__, server
 
 STATIC = server.STATIC_DIR
 # what the exported page runs, in index.html's order; the cloud, the leaderboard and notifications need a server
-SCRIPTS = ('runmodel.js', 'cloudmodel.js', 'graph.js', 'gantt.js', 'panel.js', 'diffview.js', 'files.js', 'map3d.js',
+SCRIPTS = ('theme.js', 'icons.js', 'datatable.js', 'shell.js', 'runmodel.js', 'cloudmodel.js', 'graph.js', 'gantt.js', 'panel.js', 'diffview.js', 'convo.js', 'files.js', 'map3d.js',
            'search.js', 'app.js')
-MODULES = ('iso.js', 'cloud3d.js', 'scene3d.js')            # bundled in dependency order
+MODULES = ('iso.js', 'cloud3d.js', 'findings3d.js', 'stagectl.js', 'scene3d.js')   # bundled in dependency order
 DIFF_CAP = 1 << 20                                          # one diff's JSON
+TRANSCRIPT_CAP = 2 << 20                                    # one execution's transcript
 TOTAL_CAP = 25 << 20                                        # every response together
 CDN = 'https://cdn.jsdelivr.net/npm/three@0.160.0/'
 _EXEC = re.compile(r'(?:task|dwarf|qa|solo|verification|parallel)-[0-9a-f]{32}')
@@ -145,12 +146,14 @@ def build(catalog, key, texts=False, paths=False, now=None):
     tasks = [t for t in (detail.get('tasks') or []) if isinstance(t, dict) and t.get('id')]
     for task in tasks:
         snap.add(f"{base}/tasks/{_enc(task['id'])}")
-    for name in sorted(set(_EXEC.findall(json.dumps(run)))):
+    names = sorted(set(_EXEC.findall(json.dumps(run))))
+    for name in names:
         snap.add(f'{base}/executions/{name}')
     reviews = [r.get('name') for r in (run.get('final_reviews') or []) if isinstance(r, dict) and r.get('name')]
     for name in reviews:
         snap.add(f'{base}/final-reviews/{_enc(name)}')
     snap.add(f'{base}/files')
+    snap.add(f'{base}/findings')
     fractal = run.get('fractal') or {}
     if fractal.get('enabled') and fractal.get('available'):
         for task in tasks:
@@ -170,6 +173,10 @@ def build(catalog, key, texts=False, paths=False, now=None):
                     snap.add(url, cap=DIFF_CAP)
         for name in reviews:
             snap.add(f'{base}/final-reviews/{_enc(name)}/diff', cap=DIFF_CAP)
+        # what each dwarf and reviewer said and ran: its conversation is all text
+        for name in names:
+            if name.startswith(('dwarf-', 'qa-')):
+                snap.add(f'{base}/executions/{name}/transcript', cap=TRANSCRIPT_CAP)
     meta = {'format': 'forge-ui-export', 'version': 1, 'app': __version__, 'key': key,
             'generated': now if now is not None else time.time(), 'texts': bool(texts), 'paths': bool(paths),
             'omitted': snap.omitted}
@@ -182,14 +189,17 @@ def build(catalog, key, texts=False, paths=False, now=None):
 def _page(snapshot, run):
     index = (STATIC / 'index.html').read_text(encoding='utf-8')
     importmap = re.search(r'<script type="importmap">(.*?)</script>', index, re.DOTALL).group(1)
-    body = re.search(r'<body>(.*)</body>', index, re.DOTALL).group(1)
+    body_tag, body = re.search(r'(<body[^>]*>)(.*)</body>', index, re.DOTALL).groups()
+    body = re.sub(r'\s*<script src="[^"]*"></script>', '', body)          # the page's own scripts are inlined below
     css = (STATIC / 'style.css').read_text(encoding='utf-8')
+    # the engraving face travels inside the file
+    css = re.sub(r'url\(([A-Za-z0-9_.-]+\.woff2)\)', lambda m: 'url(data:font/woff2;base64,%s)' % base64.b64encode((STATIC / m.group(1)).read_bytes()).decode('ascii'), css)
     scripts = [_script_safe((STATIC / name).read_text(encoding='utf-8')) for name in SCRIPTS if (STATIC / name).is_file()]
     data = json.dumps(snapshot, ensure_ascii=False, separators=(',', ':')).replace('<', '\\u003c').replace('>', '\\u003e').replace('&', '\\u0026')
     stage = _script_safe(bundle())
     icon = 'data:image/svg+xml;base64,' + base64.b64encode((STATIC / 'favicon.svg').read_bytes()).decode('ascii')
     csp = ("default-src 'none'; script-src " + ' '.join([_sha(importmap)] + [_sha(s) for s in scripts]) + f" blob: {CDN}; "
-           f"style-src {_sha(css)}; img-src data: blob:; connect-src 'none'; base-uri 'none'; form-action 'none'; object-src 'none'")
+           f"style-src {_sha(css)}; img-src data: blob:; font-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'; object-src 'none'")
     title = 'forge-ui · ' + re.sub(r'[<>&"]', '', str(run.get('goal') or run.get('run_id') or 'run').split('\n')[0])[:120]
     return ''.join([
         '<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n',
@@ -197,7 +207,7 @@ def _page(snapshot, run):
         '<meta name="referrer" content="no-referrer">\n',
         f'<meta http-equiv="Content-Security-Policy" content="{csp}">\n',
         f'<title>{title}</title>\n<link rel="icon" href="{icon}">\n',
-        f'<script type="importmap">{importmap}</script>\n<style>{css}</style>\n</head>\n<body>{body}',
+        f'<script type="importmap">{importmap}</script>\n<style>{css}</style>\n</head>\n{body_tag}{body}',
         f'<script type="application/json" id="forge-snapshot">{data}</script>\n',
         f'<script type="text/plain" id="forge-stage">{stage}</script>\n',
         ''.join(f'<script>{s}</script>\n' for s in scripts),