puremethod 0.1.0__py3-none-any.whl

loop/core.py

@@ -0,0 +1,1160 @@
+"""The research cycle (03-loop.md). `Loop` drives a run from the ledger alone (INV-10).
+
+Each `drive` iteration replays the ledger, does one unit of work, and records it. A unit is
+an LLM call, an adapter call, or one stage of experiments; each one checks the run's limits
+first (INV-5) and is recorded before or as it happens (INV-1). Outcomes are computed by
+`decide.evaluate` from recorded metrics (INV-2).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import functools
+import json
+import math
+import subprocess
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, TypeVar
+
+from executor import (
+    EnvRef,
+    EnvSpec,
+    Executor,
+    ExecutorError,
+    ExecutorInfo,
+    JobHandle,
+    JobResult,
+    JobSpec,
+)
+from ledger import CONFIRM_STAGE, SMOKE_STAGE, ConcurrentWrite, Entry, Ledger, LedgerRejection
+from llm import LLM, InvalidOutput, LLMError, Message, PriceUnknown
+from purescholar import REQUIRED_SCOPES, CitationRecord, PureScholar, PureScholarError
+from puretrace import Artifacts, Assessment, PureTrace, PureTraceError
+from writer import BuildResult, PaperOptions, Writer
+
+from . import harness, prompts
+from .config import RunConfig, next_stage, stage_budget_s
+from .decide import evaluate
+from .view import Hyp, RunView, build_view
+
+T = TypeVar("T")
+
+KILL_FACTOR = 1.1        # §5 step 5: an experiment is killed at 110% of its budget
+GRACE_S = 30.0           # 05-executor.md §5 step 3: termination grace after the deadline
+SMOKE_FIXES = 3          # §5 step 4.4
+POLL_S = 2.0
+QUOTE_CHARS = 20_000
+ARMS = ("treatment", "baseline")
+
+CredentialLookup = Callable[[str], str]
+LLMFactory = Callable[[dict[str, dict[str, Any]], dict[str, str]], LLM]
+ExecutorFactory = Callable[[str, CredentialLookup], Executor]
+WriterFactory = Callable[[LLM, PureScholar | None], Writer]
+
+
+class LimitReached(RuntimeError):
+    """An action's maximum cost does not fit the run's limits (INV-5)."""
+
+
+class _Pause(Exception):
+    """A service, the executor or the LLM is unavailable: the run pauses (SYS-INV-7)."""
+
+
+@dataclass(frozen=True)
+class RunStatus:
+    run_id: str
+    status: str | None
+    phase: str | None
+    reason: str
+    spend_usd: float
+    money_limit_usd: float
+    elapsed_h: float
+    wall_clock_limit_h: float
+    hypotheses: dict[str, int]
+    open_checkpoints: list[str]
+
+
+@dataclass
+class _Session:
+    config: RunConfig
+    llm: LLM
+    executor: Executor
+    info: ExecutorInfo
+    envs: dict[str, EnvRef] = field(default_factory=dict)
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _quote(text: str, source: str) -> str:
+    return LLM.quote(text[:QUOTE_CHARS], source)
+
+
+def _asdict(obj: Any) -> dict[str, Any]:
+    return dataclasses.asdict(obj)
+
+
+class Loop:
+    """Built from a Ledger, a writer factory, client factories and a credential lookup
+    (03-loop.md §3). Keeps caches only; the run state is the ledger."""
+
+    def __init__(self, ledger: Ledger, writer: WriterFactory, *, llm: LLMFactory,
+                 executor: ExecutorFactory, purescholar: Callable[[], PureScholar],
+                 puretrace: Callable[[str, list[str]], PureTrace] | None,
+                 credentials: CredentialLookup, output_root: str | Path,
+                 now: Callable[[], datetime] = _utc_now,
+                 sleep: Callable[[float], None] = time.sleep,
+                 monotonic: Callable[[], float] = time.monotonic,
+                 poll_s: float = POLL_S,
+                 client_credentials: Callable[[RunConfig], list[str]] | None = None) -> None:
+        self._ledger = ledger
+        self._client_credentials = client_credentials
+        self._writer = writer
+        self._llm_factory = llm
+        self._executor_factory = executor
+        self._ps_factory = purescholar
+        self._pt_factory = puretrace
+        self._credentials = credentials
+        self._out = Path(output_root)
+        self._now = now
+        self._sleep = sleep
+        self._mono = monotonic
+        self._poll_s = poll_s
+        self._sessions: dict[str, _Session] = {}
+        self._secrets_ok: set[str] = set()
+        self._to_reap: dict[str, list[str]] = {}
+
+    # ==== interface =========================================================================
+
+    def start(self, config: RunConfig) -> str:
+        """Opens the run and runs preflight (§5 step 1)."""
+        secrets = self._secret_values(config)
+        run_id = self._ledger.open_run(config.model_dump(mode="json"), secrets)
+        self._secrets_ok.add(run_id)
+        self._status(run_id, "preflight", "preflight")
+        try:
+            self._sessions[run_id] = self._new_session(config)
+        except (KeyError, ValueError, ExecutorError) as exc:
+            self._status(run_id, "failed", "preflight", f"cannot build clients: {exc}")
+            return run_id
+        self._guarded(run_id, lambda: self._preflight(run_id, self._view(run_id)))
+        return run_id
+
+    def drive(self, run_id: str) -> RunStatus:
+        """Advances the run until it is delivered, failed, paused or waiting at a checkpoint."""
+        while True:
+            view = self._view(run_id)
+            if view.status in ("paused", "delivered", "failed"):
+                return self.status(run_id)
+            self._session(run_id)
+            if self._to_reap.get(run_id):
+                self._guarded(run_id, functools.partial(self._reap, run_id))
+                continue
+            before = self._ledger.state(run_id).last_seq
+            self._guarded(run_id, functools.partial(self._step, run_id, view))
+            if self._ledger.state(run_id).last_seq == before:  # a step always records
+                self._fail(run_id, f"no progress in phase {view.phase}")
+
+    def pause(self, run_id: str, reason: str) -> None:
+        view = self._view(run_id)
+        if view.status not in ("preflight", "running", "stopping", "writing"):
+            raise ValueError(f"cannot pause a run that is {view.status}")
+        self._status(run_id, "paused", view.phase, f"user: {reason}", actor="user",
+                     resume_status=view.status)
+
+    def resume(self, run_id: str) -> RunStatus:
+        """User resume. After a restart, the first `drive` in the new process rebuilds the
+        session and closes dangling experiments (§5 step 9); `resume` never does, so it is
+        safe while a worker still finishes a batch."""
+        view = self._view(run_id)
+        if view.status == "paused":
+            if view.open_checkpoint() is not None:
+                raise ValueError("the run waits at a checkpoint: decide it to continue (INV-7)")
+            self._status(run_id, view.resume_status or "running", view.phase, "resumed",
+                         actor="user")
+        return self.status(run_id)
+
+    def stop(self, run_id: str) -> None:
+        """Stops exploring; the run moves to writing with what exists."""
+        view = self._view(run_id)
+        if view.phase not in ("preflight", "literature", "directions", "exploring") or \
+                view.status not in ("preflight", "running", "paused"):
+            raise ValueError(f"cannot stop a run that is {view.status} at {view.phase}")
+        cp = view.open_checkpoint()
+        if cp is not None and cp.id == "C2":
+            raise ValueError("the run already waits at C2, before writing")
+        self._status(run_id, "stopping", view.phase, "user stop", actor="user")
+
+    def decide_checkpoint(self, run_id: str, checkpoint_id: str, decision: Any) -> None:
+        view = self._view(run_id)
+        cp = view.checkpoints.get(checkpoint_id)
+        if cp is None or cp.decided is not None:
+            raise ValueError(f"checkpoint {checkpoint_id} is not open")
+        if not isinstance(decision, dict):
+            raise ValueError("a checkpoint decision is an object")
+        if checkpoint_id == "C1":
+            keep = list(decision.get("keep", list(view.ideas)))
+            add = [str(t) for t in decision.get("add", []) if str(t).strip()]
+            if set(keep) - set(view.ideas):
+                raise ValueError("keep lists an id that is not a proposed direction")
+            decided = self._append(run_id, "checkpoint.decided", {
+                "checkpoint_id": "C1", "decision": {"keep": keep, "add": add}},
+                [cp.requested, *keep], actor="user")
+            for text in add:
+                self._append(run_id, "idea.proposed", {"direction": text,
+                                                       "parents": [decided.entry_id]},
+                             [decided.entry_id], actor="user")
+            self._status(run_id, "stopping" if view.resume_status == "stopping" else "running",
+                         "exploring", "C1 decided")
+        elif checkpoint_id == "C2":
+            if decision.get("approve") is not True:
+                raise ValueError("C2 takes {'approve': true}: writing starts")
+            self._append(run_id, "checkpoint.decided", {"checkpoint_id": "C2",
+                                                        "decision": {"approve": True}},
+                         [cp.requested], actor="user")
+            self._status(run_id, "writing", "writing", "C2 decided")
+        else:
+            raise ValueError(f"unknown checkpoint {checkpoint_id}")
+
+    def status(self, run_id: str) -> RunStatus:
+        view = self._view(run_id)
+        cfg = view.config
+        counts: dict[str, int] = {}
+        for h in view.treatments():
+            final = h.final()
+            if final is not None:
+                key = final["outcome"]
+            else:
+                stages = view.stages_of(h.id)
+                key = f"stage {stages[-1][0]}" if stages else "proposed"
+            counts[key] = counts.get(key, 0) + 1
+        cp = view.open_checkpoint()
+        return RunStatus(
+            run_id=run_id, status=view.status, phase=view.phase, reason=view.reason,
+            spend_usd=self._ledger.spend(run_id).total_usd, money_limit_usd=cfg.limits.money,
+            elapsed_h=view.active_elapsed_s(self._now()) / 3600,
+            wall_clock_limit_h=cfg.limits.wall_clock, hypotheses=counts,
+            open_checkpoints=[cp.id] if cp else [])
+
+    # ==== sessions, recording ===============================================================
+
+    def _new_session(self, config: RunConfig) -> _Session:
+        creds = {n: self._credentials(n) for n in config.credential_names()}
+        llm = self._llm_factory(config.llm, creds)
+        ex = self._executor_factory(config.executor.id, self._credentials)
+        return _Session(config=config, llm=llm, executor=ex, info=ex.describe())
+
+    def _ensure_secrets(self, run_id: str) -> RunConfig:
+        entries = list(self._ledger.entries(run_id, types=["run.created"]))
+        config = RunConfig.model_validate(entries[0].payload["config"])
+        if run_id not in self._secrets_ok:
+            self._ledger.register_secrets(run_id, self._secret_values(config))
+            self._secrets_ok.add(run_id)
+        return config
+
+    def _secret_values(self, config: RunConfig) -> list[str]:
+        """Run secrets (§3, KB-022): the config's LLM and job credentials and every name on
+        the caller's client-credential list. One that cannot be read raises."""
+        names = list(config.credential_names())
+        if self._client_credentials is not None:
+            names += [n for n in self._client_credentials(config) if n not in names]
+        return [self._credentials(n) for n in names]
+
+    def _session(self, run_id: str) -> _Session:
+        if run_id not in self._sessions:
+            config = self._ensure_secrets(run_id)
+            self._ledger.close_dangling(run_id)  # INV-6: a restart closes open starts as lost
+            self._sessions[run_id] = self._new_session(config)
+            # §5 step 9 (KB-020): every `lost` job may still run or hold Docker state.
+            # Reaping is idempotent, so all of them, which also retries a failed reap.
+            self._to_reap[run_id] = [
+                e.payload["experiment"] for e in self._ledger.entries(
+                    run_id, types=["experiment.finished"]) if e.payload["status"] == "lost"]
+        return self._sessions[run_id]
+
+    def _reap(self, run_id: str) -> None:
+        """A failure pauses the run (the executor is unavailable) and is retried."""
+        tags = self._to_reap.get(run_id, [])
+        try:
+            self._sessions[run_id].executor.reap(tags)
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise ExecutorError(f"reaping lost jobs failed: {exc}") from exc
+        self._to_reap[run_id] = []
+
+    def _view(self, run_id: str) -> RunView:
+        return build_view(list(self._ledger.entries(run_id)))
+
+    def _append(self, run_id: str, type_: str, payload: dict[str, Any],
+                refs: list[str] | None = None, *, actor: str = "loop") -> Entry:
+        self._ensure_secrets(run_id)  # writes need the run's secrets registered (INV-7)
+        for attempt in range(3):
+            try:
+                return self._ledger.append(run_id, type_, payload, list(dict.fromkeys(refs or [])),
+                                           actor=actor)  # type: ignore[arg-type]
+            except ConcurrentWrite:
+                if attempt == 2:
+                    raise
+        raise AssertionError("unreachable")
+
+    def _status(self, run_id: str, status: str, phase: str | None, reason: str = "", *,
+                actor: str = "loop", **extra: Any) -> Entry:
+        payload = {"status": status, "phase": phase, "reason": reason,
+                   **{k: v for k, v in extra.items() if v is not None}}
+        return self._append(run_id, "run.status", payload, actor=actor)
+
+    def _put(self, run_id: str, data: bytes, kind: str) -> str | None:
+        self._ensure_secrets(run_id)
+        try:
+            return self._ledger.put_artifact(run_id, data, kind)
+        except LedgerRejection:  # a registered secret: withheld; the ledger logged why
+            return None
+
+    def _record_llm(self, run_id: str, r: Any) -> str:
+        rec = r.to_dict()
+        request, response = rec.pop("request"), rec.pop("response")
+        metered = bool(getattr(r, "metered", True))  # an unmetered model (07 INV-3, KB-036)
+        e = self._append(run_id, "call.recorded", {
+            "source": "llm", "record": rec, "cost_usd": r.cost_usd if metered else None,
+            "metered": metered,
+            "request_artifact": self._put(run_id, json.dumps(request).encode(), "prompt"),
+            "response_artifact": self._put(run_id, (response or "").encode(), "response")})
+        return e.entry_id
+
+    def _record_http(self, run_id: str, source: str, r: Any,
+                     citation_records: list[dict[str, Any]] | None = None) -> str:
+        rec = r.to_dict()
+        request, response = rec.pop("request_body"), rec.pop("response_body")
+        payload: dict[str, Any] = {
+            "source": source, "record": rec, "cost_usd": None, "metered": False,
+            "request_artifact": self._put(run_id, request.encode(), "prompt"),
+            "response_artifact": self._put(run_id, (response or "").encode(), "response")}
+        if citation_records is not None:
+            payload["citation_records"] = citation_records
+        return self._append(run_id, "call.recorded", payload).entry_id
+
+    def _record_all(self, run_id: str, source: str, records: list[Any],
+                    citation_records: list[dict[str, Any]] | None = None) -> list[str]:
+        """Records every call; citation records go on the last one (§5 step 11)."""
+        ids = []
+        for i, r in enumerate(records):
+            last = i == len(records) - 1
+            ids.append(self._record_http(run_id, source, r, citation_records if last else None))
+        return ids
+
+    # ==== limits (INV-5) ====================================================================
+
+    def _fits(self, run_id: str, cost_usd: float, time_s: float, *, writing: bool) -> str | None:
+        view = self._view(run_id)
+        lim = view.config.limits
+        share = 1.0 if writing else 1.0 - lim.writing_reserve
+        spend = self._ledger.spend(run_id).total_usd
+        if spend + cost_usd > lim.money * share:
+            return (f"money: spent {spend:.4f} USD + up to {cost_usd:.4f} USD exceeds "
+                    f"{lim.money * share:.4f} USD")
+        elapsed = view.active_elapsed_s(self._now())
+        if elapsed + time_s > lim.wall_clock * 3600 * share:
+            return (f"wall clock: {elapsed:.0f} s + up to {time_s:.0f} s exceeds "
+                    f"{lim.wall_clock * 3600 * share:.0f} s")
+        return None
+
+    def _guard(self, run_id: str, cost_usd: float, time_s: float = 0.0, *,
+               writing: bool = False) -> None:
+        reason = self._fits(run_id, cost_usd, time_s, writing=writing)
+        if reason:
+            raise LimitReached(f"limit reached: {reason}")
+
+    # ==== calls =============================================================================
+
+    def _ask(self, run_id: str, task: str, instruction: str, data: str,
+             schema: dict[str, Any], *, writing: bool = False) -> dict[str, Any]:
+        s = self._session(run_id)
+        role = {"directions": "planner", "hypothesis": "planner", "rank": "planner",
+                "novelty": "analyst", "harness": "coder", "fix": "coder"}[task]
+        messages: list[Message] = [{"role": "system", "content": instruction},
+                                   {"role": "user", "content": data}]
+        max_tokens = prompts.MAX_TOKENS[task]
+        self._guard(run_id, s.llm.max_cost(role, messages, max_tokens, schema), writing=writing)
+        try:
+            result = s.llm.complete(role, messages, max_tokens=max_tokens, schema=schema)
+        except LLMError as exc:
+            for r in exc.records:
+                self._record_llm(run_id, r)
+            raise
+        for r in result.records:
+            self._record_llm(run_id, r)
+        return dict(result.parsed)
+
+    def _ps(self, run_id: str, fn: Callable[[PureScholar], Awaitable[T]]) -> T:
+        self._guard(run_id, 0.0)  # PureScholar's cost is unmetered (01 §9); time still counts
+
+        async def go() -> T:
+            ps = self._ps_factory()
+            try:
+                return await fn(ps)
+            finally:
+                await ps.aclose()
+
+        try:
+            return asyncio.run(go())
+        except PureScholarError as exc:
+            self._record_all(run_id, "purescholar", exc.records)
+            raise
+
+    def _pt(self, run_id: str, fn: Callable[[PureTrace], Awaitable[T]]) -> T:
+        if self._pt_factory is None:
+            raise _Pause("PureTrace is not configured")
+        cfg = self._view(run_id).config
+        uses = [u for u in ("screening", "selfcheck") if getattr(cfg.puretrace, u)]
+        factory = self._pt_factory
+
+        async def go() -> T:
+            pt = factory(run_id, uses)
+            try:
+                return await fn(pt)
+            finally:
+                await pt.aclose()
+
+        try:
+            return asyncio.run(go())
+        except PureTraceError as exc:
+            self._record_all(run_id, "puretrace", exc.records)
+            raise
+
+    @staticmethod
+    def _citations(items: list[Any]) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for item in items:
+            rec = PureScholar.citation_for(item)
+            if isinstance(rec, CitationRecord) and all(r["key"] != rec.key for r in out):
+                out.append(_asdict(rec))
+        return out
+
+    # ==== error handling ====================================================================
+
+    def _guarded(self, run_id: str, action: Callable[[], None]) -> None:
+        """Runs one step; maps failures to a pause (services) or a failure (rule breaks)."""
+        try:
+            action()
+        except _Pause as exc:
+            self._pause_for(run_id, str(exc))
+        except PriceUnknown as exc:
+            self._fail(run_id, f"llm: {exc}")
+        except LLMError as exc:
+            self._pause_for(run_id, f"llm {type(exc).__name__}: {exc}")
+        except PureScholarError as exc:
+            self._pause_for(run_id, f"purescholar {type(exc).__name__}: {exc}")
+        except PureTraceError as exc:
+            self._pause_for(run_id, f"puretrace {type(exc).__name__}: {exc}")
+        except ExecutorError as exc:
+            self._pause_for(run_id, f"executor {type(exc).__name__}: {exc}")
+        except LedgerRejection as exc:  # a loop bug: the action did not happen (INV-1)
+            self._fail(run_id, f"ledger refused an entry ({exc.rule}): {exc}")
+
+    def _pause_for(self, run_id: str, reason: str) -> None:
+        view = self._view(run_id)
+        self._status(run_id, "paused", view.phase, reason, resume_status=view.status)
+
+    def _fail(self, run_id: str, reason: str) -> None:
+        self._status(run_id, "failed", self._view(run_id).phase, reason)
+
+    # ==== phases ============================================================================
+
+    def _step(self, run_id: str, view: RunView) -> None:
+        phase = view.phase
+        if view.status == "stopping" and phase in ("preflight", "literature", "directions",
+                                                   "exploring"):
+            self._close_open(run_id, view, "user_stopped", "the user stopped the run")
+            self._to_writing(run_id, self._view(run_id))
+        elif phase in ("writing", "selfcheck"):
+            self._write(run_id, view)  # the writer's own limit stops are handled there
+        else:
+            try:
+                if phase == "preflight":
+                    self._preflight(run_id, view)
+                elif phase == "literature":
+                    self._literature(run_id, view)
+                elif phase == "directions":
+                    self._directions(run_id, view)
+                elif phase == "exploring":
+                    self._explore_once(run_id, view)
+                else:
+                    raise AssertionError(f"unknown phase {phase!r}")
+            except LimitReached as exc:  # §5 step 5: the action does not start; write
+                self._close_open(run_id, self._view(run_id), "limit_reached", str(exc))
+                self._to_writing(run_id, self._view(run_id))
+
+    def _preflight(self, run_id: str, view: RunView) -> None:
+        """§5 step 1, INV-8 (SYS-INV-4, SYS-INV-6)."""
+        s = self._session(run_id)
+        cfg = view.config
+        problems: list[str] = []
+        if cfg.puretrace.screening:
+            problems.append("PureTrace screening applies to ML runs only" if cfg.domain != "ml"
+                            else "PureTrace screening is not supported by loop v0.1: no "
+                                 "adapter fetches the baseline paper's PDF")
+        if s.info.isolation == "none" and not cfg.executor.allow_unisolated:
+            problems.append(f"executor {s.info.id} has no isolation and allow_unisolated "
+                            "is false (SYS-INV-6)")
+        if not s.info.metered and not cfg.accept_unmetered_compute:
+            problems.append(f"executor {s.info.id} cannot report cost and "
+                            "accept_unmetered_compute is false (SYS-INV-4)")
+        problems += s.executor.preflight().problems
+        llm_report = s.llm.preflight()
+        for rec in getattr(llm_report, "records", []):  # a self-hosted model's probe (INV-1)
+            self._record_llm(run_id, rec)
+        problems += llm_report.problems
+        unmetered = getattr(llm_report, "unmetered", [])
+        if unmetered and not cfg.accept_unmetered_compute:
+            problems.append(f"models {', '.join(unmetered)} cannot report cost and "
+                            "accept_unmetered_compute is false (SYS-INV-4)")
+        identity = self._ps(run_id, lambda ps: ps.preflight())
+        self._record_all(run_id, "purescholar", identity.records)
+        missing = set(REQUIRED_SCOPES) - set(identity.scopes)
+        if missing:
+            problems.append(f"PureScholar key lacks scopes {sorted(missing)}")
+        if cfg.puretrace.selfcheck:
+            records = self._pt(run_id, lambda pt: pt.preflight())
+            self._record_all(run_id, "puretrace", records)
+        if problems:
+            self._status(run_id, "failed", "preflight", "; ".join(problems))
+        else:
+            self._status(run_id, "running", "literature", "preflight passed")
+
+    def _literature(self, run_id: str, view: RunView) -> None:
+        """§5 step 2."""
+        idea = view.config.idea
+        inputs = []
+        for name in ("literature_map", "find_gaps"):
+            g = self._ps(run_id, lambda ps, n=name: getattr(ps, n)(idea))  # type: ignore[misc]
+            ids = self._record_all(run_id, "purescholar", g.records, self._citations(g.citations))
+            inputs.append(ids[-1])
+        self._status(run_id, view.status or "running", "directions", "literature mapped",
+                     inputs=inputs)
+
+    def _directions(self, run_id: str, view: RunView) -> None:
+        """§5 step 3; C1 in checkpoint mode."""
+        lit_ids = view.inputs
+        if not any(p.get("_actor") != "user" for p in view.ideas.values()):
+            texts = []
+            for cid in lit_ids:
+                digest = view.calls[cid].get("response_artifact")
+                body = self._ledger.get_artifact(run_id, digest).decode() if digest else ""
+                texts.append(_quote(body, f"PureScholar {view.calls[cid]['record']['endpoint']}"))
+            data = f"Research idea: {view.config.idea}\n\n" + "\n\n".join(texts)
+            out = self._ask(run_id, "directions", prompts.DIRECTIONS, data,
+                            prompts.DIRECTIONS_SCHEMA)
+            for d in out["directions"]:
+                self._append(run_id, "idea.proposed", {"direction": d["direction"],
+                                                       "rationale": d["rationale"],
+                                                       "parents": lit_ids}, lit_ids)
+            view = self._view(run_id)
+        if view.config.checkpoint_on("C1") and "C1" not in view.checkpoints:
+            options = [{"id": i, "direction": p["direction"]} for i, p in view.ideas.items()]
+            self._append(run_id, "checkpoint.requested", {"checkpoint_id": "C1",
+                                                          "options": options})
+            self._status(run_id, "paused", "directions", "waiting for checkpoint C1",
+                         resume_status=view.status)
+        else:
+            self._status(run_id, view.status or "running", "exploring", "directions set")
+
+    # ---- exploring (§5 step 4) -------------------------------------------------------------
+
+    def _frontier(self, view: RunView) -> dict[str, str]:
+        """Item id -> description. Hypotheses in progress, and directions not yet tried."""
+        items: dict[str, str] = {}
+        for idea in view.active_directions():
+            hyps = [h for h in view.treatments() if h.idea == idea]
+            if not hyps:
+                items[f"new:{idea}"] = f"new pilot for direction: {view.ideas[idea]['direction']}"
+            for h in hyps:
+                if h.final() is None:
+                    stages = view.stages_of(h.id)
+                    at = stages[-1][0] if stages else "harness"
+                    items[h.id] = f"hypothesis at {at}: {h.statement}"
+        return items
+
+    def _explore_once(self, run_id: str, view: RunView) -> None:
+        items = self._frontier(view)
+        if not items:
+            self._to_writing(run_id, view)
+            return
+        pick = next(iter(items))
+        if len(items) > 1:
+            pick = self._rank(run_id, view, items)
+        if pick.startswith("new:"):
+            self._hypothesis(run_id, view, pick.removeprefix("new:"))
+        else:
+            self._advance(run_id, view, view.hypotheses[pick])
+
+    def _rank(self, run_id: str, view: RunView, items: dict[str, str]) -> str:
+        """§5 step 4.9. The planner orders; code keeps only real ids (INV-6)."""
+        status = self.status(run_id)
+        data = (f"Remaining: {status.money_limit_usd - status.spend_usd:.2f} USD, "
+                f"{status.wall_clock_limit_h - status.elapsed_h:.2f} h.\n"
+                + json.dumps([{"id": k, "item": v} for k, v in items.items()]))
+        out = self._ask(run_id, "rank", prompts.RANK, _quote(data, "frontier"),
+                        prompts.RANK_SCHEMA)
+        order = [str(k) for k in out["order"] if k in items]
+        return (order + list(items))[0]
+
+    def _results_so_far(self, view: RunView) -> str:
+        lines = []
+        for h in view.treatments():
+            final = h.final()
+            lines.append(f"- {h.statement}: {final['outcome'] if final else 'in progress'}"
+                         + (f" ({final.get('reason_code')})" if final and final.get('reason_code')
+                            else ""))
+        return "\n".join(lines) or "none yet"
+
+    def _hypothesis(self, run_id: str, view: RunView, idea: str,
+                    reframe_of: Hyp | None = None, reframed: str | None = None) -> None:
+        """§5 step 4.1: a treatment hypothesis and its baseline."""
+        cfg = view.config
+        data = (f"Research idea: {cfg.idea}\nDomain: {cfg.domain}\n"
+                f"Pilot budget: {cfg.budget_ladder.pilot_minutes} minutes per run\n"
+                + _quote(view.ideas[idea]["direction"], "direction")
+                + (f"\nData hints: {', '.join(cfg.data_hints)}" if cfg.data_hints else "")
+                + "\nResults so far:\n" + _quote(self._results_so_far(view), "ledger summary"))
+        if reframed is not None:
+            data += "\n" + _quote(reframed, "reframed hypothesis to formalise")
+        plan = self._ask(run_id, "hypothesis", prompts.HYPOTHESIS, data,
+                         prompts.HYPOTHESIS_SCHEMA)
+        if not math.isfinite(float(plan["threshold"])):
+            raise _Pause("the planner gave a non-finite threshold")
+        b = self._append(run_id, "hypothesis.proposed", {
+            "statement": plan["baseline"], "idea": idea, "kind": "baseline"}, [idea])
+        payload: dict[str, Any] = {
+            "statement": plan["treatment"], "idea": idea, "kind": "treatment",
+            "baseline": b.entry_id, "plan": {k: plan[k] for k in ("metric", "rule",
+                                                                   "threshold", "data")}}
+        refs = [idea, b.entry_id]
+        if reframe_of is not None:
+            payload["reframes"] = reframe_of.id
+            refs.append(reframe_of.id)
+        self._append(run_id, "hypothesis.proposed", payload, refs)
+
+    def _advance(self, run_id: str, view: RunView, h: Hyp) -> None:
+        if h.novelty is None:
+            self._novelty(run_id, view, h)
+            return
+        smoke_id = view.in_force.get((h.id, SMOKE_STAGE))
+        if smoke_id is None:
+            self._harness(run_id, view, h)
+            return
+        stages = view.stages_of(h.id)
+        if not stages:
+            self._smoke(run_id, view, h, smoke_id)
+            return
+        stage, pid = stages[-1]
+        decided = view.decision_at(h.id, stage)
+        if decided is None:
+            self._run_stage(run_id, view, h, stage, pid)
+        elif decided["outcome"] == "promote":
+            self._register(run_id, view, h, next_stage(view.config.budget_ladder, stage))
+
+    def _novelty(self, run_id: str, view: RunView, h: Hyp) -> None:
+        """§5 step 4.2. The judgement is recorded with its evidence; `overlap` discards
+        (`not_novel`) and, once, reframes."""
+        ev = self._ps(run_id, lambda ps: ps.novelty_evidence(h.statement))
+        closest = self._citations(ev.closest)
+        cited = self._citations(ev.answer.citations)
+        ids = self._record_all(run_id, "purescholar", ev.records,
+                               closest + [c for c in cited if c not in closest])
+        works = "\n".join(f"- {p.title} ({p.year}, {p.venue}): {p.abstract or ''}"
+                          for p in ev.closest)
+        data = (_quote(h.statement, "hypothesis") + "\n"
+                + _quote(works, "PureScholar closest works") + "\n"
+                + _quote(json.dumps(ev.answer.body)[:QUOTE_CHARS], "PureScholar ask"))
+        out = self._ask(run_id, "novelty", prompts.NOVELTY, data, prompts.NOVELTY_SCHEMA)
+        nov = self._append(run_id, "hypothesis.novelty", {
+            "hypothesis": h.id, "evidence": ids, "judgement": out["judgement"],
+            "reason": out["reason"], "closest": closest}, [h.id, *ids])
+        if out["judgement"] == "overlap":
+            self._decide(run_id, h, "0", "discard", "not_novel",
+                         f"overlaps prior work: {out['reason']}", refs=[nov.entry_id])
+            reframed = str(out.get("reframed") or "").strip()
+            if reframed and h.reframes is None:
+                self._hypothesis(run_id, self._view(run_id), h.idea, h, reframed)
+
+    def _harness(self, run_id: str, view: RunView, h: Hyp, *, fix_of: str | None = None,
+                 failure: str = "") -> None:
+        """§5 step 4.4: the coder's harness, registered for a smoke run."""
+        cfg = view.config
+        base = h.baseline or ""
+        data = (_quote(h.statement, "treatment hypothesis") + "\n"
+                + _quote(view.hypotheses[base].statement, "baseline hypothesis") + "\n"
+                + _quote(json.dumps(h.plan), "plan")
+                + (f"\nData hints: {', '.join(cfg.data_hints)}" if cfg.data_hints else ""))
+        task, instruction = "harness", prompts.HARNESS
+        if fix_of is not None:
+            prev = view.preregs[fix_of]
+            files = harness.unbundle(self._ledger.get_artifact(run_id, prev["code_digest"]))
+            data += ("\n" + _quote(json.dumps(files), "previous harness") + "\n"
+                     + _quote(failure, "smoke failure and job output"))
+            task, instruction = "fix", prompts.FIX
+        try:
+            out = self._ask(run_id, task, instruction, data, prompts.HARNESS_SCHEMA)
+            code = harness.bundle(out["files"])
+        except (harness.HarnessInvalid, InvalidOutput) as exc:
+            self._decide(run_id, h, "0", "discard", "harness_error",
+                         f"the coder gave no usable harness: {exc}")
+            return
+        digest = self._ledger.put_artifact(run_id, code, "code")
+        env = {"requirements_lock": out["requirements"]}
+        if fix_of is not None:
+            self._append(run_id, "prereg.amended", {
+                "supersedes": fix_of, "reason": f"harness fix after smoke failure: "
+                                                f"{failure[:500]}",
+                "changes": {"code_digest": digest, "entrypoint": out["entrypoint"], "env": env}},
+                [fix_of])
+            return
+        plan = h.plan
+        self._append(run_id, "prereg.registered", {
+            "hypothesis": h.id, "stage": SMOKE_STAGE, "metric": plan["metric"],
+            "comparison": {"baseline": base, "rule": plan["rule"],
+                           "threshold": float(plan["threshold"])},
+            "evaluation_data": [{"source": plan["data"], "role": "selection",
+                                 "digest": "pending:smoke"}],
+            "budget": self._budget(view, SMOKE_STAGE), "seeds": self._seeds(view, SMOKE_STAGE),
+            "code_digest": digest, "entrypoint": out["entrypoint"], "env": env}, [h.id, base])
+
+    def _budget(self, view: RunView, stage: str) -> dict[str, Any]:
+        s = self._sessions[view.run_id]
+        wall = stage_budget_s(view.config.budget_ladder, stage)
+        jobs = len(ARMS) * len(self._seeds(view, stage)["values"])
+        rate = s.info.rate_usd_per_hour or 0.0
+        return {"wall_clock_s": wall, "kill_at_s": wall * KILL_FACTOR,
+                "money_usd_estimate": jobs * rate * (wall * KILL_FACTOR + GRACE_S) / 3600}
+
+    @staticmethod
+    def _seeds(view: RunView, stage: str) -> dict[str, Any]:
+        """§4: stages before `confirm` run the first seed; `confirm` runs the confirmation
+        seeds."""
+        if stage == CONFIRM_STAGE:
+            n = view.config.budget_ladder.confirmation_seeds
+            return {"policy": "confirmation", "values": list(range(1, n + 1))}
+        return {"policy": "first", "values": [1]}
+
+    def _smoke(self, run_id: str, view: RunView, h: Hyp, smoke_id: str) -> None:
+        """Run the smoke check if needed, then register stage 0, fix, or give up."""
+        pairs = self._missing(view, smoke_id)
+        if pairs:
+            self._run_jobs(run_id, view, smoke_id, SMOKE_STAGE, pairs)
+            view = self._view(run_id)
+        problems = self._smoke_problems(run_id, view, h, smoke_id)
+        if not problems:
+            self._register(run_id, view, h, "0")
+            return
+        if view.amendments.get((h.id, SMOKE_STAGE), 0) >= SMOKE_FIXES:
+            exps = [x.id for x in self._used(view, smoke_id)]
+            self._decide(run_id, h, "0", "discard", "harness_error",
+                         f"smoke run failed after {SMOKE_FIXES} fixes: {problems[0]}",
+                         refs=[smoke_id, *exps])
+            return
+        self._harness(run_id, view, h, fix_of=smoke_id, failure=self._failure_text(
+            run_id, view, smoke_id, problems))
+
+    def _smoke_problems(self, run_id: str, view: RunView, h: Hyp, smoke_id: str) -> list[str]:
+        metric = view.preregs[smoke_id]["metric"]["name"]
+        problems: list[str] = []
+        manifests = []
+        for x in self._used(view, smoke_id):
+            f = x.finished or {}
+            if f.get("status") != "ok":
+                problems.append(f"{x.arm} arm ended {f.get('status')}: "
+                                f"{f.get('environment_problem') or 'see stderr'}")
+                continue
+            if f.get("metrics_problem"):
+                problems.append(f"{x.arm} arm: {f['metrics_problem']}")
+            elif not harness.metric_values(f.get("metrics", []), metric, "selection"):
+                problems.append(f"{x.arm} arm did not report {metric!r} on selection data")
+            sets, problem = self._manifest(run_id, f)
+            if problem:
+                problems.append(f"{x.arm} arm: {problem}")
+            manifests.append(harness.manifest_key(sets))
+        if len(manifests) == len(ARMS) and manifests[0] != manifests[1]:
+            problems.append("the two arms used different data")
+        return problems
+
+    def _failure_text(self, run_id: str, view: RunView, prereg: str, problems: list[str]) -> str:
+        parts = list(problems)
+        for x in self._used(view, prereg):
+            digest = (x.finished or {}).get("artifacts", {}).get("stderr")
+            if digest:
+                tail = self._ledger.get_artifact(run_id, digest).decode("utf-8", "replace")
+                parts.append(f"{x.arm} stderr (tail):\n{tail[-3000:]}")
+        return "\n".join(parts)
+
+    def _manifest(self, run_id: str, finished: dict[str, Any]
+                  ) -> tuple[list[dict[str, Any]], str | None]:
+        digest = finished.get("artifacts", {}).get(harness.MANIFEST_FILE)
+        raw = self._ledger.get_artifact(run_id, digest) if digest else None
+        return harness.parse_manifest(raw)
+
+    def _register(self, run_id: str, view: RunView, h: Hyp, stage: str) -> None:
+        """§5 step 4.5: the stage's pre-registration, from the passed smoke run."""
+        smoke_id = view.in_force[(h.id, SMOKE_STAGE)]
+        smoke = view.preregs[smoke_id]
+        treat = next(x for x in self._used(view, smoke_id) if x.arm == "treatment")
+        sets, _ = self._manifest(run_id, treat.finished or {})
+        self._append(run_id, "prereg.registered", {
+            "hypothesis": h.id, "stage": stage, "metric": smoke["metric"],
+            "comparison": smoke["comparison"], "evaluation_data": sets,
+            "budget": self._budget(view, stage), "seeds": self._seeds(view, stage),
+            "code_digest": smoke["code_digest"], "entrypoint": smoke["entrypoint"],
+            "env": smoke["env"], "smoke": smoke_id},
+            [h.id, smoke["comparison"]["baseline"], smoke_id])
+
+    # ---- experiments (§5 steps 4.6, 5, 10) ---------------------------------------------------
+
+    def _missing(self, view: RunView, prereg_id: str) -> list[tuple[str, int]]:
+        """(arm, seed) pairs with no usable finished experiment. Lost ones are rerun as new
+        experiments under the same pre-registration (§5 step 9)."""
+        done = {(x.arm, x.seed) for x in view.under(prereg_id)
+                if x.finished is not None and x.finished["status"] != "lost"}
+        seeds = view.preregs[prereg_id]["seeds"]["values"]
+        return [(arm, s) for s in seeds for arm in ARMS if (arm, s) not in done]
+
+    @staticmethod
+    def _used(view: RunView, prereg_id: str) -> list[Any]:
+        """The latest usable finished experiment per (arm, seed)."""
+        best: dict[tuple[str, int], Any] = {}
+        for x in view.under(prereg_id):
+            if x.finished is not None and x.finished["status"] != "lost":
+                best[(x.arm, x.seed)] = x
+        return list(best.values())
+
+    def _env(self, run_id: str, prereg: dict[str, Any]) -> tuple[EnvRef, str | None]:
+        s = self._session(run_id)
+        spec = EnvSpec(requirements_lock=str(prereg.get("env", {}).get("requirements_lock", "")))
+        digest = spec.digest()
+        if digest not in s.envs or s.envs[digest].status != "ok":
+            s.envs[digest] = s.executor.build_env(spec)
+        env_art = self._put(run_id, json.dumps(dataclasses.asdict(spec), sort_keys=True).encode(),
+                            "env")
+        return s.envs[digest], env_art
+
+    def _run_jobs(self, run_id: str, view: RunView, prereg_id: str, stage: str,
+                  pairs: list[tuple[str, int]]) -> None:
+        s = self._session(run_id)
+        prereg = view.preregs[prereg_id]
+        budget = float(prereg["budget"]["wall_clock_s"])
+        deadline = budget * KILL_FACTOR
+        rate = s.info.rate_usd_per_hour or 0.0
+        each_usd = rate * (deadline + GRACE_S) / 3600
+        conc = max(1, s.info.concurrency)
+        waves = math.ceil(len(pairs) / conc)
+        self._guard(run_id, each_usd * len(pairs), waves * (deadline + GRACE_S))
+        env, env_art = self._env(run_id, prereg)
+        code = self._ledger.get_artifact(run_id, prereg["code_digest"])
+        if env.status != "ok":
+            if stage != SMOKE_STAGE:
+                raise _Pause(f"environment build failed after a passed smoke run: "
+                             f"{env.log[-500:]}")
+            for arm, seed in pairs:  # recorded as smoke experiments that never ran
+                started = self._start_entry(run_id, s, prereg_id, prereg, env, arm, seed, stage)
+                self._append(run_id, "experiment.finished", {
+                    "experiment": started, "status": "failed", "metrics": [],
+                    "artifacts": {"env": env_art} if env_art else {},
+                    "environment_problem": f"environment build failed: {env.log[-2000:]}",
+                    "cost_usd": None, "metered": False}, [started])
+            return
+        pending = list(pairs)
+        running: dict[str, tuple[JobHandle, float, bool]] = {}
+        try:
+            while pending or running:
+                while pending and len(running) < conc:
+                    in_flight = each_usd * len(running)
+                    self._guard(run_id, in_flight + each_usd, deadline + GRACE_S)
+                    arm, seed = pending.pop(0)
+                    started = self._start_entry(run_id, s, prereg_id, prereg, env, arm, seed,
+                                                stage)
+                    try:
+                        handle = s.executor.submit(JobSpec(
+                            code=code, entrypoint=harness.command(
+                                prereg["entrypoint"], arm, stage, budget),
+                            env=env, seed=seed, deadline_s=deadline,
+                            credentials=tuple(view.config.job_credentials), tag=started))
+                    except (ExecutorError, ValueError) as exc:
+                        self._append(run_id, "experiment.finished", {
+                            "experiment": started, "status": "crashed", "metrics": [],
+                            "artifacts": {}, "environment_problem": f"submit failed: {exc}",
+                            "cost_usd": None, "metered": False}, [started])
+                        raise _Pause(f"executor: submit failed: {exc}") from exc
+                    running[started] = (handle, self._mono(), False)
+                self._sleep(self._poll_s)
+                for sid, (handle, t0, killed) in list(running.items()):
+                    if s.executor.poll(handle) == "done":
+                        status = "timeout" if killed else None
+                        self._finish_entry(run_id, sid, s.executor.result(handle), env_art,
+                                           status)
+                        del running[sid]
+                    elif not killed and self._mono() - t0 > deadline:
+                        s.executor.kill(handle)  # §5 step 5: killed at 110% (`timeout`)
+                        running[sid] = (handle, t0, True)
+        except BaseException as exc:
+            for sid, (handle, _, _) in running.items():
+                try:
+                    s.executor.kill(handle)
+                except ExecutorError:
+                    pass
+                if isinstance(exc, Exception):  # the run pauses or fails; this process lives
+                    self._append(run_id, "experiment.finished", {
+                        "experiment": sid, "status": "lost", "metrics": [], "artifacts": {},
+                        "environment_problem": f"abandoned: {type(exc).__name__}",
+                        "cost_usd": None, "metered": False}, [sid])
+            if isinstance(exc, Exception) and running:
+                try:  # KB-020: nothing of an abandoned job stays on the host
+                    s.executor.reap(list(running))
+                except (ExecutorError, OSError, subprocess.SubprocessError):
+                    self._to_reap[run_id] = list(running)  # retried before the next step
+            raise
+
+    def _start_entry(self, run_id: str, s: _Session, prereg_id: str, prereg: dict[str, Any],
+                     env: EnvRef, arm: str, seed: int, stage: str) -> str:
+        """INV-1: recorded before submission. INV-3: same executor, budget and seeds for
+        both arms."""
+        return self._append(run_id, "experiment.started", {
+            "prereg": prereg_id, "executor_id": s.info.id, "isolation": s.info.isolation,
+            "code_digest": prereg["code_digest"], "env_digest": env.digest, "seed": seed,
+            "arm": arm, "stage": stage}, [prereg_id]).entry_id
+
+    def _finish_entry(self, run_id: str, started: str, r: JobResult, env_art: str | None,
+                      status: str | None) -> None:
+        artifacts: dict[str, str] = {}
+        withheld: list[str] = []
+        files = [("stdout", r.stdout, "stdout"), ("stderr", r.stderr, "stderr")]
+        files += [(name, data, "result") for name, data in sorted(r.outputs.items())]
+        for name, data, kind in files:
+            digest = self._put(run_id, data, kind)
+            if digest:
+                artifacts[name] = digest
+            else:
+                withheld.append(name)
+        if env_art:
+            artifacts["env"] = env_art
+        metrics, problem = harness.parse_metrics(r.metrics)
+        payload: dict[str, Any] = {
+            "experiment": started, "status": status or r.status, "metrics": metrics,
+            "artifacts": artifacts, "duration_s": r.duration_s, "cost_usd": r.cost_usd,
+            "metered": r.metered, "exit_code": r.exit_code}
+        if problem:
+            payload["metrics_problem"] = problem
+        if withheld:
+            payload["withheld"] = withheld
+        self._append(run_id, "experiment.finished", payload, [started])
+
+    # ---- decisions (§5 steps 4.7, 4.8; INV-2, INV-9) ------------------------------------------
+
+    def _run_stage(self, run_id: str, view: RunView, h: Hyp, stage: str, pid: str) -> None:
+        pairs = self._missing(view, pid)
+        if pairs:
+            self._run_jobs(run_id, view, pid, stage, pairs)
+            view = self._view(run_id)
+        prereg = view.preregs[pid]
+        used = self._used(view, pid)
+        exps = [x.id for x in used]
+        fins = [x.finished_id for x in used]
+        statuses = {x.finished["status"] for x in used}
+        refs = [pid, *exps, *fins]
+        if statuses & {"failed", "crashed"}:
+            self._decide(run_id, h, stage, "discard", "harness_error",
+                         "an experiment failed or crashed: a harness error, not a refutation",
+                         prereg=pid, experiments=exps, refs=refs)
+            return
+        if "timeout" in statuses:
+            self._decide(run_id, h, stage, "discard", "infeasible",
+                         f"an experiment ran past {KILL_FACTOR:.0%} of its budget and was "
+                         "killed", prereg=pid, experiments=exps, refs=refs)
+            return
+        if statuses != {"ok"}:
+            self._decide(run_id, h, stage, "inconclusive", "no_signal",
+                         f"experiments ended {sorted(statuses)}", prereg=pid, experiments=exps,
+                         refs=refs)
+            return
+        want = harness.manifest_key(prereg["evaluation_data"])
+        for x in used:
+            sets, problem = self._manifest(run_id, x.finished)
+            if problem or harness.manifest_key(sets) != want:
+                self._decide(run_id, h, stage, "inconclusive", "no_signal",
+                             f"the {x.arm} arm's data manifest differs from the registered "
+                             "digests", prereg=pid, experiments=exps, refs=refs)
+                return
+        role = "held_out" if stage == CONFIRM_STAGE else "selection"
+        metric = prereg["metric"]
+        values: dict[str, list[float]] = {arm: [] for arm in ARMS}
+        uses = []
+        for x in used:
+            found = harness.metric_values(x.finished.get("metrics", []), metric["name"], role)
+            if found:
+                values[x.arm].append(float(found[0]["value"]))
+                uses.append({"experiment": x.finished_id, "name": metric["name"],
+                             "set": found[0]["set"]})
+        if any(len(values[arm]) != len(prereg["seeds"]["values"]) for arm in ARMS):
+            self._decide(run_id, h, stage, "inconclusive", "no_signal",
+                         f"metric {metric['name']!r} missing on {role} data for an experiment",
+                         prereg=pid, experiments=exps, refs=refs)
+            return
+        comp = prereg["comparison"]
+        v = evaluate(comp["rule"], metric["direction"], float(comp["threshold"]),
+                     values["treatment"], values["baseline"],
+                     confirm_stage=stage == CONFIRM_STAGE)
+        self._decide(run_id, h, stage, v.outcome, v.reason_code, v.reason_text, prereg=pid,
+                     experiments=exps, metrics_used=uses if v.outcome != "inconclusive" else [],
+                     comparison={**v.comparison, "data_role": role}, refs=refs)
+
+    def _decide(self, run_id: str, h: Hyp, stage: str, outcome: str, reason_code: str | None,
+                reason_text: str, *, prereg: str | None = None,
+                experiments: list[str] | None = None,
+                metrics_used: list[dict[str, Any]] | None = None,
+                comparison: dict[str, Any] | None = None, refs: list[str] | None = None) -> None:
+        payload: dict[str, Any] = {
+            "hypothesis": h.id, "stage": stage, "outcome": outcome, "reason_text": reason_text,
+            "experiments": experiments or [], "metrics_used": metrics_used or [],
+            "comparison": comparison or {}}
+        if reason_code is not None:
+            payload["reason_code"] = reason_code
+        if prereg is not None and experiments:
+            payload["prereg"] = prereg
+        self._append(run_id, "decision.made", payload, [h.id, *(refs or [])])
+
+    def _close_open(self, run_id: str, view: RunView, code: str, text: str) -> None:
+        """Every hypothesis still open gets an honest end: `user_stopped` or
+        `limit_reached` (INV-9)."""
+        for h in view.treatments():
+            if h.final() is None:
+                stages = view.stages_of(h.id)
+                stage = stages[-1][0] if stages else "0"
+                self._decide(run_id, h, stage, "inconclusive", code, text)
+
+    def _to_writing(self, run_id: str, view: RunView) -> None:
+        """C2 in checkpoint mode (INV-7), then writing."""
+        if view.config.checkpoint_on("C2"):
+            cp = view.checkpoints.get("C2")
+            if cp is None:
+                options: dict[str, list[dict[str, Any]]] = {"confirmed": [], "negative": []}
+                for h in view.treatments():
+                    final = h.final() or {}
+                    item = {"id": h.id, "statement": h.statement,
+                            "outcome": final.get("outcome"),
+                            "reason_code": final.get("reason_code")}
+                    key = "confirmed" if final.get("outcome") == "confirm" else "negative"
+                    options[key].append(item)
+                self._append(run_id, "checkpoint.requested", {"checkpoint_id": "C2",
+                                                              "options": options})
+            if cp is None or cp.decided is None:
+                self._status(run_id, "paused", "exploring", "waiting for checkpoint C2",
+                             resume_status="writing")
+                return
+        self._status(run_id, "writing", "writing", "exploration finished")
+
+    # ---- writing (§5 steps 7, 8) -------------------------------------------------------------
+
+    def _write(self, run_id: str, view: RunView) -> None:
+        s = self._session(run_id)
+        cfg = view.config
+        findings = tuple(h.id for h in view.treatments()
+                         if (h.final() or {}).get("outcome") == "confirm")   # INV-4
+        others = tuple(h.id for h in view.treatments()
+                       if h.final() is not None and h.id not in findings)
+        title = " ".join(cfg.idea.split())[:120]
+        options = PaperOptions(title=title, template=cfg.paper.template,
+                               disclosure=cfg.paper.disclosure,
+                               kind="paper" if findings else "report", findings=findings,
+                               others=others)
+        ps = self._ps_factory()
+        try:
+            writer = self._writer(s.llm, ps)
+            ctx = _Context(self, run_id)
+            try:
+                build = writer.build(run_id, options, ctx)
+            except LimitReached as exc:
+                build = BuildResult(status="failed", reasons=[str(exc)], files={},
+                                    trace_map={}, citation_keys=[])
+            paper = self._record_paper(run_id, build) if build.status == "built" else None
+            if paper and cfg.puretrace.selfcheck:
+                self._status(run_id, "writing", "selfcheck", "self-check")
+                build = self._selfcheck(run_id, writer, build, paper, title, ctx)
+            dest = self._out / run_id / f"bundle-{self._ledger.state(run_id).last_seq}"
+            writer.bundle(run_id, build, dest)
+        finally:
+            asyncio.run(ps.aclose())
+        what = ("paper" if findings else "report") if build.status == "built" else None
+        reason = (f"{what} built" if what else
+                  "no paper built: " + "; ".join(build.reasons)[:500]) + f"; bundle at {dest}"
+        self._status(run_id, "delivered", "delivered", reason, bundle=str(dest))
+
+    def _record_paper(self, run_id: str, build: BuildResult) -> Entry:
+        artifacts = {}
+        for name, data in build.files.items():
+            kind = ("figure" if name.startswith("fig-") else
+                    "paper" if name.endswith((".pdf", ".tex", ".bbl")) else "other")
+            digest = self._put(run_id, data, kind)
+            if digest:
+                artifacts[name] = digest
+        refs = sorted({i for ids in build.trace_map.values() for i in ids})
+        return self._append(run_id, "paper.built", {
+            "artifacts": artifacts, "trace_map": build.trace_map,
+            "citation_keys": build.citation_keys}, refs)
+
+    def _selfcheck(self, run_id: str, writer: Writer, build: BuildResult, paper: Entry,
+                   title: str, ctx: _Context) -> BuildResult:
+        """§5 step 8: assess, one revision with the open questions, assess again."""
+        result = self._assess(run_id, build, paper, title)
+        if not isinstance(result, Assessment) or not result.open_questions:
+            return build
+        try:
+            revised = writer.revise(run_id, build, [q.prompt for q in result.open_questions],
+                                    ctx)
+        except LimitReached:
+            return build
+        if revised.status != "built":
+            return build
+        self._assess(run_id, revised, self._record_paper(run_id, revised), title)
+        return revised
+
+    def _assess(self, run_id: str, build: BuildResult, paper: Entry, title: str) -> Any:
+        pdf = build.pdf or b""
+        result = self._pt(run_id, lambda pt: pt.assess(pdf, title, "puremethod", Artifacts(),
+                                                       None, use="selfcheck"))
+        self._record_all(run_id, "puretrace", result.records)
+        if isinstance(result, Assessment):
+            summary: dict[str, Any] = {
+                "paper_id": result.paper_id, "status": result.status,
+                "paper_type": result.paper_type, "rubric_version": result.rubric_version,
+                "overall": result.overall, "provisional": result.provisional,
+                "dimensions": [{"key": d.key, "score": d.score} for d in result.dimensions],
+                "open_questions": [q.label for q in result.open_questions]}
+        else:
+            summary = {"not_applicable": result.reason, "detected": result.detected}
+        self._append(run_id, "selfcheck.result", {"paper": paper.payload["artifacts"]["main.pdf"],
+                                                  "assessment": summary}, [paper.entry_id])
+        return result
+
+
+class _Context:
+    """The `RunContext` given to `writer` (06-writer.md §3): limits before every call, with
+    the writing reserve released; records after."""
+
+    def __init__(self, loop: Loop, run_id: str) -> None:
+        self._loop = loop
+        self._run_id = run_id
+
+    def guard(self, max_cost_usd: float) -> None:
+        self._loop._guard(self._run_id, max_cost_usd, writing=True)
+
+    def record(self, call_record: Any, artifacts: dict[str, bytes], *,
+               citation_records: list[dict[str, Any]] | None = None) -> None:
+        if hasattr(call_record, "endpoint"):
+            self._loop._record_http(self._run_id, "purescholar", call_record, citation_records)
+        else:
+            self._loop._record_llm(self._run_id, call_record)
+
+
+__all__ = ["LimitReached", "Loop", "RunStatus"]