mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/viewer.py

@@ -0,0 +1,3713 @@
+"""Local, streaming notebook workbench for ``mr-data view``.
+
+The viewer is deliberately a spectator.  It reads ``research.ipynb`` and ``table.ipynb`` from a
+local run directory, renders them through the stdlib-only ``nbrender``, and streams file changes to
+the browser over SSE.  It never starts a kernel and never executes notebook code.
+
+Each valid on-disk notebook state is retained in a bounded in-memory journal.  The authoritative
+files remain on disk beside the candidate.
+"""
+
+# Embedded browser assets are kept as readable source. Their physical line lengths are unrelated
+# to Python layout and are intentionally exempt from the Python line-width rule.
+# ruff: noqa: E501
+
+from __future__ import annotations
+
+import errno
+import fcntl
+import hashlib
+import html
+import ipaddress
+import json
+import os
+import re
+import secrets
+import shlex
+import socket
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import webbrowser
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, replace
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib.resources import files
+from pathlib import Path
+from urllib.parse import parse_qs, urlsplit
+
+from mostlyright.data_harness import events
+from mostlyright.data_harness.event_presentation import (
+    actual_run_started_record,
+    coherent_build_seal_candidate,
+    elapsed_seconds,
+    format_elapsed,
+    reduce_lifecycle,
+)
+from mostlyright.data_harness.hosted_handoff import read_handoff_receipt
+from mostlyright.data_harness.nbrender import render_notebook
+from mostlyright.data_harness.notebook import (
+    _build_notebook_from_snapshot,
+    render_table_notebook,
+)
+from mostlyright.data_harness.offline import (
+    CONTROL_PATH,
+    WORKSPACE_LOCK_NAME,
+    validate_workspace_structure,
+)
+from mostlyright.data_harness.pipeline import (
+    RUN_BUILD_ACTIVITY_LOCK,
+    _CandidateRunHandle,
+    _entry_identity,
+    _open_candidate_run_handle,
+    _validate_candidate_run_handle,
+    open_verified_snapshot,
+    verify_candidate,
+)
+from mostlyright.data_harness.ux.remediation import remediation_for
+from mostlyright.data_harness.visual_run import (
+    ReducedRun,
+    VisualRunError,
+    VisualRunEvent,
+    VisualRunTransport,
+    apply_event,
+    discover_visual_transport,
+    materialize_notebook,
+    notebook_bytes,
+    parse_last_event_id,
+    visual_authority_lock,
+)
+from mostlyright.data_harness.visual_run.query import (
+    QueryError,
+    QueryEvidence,
+    query_sealed_parquet,
+    sealed_parquet_columns,
+)
+
+HEALTH_SIDECAR_UNAVAILABLE = "VIEWER_DATASET_SIDECAR_UNAVAILABLE"
+HEALTH_WATCHER_FAILED = "VIEWER_WATCHER_FAILED"
+# The typed codes `mr-data view` reports while it keeps serving. They reach a person through the
+# page, /health and /snapshot rather than through a raise site, so the remediation completeness
+# gate reads them from here rather than from the walk over refusals.
+HEALTH_CODES: tuple[str, ...] = (HEALTH_SIDECAR_UNAVAILABLE, HEALTH_WATCHER_FAILED)
+
+_SIDECAR_NAME = "table.ipynb"
+_DOCUMENTS = {"research": "research.ipynb", "table": _SIDECAR_NAME}
+_INSTALL_HINT = 'install the viewer extra: pip install "mostlyright-data[viewer]"'
+_POLL_SECONDS = 0.25
+_WATCH_POLL_SECONDS = 0.05
+_WATCHER_STOP_SECONDS = 2.0
+_MAX_HISTORY = 240
+_MAX_NOTEBOOK_BYTES = 8 * 1024 * 1024
+_MAX_SNAPSHOT_BYTES = 12 * 1024 * 1024
+_MAX_JOURNAL_BYTES = 32 * 1024 * 1024
+_READ_CHUNK_BYTES = 1024 * 1024
+_RESEARCH_ACTIVITY_SCHEMA = "mostlyright.research-cell-activity.v1"
+_RESEARCH_CELL_ID = re.compile(r"[A-Za-z0-9_-]{1,64}")
+
+_FileSignature = tuple[int, int, int, int, int, int, int]
+_DirectoryIdentity = tuple[int, int, int]
+
+_DIRECTORY_FLAGS = (
+    os.O_RDONLY
+    | getattr(os, "O_DIRECTORY", 0)
+    | getattr(os, "O_NOFOLLOW", 0)
+    | getattr(os, "O_CLOEXEC", 0)
+)
+
+
+class ViewerError(RuntimeError):
+    """A typed pre-bind refusal for an unsafe or ambiguous viewer target."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        super().__init__(detail)
+
+
+# Vendored from mostly-right-landing/src/assets/logo-ink.svg and its Logo.astro component.
+# The self-contained viewer inlines the vectors and has no landing-site or font dependency.
+_LOGO = (
+    files("mostlyright.data_harness").joinpath("assets/logo-ink.svg").read_text(encoding="utf-8")
+)
+_MARK_ONLY = _LOGO
+
+_WORKBENCH_CSS = r"""
+:root{color-scheme:light;--mr-ink:#17160f;--mr-logo-neutral:#17160f;--mr-cobalt:#2b5fe3;
+--mr-orange-brand:#f15b22;--mr-yellow:#ffc613;--mr-body:#57534a;--mr-muted:#6e6959;
+--mr-line:#e2ddd0;--mr-line-strong:#d8d2c4;--mr-canvas:#f5f2eb;--mr-white:#fff;
+--mr-blue:#2b5fe3;--mr-blue-soft:#e8edfc;--mr-green:#187a5a;--mr-orange:#f15b22;
+--mr-topbar:56px;--mr-sans:"Space Grotesk","Avenir Next",Avenir,"Helvetica Neue",sans-serif;
+--mr-mono:"JetBrains Mono","SFMono-Regular",Consolas,"Liberation Mono",monospace}
+*,*:before,*:after{box-sizing:border-box}
+html{scroll-behavior:auto}body{margin:0;background:var(--mr-canvas);color:var(--mr-ink);
+font-family:var(--mr-sans);font-size:13px;-webkit-font-smoothing:antialiased}.mr-topbar{position:fixed;z-index:50;inset:0 0 auto 0;
+height:var(--mr-topbar);display:flex;align-items:center;gap:14px;padding:0 14px 0 16px;
+background:var(--mr-canvas);border-bottom:1px solid var(--mr-line)}
+[hidden]{display:none!important}
+.mr-brand{display:flex;width:165px;min-height:32px;flex:0 0 165px;align-items:center;padding-right:16px;border-right:1px solid var(--mr-line);color:var(--mr-ink);text-decoration:none}
+.mr-logo{display:block;width:auto;height:20px}.mr-session{display:flex;min-width:0;max-width:330px;
+align-items:center}
+.mr-session-copy{display:flex;min-width:0;align-items:center;gap:7px;white-space:nowrap}.mr-session-copy small{overflow:hidden;color:var(--mr-body);
+font:500 10px/1 var(--mr-mono);text-overflow:ellipsis}.mr-session-copy strong{display:flex;align-items:center;gap:7px;overflow:hidden;color:var(--mr-muted);
+font:500 10px/1 var(--mr-mono);text-overflow:ellipsis;white-space:nowrap}.mr-session-copy strong:before{color:#aaa294;content:"/"}
+.mr-tabs{height:36px;display:flex;align-items:center;gap:2px;margin-left:4px;padding:2px;background:#f1ede3;border:1px solid var(--mr-line);border-radius:9px}
+.mr-tab{display:flex;height:32px;align-items:center;gap:0;padding:0 9px;background:transparent;border:1px solid transparent;border-radius:7px;
+color:var(--mr-muted);font:400 10.5px/1 var(--mr-mono);cursor:pointer}.mr-tab:hover{background:#e8e2d6;color:var(--mr-body)}
+.mr-tab.is-active{background:#fff;border-color:var(--mr-line-strong);color:var(--mr-ink);font-weight:600;box-shadow:0 1px 2px rgba(31,29,23,.08)}
+.mr-tabs.is-single{margin-left:4px;padding:0 0 0 16px;background:transparent;border:0;border-left:1px solid var(--mr-line);border-radius:0}.mr-tabs.is-single .mr-tab{padding:0 4px;background:transparent;border:0;box-shadow:none;cursor:default}
+.mr-tabs.is-single .mr-tab:hover{background:transparent}.mr-tabs.is-single .mr-tab-icon{color:var(--mr-orange-brand)}
+.mr-tab-icon{width:13px;height:13px;margin-right:6px;fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.25}
+.mr-tab-name{white-space:nowrap}.mr-tab-ext{margin-left:1px;color:var(--mr-muted);font-family:var(--mr-mono);font-size:9px}.mr-actions{display:flex;
+margin-left:auto;align-items:center;gap:6px}.mr-live{display:flex;align-items:center;gap:7px;margin-right:4px;padding-right:10px;border-right:1px solid var(--mr-line);
+color:var(--mr-muted);font-size:10px}.mr-live i{width:6px;height:6px;background:var(--mr-green);border-radius:50%}
+.mr-live.is-reconnecting i{background:var(--mr-orange)}.mr-live.is-unavailable i,.mr-live.is-stopped i{background:#b42318}
+.mr-button,.mr-download{height:34px;display:inline-flex;align-items:center;justify-content:center;gap:6px;padding:0 11px;
+background:#fff;border:1px solid var(--mr-line-strong);border-radius:7px;color:var(--mr-body);font:600 10.5px/1 var(--mr-sans);
+text-decoration:none;cursor:pointer}.mr-button:hover,.mr-download:hover{background:#f8f9fb;border-color:#aeb5bf}
+.mr-button--primary{background:var(--mr-ink);border-color:var(--mr-ink);color:#fff}.mr-button--primary:hover{background:#30353c}
+.mr-download[aria-disabled="true"],.mr-button[data-explore]:disabled{display:none}.mr-button[data-files]{width:34px;padding:0}.mr-files-label{position:absolute;width:1px;height:1px;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}.mr-run-clock{min-width:44px;color:var(--mr-muted);
+font:600 11.5px/1 var(--mr-mono);font-variant-numeric:tabular-nums;text-align:right}.mr-overall{position:absolute;width:1px;height:1px;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}.mr-overall span{display:none}
+.mr-button:disabled{opacity:.45;cursor:not-allowed}.mr-workbench{min-height:100vh;padding-top:var(--mr-topbar)}
+.mr-explorer{width:min(920px,calc(100vw - 32px));max-height:80vh;border:1px solid var(--mr-line);border-radius:12px;padding:0}.mr-explorer::backdrop{background:#17202a66}.mr-explorer-head{display:flex;justify-content:space-between;align-items:center;padding:14px 16px;border-bottom:1px solid var(--mr-line)}.mr-explorer-body{overflow:auto;padding:12px 16px 18px}.mr-explorer table{border-collapse:collapse;width:100%;font-size:12px}.mr-explorer th,.mr-explorer td{border-bottom:1px solid var(--mr-line);padding:7px;text-align:left;white-space:nowrap}.mr-explorer td{font-family:var(--mr-mono)}
+.mr-explorer-tools{display:flex;flex-wrap:wrap;gap:8px;align-items:end;margin:0 0 12px}.mr-explorer-tools label{display:grid;gap:4px;font-size:11px;color:var(--mr-muted)}.mr-explorer-tools select,.mr-explorer-tools input{font:12px var(--mr-sans);border:1px solid var(--mr-line);border-radius:6px;background:var(--mr-surface);color:var(--mr-ink);padding:6px}.mr-explorer-tools select[multiple]{min-width:180px;max-height:94px}.mr-explorer-status{margin-left:auto;color:var(--mr-muted);font-size:12px}
+.mr-explorer-evidence{display:grid;gap:10px;margin:0 0 16px}.mr-explorer-evidence>h3{margin:0;font-size:14px}.mr-explorer-evidence .nb-stage-observation{max-height:420px;overflow:auto}
+.mr-stage{max-width:940px;margin:0 auto;padding:30px 28px 55vh}.mr-notebook-root{min-height:420px}
+.mr-build-progress{margin:0 0 18px;background:var(--mr-white);border:1px solid var(--mr-line);border-radius:7px;
+box-shadow:0 1px 3px rgba(31,35,41,.025)}.mr-build-progress>summary{list-style:none;cursor:pointer;padding:11px 14px}
+.mr-build-progress>summary::-webkit-details-marker{display:none}.mr-build-progress-head{display:flex;align-items:baseline;gap:12px;margin:0}
+.mr-build-progress-head strong{font-size:12px}.mr-build-progress-state{color:var(--mr-green);font:700 8.5px/1 var(--mr-mono);
+letter-spacing:.08em;text-transform:uppercase}.mr-build-progress.is-failed .mr-build-progress-state{color:#b42318}
+.mr-build-progress ol{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:7px 22px;margin:0;padding:4px 14px 14px;list-style:none}
+.mr-build-line{display:grid;grid-template-columns:18px minmax(0,1fr);column-gap:4px;align-items:baseline;color:var(--mr-body)}
+.mr-build-mark{color:var(--mr-orange);font:700 12px/1 var(--mr-mono)}.mr-build-line.is-done .mr-build-mark{color:var(--mr-green)}
+.mr-build-line.is-failed .mr-build-mark{color:#b42318}.mr-build-copy{display:flex;min-width:0;gap:7px;align-items:baseline}
+.mr-build-label{font-size:12.5px;font-weight:650}.mr-build-detail{overflow:hidden;color:var(--mr-muted);font:11px/1.35 var(--mr-mono);
+text-overflow:ellipsis;white-space:nowrap}
+.mr-health-detail{display:grid;grid-template-columns:2px minmax(0,1fr);column-gap:14px;margin:0 0 24px;padding:3px 0;
+background:transparent;border:0;color:var(--mr-ink);line-height:1.5;overflow-wrap:anywhere}.mr-health-detail:before{grid-row:1/4;width:2px;
+background:#a34718;border-radius:1px;content:""}.mr-health-detail strong{grid-column:2;color:#8b3f20;font:700 9.5px/1.4 var(--mr-mono);
+letter-spacing:.06em;text-transform:uppercase}.mr-health-detail span{grid-column:2;margin-top:5px;color:var(--mr-body);font-size:13px}
+.mr-health-detail code{grid-column:2;display:block;margin-top:8px;overflow-wrap:anywhere;color:var(--mr-muted);font:600 11px/1.5 var(--mr-mono)}
+.mr-research-terminal{margin:24px 0 0;padding:3px 0 3px 16px;background:transparent;border:0;border-left:2px solid #a34718;
+border-radius:0;color:var(--mr-ink);overflow-wrap:anywhere}.mr-research-terminal strong{display:block;font-size:15px}.mr-research-terminal p{margin:7px 0 0;
+color:var(--mr-body);font-size:14px;line-height:1.5}.mr-research-terminal small{display:block;margin-top:9px;color:var(--mr-muted);font:600 11px/1.4 var(--mr-mono)}
+.mr-workbench .nb-shell{overflow:visible;border:0;border-radius:0;background:transparent;box-shadow:none;font-family:var(--mr-sans)}
+.mr-workbench .nb-body{display:block}.mr-workbench .nb-document{padding:0;gap:20px}.mr-workbench .nb-cell{
+grid-template-columns:56px minmax(0,1fr);column-gap:16px}.mr-workbench .nb-content{font-size:13px}
+/* The output row re-enters the gutter this cell states: 72px = the 56px gutter + the 16px gap.
+Restacking lives in @container below, not @media -- the shell is narrower than the viewport. */
+.mr-workbench .nb-io{margin-left:-72px;grid-template-columns:56px minmax(0,1fr);column-gap:16px}
+.mr-workbench .nb-prompt{padding-top:8px;color:var(--mr-muted);font-size:9px;text-align:right}.mr-workbench .nb-prompt--md{padding-top:4px}
+.mr-workbench .nb-md{overflow-x:auto}.mr-workbench .nb-md p,.mr-workbench .nb-md li{font-size:12.5px;line-height:1.55}.mr-workbench .nb-md p{max-width:none}
+.mr-workbench .nb-md code{padding:1px 4px;font-size:10.5px;line-height:1.35}
+.mr-workbench .nb-md h1{max-width:32ch;font-size:24px;line-height:1.12;letter-spacing:-.025em}
+.mr-workbench .nb-md h2{font-size:17px;line-height:1.2;letter-spacing:-.015em}.mr-workbench .nb-md h3{font-size:13px;letter-spacing:0}
+.mr-workbench .nb-cell:has(.nb-md h2):not(:has(.nb-md h1)){margin-top:18px;padding-top:22px;border-top:1px solid var(--mr-line)}
+.mr-workbench .nb-document>.nb-cell:first-child{margin-top:0;padding-top:0;border-top:0}
+.mr-workbench .nb-cell:has(.nb-md h1)+.nb-cell:has(.nb-md h2){margin-top:8px;padding-top:0;border-top:0}
+.mr-workbench .nb-md h2+*{margin-top:4px}.mr-workbench .nb-md h3{margin-top:18px}.mr-workbench .nb-md-table{min-width:640px;background:var(--mr-white)}
+.mr-workbench .nb-md-table thead th{padding:8px 12px;font-size:9px}.mr-workbench .nb-md-table tbody td{padding:8px 12px;background:var(--mr-white);font-size:12px}
+.mr-workbench .nb-df{background:var(--mr-white);border-radius:6px}.mr-workbench .nb-df table{font-size:11.5px}.mr-workbench .nb-df th{padding:8px 12px;font-size:9px}.mr-workbench .nb-df td{padding:8px 12px;background:var(--mr-white)}
+.mr-workbench .nb-result-plain{padding:10px 12px;background:var(--mr-white);border:1px solid var(--mr-line);border-radius:6px;color:var(--mr-ink);font-size:11.5px;line-height:1.55}
+.mr-workbench .nb-rich{background:var(--mr-white);border-radius:6px}.mr-workbench .nb-rich-head{display:none}.mr-workbench .nb-rich-body{padding:0}
+.mr-workbench .nb-rich-body table{width:100%;border-collapse:collapse;background:var(--mr-white);font-size:11.5px}.mr-workbench .nb-md-table thead th,.mr-workbench .nb-df thead th,.mr-workbench .nb-rich-body thead th{padding:8px 12px;background:var(--nb-sub-paper);border-bottom:1px solid var(--nb-border);font-family:var(--fm);font-size:9px;font-weight:600;letter-spacing:.1em;text-transform:uppercase;color:var(--nb-dim);text-align:left}.mr-workbench .nb-md-table tbody td,.mr-workbench .nb-df tbody td,.mr-workbench .nb-rich-body tbody td{background:var(--mr-white);border-bottom:1px solid var(--nb-row-rule)}.mr-workbench .nb-md-table tbody td:first-child,.mr-workbench .nb-df tbody td:first-child,.mr-workbench .nb-rich-body tbody td:first-child{background:var(--mr-white);border-left:0 solid var(--nb-row-rule);border-right:0 solid var(--nb-row-rule)}.mr-workbench .nb-md-table tbody tr:last-child td,.mr-workbench .nb-df tbody tr:last-child td,.mr-workbench .nb-rich-body tbody tr:last-child td{border-bottom:0 solid var(--nb-row-rule)}.mr-workbench .nb-rich-body td{padding:8px 12px}
+.mr-workbench .nb-panel.is-selected,.mr-workbench .nb-cell.is-editing .nb-gutter{box-shadow:none}
+.mr-workbench .nb-prov{display:none}
+.mr-workbench button,.mr-workbench a{min-height:32px}.mr-workbench a{display:inline-flex;align-items:center}
+.mr-workbench .nb-code{border-radius:7px}.mr-workbench .nb-code .nb-lineno{display:none}
+.mr-workbench .nb-code pre[tabindex]{overflow-x:hidden;
+overflow-wrap:anywhere;white-space:pre-wrap;font-size:11.5px;line-height:1.62}
+.mr-workbench [data-research-activity]{position:relative}
+.mr-workbench [data-research-activity]:before{position:absolute;top:0;bottom:0;left:-16px;width:2px;background:var(--mr-blue);content:""}
+.mr-workbench [data-research-activity="executing"]:before{background:var(--mr-orange)}
+.mr-workbench .nb-activity{gap:5px;margin:0 0 10px;padding:0;background:transparent;border-radius:0;color:#8cadff;
+font:500 9px/1 var(--mr-mono);text-transform:none;letter-spacing:0}.mr-workbench .nb-activity--executing{background:transparent;color:#f08a61}
+.mr-workbench .nb-panel-head>.nb-activity{margin:0 7px}
+.mr-workbench .nb-activity:before{width:5px;height:5px;background:currentColor;border-radius:50%;content:""}
+.mr-workbench .nb-activity-caret{width:1px;height:10px}
+.mr-waiting{min-height:460px;display:flex;align-items:center;justify-content:center;flex-direction:column;gap:12px;
+color:var(--mr-muted);text-align:center}.mr-waiting .mr-logo{width:auto;height:26px}
+.mr-waiting strong{color:var(--mr-ink);font-size:13px}.mr-waiting span{max-width:390px;font-size:11px;line-height:1.5}
+.mr-stream-enter{animation:mr-enter .28s ease-out both}.mr-stream-update{animation:mr-update .26s ease-out both}
+.mr-sr-status{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
+.mr-toast{position:fixed;z-index:60;right:20px;bottom:20px;padding:11px 14px;background:var(--mr-ink);border-radius:8px;
+color:#fff;font-size:12.5px;box-shadow:0 8px 30px rgba(31,35,41,.2)}
+@keyframes mr-enter{from{opacity:0;transform:translateY(7px)}to{opacity:1;transform:none}}
+@keyframes mr-update{from{opacity:.72}to{opacity:1}}
+@keyframes mr-logo-f1{0%,100%{fill:var(--mr-logo-neutral)}35%{fill:var(--mr-cobalt)}50%{fill:var(--mr-orange-brand)}85%{fill:var(--mr-yellow)}}
+@keyframes mr-logo-f2{0%,100%{fill:var(--mr-orange-brand)}35%{fill:var(--mr-yellow)}50%{fill:var(--mr-logo-neutral)}85%{fill:var(--mr-cobalt)}}
+@keyframes mr-logo-f3{0%,100%{fill:var(--mr-yellow)}35%{fill:var(--mr-logo-neutral)}50%{fill:var(--mr-cobalt)}85%{fill:var(--mr-orange-brand)}}
+@keyframes mr-logo-f4{0%,100%{fill:var(--mr-cobalt)}35%{fill:var(--mr-orange-brand)}50%{fill:var(--mr-yellow)}85%{fill:var(--mr-logo-neutral)}}
+@keyframes mr-logo-f5{0%,100%{fill:var(--mr-orange-brand)}35%{fill:var(--mr-yellow)}50%{fill:var(--mr-cobalt)}85%{fill:var(--mr-logo-neutral)}}
+@keyframes mr-logo-f6{0%,100%{fill:var(--mr-logo-neutral)}35%{fill:var(--mr-cobalt)}50%{fill:var(--mr-orange-brand)}85%{fill:var(--mr-yellow)}}
+@keyframes mr-logo-f7{0%,100%{fill:var(--mr-cobalt)}35%{fill:var(--mr-orange-brand)}50%{fill:var(--mr-yellow)}85%{fill:var(--mr-cobalt)}}
+@keyframes mr-logo-f8{0%,100%{fill:var(--mr-yellow)}35%{fill:var(--mr-logo-neutral)}50%{fill:var(--mr-cobalt)}85%{fill:var(--mr-orange-brand)}}
+@keyframes mr-logo-f9{0%,100%{fill:var(--mr-yellow)}35%{fill:var(--mr-cobalt)}50%{fill:var(--mr-logo-neutral)}85%{fill:var(--mr-yellow)}}
+.mr-logo-facet--1{--mr-logo-animation:mr-logo-f1}.mr-logo-facet--2{--mr-logo-animation:mr-logo-f2}
+.mr-logo-facet--3{--mr-logo-animation:mr-logo-f3}.mr-logo-facet--4{--mr-logo-animation:mr-logo-f4}
+.mr-logo-facet--5{--mr-logo-animation:mr-logo-f5}.mr-logo-facet--6{--mr-logo-animation:mr-logo-f6}
+.mr-logo-facet--7{--mr-logo-animation:mr-logo-f7}.mr-logo-facet--8{--mr-logo-animation:mr-logo-f8}
+.mr-logo-facet--9{--mr-logo-animation:mr-logo-f9}
+@media(hover:hover){.mr-logo:hover .mr-logo-facet{animation-name:var(--mr-logo-animation);animation-duration:680ms;
+animation-timing-function:steps(1,end);animation-iteration-count:3;animation-fill-mode:both}}
+.mr-waiting .mr-logo-facet{animation-name:var(--mr-logo-animation);animation-duration:680ms;
+animation-timing-function:steps(1,end);animation-iteration-count:infinite;animation-fill-mode:both}
+@media(prefers-reduced-motion:reduce){.mr-stream-enter,.mr-stream-update,.mr-logo:hover .mr-logo-facet,
+.mr-waiting .mr-logo-facet{animation:none}}
+@media(max-width:1100px){.mr-session{max-width:230px}.mr-live{display:none}.mr-stage{padding-right:24px;padding-left:24px}}
+@media(max-width:760px){.mr-topbar{gap:6px;padding:0 9px;overflow-x:auto}.mr-brand{display:none}.mr-live{display:none}
+.mr-session{display:flex;max-width:190px}.mr-tabs{min-width:0}.mr-tab{padding:0 7px}.mr-tab-ext{display:none}.mr-actions{flex-shrink:0}
+.mr-button,.mr-download{padding:0 10px}.mr-stage{padding:28px 12px 45vh}}
+@media(max-width:559px){:root{--mr-topbar:56px}.mr-topbar{height:var(--mr-topbar);display:flex;overflow:visible}.mr-session{display:none}.mr-tabs{height:36px;margin-left:0}.mr-actions{min-width:0;margin-left:auto;gap:5px}.mr-actions [data-explore],.mr-actions .mr-download{display:none}.mr-button{height:34px;padding:0 8px;font-size:11.5px}}
+@media(max-width:620px){.mr-build-progress ol{grid-template-columns:minmax(0,1fr)}.mr-build-progress-head{align-items:flex-start;flex-direction:column;gap:5px}}
+@container (max-width:559px){.mr-workbench .nb-cell{grid-template-columns:minmax(0,1fr);column-gap:0}
+.mr-workbench .nb-gutter{grid-column:1;display:flex;gap:10px;padding:0 2px 6px;text-align:left}
+.mr-workbench .nb-content{grid-column:1;min-width:0}.mr-workbench .nb-io{margin-left:0;grid-template-columns:minmax(0,1fr);column-gap:0}.mr-workbench .nb-io-gutter,.mr-workbench .nb-io-body{grid-column:1}}
+""".strip()
+
+_RELOAD_SCRIPT = r"""
+<script>
+(() => {
+  const state = {doc: document.body.dataset.doc || '', version: Number(document.body.dataset.version || 0),
+    cursor: Number(document.body.dataset.cursor || 0),
+    epoch: document.body.dataset.epoch || '', health: document.body.dataset.health || 'running',
+    handoff: document.body.dataset.handoff === 'true', lifecycle: null,
+    requestSerial: 0, navigationSerial: 0, applyQueue: Promise.resolve(), pendingSnapshots: [], streamWorker: false,
+    followedPhases: new Set(), followHeld: false, incoming: null};
+  const root = document.querySelector('[data-notebook-root]');
+  const toast = message => { const node=document.createElement('div'); node.className='mr-toast';
+    node.setAttribute('role','status'); node.textContent=message; document.body.append(node); setTimeout(()=>node.remove(),2400); };
+  function activateInspector(select) { const inspector=select.closest('[data-column-inspector]'); if(!inspector)return;
+    const name=select.value; inspector.querySelectorAll('[data-column-profile]').forEach(panel => {
+      const active=panel.dataset.columnProfile===name; panel.hidden=!active; panel.classList.toggle('is-active',active);
+    }); const title=inspector.querySelector('[data-column-title]'); if(title) title.textContent=name;
+  }
+  function setStatus(label) { const badge=document.querySelector('[data-live-status]'); if(!badge)return;
+    badge.classList.remove('is-reconnecting','is-unavailable','is-stopped');
+    badge.classList.add('is-'+label.toLowerCase()); badge.querySelector('span').textContent=label; }
+  function healthLabel(status) { return status==='stopped'?'Stopped':status==='unavailable'?'Unavailable':'Live'; }
+  function applyHealth(health) { state.health=health.status; document.body.dataset.health=health.status;
+    setStatus(healthLabel(health.status)); const detail=document.querySelector('[data-health-detail]');if(!detail)return;
+    const failed=(health.status==='unavailable'||health.status==='stopped')&&health.code;if(!failed){detail.hidden=true;return;}
+    const code=String(health.code),message=health.detail||'',command=health.remediation||'',strong=detail.querySelector('strong'),span=detail.querySelector('span'),remediation=detail.querySelector('code');
+    const changed=strong.textContent!==code||span.textContent!==message||remediation.textContent!==command;if(!changed){detail.hidden=false;return;}detail.hidden=true;
+    strong.textContent=code;span.textContent=message;remediation.textContent=command;detail.hidden=false; }
+  function updateTabs(docs, active=state.doc) { document.querySelectorAll('.mr-tab[data-doc]').forEach(tab => { tab.hidden=!docs.includes(tab.dataset.doc);
+    tab.classList.toggle('is-active',tab.dataset.doc===active); tab.setAttribute('aria-selected',String(tab.dataset.doc===active)); }); }
+  function clockText(seconds) { seconds=Math.max(0,Math.floor(seconds));const hours=Math.floor(seconds/3600), minutes=Math.floor(seconds%3600/60), secs=seconds%60;
+    return hours?hours+':'+String(minutes).padStart(2,'0')+':'+String(secs).padStart(2,'0'):String(minutes).padStart(2,'0')+':'+String(secs).padStart(2,'0'); }
+  function tickClock() { const node=document.querySelector('[data-run-clock]'), lifecycle=state.lifecycle;if(!node||!lifecycle||lifecycle.started_at==null){if(node)node.hidden=true;return;}
+    const stop=lifecycle.ended_at==null?Date.now()/1000:Number(lifecycle.ended_at);node.textContent=clockText(stop-Number(lifecycle.started_at));node.hidden=false; }
+  function applyLifecycle(lifecycle) { if(!lifecycle)return;state.lifecycle=lifecycle;state.handoff=Boolean(lifecycle.handoff);document.body.dataset.handoff=String(state.handoff);
+    const phase=document.querySelector('[data-lifecycle-phase]');if(phase){const label=lifecycle.phase||'Research notebook';phase.textContent=label==='Research notebook'?'Research':label;}
+    const overall=document.querySelector('[data-overall-progress]'), progress=Math.max(0,Math.min(100,Number(lifecycle.progress)||0));
+    if(overall){overall.setAttribute('aria-valuenow',String(progress));const fill=overall.querySelector('span');if(fill)fill.style.width=progress+'%';}
+    const block=document.querySelector('[data-build-progress]');if(block){block.hidden=lifecycle.status==='idle';block.open=lifecycle.status!=='completed'&&lifecycle.status!=='idle';block.classList.toggle('is-failed',lifecycle.status==='failed');
+      const status=block.querySelector('[data-build-state]');if(status)status.textContent=lifecycle.status==='failed'?'Stopped':lifecycle.status==='completed'?'Complete':'Running';
+      const heading=block.querySelector('[data-build-phase]');if(heading)heading.textContent=lifecycle.phase||'';const list=block.querySelector('[data-build-lines]');
+      if(list){const nodes=(lifecycle.lines||[]).map(line=>{const item=document.createElement('li');item.className='mr-build-line is-'+line.status;item.dataset.buildSpan=line.key;
+        const mark=document.createElement('span');mark.className='mr-build-mark';mark.setAttribute('aria-hidden','true');mark.textContent=line.status==='failed'?'!':line.status==='done'?'ok':'.';
+        const copy=document.createElement('span');copy.className='mr-build-copy';const label=document.createElement('span');label.className='mr-build-label';label.textContent=line.label;
+        const detail=document.createElement('span');detail.className='mr-build-detail';detail.textContent=line.detail;copy.append(label,detail);item.append(mark,copy);return item;});list.replaceChildren(...nodes);}}
+    const files=document.querySelector('[data-files]'), filesLabel=state.handoff?'Show table in Finder':'Show run in Finder';if(files){files.setAttribute('aria-label',filesLabel);const label=files.querySelector('.mr-files-label');if(label)label.textContent=filesLabel;}
+    const download=document.querySelector('[data-download]');if(download){download.setAttribute('aria-disabled',String(!state.handoff));if(state.handoff){download.href='/download/table.parquet';download.removeAttribute('tabindex');}else{download.removeAttribute('href');download.setAttribute('tabindex','-1');}}
+    const explore=document.querySelector('[data-explore]');if(explore)explore.disabled=!state.handoff;
+    applyResearchTerminal(lifecycle);tickClock(); }
+  function applyResearchTerminal(lifecycle) { const node=document.querySelector('[data-research-terminal]'), terminal=lifecycle&&lifecycle.terminal;if(!node)return;
+    const visible=Boolean(terminal)&&state.doc!=='table';if(!visible){node.hidden=true;return;}const event=terminal.event||'',title=terminal.title||'Build stopped',message=terminal.detail||'';
+    const meta=node.querySelector('small'),parts=[terminal.severity,terminal.finding_id].filter(Boolean),metadata=parts.join(' · '),strong=node.querySelector('strong'),paragraph=node.querySelector('p');
+    const changed=node.dataset.terminalEvent!==event||strong.textContent!==title||paragraph.textContent!==message||meta.textContent!==metadata;if(!changed){node.hidden=false;return;}node.hidden=true;
+    node.dataset.terminalEvent=event;strong.textContent=title;paragraph.textContent=message;meta.textContent=metadata;meta.hidden=parts.length===0;node.hidden=false; }
+  function anchor() { const cells=[...root.querySelectorAll('[data-cell-id]')]; const item=cells.find(node=>node.getBoundingClientRect().bottom>70);
+    return item?{id:item.dataset.cellId,top:item.getBoundingClientRect().top}:null; }
+  function parsedNotebook(markup) { const template=document.createElement('template'); template.innerHTML=markup.trim();
+    const next=template.content.firstElementChild; if(!next)throw new Error('snapshot contained no notebook'); return next; }
+  function inspectorChoices(scope) { return [...scope.querySelectorAll('[data-column-select]')].map(select=>select.value); }
+  function restoreInspectorChoices(scope, choices) { scope.querySelectorAll('[data-column-select]').forEach((select,index)=>{
+    if(choices[index]&&[...select.options].some(option=>option.value===choices[index]))select.value=choices[index]; activateInspector(select); }); }
+  function ownedNodes(cell, selector) { return [...cell.querySelectorAll(selector)].filter(node=>node.closest('[data-cell-id]')===cell); }
+  function sourceNode(cell) { return cell.querySelector('.nb-code > .nb-code-lines, .nb-code > pre[tabindex], .nb-md, .nb-raw'); }
+  function outputNodes(cell) { const content=cell.querySelector(':scope > .nb-content');return content?[...content.children].filter(node=>node.matches('.nb-io,.nb-well')):[]; }
+  function syncOptional(oldCell,newCell,selector) { const oldNode=ownedNodes(oldCell,selector)[0],newNode=ownedNodes(newCell,selector)[0];
+    if(oldNode&&newNode){if(oldNode.outerHTML!==newNode.outerHTML)oldNode.parentNode.replaceChild(newNode,oldNode);return;}if(oldNode)oldNode.remove();else if(newNode){const content=oldCell.querySelector('.nb-content');if(selector==='[data-cell-exec-meta]')content.append(newNode);else content.prepend(newNode);} }
+  function syncElement(oldNode,newNode){[...oldNode.attributes].forEach(attribute=>{if(!newNode.hasAttribute(attribute.name))oldNode.removeAttribute(attribute.name);});[...newNode.attributes].forEach(attribute=>oldNode.setAttribute(attribute.name,attribute.value));oldNode.replaceChildren(...[...newNode.childNodes]);}
+  function syncOutputs(oldCell,newCell) { const oldNodes=outputNodes(oldCell),newNodes=outputNodes(newCell);
+    oldNodes.slice(newNodes.length).forEach(node=>node.remove());const content=oldCell.querySelector(':scope > .nb-content');
+    newNodes.forEach((node,index)=>{const old=oldNodes[index];if(old){if(old.outerHTML!==node.outerHTML){if(old.tagName===node.tagName)syncElement(old,node);else old.parentNode.replaceChild(node,old);}return;}
+      content.append(node);}); }
+  function syncCellState(oldCell,newCell) { oldCell.className=newCell.className;oldCell.setAttribute('aria-label',newCell.getAttribute('aria-label')||'');
+    if(newCell.hasAttribute('data-research-activity'))oldCell.setAttribute('data-research-activity',newCell.getAttribute('data-research-activity'));else oldCell.removeAttribute('data-research-activity');
+    const oldGutter=oldCell.querySelector(':scope > [data-cell-gutter]'),newGutter=newCell.querySelector(':scope > [data-cell-gutter]');
+    if(oldGutter&&newGutter)oldGutter.replaceChildren(...[...newGutter.childNodes]);
+    const oldPanel=oldCell.querySelector('.nb-panel.nb-code'),newPanel=newCell.querySelector('.nb-panel.nb-code');
+    if(oldPanel&&newPanel){oldPanel.className=newPanel.className;const oldHead=oldPanel.querySelector(':scope > .nb-panel-head'),newHead=newPanel.querySelector(':scope > .nb-panel-head');if(oldHead&&newHead)oldHead.replaceChildren(...[...newHead.childNodes]);}
+    else syncOptional(oldCell,newCell,'[data-cell-activity]');syncOptional(oldCell,newCell,'[data-cell-exec-meta]'); }
+  function exactMutationPatch(next,doc,mutation,version,epoch,cursor) { if(!mutation||doc!=='research'||root.dataset.doc!==doc||epoch!==state.epoch||
+      (mutation.source==='visual-run'&&Number(mutation.from_cursor)!==state.cursor)||
+      (mutation.source!=='visual-run'&&Number(mutation.from_version)!==state.version)||
+      Number(mutation.version)!==Number(version)||mutation.doc!==doc||
+      (mutation.source==='visual-run'&&Number(mutation.cursor)!==Number(cursor)))return null;
+    const oldDoc=root.querySelector('.nb-document'),newDoc=next.querySelector('.nb-document');if(!oldDoc||!newDoc)return null;
+    const oldCells=[...oldDoc.querySelectorAll(':scope > [data-cell-id]')],newCells=[...newDoc.querySelectorAll(':scope > [data-cell-id]')];
+    const cellId=String(mutation.cell_id||''),oldCell=oldCells.find(node=>node.dataset.cellId===cellId),newCell=newCells.find(node=>node.dataset.cellId===cellId);
+    if(!newCell)return null;const idsBefore=oldCells.map(node=>node.dataset.cellId),idsAfter=newCells.map(node=>node.dataset.cellId),newIndex=idsAfter.indexOf(cellId);
+    const insertion=!oldCell&&newCells.length===oldCells.length+1&&idsAfter.filter(id=>id!==cellId).every((id,index)=>id===idsBefore[index]);
+    const sameOrder=idsBefore.every((id,index)=>id===idsAfter[index]),move=mutation.kind==='move'&&oldCell&&newCells.length===oldCells.length&&idsBefore.every(id=>idsAfter.includes(id));
+    const update=oldCell&&newCells.length===oldCells.length&&(sameOrder||move);if(!insertion&&!update)return null;
+    if(insertion){newCell.classList.add('mr-stream-enter');const anchor=oldCells[newIndex]||null;if(anchor)anchor.before(newCell);else oldDoc.append(newCell);return newCell;}
+    if(mutation.kind==='move'){const anchorId=String(mutation.after_cell_id||''),anchor=oldCells.find(node=>node.dataset.cellId===anchorId);if(!anchor)return null;anchor.after(oldCell);syncCellState(oldCell,newCell);oldCell.classList.add('mr-stream-update');return oldCell;}
+    const oldSource=sourceNode(oldCell),newSource=sourceNode(newCell);if(!oldSource||!newSource)return null;
+    const kind=mutation.kind;if(kind==='source'){if(outputNodes(oldCell).map(node=>node.outerHTML).join('')!==outputNodes(newCell).map(node=>node.outerHTML).join(''))return null;oldSource.parentNode.replaceChild(newSource,oldSource);}
+    else if(kind==='revision'){oldSource.parentNode.replaceChild(newSource,oldSource);syncOutputs(oldCell,newCell);}
+    else if(kind==='output'||kind==='state'){if(oldSource.textContent!==newSource.textContent)return null;if(newSource.hasAttribute('aria-label'))oldSource.setAttribute('aria-label',newSource.getAttribute('aria-label')||'');oldSource.querySelectorAll('[aria-label]').forEach((node,index)=>{const fresh=newSource.querySelectorAll('[aria-label]')[index];if(fresh)node.setAttribute('aria-label',fresh.getAttribute('aria-label')||'');});syncOutputs(oldCell,newCell);}
+    else return null;syncCellState(oldCell,newCell);oldCell.classList.add('mr-stream-update');return oldCell; }
+  function followPhase(cell,mutation) { const key=mutation.cell_id+':'+mutation.phase;if(state.followedPhases.has(key))return;state.followedPhases.add(key);
+    const announcement=document.querySelector('[data-stream-announcement]');if(announcement)announcement.textContent=mutation.announcement||('Research cell '+mutation.phase);
+    const follow=document.querySelector('[data-follow-agent]'),active=cell.matches('[data-research-activity]');if(state.followHeld&&active){if(follow)follow.hidden=false;return;}if(follow)follow.hidden=true;
+    const reduced=matchMedia('(prefers-reduced-motion: reduce)').matches,delta=cell.getBoundingClientRect().top-innerHeight*.32;
+    scrollBy({top:delta,left:0,behavior:reduced?'auto':'smooth'}); }
+  function patchNotebook(markup, doc) { const incoming=state.incoming||{},mutation=incoming.mutation||null,version=incoming.version??state.version,epoch=incoming.epoch||state.epoch,cursor=incoming.cursor??state.cursor;
+    const next=parsedNotebook(markup); const held=anchor(); const choices=inspectorChoices(root);
+    const streamed=exactMutationPatch(next,doc,mutation,version,epoch,cursor);if(streamed){const heldNext=held?[...root.querySelectorAll('[data-cell-id]')].find(node=>node.dataset.cellId===held.id):null;
+      if(held&&heldNext)scrollBy(0,heldNext.getBoundingClientRect().top-held.top);followPhase(streamed,mutation);return;}
+    if(root.dataset.doc===doc){const oldDoc=root.querySelector('.nb-document'), newDoc=next.querySelector('.nb-document');
+      if(oldDoc&&newDoc){restoreInspectorChoices(newDoc,choices);
+        const oldCells=new Map([...oldDoc.querySelectorAll(':scope > [data-cell-id]')].map(node=>[node.dataset.cellId,node]));const reused=new Set();
+        const placements=[...newDoc.querySelectorAll(':scope > [data-cell-id]')].map(node=>{const old=oldCells.get(node.dataset.cellId);
+          if(!old||reused.has(old)){node.classList.add('mr-stream-enter');return node;}const prior=old.cloneNode(true);prior.classList.remove('mr-stream-enter','mr-stream-update');
+          if(prior.outerHTML!==node.outerHTML){node.classList.add('mr-stream-update');return node;}reused.add(old);return old;});
+        const heldNext=held?placements.find(node=>node.dataset.cellId===held.id):null;
+        oldDoc.replaceChildren(...placements); root.dataset.doc=doc;
+        if(held&&heldNext)scrollBy(0,heldNext.getBoundingClientRect().top-held.top);const active=mutation&&placements.find(node=>node.dataset.cellId===String(mutation.cell_id||''));if(active)followPhase(active,mutation);return;}}
+    restoreInspectorChoices(next,choices); const heldNext=held?[...next.querySelectorAll('[data-cell-id]')].find(node=>node.dataset.cellId===held.id):null;
+    root.replaceChildren(next); root.dataset.doc=doc;
+    if(held&&heldNext)scrollBy(0,heldNext.getBoundingClientRect().top-held.top);
+  }
+  async function getSnapshot(doc=state.doc, version='', cursor='') { const query=new URLSearchParams({doc}); if(version!=='')query.set('version',String(version));if(cursor!=='')query.set('cursor',String(cursor));
+    const response=await fetch('/snapshot?'+query); if(!response.ok){const error=new Error('snapshot unavailable');error.status=response.status;throw error;} return response.json(); }
+  function requestContext(doc=state.doc) { return {doc,serial:++state.requestSerial,navigation:state.navigationSerial}; }
+  function requestIsCurrent(context) { return context.navigation===state.navigationSerial&&(context.serial==null||context.serial===state.requestSerial); }
+  function commitSnapshot(data, doc) { updateTabs(data.docs,doc); state.doc=doc; state.epoch=data.epoch; state.version=data.version;
+    state.cursor=Number(data.cursor||0);
+    document.body.dataset.doc=doc; document.body.dataset.epoch=data.epoch;
+    document.body.dataset.version=String(data.version);document.body.dataset.cursor=String(state.cursor);applyHealth(data.health); applyLifecycle(data.lifecycle); }
+  async function applySnapshot(data) { if(data.epoch===state.epoch&&data.version<state.version)return;const doc=data.doc||'';
+    if(data.epoch!==state.epoch)state.followedPhases.clear();state.incoming={mutation:data.mutation,version:data.version,epoch:data.epoch,cursor:data.cursor};patchNotebook(data.html,doc);state.incoming=null;commitSnapshot(data,doc); }
+  async function recoverSnapshot(error, context) { if(!requestIsCurrent(context))return;
+    if(error.status===410&&context.cursor!==''){try{const latest=await getSnapshot(context.doc);if(requestIsCurrent(context)){await applySnapshot(latest);return;}}catch(_latestError){}}
+    console.error('Mostly Right snapshot update failed',error);setStatus('Unavailable'); }
+  function queueSnapshot(doc=state.doc,version='',cursor='') { const numeric=version===''?'':Number(version),eventCursor=cursor===''?'':Number(cursor);
+    if(state.pendingSnapshots.some(item=>item.doc===doc&&item.version===numeric&&item.cursor===eventCursor))return state.applyQueue;
+    state.pendingSnapshots.push({doc,version:numeric,cursor:eventCursor,navigation:state.navigationSerial});if(state.streamWorker)return state.applyQueue;
+    state.streamWorker=true;state.applyQueue=state.applyQueue.then(async()=>{while(state.pendingSnapshots.length){const context=state.pendingSnapshots.shift();
+      if(!requestIsCurrent(context))continue;try{const data=await getSnapshot(context.doc,context.version,context.cursor);if(!requestIsCurrent(context))continue;await applySnapshot(data);}
+      catch(error){await recoverSnapshot(error,context);}}}).finally(()=>{state.streamWorker=false;if(state.pendingSnapshots.length)queueSnapshot();});return state.applyQueue; }
+  function queueCoordinate(data) { state.applyQueue=state.applyQueue.then(()=>{if(data.epoch===state.epoch&&data.version<state.version)return;
+    if(data.epoch!==state.epoch||data.version>state.version){
+    state.epoch=data.epoch;state.version=data.version;document.body.dataset.epoch=data.epoch;document.body.dataset.version=String(data.version);}
+    const visibleDocs=data.lifecycle&&data.lifecycle.handoff?data.docs:data.docs.filter(doc=>doc!=='table');
+    updateTabs(visibleDocs,state.doc);applyHealth(data.health);applyLifecycle(data.lifecycle);});return state.applyQueue; }
+  async function navigate(doc) { holdFollow();const navigation=++state.navigationSerial;const context=requestContext(doc);
+    state.pendingSnapshots=[];
+    try{const data=await getSnapshot(doc);if(!requestIsCurrent(context)||navigation!==state.navigationSerial)return;await applySnapshot(data);}
+    catch(error){await recoverSnapshot(error,context);} }
+  const explorerState={offset:0,limit:50,columns:[],allColumns:[],filters:[]};
+  function explorerValue(value){if(value==='true')return true;if(value==='false')return false;if(/^-?[0-9]+$/.test(value))return Number(value);if(/^-?[0-9]+\.[0-9]+$/.test(value))return Number(value);return value;}
+  async function loadExplorer(reset=false){const dialog=document.querySelector('[data-explorer]'),body=dialog.querySelector('[data-explorer-body]');if(reset)explorerState.offset=0;body.setAttribute('aria-busy','true');
+    const query=new URLSearchParams({offset:String(explorerState.offset),limit:String(explorerState.limit)});if(explorerState.columns.length)query.set('columns',explorerState.columns.join(','));if(explorerState.filters.length)query.set('filters',JSON.stringify(explorerState.filters));
+    try{const response=await fetch('/rows?'+query),data=await response.json();if(!response.ok)throw new Error();if(!explorerState.allColumns.length)explorerState.allColumns=[...data.columns];if(!explorerState.columns.length)explorerState.columns=[...data.columns];
+      const tools=document.createElement('div');tools.className='mr-explorer-tools';const columnLabel=document.createElement('label');columnLabel.textContent='Columns';const columnSelect=document.createElement('select');columnSelect.multiple=true;columnSelect.dataset.explorerColumns='';explorerState.allColumns.forEach(name=>{const option=document.createElement('option');option.value=name;option.textContent=name;option.selected=explorerState.columns.includes(name);columnSelect.append(option);});columnLabel.append(columnSelect);
+      const filterLabel=document.createElement('label');filterLabel.textContent='Filter column';const filterColumn=document.createElement('select');filterColumn.dataset.explorerFilterColumn='';explorerState.allColumns.forEach(name=>{const option=document.createElement('option');option.value=name;option.textContent=name;filterColumn.append(option);});filterLabel.append(filterColumn);
+      const opLabel=document.createElement('label');opLabel.textContent='Operator';const opSelect=document.createElement('select');opSelect.dataset.explorerFilterOp='';[['eq','='],['ne','not equal'],['lt','less than'],['le','at most'],['gt','greater than'],['ge','at least'],['is_null','is null'],['is_not_null','is not null']].forEach(([value,label])=>{const option=document.createElement('option');option.value=value;option.textContent=label;opSelect.append(option);});opLabel.append(opSelect);
+      const valueLabel=document.createElement('label');valueLabel.textContent='Value';const valueInput=document.createElement('input');valueInput.dataset.explorerFilterValue='';valueInput.type='text';valueInput.placeholder='bounded value';valueLabel.append(valueInput);const apply=document.createElement('button');apply.className='mr-button';apply.type='button';apply.dataset.explorerApply='';apply.textContent='Apply';
+      const previous=document.createElement('button');previous.className='mr-button';previous.type='button';previous.dataset.explorerPage='previous';previous.textContent='Previous';previous.disabled=data.offset===0;const next=document.createElement('button');next.className='mr-button';next.type='button';next.dataset.explorerPage='next';next.textContent='Next';next.disabled=!data.truncated;const status=document.createElement('span');status.className='mr-explorer-status';status.textContent=(data.rows.length?String(data.offset+1)+'-'+String(data.offset+data.rows.length):'0')+' of '+String(data.matched_row_count)+' matching rows';tools.append(columnLabel,filterLabel,opLabel,valueLabel,apply,previous,next,status);
+      const table=document.createElement('table'),head=document.createElement('thead'),hr=document.createElement('tr');data.columns.forEach(name=>{const th=document.createElement('th');th.scope='col';th.textContent=name;hr.append(th);});head.append(hr);table.append(head);const tbody=document.createElement('tbody');data.rows.forEach(row=>{const tr=document.createElement('tr');data.columns.forEach(name=>{const td=document.createElement('td'),value=row[name];td.textContent=value===null?'null':typeof value==='object'?JSON.stringify(value):String(value);tr.append(td);});tbody.append(tr);});table.append(tbody);const evidence=document.createElement('section');evidence.className='mr-explorer-evidence';evidence.setAttribute('aria-label','Verified explorer evidence');const evidenceTitle=document.createElement('h3');evidenceTitle.textContent='Verified profiles, findings & lineage';const evidenceBody=document.createElement('pre');evidenceBody.className='nb-json';evidenceBody.textContent=JSON.stringify(data.evidence,null,2);evidence.append(evidenceTitle,evidenceBody);body.replaceChildren(evidence,tools,table);
+    }catch(_error){body.textContent='Could not load the verified row window.';}finally{body.removeAttribute('aria-busy');}}
+  document.addEventListener('change', event => { const select=event.target.closest&&event.target.closest('[data-column-select]');if(select)activateInspector(select); });
+  const holdFollow=()=>{state.followHeld=true;const button=document.querySelector('[data-follow-agent]'),active=root.querySelector('[data-research-activity]');if(button)button.hidden=!active;};
+  if(window.addEventListener){window.addEventListener('wheel',holdFollow,{passive:true});window.addEventListener('touchstart',holdFollow,{passive:true});
+    window.addEventListener('keydown',event=>{if(['PageUp','PageDown','Home','End','ArrowUp','ArrowDown'].includes(event.key))holdFollow();});}
+  document.addEventListener('click', async event => {
+    const copy=event.target.closest('.nb-panel-btn');if(copy&&copy.textContent.trim()==='copy'){const panel=copy.closest('.nb-code');const pre=panel&&panel.querySelector('pre:not(.nb-lineno)');
+      if(pre){try{await navigator.clipboard.writeText(pre.textContent||'');const before=copy.textContent;copy.textContent='copied';toast('Code copied');setTimeout(()=>copy.textContent=before,1400);}catch(_error){toast('Could not copy code');}}return;}
+    const tab=event.target.closest('.mr-tab[data-doc]'); if(tab){await navigate(tab.dataset.doc);return;}
+    if(event.target.closest('[data-follow-agent]')){state.followHeld=false;event.target.closest('[data-follow-agent]').hidden=true;const active=root.querySelector('[data-research-activity]');if(active)active.scrollIntoView({block:'center',behavior:matchMedia('(prefers-reduced-motion: reduce)').matches?'auto':'smooth'});return;}
+    if(event.target.closest('[data-explore]')){const dialog=document.querySelector('[data-explorer]'),body=dialog.querySelector('[data-explorer-body]');body.textContent='Loading rows…';dialog.showModal();await loadExplorer(true);return;}
+    if(event.target.closest('[data-explorer-apply]')){const body=document.querySelector('[data-explorer-body]'),selected=[...body.querySelector('[data-explorer-columns]').selectedOptions].map(option=>option.value);if(!selected.length){toast('Select at least one column');return;}explorerState.columns=selected;const column=body.querySelector('[data-explorer-filter-column]').value,op=body.querySelector('[data-explorer-filter-op]').value,raw=body.querySelector('[data-explorer-filter-value]').value;explorerState.filters=raw||op==='is_null'||op==='is_not_null'?[{column,op,...(op==='is_null'||op==='is_not_null'?{}:{value:explorerValue(raw)})}]:[];await loadExplorer(true);return;}
+    const explorerPage=event.target.closest('[data-explorer-page]');if(explorerPage){explorerState.offset=Math.max(0,explorerState.offset+(explorerPage.dataset.explorerPage==='next'?explorerState.limit:-explorerState.limit));await loadExplorer();return;}
+    if(event.target.closest('[data-explorer-close]')){document.querySelector('[data-explorer]').close();return;}
+    if(event.target.closest('[data-files]')){const response=await fetch('/open-files',{method:'POST'});toast(response.ok?(state.handoff?'Revealed the table':'Opened the run location'):'Could not open the run location');return;}
+  });
+  setStatus('Connecting');
+  const source=new EventSource('/events'); source.onmessage=event=>{const data=JSON.parse(event.data);
+    if(data.visual_event){if(Number(data.cursor)<=state.cursor)return;queueSnapshot(state.doc,'',data.cursor);return;}
+    // Only 'stopped' is terminal. 'unavailable' is a steady state the page keeps serving research
+    // in -- an appended-to table notebook stays unavailable for as long as it is appended to --
+    // so it applies the health and then goes on fetching snapshots.
+    if(data.health.status==='stopped'){if(Number(data.cursor||0)>state.cursor){queueSnapshot(state.doc,'',data.cursor);return;}applyHealth(data.health);return;}
+    if(data.health.status==='unavailable')applyHealth(data.health);
+    if(Number(data.cursor||0)>state.cursor){queueSnapshot(state.doc,'',data.cursor);return;}
+    const handoff=!state.handoff&&data.lifecycle&&data.lifecycle.handoff;
+    if(!handoff&&state.doc&&Array.isArray(data.changed_docs)&&!data.changed_docs.includes(state.doc)){
+      queueCoordinate(data);return;}
+    if(data.epoch!==state.epoch||data.version>state.version||handoff)queueSnapshot(handoff?'table':state.doc,handoff?'':data.version);else applyLifecycle(data.lifecycle);};
+  source.onopen=async()=>{setStatus('Connecting');const context=requestContext(state.doc);try{const data=await getSnapshot(context.doc);if(requestIsCurrent(context)){if(data.epoch===state.epoch&&Number(data.version)===state.version&&Number(data.cursor||0)===state.cursor)commitSnapshot(data,context.doc);else await applySnapshot(data);}}
+    catch(error){await recoverSnapshot(error,context);}};
+  source.onerror=()=>{if(state.health!=='stopped'&&state.health!=='unavailable')setStatus('Reconnecting');};
+  window.setInterval(tickClock,1000);
+})();
+</script>
+""".strip()
+
+
+class ViewerExtraMissing(RuntimeError):
+    """Compatibility type retained for one release; the base renderer never raises it."""
+
+    def __init__(self, message: str = _INSTALL_HINT) -> None:
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class _JournalEntry:
+    version: int
+    documents: dict[str, bytes]
+    mutation: dict[str, object] | None = None
+    visual_cursor: int = 0
+
+
+def _parsed_notebook(raw: bytes) -> dict[str, object] | None:
+    try:
+        value = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError, RecursionError):
+        return None
+    if (
+        not isinstance(value, dict)
+        or value.get("nbformat") != 4
+        or not isinstance(value.get("metadata"), dict)
+        or not isinstance(value.get("cells"), list)
+    ):
+        return None
+    return value
+
+
+def _declared_activity(cell: object) -> str | None | bool:
+    """Return writing/executing, None for complete, or False for malformed metadata."""
+
+    if not isinstance(cell, dict) or not isinstance(cell.get("metadata"), dict):
+        return False
+    metadata = cell["metadata"]
+    mostlyright = metadata.get("mostlyright")
+    if mostlyright is None:
+        return None
+    if not isinstance(mostlyright, dict):
+        return False
+    activity = mostlyright.get("activity")
+    if activity is None:
+        return None
+    if (
+        not isinstance(activity, dict)
+        or set(activity) != {"schema_version", "state"}
+        or activity.get("schema_version") != _RESEARCH_ACTIVITY_SCHEMA
+        or activity.get("state") not in {"writing", "executing"}
+    ):
+        return False
+    return str(activity["state"])
+
+
+def _metadata_without_activity(cell: dict[str, object]) -> dict[str, object] | None:
+    metadata = cell.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    result = dict(metadata)
+    mostlyright = result.get("mostlyright")
+    if mostlyright is not None:
+        if not isinstance(mostlyright, dict):
+            return None
+        cleaned = dict(mostlyright)
+        cleaned.pop("activity", None)
+        if cleaned:
+            result["mostlyright"] = cleaned
+        else:
+            result.pop("mostlyright", None)
+    return result
+
+
+def _standard_outputs(value: object, *, cell_count: int | None) -> bool:
+    if not isinstance(value, list):
+        return False
+    fields = {
+        "stream": {"output_type", "name", "text"},
+        "display_data": {"output_type", "data", "metadata"},
+        "execute_result": {"output_type", "data", "metadata", "execution_count"},
+        "error": {"output_type", "ename", "evalue", "traceback"},
+    }
+    for output in value:
+        if not isinstance(output, dict):
+            return False
+        output_type = output.get("output_type")
+        if not isinstance(output_type, str) or set(output) != fields.get(output_type):
+            return False
+        if output_type == "stream":
+            text = output.get("text")
+            if output.get("name") not in {"stdout", "stderr"} or not (
+                isinstance(text, str)
+                or (isinstance(text, list) and all(isinstance(part, str) for part in text))
+            ):
+                return False
+        elif output_type in {"display_data", "execute_result"}:
+            if not isinstance(output.get("data"), dict) or not isinstance(
+                output.get("metadata"), dict
+            ):
+                return False
+            if output_type == "execute_result" and (
+                isinstance(output.get("execution_count"), bool)
+                or not isinstance(output.get("execution_count"), int)
+                or output.get("execution_count", -1) < 0
+                or (cell_count is not None and output.get("execution_count") != cell_count)
+            ):
+                return False
+        elif not (
+            isinstance(output.get("ename"), str)
+            and isinstance(output.get("evalue"), str)
+            and isinstance(output.get("traceback"), list)
+            and all(isinstance(line, str) for line in output["traceback"])
+        ):
+            return False
+    return True
+
+
+def _helper_cell_shape(cell: object, state: str | None) -> bool:
+    """Recognize only cells emitted by the strict --cell-file helper contract."""
+
+    if not isinstance(cell, dict):
+        return False
+    cell_id = cell.get("id")
+    cell_type = cell.get("cell_type")
+    if (
+        not isinstance(cell_id, str)
+        or _RESEARCH_CELL_ID.fullmatch(cell_id) is None
+        or cell_type not in {"markdown", "code"}
+        or not isinstance(cell.get("source"), str)
+        or _declared_activity(cell) != state
+    ):
+        return False
+    expected = {"cell_type", "id", "metadata", "source"}
+    if cell_type == "code":
+        expected |= {"execution_count", "outputs"}
+        count = cell.get("execution_count")
+        outputs = cell.get("outputs")
+        if not _standard_outputs(outputs, cell_count=count if state is None else None):
+            return False
+        if state is None:
+            if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+                return False
+        elif count is not None or (state == "writing" and outputs):
+            return False
+        if state == "executing" and cell_type != "code":
+            return False
+    elif state == "executing":
+        return False
+    return set(cell) == expected
+
+
+def _research_mutation(
+    before_raw: bytes,
+    after_raw: bytes,
+    *,
+    from_version: int,
+    version: int,
+) -> dict[str, object] | None:
+    """Prove one exact trailing-cell transition from two valid notebook documents."""
+
+    before = _parsed_notebook(before_raw)
+    after = _parsed_notebook(after_raw)
+    if before is None or after is None or before["metadata"] != after["metadata"]:
+        return None
+    old_cells = before["cells"]
+    new_cells = after["cells"]
+    assert isinstance(old_cells, list) and isinstance(new_cells, list)
+    phase_start = False
+    if len(new_cells) == len(old_cells) + 1 and old_cells == new_cells[:-1]:
+        old_cell = None
+        new_cell = new_cells[-1]
+        new_state = _declared_activity(new_cell)
+        if new_state != "writing" or not _helper_cell_shape(new_cell, "writing"):
+            return None
+        kind = "source"
+        phase = "writing"
+        phase_start = True
+    elif len(new_cells) == len(old_cells) and new_cells and old_cells[:-1] == new_cells[:-1]:
+        old_cell = old_cells[-1]
+        new_cell = new_cells[-1]
+        if not isinstance(old_cell, dict) or not isinstance(new_cell, dict):
+            return None
+        if old_cell.get("id") != new_cell.get("id") or old_cell.get("cell_type") != new_cell.get(
+            "cell_type"
+        ):
+            return None
+        old_state = _declared_activity(old_cell)
+        new_state = _declared_activity(new_cell)
+        if old_state not in {"writing", "executing"} or new_state is False:
+            return None
+        if not _helper_cell_shape(old_cell, str(old_state)) or not _helper_cell_shape(
+            new_cell, None if new_state is None else str(new_state)
+        ):
+            return None
+        if _metadata_without_activity(old_cell) != _metadata_without_activity(new_cell):
+            return None
+        old_source = old_cell["source"]
+        new_source = new_cell["source"]
+        assert isinstance(old_source, str) and isinstance(new_source, str)
+        if old_state == "writing" and new_state == "writing":
+            if old_source == new_source or not new_source.startswith(old_source):
+                return None
+            if old_cell.get("outputs") != new_cell.get("outputs"):
+                return None
+            kind, phase = "source", "writing"
+        elif old_state == "writing" and new_state == "executing":
+            if old_cell.get("cell_type") != "code" or old_source != new_source:
+                return None
+            kind, phase, phase_start = "state", "executing", True
+        elif old_state == "executing" and new_state == "executing":
+            if old_source != new_source or old_cell.get("outputs") == new_cell.get("outputs"):
+                return None
+            kind, phase = "output", "executing"
+        elif new_state is None and (
+            old_state == "executing"
+            or (old_state == "writing" and old_cell.get("cell_type") == "markdown")
+        ):
+            if old_source != new_source:
+                return None
+            kind, phase, phase_start = "state", "complete", True
+        else:
+            return None
+    else:
+        return None
+    assert isinstance(new_cell, dict)
+    return {
+        "from_version": from_version,
+        "version": version,
+        "doc": "research",
+        "cell_id": new_cell["id"],
+        "kind": kind,
+        "phase": phase,
+        "phase_start": phase_start,
+    }
+
+
+def _only_research_document_changed(before: dict[str, bytes], after: dict[str, bytes]) -> bool:
+    """Keep document-set and table changes out of the cell-mutation channel."""
+
+    if set(before) != set(after) or before.get("research") == after.get("research"):
+        return False
+    return all(before[name] == after[name] for name in before if name != "research")
+
+
+@dataclass(frozen=True)
+class ViewerTarget:
+    """One explicit viewer layout selected by the caller."""
+
+    mode: str
+    selected_path: Path
+    run_dir: Path
+    research_path: Path
+    table_path: Path
+    files_dir: Path
+    # Whether the caller named the research folder. Run-directory mode watches one either way, but
+    # only a named one was asked for -- and a command this viewer prints for the reader to run has
+    # to be the command they ran, not one carrying a flag they never passed.
+    explicit_research: bool = False
+
+
+def viewer_target(
+    *,
+    workspace: Path | None = None,
+    run_dir: Path | None = None,
+    research_dir: Path | None = None,
+) -> ViewerTarget:
+    """Return the exact notebook paths for one and only one explicit target mode."""
+
+    if (workspace is None) == (run_dir is None):
+        raise ValueError("viewer needs exactly one of workspace or run_dir")
+    selected = Path(os.path.abspath(os.fspath(workspace if workspace is not None else run_dir)))
+    explicit_research = (
+        Path(os.path.abspath(os.fspath(research_dir))) if research_dir is not None else None
+    )
+    if workspace is not None:
+        research_root = explicit_research or selected
+        return ViewerTarget(
+            mode="workspace",
+            selected_path=selected,
+            run_dir=selected / "result",
+            research_path=research_root / "research.ipynb",
+            table_path=selected / "result" / _SIDECAR_NAME,
+            files_dir=research_root,
+            explicit_research=explicit_research is not None,
+        )
+    research_root = explicit_research or selected.parent
+    return ViewerTarget(
+        mode="run-dir",
+        selected_path=selected,
+        run_dir=selected,
+        research_path=research_root / "research.ipynb",
+        table_path=selected / _SIDECAR_NAME,
+        files_dir=research_root,
+        explicit_research=explicit_research is not None,
+    )
+
+
+def prepare_viewer_target(
+    *,
+    workspace: Path | None = None,
+    run_dir: Path | None = None,
+    research_dir: Path | None = None,
+) -> ViewerTarget:
+    """Validate one CLI target and install its initial research notebook before binding.
+
+    Workspace mode deliberately has no implicit research location.  A future workspace must stay
+    absent so ``mr-data init`` can install it atomically, while an existing target must replay as a
+    real Harness workspace.  Research always lives in an explicit, already-existing real folder.
+
+    A notebook is seeded only where the caller named the folder to seed.  Run-directory mode still
+    watches ``research.ipynb`` beside the selected run when ``--research-dir`` is omitted, but that
+    folder was never named -- it is usually a home or working directory the caller was not asking
+    the viewer to write into -- so nothing is created there and the page waits.
+    """
+
+    target = viewer_target(workspace=workspace, run_dir=run_dir, research_dir=research_dir)
+    if workspace is not None:
+        if research_dir is None:
+            raise ViewerError(
+                "VIEWER_RESEARCH_DIR_REQUIRED",
+                "--workspace requires an explicit --research-dir that already exists",
+            )
+        _validate_workspace_target(target.selected_path)
+    else:
+        _validate_run_target(target.selected_path)
+    _require_real_directory(target.files_dir, label="research directory")
+    if research_dir is not None:
+        _seed_research_notebook(target.files_dir)
+    return target
+
+
+def _validate_workspace_target(workspace: Path) -> None:
+    """Accept an absent future target or a descriptor-validated Harness workspace."""
+
+    try:
+        info = os.lstat(workspace)
+    except FileNotFoundError:
+        # Still reject a missing target reached through a symlinked ancestor.
+        try:
+            _canonical_viewer_root(workspace)
+        except ValueError as exc:
+            raise ViewerError(
+                "VIEWER_WORKSPACE_INVALID", f"workspace path must use real directories: {workspace}"
+            ) from exc
+        return
+    except OSError as exc:
+        raise ViewerError(
+            "VIEWER_WORKSPACE_UNAVAILABLE", f"workspace is unavailable: {workspace}"
+        ) from exc
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise ViewerError(
+            "VIEWER_WORKSPACE_INVALID",
+            f"an existing --workspace must be a real Harness workspace: {workspace}",
+        )
+    try:
+        _canonical_viewer_root(workspace)
+    except ValueError as exc:
+        raise ViewerError(
+            "VIEWER_WORKSPACE_INVALID", f"workspace path must use real directories: {workspace}"
+        ) from exc
+    try:
+        validate_workspace_structure(workspace)
+    except Exception as exc:
+        raise ViewerError(
+            "VIEWER_WORKSPACE_INVALID",
+            f"an existing --workspace must be a valid Harness workspace: {workspace}",
+        ) from exc
+
+
+def _validate_run_target(run_dir: Path) -> None:
+    """Accept an absent future target or an existing descriptor-verified Harness Build."""
+
+    try:
+        info = os.lstat(run_dir)
+    except FileNotFoundError:
+        try:
+            _canonical_viewer_root(run_dir)
+        except ValueError as exc:
+            raise ViewerError(
+                "VIEWER_RUN_DIR_INVALID", f"run path must use real directories: {run_dir}"
+            ) from exc
+        return
+    except OSError as exc:
+        raise ViewerError(
+            "VIEWER_RUN_DIR_UNAVAILABLE", f"run path is unavailable: {run_dir}"
+        ) from exc
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise ViewerError(
+            "VIEWER_RUN_DIR_INVALID",
+            f"an existing --run-dir must be a verified Harness Build: {run_dir}",
+        )
+    try:
+        _canonical_viewer_root(run_dir)
+        verify_candidate(run_dir)
+    except Exception as exc:
+        raise ViewerError(
+            "VIEWER_RUN_DIR_INVALID",
+            f"an existing --run-dir must be a verified Harness Build: {run_dir}",
+        ) from exc
+
+
+def _require_real_directory(path: Path, *, label: str) -> None:
+    anchor: _PinnedPath | None = None
+    try:
+        canonical, _anchors = _canonical_viewer_root(path)
+        anchor = _PinnedPath(canonical)
+        descriptor = anchor.open_directory()
+    except (OSError, ValueError) as exc:
+        raise ViewerError(
+            "VIEWER_RESEARCH_DIR_INVALID", f"{label} must use real directories: {path}"
+        ) from exc
+    try:
+        if not stat.S_ISDIR(os.fstat(descriptor).st_mode):
+            raise ViewerError(
+                "VIEWER_RESEARCH_DIR_INVALID", f"{label} must be a real directory: {path}"
+            )
+    finally:
+        os.close(descriptor)
+        if anchor is not None:
+            anchor.close()
+
+
+def _seed_research_notebook(research_dir: Path) -> None:
+    """Exclusively and atomically install a minimal claim-free notebook when absent."""
+
+    notebook = {
+        "cells": [
+            {
+                "cell_type": "markdown",
+                "id": "research-ready",
+                # Marked so the bundled helper can drop it the first time a real section is
+                # written. Without the marker it survives every update and the delivered notebook
+                # opens on an empty placeholder claiming the work has not started.
+                "metadata": {"mostlyright": {"seed": True}},
+                "source": (
+                    "# Research workspace\n\n"
+                    "Ready for research notes. Record the question, selected sources, and "
+                    "supporting evidence here as the work proceeds."
+                ),
+            }
+        ],
+        "metadata": {"mostlyright": {"phase": "ready_for_research"}},
+        "nbformat": 4,
+        "nbformat_minor": 5,
+    }
+    raw = (json.dumps(notebook, ensure_ascii=False, indent=1) + "\n").encode("utf-8")
+    try:
+        anchor = _PinnedPath(research_dir)
+        directory_fd = anchor.open_directory()
+    except (OSError, ValueError) as exc:
+        raise ViewerError(
+            "VIEWER_RESEARCH_DIR_INVALID",
+            f"research directory must use real directories: {research_dir}",
+        ) from exc
+    try:
+        anchor.validate()
+        try:
+            existing = os.stat("research.ipynb", dir_fd=directory_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            existing = None
+        if existing is not None:
+            if not _is_regular_single_link(existing):
+                raise ViewerError(
+                    "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                    "existing research.ipynb must be a regular single-link file",
+                )
+            _validate_existing_research_notebook(directory_fd, existing)
+            return
+        installed = _install_seeded_notebook(directory_fd, raw, research_dir)
+        _validate_existing_research_notebook(directory_fd, installed)
+    finally:
+        os.close(directory_fd)
+        anchor.close()
+
+
+def _install_seeded_notebook(directory_fd: int, raw: bytes, research_dir: Path) -> os.stat_result:
+    """Write and atomically install the seed, reporting a refused write as a typed refusal.
+
+    ENOSPC on the volume, a read-only mount, or a filesystem with no hard links -- exFAT and some
+    SMB shares -- all surface here, and a raw OSError carries no code for the remediation map to
+    answer through.
+    """
+
+    temporary = ""
+    descriptor = -1
+    try:
+        for _attempt in range(100):
+            temporary = f".research.ipynb.{secrets.token_hex(12)}"
+            try:
+                descriptor = os.open(
+                    temporary,
+                    os.O_WRONLY
+                    | os.O_CREAT
+                    | os.O_EXCL
+                    | os.O_NOFOLLOW
+                    | getattr(os, "O_CLOEXEC", 0),
+                    0o600,
+                    dir_fd=directory_fd,
+                )
+                break
+            except FileExistsError:
+                continue
+        else:  # pragma: no cover - cryptographically improbable without hostile interference
+            raise ViewerError(
+                "VIEWER_RESEARCH_SEED_FAILED",
+                "could not allocate a research notebook temporary file",
+            )
+        offset = 0
+        while offset < len(raw):
+            written = os.write(descriptor, raw[offset:])
+            if written < 1:
+                raise OSError("research notebook write did not make progress")
+            offset += written
+        os.fsync(descriptor)
+        os.fchmod(descriptor, 0o644)
+        os.fsync(descriptor)
+        os.close(descriptor)
+        descriptor = -1
+        try:
+            # Linking a complete temporary file is an atomic no-replace installation.  A racing
+            # writer wins without ever being overwritten.
+            os.link(
+                temporary,
+                "research.ipynb",
+                src_dir_fd=directory_fd,
+                dst_dir_fd=directory_fd,
+                follow_symlinks=False,
+            )
+        except FileExistsError:
+            pass
+        os.unlink(temporary, dir_fd=directory_fd)
+        temporary = ""
+        os.fsync(directory_fd)
+        installed = os.stat("research.ipynb", dir_fd=directory_fd, follow_symlinks=False)
+        if not _is_regular_single_link(installed):
+            raise ViewerError(
+                "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                "research.ipynb was replaced during viewer startup",
+            )
+        return installed
+    except ViewerError:
+        raise
+    except OSError as exc:
+        raise ViewerError(
+            "VIEWER_RESEARCH_SEED_FAILED",
+            f"research.ipynb could not be installed in {research_dir}: {exc}",
+        ) from exc
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        if temporary:
+            try:
+                os.unlink(temporary, dir_fd=directory_fd)
+            except FileNotFoundError:
+                pass
+
+
+def _validate_existing_research_notebook(directory_fd: int, expected: os.stat_result) -> None:
+    """Read and render-check an existing research notebook through its pinned directory."""
+
+    if expected.st_size > _MAX_NOTEBOOK_BYTES:
+        raise ViewerError(
+            "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+            f"existing research.ipynb exceeds the {_MAX_NOTEBOOK_BYTES}-byte viewer limit",
+        )
+    descriptor = -1
+    try:
+        descriptor = os.open(
+            "research.ipynb",
+            os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0),
+            dir_fd=directory_fd,
+        )
+        opened = os.fstat(descriptor)
+        if not _is_regular_single_link(opened) or _stat_signature(opened) != _stat_signature(
+            expected
+        ):
+            raise ViewerError(
+                "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                "existing research.ipynb changed during viewer startup",
+            )
+        chunks: list[bytes] = []
+        remaining = _MAX_NOTEBOOK_BYTES + 1
+        while remaining:
+            chunk = os.read(descriptor, min(_READ_CHUNK_BYTES, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        raw = b"".join(chunks)
+        if len(raw) > _MAX_NOTEBOOK_BYTES or len(raw) != opened.st_size:
+            raise ViewerError(
+                "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                "existing research.ipynb changed or exceeds the viewer limit",
+            )
+        try:
+            decoded = raw.decode("utf-8")
+            parsed = json.loads(decoded)
+            if not isinstance(parsed, dict):
+                raise ValueError("notebook root must be an object")
+            render_notebook(parsed, mode="embed", filename="research.ipynb")
+        except (
+            UnicodeDecodeError,
+            ValueError,
+            TypeError,
+            KeyError,
+            OverflowError,
+            RecursionError,
+        ) as exc:
+            raise ViewerError(
+                "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                "existing research.ipynb is not a valid renderable UTF-8 JSON notebook",
+            ) from exc
+        current = os.fstat(descriptor)
+        named = os.stat("research.ipynb", dir_fd=directory_fd, follow_symlinks=False)
+        if _stat_signature(current) != _stat_signature(opened) or _stat_signature(
+            named
+        ) != _stat_signature(opened):
+            raise ViewerError(
+                "VIEWER_RESEARCH_NOTEBOOK_INVALID",
+                "existing research.ipynb changed during viewer startup",
+            )
+    except ViewerError:
+        raise
+    except OSError as exc:
+        raise ViewerError(
+            "VIEWER_RESEARCH_NOTEBOOK_UNAVAILABLE",
+            "existing research.ipynb could not be read safely",
+        ) from exc
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+
+def _stat_signature(info: os.stat_result) -> _FileSignature:
+    return (
+        info.st_dev,
+        info.st_ino,
+        info.st_mode,
+        info.st_nlink,
+        info.st_size,
+        info.st_mtime_ns,
+        info.st_ctime_ns,
+    )
+
+
+def _is_regular_single_link(info: os.stat_result) -> bool:
+    return stat.S_ISREG(info.st_mode) and info.st_nlink == 1
+
+
+def _directory_identity(info: os.stat_result) -> _DirectoryIdentity:
+    return (info.st_dev, info.st_ino, info.st_mode)
+
+
+def _canonical_viewer_root(
+    target: Path,
+) -> tuple[Path, tuple[tuple[Path, _DirectoryIdentity], ...]]:
+    """Canonicalize one selected root and bind every ancestor that already exists."""
+
+    absolute = Path(os.path.abspath(os.fspath(target)))
+    canonical = absolute.resolve(strict=False)
+    if canonical != absolute:
+        raise ValueError("viewer root must not contain symlinked ancestors")
+    chain: list[tuple[Path, _DirectoryIdentity]] = []
+    current = Path(canonical.anchor)
+    components = canonical.parts[1:]
+    for component in (None, *components):
+        if component is not None:
+            current /= component
+        try:
+            info = os.lstat(current)
+        except FileNotFoundError:
+            break
+        except OSError as exc:
+            raise ValueError("viewer root ancestors are unavailable") from exc
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+            raise ValueError("viewer root ancestors must be real directories")
+        chain.append((current, _directory_identity(info)))
+    return canonical, tuple(chain)
+
+
+class _PinnedPath:
+    """Walk absolute paths from a retained filesystem-root descriptor without following links."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(os.path.abspath(os.fspath(path)))
+        self._root_fd = os.open(self.path.anchor, _DIRECTORY_FLAGS)
+        root = os.fstat(self._root_fd)
+        if not stat.S_ISDIR(root.st_mode):
+            self.close()
+            raise ValueError("viewer filesystem anchor is not a directory")
+        self._expected: dict[tuple[str, ...], _DirectoryIdentity] = {(): _directory_identity(root)}
+        descriptor = os.dup(self._root_fd)
+        walked: list[str] = []
+        try:
+            for component in self.path.parts[1:]:
+                try:
+                    child = os.open(component, _DIRECTORY_FLAGS, dir_fd=descriptor)
+                except FileNotFoundError:
+                    break
+                opened = os.fstat(child)
+                if not stat.S_ISDIR(opened.st_mode):
+                    os.close(child)
+                    raise ValueError("viewer path component is not a directory")
+                os.close(descriptor)
+                descriptor = child
+                walked.append(component)
+                self._expected[tuple(walked)] = _directory_identity(opened)
+        except BaseException:
+            self.close()
+            raise
+        finally:
+            os.close(descriptor)
+
+    def close(self) -> None:
+        if getattr(self, "_root_fd", -1) >= 0:
+            os.close(self._root_fd)
+            self._root_fd = -1
+
+    def open_directory(self, path: Path | None = None) -> int:
+        target = self.path if path is None else Path(os.path.abspath(os.fspath(path)))
+        try:
+            relative = target.relative_to(Path(target.anchor))
+        except ValueError as exc:
+            raise OSError(errno.EINVAL, "viewer path has a different filesystem anchor") from exc
+        descriptor = os.dup(self._root_fd)
+        walked: list[str] = []
+        try:
+            if _directory_identity(os.fstat(descriptor)) != self._expected[()]:
+                raise OSError(errno.ESTALE, "viewer filesystem anchor changed")
+            for component in relative.parts:
+                child = os.open(component, _DIRECTORY_FLAGS, dir_fd=descriptor)
+                opened = os.fstat(child)
+                if not stat.S_ISDIR(opened.st_mode):
+                    os.close(child)
+                    raise OSError(errno.ENOTDIR, "viewer path component is not a directory")
+                os.close(descriptor)
+                descriptor = child
+                walked.append(component)
+                expected = self._expected.get(tuple(walked))
+                if expected is not None and _directory_identity(opened) != expected:
+                    raise OSError(errno.ESTALE, "viewer path ancestor changed identity")
+            return descriptor
+        except BaseException:
+            os.close(descriptor)
+            raise
+
+    def validate(self) -> None:
+        descriptor = self.open_directory()
+        os.close(descriptor)
+
+    def open_parent(self, path: Path) -> tuple[int, str]:
+        absolute = Path(os.path.abspath(os.fspath(path)))
+        if not absolute.name:
+            raise OSError(errno.EINVAL, "viewer member has no name")
+        return self.open_directory(absolute.parent), absolute.name
+
+
+@dataclass
+class _RunRecoveryLease:
+    """A descriptor-pinned run and its exact exclusive sidecar-writer interval."""
+
+    run_handle: _CandidateRunHandle
+    lock_fd: int
+    lock_identity: _DirectoryIdentity
+
+    @property
+    def run_fd(self) -> int:
+        return self.run_handle.run_fd
+
+    def validate(self) -> None:
+        """Require both selected path and named lock to remain the objects we acquired."""
+
+        _validate_candidate_run_handle(self.run_handle)
+        opened = os.fstat(self.lock_fd)
+        if not _is_regular_single_link(opened) or _entry_identity(opened) != self.lock_identity:
+            raise OSError(errno.ESTALE, "run build activity lock changed identity")
+        named = os.stat(
+            RUN_BUILD_ACTIVITY_LOCK,
+            dir_fd=self.run_fd,
+            follow_symlinks=False,
+        )
+        if not _is_regular_single_link(named) or _entry_identity(named) != self.lock_identity:
+            raise OSError(errno.ESTALE, "run build activity lock path changed identity")
+        _validate_candidate_run_handle(self.run_handle)
+
+    def manifest_observation(self) -> _FileSignature | None:
+        """Read the exact pinned run's manifest identity for the one-attempt latch."""
+
+        candidate_fd = -1
+        try:
+            candidate_fd = os.open("candidate", _DIRECTORY_FLAGS, dir_fd=self.run_fd)
+            manifest = os.stat("manifest.json", dir_fd=candidate_fd, follow_symlinks=False)
+        except OSError:
+            return None
+        finally:
+            if candidate_fd >= 0:
+                os.close(candidate_fd)
+        if not _is_regular_single_link(manifest):
+            return None
+        return _stat_signature(manifest)
+
+    def close(self) -> None:
+        """Release exclusion only after every descriptor-relative recovery step is finished."""
+
+        if fcntl is None:
+            raise ViewerError(
+                "VIEWER_PLATFORM_UNSUPPORTED",
+                "secure viewer locking is unavailable on this platform",
+            )
+        try:
+            fcntl.flock(self.lock_fd, fcntl.LOCK_UN)
+        finally:
+            try:
+                os.close(self.lock_fd)
+            finally:
+                self.run_handle.close()
+
+
+def _sidecar_lifecycle_grows_monotonically(
+    previous: Mapping[str, object], lifecycle: Mapping[str, object]
+) -> bool:
+    """Allow one same-feed sidecar transition and make its first outcome sticky."""
+
+    before = previous.get("sidecar_state")
+    after = lifecycle.get("sidecar_state")
+    if before is None and after is None:
+        # The visual projection narrates no sidecar outcome, so there is no first outcome here to
+        # make sticky, and the caller has already established that this is structurally the same
+        # attempt. Falling through to the refusal below instead froze a completed visual lifecycle
+        # forever: the one same-attempt change the caller exists to allow -- independent dataset
+        # admission turning handoff on -- was refused along with everything else, so a Dataset that
+        # became admissible after its run had narrated completion never reached the page.
+        return True
+    if before == "absent":
+        return after in {"absent", "invalid", "started"}
+    if before == "invalid":
+        return after == "invalid"
+    if before == "started":
+        return after in {"started", "ready", "failed"}
+    if before in {"ready", "failed"}:
+        # Ready and failed are both terminal outcomes for this attempt/path. Table admission may
+        # still change handoff after ready, but the narrated outcome itself is immutable.
+        return after == before
+    return False
+
+
+def _visual_event_mutation(event: VisualRunEvent, before: ReducedRun) -> dict[str, object] | None:
+    """Translate one durable visual event into browser mutation intent.
+
+    The event sequence and object version are authoritative.  Notebook diffs remain a defensive
+    DOM-equivalence check, never the source of identity, ordering, follow behavior, or narration.
+    """
+
+    if not event.event_type.startswith("cell."):
+        return None
+    kind_by_event = {
+        "cell.created": "source",
+        "cell.source_extended": "source",
+        "cell.source_revised": "revision",
+        "cell.moved": "move",
+        "cell.execution_started": "state",
+        "cell.output_appended": "output",
+        "cell.output_replaced": "output",
+        "cell.completed": "state",
+        "cell.failed": "state",
+    }
+    phase_by_event = {
+        "cell.created": "writing",
+        "cell.source_extended": "writing",
+        "cell.source_revised": "writing",
+        "cell.moved": "writing",
+        "cell.execution_started": "executing",
+        "cell.output_appended": "executing",
+        "cell.output_replaced": "executing",
+        "cell.completed": "complete",
+        "cell.failed": "failed",
+    }
+    kind = kind_by_event.get(event.event_type)
+    if kind is None:
+        return None
+    prior = before.cells.get(event.object_id)
+    result: dict[str, object] = {
+        "source": "visual-run",
+        "doc": "research",
+        "cursor": event.sequence,
+        "from_cursor": before.cursor,
+        "event_type": event.event_type,
+        "cell_id": event.object_id,
+        "object_version": event.object_version,
+        "previous_object_version": event.previous_object_version,
+        "kind": kind,
+        "phase": phase_by_event[event.event_type],
+        "announcement": f"Research cell {phase_by_event[event.event_type]}",
+    }
+    if prior is not None:
+        result["previous_status"] = prior.status
+    if event.event_type == "cell.moved":
+        result["after_cell_id"] = str(event.payload["after_cell_id"])
+    if event.event_type.startswith("cell.output_"):
+        result["output_index"] = int(event.payload["output_index"])
+    return result
+
+
+def _visual_lifecycle(
+    reduced: ReducedRun,
+    *,
+    table_ready: bool,
+    admitted_candidate_digest: str | None,
+) -> dict[str, object]:
+    """Project browser lifecycle only from authoritative reduced protocol objects."""
+
+    handoff = bool(
+        table_ready
+        and reduced.table_ready
+        and admitted_candidate_digest is not None
+        and admitted_candidate_digest == reduced.candidate_digest
+    )
+    lines: list[dict[str, object]] = []
+    last_stage = "Research"
+    for item in reduced.objects.values():
+        if item.kind in {"cell", "run", "phase"}:
+            continue
+        status = (
+            "failed"
+            if item.status in {"failed", "rejected"}
+            else "done"
+            if item.status == "complete"
+            else "running"
+        )
+        if item.kind == "source":
+            label = "Source evidence"
+            detail = str(item.payload.get("observation_kind", item.payload.get("source_kind", "")))
+        elif item.kind == "transformation":
+            operation = str(item.payload.get("operation", "transformation"))
+            label = f"{operation.title()} transformation"
+            detail = f"{item.stage} · {item.payload.get('row_count', 'pending')} rows"
+            status = "done" if item.version >= 2 and item.status != "failed" else status
+        elif item.kind == "quality":
+            label = "Quality evidence"
+            detail = (
+                f"{item.payload.get('checks_passed', 0)}/"
+                f"{item.payload.get('checks_total', 0)} checks"
+            )
+        elif item.kind == "table":
+            label = "Table written"
+            detail = (
+                f"{item.payload.get('row_count', 0)} rows · "
+                f"{item.payload.get('column_count', 0)} columns"
+            )
+        elif item.kind == "build":
+            digest = str(item.payload.get("candidate_digest", ""))
+            lines.append(
+                {
+                    "key": "build:sealed",
+                    "label": "Build sealed",
+                    "detail": digest[:16],
+                    "status": "done",
+                }
+            )
+            label = "Build verified"
+            detail = digest[:16]
+            status = "done" if item.version >= 2 and item.status == "complete" else "running"
+        elif item.kind == "notebook":
+            label = f"{item.object_id.partition(':')[2].title()} notebook"
+            detail = str(item.payload.get("notebook_digest", ""))[:16]
+        else:
+            continue
+        last_stage = item.stage.replace("-", " ").title()
+        lines.append(
+            {
+                "key": item.object_id,
+                "label": label,
+                "detail": detail,
+                "status": status,
+            }
+        )
+        if item.kind == "transformation" and item.version >= 3:
+            lines.append(
+                {
+                    "key": f"{item.object_id}:evidence",
+                    "label": "Stage evidence",
+                    "detail": f"{item.payload.get('operation', 'operation')} · verified observation",
+                    "status": "done",
+                }
+            )
+    status = (
+        "failed"
+        if reduced.lifecycle in {"failed", "interrupted"}
+        else "completed"
+        if reduced.lifecycle == "completed"
+        else "running"
+    )
+    done = sum(line["status"] == "done" for line in lines)
+    progress = 100 if status == "completed" else int(96 * done / max(len(lines) + 1, 1))
+    if reduced.active_object_id is not None:
+        active = reduced.objects.get(reduced.active_object_id)
+        if active is not None and active.kind not in {"cell", "run", "phase"}:
+            last_stage = active.stage.replace("-", " ").title()
+    if not lines and status == "running":
+        status = "idle"
+    return {
+        "status": status,
+        "phase": "Table ready" if handoff else last_stage,
+        "progress": progress,
+        "lines": lines,
+        "handoff": handoff,
+        "sealed": reduced.candidate_digest is not None,
+        "legacy_handoff_allowed": False,
+        "started_at": None,
+        "ended_at": None,
+        "terminal": (
+            {
+                "event": reduced.lifecycle,
+                "title": reduced.terminal_error.code,
+                "detail": reduced.terminal_error.message,
+            }
+            if reduced.terminal_error is not None
+            else None
+        ),
+    }
+
+
+class _ViewerState:
+    """Atomic notebook snapshots and a bounded journal of real file changes."""
+
+    def __init__(self, target: ViewerTarget | Path) -> None:
+        if isinstance(target, Path):
+            target = viewer_target(run_dir=target)
+        canonical, _selected_anchors = _canonical_viewer_root(target.selected_path)
+        canonical_research, _research_anchors = _canonical_viewer_root(target.research_path.parent)
+        # Canonicalizing names the research folder whether or not the caller did, so the caller's
+        # answer is carried across rather than re-derived from the rebuilt paths.
+        target = replace(
+            viewer_target(
+                workspace=canonical if target.mode == "workspace" else None,
+                run_dir=canonical if target.mode == "run-dir" else None,
+                research_dir=canonical_research,
+            ),
+            explicit_research=target.explicit_research,
+        )
+        self.target = target
+        self.run_dir = target.run_dir
+        self.research_path = target.research_path
+        self.table_path = target.table_path
+        self.files_dir = target.files_dir
+        self._selected_path = _PinnedPath(target.selected_path)
+        self._research_path = _PinnedPath(target.research_path.parent)
+        self._visual_transport: VisualRunTransport | None = None
+        self._visual_refresh_lock = threading.Lock()
+        self._visual_present = False
+        self._visual_error: VisualRunError | None = None
+        self._visual_cursor = 0
+        self._visual_state = ReducedRun()
+        try:
+            self._research_fd = self._research_path.open_directory()
+        except BaseException:
+            self._selected_path.close()
+            self._research_path.close()
+            raise
+        self._visual_present = self._visual_boundary_exists()
+        if self._visual_present:
+            try:
+                self._visual_transport = discover_visual_transport(
+                    self.research_path.parent, directory_fd=self._research_fd
+                )
+            except VisualRunError as exc:
+                self._visual_error = exc
+        if self._visual_transport is not None:
+            self._refresh_visual_notebook()
+        self.epoch = secrets.token_urlsafe(18)
+        self._lock = threading.Lock()
+        self._condition = threading.Condition(self._lock)
+        self._health_status = "running"
+        self._health_code: str | None = None
+        if self._visual_error is not None:
+            self._health_status = "stopped"
+            self._health_code = HEALTH_WATCHER_FAILED
+        self._health_build_present = False
+        self._health_path_exists = False
+        self._sidecar_manifest_observation: _FileSignature | None = None
+        self._sidecar_candidate_identity: str | None = None
+        self._admitted_table_key: tuple[_FileSignature, _FileSignature] | None = None
+        self._admitted_candidate_digest: str | None = None
+        self._rejected_table_signature: _FileSignature | None = None
+        self._version = 0
+        self._signature: tuple[tuple[str, _FileSignature], ...] = ()
+        signature = self._scan_signature(names=("table",) if self._visual_present else _DOCUMENTS)
+        snapshot = self._read_documents(signature, previous={}) if signature is not None else None
+        if snapshot is not None:
+            self._signature, documents = snapshot
+        else:
+            documents = {}
+        with visual_authority_lock(self._research_fd, exclusive=False) as validate_authority:
+            if not self._visual_present and self._visual_boundary_exists():
+                # The shared research-root lock makes this absence observation and initial legacy
+                # journal commit one linearizable interval with respect to store installation.
+                # A visual writer either installs its boundary first and wins, or waits until the
+                # already validated legacy snapshot is committed.
+                self._visual_present = True
+                self._refresh_visual_notebook()
+                signature = self._scan_signature(names=("table",))
+                snapshot = (
+                    self._read_documents(signature, previous={}) if signature is not None else None
+                )
+                if snapshot is not None:
+                    self._signature, documents = snapshot
+                else:
+                    documents = {}
+            if self._visual_transport is not None and self._visual_error is None:
+                documents["research"] = notebook_bytes(
+                    self._visual_state, self._visual_transport.store.read_artifact
+                )
+            validate_authority()
+            validate_authority.commit_after_validation(
+                lambda: setattr(
+                    self,
+                    "_history",
+                    [_JournalEntry(0, documents, visual_cursor=self._visual_cursor)],
+                )
+            )
+        try:
+            self.feed_dir: Path | None = events.run_feed_dir(self.run_dir)
+        except ValueError:
+            # A legacy run name outside the feed's bounded path vocabulary remains viewable; it
+            # simply cannot have a feed selected for it.
+            self.feed_dir = None
+        self._lifecycle_feed_path: Path | None = None
+        self._lifecycle_run_started_at: float | None = None
+        try:
+            (
+                self._lifecycle_feed_path,
+                self._lifecycle_run_started_at,
+                self._lifecycle,
+            ) = self._read_lifecycle(table_ready="table" in documents)
+        except (LookupError, TypeError, ValueError):
+            # Missing or malformed feed bytes cannot make an independently admitted table
+            # unavailable, and a future run legitimately has no feed at startup.
+            self._lifecycle = reduce_lifecycle([], table_ready="table" in documents)
+            self._lifecycle["hosted"] = self._hosted_coordinate()
+        self._lifecycle_serial = 0
+
+    def close(self) -> None:
+        """Release descriptors retained for the viewer lifetime."""
+
+        self._closed = True
+        transport = getattr(self, "_visual_transport", None)
+        if transport is not None:
+            transport.store.close()
+            self._visual_transport = None
+        research_fd = getattr(self, "_research_fd", -1)
+        if research_fd >= 0:
+            os.close(research_fd)
+            self._research_fd = -1
+        research_path = getattr(self, "_research_path", None)
+        if research_path is not None:
+            research_path.close()
+        selected_path = getattr(self, "_selected_path", None)
+        if selected_path is not None:
+            selected_path.close()
+
+    def __del__(self) -> None:
+        try:
+            if not getattr(self, "_closed", False):
+                self.close()
+        except (AttributeError, OSError):
+            pass
+
+    def _member_stat(self, name: str) -> os.stat_result:
+        if name == "research":
+            self._research_path.validate()
+            return os.stat("research.ipynb", dir_fd=self._research_fd, follow_symlinks=False)
+        parent_fd, leaf = self._selected_path.open_parent(self.table_path)
+        try:
+            return os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+        finally:
+            os.close(parent_fd)
+
+    def _visual_boundary_exists(self) -> bool:
+        """Observe the fixed visual-run authority name without following it."""
+
+        try:
+            os.stat("visual-run", dir_fd=self._research_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            return False
+        except OSError:
+            # An unreadable or malformed authority boundary still fences legacy input.
+            return True
+        return True
+
+    def _open_member(self, name: str) -> tuple[int, int, str]:
+        if name == "research":
+            self._research_path.validate()
+            parent_fd = os.dup(self._research_fd)
+            leaf = "research.ipynb"
+        else:
+            parent_fd, leaf = self._selected_path.open_parent(self.table_path)
+        try:
+            descriptor = os.open(
+                leaf,
+                os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0),
+                dir_fd=parent_fd,
+            )
+        except BaseException:
+            os.close(parent_fd)
+            raise
+        return descriptor, parent_fd, leaf
+
+    def _scan_signature(
+        self, *, names: tuple[str, ...] = _DOCUMENTS
+    ) -> tuple[tuple[str, _FileSignature], ...] | None:
+        """Return no-follow identities, refusing unsafe or unverified notebook inputs."""
+
+        signature: list[tuple[str, _FileSignature]] = []
+        total = 0
+        for name in names:
+            try:
+                info = self._member_stat(name)
+            except FileNotFoundError:
+                continue
+            except OSError:
+                if name == "table":
+                    continue
+                return None
+            if not _is_regular_single_link(info) or info.st_size > _MAX_NOTEBOOK_BYTES:
+                if name == "table":
+                    self._rejected_table_signature = _stat_signature(info)
+                    self._mark_sidecar_unavailable()
+                    continue
+                return None
+            stamp = _stat_signature(info)
+            if name == "table":
+                if self._rejected_table_signature not in (None, stamp):
+                    self._rejected_table_signature = None
+                if self._rejected_table_signature == stamp:
+                    continue
+                if not self._table_is_admissible(stamp):
+                    # A future target is intentionally allowed to be absent at startup.  Its later
+                    # appearance is not evidence that a Build produced it: ordinary directories
+                    # must not satisfy the live viewer handoff merely by containing a renderable
+                    # file with the sidecar name.
+                    continue
+            total += info.st_size
+            if total > _MAX_SNAPSHOT_BYTES:
+                return None
+            signature.append((name, stamp))
+        return tuple(signature)
+
+    def _manifest_observation(self) -> _FileSignature | None:
+        """Return the current descriptor-relative manifest identity, when one is safe to inspect."""
+
+        manifest_path = self.run_dir / "candidate" / "manifest.json"
+        manifest_parent = -1
+        try:
+            manifest_parent, manifest_name = self._selected_path.open_parent(manifest_path)
+            manifest = os.stat(manifest_name, dir_fd=manifest_parent, follow_symlinks=False)
+        except OSError:
+            return None
+        finally:
+            if manifest_parent >= 0:
+                os.close(manifest_parent)
+        if not _is_regular_single_link(manifest):
+            return None
+        return _stat_signature(manifest)
+
+    def _table_is_admissible(self, sidecar: _FileSignature) -> bool:
+        """Admit only the deterministic sidecar bytes derived from the exact verified Build."""
+
+        manifest = self._manifest_observation()
+        if manifest is None:
+            self._admitted_table_key = None
+            self._admitted_candidate_digest = None
+            return False
+        key = (manifest, sidecar)
+        if key == self._admitted_table_key:
+            return True
+        try:
+            with open_verified_snapshot(self.run_dir) as verified_snapshot:
+                candidate_digest = verified_snapshot.verified.candidate_digest
+                notebook = _build_notebook_from_snapshot(
+                    self.run_dir / "candidate", verified_snapshot
+                )
+                expected = (json.dumps(notebook, indent=1, ensure_ascii=False) + "\n").encode(
+                    "utf-8"
+                )
+                actual = self._read_document("table", sidecar)
+            current = self._member_stat("table")
+        except Exception:
+            self._admitted_table_key = None
+            self._admitted_candidate_digest = None
+            return False
+        if (
+            actual != expected
+            or not _is_regular_single_link(current)
+            or _stat_signature(current) != sidecar
+            or self._manifest_observation() != manifest
+        ):
+            self._admitted_table_key = None
+            self._admitted_candidate_digest = None
+            self._rejected_table_signature = sidecar
+            self._mark_sidecar_unavailable()
+            return False
+        self._admitted_table_key = key
+        self._admitted_candidate_digest = candidate_digest
+        return True
+
+    def _read_documents(
+        self,
+        signature: tuple[tuple[str, _FileSignature], ...],
+        *,
+        previous: dict[str, bytes],
+    ) -> tuple[tuple[tuple[str, _FileSignature], ...], dict[str, bytes]] | None:
+        """Read one coherent valid state, sharing unchanged bytes with the previous entry."""
+
+        previous_stamps = dict(self._signature)
+        accepted: list[tuple[str, _FileSignature]] = []
+        documents: dict[str, bytes] = {}
+        for name, expected in signature:
+            if previous_stamps.get(name) == expected and name in previous:
+                documents[name] = previous[name]
+                accepted.append((name, expected))
+                continue
+            raw = self._read_document(name, expected)
+            if raw is None:
+                if name == "table":
+                    self._rejected_table_signature = expected
+                    self._mark_sidecar_unavailable()
+                    continue
+                return None
+            documents[name] = raw
+            accepted.append((name, expected))
+        accepted_signature = tuple(accepted)
+        if (
+            self._scan_signature(names=tuple(name for name, _stamp in signature))
+            != accepted_signature
+        ):
+            return None
+        return accepted_signature, documents
+
+    def _read_document(self, name: str, expected: _FileSignature) -> bytes | None:
+        """Read and render-check one descriptor-bound notebook without admitting a raced file."""
+
+        descriptor = -1
+        parent_fd = -1
+        try:
+            descriptor, parent_fd, leaf = self._open_member(name)
+            opened = os.fstat(descriptor)
+            if not _is_regular_single_link(opened) or _stat_signature(opened) != expected:
+                return None
+            chunks: list[bytes] = []
+            remaining = _MAX_NOTEBOOK_BYTES + 1
+            while remaining:
+                chunk = os.read(descriptor, min(_READ_CHUNK_BYTES, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            raw = b"".join(chunks)
+            if len(raw) > _MAX_NOTEBOOK_BYTES or len(raw) != opened.st_size:
+                return None
+            try:
+                decoded = raw.decode("utf-8")
+                parsed = json.loads(decoded)
+            except (UnicodeDecodeError, ValueError, RecursionError):
+                return None
+            if not isinstance(parsed, dict):
+                return None
+            # A notebook joins the journal only if the same stdlib renderer used by HTTP can
+            # consume it. These are content-shaped failures; unexpected runtime/programming errors
+            # deliberately cross the polling boundary instead of being hidden.
+            try:
+                render_notebook(parsed, mode="embed", filename=_DOCUMENTS[name])
+            except (OverflowError, RecursionError):
+                return None
+            current = os.fstat(descriptor)
+            named = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+            if _stat_signature(current) != expected or _stat_signature(named) != expected:
+                return None
+            return raw
+        except OSError:
+            return None
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+            if parent_fd >= 0:
+                os.close(parent_fd)
+
+    def _journal_bytes(self) -> int:
+        seen: set[int] = set()
+        total = 0
+        for entry in self._history:
+            for raw in entry.documents.values():
+                identity = id(raw)
+                if identity not in seen:
+                    seen.add(identity)
+                    total += len(raw)
+        return total
+
+    def _trim_history(self) -> None:
+        while len(self._history) > 1 and (
+            len(self._history) > _MAX_HISTORY or self._journal_bytes() > _MAX_JOURNAL_BYTES
+        ):
+            self._history.pop(0)
+
+    def _append_history(
+        self,
+        documents: dict[str, bytes],
+        *,
+        mutation: dict[str, object] | None = None,
+        visual_cursor: int | None = None,
+    ) -> None:
+        """Append one real version so every retained mutation has a consecutive predecessor."""
+
+        previous = self._history[-1]
+        next_version = self._version + 1
+        if mutation is None and visual_cursor is None:
+            before = previous.documents.get("research")
+            after = documents.get("research")
+            if (
+                before is not None
+                and after is not None
+                and _only_research_document_changed(previous.documents, documents)
+            ):
+                mutation = _research_mutation(
+                    before,
+                    after,
+                    from_version=previous.version,
+                    version=next_version,
+                )
+        if mutation is not None:
+            mutation = {**mutation, "from_version": previous.version, "version": next_version}
+        entry = _JournalEntry(
+            next_version,
+            documents,
+            mutation,
+            previous.visual_cursor if visual_cursor is None else visual_cursor,
+        )
+        self._history.append(entry)
+        self._version = next_version
+        self._trim_history()
+
+    def poll(self, *, refresh_operational: bool = True) -> None:
+        # Nothing about the table sidecar may gate this scan. Research streaming is the viewer's
+        # first promise, and an unrecoverable sidecar is sticky per candidate identity: returning
+        # early on one stopped research.ipynb from ever being read again, for the life of the
+        # process, with the page still reporting a live server. The scan is already cheap in that
+        # state -- a missing table member is skipped and a rejected signature short-circuits.
+        # Read narration first so a current CLI sidecar write can exclude viewer recovery before
+        # this poll touches the same absent pathname. Refresh again after document admission below,
+        # because handoff requires both the ready record and the independently verified notebook.
+        self._refresh_visual_notebook()
+        if refresh_operational:
+            self._refresh_lifecycle()
+            self._recover_missing_table_sidecar()
+        with self._lock:
+            sidecar_unavailable = self._health_code == HEALTH_SIDECAR_UNAVAILABLE
+        visual_authoritative = self._visual_present or self._visual_transport is not None
+        signature = self._scan_signature(names=("table",) if visual_authoritative else _DOCUMENTS)
+        if signature is not None:
+            with self._condition:
+                unchanged = signature == self._signature
+                previous = self._history[-1].documents
+                if unchanged and sidecar_unavailable and "table" in previous:
+                    self._health_status = "running"
+                    self._health_code = None
+                    self._condition.notify_all()
+            if not unchanged:
+                snapshot = self._read_documents(signature, previous=previous)
+                if snapshot is not None:
+                    accepted_signature, documents = snapshot
+                    if visual_authoritative and "research" in previous:
+                        documents["research"] = previous["research"]
+                    if not visual_authoritative:
+                        with visual_authority_lock(
+                            self._research_fd, exclusive=False
+                        ) as validate_authority:
+                            if self._visual_boundary_exists():
+                                # A first visual writer takes this same research-root lock
+                                # exclusively while installing the durable boundary. It therefore
+                                # cannot appear between this observation and the legacy commit.
+                                self._visual_present = True
+                                self._refresh_visual_notebook()
+                                return
+                            validate_authority()
+
+                            def commit_legacy() -> None:
+                                with self._condition:
+                                    if accepted_signature != self._signature:
+                                        self._signature = accepted_signature
+                                        self._append_history(documents)
+                                        if sidecar_unavailable and "table" in documents:
+                                            self._health_status = "running"
+                                            self._health_code = None
+                                        self._condition.notify_all()
+
+                            validate_authority.commit_after_validation(commit_legacy)
+                    else:
+                        with self._condition:
+                            if accepted_signature != self._signature:
+                                self._signature = accepted_signature
+                                self._append_history(documents)
+                                if sidecar_unavailable and "table" in documents:
+                                    self._health_status = "running"
+                                    self._health_code = None
+                                self._condition.notify_all()
+        if refresh_operational:
+            self._refresh_lifecycle()
+
+    def _hosted_coordinate(self) -> dict[str, object] | None:
+        """Name the hosted run these local bytes came from, when one wrote a record here.
+
+        The viewer observes content fingerprints and local files; nothing in it otherwise names a
+        run, a Dataset, a Table, or a version, so a Build that arrived from hosted execution could
+        be shown but not attributed. This reads the record the handoff wrote beside the Build and
+        reports the five identifiers on it.
+
+        It decides nothing. Admission is unchanged and does not consult this: a dataset is shown
+        because this viewer verified the Build and re-derived the notebook itself, and it would be
+        shown identically if the record were absent, and refused identically if the record claimed
+        anything at all.
+        """
+
+        receipt = read_handoff_receipt(self.run_dir)
+        if receipt is None:
+            return None
+        named = {
+            key: receipt.get(key)
+            for key in (
+                "dataset_id",
+                "table_id",
+                "table_version_id",
+                "version_number",
+                "hosted_run_id",
+            )
+        }
+        return named if all(value is not None for value in named.values()) else None
+
+    def _read_lifecycle(
+        self, *, table_ready: bool
+    ) -> tuple[Path | None, float | None, dict[str, object]]:
+        """Read the selected live attempt and reduce it without receipt replay or inference."""
+
+        if self._visual_transport is not None:
+            snapshot = self._visual_transport.snapshot()
+            reduced = snapshot.state
+            lifecycle = _visual_lifecycle(
+                reduced,
+                table_ready=table_ready,
+                admitted_candidate_digest=self._admitted_candidate_digest,
+            )
+            lifecycle["hosted"] = self._hosted_coordinate()
+            return self._visual_transport.store.log_path, None, lifecycle
+        if self._visual_present:
+            raise ValueError("visual run log is invalid")
+        if self.feed_dir is None:
+            return None, None, reduce_lifecycle([], table_ready=table_ready)
+        path, _size, records = events.select_narrated_feed(
+            self.feed_dir,
+            sealed_candidate_digest=self._admitted_candidate_digest,
+        )
+        if path is None:
+            raise LookupError("no narrated feed is currently selected")
+        if not records:
+            if not events.feed_is_readable(path):
+                raise ValueError("selected feed is not readable")
+            raise LookupError("selected feed has not narrated an event")
+        start = actual_run_started_record(records)
+        run_started_at: float | None = None
+        if start is not None:
+            facts = start.get("facts")
+            moment = start.get("at")
+            try:
+                events.validate_facts("run_started", facts)  # type: ignore[arg-type]
+            except ValueError:
+                pass
+            else:
+                if isinstance(moment, (int, float)) and not isinstance(moment, bool):
+                    run_started_at = float(moment)
+        admitted_digest = self._admitted_candidate_digest
+        selected_digest = coherent_build_seal_candidate(records)
+        attempt_table_ready = (
+            table_ready and admitted_digest is not None and selected_digest == admitted_digest
+        )
+        previous_path = getattr(self, "_lifecycle_feed_path", None)
+        previous_lifecycle = getattr(self, "_lifecycle", {})
+        allow_legacy_handoff = (
+            bool(previous_lifecycle.get("legacy_handoff_allowed", True))
+            if path == previous_path
+            else previous_path is None
+        )
+        lifecycle = reduce_lifecycle(
+            records,
+            table_ready=attempt_table_ready,
+            allow_legacy_handoff=allow_legacy_handoff,
+        )
+        lifecycle["hosted"] = self._hosted_coordinate()
+        return path, run_started_at, lifecycle
+
+    @staticmethod
+    def _coherent_lifecycle_successor(
+        previous: Mapping[str, object],
+        previous_path: Path | None,
+        lifecycle: Mapping[str, object],
+        path: Path | None,
+        run_started_at: float | None,
+    ) -> bool:
+        """Require a distinct, later attempt before replacing a terminal state.
+
+        A same-path feed may only grow; replacing it with a shorter valid prefix is not evidence of
+        a retry. The only accepted same-attempt change preserves its start and terminal timestamps,
+        as when independent table admission changes handoff presentation. A genuine retry has its
+        own attempt file and a ``run_started`` timestamp strictly after the prior terminal timestamp.
+        """
+
+        if previous.get("status") not in {"completed", "failed"}:
+            return True
+        if path is None or previous_path is None:
+            return False
+        if path == previous_path:
+            structurally_same_attempt = (
+                previous.get("status") == "completed"
+                and lifecycle.get("status") == "completed"
+                and previous.get("sealed") is True
+                and lifecycle.get("sealed") is True
+                and lifecycle.get("started_at") == previous.get("started_at")
+                and lifecycle.get("ended_at") == previous.get("ended_at")
+            )
+            return structurally_same_attempt and _sidecar_lifecycle_grows_monotonically(
+                previous, lifecycle
+            )
+        previous_end = previous.get("ended_at")
+        return (
+            isinstance(previous_end, (int, float))
+            and not isinstance(previous_end, bool)
+            and run_started_at is not None
+            and run_started_at > float(previous_end)
+        )
+
+    def _refresh_lifecycle(self) -> None:
+        """Publish a lifecycle notice only when real feed or handoff state changed."""
+
+        with self._lock:
+            table_ready = "table" in self._history[-1].documents
+        try:
+            path, run_started_at, lifecycle = self._read_lifecycle(table_ready=table_ready)
+        except LookupError:
+            # A legacy/direct library build may have no narrated records at all. Only an idle
+            # lifecycle may fall back to independently admitted document state; once any attempt
+            # has narrated progress or a terminal, a missing/header-only replacement retains it.
+            with self._lock:
+                if self._lifecycle.get("status") != "idle":
+                    return
+            path = None
+            run_started_at = None
+            lifecycle = reduce_lifecycle([], table_ready=table_ready)
+            lifecycle["hosted"] = self._hosted_coordinate()
+        except Exception:
+            # The feed is untrusted and concurrently written. Keep the last understood lifecycle;
+            # the next poll retries, exactly as notebook rendering keeps its last valid snapshot.
+            return
+        with self._condition:
+            if lifecycle == self._lifecycle:
+                return
+            if not self._coherent_lifecycle_successor(
+                self._lifecycle,
+                self._lifecycle_feed_path,
+                lifecycle,
+                path,
+                run_started_at,
+            ):
+                return
+            self._lifecycle = lifecycle
+            self._lifecycle_feed_path = path
+            self._lifecycle_run_started_at = run_started_at
+            self._lifecycle_serial += 1
+            self._condition.notify_all()
+
+    def _refresh_visual_notebook(self) -> None:
+        """Project the visual log when present; never combine it with legacy notebook events."""
+
+        self._visual_refresh_lock.acquire()
+        try:
+            self._refresh_visual_notebook_locked()
+        finally:
+            self._visual_refresh_lock.release()
+
+    def _refresh_visual_notebook_locked(self) -> None:
+        transport = getattr(self, "_visual_transport", None)
+        if transport is None:
+            self._visual_present = self._visual_present or self._visual_boundary_exists()
+            try:
+                transport = discover_visual_transport(
+                    self.research_path.parent, directory_fd=self._research_fd
+                )
+            except VisualRunError as exc:
+                self._visual_error = exc
+                self._visual_present = True
+                condition = getattr(self, "_condition", None)
+                if condition is not None:
+                    with condition:
+                        self._health_status = "stopped"
+                        self._health_code = HEALTH_WATCHER_FAILED
+                        condition.notify_all()
+                return
+            if transport is None:
+                return
+            self._visual_transport = transport
+            self._visual_present = True
+        try:
+            snapshot = transport.snapshot()
+            if not hasattr(self, "_history"):
+                self._visual_state = snapshot.state
+                if snapshot.cursor == self._visual_cursor:
+                    return
+                materialize_notebook(
+                    self.research_path,
+                    snapshot.state,
+                    transport.store.read_artifact,
+                    directory_fd=self._research_fd,
+                )
+                self._visual_cursor = snapshot.cursor
+                return
+            if snapshot.cursor == self._visual_cursor:
+                return
+            state = self._visual_state
+            while self._visual_cursor < snapshot.cursor:
+                page = transport.events_after(self._visual_cursor, limit=256)
+                if not page.events:
+                    raise VisualRunError(
+                        "VISUAL_RUN_SEQUENCE_GAP", "visual event cursor did not advance"
+                    )
+                for event in page.events:
+                    before = state
+                    state = apply_event(state, event)
+                    raw = notebook_bytes(state, transport.store.read_artifact)
+                    with self._condition:
+                        documents = dict(self._history[-1].documents)
+                        documents["research"] = raw
+                        self._append_history(
+                            documents,
+                            mutation=_visual_event_mutation(event, before),
+                            visual_cursor=event.sequence,
+                        )
+                        self._condition.notify_all()
+                    self._visual_cursor = event.sequence
+            self._visual_state = state
+            materialize_notebook(
+                self.research_path,
+                state,
+                transport.store.read_artifact,
+                directory_fd=self._research_fd,
+            )
+            observed = self._scan_signature(names=("table",))
+            held = set(self._history[-1].documents)
+            if observed is not None and all(name in held for name, _stamp in observed):
+                # Only stamps for documents this journal actually holds may be adopted here.
+                # `self._signature` is the identity of what the last entry contains, and adopting
+                # the stamp of a sidecar that has just appeared but has not been read would say
+                # the entry holds it. `poll` compares the two to decide whether to read, so that
+                # claim is self-fulfilling: the sidecar looks unchanged from then on and is never
+                # admitted, for the life of the process. It is reachable whenever a Build writes
+                # the sidecar and closes its narration between two polls, which is the ordinary
+                # case when the Build is not the local one -- and the reason it stayed invisible
+                # is that a local Build's sidecar usually lands a poll earlier than its last
+                # event does.
+                self._signature = observed
+        except (OSError, ValueError, VisualRunError) as exc:
+            if isinstance(exc, VisualRunError):
+                self._visual_error = exc
+            elif isinstance(exc, ValueError):
+                self._visual_error = VisualRunError("VISUAL_RUN_PROJECTION_LIMIT", str(exc))
+            condition = getattr(self, "_condition", threading.Condition())
+            with condition:
+                if hasattr(self, "_health_status"):
+                    self._health_status = "stopped"
+                    self._health_code = HEALTH_WATCHER_FAILED
+                    condition.notify_all()
+
+    def _recover_missing_table_sidecar(self) -> None:
+        """Make at most one verified render attempt for each observed candidate identity.
+
+        Recovery is for an absent sidecar and nothing else.  A file that is there is never
+        replaced, whatever it holds: the shipped skill tells the agent to append executed chart
+        cells to ``table.ipynb``, and those cells make the file differ from the deterministic
+        render, which is exactly the state a regenerating watcher would overwrite -- silently, and
+        within one poll.  A present sidecar the viewer cannot admit is reported instead, and
+        ``mr-data notebook RUN_DIR --json`` is the explicit, human-initiated way to rebuild it.
+
+        Recovery stands down structurally while a build is active. ``build_candidate`` installs
+        :data:`RUN_BUILD_ACTIVITY_LOCK` with the atomic run directory and holds an exclusive kernel
+        lock on it until installed verification has closed its namespace monitor. A viewer acquires
+        and retains an exclusive lock on that exact inode plus the descriptor-pinned run through its
+        own verification and create-only write. The run-directory path therefore has no
+        elapsed-time guess or check/use gap: an active Build keeps the writer out, while process
+        death releases the lock and permits recovery. Workspace mode retains its execution-lock
+        probe as an additional guard around the wider offline operation.
+        """
+
+        with self._lock:
+            sidecar_line = next(
+                (
+                    line
+                    for line in self._lifecycle.get("lines", [])
+                    if isinstance(line, Mapping) and line.get("key") == "table-notebook"
+                ),
+                None,
+            )
+        if isinstance(sidecar_line, Mapping) and sidecar_line.get("status") in {
+            "running",
+            "failed",
+        }:
+            # The CLI owns the write while it is running. A narrated failure remains best-effort
+            # and visible; silently retrying it here would contradict the real terminal outcome.
+            return
+        try:
+            self._member_stat("table")
+        except FileNotFoundError:
+            pass
+        except OSError:
+            return
+        else:
+            return
+        if self._workspace_build_is_active():
+            return
+        recovery_lease = self._acquire_run_recovery_lease()
+        if recovery_lease is None:
+            return
+        try:
+            recovery_lease.validate()
+            try:
+                os.stat(_SIDECAR_NAME, dir_fd=recovery_lease.run_fd, follow_symlinks=False)
+            except FileNotFoundError:
+                pass
+            except OSError:
+                return
+            else:
+                return
+            observation = recovery_lease.manifest_observation()
+            if observation is None or observation == self._sidecar_manifest_observation:
+                return
+            self._sidecar_manifest_observation = observation
+            try:
+                verified = verify_candidate(
+                    self.run_dir,
+                    _run_fd=recovery_lease.run_fd,
+                    _ancestor_validator=recovery_lease.validate,
+                )
+            except Exception:
+                self._mark_sidecar_unavailable()
+                return
+            identity = verified.candidate_digest
+            if identity == self._sidecar_candidate_identity:
+                return
+            # Record before rendering: failures are stable for this verified candidate and cannot
+            # turn the 250ms watcher into an unbounded retry loop.
+            self._sidecar_candidate_identity = identity
+            try:
+                # The shared activity lock and exact run descriptor remain owned through the
+                # create-only placement. A sidecar that arrived inside the render still wins.
+                render_table_notebook(
+                    self.run_dir,
+                    replace_existing=False,
+                    _run_fd=recovery_lease.run_fd,
+                    _ancestor_validator=recovery_lease.validate,
+                )
+                recovery_lease.validate()
+            except FileExistsError:
+                self._sidecar_manifest_observation = None
+                self._sidecar_candidate_identity = None
+                return
+            except Exception:
+                self._mark_sidecar_unavailable()
+                return
+        finally:
+            recovery_lease.close()
+        # A successful recovery is not rate-limited: if the sidecar is later deleted while this
+        # same candidate remains current, the next poll regenerates it. That release is only safe
+        # once the file just written is one the viewer will admit. A render this watcher would
+        # reject again -- one over the size limit, say -- would otherwise re-verify the whole
+        # candidate, re-render it and replace the file four times a second, forever.
+        if not self._recovered_sidecar_is_admissible():
+            self._mark_sidecar_unavailable()
+            return
+        self._sidecar_manifest_observation = None
+        self._sidecar_candidate_identity = None
+        self._rejected_table_signature = None
+        with self._condition:
+            if self._health_status == "unavailable":
+                self._health_status = "running"
+                self._health_code = None
+                self._condition.notify_all()
+
+    def _workspace_build_is_active(self) -> bool:
+        """Whether a build currently holds this workspace's execution lock.
+
+        ``offline._execute_workspace`` opens the workspace, taking that lock exclusively, and calls
+        ``build_candidate`` inside it -- so the lock is held across the post-rename verification a
+        recovery write would break. Probing it shared and non-blocking answers the question without
+        excluding anything for longer than the probe. The run-local recovery lease below provides
+        the write-owning exclusion interval in both modes.
+        """
+
+        if fcntl is None:
+            raise ViewerError(
+                "VIEWER_PLATFORM_UNSUPPORTED",
+                "secure viewer locking is unavailable on this platform",
+            )
+        if self.target.mode != "workspace":
+            return False
+        control_fd = -1
+        lock_fd = -1
+        try:
+            control_fd = self._selected_path.open_directory(
+                self.target.selected_path / CONTROL_PATH
+            )
+            lock_fd = os.open(
+                WORKSPACE_LOCK_NAME,
+                os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=control_fd,
+            )
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError as exc:
+                return exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES)
+            fcntl.flock(lock_fd, fcntl.LOCK_UN)
+            return False
+        except OSError:
+            # No control tree, or one this viewer may not read through: there is no build to defer
+            # to, and the quiet-poll wait below still applies.
+            return False
+        finally:
+            if lock_fd >= 0:
+                os.close(lock_fd)
+            if control_fd >= 0:
+                os.close(control_fd)
+
+    def _acquire_run_recovery_lease(self) -> _RunRecoveryLease | None:
+        """Acquire the exact run and activity lock for the complete recovery transaction.
+
+        Absence, contention, malformed state, and every identity race fail closed. In particular,
+        an absent future run cannot become a published Build after this method returns a negative
+        answer and still be touched by the same poll: no lease means no subsequent recovery work.
+        Legacy Builds without the structural activity file require explicit ``mr-data notebook``.
+        """
+
+        if fcntl is None:
+            raise ViewerError(
+                "VIEWER_PLATFORM_UNSUPPORTED",
+                "secure viewer locking is unavailable on this platform",
+            )
+        run_handle: _CandidateRunHandle | None = None
+        lock_fd = -1
+        acquired = False
+        transferred = False
+        try:
+            run_handle = _open_candidate_run_handle(self.run_dir)
+            _validate_candidate_run_handle(run_handle)
+            try:
+                named_before = os.stat(
+                    RUN_BUILD_ACTIVITY_LOCK,
+                    dir_fd=run_handle.run_fd,
+                    follow_symlinks=False,
+                )
+            except FileNotFoundError:
+                return None
+            if not _is_regular_single_link(named_before):
+                return None
+            lock_fd = os.open(
+                RUN_BUILD_ACTIVITY_LOCK,
+                os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0),
+                dir_fd=run_handle.run_fd,
+            )
+            opened = os.fstat(lock_fd)
+            if not _is_regular_single_link(opened) or _entry_identity(opened) != _entry_identity(
+                named_before
+            ):
+                return None
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
+                acquired = True
+            except OSError as exc:
+                if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                    return None
+                return None
+            named_after = os.stat(
+                RUN_BUILD_ACTIVITY_LOCK,
+                dir_fd=run_handle.run_fd,
+                follow_symlinks=False,
+            )
+            lock_identity = _entry_identity(opened)
+            if (
+                not _is_regular_single_link(named_after)
+                or _entry_identity(named_after) != lock_identity
+            ):
+                return None
+            lease = _RunRecoveryLease(run_handle, lock_fd, lock_identity)
+            lease.validate()
+            transferred = True
+            return lease
+        except Exception:
+            return None
+        finally:
+            if not transferred:
+                if acquired:
+                    try:
+                        fcntl.flock(lock_fd, fcntl.LOCK_UN)
+                    except OSError:
+                        pass
+                if lock_fd >= 0:
+                    try:
+                        os.close(lock_fd)
+                    except OSError:
+                        pass
+                if run_handle is not None:
+                    try:
+                        run_handle.close()
+                    except Exception:
+                        pass
+
+    def _recovered_sidecar_is_admissible(self) -> bool:
+        """Read back the sidecar this recovery wrote under the live admission rules."""
+
+        try:
+            sidecar = self._member_stat("table")
+        except OSError:
+            return False
+        if not _is_regular_single_link(sidecar) or sidecar.st_size > _MAX_NOTEBOOK_BYTES:
+            return False
+        return self._table_is_admissible(_stat_signature(sidecar))
+
+    def _run_directory_exists(self) -> bool:
+        """Ask whether the run directory itself is there, without following a link to it."""
+
+        descriptor = -1
+        try:
+            descriptor = self._selected_path.open_directory(self.run_dir)
+        except OSError:
+            return False
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+        return True
+
+    def _mark_sidecar_unavailable(self) -> None:
+        build_present = self._manifest_observation() is not None
+        path_exists = build_present or self._run_directory_exists()
+        with self._condition:
+            self._health_build_present = build_present
+            self._health_path_exists = path_exists
+            self._health_status = "unavailable"
+            self._health_code = HEALTH_SIDECAR_UNAVAILABLE
+            self._condition.notify_all()
+
+    @property
+    def version(self) -> int:
+        with self._lock:
+            return self._version
+
+    def visual_cursor_is_admitted(self, cursor: int) -> bool:
+        """Return whether a cursor can safely be announced to a snapshot client."""
+
+        with self._lock:
+            return cursor <= self._visual_cursor
+
+    def versions(self) -> list[int]:
+        with self._lock:
+            return [entry.version for entry in self._history]
+
+    def snapshot(self, version: int | None = None) -> _JournalEntry:
+        with self._lock:
+            return self._snapshot_unlocked(version)
+
+    def _snapshot_unlocked(self, version: int | None = None) -> _JournalEntry:
+        if version is None:
+            return self._history[-1]
+        if version < 0 or version > self._version:
+            raise KeyError(version)
+        for entry in self._history:
+            if entry.version == version:
+                return entry
+        raise LookupError(version)
+
+    def _snapshot_cursor_unlocked(self, cursor: int) -> _JournalEntry:
+        if cursor < 0 or cursor > self._visual_cursor:
+            raise KeyError(cursor)
+        for entry in self._history:
+            if entry.visual_cursor == cursor:
+                return entry
+        raise LookupError(cursor)
+
+    def presentation(
+        self, version: int | None = None
+    ) -> tuple[_JournalEntry, dict[str, str | None], dict[str, object]]:
+        """Return notebook, health, and lifecycle from one atomic viewer observation."""
+
+        with self._lock:
+            return (
+                self._snapshot_unlocked(version),
+                self._health_unlocked(),
+                dict(self._lifecycle),
+            )
+
+    def presentation_cursor(
+        self, cursor: int
+    ) -> tuple[_JournalEntry, dict[str, str | None], dict[str, object]]:
+        """Return the exact retained notebook state produced by one durable visual cursor."""
+
+        with self._lock:
+            return (
+                self._snapshot_cursor_unlocked(cursor),
+                self._health_unlocked(),
+                dict(self._lifecycle),
+            )
+
+    @property
+    def health(self) -> dict[str, str | None]:
+        with self._lock:
+            return self._health_unlocked()
+
+    @property
+    def lifecycle(self) -> dict[str, object]:
+        with self._lock:
+            return dict(self._lifecycle)
+
+    def handoff_candidate_digest(self) -> str | None:
+        """Return the exact admitted Build identity only while its table is handed off."""
+
+        with self._lock:
+            if not self._lifecycle.get("handoff"):
+                return None
+            if "table" not in self._history[-1].documents:
+                return None
+            return self._admitted_candidate_digest
+
+    def _health_unlocked(self) -> dict[str, str | None]:
+        """Describe one health state from the registry every other surface answers through.
+
+        The page, ``/health``, ``/snapshot`` and the command line all read this, and the sentences
+        come from :func:`remediation_for` so that none of them can drift from the answer a person
+        gets for the same code anywhere else.  The command is the one part the map cannot write:
+        restarting this viewer needs the exact target and research folders this process was given,
+        and a map keyed by one path has no way to name two.
+
+        The observations are the ones taken when this state was entered rather than a fresh look:
+        every streaming client reads this four times a second, under the lock the watcher needs,
+        and the map's question is what the caller found when it looked.  Both are passed, because
+        a viewer started before the build has a run directory with no Build in it, and every
+        default sentence for the table code is written about a Build that is there.
+        """
+
+        health: dict[str, str | None] = {"status": self._health_status, "code": self._health_code}
+        if self._health_code is None:
+            return health
+        lines = remediation_for(
+            self._health_code,
+            path=str(self.run_dir),
+            path_exists=self._health_path_exists,
+            build_present=self._health_build_present,
+        )
+        prefix = "Run: "
+        detail = " ".join(line for line in lines if not line.startswith(prefix))
+        command = next(
+            (line[len(prefix) :] for line in lines if line.startswith(prefix)),
+            None,
+        )
+        if command is None and self._health_code == HEALTH_WATCHER_FAILED:
+            target_flag = "--workspace" if self.target.mode == "workspace" else "--run-dir"
+            research = (
+                ["--research-dir", str(self.research_path.parent)]
+                if self.target.explicit_research
+                else []
+            )
+            command = shlex.join(
+                [
+                    "mr-data",
+                    "view",
+                    target_flag,
+                    str(self.target.selected_path),
+                    *research,
+                    "--json",
+                ]
+            )
+        health.update({"detail": detail, "remediation": command})
+        return health
+
+    def mark_watcher_failed(self) -> None:
+        with self._condition:
+            self._health_status = "stopped"
+            self._health_code = HEALTH_WATCHER_FAILED
+            self._condition.notify_all()
+
+    def _notice_unlocked(self) -> dict[str, object]:
+        return {
+            "epoch": self.epoch,
+            "version": self._version,
+            "cursor": self._visual_cursor,
+            "docs": list(self._history[-1].documents),
+            "health": self._health_unlocked(),
+            "lifecycle": self._lifecycle,
+        }
+
+    def notice(self) -> dict[str, object]:
+        with self._lock:
+            return self._notice_unlocked()
+
+    def wait_for_notice(
+        self, last: tuple[object, ...] | None, timeout: float
+    ) -> tuple[dict[str, object], tuple[object, ...]]:
+        with self._condition:
+            current = (
+                self.epoch,
+                self._version,
+                self._health_status,
+                self._health_code,
+                self._lifecycle_serial,
+            )
+            if last == current:
+                self._condition.wait(timeout)
+            notice = self._notice_unlocked()
+            key = (
+                notice["epoch"],
+                notice["version"],
+                notice["health"]["status"],  # type: ignore[index]
+                notice["health"]["code"],  # type: ignore[index]
+                self._lifecycle_serial,
+            )
+            return notice, key
+
+
+def _notebook_shell(raw: bytes, filename: str) -> str:
+    notebook = json.loads(raw.decode("utf-8"))
+    return render_notebook(notebook, mode="embed", filename=filename)
+
+
+def _waiting() -> str:
+    return (
+        '<section class="mr-waiting" role="status" aria-live="polite">'
+        f"{_MARK_ONLY}"
+        "<strong>No notebook has been written yet</strong>"
+        "<span>Create research.ipynb for research notes. table.ipynb appears only after a "
+        "successful verified Build.</span></section>"
+    )
+
+
+def _render_snapshot(
+    entry: _JournalEntry, requested: str, *, allow_table: bool = True
+) -> tuple[str, str, list[str]]:
+    """Render admitted documents, withholding table UI until narrated handoff completes."""
+
+    docs = [
+        name for name in _DOCUMENTS if name in entry.documents and (name != "table" or allow_table)
+    ]
+    active = requested if requested in docs else (docs[0] if docs else "")
+    if not active:
+        return _waiting(), active, docs
+    filename = _DOCUMENTS[active]
+    return _notebook_shell(entry.documents[active], filename), active, docs
+
+
+def _tabs(docs: list[str], active: str) -> str:
+    tabs = []
+    for name in _DOCUMENTS:
+        hidden = "" if name in docs else " hidden"
+        selected = name == active
+        classes = "mr-tab is-active" if selected else "mr-tab"
+        tabs.append(
+            f'<button class="{classes}" type="button" role="tab" '
+            f'aria-selected="{str(selected).lower()}" data-doc="{name}"{hidden}>'
+            '<svg class="mr-tab-icon" viewBox="0 0 16 16" aria-hidden="true">'
+            '<rect x="3.25" y="1.75" width="10.5" height="12.5" rx="1.75"></rect>'
+            '<path d="M6 1.75v12.5M8.5 5h3M8.5 8h3M8.5 11h2"></path></svg>'
+            f'<span class="mr-tab-name">{name}<span class="mr-tab-ext">.ipynb</span></span></button>'
+        )
+    return "".join(tabs)
+
+
+def _lifecycle_block(lifecycle: dict[str, object]) -> str:
+    status = str(lifecycle.get("status", "idle"))
+    hidden = " hidden" if status == "idle" else ""
+    state_label = (
+        "Stopped"
+        if status == "failed"
+        else "Complete"
+        if status == "completed"
+        else "Ready"
+        if status == "idle"
+        else "Running"
+    )
+    items = []
+    for line in lifecycle.get("lines", []):
+        if not isinstance(line, dict):
+            continue
+        line_status = str(line.get("status", "running"))
+        mark = "!" if line_status == "failed" else "ok" if line_status == "done" else "."
+        items.append(
+            f'<li class="mr-build-line is-{html.escape(line_status)}" '
+            f'data-build-span="{html.escape(str(line.get("key", "")))}">'
+            f'<span class="mr-build-mark" aria-hidden="true">{mark}</span>'
+            '<span class="mr-build-copy">'
+            f'<span class="mr-build-label">{html.escape(str(line.get("label", "")))}</span>'
+            f'<span class="mr-build-detail">{html.escape(str(line.get("detail", "")))}</span>'
+            "</span></li>"
+        )
+    classes = "mr-build-progress is-failed" if status == "failed" else "mr-build-progress"
+    opened = " open" if status not in {"idle", "completed"} else ""
+    return (
+        f'<details class="{classes}" data-build-progress{hidden}{opened}>'
+        '<summary class="mr-build-progress-head" aria-live="polite">'
+        f'<span class="mr-build-progress-state" data-build-state>{state_label}</span>'
+        f"<strong data-build-phase>{html.escape(str(lifecycle.get('phase', '')))}</strong>"
+        "</summary><ol data-build-lines>" + "".join(items) + "</ol></details>"
+    )
+
+
+def _research_terminal_block(lifecycle: dict[str, object], active: str) -> str:
+    """Render a failed attempt's real feed terminal as the research document's closing block."""
+
+    terminal = lifecycle.get("terminal")
+    visible = isinstance(terminal, Mapping) and active != "table"
+    if not isinstance(terminal, Mapping):
+        terminal = {}
+    metadata = [
+        str(value)
+        for value in (terminal.get("severity"), terminal.get("finding_id"))
+        if isinstance(value, str) and value
+    ]
+    metadata_text = " · ".join(metadata)
+    hidden = "" if visible else " hidden"
+    metadata_hidden = "" if metadata_text else " hidden"
+    return (
+        '<section class="mr-research-terminal" data-research-terminal role="status" aria-atomic="true"'
+        f' data-terminal-event="{html.escape(str(terminal.get("event", "")))}"{hidden}>'
+        f"<strong>{html.escape(str(terminal.get('title', '')))}</strong>"
+        f"<p>{html.escape(str(terminal.get('detail', '')))}</p>"
+        f"<small{metadata_hidden}>{html.escape(metadata_text)}</small></section>"
+    )
+
+
+def _workbench_document(
+    shell: str,
+    *,
+    run_name: str,
+    active: str,
+    docs: list[str],
+    version: int,
+    epoch: str,
+    health: dict[str, str | None],
+    visual_cursor: int = 0,
+    lifecycle: dict[str, object] | None = None,
+) -> str:
+    lifecycle = lifecycle or reduce_lifecycle([], table_ready=False)
+    handoff = bool(lifecycle.get("handoff"))
+    download_state = (
+        ' href="/download/table.parquet" aria-disabled="false"'
+        if handoff
+        else ' aria-disabled="true" tabindex="-1"'
+    )
+    lifecycle_phase = str(lifecycle.get("phase", "Research notebook"))
+    phase = html.escape("Research" if lifecycle_phase == "Research notebook" else lifecycle_phase)
+    progress = int(lifecycle.get("progress", 0))
+    elapsed = format_elapsed(elapsed_seconds(lifecycle, now=time.time()))
+    elapsed_hidden = "" if elapsed else " hidden"
+    files_label = "Show table in Finder" if handoff else "Show run in Finder"
+    initial_status = (
+        "Stopped"
+        if health["status"] == "stopped"
+        else "Unavailable"
+        if health["status"] == "unavailable"
+        else "Connecting"
+    )
+    detail_hidden = "" if health["status"] in {"unavailable", "stopped"} else " hidden"
+    detail_code = html.escape(health.get("code") or "")
+    detail_text = html.escape(health.get("detail") or "")
+    detail_command = html.escape(health.get("remediation") or "")
+    tabs_class = "mr-tabs is-single" if len(docs) == 1 else "mr-tabs"
+    return (
+        '<!doctype html>\n<html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{html.escape(run_name)} · Mostly Right</title><style>{_WORKBENCH_CSS}</style>"
+        "</head>"
+        f'<body data-doc="{html.escape(active)}" data-version="{version}" '
+        f'data-cursor="{visual_cursor}" '
+        f'data-epoch="{html.escape(epoch)}" data-health="{html.escape(str(health["status"]))}" '
+        f'data-handoff="{str(handoff).lower()}">'
+        '<header class="mr-topbar">'
+        f'<a class="mr-brand" href="/" aria-label="Mostly Right">{_LOGO}</a>'
+        '<div class="mr-session"><span class="mr-session-copy">'
+        f"<small>{html.escape(run_name)}</small><strong data-lifecycle-phase>{phase}</strong></span></div>"
+        f'<nav class="{tabs_class}" role="tablist" aria-label="Open notebooks">{_tabs(docs, active)}</nav>'
+        '<div class="mr-actions"><span class="mr-live" data-live-status role="status" '
+        f'aria-live="polite"><i></i><span>{initial_status}</span></span>'
+        f'<time class="mr-run-clock" data-run-clock{elapsed_hidden}>{html.escape(elapsed)}</time>'
+        '<button class="mr-button" type="button" data-follow-agent hidden>Follow agent</button>'
+        f'<button class="mr-button" type="button" data-explore{"" if handoff else " disabled"}>Explore rows</button>'
+        f'<button class="mr-button" type="button" data-files aria-label="{files_label}">'
+        '<svg aria-hidden="true" width="15" height="15" viewBox="0 0 16 16" fill="none"><path d="M1.5 4.25h5l1.2 1.5h6.8v6.5H1.5z" stroke="currentColor" stroke-width="1.25"/></svg>'
+        f'<span class="mr-files-label">{files_label}</span></button>'
+        f'<a class="mr-download" data-download{download_state}>Download table</a>'
+        f'</div><div class="mr-overall" role="progressbar" aria-label="Build progress" aria-valuemin="0" '
+        f'aria-valuemax="100" aria-valuenow="{progress}" data-overall-progress><span style="width:{progress}%"></span></div></header>'
+        '<main class="mr-workbench"><div class="mr-stage">'
+        f"{_lifecycle_block(lifecycle)}"
+        f'<section class="mr-health-detail" data-health-detail role="alert" aria-atomic="true"{detail_hidden}>'
+        f"<strong>{detail_code}</strong><span>{detail_text}</span><code>{detail_command}</code>"
+        '</section><div class="mr-sr-status" data-stream-announcement role="status" aria-live="polite" aria-atomic="true"></div>'
+        '<div class="mr-notebook-root" '
+        f'data-notebook-root data-doc="{html.escape(active)}">{shell}</div>'
+        f"{_research_terminal_block(lifecycle, active)}</div></main>"
+        '<dialog class="mr-explorer" data-explorer aria-labelledby="mr-explorer-title">'
+        '<div class="mr-explorer-head"><strong id="mr-explorer-title">Verified table rows</strong>'
+        '<button class="mr-button" type="button" data-explorer-close>Close</button></div>'
+        '<div class="mr-explorer-body" data-explorer-body></div></dialog>'
+        f"{_RELOAD_SCRIPT}</body></html>\n"
+    )
+
+
+def _document(shell: str, title: str) -> str:
+    """Compatibility full document used by direct ``render_html`` callers."""
+
+    return (
+        '<!doctype html>\n<html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{html.escape(title)}</title>"
+        "<style>body{margin:0;background:#f1f3f6;padding:24px}.nb-shell{max-width:1180px;margin:0 auto}</style>"
+        f"</head><body>{shell}{_RELOAD_SCRIPT}</body></html>\n"
+    )
+
+
+def render_html(ipynb_path: Path) -> str:
+    """Render one notebook as a self-contained static document, without a kernel."""
+
+    ipynb_path = Path(ipynb_path)
+    return render_html_bytes(ipynb_path.read_bytes(), filename=ipynb_path.name)
+
+
+def render_html_bytes(raw: bytes, *, filename: str = _SIDECAR_NAME) -> str:
+    """Render already-read notebook bytes without reopening the selected path."""
+
+    notebook = json.loads(raw)
+    shell = render_notebook(notebook, mode="static", filename=filename)
+    return _document(shell, title=filename)
+
+
+class _ViewerServer(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, address: tuple[str, int], handler: type, state: _ViewerState) -> None:
+        self.viewer_state = state
+        self.viewer_stopped = False
+        self.viewer_watcher: threading.Thread | None = None
+        self._stream_lock = threading.Lock()
+        self._stream_connections: set[socket.socket] = set()
+        super().__init__(address, handler)
+
+    def register_stream(self, connection: socket.socket) -> None:
+        with self._stream_lock:
+            self._stream_connections.add(connection)
+
+    def unregister_stream(self, connection: socket.socket) -> None:
+        with self._stream_lock:
+            self._stream_connections.discard(connection)
+
+    def close_streams(self) -> None:
+        with self._stream_lock:
+            connections = tuple(self._stream_connections)
+        for connection in connections:
+            try:
+                connection.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+
+    def shutdown(self) -> None:
+        self.viewer_stopped = True
+        self.close_streams()
+        super().shutdown()
+
+    def server_close(self) -> None:
+        try:
+            super().server_close()
+        finally:
+            self.viewer_state.close()
+
+    def handle_error(self, _request: object, _client_address: object) -> None:
+        """A browser closing an SSE socket is normal and should not spill a traceback."""
+
+        return
+
+
+class _ViewerServerV6(_ViewerServer):
+    address_family = socket.AF_INET6
+
+
+class _TableUnavailable(RuntimeError):
+    pass
+
+
+def _verified_table_snapshot(
+    state: _ViewerState,
+    *,
+    expected_candidate_digest: str,
+) -> tuple[tempfile.SpooledTemporaryFile[bytes], int]:
+    """Copy exact admitted-and-reverified Parquet bytes into an immutable response snapshot."""
+
+    retained: list[object] = []
+    data_fd = -1
+    source_fd = -1
+    spool: tempfile.SpooledTemporaryFile[bytes] | None = None
+    try:
+        verified = verify_candidate(state.run_dir, _retained_leases=retained)  # type: ignore[arg-type]
+        if len(retained) != 1:
+            raise _TableUnavailable("Build verification lease unavailable")
+        if verified.candidate_digest != expected_candidate_digest:
+            raise _TableUnavailable("verified Build differs from the admitted handoff")
+        lease = retained[0]
+        candidate_fd = lease.candidate_fd  # type: ignore[attr-defined]
+        directory_flags = (
+            os.O_RDONLY
+            | getattr(os, "O_CLOEXEC", 0)
+            | getattr(os, "O_DIRECTORY", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+        )
+        data_fd = os.open("data", directory_flags, dir_fd=candidate_fd)
+        if not stat.S_ISDIR(os.fstat(data_fd).st_mode):
+            raise _TableUnavailable("Build data member is not a directory")
+        source_fd = os.open(
+            "table.parquet",
+            os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0),
+            dir_fd=data_fd,
+        )
+        before = os.fstat(source_fd)
+        named = os.stat("table.parquet", dir_fd=data_fd, follow_symlinks=False)
+        if not _is_regular_single_link(before) or _stat_signature(before) != _stat_signature(named):
+            raise _TableUnavailable("table member is not a stable regular file")
+        expected_member = next(
+            (
+                item
+                for item in verified.manifest.get("members", [])
+                if isinstance(item, dict) and item.get("path") == "data/table.parquet"
+            ),
+            None,
+        )
+        if not isinstance(expected_member, dict):
+            raise _TableUnavailable("verified manifest has no table member")
+        expected_size = expected_member.get("bytes")
+        if (
+            not isinstance(expected_size, int)
+            or isinstance(expected_size, bool)
+            or expected_size < 0
+        ):
+            raise _TableUnavailable("verified table size is invalid")
+        spool = tempfile.SpooledTemporaryFile(max_size=8 * 1024 * 1024, mode="w+b")
+        digest = hashlib.sha256()
+        copied = 0
+        while True:
+            chunk = os.read(source_fd, _READ_CHUNK_BYTES)
+            if not chunk:
+                break
+            copied += len(chunk)
+            if copied > expected_size:
+                raise _TableUnavailable("table changed while preparing the download")
+            digest.update(chunk)
+            spool.write(chunk)
+        after = os.fstat(source_fd)
+        named_after = os.stat("table.parquet", dir_fd=data_fd, follow_symlinks=False)
+        if (
+            copied != expected_size
+            or copied != before.st_size
+            or _stat_signature(after) != _stat_signature(before)
+            or _stat_signature(named_after) != _stat_signature(before)
+            or digest.hexdigest() != verified.table_sha256
+        ):
+            raise _TableUnavailable("table changed or failed its verified digest")
+        lease.validate()  # type: ignore[attr-defined]
+        spool.seek(0)
+        ready = spool
+        spool = None
+        return ready, copied
+    except _TableUnavailable:
+        raise
+    except Exception as exc:
+        raise _TableUnavailable("table is not a currently verified snapshot") from exc
+    finally:
+        if source_fd >= 0:
+            os.close(source_fd)
+        if data_fd >= 0:
+            os.close(data_fd)
+        for lease in retained:
+            lease.close()  # type: ignore[attr-defined]
+        if spool is not None:
+            spool.close()
+
+
+def _verified_query_snapshot(
+    state: _ViewerState, *, expected_candidate_digest: str
+) -> tuple[bytes, QueryEvidence]:
+    """Pin Parquet and all explorer evidence to one replay-verified snapshot."""
+
+    try:
+        with open_verified_snapshot(state.run_dir) as snapshot:
+            verified = snapshot.verified
+            if verified.candidate_digest != expected_candidate_digest:
+                raise _TableUnavailable("verified Build differs from the admitted handoff")
+            parquet_raw = snapshot.member_bytes("data/table.parquet")
+            profile_raw = snapshot.member_bytes("evidence/profile.json")
+            quality_raw = snapshot.member_bytes("evidence/quality.json")
+            lineage_raw = snapshot.member_bytes("evidence/lineage.json")
+            sources_raw = snapshot.member_bytes("evidence/sources.json")
+            profile = json.loads(profile_raw)
+            quality = json.loads(quality_raw)
+            lineage_value = json.loads(lineage_raw)
+            sources = json.loads(sources_raw)
+            if not all(
+                isinstance(value, dict) for value in (profile, quality, lineage_value)
+            ) or not isinstance(sources, list):
+                raise _TableUnavailable("verified explorer evidence has an invalid shape")
+
+            observations_raw: bytes | None = None
+            observations: list[dict[str, object]] = []
+            if "evidence/observations.json" in snapshot.members:
+                observations_raw = snapshot.member_bytes("evidence/observations.json")
+                observation_set = json.loads(observations_raw)
+                if (
+                    not isinstance(observation_set, dict)
+                    or not isinstance(observation_set.get("observations"), list)
+                    or any(not isinstance(item, dict) for item in observation_set["observations"])
+                ):
+                    raise _TableUnavailable("verified observation evidence is invalid")
+                observations = observation_set["observations"]
+
+            columns = profile.get("columns")
+            if not isinstance(columns, list) or any(not isinstance(item, str) for item in columns):
+                raise _TableUnavailable("verified profile does not name the table columns")
+            terminal = observations[-1] if observations else None
+            terminal_profiles = terminal.get("profiles") if terminal is not None else None
+            if isinstance(terminal_profiles, list):
+                profiles = {
+                    str(item["column"]): dict(item)
+                    for item in terminal_profiles
+                    if isinstance(item, dict) and isinstance(item.get("column"), str)
+                }
+            else:
+                types = profile.get("types")
+                null_counts = profile.get("null_counts")
+                row_count = profile.get("row_count")
+                if (
+                    not isinstance(types, dict)
+                    or not isinstance(null_counts, dict)
+                    or isinstance(row_count, bool)
+                    or not isinstance(row_count, int)
+                ):
+                    raise _TableUnavailable("verified profiles are incomplete")
+                profiles = {
+                    column: {
+                        "column": column,
+                        "rows_examined": row_count,
+                        "logical_type": types.get(column),
+                        "null_count": null_counts.get(column),
+                    }
+                    for column in columns
+                }
+
+            lineage_columns = lineage_value.get("columns", lineage_value)
+            if not isinstance(lineage_columns, dict):
+                raise _TableUnavailable("verified lineage is incomplete")
+            normalized_lineage = {
+                column: {"column": column, **dict(lineage_columns[column])}
+                for column in columns
+                if isinstance(lineage_columns.get(column), dict)
+            }
+            findings = terminal.get("findings", []) if terminal is not None else []
+            if not isinstance(findings, list) or any(
+                not isinstance(item, dict) for item in findings
+            ):
+                raise _TableUnavailable("verified findings are invalid")
+            rights_statuses: list[str] = []
+            classifications: list[str] = []
+            for source in sources:
+                if not isinstance(source, dict) or not isinstance(source.get("rights"), dict):
+                    raise _TableUnavailable("verified source governance is invalid")
+                rights_statuses.append(str(source["rights"].get("status", "unknown")))
+                classifications.append(str(source.get("classification", "unknown")))
+            display = (
+                str(terminal.get("display"))
+                if terminal is not None
+                else (
+                    "full"
+                    if rights_statuses
+                    and all(
+                        status in {"public_domain", "permissive_license"}
+                        for status in rights_statuses
+                    )
+                    and classifications
+                    and all(item == "public" for item in classifications)
+                    else "schema_only"
+                )
+            )
+            member_bytes = {
+                "evidence/profile.json": profile_raw,
+                "evidence/quality.json": quality_raw,
+                "evidence/lineage.json": lineage_raw,
+                "evidence/sources.json": sources_raw,
+            }
+            if observations_raw is not None:
+                member_bytes["evidence/observations.json"] = observations_raw
+            evidence = QueryEvidence(
+                candidate_digest=verified.candidate_digest,
+                table_sha256=verified.table_sha256,
+                display=display,
+                rights_statuses=tuple(rights_statuses),
+                classifications=tuple(classifications),
+                profiles=profiles,
+                findings=tuple(findings),
+                lineage=normalized_lineage,
+                evidence_sha256={
+                    path: hashlib.sha256(raw).hexdigest() for path, raw in member_bytes.items()
+                },
+            )
+            return parquet_raw, evidence
+    except _TableUnavailable:
+        raise
+    except Exception as exc:
+        raise _TableUnavailable("table is not a currently verified query snapshot") from exc
+
+
+def _reveal_verified_table(state: _ViewerState, *, expected_candidate_digest: str) -> None:
+    """Launch the platform file action only for the exact admitted, still-verified Build."""
+
+    retained: list[object] = []
+    data_fd = -1
+    table_fd = -1
+    try:
+        try:
+            verified = verify_candidate(  # type: ignore[arg-type]
+                state.run_dir,
+                _retained_leases=retained,
+            )
+            if len(retained) != 1 or verified.candidate_digest != expected_candidate_digest:
+                raise _TableUnavailable("verified Build differs from the admitted handoff")
+            lease = retained[0]
+            lease.validate()  # type: ignore[attr-defined]
+        except _TableUnavailable:
+            raise
+        except Exception as exc:
+            raise _TableUnavailable("table is not the admitted verified snapshot") from exc
+        directory_flags = (
+            os.O_RDONLY
+            | getattr(os, "O_CLOEXEC", 0)
+            | getattr(os, "O_DIRECTORY", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+        )
+        data_fd = os.open("data", directory_flags, dir_fd=lease.candidate_fd)  # type: ignore[attr-defined]
+        table_fd = os.open(
+            "table.parquet",
+            os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0),
+            dir_fd=data_fd,
+        )
+        opened = os.fstat(table_fd)
+        named = os.stat("table.parquet", dir_fd=data_fd, follow_symlinks=False)
+        if not _is_regular_single_link(opened) or _stat_signature(opened) != _stat_signature(named):
+            raise _TableUnavailable("table member is not a stable regular file")
+        descriptor_path = (
+            f"/dev/fd/{table_fd}" if sys.platform == "darwin" else f"/proc/self/fd/{table_fd}"
+        )
+        command = (
+            ["open", "-R", descriptor_path]
+            if sys.platform == "darwin"
+            else ["xdg-open", descriptor_path]
+        )
+        # The child inherits the already-open table descriptor. A same-UID actor may replace the
+        # public pathname before launch, but cannot redirect this descriptor-backed target.
+        subprocess.Popen(
+            command,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            pass_fds=(table_fd,),
+        )
+        try:
+            lease.validate()  # type: ignore[attr-defined]
+        except Exception as exc:
+            raise _TableUnavailable("table changed while opening its location") from exc
+    finally:
+        if table_fd >= 0:
+            os.close(table_fd)
+        if data_fd >= 0:
+            os.close(data_fd)
+        for lease in retained:
+            lease.close()  # type: ignore[attr-defined]
+
+
+class _ViewerHandler(BaseHTTPRequestHandler):
+    def log_message(self, *_args: object) -> None:
+        return
+
+    @property
+    def _state(self) -> _ViewerState:
+        return self.server.viewer_state  # type: ignore[attr-defined]
+
+    def do_GET(self) -> None:
+        if not self._request_targets_this_loopback_server():
+            self.send_error(421)
+            return
+        parsed = urlsplit(self.path)
+        if parsed.path == "/":
+            self._serve_index(parse_qs(parsed.query))
+        elif parsed.path == "/snapshot":
+            self._serve_snapshot(parse_qs(parsed.query))
+        elif parsed.path == "/health":
+            self._write_json(200, self._state.notice())
+        elif parsed.path == "/events":
+            self._serve_events()
+        elif parsed.path == "/download/table.parquet":
+            self._serve_table()
+        elif parsed.path == "/rows":
+            self._serve_rows(parse_qs(parsed.query))
+        else:
+            self.send_error(404)
+
+    def do_POST(self) -> None:
+        if not self._request_targets_this_loopback_server():
+            self.send_error(421)
+            return
+        if urlsplit(self.path).path != "/open-files":
+            self.send_error(404)
+            return
+        candidate_digest = self._state.handoff_candidate_digest()
+        if candidate_digest is None:
+            location = (
+                self._state.run_dir
+                if self._state._run_directory_exists()
+                else self._state.target.selected_path.parent
+            )
+            command = (
+                ["open", str(location)] if sys.platform == "darwin" else ["xdg-open", str(location)]
+            )
+            try:
+                subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            except OSError:
+                self._write_json(500, {"ok": False})
+                return
+        else:
+            try:
+                _reveal_verified_table(
+                    self._state,
+                    expected_candidate_digest=candidate_digest,
+                )
+            except _TableUnavailable:
+                self._write_json(409, {"ok": False})
+                return
+            except OSError:
+                self._write_json(500, {"ok": False})
+                return
+        self._write_json(200, {"ok": True})
+
+    def _request_targets_this_loopback_server(self) -> bool:
+        """Reject DNS-rebound and cross-origin access to local run contents."""
+
+        bound_port = int(self.server.server_address[1])
+        try:
+            bound_address = ipaddress.ip_address(str(self.server.server_address[0]))
+        except ValueError:
+            return False
+
+        def local_authority(value: str, *, origin: bool) -> bool:
+            try:
+                parsed = urlsplit(value if origin else f"//{value}")
+                hostname = parsed.hostname
+                port = parsed.port
+            except ValueError:
+                return False
+            if parsed.username is not None or parsed.password is not None:
+                return False
+            if hostname is None or port != bound_port:
+                return False
+            if hostname == "localhost":
+                return bound_address.is_loopback
+            try:
+                requested = ipaddress.ip_address(hostname)
+            except ValueError:
+                return False
+            return requested.is_loopback and requested == bound_address
+
+        host = self.headers.get("Host")
+        if host is None or not local_authority(host, origin=False):
+            return False
+        origin = self.headers.get("Origin")
+        return origin is None or local_authority(origin, origin=True)
+
+    def _write_html(self, status: int, markup: str) -> None:
+        body = markup.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _write_json(self, status: int, value: object) -> None:
+        body = json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    @staticmethod
+    def _requested(query: dict[str, list[str]]) -> str:
+        value = query.get("doc", ["table"])[0]
+        return value if value in _DOCUMENTS else "table"
+
+    @staticmethod
+    def _version(query: dict[str, list[str]]) -> int | None:
+        if "version" not in query:
+            return None
+        try:
+            value = int(query["version"][0])
+        except (IndexError, TypeError, ValueError) as exc:
+            raise KeyError("malformed snapshot version") from exc
+        if value < 0:
+            raise KeyError(value)
+        return value
+
+    def _serve_index(self, query: dict[str, list[str]]) -> None:
+        entry, health, lifecycle = self._state.presentation()
+        shell, active, docs = _render_snapshot(
+            entry,
+            self._requested(query),
+            allow_table=bool(lifecycle.get("handoff")),
+        )
+        markup = _workbench_document(
+            shell,
+            run_name=self._state.run_dir.name,
+            active=active,
+            docs=docs,
+            version=entry.version,
+            epoch=self._state.epoch,
+            health=health,
+            visual_cursor=entry.visual_cursor,
+            lifecycle=lifecycle,
+        )
+        self._write_html(200, markup)
+
+    def _serve_snapshot(self, query: dict[str, list[str]]) -> None:
+        try:
+            version = self._version(query)
+            cursor_values = query.get("cursor")
+            if cursor_values is not None:
+                if version is not None or len(cursor_values) != 1:
+                    raise KeyError("snapshot accepts one coordinate")
+                cursor = int(cursor_values[0])
+                entry, health, lifecycle = self._state.presentation_cursor(cursor)
+            else:
+                entry, health, lifecycle = self._state.presentation(version)
+        except (KeyError, ValueError):
+            self.send_error(404, "snapshot version does not exist")
+            return
+        except LookupError:
+            self.send_error(410, "snapshot version is no longer retained")
+            return
+        shell, active, docs = _render_snapshot(
+            entry,
+            self._requested(query),
+            allow_table=bool(lifecycle.get("handoff")),
+        )
+        self._write_json(
+            200,
+            {
+                "epoch": self._state.epoch,
+                "version": entry.version,
+                "cursor": entry.visual_cursor,
+                "doc": active,
+                "docs": docs,
+                "html": shell,
+                "mutation": (
+                    {key: value for key, value in entry.mutation.items() if key != "phase_start"}
+                    if entry.mutation is not None
+                    else None
+                ),
+                "health": health,
+                "lifecycle": lifecycle,
+            },
+        )
+
+    def _serve_table(self) -> None:
+        candidate_digest = self._state.handoff_candidate_digest()
+        if candidate_digest is None:
+            self.send_error(409, "table handoff is not complete")
+            return
+        try:
+            source, size = _verified_table_snapshot(
+                self._state,
+                expected_candidate_digest=candidate_digest,
+            )
+        except _TableUnavailable:
+            status = 404 if not (self._state.run_dir / "candidate").exists() else 409
+            self.send_error(status, "table is not ready as a verified snapshot")
+            return
+        with source:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/vnd.apache.parquet")
+            self.send_header("Content-Disposition", 'attachment; filename="table.parquet"')
+            self.send_header("Content-Length", str(size))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            while True:
+                chunk = source.read(_READ_CHUNK_BYTES)
+                if not chunk:
+                    break
+                self.wfile.write(chunk)
+
+    def _serve_rows(self, query: dict[str, list[str]]) -> None:
+        candidate_digest = self._state.handoff_candidate_digest()
+        if candidate_digest is None:
+            self.send_error(409, "table handoff is not complete")
+            return
+        try:
+            parquet_raw, evidence = _verified_query_snapshot(
+                self._state,
+                expected_candidate_digest=candidate_digest,
+            )
+            columns = tuple(
+                item for value in query.get("columns", []) for item in value.split(",") if item
+            )
+            if not columns:
+                columns = sealed_parquet_columns(parquet_raw, evidence=evidence)
+            filters_value = json.loads(query.get("filters", ["[]"])[0])
+            if not isinstance(filters_value, list):
+                raise QueryError("QUERY_FILTER", "filters must be an array")
+            payload = query_sealed_parquet(
+                parquet_raw,
+                columns=columns,
+                predicates=filters_value,
+                offset=int(query.get("offset", ["0"])[0]),
+                limit=int(query.get("limit", ["50"])[0]),
+                evidence=evidence,
+            )
+        except _TableUnavailable:
+            self.send_error(409, "table changed while opening its verified snapshot")
+            return
+        except (QueryError, ValueError, json.JSONDecodeError) as exc:
+            self.send_error(400, str(exc))
+            return
+        self._write_json(200, payload)
+
+    def _serve_events(self) -> None:
+        if self._state._visual_transport is not None:
+            self._serve_visual_events()
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.end_headers()
+        server = self.server
+        server.register_stream(self.connection)  # type: ignore[attr-defined]
+        last: tuple[object, ...] | None = None
+        sent_version: int | None = None
+        sent_documents: dict[str, bytes] | None = None
+        try:
+            while not getattr(self.server, "viewer_stopped", False):
+                # The viewer is intentionally allowed to open before an agent creates the
+                # durable visual-run log.  Discover it from this live request as well as from the
+                # watcher, then continue on the same EventSource connection.  Closing the legacy
+                # response and relying on browser reconnection left already-open pages stale until
+                # refresh when the first visual event appeared during unrelated watcher work.
+                self._state._refresh_visual_notebook()
+                transport = self._state._visual_transport
+                if transport is not None:
+                    self._stream_visual_events(transport, cursor=0)
+                    return
+                notice, current = self._state.wait_for_notice(last, _POLL_SECONDS)
+                transport = self._state._visual_transport
+                if transport is not None:
+                    self._stream_visual_events(transport, cursor=0)
+                    return
+                if current != last:
+                    last = current
+                    current_version = int(notice["version"])
+                    versions = [current_version]
+                    if sent_version is not None and current_version > sent_version:
+                        retained = self._state.versions()
+                        versions = [
+                            version
+                            for version in retained
+                            if sent_version < version <= current_version
+                        ]
+                    for version in versions:
+                        versioned = dict(notice)
+                        versioned["version"] = version
+                        try:
+                            entry = self._state.snapshot(version)
+                        except (KeyError, LookupError):
+                            continue
+                        versioned["docs"] = list(entry.documents)
+                        versioned["changed_docs"] = [
+                            name
+                            for name in _DOCUMENTS
+                            if sent_documents is None
+                            or sent_documents.get(name) != entry.documents.get(name)
+                        ]
+                        payload = json.dumps(versioned, separators=(",", ":"))
+                        self.wfile.write(f"data: {payload}\n\n".encode())
+                        sent_documents = entry.documents
+                    sent_version = current_version
+                else:
+                    self.wfile.write(b": ping\n\n")
+                self.wfile.flush()
+                time.sleep(_POLL_SECONDS)
+        except (BrokenPipeError, ConnectionResetError, OSError, VisualRunError):
+            return
+        finally:
+            server.unregister_stream(self.connection)  # type: ignore[attr-defined]
+
+    def _serve_visual_events(self) -> None:
+        transport = self._state._visual_transport
+        assert transport is not None
+        try:
+            cursor = parse_last_event_id(self.headers.get("Last-Event-ID"))
+            transport.events_after(cursor, limit=1)
+        except VisualRunError:
+            self.send_error(409, "visual event cursor is invalid")
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.end_headers()
+        server = self.server
+        server.register_stream(self.connection)  # type: ignore[attr-defined]
+        try:
+            self._stream_visual_events(transport, cursor=cursor)
+        except (BrokenPipeError, ConnectionResetError, OSError, VisualRunError):
+            return
+        finally:
+            server.unregister_stream(self.connection)  # type: ignore[attr-defined]
+
+    def _stream_visual_events(self, transport: VisualRunTransport, *, cursor: int) -> None:
+        """Multiplex durable visual cursors and ordinary viewer state on one live SSE."""
+
+        server = self.server
+        _, last_notice = self._state.wait_for_notice(None, 0)
+        sent_documents = self._state.snapshot().documents
+        while not getattr(server, "viewer_stopped", False):
+            try:
+                page = transport.events_after(cursor, limit=1)
+            except VisualRunError:
+                self._state.poll(refresh_operational=False)
+                self._write_visual_health_notice()
+                return
+            if page.events:
+                # Admit the corresponding reduced state before publishing its cursor.  The
+                # browser can therefore request /snapshot?cursor=N without racing the watcher.
+                self._state.poll(refresh_operational=False)
+                for event in page.events:
+                    if not self._state.visual_cursor_is_admitted(event.sequence):
+                        # Another request may currently own the non-blocking projection lock.
+                        # Keep the durable cursor unannounced until that projection finishes.
+                        if self._state.health["status"] == "stopped":
+                            self._write_visual_health_notice()
+                            return
+                        self.wfile.write(b": waiting for visual projection\n\n")
+                        break
+                    cursor = event.sequence
+                    payload = json.dumps(
+                        {"cursor": cursor, "visual_event": event.to_mapping()},
+                        separators=(",", ":"),
+                    )
+                    self.wfile.write(f"id: {cursor}\ndata: {payload}\n\n".encode())
+            notice, current_notice = self._state.wait_for_notice(last_notice, 0)
+            notice_cursor = int(notice.get("cursor", 0))
+            if current_notice != last_notice and notice_cursor <= cursor:
+                documents = self._state.snapshot().documents
+                notice["changed_docs"] = [
+                    name for name in _DOCUMENTS if sent_documents.get(name) != documents.get(name)
+                ]
+                payload = json.dumps(notice, separators=(",", ":"))
+                self.wfile.write(f"data: {payload}\n\n".encode())
+                sent_documents = documents
+                last_notice = current_notice
+            elif not page.events:
+                self.wfile.write(b": ping\n\n")
+            self.wfile.flush()
+            time.sleep(_POLL_SECONDS)
+
+    def _write_visual_health_notice(self) -> None:
+        """Tell an already-open visual client why projection stopped before closing SSE."""
+
+        notice = self._state.notice()
+        payload = json.dumps(notice, separators=(",", ":"))
+        self.wfile.write(f"data: {payload}\n\n".encode())
+        self.wfile.flush()
+
+
+def _watch_loop(server: _ViewerServer) -> None:
+    try:
+        while not server.viewer_stopped:
+            server.viewer_state.poll()
+            time.sleep(_WATCH_POLL_SECONDS)
+    except Exception:
+        server.viewer_state.mark_watcher_failed()
+
+
+def _build_server(target: ViewerTarget | Path, host: str, port: int) -> tuple[_ViewerServer, str]:
+    address = ipaddress.ip_address(host)
+    if not address.is_loopback:
+        raise ValueError("mr-data view must bind to a loopback address")
+    state = _ViewerState(target)
+    server_type = _ViewerServerV6 if address.version == 6 else _ViewerServer
+    # ``TCPServer.__init__`` calls ``server_close`` if binding fails. The server receives ownership
+    # of ``state`` before its base initializer starts, so that partial-construction cleanup closes
+    # the retained descriptors without replacing the original socket error.
+    server = server_type((address.compressed, port), _ViewerHandler, state)
+    bound_host = str(server.server_address[0])
+    url_host = f"[{bound_host}]" if address.version == 6 else bound_host
+    url = f"http://{url_host}:{server.server_address[1]}/"
+    server.viewer_watcher = threading.Thread(target=_watch_loop, args=(server,), daemon=True)
+    server.viewer_watcher.start()
+    return server, url
+
+
+def serve_notebook(
+    target: ViewerTarget | Path,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    open_browser: bool = False,
+    announce: Callable[[str], None] | None = None,
+) -> None:
+    """Serve a local run's notebooks as a streaming, read-only visual workbench."""
+
+    server, url = _build_server(target, host, port)
+    if announce is None:
+        print(f"mr-data view: serving {url} (Ctrl-C to stop)", flush=True)
+    else:
+        announce(url)
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.viewer_stopped = True
+        server.close_streams()
+        if server.viewer_watcher is not None:
+            # The watcher reads notebooks through descriptors ``server_close`` releases with the
+            # state, so it is given a moment to see the stop flag first. A watcher still inside a
+            # long verification is left to the daemon flag rather than waited on.
+            server.viewer_watcher.join(timeout=_WATCHER_STOP_SECONDS)
+        server.server_close()