mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/watch.py

@@ -0,0 +1,2999 @@
+"""The live run view for ``mr-data watch``: a localhost page that tails one run's event feed.
+
+Watch is the live run view; the notebook sidecar (``mr-data view``) is the finished dataset view.
+They share HTTP serving conventions but no files. Watch uses ``ThreadingHTTPServer``, an ephemeral
+loopback port, a 0.25 s SSE poll, and a disabled access log.
+
+Watch is a spectator. No route on this server mutates anything, and there is no POST handler at
+all: v1 approval is display-only, and the ABSENCE of a mutating route is the mitigation for the
+approval-authority threat. Nothing here writes to the run directory, to ``state.json``, or to the
+feed; deleting the feed loses nothing but the show.
+
+One thing is fixed here that the merged viewer still gets wrong: rendering on the request thread.
+Watch is ALWAYS reading a file another process is appending to, so the watcher thread reads, parses
+and renders, and the handler only writes bytes it was handed and cannot fail on bad feed bytes.
+"""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import hmac
+import ipaddress
+import json
+import os
+import re
+import socket
+import threading
+import time
+import urllib.parse
+import webbrowser
+from collections.abc import Callable, Mapping, Sequence
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, NamedTuple
+
+from mostlyright.data_harness import events
+from mostlyright.data_harness.event_presentation import (
+    EVENT_SENTENCES as _EVENT_SENTENCES,
+)
+from mostlyright.data_harness.event_presentation import (
+    STAGE_RAIL,
+    STOPPED_EVENTS,
+    sentence,
+)
+from mostlyright.data_harness.nbrender.parse import esc
+
+EVENT_SENTENCES = _EVENT_SENTENCES
+
+# Keep the live-run palette independent of notebook renderer imports.
+PAPER = "#F5F2EB"  # page ground
+SUB_PAPER = "#FAF8F3"  # card fill
+SURFACE = "#EDE9DF"  # rail fill, command block fill
+BORDER = "#E2DDD0"  # every 1px border
+INK = "#17160F"  # headings, reached labels
+BODY = "#3B382F"  # body text
+MUTED = "#57534A"  # secondary text
+FAINT = "#6E6959"  # tertiary text, unreached labels
+DIM = "#837D6E"  # the "receipt appears later" note
+COBALT = "#2B5FE3"  # links, reached marks, the copy button
+ORANGE = "#F15B22"  # a build that stopped
+FONT_SANS = '"Space Grotesk", "Helvetica Neue", sans-serif'
+FONT_MONO = '"JetBrains Mono", Menlo, monospace'
+
+# The watcher and SSE loop use the same interval.
+_POLL_SECONDS = 0.25
+
+# The manifest is a file another local user may have written. Read it with a ceiling rather than
+# allocating whatever is on disk.
+_MAX_MANIFEST_BYTES = 4 * 1024 * 1024
+
+# These errnos mean the candidate path is absent, not a directory, or a symlink. Other errors fail
+# the current poll without invalidating an already pinned descriptor.
+_NAME_HOLDS_NO_CANDIDATE = frozenset({errno.ENOENT, errno.ENOTDIR, errno.ELOOP})
+
+# `manifest.json` is a real file inside the run but is NOT one of `manifest["members"]` -- a
+# manifest cannot carry its own digest -- so the member set carries it explicitly.
+_MANIFEST_NAME = "manifest.json"
+
+# The ceiling on a single served receipt. Every member of a real run is far below it; the cap
+# exists because the run directory is a place another local user can write (T-30-24).
+MAX_RECEIPT_BYTES = 2 * 1024 * 1024
+
+# Proving a member is the file the run recorded means hashing it, and a dataset is the one member
+# that can be large. It is read in chunks so the cost is time and not memory.
+_MEMBER_HASH_CHUNK_BYTES = 1024 * 1024
+
+# Bound the total bytes and member count verified in one pass. Members are considered in manifest
+# order; a member larger than the remaining byte budget is skipped.
+MAX_VERIFIED_TOTAL_BYTES = 256 * 1024 * 1024
+MAX_MANIFEST_MEMBERS = 4096
+
+# A settled run must still notice a member changed without turning the maximum accepted receipt
+# into a permanent syscall budget. Page-authoritative members are checked every tick; the rest are
+# walked as a rotating slice, so every accepted member is revisited within a bounded number of
+# ticks while one tick never opens all 4,096. Receipt requests remain stronger still: they hash the
+# requested bytes synchronously and never serve from this change-detection cache.
+MAX_SETTLED_MEMBER_PROBES_PER_POLL = 256
+
+# These members can change the main page's cards, approval decision, rail, or fixed event receipts.
+# They stay outside the rotating delay. The event mapping is the normative source for build-step
+# evidence; the five authored/governance records are the pre-build surface declared by STAGE_RAIL.
+_PAGE_AUTHORITY_MEMBERS = frozenset(events.EVIDENCE_MEMBER.values()) | frozenset(
+    {
+        "question.json",
+        "requirements.json",
+        "source-proposals.json",
+        "recipe.json",
+        "recipe-approval.json",
+    }
+)
+
+# The pacing clamp for `--replay`: a run that sat idle overnight must not make a demo sit idle
+# overnight, so no released gap is ever longer than this before the speed divisor is applied.
+MAX_REPLAY_GAP_SECONDS = 5.0
+
+# A rederived feed has no clock -- every projected record carries `at: 0.0` -- so a rederived
+# replay chooses a readable rhythm rather than inventing timings it does not have.
+REDERIVED_REPLAY_STEP_SECONDS = 0.35
+
+# The four refusal sentences. Plain language, no internal vocabulary, and -- for the two tamper
+# cases -- deliberately identical, so a refusal never tells a prober WHICH check it failed.
+_NOT_FINISHED = "This build has not finished yet, so there is no receipt to show."
+_NOT_A_RECEIPT = "This build has no receipt by that name."
+_NOT_THE_RECORDED_FILE = "The file on disk is not the file this build recorded, so it is not shown."
+_TOO_LARGE = "This receipt is too large to show here."
+
+# The member-path character class, copied deliberately from `events._MEMBER_PATH_RE` rather than
+# imported: a manifest is a file on disk that another local user may have written, so the member
+# names it offers are untrusted strings even though they arrive through the run's own receipt.
+_MEMBER_PATH_RE = re.compile(r"\A[A-Za-z0-9._/-]{1,128}\Z")
+
+# The shape a recorded SHA-256 digest has: 64 lowercase hex characters, which is what
+# `hashlib.sha256(...).hexdigest()` and `canonical.sha256_bytes` produce and therefore the only
+# string a recorded digest can be.
+_HEX_DIGEST_RE = re.compile(r"\A[0-9a-f]{64}\Z")
+
+
+def _is_member_path(value: Any) -> bool:
+    """True when ``value`` is a candidate-relative member path and nothing else."""
+
+    if not isinstance(value, str) or not _MEMBER_PATH_RE.match(value):
+        return False
+    if value.startswith("/") or ".." in value.split("/"):
+        return False
+    return True
+
+
+def _is_recorded_digest(value: Any) -> bool:
+    """True when ``value`` is the shape a recorded SHA-256 digest has, and nothing else."""
+
+    return isinstance(value, str) and _HEX_DIGEST_RE.match(value) is not None
+
+
+def _matches_digest(found: Any, recorded: Any) -> bool:
+    """Return whether both values are lowercase SHA-256 digests with equal bytes.
+
+    Validate both operands first because ``hmac.compare_digest`` raises for non-ASCII strings.
+    Invalid values are verification failures.
+    """
+
+    return (
+        _is_recorded_digest(found)
+        and _is_recorded_digest(recorded)
+        and hmac.compare_digest(found, recorded)
+    )
+
+
+# Shared nonblocking, no-follow regular-file opener.
+_open_regular_member = events.open_regular_file
+
+
+def _writable_path_text(value: str | os.PathLike[str]) -> str:
+    """Return a path, or one component of it, as text a served page can actually encode.
+
+    The run-directory name is also a display-string boundary. ``cli`` hands
+    ``resolve_target`` whatever ``os.fsdecode`` made of ``argv``, POSIX decodes an argument that is
+    not valid UTF-8 through ``surrogateescape``, and ``mr-data watch /data/runs/caf<0xe9>-run`` puts
+    ``'caf\\udce9-run'`` into ``_render_header``'s "Build:" line on EVERY page and into
+    ``approve_command``'s copyable line -- with no member, no feed and no adversary. The directory
+    need not exist when the watcher starts.
+
+    ``render_page`` does not encode the result. Invalid text would let polling succeed and then make
+    ``_write_html`` fail during
+    ``markup.encode("utf-8")`` BEFORE ``send_response``, inside the handler thread where
+    ``BaseHTTPRequestHandler`` has no ``except``; ``/events`` keeps writing version frames and the
+    tab's ``fetch('/')`` rejects into the live script's empty ``.catch``. ``/`` is dead for the life
+    of the server and the page says nothing.
+
+    Apply ``events.writable_text`` at this boundary, not in ``_write_html``. It changes display
+    text, never the ``Path``: every filesystem
+    call in this module goes through a descriptor opened from the real name, so a directory whose
+    name really does carry those bytes is still read, and only what a page writes is bounded.
+    """
+
+    # This is display-only path algebra.  ``os.fspath`` made the source gate classify the
+    # conversion itself as a filesystem lookup even though no name is resolved here.
+    return events.writable_text(str(value))
+
+
+def _file_identity(info: os.stat_result) -> tuple[int, int, int, int, int]:
+    """Bind a digest proof to the file snapshot it measured.
+
+    Size and mtime are writer-controlled and therefore only hints.  POSIX ctime is the invalidation
+    token here: ordinary file APIs advance it for a content, mode, link or timestamp change and do
+    not let that writer restore its old value.  The digest remains the proof of bytes; this tuple
+    says when that proof must be paid again.
+    """
+
+    return (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns)
+
+
+def _feed_rejection_proof(
+    path: Path,
+) -> tuple[str, tuple[int, int, int, int, int], str] | None:
+    """Return stable identity plus bounded content evidence for one rejected feed snapshot.
+
+    Size alone cannot identify bytes: an atomic replacement may carry a valid feed of the exact
+    same length. The cache therefore binds both descriptor identity and a digest of the bounded
+    bytes read from that descriptor. A file that changes during the read earns no reusable proof.
+    """
+
+    try:
+        descriptor = events.open_regular_file(path)
+    except OSError:
+        return None
+    try:
+        identity_before = _file_identity(os.fstat(descriptor))
+        remaining = events.MAX_FEED_BYTES + 1
+        digest = hashlib.sha256()
+        while remaining:
+            chunk = os.read(descriptor, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            digest.update(chunk)
+            remaining -= len(chunk)
+        identity_after = _file_identity(os.fstat(descriptor))
+    except OSError:
+        return None
+    finally:
+        os.close(descriptor)
+    if identity_after != identity_before:
+        return None
+    # Display/cache-key conversion only. The descriptor open above is the sole name resolution.
+    return str(path), identity_after, digest.hexdigest()
+
+
+class ReceiptRefused(Exception):
+    """A receipt could not be served. Carries the status and the one plain sentence to show.
+
+    Every refusal renders a page with the sentence and NOTHING of the file's content: a member
+    whose bytes do not match the digest the run recorded has already failed the only test that
+    makes it a receipt, and showing it anyway would be showing an unlabelled claim.
+    """
+
+    def __init__(self, status: int, sentence: str) -> None:
+        super().__init__(sentence)
+        self.status = status
+        self.sentence = sentence
+
+
+class _Target(NamedTuple):
+    """The two directories a watcher needs: the run it describes and the feed it tails."""
+
+    run_dir: Path
+    feed_dir: Path
+
+
+def resolve_target(run_dir: str | os.PathLike[str]) -> _Target:
+    """Return ``(run_dir, feed_dir)`` for a run directory.
+
+    The feed lives in the runs PARENT (``events.run_feed_dir`` puts it there), because a failed
+    build has no run directory at all and a file inside the run directory would be a new file
+    inside a closed member set. It is scoped by the run's own name, so a sibling run's feed is not
+    in this directory and cannot be mistaken for this run's. Neither directory need exist: the
+    primary scenario is a watcher started BEFORE the build, when neither does.
+    """
+
+    resolved = Path(run_dir).absolute()
+    return _Target(resolved, events.run_feed_dir(resolved))
+
+
+class _WatchState:
+    """Everything the request path must not do: read the feed, parse it, and render the page.
+
+    The member set is an INPUT to each render, not a property of the server, because the run it
+    describes does not exist yet when the server starts. ``poll`` passes the current value on every
+    render and never a value captured at construction.
+    """
+
+    def __init__(
+        self,
+        target: _Target | str | os.PathLike[str],
+        *,
+        replay: float | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.target = target if isinstance(target, _Target) else resolve_target(target)
+        self.run_dir = self.target.run_dir
+        self.feed_dir = self.target.feed_dir
+
+        self._lock = threading.Lock()
+        self._version = 0
+        self._last_seq = 0
+        # A page before any I/O has happened: `render_page` reads no file of its own, so this
+        # cannot raise, and a request that arrives before the first poll gets a document rather
+        # than an empty body.
+        self._html = render_page(
+            [], run_dir=self.run_dir, members_present=frozenset(), now=time.time()
+        )
+        # The last render that SUCCEEDED, with no stall note spliced into it. `_html` is what a
+        # request is served and may carry the note; this is what the note is spliced onto, so a
+        # stall that lasts a thousand polls still yields one note and not a thousand.
+        self._good_html = self._html
+        self._offset = 0  # bytes of the last successfully parsed feed read
+        self._fingerprint: tuple[Any, ...] | None = None
+        self._rejected_feed: tuple[str, tuple[int, int, int, int, int], str] | None = None
+        self._failed_polls = 0
+        # The class name of the last failure, or None while the last poll cycle completed. Only the
+        # NAME: an exception's message can carry bytes off disk, and this one is rendered.
+        self._failure_reason: str | None = None
+
+        self._manifest: Mapping[str, Any] | None = None
+        self._members_present: frozenset[str] = frozenset()
+        self._member_index: dict[str, Mapping[str, Any]] = {}
+        self._candidate_fd: int | None = None
+        self._candidate_identity: tuple[int, int] | None = None
+        self._manifest_file_identity: tuple[int, int, int, int, int] | None = None
+        # True when a manifest is on disk and does NOT carry its own fingerprint. Distinct from
+        # "no manifest yet", which is every run before it exists. It is a verdict about the bytes
+        # THIS poll read, so it is re-derived like every other one and never held past a poll that
+        # found the file intact again.
+        self._manifest_disowned = False
+        # The members this reader has PROVED under the currently pinned candidate, and the ones it
+        # has read whole and found not to be what the run recorded. Between them and the manifest's
+        # own index they say whether the answer is complete; see `_refresh_run`.
+        self._verified: dict[str, tuple[int, int, int, int, int]] = {}
+        self._measured_wrong: dict[str, tuple[int, int, int, int, int] | None] = {}
+        self._settled_probe_cursor = 0
+
+        # Replay state. `replay` is None for a live watch and a positive speed multiplier for a
+        # paced one; the released count is the only thing pacing changes, so live and paced share
+        # one renderer, one channel and one code path.
+        self._replay = replay
+        self._clock = clock
+        self._released = 0
+        self._released_at: float | None = None
+        # The records the last successful rederivation returned, retained only with the complete
+        # descriptor-relative proof beside them. A changed candidate, manifest, member decision,
+        # or directory namespace makes the pair unusable; refusals are never retained.
+        self._rederived: list[dict[str, Any]] | None = None
+        self._rederived_proof: tuple[Any, ...] | None = None
+        self._records_source = "none"
+
+        try:
+            self.poll()
+        except BaseException:
+            # `poll` may have adopted the candidate directory before a process-level exception.
+            # The caller cannot close an object whose constructor never returned, so ownership
+            # has to unwind here. Cleanup is secondary and must not replace the initiating error.
+            try:
+                self.close()
+            except BaseException:
+                pass
+            raise
+
+    # -- reads -----------------------------------------------------------------------------------
+
+    def snapshot(self) -> tuple[int, int, str]:
+        """Return one consistent ``(version, last_seq, html)`` snapshot.
+
+        Every ``_html`` update increments ``_version`` so open clients observe page changes.
+        """
+
+        with self._lock:
+            return self._version, self._last_seq, self._html
+
+    def evidence_index(self) -> tuple[Mapping[str, Any] | None, frozenset[str]]:
+        """Return the memoized manifest and member set as a CONSISTENT pair, under the lock."""
+
+        with self._lock:
+            return self._manifest, self._members_present
+
+    def members_present(self) -> frozenset[str]:
+        """The member paths this run carries, or an empty set before the manifest exists."""
+
+        return self.evidence_index()[1]
+
+    def member_index(self) -> dict[str, Mapping[str, Any]]:
+        """The run's own allowlist: member path to the entry the run recorded for it.
+
+        This is an ALLOWLIST, never a path sanitizer. A sanitizer is a list of attacks someone
+        thought of; an allowlist is the set of files this run actually recorded. A name that is not
+        a key here never reaches the filesystem at all (T-30-21).
+        """
+
+        with self._lock:
+            return dict(self._member_index)
+
+    def recorded_digests(self) -> dict[str, str]:
+        """Return each member path and the SHA-256 recorded in the manifest."""
+
+        return {
+            member: entry["sha256"]
+            for member, entry in self.member_index().items()
+            if _is_recorded_digest(entry.get("sha256"))
+        }
+
+    def _duplicate_candidate_fd(self) -> int | None:
+        """Own a stable reference to the pinned candidate, or return ``None``.
+
+        Reading the integer under the lock is not ownership.  Another thread may drop the run,
+        close that descriptor and let the kernel reuse the same number before an ``openat`` uses
+        it.  Duplication happens while the retained descriptor is protected by the same lock that
+        detaches it in ``_drop_run``; the caller then owns an independent reference and must close
+        it after its complete descriptor-rooted operation.
+        """
+
+        with self._lock:
+            if self._candidate_fd is None:
+                return None
+            try:
+                return events.duplicate_directory(self._candidate_fd)
+            except OSError:
+                # A descriptor-pressure failure is a fact about this read, not about the run.
+                return None
+
+    # -- the verified read ------------------------------------------------------------------------
+
+    def read_member(self, member: str, cited: str | None = None) -> bytes:
+        """Return one member's bytes, or raise ``ReceiptRefused`` with the sentence to show.
+
+        The order is the whole security argument and it does not commute: resolve the name against
+        the run's own allowlist FIRST, then open relative to the retained directory descriptor,
+        then hash, then compare. A name that fails the allowlist causes no filesystem call, and a
+        file whose bytes fail their fingerprint renders nothing.
+        """
+
+        manifest, _members = self.evidence_index()
+        if manifest is None:
+            with self._lock:
+                disowned = self._manifest_disowned
+            # Two different facts, and they must not be told as one. A run that does not exist has
+            # no receipt YET; a run whose receipt is not its own receipt has failed the only test
+            # that makes it a receipt, and that reads exactly like a member whose bytes changed --
+            # same status, same sentence -- so a refusal never tells a prober which check it failed.
+            if disowned:
+                raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+            raise ReceiptRefused(404, _NOT_FINISHED)
+
+        if member == _MANIFEST_NAME:
+            # ONE named branch, taken before the allowlist lookup, and not a special case a later
+            # reader may tidy away. `manifest.json` is NOT an entry in `manifest["members"]` and
+            # structurally cannot be: `members` is built from the expected file set and the
+            # manifest is written afterwards, so a file would have to contain its own fingerprint.
+            # Looking it up in the allowlist therefore returns nothing, and comparing it against
+            # "the recorded fingerprint" compares against a value that does not exist.
+            return self._verify_manifest_self(self._read_member_bytes(_MANIFEST_NAME), cited)
+
+        entry = self.member_index().get(member)
+        if entry is None:
+            raise ReceiptRefused(404, _NOT_A_RECEIPT)
+        recorded = entry.get("sha256")
+        if not _is_recorded_digest(recorded):
+            # Checked BEFORE the read so a receipt carrying a value that is not a digest costs no
+            # filesystem call and no hash, and reported as tamper because that is what it is.
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+
+        raw = self._read_member_bytes(member)
+        found = hashlib.sha256(raw).hexdigest()
+        if not _matches_digest(found, recorded):
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+        if cited is not None and not _matches_digest(found, cited):
+            # `cited` came off the query string, so it is the least trusted value on this path.
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+        return raw
+
+    def _read_member_bytes(self, member: str) -> bytes:
+        """Open ``member`` RELATIVE to the retained descriptor, never by string concatenation."""
+
+        fd = self._duplicate_candidate_fd()
+        if fd is None:
+            raise ReceiptRefused(404, _NOT_FINISHED)
+        try:
+            try:
+                handle_fd = _open_regular_member(member, dir_fd=fd)
+                with os.fdopen(handle_fd, "rb") as handle:
+                    raw = handle.read(MAX_RECEIPT_BYTES + 1)
+            except OSError as exc:
+                raise ReceiptRefused(404, _NOT_A_RECEIPT) from exc
+        finally:
+            os.close(fd)
+        if len(raw) > MAX_RECEIPT_BYTES:
+            raise ReceiptRefused(413, _TOO_LARGE)
+        return raw
+
+    def _durable_candidate_digest(self) -> str | None:
+        """The candidate digest the WORKSPACE durably recorded, or ``None`` when there is none.
+
+        The second authority, and the only one on this disk that is not the manifest talking about
+        itself. ``offline`` writes ``state['candidate']['candidate_digest']`` and re-checks it at
+        three linearization points, and an enrolled review binds it under a signature. ``watch``
+        consulted neither, which is why ``_verify_manifest_self`` proves coherence and not
+        authenticity.
+
+        Read through the hardened reader, relative to a descriptor for the workspace, so
+        ``.mr-data`` cannot be a symlink out of it. A run directory that is not a workspace's
+        ``result/`` simply has no such file, and this returns ``None``: absence of a second
+        authority is reported as absence, never as agreement.
+        """
+
+        _status, digest = self._durable_candidate_digest_status()
+        return digest
+
+    def _durable_candidate_digest_status(self) -> tuple[str, str | None]:
+        """Return ``(absent|unreadable|present, digest)`` for the workspace authority.
+
+        ``absent`` is deliberately not an approval verdict. It only distinguishes a workspace
+        without a durable authority from one whose authority is present but unreadable; callers
+        that need corroboration must require ``present`` and an agreeing digest. Otherwise deleting
+        the whole control directory -- including across a Watch restart -- manufactures approval.
+        """
+
+        try:
+            workspace_fd = events.open_directory(self.run_dir.parent)
+        except OSError:
+            return "unreadable", None
+        try:
+            try:
+                state_fd = events.open_directory(".mr-data", dir_fd=workspace_fd)
+            except OSError as exc:
+                if exc.errno == errno.ENOENT:
+                    return "absent", None
+                return "unreadable", None
+            try:
+                raw = events.read_regular_bytes(
+                    "state.json",
+                    dir_fd=state_fd,
+                    max_bytes=_MAX_MANIFEST_BYTES,
+                )
+            finally:
+                os.close(state_fd)
+            candidate = json.loads(raw.decode("utf-8")).get("candidate")
+        except (OSError, ValueError, AttributeError, RecursionError):
+            return "unreadable", None
+        finally:
+            os.close(workspace_fd)
+        digest = candidate.get("candidate_digest") if isinstance(candidate, Mapping) else None
+        if not _is_recorded_digest(digest):
+            return "unreadable", None
+        return "present", digest
+
+    def _approval_is_corroborated(self) -> bool:
+        """True only when the second authority corroborates the approval summary's receipt.
+
+        The summary is the one part of this page that talks a person into an action (T-30-27), and
+        the receipt underneath it proves only coherence: whoever writes ``manifest.json`` writes
+        its ``candidate_digest`` too, so an adversary who reseals is not detected by recomputing
+        it. This is the cross-check that is available -- the workspace's durable
+        ``state.json`` -- and its verdict is deliberately fail closed:
+
+        * the durable digest AGREES with the manifest's: render;
+        * the durable digest DISAGREES: render nothing, because two authorities on this disk
+          disagree about which candidate this is and a summary is a claim about a specific one;
+        * there is NO readable durable digest (a bare run directory or a workspace mid-write):
+          render no approval summary. Candidate-local bytes prove only their own coherence, and
+          process-local memory cannot distinguish a genuinely bare run from an authority an
+          attacker deleted before this Watch process started.
+
+        Nothing here is memoized, and the ANSWER is part of the poll's fingerprint. Those two are
+        one sentence, not two: a disagreement while the seal is mid-flight -- the candidate
+        directory renamed into place before ``state.json`` is republished -- must cost that render
+        and not that candidate, so the next poll asks again AND acts on a different answer. Asked
+        below the fingerprint gate, as an argument to ``render_page``, the next poll returned
+        before asking; see ``_poll_once``.
+        """
+
+        manifest, _members = self.evidence_index()
+        if manifest is None:
+            return False
+        durable_status, durable = self._durable_candidate_digest_status()
+        if durable_status != "present" or durable is None:
+            return False
+        # No shape check here: the comparator owns it, on both operands. A proof two methods away
+        # -- `_verify_manifest_self` refuses a manifest whose `candidate_digest` is not a digest
+        # before `self._manifest` is ever set -- is not a guard at the comparison.
+        return _matches_digest(manifest.get("candidate_digest"), durable)
+
+    def _verify_manifest_self(self, raw: bytes, cited: str | None) -> bytes:
+        """Verify that the run's receipt is COHERENT, by recomputing its fingerprint over itself.
+
+        COHERENCE, NOT AUTHENTICITY, and the difference is the whole reading of this method. The
+        seal computes the fingerprint over the receipt minus that one field, so verifying it means
+        doing exactly that again and comparing -- against a value in the same file, written by
+        whoever wrote the file. It detects an edit that forgot to reseal. It detects nothing at all
+        from an adversary who reseals, and the adversary this module names throughout is a local
+        user who can write the run directory (T-30-24), which is to say one who can reseal.
+
+        There is no other file inside the candidate that records this file's fingerprint, so this
+        is the strongest statement available from the candidate alone. The authority that is NOT
+        inside the candidate is the workspace's durable ``state.json``; see
+        ``_durable_candidate_digest`` and ``_approval_is_corroborated``, which is where the one
+        claim on this page that asks a person to act is gated on it.
+        """
+
+        # Deferred: `watch` must stay importable without pulling `pipeline` in at module load.
+        from mostlyright.data_harness.canonical import sha256_bytes
+        from mostlyright.data_harness.pipeline import canonical_json_line_bytes
+
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+            recorded = payload.pop("candidate_digest")
+        except (ValueError, TypeError, KeyError, AttributeError, RecursionError) as exc:
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE) from exc
+        if not _is_recorded_digest(recorded):
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+        try:
+            recomputed = sha256_bytes(canonical_json_line_bytes(payload))
+        except (TypeError, ValueError) as exc:
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE) from exc
+        if not _matches_digest(recomputed, recorded):
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+        if cited is not None and not _matches_digest(recorded, cited):
+            raise ReceiptRefused(409, _NOT_THE_RECORDED_FILE)
+        return raw
+
+    # -- the poll --------------------------------------------------------------------------------
+
+    def poll(self) -> None:
+        """Refresh run state, feed records, and rendered HTML when inputs change.
+
+        An exception increments failed-poll state and preserves the previous valid page. The page
+        reports the exception class and failure count.
+        """
+
+        try:
+            self._poll_once()
+        except Exception as exc:
+            self._record_failed_poll(exc)
+        else:
+            self._clear_failed_poll()
+
+    def _record_failed_poll(self, exc: BaseException) -> None:
+        """Count a cycle that could not complete, and say so on the page that stopped moving.
+
+        The version moves with the page. Splicing the note in without it left the note reachable
+        only by a hard reload: ``/events`` writes a ``data:`` frame when the version changes and a
+        comment ping otherwise, and a comment fires nothing in a browser, so the tab ``mr-data
+        watch`` opened -- the only view this command produces -- sat on a frozen page and was told
+        nothing. A note about a stall that the stalled page cannot deliver is not a note.
+        """
+
+        with self._lock:
+            self._failed_polls += 1
+            self._failure_reason = type(exc).__name__
+            self._html = _with_stall_note(self._good_html, self._failed_polls, self._failure_reason)
+            self._version += 1
+
+    def _clear_failed_poll(self) -> None:
+        """Take the note off once a cycle completes again.
+
+        Cleared on a COMPLETED cycle, not on a fresh render: most polls change nothing and return
+        early by design, and a page that only recovered when something new happened would keep
+        telling a reader it was stuck long after it had started reading again.
+
+        The count is not reset. It is the accounting of how many reads of this run have failed, and
+        that is a fact about the run, not about the current streak.
+
+        The version moves here for the same reason it moves when the note goes on: a tab that was
+        told the page had stopped must be told it started again, or the note outlives the stall.
+        """
+
+        with self._lock:
+            if self._failure_reason is None:
+                return
+            self._failure_reason = None
+            self._html = self._good_html
+            self._version += 1
+
+    def _poll_once(self) -> None:
+        """One poll cycle. Every raise it can produce is caught by ``poll``."""
+
+        self._refresh_run()
+        # This verdict is asked on every cycle, before any feed memo can return.  A rejected feed
+        # may suppress another read of the same bad bytes, but it cannot freeze the authority that
+        # decides whether the approval summary is safe to show.
+        corroborated = self._approval_is_corroborated()
+
+        path, size, records = self._current_feed()
+        key = None if path is None else (str(path), size)
+        rejection_proof = _feed_rejection_proof(path) if path is not None and not records else None
+        with self._lock:
+            rejected = self._rejected_feed
+            fingerprint_before = self._fingerprint
+            members = self._members_present
+            identity = self._candidate_identity
+            recorded_digests = tuple(
+                sorted(
+                    (member, entry["sha256"])
+                    for member, entry in self._member_index.items()
+                    if _is_recorded_digest(entry.get("sha256"))
+                )
+            )
+        feed_rejected = rejection_proof is not None and rejection_proof == rejected
+        if feed_rejected:
+            # These exact bytes did not parse last tick and have not changed since. Re-reading them
+            # every 0.25 s would be work with a known answer.
+            records = []
+
+        if (
+            not feed_rejected
+            and path is not None
+            and size > 0
+            and not records
+            and not events.feed_is_readable(path)
+        ):
+            # These bytes are not a feed at all: a foreign header, a truncation, or a half-written
+            # first line. Memoize and keep serving the last good render.
+            #
+            # READ AS NOTHING is not the same state as NARRATED NOTHING, and only the first belongs
+            # here. An attempt file that parses cleanly and carries no record is routine -- an
+            # idempotent re-run arms a feed and writes only its header -- and it never changes size,
+            # so memoizing it against `(path, size)` blocked the receipts fallback below for the
+            # life of the server and rendered a sealed, verifying run as "Nothing has happened yet."
+            proof_after = _feed_rejection_proof(path)
+            with self._lock:
+                self._rejected_feed = (
+                    rejection_proof
+                    if rejection_proof is not None and rejection_proof == proof_after
+                    else None
+                )
+            feed_rejected = True
+
+        if not feed_rejected:
+            with self._lock:
+                self._rejected_feed = None
+
+        if feed_rejected and identity is None:
+            # A live build has no receipts to fall back to.  The corroboration verdict above was
+            # still re-asked, but there is no page input it can safely replace the last good feed
+            # render with, so keep serving it until readable bytes or a candidate exists.
+            return
+
+        source = "feed" if records else "none"
+        if not records:
+            rederived = self._rederived_records(identity)
+            if rederived:
+                records, source = rederived, "receipts"
+        self._records_source = source
+
+        visible = self._release(records, source)
+
+        # Include every page input in the fingerprint so a changed verification result rerenders.
+        fingerprint = (
+            key,
+            source,
+            len(visible),
+            visible[-1]["seq"] if visible else 0,
+            visible[-1]["at"] if visible else 0.0,
+            identity,
+            members,
+            recorded_digests,
+            corroborated,
+        )
+        if fingerprint == fingerprint_before:
+            return
+
+        # `poll` records render failures and preserves the previous valid page.
+        markup = render_page(
+            visible,
+            run_dir=self.run_dir,
+            members_present=members,
+            now=time.time(),
+            read_member=self.read_member,
+            recorded_digests=dict(recorded_digests),
+            approval_corroborated=corroborated,
+        )
+
+        with self._lock:
+            self._offset = size if path is not None else 0
+            self._fingerprint = fingerprint
+            self._version += 1
+            self._last_seq = int(visible[-1]["seq"]) if visible else 0
+            self._html = markup
+            self._good_html = markup
+
+    # -- the record source and the paced release --------------------------------------------------
+
+    def _rederived_records(self, identity: tuple[int, int] | None) -> list[dict[str, Any]]:
+        """Project this run's feed from its own receipts when no feed file exists.
+
+        The retained candidate descriptor, namespace proof, and member identities must remain
+        unchanged before cached records are reused. Actual member bytes and member count are bounded
+        by the same limits as direct verification. Failed verification is not cached.
+        """
+
+        if identity is None:
+            return []
+        fd = self._duplicate_candidate_fd()
+        with self._lock:
+            manifest = self._manifest
+        if fd is None or manifest is None:
+            # Nothing pinned this instant, or no member set established, so there is nothing to ask
+            # about and nothing to bound the asking with. The next poll decides.
+            if fd is not None:
+                os.close(fd)
+            return []
+        try:
+            if not self._rederivation_fits_the_budget(fd):
+                return []
+            proof_before = self._rederivation_proof(fd)
+            with self._lock:
+                cached = None if self._rederived is None else list(self._rederived)
+                cached_proof = self._rederived_proof
+            if proof_before is not None and cached is not None and proof_before == cached_proof:
+                return cached
+            try:
+                rederived = events.rederive_feed(self.run_dir, pinned_candidate_fd=fd)
+            except Exception:
+                # Retry failed verification on the next poll.
+                rederived = []
+            proof_after = self._rederivation_proof(fd)
+            if proof_before is None or proof_after != proof_before:
+                rederived = []
+                proof_after = None
+            with self._lock:
+                self._rederived = list(rederived)
+                # A refusal is never memoized. The next poll must be able to observe a repair
+                # without depending on an incomplete proxy for the state that caused the refusal.
+                self._rederived_proof = proof_after if rederived else None
+            return rederived
+        finally:
+            os.close(fd)
+
+    def _rederivation_proof(self, fd: int) -> tuple[Any, ...] | None:
+        """Complete cheap identity paired with a successful receipts replay.
+
+        File contents retain the rotating descriptor probes in ``_run_is_settled``. Directory
+        namespace is cheaper and must be complete: adding an unrecorded member changes the child
+        set and invalidates the cached projection.
+        """
+
+        with self._lock:
+            if self._manifest is None or self._manifest_file_identity is None:
+                return None
+            candidate_identity = self._candidate_identity
+            manifest_identity = self._manifest_file_identity
+            index = dict(self._member_index)
+            verified = tuple(sorted(self._verified.items()))
+            wrong = tuple(
+                sorted(
+                    (member, () if decided is None else decided)
+                    for member, decided in self._measured_wrong.items()
+                )
+            )
+        try:
+            namespace = events.snapshot_candidate_namespace(fd, tuple(index))
+        except OSError:
+            return None
+        return candidate_identity, manifest_identity, verified, wrong, namespace
+
+    def _rederivation_fits_the_budget(self, fd: int) -> bool:
+        """Whether re-proving this candidate costs less than the ceiling the sibling reader uses.
+
+        Measured through the PINNED descriptor with open-then-fstat, so the size is the object's and
+        not the name's, and so the answer cannot be lied to by the manifest that is about to be
+        read: the pipeline's own pre-read ceiling is asked of the DECLARED byte counts, and the
+        declared counts are exactly what an attacker writes. A member this cannot open is counted as
+        nothing, because the rederivation will not read it either -- it will refuse the whole feed.
+
+        The sum is over the member set the run declares and the projection reads it TWICE (once in
+        ``verify_candidate``'s snapshot, once to project), so a set that fits here is bounded at
+        both passes.
+        """
+
+        index = self.member_index()
+        if len(index) > MAX_MANIFEST_MEMBERS:
+            return False
+        total = 0
+        for member in index:
+            try:
+                handle_fd = _open_regular_member(member, dir_fd=fd)
+            except OSError:
+                continue
+            try:
+                total += os.fstat(handle_fd).st_size
+            finally:
+                os.close(handle_fd)
+            if total > MAX_VERIFIED_TOTAL_BYTES:
+                return False
+        return True
+
+    def _release(self, records: list[dict[str, Any]], source: str) -> list[dict[str, Any]]:
+        """Return the prefix of ``records`` the page may show right now.
+
+        With no ``replay`` speed this is every record, which is what a live watch wants. With a
+        speed it is the records whose original inter-arrival gap has elapsed, divided by the speed
+        and clamped, so the existing channel and the existing renderer drive the replay with no new
+        machinery. Reaching the end stops releasing and leaves the final state on screen; it does
+        not loop and does not clear.
+        """
+
+        if self._replay is None or not records:
+            return records
+
+        now = self._clock()
+        if self._released_at is None:
+            self._released = 1
+            self._released_at = now
+            return records[:1]
+
+        while self._released < len(records):
+            if source == "receipts":
+                gap = REDERIVED_REPLAY_STEP_SECONDS
+            else:
+                previous = float(records[self._released - 1]["at"])
+                following = float(records[self._released]["at"])
+                gap = min(max(following - previous, 0.0), MAX_REPLAY_GAP_SECONDS)
+            delay = gap / self._replay
+            if now - self._released_at < delay:
+                break
+            self._released += 1
+            self._released_at += delay
+        if self._released >= len(records):
+            # Caught up. A feed that is still being written continues from here in live mode --
+            # one code path, two modes -- so the release clock must not stay in the past.
+            self._released_at = max(self._released_at, now)
+        return records[: self._released]
+
+    def _current_feed(self) -> tuple[Path | None, int, list[dict[str, Any]]]:
+        """Return the attempt being watched: ``(path, size, records)``, or ``(None, 0, [])``.
+
+        Resolve the attempt on every poll. Selection uses the sealed candidate digest when present;
+        otherwise it uses the newest active attempt according to ``events.select_narrated_feed``.
+        """
+
+        with self._lock:
+            manifest = self._manifest
+        digest = manifest.get("candidate_digest") if isinstance(manifest, Mapping) else None
+        return events.select_narrated_feed(
+            self.feed_dir,
+            sealed_candidate_digest=digest if isinstance(digest, str) else None,
+        )
+
+    # -- the run directory -----------------------------------------------------------------------
+
+    def _refresh_run(self) -> None:
+        """Load, keep or drop the run's manifest and member set. Called before every render.
+
+        The run directory does NOT exist while the build runs: ``build_candidate`` stages into a
+        hidden temporary directory and renames into place only after sealing. A manifest memoized
+        at construction is therefore permanently empty for exactly the build the user is watching.
+
+        Open the directory on every poll and measure identity from that descriptor. An unchanged
+        directory closes the new descriptor and retains the existing pinned reference.
+
+        Manifest content is not cached against directory identity. Incomplete reads are retried:
+
+        * complete means a manifest that parses and verifies, and every member it names either
+          proved present or READ WHOLE and found not to be the bytes the run recorded;
+        * a manifest that will not parse or will not verify is not complete, so the next poll reads
+          the file again;
+        * a member whose open or read RAISED measured nothing, so it is not complete either. That
+          covers the transient errnos above and it covers a run still arriving on disk.
+
+        A completed digest mismatch remains valid only for the measured file identity.
+        """
+
+        candidate = self.run_dir / "candidate"
+        try:
+            opened = events.open_directory(candidate)
+        except OSError as exc:
+            if exc.errno in _NAME_HOLDS_NO_CANDIDATE:
+                # Absent, removed, or no longer a directory.
+                self._drop_run()
+            return
+
+        adopted = False
+        try:
+            info = os.fstat(opened)
+            identity = (info.st_dev, info.st_ino)
+            with self._lock:
+                retained_identity = self._candidate_identity
+            if retained_identity is not None and identity != retained_identity:
+                # The directory at this path was REPLACED -- a rebuild. Drop the descriptor, the
+                # manifest and the member set before loading anything, so a new run is never served
+                # through the previous run's allowlist.
+                self._drop_run()
+
+            with self._lock:
+                if self._candidate_fd is None:
+                    # Pin the descriptor used to measure `identity`.
+                    self._candidate_fd = opened
+                    self._candidate_identity = identity
+                    adopted = True
+        finally:
+            if not adopted:
+                os.close(opened)
+
+        owned = self._duplicate_candidate_fd()
+        if owned is None:
+            return
+        try:
+            self._refresh_pinned_run(owned)
+        finally:
+            os.close(owned)
+
+    def _refresh_pinned_run(self, pinned: int) -> None:
+        """Refresh manifest state through one directory reference owned for the whole operation."""
+
+        if self._run_is_settled(pinned):
+            return
+
+        try:
+            raw, manifest_file_identity = self._read_manifest_snapshot(pinned)
+        except OSError:
+            # The seal is mid-flight, absent, or unreadable this instant. An earlier accepted
+            # manifest cannot remain the page's authority while its own receipt route says 404,
+            # so revoke every conclusion derived from it and retry next tick.
+            self._invalidate_installed_manifest(disowned=False)
+            return
+
+        try:
+            manifest = json.loads(raw.decode("utf-8"))
+            # The member names come out of a file another local user may have written, so they are
+            # re-checked against the member-path shape before any of them can become an allowlist
+            # key. A name that is not a member path is dropped, not repaired.
+            index = {
+                entry["path"]: dict(entry)
+                for entry in manifest["members"]
+                if isinstance(entry, Mapping) and _is_member_path(entry.get("path"))
+            }
+        except (ValueError, TypeError, KeyError, RecursionError):
+            # A half-written file. NOT memoized: this is a verdict about bytes, and the candidate
+            # directory's inode -- the only key this class has -- cannot see those bytes change.
+            # It DOES revoke an earlier accepted manifest immediately. Keeping the installed
+            # allowlist/page while the current receipt is invalid lets one page describe bytes
+            # that its own receipt endpoint refuses.
+            self._invalidate_installed_manifest(disowned=True)
+            return
+
+        # A NAME IN A FILE IS NOT EVIDENCE. Everything downstream of `members_present` -- the rail,
+        # the receipt links, the cards, the freeze summary -- reads that set as "this run really
+        # carries this file", and the rail turns membership alone into a done mark. So the set is
+        # built from what this reader has ESTABLISHED, in two steps that do not commute:
+        #
+        #   1. The receipt must be COHERENT. `manifest.json` records its fingerprint over itself,
+        #      so it is recomputed and compared before a single member name is believed. Appending
+        #      fabricated entries and leaving that fingerprint alone breaks it, and a manifest that
+        #      fails here contributes no members at all -- not even `manifest.json`.
+        #   2. Each member must be the bytes THIS receipt recorded. A name whose file is absent,
+        #      truncated or altered is dropped from the set, so a partial copy narrates the members
+        #      it still has and claims nothing for the ones it lost.
+        #
+        # WHAT THESE TWO STEPS DO NOT DO, stated here because this comment used to claim it: they
+        # do not establish that the receipt is the run's. Whoever writes the file writes its
+        # fingerprint, so a local user who RESEALS passes step 1, and step 2 then measures their
+        # members against their own manifest. A forged, fully self-consistent manifest naming
+        # attacker-written `recipe.json` and `recipe-approval.json` members renders as a verified
+        # member set. The claim on this page that a forgery could turn into an action -- the
+        # approval summary -- is therefore gated separately on the workspace's durable digest; see
+        # `_approval_is_corroborated`. Other content describes verified candidate members.
+        try:
+            self._verify_manifest_self(raw, None)
+        except ReceiptRefused:
+            # Also not memoized, and for the same reason. The flag says what THIS poll found, so a
+            # manifest restored on disk stops being disowned on the next tick rather than never.
+            self._invalidate_installed_manifest(disowned=True)
+            return
+
+        with self._lock:
+            if self._manifest_file_identity != manifest_file_identity:
+                self._verified.clear()
+                self._measured_wrong.clear()
+                self._settled_probe_cursor = 0
+            self._manifest_file_identity = manifest_file_identity
+        self._verify_members(pinned, index)
+
+        with self._lock:
+            self._manifest = manifest
+            self._members_present = frozenset(self._verified) | {_MANIFEST_NAME}
+            self._member_index = index
+            self._manifest_disowned = False
+
+    def _run_is_settled(self, fd: int) -> bool:
+        """Whether every installed digest decision still names the same kernel snapshot.
+
+        The digest is paid once for a snapshot. Each later poll opens and fstats the manifest, every
+        page-authoritative member, and one rotating bounded slice of the remaining decisions. Any
+        device, inode, size, mtime OR unforgeable ctime change invalidates the decision and routes
+        the new snapshot through bounded hashing. Missing and unreadable proved objects become
+        unsettled, so manifest revocation and copy-in-progress recovery keep their fail-closed
+        behaviour. The rotation means every accepted member is revisited, without making 4,096
+        opens the permanent price of watching an unchanged run.
+        """
+
+        with self._lock:
+            if self._manifest is None or self._manifest_file_identity is None:
+                return False
+            manifest_identity = self._manifest_file_identity
+            index = dict(self._member_index)
+            verified = dict(self._verified)
+            wrong = dict(self._measured_wrong)
+
+        try:
+            manifest_fd = _open_regular_member(_MANIFEST_NAME, dir_fd=fd)
+        except OSError:
+            return False
+        try:
+            if _file_identity(os.fstat(manifest_fd)) != manifest_identity:
+                return False
+        finally:
+            os.close(manifest_fd)
+
+        complete = not (set(index) - set(verified) - set(wrong))
+        decided = sorted(
+            set(verified)
+            | {member for member, decided_identity in wrong.items() if decided_identity is not None}
+        )
+        priority = [member for member in decided if member in _PAGE_AUTHORITY_MEMBERS]
+        background = [member for member in decided if member not in _PAGE_AUTHORITY_MEMBERS]
+        remaining = max(0, MAX_SETTLED_MEMBER_PROBES_PER_POLL - len(priority))
+        if background and remaining:
+            with self._lock:
+                start = self._settled_probe_cursor % len(background)
+                count = min(remaining, len(background))
+                self._settled_probe_cursor = (start + count) % len(background)
+            rotated = background[start:] + background[:start]
+            probes = priority + rotated[:count]
+        else:
+            probes = priority
+
+        changed = False
+        for member in probes:
+            decided_identity = verified.get(member)
+            was_verified = decided_identity is not None
+            if decided_identity is None:
+                decided_identity = wrong[member]
+            try:
+                member_fd = _open_regular_member(member, dir_fd=fd)
+            except OSError:
+                if was_verified:
+                    with self._lock:
+                        self._verified.pop(member, None)
+                    changed = True
+                # An already-refused member becoming absent does not make the page less true. Keep
+                # its refusal; when a file appears here again its identity is compared on its next
+                # rotating probe and a changed snapshot is re-proved.
+                continue
+            try:
+                unchanged = _file_identity(os.fstat(member_fd)) == decided_identity
+            finally:
+                os.close(member_fd)
+            if not unchanged:
+                with self._lock:
+                    if was_verified:
+                        self._verified.pop(member, None)
+                    else:
+                        self._measured_wrong.pop(member, None)
+                changed = True
+        return complete and not changed
+
+    def _verify_members(self, fd: int, index: Mapping[str, Mapping[str, Any]]) -> None:
+        """Verify undecided members under ``fd`` within the per-pass limits.
+
+        Digests are streamed and reused only while file identity is unchanged. Open or read errors
+        remain undecided and are retried on the next poll.
+        """
+
+        budget = MAX_VERIFIED_TOTAL_BYTES
+        for member, entry in list(index.items())[:MAX_MANIFEST_MEMBERS]:
+            if member in self._verified or member in self._measured_wrong:
+                continue
+            recorded = entry.get("sha256")
+            size = entry.get("bytes")
+            if not _is_recorded_digest(recorded) or type(size) is not int or size < 0:
+                # The ENTRY is unusable, and the entry is part of the manifest this pass already
+                # proved coherent. Nothing about the file on disk can change that, so it is decided.
+                self._measured_wrong[member] = None
+                continue
+            if size > budget:
+                # Not called present and not called absent: this reader declines to hash it. The
+                # rail still lights the step from the member's OWN event, which is evidence of the
+                # same fact from the producer rather than from this reader. Undecided, so the next
+                # pass -- which starts with a full budget -- offers it the remainder again.
+                continue
+            digest = hashlib.sha256()
+            read = 0
+            try:
+                handle_fd = _open_regular_member(member, dir_fd=fd)
+                with os.fdopen(handle_fd, "rb") as handle:
+                    identity_before = _file_identity(os.fstat(handle.fileno()))
+                    while True:
+                        chunk = handle.read(_MEMBER_HASH_CHUNK_BYTES)
+                        if not chunk:
+                            break
+                        read += len(chunk)
+                        if read > size:
+                            break
+                        digest.update(chunk)
+                    identity_after = _file_identity(os.fstat(handle.fileno()))
+            except OSError:
+                # Absent, unreadable, a symlink or a FIFO where a member should be. This poll could
+                # not look; it is not a fact about the run, and the next poll asks again.
+                budget -= read
+                continue
+            budget -= read
+            if identity_before != identity_after:
+                # The name changed while it was being measured. Neither the digest nor a refusal
+                # is attached to that mixed read; the next poll opens the resulting snapshot.
+                continue
+            if read != size or not _matches_digest(digest.hexdigest(), recorded):
+                self._measured_wrong[member] = identity_after
+                continue
+            self._measured_wrong.pop(member, None)
+            self._verified[member] = identity_after
+
+    def _read_manifest_snapshot(self, fd: int) -> tuple[bytes, tuple[int, int, int, int, int]]:
+        """Read ``manifest.json`` RELATIVE to the retained descriptor, never by path.
+
+        Holding the descriptor rather than re-opening by path per request is what makes a receipt
+        immune to a path swapped underneath it. A missing or non-regular manifest is retried on the
+        next poll.
+        """
+
+        handle_fd = _open_regular_member(_MANIFEST_NAME, dir_fd=fd)
+        with os.fdopen(handle_fd, "rb") as handle:
+            identity_before = _file_identity(os.fstat(handle.fileno()))
+            raw = handle.read(_MAX_MANIFEST_BYTES + 1)
+            identity_after = _file_identity(os.fstat(handle.fileno()))
+        if len(raw) > _MAX_MANIFEST_BYTES:
+            raise OSError("manifest is larger than this reader accepts")
+        if identity_before != identity_after:
+            raise OSError("manifest changed while this reader measured it")
+        return raw, identity_after
+
+    def _drop_run(self) -> None:
+        # Detach the retained descriptor while holding the same lock used to duplicate it. A
+        # reader therefore either owns its duplicate before this point or observes no candidate;
+        # it can never carry a bare descriptor number across this close and into kernel reuse.
+        with self._lock:
+            candidate_fd = self._candidate_fd
+            self._candidate_fd = None
+            self._candidate_identity = None
+            self._rederived = None
+            self._rederived_proof = None
+            self._manifest = None
+            self._members_present = frozenset()
+            self._member_index = {}
+            self._manifest_disowned = False
+            self._manifest_file_identity = None
+            self._verified = {}
+            self._measured_wrong = {}
+            self._settled_probe_cursor = 0
+        if candidate_fd is not None:
+            try:
+                os.close(candidate_fd)
+            except OSError:  # pragma: no cover - closing a descriptor twice is the only shape
+                pass
+
+    def _invalidate_installed_manifest(self, *, disowned: bool) -> None:
+        """Revoke every conclusion derived from manifest bytes this poll found invalid.
+
+        The candidate descriptor remains pinned so a restored receipt can recover on the next
+        poll. Only the installed authority, allowlist and member decisions are cleared; retaining
+        any one of them would keep the stale page or a stale receipt route alive.
+        """
+
+        self._rederived = None
+        self._rederived_proof = None
+        with self._lock:
+            self._manifest = None
+            self._members_present = frozenset()
+            self._member_index = {}
+            self._manifest_disowned = disowned
+            self._manifest_file_identity = None
+            self._verified.clear()
+            self._measured_wrong.clear()
+            self._settled_probe_cursor = 0
+
+    def close(self) -> None:
+        """Release the retained descriptor. Called on server shutdown."""
+
+        self._drop_run()
+
+
+class _WatchServer(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, address: tuple[str, int], handler: type, state: _WatchState) -> None:
+        super().__init__(address, handler)
+        self.watch_state = state
+        self.watch_stopped = False
+        self.watch_thread: threading.Thread | None = None
+
+
+class _WatchServerV6(_WatchServer):
+    address_family = socket.AF_INET6
+
+
+class _WatchHandler(BaseHTTPRequestHandler):
+    # The server exposes read-only GET routes. Approval remains a terminal operation.
+
+    def log_message(self, *_args: object) -> None:  # silence default stderr access logging
+        return
+
+    @property
+    def _state(self) -> _WatchState:
+        return self.server.watch_state  # type: ignore[attr-defined]
+
+    def do_GET(self) -> None:  # BaseHTTPRequestHandler's fixed dispatch name
+        if not self._request_targets_this_loopback_server():
+            self.send_error(421)
+            return
+        path = self.path.split("?", 1)[0]
+        if path == "/":
+            self._serve_index()
+        elif path == "/events":
+            self._serve_events()
+        elif path == "/receipt":
+            self._serve_receipt()
+        else:
+            self.send_error(404)
+
+    def _request_targets_this_loopback_server(self) -> bool:
+        """Reject DNS-rebound and cross-origin reads before any run content is written."""
+
+        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 = urllib.parse.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 True
+            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 _serve_index(self) -> None:
+        """Write the memoized bytes. Performs no file I/O and cannot raise on bad feed bytes."""
+
+        _version, _last_seq, markup = self._state.snapshot()
+        self._write_html(200, markup)
+
+    def _serve_receipt(self) -> None:
+        """Serve one receipt, verified against the fingerprint the run recorded for it.
+
+        The manifest, the allowlist and the directory descriptor are read from ``_WatchState`` on
+        every request and never captured at handler construction because they may change while the
+        build runs.
+        """
+
+        query = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+        member = (query.get("member") or [""])[0]
+        cited_values = query.get("sha256") or []
+        cited = cited_values[0] if cited_values else None
+
+        try:
+            raw = self._state.read_member(member, cited)
+        except ReceiptRefused as refusal:
+            self._write_html(refusal.status, render_refusal(refusal.sentence))
+            return
+        except Exception:  # pragma: no cover - every refusal shape above is typed
+            self._write_html(404, render_refusal(_NOT_A_RECEIPT))
+            return
+
+        try:
+            markup = render_receipt(member, raw)
+        except Exception:  # pragma: no cover - render_receipt degrades rather than raising
+            self._write_html(404, render_refusal(_NOT_A_RECEIPT))
+            return
+        self._write_html(200, markup)
+
+    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.end_headers()
+        self.wfile.write(body)
+
+    def _serve_events(self) -> None:
+        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()
+        last = self._state.snapshot()[0]
+        try:
+            while not getattr(self.server, "watch_stopped", False):
+                version, last_seq, _markup = self._state.snapshot()
+                if version != last:
+                    last = version
+                    # The version leads, and the sequence number rides along. The client treats a
+                    # frame it has already seen as nothing to do, so the value on the wire has to
+                    # change whenever the served page changes -- and the sequence number alone does
+                    # not: a failed poll puts a stall note on the page and adds no record, so a tab
+                    # deduping on the sequence threw away the one frame that mattered. It is still
+                    # a state identity and not a reload signal: a full reload on every event is a
+                    # flicker, and the page should feel like a record of events accumulating, not a
+                    # dashboard refreshing.
+                    self.wfile.write(f"data: {version}.{last_seq}\n\n".encode())
+                else:
+                    self.wfile.write(b": ping\n\n")
+                self.wfile.flush()
+                time.sleep(_POLL_SECONDS)
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            return
+
+
+def _watch_loop(server: _WatchServer) -> None:
+    state = server.watch_state
+    while not server.watch_stopped:
+        state.poll()
+        time.sleep(_POLL_SECONDS)
+
+
+def _shutdown_watch_server(server: _WatchServer) -> None:
+    """Stop and join the sole poll thread before closing anything it can still reach."""
+
+    server.watch_stopped = True
+    failure: BaseException | None = None
+    thread = server.watch_thread
+    if thread is not None and thread.ident is not None:
+        try:
+            thread.join()
+        except BaseException as error:
+            failure = error
+    try:
+        server.watch_state.close()
+    except BaseException as error:
+        if failure is None:
+            failure = error
+    try:
+        server.server_close()
+    except BaseException as error:
+        if failure is None:
+            failure = error
+    if failure is not None:
+        raise failure
+
+
+def _build_server(
+    target: _Target | str | os.PathLike[str],
+    host: str,
+    port: int,
+    *,
+    replay: float | None = None,
+) -> tuple[_WatchServer, str]:
+    """Bind a loopback server over the run's feed and start its watcher thread."""
+
+    state = _WatchState(target, replay=replay)
+    server: _WatchServer | None = None
+    try:
+        address = ipaddress.ip_address(host)
+        server_type = _WatchServerV6 if address.version == 6 else _WatchServer
+        server = server_type((address.compressed, port), _WatchHandler, 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.watch_thread = threading.Thread(target=_watch_loop, args=(server,), daemon=True)
+        server.watch_thread.start()
+        return server, url
+    except BaseException:
+        try:
+            if server is not None:
+                _shutdown_watch_server(server)
+            else:
+                state.close()
+        except BaseException:
+            # Construction/startup is the first failure. Cleanup still runs compoundly above,
+            # but a secondary failure must not replace the one the caller needs to diagnose.
+            pass
+        raise
+
+
+def serve_watch(
+    target: _Target | str | os.PathLike[str],
+    *,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    open_browser: bool = False,
+    replay: float | None = None,
+    announce: Callable[[str], None] | None = None,
+) -> None:
+    """Serve the live run view on ``localhost``. ``KeyboardInterrupt`` (Ctrl-C) shuts it down.
+
+    The served-URL line is flushed immediately: the port is ephemeral, so a caller that starts this
+    in the background has to read that line to learn the port, and a block-buffered pipe would
+    withhold it for the entire life of the server.
+
+    ``replay`` paces a finished run's records on their original inter-arrival gaps divided by the
+    given speed. Replay opens nothing for writing: it re-runs no build, appends to no feed and
+    touches no byte of the run directory.
+    """
+
+    server, url = _build_server(target, host, port, replay=replay)
+    try:
+        if announce is None:
+            print(f"mr-data watch: 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:
+        _shutdown_watch_server(server)
+
+
+# ------------------------------------------------------------------------------------------------
+# The page
+# ------------------------------------------------------------------------------------------------
+
+
+_STOPPED_EVENTS = STOPPED_EVENTS
+
+
+def _rail_positions() -> dict[str, tuple[int, int]]:
+    """Map every event name onto its position in the rail. A stage header sits at step ``-1``."""
+
+    positions: dict[str, tuple[int, int]] = {}
+    for stage_index, stage in enumerate(STAGE_RAIL):
+        for name in stage["events"]:
+            positions[name] = (stage_index, -1)
+        for step_index, step in enumerate(stage["steps"]):
+            for name in step["events"]:
+                positions[name] = (stage_index, step_index)
+    return positions
+
+
+_EVENT_POSITIONS = _rail_positions()
+
+
+def _rail_members(element: Mapping[str, Any]) -> tuple[str, ...]:
+    """The files that prove this rail element happened, or an empty tuple when it has none.
+
+    A step declares no ``members`` key of its own: the member its event points at IS its proof, and
+    ``_rail_member`` already resolves it from ``events.EVIDENCE_MEMBER``.
+    """
+
+    declared = element.get("members")
+    if declared:
+        return tuple(declared)
+    member = _rail_member(element["events"])
+    return (member,) if member is not None else ()
+
+
+# Written with %-placeholders rather than an f-string so CSS braces stay unescaped and readable.
+# Every colour and type value is an imported token; nothing here invents a hex. Classes are
+# `mr-watch-` prefixed kebab-case with `is-<state>` for transient state, following the notebook
+# renderer's class convention without touching any of its files.
+_CSS = """
+body { margin: 0; padding: 32px 24px 56px; background: %(paper)s; color: %(ink)s;
+  font-family: %(sans)s; }
+.mr-watch-page { max-width: 860px; margin: 0 auto; }
+.mr-watch-title { font-size: 25px; font-weight: 600; letter-spacing: -0.02em; margin: 0 0 6px;
+  color: %(ink)s; }
+.mr-watch-run { font-family: %(mono)s; font-size: 11.5px; color: %(muted)s; margin: 0 0 4px; }
+.mr-watch-elapsed { font-family: %(mono)s; font-size: 11.5px; color: %(faint)s; margin: 0 0 26px; }
+.mr-watch-rail { list-style: none; margin: 0 0 28px; padding: 16px 20px; border-radius: 12px;
+  border: 1px solid %(border)s; background: %(surface)s; }
+.mr-watch-stage { display: block; padding: 5px 0; }
+.mr-watch-stage-mark, .mr-watch-step-mark { display: inline-block; width: 8px; height: 8px;
+  border-radius: 2px; margin-right: 10px; vertical-align: 1px; background: %(border)s; }
+.mr-watch-stage.is-done > .mr-watch-stage-mark { background: %(cobalt)s; }
+.mr-watch-step.is-done > .mr-watch-step-mark { background: %(cobalt)s; }
+.mr-watch-stage-label { font-size: 15px; font-weight: 600; color: %(faint)s; }
+.mr-watch-stage.is-done > .mr-watch-stage-label { color: %(ink)s; }
+.mr-watch-steps { list-style: none; margin: 6px 0 6px 18px; padding: 0; }
+.mr-watch-step { display: block; padding: 3px 0; }
+.mr-watch-step-label { font-family: %(mono)s; font-size: 12px; color: %(faint)s; }
+.mr-watch-step.is-done > .mr-watch-step-label { color: %(body)s; }
+.mr-watch-log { list-style: none; margin: 0; padding: 0; border-top: 1px solid %(border)s; }
+.mr-watch-event { display: flex; gap: 14px; align-items: baseline; padding: 7px 2px;
+  border-bottom: 1px solid %(border)s; }
+.mr-watch-event.is-stopped > .mr-watch-text { color: %(orange)s; }
+.mr-watch-time { font-family: %(mono)s; font-size: 11px; color: %(faint)s; min-width: 56px;
+  font-variant-numeric: tabular-nums; }
+.mr-watch-text { font-size: 14px; color: %(body)s; flex: 1; }
+.mr-watch-receipt { font-family: %(mono)s; font-size: 11px; color: %(muted)s; }
+.mr-watch-receipt-link { font-family: %(mono)s; font-size: 11px; color: %(cobalt)s; }
+.mr-watch-later { font-family: %(mono)s; font-size: 11px; color: %(dim)s; }
+.mr-watch-empty { font-family: %(mono)s; font-size: 12px; color: %(faint)s; }
+.mr-watch-stalled { font-size: 13.5px; color: %(orange)s; border: 1px solid %(orange)s;
+  border-radius: 8px; background: %(sub_paper)s; padding: 10px 12px; margin: 0 0 20px; }
+.mr-watch-cards { margin: 0 0 28px; }
+.mr-watch-card { border: 1px solid %(border)s; border-radius: 12px; background: %(sub_paper)s;
+  padding: 16px 20px; margin: 0 0 14px; }
+.mr-watch-card-title { font-size: 16px; font-weight: 600; margin: 0 0 8px; color: %(ink)s; }
+.mr-watch-card-lead { font-size: 14px; color: %(body)s; margin: 0 0 10px; }
+.mr-watch-list { margin: 0 0 8px; padding-left: 20px; }
+.mr-watch-list li { font-size: 13.5px; color: %(body)s; padding: 2px 0; }
+.mr-watch-sub { border-top: 1px solid %(border)s; margin-top: 10px; padding-top: 10px; }
+.mr-watch-sub-title { font-size: 14px; font-weight: 600; color: %(ink)s; margin: 0 0 4px; }
+.mr-watch-defs { margin: 0; font-size: 13.5px; color: %(body)s; }
+.mr-watch-defs dt { font-weight: 600; color: %(muted)s; font-size: 12px; margin-top: 6px; }
+.mr-watch-defs dd { margin: 1px 0 0; }
+.mr-watch-table { border-collapse: collapse; width: 100%%; font-size: 13px; margin: 6px 0 2px; }
+.mr-watch-table th { text-align: left; font-size: 11.5px; color: %(muted)s; font-weight: 600;
+  border-bottom: 1px solid %(border)s; padding: 4px 10px 4px 0; }
+.mr-watch-table td { color: %(body)s; border-bottom: 1px solid %(border)s; padding: 4px 10px 4px 0;
+  vertical-align: top; }
+.mr-watch-approve { border: 1px solid %(cobalt)s; border-radius: 12px; background: %(sub_paper)s;
+  padding: 16px 20px; margin: 0 0 24px; }
+.mr-watch-note { font-size: 13px; color: %(muted)s; margin: 10px 0 8px; }
+.mr-watch-command { display: block; font-family: %(mono)s; font-size: 11.5px; color: %(ink)s;
+  background: %(surface)s; border: 1px solid %(border)s; border-radius: 8px; padding: 10px 12px;
+  overflow-x: auto; white-space: pre; }
+.mr-watch-copy { font-family: %(sans)s; font-size: 12.5px; color: %(paper)s; background: %(cobalt)s;
+  border: 1px solid %(cobalt)s; border-radius: 8px; padding: 6px 14px; margin-top: 10px;
+  cursor: pointer; }
+.mr-watch-back { font-size: 12.5px; color: %(cobalt)s; display: inline-block; margin-bottom: 18px; }
+.mr-watch-refusal { font-size: 15px; color: %(orange)s; margin: 0; }
+.mr-watch-pre { font-family: %(mono)s; font-size: 11.5px; color: %(body)s; white-space: pre-wrap;
+  word-break: break-all; margin: 0; }
+"""
+
+# The whole client: one EventSource, one 1 Hz recompute of the elapsed text. No framework, no
+# bundler, no build step, no network. Wrapped in try/catch so live update is best-effort -- a page
+# whose script failed is still a correct record of everything that had happened when it was served.
+_LIVE_SCRIPT = (
+    "<script>\n"
+    "(function () {\n"
+    "  try {\n"
+    "    var seen = null;\n"
+    "    var source = new EventSource('/events');\n"
+    "    source.onmessage = function (event) {\n"
+    "      if (event.data === seen) { return; }\n"
+    "      seen = event.data;\n"
+    "      fetch('/').then(function (response) { return response.text(); })\n"
+    "        .then(function (text) {\n"
+    "          var parsed = new DOMParser().parseFromString(text, 'text/html');\n"
+    "          document.body.innerHTML = parsed.body.innerHTML;\n"
+    "        })\n"
+    "        .catch(function () { /* the next event tries again */ });\n"
+    "    };\n"
+    "    var retick = function () {\n"
+    "      var node = document.querySelector('.mr-watch-elapsed');\n"
+    "      if (!node) { return; }\n"
+    "      var at = parseFloat(node.getAttribute('data-at'));\n"
+    "      if (!(at > 0)) { return; }\n"
+    "      var seconds = Math.max(0, Math.round(Date.now() / 1000 - at));\n"
+    "      node.textContent = 'Last event ' + seconds + ' seconds ago';\n"
+    "    };\n"
+    "    window.setInterval(retick, 1000);\n"
+    "    document.addEventListener('click', function (clicked) {\n"
+    "      var button = clicked.target.closest('.mr-watch-copy');\n"
+    "      if (!button) { return; }\n"
+    "      var target = document.getElementById(button.getAttribute('data-copy-target'));\n"
+    "      if (!target) { return; }\n"
+    "      var text = target.textContent;\n"
+    "      var done = function () {\n"
+    "        button.textContent = 'Copied';\n"
+    "        window.setTimeout(function () { button.textContent = 'Copy'; }, 2000);\n"
+    "      };\n"
+    "      if (navigator.clipboard && navigator.clipboard.writeText) {\n"
+    "        navigator.clipboard.writeText(text).then(done, function () {});\n"
+    "        return;\n"
+    "      }\n"
+    "      var scratch = document.createElement('textarea');\n"
+    "      scratch.value = text;\n"
+    "      document.body.appendChild(scratch);\n"
+    "      scratch.select();\n"
+    "      try { document.execCommand('copy'); done(); } catch (error) { /* nothing to do */ }\n"
+    "      document.body.removeChild(scratch);\n"
+    "    });\n"
+    "  } catch (error) { /* live update is best-effort */ }\n"
+    "})();\n"
+    "</script>"
+)
+
+
+def stylesheet() -> str:
+    return (
+        "<style>"
+        + _CSS
+        % {
+            "paper": PAPER,
+            "ink": INK,
+            "body": BODY,
+            "muted": MUTED,
+            "faint": FAINT,
+            "dim": DIM,
+            "border": BORDER,
+            "surface": SURFACE,
+            "sub_paper": SUB_PAPER,
+            "cobalt": COBALT,
+            "orange": ORANGE,
+            "sans": FONT_SANS,
+            "mono": FONT_MONO,
+        }
+        + "</style>"
+    )
+
+
+def _seen_events(records: Sequence[Mapping[str, Any]]) -> frozenset[str]:
+    """Return the rail event names present in the feed."""
+
+    return frozenset(
+        str(record.get("event"))
+        for record in records
+        if str(record.get("event")) in _EVENT_POSITIONS
+    )
+
+
+def _state_class(
+    element: Mapping[str, Any],
+    seen: frozenset[str],
+    members_present: frozenset[str],
+) -> str:
+    """A rail item is done when its OWN evidence says so, and never on a later item's strength.
+
+    Two ways to be done, and no third: one of the element's own events is in the feed, or every
+    file it names is in the sealed member set. Anything else waits. There is no animated state --
+    progress on this page is events that happened, never a spinner.
+    """
+
+    if any(name in seen for name in element["events"]):
+        return "is-done"
+    members = _rail_members(element)
+    if members and all(member in members_present for member in members):
+        return "is-done"
+    return "is-waiting"
+
+
+def _sentence(event: str, facts: Mapping[str, Any]) -> str:
+    return sentence(event, facts)
+
+
+def _pointer_of(record: Mapping[str, Any]) -> tuple[str | None, str | None]:
+    """Return ``(member, sha256)`` for a record's evidence pointer, either half possibly ``None``.
+
+    A record sealed AFTER the fact carries both halves in ``evidence``; a record emitted DURING the
+    build carries only the member name it will be provable against, in ``facts["evidence_member"]``.
+    """
+
+    evidence = record.get("evidence")
+    if isinstance(evidence, Mapping):
+        member = evidence.get("member")
+        sha256 = evidence.get("sha256")
+        if isinstance(member, str):
+            return member, sha256 if isinstance(sha256, str) else None
+    facts = record.get("facts")
+    member = facts.get("evidence_member") if isinstance(facts, Mapping) else None
+    return (member if isinstance(member, str) else None), None
+
+
+def receipt_href(member: str, sha256: str | None = None) -> str:
+    """Build the link to one receipt. Both values are percent-quoted before they reach the URL."""
+
+    query = {"member": member}
+    if sha256:
+        query["sha256"] = sha256
+    return "/receipt?" + urllib.parse.urlencode(query, quote_via=urllib.parse.quote)
+
+
+def _receipt(
+    record: Mapping[str, Any],
+    members_present: frozenset[str],
+    recorded_digests: Mapping[str, str] | None = None,
+) -> str:
+    """Return a receipt link when the member and manifest digest are verified.
+
+    A feed digest that disagrees with the manifest suppresses the link.
+    """
+
+    member, sha256 = _pointer_of(record)
+    if member is None:
+        return ""
+    if member not in members_present:
+        return '<span class="mr-watch-later">receipt appears when the build finishes</span>'
+    recorded = (recorded_digests or {}).get(member)
+    if sha256 is not None and recorded is not None and not _matches_digest(sha256, recorded):
+        return ""
+    return (
+        f'<a class="mr-watch-receipt-link" href="{esc(receipt_href(member, recorded))}"'
+        f' data-member="{esc(member)}">Receipt: {esc(member)}</a>'
+    )
+
+
+def render_stall_note(failures: int, reason: str) -> str:
+    """The sentence a view that has stopped reading owes its reader.
+
+    Watch has no spinner: the page shows what happened, and where nothing has happened it says so.
+    A page whose reader has stopped being able to read is the same
+    obligation one step further on -- it is still showing a true record, but of a moment that has
+    passed, and a reader has no way to tell that from a build that is simply taking its time.
+
+    The failure's own NAME is on the page and its message is not. A name comes from this codebase;
+    a message can carry bytes out of the run directory, which is a place another local user writes.
+    """
+
+    times = "once" if failures == 1 else f"{failures} times"
+    return (
+        f'<p class="mr-watch-stalled" data-failed-polls="{esc(failures)}"'
+        f' data-reason="{esc(reason)}">'
+        f"This page has stopped updating. Reading this build failed {esc(times)}, "
+        f"the last time with {esc(reason)}. "
+        "What you see below is the last thing this page could read."
+        "</p>"
+    )
+
+
+# The stall note is spliced in after the header rather than rendered with the page, because the page
+# it belongs on is by definition one this reader could NOT re-render. Every page this module builds
+# opens with exactly one header, so the first close tag is the anchor.
+_STALL_ANCHOR = "</header>"
+
+
+def _with_stall_note(markup: str, failures: int, reason: str) -> str:
+    """Return the last good page with the stall note under its header."""
+
+    head, anchor, tail = markup.partition(_STALL_ANCHOR)
+    note = render_stall_note(failures, reason)
+    if not anchor:  # pragma: no cover - every page this module renders carries a header
+        return note + markup
+    return head + anchor + note + tail
+
+
+def _render_header(run_dir: Path, records: Sequence[Mapping[str, Any]], now: float) -> str:
+    last_at = float(records[-1]["at"]) if records else 0.0
+    if records and last_at > 0:
+        text = f"Last event {max(0, int(now - last_at))} seconds ago"
+    elif records:
+        # Rederived records have no source timestamp.
+        text = "Rebuilt from the files this build recorded"
+    else:
+        text = "No events yet"
+    return (
+        '<header class="mr-watch-header">'
+        '<h1 class="mr-watch-title">Watch</h1>'
+        f'<p class="mr-watch-run">Build: {esc(_writable_path_text(run_dir.name))}</p>'
+        f'<p class="mr-watch-elapsed" data-at="{esc(f"{last_at:.3f}")}">{esc(text)}</p>'
+        "</header>"
+    )
+
+
+def _rail_member(names: Sequence[str]) -> str | None:
+    """The receipt a rail element stands for: the first of its events with a fixed pointer.
+
+    ``member_sealed`` and ``build_sealed`` have no fixed member -- the first varies per member and
+    the second anchors on the run's own fingerprint -- so the "Receipt recorded" step falls through
+    to the run's own receipt, which is exactly what a reader clicking it wants to see.
+    """
+
+    for name in names:
+        member = events.EVIDENCE_MEMBER.get(name)
+        if member is not None:
+            return member
+    if "build_sealed" in names:
+        return _MANIFEST_NAME
+    return None
+
+
+def _rail_label(label: str, css: str, names: Sequence[str], members_present: frozenset[str]) -> str:
+    """Render one rail element's label, linked to its receipt once that receipt exists."""
+
+    member = _rail_member(names)
+    if member is None or member not in members_present:
+        return f'<span class="{css}">{esc(label)}</span>'
+    return (
+        f'<a class="{css}" href="{esc(receipt_href(member))}"'
+        f' data-member="{esc(member)}">{esc(label)}</a>'
+    )
+
+
+def _render_rail(seen: frozenset[str], members_present: frozenset[str]) -> str:
+    items: list[str] = []
+    for stage in STAGE_RAIL:
+        stage_state = _state_class(stage, seen, members_present)
+        steps = "".join(
+            f'<li class="mr-watch-step {_state_class(step, seen, members_present)}"'
+            f' data-rail="{esc(stage["stage"])}.{esc(step["step"])}">'
+            '<span class="mr-watch-step-mark"></span>'
+            + _rail_label(step["label"], "mr-watch-step-label", step["events"], members_present)
+            + "</li>"
+            for step in stage["steps"]
+        )
+        items.append(
+            f'<li class="mr-watch-stage {stage_state}" data-rail="{esc(stage["stage"])}">'
+            '<span class="mr-watch-stage-mark"></span>'
+            + _rail_label(stage["label"], "mr-watch-stage-label", stage["events"], members_present)
+            + (f'<ol class="mr-watch-steps">{steps}</ol>' if steps else "")
+            + "</li>"
+        )
+    return '<ol class="mr-watch-rail">' + "".join(items) + "</ol>"
+
+
+def _render_log(
+    records: Sequence[Mapping[str, Any]],
+    members_present: frozenset[str],
+    recorded_digests: Mapping[str, str] | None = None,
+) -> str:
+    if not records:
+        return '<p class="mr-watch-empty">Nothing has happened yet.</p>'
+    started = float(records[0]["at"])
+    items: list[str] = []
+    for record in records:
+        event = str(record.get("event", ""))
+        facts = record.get("facts")
+        offset = max(0, int(float(record.get("at", started)) - started))
+        classes = "mr-watch-event is-stopped" if event in _STOPPED_EVENTS else "mr-watch-event"
+        items.append(
+            f'<li class="{classes}">'
+            f'<span class="mr-watch-time">+{esc(offset)}s</span>'
+            f'<span class="mr-watch-text">'
+            f"{esc(_sentence(event, facts if isinstance(facts, Mapping) else {}))}</span>"
+            f"{_receipt(record, members_present, recorded_digests)}"
+            "</li>"
+        )
+    return '<ol class="mr-watch-log">' + "".join(items) + "</ol>"
+
+
+def render_page(
+    records: Sequence[Mapping[str, Any]],
+    *,
+    run_dir: Path,
+    members_present: frozenset[str],
+    now: float,
+    read_member: Callable[[str], bytes] | None = None,
+    recorded_digests: Mapping[str, str] | None = None,
+    approval_corroborated: bool = True,
+) -> str:
+    """Render the whole page. It opens no file of its own and takes every input as an argument.
+
+    ``read_member`` is the one exception and it is a PARAMETER, not a capability this function
+    reaches for: the cards and the approval summary are claims about what the run recorded, so they
+    are built from the same fingerprint-verified read ``/receipt`` uses and can never render bytes
+    that failed their check. With no reader the page is the rail and the event log, which is exactly
+    what a watcher started before the build should show.
+
+    Every interpolated value crosses ``esc`` because feed and evidence strings may contain markup.
+
+    ``recorded_digests`` is the run's OWN digest for each member -- ``member_index`` -- and it is
+    what every receipt link uses.
+    """
+
+    seen = _seen_events(records)
+    approval = ""
+    cards = ""
+    if read_member is not None and approval_corroborated:
+        approval = _safe(lambda: render_approval(run_dir, members_present, read_member))
+    if read_member is not None:
+        cards = _safe(lambda: render_cards(members_present, read_member))
+    return (
+        "<!doctype html>\n"
+        '<html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        "<title>Watch</title>"
+        f"{stylesheet()}"
+        "</head><body>\n"
+        '<div class="mr-watch-page">'
+        f"{_render_header(run_dir, records, now)}"
+        f"{_render_rail(seen, members_present)}"
+        f"{approval}"
+        f"{cards}"
+        f"{_render_log(records, members_present, recorded_digests)}"
+        "</div>\n"
+        f"{_LIVE_SCRIPT}\n"
+        "</body></html>\n"
+    )
+
+
+def _safe(render: Callable[[], str]) -> str:
+    """Render a section, or render nothing. A section is never allowed to blank the page.
+
+    The run directory is a place another local user can write, so a member can be any bytes at all.
+    A card that raised on a shape it did not expect would take down the event log with it, and the
+    event log is the part a reader most needs when something has gone wrong.
+    """
+
+    try:
+        return render()
+    except Exception:
+        return ""
+
+
+# ------------------------------------------------------------------------------------------------
+# Plain vocabulary
+# ------------------------------------------------------------------------------------------------
+#
+# Two vocabularies, one direction. The evidence a receipt renders is internal contract JSON, and its
+# field names are engineering-precise on purpose. None of them may reach a page. The rule this file
+# follows is to map every field to a plain phrase and omit fields without a plain rendering.
+
+# A word that, appearing in a key, means that key has no plain rendering and must be dropped.
+_INTERNAL_WORDS = frozenset(
+    {
+        "acquisition",
+        "adapter",
+        "attempt",
+        "candidate",
+        "capability",
+        "caps",
+        "classification",
+        "credential",
+        "crawler",
+        "decode",
+        "digest",
+        "digests",
+        "golden",
+        "governance",
+        "id",
+        "ids",
+        "lawful",
+        "manifest",
+        "materialization",
+        "normalizer",
+        "policy",
+        "predecessor",
+        "principal",
+        "producer",
+        "promotion",
+        "sandbox",
+        "schema",
+        "sealed",
+        "semantics",
+        "sha256",
+        "sha256s",
+        "template",
+        "verifier",
+        "version",
+        "watermark",
+        "workspace",
+    }
+)
+
+# Keys whose plain phrase is worth stating explicitly rather than deriving.
+_PLAIN_KEYS: Mapping[str, str] = {
+    "bytes": "Size in bytes",
+    "cardinality": "Shape of the match",
+    "cleaning": "Cleaning",
+    "columns": "Columns",
+    "created_at": "Recorded at",
+    "evidence": "What backs it",
+    "expected": "Expected",
+    "grain": "One row per",
+    "join": "Join",
+    "keys": "Joined on",
+    "left_rows": "Rows on the left",
+    "left_source": "Left side",
+    "matched_left_rows": "Rows that matched",
+    "null_counts": "Blanks per column",
+    "observed": "Observed",
+    "operations": "What was done to it",
+    "origin": "Where it came from",
+    "output_intent": "Meant for",
+    "output_rows": "Rows out",
+    "passed": "Result",
+    "permissions": "You may",
+    "population": "Who is in it",
+    "quality": "Checks",
+    "questions": "Questions",
+    "relative_path": "File",
+    "rights": "Rights",
+    "right_rows": "Rows on the right",
+    "right_source": "Right side",
+    "row_count": "Rows",
+    "row_multiplier": "Row multiplier",
+    "rows": "Rows",
+    "select": "Columns kept",
+    "sources": "Sources",
+    "stable_order": "Row order",
+    "status": "State",
+    "text": "Text",
+    "types": "Types",
+    "unmatched_left_rows": "Rows that did not match",
+}
+
+# Contract values that have a plain reading. Anything not here is humanized, never dropped: a value
+# is data the run recorded, and dropping data would be editing the receipt.
+_RIGHTS_STATUS: Mapping[str, str] = {
+    "project_owned": "owned by this project",
+    "public_domain": "in the public domain",
+    "licensed": "used under a licence",
+    "permitted": "cleared for this use",
+    "restricted": "restricted",
+    "unknown": "not decided yet",
+}
+
+_RIGHTS_DECISION: Mapping[str, str] = {
+    "approved": "cleared for this use",
+    "conditional": "conditions attached",
+    "denied": "not usable",
+    "blocked": "not usable",
+    "pending": "not decided yet",
+}
+
+_PERMISSIONS: Mapping[str, str] = {
+    "local_use": "use it here",
+    "redistribute": "share it on",
+    "host": "publish it",
+}
+
+_HOW_FETCHED: Mapping[str, str] = {
+    "checked_in_fixture": "a file kept with the project",
+    "user_file": "a file you supplied",
+    "download": "downloaded over the network",
+    "api": "read from an interface",
+}
+
+_MATCH_SHAPE: Mapping[str, str] = {
+    "one_to_one": "one row to one row",
+    "many_to_one": "many rows to one row",
+    "one_to_many": "one row to many rows",
+    "many_to_many": "many rows to many rows",
+}
+
+_JOIN_KIND: Mapping[str, str] = {
+    "left": "kept every row on the left",
+    "inner": "kept only rows on both sides",
+}
+
+_OUTPUT_INTENT: Mapping[str, str] = {
+    "local_use": "use here only",
+    "redistribute": "sharing on",
+    "host": "publishing",
+}
+
+# The five checks a Recipe run must pass (`recipe.REQUIRED_CHECK_INVENTORY`) plus the three a plan
+# declares, each with the sentence a person reads. A check id is an internal name by design; this is
+# the map that keeps it from reaching a page.
+_PLAIN_CHECKS: Mapping[str, str] = {
+    "EXACT_CANDIDATE_REPLAY": "The build reproduces exactly, byte for byte",
+    "RECIPE_DRIFT": "Nothing has drifted from the Recipe",
+    "SOURCE_AUTHORITY": "Every source is the one the Recipe names",
+    "OUTPUT_SEMANTICS": "Every column still means what was approved",
+    "TEMPORAL_INTEGRITY": "The time window still holds",
+}
+
+
+def _humanize(value: Any) -> str:
+    """Render one contract value as words: underscores out, first letter up."""
+
+    text = str(value).replace("_", " ").replace("-", " ").strip()
+    return text[:1].upper() + text[1:] if text else ""
+
+
+def _plain_label(key: Any) -> str | None:
+    """Return the plain heading for one field name, or ``None`` when it has no plain reading."""
+
+    if not isinstance(key, str) or not key:
+        return None
+    known = _PLAIN_KEYS.get(key)
+    if known is not None:
+        return known
+    words = key.replace("-", " ").replace("_", " ").split()
+    if not words or any(word.lower() in _INTERNAL_WORDS for word in words):
+        return None
+    text = " ".join(words)
+    return text[:1].upper() + text[1:]
+
+
+def _plain_from(table: Mapping[str, str], value: Any) -> str:
+    known = table.get(str(value))
+    return known if known is not None else _humanize(value)
+
+
+def _plain_operation(operation: Any) -> str:
+    text = str(operation)
+    if text.startswith("cast:"):
+        return f"read as {text.split(':', 1)[1]}"
+    if text == "trim":
+        return "trimmed of stray spaces"
+    return _humanize(text)
+
+
+def _plain_check(check_id: Any, expected: Any) -> str:
+    """Name one check the way a person would say it.
+
+    Known internal check identifiers map to explicit operator-facing descriptions.
+    """
+
+    text = str(check_id)
+    known = _PLAIN_CHECKS.get(text)
+    if known is not None:
+        return known
+    if text == "MIN_ROWS":
+        return f"At least {str(expected).lstrip('>=')} rows"
+    if text.startswith("NOT_NULL_"):
+        return f"No blanks in {text[len('NOT_NULL_') :]}"
+    if text == "UNIQUE_GRAIN":
+        return "One row per key, with no repeats"
+    words = text.replace("_", " ").replace("-", " ").split()
+    if not words or any(word.lower() in _INTERNAL_WORDS for word in words):
+        return "A check this build requires"
+    return _humanize(text)
+
+
+def _joined(values: Any, empty: str = "none") -> str:
+    if not isinstance(values, (list, tuple)) or not values:
+        return empty
+    return ", ".join(str(value) for value in values)
+
+
+# ------------------------------------------------------------------------------------------------
+# Receipts
+# ------------------------------------------------------------------------------------------------
+
+
+def _document(title: str, body: str, *, script: str = "") -> str:
+    return (
+        "<!doctype html>\n"
+        '<html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{esc(title)}</title>"
+        f"{stylesheet()}"
+        "</head><body>\n"
+        f'<div class="mr-watch-page">{body}</div>\n'
+        f"{script}"
+        "</body></html>\n"
+    )
+
+
+def _back() -> str:
+    return '<a class="mr-watch-back" href="/">Back to the build</a>'
+
+
+def render_refusal(sentence: str) -> str:
+    """Render a refusal: the one plain sentence, the way back, and NONE of the file's content."""
+
+    return _document(
+        "Receipt",
+        _back() + f'<p class="mr-watch-refusal">{esc(sentence)}</p>',
+    )
+
+
+def _definitions(pairs: Sequence[tuple[str, str]]) -> str:
+    items = "".join(
+        f"<dt>{esc(label)}</dt><dd>{esc(value)}</dd>" for label, value in pairs if label
+    )
+    return f'<dl class="mr-watch-defs">{items}</dl>' if items else ""
+
+
+def _table(headings: Sequence[str], rows: Sequence[Sequence[Any]]) -> str:
+    head = "".join(f"<th>{esc(heading)}</th>" for heading in headings)
+    body = "".join(
+        "<tr>" + "".join(f"<td>{esc(cell)}</td>" for cell in row) + "</tr>" for row in rows
+    )
+    return (
+        f'<table class="mr-watch-table"><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table>'
+    )
+
+
+def _lines(sentences: Sequence[str]) -> str:
+    items = "".join(f"<li>{esc(sentence)}</li>" for sentence in sentences if sentence)
+    return f'<ul class="mr-watch-list">{items}</ul>' if items else ""
+
+
+def _render_run_receipt(payload: Mapping[str, Any]) -> str:
+    members = payload.get("members")
+    members = members if isinstance(members, list) else []
+    total = sum(entry.get("bytes", 0) for entry in members if isinstance(entry, Mapping))
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">The receipt for this whole build</h1>',
+            '<p class="mr-watch-card-lead">This is what the build recorded about itself. '
+            "Every file below was fingerprinted when the build finished, and the fingerprint of "
+            "the whole set is the one line to quote when someone asks which build this was.</p>",
+            _definitions(
+                [
+                    ("Fingerprint of the whole build", str(payload.get("candidate_digest", ""))),
+                    ("Files recorded", str(len(members))),
+                    ("Total size in bytes", str(total)),
+                    ("Built with engine", str(payload.get("engine_version", ""))),
+                ]
+            ),
+            _table(
+                ["File", "Size in bytes", "Fingerprint"],
+                [
+                    [entry.get("path", ""), entry.get("bytes", ""), entry.get("sha256", "")]
+                    for entry in members
+                    if isinstance(entry, Mapping)
+                ],
+            ),
+        ]
+    )
+
+
+def _render_join(payload: Mapping[str, Any]) -> str:
+    matched = payload.get("matched_left_rows")
+    left = payload.get("left_rows")
+    unmatched = payload.get("unmatched_left_rows")
+    keys = _joined(payload.get("keys"))
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">The join</h1>',
+            f'<p class="mr-watch-card-lead">{esc(f"Joined on {keys}.")} '
+            f"{esc(f'{matched} of {left} rows matched; {unmatched} did not.')}</p>",
+            _definitions(
+                [
+                    ("Joined on", keys),
+                    ("Left side", str(payload.get("left_source", ""))),
+                    ("Right side", str(payload.get("right_source", ""))),
+                    ("Rows on the left", str(left)),
+                    ("Rows on the right", str(payload.get("right_rows", ""))),
+                    ("Rows that matched", str(matched)),
+                    ("Rows that did not match", str(unmatched)),
+                    ("Rows out", str(payload.get("output_rows", ""))),
+                    ("Row multiplier", str(payload.get("row_multiplier", ""))),
+                    ("Shape of the match", _plain_from(_MATCH_SHAPE, payload.get("cardinality"))),
+                    ("Row order", _humanize(payload.get("stable_order", ""))),
+                ]
+            ),
+        ]
+    )
+
+
+def _render_quality(payload: Mapping[str, Any]) -> str:
+    checks = payload.get("checks")
+    checks = checks if isinstance(checks, list) else []
+    passed = sum(
+        1 for check in checks if isinstance(check, Mapping) and check.get("passed") is True
+    )
+    rows = [
+        [
+            _plain_check(check.get("check_id"), check.get("expected")),
+            "pass" if check.get("passed") is True else "fail",
+            check.get("observed", ""),
+            check.get("expected", ""),
+        ]
+        for check in checks
+        if isinstance(check, Mapping)
+    ]
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">The checks</h1>',
+            f'<p class="mr-watch-card-lead">{esc(f"{passed} of {len(checks)} checks passed.")}</p>',
+            _table(["Check", "Result", "Observed", "Expected"], rows),
+        ]
+    )
+
+
+def _render_sources(payload: Any) -> str:
+    entries = payload if isinstance(payload, list) else []
+    cards: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, Mapping):
+            continue
+        rights = entry.get("rights")
+        rights = rights if isinstance(rights, Mapping) else {}
+        permissions = rights.get("permissions")
+        cards.append(
+            '<div class="mr-watch-sub">'
+            f'<p class="mr-watch-sub-title">{esc(entry.get("source_id", ""))}</p>'
+            + _definitions(
+                [
+                    ("Where it came from", str(entry.get("origin", ""))),
+                    ("File", str(entry.get("relative_path", ""))),
+                    (
+                        "How it was fetched",
+                        _plain_from(_HOW_FETCHED, entry.get("acquisition_method")),
+                    ),
+                    ("Rights", _plain_from(_RIGHTS_STATUS, rights.get("status"))),
+                    (
+                        "You may",
+                        ", ".join(_plain_from(_PERMISSIONS, item) for item in permissions)
+                        if isinstance(permissions, list) and permissions
+                        else "nothing recorded",
+                    ),
+                    ("What backs that", str(rights.get("evidence", ""))),
+                    ("Size in bytes", str(entry.get("bytes", ""))),
+                    ("Fingerprint", str(entry.get("sha256", ""))),
+                ]
+            )
+            + "</div>"
+        )
+    return (
+        '<h1 class="mr-watch-card-title">The sources this build read</h1>'
+        f'<p class="mr-watch-card-lead">{esc(f"{len(cards)} sources were read.")}</p>'
+        + "".join(cards)
+    )
+
+
+def _profile_table(profile: Mapping[str, Any]) -> str:
+    columns = profile.get("columns")
+    columns = columns if isinstance(columns, list) else []
+    types = profile.get("types")
+    types = types if isinstance(types, Mapping) else {}
+    blanks = profile.get("null_counts")
+    blanks = blanks if isinstance(blanks, Mapping) else {}
+    return _table(
+        ["Column", "Type", "Blanks"],
+        [[name, types.get(name, ""), blanks.get(name, "")] for name in columns],
+    )
+
+
+def _render_profile(payload: Mapping[str, Any]) -> str:
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">The dataset this build produced</h1>',
+            f'<p class="mr-watch-card-lead">{esc(str(payload.get("row_count", 0)))} rows.</p>',
+            _profile_table(payload),
+        ]
+    )
+
+
+def _render_source_profiles(payload: Mapping[str, Any]) -> str:
+    parts = ['<h1 class="mr-watch-card-title">What each source looked like</h1>']
+    for source_id in sorted(payload):
+        shapes = payload[source_id]
+        if not isinstance(shapes, Mapping):
+            continue
+        parts.append(
+            f'<div class="mr-watch-sub"><p class="mr-watch-sub-title">{esc(source_id)}</p>'
+        )
+        for stage, label in (("raw", "As it was read"), ("cleaned", "After cleaning")):
+            shape = shapes.get(stage)
+            if isinstance(shape, Mapping):
+                parts.append(f"<p><strong>{esc(label)}</strong></p>")
+                parts.append(f'<p class="mr-watch-note">{esc(shape.get("row_count", 0))} rows</p>')
+                parts.append(_profile_table(shape))
+        parts.append("</div>")
+    return "".join(parts)
+
+
+def _render_lineage(payload: Mapping[str, Any]) -> str:
+    sentences = []
+    for column in sorted(payload):
+        entry = payload[column]
+        if not isinstance(entry, Mapping):
+            continue
+        operations = entry.get("operations")
+        applied = (
+            ", ".join(_plain_operation(item) for item in operations)
+            if isinstance(operations, list) and operations
+            else "nothing"
+        )
+        sentences.append(
+            f"{column} comes from {entry.get('source_column', '')} in "
+            f"{entry.get('source_id', '')}; it was {applied}."
+        )
+    return (
+        '<h1 class="mr-watch-card-title">Where every column came from</h1>'
+        '<p class="mr-watch-card-lead">One line per column in the finished dataset.</p>'
+        + _lines(sentences)
+    )
+
+
+def _plan_summary(plan: Mapping[str, Any]) -> list[tuple[str, str]]:
+    sources = plan.get("sources")
+    sources = sources if isinstance(sources, list) else []
+    join = plan.get("join")
+    join = join if isinstance(join, Mapping) else {}
+    quality = plan.get("quality")
+    quality = quality if isinstance(quality, Mapping) else {}
+    cleaning = plan.get("cleaning")
+    cleaning = cleaning if isinstance(cleaning, list) else []
+    return [
+        (
+            "Sources",
+            ", ".join(
+                str(source.get("id", "")) for source in sources if isinstance(source, Mapping)
+            )
+            or "none",
+        ),
+        ("One row per", _joined(plan.get("grain"))),
+        ("Columns kept", _joined(plan.get("select"))),
+        ("Cleaning", f"{len(cleaning)} steps"),
+        (
+            "Join",
+            f"{join.get('left', '')} to {join.get('right', '')} on {_joined(join.get('on'))}, "
+            f"{_plain_from(_JOIN_KIND, join.get('kind'))}, "
+            f"{_plain_from(_MATCH_SHAPE, join.get('cardinality'))}",
+        ),
+        ("Meant for", _plain_from(_OUTPUT_INTENT, plan.get("output_intent", ""))),
+        (
+            "Checks",
+            f"at least {quality.get('min_rows', 0)} rows; no blanks in "
+            f"{_joined(quality.get('not_null'))}",
+        ),
+    ]
+
+
+def _cleaning_lines(plan: Mapping[str, Any]) -> list[str]:
+    cleaning = plan.get("cleaning")
+    cleaning = cleaning if isinstance(cleaning, list) else []
+    lines: list[str] = []
+    for step in cleaning:
+        if not isinstance(step, Mapping):
+            continue
+        columns = step.get("columns")
+        if isinstance(columns, Mapping):
+            named = ", ".join(f"{key} as {value}" for key, value in columns.items())
+        else:
+            named = _joined(columns)
+        lines.append(f"{_plain_operation(step.get('operation'))}: {named} in {step.get('source')}")
+    return lines
+
+
+def _render_plan(payload: Mapping[str, Any]) -> str:
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">What this build was asked to do</h1>',
+            f'<p class="mr-watch-card-lead">{esc(payload.get("question", ""))}</p>',
+            _definitions(_plan_summary(payload)),
+            "<p><strong>Cleaning, in order</strong></p>",
+            _lines(_cleaning_lines(payload)),
+        ]
+    )
+
+
+def _render_generic(payload: Any) -> str:
+    """The fallback for a file with no renderer of its own.
+
+    It renders only fields that HAVE a plain reading and drops the rest, because the alternative --
+    dumping the field names the contract uses -- is the jargon leak this product refuses. A file
+    whose every field is internal renders its size and fingerprint and nothing else, which is an
+    honest thing for a page to say.
+    """
+
+    if not isinstance(payload, Mapping):
+        return '<p class="mr-watch-card-lead">This file was recorded for this build.</p>'
+    pairs: list[tuple[str, str]] = []
+    for key in payload:
+        label = _plain_label(key)
+        if label is None:
+            continue
+        value = payload[key]
+        if isinstance(value, Mapping):
+            rendered = f"{len(value)} entries"
+        elif isinstance(value, list):
+            rendered = (
+                _joined(value)
+                if all(not isinstance(v, (dict, list)) for v in value)
+                else (f"{len(value)} entries")
+            )
+        else:
+            rendered = str(value)
+        pairs.append((label, rendered))
+    return (
+        '<p class="mr-watch-card-lead">This file was recorded for this build.</p>'
+        + _definitions(pairs)
+    )
+
+
+def _render_opaque(member: str, raw: bytes) -> str:
+    """A data file's receipt is its size and its fingerprint, not its bytes.
+
+    Rendering the content of an arbitrary recorded file would put untrusted bytes of unknown
+    encoding on a page for no gain: the thing that makes a data file trustworthy is that its
+    fingerprint matches what the build recorded, and that is what this page states.
+    """
+
+    return "".join(
+        [
+            '<h1 class="mr-watch-card-title">A data file from this build</h1>',
+            '<p class="mr-watch-card-lead">This file holds data rather than a written record, '
+            "so what is shown is what the build recorded about it.</p>",
+            _definitions(
+                [
+                    ("File", member),
+                    ("Size in bytes", str(len(raw))),
+                    ("Fingerprint", hashlib.sha256(raw).hexdigest()),
+                ]
+            ),
+        ]
+    )
+
+
+_RECEIPT_RENDERERS: Mapping[str, Callable[[Any], str]] = {
+    "manifest.json": _render_run_receipt,
+    "plan.json": _render_plan,
+    "evidence/join.json": _render_join,
+    "evidence/quality.json": _render_quality,
+    "evidence/sources.json": _render_sources,
+    "evidence/profile.json": _render_profile,
+    "evidence/source_profiles.json": _render_source_profiles,
+    "evidence/lineage.json": _render_lineage,
+}
+
+
+def render_receipt(member: str, raw: Any) -> str:
+    """Render one verified receipt as a page a person can read.
+
+    ``raw`` is the member's bytes, already verified against the fingerprint the build recorded for
+    it. A renderer that raises on a shape it did not expect degrades to the generic renderer; a
+    malformed file must produce a plain page, never a traceback.
+
+    VERIFIED IS NOT WRITABLE. Everything that reaches the page here crosses ``_writable_payload``
+    first -- the member name included, for the opaque path below -- because a member whose bytes
+    match the digest the run recorded can still carry a lone surrogate that no surface can encode;
+    see that function.
+    """
+
+    member = events.writable_text(member)
+    payload: Any
+    if isinstance(raw, (bytes, bytearray)):
+        try:
+            payload = _writable_payload(json.loads(bytes(raw).decode("utf-8")))
+        except (ValueError, UnicodeDecodeError, RecursionError):
+            return _document("Receipt", _back() + _render_opaque(member, bytes(raw)))
+    else:
+        payload = _writable_payload(raw)
+
+    renderer = _RECEIPT_RENDERERS.get(member)
+    body = ""
+    if renderer is not None:
+        try:
+            body = renderer(payload)
+        except Exception:
+            body = ""
+    if not body:
+        body = _AUTHORED_RECEIPTS.get(member, _render_generic)(payload)
+    return _document("Receipt", _back() + body)
+
+
+# ------------------------------------------------------------------------------------------------
+# Authored artifact cards
+# ------------------------------------------------------------------------------------------------
+
+
+def _card(title: str, lead: str, body: str) -> str:
+    return (
+        '<section class="mr-watch-card">'
+        f'<h2 class="mr-watch-card-title">{esc(title)}</h2>'
+        + (f'<p class="mr-watch-card-lead">{esc(lead)}</p>' if lead else "")
+        + body
+        + "</section>"
+    )
+
+
+def _question_card(question: Any, requirements: Any = None) -> str:
+    if not isinstance(question, Mapping):
+        return ""
+    criteria = []
+    if isinstance(requirements, Mapping):
+        listed = requirements.get("success_criteria")
+        if isinstance(listed, list):
+            criteria = [str(item) for item in listed]
+    body = ("<p><strong>It is done when</strong></p>" + _lines(criteria)) if criteria else ""
+    return _card("The question", str(question.get("text", "")), body)
+
+
+def _requirements_card(requirements: Any) -> str:
+    if not isinstance(requirements, Mapping):
+        return ""
+    sentences: list[str] = []
+    population = requirements.get("population")
+    if population:
+        sentences.append(str(population))
+    window = requirements.get("time_range")
+    if isinstance(window, Mapping):
+        sentences.append(
+            f"It covers {window.get('start_inclusive', '')} up to "
+            f"{window.get('end_exclusive', '')}."
+        )
+    grain = requirements.get("output_grain")
+    if isinstance(grain, Mapping) and grain.get("description"):
+        sentences.append(str(grain["description"]))
+    fields = requirements.get("required_fields")
+    if isinstance(fields, list) and fields:
+        sentences.append(f"Every row carries {_joined(fields)}.")
+    feasibility = requirements.get("feasibility")
+    if isinstance(feasibility, Mapping) and feasibility.get("narrative"):
+        sentences.append(str(feasibility["narrative"]))
+    if not sentences:
+        return ""
+    return _card("What it has to satisfy", "", _lines(sentences))
+
+
+def _proposals_card(proposals: Any) -> str:
+    listed: Any = None
+    if isinstance(proposals, Mapping):
+        listed = proposals.get("source_proposals")
+    elif isinstance(proposals, list):
+        listed = proposals
+    if not isinstance(listed, list) or not listed:
+        return ""
+    blocks: list[str] = []
+    for proposal in listed:
+        if not isinstance(proposal, Mapping):
+            continue
+        coverage = proposal.get("historical_coverage")
+        evidence = proposal.get("evidence")
+        argument = (
+            "The agent chose this one."
+            if proposal.get("fitness_decision") == "selected"
+            else f"The agent's reading: {_humanize(proposal.get('fitness_decision'))}."
+        )
+        if isinstance(coverage, Mapping):
+            argument += (
+                f" It covers {coverage.get('start_inclusive', '')} up to "
+                f"{coverage.get('end_exclusive', '')}."
+            )
+        if isinstance(evidence, list) and evidence:
+            argument += f" {len(evidence)} pieces of backing were recorded."
+        blocks.append(
+            '<div class="mr-watch-sub">'
+            f'<p class="mr-watch-sub-title">{esc(proposal.get("display_name", ""))}</p>'
+            + _definitions(
+                [
+                    ("What it is", _humanize(proposal.get("data_format", ""))),
+                    ("Where it came from", str(proposal.get("locator", ""))),
+                    ("Why it fits", argument),
+                    ("Rights", _plain_from(_RIGHTS_DECISION, proposal.get("rights_status"))),
+                ]
+            )
+            + "</div>"
+        )
+    if not blocks:
+        return ""
+    return _card(
+        "Sources the agent proposed",
+        f"{len(blocks)} proposed.",
+        "".join(blocks),
+    )
+
+
+def _recipe_summary(recipe: Mapping[str, Any]) -> list[tuple[str, str]]:
+    plan = recipe.get("transform_plan")
+    plan = plan if isinstance(plan, Mapping) else {}
+    validation = recipe.get("validation")
+    validation = validation if isinstance(validation, Mapping) else {}
+    pairs = _plan_summary(plan)
+    required = validation.get("required_check_ids")
+    if isinstance(required, list) and required:
+        # Semicolons, not commas: every one of these is a sentence, and comma-joining sentences
+        # produces a paragraph a reader cannot parse into its parts.
+        pairs.append(
+            (
+                "Checks that must pass",
+                "; ".join(_plain_check(item, "") for item in required),
+            )
+        )
+    return pairs
+
+
+def _recipe_card(recipe: Any) -> str:
+    if not isinstance(recipe, Mapping):
+        return ""
+    plan = recipe.get("transform_plan")
+    plan = plan if isinstance(plan, Mapping) else {}
+    return _card(
+        "The Recipe",
+        "These are the locked instructions this build followed. They do not change between runs.",
+        _definitions(_recipe_summary(recipe))
+        + "<p><strong>Cleaning, in order</strong></p>"
+        + _lines(_cleaning_lines(plan)),
+    )
+
+
+# The four authored artifacts render the SAME body whether they are reached as a card on the index
+# or as a receipt of their own, so a reader never meets two readings of one file.
+_AUTHORED_RECEIPTS: Mapping[str, Callable[[Any], str]] = {
+    "question.json": _question_card,
+    "requirements.json": _requirements_card,
+    "source-proposals.json": _proposals_card,
+    "recipe.json": _recipe_card,
+}
+
+_CARD_MEMBERS = ("question.json", "requirements.json", "source-proposals.json", "recipe.json")
+
+
+def _writable_payload(value: Any) -> Any:
+    """Normalize every string so the rendered payload is UTF-8 encodable."""
+
+    if isinstance(value, str):
+        return events.writable_text(value)
+    if isinstance(value, Mapping):
+        return {_writable_payload(key): _writable_payload(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_writable_payload(item) for item in value]
+    return value
+
+
+def _member_payload(read_member: Callable[[str], bytes], member: str) -> Any:
+    """Read and parse one member through the verified read, or return ``None``.
+
+    Verified is not writable: see ``_writable_payload`` for why a member that passed every check
+    the run makes of it still cannot be put on a page unchanged.
+    """
+
+    try:
+        raw = read_member(member)
+    except Exception:
+        return None
+    try:
+        return _writable_payload(json.loads(raw.decode("utf-8")))
+    except (ValueError, UnicodeDecodeError, RecursionError):
+        return None
+
+
+def render_cards(members_present: frozenset[str], read_member: Callable[[str], bytes]) -> str:
+    """Render each verified authored artifact that is currently present."""
+
+    loaded: dict[str, Any] = {}
+    for member in _CARD_MEMBERS:
+        if member in members_present:
+            payload = _member_payload(read_member, member)
+            if payload is not None:
+                loaded[member] = payload
+    if not loaded:
+        return ""
+
+    cards: list[str] = []
+    if "question.json" in loaded:
+        cards.append(
+            _safe(lambda: _question_card(loaded["question.json"], loaded.get("requirements.json")))
+        )
+    if "requirements.json" in loaded:
+        cards.append(_safe(lambda: _requirements_card(loaded["requirements.json"])))
+    if "source-proposals.json" in loaded:
+        cards.append(_safe(lambda: _proposals_card(loaded["source-proposals.json"])))
+    if "recipe.json" in loaded:
+        cards.append(_safe(lambda: _recipe_card(loaded["recipe.json"])))
+    rendered = "".join(card for card in cards if card)
+    return f'<section class="mr-watch-cards">{rendered}</section>' if rendered else ""
+
+
+# ------------------------------------------------------------------------------------------------
+# The approval gate -- display only
+# ------------------------------------------------------------------------------------------------
+#
+# The displayed command uses the explicit recipe approval interface. Tests bind the command and
+# option names to the CLI parser.
+APPROVE_COMMAND_NAME = "recipe-approve"
+APPROVE_COMMAND_TEMPLATE = (
+    "mr-data recipe-approve"
+    " --recipe {recipe}"
+    " --approval-id APPROVAL_ID"
+    " --approved-by YOUR_NAME"
+    " --approved-at TIMESTAMP"
+    " --approval-policy-digest APPROVAL_RULES_FINGERPRINT"
+    " --output {output}"
+)
+
+_APPROVE_COMMAND_ID = "mr-watch-approve-command"
+
+
+def approve_command(run_dir: Path) -> str:
+    """Return the approval command with normalized recipe and output paths."""
+
+    return APPROVE_COMMAND_TEMPLATE.format(
+        recipe=_writable_path_text(run_dir / "candidate" / "recipe.json"),
+        output=_writable_path_text(run_dir / "recipe-approval.json"),
+    )
+
+
+# Relationship between an approval record and its recipe digest.
+_BINDS = "binds"
+_DISAGREES = "disagrees"
+_CLAIMS_NOTHING = "claims-nothing"
+
+
+def _recipe_digest(recipe: Mapping[str, Any]) -> str:
+    """The Recipe's own canonical digest, computed exactly as ``RecipeApproval`` computes it."""
+
+    try:
+        # Deferred: `watch` must stay importable without pulling `canonical` in at module load.
+        from mostlyright.data_harness.canonical import canonical_json_bytes, sha256_bytes
+
+        return sha256_bytes(canonical_json_bytes(dict(recipe)))
+    except Exception:
+        return ""
+
+
+def _approval_record(
+    read_member: Callable[[str], bytes], members_present: frozenset[str]
+) -> Mapping[str, Any] | None:
+    """The run's approval record, read once through the verified read the rest of the page uses."""
+
+    if "recipe-approval.json" not in members_present:
+        return None
+    record = _member_payload(read_member, "recipe-approval.json")
+    return record if isinstance(record, Mapping) else None
+
+
+def _approval_binding(record: Mapping[str, Any] | None, computed: str) -> str:
+    """Whether ``record`` binds an approval to the Recipe whose derived digest is ``computed``.
+
+    Through ``_matches_digest``, so a claim that is not a digest at all gets the same answer as a
+    claim that is the wrong digest. ``computed`` is "" when the Recipe yields no canonical digest,
+    and the comparator refuses that operand too: nothing can be proven to bind a Recipe whose own
+    fingerprint cannot be derived.
+    """
+
+    claimed = None if record is None else record.get("recipe_digest")
+    if not isinstance(claimed, str) or not claimed:
+        return _CLAIMS_NOTHING
+    return _BINDS if _matches_digest(computed, claimed) else _DISAGREES
+
+
+def _recipe_fingerprint(
+    read_member: Callable[[str], bytes],
+    members_present: frozenset[str],
+    recipe: Mapping[str, Any],
+) -> str:
+    """Return the canonical recipe digest unless the approval records a different digest."""
+
+    return _fingerprint_line(recipe, _approval_record(read_member, members_present))
+
+
+def _fingerprint_line(recipe: Mapping[str, Any], record: Mapping[str, Any] | None) -> str:
+    """The value ``_recipe_fingerprint`` returns, from a record the caller has already read."""
+
+    computed = _recipe_digest(recipe)
+    if not computed:
+        return ""
+    return "" if _approval_binding(record, computed) == _DISAGREES else computed
+
+
+def render_approval(
+    run_dir: Path,
+    members_present: frozenset[str],
+    read_member: Callable[[str], bytes],
+) -> str:
+    """Render the verified recipe and its approval state, or return an empty string.
+
+    Approved output requires an approval digest that matches the canonical recipe digest. A
+    mismatch is reported without an approval command. Approval itself remains a terminal action.
+    """
+
+    if "recipe.json" not in members_present:
+        return ""
+    recipe = _member_payload(read_member, "recipe.json")
+    if not isinstance(recipe, Mapping):
+        return ""
+
+    # One binding result controls both the displayed digest and approval state.
+    record = _approval_record(read_member, members_present)
+    binding = _approval_binding(record, _recipe_digest(recipe))
+
+    pairs = _recipe_summary(recipe)
+    fingerprint = _fingerprint_line(recipe, record)
+    if fingerprint:
+        pairs.append(("Fingerprint of the Recipe", fingerprint))
+    receipt = _member_payload(read_member, _MANIFEST_NAME)
+    if isinstance(receipt, Mapping) and receipt.get("candidate_digest"):
+        # Kept, under a label that says whose fingerprint it is. It identifies the build, not the
+        # Recipe, and a reader who quotes one for the other has quoted the wrong thing.
+        pairs.append(("Fingerprint of this build", str(receipt["candidate_digest"])))
+
+    approval = (
+        record if binding == _BINDS and record is not None and record.get("approved_by") else None
+    )
+
+    if approval is not None:
+        return (
+            '<section class="mr-watch-approve">'
+            '<h2 class="mr-watch-card-title">What this build was built from</h2>'
+            '<p class="mr-watch-card-lead">This Recipe was approved before the build ran, and the '
+            "build followed it exactly. Nothing on this page changes that.</p>"
+            + _definitions(pairs)
+            + f'<p class="mr-watch-note">Approved by {esc(approval.get("approved_by", ""))} '
+            f"on {esc(approval.get('approved_at', ''))}.</p>" + "</section>"
+        )
+
+    if binding == _DISAGREES:
+        return (
+            '<section class="mr-watch-approve">'
+            '<h2 class="mr-watch-card-title">Approval does not match this Recipe</h2>'
+            '<p class="mr-watch-card-lead">The approval on disk binds a different Recipe. '
+            "This build cannot present it as approval for the Recipe shown here.</p>"
+            + _definitions(pairs)
+            + '<p class="mr-watch-note">No approval command is shown while these records '
+            "disagree. Check the Recipe and approval receipts before taking any action.</p>"
+            "</section>"
+        )
+
+    command = approve_command(run_dir)
+    return (
+        '<section class="mr-watch-approve">'
+        '<h2 class="mr-watch-card-title">What you are about to freeze</h2>'
+        '<p class="mr-watch-card-lead">Freezing turns these instructions into a Recipe that runs '
+        "the same way every time. Read what is below before you do it.</p>"
+        + _definitions(pairs)
+        + '<p class="mr-watch-note">Approving happens in your terminal. This page only shows you '
+        "what you would be approving. Copy the line below and run it yourself.</p>"
+        + '<p class="mr-watch-note">Four values in the line are yours to supply, and they are '
+        "written in capitals: a name for this approval, your own name, the time you approved, and "
+        "the fingerprint of the approval rules you followed.</p>"
+        + f'<code class="mr-watch-command" id="{_APPROVE_COMMAND_ID}">{esc(command)}</code>'
+        + f'<button type="button" class="mr-watch-copy" data-copy-target="{_APPROVE_COMMAND_ID}">'
+        "Copy</button>"
+        "</section>"
+    )