Deploy 2565f24

Merge pull request #15 from WINTER4000/feat/review-round

Source: https://github.com/WINTER4000/turingDNA/commit/2565f240caa00a235efe766428804beb9c40aa75

dee/core/agent_tools.py

@@ -146,8 +146,9 @@ def _tool_fold_structure(args: Dict[str, Any]) -> Dict[str, Any]:
         logger.exception("fold_structure uniprot resolve failed")
         return {"ok": False, "error": "Structure lookup failed — try again shortly."}
     if not result.get("ok"):
-        return {"ok": False, "error": result.get("error") or "No structure found."}
-    return {
+        return {"ok": False, "error": result.get("error") or "No structure found.",
+                "kind": result.get("kind") or ""}
+    out = {
         "ok": True,
         "gene_symbol": gene,
         "organism": organism,
@@ -156,6 +157,22 @@ def _tool_fold_structure(args: Dict[str, Any]) -> Dict[str, Any]:
         "alphafold_page": result.get("alphafold_page", ""),
         "source": "AlphaFold DB",
     }
+    # WHICH entry this actually is, not just its accession. The agent said
+    # "I6ZGA9" for beta-lactamase TEM-1 and the reviewer had no way to tell
+    # from that whether it was the right protein — it was a 264 aa fragment
+    # where they had pasted 286 aa (see resolve.resolve_uniprot). The
+    # identifying facts have to travel with the accession.
+    for key in ("entry_name", "protein_name", "protein_length", "reviewed",
+                "matched_organism", "plddt", "model_version",
+                "structure_verified"):
+        if result.get(key) is not None:
+            out[key] = result[key]
+    # Caveats are not decoration. A fragment entry's residue numbers do not
+    # line up with the user's sequence, and passing that on silently is how a
+    # scientist mutates the wrong position.
+    if result.get("caveats"):
+        out["caveats"] = list(result["caveats"])
+    return out
 
 
 # The subset of a guide worth reading inline in a chat reply. The full

dee/core/crispr.py

@@ -262,6 +262,27 @@ _CFD_PAM: Dict[str, float] = {
 }
 
 
+# ─── The one tuning constant in the whole CRISPR ranking ─────────────
+#
+#     composite = on_target × (1 − COMPOSITE_OFFTARGET_WEIGHT × self_off)
+#
+# 0.6 is a JUDGEMENT CALL, not a published constant, and it is the only
+# number in this file that isn't traceable to a paper. It decides how hard
+# a self-off-target hit demotes a guide: at 0.6, a guide whose spacer is
+# duplicated exactly elsewhere in the pasted input (CFD 1.0) keeps 40% of
+# its on-target score instead of collapsing to zero — because a repeat
+# inside a pasted region is often a legitimate second copy of the target,
+# not a disqualifying off-target, and zeroing it would bury guides that
+# are fine for the user's actual experiment.
+#
+# It is a named, exported constant (and is serialised onto every guide by
+# guide_to_dict) specifically so the UI can print the arithmetic. A
+# reviewing scientist ranked a table by "composite" and had no way to find
+# out that a 0.6 weight existed at all; a weight nobody can see is not a
+# method, it's a hunch with a decimal point.
+COMPOSITE_OFFTARGET_WEIGHT = 0.6
+
+
 # ─── Data classes ────────────────────────────────────────────────────
 
 @dataclass
@@ -402,6 +423,13 @@ def guide_to_dict(g: "GuideRNA") -> Dict[str, Any]:
         "pam":               g.pam,
         "target_context":    g.target_context,
         "composite_score":   g.composite_score,
+        # The weight that made composite_score, shipped WITH the number it
+        # weighted. The table sorts by composite, so the user is entitled to
+        # see the arithmetic; sending the constant per row (rather than once
+        # per response) means the agent's design_crispr_guides path, which
+        # builds its panel straight from these dicts and never touches the
+        # REST envelope, discloses it too.
+        "composite_offtarget_weight": COMPOSITE_OFFTARGET_WEIGHT,
         "on_target_score":   g.on_target_score,
         "cfd_max_offtarget": g.cfd_max_offtarget,
         "offtarget_count":   g.offtarget_count,
@@ -1124,8 +1152,10 @@ def find_guides(
             spacer, pos, all_candidates, enzyme,
         )
         # Composite score: on-target activity discounted by off-target
-        # penalty. A guide with on=0.9 and max_cfd=0.5 ends up at ~0.45.
-        composite = on_score * (1.0 - 0.6 * max_cfd)
+        # penalty. A guide with on=0.9 and max_cfd=0.5 ends up at ~0.63.
+        # The weight is named (not inlined) because the UI prints it —
+        # see COMPOSITE_OFFTARGET_WEIGHT for why 0.6 and not 1.0.
+        composite = on_score * (1.0 - COMPOSITE_OFFTARGET_WEIGHT * max_cfd)
         # Cut-position for the KO position-bias heuristic. Display-only:
         # ko_efficacy is NOT part of composite_score, so this never
         # reorders the table. Use the SAME strand-aware cut convention as

dee/core/crispr_methods.py

@@ -24,11 +24,26 @@ METHODS: Dict[str, Dict[str, Any]] = {
         "label": "Composite",
         "what": "The column the table sorts by — one number balancing "
                 "how well a guide should cut against how uniquely it targets.",
-        "formula": "composite = on_target × (1 − self_off)",
-        "basis": "A plain product of the two scores below. There are no hidden "
-                 "weights and no tuning constants: an efficacy estimate scaled "
-                 "down by the specificity penalty.",
-        "limits": "Inherits every limit of its two inputs — in particular the "
+        # Kept in sync with dee.core.crispr.COMPOSITE_OFFTARGET_WEIGHT by
+        # test_composite_weight_is_disclosed_with_its_real_value, because this
+        # entry previously claimed a formula the code did not use.
+        "formula": "composite = on_target × (1 − 0.6 × self_off)",
+        "basis": "An efficacy estimate scaled down by the specificity "
+                 "penalty. The 0.6 is the only tuning constant in the whole "
+                 "CRISPR ranking and it is our judgement call, not a "
+                 "published value: it means a guide whose spacer is "
+                 "duplicated exactly elsewhere in your input keeps 40% of "
+                 "its on-target score instead of dropping to zero, because a "
+                 "repeat inside a pasted region is often a second legitimate "
+                 "copy of your target rather than a disqualifying "
+                 "off-target. Every guide carries the weight in its own row "
+                 "(composite_offtarget_weight), so the arithmetic is "
+                 "checkable per guide.",
+        "limits": "The 0.6 is uncalibrated — no measured cleavage dataset was "
+                  "used to fit it, and a different weight would reorder guides "
+                  "whose self-off scores differ. Sort by On-target and Self-off "
+                  "separately if you want to apply your own trade-off. It also "
+                  "inherits every limit of its two inputs — in particular the "
                   "specificity term only sees the sequence you pasted.",
         "citations": [],
     },
@@ -116,6 +131,17 @@ METHODS: Dict[str, Dict[str, Any]] = {
                  "the templated single-base insertion class Cas9 is known to "
                  "produce. These ARE per-guide, sequence-driven predictions — "
                  "not a fixed average.",
+        # The repair context these numbers assume, stated as a first-class
+        # field so the UI can print it next to FS % rather than leaving the
+        # reader to infer it. Everything here is read off the algorithm:
+        # crispr._predict_indels models MMEJ deletions + a fixed 32% templated
+        # +1 insertion class and has no donor, cell-type or organism argument.
+        "assumes": "Template-free end-joining repair (MMEJ + classical NHEJ) "
+                   "of a blunt Cas9 double-strand break, in a cell with intact "
+                   "repair machinery and no HDR donor supplied. Supply a repair "
+                   "template, use a nickase or a base editor, or work in a "
+                   "repair-deficient background, and these outcomes do not "
+                   "apply.",
         "limits": "Two real limits. (1) HEURISTIC: this is not the inDelphi "
                   "neural network — it reproduces roughly 80% of that model's "
                   "rank-ordering, not its calibrated frequencies. (2) "
@@ -138,15 +164,53 @@ METHOD_ORDER: List[str] = ["composite", "on_target", "self_off", "genome_off",
                            "ko_score", "indels"]
 
 
+def genome_scopes() -> Dict[str, Dict[str, Any]]:
+    """What the genome off-target search actually covers, per organism.
+
+    Read straight off ``offtarget.GENOME_SOURCES`` rather than restated here:
+    the results panel prints this next to the off-target numbers, and a
+    hand-copied list is exactly how a panel ends up claiming a whole-genome
+    screen for an organism that is indexed over coding sequence only. Adding
+    an organism to the registry adds it here with no second edit.
+    """
+    try:
+        from dee.core.offtarget import GENOME_SOURCES
+    except Exception:  # noqa: BLE001 — provenance must never break the route
+        return {}
+    out: Dict[str, Dict[str, Any]] = {}
+    for key, src in GENOME_SOURCES.items():
+        scope = str(src.get("scope", ""))
+        complete = scope == "full genome"
+        out[key] = {
+            "name": str(src.get("name", key)),
+            "scope": scope,
+            "complete": complete,
+            # One sentence the UI can print verbatim, so the wording lives
+            # next to the registry that decides whether it is true.
+            "note": (
+                "Complete genome indexed — an off-target anywhere is found."
+                if complete else
+                "CODING SEQUENCE ONLY. Off-targets in introns, intergenic and "
+                "regulatory DNA are outside this index and will not appear. "
+                "Use a whole-genome tool if your application needs them."
+            ),
+        }
+    return out
+
+
 def methods_payload() -> Dict[str, Any]:
     """Serializable provenance block for GET /api/crispr/methods."""
     return {
         "order": list(METHOD_ORDER),
         "methods": {k: dict(METHODS[k]) for k in METHOD_ORDER},
+        "genome_scopes": genome_scopes(),
         "summary": (
             "Every score here is computed from published, sequence-based "
-            "methods — no black box. Two scope limits matter most: for human "
-            "and mouse the genome off-target search covers coding sequence "
-            "only, and indel predictions are not tuned to your cell type."
+            "methods — no black box, and exactly one tuning constant (the "
+            "0.6 off-target weight in Composite, which is our judgement "
+            "call). Two scope limits matter most: for human and mouse the "
+            "genome off-target search covers coding sequence only, and indel "
+            "predictions assume template-free end-joining repair with fixed "
+            "constants — they are not tuned to your cell type."
         ),
     }

dee/core/epistasis.py

@@ -174,22 +174,103 @@ def _magnitude_word(x: float) -> str:
     return "strong" if ax >= 1.5 else "moderate" if ax >= 0.7 else "slight"
 
 
+# A site is only worth naming as a second actor if it moved enough to mean
+# something. Same 0.3 the UI uses to tint a mutation chip (app.js
+# _radarSiteChip), so the prose and the colours agree about what "moved" is.
+_SITE_NOTABLE = 0.3
+
+
+def _plural(n: int, word: str) -> str:
+    return f"{n} {word}" if n == 1 else f"{n} {word}s"
+
+
+def _the_others(n_other: int, verb_sing: str, verb_plur: str) -> str:
+    """'The other site barely moves' / 'The other 3 sites barely move'.
+    A bare _plural() here produced "The other 1 site barely move"."""
+    subject = "The other site" if n_other == 1 else f"The other {n_other} sites"
+    return f"{subject} {verb_sing if n_other == 1 else verb_plur}"
+
+
 def _narrate(verdict: str, sites: List[SiteShift], risk: float, signed: float) -> str:
+    """One row's explanation, built from THAT row's numbers.
+
+    This used to be one fixed sentence per verdict class, so a ten-row
+    Interaction Radar printed the same three sentences over and over and a
+    reviewing scientist read the whole panel as copy-paste — the analysis
+    looked like it had not actually run per variant. Nothing here inflates:
+    every adjective is a threshold lookup (:func:`_magnitude_word`) over a
+    number that is also printed, and the sites named are the ones that
+    actually moved. Two rows in the same verdict class differ because their
+    measurements differ, which is the point.
+    """
     if verdict == "single":
+        # sites carries the one substitution, so the marginal can be stated
+        # rather than the row reading as an empty "nothing to see here".
+        if sites:
+            s = sites[0]
+            return (f"{s.label} is the only substitution — nothing for it to interact "
+                    f"with. On the wild-type background it scores {s.marginal_ll:+.2f} ΣΔLL.")
         return "A single substitution — no interactions to analyze."
+
+    n = len(sites)
     if verdict == "independent":
-        return ("The substitutions act roughly independently — no strong "
-                "interaction detected. Predicted fitness should hold up.")
+        if not sites:
+            return ("No scorable interaction between these substitutions — they "
+                    "look independent.")
+        top = max(sites, key=lambda s: abs(s.shift))
+        # "Nothing moved at all" and "two sites moved and cancelled out" are
+        # both 'independent', and they are not the same finding. Leading with
+        # the same clause for both is what made these rows interchangeable.
+        movers = [s for s in sites if abs(s.shift) >= _SITE_NOTABLE]
+        if not movers:
+            return (f"Nothing moves much in context — the largest shift is {top.label} "
+                    f"at {top.shift:+.2f} ΣΔLL, well inside the ±{COOP_FLOOR:g} flag "
+                    f"threshold. The {n} substitutions act independently, so the "
+                    f"additive score should hold.")
+        spread = ("every site shifts but they cancel out" if len(movers) == n
+                  else f"{_plural(len(movers), 'site')} of {n} shifts")
+        return (f"Largest context shift is {top.label} at {top.shift:+.2f} ΣΔLL "
+                f"({top.marginal_ll:+.2f} alone → {top.context_ll:+.2f} in combination); "
+                f"{spread}, for a net {signed:+.2f} ΣΔLL — under the ±{COOP_FLOOR:g} flag "
+                f"threshold. Independent enough that the additive score should hold.")
+
     if verdict == "clash":
-        worst = min(sites, key=lambda s: s.shift)   # most negative
-        return (f"Predicted antagonism: {worst.label} looks {_magnitude_word(worst.shift)}ly "
-                "less favorable once the other mutations are present — the substitutions may "
-                "clash. Worth testing it separately, or dropping it from this combination.")
+        worst = min(sites, key=lambda s: s.shift)          # most negative
+        others = [s for s in sites if s is not worst and s.shift <= -_SITE_NOTABLE]
+        if others:
+            second = min(others, key=lambda s: s.shift)
+            extra = (f" {second.label} is dragged down too ({second.shift:+.2f}), so "
+                     f"{_plural(len(others) + 1, 'site')} of {n} antagonize.")
+        else:
+            extra = " " + _the_others(n - 1, "is largely unaffected.",
+                                      "are largely unaffected.")
+        # The worst site IS the whole risk in a 2-site variant with one loser,
+        # so restating it as a "total" reads like a second, disagreeing number.
+        total = (f" Total antagonism across the variant is {risk:.2f} ΣΔLL."
+                 if risk - abs(worst.shift) >= 0.05 else "")
+        return (f"{worst.label} loses {abs(worst.shift):.2f} ΣΔLL once the other "
+                f"substitutions are present ({worst.marginal_ll:+.2f} alone → "
+                f"{worst.context_ll:+.2f} in combination) — a {_magnitude_word(worst.shift)} "
+                f"antagonistic shift, so this combination is flagged as a clash.{extra}"
+                f"{total} Test {worst.label} on its own, or drop it from this combination.")
+
     # cooperative
     best = max(sites, key=lambda s: s.shift)
-    return (f"Predicted cooperativity: the substitutions reinforce each other — {best.label} "
-            f"looks {_magnitude_word(best.shift)}ly stronger in this combination than alone. "
-            "A promising multi-mutant to prioritize.")
+    gained = [s for s in sites if s.shift >= _SITE_NOTABLE]
+    drag = [s for s in sites if s.shift <= -_SITE_NOTABLE]
+    if len(gained) > 1:
+        extra = f" {_plural(len(gained), 'site')} of {n} gain in context."
+    elif drag:
+        worst = min(drag, key=lambda s: s.shift)
+        # Honest counterweight: net cooperative does not mean every site won.
+        extra = (f" {worst.label} still loses {abs(worst.shift):.2f} ΣΔLL, so the gain "
+                 f"is not uniform across the {n} sites.")
+    else:
+        extra = " " + _the_others(n - 1, "barely moves.", "barely move.")
+    return (f"{best.label} gains {best.shift:.2f} ΣΔLL in this combination "
+            f"({best.marginal_ll:+.2f} alone → {best.context_ll:+.2f} together) — a "
+            f"{_magnitude_word(best.shift)} cooperative shift, so the substitutions "
+            f"reinforce each other.{extra} Net {signed:+.2f} ΣΔLL over the additive score.")
 
 
 def _wt_rows(
@@ -252,12 +333,15 @@ def analyze_variant(
         w, p, m = sites_parsed[0]
         row = _wt_rows(wt_protein, [p], masked_log_probs_fn, wt_cache)[p]
         marg = float(row[_AA_COL[m]] - row[_AA_COL[w]])
+        only = SiteShift(f"{w}{p + 1}{m}", p, w, m, marg, marg, 0.0)
         return VariantEpistasis(
             variant_id=variant_id, mutations=mut_str, n_sites=1,
             additive_score=marg, epistasis_signed=0.0, epistasis_risk=0.0,
             corrected_score=marg, verdict="single",
-            note=_narrate("single", [], 0.0, 0.0),
-            sites=[SiteShift(f"{w}{p + 1}{m}", p, w, m, marg, marg, 0.0)],
+            # The site goes in so the note can quote the real marginal instead
+            # of the same content-free sentence on every single-mutant row.
+            note=_narrate("single", [only], 0.0, 0.0),
+            sites=[only],
         )
 
     mutant = _apply_mutations(wt_protein, sites_parsed)

dee/core/orchestrator.py

@@ -76,12 +76,45 @@ MAX_EXTENSIONS = 4
 _STEER_MAX_QUEUED = 8
 _STEER_MAX_CHARS = 4000
 
+# Extensions granted WITHOUT stopping to ask, while the run is still doing
+# real work and the money is not the binding constraint. The reviewer's
+# 2026-07-30 log has "I've used this stretch of the run … say continue" firing
+# repeatedly, with the reviewer typing "continue" each time — which reads as
+# the agent stalling, not pacing itself. The step cap was never the guard that
+# mattered (the cost cap is, and this file has said so since it was written);
+# it was just the loud one. So the first few stretches extend themselves and
+# the user is only asked when there is a real decision to make: no progress,
+# or the budget genuinely running down.
+AUTO_EXTENSIONS = 2
+
+# Spend, as a fraction of the run's cost cap.
+#   WARN       — say so once, in the user's terms, and keep going.
+#   CHECKPOINT — park while there is still enough left to finish something.
+# The old code had neither: the first and only signal about money was the
+# ceiling, delivered as a red error block mid-task ("not clear what happened
+# here / was this a user limit?").
+COST_WARN_FRACTION = 0.60
+COST_CHECKPOINT_FRACTION = 0.85
+
 # Hard ceiling on retained history. Gemini's window is ~1M tokens so this
 # isn't about fitting — it's about an abandoned tab not silently costing more
 # every turn. Oldest messages drop first; the system prompt is never part of
 # history (rebuilt per call) so it can't be evicted.
 MAX_HISTORY_MESSAGES = 80
 
+# How much of the bound target's sequence survives compaction. Pinning the
+# letters is the whole fix for "asked for protein sequence again even though
+# it was given the sequence 1 turn ago" — but a pinned 400 kb plasmid re-sent
+# every step would be a bill, not a fix. Above this the pin keeps the target's
+# IDENTITY and says plainly that the letters were dropped, so the agent
+# re-fetches instead of asking the user to paste it again.
+TARGET_PIN_MAX_NT = 20_000
+
+# Every message this module pins into the head of a compacted history. They
+# are our own scaffolding, not things the user said, so _digest_dropped must
+# not re-report them back as "earlier from the user".
+_PIN_PREFIX = "[TuringDNA pinned]"
+
 _RUN_TTL_SECONDS = 6 * 60 * 60  # matches agent.py's session TTL
 
 
@@ -292,6 +325,29 @@ class Run:
     # looking this up there would mean a database round-trip per step for
     # something that doesn't change within a run.
     continuity: str = ""
+    # WHAT THIS RUN IS ABOUT. See _bind_target: the single most consequential
+    # field on a Run, and the thing whose absence caused the worst failure in
+    # the 2026-07-30 reviewer log — the agent planning a thermostability job
+    # against a protein from a DIFFERENT conversation. Empty until a tool
+    # actually resolves something; a run must never assert a target it does
+    # not have.
+    target: Dict[str, Any] = field(default_factory=dict)
+    # Real tool executions (ask_user and update_plan don't count — neither
+    # changes anything in the world). Compared against tools_at_checkpoint to
+    # tell "still working" from "looping", which is what decides whether the
+    # step budget extends itself or stops and asks.
+    tools_run: int = 0
+    tools_at_checkpoint: int = 0
+    # The spend warning fires once per run, not once per step.
+    budget_warned: bool = False
+    # This run's compute allowance and whether it is gone. Mirrored onto the
+    # Run (from OpenRouterConfig at spawn) so the HTTP layer can answer "can
+    # this run continue?" without re-reading the environment — and so the
+    # client can show the budget rather than being surprised by it.
+    cost_limit_usd: float = 0.0
+    budget_spent: bool = False
+    # Set when this run was seeded from an earlier one that ran out of budget.
+    carried_from: str = ""
 
 
 _RUNS: Dict[str, Run] = {}
@@ -484,6 +540,11 @@ def public_state(run: Run) -> Dict[str, Any]:
             "seq": run.seq,
             "steps": run.steps,
             "cost_usd": round(run.cost_usd, 6),
+            # Published so a client can SHOW the allowance instead of the user
+            # meeting it for the first time as a wall (reviewer, 2026-07-30:
+            # "not clear what happened here / was this a user limit?").
+            "cost_limit_usd": round(run.cost_limit_usd, 6),
+            "budget_spent": run.budget_spent,
             "context_tokens_used": run.context_tokens,
             "context_tokens_limit": _llm.CONTEXT_WINDOW_TOKENS,
             "plan": list(run.plan),
@@ -491,6 +552,104 @@ def public_state(run: Run) -> Dict[str, Any]:
         }
 
 
+# ─── The run's target ───────────────────────────────────────────────────
+# THE incident this exists for (reviewer log, 2026-07-30, beta-lactamase
+# TEM-1): asked to "design a more thermostable variant of this protein", the
+# agent "began referencing a protein from a different conversation instead of
+# the current conversation" — it planned against IsPETase, a target from
+# another run. In the same session it also asked the reviewer for a sequence
+# it had been given one turn earlier.
+#
+# Both are the same hole. Nothing bound a run to what the run was ABOUT. The
+# target existed only as a `tool` message inside run.history, which compaction
+# is free to evict, while the system prompt — rebuilt from scratch and re-sent
+# on EVERY step — carried the user's saved libraries under a heading telling
+# the model not to start from scratch on work they already had. So the most
+# prominent, most repeated, most instruction-shaped thing in context named a
+# target from a different conversation, and the one the user was actually
+# talking about was a truncated JSON blob forty messages back, or gone.
+#
+# Binding is deliberately EVIDENCE-ONLY: a target is recorded when a tool
+# actually resolved one, never inferred from what the user typed. A run that
+# has resolved nothing asserts nothing.
+
+def _bind_target(run: Run, name: str, args: Dict[str, Any],
+                 result: Dict[str, Any]) -> None:
+    """Record what this run is about, from a tool result that proves it."""
+    if not isinstance(result, dict) or not result.get("ok"):
+        # A failed lookup is not a target. Binding "Couldn't find blaTEM"
+        # would put a name the tool explicitly refused into the standing
+        # instructions as established fact.
+        return
+
+    if name == "fetch_sequence":
+        seq = str(result.get("sequence") or "")
+        if not seq:
+            return
+        # A later successful resolve REPLACES the binding: that is the user
+        # changing subject mid-run, and a binding that couldn't follow them
+        # would be a cage rather than a fix.
+        run.target = {
+            "label": str(result.get("label") or "")[:120],
+            "gene_symbol": str(result.get("gene_symbol") or "")[:32],
+            "organism": str(args.get("organism") or "")[:48],
+            "kind": str(result.get("kind") or "")[:24],
+            "source": str(result.get("source") or "")[:24],
+            "length": int(result.get("length") or len(seq)),
+            "sequence": seq,
+            "bound_at_step": run.steps,
+        }
+        return
+
+    if name == "fold_structure":
+        acc = str(result.get("uniprot") or "")[:16]
+        if run.target:
+            # ENRICH, never replace. fold_structure resolves an accession;
+            # letting it redefine the run's subject is the bleed itself, one
+            # stray structure lookup away.
+            if acc and not run.target.get("uniprot"):
+                run.target = dict(run.target, uniprot=acc)
+            return
+        # Nothing bound yet: "fold TEM-1" IS the run's subject, even with no
+        # sequence in hand. No `sequence` key — we have not resolved one.
+        gene = str(result.get("gene_symbol") or "")[:32]
+        if not gene:
+            return
+        run.target = {
+            "label": gene,
+            "gene_symbol": gene,
+            "organism": str(result.get("organism") or "")[:48],
+            "kind": "structure",
+            "source": str(result.get("source") or "")[:24],
+            "uniprot": acc,
+            "bound_at_step": run.steps,
+        }
+
+
+def _target_pin(target: Dict[str, Any]) -> str:
+    """The target, phrased so it survives compaction intact.
+
+    This is the mechanical half of the re-ask fix. `_trim_history` evicts the
+    oldest messages and `_digest_dropped` replaces them with "tools already
+    run: fetch_sequence" — the LETTERS are destroyed, and after that the only
+    way for the agent to obtain the user's sequence is to ask for it again.
+    Which is exactly what the reviewer saw.
+    """
+    label = (target.get("label") or target.get("gene_symbol")
+             or "the target of this run")
+    seq = str(target.get("sequence") or "")
+    n = int(target.get("length") or len(seq))
+    head = f"{_PIN_PREFIX} Target of this run: {label}"
+    if not seq:
+        return head
+    if len(seq) <= TARGET_PIN_MAX_NT:
+        return (f"{head} — the sequence already resolved in this "
+                f"conversation, {n:,} nt:\n{seq}")
+    return (f"{head} — {n:,} nt, too long to keep pinned in context. Call "
+            f"fetch_sequence again if you need the letters. Do NOT ask the "
+            f"user to re-send something they already gave you.")
+
+
 def _digest_dropped(messages: List[Dict[str, Any]]) -> str:
     """A compact, factual account of history about to be evicted.
 
@@ -518,7 +677,11 @@ def _digest_dropped(messages: List[Dict[str, Any]]) -> str:
                 tools[-1] += " (failed)"
         elif role == "user":
             text = str(m.get("content") or "").strip()
-            if text:
+            # Our own pinned scaffolding is not something the user said.
+            # Re-reporting it as "earlier from the user" turned the goal pin
+            # into a fake quote, and would drag a pinned sequence's first 160
+            # bases into the digest as if the user had typed them.
+            if text and not text.startswith(_PIN_PREFIX):
                 asks.append(text[:160])
 
     bits: List[str] = []
@@ -571,7 +734,14 @@ def _trim_history(run: Run) -> Optional[str]:
     # forgotten what it was asked will still answer — just not the question.
     if run.goal:
         head.append({"role": "user",
-                     "content": f"[Original request, pinned] {run.goal}"})
+                     "content": f"{_PIN_PREFIX} Original request: {run.goal}"})
+    # Re-pin the target too. The goal survives compaction but the SEQUENCE did
+    # not, and an agent that remembers it was asked to make a protein more
+    # thermostable but no longer holds the protein will do the only thing left
+    # — ask the user for it again. That is the reviewer's "asked for protein
+    # sequence again even though it was given the sequence 1 turn ago".
+    if run.target:
+        head.append({"role": "user", "content": _target_pin(run.target)})
     head.append({"role": "user", "content": note})
     run.history = head + run.history[cut:]
     return note
@@ -587,12 +757,31 @@ def _drive(run: Run, config: _llm.OpenRouterConfig) -> None:
     instead of spinning on a run that quietly died.
     """
     try:
-        while run.steps < MAX_STEPS + run.extensions * STEP_EXTENSION:
+        while True:
+            # ── Out of steps? Buy more, if this is still work. ────────────
+            # The step budget used to end the stretch and make the user type
+            # "continue", every 24 steps, no matter how well it was going.
+            # _auto_extend takes that decision when there is nothing for the
+            # user to decide; when there IS (nothing is landing, or the money
+            # is running down) it declines and we checkpoint properly.
+            if run.steps >= MAX_STEPS + run.extensions * STEP_EXTENSION:
+                if not _auto_extend(run, config):
+                    _checkpoint(run, reason="steps")
+                    return
+
             if run.stop_requested:
                 run.status = "stopped"
                 _emit(run, "done", {"reason": "stopped"})
                 return
 
+            # ── Money, checked before another step is spent ───────────────
+            # Parking with budget still on the clock leaves a run the user can
+            # resume. The old code only ever noticed spend AFTER the ceiling
+            # had been crossed, which leaves nothing to resume with.
+            if _cost_fraction(run, config) >= COST_CHECKPOINT_FRACTION:
+                _checkpoint(run, reason="cost")
+                return
+
             # Anything the user typed while we were working lands HERE, at a
             # clean boundary. It cannot go in mid-step: a user message spliced
             # between an assistant tool_calls message and its results makes the
@@ -615,7 +804,8 @@ def _drive(run: Run, config: _llm.OpenRouterConfig) -> None:
                 # workspace that no longer matches what the user is looking at.
                 "messages": ([{"role": "system",
                                "content": build_system_prompt(
-                                   run.anonymous, run.workspace, run.continuity)}]
+                                   run.anonymous, run.workspace, run.continuity,
+                                   run.target)}]
                              + run.history),
                 "tools": TOOL_SPECS,
                 "temperature": 0,
@@ -632,14 +822,11 @@ def _drive(run: Run, config: _llm.OpenRouterConfig) -> None:
 
             run.cost_usd += cost
             run.context_tokens = ptoks
-            if run.cost_usd > config.max_cost_usd:
+            if _cost_fraction(run, config) >= 1.0:
                 logger.warning("run %s exceeded cost cap (%.4f)", run.run_id, run.cost_usd)
-                run.status = "error"
-                _emit(run, "error", {
-                    "error": "This run hit its budget ceiling. Start a new one to continue.",
-                    "error_kind": "cost_capped",
-                })
+                _budget_spent(run, config)
                 return
+            _warn_on_spend(run, config)
 
             text = (message.get("content") or "").strip()
             tool_calls = message.get("tool_calls") or []
@@ -703,10 +890,6 @@ def _drive(run: Run, config: _llm.OpenRouterConfig) -> None:
             if note:
                 _emit(run, "compacted", {"note": note})
 
-        # ── Budget spent. A checkpoint, not a wall. ──────────────────────
-        _checkpoint(run)
-        return
-
     except Exception:  # noqa: BLE001 — a crashed thread must not hang the client
         logger.exception("orchestrator run %s crashed", run.run_id)
         run.status = "error"
@@ -777,9 +960,13 @@ def _run_one_tool(run: Run, name: str, call_id: str, args: Dict[str, Any]) -> bo
 
     # run.owner is the user_id for a signed-in run, "ip:<hash>" for anonymous.
     # Only pass a real id — an anonymous run must never resolve to a row.
+    run.tools_run += 1
     result = _tools.execute_tool(name, args, run.anonymous,
                                  user_id=(None if run.anonymous else run.owner))
     model_result = _strip_ui(result)
+    # Bind BEFORE the event is emitted, so the very next system prompt — the
+    # one the model plans with — already knows what this run is about.
+    _bind_target(run, name, args, result)
 
     _emit(run, "tool_result", {
         "id": call_id,
@@ -835,31 +1022,227 @@ def _clean_plan(raw: Any) -> List[Dict[str, str]]:
     return out
 
 
-def _checkpoint(run: Run) -> None:
-    """Out of step budget — report where we got to and offer to continue.
+# ─── Budget: warn, pace, hand over ──────────────────────────────────────
+# The reviewer's 2026-07-30 note on the old ceiling was "not clear what
+# happened here / was this a user limit?" — a fair question, because
+# "This run hit its budget ceiling. Start a new one to continue." names no
+# amount, no unit and no owner, arrives as a red error block, and strands
+# everything the run had already done. All three are fixed below.
+
+def _cost_fraction(run: Run, config: _llm.OpenRouterConfig) -> float:
+    """How much of this run's allowance is gone, 0-1. Zero when uncapped."""
+    limit = float(getattr(config, "max_cost_usd", 0.0) or 0.0)
+    if limit <= 0:
+        return 0.0
+    return run.cost_usd / limit
+
+
+def _warn_on_spend(run: Run, config: _llm.OpenRouterConfig) -> None:
+    """One heads-up, in the user's terms, well before anything stops."""
+    if run.budget_warned or _cost_fraction(run, config) < COST_WARN_FRACTION:
+        return
+    run.budget_warned = True
+    limit = float(config.max_cost_usd)
+    _emit(run, "budget", {
+        "spent_usd": round(run.cost_usd, 4),
+        "limit_usd": round(limit, 4),
+        "fraction": round(_cost_fraction(run, config), 3),
+    })
+    _emit(run, "text", {"text": (
+        f"Heads up — I've used about {round(_cost_fraction(run, config) * 100)}% "
+        f"of this run's compute allowance (${limit:.2f} of model time per run; "
+        f"it's a cap on the run, not a limit on your account). I'll pause and "
+        f"check in with you before it runs out.")})
+
+
+def _budget_spent(run: Run, config: _llm.OpenRouterConfig) -> None:
+    """The allowance is gone. End the run cleanly and carry the work across."""
+    limit = float(config.max_cost_usd)
+    run.budget_spent = True
+    _hand_over(run, reason="budget_spent", why=(
+        f"That's this run's full compute allowance spent (${limit:.2f} of "
+        f"model time per run — it's a cap on the run, not a limit on your "
+        f"account, and nothing you did is lost)."))
+
+
+def handover_note(run: Run) -> str:
+    """A factual brief a fresh run can start from.
+
+    Built deterministically from what this run actually did — no model call,
+    nothing inferred. "Start a new one to continue" was advice the product
+    could not act on: a new run began cold, with no target, no plan and no
+    record of what had already happened, so the reviewer's work was simply
+    gone.
+    """
+    bits: List[str] = []
+    if run.goal:
+        bits.append(f"Original request: {run.goal}")
+    target = run.target or {}
+    if target:
+        ident = target.get("label") or target.get("gene_symbol") or ""
+        line = f"Target already resolved: {ident}"
+        if target.get("uniprot"):
+            line += f" (UniProt {target['uniprot']})"
+        if target.get("length"):
+            line += f" · {int(target['length']):,} nt"
+        bits.append(line)
+    done = [p["step"] for p in run.plan if p["status"] == "done"]
+    left = [p["step"] for p in run.plan if p["status"] in ("pending", "active")]
+    if done:
+        bits.append("Already finished: " + "; ".join(done[:8]))
+    if left:
+        bits.append("Still to do: " + "; ".join(left[:8]))
+    tools: List[str] = []
+    for ev in run.events:
+        if ev.get("kind") == "tool_result" and ev.get("ok"):
+            name = str(ev.get("name") or "")
+            if name and name not in tools:
+                tools.append(name)
+    if tools:
+        bits.append("Tools already run successfully: " + ", ".join(tools[:12]))
+    if not bits:
+        return ""
+    return (f"{_PIN_PREFIX} Carried over from the previous run, which reached "
+            f"its limit part-way through.\n" + "\n".join(bits)
+            + "\nPick up from here. Do not repeat finished work, and do not "
+              "ask the user for anything they have already given you.")
+
+
+# A handover waits here for the owner's next run. In-process and short-lived
+# on purpose: this is continuity across one interrupted piece of work, not a
+# memory feature. Keyed by owner, cleared the moment it is used.
+_HANDOVER_TTL_SECONDS = 30 * 60
+_HANDOVERS_MAX = 200
+_HANDOVERS: Dict[str, Dict[str, Any]] = {}
+
+
+def _record_handover(run: Run, note: str) -> None:
+    if run.anonymous or not run.owner or not note:
+        return
+    with _RUNS_LOCK:
+        cutoff = time.time() - _HANDOVER_TTL_SECONDS
+        for k in [k for k, v in _HANDOVERS.items() if v.get("at", 0) < cutoff]:
+            _HANDOVERS.pop(k, None)
+        if len(_HANDOVERS) >= _HANDOVERS_MAX and run.owner not in _HANDOVERS:
+            return
+        _HANDOVERS[run.owner] = {
+            "run_id": run.run_id,
+            "note": note,
+            "goal": run.goal,
+            "target": dict(run.target),
+            "plan": [dict(p) for p in run.plan],
+            "at": time.time(),
+        }
+
+
+def take_handover(owner: str, anonymous: bool = False) -> Optional[Dict[str, Any]]:
+    """The pending handover for this owner, consumed. None if there isn't one.
+
+    Consumed rather than read so it can only ever seed ONE run — a handover
+    that kept re-applying would silently drag an old goal into unrelated work,
+    which is the very failure the target binding above exists to stop.
+    """
+    if anonymous or not owner:
+        return None
+    with _RUNS_LOCK:
+        item = _HANDOVERS.pop(owner, None)
+    if not item or item.get("at", 0) < time.time() - _HANDOVER_TTL_SECONDS:
+        return None
+    return item
+
+
+def _hand_over(run: Run, reason: str, why: str) -> None:
+    """End a run that cannot continue, leaving the work recoverable.
+
+    Deliberately NOT an `error` event: a budget ceiling is an expected end to
+    a run, not a fault, and painting a red block over work that largely
+    succeeded is what made the reviewer ask whether something had broken.
+    """
+    note = handover_note(run)
+    left = [p["step"] for p in run.plan if p["status"] in ("pending", "active")]
+    _record_handover(run, note)
+    run.status = "done"
+    run.pending_tool_call_id = None
+    tail = ("" if not left else
+            "\n\nStill to do:\n" + "\n".join("• " + s for s in left[:6]))
+    _emit(run, "text", {"text": (
+        why + " Send your next message and I'll start a fresh run carrying "
+        "this one's target, plan and progress over." + tail)})
+    _emit(run, "checkpoint", {
+        "remaining": left,
+        "steps_used": run.steps,
+        "can_continue": False,
+        "reason": reason,
+        "carry_over": bool(note),
+    })
+    _emit(run, "done", {"reason": reason, "carry_over": bool(note)})
+
+
+def _auto_extend(run: Run, config: _llm.OpenRouterConfig) -> bool:
+    """Top the step budget up without stopping to ask. True if granted.
+
+    Only when there is genuinely nothing for the user to decide:
+      • extensions left in the automatic allowance, AND
+      • real work landed during the stretch just finished — update_plan and
+        ask_user change nothing in the world, so a stretch of only those is a
+        loop, and quietly funding it is the runaway the cap exists to stop;
+      • AND the money is not the binding constraint. Once spend is the reason
+        we would stop, the user is the one who should decide, not us.
+    """
+    if run.extensions >= min(AUTO_EXTENSIONS, MAX_EXTENSIONS):
+        return False
+    if run.tools_run <= run.tools_at_checkpoint:
+        return False
+    if _cost_fraction(run, config) >= COST_WARN_FRACTION:
+        return False
+    run.extensions += 1
+    run.tools_at_checkpoint = run.tools_run
+    # Recorded, not rendered. The transcript and the export show it; the rail
+    # does not, because "I gave myself twelve more steps" is not news to a
+    # user watching tool calls land.
+    _emit(run, "extended", {
+        "steps_used": run.steps,
+        "steps_limit": MAX_STEPS + run.extensions * STEP_EXTENSION,
+        "extensions": run.extensions,
+    })
+    return True
+
+
+def _checkpoint(run: Run, reason: str = "steps") -> None:
+    """Pause and hand the decision back — report where we got to.
 
     The old behaviour said "I've taken this as far as one run goes", marked the
     run done, and left the user to guess what had and hadn't happened. That is
     an abandonment dressed as a completion. A checkpoint states what remains,
     keeps the run resumable, and is honest about why it paused.
+
+    "Why" now has to be specific. "I've used this stretch of the run" describes
+    nothing a user can act on — it names no unit, no amount and no cause — and
+    the reviewer read the repeats of it as the agent stalling.
     """
     left = [p["step"] for p in run.plan if p["status"] in ("pending", "active")]
+    run.tools_at_checkpoint = run.tools_run
     if run.extensions >= MAX_EXTENSIONS:
-        run.status = "done"
-        _emit(run, "text", {"text": (
-            "I've hit this run's overall ceiling. Everything above is saved — "
-            "start a new run and I'll pick up from it.")})
-        _emit(run, "done", {"reason": "max_steps"})
+        _hand_over(run, reason="max_steps", why=(
+            f"I've reached this run's overall ceiling at {run.steps} steps."))
         return
 
+    if reason == "cost":
+        head = (f"I've used most of this run's compute allowance "
+                f"(${run.cost_usd:.2f} of model time so far — a cap on the "
+                f"run, not a limit on your account).")
+    else:
+        head = (f"I've run {run.steps} steps on this — that's where I check in "
+                f"rather than keep spending on my own read of the task.")
+
     if left:
-        body = ("I've used this stretch of the run. Still to do:\n"
+        body = (head + " Still to do:\n"
                 + "\n".join("• " + s for s in left[:6])
-                + "\n\nSay **continue** and I'll carry on, or redirect me.")
+                + f"\n\nSay **continue** for another {STEP_EXTENSION} steps, "
+                  f"or redirect me.")
     else:
-        body = ("I've used this stretch of the run without closing out the "
-                "task. Say **continue** and I'll carry on, or tell me what to "
-                "focus on.")
+        body = (head + " I haven't closed the task out. Say **continue** for "
+                f"another {STEP_EXTENSION} steps, or tell me what to focus on.")
     run.status = "awaiting_input"
     run.pending_tool_call_id = None
     _emit(run, "text", {"text": body})
@@ -867,6 +1250,7 @@ def _checkpoint(run: Run) -> None:
         "remaining": left,
         "steps_used": run.steps,
         "can_continue": True,
+        "reason": reason,
     })
 
 
@@ -885,6 +1269,7 @@ def _spawn(run: Run) -> None:
             "error_kind": "agent_unconfigured",
         })
         return
+    run.cost_limit_usd = float(config.max_cost_usd or 0.0)
     run.status = "running"
     run.stop_requested = False
     t = threading.Thread(target=_drive, args=(run, config), daemon=True)
@@ -956,9 +1341,72 @@ def set_workspace(run: Run, workspace: Optional[Dict[str, Any]]) -> None:
     run.workspace = clean
 
 
-def start(run: Run, message: str, workspace: Optional[Dict[str, Any]] = None) -> None:
-    """Begin (or continue) a run with a user message."""
+def _apply_handover(run: Run, item: Dict[str, Any], source_run_id: str,
+                    inherit: bool) -> None:
+    """Seed a fresh run from an interrupted one's brief.
+
+    ``inherit`` distinguishes the two ways this happens, and the distinction
+    matters more than it looks:
+
+      • asked for explicitly (carry_from) — the caller has said this new run
+        IS the old one continued, so it adopts the goal, the bound target and
+        the plan outright;
+      • picked up automatically after a budget stop — the brief goes into
+        history as CONTEXT the model can read and disregard, and nothing is
+        bound. A user whose next message is about something else entirely
+        must not find their new run silently asserting an old target. That
+        would be the cross-conversation bleed again, rebuilt from the other
+        side.
+    """
+    note = str(item.get("note") or "")
+    if not note:
+        return
+    if inherit:
+        if not run.goal and item.get("goal"):
+            run.goal = str(item["goal"])[:400]
+        if not run.target and isinstance(item.get("target"), dict):
+            run.target = dict(item["target"])
+        if not run.plan and isinstance(item.get("plan"), list):
+            run.plan = [dict(p) for p in item["plan"] if isinstance(p, dict)]
+    run.carried_from = source_run_id
+    run.history.append({"role": "user", "content": note})
+    # Said out loud. Silently inheriting a previous run's goal is the same
+    # class of failure as the cross-conversation bleed — context the user
+    # cannot see and cannot correct.
+    _emit(run, "text", {"text": (
+        "Picking up from your last run — same target and plan, fresh budget.")})
+    if run.plan:
+        _emit(run, "plan", {"steps": list(run.plan)})
+
+
+def start(run: Run, message: str, workspace: Optional[Dict[str, Any]] = None,
+          carry_from: Optional[Run] = None) -> None:
+    """Begin (or continue) a run with a user message.
+
+    ``carry_from`` seeds this run from one that ran out of budget mid-task, so
+    "start a new one to continue" stops being advice the product can't act on.
+    Ownership is enforced here rather than by the caller: the brief lands in
+    the model's context verbatim, and one run reading another owner's goal
+    would be a cross-account leak, not merely a bug.
+    """
     set_workspace(run, workspace)
+    if carry_from is not None:
+        if not run.owner or carry_from.owner != run.owner or carry_from.anonymous:
+            raise ValueError("carry_from must be a run the same owner started")
+        _apply_handover(run, {
+            "note": handover_note(carry_from),
+            "goal": carry_from.goal,
+            "target": dict(carry_from.target),
+            "plan": [dict(p) for p in carry_from.plan],
+        }, carry_from.run_id, inherit=True)
+    elif not run.history:
+        # Nothing explicit — but if this owner's last run ended on a limit
+        # with work outstanding, this IS the "start a new one" they were told
+        # to do. Consumed, so it can seed exactly one run.
+        pending = take_handover(run.owner, run.anonymous)
+        if pending:
+            _apply_handover(run, pending, str(pending.get("run_id") or ""),
+                            inherit=False)
     # The opening ask names the run in the history list. Set once, so a long
     # conversation keeps the title it started with rather than renaming
     # itself to whatever was asked last.
@@ -1479,19 +1927,76 @@ def continuity_note(user_id: str) -> str:
         lines.append(bit)
 
     return (
-        "\n\nWHAT THEY WERE ALREADY WORKING ON\n"
-        "This user has saved work. Do NOT re-introduce yourself or propose "
-        "starting from scratch on something they already have:\n"
+        # The heading used to read "WHAT THEY WERE ALREADY WORKING ON", which
+        # is ambiguous in the one way that matters: it does not say these came
+        # from OTHER conversations. Combined with "do NOT propose starting
+        # from scratch", it read as a standing instruction to work on them —
+        # and on 2026-07-30 a run about beta-lactamase TEM-1 started planning
+        # against IsPETase, a library from a different run. Naming the scope
+        # is half the fix; _target_note is the other half.
+        "\n\nWORK FROM OTHER CONVERSATIONS (background — NOT this run's "
+        "subject)\n"
+        "This user has saved work from earlier, separate conversations. It is "
+        "here so you don't re-introduce yourself or propose building something "
+        "they already have — it is NOT what this conversation is about:\n"
         + "\n".join(lines)
         + "\nUse list_my_work for ids and detail. If a library has results "
         "logged, propose_round2 is the natural next step; if it has none and "
-        "they mention bench numbers, log_outcome is.\n"
+        "they mention bench numbers, log_outcome is. Never treat one of these "
+        "as the target of the current run unless the user names it here.\n"
     )
 
 
+def _target_note(target: Dict[str, Any]) -> str:
+    """State, every step, what this conversation is about.
+
+    Placed LAST in the prompt on purpose: it is the most proximate standing
+    instruction, and it has to outrank the saved-work list above it. Only
+    values a tool actually returned appear here.
+    """
+    if not target:
+        return ""
+    label = (target.get("label") or target.get("gene_symbol")
+             or "the target resolved in this conversation")
+    lines = [f"\n\nTHE TARGET OF THIS RUN — BOUND TO THIS CONVERSATION\n"
+             f"Everything in this run is about: {label}"]
+    if target.get("gene_symbol"):
+        lines.append(f"  · gene / name: {target['gene_symbol']}")
+    if target.get("organism"):
+        lines.append(f"  · organism: {target['organism']}")
+    if target.get("uniprot"):
+        lines.append(f"  · UniProt: {target['uniprot']}")
+    if target.get("sequence"):
+        n = int(target.get("length") or len(str(target["sequence"])))
+        lines.append(
+            f"  · sequence: {n:,} nt, ALREADY RESOLVED in this conversation "
+            f"(source: {target.get('source') or 'fetch_sequence'})")
+        lines.append(
+            "You already hold that sequence — feed it straight from the "
+            "fetch_sequence result into the next tool. DO NOT ASK THE USER to "
+            "paste or re-send it. They gave it to you; asking again is the "
+            "single thing that most makes this feel broken. If the transcript "
+            "has been condensed and you genuinely no longer have the letters, "
+            "call fetch_sequence yourself rather than asking them.")
+    else:
+        lines.append(
+            "No sequence has been resolved for it yet — call fetch_sequence "
+            "before any tool that needs one.")
+    lines.append(
+        "Anything listed under WORK FROM OTHER CONVERSATIONS belongs to a "
+        "different conversation. It is not this one. Never plan, fold, score "
+        "or design against it, and never talk about it as if it were what you "
+        "are working on now. If you believe the user has changed target, say "
+        "so and resolve the new one with fetch_sequence — never switch "
+        "silently.")
+    return "\n".join(lines)
+
+
 def build_system_prompt(anonymous: bool, workspace: Optional[Dict[str, Any]] = None,
-                        continuity: str = "") -> str:
+                        continuity: str = "",
+                        target: Optional[Dict[str, Any]] = None) -> str:
     return (SYSTEM_PROMPT
             + (_ANON_NOTE if anonymous else "")
             + (continuity or "")
-            + _workspace_note(workspace or {}))
+            + _workspace_note(workspace or {})
+            + _target_note(target or {}))

dee/core/resolve.py

@@ -122,6 +122,69 @@ def _fetch_refseq(accession: str) -> str:
     return _exon._fasta_to_seq(fasta) if fasta else ""
 
 
+# AlphaFold DB's own prediction index. Asking it whether a model exists is
+# the only honest way to answer that question — the file URL below is
+# CONSTRUCTED, and a constructed URL is a claim, not a fact.
+#
+# Two things verified live on 2026-08-01:
+#   • the DB now serves model_v6 only. AF-P62593-F1-model_v4.pdb is a 404 and
+#     ...model_v6.pdb is a 200, so a stale version number in a hand-built URL
+#     reads as "no structure" for a protein that has one. Do not conclude
+#     "not found" from an old version number.
+#   • a well-formed accession with no entry (A0A0A0AAAA) answers 400, not 200
+#     with an empty list — so "no model" and "the service is down" have to be
+#     told apart at the transport, exactly as UniProtUnavailable is.
+ALPHAFOLD_API = "https://alphafold.ebi.ac.uk/api/prediction/"
+
+
+def alphafold_model(accession: str):
+    """Does AlphaFold DB actually hold a model for this accession?
+
+    Returns ("ok", {...}) | ("absent", None) | ("unavailable", None).
+
+    "unavailable" is NOT "absent" (docs/ENGINEERING.md §9): telling a
+    scientist their protein has no predicted structure because an EBI endpoint
+    blinked is a false negative that makes a working viewer look empty.
+    """
+    import json as _json
+    from dee.core import uniprot as _up
+
+    acc = re.sub(r"[^A-Za-z0-9]", "", str(accession or ""))[:16]
+    if not acc:
+        return ("absent", None)
+    try:
+        raw = _up._get(ALPHAFOLD_API + acc)
+    except _up.UniProtUnavailable:
+        return ("unavailable", None)
+    if not raw:
+        return ("absent", None)          # 400/404 — a real "nothing there"
+    try:
+        payload = _json.loads(raw.decode("utf-8"))
+    except (ValueError, AttributeError):
+        return ("unavailable", None)     # a 200 that isn't JSON is a bad day
+    entries = payload if isinstance(payload, list) else [payload]
+    entry = next((e for e in entries if isinstance(e, dict)), None)
+    if not entry:
+        return ("absent", None)
+    # Take the URLs the API itself reports rather than rebuilding them, so a
+    # future version bump (v6 → v7) cannot silently start 404ing.
+    pdb_url = str(entry.get("pdbUrl") or "")
+    if not pdb_url and not entry.get("cifUrl"):
+        # A 200 carrying no model file is not a confirmation. Treat it as "we
+        # could not check" rather than as either a yes or a no — claiming
+        # "verified" off a response that names no file is exactly the kind of
+        # confident-and-wrong this guard exists to stop.
+        return ("unavailable", None)
+    return ("ok", {
+        "pdb_url": pdb_url,
+        "cif_url": str(entry.get("cifUrl") or ""),
+        # AlphaFold's own mean pLDDT for this model. Reported, never derived —
+        # this number reaches a scientist deciding whether to trust a fold.
+        "plddt": entry.get("globalMetricValue"),
+        "version": entry.get("latestVersion"),
+    })
+
+
 def resolve_uniprot(organism: str, gene_symbol: str) -> Dict:
     """Resolve a gene symbol (+ organism) to a UniProt accession and the
     AlphaFold-DB structure URLs, for the structure viewer (Phase 3, M5).
@@ -129,6 +192,25 @@ def resolve_uniprot(organism: str, gene_symbol: str) -> Dict:
     Returns {ok, uniprot, alphafold_url, alphafold_page, error?}. Only the
     (organism, gene_symbol) leaves the Space. Works for any organism —
     AlphaFold DB covers all of UniProt.
+
+    THE TEM-1 INCIDENT (reviewer log, 2026-07-30). A reviewer pasted
+    beta-lactamase TEM-1 and the bench showed I6ZGA9 as the model's accession.
+    Verified against the live APIs on 2026-08-01:
+
+      • I6ZGA9 exists — UniProtKB unreviewed (TrEMBL), I6ZGA9_ECOLX, E. coli,
+        "Beta-lactamase", flagged **Fragment**, 264 aa, and AlphaFold really
+        does hold AF-I6ZGA9-F1 at 95.25 pLDDT. So the 3-D view was showing a
+        genuine structure, and "I6ZGA9 is not a recognised UniProt
+        identifier" is not correct.
+      • But it was the WRONG entry. The reviewer's sequence is 286 aa and is
+        P62593 (BLAT_ECOLX, Swiss-Prot, "Beta-lactamase TEM", alt name
+        TEM-1). I6ZGA9's sequence begins 11 residues in — it is a partial
+        entry — so every residue number in that viewer was offset by 11, in a
+        product whose entire job is telling someone which residue to mutate.
+
+    Two fixes: uniprot.find_gene now searches the protein-name field too and
+    prefers a reviewed entry on either field (which lands TEM-1 on P62593),
+    and this function no longer asserts a structure it has not confirmed.
     """
     if not gene_symbol:
         return {"ok": False, "error": "No gene symbol to look up."}
@@ -155,17 +237,62 @@ def resolve_uniprot(organism: str, gene_symbol: str) -> Dict:
                           f"{_up.normalize_organism(organism) or 'that organism'}. "
                           f"Check the gene name, or give the organism explicitly.")}
     acc = hit.accession
-    return {
+    out = {
         "matched_organism": hit.organism,
         "reviewed": hit.reviewed,
         "ok": True,
         "uniprot": acc,
+        "entry_name": hit.entry_name,
+        "protein_name": hit.protein_name,
+        "protein_length": len(hit.protein),
+        "fragment": hit.fragment,
+        "matched_by": hit.matched_by,
         # Fallback URL only — the client re-resolves the current model version
         # via the AlphaFold prediction API (the DB bumps versions: v4→v6→…).
         "alphafold_url":  f"https://alphafold.ebi.ac.uk/files/AF-{acc}-F1-model_v6.pdb",
         "alphafold_page": f"https://alphafold.ebi.ac.uk/entry/{acc}",
+        "structure_verified": False,
     }
 
+    # Caveats the caller must be able to pass on. A partial entry's residue
+    # numbering does not line up with the user's sequence, and that is the
+    # difference between "mutate residue 104" and mutating the wrong residue.
+    caveats = []
+    if hit.fragment:
+        caveats.append(
+            f"{acc} is a PARTIAL (fragment) UniProt entry of "
+            f"{len(hit.protein)} aa — residue numbering in this model will "
+            f"not line up with a full-length sequence.")
+    if not hit.reviewed:
+        caveats.append(
+            f"{acc} is an unreviewed (TrEMBL) entry — computationally "
+            f"annotated, not curated.")
+    if caveats:
+        out["caveats"] = caveats
+
+    # A CONSTRUCTED file URL is a claim, not a fact. Confirm the model exists
+    # before anyone paints it as this protein's structure.
+    status, model = alphafold_model(acc)
+    if status == "absent":
+        return {"ok": False, "kind": "no_structure", "uniprot": acc,
+                "error": (f"Matched {gene_symbol} to UniProt {acc} "
+                          f"({hit.entry_name or 'no entry name'}), but "
+                          f"AlphaFold DB has no predicted model for it, so "
+                          f"there is no structure to show.")}
+    if status == "ok" and model:
+        if model.get("pdb_url"):
+            out["alphafold_url"] = model["pdb_url"]
+        out["structure_verified"] = True
+        # AlphaFold's own numbers, reported verbatim.
+        if model.get("plddt") is not None:
+            out["plddt"] = model["plddt"]
+        if model.get("version") is not None:
+            out["model_version"] = model["version"]
+    # status == "unavailable": EBI didn't answer. Keep the constructed URL and
+    # leave structure_verified False rather than declaring a real protein
+    # unmodelled because an endpoint blinked (§9, transient ≠ absent).
+    return out
+
 
 def _resolve_via_uniprot(symbol: str, organism: str) -> Dict:
     """Gene symbol → CDS for organisms Ensembl's main REST API doesn't serve.

dee/core/uniprot.py

@@ -109,6 +109,15 @@ class GeneHit:
     protein: str            # amino-acid sequence
     reviewed: bool          # SwissProt (True) vs TrEMBL (False)
     embl_cds: tuple         # EMBL protein_ids that carry the CDS
+    # UniProt's own "Fragment" / "Fragments" flag. A fragment entry is a
+    # PARTIAL protein, so its residue numbering is offset from the full
+    # sequence — which makes "the clash is at position 104" point at the wrong
+    # residue. Carried out so callers can say so instead of passing a partial
+    # entry off as the whole protein. See the TEM-1 incident in resolve.py.
+    fragment: bool = False
+    # Which query found it: "gene" or "protein_name". Diagnostic, and the
+    # thing that made the TEM-1 mis-resolution legible.
+    matched_by: str = "gene"
 
 
 # Organism names are letters, spaces, dots, hyphens and the odd apostrophe
@@ -121,6 +130,11 @@ _ORG_SAFE = re.compile(r"[^A-Za-z0-9 .'\-]")
 _ORG_MAX = 64
 # Same reasoning for the gene symbol, which is interpolated as gene:{…}.
 _GENE_SAFE = re.compile(r"[^A-Za-z0-9._\-]")
+# And for the protein-name term, interpolated as protein_name:"…". The double
+# quote is the character that matters: leaving one in would close the quoted
+# term early and change what the query means.
+_NAME_SAFE = re.compile(r"[^A-Za-z0-9 ._\-]")
+_NAME_MAX = 48
 
 
 def normalize_organism(organism: str) -> str:
@@ -167,22 +181,60 @@ def _search(query: str) -> Optional[dict]:
 
 
 def find_gene(gene_symbol: str, organism: str) -> Optional[GeneHit]:
-    """Resolve (gene, organism) to a UniProt entry. None if genuinely absent.
+    """Resolve (gene or protein name, organism) to a UniProt entry.
 
-    Prefers a REVIEWED (SwissProt) entry and only falls back to unreviewed if
-    there is no reviewed one — with `reviewed=False` on the result so callers
-    can say so rather than passing off a computationally-annotated entry as
-    curated.
+    None only if genuinely absent. REVIEWED (SwissProt) beats unreviewed, and
+    unreviewed comes back with `reviewed=False` so callers can say so rather
+    than passing a computationally-annotated entry off as curated.
+
+    WHY THE PROTEIN-NAME QUERY EXISTS (incident, reviewer log 2026-07-30).
+    Scientists name proteins, not gene loci. Asked for beta-lactamase
+    "TEM-1" in E. coli this searched `gene:TEM-1` only, and:
+
+        gene:TEM-1 … reviewed:true        → nothing
+        gene:TEM-1                        → I6ZGA9, TrEMBL, 264 aa, FRAGMENT
+
+    ...so the structure viewer was handed I6ZGA9 — verified live: a real
+    accession (the reviewer's "not a recognised UniProt identifier" is wrong),
+    with a real AlphaFold model at 95.25 pLDDT, but a PARTIAL entry whose
+    sequence starts 11 residues into the protein the user had pasted. Every
+    residue number in the 3-D view was therefore off by 11.
+
+    The canonical entry was there the whole time. TEM-1 is not a gene name on
+    it — the gene is `bla`; "TEM-1" is a protein ALTERNATIVE name:
+
+        protein_name:TEM-1 … reviewed:true → P62593 BLAT_ECOLX, Swiss-Prot,
+                                             286 aa, "Beta-lactamase TEM"
+
+    286 aa is exactly what the reviewer pasted. So: try both fields, and take
+    a REVIEWED match on either before an unreviewed match on the first. This
+    adds no allow-list — it removes a way of missing entries that were always
+    there.
     """
     gene = _GENE_SAFE.sub("", str(gene_symbol or "").strip())[:32]
+    name = _NAME_SAFE.sub(" ", str(gene_symbol or "").strip())[:_NAME_MAX].strip()
     org = normalize_organism(organism)
     if not gene or not org:
         return None
 
+    # Reviewed-first ACROSS both fields. Getting this order wrong is the whole
+    # bug: an unreviewed gene-name match used to beat a curated protein-name
+    # match that named the same protein.
+    strategies = [
+        ("gene", f'gene:{gene} AND organism_name:"{org}" AND reviewed:true'),
+        ("protein_name", f'protein_name:"{name}" AND organism_name:"{org}" '
+                         f'AND reviewed:true') if name else None,
+        ("gene", f'gene:{gene} AND organism_name:"{org}"'),
+        ("protein_name", f'protein_name:"{name}" AND organism_name:"{org}"')
+        if name else None,
+    ]
+
     hit = None
-    for reviewed in (True, False):
-        q = (f'gene:{gene} AND organism_name:"{org}"'
-             + (" AND reviewed:true" if reviewed else ""))
+    matched_by = "gene"
+    for entry in strategies:
+        if entry is None:
+            continue
+        matched_by, q = entry
         hit = _search(q)
         if hit:
             break
@@ -199,10 +251,17 @@ def find_gene(gene_symbol: str, organism: str) -> Optional[GeneHit]:
                 embl.append(prop["value"])
 
     protein_name = ""
+    fragment = False
     try:
-        protein_name = (((hit.get("proteinDescription") or {})
-                         .get("recommendedName") or {})
+        description = hit.get("proteinDescription") or {}
+        protein_name = ((description.get("recommendedName") or {})
                         .get("fullName") or {}).get("value") or ""
+        # "Fragment" / "Fragments". UniProt also uses this slot for
+        # "Precursor", which is NOT a fragment — a precursor is the complete
+        # translated chain including its signal peptide, and P62593 (the
+        # correct TEM-1) is flagged exactly that. Matching on the prefix
+        # rather than "is the flag set" is the difference.
+        fragment = str(description.get("flag") or "").lower().startswith("fragment")
     except (AttributeError, TypeError):
         pass
 
@@ -214,6 +273,8 @@ def find_gene(gene_symbol: str, organism: str) -> Optional[GeneHit]:
         protein=seq,
         reviewed=bool(hit.get("entryType", "").startswith("UniProtKB reviewed")),
         embl_cds=tuple(embl[:4]),
+        fragment=fragment,
+        matched_by=matched_by,
     )
 
 

dee/optimizer/search.py

@@ -78,6 +78,28 @@ class SearchConfig:
     duplicate_position_penalty: float = 1e3  # Per repeated residue position.
     seed: Optional[int] = None
 
+    # ─── Cross-variant library diversity ────────────────────────────
+    # duplicate_position_penalty is a WITHIN-variant rule: it stops one
+    # variant mutating the same residue twice. It says nothing about the
+    # returned K as a set — and because fitness is an ADDITIVE sum of ΔLL,
+    # the top-K of that sum are near-copies of each other: whatever the
+    # best few single mutations are, they are in almost every variant.
+    #
+    # Measured on TEM-1 beta-lactamase (BLAT_ECOLX, the DMS fixture in
+    # dee/data/dms_fixtures, ESM-2 35M, top-15% pool, k=10, 8 restarts x
+    # 1200 steps, seed 7): H87L, H1M and M157T each occupied 10 of the 10
+    # returned variants, and the whole library spanned 8 distinct
+    # substitutions. That is the library a reviewer got — one substitution
+    # in nine of ten rows — and it is bad experimental design, not just
+    # dull: if every clone carries H87L you cannot attribute any measured
+    # effect to it, and the round-2 surrogate learns nothing about it
+    # either, because there is no contrast to learn from.
+    #
+    # So cap occupancy when the hall of fame is assembled into the
+    # returned library. Set either to >= 1.0 to switch that cap off.
+    max_substitution_share: float = 0.5  # one (position, aa) in at most half the library
+    max_position_share: float = 0.7      # one residue position in at most this share
+
 
 @dataclass
 class Variant:
@@ -206,6 +228,54 @@ def _simulated_anneal(
         temperature *= cooling
 
 
+def _select_diverse(ranked: List[Variant], cfg: SearchConfig) -> List[Variant]:
+    """Assemble the returned library from the fitness-ordered hall of fame,
+    under per-substitution and per-residue occupancy quotas.
+
+    Greedy in fitness order, so the single best variant is always kept — the
+    cap changes which *near-duplicates* of it come along, not what wins. A
+    variant that would push any of its substitutions over quota is deferred,
+    not discarded: if the quotas can't fill K (a small hall of fame, or a
+    pool spanning few positions), the shortfall is backfilled from the
+    deferred list in fitness order, so this can never return fewer variants
+    than the plain top-K did.
+    """
+    k = cfg.k
+    if k <= 0 or not ranked:
+        return []
+    # ceil, and never below 1 — a quota of 0 would reject everything,
+    # including the best variant.
+    sub_quota = max(1, int(math.ceil(cfg.max_substitution_share * k)))
+    pos_quota = max(1, int(math.ceil(cfg.max_position_share * k)))
+
+    chosen: List[Variant] = []
+    deferred: List[Variant] = []
+    sub_used: Dict[Tuple[int, str], int] = {}
+    pos_used: Dict[int, int] = {}
+
+    for v in ranked:
+        if len(chosen) >= k:
+            break
+        fits = all(
+            sub_used.get((m.position, m.mut_aa), 0) < sub_quota
+            and pos_used.get(m.position, 0) < pos_quota
+            for m in v.mutations
+        )
+        if fits:
+            chosen.append(v)
+            for m in v.mutations:
+                sub_used[(m.position, m.mut_aa)] = sub_used.get((m.position, m.mut_aa), 0) + 1
+                pos_used[m.position] = pos_used.get(m.position, 0) + 1
+        else:
+            deferred.append(v)
+
+    if len(chosen) < k:
+        chosen.extend(deferred[: k - len(chosen)])
+    # Rank is still fitness order — the cap decides membership, not order.
+    chosen.sort(key=lambda v: v.fitness, reverse=True)
+    return chosen
+
+
 def evolve(pool_df: pd.DataFrame, cfg: Optional[SearchConfig] = None) -> List[Variant]:
     """Run the SA search and return the top-K unique multi-mutants.
 
@@ -242,14 +312,22 @@ def evolve(pool_df: pd.DataFrame, cfg: Optional[SearchConfig] = None) -> List[Va
             len(hall_of_fame),
         )
 
-    ranked = sorted(hall_of_fame.values(), key=lambda v: v.fitness, reverse=True)[: cfg.k]
+    # Sort the WHOLE hall of fame, then choose K from it. Truncating to K
+    # first would leave _select_diverse nothing to swap in — the near-copies
+    # of the best variant are exactly what fills the first K slots.
+    by_fitness = sorted(hall_of_fame.values(), key=lambda v: v.fitness, reverse=True)
+    ranked = _select_diverse(by_fitness, cfg)
     for i, v in enumerate(ranked):
         v.rank = i + 1
 
     logger.info(
-        "Search done. Returning top %d / %d unique variants. Best fitness=%.3f.",
+        "Search done. Returning %d / %d unique variants (diversity caps: "
+        "substitution <= %.0f%%, position <= %.0f%% of the library). "
+        "Best fitness=%.3f.",
         len(ranked),
         len(hall_of_fame),
+        cfg.max_substitution_share * 100,
+        cfg.max_position_share * 100,
         ranked[0].fitness if ranked else float("nan"),
     )
     return ranked

dee/server.py

@@ -1311,7 +1311,20 @@ def create_app() -> Flask:
             }), 400
         auth = _auth.get_auth()
         run = _orch.create_run(owner=(auth.user_id or ""), anonymous=auth.anonymous)
-        _orch.start(run, message, body.get("workspace"))
+        # Continuing a run that ran out of budget mid-task. The old ceiling
+        # said "start a new one to continue" and the new one started cold —
+        # no target, no plan, no record of what had already happened — so the
+        # advice was unfollowable and the work was simply lost. Passing the
+        # source run's ID (never a client-supplied brief: that text lands in
+        # the model's context) rebuilds the handover server-side, and
+        # _orch.start enforces that the caller owns it.
+        carry_id = str(body.get("carry_from") or "").strip()
+        source = _orch.get_run(carry_id) if carry_id else None
+        try:
+            _orch.start(run, message, body.get("workspace"), carry_from=source)
+        except ValueError:
+            return jsonify({"error": "That run isn't yours to continue.",
+                            "kind": "carry_forbidden"}), 403
         resp = jsonify(_orch.public_state(run))
         return _auth.increment_anon_runs_on_response(resp)
 
@@ -1378,6 +1391,21 @@ def create_app() -> Flask:
         # sit in a client-side queue until the run finished, by which point
         # the wrong work was already done and paid for. steer() hands it to
         # the run loop, which picks it up at its next step boundary.
+        # A run whose compute allowance is gone cannot answer this. Spawning
+        # it again would spend one more model call to rediscover that and show
+        # the user a second dead end. 410 is the shape the cockpit already
+        # recovers from (it clears the run and re-sends as a fresh start), and
+        # the server-side handover is what makes that fresh start land on the
+        # work instead of a blank page. `carry_from` is returned so a client
+        # that wants to be explicit about it can be.
+        if run.budget_spent:
+            return jsonify({
+                "error": ("That run used its full compute allowance. Your next "
+                          "message starts a fresh run carrying its target, "
+                          "plan and progress over."),
+                "kind": "run_budget_spent",
+                "carry_from": run.run_id,
+            }), 410
         if run.status == "running":
             if _orch.steer(run, message):
                 _orch.set_workspace(run, body.get("workspace"))

dee/static/app.css

@@ -1941,22 +1941,49 @@ input:focus, textarea:focus, select:focus {
     margin-bottom: 2px;
 }
 .mutmap-head .muted { margin: 0; font-size: 11px; }
-.mutmap-legend {
+/* ── the colour key ──────────────────────────────────────────────────────
+   Replaces the three .lg-dot chips (Low / Med / High) that used to sit in the
+   head. Those were removed as scaffolding and nothing took over, so a signed
+   continuous quantity shipped with no key at all for a month.
+
+   The gradient itself is an inline style written by renderMutationKey() from
+   mutmapColor(), the same function that fills the dots — so there is exactly
+   one definition of the scale and the key cannot drift from the chart. Only
+   the geometry and the type live here. */
+.mutmap-key {
+    margin-top: 12px;
+    padding-top: 11px;
+    border-top: 1px solid var(--line);
+}
+.mutmap-key:empty { display: none; }     /* no run, no rule floating on its own */
+.mutmap-key-scale { max-width: 380px; }
+.mutmap-key-bar {
+    display: block;
+    height: 9px;
+    border-radius: 2px;
+    /* The ramp is near-iso-luminant so it reads on both canvases; a hairline
+       keeps its ENDS from bleeding into a mid-tone background. */
+    border: 1px solid var(--line-strong);
+}
+.mutmap-key-ticks {
     display: flex;
-    align-items: center;
-    gap: 8px;
-    font-size: 11px;
+    justify-content: space-between;
+    margin-top: 3px;
+    font-family: var(--font-mono);
+    font-size: 9.5px;
+    letter-spacing: 0.04em;
     color: var(--ink-faint);
+    font-variant-numeric: tabular-nums;
 }
-.lg-dot {
-    width: 8px;
-    height: 8px;
-    border-radius: 50%;
-    display: inline-block;
+.mutmap-key-note {
+    margin: 8px 0 0;
+    max-width: 68ch;
+    font-size: 11px;
+    line-height: 1.5;
+    color: var(--ink-faint);
 }
-.lg-mild   { background: var(--brand-200); }
-.lg-mid    { background: var(--brand); }
-.lg-strong { background: var(--brand-deep); }
+.mutmap-key-note strong { color: var(--ink-soft); font-weight: 600; }
+.mutmap-key-note em { font-style: italic; }
 
 .mutmap-canvas {
     background: var(--gray-0);
@@ -7794,6 +7821,27 @@ body[data-cockpit="open"]:not([data-bench="open"]) .cockpit { top: 0; }
     display: flex; flex-direction: column; gap: 14px;
     -webkit-overflow-scrolling: touch;   /* iOS momentum (standing constraint) */
 }
+/* THE GLITCHED BOXES.
+
+   The transcript is a column flex container, so every turn in it is a flex
+   ITEM and inherits flex-shrink:1. Once a run is long enough to overflow the
+   rail, the free space goes negative and the browser shrinks the items before
+   it ever considers scrolling.
+
+   Most turns survive that: min-height:auto gives a flex item a content-based
+   minimum — but ONLY while its overflow is `visible`. `.cp-tool` sets
+   `overflow: hidden` (it has to; the rounded corners clip the result table),
+   which drops its automatic minimum to zero. So the tool rows, and only the
+   tool rows, get squeezed — measured at 9.6px tall against a 34.6px header,
+   i.e. collapsed to roughly their own border with the content clipped away.
+   That is the "glitched box" in the review screenshots, and it is also why
+   the transcript's scrollHeight equalled its clientHeight: nothing was
+   scrolling, everything was being crushed to fit.
+
+   Pinning every child to its natural size restores scrolling and the boxes.
+   Do not "simplify" this to a rule on .cp-tool alone — the next component
+   that clips its own overflow would silently inherit the same bug. */
+.cp-transcript > * { flex: 0 0 auto; }
 /* min-width:0 + break-word on every turn, not just the sequence card.
 
    The rail is ~390px and the agent is instructed to put sequences on their
@@ -8482,6 +8530,28 @@ body[data-cockpit="min"] .cp-head { cursor: pointer; }
    straight through as a course correction — but it stays tagged, so reading a
    run back later answers "why did it switch to mouse at this point?". */
 .cp-user { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; }
+/* THE CUT-OFF TEXT.
+
+   Making the user's turn a flex row (for the STEER tag) turned its text into
+   a flex item, and a flex item's default `min-width: auto` refuses to shrink
+   below its MIN-CONTENT width. `overflow-wrap: break-word` on .cp-turn does
+   not help here: break-word permits a break at render time but deliberately
+   does not reduce the intrinsic min-content size, so the box still asks for
+   the width of the longest unbroken token.
+
+   Paste the 286-residue TEM-1 protein from the review and that token is the
+   whole sequence: measured at 2,389px of text inside a 391px rail — 2,024px
+   running off the right edge, unwrapped and unreachable.
+
+   `overflow-wrap: anywhere` is the one that DOES shrink min-content, and
+   min-width:0 removes the floor as well. Ordinary prose is unaffected: like
+   break-word, `anywhere` only breaks a word that would otherwise overflow.
+
+   Note this is the fallback, not the good outcome. A bare sequence still
+   reads better as a .cp-seq card (mono, FASTA-wrapped, copyable). md() routes
+   nucleotide lines there already; its bare-sequence test is `/^[ACGTUN]+$/i`,
+   so protein never matches. Widening that test is the real fix. */
+.cp-user > div { min-width: 0; overflow-wrap: anywhere; }
 .cp-q-tag {
     font-family: var(--font-mono); font-size: 9.5px; letter-spacing: 0.08em;
     text-transform: uppercase; color: var(--ink-faint); flex: 0 0 auto;
@@ -8609,3 +8679,46 @@ body[data-cockpit="min"] .cp-head { cursor: pointer; }
    them fail; the banner says to run the full tool for both. */
 body.de-agent-run #downloadMenu,
 body.de-agent-run .dna-edit-actions { display: none; }
+
+/* ══════════════════════════════════════════════ hidden must mean hidden ══
+   Eight elements in this app carried the `hidden` attribute and rendered
+   anyway. One cause, and it looks like correct CSS in every diff:
+
+     the UA sheet's `[hidden] { display: none }` is an AUTHOR-vs-UA contest,
+     not a specificity contest. Any author `display:` on the element wins,
+     however low its specificity.
+
+   So `.run-meta { display: flex }` quietly cancelled `<div class="run-meta"
+   hidden>`, and a scientist looking at a library painted from a chat saw an
+   empty bordered box under "How to read this" — 888x30, one pixel of border,
+   nothing in it. That is the empty box in the review screenshots.
+
+   Measured on a fresh load, the same fault was rendering a 92px CRISPR
+   base-editor row, a 136px primer organism block, a stray filter-clear glyph,
+   two clone panes, and — worst — the entire 946x401 primer results card,
+   headings and all, above a form nobody had submitted yet.
+
+   `.x[hidden]` is (0,2,0) and beats a bare `.x`, so these can live together
+   in one block. Every element listed is toggled through the `hidden`
+   PROPERTY in app.js (`el.hidden = false`), which removes the attribute, so
+   nothing here can strand a panel that is supposed to appear.
+
+   `.sidebar-scrim` is the deliberate exception and keeps its own rule above:
+   it stays boxed while it fades out.
+
+   tests/test_hidden_attribute.py locks this down — it re-derives the list
+   from the markup and fails on the next class that acquires a `display:`
+   without a guard. */
+.run-meta[hidden],
+.filter-clear[hidden],
+.crispr-context-row[hidden],
+.crispr-vector-row[hidden],
+.crispr-vendor-row[hidden],
+.crispr-vendor-strip[hidden],
+.primer-organism-row[hidden],
+.primer-results-card[hidden],
+.primer-scan-status[hidden],
+.plasmid-seq-tools[hidden],
+.clone-pane[hidden],
+.clone-gg-enz[hidden],
+.ghost[hidden] { display: none; }

dee/static/app.js

@@ -1110,7 +1110,11 @@ function teardownSkeleton() {
                 <tr>
                     <th class="sortable" data-sort="rank" title="Rank by predicted fitness (1 = best).">Rank <span class="sort-ind">↕</span></th>
                     <th class="sortable" data-sort="mutations" title="Substitutions vs. the wild-type protein, in the format WT_aa-position-new_aa.">Mutations <span class="sort-ind">↕</span></th>
-                    <th class="num sortable" data-sort="fitness" title="Cumulative ΣΔLL from ESM-2: sum of log-likelihood improvements over WT across all substitutions in this variant.">Fitness <span class="sort-ind">↕</span></th>
+                    <!-- Unit in the header, not only in the title. This shell is
+                         rebuilt from JS after the skeleton, so it has to carry the
+                         same markup as index.html's copy or the unit would vanish
+                         on every real run and survive only in the empty state. -->
+                    <th class="num sortable" data-sort="fitness" title="Cumulative ΣΔLL from ESM-2: sum of log-likelihood improvements over WT across all substitutions in this variant.">Fitness <span class="th-unit">ΣΔLL</span> <span class="sort-ind">↕</span></th>
                     <th class="num sortable" data-sort="gc" title="GC content of the codon-optimized DNA, %.">GC% <span class="sort-ind">↕</span></th>
                     <th class="num sortable" data-sort="tm" title="Lower of the two primer Tm values (°C).">Tm (°C) <span class="sort-ind">↕</span></th>
                     <th class="num sortable" data-sort="length" title="Length of the codon-optimized DNA, bp.">bp <span class="sort-ind">↕</span></th>
@@ -1368,7 +1372,7 @@ function _renderLearnedPanel(surrogate) {
         return `<div class="learned-row" style="--i:${i}">
             <span class="learned-arrow learned-${cls}">${arrow}</span>
             <span class="learned-label">${escapeHtml(d.label)}</span>
-            <span class="learned-scores"><span class="ls-old">${d.prior_score.toFixed(2)}</span> &rarr; <span class="ls-new">${d.adjusted_score.toFixed(2)}</span></span>
+            <span class="learned-scores"><span class="ls-old">${d.prior_score.toFixed(2)}</span> &rarr; <span class="ls-new">${d.adjusted_score.toFixed(2)}</span> <span class="ls-unit">ΔLL</span></span>
             ${badge}
             <span class="learned-reason">${escapeHtml(d.reason)}</span>
         </div>`;
@@ -1431,7 +1435,7 @@ function _renderCalibration(round1Data, measurements) {
     svg.setAttribute('viewBox', `0 0 ${W} ${H}`);
     svg.setAttribute('class', 'calib-svg');
     svg.setAttribute('role', 'img');
-    svg.setAttribute('aria-label', 'Scatter plot of ESM-2 predicted fitness versus your measured values');
+    svg.setAttribute('aria-label', 'Scatter plot of ESM-2 predicted fitness in ΣΔLL versus your measured values');
 
     const xAxis = document.createElementNS(svgNS, 'line');
     xAxis.setAttribute('x1', pad.left); xAxis.setAttribute('x2', pad.left + innerW);
@@ -1457,13 +1461,16 @@ function _renderCalibration(round1Data, measurements) {
     const xLabel = document.createElementNS(svgNS, 'text');
     xLabel.setAttribute('x', pad.left + innerW / 2); xLabel.setAttribute('y', H - 6);
     xLabel.setAttribute('text-anchor', 'middle'); xLabel.setAttribute('class', 'calib-axislabel');
-    xLabel.textContent = 'ESM-2 predicted fitness (round 1)';
+    // Axis titles carry the unit. "predicted fitness" against "measured value"
+    // is two unlabelled scales facing each other; the reader cannot tell what
+    // a one-unit step on x means without it.
+    xLabel.textContent = 'ESM-2 predicted fitness · ΣΔLL (round 1)';
     svg.appendChild(xLabel);
     const yLabel = document.createElementNS(svgNS, 'text');
     yLabel.setAttribute('x', -(pad.top + innerH / 2)); yLabel.setAttribute('y', 12);
     yLabel.setAttribute('transform', 'rotate(-90)');
     yLabel.setAttribute('text-anchor', 'middle'); yLabel.setAttribute('class', 'calib-axislabel');
-    yLabel.textContent = 'Your measured value';
+    yLabel.textContent = 'Your measured value (your assay units)';
     svg.appendChild(yLabel);
 
     body.innerHTML = '';
@@ -1587,7 +1594,7 @@ function _radarSiteChip(site) {
     if (site.shift <= -0.3) cls = 'anti';
     else if (site.shift >= 0.3) cls = 'coop';
     const sign = site.shift > 0 ? '+' : '';
-    return `<span class="radar-site radar-site--${cls}" title="ESM-2 ΔLL shift in context: ${sign}${site.shift.toFixed(2)}">${escapeHtml(site.label)}</span>`;
+    return `<span class="radar-site radar-site--${cls}" title="ESM-2 ΔLL shift in context: ${sign}${site.shift.toFixed(2)} — how much this substitution's log-likelihood gain changes once the other mutations are present.">${escapeHtml(site.label)}</span>`;
 }
 
 function _renderRadar(analysis) {
@@ -1601,9 +1608,11 @@ function _renderRadar(analysis) {
         const m = _radarVerdictMeta(v.verdict);
         const chips = (v.sites || []).map(_radarSiteChip).join('<span class="radar-plus">·</span>');
         const moved = Math.abs(v.corrected_score - v.additive_score) >= 0.05;
+        // Same unit rule as the library table: the number is meaningless
+        // without ΣΔLL next to it, and nobody hovers a score.
         const scoreLine = moved
-            ? `<span class="radar-scores">corrected <b>${v.corrected_score.toFixed(2)}</b> <span class="rs-old">was ${v.additive_score.toFixed(2)}</span></span>`
-            : `<span class="radar-scores">score <b>${v.additive_score.toFixed(2)}</b></span>`;
+            ? `<span class="radar-scores">corrected <b>${v.corrected_score.toFixed(2)}</b> <span class="rs-unit">ΣΔLL</span> <span class="rs-old">was ${v.additive_score.toFixed(2)}</span></span>`
+            : `<span class="radar-scores">score <b>${v.additive_score.toFixed(2)}</b> <span class="rs-unit">ΣΔLL</span></span>`;
         return `<div class="radar-row radar-row--${m.cls}">
             <div class="radar-row-top">
                 <span class="radar-verdict radar-verdict--${m.cls}">${m.label}</span>
@@ -1624,6 +1633,47 @@ function _renderRadar(analysis) {
         st.hidden = false; st.textContent = msg;
         st.classList.toggle('radar-status--warn', !!warn);
     };
+
+    /* Progress signal for a genuinely slow path.
+
+       "Slightly long loading time" was the review note. It is one ESM-2
+       forward pass per mutated site per background, run serially inside a
+       single POST — 12 variants is comfortably tens of seconds on CPU, and
+       the only feedback was a button reading "Analyzing…", which after 20
+       seconds is indistinguishable from a hang. Tool rows in the rail have
+       had an elapsed clock since the CRISPR index made that exact mistake
+       (cockpit.js startTimer); this path never used one.
+
+       Elapsed + the count of passes, not a percentage: the server returns one
+       response for the whole library, so there is no per-variant progress to
+       report and a bar that crept to 60% would be inventing one. */
+    let radarTimer = null;
+    const stopRadarClock = () => {
+        if (radarTimer) { clearInterval(radarTimer); radarTimer = null; }
+    };
+    const startRadarClock = (n) => {
+        const st = document.getElementById('radarStatus');
+        if (!st) return;
+        stopRadarClock();
+        const t0 = Date.now();
+        st.hidden = false;
+        st.classList.remove('radar-status--warn');
+        const lead = `Re-scoring ${n} combination${n === 1 ? '' : 's'} in context with ESM-2 `
+                   + '— one masked forward pass per mutated site, run in sequence.';
+        st.innerHTML = `<span class="radar-lead"></span> <span class="radar-elapsed"></span>`
+                     + '<span class="radar-progress" role="progressbar" aria-label="Analyzing interactions"></span>';
+        st.querySelector('.radar-lead').textContent = lead;
+        const el = st.querySelector('.radar-elapsed');
+        const tick = () => {
+            const s = Math.round((Date.now() - t0) / 1000);
+            const txt = s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+            el.textContent = txt;
+            btn.textContent = `Analyzing… ${txt}`;
+        };
+        tick();
+        radarTimer = setInterval(tick, 1000);
+    };
+
     btn.addEventListener('click', async () => {
         const data = state.lastRun || {};
         const variants = (data.variants || [])
@@ -1631,8 +1681,8 @@ function _renderRadar(analysis) {
             .slice(0, 12)
             .map((v) => ({ Variant_ID: v.Variant_ID, Mutations_AA: v.Mutations_AA }));
         if (!variants.length) { setStatus('No multi-mutant variants to analyze.', true); return; }
-        const orig = btn.textContent; btn.disabled = true; btn.textContent = 'Analyzing…';
-        setStatus(`Re-scoring ${variants.length} combination${variants.length === 1 ? '' : 's'} in context with ESM-2…`);
+        const orig = btn.textContent; btn.disabled = true; btn.textContent = 'Analyzing… 0s';
+        startRadarClock(variants.length);
         try {
             const res = await fetch('/api/de/epistasis', {
                 method: 'POST', headers: { 'Content-Type': 'application/json' },
@@ -1657,7 +1707,14 @@ function _renderRadar(analysis) {
             }
             btn.textContent = 'Re-analyze';
         } catch (e) { setStatus('Interaction analysis failed — please try again.', true); }
-        finally { btn.disabled = false; if (btn.textContent === 'Analyzing…') btn.textContent = orig; }
+        finally {
+            // Before anything else: an interval that outlives the request keeps
+            // counting on a finished panel and rewrites the button label back
+            // to "Analyzing…" every second, which is worse than no clock.
+            stopRadarClock();
+            btn.disabled = false;
+            if (/^Analyzing…/.test(btn.textContent)) btn.textContent = orig;
+        }
     });
 })();
 
@@ -1732,8 +1789,26 @@ function renderResults(data) {
     // hidden — promising a download next to a hidden button is exactly the
     // kind of small lie this table can't afford.
     const provenance = data.agentRun ? 'designed in this conversation' : 'ready to download';
+    /* Requested vs delivered, on the result itself.
+
+       Two ways these differ and both were silent. A conversation-driven
+       design is capped (see CHAT_LIBRARY_CAP), and a sidebar run can return
+       fewer than K when the search cannot find that many distinct variants
+       above the percentile floor. Either way the user typed a number and got
+       a smaller one, with the table's own counter cheerfully reporting the
+       smaller one as if it were the whole story. */
+    const requestedK = data.agentRun
+        ? (Number(data.requestedK) || null)
+        : (Number((data.settings_used || {}).k) || null);
+    const countNote = (requestedK && requestedK !== evolvedCount)
+        ? `<span class="count-note">Requested <b>${requestedK}</b> · scored <b>${evolvedCount}</b>`
+          + (data.agentRun
+              ? ` — a design run inside a conversation is capped at ${CHAT_LIBRARY_CAP}.`
+              : ' — the search found no further distinct variants above the percentile floor.')
+          + '</span>'
+        : '';
     $('#resultSummary').innerHTML =
-        `<strong>${evolvedCount}</strong> variants${hasWt ? ' + wild type' : ''} of <strong>${escapeHtml(data.wt_identifier)}</strong> · ${data.wt_protein.length} aa · ${provenance}${gpNote}`;
+        `<strong>${evolvedCount}</strong> variants${hasWt ? ' + wild type' : ''} of <strong>${escapeHtml(data.wt_identifier)}</strong> · ${data.wt_protein.length} aa · ${provenance}${gpNote}${countNote}`;
 
     // Learning flywheel: remember this run + (re)build the round-2 panel.
     state.lastRun = data;
@@ -1784,6 +1859,20 @@ function renderResults(data) {
     card.scrollIntoView({ behavior: 'smooth', block: 'start' });
 }
 
+/* The chat design tool's REAL bounds, mirrored from
+   dee/core/agent_tools.py::_tool_design_variant_library:
+
+       k = int(args.get("k", 10))      → CHAT_LIBRARY_DEFAULT_K
+       k = max(1, min(20, k))          → CHAT_LIBRARY_CAP
+
+   Hardcoded because the browser has no way to ask the server for them, and
+   guarded by tests/test_chat_library_cap.py, which reads both numbers out of
+   the Python and fails if this file or index.html disagrees. A disclosure
+   that has drifted from the behaviour it describes is worse than none — the
+   user then has a specific wrong number to trust. */
+const CHAT_LIBRARY_CAP = 20;
+const CHAT_LIBRARY_DEFAULT_K = 10;
+
 /* design_variant_library → the Library table.
 
    Lossless: the rows in `panel.variants` come from codon.variants_to_dataframe,
@@ -1791,8 +1880,13 @@ function renderResults(data) {
    real computed value rather than a chat-shaped approximation. What's missing
    is a server-side JOB — so the two controls that need one (library download,
    in-place DNA editing) are switched off via .de-agent-run rather than left
-   to fail against a null job id. */
-function paintAgentDesignRun(panel) {
+   to fail against a null job id.
+
+   `callArgs` is the tool_call's own arguments, handed over by the cockpit. It
+   is the only place the REQUESTED variant count exists on the client: the
+   result payload carries what was delivered and nothing about what was asked
+   for, so without it "you asked for 30, here are 10" cannot be said at all. */
+function paintAgentDesignRun(panel, callArgs) {
     if (!panel || !Array.isArray(panel.variants) || !panel.variants.length) return false;
     renderResults({
         variants: panel.variants,
@@ -1800,13 +1894,35 @@ function paintAgentDesignRun(panel) {
         wt_identifier: panel.wt_identifier || 'Turing run',
         round: panel.round || 1,
         agentRun: true,
+        requestedK: Number((callArgs || {}).k) || null,
     });
     state.jobId = null;
     document.body.classList.add('de-agent-run');
+
+    const delivered = panel.variants.length;
+    const asked = Number((callArgs || {}).k) || null;
+    // Three honest cases, and they say different things. Lumping them into
+    // one sentence ("a chat run just caps the library size") is what left a
+    // user staring at 10 rows after typing 30.
+    let lead;
+    if (asked && asked > delivered) {
+        lead = `You asked for ${asked} variants; ${delivered} were scored. `
+             + `A design run inside a conversation is capped at ${CHAT_LIBRARY_CAP} `
+             + 'because it has to finish inside one reply instead of running as a '
+             + 'background job. ';
+    } else if (asked) {
+        lead = `${delivered} variants — the ${asked} you asked for. `
+             + `A design run inside a conversation is capped at ${CHAT_LIBRARY_CAP}. `;
+    } else {
+        lead = `${delivered} variants. A design run inside a conversation returns `
+             + `${CHAT_LIBRARY_DEFAULT_K} by default and is capped at ${CHAT_LIBRARY_CAP}, `
+             + 'because it has to finish inside one reply. ';
+    }
     window.TDAgentPaint.note('#resultsCard',
-        `These ${panel.variants.length} variants were scored by the same model the full `
-        + 'tool uses — a chat run just caps the library size. Run Directed Evolution '
-        + 'above for a wider search, a downloadable library, and DNA editing.');
+        lead
+        + 'They were scored by the same model and the same search the full tool uses, '
+        + 'on a smaller budget. Run Directed Evolution above for a wider search, a '
+        + 'downloadable library, and DNA editing.');
     return true;
 }
 window.TDDesign = Object.assign(window.TDDesign || {}, { paintAgentRun: paintAgentDesignRun });
@@ -2855,7 +2971,10 @@ function renderStatsStrip(data) {
 
     const tiles = [
         { label: 'Variants', val: variants.length, sub: `${min(nMutations)}–${max(nMutations)} mutations each · mean ${mean(nMutations).toFixed(1)}` },
-        { label: 'Top fitness', val: max(fitness).toFixed(2), sub: `mean ${mean(fitness).toFixed(2)} ΣΔLL` },
+        // A tile is read at a glance and never hovered, so the unit has to be
+        // in the label — "Top fitness 3.41" alone tells a reader nothing about
+        // what 3.41 is or what a good one looks like.
+        { label: 'Top fitness (ΣΔLL)', val: max(fitness).toFixed(2), sub: `mean ${mean(fitness).toFixed(2)} · unnormalised, no fixed zero` },
         { label: 'Position coverage', val: `${positionsTouched.size}`, sub: `${coveragePct}% of WT (${uniqueSubs.size} unique subs)` },
         { label: 'Mean GC', val: `${mean(gc).toFixed(1)}%`, sub: `${min(gc).toFixed(1)}–${max(gc).toFixed(1)}% range` },
         { label: 'Cooler primer Tm', val: `${min(tms).toFixed(1)}°`, sub: `mean ${mean(tms).toFixed(1)}°C` },
@@ -2908,16 +3027,76 @@ function renderRunMeta(data) {
         ['Device', s.device],
         ['Seed', s.seed != null ? s.seed : 'random'],
         ['Wall time', elapsed],
+        // "What score guides the simulated annealing search?" — asked by a
+        // reviewing scientist who could not answer it from this panel. The
+        // objective was only ever stated inside the copy-paste methods
+        // paragraph, which nobody reads as documentation. It belongs in the
+        // parameter row next to the restarts and steps it governs.
+        ['Objective', 'maximise Σ ΔLL'],
     ];
     const pillHtml = pills.map(([k, v]) => `<span class="run-pill">${escapeHtml(k)} <strong>${escapeHtml(String(v))}</strong></span>`).join('');
 
+    // Occupancy of the most-shared substitution across the returned library,
+    // MEASURED from the variants on screen rather than asserted from config.
+    // A reviewer's TEM-1 run came back with one substitution in nine of ten
+    // rows; search.py now caps that, and this is how the user can see it did
+    // — and see it for their own run, whatever the cap is set to.
+    const _occ = new Map();
+    (data.variants || []).forEach((v) => {
+        (v.Mutations_AA || '').split(',').map(x => x.trim()).filter(Boolean)
+            .forEach(m => _occ.set(m, (_occ.get(m) || 0) + 1));
+    });
+    const _nVar = (data.variants || []).length;
+    let _topMut = null, _topN = 0;
+    _occ.forEach((n, m) => { if (n > _topN) { _topN = n; _topMut = m; } });
+    // Concatenated, not interpolated. rjsmin — which minifies every asset in
+    // production — mis-tokenises an APOSTROPHE INSIDE A NESTED template
+    // literal: it reads the ' as the start of a single-quoted string and
+    // loses track of the template. Isolated 2026-08-01: a plain template
+    // holding "the search's set" is fine, and a nested template without an
+    // apostrophe is fine; only the combination breaks. Once desynced it
+    // treats the // in the next `https://…` template as a line comment and
+    // deletes the rest of that line, closing backtick and paren included, so
+    // the SERVED app.js fails to parse and nothing in it runs. `node --check`
+    // on the source passes throughout. tests/test_static_minifies_cleanly.py
+    // catches it now.
+    const diversityHtml = (_nVar && _topMut)
+        ? '<p class="run-diversity"><strong>Library spread.</strong> The most-shared substitution, '
+          + '<code>' + escapeHtml(_topMut) + '</code>, is in <strong>' + _topN + ' of ' + _nVar
+          + '</strong> returned variants; the library covers <strong>' + _occ.size
+          + '</strong> distinct substitutions. The search caps how much of a library any one '
+          + 'substitution may occupy &mdash; a set of near-identical clones tells you nothing '
+          + 'about which mutation did the work.</p>'
+        : '';
+    const diversitySentence = (_nVar && _topMut)
+        ? ' The returned set was assembled from the hall of fame under a per-substitution '
+          + 'occupancy cap, so that no single substitution dominates the library (most-shared: '
+          + escapeHtml(_topMut) + ', ' + _topN + ' of ' + _nVar + ' variants).'
+        : '';
+
+    // The direct answer to "what does the search maximise?", in prose, above
+    // the manuscript paragraph. Confirmed against dee/optimizer/search.py
+    // (_fitness) and dee/models/scorer.py (score_all_substitutions) before
+    // it was written: additive sum of per-substitution ΔLL, minus two hard
+    // penalties, and it is the same number the Fitness column shows.
+    const objectiveHtml =
+        '<p class="run-objective"><strong>What the search maximises.</strong> The sum of the '
+        + 'per-substitution scores of a variant&rsquo;s mutations, minus a hard penalty for a stop '
+        + 'codon or for two mutations at the same residue &mdash; the same number the '
+        + '<em>Fitness</em> column shows. Those per-substitution scores are ESM-2 &Delta;LL '
+        + '(wild-type marginal log-likelihood of the mutant residue minus the wild-type residue); '
+        + 'after you log bench results, round 2 replaces them with the learned acquisition score '
+        + 'and the search is otherwise unchanged. The objective is additive, so it does '
+        + '<em>not</em> model epistasis &mdash; that is what the Radar is for.</p>';
+
     // Auto-generated methods paragraph — copy-paste into a manuscript.
     const wtLen = (data.wt_protein || '').length;
     const wtId  = data.wt_identifier || 'wild-type';
-    const methods = `Variants of ${escapeHtml(wtId)} (${wtLen} aa) were designed in silico with ESM-2 ${modelLabel.replace('ESM-2 ', '')} (Lin et al., <cite>Science</cite> 2023) using the wild-type marginal log-likelihood scoring scheme of Meier et al. (<cite>Adv. Neural Inf. Process. Syst.</cite> 2021). Single-point substitutions in the top ${(100 - s.percentile).toFixed(0)}% by ΔLL were retained as the combinatorial search space. ${s.k} multi-mutant variants with ${s.min_mutations}–${s.max_mutations} simultaneous substitutions were generated by simulated annealing (${s.restarts} restarts × ${s.steps_per_restart} steps, geometric cooling) maximizing cumulative ΔLL with stop-codon and duplicate-position penalties. Optimized DNA was reverse-translated using ${hostLabel} codon-usage frequencies and synonymously cleaned of BsaI, BsmBI, and NotI recognition sites for Golden Gate compatibility.`;
+    const methods = `Variants of ${escapeHtml(wtId)} (${wtLen} aa) were designed in silico with ESM-2 ${modelLabel.replace('ESM-2 ', '')} (Lin et al., <cite>Science</cite> 2023) using the wild-type marginal log-likelihood scoring scheme of Meier et al. (<cite>Adv. Neural Inf. Process. Syst.</cite> 2021). Single-point substitutions in the top ${(100 - s.percentile).toFixed(0)}% by ΔLL were retained as the combinatorial search space. ${s.k} multi-mutant variants with ${s.min_mutations}–${s.max_mutations} simultaneous substitutions were generated by simulated annealing (${s.restarts} restarts × ${s.steps_per_restart} steps, geometric cooling) maximizing cumulative ΔLL with stop-codon and duplicate-position penalties.${diversitySentence} Optimized DNA was reverse-translated using ${hostLabel} codon-usage frequencies and synonymously cleaned of BsaI, BsmBI, and NotI recognition sites for Golden Gate compatibility.`;
 
     box.innerHTML = `
         <div class="run-meta-pills">${pillHtml}</div>
+        <div class="run-notes">${objectiveHtml}${diversityHtml}</div>
         <div class="run-methods">
             <div class="run-methods-head">
                 <h4>Materials &amp; methods (copy-paste)</h4>
@@ -2931,37 +3110,111 @@ function renderRunMeta(data) {
 
 // =============================================================== MUTATION MAP
 // Lollipop chart: x = residue position, y = how many variants share a mutation
-// at that position. Dots colored by mean ΔLL strength. Standard genomics
-// visualization (cBioPortal / ProteinPaint).
+// at that position, colour = the signed mean ΔLL at that position. Standard
+// genomics visualization (cBioPortal / ProteinPaint).
+//
+// ── the colour scale, and why it is this one ────────────────────────────────
+// ΔLL is continuous and SIGNED, and the sign is the entire claim: positive
+// means ESM-2 finds the substitution MORE plausible than the residue evolution
+// actually chose, negative means less. The first version threw that away
+// twice over. It min-max normalised the values — which erases zero, so a set
+// of uniformly bad mutations rendered identically to a set of uniformly good
+// ones — and then quantised the result into three hard-coded greys,
+// '#CFCBC2' / '#3D3A34' / '#1B1A17'. Measured against a real 30-variant GFP
+// library those three collapsed to ONE (the run mutates two positions with
+// equal mean, so sMax === sMin and every dot took the same fill), and that
+// fill scored 1.53:1 against the dark canvas — below the 3:1 floor for a
+// non-text element, which is exactly the "invisible" in the review. The card
+// meanwhile described a legend, "faint · medium · saturated", that had been
+// deleted from the markup.
+//
+// What replaces it:
+//   • Diverging, anchored at ΔLL = 0, so the zero crossing is a colour
+//     boundary you can see rather than a number you have to read.
+//   • Blue ↔ orange, the Okabe–Ito colour-vision-deficiency-safe pair
+//     (#0072B2 / #D55E00). Red/green would be the obvious "bad/good" choice
+//     and is the one pair ~8% of male readers cannot separate. This is a
+//     scientific readout, so it does not get to be the obvious one.
+//   • Near-constant luminance across the whole ramp. A conventional diverging
+//     scale pales towards the middle, which disappears on the light theme's
+//     white canvas; holding every stop between 0.13 and 0.30 relative
+//     luminance keeps ≥3:1 against BOTH canvases (white, and #1B1A18) at
+//     every value. Verified numerically, not by eye —
+//     tests/test_mutmap_scale.py re-derives the contrast for the whole ramp.
+//   • A legend that states the units and the domain, including when the
+//     domain is clipped.
+const MUTMAP_NEG = [0, 114, 178];      // Okabe–Ito blue   — worse than wild type
+const MUTMAP_POS = [213, 94, 0];       // Okabe–Ito vermillion — better than WT
+const MUTMAP_MID = [123, 119, 111];    // warm neutral: ΔLL ≈ 0, "no signal"
+
+// t ∈ [-1, +1] → CSS rgb(). A straight blend from the neutral out to each
+// endpoint. Deliberately not a lightness ramp: see the note above.
+function mutmapColor(t) {
+    const k = Math.max(-1, Math.min(1, Number(t) || 0));
+    const end = k < 0 ? MUTMAP_NEG : MUTMAP_POS;
+    const a = Math.abs(k);
+    const c = MUTMAP_MID.map((m, i) => Math.round(m + (end[i] - m) * a));
+    return `rgb(${c[0]}, ${c[1]}, ${c[2]})`;
+}
+
+// The rail is draggable now (railsplit.js) and the chart is laid out in
+// absolute pixels read from clientWidth, so a resize has to re-lay it out or
+// the SVG stretches its own axis labels.
+let _mutmapLast = null;
+let _mutmapRO = null;
+
 function renderMutationMap(data) {
     const root = document.getElementById('mutmapCanvas');
     if (!root) return;
+    _mutmapLast = data;
     root.innerHTML = '';
 
     const wtLen = (data.wt_protein || '').length;
     if (!wtLen) return;
+    // Fill the real protein length into the axis key above the chart, so
+    // "x = residue position (1–N)" names an actual range instead of an N.
+    const lenSlot = document.getElementById('mutmapLen');
+    if (lenSlot) lenSlot.textContent = String(wtLen);
 
-    // Aggregate mutation counts and signed ΔLL contribution per position.
+    // Aggregate per position: how many variants mutate here, and the mean
+    // signed ΔLL attributed to the position.
+    //
+    // The attribution is the honest limit of what the payload carries. A
+    // variant reports ΣΔLL over its own substitutions and nothing per-residue,
+    // so each of its mutations is credited ΣΔLL ÷ (number of mutations) and
+    // those are averaged over the variants that touch the position. It is an
+    // even split, not a measurement of that one substitution — the tooltip
+    // and the legend both say "attributed" for that reason. Do not relabel it
+    // as the substitution's own ΔLL.
+    //
+    // MEAN, not the sum the first version used: the sum grows with the number
+    // of variants at a position, which is already the bar's height, so a
+    // frequently-hit position looked "strong" purely for being frequent.
     const counts = new Map();      // position -> count
-    const strength = new Map();    // position -> sum of fitness contribution
+    const total = new Map();       // position -> summed attributed ΔLL
     let maxCount = 0;
     (data.variants || []).forEach((v) => {
         const muts = (v.Mutations_AA || '').split(',').map(s => s.trim()).filter(Boolean);
-        // Per-variant fitness divided by mutation count is our crude per-mut weight.
-        const w = Number(v.Predicted_Fitness_Score) / Math.max(1, muts.length);
+        if (!muts.length) return;                       // WT row carries no mutations
+        const score = Number(v.Predicted_Fitness_Score);
+        if (!Number.isFinite(score)) return;            // never coerce a blank to 0
+        const w = score / muts.length;
         muts.forEach((m) => {
             const numMatch = m.match(/[0-9]+/);
             if (!numMatch) return;
             const pos = parseInt(numMatch[0], 10);
             counts.set(pos, (counts.get(pos) || 0) + 1);
-            strength.set(pos, (strength.get(pos) || 0) + w);
+            total.set(pos, (total.get(pos) || 0) + w);
             if (counts.get(pos) > maxCount) maxCount = counts.get(pos);
         });
     });
     if (!counts.size) {
         root.innerHTML = '<div class="muted" style="padding:16px;text-align:center;">No mutations to plot.</div>';
+        renderMutationKey(null);
         return;
     }
+    const strength = new Map();    // position -> MEAN attributed ΔLL
+    counts.forEach((n, pos) => strength.set(pos, total.get(pos) / n));
 
     // SVG geometry
     const W = root.clientWidth || 800;
@@ -2973,17 +3226,28 @@ function renderMutationMap(data) {
     const xScale = (p) => pad.left + (p - 1) / Math.max(1, wtLen - 1) * innerW;
     const yScale = (c) => pad.top + innerH - (c / maxCount) * innerH;
 
-    // Compute color by strength: brand-200 (low) → brand (mid) → brand-deep (high)
+    /* The domain. Symmetric about zero — an asymmetric one would put the
+       neutral colour somewhere other than ΔLL = 0 and the scale would lie
+       about the sign.
+
+       Clipped at the 95th percentile of |ΔLL| so one outlier position cannot
+       flatten every other dot to grey, but ONLY when there are enough
+       positions for a percentile to mean anything. Below 8 the domain is the
+       plain observed maximum, and the legend says which of the two you are
+       looking at — announcing "clipped at p95" over three data points would
+       be a statistic invented to sound rigorous. */
     const strengths = [...strength.values()];
-    const sMax = Math.max(...strengths);
-    const sMin = Math.min(...strengths);
-    const colorFor = (s) => {
-        if (sMax === sMin) return '#3D3A34';
-        const t = (s - sMin) / (sMax - sMin);
-        if (t < 0.33) return '#CFCBC2';
-        if (t < 0.66) return '#3D3A34';
-        return '#1B1A17';
-    };
+    const mags = strengths.map(Math.abs).sort((a, b) => a - b);
+    const CLIP_MIN_N = 8;
+    const clipped = mags.length >= CLIP_MIN_N;
+    let domain = clipped
+        ? mags[Math.min(mags.length - 1, Math.floor(0.95 * (mags.length - 1)))]
+        : mags[mags.length - 1];
+    if (!(domain > 0)) domain = 0;                 // every position exactly 0
+    const nOutside = clipped ? mags.filter(m => m > domain).length : 0;
+    // A dot at ±domain reaches full saturation; beyond it the colour holds
+    // (that is what clipping means) and the legend declares it.
+    const colorFor = (s) => mutmapColor(domain > 0 ? s / domain : 0);
 
     // Ticks every ~50 residues, with at least 4 ticks.
     const tickStep = Math.max(10, Math.ceil(wtLen / Math.max(4, Math.min(12, Math.floor(wtLen / 25)))));
@@ -3024,8 +3288,9 @@ function renderMutationMap(data) {
         axis.appendChild(lbl);
     });
 
-    // Y axis labels (count)
-    const yLabels = [maxCount, Math.ceil(maxCount / 2), 1];
+    // Y axis labels (count). Deduped: a library that hits every position once
+    // gives maxCount = 1 and printed "1" three times on top of itself.
+    const yLabels = [...new Set([maxCount, Math.ceil(maxCount / 2), 1])];
     yLabels.forEach((c) => {
         const y = yScale(c);
         const lbl = document.createElementNS(svgNS, 'text');
@@ -3050,19 +3315,126 @@ function renderMutationMap(data) {
         stem.setAttribute('class', 'mutmap-stem');
         svg.appendChild(stem);
 
+        const mean = strength.get(pos);
         const dot = document.createElementNS(svgNS, 'circle');
         dot.setAttribute('cx', x);
         dot.setAttribute('cy', y);
         dot.setAttribute('r', Math.max(3, 3 + c * 0.4));
-        dot.setAttribute('fill', colorFor(strength.get(pos)));
+        dot.setAttribute('fill', colorFor(mean));
         dot.setAttribute('class', 'mutmap-dot');
         const title = document.createElementNS(svgNS, 'title');
-        title.textContent = `Position ${pos} · ${c} variant${c === 1 ? '' : 's'} mutate here · Σ contribution ${strength.get(pos).toFixed(2)}`;
+        // Signed, and it says what the number IS. "Σ contribution" named a
+        // quantity that was neither a sum the reader could reconstruct nor
+        // comparable between positions. Concatenation, not a template
+        // literal: rjsmin strips whitespace either side of `${…}` in the
+        // SERVED bundle, which is what put "1 variant mutate here" and
+        // "units(ESM-2 35M)" in front of a reviewer.
+        title.textContent = 'Position ' + pos + ' · ' + c
+            + (c === 1 ? ' variant mutates here · ' : ' variants mutate here · ')
+            + 'mean attributed ΔLL ' + (mean >= 0 ? '+' : '') + mean.toFixed(2);
         dot.appendChild(title);
         svg.appendChild(dot);
     });
 
     root.appendChild(svg);
+    renderMutationKey({ domain, clipped, nOutside, nPositions: counts.size,
+                        model: (data.settings_used || {}).model });
+
+    // One observer for the life of the page; it re-runs the layout above with
+    // whatever data was last rendered.
+    if (!_mutmapRO && typeof ResizeObserver !== 'undefined') {
+        let pending = null;
+        _mutmapRO = new ResizeObserver(() => {
+            if (pending) return;
+            pending = requestAnimationFrame(() => {
+                pending = null;
+                if (_mutmapLast && root.isConnected && root.clientWidth) {
+                    renderMutationMap(_mutmapLast);
+                }
+            });
+        });
+        _mutmapRO.observe(root);
+    }
+}
+
+/* The legend. A gradient with no numbers on it is decoration; this one has to
+   answer "what is being encoded, in what units, over what range, and is the
+   range the whole story". The swatches come from mutmapColor(), so the key
+   cannot drift away from the chart it explains. */
+function renderMutationKey(info) {
+    const host = document.getElementById('mutmapKey');
+    if (!host) return;
+    if (!info || !(info.domain > 0)) {
+        // Every position identical (or zero). A ramp here would imply a
+        // spread that isn't in the data.
+        host.innerHTML = info
+            ? '<p class="mutmap-key-note">Every plotted position carries the same attributed '
+              + '&Delta;LL, so there is no gradient to show &mdash; the dots are one colour '
+              + 'because the data is one value, not because the scale collapsed.</p>'
+            : '';
+        return;
+    }
+    /* Built with ordinary quoted strings and `+`, NOT a template literal.
+
+       The assets are minified in production by rjsmin, which predates ES6 and
+       does not recognise a backtick as opening a string. Inside a template
+       literal it therefore treats the prose as code and strips "insignificant"
+       whitespace next to punctuation — so
+
+           `... units${modelLabel ? ' (' + m + ')' : ''}.`
+           `... across ${n} position${n === 1 ? '' : 's'} &mdash; nothing`
+
+       shipped to users as "units(ESM-2 35M)" and "2positions&mdash;nothing".
+       Verified by running rjsmin.jsmin() over this function: the spaces either
+       side of every ${…} boundary are gone in the minified output, while the
+       same text inside '…' survives untouched.
+
+       This is not local to the legend — it is a property of every template
+       literal in app.js — but the fix here is to stop relying on it. Spaced
+       em dashes are the house style (30 of 33 in index.html, 352 of 421 in
+       app.js), and this paragraph is the one that has to read as though a
+       scientist wrote it. */
+    const stops = [-1, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1]
+        .map(t => mutmapColor(t) + ' ' + ((t + 1) / 2 * 100).toFixed(0) + '%')
+        .join(', ');
+    const d = info.domain;
+    const fmt = (n) => (n >= 0 ? '+' : '') + n.toFixed(2);
+    const modelLabel = { small: 'ESM-2 35M', medium: 'ESM-2 650M', large: 'ESM-2 3B' }[info.model];
+    const n = info.nPositions;
+    const plural = (k, word) => k + ' ' + word + (k === 1 ? '' : 's');
+
+    const domainNote = info.clipped
+        ? ('Scale clipped at the 95th percentile of |&Delta;LL| across '
+           + plural(n, 'position')
+           + (info.nOutside
+                ? (' &mdash; ' + plural(info.nOutside, 'position') + ' '
+                   + (info.nOutside === 1 ? 'falls' : 'fall')
+                   + ' beyond it and ' + (info.nOutside === 1 ? 'is' : 'are')
+                   + ' drawn at full saturation.')
+                : '.'))
+        : ('Scale spans the full observed range across ' + plural(n, 'position')
+           + ' &mdash; nothing is clipped.');
+
+    host.innerHTML =
+        '<div class="mutmap-key-scale" role="img" aria-label="Diverging colour scale from '
+          + escapeHtml(fmt(-d)) + ' to ' + escapeHtml(fmt(d))
+          + ' log-likelihood units, centred on zero">'
+          + '<span class="mutmap-key-bar" style="background: linear-gradient(to right, '
+            + stops + ');"></span>'
+          + '<span class="mutmap-key-ticks">'
+            + '<span>' + escapeHtml(fmt(-d)) + '</span><span>0</span>'
+            + '<span>' + escapeHtml(fmt(d)) + '</span>'
+          + '</span>'
+        + '</div>'
+        + '<p class="mutmap-key-note">'
+          + '<strong>Mean attributed &Delta;LL per mutation</strong>, in log-likelihood units'
+          + (modelLabel ? ' (' + escapeHtml(modelLabel) + ')' : '') + '. '
+          + 'Positive means the model finds the substitution <em>more</em> plausible than the '
+          + 'wild-type residue; negative, less. Each variant&rsquo;s &Sigma;&Delta;LL is split '
+          + 'evenly across its own mutations, so this is '
+          + 'an attribution, not a per-substitution measurement.'
+        + '</p>'
+        + '<p class="mutmap-key-note">' + domainNote + '</p>';
 }
 
 // =============================================================== COMMAND PALETTE
@@ -5579,6 +5951,21 @@ if (_quitBtn) {
         const origLabel = labelEl ? labelEl.textContent : '';
         if (labelEl) labelEl.textContent = 'Designing…';
 
+        // The progress shimmer's stop switch, declared OUT here deliberately.
+        // `finally` is a sibling block to `try`, so a `const` declared inside
+        // the try is not in scope in the finally — the old placement made the
+        // closing `_hideProgress()` throw ReferenceError on EVERY design, and
+        // a throw in a finally also swallows whatever error the catch was
+        // handling. Measured 2026-08-01: after a *successful* design the
+        // shimmer was still on screen at 74 px with its elapsed counter still
+        // ticking (3.0s and climbing), and the setInterval leaked every run.
+        let progressTimer = null;
+        let progressShell = null;
+        const _hideProgress = () => {
+            if (progressTimer) { clearInterval(progressTimer); progressTimer = null; }
+            if (progressShell) progressShell.hidden = true;
+        };
+
         try {
             // Read the enzyme picker (Phase 1). Defaults to cas9 if the
             // picker isn't in the DOM (cached old build).
@@ -5605,11 +5992,10 @@ if (_quitBtn) {
             // to the slowest step the request will hit so the user knows
             // what's taking time (esp. for the ~60-90 s first build of
             // the human genome index).
-            const progressShell  = document.getElementById('crisprProgressShell');
+            progressShell  = document.getElementById('crisprProgressShell');
             const progressStatus = document.getElementById('crisprProgressStatus');
             const progressElapsed = document.getElementById('crisprProgressElapsed');
             const progressMessage = document.getElementById('crisprProgressMessage');
-            let progressTimer = null;
             if (progressShell) {
                 progressShell.hidden = false;
                 if (progressStatus) {
@@ -5638,13 +6024,6 @@ if (_quitBtn) {
                     }
                 }, 100);
             }
-            // Wrap in a try/finally so the spinner ALWAYS hides, even
-            // on early returns (signin modal, error, etc.).
-            const _hideProgress = () => {
-                if (progressTimer) { clearInterval(progressTimer); progressTimer = null; }
-                if (progressShell) progressShell.hidden = true;
-            };
-
             // Phase 2C-1: lazy-load the vector catalog on first design
             // click (subsequent clicks reuse the cache). Picker only
             // gets populated AFTER the load, so the first fetch sends
@@ -5654,6 +6033,11 @@ if (_quitBtn) {
             await ensureVectorsLoaded(enzyme);
             const vector_id = (vectorSelect && vectorSelect.value) || '';
 
+            // Warm the genome registry while the design runs, so the scope
+            // strip can name the actual coverage on its FIRST paint instead
+            // of a beat later. Fire-and-forget: a failure only costs detail.
+            _ensureGenomeScopes();
+
             const res = await fetch('/api/crispr/design', {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
@@ -5724,6 +6108,118 @@ if (_quitBtn) {
             'Your guides are scored normally &mdash; the <em>Genome off</em> column will fill in after you click <strong>Design</strong> again in a minute or two.';
     }
 
+    // ─── Scope strip: what these numbers assume, at the point you read them
+    //
+    // Three facts a reviewing scientist could not get out of this panel:
+    //   1. "Composite" bakes in a 0.6 weight nobody could see.
+    //   2. FS % / Top indel are end-joining repair predictions with fixed
+    //      constants — they are NOT conditioned on the user's cell type,
+    //      and the panel never admitted it.
+    //   3. For human/mouse the genome search covers CODING SEQUENCE ONLY,
+    //      while the surrounding panel reads like a whole-genome screen.
+    //
+    // All three live here, once, immediately above the table — not repeated
+    // per column and not hidden behind the collapsed provenance block, which
+    // is where they were and which is why they went unread. The per-guide
+    // why-panel keeps a one-clause version tied to that guide's own numbers;
+    // the collapsed block keeps the full method text.
+    //
+    // The genome wording comes from the server's own registry via
+    // /api/crispr/methods (genome_scopes), never from a list hardcoded here.
+    let _genomeScopes = null;
+
+    function _scopeStripEl() {
+        let el = document.getElementById('crisprScopeStrip');
+        if (!el) {
+            el = document.createElement('div');
+            el.id = 'crisprScopeStrip';
+            el.className = 'crispr-scope-strip';
+            const tableWrap = resCard.querySelector('.result-table-wrap');
+            if (tableWrap && tableWrap.parentNode) tableWrap.parentNode.insertBefore(el, tableWrap);
+            else resCard.appendChild(el);
+        }
+        return el;
+    }
+
+    function _renderScopeStrip(data) {
+        const el = _scopeStripEl();
+        const guides = data.guides || [];
+        const isBE = data.mode === 'base_edit';
+        const org = data.genome_organism || '';
+        const rows = [];
+
+        // 1. Composite — the weight, read off the guide that carries it, so
+        //    the strip can never drift from the constant the engine used.
+        //    (Older cached payloads have no weight field; then say nothing
+        //    rather than assert a number we didn't get.)
+        if (!isBE) {
+            const w = guides.length ? guides[0].composite_offtarget_weight : null;
+            if (typeof w === 'number') {
+                rows.push(['Composite',
+                    'on-target × (1 − ' + w + ' × self-off). The ' + w + ' is our judgement call, '
+                    + 'not a published constant &mdash; a guide duplicated exactly elsewhere in your '
+                    + 'input keeps ' + Math.round((1 - w) * 100) + '% of its on-target score rather than dropping to zero. '
+                    + 'Sort by On-target and Self-off separately to apply your own trade-off.']);
+            }
+        }
+
+        // 2. Repair context for the indel columns (knockout mode only —
+        //    base-edit mode hides them).
+        if (!isBE) {
+            rows.push(['Repair outcomes',
+                '<strong>Top indel</strong>, <strong>FS&nbsp;%</strong> and <strong>Dominance</strong> assume '
+                + 'template-free end-joining (MMEJ + NHEJ) of a blunt Cas9 cut, with no HDR donor. '
+                + 'The model uses fixed published constants and takes <strong>no cell-type input</strong>, '
+                + 'so the same guide returns the same FS&nbsp;% in mESC, U2OS, HEK293 or primary cells &mdash; '
+                + 'yet the real MMEJ/NHEJ balance differs between them. Rank guides with these; don&rsquo;t quote them '
+                + 'as rates for your cell line.']);
+        }
+
+        // 3. Off-target scope. Three genuinely different states, and the
+        //    difference matters more than the numbers do.
+        const screened = data.genome_searched_top_n || 0;
+        if (!org) {
+            rows.push(['Off-target scope',
+                '<strong>The pasted sequence only.</strong> No genome was searched &mdash; the '
+                + '<em>Self-off</em> column compares each guide against the other candidate sites in your '
+                + 'input, nothing more. Pick an organism above to screen your top guides against a genome.']);
+        } else {
+            const sc = _genomeScopes && _genomeScopes[org];
+            const name = (sc && sc.name) || org;
+            const complete = sc ? !!sc.complete : null;
+            const note = sc ? sc.note
+                            : 'Coverage for this organism is listed under &ldquo;How these numbers were computed&rdquo;.';
+            const depth = screened
+                ? ' Only the top ' + screened + ' of ' + guides.length + ' guides were screened (the ones you would realistically order).'
+                : '';
+            rows.push(['Off-target scope',
+                (complete === false ? '<strong>Not a whole-genome screen.</strong> ' : '')
+                + 'Searched against <strong>' + escapeHtml(name) + '</strong>. ' + note + depth]);
+        }
+
+        el.innerHTML = rows.map(([k, v]) =>
+            '<div class="crispr-scope-row"><span class="crispr-scope-k">' + escapeHtml(k) + '</span>'
+            + '<span class="crispr-scope-v">' + v + '</span></div>').join('');
+        el.hidden = !rows.length;
+    }
+
+    // Fetch the genome registry once, then repaint the strip with the real
+    // per-organism coverage. Deliberately fire-and-forget: the strip already
+    // rendered a truthful (if less specific) line synchronously, so a failed
+    // fetch degrades to less detail, never to a wrong claim.
+    function _ensureGenomeScopes() {
+        if (_genomeScopes || !window.TDMethods || !window.TDMethods.ensure) return;
+        window.TDMethods.ensure().then((payload) => {
+            if (!payload || !payload.genome_scopes) return;
+            _genomeScopes = payload.genome_scopes;
+            // Repaint the two places that name the coverage: the strip and
+            // the copy-paste methods paragraph. (Per-guide why-panels fall
+            // back to pointing at the strip until the next render, which is
+            // vaguer but never wrong.)
+            if (crisprData) { _renderScopeStrip(crisprData); _renderCrisprMeta(crisprData); }
+        }).catch(() => {});
+    }
+
     // ─── Phase 3 (M3): results UX — sort / filter / explain ─────────
     // The design response is cached so header-click sorting and filter
     // toggles re-render the table WITHOUT re-fetching from the backend.
@@ -5780,8 +6276,22 @@ if (_quitBtn) {
             p.push(`Editability is <strong>${(g.be_editability || 0).toFixed(2)}</strong> (higher = the edit is more likely).`);
         } else {
             p.push(`On-target activity <strong>${(g.on_target_score || 0).toFixed(2)}</strong>, predicted knockout efficacy <strong>${(g.ko_efficacy || 0).toFixed(2)}</strong>${g.ko_reasoning ? ' — ' + escapeHtml(g.ko_reasoning) : ''}.`);
+            // The composite arithmetic for THIS guide, with the weight the
+            // engine actually used. The weight rides on the guide
+            // (composite_offtarget_weight) rather than being written here, so
+            // a change to crispr.COMPOSITE_OFFTARGET_WEIGHT can't leave the
+            // explanation showing a number the ranking no longer uses.
+            const cw = g.composite_offtarget_weight;
+            if (typeof cw === 'number' && typeof g.composite_score === 'number') {
+                p.push(`Composite <strong>${g.composite_score.toFixed(3)}</strong> = on-target `
+                    + `${(g.on_target_score || 0).toFixed(3)} × (1 − ${cw} × self-off `
+                    + `${(g.cfd_max_offtarget || 0).toFixed(3)}).`);
+            }
             if (typeof g.frameshift_pct === 'number') {
                 p.push(`About <strong>${g.frameshift_pct.toFixed(0)}%</strong> of predicted repair outcomes cause a frameshift; the most likely single outcome is <strong>${escapeHtml(g.top_indel_label || '—')}</strong>.`);
+                // Never let a frameshift percentage be read as a measured rate
+                // for the reader's own cells: the model has no cell-type input.
+                p.push('Those are end-joining predictions with fixed constants and <strong>no cell-type conditioning</strong> — use them to compare guides, not as expected rates in your line.');
             }
         }
         const selfCfd = g.cfd_max_offtarget || 0;
@@ -5802,14 +6312,22 @@ if (_quitBtn) {
         // guide. Previously this always told the user to go run CRISPOR — even
         // when a real genome search had just run here, which is what made the
         // tool feel like a stop on the way to somewhere else.
+        // Coverage comes from the server's genome registry, not from a list
+        // written here. The old test was `organism === 'ecoli' ? complete :
+        // coding-sequence-only`, which told every yeast, worm and fly run it
+        // had screened coding sequence only — those genomes are indexed
+        // COMPLETE. The full scope wording lives in the strip above the
+        // table; this is the one-clause version tied to this guide.
         if (!g.genome_organism) {
             p.push('<em>No genome off-target search was run — pick an organism above to screen your top guides against the genome.</em>');
-        } else if (g.genome_organism === 'ecoli') {
-            p.push('<em>Screened against the complete E. coli K-12 genome.</em>');
         } else {
-            p.push('<em>Screened against ' + escapeHtml(g.genome_organism) +
-                   ' coding sequence. Intronic and intergenic off-targets are outside this index — ' +
-                   'use a whole-genome tool if your application needs them.</em>');
+            const sc = _genomeScopes && _genomeScopes[g.genome_organism];
+            const nm = escapeHtml((sc && sc.name) || g.genome_organism);
+            p.push(!sc
+                ? `<em>Screened against ${nm} — see the off-target scope note above the table.</em>`
+                : (sc.complete
+                    ? `<em>Screened against the complete ${nm} genome.</em>`
+                    : `<em>Screened against ${nm} — coding sequence only; intronic and intergenic sites are outside this index.</em>`));
         }
         // Phase 3 (M5): structure-view button when the cut maps to a residue
         // AND a gene symbol + organism are set (needed to resolve UniProt).
@@ -6266,6 +6784,14 @@ if (_quitBtn) {
         const enzLabel = enzyme === 'cas12a' ? 'Cas12a (TTTV PAM)' : 'SpCas9 (NGG PAM)';
         const be = (data.base_editor || '').toUpperCase();
         const org = data.genome_organism || '';
+        // How many guides the genome search actually covered, and over what.
+        // Both come from the run + the server's genome registry; when the
+        // registry hasn't loaded we omit the qualifier rather than guess it.
+        const screened = data.genome_searched_top_n || 0;
+        const scopeSrc = _genomeScopes && _genomeScopes[org];
+        const scopeName = (scopeSrc && scopeSrc.name) || org;
+        const scopeQual = !scopeSrc ? ''
+            : (scopeSrc.complete ? ' (complete genome)' : ' (coding sequence only; intronic and intergenic sites not covered)');
         const top = guides.slice().sort((a, b) => (b.composite_score || 0) - (a.composite_score || 0))[0] || guides[0];
         const strand = (top.strand === '-' || top.strand < 0) ? 'antisense' : 'sense';
         const comp = top.composite_score != null ? Number(top.composite_score).toFixed(2) : '—';
@@ -6273,7 +6799,22 @@ if (_quitBtn) {
         if (isBE) {
             m = `Guide RNAs (n=${guides.length}) were designed in silico for ${enzLabel} base editing with the ${escapeHtml(be) || 'selected'} editor (Komor et al., <cite>Nature</cite> 2016; Gaudelli et al., <cite>Nature</cite> 2017). On-target activity used Doench-style sequence features; per-guide editability was scored over the editor's activity window, with the predicted edit and amino-acid consequence reported. The top-ranked guide (${escapeHtml(top.spacer || '')}, ${strand} strand) was selected.`;
         } else {
-            m = `Guide RNAs (n=${guides.length}) were designed in silico for ${enzLabel}. On-target activity was scored from Doench-style sequence features, and off-target potential within the provided sequence by the cutting-frequency-determination (CFD) matrix (Doench et al., <cite>Nat. Biotechnol.</cite> 2016); knockout likelihood was estimated from the predicted indel spectrum (frameshift fraction and out-of-frame dominance). The top-ranked guide (${escapeHtml(top.spacer || '')}, ${strand} strand, composite ${comp})${enzyme === 'cas12a' ? ' was selected' : ' was selected, and cloning oligos were generated for the standard BbsI/BsmBI vector'}. Off-target assessment is limited to the input sequence and is not genome-wide.`;
+            // Everything a reader would need to reproduce or challenge the
+            // ranking, including the two things the paragraph used to leave
+            // out: the composite's weight, and what repair context the indel
+            // numbers assume. Both are read off the run, not asserted here.
+            const cw = top.composite_offtarget_weight;
+            const rankSentence = (typeof cw === 'number')
+                ? ` Guides were ranked by a composite score, on-target × (1 − ${cw} × CFD_max), in which the ${cw} off-target weight is an uncalibrated in-house choice rather than a published constant.`
+                : '';
+            // Scope, stated as what was actually screened. The old closing
+            // sentence claimed "not genome-wide" unconditionally, which stopped
+            // being true the moment the genome search shipped — and is still
+            // the honest answer when no organism was picked.
+            const scopeSentence = (org && screened)
+                ? ` The ${screened} top-ranked guides were additionally screened for genomic off-targets against ${escapeHtml(scopeName)}${scopeQual}; the remaining candidates were not screened.`
+                : ' Off-target assessment is limited to the input sequence and is not genome-wide.';
+            m = `Guide RNAs (n=${guides.length}) were designed in silico for ${enzLabel}. On-target activity was scored from Doench-style sequence features, and off-target potential within the provided sequence by the cutting-frequency-determination (CFD) matrix (Doench et al., <cite>Nat. Biotechnol.</cite> 2016).${rankSentence} Knockout likelihood was estimated from a predicted indel spectrum — microhomology-mediated deletions (Bae et al., <cite>Nat. Methods</cite> 2014) plus a templated +1 insertion class — summarised as the frameshift fraction and the share of the single most likely outcome; that model assumes template-free end-joining repair and uses fixed constants, so it is not conditioned on cell type. The top-ranked guide (${escapeHtml(top.spacer || '')}, ${strand} strand, composite ${comp})${enzyme === 'cas12a' ? ' was selected' : ' was selected, and cloning oligos were generated for the standard BbsI/BsmBI vector'}.${scopeSentence}`;
         }
         tdRenderMethods('crisprRunMeta', [
             ['Mode', isBE ? 'base edit' : 'knockout'],
@@ -6313,6 +6854,11 @@ if (_quitBtn) {
         // previous design had no vector picked).
         lastGuides = data.guides || [];
         crisprData = data;
+        // What the numbers assume, above the numbers. Rendered on every
+        // paint (including sort/filter re-renders) so it can never be
+        // scrolled away from the columns it qualifies.
+        _renderScopeStrip(data);
+        _ensureGenomeScopes();
         if (!_isRerender && window.TDCrisprOutcomes) window.TDCrisprOutcomes.populate(data.guides || []);
         renderVendorButtons();
 
@@ -10180,6 +10726,12 @@ function runOracle(opts){
                 + '<p class="method-what">' + esc(m.what) + '</p>'
                 + (m.formula ? '<p class="method-formula">' + esc(m.formula) + '</p>' : '')
                 + (m.basis ? '<p class="method-basis">' + esc(m.basis) + '</p>' : '')
+                // "assumes" is the biological context a number is only valid
+                // inside — for the indel columns, template-free end-joining
+                // repair. Rendered as its own line rather than folded into
+                // basis, because it changes whether the number applies at all.
+                + (m.assumes ? '<p class="method-assumes"><strong>Assumes:</strong> '
+                    + esc(m.assumes) + '</p>' : '')
                 + (m.limits ? '<p class="method-limits' + (isScopeWarning(m.limits) ? ' warn' : '')
                     + '">' + esc(m.limits) + '</p>' : '')
                 + ((m.citations && m.citations.length)
@@ -10189,11 +10741,26 @@ function runOracle(opts){
         body.innerHTML = html || '<p class="muted">Methods unavailable.</p>';
     }
 
+    // One in-flight fetch shared by the collapsed provenance block and the
+    // always-visible scope strip above the table. The strip needs
+    // genome_scopes (which organism is indexed over the COMPLETE genome and
+    // which over coding sequence only) and that answer has to come from the
+    // server's own registry — a scope list copied into JS is how a panel ends
+    // up promising a whole-genome screen the engine never ran.
+    let pending = null;
+    function ensure() {
+        if (!pending) {
+            pending = fetch('/api/crispr/methods')
+                .then((r) => r.json())
+                .catch((e) => { pending = null; throw e; });
+        }
+        return pending;
+    }
+
     function load() {
         if (loaded) return;
         loaded = true;
-        fetch('/api/crispr/methods')
-            .then((r) => r.json())
+        ensure()
             .then(render)
             .catch(() => {
                 const body = document.getElementById('crisprMethodsBody');
@@ -10204,7 +10771,7 @@ function runOracle(opts){
 
     const det = document.getElementById('crisprMethods');
     if (det) det.addEventListener('toggle', function () { if (det.open) load(); });
-    window.TDMethods = { load: load };
+    window.TDMethods = { load: load, ensure: ensure };
 })();
 
 // ═══════════════════════════════════════════════════════════════════════

dee/static/catalog.css

@@ -26,18 +26,37 @@
 }
 .rail-split[hidden] { display: none; }
 
+/* Visible AT REST, and this is the whole point of the control.
+
+   The first version started at opacity 0 and only appeared on hover. Measured
+   in the browser: `getComputedStyle(.rail-split-grip).opacity === "0"` with
+   the split open and the pointer elsewhere — so the boundary between the
+   conversation and the bench looked exactly like the fixed 1px border it used
+   to be, and nothing on screen said it could move. A handle you have to
+   already know about is not a handle.
+
+   So it shows: a short grip on the seam, in --line-bold — one step up from
+   the .cockpit border-right it sits on, present enough to read as a grab
+   point, quiet enough not to become a third vertical rule in the layout. It
+   grows and takes ink on hover, focus and drag, which is where the affordance
+   should be loud. */
 .rail-split-grip {
     width: 3px;
-    height: 46px;
+    height: 34px;
     border-radius: 3px;
-    background: var(--line-strong);
-    opacity: 0;
+    background: var(--line-bold);
+    opacity: 1;
     transition: opacity var(--t-fast, .12s) var(--ease, ease),
+                height var(--t-fast, .12s) var(--ease, ease),
                 background var(--t-fast, .12s) var(--ease, ease);
 }
 .rail-split:hover .rail-split-grip,
 .rail-split:focus-visible .rail-split-grip,
-body.is-railsplitting .rail-split-grip { opacity: 1; background: var(--ink-soft); }
+body.is-railsplitting .rail-split-grip {
+    height: 46px;
+    background: var(--ink-soft);
+}
+@media (prefers-reduced-motion: reduce) { .rail-split-grip { transition: none; } }
 
 .rail-split:focus-visible {
     outline: 2px solid var(--ink-strong);
@@ -207,8 +226,18 @@ body.cat-open { overflow: hidden; }
 .cat-thumb[data-sc="error"] .cat-thumb-msg::after { content: "Structure unavailable"; }
 .cat-thumb[data-sc="ok"] .cat-acc { display: block; }
 .cat-thumb[data-sc="none"] .cat-acc { display: none; }
-.cat-thumb--cx { color: var(--ink-faint); }
-.cat-thumb--cx svg { width: 26px; height: 26px; }
+/* A construct has no fold to show, so its tile carries a mark instead of a
+   picture. Dropping the border is the point: a 1px frame around a small glyph
+   on an empty ground is the shape of a broken image, and that is what it was
+   being read as. Without the frame it reads as an icon beside a title, which
+   is what it is. */
+.cat-thumb--cx {
+    color: var(--ink-faint);
+    border-color: transparent;
+    background: var(--bg-subtle);
+}
+.cat-thumb--cx svg { width: 34px; height: 34px; }
+.cat-card--cx:hover .cat-thumb--cx { color: var(--ink-soft); }
 
 /* ── body ───────────────────────────────────────────────────────────────── */
 .cat-main { grid-area: main; min-width: 0; display: flex; flex-direction: column; gap: 5px; }

dee/static/catalog.js

@@ -10,11 +10,14 @@
    conversations.
 
    This is that catalog. Both kinds of thing in one panel, searchable, with the
-   two verbs that were missing. And each conversation carries the fold of the
+   verbs that were missing. And each conversation carries the fold of the
    protein it is about, drawn from the run's own saved bench snapshot — because
    a scientist finds "the one about the beta-lactamase" by recognising it, not
    by reading ten near-identical sentences.
 
+   Constructs are deletable too, as far as the API allows — see CX_DELETE for
+   which kinds have a route and which are still a server-side gap.
+
    Depends on: TDStructCard (thumbnails), TDCockpit (switchRun/newRun),
    TDBench (openConstruct). Degrades if any is missing rather than throwing.
    =========================================================================== */
@@ -175,6 +178,30 @@
         primers: "Primers", plasmid: "Map",
     };
 
+    /* Where a construct of each kind can be deleted, and what it is called
+       while you are being asked to confirm it.
+
+       The reviewer asked for two things — "no catalog of conversations/chats
+       or way to delete 'constructs' and conversations". Conversations got both
+       verbs. Constructs got neither, and half of that is a server gap rather
+       than a UI one: plasmids and primer analyses have owner-checked DELETE
+       routes, saved LIBRARIES and CRISPR DESIGNS have none, in server.py or in
+       auth.py. A library is the primary artifact this product makes, so that
+       is the bigger half of the hole.
+
+       This table is the whole switch. A kind with no entry renders no Delete
+       button, because the alternative is a button that 404s — and a delete
+       control that silently does nothing is worse than an honest absence. Add
+       `DELETE /api/library/<id>` and `DELETE /api/crispr/designs/<id>` plus
+       their auth.py counterparts and the two commented lines below finish the
+       feature; nothing else here changes. */
+    var CX_DELETE = {
+        plasmid: { path: "/api/plasmid/library/", noun: "plasmid map" },
+        primer:  { path: "/api/primers/analyses/", noun: "primer analysis" },
+        // library: { path: "/api/library/",          noun: "variant library" },
+        // crispr:  { path: "/api/crispr/designs/",   noun: "CRISPR design" },
+    };
+
     function thumbHtml(r) {
         if (r.uniprot) {
             return '<span class="cat-thumb" data-sc-host data-sc="idle">' +
@@ -228,20 +255,58 @@
         "</article>";
     }
 
+    /* One mark per kind of artifact.
+
+       Every construct used to get the same glyph: two crossing curves meant as
+       a DNA helix, drawn without its rungs, at 26px inside a 104x84 bordered
+       tile. At that size against an empty frame it reads as a large X — the
+       browser's broken-image placeholder, which is exactly what a reviewer
+       took it for. Worse, it was the same X for a plasmid map, a primer set, a
+       CRISPR design and a variant library, so the tile cost 104px of card and
+       carried no information at all.
+
+       These are the four things this product makes, and each mark says which:
+       a ranked list, a circular map, a cut site, a converging pair. Stroke
+       glyphs on a 24-unit grid, so they stay legible at the tile's size and
+       inherit the card's ink. */
+    var CX_GLYPH = {
+        library: '<path d="M4 6h16M4 12h11M4 18h6"/>',
+        plasmid: '<circle cx="12" cy="12" r="8"/>' +
+                 '<path d="M12 4a8 8 0 0 1 6.93 4" stroke-width="2.4"/>',
+        crispr:  '<path d="M3 9h6M15 9h6M3 15h6M15 15h6"/>' +
+                 '<path d="M12 3v18" stroke-dasharray="2.5 2.5"/>',
+        primer:  '<path d="M3 12h18"/><path d="M6.5 8.2 10.5 12l-4 3.8"/>' +
+                 '<path d="M17.5 15.8 13.5 12l4-3.8"/>',
+    };
+    var CX_GLYPH_FALLBACK = '<path d="M5 5.5c7 3.5 5.5 12.5 12.5 16M5 19.5c7-3.5 5.5-12.5 12.5-16"/>' +
+                            '<path d="M7.6 8.4h8M8.6 15.6h8"/>';
+
     function constructCard(c, i) {
         var meta = [];
         if (c.kind) meta.push(String(c.kind));
         var w = when(c.at); if (w) meta.push(w);
-        return '<article class="cat-card cat-card--cx" data-i="' + i + '" data-cx="' + esc(c.id) + '">' +
+        var del = CX_DELETE[c.kind];
+        var busy = state.busy[c.id];
+        var glyph = CX_GLYPH[c.kind] || CX_GLYPH_FALLBACK;
+        return '<article class="cat-card cat-card--cx' + (busy ? " is-busy" : "") +
+                 '" data-i="' + i + '" data-cx="' + esc(c.id) + '" data-kind="' + esc(c.kind || "") + '">' +
             '<span class="cat-thumb cat-thumb--cx" data-sc="cx" aria-hidden="true">' +
-              '<svg viewBox="0 0 26 26" fill="none" stroke="currentColor" stroke-width="1.1">' +
-              '<path d="M6 4c8 4 6 14 14 18M6 22c8-4 6-14 14-18"/></svg></span>' +
+              '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" ' +
+                   'stroke-linecap="round" stroke-linejoin="round">' + glyph + "</svg></span>" +
             '<div class="cat-main">' +
               '<button type="button" class="cat-open" data-act="opencx" data-cx="' + esc(c.id) +
                       '" data-name="' + esc(c.name) + '">' +
                 '<span class="cat-name">' + esc(c.name) + "</span></button>" +
               '<div class="cat-meta">' + esc(meta.join(" · ")) + "</div>" +
-            "</div></article>";
+              (_notes[c.id] ? '<p class="cat-note" role="status">' + esc(_notes[c.id]) + "</p>" : "") +
+            "</div>" +
+            (del
+               ? '<div class="cat-acts">' +
+                   '<button type="button" class="cat-act is-danger" data-act="delcx" data-cx="' + esc(c.id) +
+                           '" aria-label="Delete this ' + esc(del.noun) + '" title="Delete">Delete</button>' +
+                 "</div>"
+               : "") +
+        "</article>";
     }
 
     /* ── render ─────────────────────────────────────────────────────────── */
@@ -307,7 +372,8 @@
             if (act === "open") { openRun(btn.getAttribute("data-run")); return; }
             if (act === "opencx") { openConstruct(btn); return; }
             if (act === "rename") { startRename(btn.getAttribute("data-run")); return; }
-            if (act === "delete") { confirmDelete(btn.getAttribute("data-run")); return; }
+            if (act === "delete") { confirmDeleteRun(btn.getAttribute("data-run")); return; }
+            if (act === "delcx") { confirmDeleteConstruct(btn.getAttribute("data-cx")); return; }
             return;
         }
         var seg = e.target.closest(".cat-segb");
@@ -328,16 +394,17 @@
         }
     }
 
-    function cardFor(runId) {
-        if (!state.root) return null;
-        // Run ids are minted as uuid4().hex, so an attribute-value scan is
-        // exact without needing CSS.escape (which older Safari lacks).
+    function cardBy(attr, id) {
+        if (!state.root || !id) return null;
+        // Ids are minted as uuid4().hex, so an attribute-value scan is exact
+        // without needing CSS.escape (which older Safari lacks).
         var all = state.root.querySelectorAll(".cat-card");
         for (var i = 0; i < all.length; i++) {
-            if (all[i].getAttribute("data-run") === runId) return all[i];
+            if (all[i].getAttribute(attr) === id) return all[i];
         }
         return null;
     }
+    function cardFor(runId) { return cardBy("data-run", runId); }
 
     /* Rename in place. A prompt() would be two fewer lines and would also be a
        modal inside a modal that cannot be styled, cannot be cancelled with
@@ -397,26 +464,79 @@
           });
     }
 
-    /* Two-step delete, inline. There is no undo behind this — the transcript
-       is the record — so the confirm names what is about to go. */
-    function confirmDelete(runId) {
-        var card = cardFor(runId);
-        var run = state.runs.filter(function (r) { return r.runId === runId; })[0];
-        if (!card || !run || card.querySelector(".cat-confirm")) return;
+    /* Two-step delete, inline. There is no undo behind any of these, so the
+       confirm names the thing that is about to go rather than asking "are you
+       sure?" about an unnamed row. */
+    function confirmDelete(card, message, onYes) {
+        if (!card || card.querySelector(".cat-confirm")) return;
         var bar = document.createElement("div");
         bar.className = "cat-confirm";
-        bar.innerHTML = '<span>Delete “' + esc(run.title || "Untitled run") +
-                        '”? Its transcript goes with it.</span>' +
+        bar.innerHTML = "<span>" + message + "</span>" +
                         '<button type="button" class="cat-act is-danger" data-yes>Delete</button>' +
                         '<button type="button" class="cat-act" data-no>Keep</button>';
         card.appendChild(bar);
         bar.querySelector("[data-no]").addEventListener("click", function () { bar.remove(); });
         bar.querySelector("[data-yes]").addEventListener("click", function () {
-            bar.remove(); doDelete(runId);
+            bar.remove(); onYes();
         });
         bar.querySelector("[data-yes]").focus();
     }
 
+    function confirmDeleteRun(runId) {
+        var run = state.runs.filter(function (r) { return r.runId === runId; })[0];
+        if (!run) return;
+        confirmDelete(cardFor(runId),
+            "Delete “" + esc(run.title || "Untitled run") +
+            "”? Its transcript goes with it.",
+            function () { doDelete(runId); });
+    }
+
+    /* Constructs are saved WORK — a plasmid map, a primer analysis — not a
+       conversation about it, so the confirm says which kind is going and does
+       not promise anything about the run that produced it. */
+    function confirmDeleteConstruct(cxId) {
+        var cx = state.constructs.filter(function (c) { return String(c.id) === String(cxId); })[0];
+        if (!cx) return;
+        var del = CX_DELETE[cx.kind];
+        if (!del) return;
+        confirmDelete(cardBy("data-cx", cxId),
+            "Delete the " + esc(del.noun) + " “" + esc(cx.name || "Untitled") +
+            "”? This removes the saved record.",
+            function () { doDeleteConstruct(cxId); });
+    }
+
+    function doDeleteConstruct(cxId) {
+        var cx = state.constructs.filter(function (c) { return String(c.id) === String(cxId); })[0];
+        var del = cx && CX_DELETE[cx.kind];
+        if (!del) return;
+        state.busy[cxId] = 1; paint();
+        fetch(del.path + encodeURIComponent(cxId), { method: "DELETE" })
+            .then(function (r) {
+                return r.json().catch(function () { return { ok: r.ok }; });
+            })
+            .then(function (d) {
+                delete state.busy[cxId];
+                if (d && d.ok) {
+                    state.constructs = state.constructs.filter(function (c) {
+                        return String(c.id) !== String(cxId);
+                    });
+                    // Mission Control lists the same constructs from the same
+                    // endpoint. Leaving it showing a card whose record is gone
+                    // is the silted-up-dropdown problem in a second place.
+                    try {
+                        if (window.TDMission && window.TDMission.reload) window.TDMission.reload();
+                    } catch (e) {}
+                } else {
+                    note(cxId, (d && d.error) || "Couldn't delete that.");
+                }
+                paint();
+            }).catch(function () {
+                delete state.busy[cxId];
+                note(cxId, "Couldn't reach the server.");
+                paint();
+            });
+    }
+
     function doDelete(runId) {
         state.busy[runId] = 1; paint();
         fetch("/api/orchestrator/runs/" + encodeURIComponent(runId), { method: "DELETE" })

dee/static/cockpit.js

@@ -45,6 +45,12 @@
         timer: null,
         els: null,
         toolNodes: {},      // tool_call id → its DOM block, so the result fills it in
+        /* tool_call id → the arguments the agent passed. The RESULT event
+           carries what came back and nothing about what was asked for, so
+           without this the design panel cannot say "you asked for 30, 10 were
+           scored" — which is exactly the sentence a reviewer went looking for
+           and could not find. */
+        toolArgs: {},
         mounted: false,
         stick: true,        // follow the tail? false once the user scrolls up
         queue: [],          // messages typed while the agent was working
@@ -383,10 +389,23 @@
             /* Cost and context are already computed server-side and returned
                on every response — they were simply never shown. For someone
                deciding whether to pay, "what did that cost and how full is
-               the context" is the question. */
+               the context" is the question.
+
+               It shipped as the bare string "context 0% · $0.11", which a
+               reviewing scientist read as noise, and fairly: neither number
+               named what it measured, and a sub-1% context reading rendered
+               as a flat "0%" that looked broken. Both are kept — hiding cost
+               from someone deciding whether to keep going is worse than
+               showing it — but named, given their denominator, and given the
+               decision trace as somewhere to read what they mean in full
+               sentences. The row doubles as the trace's entry point, which is
+               why it now shows whenever there is a run rather than only once
+               a cost has accrued. */
             '<div class="cp-meter" id="cpMeter" hidden>' +
               '<span class="cp-meter-bar"><span class="cp-meter-fill" id="cpMeterFill"></span></span>' +
               '<span class="cp-meter-t" id="cpMeterText"></span>' +
+              '<button type="button" class="cp-trace-btn" id="cpTrace" hidden ' +
+                      'aria-label="Open the decision trace — every step of this run">Trace</button>' +
             '</div>' +
             '<div class="cp-transcript" id="cpTranscript" role="log" aria-live="polite"></div>' +
             '<button type="button" class="cp-jump" id="cpJump" hidden>&darr; Jump to latest</button>' +
@@ -412,8 +431,14 @@
             meter: root.querySelector("#cpMeter"),
             meterFill: root.querySelector("#cpMeterFill"),
             meterText: root.querySelector("#cpMeterText"),
+            traceBtn: root.querySelector("#cpTrace"),
         };
 
+        state.els.traceBtn.addEventListener("click", function () {
+            closeMenu();
+            if (window.TDTrace) window.TDTrace.toggle();
+        });
+
         state.els.newBtn.addEventListener("click", function () {
             closeMenu();
             newRun();
@@ -621,9 +646,78 @@
         }, 1400);
     }
 
+    /* The same error, three times in a row, is ONE problem — not three.
+       The 2026-07-30 reviewer log has a stack of identical red blocks on a
+       single request; every copy after the first adds alarm and no
+       information. Consecutive duplicates collapse into one block with a
+       repeat count, so nothing is hidden and nothing is shouted twice.
+
+       Only CONSECUTIVE ones: two identical errors with real work between them
+       are two events in the record, and merging those would lose the fact
+       that it happened again later. */
+    var _lastErr = null;      // { text, node, n }
     function addError(text) {
-        addNode("cp-err",
-            '<span class="cp-err-i" aria-hidden="true">!</span><div>' + esc(text) + "</div>");
+        var msg = String(text || "");
+        var tail = state.els && state.els.transcript.lastElementChild;
+        if (_lastErr && _lastErr.node === tail && _lastErr.text === msg) {
+            _lastErr.n += 1;
+            /* A data-attribute hook, not a class: dee/static/app.css is owned
+               elsewhere, and inventing a class name there would be a silent
+               no-op (see docs/ENGINEERING.md §13.7). */
+            var c = _lastErr.node.querySelector("[data-cp-err-n]");
+            if (c) c.textContent = " ×" + _lastErr.n;
+            scrollDown();
+            return _lastErr.node;
+        }
+        var node = addNode("cp-err",
+            '<span class="cp-err-i" aria-hidden="true">!</span><div>' + esc(msg) +
+            "<span data-cp-err-n></span></div>");
+        _lastErr = { text: msg, node: node, n: 1 };
+        return node;
+    }
+
+    /* An attempt that was RETRIED and then worked is not a failure — it is
+       the agent recovering, which is the behaviour we want it to have.
+
+       Reviewer, 2026-07-30: three red "couldn't find the gene" blocks on a
+       request that went on to produce a correct answer (286 aa → 861 bp, the
+       reviewer checked it). The run was fine; the transcript read like it had
+       broken three times. Rendering a superseded attempt at full error weight
+       makes a working recovery look like a failing product.
+
+       So when a tool SUCCEEDS, earlier failed attempts at the SAME tool are
+       demoted in place: the red border and red text come off, the cross
+       becomes a neutral retry mark, and the line says plainly that the
+       attempt returned nothing and was retried. Nothing is deleted, nothing
+       is recoloured green, and the original error stays on the node's title —
+       the transcript export reads the event log, not the DOM, so the full
+       record is untouched either way. */
+    function demoteSupersededAttempts(name) {
+        if (!name || !state.els) return 0;
+        var nodes = state.els.transcript.querySelectorAll(
+            '[data-cp-tool="' + name + '"][data-cp-state="fail"]');
+        for (var i = 0; i < nodes.length; i++) {
+            var n = nodes[i];
+            n.setAttribute("data-cp-state", "superseded");
+            n.classList.remove("cp-tool--fail");
+            var cross = n.querySelector(".cp-cross");
+            if (cross) {
+                /* No class: .cp-cross is red by definition and .cp-tick is
+                   green, and neither is honest here. An unclassed span
+                   inherits the row's own mono font and ink. The inline
+                   flex-basis replaces the one .cp-cross was providing —
+                   deliberately inline rather than a new rule, since the
+                   stylesheet is another workstream's file. */
+                cross.outerHTML =
+                    '<span aria-hidden="true" style="flex:0 0 auto">↻</span>';
+            }
+            var sum = n.querySelector(".cp-tool-sum");
+            if (sum) {
+                if (!n.getAttribute("title")) n.setAttribute("title", sum.textContent);
+                sum.textContent = "no result — retried";
+            }
+        }
+        return nodes.length;
     }
 
     /* A tool in flight. Returns the node so the matching result can fill it
@@ -671,6 +765,12 @@
         if (!node) node = addToolCall({ verb: ev.name, name: ev.name, replay: true });
         node.classList.remove("cp-tool--running");
         node.classList.add(ev.ok ? "cp-tool--ok" : "cp-tool--fail");
+        // Tagged so a later success at the same tool can find it. Attributes
+        // rather than an in-memory index, because a reload replays the whole
+        // transcript from the event log and any index would be empty.
+        node.setAttribute("data-cp-tool", String(ev.name || ""));
+        node.setAttribute("data-cp-state", ev.ok ? "ok" : "fail");
+        if (ev.ok) demoteSupersededAttempts(ev.name);
 
         // Freeze the clock at the real duration — how long a step took is
         // part of the record, not just reassurance while it runs.
@@ -870,9 +970,12 @@
     };
     function _viewFor(name) { return TOOL_VIEW[name] || null; }
 
+    /* Second argument is the tool_call's own args (state.toolArgs). Painters
+       that don't need it simply ignore it, so this stays additive — only the
+       design panel currently reads it, to state requested-vs-scored. */
     var PAINTERS = {
-        design_variant_library: function (panel) {
-            return !!(window.TDDesign && window.TDDesign.paintAgentRun(panel));
+        design_variant_library: function (panel, args) {
+            return !!(window.TDDesign && window.TDDesign.paintAgentRun(panel, args));
         },
         design_crispr_guides: function (panel) {
             return !!(window.TDCrispr && window.TDCrispr.paintAgentRun(panel));
@@ -915,7 +1018,8 @@
                     alphafold_page: p.alphafold_page || "",
                 });
                 if (live) gotoView(ui.view);
-            } else if (PAINTERS[ev.name] && ui.panel && PAINTERS[ev.name](ui.panel)) {
+            } else if (PAINTERS[ev.name] && ui.panel &&
+                       PAINTERS[ev.name](ui.panel, (ev.id && state.toolArgs[ev.id]) || {})) {
                 if (live) gotoView(ui.view);
             }
             // After gotoView: opening the bench stamps the goal sentence as the
@@ -1232,6 +1336,14 @@
         // Keep every event, in order, for the export. This is the only
         // complete record the client has of what actually happened.
         state.transcript.push(ev);
+        /* Same events, second consumer. The rail renders them as a river that
+           scrolls away; the trace holds them still and numbered. Fed here, at
+           the single point every event passes through, so a replay after
+           reload rebuilds the trace exactly as it rebuilds the transcript —
+           and so no future event kind can reach one surface but not the
+           other. TDTrace.push swallows its own errors; a trace row must never
+           be able to kill a run. */
+        if (window.TDTrace) window.TDTrace.push(ev);
         switch (ev.kind) {
             case "user":
                 // Live, we already echoed this locally for immediacy. On a
@@ -1246,6 +1358,7 @@
                 break;
             case "text":        stopThinking(); addText(ev.text, ev.replay); break;
             case "tool_call":
+                if (ev.id) state.toolArgs[ev.id] = ev.args || {};
                 stopThinking(); addToolCall(ev);
                 // Show it on the CANVAS too, not only in the rail — and move
                 // to where the output will land before it arrives.
@@ -1333,6 +1446,12 @@
                 if (typeof d.cost_usd === "number") state.cost = d.cost_usd;
                 if (typeof d.context_tokens_used === "number") state.ctxUsed = d.context_tokens_used;
                 if (typeof d.context_tokens_limit === "number") state.ctxLimit = d.context_tokens_limit;
+                if (window.TDTrace) {
+                    window.TDTrace.setMeta({
+                        cost: state.cost, ctxUsed: state.ctxUsed,
+                        ctxLimit: state.ctxLimit, status: d.status,
+                    });
+                }
                 renderMeter();
                 setStatus(d.status);
                 // A settled run can't be timing anything; leaving intervals
@@ -1649,12 +1768,17 @@
     function reset() {
         clearTimers();
         stopThinking();
-        state.runId = null; state.lastSeq = 0; state.toolNodes = {}; _title = "";
+        state.runId = null; state.lastSeq = 0; state.toolNodes = {}; state.toolArgs = {};
+        _title = "";
         state.pendingEcho = []; state.ready = []; state.ident = {};
         _planNode = null;   // a new run gets a fresh checklist, not the old one
         state.digest = {}; state.transcript = [];
         state.cost = 0; state.ctxUsed = 0; state.ctxLimit = 0;
         _noted = false; _phase = 0; _seq = "";
+        // The trace is per-run. Carrying the previous run's steps into a new
+        // one would be the same mistake the plan node used to make — a stale
+        // record presented as the current one.
+        if (window.TDTrace) { window.TDTrace.reset(); window.TDTrace.close(); }
         saveRun();
         setStatus("idle");
         renderMeter();
@@ -1926,22 +2050,57 @@
         }, 0);
     }
 
-    /* ── cost + context meter ────────────────────────────────────────── */
+    /* ── the run strip: context, cost, and the way into the trace ────────
+       Was "context 0% · $0.11" — two numbers, no nouns, no denominators. */
+    function fmtTokens(n) {
+        n = Number(n) || 0;
+        if (n >= 1000000) return (n / 1000000).toFixed(n % 1000000 === 0 ? 0 : 1) + "M";
+        if (n >= 1000) return Math.round(n / 1000) + "k";
+        return String(n);
+    }
+
     function renderMeter() {
         if (!state.els) return;
-        if (!state.ctxLimit && !state.cost) { state.els.meter.hidden = true; return; }
+        var steps = window.TDTrace ? window.TDTrace.count() : 0;
+        // The strip now also carries the trace button, so it appears as soon
+        // as the run has done anything — not only once a cost has accrued.
+        if (!state.ctxLimit && !state.cost && !steps) {
+            state.els.meter.hidden = true;
+            return;
+        }
         var pct = state.ctxLimit
-            ? Math.min(100, Math.round((state.ctxUsed / state.ctxLimit) * 100)) : 0;
+            ? Math.min(100, (state.ctxUsed / state.ctxLimit) * 100) : 0;
         state.els.meter.hidden = false;
         state.els.meterFill.style.width = pct + "%";
         state.els.meter.classList.toggle("cp-meter--warn", pct >= 80);
+
         var bits = [];
-        if (state.ctxLimit) bits.push("context " + pct + "%");
+        if (state.ctxLimit) {
+            // "0%" on a 1M window is the common case and reads as broken or
+            // as a placeholder, so the token counts carry the magnitude here.
+            // The percentage is added back only once it's the point — the bar
+            // shows the fraction the rest of the time, the trace states it
+            // exactly, and at 390px (the rail's real width) the extra "(4%)"
+            // is what pushes "model cost" onto a second line.
+            bits.push("Context " + fmtTokens(state.ctxUsed) + " / " +
+                      fmtTokens(state.ctxLimit) +
+                      (pct >= 50 ? " (" + Math.round(pct) + "%)" : ""));
+        }
         // Sub-cent runs are the norm; "$0.00" reads as broken, so show the
         // real figure at the precision it actually has.
         if (state.cost) bits.push("$" + (state.cost < 0.01
-            ? state.cost.toFixed(4) : state.cost.toFixed(2)));
+            ? state.cost.toFixed(4) : state.cost.toFixed(2)) + " model cost");
         state.els.meterText.textContent = bits.join(" · ");
+        // The full sentences live in the trace, but a hover here costs
+        // nothing and helps the reader who never opens it.
+        state.els.meter.title =
+            "Context — how much of the model's " + Number(state.ctxLimit || 0).toLocaleString() +
+            "-token window this conversation occupies; when it fills, earlier steps are " +
+            "condensed rather than dropped. Model cost — USD spent on model calls in this run " +
+            "so far. Open the decision trace for the full step-by-step record.";
+
+        state.els.traceBtn.hidden = !steps;
+        state.els.traceBtn.textContent = "Trace · " + steps;
     }
 
     /* ── elapsed timers ──────────────────────────────────────────────────

dee/static/index.html

@@ -112,11 +112,21 @@
     <!-- ?v= query bumps invalidate browser + iframe asset caches when app.css /
          app.js change. Bump these numbers whenever you ship a frontend update —
          without them, users keep getting the stale file for up to a week. -->
-    <link rel="stylesheet" href="/static/app.css?v=20260731-structpanel" />
+    <link rel="stylesheet" href="/static/app.css?v=20260801-review" />
     <!-- The work catalog + the draggable rail. Kept out of app.css so two new
          self-contained surfaces stay reviewable; every colour is an app.css
          token, so both themes work with nothing added. -->
-    <link rel="stylesheet" href="/static/catalog.css?v=20260801-catalog" />
+    <link rel="stylesheet" href="/static/catalog.css?v=20260801-review" />
+    <!-- Units, the run strip and the decision trace. Same reasoning as
+         catalog.css: kept out of app.css so a self-contained surface stays
+         reviewable, and every colour is an app.css token so both themes
+         work with nothing added. -->
+    <link rel="stylesheet" href="/static/trace.css?v=20260801-review" />
+    <!-- Disclosure surfaces added in the 2026-08 scientific review (CRISPR
+         scope strip, provenance "Assumes" line). Separate file for the same
+         reason as catalog.css: small, self-contained, and app.css's cascade
+         is hostile. Uses app.css tokens only, so both themes work. -->
+    <link rel="stylesheet" href="/static/science.css?v=20260801-review" />
     <link rel="icon" type="image/svg+xml" href="/static/favicon.svg?v=2" />
     <link rel="apple-touch-icon" href="/static/favicon.svg?v=2" />
     <!-- Mol* (PDBe) 3-D viewer is ~4.9 MB. We do NOT eager-load it on every
@@ -746,6 +756,19 @@
                             <span class="setting-name">Variants to generate</span>
                             <span class="setting-hint">Top-K multi-mutants returned in the library.</span>
                             <input type="number" id="settingK" value="30" min="5" max="500" step="5" />
+                            <!-- The cap disclosed WHERE THE NUMBER IS TYPED. A
+                                 reviewer set 30 here, asked Turing for a library
+                                 and got 10 rows; the only notice was one clause
+                                 in a banner in a different section of the page.
+                                 The numbers are the real ones from
+                                 dee/core/agent_tools.py (k clamped to 1–20,
+                                 default 10) and tests/test_chat_library_cap.py
+                                 fails if this text and that clamp drift apart. -->
+                            <p class="setting-note">This box drives the <strong>Directed Evolution</strong> run
+                                below, which honours it up to 500. A library designed <strong>in conversation
+                                with Turing</strong> does not read this box: that path runs inside a single
+                                reply rather than as a background job, so it returns <strong>10 variants by
+                                default and at most 20</strong>.</p>
                         </label>
 
                         <label class="setting">
@@ -892,6 +915,12 @@
                          real spread) — see _renderLearnedPanel in app.js. -->
                     <section class="learned-panel" id="learnedPanel" hidden>
                         <p class="card-kicker">&sect; What Turing learned</p>
+                        <!-- These are SINGLE-substitution scores (dee/server.py
+                             _de_round2_library reads m.delta_ll per mutation),
+                             so the unit is ΔLL — not the table's summed ΣΔLL.
+                             Labelling them the same would imply the two columns
+                             are on one scale, and they are not. -->
+                        <p class="unit-legend unit-legend--tight">Per-substitution score, <strong>&Delta;LL</strong> &mdash; ESM-2&rsquo;s prior for that one mutation, before &rarr; after your measured results were folded in. Not the same scale as the table&rsquo;s summed &Sigma;&Delta;LL.</p>
                         <div class="learned-list" id="learnedList"></div>
                     </section>
                     <!-- Predicted-vs-measured calibration — client-side only, built
@@ -903,16 +932,30 @@
                         <div class="calib-body" id="calibBody"></div>
                     </section>
 
-                    <!-- Mutation map (lollipop chart). Was carrying a chip-
-                         legend (Low / Med / High dots) that read as
-                         dashboard scaffolding; legend text is now inline
-                         in the description. -->
+                    <!-- Mutation map (lollipop chart).
+
+                         The chip legend that used to sit here (Low / Med /
+                         High dots) was deleted as dashboard scaffolding and
+                         its explanation moved into the description below —
+                         which then described a three-step colour ramp that
+                         encoded a signed, continuous quantity. #mutmapKey is
+                         the replacement, and it is built by renderMutationKey()
+                         from the same colour function the dots use, so the
+                         key and the chart cannot disagree. -->
                     <div class="mutmap-card" id="mutmapCard">
                         <div class="mutmap-head">
                             <h3>Mutation landscape</h3>
-                            <p class="muted">Where mutations land across the protein. Bar height counts variants sharing a position; color encodes ΔLL strength (faint &middot; medium &middot; saturated).</p>
+                            <!-- Colour is the MEAN attributed ΔLL, signed —
+                                 not the sum. The sum grew with the variant
+                                 count that bar height already encodes, so the
+                                 two channels said the same thing twice and
+                                 neither said the direction. The full key,
+                                 with units and domain, is rendered into
+                                 #mutmapKey below. -->
+                            <p class="muted">Where mutations land across the protein. <strong>x</strong> = residue position (1&ndash;<span id="mutmapLen">N</span>) &middot; <strong>bar height</strong> = variants sharing that position &middot; <strong>colour</strong> = the mean &Delta;LL there, signed, in ESM-2 log-likelihood units. Full scale and domain in the key below.</p>
                         </div>
                         <div class="mutmap-canvas" id="mutmapCanvas"></div>
+                        <div class="mutmap-key" id="mutmapKey"></div>
                     </div>
 
                     <!-- ================= INTERACTION RADAR (Pillar 1) =================
@@ -936,6 +979,24 @@
                         <p class="radar-foot muted" id="radarFoot" hidden></p>
                     </section>
 
+                    <!-- The Fitness column's unit, stated where the column is,
+                         not only in a hover title and not only inside the
+                         collapsed "How to read this" block above. A reviewing
+                         scientist asked "what does a fitness score of 1.0
+                         represent? 2/3 is over and 1/3 is under, but none are
+                         negative" — all three parts of that are answered here:
+                         the unit, the absence of a fixed zero, and why a
+                         top-ranked slice is not expected to contain negatives.
+                         Styling lives in trace.css (app.css is off-limits to
+                         this change set). -->
+                    <p class="unit-legend" id="fitnessLegend">
+                        <strong>Fitness = &Sigma;&Delta;LL</strong> &mdash; the ESM-2 log-likelihood
+                        change vs.&nbsp;wild type, <em>summed</em> over this variant&rsquo;s substitutions.
+                        Unnormalised: no fixed zero and no maximum, and because the table shows the
+                        top-ranked slice of the search, negatives rarely survive into it.
+                        Ranks variants <em>within this library</em> &mdash; not across proteins or runs.
+                    </p>
+
                     <!-- Filter bar — instant client-side filter over the rendered table. -->
                     <div class="table-toolbar">
                         <div class="filter-input-wrap">
@@ -954,7 +1015,10 @@
                                 <tr>
                                     <th class="sortable" data-sort="rank" title="Rank by predicted fitness (1 = best).">Rank <span class="sort-ind">↕</span></th>
                                     <th class="sortable" data-sort="mutations" title="Substitutions vs. the wild-type protein, in the format WT_aa-position-new_aa.">Mutations <span class="sort-ind">↕</span></th>
-                                    <th class="num sortable" data-sort="fitness" title="Cumulative ΣΔLL from ESM-2: sum of log-likelihood improvements over WT across all substitutions in this variant.">Fitness <span class="sort-ind">↕</span></th>
+                                    <!-- The unit rides in the header itself. It was title-only
+                                         since May 2026, which means it did not exist for anyone
+                                         who didn't hover the right 60px of the page. -->
+                                    <th class="num sortable" data-sort="fitness" title="Cumulative ΣΔLL from ESM-2: sum of log-likelihood improvements over WT across all substitutions in this variant.">Fitness <span class="th-unit">ΣΔLL</span> <span class="sort-ind">↕</span></th>
                                     <th class="num sortable" data-sort="gc" title="GC content of the codon-optimized DNA. PCR-friendly range: 40–60%.">GC % <span class="sort-ind">↕</span></th>
                                     <th class="num sortable" data-sort="tm" title="Cooler of the two PCR primer Tm values (nearest-neighbor, standard salt). Annealing = Tm − 5°C for Q5/Phusion.">Tm (°C) <span class="sort-ind">↕</span></th>
                                     <th class="num sortable" data-sort="bp" title="Amplicon length in base pairs. Same for every variant in this library (length-preserving substitutions only).">bp <span class="sort-ind">↕</span></th>
@@ -1306,9 +1370,16 @@
                                       <th>Spacer</th>
                                       <th>PAM</th>
                                       <!-- Composite is the ranking column —
-                                           on-target × (1 − CFD-penalty).
+                                           on-target × (1 − 0.6 × self-off CFD).
+                                           The 0.6 is the engine's only tuning
+                                           constant and a judgement call, so it
+                                           is spelled out here, in the scope
+                                           strip, per guide in the why-panel, and
+                                           in the methods paragraph — a weight
+                                           that decides the sort order has to be
+                                           readable without asking us.
                                            Always the primary sort. -->
-                                      <th class="num crispr-sortable" data-sort-key="composite_score" title="On-target × (1 − CFD off-target penalty). Click to sort.">Composite</th>
+                                      <th class="num crispr-sortable" data-sort-key="composite_score" title="on-target × (1 − 0.6 × self-off CFD). The 0.6 off-target weight is our uncalibrated judgement call, not a published constant — expand a row to see the arithmetic for that guide. Click to sort.">Composite</th>
                                       <th class="num crispr-sortable" data-sort-key="on_target_score" title="TuringDNA on-target activity score (Doench-inspired sequence-only features). 1.0 = expected strong cut. Click to sort.">On-target</th>
                                       <!-- CFD-against-input is the Phase 1
                                            differentiator. 0.00 = no other
@@ -1324,17 +1395,17 @@
                                            e.g. "-3 ATG (28%)" or "+1 T (32%)". The
                                            dominant outcome usually accounts for 15-40%
                                            of all repair events. -->
-                                      <th class="col-ko" title="Single most-likely repair outcome (inDelphi-inspired). The number is the predicted frequency of THIS outcome among all repair events.">Top indel</th>
+                                      <th class="col-ko" title="Single most-likely repair outcome (inDelphi-inspired). The number is the predicted frequency of THIS outcome among all repair events. Assumes template-free end-joining repair and is NOT conditioned on your cell type.">Top indel</th>
                                       <!-- Phase 2A: % of predicted repair outcomes that
                                            introduce a frameshift. Higher = more likely
                                            to produce a true loss-of-function allele. -->
-                                      <th class="num col-ko crispr-sortable" data-sort-key="frameshift_pct" title="% of predicted repair outcomes that introduce a frameshift (non-multiple-of-3 indel). Higher = stronger KO likelihood. Click to sort.">FS %</th>
+                                      <th class="num col-ko crispr-sortable" data-sort-key="frameshift_pct" title="% of predicted repair outcomes that introduce a frameshift (non-multiple-of-3 indel). Higher = stronger KO likelihood. Assumes template-free end-joining (MMEJ + NHEJ) with fixed constants and NO cell-type conditioning — rank guides with it, don't quote it as a rate for your line. Click to sort.">FS %</th>
                                       <!-- Phase 2A: dominance of the SINGLE most-likely
                                            outcome, as a percent. Direct biological
                                            readout — "will I get one main edit product
                                            or many?" 40%+ = clean, 25-40% = typical,
                                            <25% = messy heterogeneous repair. -->
-                                      <th class="num col-ko crispr-sortable" data-sort-key="top_dominance_pct" title="Frequency of the single most-likely repair outcome. 40%+ = clean; <25% = messy. Click to sort.">Dominance</th>
+                                      <th class="num col-ko crispr-sortable" data-sort-key="top_dominance_pct" title="Frequency of the single most-likely repair outcome. 40%+ = clean; <25% = messy. Same end-joining assumptions as FS % — no cell-type conditioning. Click to sort.">Dominance</th>
                                       <!-- Phase 2A: does the spacer's editing window
                                            (positions 4-8) hold a C or A? If yes, this
                                            guide could ALSO be used for a point edit
@@ -1346,12 +1417,16 @@
                                       <th class="num col-be crispr-sortable" data-sort-key="be_editability" title="Strongest in-window editing activity for a target base (0–1). Higher = more likely. Click to sort.">Editability</th>
                                       <th class="col-be" title="Amino-acid consequence of the edit when a reading frame is known (gene symbol given, or pasted sequence is a coding sequence). '* (stop gained)' = a DSB-free knockout via CRISPR-STOP.">AA change</th>
                                       <th class="col-be" title="A clean edit changes a single base in the window; a bystander edit hits more than one. 'STOP' marks guides that install a premature stop codon (knockout by base editing).">Outcome</th>
-                                      <!-- Phase 2B-1: scored against the full chosen
-                                           organism's genome (currently E. coli only on
-                                           the free tier). Empty when no organism is
+                                      <!-- Phase 2B-1: scored against the chosen organism's
+                                           indexed genome. Empty when no organism is
                                            picked; "unique" when the organism was
-                                           searched and no real off-targets found. -->
-                                      <th class="num" title="Worst CFD score against any site in the chosen organism's genome. 'unique' = clean (no real off-targets); 0.5+ = strong off-target that may cleave (look at the tooltip for location).">Genome off</th>
+                                           searched and no real off-targets found.
+                                           COVERAGE IS NOT UNIFORM: E. coli, yeast, worm
+                                           and fly are indexed complete; human and mouse
+                                           are CODING SEQUENCE ONLY. The scope strip above
+                                           the table states which applied to this run,
+                                           sourced from offtarget.GENOME_SOURCES. -->
+                                      <th class="num" title="Worst CFD score against any site in the chosen organism's INDEXED genome. 'unique' = no off-target found above threshold; 0.5+ = strong off-target that may cleave (tooltip gives the location). Coverage varies by organism — human and mouse are coding sequence only, and only the top-ranked guides are screened. See the scope note above the table.">Genome off</th>
                                       <!-- Phase 2B-1: only populated when the user
                                            gave a gene symbol AND the input could be
                                            aligned to the gene's CDS. Shows exon
@@ -2393,16 +2468,21 @@
     <!-- Cloning reference data must load before app.js so the Designer
          can read VECTORS / ENZYMES / CLONING_METHODS / TAGS / LINKERS. -->
     <script src="/static/cloning_db.js?v=20260530-ui-polish" defer></script>
-    <script src="/static/app.js?v=20260731-structpanel" defer></script>
+    <script src="/static/app.js?v=20260801-review" defer></script>
+    <!-- The decision trace, BEFORE cockpit.js: applyEvent calls TDTrace.push
+         on the very first event, and both are `defer`, so document order is
+         load order. Loading it after would drop the opening events of a
+         restored run on the floor — silently, since the push is guarded. -->
+    <script src="/static/trace.js?v=20260801-review" defer></script>
     <!-- THE COCKPIT — the persistent orchestrator rail. Loads after app.js so
          TDBench/TDStructure exist when a tool result asks the workspace to
          render something. This is the only conversation surface in the app. -->
-    <script src="/static/cockpit.js?v=20260730-editor10" defer></script>
+    <script src="/static/cockpit.js?v=20260801-review" defer></script>
     <!-- structcard before catalog: the catalog calls TDStructCard.observe as
          soon as it paints. Both are defer, so document order is load order. -->
-    <script src="/static/structcard.js?v=20260801-catalog" defer></script>
-    <script src="/static/catalog.js?v=20260801-catalog" defer></script>
-    <script src="/static/railsplit.js?v=20260801-catalog" defer></script>
+    <script src="/static/structcard.js?v=20260801-review" defer></script>
+    <script src="/static/catalog.js?v=20260801-review" defer></script>
+    <script src="/static/railsplit.js?v=20260801-review" defer></script>
     <!-- Dwell-time heartbeat. Loads after auth.js so its /api/ping calls go
          through the JWT-attaching fetch wrapper (signed-in attribution). -->
     <script src="/static/telemetry.js?v=20260622-analytics" defer></script>

dee/static/railsplit.js

@@ -35,8 +35,17 @@
         return Math.max(MIN_W, Math.min(maxW(), Math.round(w)));
     }
 
+    /* Three conditions, and the third was missing on the first cut.
+
+       Collapsing the rail (the ▾ in the cockpit header, toggleMin) narrows
+       .cockpit to 236px on desktop but leaves --bench-rail at whatever the
+       user dragged it to, because the collapsed bar is not the split any
+       more. The handle went on tracking --bench-rail, so it sat ~150px out
+       in the canvas, over the workspace, offering to resize an edge that was
+       no longer there. A boundary marker has to be on the boundary or gone. */
     function splitActive() {
         return document.body.getAttribute("data-bench") === "open" &&
+               document.body.getAttribute("data-cockpit") !== "min" &&
                window.innerWidth >= SPLIT_MIN_VIEWPORT;
     }
 
@@ -89,6 +98,9 @@
         handle.setAttribute("aria-label", "Resize the conversation panel");
         handle.setAttribute("aria-valuemin", String(MIN_W));
         handle.setAttribute("tabindex", "0");
+        // Says what it does on hover. The grip is visible now (catalog.css),
+        // but "this line is draggable" still has to be stated once.
+        handle.title = "Drag to resize the conversation · double-click to reset";
         handle.innerHTML = '<span class="rail-split-grip" aria-hidden="true"></span>';
 
         handle.addEventListener("pointerdown", onDown);
@@ -163,20 +175,30 @@
         window.addEventListener("pointermove", onMove);
         window.addEventListener("pointerup", onUp);
         window.addEventListener("pointercancel", onUp);
+
+        /* The resize handler used to branch: sync() when the split had gone
+           away, a cheap re-clamp when it was still there. The branch was the
+           bug. Narrowing the window past 900px hid the handle and handed
+           --bench-rail back to the mobile rules (correct); widening it again
+           took the OTHER branch, which never un-hid anything. Measured: drag
+           the rail to 553px, narrow to 800, widen back to 1440 — handle
+           `hidden`, rail back at the 392px default, and no way to get either
+           back short of a reload.
+
+           sync() already does the whole job and is idempotent, so just call
+           it. The only state it must not stamp on is a drag in flight. */
         window.addEventListener("resize", function () {
-            if (!splitActive()) { sync(); return; }
-            // A narrower window can invalidate a stored width.
-            var cur = parseInt(getComputedStyle(document.documentElement)
-                               .getPropertyValue("--bench-rail"), 10) || DEFAULT_W;
-            handle.setAttribute("aria-valuemax", String(maxW()));
-            if (cur !== clamp(cur)) apply(clamp(cur), false);
+            if (dragging) return;
+            sync();
         });
 
-        // Bench opens and closes by flipping data-bench on <body>, with no
-        // event to listen for — so watch the attribute itself.
+        /* The bench opens/closes and the rail collapses/expands by flipping
+           attributes on <body>, with no event to listen for — so watch the
+           attributes themselves. data-cockpit matters as much as data-bench:
+           see splitActive(). */
         if ("MutationObserver" in window) {
             new MutationObserver(sync).observe(document.body, {
-                attributes: true, attributeFilter: ["data-bench"],
+                attributes: true, attributeFilter: ["data-bench", "data-cockpit"],
             });
         }
     }

dee/static/science.css

@@ -0,0 +1,102 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   science.css — disclosure surfaces added for the 2026-08 scientific
+   review. Kept out of app.css deliberately: this is a small, self-contained
+   layer, and app.css is ~8,000 lines with a hostile cascade (see
+   docs/ENGINEERING.md §13).
+
+   TOKENS: only variables that already exist are used — here --line, --ink
+   and --ink-soft. Inventing a token name silently computes the whole
+   shorthand to nothing (§13.1), so grep app.css before adding one.
+   ═══════════════════════════════════════════════════════════════════════ */
+
+/* ─── CRISPR scope strip ───────────────────────────────────────────────
+   The three things the results panel used to leave the reader to infer:
+   the composite's weight, what repair context the indel columns assume,
+   and how much of the genome was actually searched. Sits directly above
+   the table, always visible — not a collapsed <details>, because the whole
+   failure being fixed is that these facts were one click away and nobody
+   clicked. Quiet by default so it informs without shouting over the data. */
+.crispr-scope-strip {
+    margin: 10px 0 12px;
+    padding: 10px 12px;
+    border: 1px solid var(--line);
+    border-left-width: 3px;
+    border-radius: 6px;
+    font-size: 0.82rem;
+    line-height: 1.5;
+    color: var(--ink-soft);
+    display: grid;
+    gap: 6px;
+}
+
+.crispr-scope-strip:empty { display: none; }
+
+.crispr-scope-row {
+    display: grid;
+    grid-template-columns: 8.6rem 1fr;
+    gap: 10px;
+    align-items: baseline;
+}
+
+.crispr-scope-k {
+    font-weight: 600;
+    color: var(--ink);
+    letter-spacing: 0.01em;
+    text-transform: uppercase;
+    font-size: 0.68rem;
+    padding-top: 0.12rem;
+}
+
+.crispr-scope-v strong { color: var(--ink); font-weight: 600; }
+.crispr-scope-v em { font-style: italic; }
+
+/* Stack on narrow screens — a 8.6rem label column plus prose does not fit
+   a phone, and the label is short enough to read as a heading. */
+@media (max-width: 640px) {
+    .crispr-scope-row { grid-template-columns: 1fr; gap: 2px; }
+}
+
+/* ─── Provenance block: the "Assumes" line ─────────────────────────────
+   Rendered by TDMethods from METHODS[*].assumes. Distinct from .basis
+   (how the number was made) because it states the biological context the
+   number is only valid inside — the difference between "here's the
+   method" and "here's when it doesn't apply". */
+.method-assumes {
+    margin: 4px 0 0;
+    color: var(--ink-soft);
+}
+
+.method-assumes strong { color: var(--ink); }
+
+/* ─── Directed evolution: search objective + library spread ───────────
+   The reviewer asked what score the simulated annealing maximises and
+   could not find out — it was stated only inside the copy-paste
+   manuscript paragraph. These two notes sit between the parameter pills
+   and that paragraph: the objective in prose, and the MEASURED occupancy
+   of the most-shared substitution in the library on screen. */
+.run-notes {
+    display: grid;
+    gap: 8px;
+    margin: 10px 0 4px;
+}
+
+.run-notes:empty { display: none; }
+
+.run-objective,
+.run-diversity {
+    margin: 0;
+    padding: 9px 11px;
+    border: 1px solid var(--line);
+    border-radius: 6px;
+    font-size: 0.82rem;
+    line-height: 1.55;
+    color: var(--ink-soft);
+}
+
+.run-objective strong,
+.run-diversity strong { color: var(--ink); font-weight: 600; }
+
+.run-diversity code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 0.94em;
+}

dee/static/trace.css

@@ -0,0 +1,411 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   LEGIBILITY (2026-08-01) — units, the run strip, and the decision trace.
+
+   All of it lives here rather than in app.css for the reason PR #14 kept the
+   catalog out: app.css is ~8,600 lines with a hostile cascade, and three
+   people are editing this tree at once. Everything below is either a NEW
+   class or a deliberate, commented override of an app.css rule; nothing
+   redefines a token.
+
+   Colours are app.css tokens only (--line, --line-strong, --ink,
+   --ink-strong, --ink-soft, --ink-faint, --bg-card, --bg-subtle, --bg-app,
+   --danger, --success, --font-mono, --r-2..--r-4, --elev-4, --topbar-h).
+   Inventing a var() name here would compute the whole shorthand to nothing
+   — see ENGINEERING.md §13.1.
+   ═══════════════════════════════════════════════════════════════════════ */
+
+
+/* ── 1. UNITS ─────────────────────────────────────────────────────────────
+   "Fitness 1.0" had its unit in a hover title only, so for anyone who did
+   not hover the right 60px it did not exist. These carry it in the page. */
+
+/* The unit chip inside a column header. Subordinate to the header word but
+   not hidden — it has to survive being read at a glance. */
+.th-unit {
+    font-family: var(--font-mono);
+    font-size: 9.5px;
+    letter-spacing: 0.02em;
+    font-weight: 400;
+    color: var(--ink-faint);
+    /* The header cell is .num (right-aligned) and already tight; keep the
+       chip on the same baseline rather than wrapping it to its own line. */
+    white-space: nowrap;
+}
+
+/* The always-visible legend that answers "what does 1.0 represent?" without
+   opening the collapsed "How to read this" block. */
+.unit-legend {
+    margin: 0 0 10px;
+    padding: 8px 11px;
+    border-left: 2px solid var(--line-strong);
+    background: var(--bg-subtle);
+    border-radius: 0 var(--r-2) var(--r-2) 0;
+    font-size: 12px;
+    line-height: 1.55;
+    color: var(--ink-soft);
+}
+.unit-legend strong { color: var(--ink-strong); font-weight: 600; }
+.unit-legend em { font-style: italic; }
+.unit-legend--tight { margin: 6px 0 10px; font-size: 11.5px; }
+
+/* Inline unit after a score, in the Radar rows and the round-2 learned rows.
+   Mono so it reads as a unit rather than as part of the number. */
+.rs-unit,
+.ls-unit {
+    font-family: var(--font-mono);
+    font-size: 9.5px;
+    color: var(--ink-faint);
+    letter-spacing: 0.02em;
+}
+
+
+/* ── 2. THE CHAT-LIBRARY CAP ──────────────────────────────────────────────
+   The reviewer typed 30 into "Variants to generate" and a Turing-run library
+   came back with 10 rows. The only disclosure was a banner in a different
+   section of the page. This one sits under the input itself. */
+.setting-note {
+    margin: 6px 0 0;
+    font-size: 11px;
+    line-height: 1.5;
+    color: var(--ink-faint);
+}
+.setting-note strong { color: var(--ink-soft); font-weight: 600; }
+
+/* Requested-vs-delivered, stated on the result itself. Not an error state —
+   a chat run capping at 20 is correct behaviour, it just has to be said. */
+.count-note {
+    display: block;
+    margin-top: 4px;
+    font-family: var(--font-mono);
+    font-size: 10.5px;
+    letter-spacing: 0.02em;
+    color: var(--ink-faint);
+}
+.count-note b { color: var(--ink-soft); font-weight: 600; }
+
+
+/* ── 3. INTERACTION RADAR PROGRESS ────────────────────────────────────────
+   One ESM-2 forward pass per variant, serial, with no signal at all beyond a
+   button reading "Analyzing…". Tool rows in the rail have had an elapsed
+   clock since the CRISPR index made two minutes of silence read as a hang;
+   this path never used it. */
+.radar-elapsed {
+    font-family: var(--font-mono);
+    font-size: 10.5px;
+    letter-spacing: 0.03em;
+    color: var(--ink-faint);
+    font-variant-numeric: tabular-nums;   /* so the seconds don't jitter */
+}
+.radar-progress {
+    display: block;
+    height: 2px;
+    margin-top: 7px;
+    background: var(--line);
+    overflow: hidden;
+    border-radius: 1px;
+}
+/* Indeterminate on purpose. The server returns one response for the whole
+   library, so there is no honest per-variant fraction to draw — a bar that
+   filled to 60% would be inventing progress. This says "working", and the
+   elapsed clock next to it says how long for. */
+.radar-progress::after {
+    content: "";
+    display: block;
+    width: 34%;
+    height: 100%;
+    background: var(--ink-soft);
+    animation: tdRadarSlide 1.25s var(--ease-snap) infinite;
+}
+@keyframes tdRadarSlide {
+    0%   { transform: translateX(-100%); }
+    100% { transform: translateX(320%); }
+}
+@media (prefers-reduced-motion: reduce) {
+    .radar-progress::after { animation: none; width: 100%; opacity: 0.35; }
+}
+
+
+/* ── 4. THE RUN STRIP (was the unlabelled "context 0% · $0.11") ───────────
+   Two numbers with no nouns read as noise. They are kept — cost is exactly
+   what someone deciding whether to keep going wants — but named, given a
+   denominator so a sub-1% reading isn't rendered as a flat "0%", and given
+   the trace as somewhere to go and read what they mean in full sentences. */
+
+/* The bar was flex:1 and ate the row; the text now carries the meaning, so
+   the bar becomes a fixed-width glance indicator. Specificity (0,2,0) beats
+   app.css's (0,1,0) `.cp-meter-bar`, and this file loads after it — both
+   conditions are needed (ENGINEERING.md §13.2/§13.3). */
+.cp-meter .cp-meter-bar { flex: 0 0 28px; }
+/* Wraps rather than truncates. Measured at 390px (the rail's real width):
+   "Context 41k / 1M (4%) · $0.14 model cost" overflows by 7px, and an
+   ellipsis there eats "model cost" — putting the label back out of reach on
+   exactly the narrow screens this change set exists to serve. A second line
+   costs 12px; a hidden noun costs the whole fix. */
+.cp-meter .cp-meter-t {
+    flex: 1 1 auto;
+    min-width: 0;
+    white-space: normal;
+    line-height: 1.35;
+    font-variant-numeric: tabular-nums;
+}
+
+/* The way into the trace. Text, not a glyph: the whole complaint upstream of
+   this file is unlabelled controls. */
+.cp-trace-btn {
+    flex: 0 0 auto;
+    font-family: var(--font-mono);
+    font-size: 9.5px;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 3px 8px;
+    border: 1px solid var(--line-strong);
+    border-radius: 999px;
+    background: transparent;
+    color: var(--ink-soft);
+    cursor: pointer;
+    white-space: nowrap;
+}
+.cp-trace-btn:hover { border-color: var(--ink-soft); color: var(--ink-strong); }
+.cp-trace-btn[hidden] { display: none; }
+/* Matches .cp-icon's rule: the 57px collapsed rail has room for nothing. */
+body[data-cockpit="min"] .cp-trace-btn { display: none; }
+
+
+/* ── 5. THE DECISION TRACE ────────────────────────────────────────────────
+   The rail already showed every step; it showed them as a river. Ten minutes
+   in, "what did it actually do and why" is unanswerable because the answer
+   scrolled past. This is the same events, held still. */
+.td-trace {
+    position: fixed;
+    inset: 0;
+    z-index: 60;                 /* above the rail (z 40s) and the canvas */
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+}
+.td-trace[hidden] { display: none; }
+
+.td-trace-scrim {
+    position: absolute;
+    inset: 0;
+    background: rgba(10, 10, 10, 0.42);
+    border: 0;
+    padding: 0;
+    cursor: pointer;
+}
+
+.td-trace-panel {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    width: min(760px, 100%);
+    max-height: min(82vh, 900px);
+    background: var(--bg-card);
+    border: 1px solid var(--line-strong);
+    border-radius: var(--r-4);
+    box-shadow: var(--elev-4);
+    overflow: hidden;
+}
+
+.td-trace-head {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    padding: 16px 18px 12px;
+    border-bottom: 1px solid var(--line);
+    flex: 0 0 auto;
+}
+.td-trace-head h2 {
+    margin: 0;
+    font-size: 15px;
+    letter-spacing: -0.01em;
+    color: var(--ink-strong);
+}
+.td-trace-sub {
+    margin: 4px 0 0;
+    font-size: 12px;
+    line-height: 1.5;
+    color: var(--ink-faint);
+}
+.td-trace-x {
+    margin-left: auto;
+    flex: 0 0 auto;
+    width: 26px;
+    height: 26px;
+    line-height: 1;
+    font-size: 15px;
+    border: 1px solid var(--line-strong);
+    border-radius: var(--r-2);
+    background: transparent;
+    color: var(--ink-soft);
+    cursor: pointer;
+}
+.td-trace-x:hover { border-color: var(--ink-soft); color: var(--ink-strong); }
+
+/* Goal + the two meters, spelled out in words. This is where "context 3%"
+   is allowed the room to say what it is. */
+.td-trace-meta {
+    flex: 0 0 auto;
+    padding: 12px 18px;
+    border-bottom: 1px solid var(--line);
+    background: var(--bg-subtle);
+    font-size: 12px;
+    line-height: 1.6;
+    color: var(--ink-soft);
+}
+.td-trace-goal {
+    margin: 0 0 8px;
+    color: var(--ink-strong);
+    font-size: 13px;
+}
+.td-trace-goal b {
+    display: block;
+    font-family: var(--font-mono);
+    font-size: 9px;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--ink-faint);
+    font-weight: 500;
+    margin-bottom: 2px;
+}
+.td-trace-facts { margin: 0; padding: 0; list-style: none; }
+.td-trace-facts li { margin: 0; }
+.td-trace-facts b { color: var(--ink-strong); font-weight: 600; }
+
+.td-trace-list {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow-y: auto;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    -webkit-overflow-scrolling: touch;
+}
+
+.td-step { border-bottom: 1px solid var(--line); }
+.td-step:last-child { border-bottom: 0; }
+
+.td-step > details > summary {
+    display: flex;
+    align-items: baseline;
+    gap: 10px;
+    padding: 10px 18px;
+    cursor: pointer;
+    list-style: none;
+}
+.td-step > details > summary::-webkit-details-marker { display: none; }
+.td-step > details > summary:hover { background: var(--bg-subtle); }
+.td-step > details[open] > summary { background: var(--bg-subtle); }
+
+.td-step-n {
+    flex: 0 0 auto;
+    min-width: 20px;
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--ink-faint);
+    font-variant-numeric: tabular-nums;
+}
+.td-step-main { flex: 1 1 auto; min-width: 0; }
+.td-step-obj {
+    display: block;
+    font-size: 13px;
+    color: var(--ink-strong);
+    overflow-wrap: break-word;
+}
+.td-step-args {
+    display: block;
+    margin-top: 1px;
+    font-family: var(--font-mono);
+    font-size: 10.5px;
+    color: var(--ink-faint);
+    overflow-wrap: break-word;
+}
+.td-step-status {
+    flex: 0 0 auto;
+    font-family: var(--font-mono);
+    font-size: 9px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    padding: 2px 7px;
+    border-radius: 999px;
+    border: 1px solid var(--line-strong);
+    color: var(--ink-faint);
+}
+.td-step--ok    .td-step-status { color: var(--success); border-color: var(--success); }
+.td-step--fail  .td-step-status { color: var(--danger);  border-color: var(--danger); }
+.td-step--run   .td-step-status { color: var(--ink-soft); }
+.td-step-t {
+    flex: 0 0 auto;
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--ink-faint);
+    font-variant-numeric: tabular-nums;
+    min-width: 34px;
+    text-align: right;
+}
+
+.td-step-detail {
+    padding: 2px 18px 14px 48px;
+    font-size: 12.5px;
+    line-height: 1.6;
+    color: var(--ink);
+}
+.td-step-lbl {
+    margin: 10px 0 2px;
+    font-family: var(--font-mono);
+    font-size: 9px;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--ink-faint);
+}
+.td-step-detail p { margin: 0; overflow-wrap: break-word; }
+.td-step-detail p.td-muted { color: var(--ink-faint); font-style: italic; }
+.td-step-kv {
+    margin: 0;
+    display: grid;
+    grid-template-columns: minmax(0, auto) minmax(0, 1fr);
+    gap: 1px 12px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+}
+.td-step-kv dt { color: var(--ink-faint); }
+.td-step-kv dd { margin: 0; color: var(--ink-strong); overflow-wrap: anywhere; }
+
+/* Plan steps replayed inside a "Plan" entry. */
+.td-plan { margin: 0; padding: 0; list-style: none; font-size: 12.5px; }
+.td-plan li { display: flex; gap: 8px; align-items: baseline; }
+.td-plan-g { flex: 0 0 auto; width: 12px; color: var(--ink-faint); font-family: var(--font-mono); font-size: 11px; }
+.td-plan--done > span:last-child { color: var(--ink-faint); }
+
+.td-trace-empty {
+    margin: 0;
+    padding: 28px 18px;
+    text-align: center;
+    font-size: 12.5px;
+    color: var(--ink-faint);
+}
+.td-trace-empty[hidden] { display: none; }
+
+.td-trace-foot {
+    flex: 0 0 auto;
+    padding: 10px 18px;
+    border-top: 1px solid var(--line);
+    font-size: 11px;
+    line-height: 1.5;
+    color: var(--ink-faint);
+}
+
+/* The rail is ~390px and phones are narrower still; a 24px inset frame there
+   wastes a third of the screen. Full-bleed sheet instead. */
+@media (max-width: 720px) {
+    .td-trace { padding: 0; align-items: stretch; }
+    .td-trace-panel {
+        width: 100%;
+        max-height: none;
+        height: 100%;
+        border: 0;
+        border-radius: 0;
+    }
+    .td-step-detail { padding-left: 18px; }
+}

dee/static/trace.js

@@ -0,0 +1,447 @@
+/* ═══════════════════════════════════════════════════════════════════════
+   THE DECISION TRACE (2026-08-01)
+
+   A reviewing scientist asked for "a function where the entire decision
+   process is shown" — numbered steps, each with an objective, a rationale, a
+   status and a result. The cockpit rail already renders every one of those
+   events. It renders them as a river: ten minutes into a run, "what did it
+   actually do, and why did it do that" is unanswerable, because the answer
+   scrolled off the top and the transcript is interleaved with prose.
+
+   So this invents no instrumentation. Every field below comes out of the
+   orchestrator's existing event stream (dee/core/orchestrator.py `_emit`):
+
+     kind          fields this file reads
+     ────────────  ──────────────────────────────────────────────────────────
+     user          text                → the goal, or a mid-run correction
+     text          text                → the model's own words BEFORE a call,
+                                         which is the only honest "rationale"
+                                         available — see _pendingWhy
+     plan          steps[{step,status}]→ the agent's own decomposition
+     tool_call     id,name,verb,args,at
+     tool_result   id,ok,summary,error,at
+     ask           question,options
+     compacted     note
+     error         error
+     checkpoint / done                 → run outcome, not a step
+
+   Two things this deliberately does NOT do:
+
+   • It does not time steps in the browser. Every event carries a server
+     `at` (unix seconds, 3dp), so a step's duration is result.at − call.at —
+     real, and still correct after a reload replays the run from seq 0. A
+     client-side stopwatch would show nothing on replay, or worse, show the
+     replay's own duration and pass it off as the step's.
+   • It does not synthesise a reason. If the model said nothing before a
+     call, the row says so and offers the active plan step instead, labelled
+     as the plan rather than quoted as the model's reasoning.
+
+   Public surface (cockpit.js is the only caller):
+       TDTrace.push(ev)          one orchestrator event, in order
+       TDTrace.reset()           new/switched run
+       TDTrace.setMeta({...})    cost + context + status from the poll
+       TDTrace.count()           number of steps, for the entry-point button
+       TDTrace.open/close/toggle/isOpen
+   ═══════════════════════════════════════════════════════════════════════ */
+(function () {
+    "use strict";
+
+    /* ── state ─────────────────────────────────────────────────────────── */
+    var entries = [];        // ordered trace entries (see push)
+    var byId = {};           // tool_call id → its entry
+    var goal = "";
+    var meta = { cost: 0, ctxUsed: 0, ctxLimit: 0, status: "" };
+    var planRev = 0;
+    var lastPlan = null;     // most recent plan steps, for the fallback reason
+    var pendingWhy = [];     // assistant prose since the previous step
+    var els = null;
+    var isOpen = false;
+
+    function esc(s) {
+        return String(s == null ? "" : s)
+            .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;");
+    }
+
+    /* ── ingest ────────────────────────────────────────────────────────── */
+    /* Never let a malformed event break the rail. applyEvent calls this
+       inline, so a throw here would kill the transcript too. */
+    function push(ev) {
+        try { _push(ev); } catch (e) { /* a trace row is never worth a dead run */ }
+        if (isOpen) render();
+    }
+
+    function _push(ev) {
+        if (!ev || !ev.kind) return;
+        switch (ev.kind) {
+            case "user":
+                // The FIRST user turn is the goal; everything after it is a
+                // course correction, and which one it was is exactly what a
+                // reader of a finished run needs to know.
+                if (!goal) { goal = ev.text || ""; return; }
+                pendingWhy = [];
+                entries.push({ t: "steer", label: "Course correction",
+                               text: ev.text || "" });
+                return;
+            case "text":
+                if (ev.text) pendingWhy.push(String(ev.text));
+                return;
+            case "plan":
+                planRev++;
+                lastPlan = ev.steps || [];
+                entries.push({ t: "plan", rev: planRev, steps: lastPlan.slice() });
+                pendingWhy = [];
+                return;
+            case "tool_call": {
+                var e = {
+                    t: "tool",
+                    id: ev.id || "",
+                    name: ev.name || "",
+                    verb: ev.verb || ev.name || "step",
+                    args: ev.args || {},
+                    at: typeof ev.at === "number" ? ev.at : null,
+                    status: "run",
+                    why: pendingWhy.join("\n\n").trim(),
+                    // Snapshot the plan step that was active AT THIS MOMENT.
+                    // Reading it later would attribute a step to whatever the
+                    // plan says now, which is a different claim.
+                    planStep: _activePlanStep(),
+                };
+                pendingWhy = [];
+                entries.push(e);
+                if (e.id) byId[e.id] = e;
+                return;
+            }
+            case "tool_result": {
+                var target = ev.id ? byId[ev.id] : null;
+                if (!target) {
+                    // A result with no matching call (older transcript, or a
+                    // truncated replay). Record it rather than dropping it.
+                    target = { t: "tool", name: ev.name || "", verb: ev.name || "step",
+                               args: {}, at: null, why: "", planStep: "" };
+                    entries.push(target);
+                }
+                target.status = ev.ok ? "ok" : "fail";
+                target.summary = ev.summary || "";
+                target.error = ev.error || "";
+                target.resultKind = ev.result_kind || "";
+                target.endAt = typeof ev.at === "number" ? ev.at : null;
+                return;
+            }
+            case "ask":
+                entries.push({ t: "ask", question: ev.question || "",
+                               options: ev.options || [] });
+                pendingWhy = [];
+                return;
+            case "compacted":
+                entries.push({ t: "compacted", note: ev.note || "" });
+                return;
+            case "error":
+                entries.push({ t: "error", text: ev.error || "" });
+                return;
+            case "checkpoint":
+                meta.checkpoint = true;
+                return;
+            case "done":
+                meta.done = true;
+                return;
+            default:
+                return;
+        }
+    }
+
+    function _activePlanStep() {
+        if (!lastPlan || !lastPlan.length) return "";
+        for (var i = 0; i < lastPlan.length; i++) {
+            if (lastPlan[i].status === "active") return lastPlan[i].step || "";
+        }
+        for (var j = 0; j < lastPlan.length; j++) {
+            if ((lastPlan[j].status || "pending") === "pending") return lastPlan[j].step || "";
+        }
+        return "";
+    }
+
+    function reset() {
+        entries = []; byId = {}; goal = ""; planRev = 0; lastPlan = null;
+        pendingWhy = [];
+        meta = { cost: 0, ctxUsed: 0, ctxLimit: 0, status: "" };
+        if (isOpen) render();
+    }
+
+    function setMeta(m) {
+        if (!m) return;
+        if (typeof m.cost === "number") meta.cost = m.cost;
+        if (typeof m.ctxUsed === "number") meta.ctxUsed = m.ctxUsed;
+        if (typeof m.ctxLimit === "number") meta.ctxLimit = m.ctxLimit;
+        if (typeof m.status === "string") meta.status = m.status;
+        if (typeof m.title === "string") meta.title = m.title;
+        if (isOpen) render();
+    }
+
+    function count() {
+        return entries.length;
+    }
+
+    /* ── formatting ────────────────────────────────────────────────────── */
+    function secs(a, b) {
+        if (typeof a !== "number" || typeof b !== "number") return "";
+        var d = Math.max(0, b - a);
+        if (d < 60) return (d < 10 ? d.toFixed(1) : Math.round(d)) + "s";
+        return Math.floor(d / 60) + "m " + Math.round(d % 60) + "s";
+    }
+
+    /* Arguments the agent actually passed. The server already strips
+       `sequence` before emitting, so nothing here can leak a construct; the
+       remaining values are short scalars (gene, organism, k, host). Anything
+       structured is summarised rather than dumped — a trace row is a record,
+       not a JSON viewer. */
+    function argRows(args) {
+        var keys = Object.keys(args || {});
+        if (!keys.length) return "";
+        var out = "";
+        for (var i = 0; i < keys.length; i++) {
+            var k = keys[i], v = args[k];
+            var txt;
+            if (v == null) continue;
+            if (Array.isArray(v)) txt = v.length + " item" + (v.length === 1 ? "" : "s");
+            else if (typeof v === "object") txt = "(object)";
+            else {
+                txt = String(v);
+                if (txt.length > 160) txt = txt.slice(0, 160) + "…";
+            }
+            out += "<dt>" + esc(k) + "</dt><dd>" + esc(txt) + "</dd>";
+        }
+        return out ? '<dl class="td-step-kv">' + out + "</dl>" : "";
+    }
+
+    function argSummary(args) {
+        var order = ["gene_symbol", "organism", "text", "target", "host", "property", "k"];
+        var bits = [];
+        for (var i = 0; i < order.length; i++) {
+            var v = (args || {})[order[i]];
+            if (v == null || typeof v === "object") continue;
+            var s = String(v);
+            if (!s || s.length > 48) continue;
+            bits.push(order[i] === "k" ? "k=" + s : s);
+        }
+        return bits.join(" · ");
+    }
+
+    var STATUS_WORD = { ok: "done", fail: "failed", run: "running" };
+
+    function toolRow(e, n) {
+        var cls = e.status === "ok" ? "td-step--ok"
+                : e.status === "fail" ? "td-step--fail" : "td-step--run";
+        var el = secs(e.at, e.endAt);
+        var args = argSummary(e.args);
+
+        var why = e.why
+            ? '<p>' + esc(e.why) + "</p>"
+            : (e.planStep
+                ? '<p class="td-muted">The model called this without narrating it. '
+                  + "The plan step active at the time was: " + esc(e.planStep) + "</p>"
+                : '<p class="td-muted">The model called this without narrating it, '
+                  + "and no plan was set.</p>");
+
+        var result;
+        if (e.status === "run") {
+            result = '<p class="td-muted">Still running.</p>';
+        } else if (e.status === "fail") {
+            result = "<p>" + esc(e.error || "Failed.") + "</p>"
+                   + (e.resultKind ? '<p class="td-muted">' + esc(e.resultKind) + "</p>" : "");
+        } else {
+            result = e.summary ? "<p>" + esc(e.summary) + "</p>"
+                               : '<p class="td-muted">Completed; the tool returned no summary line.</p>';
+        }
+
+        return '<li class="td-step ' + cls + '"><details><summary>'
+            + '<span class="td-step-n">' + n + "</span>"
+            + '<span class="td-step-main">'
+              + '<span class="td-step-obj">' + esc(e.verb) + "</span>"
+              + (args ? '<span class="td-step-args">' + esc(args) + "</span>" : "")
+            + "</span>"
+            + '<span class="td-step-status">' + esc(STATUS_WORD[e.status] || e.status) + "</span>"
+            + '<span class="td-step-t">' + esc(el) + "</span>"
+            + "</summary>"
+            + '<div class="td-step-detail">'
+              + '<p class="td-step-lbl">Objective</p><p>' + esc(e.verb)
+                 + (e.name ? " — tool <code>" + esc(e.name) + "</code>" : "") + "</p>"
+              + '<p class="td-step-lbl">Rationale</p>' + why
+              + (argRows(e.args) ? '<p class="td-step-lbl">Inputs</p>' + argRows(e.args) : "")
+              + '<p class="td-step-lbl">Result</p>' + result
+            + "</div></details></li>";
+    }
+
+    function plainRow(n, title, sub, body, cls) {
+        return '<li class="td-step ' + (cls || "") + '"><details><summary>'
+            + '<span class="td-step-n">' + n + "</span>"
+            + '<span class="td-step-main"><span class="td-step-obj">' + esc(title) + "</span>"
+            + (sub ? '<span class="td-step-args">' + esc(sub) + "</span>" : "")
+            + "</span>"
+            + '<span class="td-step-status">note</span>'
+            + '<span class="td-step-t"></span>'
+            + "</summary>"
+            + '<div class="td-step-detail">' + body + "</div></details></li>";
+    }
+
+    var PLAN_GLYPH = { done: "✓", active: "▸", skipped: "–", pending: "○" };
+
+    function planRow(e, n) {
+        var items = "";
+        for (var i = 0; i < e.steps.length; i++) {
+            var st = e.steps[i].status || "pending";
+            items += '<li class="td-plan--' + esc(st) + '">'
+                + '<span class="td-plan-g">' + (PLAN_GLYPH[st] || "○") + "</span>"
+                + "<span>" + esc(e.steps[i].step || "") + "</span></li>";
+        }
+        var done = 0;
+        for (var j = 0; j < e.steps.length; j++) if (e.steps[j].status === "done") done++;
+        return plainRow(
+            n,
+            e.rev === 1 ? "Set out a plan" : "Revised the plan (revision " + e.rev + ")",
+            e.steps.length + " step" + (e.steps.length === 1 ? "" : "s") + " · " + done + " done",
+            '<p class="td-step-lbl">Plan at this point</p><ul class="td-plan">' + items + "</ul>");
+    }
+
+    function render() {
+        if (!els) return;
+        var rows = "";
+        var n = 0;
+        for (var i = 0; i < entries.length; i++) {
+            var e = entries[i];
+            n++;
+            if (e.t === "tool") rows += toolRow(e, n);
+            else if (e.t === "plan") rows += planRow(e, n);
+            else if (e.t === "steer") {
+                rows += plainRow(n, "You steered the run", "",
+                    '<p class="td-step-lbl">What you said</p><p>' + esc(e.text) + "</p>"
+                    + '<p class="td-step-lbl">Effect</p><p class="td-muted">Applied at the '
+                    + "next step boundary, so at most one tool call was already in flight.</p>");
+            } else if (e.t === "ask") {
+                rows += plainRow(n, "Asked you a question", "run parked",
+                    '<p class="td-step-lbl">Question</p><p>' + esc(e.question) + "</p>"
+                    + (e.options.length
+                        ? '<p class="td-step-lbl">Options offered</p><p>'
+                          + esc(e.options.join(" · ")) + "</p>" : ""));
+            } else if (e.t === "compacted") {
+                rows += plainRow(n, "Condensed earlier steps", "context limit",
+                    '<p class="td-step-lbl">Why</p><p>Earlier messages were replaced by a '
+                    + "deterministic digest to stay inside the context window. The original "
+                    + "goal is pinned and never condensed.</p>"
+                    + (e.note ? '<p class="td-step-lbl">Digest</p><p>' + esc(e.note) + "</p>" : ""));
+            } else if (e.t === "error") {
+                rows += plainRow(n, "Run error", "", '<p>' + esc(e.text) + "</p>", "td-step--fail");
+            } else { n--; }
+        }
+
+        els.list.innerHTML = rows;
+        els.empty.hidden = !!rows;
+        if (!rows) {
+            els.empty.textContent = goal
+                ? "This run has not taken a step yet."
+                : "No run yet. Ask Turing for something and every step it takes will be recorded here.";
+        }
+
+        els.sub.textContent = n === 0
+            ? "Every step of the current run, held still."
+            : n + " step" + (n === 1 ? "" : "s") + " in this run"
+              + (meta.done ? " · finished" : meta.status === "running" ? " · still running" : "");
+
+        var facts = "";
+        if (goal) {
+            facts += '<p class="td-trace-goal"><b>Goal</b>' + esc(goal) + "</p>";
+        }
+        facts += '<ul class="td-trace-facts">';
+        // The two numbers the rail shows as "context 0% · $0.11", written out.
+        if (meta.ctxLimit) {
+            var pct = meta.ctxUsed / meta.ctxLimit * 100;
+            facts += "<li><b>Context used:</b> " + fmtTokens(meta.ctxUsed) + " of "
+                + fmtTokens(meta.ctxLimit) + " tokens ("
+                + (pct >= 1 ? Math.round(pct) : pct.toFixed(1)) + "%) — how much of the "
+                + "model's window this conversation occupies. When it fills, earlier steps "
+                + "are condensed rather than dropped.</li>";
+        }
+        if (meta.cost) {
+            facts += "<li><b>Model cost so far:</b> $" + meta.cost.toFixed(4)
+                + " — what this run has spent on model calls. Compute run on this "
+                + "server (scoring, folding, guide design) is not billed per call.</li>";
+        }
+        facts += "</ul>";
+        els.meta.innerHTML = facts;
+    }
+
+    function fmtTokens(n) {
+        n = Number(n) || 0;
+        if (n >= 1000000) return (n / 1000000).toFixed(n % 1000000 === 0 ? 0 : 2) + "M";
+        if (n >= 1000) return (n / 1000).toFixed(n >= 100000 ? 0 : 1) + "k";
+        return String(n);
+    }
+
+    /* ── mount ─────────────────────────────────────────────────────────── */
+    function mount() {
+        if (els) return els;
+        var root = document.createElement("div");
+        root.className = "td-trace";
+        root.id = "tdTrace";
+        root.hidden = true;
+        root.innerHTML =
+            '<button type="button" class="td-trace-scrim" data-close aria-label="Close decision trace"></button>' +
+            '<section class="td-trace-panel" role="dialog" aria-labelledby="tdTraceTitle">' +
+              '<header class="td-trace-head">' +
+                "<div>" +
+                  '<h2 id="tdTraceTitle">Decision trace</h2>' +
+                  '<p class="td-trace-sub" id="tdTraceSub"></p>' +
+                "</div>" +
+                '<button type="button" class="td-trace-x" data-close aria-label="Close decision trace">&times;</button>' +
+              "</header>" +
+              '<div class="td-trace-meta" id="tdTraceMeta"></div>' +
+              '<ol class="td-trace-list" id="tdTraceList"></ol>' +
+              '<p class="td-trace-empty" id="tdTraceEmpty"></p>' +
+              '<p class="td-trace-foot">Built from the run\'s own event log — the same events ' +
+                "the rail renders. Every step, input and result below is what the orchestrator " +
+                "recorded; nothing here is reconstructed after the fact.</p>" +
+            "</section>";
+        document.body.appendChild(root);
+        els = {
+            root: root,
+            list: root.querySelector("#tdTraceList"),
+            empty: root.querySelector("#tdTraceEmpty"),
+            sub: root.querySelector("#tdTraceSub"),
+            meta: root.querySelector("#tdTraceMeta"),
+        };
+        [].forEach.call(root.querySelectorAll("[data-close]"), function (b) {
+            b.addEventListener("click", close);
+        });
+        document.addEventListener("keydown", function (e) {
+            if (e.key === "Escape" && isOpen) close();
+        });
+        return els;
+    }
+
+    function open() {
+        mount();
+        isOpen = true;
+        els.root.hidden = false;
+        render();
+        // The list is the scrollable region; a re-open should show the top of
+        // the run, not wherever it was left.
+        els.list.scrollTop = 0;
+    }
+    function close() {
+        if (!els) return;
+        isOpen = false;
+        els.root.hidden = true;
+    }
+    function toggle() { if (isOpen) close(); else open(); }
+
+    window.TDTrace = {
+        push: push,
+        reset: reset,
+        setMeta: setMeta,
+        count: count,
+        open: open,
+        close: close,
+        toggle: toggle,
+        isOpen: function () { return isOpen; },
+    };
+})();

tests/conftest.py

@@ -8,6 +8,25 @@ not listed in requirements.txt. Run with:  pip install pytest && pytest -q
 import os
 import sys
 
+import pytest
+
 _REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if _REPO_ROOT not in sys.path:
     sys.path.insert(0, _REPO_ROOT)
+
+
+@pytest.fixture(autouse=True)
+def _no_leaked_handover():
+    """The orchestrator parks a handover, keyed by owner, when a run ends on a
+    budget limit — so the owner's next run can pick the work up.
+
+    That map is module-level process state, and almost every orchestrator test
+    uses owner "u1". Without this, a test that ends a run on a limit seeds the
+    NEXT test's run with its goal and plan, and the failure surfaces somewhere
+    unrelated. Same class of bug as the persistence flake in
+    docs/ENGINEERING.md §13.23: shared state crossing a test boundary.
+    """
+    from dee.core import orchestrator as _orch
+    _orch._HANDOVERS.clear()
+    yield
+    _orch._HANDOVERS.clear()

tests/test_catalog_constructs.py

@@ -0,0 +1,110 @@
+"""Deleting constructs, not just conversations.
+
+The reviewer's words were "no catalog of conversations/chats or way to delete
+'constructs' and conversations". The catalog shipped with rename and delete for
+conversations and neither for constructs — the cards had one action, "open".
+
+Half of that gap is a server gap. Plasmids and primer analyses have
+owner-checked DELETE routes; saved LIBRARIES and CRISPR DESIGNS have no route
+in server.py and no function in auth.py, and a library is the primary artifact
+this product makes. So catalog.js drives a table, CX_DELETE, and renders a
+Delete button only for the kinds that have somewhere to send it — a delete
+control that 404s is worse than an honest absence.
+
+These tests keep the two halves in step: every endpoint the client is prepared
+to call has to exist on the server, and the kinds that cannot be deleted have
+to stay silent rather than grow a button that fails.
+"""
+import re
+
+from dee import server
+
+_CAT = "dee/static/catalog.js"
+
+
+def _read(path):
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _cx_delete_table():
+    """The live CX_DELETE map, parsed out of catalog.js (commented-out entries
+    are deliberately NOT picked up — they are the documented server gap)."""
+    src = _read(_CAT)
+    block = src[src.index("var CX_DELETE = {"):]
+    block = block[:block.index("};")]
+    out = {}
+    for line in block.split("\n"):
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue
+        m = re.search(r'(\w+)\s*:\s*\{\s*path:\s*"([^"]+)"', stripped)
+        if m:
+            out[m.group(1)] = m.group(2)
+    return out
+
+
+def _delete_routes():
+    app = server.create_app()
+    return {str(r.rule) for r in app.url_map.iter_rules() if "DELETE" in (r.methods or set())}
+
+
+def test_every_endpoint_the_catalog_will_call_actually_exists():
+    """The failure this prevents: shipping a Delete button whose fetch 404s,
+    which looks to the user exactly like the bug they reported."""
+    routes = _delete_routes()
+    for kind, path in _cx_delete_table().items():
+        # "/api/plasmid/library/" in the client -> "/api/plasmid/library/<id>"
+        # on the server. Match on the prefix, since the client appends the id.
+        assert any(rule.startswith(path) for rule in routes), (
+            f"catalog.js will DELETE {path}<id> for a {kind} construct, but no "
+            f"DELETE route starts with that. Routes: {sorted(routes)}")
+
+
+def test_the_two_kinds_with_no_route_render_no_delete_button():
+    """Libraries and CRISPR designs genuinely cannot be deleted yet. The
+    catalog must not pretend otherwise — and when the routes land, uncommenting
+    two lines in CX_DELETE is the whole client change."""
+    table = _cx_delete_table()
+    routes = _delete_routes()
+    for kind, prefix in (("library", "/api/library/"), ("crispr", "/api/crispr/designs/")):
+        if any(r.startswith(prefix) for r in routes):
+            # The server gap is closed — then the client must offer the verb.
+            assert kind in table, (
+                f"{prefix}<id> now exists server-side; uncomment the {kind} entry "
+                "in CX_DELETE so the catalog offers it")
+        else:
+            assert kind not in table, (
+                f"catalog.js offers to delete a {kind} construct but there is no "
+                f"DELETE route under {prefix}")
+
+
+def test_the_construct_card_only_grows_actions_it_can_perform():
+    src = _read(_CAT)
+    card = src[src.index("function constructCard"):]
+    card = card[:card.index("\n    }")]
+    assert "CX_DELETE[c.kind]" in card, (
+        "the Delete button must be gated on the endpoint table, not rendered "
+        "unconditionally")
+    assert 'data-act="delcx"' in card
+
+
+def test_deleting_a_construct_confirms_first_and_names_it():
+    """Same rule as conversations: there is no undo behind any of this, so the
+    confirm says which thing is going rather than asking 'are you sure?'."""
+    src = _read(_CAT)
+    fn = src[src.index("function confirmDeleteConstruct"):]
+    fn = fn[:fn.index("\n    }")]
+    assert "confirmDelete(" in fn
+    assert "cx.name" in fn, "the confirm must name the construct"
+    assert "del.noun" in fn, "the confirm must say what kind of thing it is"
+
+
+def test_deleting_a_construct_refreshes_mission_control():
+    """Mission Control lists the same constructs from the same endpoint.
+    Leaving it showing a card whose record is gone is the silted-up-dropdown
+    problem in a second place."""
+    src = _read(_CAT)
+    fn = src[src.index("function doDeleteConstruct"):]
+    fn = fn[:fn.index("\n    }\n")]
+    assert "TDMission" in fn and "reload" in fn

tests/test_chat_library_cap.py

@@ -0,0 +1,143 @@
+"""The chat library caps at 20, and the app has to say so where it matters.
+
+The incident: a reviewer typed 30 into "Variants to generate", asked Turing
+for a library, and got 10 rows. Their words — "did not explicitly or clearly
+state anywhere that only 10 variants would be scored… you have to search for
+this info in small text in a banner in a different section."
+
+The cap is real and correct: ``_tool_design_variant_library`` runs inside one
+reply rather than as a background job, so it clamps ``k`` to 1–20 and defaults
+to 10. The bug was purely that nothing said so at the input, and the one thing
+that did say so ("a chat run just caps the library size") named no number.
+
+The disclosure now names 20 and 10 in two places, and the browser has no way
+to ask the server what they are. So these tests read the numbers out of the
+Python and fail if the copy has drifted from the behaviour it describes — a
+disclosure with a stale number is worse than none, because the user then has a
+specific wrong number to plan around.
+"""
+import re
+
+import pytest
+
+from dee.core import agent_tools as t
+
+_APP_JS = "dee/static/app.js"
+_COCKPIT = "dee/static/cockpit.js"
+_INDEX = "dee/static/index.html"
+
+
+def _read(p):
+    with open(p, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _python_bounds():
+    """(default_k, cap) as the chat tool actually enforces them."""
+    src = _read("dee/core/agent_tools.py")
+    body = re.search(
+        r"def _tool_design_variant_library\(.*?\n(?=\ndef |\n# )", src, re.S).group(0)
+    default = int(re.search(r'int\(args\.get\("k",\s*(\d+)\)\)', body).group(1))
+    cap = int(re.search(r"k\s*=\s*max\(1,\s*min\((\d+),\s*k\)\)", body).group(1))
+    return default, cap
+
+
+# --------------------------------------------------------------------------- #
+# the numbers themselves
+# --------------------------------------------------------------------------- #
+def test_the_cap_is_what_the_tool_actually_enforces():
+    """Executed, not read: a 30-variant request has to come back clamped."""
+    default, cap = _python_bounds()
+    assert (default, cap) == (10, 20)
+    spec = next(s for s in __import__("dee.core.orchestrator", fromlist=["x"]).TOOL_SPECS
+                if s["function"]["name"] == "design_variant_library")
+    desc = spec["function"]["parameters"]["properties"]["k"]["description"]
+    assert str(cap) in desc and str(default) in desc, desc
+
+
+def test_the_client_constants_match_the_server_clamp():
+    app = _read(_APP_JS)
+    default, cap = _python_bounds()
+    assert f"const CHAT_LIBRARY_CAP = {cap};" in app
+    assert f"const CHAT_LIBRARY_DEFAULT_K = {default};" in app
+
+
+# --------------------------------------------------------------------------- #
+# WHERE the number is entered — the whole point of the complaint
+# --------------------------------------------------------------------------- #
+def test_the_cap_is_disclosed_at_the_input_not_only_in_a_banner():
+    html = _read(_INDEX)
+    default, cap = _python_bounds()
+    # the note has to sit with the K field, not somewhere else on the page
+    block = re.search(
+        r'<input type="number" id="settingK".*?</label>', html, re.S)
+    assert block, "settingK field not found — did the settings card move?"
+    note = block.group(0)
+    assert 'class="setting-note"' in note, note
+    assert str(cap) in note and str(default) in note, note
+    # and it must distinguish the two paths, or it just looks like the sidebar
+    # run is capped at 20 too
+    assert "Directed Evolution" in note and "Turing" in note
+
+
+def test_the_note_has_styles_to_render_with():
+    """A class with no rule is invisible, and this one is built into static
+    HTML — nothing else in the app would fail if the stylesheet lost it."""
+    css = _read("dee/static/trace.css")
+    assert ".setting-note" in css
+    assert ".count-note" in css
+
+
+# --------------------------------------------------------------------------- #
+# the delivered result has to state requested vs scored
+# --------------------------------------------------------------------------- #
+def test_the_painted_library_states_requested_versus_scored():
+    app = _read(_APP_JS)
+    fn = re.search(r"function paintAgentDesignRun\(.*?\n\}", app, re.S).group(0)
+    assert "callArgs" in fn, "the requested k is only available on the tool_call args"
+    assert "You asked for" in fn
+    assert "CHAT_LIBRARY_CAP" in fn
+    # the summary line above the table carries it too, for the sidebar path
+    assert 'class="count-note"' in app
+    assert "Requested" in app
+
+
+def test_the_requested_count_actually_reaches_the_painter():
+    """The tool RESULT carries what came back and nothing about what was
+    asked for. Without the tool_call args being stashed and handed over, the
+    painter has no requested number and the sentence cannot be written —
+    which is a silent no-op, not an error."""
+    cp = _read(_COCKPIT)
+    assert "state.toolArgs[ev.id] = ev.args" in cp
+    assert "toolArgs: {}" in cp
+    # handed to the painter, and the design painter accepts it
+    assert re.search(r"PAINTERS\[ev\.name\]\(ui\.panel,\s*\(ev\.id && state\.toolArgs\[ev\.id\]\)",
+                     cp), "painter called without the call args"
+    assert re.search(r"design_variant_library: function \(panel, args\)", cp)
+    assert "TDDesign.paintAgentRun(panel, args)" in cp
+    # ...and cleared with the run, so run 2 can't inherit run 1's arguments
+    assert "state.toolArgs = {}" in cp
+
+
+# --------------------------------------------------------------------------- #
+# round 2 in chat has its own, smaller, hardcoded ceiling
+# --------------------------------------------------------------------------- #
+def test_chat_round_two_returns_at_most_ten_and_says_so_in_its_own_payload():
+    """propose_round2 hardcodes k=10 and then slices [:10] again. Nothing in
+    the UI reads that path's count, so this only guards the number quoted in
+    the tool description the model reads."""
+    src = _read("dee/core/agent_tools.py")
+    body = re.search(r"def _tool_propose_round2\(.*?\n(?=\ndef |\n# )", src, re.S).group(0)
+    assert re.search(r'"k":\s*10', body)
+    assert re.search(r"\[:10\]", body)
+
+
+@pytest.mark.parametrize("asked, delivered", [(30, 10), (20, 20), (5, 5)])
+def test_the_sentence_only_claims_a_shortfall_when_there_is_one(asked, delivered):
+    """Three cases and they say different things; collapsing them into one
+    line ("a chat run just caps the library size") is what left a user
+    staring at 10 rows after typing 30."""
+    app = _read(_APP_JS)
+    fn = re.search(r"function paintAgentDesignRun\(.*?\n\}", app, re.S).group(0)
+    assert "asked > delivered" in fn
+    assert "the ${asked} you asked for" in fn

tests/test_cockpit_rail.py

@@ -0,0 +1,119 @@
+"""The chat rail: the glitched boxes, the cut-off text, and the split handle.
+
+Three separate review findings, one file, because all three are properties of
+the same 390px column and all three were reproduced by measuring the live DOM
+rather than by reading the CSS.
+
+**Glitched boxes.** `.cp-transcript` is a column flex container, so every turn
+is a flex item with the default `flex-shrink: 1`. Once a run overflows the
+rail the browser shrinks the items before it considers scrolling. Most turns
+survive on `min-height: auto`'s content-based minimum — but that minimum is
+only content-based while `overflow` is `visible`, and `.cp-tool` sets
+`overflow: hidden`. So the tool rows, and only the tool rows, collapse.
+Measured on an eight-tool transcript: rows at **9.6px** against a 34.6px
+header, and `scrollHeight == clientHeight`, i.e. nothing scrolled, everything
+was crushed.
+
+**Cut-off text.** `.cp-user` is a flex row (it carries the STEER tag), which
+makes the message text a flex item whose `min-width: auto` refuses to go below
+its MIN-CONTENT width. `overflow-wrap: break-word` does not reduce min-content
+— that is the difference between it and `anywhere`. Paste the 286-residue
+TEM-1 protein from the review and the box asks for **2,389px inside a 391px
+rail**: 2,024px of sequence off the right edge.
+
+**The split handle.** It shipped at `opacity: 0` until hover, and it survived
+neither the rail being collapsed nor the window being narrowed and widened
+again.
+"""
+import re
+
+_CSS = "dee/static/app.css"
+_CATCSS = "dee/static/catalog.css"
+_RAIL = "dee/static/railsplit.js"
+
+
+def _read(path):
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _rule(css, selector):
+    """The declaration block for an exact selector, comments stripped."""
+    css = re.sub(r"/\*.*?\*/", " ", css, flags=re.S)
+    m = re.search(re.escape(selector) + r"\s*\{([^}]*)\}", css)
+    assert m, f"no rule for `{selector}`"
+    return m.group(1)
+
+
+# --------------------------------------------------------------------------- #
+# glitched boxes
+# --------------------------------------------------------------------------- #
+def test_transcript_children_cannot_be_shrunk():
+    """Without this the tool rows collapse to their own border. Note it is on
+    the CHILDREN of the transcript, not on .cp-tool: the next component that
+    clips its own overflow would otherwise inherit the same bug silently."""
+    body = _rule(_read(_CSS), ".cp-transcript > *")
+    assert re.search(r"flex\s*:\s*0\s+0\s+auto", body), (
+        ".cp-transcript > * must be flex: 0 0 auto")
+
+
+def test_the_tool_row_still_clips_its_own_overflow():
+    """The tempting 'fix' is to drop `overflow: hidden` from .cp-tool, which
+    removes the shrink but also lets a result table escape the rounded corner
+    and the rail's width. Keep the clip; pin the size instead."""
+    assert re.search(r"overflow\s*:\s*hidden", _rule(_read(_CSS), ".cp-tool"))
+
+
+# --------------------------------------------------------------------------- #
+# cut-off text
+# --------------------------------------------------------------------------- #
+def test_a_pasted_sequence_can_shrink_below_its_min_content_width():
+    body = _rule(_read(_CSS), ".cp-user > div")
+    assert re.search(r"min-width\s*:\s*0", body), "min-width:0 removes the flex floor"
+    assert re.search(r"overflow-wrap\s*:\s*anywhere", body), (
+        "must be `anywhere`, not `break-word`: only `anywhere` reduces the "
+        "min-content size, and min-content is what the flex item asks for")
+
+
+# --------------------------------------------------------------------------- #
+# the split handle
+# --------------------------------------------------------------------------- #
+def test_the_grip_is_visible_before_you_touch_it():
+    """It shipped invisible until hover — measured `opacity: "0"` with the
+    split open. A handle you have to already know about is not a handle."""
+    body = _rule(_read(_CATCSS), ".rail-split-grip")
+    m = re.search(r"opacity\s*:\s*([0-9.]+)", body)
+    assert m and float(m.group(1)) > 0.5, (
+        "the resting grip must be visible; hover/focus can make it louder")
+
+
+def test_the_handle_stands_down_when_the_rail_is_collapsed():
+    """Collapsing the rail narrows .cockpit to 236px but leaves --bench-rail
+    where the user dragged it, so the handle sat ~150px out over the canvas
+    offering to resize an edge that was not there."""
+    src = _read(_RAIL)
+    fn = src[src.index("function splitActive"):]
+    fn = fn[:fn.index("\n    }")]
+    assert "data-cockpit" in fn, "splitActive() must account for the collapsed rail"
+
+
+def test_a_narrow_window_does_not_retire_the_handle_permanently():
+    """The resize handler used to branch, and only the 'split has gone away'
+    branch called sync(). Narrow past 900px and back and the handle stayed
+    hidden with the stored width lost until a reload."""
+    src = _read(_RAIL)
+    m = re.search(r'addEventListener\("resize",\s*function[^)]*\)\s*\{(.*?)\n        \}\);',
+                  src, re.S)
+    assert m, "no resize handler found"
+    assert "sync()" in m.group(1), "resize must go through sync()"
+    assert "dragging" in m.group(1), (
+        "sync() must not stamp on a drag in flight — that is the one state it "
+        "would clobber")
+
+
+def test_the_observer_watches_both_body_attributes():
+    src = _read(_RAIL)
+    m = re.search(r"attributeFilter:\s*\[([^\]]*)\]", src)
+    assert m, "no attributeFilter"
+    watched = m.group(1)
+    assert "data-bench" in watched and "data-cockpit" in watched

tests/test_cockpit_recovered_attempts.py

@@ -0,0 +1,113 @@
+"""A recovered attempt must not render as a failure - reviewer log 2026-07-30.
+
+The reviewer's run on beta-lactamase TEM-1 threw three red "couldn't find the
+gene" blocks on a request that then went on to produce a correct answer (286
+aa -> 861 bp, which they checked). The run was fine. The transcript read like
+the product had broken three times.
+
+Source-level assertions, matching the pattern in tests/test_focus_on.py and
+tests/test_plasmid_editor.py - there is no JS runner in this repo. The
+behaviour itself was measured in a real headless browser against
+http://localhost:7863 on 2026-08-01, with the app driven by a scripted fake
+model (three failing fetch_sequence calls, then one that resolves):
+
+  BEFORE  3 x class "cp-turn cp-tool cp-tool--fail"
+          border-top-color color(srgb 0.436627 0.267451 0.246353)   (danger)
+          .cp-tool-sum     rgb(244, 121, 111)                       (danger)
+          glyph            .cp-cross  (red x)
+
+  AFTER   3 x class "cp-turn cp-tool"           (no --fail)
+          border-top-color rgb(43, 41, 38)      (--line, the default)
+          .cp-tool-sum     rgb(144, 138, 128)   (--ink-faint)
+          glyph            neutral, unclassed
+          title            the original error text, still there
+          summary          "no result - retried"
+
+  and identical after a reload, so the demotion survives transcript replay.
+  Zero page errors; documentElement.scrollWidth - innerWidth == 0.
+"""
+import re
+
+import pytest
+
+_COCKPIT = "dee/static/cockpit.js"
+
+
+def _read(path):
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+@pytest.fixture(scope="module")
+def js():
+    return _read(_COCKPIT)
+
+
+def test_a_failed_tool_call_is_tagged_so_a_later_success_can_find_it(js):
+    """Attributes, not an in-memory index: a reload replays the whole
+    transcript from the event log, and an index would be empty at that
+    point."""
+    assert 'setAttribute("data-cp-tool"' in js
+    assert 'setAttribute("data-cp-state"' in js
+
+
+def test_a_success_demotes_earlier_failed_attempts_at_the_same_tool(js):
+    assert "function demoteSupersededAttempts" in js
+    assert re.search(r"if \(ev\.ok\) demoteSupersededAttempts\(ev\.name\)", js)
+    body = js[js.index("function demoteSupersededAttempts"):]
+    body = body[:body.index("\n    function fillToolResult")]
+    # Same tool only. Demoting an unrelated failure because something else
+    # later worked would hide a real problem.
+    assert '[data-cp-tool="\' + name + \'"][data-cp-state="fail"]' in body
+    assert 'classList.remove("cp-tool--fail")' in body
+
+
+def test_the_demoted_row_is_neutral_not_green(js):
+    """It did not succeed. Recolouring it as a success would be a lie about
+    what happened; the point is only that it is no longer shouted."""
+    body = js[js.index("function demoteSupersededAttempts"):]
+    body = body[:body.index("\n    function fillToolResult")]
+    assert 'class="cp-tick"' not in body            # the markup, not the prose
+    assert 'classList.add("cp-tool--ok")' not in body
+
+
+def test_the_original_error_is_kept_not_discarded(js):
+    """Softening the render must not delete the record. The error stays on the
+    node's title, and the transcript export reads the event log rather than
+    the DOM, so the full text survives either way."""
+    body = js[js.index("function demoteSupersededAttempts"):]
+    body = body[:body.index("\n    function fillToolResult")]
+    assert 'setAttribute("title"' in body
+
+
+def test_no_new_css_class_is_invented(js):
+    """docs/ENGINEERING.md §13.7: a guessed class name is a silent no-op, and
+    dee/static/app.css is a different workstream's file. The demoted state is
+    reached by REMOVING a class, and the two hooks are data-attributes."""
+    body = js[js.index("function demoteSupersededAttempts"):]
+    body = body[:body.index("\n    function fillToolResult")]
+    for cls in re.findall(r'classList\.add\("([^"]+)"\)', body):
+        raise AssertionError(f"demotion adds a class ({cls}) that must exist "
+                             f"in app.css - it does not own that file")
+    css = _read("dee/static/app.css")
+    assert ".cp-tool--fail" in css and ".cp-cross" in css     # the ones read
+
+
+def test_repeated_identical_errors_collapse_instead_of_stacking(js):
+    """Three copies of one error is one problem shouted three times. Only
+    CONSECUTIVE duplicates merge - two identical errors with work between them
+    really are two events."""
+    body = js[js.index("function addError"):]
+    body = body[:body.index("\n    /* An attempt that was RETRIED")]
+    assert "_lastErr" in body
+    assert "lastElementChild" in body          # consecutive-only check
+    assert "data-cp-err-n" in body
+
+
+def test_the_cockpit_cache_key_was_bumped(js):
+    """docs/ENGINEERING.md §14: without a fresh ?v= the browser serves the old
+    file and the change appears not to work."""
+    html = _read("dee/static/index.html")
+    m = re.search(r"cockpit\.js\?v=([^\"]+)", html)
+    assert m, "cockpit.js has no cache key"
+    assert m.group(1) != "20260730-editor10", "cache key not bumped"

tests/test_crispr_disclosure.py

@@ -0,0 +1,243 @@
+"""The CRISPR panel must disclose what its numbers mean, not just print them.
+
+Written after a reviewing scientist read the results table and could not
+answer three questions from the interface:
+
+  1. "Showing on-target and composite scores are good but the weights making
+     the composite score should be transparent." — the table sorts by
+     ``composite``, which silently applies a 0.6 off-target weight. Nothing
+     on screen said the weight existed, and crispr_methods.py actively said
+     the opposite ("no hidden weights and no tuning constants") while the
+     engine multiplied by 0.6.
+  2. Frameshift % and top-indel are end-joining repair predictions with
+     fixed constants. The panel never stated the repair context they assume,
+     and never admitted outcomes vary by cell type.
+  3. The genome off-target panel reads like a whole-genome screen. For human
+     and mouse the index is coding sequence only.
+
+These assert the disclosures exist AND that they still match the algorithm —
+a provenance file that drifts from the code is worse than none, because it
+converts an unknown into a confident wrong answer.
+"""
+import pytest
+
+from dee import server
+from dee.core import crispr as C
+from dee.core import crispr_methods as cm
+
+
+@pytest.fixture
+def client():
+    app = server.create_app()
+    app.config.update(TESTING=True)
+    return app.test_client()
+
+
+# A sequence with enough NGG PAMs to yield guides on both strands.
+SEQ = (
+    "ATGGCCTACGACGCATCTTCCCGACAACGTGGACCGGTACCGGAGGTTTAA"
+    "CCGGTACCGGATCGATCGGGCCCAGGTACCGGATTACCGGTACCGGATCC"
+    "GGGTACCGGATCGGGCCCAGGTTTAACCGGTACCGGATCGATCGGGAA"
+)
+
+
+# --------------------------------------------------------------------- #
+# 1. The composite weight
+# --------------------------------------------------------------------- #
+def test_composite_weight_is_a_named_constant_the_engine_actually_uses():
+    """The weight must be one value, not a literal inlined at the call site.
+
+    It was `on_score * (1.0 - 0.6 * max_cfd)` with the 0.6 written in place,
+    so nothing could report it without hardcoding a copy that could drift.
+    """
+    assert isinstance(C.COMPOSITE_OFFTARGET_WEIGHT, float)
+    assert 0.0 < C.COMPOSITE_OFFTARGET_WEIGHT <= 1.0
+
+    guides = C.find_guides(SEQ, max_results=50)
+    assert guides
+    for g in guides:
+        expected = g.on_target_score * (1.0 - C.COMPOSITE_OFFTARGET_WEIGHT * g.cfd_max_offtarget)
+        # Both sides are stored rounded to 3 dp, so allow one unit of that.
+        assert g.composite_score == pytest.approx(expected, abs=2e-3), (
+            f"composite for {g.spacer} is not on_target x (1 - w x self_off)"
+        )
+
+
+def test_every_serialized_guide_carries_the_weight_that_ranked_it():
+    """The UI prints the arithmetic per guide; it must read the weight off the
+    payload rather than keep its own copy. The agent's design_crispr_guides
+    tool builds its panel from these same dicts, so it discloses it too."""
+    guides = C.find_guides(SEQ, max_results=10)
+    dicts = [C.guide_to_dict(g) for g in guides]
+    assert dicts
+    for d in dicts:
+        assert d["composite_offtarget_weight"] == C.COMPOSITE_OFFTARGET_WEIGHT
+
+
+def test_composite_weight_is_disclosed_with_its_real_value():
+    """crispr_methods must state the weight the engine uses.
+
+    This replaces an earlier assertion that the basis said "no hidden
+    weights". That was locking in a false claim: the code has multiplied the
+    off-target term by 0.6 since the composite shipped. The contract changed
+    deliberately — the provenance now describes the algorithm.
+    """
+    c = cm.METHODS["composite"]
+    w = C.COMPOSITE_OFFTARGET_WEIGHT
+    assert str(w) in c["formula"], c["formula"]
+    assert "on_target" in c["formula"] and "self_off" in c["formula"]
+    # And it must say the weight is a judgement call, not a published value.
+    assert "judgement call" in c["basis"]
+    assert "uncalibrated" in c["limits"]
+
+
+def test_composite_provenance_does_not_claim_there_are_no_weights():
+    # The exact sentence that made the reviewer's question unanswerable.
+    c = cm.METHODS["composite"]
+    assert "no hidden weights" not in c["basis"].lower()
+    assert "no tuning constants" not in c["basis"].lower()
+
+
+# --------------------------------------------------------------------- #
+# 2. Repair context for the indel columns
+# --------------------------------------------------------------------- #
+def test_indel_predictor_genuinely_takes_no_cell_type_input():
+    """Guards the executive decision NOT to ship a cell-line selector.
+
+    A dropdown that changes nothing is worse than no dropdown. If someone
+    later gives _predict_indels a cell-type or repair-context argument, this
+    fails — and that is the signal that the disclosure can become a control.
+    """
+    import inspect
+    params = list(inspect.signature(C._predict_indels).parameters)
+    assert params == ["spacer", "pam", "target_context", "enzyme"], params
+
+
+def test_indel_predictions_are_identical_for_the_same_sequence():
+    """The cell-type-agnostic claim, measured rather than asserted: the same
+    guide returns the same numbers every time, because nothing else feeds it."""
+    a = C.find_guides(SEQ, max_results=20)
+    b = C.find_guides(SEQ, max_results=20)
+    for ga, gb in zip(a, b):
+        assert (ga.frameshift_pct, ga.top_indel_label, ga.top_dominance_pct) == \
+               (gb.frameshift_pct, gb.top_indel_label, gb.top_dominance_pct)
+
+
+def test_indels_state_the_repair_context_they_assume():
+    m = cm.METHODS["indels"]
+    assumes = m.get("assumes", "")
+    assert assumes, "indel columns must state the repair context they assume"
+    assert "end-joining" in assumes
+    assert "HDR" in assumes            # no donor template modelled
+    # And the pre-existing cell-type caveat must survive.
+    assert "CELL-TYPE-AGNOSTIC" in m["limits"]
+
+
+def test_methods_route_serves_the_assumes_field(client):
+    body = client.get("/api/crispr/methods").get_json()
+    assert body["methods"]["indels"]["assumes"]
+
+
+# --------------------------------------------------------------------- #
+# 3. Genome off-target scope
+# --------------------------------------------------------------------- #
+def test_genome_scopes_are_derived_from_the_registry_not_restated():
+    """The UI names the coverage per organism. That answer has to come from
+    offtarget.GENOME_SOURCES — a hand-copied list is exactly how a panel ends
+    up promising a whole-genome screen the engine never ran."""
+    from dee.core.offtarget import GENOME_SOURCES
+    scopes = cm.genome_scopes()
+    assert set(scopes) == set(GENOME_SOURCES)
+    for key, src in GENOME_SOURCES.items():
+        assert scopes[key]["scope"] == src["scope"]
+        assert scopes[key]["complete"] is (src["scope"] == "full genome")
+
+
+def test_mammalian_scope_note_says_coding_sequence_only_in_caps():
+    scopes = cm.genome_scopes()
+    for org in ("human", "mouse"):
+        assert scopes[org]["complete"] is False
+        note = scopes[org]["note"]
+        assert "CODING SEQUENCE ONLY" in note
+        assert "intron" in note and "intergenic" in note
+
+
+def test_complete_genome_organisms_are_not_labelled_partial():
+    """The old frontend test was `organism === 'ecoli' ? complete : CDS-only`,
+    which told every yeast / worm / fly run it had screened coding sequence
+    only. Those genomes are indexed complete."""
+    scopes = cm.genome_scopes()
+    for org in ("ecoli", "yeast", "worm", "fly"):
+        assert scopes[org]["complete"] is True
+        assert "CODING SEQUENCE ONLY" not in scopes[org]["note"]
+
+
+def test_methods_route_carries_the_scope_map(client):
+    body = client.get("/api/crispr/methods").get_json()
+    assert body["ok"] is True
+    assert body["genome_scopes"]["human"]["complete"] is False
+    assert body["genome_scopes"]["ecoli"]["complete"] is True
+
+
+# --------------------------------------------------------------------- #
+# The disclosures have to reach the browser, not just the API
+# --------------------------------------------------------------------- #
+def _static(name: str) -> str:
+    from pathlib import Path
+    return (Path(server.__file__).resolve().parent / "static" / name).read_text(encoding="utf-8")
+
+
+def test_frontend_reads_the_weight_from_the_payload_not_a_hardcoded_copy():
+    """A second copy of 0.6 in JS is a drift bug waiting to happen: change the
+    constant in Python and the explanation keeps printing the old number."""
+    js = _static("app.js")
+    assert "composite_offtarget_weight" in js
+    # The why-panel and the scope strip must both build the sentence from it.
+    assert js.count("composite_offtarget_weight") >= 3
+
+
+def test_scope_strip_is_rendered_on_every_paint():
+    js = _static("app.js")
+    assert "_renderScopeStrip" in js
+    assert "crisprScopeStrip" in js
+    # It must not be behind a <details> — the failure being fixed is that
+    # these facts were one click away and went unread.
+    html = _static("index.html")
+    assert "crisprScopeStrip" not in html or "details" not in html.split("crisprScopeStrip")[0][-200:]
+
+
+def test_design_progress_shell_can_actually_be_hidden():
+    """Found while verifying the disclosures in a real browser, not by reading.
+
+    `_hideProgress` was a `const` declared INSIDE the design handler's `try`,
+    and it is called from the `finally`. `finally` is a sibling block, so the
+    binding was never in scope there: every CRISPR design threw
+    "ReferenceError: _hideProgress is not defined" out of the finally, which
+    also swallows whatever error the catch was handling. Measured on the
+    shipping build before the fix: after a SUCCESSFUL design the progress
+    shimmer was still on screen at 74 px with its elapsed counter ticking
+    (3.0s and climbing) and the setInterval leaked once per run. After:
+    shell hidden, height 0, no page errors.
+    """
+    js = _static("app.js")
+    # Anchor on a line unique to the CRISPR design handler.
+    handler = js[js.index("_saveCrisprResume(seq);"):]
+    decl = handler.index("const _hideProgress")
+    try_block = handler.index("try {")
+    assert decl < try_block, (
+        "_hideProgress must be declared before the try, or the finally that "
+        "calls it cannot see it"
+    )
+
+
+def test_science_css_is_linked_and_uses_only_real_tokens():
+    html = _static("index.html")
+    assert "/static/science.css?v=" in html
+    css = _static("science.css")
+    real = {"--line", "--line-strong", "--line-bold", "--bg-app",
+            "--ink", "--ink-strong", "--ink-soft", "--ink-faint"}
+    import re
+    used = set(re.findall(r"var\((--[a-z0-9-]+)", css))
+    assert used <= real, f"invented CSS tokens (they compute to nothing): {used - real}"
+    # §13.5: a stray */ silently kills the rest of the stylesheet.
+    assert css.count("/*") == css.count("*/")

tests/test_crispr_methods.py

@@ -28,10 +28,21 @@ def test_every_ordered_method_exists_and_is_complete():
 
 def test_composite_formula_is_stated_not_hidden():
     # The reviewer's ask: "the weights making the composite score should be
-    # transparent." It's a plain product — say so explicitly.
+    # transparent."
+    #
+    # CONTRACT CHANGED 2026-08-01, deliberately. This test used to assert
+    # `"no hidden" in basis`, which locked in a false claim: the composite is
+    # NOT a plain product. crispr.py has always computed
+    # `on_target * (1 - 0.6 * self_off)`, so "no hidden weights and no tuning
+    # constants" was the disclosure hiding the one weight there is. The
+    # provenance now states the weight and calls it a judgement call; the
+    # value is asserted against the engine's own constant in
+    # tests/test_crispr_disclosure.py so the two cannot drift apart again.
+    from dee.core.crispr import COMPOSITE_OFFTARGET_WEIGHT
     c = cm.METHODS["composite"]
     assert "on_target" in c["formula"] and "self_off" in c["formula"]
-    assert "no hidden" in c["basis"].lower()
+    assert str(COMPOSITE_OFFTARGET_WEIGHT) in c["formula"]
+    assert "judgement call" in c["basis"]
 
 
 def test_on_target_does_not_claim_to_be_rule_set_2():

tests/test_epistasis_narration.py

@@ -0,0 +1,229 @@
+"""Interaction Radar prose — one row must not read like the row above it.
+
+The incident: a reviewing scientist ran the Radar, got ten rows, and quoted
+the repeated sentence back verbatim. ``_narrate`` was one fixed template per
+verdict class, so every clash said "Predicted antagonism: X looks …ly less
+favorable…" and every independent row said the same twenty words with nothing
+from the measurement in them. The analysis had genuinely run per variant; the
+panel gave no evidence of it, which is indistinguishable from a panel that
+prints canned text.
+
+These lock the fix as a property of the OUTPUT, not of the template: within a
+verdict class, rows built from different numbers must produce different notes,
+and the notes must quote the numbers they were built from. They also guard the
+honesty edge — the adjectives are threshold lookups, so a "strong" claim must
+be backed by a shift the threshold actually admits.
+"""
+import re
+
+import numpy as np
+import pytest
+
+from dee.core import epistasis as E
+from dee.core.epistasis import AA_ORDER, COOP_FLOOR, analyze_variant
+
+_COL = {aa: i for i, aa in enumerate(AA_ORDER)}
+
+
+def _matrix(n, overrides):
+    m = np.zeros((n, len(AA_ORDER)), dtype=np.float64)
+    for (pos, aa), val in overrides.items():
+        m[pos, _COL[aa]] = val
+    return m
+
+
+class _FakeLP:
+    def __init__(self, by_seq):
+        self.by_seq = by_seq
+
+    def __call__(self, seq, positions):
+        m = self.by_seq[seq]
+        return np.stack([m[p] for p in list(positions)])
+
+
+def _two_site(marg_a, marg_b, shift_a, shift_b, wt_len=8):
+    """A 2-site variant A1C,A5D with exactly the marginals and shifts asked for.
+
+    Returns the VariantEpistasis. Building the fixture from (marginal, shift)
+    rather than from raw log-probs is what lets a test say "give me a -1.5
+    clash" and read the resulting sentence.
+    """
+    wt = "A" * wt_len
+    mutant = list(wt)
+    mutant[0], mutant[4] = "C", "D"
+    mutant = "".join(mutant)
+    lp_wt = _matrix(wt_len, {(0, "C"): marg_a, (4, "D"): marg_b})
+    lp_mut = _matrix(wt_len, {(0, "C"): marg_a + shift_a, (4, "D"): marg_b + shift_b})
+    return analyze_variant(wt, "A1C,A5D", _FakeLP({wt: lp_wt, mutant: lp_mut}))
+
+
+# --------------------------------------------------------------------------- #
+# the actual complaint: ten rows, one sentence
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize("verdict, rows", [
+    # (marg_a, marg_b, shift_a, shift_b) — all land in one verdict class.
+    ("clash", [(0.4, 0.3, -1.9, 0.0), (0.9, 0.2, -1.2, -0.5),
+               (0.5, 0.6, -0.7, 0.1), (1.2, 0.4, -2.6, -0.9)]),
+    ("cooperative", [(0.2, 0.1, 1.0, 0.5), (0.8, 0.3, 0.6, 0.2),
+                     (0.4, 0.4, 2.2, 0.1), (0.1, 0.9, 0.9, 0.8)]),
+    ("independent", [(0.5, 0.5, 0.0, 0.0), (0.3, 0.2, 0.4, -0.2),
+                     (0.7, 0.1, 0.35, 0.05), (0.2, 0.6, -0.4, 0.35)]),
+])
+def test_rows_in_one_verdict_class_do_not_share_a_sentence(verdict, rows):
+    notes = []
+    for (ma, mb, sa, sb) in rows:
+        res = _two_site(ma, mb, sa, sb)
+        assert res.verdict == verdict, (verdict, ma, mb, sa, sb, res.verdict)
+        notes.append(res.note)
+    assert len(set(notes)) == len(notes), notes
+
+
+def test_the_note_quotes_the_numbers_it_was_built_from():
+    """A sentence that names no measurement can be printed without doing the
+    measurement — which is exactly how the old one read."""
+    res = _two_site(0.40, 0.30, -1.90, 0.00)
+    assert res.verdict == "clash"
+    # worst site's own three numbers: shift magnitude, marginal, in-context
+    assert "1.90" in res.note
+    assert "+0.40" in res.note
+    assert "-1.50" in res.note      # 0.40 + (-1.90)
+    assert "A1C" in res.note
+
+
+def test_every_verdict_names_the_site_that_drove_it():
+    """"the substitutions clash" without saying WHICH one is not actionable —
+    the user's next move is to drop or re-test one specific mutation."""
+    clash = _two_site(0.4, 0.3, -1.9, 0.0)
+    coop = _two_site(0.2, 0.1, 1.0, 0.5)
+    indep = _two_site(0.3, 0.2, 0.4, -0.2)
+    assert "A1C" in clash.note and clash.verdict == "clash"
+    assert "A1C" in coop.note and coop.verdict == "cooperative"
+    assert "A1C" in indep.note and indep.verdict == "independent"
+
+
+# --------------------------------------------------------------------------- #
+# the keywords the UI and the agent read (app.js _radarVerdictMeta renders the
+# chip; check_interactions passes `note` to the model as `explanation`)
+# --------------------------------------------------------------------------- #
+def test_the_verdict_word_survives_in_the_prose():
+    assert "clash" in _two_site(0.4, 0.3, -1.9, 0.0).note.lower()
+    assert "reinforce" in _two_site(0.2, 0.1, 1.0, 0.5).note.lower()
+    assert "independent" in _two_site(0.3, 0.2, 0.4, -0.2).note.lower()
+
+
+# --------------------------------------------------------------------------- #
+# honesty: the adjective is a threshold lookup, never a flourish
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize("shift, word", [
+    (-2.4, "strong"), (-1.5, "strong"), (-1.0, "moderate"),
+    (-0.7, "moderate"), (-0.6, "slight"),
+])
+def test_magnitude_words_track_the_threshold_not_the_mood(shift, word):
+    res = _two_site(3.0, 0.3, shift, 0.0)
+    assert res.verdict == "clash"
+    assert f"a {word} antagonistic shift" in res.note, res.note
+
+
+def test_no_superlative_appears_that_the_numbers_do_not_support():
+    """A 0.6 ΣΔLL drop is 'slight' by the module's own thresholds. Calling it
+    strong is the exact failure mode ENGINEERING.md §9 exists to prevent —
+    the scientist acts on the adjective, not the float."""
+    res = _two_site(3.0, 0.3, -0.6, 0.0)
+    assert "strong" not in res.note
+    assert "slight" in res.note
+
+
+# --------------------------------------------------------------------------- #
+# the two shapes of 'independent' are not the same finding
+# --------------------------------------------------------------------------- #
+def test_flat_and_cancelling_independents_read_differently():
+    """Nothing moved, versus two sites moved half a log-unit each and
+    cancelled. Both score 'independent'; only one of them is boring."""
+    flat = _two_site(0.5, 0.5, 0.0, 0.0)
+    cancel = _two_site(0.5, 0.5, 0.45, -0.45)
+    assert flat.verdict == cancel.verdict == "independent"
+    assert flat.note != cancel.note
+    assert "cancel" in cancel.note
+    # and the threshold it was measured against is stated, not implied
+    assert f"{COOP_FLOOR:g}" in flat.note and f"{COOP_FLOOR:g}" in cancel.note
+
+
+def test_a_net_cooperative_row_still_reports_a_site_that_lost():
+    """Net-positive does not mean every substitution won. Suppressing the
+    loser is how a user orders a variant with a known bad site in it."""
+    # -0.45 is deliberate: notable enough to name (>= 0.3) but under
+    # RISK_FLOOR, so the verdict stays cooperative instead of flipping to
+    # clash. That band is exactly where a hidden loser can ride along.
+    res = _two_site(0.3, 0.3, 1.4, -0.45)
+    assert res.verdict == "cooperative"
+    assert "A5D" in res.note and "0.45" in res.note
+    assert "not uniform" in res.note
+
+
+# --------------------------------------------------------------------------- #
+# grammar that a naive pluralizer gets wrong ("The other 1 site barely move")
+# --------------------------------------------------------------------------- #
+def test_singular_and_plural_remainders_agree_with_their_verb():
+    two = _two_site(0.2, 0.1, 1.0, 0.0)                      # 1 other site
+    assert "The other site barely moves." in two.note
+    assert "The other 1 site" not in two.note
+
+    # 3 sites, one mover → 2 others
+    wt = "A" * 10
+    mutant = "C" + "A" * 3 + "D" + "A" * 3 + "E" + "A"
+    lp_wt = _matrix(10, {(0, "C"): 0.2, (4, "D"): 0.1, (8, "E"): 0.1})
+    lp_mut = _matrix(10, {(0, "C"): 1.2, (4, "D"): 0.1, (8, "E"): 0.1})
+    three = analyze_variant(wt, "A1C,A5D,A9E", _FakeLP({wt: lp_wt, mutant: lp_mut}))
+    assert three.verdict == "cooperative"
+    assert "The other 2 sites barely move." in three.note
+
+
+# --------------------------------------------------------------------------- #
+# a single substitution has a number too
+# --------------------------------------------------------------------------- #
+def test_single_mutants_report_their_marginal():
+    """The old note was 'A single substitution — no interactions to analyze.',
+    identical on every single-mutant row and carrying nothing measured."""
+    wt = "AAAAAA"
+    res = analyze_variant(wt, "A1C", _FakeLP({wt: _matrix(6, {(0, "C"): 1.23})}))
+    assert res.verdict == "single"
+    assert "A1C" in res.note and "+1.23" in res.note
+
+
+# --------------------------------------------------------------------------- #
+# the unit, because "1.0" on its own means nothing (the same reviewer's other
+# complaint, and this prose is one of the places the number appears)
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize("args", [
+    (0.4, 0.3, -1.9, 0.0),      # clash
+    (0.2, 0.1, 1.0, 0.5),       # cooperative
+    (0.3, 0.2, 0.4, -0.2),      # independent
+    (0.5, 0.5, 0.0, 0.0),       # flat independent
+])
+def test_every_number_in_the_prose_carries_its_unit(args):
+    note = _two_site(*args).note
+    assert "ΣΔLL" in note
+    # No bare decimal outside a parenthetical pair or immediately before the
+    # unit — catches a future edit that adds "risk 1.42" with nothing after it.
+    stripped = re.sub(r"[-+]?\d+\.\d+\s*ΣΔLL", "", note)
+    stripped = re.sub(r"\([-+]?\d+\.\d+ alone → [-+]?\d+\.\d+ in combination\)", "", stripped)
+    stripped = re.sub(r"\([-+]?\d+\.\d+ alone → [-+]?\d+\.\d+ together\)", "", stripped)
+    stripped = re.sub(r"\([-+]?\d+\.\d+\)", "", stripped)          # "dragged down too (-0.40)"
+    stripped = re.sub(r"±\d+(\.\d+)?", "", stripped)               # the flag threshold
+    stripped = re.sub(r"\b\d+ sites?\b", "", stripped)             # counts, not measurements
+    assert not re.search(r"\d+\.\d+", stripped), stripped
+
+
+# --------------------------------------------------------------------------- #
+# the chip threshold and the prose threshold must not drift apart
+# --------------------------------------------------------------------------- #
+def test_the_notable_site_threshold_matches_the_ui_chip():
+    """app.js _radarSiteChip tints a mutation chip at |shift| >= 0.3. If the
+    prose used a different bar, a row could name a site as "dragged down too"
+    while its chip rendered neutral, or vice versa — the panel would visibly
+    disagree with itself."""
+    with open("dee/static/app.js", encoding="utf-8") as fh:
+        app = fh.read()
+    block = re.search(r"function _radarSiteChip\(site\) \{(.*?)\n\}", app, re.S).group(1)
+    ui = {float(x) for x in re.findall(r"shift\s*[<>]=\s*-?([0-9.]+)", block)}
+    assert ui == {E._SITE_NOTABLE}, (ui, E._SITE_NOTABLE)

tests/test_hidden_attribute.py

@@ -0,0 +1,128 @@
+"""`hidden` has to mean hidden.
+
+Eight elements carried the `hidden` attribute and rendered anyway, because the
+UA sheet's `[hidden] { display: none }` loses to ANY author `display:` on the
+element — it is an author-vs-UA contest, not a specificity one, so a plain
+`.run-meta { display: flex }` cancels it.
+
+What that looked like: an empty bordered box, 888x30 with one pixel of border
+and nothing in it, sitting under "How to read this" on every library painted
+from a conversation (renderRunMeta re-hides the box when the payload has no
+`settings_used`, which an agent-painted run never does). A reviewing scientist
+photographed it. Measured on a fresh load the same fault was also rendering a
+92px CRISPR base-editor row, a 136px primer organism block, two clone panes, a
+stray filter-clear glyph, and the entire 946x401 primer results card.
+
+This test re-derives the list from the markup rather than hard-coding it, so
+the next class that acquires a `display:` fails here instead of in a
+screenshot.
+"""
+import re
+
+_HTML = "dee/static/index.html"
+_SHEETS = ("dee/static/app.css", "dee/static/catalog.css")
+
+_EXEMPT = {
+    # Deliberate, and says so in a comment: the scrim keeps its box while it
+    # fades out, so `.sidebar-scrim[hidden] { display: block }` is the point.
+    "sidebar-scrim":
+        "keeps its box during the fade-out transition, on purpose",
+    # These get a display ONLY from `body[data-ui="bench"][data-bench="open"]
+    # .bench-strip`, and app.js clears their `hidden` in the same block that
+    # sets data-bench. The state and the attribute never co-occur, and a bare
+    # `.bench-strip[hidden]` guard is (0,2,0) — it would lose to that (0,3,1)
+    # selector anyway, so adding one would look like protection and be none.
+    "bench-strip":
+        "display comes only from a body[data-bench=open] rule; JS clears "
+        "hidden in the same block",
+    "bench-canvashead":
+        "same as .bench-strip",
+}
+
+
+def _read(path):
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _classes_rendered_with_hidden(html):
+    """Every class that appears on an element written with a bare `hidden`."""
+    out = set()
+    for m in re.finditer(r"<\w+([^>]*)>", html):
+        attrs = m.group(1)
+        if not re.search(r"(^|\s)hidden(\s|=|/|$)", attrs):
+            continue
+        cm = re.search(r'class="([^"]*)"', attrs)
+        if cm:
+            out.update(cm.group(1).split())
+    return out
+
+
+def _strip_comments(css):
+    return re.sub(r"/\*.*?\*/", " ", css, flags=re.S)
+
+
+def _classes_given_a_display(css):
+    """Classes that are the SUBJECT of a rule declaring `display:`.
+
+    Subject means the last compound selector — `.brand-mark svg` styles the
+    svg, not `.brand-mark`, so it cannot cancel `hidden` on `.brand-mark`.
+    Selectors already qualified with `[hidden]` are the fix, not the fault.
+    """
+    css = _strip_comments(css)
+    out = {}
+    for rule in re.finditer(r"([^{}]+)\{([^{}]*)\}", css):
+        selector, body = rule.group(1), rule.group(2)
+        decl = re.search(r"(?:^|[;{\s])display\s*:\s*([a-z-]+)", body)
+        if not decl:
+            continue
+        # `display: none` cannot cancel `hidden` — it agrees with it.
+        if decl.group(1) == "none":
+            continue
+        for part in selector.split(","):
+            part = part.strip()
+            if not part or part.startswith("@"):
+                continue
+            subject = re.split(r"[\s>+~]+", part)[-1]
+            if "[hidden]" in subject:
+                continue
+            for cls in re.findall(r"\.([A-Za-z0-9_-]+)", subject):
+                out.setdefault(cls, part)
+    return out
+
+
+def _guarded(css):
+    return set(re.findall(r"\.([A-Za-z0-9_-]+)\[hidden\]", _strip_comments(css)))
+
+
+def test_no_class_silently_cancels_the_hidden_attribute():
+    html = _read(_HTML)
+    displays, guards = {}, set()
+    for sheet in _SHEETS:
+        css = _read(sheet)
+        displays.update(_classes_given_a_display(css))
+        guards |= _guarded(css)
+
+    unguarded = sorted(
+        cls for cls in _classes_rendered_with_hidden(html)
+        if cls in displays and cls not in guards and cls not in _EXEMPT
+    )
+    assert not unguarded, (
+        "these classes are written with `hidden` in index.html but a stylesheet "
+        "gives them a display:, which beats the UA [hidden] rule, so they render "
+        "anyway — add `.<class>[hidden] { display: none; }`: "
+        + ", ".join(f"{c} (from `{displays[c]}`)" for c in unguarded)
+    )
+
+
+def test_the_run_meta_box_is_the_one_from_the_review():
+    """Named explicitly: this is the empty bordered box in the screenshots, and
+    it appears twice (#runMeta on Directed Evolution, #primerRunMeta on Primer
+    Analysis) because both use the .run-meta class."""
+    css = _read("dee/static/app.css")
+    assert re.search(r"\.run-meta\[hidden\][^{]*\{[^}]*display\s*:\s*none", _strip_comments(css)), (
+        ".run-meta[hidden] must resolve to display:none; without it the box "
+        "renders empty on any library painted from a conversation."
+    )
+    html = _read(_HTML)
+    assert html.count('class="run-meta"') >= 2

tests/test_legibility_ui.py

@@ -0,0 +1,326 @@
+"""Legibility of the design surface: units, the run strip, the decision trace.
+
+Three review findings, all of the same shape — the app knew something and did
+not say it where it could be read:
+
+  • "what does a fitness score of 1.0 represent? 2/3 is over and 1/3 is under,
+    but none are negative." The unit (ΣΔLL) lived in a hover `title` on one
+    column header, added May 2026. On a touch device it did not exist at all.
+  • "context 0% · $0.11" — two numbers, no nouns, no denominators.
+  • "a function where the entire decision process is shown" — the events all
+    existed; they scrolled away.
+
+These are markup/wiring assertions because every one of these failures is
+SILENT: a missing class renders nothing, a painter called with the wrong
+arity returns undefined, a script loaded in the wrong order drops the opening
+events of a restored run. None of them raises.
+"""
+import re
+
+import pytest
+
+_APP_JS = "dee/static/app.js"
+_COCKPIT = "dee/static/cockpit.js"
+_TRACE_JS = "dee/static/trace.js"
+_TRACE_CSS = "dee/static/trace.css"
+_INDEX = "dee/static/index.html"
+
+
+def _read(p):
+    with open(p, encoding="utf-8") as fh:
+        return fh.read()
+
+
+# --------------------------------------------------------------------------- #
+# 1. the unit, visible without hovering
+# --------------------------------------------------------------------------- #
+def test_the_fitness_column_carries_its_unit_in_both_table_shells():
+    """There are TWO copies of the results table header: the static one in
+    index.html and the one teardownSkeleton() rebuilds in JS after the loading
+    skeleton. Fixing only the static copy means the unit shows on an empty
+    page and vanishes on every real run."""
+    for src in (_read(_INDEX), _read(_APP_JS)):
+        header = re.search(r'data-sort="fitness"[^>]*>(.*?)</th>', src, re.S)
+        assert header, "fitness column header not found"
+        assert 'class="th-unit"' in header.group(1), header.group(1)
+        assert "ΣΔLL" in header.group(1)
+
+
+def test_the_unit_is_not_only_in_a_hover_title():
+    """The regression this locks: someone "tidies" the header back to a bare
+    word because the title attribute already says it. The title is not
+    readable on a phone and not discoverable on a desktop."""
+    html = _read(_INDEX)
+    header = re.search(r'data-sort="fitness"[^>]*>(.*?)</th>', html, re.S).group(1)
+    visible = re.sub(r"<[^>]+>", "", header)
+    assert "ΣΔLL" in visible, visible
+
+
+def test_the_legend_answers_all_three_parts_of_the_question():
+    """Unit, no fixed zero, and why a top-ranked slice has no negatives in it.
+    The reviewer asked all three; answering one of them is not a fix."""
+    html = _read(_INDEX)
+    legend = re.search(r'<p class="unit-legend" id="fitnessLegend">(.*?)</p>',
+                       html, re.S).group(1)
+    assert "&Sigma;&Delta;LL" in legend or "ΣΔLL" in legend
+    assert "no fixed zero" in legend
+    assert "negatives" in legend
+    # and it must NOT be inside the collapsed "How to read this" block
+    pos = html.index('id="fitnessLegend"')
+    details = [m.span() for m in re.finditer(r"<details.*?</details>", html, re.S)]
+    assert not any(a < pos < b for a, b in details), "legend hidden inside a <details>"
+
+
+def test_every_place_the_score_is_printed_names_its_unit():
+    app = _read(_APP_JS)
+    # stat tile label (the tile is read at a glance and never hovered)
+    assert "'Top fitness (ΣΔLL)'" in app
+    # calibration chart axis
+    assert "ESM-2 predicted fitness · ΣΔLL" in app
+    assert "your assay units" in app
+    # interaction radar score line
+    assert 'class="rs-unit"' in app
+    # round-2 learned rows are PER-SUBSTITUTION, so ΔLL, not ΣΔLL — labelling
+    # them the same would imply one scale across two different numbers
+    assert 'class="ls-unit">ΔLL<' in app
+
+
+def test_the_learned_panel_says_it_is_a_different_scale():
+    html = _read(_INDEX)
+    panel = re.search(r'<section class="learned-panel".*?</section>', html, re.S).group(0)
+    assert "&Delta;LL" in panel
+    assert "Not the same scale" in panel
+
+
+def test_the_mutation_map_states_its_axes_outside_the_svg():
+    """The chart is an SVG with preserveAspectRatio="none", which
+    non-uniformly scales any text inside it — so the axis key is prose above
+    the chart, and the protein length is filled in from the real run."""
+    html = _read(_INDEX)
+    app = _read(_APP_JS)
+    head = re.search(r'<div class="mutmap-head">(.*?)</div>', html, re.S).group(1)
+    assert "residue position" in head
+    assert 'id="mutmapLen"' in head
+    assert "log-likelihood" in head
+    assert "getElementById('mutmapLen')" in app
+
+
+@pytest.mark.parametrize("cls", ["th-unit", "unit-legend", "rs-unit", "ls-unit"])
+def test_the_unit_classes_have_rules(cls):
+    """ENGINEERING.md §13.7: a guessed class name is a silent no-op. These are
+    all new, all in trace.css, and all invisible if the rule is missing."""
+    assert "." + cls in _read(_TRACE_CSS)
+
+
+# --------------------------------------------------------------------------- #
+# 2. the run strip — was "context 0% · $0.11"
+# --------------------------------------------------------------------------- #
+def test_both_meter_numbers_are_named_and_have_a_denominator():
+    cp = _read(_COCKPIT)
+    meter = re.search(r"function renderMeter\(\) \{.*?\n    \}", cp, re.S).group(0)
+    assert '"Context "' in meter, "the context reading is unlabelled"
+    assert "model cost" in meter, "the dollar figure is unlabelled"
+    # a 1M window makes the honest reading "0%", which reads as broken; the
+    # token counts are what carry the magnitude
+    assert "fmtTokens(state.ctxUsed)" in meter and "fmtTokens(state.ctxLimit)" in meter
+    assert "state.els.meter.title" in meter, "no plain-language explanation anywhere"
+
+
+def test_a_sub_one_percent_context_is_not_rendered_as_a_flat_zero():
+    """The old strip printed "context 0%" for the entire normal life of a run,
+    because a few thousand tokens of a 1M window rounds to zero. The token
+    counts are what carry the magnitude now; the percentage is appended only
+    once it is the thing worth reading. Measured, not guessed: at the rail's
+    real 390px, the extra "(4%)" is what pushed "model cost" onto a second
+    line, and an ellipsis there hides the noun this whole change adds."""
+    cp = _read(_COCKPIT)
+    meter = re.search(r"function renderMeter\(\) \{.*?\n    \}", cp, re.S).group(0)
+    assert 'pct >= 50 ? " (" + Math.round(pct) + "%)" : ""' in meter
+    # ...and the exact figure is never lost — the trace states it either way
+    assert "pct >= 1 ? Math.round(pct) : pct.toFixed(1)" in _read(_TRACE_JS)
+
+
+def test_the_warn_threshold_survived_the_rewrite():
+    """The 80%-full warning is the only reason the percentage is still shown
+    at all. Losing it while renaming things would be a silent downgrade."""
+    cp = _read(_COCKPIT)
+    assert 'classList.toggle("cp-meter--warn", pct >= 80)' in cp
+
+
+# --------------------------------------------------------------------------- #
+# 3. the decision trace
+# --------------------------------------------------------------------------- #
+def test_the_trace_is_fed_from_the_single_point_every_event_passes():
+    """Feeding it from anywhere else means a future event kind reaches the
+    rail and not the trace, and nothing fails."""
+    cp = _read(_COCKPIT)
+    body = re.search(r"function applyEvent\(ev\) \{(.*?)\n    \}", cp, re.S).group(1)
+    assert "window.TDTrace.push(ev)" in body
+    # before the switch, so an unhandled kind still reaches the trace
+    assert body.index("TDTrace.push(ev)") < body.index("switch (ev.kind)")
+
+
+def test_the_trace_consumes_every_event_kind_the_rail_does():
+    """A kind the rail routes but the trace drops is a hole in the record."""
+    cp = _read(_COCKPIT)
+    tr = _read(_TRACE_JS)
+    body = re.search(r"function applyEvent\(ev\) \{(.*?)\n    \}", cp, re.S).group(1)
+    rail_kinds = set(re.findall(r'case "(\w+)":', body))
+    trace_kinds = set(re.findall(r'case "(\w+)":', tr))
+    assert rail_kinds <= trace_kinds, rail_kinds - trace_kinds
+
+
+def test_the_trace_loads_before_the_cockpit():
+    """Both are `defer`, so document order is load order. Loaded after, the
+    guarded `window.TDTrace &&` push silently drops the opening events of a
+    restored run — the trace would be missing exactly the steps that explain
+    how the run started."""
+    html = _read(_INDEX)
+    assert html.index("/static/trace.js") < html.index("/static/cockpit.js")
+
+
+def test_the_trace_stylesheet_is_linked():
+    html = _read(_INDEX)
+    assert "/static/trace.css" in html
+
+
+def test_each_step_carries_objective_rationale_status_and_result():
+    """The four fields the reviewer named, by reference to a tool they use."""
+    tr = _read(_TRACE_JS)
+    row = re.search(r"function toolRow\(e, n\) \{.*?\n    \}", tr, re.S).group(0)
+    for label in ("Objective", "Rationale", "Result"):
+        assert f">{label}</p>" in row, label
+    assert "td-step-status" in row
+    assert "STATUS_WORD" in tr
+
+
+def test_a_step_with_no_stated_reason_says_so_instead_of_inventing_one():
+    """The plan step is offered as context and LABELLED as the plan. Quoting
+    it as the model's rationale would be putting words in its mouth."""
+    tr = _read(_TRACE_JS)
+    row = re.search(r"function toolRow\(e, n\) \{.*?\n    \}", tr, re.S).group(0)
+    assert "without narrating it" in row
+    assert "The plan step active at the time was" in row
+
+
+def test_durations_come_from_the_server_clock_not_a_browser_stopwatch():
+    """Every event carries `at` from orchestrator._emit. A client-side timer
+    would show nothing after a reload replays the run, or would time the
+    replay and present that as the step's duration."""
+    tr = _read(_TRACE_JS)
+    assert "secs(e.at, e.endAt)" in tr
+    assert "Date.now()" not in tr, "browser clock used for step timing"
+
+
+def test_the_trace_is_per_run_and_cleared_with_it():
+    cp = _read(_COCKPIT)
+    reset = re.search(r"function reset\(\) \{.*?\n    \}", cp, re.S).group(0)
+    assert "TDTrace.reset()" in reset
+    assert "TDTrace.close()" in reset
+
+
+def test_the_trace_never_breaks_the_rail():
+    """push() is called inline from applyEvent, so a throw would take the
+    transcript down with it."""
+    tr = _read(_TRACE_JS)
+    push = re.search(r"function push\(ev\) \{.*?\n    \}", tr, re.S).group(0)
+    assert "try {" in push and "catch" in push
+
+
+def test_the_meter_explains_itself_in_full_sentences_inside_the_trace():
+    tr = _read(_TRACE_JS)
+    assert "Context used:" in tr
+    assert "Model cost so far:" in tr
+    assert "token" in tr
+
+
+def test_the_entry_point_is_labelled_text_not_a_bare_glyph():
+    """The complaint upstream of all of this is unlabelled UI. A ▤ button
+    would reproduce it."""
+    cp = _read(_COCKPIT)
+    assert 'id="cpTrace"' in cp
+    assert ">Trace</button>" in cp
+    assert 'aria-label="Open the decision trace' in cp
+    assert '"Trace · " + steps' in cp        # and it says how many
+
+
+@pytest.mark.parametrize("cls", [
+    "td-trace", "td-trace-panel", "td-step", "td-step-obj", "td-step-status",
+    "td-step-detail", "td-trace-meta", "cp-trace-btn",
+])
+def test_the_trace_classes_have_rules(cls):
+    assert "." + cls in _read(_TRACE_CSS)
+
+
+# --------------------------------------------------------------------------- #
+# 4. interaction analysis progress
+# --------------------------------------------------------------------------- #
+def test_the_radar_has_an_elapsed_clock_like_every_other_slow_path():
+    app = _read(_APP_JS)
+    assert "startRadarClock" in app and "stopRadarClock" in app
+    assert 'class="radar-elapsed"' in app
+    assert "Analyzing… ${txt}" in app
+
+
+def test_the_radar_clock_is_always_stopped():
+    """An interval outliving the request keeps counting on a finished panel
+    and rewrites the button label back to "Analyzing…" every second."""
+    app = _read(_APP_JS)
+    fn = re.search(r"\(function initRadar\(\) \{.*?\n\}\)\(\);", app, re.S).group(0)
+    finally_block = re.search(r"finally \{(.*?)\n        \}", fn, re.S).group(1)
+    assert "stopRadarClock()" in finally_block
+
+
+def test_the_radar_progress_bar_is_indeterminate_on_purpose():
+    """One POST covers the whole library, so there is no per-variant fraction
+    to draw. A bar that crept to 60% would be inventing progress."""
+    css = _read(_TRACE_CSS)
+    assert ".radar-progress" in css
+    assert "Indeterminate on purpose" in css
+    assert "prefers-reduced-motion" in css
+
+
+def test_the_radar_says_what_the_wait_is_for():
+    """"Analyzing…" for 40 seconds is indistinguishable from a hang. Naming
+    the work — n combinations, one forward pass per site — makes the wait
+    legible even before the clock is read."""
+    app = _read(_APP_JS)
+    assert "one masked forward pass per mutated site" in app
+
+
+# --------------------------------------------------------------------------- #
+# 5. this whole change set is invisible behind a stale cache
+# --------------------------------------------------------------------------- #
+def test_the_changed_assets_got_a_fresh_cache_key():
+    """ENGINEERING.md §14: assets are served max-age=31536000 and busted only
+    by ?v=. Shipping app.js/cockpit.js edits without a bump is the documented
+    way to make a frontend change appear not to work."""
+    html = _read(_INDEX)
+    for asset in ("app.js", "cockpit.js", "trace.js", "trace.css"):
+        m = re.search(r"/static/" + re.escape(asset) + r"\?v=([\w.-]+)", html)
+        assert m, asset
+        # Assert the tag belongs to THIS review round, not a specific
+        # workstream's label. Four branches edited app.js and cockpit.js in
+        # parallel and each bumped the tag to its own name; pinning one
+        # literal here just makes whichever branch merges last look broken,
+        # while testing nothing about staleness.
+        assert m.group(1).startswith("20260801-"), (asset, m.group(1))
+
+
+def test_trace_css_uses_only_tokens_that_exist():
+    """ENGINEERING.md §13.1: an invalid var() poisons the whole shorthand —
+    `border: 1px solid var(--rule)` computes to `border: none`, not to a
+    default colour. Two invented names once made a panel render as floating
+    text."""
+    css = _read("dee/static/app.css")
+    declared = set(re.findall(r"^\s*(--[\w-]+)\s*:", css, re.M))
+    used = set(re.findall(r"var\((--[\w-]+)", _read(_TRACE_CSS)))
+    assert used <= declared, used - declared
+
+
+def test_trace_css_comment_markers_balance():
+    """ENGINEERING.md §13.5: one stray `*/` silently kills the rest of a
+    stylesheet, and the only reason it was caught last time is that a measured
+    metric moved the wrong way."""
+    css = _read(_TRACE_CSS)
+    assert css.count("/*") == css.count("*/"), (css.count("/*"), css.count("*/"))

tests/test_mutation_landscape.py

@@ -0,0 +1,240 @@
+"""The mutation landscape's colour scale.
+
+A reviewing scientist asked for "clearer / more continuous color coding than
+white, gray, and invisible". They were describing this chart. It encoded
+ESM-2 delta-log-likelihood — continuous, signed, and the sign is the whole
+claim — as three hard-coded greys chosen by min-max normalisation, with no
+legend and a card description that named a legend which had been deleted.
+
+Two failures, both silent:
+
+  * min-max erases zero. A library whose positions are all worse than wild
+    type rendered identically to one whose positions are all better, because
+    the scale only ever showed rank within the run.
+  * the greys were literals, so they ignored the theme. Measured against a
+    real 30-variant GFP library on the dark canvas, the fill that every dot
+    ended up with scored **1.53:1** — under the 3:1 floor for a non-text
+    element. That is the "invisible".
+
+The replacement is diverging, anchored at zero, and near-iso-luminant so the
+same ramp clears 3:1 on BOTH canvases. These tests re-derive the ramp from
+app.js and check that numerically, because "looks fine" is what shipped the
+1.53:1 version.
+"""
+import re
+
+import pytest
+
+_APP = "dee/static/app.js"
+_CSS = "dee/static/app.css"
+_HTML = "dee/static/index.html"
+
+# The two canvases the dots are drawn on, read from app.css's own tokens
+# (.mutmap-canvas background) — dark theme --gray-0 and light theme white.
+CANVAS_DARK = (27, 26, 24)
+CANVAS_LIGHT = (255, 255, 255)
+
+# WCAG 2.1 non-text contrast minimum. A dot IS the datum here, so it is not
+# decorative and the floor applies.
+MIN_CONTRAST = 3.0
+
+
+def _read(path):
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _anchor(name):
+    """Pull one MUTMAP_* triple straight out of app.js, so the test cannot
+    drift away from the shipped constant."""
+    m = re.search(name + r"\s*=\s*\[\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\]", _read(_APP))
+    assert m, f"{name} not found in {_APP}"
+    return tuple(int(g) for g in m.groups())
+
+
+def _ramp(t, neg, mid, pos):
+    """The Python twin of mutmapColor(): blend the neutral out to an endpoint."""
+    k = max(-1.0, min(1.0, t))
+    end = neg if k < 0 else pos
+    a = abs(k)
+    return tuple(round(m + (e - m) * a) for m, e in zip(mid, end))
+
+
+def _relative_luminance(rgb):
+    def channel(c):
+        c = c / 255.0
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+    r, g, b = (channel(v) for v in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def _contrast(a, b):
+    la, lb = _relative_luminance(a), _relative_luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def _stops(n=41):
+    neg, mid, pos = _anchor("MUTMAP_NEG"), _anchor("MUTMAP_MID"), _anchor("MUTMAP_POS")
+    return [(-1 + 2 * i / (n - 1), _ramp(-1 + 2 * i / (n - 1), neg, mid, pos))
+            for i in range(n)]
+
+
+# --------------------------------------------------------------------------- #
+# the scale itself
+# --------------------------------------------------------------------------- #
+def test_every_value_on_the_ramp_clears_3_to_1_on_both_canvases():
+    """The old scale's failure mode, made impossible to reintroduce quietly.
+
+    A conventional diverging ramp pales towards the middle, which is fine on
+    white and vanishes on a dark canvas — and vice versa for a dark middle. So
+    this ramp holds luminance nearly constant and varies hue instead; that
+    choice is only worth anything if it is actually checked."""
+    worst_dark = min((_contrast(c, CANVAS_DARK), t) for t, c in _stops())
+    worst_light = min((_contrast(c, CANVAS_LIGHT), t) for t, c in _stops())
+    assert worst_dark[0] >= MIN_CONTRAST, (
+        f"worst contrast on the dark canvas is {worst_dark[0]:.2f}:1 at t={worst_dark[1]:.2f}")
+    assert worst_light[0] >= MIN_CONTRAST, (
+        f"worst contrast on the light canvas is {worst_light[0]:.2f}:1 at t={worst_light[1]:.2f}")
+
+
+def test_the_scale_diverges_around_zero():
+    """Zero has to be the neutral and the two halves have to be different
+    hues, or the sign — the only thing this chart is really saying — is not
+    encoded at all."""
+    neg, mid, pos = _anchor("MUTMAP_NEG"), _anchor("MUTMAP_MID"), _anchor("MUTMAP_POS")
+    assert _ramp(0.0, neg, mid, pos) == mid
+    # Negative end is blue-dominant, positive end is red-dominant. Not a
+    # stylistic assertion: it is what makes "better than wild type" and "worse
+    # than wild type" separable at a glance.
+    assert neg[2] > neg[0], "the negative anchor must be blue-dominant"
+    assert pos[0] > pos[2], "the positive anchor must be warm/red-dominant"
+    for t in (0.25, 0.5, 0.75, 1.0):
+        cool = _ramp(-t, neg, mid, pos)
+        warm = _ramp(+t, neg, mid, pos)
+        assert cool[2] > cool[0], f"t=-{t} lost its blue bias"
+        assert warm[0] > warm[2], f"t=+{t} lost its warm bias"
+
+
+def test_the_endpoints_survive_red_green_colour_vision_deficiency():
+    """Red/green is the obvious encoding for bad/good and the one ~8% of male
+    readers cannot separate. These anchors are Okabe–Ito blue and vermillion;
+    the check is that they stay far apart after protanope and deuteranope
+    simulation (Brettel/Viénot-style channel collapse), not that they look
+    nice to a trichromat."""
+    neg, mid, pos = _anchor("MUTMAP_NEG"), _anchor("MUTMAP_MID"), _anchor("MUTMAP_POS")
+
+    def protan(rgb):
+        r, g, b = rgb
+        return (0.170 * r + 0.830 * g, 0.170 * r + 0.830 * g, b)
+
+    def deutan(rgb):
+        r, g, b = rgb
+        return (0.330 * r + 0.670 * g, 0.330 * r + 0.670 * g, b)
+
+    for name, sim in (("protanopia", protan), ("deuteranopia", deutan)):
+        a, b = sim(neg), sim(pos)
+        dist = sum((x - y) ** 2 for x, y in zip(a, b)) ** 0.5
+        assert dist > 60, f"{name}: the two ends collapse to within {dist:.0f} of each other"
+        # And each end must still separate from the ΔLL≈0 neutral, or a strong
+        # result reads the same as no result.
+        for end, label in ((a, "negative"), (b, "positive")):
+            n = sim(mid)
+            d = sum((x - y) ** 2 for x, y in zip(end, n)) ** 0.5
+            assert d > 25, f"{name}: the {label} end collapses into the neutral"
+
+
+def test_the_three_hard_coded_greys_are_gone():
+    """The literals that produced the 1.53:1 dots. Their absence is the fix;
+    a well-meaning revert would put them straight back."""
+    src = _read(_APP)
+    for dead in ("'#CFCBC2'", "'#3D3A34'", "'#1B1A17'"):
+        assert dead not in src.split("function renderMutationMap")[1][:6000], (
+            f"{dead} is back in the mutation map — that is the quantised grey scale")
+
+
+# --------------------------------------------------------------------------- #
+# the legend
+# --------------------------------------------------------------------------- #
+def test_the_key_states_units_and_direction():
+    """A gradient with no numbers on it is decoration. The reviewer's complaint
+    was partly that nothing said what the colour meant."""
+    src = _read(_APP)
+    key = src[src.index("function renderMutationKey"):]
+    key = key[:key.index("\n}\n")]
+    assert "log-likelihood units" in key, "the key must name the units"
+    assert "more" in key and "wild-type" in key, \
+        "the key must say which direction is better than wild type"
+    assert "attribution, not a per-substitution measurement" in key, (
+        "the key must not let an even split of a variant's ΣΔLL read as a "
+        "measured per-substitution value")
+
+
+def test_the_key_declares_the_domain_and_says_when_it_is_clipped():
+    """Clipping at a percentile is fine; not saying so is not. And claiming a
+    percentile over three data points would be a statistic invented to sound
+    rigorous, so the honest branch has to exist too."""
+    src = _read(_APP)
+    assert "95th percentile" in src
+    assert "Scale spans the full observed range" in src
+    assert "CLIP_MIN_N" in src, (
+        "there must be a floor below which the percentile is not claimed")
+
+
+def test_the_card_no_longer_describes_a_legend_that_is_not_there():
+    """The head text read 'faint · medium · saturated' — describing the chip
+    legend that had already been deleted. The markup now carries a real key."""
+    html = _read(_HTML)
+    assert "faint &middot; medium &middot; saturated" not in html
+    assert 'id="mutmapKey"' in html
+
+
+def test_the_key_copy_survives_the_production_minifier():
+    """rjsmin predates ES6 and does not treat a backtick as opening a string.
+    Inside a template literal it reads the prose as code and strips whitespace
+    next to punctuation, so
+
+        `... units${modelLabel ? ' (' + m + ')' : ''}.`
+
+    shipped as "units(ESM-2 35M)" and "2positions&mdash;nothing is clipped" —
+    in the one paragraph whose whole job is to make a scientific readout look
+    like a scientist wrote it. Nothing raises; the source is fine and only the
+    served asset is wrong, which is why this asserts on minified output.
+
+    The fix is ordinary quoted strings, which rjsmin leaves alone.
+    """
+    rjsmin = pytest.importorskip(
+        "rjsmin", reason="production minifier; CI installs it (see ENGINEERING.md 13.21)")
+    src = _read(_APP)
+    start = src.index("function renderMutationKey")
+    fn = src[start:src.index("\n}\n", start)]
+    out = rjsmin.jsmin(fn)
+    assert "' log-likelihood units, centred on zero" in out, \
+        "the space before 'log-likelihood' was eaten by the minifier"
+    assert "' &mdash; nothing is clipped.'" in out, \
+        "the spaces around the em dash were eaten by the minifier"
+    assert "' (' + escapeHtml(modelLabel)" in fn.replace("'(' ", "' (' "), \
+        "the space before the model label must be inside a quoted string"
+    # And no template literal may creep back into the copy — that is the trap.
+    # Comments stripped: the one above deliberately quotes the broken form.
+    code = re.sub(r"/\*.*?\*/", " ", fn, flags=re.S)
+    code = "\n".join(ln for ln in code.split("\n") if not ln.strip().startswith("//"))
+    assert "`" not in code, "the legend copy must not go back into a template literal"
+
+
+def test_the_colour_encodes_a_mean_not_a_sum():
+    """Summing the per-position contribution made a frequently-mutated
+    position look 'strong' purely for being frequent — and the bar's height
+    already encodes exactly that count, so the chart said the same thing
+    twice and called the second one strength."""
+    src = _read(_APP)
+    body = src[src.index("function renderMutationMap"):]
+    body = body[:body.index("function renderMutationKey")]
+    # Comments stripped: they deliberately name the thing being warned against
+    # ("Σ contribution named a quantity that..."), and matching prose would
+    # make this test pass or fail on the wording. Same reason as
+    # test_plasmid_editor's _code() helper.
+    code = "\n".join(ln for ln in body.split("\n")
+                     if not ln.strip().startswith(("//", "*", "/*")))
+    assert "total.get(pos) / n" in code, "per-position colour must be a mean"
+    assert "Σ contribution" not in code, "the old summed label is back"

tests/test_orchestrator.py

@@ -246,7 +246,16 @@ def test_step_cap_checkpoints_instead_of_dead_ending(monkeypatch, no_tools):
     The old behaviour marked the run `done` and said "I've taken this as far
     as one run goes" — which reads as completion while actually abandoning the
     task mid-flight, with no way to find out where it got to. Now it parks
-    awaiting input, names what's left, and can be resumed."""
+    awaiting input, names what's left, and can be resumed.
+
+    AUTO_EXTENSIONS is pinned to 0 so this stays a test of the CHECKPOINT.
+    Since 2026-08-01 a run that is still landing tool calls, with budget to
+    spare, tops its own step allowance up instead of stopping to make the user
+    type "continue" — the reviewer's log has that prompt firing repeatedly and
+    reads it as the agent stalling. Auto-extension has its own tests in
+    tests/test_run_budget.py; leaving it on here would only move the same
+    checkpoint 24 steps later."""
+    monkeypatch.setattr(orch, "AUTO_EXTENSIONS", 0)
     monkeypatch.setattr(orch, "MAX_STEPS", 3)
     _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
                                      call_id=f"c{i}") for i in range(50)])
@@ -280,7 +289,13 @@ def test_checkpoint_names_the_unfinished_plan_steps(monkeypatch, no_tools):
 
 def test_run_never_exceeds_the_extension_ceiling(monkeypatch, no_tools):
     """Continuing must stay bounded — otherwise "continue" is an infinite
-    money tap on a run that may simply be stuck."""
+    money tap on a run that may simply be stuck.
+
+    AUTO_EXTENSIONS pinned to 0 for the same reason as the test above: with
+    self-extension on, the single extension MAX_EXTENSIONS allows here would
+    be spent automatically and the user would never be offered the "continue"
+    this test is about. The ceiling itself is what's under test."""
+    monkeypatch.setattr(orch, "AUTO_EXTENSIONS", 0)
     monkeypatch.setattr(orch, "MAX_STEPS", 2)
     monkeypatch.setattr(orch, "MAX_EXTENSIONS", 1)
     _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
@@ -294,13 +309,25 @@ def test_run_never_exceeds_the_extension_ceiling(monkeypatch, no_tools):
 
 
 def test_cost_cap_stops_the_run(monkeypatch, no_tools):
+    """The cap still binds — but it ends the run, it does not fault it.
+
+    CONTRACT CHANGED 2026-08-01, deliberately. This used to assert
+    status=="error" with error_kind "cost_capped", which is what put a red
+    error block over a mostly-successful run and produced the reviewer's "not
+    clear what happened here / was this a user limit?". Spending an allowance
+    is an expected end to a run, not a fault, so it now lands as `done` with
+    reason "budget_spent" and a handover. What must NOT change is that the
+    money stops the run — that is still asserted here. The message wording and
+    the carry-over are covered in tests/test_run_budget.py."""
     _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
                                      call_id=f"c{i}") for i in range(50)],
             cost=0.4)
     run = orch.create_run(owner="u1", anonymous=False)
     orch.start(run, "expensive")
-    assert _run_to_rest(run) == "error"
-    assert _of_kind(run, "error")[0]["error_kind"] == "cost_capped"
+    assert _run_to_rest(run) == "done"
+    assert _of_kind(run, "done")[-1]["reason"] == "budget_spent"
+    assert run.steps < 50                       # it really did stop early
+    assert not _of_kind(run, "error")
 
 
 def test_openrouter_failure_surfaces_as_a_clean_error(monkeypatch, no_tools):

tests/test_resolve.py

@@ -151,12 +151,38 @@ def _uniprot_hit(acc="P04637", org="Homo sapiens", seq="MEEPQ"):
     }]}
 
 
+def _alphafold_hit(acc="P04637", plddt=94.9, version=6):
+    """Shape of one AlphaFold prediction-API entry, as resolve reads it.
+
+    Field names checked against the live API on 2026-08-01
+    (https://alphafold.ebi.ac.uk/api/prediction/P62593).
+    """
+    return [{
+        "modelEntityId": f"AF-{acc}-F1",
+        "pdbUrl": f"https://alphafold.ebi.ac.uk/files/AF-{acc}-F1-model_v{version}.pdb",
+        "cifUrl": f"https://alphafold.ebi.ac.uk/files/AF-{acc}-F1-model_v{version}.cif",
+        "globalMetricValue": plddt,
+        "latestVersion": version,
+    }]
+
+
+def _two_hop(uniprot_payload, alphafold_payload, captured=None):
+    """resolve_uniprot makes TWO calls now: UniProt, then AlphaFold DB to
+    confirm a model actually exists (added 2026-08-01 — see the TEM-1
+    incident in resolve.resolve_uniprot). One stub, routed by host."""
+    def _get(url, **k):
+        if "alphafold" in url:
+            return json.dumps(alphafold_payload).encode() if alphafold_payload else b""
+        if captured is not None:
+            captured["url"] = url
+        return json.dumps(uniprot_payload).encode()
+    return _get
+
+
 def test_resolve_uniprot_ok(monkeypatch):
     captured = {}
-    def _get(url, **k):
-        captured["url"] = url
-        return json.dumps(_uniprot_hit()).encode()
-    monkeypatch.setattr(U, "_get", _get)
+    monkeypatch.setattr(U, "_get",
+                        _two_hop(_uniprot_hit(), _alphafold_hit(), captured))
     out = R.resolve_uniprot("human", "TP53")
     assert out["ok"] and out["uniprot"] == "P04637"
     assert out["alphafold_url"] == "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.pdb"
@@ -178,14 +204,16 @@ def test_resolve_uniprot_serves_bacteria_and_yeast(monkeypatch):
     """The structure viewer used to refuse anything but human/mouse via a
     two-entry taxid table, so SpCas9 came back as "no structure" even though
     AlphaFold has modelled Q99ZW2 all along. Any organism must resolve."""
-    monkeypatch.setattr(U, "_get", lambda url, **k: json.dumps(
-        _uniprot_hit("Q99ZW2", "Streptococcus pyogenes serotype M1")).encode())
+    monkeypatch.setattr(U, "_get", _two_hop(
+        _uniprot_hit("Q99ZW2", "Streptococcus pyogenes serotype M1"),
+        _alphafold_hit("Q99ZW2")))
     out = R.resolve_uniprot("s. pyogenes", "cas9")
     assert out["ok"] and out["uniprot"] == "Q99ZW2"
     assert "AF-Q99ZW2" in out["alphafold_url"]
 
-    monkeypatch.setattr(U, "_get", lambda url, **k: json.dumps(
-        _uniprot_hit("P04385", "Saccharomyces cerevisiae")).encode())
+    monkeypatch.setattr(U, "_get", _two_hop(
+        _uniprot_hit("P04385", "Saccharomyces cerevisiae"),
+        _alphafold_hit("P04385")))
     assert R.resolve_uniprot("yeast", "GAL1")["ok"] is True
 
 
@@ -200,6 +228,162 @@ def test_resolve_uniprot_outage_is_not_a_missing_gene(monkeypatch):
     assert "check" not in out["error"].lower()
 
 
+# ───────────────── the TEM-1 mis-resolution (reviewer log, 2026-07-30) ──────
+#
+# The bench showed I6ZGA9 as the AlphaFold model's accession for
+# beta-lactamase TEM-1. Checked against the LIVE APIs on 2026-08-01, verbatim:
+#
+#   GET rest.uniprot.org/uniprotkb/I6ZGA9.json                          → 200
+#     entryType "UniProtKB unreviewed (TrEMBL)", uniProtkbId I6ZGA9_ECOLX,
+#     Escherichia coli, proteinDescription.recommendedName "Beta-lactamase",
+#     flag "Fragment", sequence.length 264
+#   GET alphafold.ebi.ac.uk/api/prediction/I6ZGA9                       → 200
+#     AF-I6ZGA9-F1, globalMetricValue 95.25, latestVersion 6
+#   GET rest.uniprot.org/uniprotkb/P62593.json                          → 200
+#     "UniProtKB reviewed (Swiss-Prot)", BLAT_ECOLX, "Beta-lactamase TEM",
+#     alternativeNames include TEM-1, gene bla, flag "Precursor", length 286
+#   GET alphafold.ebi.ac.uk/api/prediction/P62593                       → 200
+#     AF-P62593-F1, globalMetricValue 94.88, latestVersion 6, sequence begins
+#     MSIQHFRVALIPFFAAFCLPVFAHPETL… — the reviewer's paste, exactly
+#   GET alphafold.ebi.ac.uk/files/AF-P62593-F1-model_v4.pdb             → 404
+#   GET alphafold.ebi.ac.uk/files/AF-P62593-F1-model_v6.pdb             → 200
+#
+# So I6ZGA9 IS a real accession with a real model — "not a recognised UniProt
+# identifier" is not correct — but it is a PARTIAL entry beginning 11 residues
+# into the protein the reviewer pasted, so the viewer's residue numbering was
+# offset by 11. Two defects, one visible symptom.
+
+def _tem1_style_payload(acc, entry_id, entry_type, length, flag=None,
+                        name="Beta-lactamase"):
+    description = {"recommendedName": {"fullName": {"value": name}}}
+    if flag:
+        description["flag"] = flag
+    return {"results": [{
+        "primaryAccession": acc,
+        "uniProtkbId": entry_id,
+        "entryType": entry_type,
+        "organism": {"scientificName": "Escherichia coli"},
+        "proteinDescription": description,
+        "sequence": {"value": "M" * length},
+        "uniProtKBCrossReferences": [],
+    }]}
+
+
+def test_a_reviewed_protein_name_match_beats_an_unreviewed_gene_match(monkeypatch):
+    """The TEM-1 defect itself.
+
+    `gene:TEM-1 … reviewed:true` finds nothing (the gene is `bla`; TEM-1 is a
+    protein ALTERNATIVE name), so the old two-query resolver fell straight to
+    `gene:TEM-1` unreviewed and took I6ZGA9 — a 264 aa fragment. The reviewed
+    entry, P62593 at 286 aa, was reachable the whole time via protein_name.
+    """
+    seen = []
+
+    def _get(url, **k):
+        query = urllib.parse.unquote(url)
+        seen.append(query)
+        if "alphafold" in url:
+            return json.dumps(_alphafold_hit("P62593", 94.88)).encode()
+        # "protein_name:" with the colon — the &fields= list also contains the
+        # bare word protein_name, so matching on that alone makes this stub
+        # answer the GENE query and quietly invert what the test proves.
+        if "protein_name:" in query and "reviewed:true" in query:
+            return json.dumps(_tem1_style_payload(
+                "P62593", "BLAT_ECOLX", "UniProtKB reviewed (Swiss-Prot)",
+                286, flag="Precursor", name="Beta-lactamase TEM")).encode()
+        if "gene:TEM-1" in query and "reviewed:true" not in query:
+            return json.dumps(_tem1_style_payload(
+                "I6ZGA9", "I6ZGA9_ECOLX", "UniProtKB unreviewed (TrEMBL)",
+                264, flag="Fragment")).encode()
+        return b'{"results": []}'
+
+    monkeypatch.setattr(U, "_get", _get)
+    hit = U.find_gene("TEM-1", "ecoli")
+    assert hit is not None
+    assert hit.accession == "P62593", "still resolving to the TrEMBL fragment"
+    assert hit.reviewed is True and hit.fragment is False
+    assert hit.matched_by == "protein_name"
+    # The reviewed gene query must still be tried FIRST — protein_name is a
+    # fallback, not a replacement.
+    assert "gene:TEM-1" in seen[0] and "reviewed:true" in seen[0]
+
+
+def test_a_fragment_entry_is_reported_as_partial_not_passed_off_as_the_protein(
+        monkeypatch):
+    """A fragment's residue numbering is offset from the full sequence. In a
+    product whose output is "mutate residue 104", handing one over silently is
+    the difference between the right residue and the wrong one."""
+    monkeypatch.setattr(U, "_get", _two_hop(
+        _tem1_style_payload("I6ZGA9", "I6ZGA9_ECOLX",
+                            "UniProtKB unreviewed (TrEMBL)", 264,
+                            flag="Fragment"),
+        _alphafold_hit("I6ZGA9", 95.25)))
+    out = R.resolve_uniprot("ecoli", "TEM-1")
+    assert out["ok"] is True                 # a fragment model is still a model
+    assert out["fragment"] is True
+    joined = " ".join(out["caveats"]).lower()
+    assert "partial" in joined or "fragment" in joined
+    assert "unreviewed" in joined
+    assert out["protein_length"] == 264
+
+
+def test_precursor_is_not_mistaken_for_a_fragment(monkeypatch):
+    """UniProt puts "Precursor" in the same slot as "Fragment", and P62593 —
+    the CORRECT TEM-1 — is flagged Precursor. A precursor is the complete
+    chain including its signal peptide; calling it partial would attach a
+    false caveat to the right answer."""
+    monkeypatch.setattr(U, "_get", _two_hop(
+        _tem1_style_payload("P62593", "BLAT_ECOLX",
+                            "UniProtKB reviewed (Swiss-Prot)", 286,
+                            flag="Precursor", name="Beta-lactamase TEM"),
+        _alphafold_hit("P62593", 94.88)))
+    out = R.resolve_uniprot("ecoli", "TEM-1")
+    assert out["ok"] and out["fragment"] is False
+    assert "caveats" not in out
+    assert out["plddt"] == 94.88 and out["structure_verified"] is True
+
+
+def test_an_accession_with_no_alphafold_model_never_becomes_a_structure(
+        monkeypatch):
+    """The file URL is CONSTRUCTED — a claim, not a fact. Before this, any
+    UniProt hit produced an AF-…-model_v6.pdb URL whether or not AlphaFold had
+    ever modelled it, and the viewer was told to go and paint it."""
+    monkeypatch.setattr(U, "_get", _two_hop(_uniprot_hit("Q9XXXX"), None))
+    out = R.resolve_uniprot("human", "SOMEGENE")
+    assert out["ok"] is False
+    assert out["kind"] == "no_structure"
+    assert "Q9XXXX" in out["error"]
+    assert "alphafold_url" not in out
+
+
+def test_an_alphafold_outage_is_not_a_missing_structure(monkeypatch):
+    """Transient ≠ absent (docs/ENGINEERING.md §9). If EBI doesn't answer, we
+    keep the fallback URL and say the model is UNVERIFIED — telling a
+    scientist their protein has no predicted structure because an endpoint
+    blinked is a false negative that makes a working viewer look empty."""
+    def _get(url, **k):
+        if "alphafold" in url:
+            raise U.UniProtUnavailable("HTTP 503")
+        return json.dumps(_uniprot_hit("P04637")).encode()
+    monkeypatch.setattr(U, "_get", _get)
+    out = R.resolve_uniprot("human", "TP53")
+    assert out["ok"] is True
+    assert out["structure_verified"] is False
+    assert out["alphafold_url"].endswith("AF-P04637-F1-model_v6.pdb")
+
+
+def test_the_model_url_comes_from_alphafold_not_from_us(monkeypatch):
+    """Verified live 2026-08-01: AF-P62593-F1-model_v4.pdb is a 404 and
+    ...model_v6.pdb is a 200. A hand-built URL carrying a stale version number
+    reads as "no structure" for a protein that has one, so when the API tells
+    us the file's location we use ITS answer."""
+    monkeypatch.setattr(U, "_get", _two_hop(
+        _uniprot_hit("P04637"), _alphafold_hit("P04637", version=7)))
+    out = R.resolve_uniprot("human", "TP53")
+    assert out["alphafold_url"].endswith("AF-P04637-F1-model_v7.pdb")
+    assert out["model_version"] == 7
+
+
 # ─────────── upstream outage vs genuine absence (2026-07-27) ───────────
 
 def test_ensembl_outage_is_not_reported_as_a_bad_gene_symbol(monkeypatch):

tests/test_run_budget.py

@@ -0,0 +1,337 @@
+"""Budget: warn, pace, hand over — reviewer log, 2026-07-30.
+
+Two complaints, both about a run running out of room:
+
+  • "This run hit its budget ceiling. Start a new one to continue." arrived
+    with no warning, as a RED ERROR BLOCK, mid-task. The reviewer's note was
+    "not clear what happened here / was this a user limit?" — a fair question,
+    because the sentence names no budget, no number and no unit, and offers no
+    way to carry the work across. Everything done so far was simply stranded.
+
+  • "I've used this stretch of the run. Still to do: …  Say **continue**"
+    fired over and over and the reviewer had to keep typing "continue". A
+    pause the user must clear every 24 steps is not pacing, it reads as the
+    agent stalling.
+
+The two are one design problem: the step budget was the loud gate and the
+COST budget — the one that actually protects anyone — was a silent wall at
+the end. Inverted here. The step budget extends itself while there is real
+progress and real money left; the cost budget warns, then checkpoints with
+room to spare, and only hands over when it is genuinely spent.
+"""
+import json
+import time
+
+import pytest
+
+from dee.core import llm as _llm
+from dee.core import orchestrator as orch
+
+
+def _msg_tool(name, args, call_id="c1", content=None):
+    return {
+        "content": content,
+        "tool_calls": [{
+            "id": call_id,
+            "function": {"name": name, "arguments": json.dumps(args)},
+        }],
+    }
+
+
+def _msg_text(text):
+    return {"content": text, "tool_calls": []}
+
+
+def _script(monkeypatch, messages, cost=0.001):
+    seq = list(messages)
+
+    def fake(config, body):
+        nxt = seq.pop(0) if seq else _msg_text("finished")
+        return nxt, cost, 1234
+    monkeypatch.setattr(_llm, "call", fake)
+
+
+def _run_to_rest(run, timeout=5.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if run.status in ("awaiting_input", "done", "error", "stopped"):
+            return run.status
+        time.sleep(0.01)
+    raise AssertionError(f"run never settled (status={run.status})")
+
+
+def _of_kind(run, kind):
+    return [e for e in run.events if e["kind"] == kind]
+
+
+def _all_text(run):
+    return " ".join(e.get("text", "") for e in _of_kind(run, "text"))
+
+
+@pytest.fixture(autouse=True)
+def _configured(monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "test-key")
+    monkeypatch.setenv("AGENT_MAX_COST_USD", "0.5")
+
+
+@pytest.fixture
+def no_tools(monkeypatch):
+    monkeypatch.setattr(orch._tools, "execute_tool",
+                        lambda name, args, anon, **kw: {"ok": True})
+
+
+# --------------------------------------------------------------------------- #
+# 3. the ceiling arrived with no warning and no way across
+# --------------------------------------------------------------------------- #
+def test_spending_is_warned_about_before_the_ceiling(monkeypatch, no_tools):
+    """REPRODUCES "not clear what happened here".
+
+    Before the fix the only signal about spend was the ceiling itself. A run
+    could go from silent to dead in one step with nothing in between.
+    """
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.16)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "long job")
+    _run_to_rest(run)
+
+    warns = _of_kind(run, "budget")
+    assert warns, "the run never told the user it was approaching the ceiling"
+    assert warns[0]["spent_usd"] <= warns[0]["limit_usd"]
+    said = _all_text(run).lower()
+    assert "budget" in said or "allowance" in said
+
+
+def test_the_ceiling_message_says_what_it_means(monkeypatch, no_tools):
+    """"This run hit its budget ceiling" names no number, no unit, and does
+    not say whose limit it is — hence "was this a user limit?"."""
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.4)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "expensive")
+    _run_to_rest(run)
+
+    said = _all_text(run).lower()
+    assert "$" in _all_text(run), "the message states no amount"
+    assert "not a limit on your account" in said or "not your account" in said, \
+        "the message never answers 'was this a user limit?'"
+
+
+def test_hitting_the_ceiling_is_not_rendered_as_an_error(monkeypatch, no_tools):
+    """A budget ceiling is an expected end to a run, not a fault. Emitting it
+    as an `error` event paints a red block and settles the stage as failed —
+    over work that largely succeeded."""
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.4)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "expensive")
+    _run_to_rest(run)
+    assert not _of_kind(run, "error")
+    assert _of_kind(run, "done")[-1]["reason"] == "budget_spent"
+
+
+def test_the_work_can_be_carried_into_a_new_run(monkeypatch, no_tools):
+    """REPRODUCES "no way to carry the work over".
+
+    "Start a new one to continue" was advice the product could not act on: a
+    new run started cold, with no target, no plan and no record of what had
+    already been done.
+    """
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.4)
+    run = orch.create_run(owner="u1", anonymous=False)
+    run.plan = [{"step": "Fetch TEM-1", "status": "done"},
+                {"step": "Score a stability library", "status": "active"}]
+    orch.start(run, "make TEM-1 more thermostable")
+    _run_to_rest(run)
+
+    note = orch.handover_note(run)
+    assert "make TEM-1 more thermostable" in note      # the original goal
+    assert "Score a stability library" in note          # what is left
+
+    fresh = orch.create_run(owner="u1", anonymous=False)
+    orch.start(fresh, "carry on", carry_from=run)
+    _run_to_rest(fresh)
+    assert "Score a stability library" in json.dumps(fresh.history)
+    assert fresh.goal == run.goal
+
+
+def test_carry_over_never_inherits_another_owners_run(monkeypatch, no_tools):
+    """The handover lands verbatim in a system-adjacent context. It may only
+    ever come from a run the same person owns."""
+    _script(monkeypatch, [_msg_text("hi")])
+    theirs = orch.create_run(owner="u2", anonymous=False)
+    theirs.goal = "their secret project"
+    mine = orch.create_run(owner="u1", anonymous=False)
+    with pytest.raises(ValueError):
+        orch.start(mine, "carry on", carry_from=theirs)
+
+
+# --------------------------------------------------------------------------- #
+# 4. the "continue" loop
+# --------------------------------------------------------------------------- #
+def test_a_progressing_run_extends_itself_instead_of_asking(monkeypatch,
+                                                            no_tools):
+    """REPRODUCES the continue loop.
+
+    Before the fix, running out of the first 24 steps always parked the run
+    and made the user type "continue" — even though the cost cap, which is the
+    guard that actually matters, was barely touched. With work still landing
+    and money still on the clock, asking is friction, not supervision.
+    """
+    monkeypatch.setattr(orch, "MAX_STEPS", 3)
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(6)]
+            + [_msg_text("finished")],
+            cost=0.0001)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "long job")
+    assert _run_to_rest(run) == "done"
+    assert not _of_kind(run, "checkpoint"), \
+        "the user was asked to say 'continue' while the run was still working"
+    assert run.extensions >= 1
+
+
+def test_a_stalled_run_still_stops_and_asks(monkeypatch, no_tools):
+    """Auto-extension is for a run that is getting somewhere. A run that
+    burned a whole stretch without executing a single tool is looping, and
+    spending more on it silently is the failure mode extensions exist to
+    bound."""
+    monkeypatch.setattr(orch, "MAX_STEPS", 2)
+    # update_plan is not work: it changes nothing in the world.
+    _script(monkeypatch, [_msg_tool("update_plan",
+                                    {"steps": [{"step": "think", "status": "active"}]},
+                                    call_id=f"p{i}") for i in range(40)],
+            cost=0.0001)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "spin")
+    assert _run_to_rest(run) == "awaiting_input"
+    assert _of_kind(run, "checkpoint")
+
+
+def test_auto_extension_stays_bounded(monkeypatch, no_tools):
+    """Self-extending must not become an unbounded money tap."""
+    monkeypatch.setattr(orch, "MAX_STEPS", 2)
+    monkeypatch.setattr(orch, "AUTO_EXTENSIONS", 1)
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(400)],
+            cost=0.0001)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "loop forever")
+    assert _run_to_rest(run) == "awaiting_input"
+    assert run.extensions == 1
+    assert _of_kind(run, "checkpoint")
+
+
+def test_the_checkpoint_says_why_it_paused_in_plain_terms(monkeypatch, no_tools):
+    """"I've used this stretch of the run" describes nothing a user can act
+    on. Say what ran out and roughly how much more there is."""
+    monkeypatch.setattr(orch, "MAX_STEPS", 2)
+    monkeypatch.setattr(orch, "AUTO_EXTENSIONS", 0)
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(80)],
+            cost=0.0001)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "long job")
+    assert _run_to_rest(run) == "awaiting_input"
+    said = _all_text(run).lower()
+    assert "stretch of the run" not in said
+    assert "step" in said
+
+
+# --------------------------------------------------------------------------- #
+# the route: "start a new one to continue" has to be followable
+# --------------------------------------------------------------------------- #
+@pytest.fixture
+def client(monkeypatch):
+    from dee import server
+    app = server.create_app()
+    app.config.update(TESTING=True)
+    return app.test_client()
+
+
+def _as(monkeypatch, user_id):
+    import types
+    from dee import server
+    monkeypatch.setattr(server._auth, "get_auth",
+                        lambda: types.SimpleNamespace(anonymous=False,
+                                                      user_id=user_id))
+    monkeypatch.setattr(server._auth, "require_auth_or_quota", lambda: None)
+    monkeypatch.setattr(server._auth, "increment_anon_runs_on_response",
+                        lambda resp: resp)
+
+
+def test_replying_to_a_spent_run_routes_to_a_fresh_one(client, monkeypatch,
+                                                       no_tools):
+    """A run with no allowance left cannot answer. Re-spawning it would spend
+    one more model call to rediscover that and hand the user a second dead
+    end; 410 is the shape the cockpit already recovers from by starting a
+    fresh run — which is exactly what should happen."""
+    _as(monkeypatch, "u1")
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.4)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "expensive")
+    _run_to_rest(run)
+    assert run.budget_spent
+
+    r = client.post(f"/api/orchestrator/{run.run_id}/reply",
+                    json={"message": "keep going"})
+    assert r.status_code == 410
+    assert r.get_json()["kind"] == "run_budget_spent"
+    assert r.get_json()["carry_from"] == run.run_id
+
+
+def test_the_next_start_picks_the_stranded_work_up(client, monkeypatch,
+                                                   no_tools):
+    """The other half: the fresh run must land on the work, not a blank page.
+    Without this "start a new one to continue" is advice the product cannot
+    act on."""
+    _as(monkeypatch, "u1")
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(50)],
+            cost=0.4)
+    dead = orch.create_run(owner="u1", anonymous=False)
+    dead.plan = [{"step": "Score a stability library", "status": "active"}]
+    orch.start(dead, "make TEM-1 more thermostable")
+    _run_to_rest(dead)
+
+    _script(monkeypatch, [_msg_text("ok")])
+    r = client.post("/api/orchestrator/start", json={"message": "keep going"})
+    assert r.status_code == 200
+    fresh = orch.get_run(r.get_json()["run_id"])
+    _run_to_rest(fresh)
+    assert "make TEM-1 more thermostable" in json.dumps(fresh.history)
+    assert fresh.carried_from == dead.run_id
+
+
+def test_carry_from_another_owners_run_is_refused(client, monkeypatch, no_tools):
+    _as(monkeypatch, "u1")
+    theirs = orch.create_run(owner="u2", anonymous=False)
+    theirs.goal = "their secret project"
+    _script(monkeypatch, [_msg_text("ok")])
+    r = client.post("/api/orchestrator/start",
+                    json={"message": "hi", "carry_from": theirs.run_id})
+    assert r.status_code == 403
+    assert r.get_json()["kind"] == "carry_forbidden"
+
+
+def test_cost_checkpoints_before_it_hits_the_wall(monkeypatch, no_tools):
+    """With money nearly gone, park while there is still enough left to
+    finish something — a checkpoint the user can resume beats a ceiling they
+    cannot."""
+    monkeypatch.setattr(orch, "MAX_STEPS", 40)
+    _script(monkeypatch, [_msg_tool("fetch_sequence", {"text": "X"},
+                                    call_id=f"c{i}") for i in range(80)],
+            cost=0.05)
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "steady spend")
+    assert _run_to_rest(run) == "awaiting_input"
+    cps = _of_kind(run, "checkpoint")
+    assert cps and cps[-1]["reason"] == "cost"
+    assert run.cost_usd < 0.5           # parked with budget still on the clock

tests/test_run_target_binding.py

@@ -0,0 +1,312 @@
+"""The run's TARGET must belong to the run — reviewer log, 2026-07-30.
+
+Two failures in that log, one root cause. A reviewer pasted beta-lactamase
+TEM-1, worked with it for several turns, and then:
+
+  • asked "design a more thermostable variant of this protein" and the agent
+    "began referencing a protein from a different conversation instead of the
+    current conversation" — it planned against IsPETase, a target from
+    another run entirely;
+  • asked for the protein sequence AGAIN, one turn after being given it.
+
+Both are the same defect. Nothing in this codebase ever bound a run to what
+the run was ABOUT. The target existed only as a `tool` message buried in
+`run.history` — which compaction is free to evict — while the system prompt,
+rebuilt from scratch on every single step, carried:
+
+    WHAT THEY WERE ALREADY WORKING ON
+    This user has saved work. Do NOT ... propose starting from scratch on
+    something they already have:
+      - IsPETase thermostability (48 variants) — 6 results logged
+
+...and not one word about TEM-1. So the most prominent, most recently
+restated, most instruction-carrying thing in the model's context was a target
+from a DIFFERENT conversation, and the thing the user was actually talking
+about was a truncated JSON blob 40 messages back, or gone.
+
+These tests measure the model's INPUT, not its output — they capture the
+exact `messages` payload handed to OpenRouter and assert on it. A test that
+asserted "the agent didn't mention IsPETase" would be asserting something
+about a model we cannot run here; what we can prove is that the context we
+hand it no longer sets the trap.
+"""
+import json
+import time
+
+import pytest
+
+from dee.core import llm as _llm
+from dee.core import orchestrator as orch
+
+
+# An obvious stand-in, never a real sequence. Length is what these tests care
+# about; inventing a plausible TEM-1 CDS to sit in a fixture is exactly the
+# habit docs/ENGINEERING.md §9 forbids.
+_STUB_CDS = "ATGC" * 40
+
+
+def _cfg():
+    return _llm.OpenRouterConfig(
+        api_key="test-key", model="test/model", max_steps=8, max_cost_usd=0.5
+    )
+
+
+def _msg_tool(name, args, call_id="c1", content=None):
+    return {
+        "content": content,
+        "tool_calls": [{
+            "id": call_id,
+            "function": {"name": name, "arguments": json.dumps(args)},
+        }],
+    }
+
+
+def _msg_text(text):
+    return {"content": text, "tool_calls": []}
+
+
+def _run_to_rest(run, timeout=5.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if run.status in ("awaiting_input", "done", "error", "stopped"):
+            return run.status
+        time.sleep(0.01)
+    raise AssertionError(f"run never settled (status={run.status})")
+
+
+@pytest.fixture(autouse=True)
+def _configured(monkeypatch):
+    monkeypatch.setenv("OPENROUTER_API_KEY", "test-key")
+    monkeypatch.setenv("AGENT_MAX_COST_USD", "0.5")
+
+
+@pytest.fixture
+def bodies(monkeypatch):
+    """Every request body sent to OpenRouter, in order.
+
+    The whole point: assert on what the model was ASKED, since we cannot run
+    the model itself here.
+    """
+    sent = []
+
+    def make(messages, cost=0.001):
+        seq = list(messages)
+
+        def fake(config, body):
+            sent.append(body)
+            nxt = seq.pop(0) if seq else _msg_text("done")
+            return nxt, cost, 1234
+        monkeypatch.setattr(_llm, "call", fake)
+        return sent
+    return make
+
+
+@pytest.fixture
+def resolves_tem1(monkeypatch):
+    """fetch_sequence resolves the reviewer's pasted protein to a CDS."""
+    def _exec(name, args, anon, **kw):
+        if name == "fetch_sequence":
+            return {"ok": True, "kind": "sequence", "sequence": _STUB_CDS,
+                    "length": len(_STUB_CDS), "gene_symbol": "TEM-1",
+                    "label": "beta-lactamase TEM-1 · CDS 861 nt",
+                    "source": "input"}
+        return {"ok": True}
+    monkeypatch.setattr(orch._tools, "execute_tool", _exec)
+
+
+# --------------------------------------------------------------------------- #
+# 1. cross-conversation bleed
+# --------------------------------------------------------------------------- #
+def test_the_prompt_names_this_runs_target_not_another_conversations(
+        monkeypatch, bodies, resolves_tem1):
+    """REPRODUCES the reviewer's worst finding.
+
+    The run resolves TEM-1. The user's saved work — from other conversations —
+    is an IsPETase library. Before the fix the system prompt on the step AFTER
+    the resolve contained "IsPETase" and did NOT contain "TEM-1": the only
+    named target in the model's standing instructions was the wrong one.
+    """
+    import dee.auth as _auth
+    monkeypatch.setattr(_auth, "list_libraries", lambda u: [
+        {"id": "lib-pet", "name": "IsPETase thermostability", "n_variants": 48},
+    ])
+    monkeypatch.setattr(_auth, "list_de_outcomes", lambda u, lid: [{}] * 6)
+
+    sent = bodies([
+        _msg_tool("fetch_sequence", {"text": "MSIQHFRVAL…"}, call_id="f1"),
+        _msg_text("Resolved."),
+    ])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "design a more thermostable variant of this protein")
+    assert _run_to_rest(run) == "done"
+
+    # The step taken AFTER fetch_sequence returned — i.e. the one that plans
+    # the thermostability work.
+    system = sent[-1]["messages"][0]["content"]
+    assert "TEM-1" in system, (
+        "the run's own target is nowhere in the model's standing context")
+    assert "861" in system, "the resolved length is not bound to the run"
+
+    # The other conversation's work must still be visible, but marked as
+    # exactly that — not as the subject of this run.
+    assert "IsPETase" in system
+    i_target = system.index("TEM-1")
+    i_other = system.index("IsPETase")
+    assert i_other < i_target, (
+        "the bound target must be the LAST thing stated, so it is the most "
+        "proximate instruction, not the saved-work list")
+    assert "OTHER CONVERSATIONS" in system.upper(), (
+        "saved work is not labelled as belonging to other conversations")
+
+
+def test_the_bound_target_is_stated_as_non_substitutable(
+        monkeypatch, bodies, resolves_tem1):
+    """It is not enough to mention the target; the prompt has to say the
+    saved-work list is not a substitute for it. That sentence is the fix for
+    "began referencing a protein from a different conversation"."""
+    sent = bodies([
+        _msg_tool("fetch_sequence", {"text": "MSIQHFRVAL…"}, call_id="f1"),
+        _msg_text("Resolved."),
+    ])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "design a more thermostable variant of this protein")
+    _run_to_rest(run)
+
+    system = sent[-1]["messages"][0]["content"].lower()
+    assert "different conversation" in system
+
+
+def test_no_target_bound_means_no_target_block(monkeypatch, bodies):
+    """A run that has resolved nothing must not claim a target. Asserting a
+    bound target that does not exist would be its own fabrication."""
+    monkeypatch.setattr(orch._tools, "execute_tool",
+                        lambda name, args, anon, **kw: {"ok": True})
+    sent = bodies([_msg_text("hello")])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "hi")
+    _run_to_rest(run)
+    assert "TARGET OF THIS RUN" not in sent[0]["messages"][0]["content"]
+
+
+def test_a_failed_resolve_binds_nothing(monkeypatch, bodies):
+    """"Couldn't find the gene" must not become the run's target. Binding a
+    failure would put a name the tool explicitly refused into the standing
+    instructions as fact."""
+    monkeypatch.setattr(
+        orch._tools, "execute_tool",
+        lambda name, args, anon, **kw: {"ok": False,
+                                        "error": "Couldn't find “blaTEM” in ecoli."})
+    sent = bodies([
+        _msg_tool("fetch_sequence", {"text": "blaTEM"}, call_id="f1"),
+        _msg_text("no luck"),
+    ])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "fetch blaTEM")
+    _run_to_rest(run)
+    assert not run.target
+    assert "TARGET OF THIS RUN" not in sent[-1]["messages"][0]["content"]
+
+
+def test_the_user_can_move_the_target_within_a_run(monkeypatch, bodies):
+    """Binding must not be a cage. A second successful resolve is the user
+    changing subject, and the run has to follow them."""
+    seqs = {"n": 0}
+
+    def _exec(name, args, anon, **kw):
+        seqs["n"] += 1
+        first = seqs["n"] == 1
+        return {"ok": True, "kind": "gene", "sequence": _STUB_CDS,
+                "length": len(_STUB_CDS),
+                "gene_symbol": "TEM-1" if first else "MSTN",
+                "label": ("beta-lactamase TEM-1 · CDS 861 nt" if first
+                          else "MSTN · CDS 1128 nt"),
+                "source": "uniprot"}
+    monkeypatch.setattr(orch._tools, "execute_tool", _exec)
+
+    sent = bodies([
+        _msg_tool("fetch_sequence", {"text": "TEM-1"}, call_id="f1"),
+        _msg_tool("fetch_sequence", {"text": "MSTN"}, call_id="f2"),
+        _msg_text("switched"),
+    ])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "TEM-1 please")
+    _run_to_rest(run)
+
+    system = sent[-1]["messages"][0]["content"]
+    assert "MSTN" in system
+    assert run.target.get("gene_symbol") == "MSTN"
+
+
+# --------------------------------------------------------------------------- #
+# 2. "asked for protein sequence again even though it was given the sequence
+#    1 turn ago"
+# --------------------------------------------------------------------------- #
+def test_the_resolved_sequence_survives_compaction(monkeypatch, bodies,
+                                                   resolves_tem1):
+    """REPRODUCES the re-ask, mechanically.
+
+    This is the concrete half of the same defect and it needs no model
+    judgement at all. `_trim_history` evicts the oldest messages once history
+    passes MAX_HISTORY_MESSAGES, and `_digest_dropped` replaces them with
+    "tools already run: fetch_sequence". The LETTERS are destroyed. After that
+    the agent has no way to obtain the user's sequence except to ask for it —
+    which is exactly what the reviewer saw.
+
+    A long run reaches that cap easily: the reviewer's run ran past its step
+    budget and was extended by hand several times, and every step appends two
+    or three messages.
+    """
+    monkeypatch.setattr(orch, "MAX_HISTORY_MESSAGES", 8)
+    sent = bodies(
+        [_msg_tool("fetch_sequence", {"text": "MSIQHFRVAL…"}, call_id="f1")]
+        + [_msg_tool("check_prior_art", {"topic": "TEM-1"}, call_id=f"c{i}")
+           for i in range(12)]
+        + [_msg_text("done")]
+    )
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "design a more thermostable variant of this protein")
+    _run_to_rest(run)
+
+    # Compaction must actually have fired, or this test proves nothing.
+    assert [e for e in run.events if e["kind"] == "compacted"], \
+        "history never compacted — the reproduction did not run"
+
+    last = json.dumps(sent[-1]["messages"])
+    assert _STUB_CDS in last, (
+        "the user's own sequence is no longer anywhere in the model's "
+        "context — the only way left to get it is to ask them for it again")
+
+
+def test_the_prompt_says_the_sequence_is_already_in_hand(
+        monkeypatch, bodies, resolves_tem1):
+    """The standing instructions have to state, every step, that the sequence
+    is already resolved — otherwise "do you have the sequence?" is a
+    reasonable question for the model to ask."""
+    sent = bodies([
+        _msg_tool("fetch_sequence", {"text": "MSIQHFRVAL…"}, call_id="f1"),
+        _msg_text("ok"),
+    ])
+    run = orch.create_run(owner="u1", anonymous=False)
+    orch.start(run, "design a more thermostable variant of this protein")
+    _run_to_rest(run)
+
+    system = sent[-1]["messages"][0]["content"].lower()
+    assert "do not ask the user" in system
+    assert "already" in system
+
+
+def test_a_pinned_target_is_never_counted_as_free_context(monkeypatch,
+                                                          resolves_tem1):
+    """Pinning must stay bounded. A 400 kb pasted plasmid re-sent on every
+    step would be a bill, not a fix — over the cap we pin the identity and
+    say the letters were dropped rather than pinning them."""
+    monkeypatch.setattr(orch, "MAX_HISTORY_MESSAGES", 4)
+    monkeypatch.setattr(orch, "TARGET_PIN_MAX_NT", 32)
+    run = orch.create_run(owner="u1", anonymous=False)
+    run.target = {"label": "big construct", "sequence": "A" * 5000,
+                  "length": 5000}
+    run.history = [{"role": "user", "content": f"m{i}"} for i in range(10)]
+    orch._trim_history(run)
+    head = json.dumps(run.history[:3])
+    assert "A" * 100 not in head
+    assert "5,000" in head or "5000" in head

tests/test_search_diversity.py

@@ -0,0 +1,190 @@
+"""Cross-variant diversity in the returned variant library
+(`dee.optimizer.search._select_diverse` / `evolve`).
+
+The incident: a reviewing scientist ran TEM-1 beta-lactamase and got ten
+variants, nine of which carried the same substitution. ``search.py`` had a
+``duplicate_position_penalty`` — but that is a WITHIN-variant rule, stopping
+one variant mutating a residue twice. Nothing constrained the K variants as a
+SET, and because fitness is an additive sum of ΔLL, the top-K of that sum are
+near-copies of each other: whatever the best few single mutations are, they
+appear in nearly every returned variant.
+
+Measured on the real protein (scripts/measure_library_diversity.py, TEM-1
+BLAT_ECOLX fixture, ESM-2 35M, top-15% pool, k=10, 8 restarts x 1200 steps,
+seed 7):
+
+    before   H1M / H87L / M157T each in 10 of 10 variants; 8 distinct
+             substitutions across the whole library
+    after    most-shared substitution in 5 of 10; 14 distinct substitutions
+
+These tests pin the properties that make that safe: the best variant is never
+displaced, K is always filled, and the cap can be switched off.
+
+Pure pandas + the module under test. No torch, no network.
+"""
+import math
+
+import pandas as pd
+import pytest
+
+from dee.optimizer.search import SearchConfig, Variant, _select_diverse, evolve
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+def _pool_df(rows):
+    """rows := [(position, wt_aa, mut_aa, delta_ll)]"""
+    return pd.DataFrame(rows, columns=["position", "wt_aa", "mut_aa", "delta_ll"])
+
+
+def _dominated_pool():
+    """A pool with one runaway substitution plus a long tail of small ones.
+
+    This is the shape that produced the incident: a couple of substitutions
+    with ΔLL far above everything else, so every high-fitness combination
+    contains them.
+    """
+    rows = [(0, "A", "L", 9.0), (1, "C", "M", 4.0)]
+    rows += [(p, "G", "V", 0.5 - 0.001 * p) for p in range(2, 40)]
+    rows += [(p, "G", "I", 0.4 - 0.001 * p) for p in range(2, 40)]
+    return _pool_df(rows)
+
+
+def _occupancy(variants):
+    counts = {}
+    for v in variants:
+        for label in v.mutation_labels:
+            counts[label] = counts.get(label, 0) + 1
+    return counts
+
+
+def _cfg(**kw):
+    base = dict(k=10, max_mutations=5, min_mutations=2,
+                n_restarts=8, steps_per_restart=600, seed=7)
+    base.update(kw)
+    return SearchConfig(**base)
+
+
+# --------------------------------------------------------------------------- #
+# the headline property
+# --------------------------------------------------------------------------- #
+def test_no_substitution_may_occupy_more_than_its_share_of_the_library():
+    pool = _dominated_pool()
+
+    uncapped = evolve(pool, _cfg(max_substitution_share=1.0, max_position_share=1.0))
+    capped = evolve(pool, _cfg())
+
+    before = max(_occupancy(uncapped).values())
+    after = max(_occupancy(capped).values())
+    quota = math.ceil(SearchConfig().max_substitution_share * 10)
+
+    # The uncapped run must actually exhibit the problem, or this test is
+    # asserting nothing — the fixture has to reproduce the incident first.
+    assert before > quota, f"fixture did not reproduce the pile-up (max {before})"
+    assert after <= quota, f"cap not enforced: {after} > {quota}"
+
+
+def test_capping_increases_the_number_of_distinct_substitutions_offered():
+    pool = _dominated_pool()
+    uncapped = evolve(pool, _cfg(max_substitution_share=1.0, max_position_share=1.0))
+    capped = evolve(pool, _cfg())
+    assert len(_occupancy(capped)) > len(_occupancy(uncapped))
+
+
+def test_position_share_is_capped_too():
+    """H87L and H87I are different substitutions at the SAME residue. A library
+    that explores one position twenty ways is barely more informative than one
+    that explores it once."""
+    pool = _dominated_pool()
+    capped = evolve(pool, _cfg())
+    per_position = {}
+    for v in capped:
+        for m in v.mutations:
+            per_position[m.position] = per_position.get(m.position, 0) + 1
+    assert max(per_position.values()) <= math.ceil(SearchConfig().max_position_share * 10)
+
+
+# --------------------------------------------------------------------------- #
+# what the cap must NOT do
+# --------------------------------------------------------------------------- #
+def test_the_best_variant_is_never_displaced():
+    """Selection is greedy in fitness order and the counters start empty, so
+    rank 1 always survives the cap. If diversity could cost the top hit, the
+    feature would be trading away the product's actual answer."""
+    pool = _dominated_pool()
+    uncapped = evolve(pool, _cfg(max_substitution_share=1.0, max_position_share=1.0))
+    capped = evolve(pool, _cfg())
+    assert capped[0].key == uncapped[0].key
+    assert capped[0].fitness == uncapped[0].fitness
+
+
+def test_library_size_is_still_k():
+    """Deferred variants are backfilled, so a binding quota can never return a
+    shorter library than the plain top-K did."""
+    pool = _dominated_pool()
+    uncapped = evolve(pool, _cfg(max_substitution_share=1.0, max_position_share=1.0))
+    capped = evolve(pool, _cfg())
+    assert len(capped) == len(uncapped) == 10
+
+
+def test_backfill_fires_when_the_quota_cannot_be_met():
+    """A hall of fame that is genuinely all the same variant: the quota cannot
+    be satisfied, and the answer is still K variants, not 1."""
+    # A 3-substitution pool with 2-3 mutations per variant admits exactly four
+    # distinct variants, so ask for three of them.
+    muts = evolve(_pool_df([(0, "A", "L", 9.0), (1, "C", "M", 8.0), (2, "D", "K", 7.0)]),
+                  _cfg(k=3, max_mutations=3))
+    assert len(muts) == 3
+    # Every variant is drawn from that 3-substitution pool, so occupancy MUST
+    # exceed the 50% quota — the backfill is what makes that possible.
+    assert max(_occupancy(muts).values()) > math.ceil(0.5 * 3)
+
+
+def test_results_stay_ranked_by_fitness():
+    capped = evolve(_dominated_pool(), _cfg())
+    fits = [v.fitness for v in capped]
+    assert fits == sorted(fits, reverse=True)
+    assert [v.rank for v in capped] == list(range(1, len(capped) + 1))
+
+
+def test_share_of_one_restores_the_previous_behaviour_exactly():
+    """The off switch has to be a true no-op, so a caller can reproduce an old
+    library and so the before/after measurement is honest."""
+    pool = _dominated_pool()
+    off = evolve(pool, _cfg(max_substitution_share=1.0, max_position_share=1.0))
+    plain_top_k = sorted(
+        evolve(pool, _cfg(k=500, max_substitution_share=1.0, max_position_share=1.0)),
+        key=lambda v: v.fitness, reverse=True)[:10]
+    assert [v.key for v in off] == [v.key for v in plain_top_k]
+
+
+# --------------------------------------------------------------------------- #
+# _select_diverse in isolation
+# --------------------------------------------------------------------------- #
+def _v(labels, fitness):
+    from dee.optimizer.search import Mutation
+    muts = tuple(Mutation(position=int(l[1:-1]) - 1, wt_aa=l[0], mut_aa=l[-1], delta_ll=0.0)
+                 for l in labels)
+    return Variant(mutations=muts, fitness=fitness)
+
+
+def test_select_diverse_prefers_fitness_within_the_quota():
+    ranked = [
+        _v(["A1L", "C2M"], 10.0),
+        _v(["A1L", "D3K"], 9.0),
+        _v(["A1L", "E4R"], 8.0),   # quota for A1L is 1 at k=2, so this defers
+        _v(["F5W", "G6Y"], 1.0),
+    ]
+    cfg = SearchConfig(k=2, max_substitution_share=0.5, max_position_share=0.5)
+    out = _select_diverse(ranked, cfg)
+    assert [v.fitness for v in out] == [10.0, 1.0]
+
+
+def test_select_diverse_handles_an_empty_hall_of_fame():
+    assert _select_diverse([], SearchConfig()) == []
+
+
+@pytest.mark.parametrize("k", [0, -1])
+def test_select_diverse_refuses_a_nonpositive_k(k):
+    assert _select_diverse([_v(["A1L", "C2M"], 1.0)], SearchConfig(k=k)) == []

tests/test_static_minifies_cleanly.py

@@ -0,0 +1,94 @@
+"""Production serves MINIFIED assets. The source parsing is not the check.
+
+dee/server.py::_minified_asset runs every .js and .css through rjsmin/rcssmin
+before serving, so the file the browser executes is not the file in the repo.
+On 2026-08-01 an apostrophe inside a NESTED template literal —
+`${cond ? `the search's set …` : ''}` inside a larger template — desynced
+rjsmin's string tracking: it read the ' as the start of a single-quoted
+string. Isolated: a plain template containing an apostrophe minifies fine,
+and a nested template without one minifies fine; only the combination breaks.
+From that point it treated the `//` in
+
+    push(`https://alphafold.ebi.ac.uk/files/AF-${acc}-F1-model_v${v}.pdb`)
+
+as a line comment and deleted the rest of the line, closing backtick and
+paren included. `node --check` on the source passed. The SERVED file threw
+"SyntaxError: missing ) after argument list" on load, so nothing in app.js
+ran at all — no console error pointing at the real cause, just an app that
+booted dead. It was caught by driving a browser, not by reading the diff.
+
+The cheap always-on canary is below: URLs written in code must survive the
+minifier. When rjsmin desyncs it eats them, so the count drops. The strong
+check (node --check on the minified output) runs when node is present.
+"""
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+import dee.server as server
+
+STATIC = Path(server.__file__).resolve().parent / "static"
+
+# Assets this workstream owns. cockpit.js and the other surfaces belong to
+# other files; adding them here is fine, but a failure must be actionable by
+# whoever owns the file.
+JS_ASSETS = ["app.js"]
+CSS_ASSETS = ["science.css"]
+
+
+def _minify(name: str) -> str:
+    out = server._minified_asset(name)
+    assert out is not None, (
+        f"{name} would be served RAW — rjsmin/rcssmin missing, which also "
+        "silently changes the cache headers (see ENGINEERING.md §13.21)"
+    )
+    return out
+
+
+@pytest.mark.parametrize("name", JS_ASSETS)
+def test_urls_in_code_survive_minification(name):
+    """The canary for a desynced minifier: it eats from `//` to end of line."""
+    src = (STATIC / name).read_text(encoding="utf-8")
+    out = _minify(name)
+    # Comments are stripped, so the source count is an upper bound; what
+    # matters is that no URL inside actual code disappears. Every URL the
+    # runtime needs is in a string, and the minifier must preserve all of them.
+    for url in ("https://alphafold.ebi.ac.uk", "https://"):
+        assert url in out, f"{name}: minifier ate {url}"
+    assert out.count("https://") >= src.count("https://") - _comment_urls(src), (
+        f"{name}: minified output lost URLs that are not in comments — "
+        "rjsmin has almost certainly lost string context"
+    )
+
+
+def _comment_urls(src: str) -> int:
+    """URLs that legitimately disappear because they sit in a comment."""
+    n = 0
+    for line in src.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("//") or stripped.startswith("*") or stripped.startswith("/*"):
+            n += line.count("https://")
+    return n
+
+
+@pytest.mark.skipif(shutil.which("node") is None, reason="node not installed")
+@pytest.mark.parametrize("name", JS_ASSETS)
+def test_minified_js_still_parses(name, tmp_path):
+    """The real check, when a JS engine is available: does the SERVED file parse?"""
+    p = tmp_path / name
+    p.write_text(_minify(name), encoding="utf-8")
+    r = subprocess.run(["node", "--check", str(p)], capture_output=True, text=True)
+    assert r.returncode == 0, f"minified {name} does not parse:\n{r.stderr[:800]}"
+
+
+@pytest.mark.parametrize("name", CSS_ASSETS)
+def test_css_minifies_and_keeps_its_rules(name):
+    out = _minify(name)
+    src = (STATIC / name).read_text(encoding="utf-8")
+    # Every selector in the source must still be in the served file. A stray
+    # `*/` (ENGINEERING.md §13.5) silently drops everything after it.
+    for sel in (".crispr-scope-strip", ".crispr-scope-row", ".method-assumes",
+                ".run-objective", ".run-diversity"):
+        assert sel in src and sel in out, f"{name}: {sel} did not survive minification"