v1.0.1 — a failed attempt no longer strands HEAD on a loser

An attempt that raised after its edit was committed left the branch on a commit the loop never scored, so the next baseline read the loser. The champion is restored on the way out — and the restore declines when the tree is dirty outside the editable allowlist, because a `reset --hard` that discards somebody else's work to tidy up after ourselves is worse than the mess.

Also: ui/metrics.py brought in line with the house lint, version bumped in all three places it is declared, NAV points at the new entry, and the accumulated [Unreleased] changelog block is released as part of 1.0.1.

750 tests pass (was 748).

docs/CHANGELOG.md

@@ -6,18 +6,27 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-### Changed
+## [1.0.1] — 2026-09-15
 
-- **Removed hackathon framing from the public surfaces.** README, `pyproject.toml`
-  description, the package docstring, `CLAUDE.md`, and the active docs (autotune /
-  architecture / development / coach / yaml_schema / HANDOFF / NAV) no longer frame
-  mindXtrain as a hackathon submission; deleted `docs/HACKATHON.md` and
-  `docs/hackathon_submission.md`. The frozen `docs/blueprints/` and dated dev-blog
-  posts are preserved unchanged as the historical record. README now leads with the
-  dcoach proof loop.
 
 ### Added
 
+- **autoresearch — the keep/reset search, shipped whole.** The `research` command had
+  been in the CLI since the Hugging Face fork, but `mindxtrain/research/` was never
+  committed, so `mindxtrain research` raised `ModuleNotFoundError` on every checkout but
+  the author's. The package now ships: the declarative `AttemptContract`, the git fence
+  (commit-before-measure · editable allowlist · dedup-by-commit), the bounded attempt
+  runner with process-group teardown, the durable append-only ledger, the keep/reset
+  search loop, the Base anchor + `mindx_autoresearch_registry.sol`, the coach's read-only
+  observer page (`/coach/research`), the k8s researcher job, and the `attempt_diff` hash
+  in the provenance manifest — so the *edit* that earned a promotion is hashed into the
+  receipt, not just the resulting weights.
+- **The Console and Science rooms' own modules.** `ui/console.py` (Ollama chat, token
+  accounting, error explanations that say what to run) and `ui/reasoning.py` (the claims
+  / Socratic-questions / contradictions pass, aGLM when importable and an in-house
+  fallback otherwise), both previously uncommitted, both now covered by tests that need
+  no daemon, GPU or optional dependency.
+
 - **dcoach page + prompt-tools + decentralized panel.** New `/coach/dcoach` workflow
   page: one-click **Imprint & Prove** (persona/skills + advanced toggles) streams the
   proof loop live (`POST /coach/api/dcoach/run`, SSE) and shows the classroom before/after
@@ -70,6 +79,25 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **The default editor corrupted any editable that was not a flat TOML.** Its docstring
+  promised a no-op; the code stringified a `[table]` into `trainer = "{'lr': 0.001}"`,
+  then committed and measured that. It now checks flatness and declines, and
+  `_write_flat_toml` refuses non-scalars instead of repr-ing them. Strings escape through
+  `json.dumps`, so a value holding a quote or a backslash can no longer emit broken TOML.
+- **A failed attempt stranded HEAD on a loser.** When an attempt raised after its edit was
+  committed, the loop propagated the error and left the branch on a commit it had never
+  scored — so the next run's baseline read the loser. The champion is restored on the way
+  out. The restore is `reset --hard`, so it is taken only while the fence still passes: if
+  the tree is dirty outside the allowlist that work belongs to someone else, and it is left
+  exactly where it is.
+- **`mindxtrain.ui` demanded gradio for stdlib-only code.** The package eagerly imported
+  `.app`, so the optional `ui` extra was needed to reach `console`, `reasoning` or
+  `parse_log` — none of which import anything beyond the standard library. The
+  Gradio-backed exports (`build`, `main`, `VERSION`) resolve lazily via PEP 562; a box that
+  cannot spare the dependency can still parse a training log and talk to the daemon.
+- **The contradiction check was asymmetric**, though documented as a truth-table check:
+  it only fired when the negative claim happened to be written first.
+
 - **Imprint recall now measured under the trained conditioning.** `probe_recall` accepts an
   optional `system` prompt and the proof loop passes the persona's system prompt to both the
   before and after probes — matching the system turn the script rows train under. Without it
@@ -77,6 +105,20 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   imprint; the CPU proof loop now reports a strong positive Δ (e.g. 0.066→0.247) and an
   APPROVED verdict.
 
+### Changed
+
+- New and touched modules are ruff clean under the house config (unused imports, `typing`
+  modernisation). Pre-existing debt elsewhere is left alone rather than folded into this
+  release.
+
+- **Removed hackathon framing from the public surfaces.** README, `pyproject.toml`
+  description, the package docstring, `CLAUDE.md`, and the active docs (autotune /
+  architecture / development / coach / yaml_schema / HANDOFF / NAV) no longer frame
+  mindXtrain as a hackathon submission; deleted `docs/HACKATHON.md` and
+  `docs/hackathon_submission.md`. The frozen `docs/blueprints/` and dated dev-blog
+  posts are preserved unchanged as the historical record. README now leads with the
+  dcoach proof loop.
+
 ## [1.0.0] — 2026-06-11
 
 First production release. **CPU training is active end-to-end**; the GPU

docs/NAV.md

@@ -164,8 +164,9 @@ Target metrics + framework comparison.
 - [What's not measured (yet)](benchmarks.md#whats-not-measured-yet)
 
 ### [CHANGELOG](CHANGELOG.md)
-Version history (current: v1.0.0).
+Version history (current: v1.0.1).
 - [[Unreleased]](CHANGELOG.md#unreleased)
+- [[1.0.1] — 2026-09-15](CHANGELOG.md#101--2026-09-15)
 - [[1.0.0] — 2026-06-11](CHANGELOG.md#100--2026-06-11)
 - [[0.1.0] — 2026-05-06](CHANGELOG.md#010--2026-05-06)
 

mindxtrain/__init__.py

@@ -16,4 +16,4 @@ Layout per mindXtrain2.md §Part 4 "Repository layout":
     budget/      psutil-derived ResourceBudget (carry-over from aGLM)
 """
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"

mindxtrain/research/search.py

@@ -21,7 +21,12 @@ from pathlib import Path
 from mindxtrain.autotune.feedback import suggest_next_params
 from mindxtrain.research.attempt import AttemptResult, run_attempt
 from mindxtrain.research.contract import AttemptContract
-from mindxtrain.research.guard import git, repo_root
+from mindxtrain.research.guard import (
+    ResearchAbort,
+    assert_clean_and_committed,
+    git,
+    repo_root,
+)
 from mindxtrain.research.ledger import Ledger
 
 ProposeEdit = Callable[[AttemptContract, AttemptResult, Ledger, Path], None]
@@ -110,6 +115,26 @@ def _run_dir(log_root: Path, researcher: str, i: int) -> Path:
     return Path(log_root) / researcher / f"attempt-{i:03d}"
 
 
+def _restore_champion(contract: AttemptContract, champion: AttemptResult, root: Path) -> bool:
+    """Put HEAD back on the champion after a failed attempt. Returns whether it did.
+
+    An attempt that raises *after* its edit was committed would otherwise leave HEAD parked
+    on a loser the loop never scored — the opposite of the keep/reset contract, and not what
+    the next run's baseline should read.
+
+    The reset is `--hard`, so it is only taken when the fence still passes. If the tree is
+    dirty outside the editable allowlist that dirt belongs to someone else, and discarding it
+    to tidy up after ourselves would be worse than the mess: we leave everything untouched and
+    let the caller see the failure with the tree intact.
+    """
+    try:
+        assert_clean_and_committed(contract.editable, root)
+    except ResearchAbort:
+        return False
+    git("reset", "--hard", champion.commit, cwd=root)
+    return True
+
+
 def search(
     contract: AttemptContract,
     researcher: str,
@@ -131,7 +156,13 @@ def search(
         propose_edit(contract, champion, ledger, root)
         if not _commit_editable(contract.editable, f"attempt {i}", root):
             break  # converged: no new edit proposed
-        result = run_attempt(contract, researcher, _run_dir(log_root, researcher, i), ledger, root=root)
+        try:
+            result = run_attempt(
+                contract, researcher, _run_dir(log_root, researcher, i), ledger, root=root
+            )
+        except Exception:
+            _restore_champion(contract, champion, root)  # never strand HEAD on a loser
+            raise
         if _improved(result.value, champion.value, contract.mode, contract.min_improvement):
             champion = result
         else:

mindxtrain/ui/app.py

@@ -36,7 +36,7 @@ import gradio as gr
 from .metrics import RunMetrics, parse_log  # noqa: F401  (parse_log re-exported for tests)
 from .theme import CSS, theme
 
-VERSION = "1.0.0"
+VERSION = "1.0.1"
 HOME = Path(os.environ.get("MINDXTRAIN_HOME") or Path(__file__).resolve().parents[2])
 RECIPES = HOME / "mindxtrain" / "train" / "recipes"
 TIERS = ["Basic", "Advanced", "Scientific"]

mindxtrain/ui/metrics.py

@@ -23,7 +23,7 @@ import re
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 _DICT = re.compile(r"\{'(?:loss|eval_loss|train_runtime)'.*?\}")
 _TQDM = re.compile(r"(?:(?P<label>[A-Za-z][A-Za-z ._-]{2,30}):\s*)?(?P<pct>\d+)%\|[^|]*\|\s*"
@@ -32,7 +32,7 @@ _THROTTLE = re.compile(r"cpu_throttle overridden:\s*percent=(\d+)\s*nice=(\d+)")
 _TOKENIZING = re.compile(r"Tokenizing train dataset:.*?(\d+)/(\d+)")
 
 
-def _secs(hms: str) -> Optional[float]:
+def _secs(hms: str) -> float | None:
     if not hms or "?" in hms:
         return None
     parts = [float(x) for x in hms.split(":")]
@@ -41,7 +41,7 @@ def _secs(hms: str) -> Optional[float]:
     return parts[0] * 3600 + parts[1] * 60 + parts[2]
 
 
-def _fmt_secs(s: Optional[float]) -> str:
+def _fmt_secs(s: float | None) -> str:
     if s is None:
         return "—"
     s = int(s)
@@ -50,31 +50,31 @@ def _fmt_secs(s: Optional[float]) -> str:
 
 @dataclass
 class RunMetrics:
-    steps: List[Dict[str, float]] = field(default_factory=list)
-    evals: List[Dict[str, float]] = field(default_factory=list)
-    final: Dict[str, float] = field(default_factory=dict)
-    progress: Dict[str, Any] = field(default_factory=dict)        # the TRAINING bar
-    eval_progress: Dict[str, Any] = field(default_factory=dict)   # the evaluation loop's own bar
-    throttle: Dict[str, int] = field(default_factory=dict)
-    warnings: List[str] = field(default_factory=list)
-    phases: List[str] = field(default_factory=list)
-    dataset_rows: Optional[int] = None
+    steps: list[dict[str, float]] = field(default_factory=list)
+    evals: list[dict[str, float]] = field(default_factory=list)
+    final: dict[str, float] = field(default_factory=dict)
+    progress: dict[str, Any] = field(default_factory=dict)        # the TRAINING bar
+    eval_progress: dict[str, Any] = field(default_factory=dict)   # the evaluation loop's own bar
+    throttle: dict[str, int] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    phases: list[str] = field(default_factory=list)
+    dataset_rows: int | None = None
 
     # ── the few fields other rooms read ──
     @property
-    def last_step(self) -> Optional[int]:
+    def last_step(self) -> int | None:
         return self.progress.get("step") or (len(self.steps) or None)
 
     @property
-    def train_loss(self) -> Optional[float]:
+    def train_loss(self) -> float | None:
         return self.final.get("train_loss") or (self.steps[-1].get("loss") if self.steps else None)
 
     @property
-    def eval_loss(self) -> Optional[float]:
+    def eval_loss(self) -> float | None:
         return self.evals[-1].get("eval_loss") if self.evals else None
 
     # ── derived, honestly ──
-    def rate(self) -> Dict[str, Optional[float]]:
+    def rate(self) -> dict[str, float | None]:
         """Throughput as the trainer reports it — seconds per step, tokens per second, ETA."""
         s_it = self.progress.get("s_per_it")
         tok = self.steps[-1].get("num_tokens") if self.steps else None
@@ -84,7 +84,7 @@ class RunMetrics:
                 "tokens_per_s": (per_step / s_it) if (per_step and s_it) else None,
                 "eta_s": self.progress.get("eta_s"), "elapsed_s": self.progress.get("elapsed_s")}
 
-    def trend(self, key: str, window: int = 10) -> Optional[float]:
+    def trend(self, key: str, window: int = 10) -> float | None:
         """Change in a metric over the last `window` logged steps (late mean − early mean)."""
         vals = [s[key] for s in self.steps if key in s and isinstance(s[key], (int, float))]
         if len(vals) < 4:
@@ -92,7 +92,7 @@ class RunMetrics:
         w = min(window, len(vals) // 2)
         return round(sum(vals[-w:]) / w - sum(vals[:w]) / w, 4)
 
-    def diagnose(self) -> List[str]:
+    def diagnose(self) -> list[str]:
         """What an operator would want said out loud. Each line is a fact plus its consequence."""
         out = list(self.warnings)
         dl = self.trend("loss")
@@ -123,7 +123,7 @@ class RunMetrics:
         return out
 
     # ── rendering ──
-    def headline(self, running: bool, started: Optional[float] = None) -> str:
+    def headline(self, running: bool, started: float | None = None) -> str:
         p = self.progress
         bar = ""
         if p.get("total"):
@@ -142,7 +142,7 @@ class RunMetrics:
         diag = "<br>".join("· " + d for d in self.diagnose()[:4])
         return f"<div class='mx-kiln'>{bar}{' · '.join(bits)}<div class='mx-diag'>{diag}</div></div>"
 
-    def rows(self, scientific: bool = False) -> List[List[Any]]:
+    def rows(self, scientific: bool = False) -> list[list[Any]]:
         """metric · value · unit · where it came from."""
         s = self.steps[-1] if self.steps else {}
         e = self.evals[-1] if self.evals else {}
@@ -177,7 +177,7 @@ class RunMetrics:
             ]
         return rows
 
-    def frame(self) -> Dict[str, List[Any]]:
+    def frame(self) -> dict[str, list[Any]]:
         """Long-form rows for the plot: loss, token accuracy, and lr normalised to its own max."""
         xs, ms, vs = [], [], []
         lrs = [s.get("learning_rate") for s in self.steps if isinstance(s.get("learning_rate"), (int, float))]
@@ -195,7 +195,7 @@ class RunMetrics:
     def tail(log: Path, n: int = 60) -> str:
         try:
             lines = [ln.rstrip() for ln in log.read_text(errors="replace").splitlines() if ln.strip()]
-        except Exception:  # noqa: BLE001
+        except Exception:
             return ""
         return "\n".join(ln[-400:] for ln in lines[-n:])
 
@@ -213,16 +213,16 @@ class RunMetrics:
         return str(v)
 
 
-def parse_log(log: Optional[Path]) -> RunMetrics:
+def parse_log(log: Path | None) -> RunMetrics:
     """Read a training log into metrics. Tolerant by design: a half-written line is skipped, never fatal."""
     m = RunMetrics()
     if not log:
         return m
     try:
         text = Path(log).read_text(errors="replace")
-    except Exception:  # noqa: BLE001
+    except Exception:
         return m
-    bars: List[Dict[str, Any]] = []
+    bars: list[dict[str, Any]] = []
     for raw in text.splitlines():
         line = raw.strip()
         if not line:
@@ -230,7 +230,7 @@ def parse_log(log: Optional[Path]) -> RunMetrics:
         for d in _DICT.findall(line):
             try:
                 rec = ast.literal_eval(d)
-            except Exception:  # noqa: BLE001
+            except Exception:
                 continue
             rec = {k: (float(v) if isinstance(v, str) and re.fullmatch(r"[-+0-9.eE]+", v) else v) for k, v in rec.items()}
             if "train_runtime" in rec:
@@ -276,7 +276,7 @@ def parse_log(log: Optional[Path]) -> RunMetrics:
         # eval bar at the end, because tqdm redraws each eval bar many times. The one that holds is
         # the CLOCK: the training bar's elapsed runs for the whole run (1:10:00 here) while every eval
         # bar's elapsed restarts from zero.
-        by_total: Dict[int, float] = {}
+        by_total: dict[int, float] = {}
         for b in bars:
             by_total[b["total"]] = max(by_total.get(b["total"], 0.0), b.get("elapsed_s") or 0.0)
         train_total = max(by_total, key=lambda t: by_total[t])

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mindxtrain"
-version = "1.0.0"
+version = "1.0.1"
 description = "Production training framework for fine-tuning open-weight LLMs on AMD MI300X and serving them through an OpenAI-compatible API."
 requires-python = ">=3.12,<3.13"
 license = { text = "Apache-2.0" }

tests/test_research_search.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import subprocess
 import sys
 import tomllib
+from importlib import import_module
 from pathlib import Path
 
 import pytest
@@ -39,6 +40,18 @@ def _git(repo: Path, *args: str) -> None:
     subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, text=True)
 
 
+def _head(repo: Path) -> str:
+    out = subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"],
+                         check=True, capture_output=True, text=True)
+    return out.stdout.strip()
+
+
+def _status(repo: Path) -> str:
+    out = subprocess.run(["git", "-C", str(repo), "status", "--porcelain"],
+                         check=True, capture_output=True, text=True)
+    return out.stdout.strip()
+
+
 @pytest.fixture
 def repo(tmp_path: Path) -> Path:
     _git(tmp_path, "init", "-b", "main")
@@ -223,3 +236,59 @@ def test_flat_toml_roundtrips_awkward_strings(tmp_path: Path) -> None:
 def test_flat_toml_refuses_a_nested_value(tmp_path: Path) -> None:
     with pytest.raises(TypeError, match="not a flat TOML scalar"):
         _write_flat_toml(tmp_path / "p.toml", {"trainer": {"lr": 0.1}})
+
+
+# --- a failed attempt must not strand HEAD on a loser ------------------------------------
+
+
+def _raise_after_baseline(monkeypatch, exc: Exception):
+    """Let the baseline attempt run for real, then fail every attempt after it."""
+    # import_module, not `from mindxtrain.research import search`: the package re-exports the
+    # search *function* under that name, which shadows the submodule.
+    search_mod = import_module("mindxtrain.research.search")
+
+    real = search_mod.run_attempt
+    calls = {"n": 0}
+
+    def flaky(*a, **kw):  # type: ignore[no-untyped-def]
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return real(*a, **kw)
+        raise exc
+
+    monkeypatch.setattr(search_mod, "run_attempt", flaky)
+    return calls
+
+
+def test_failed_attempt_restores_the_champion(repo: Path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    """Regression: the loop used to leave HEAD on the unscored attempt commit."""
+    _raise_after_baseline(monkeypatch, RuntimeError("runner exploded"))
+    head_before = _head(repo)
+
+    with pytest.raises(RuntimeError, match="runner exploded"):
+        search(_contract(repo), "r", repo / "out", 3, _increasing_edit(1.0), root=repo)
+
+    assert _head(repo) == head_before  # back on the champion, not the loser
+    assert float((repo / "value.txt").read_text()) == 1.0
+    assert not _status(repo)  # and the tree is clean
+
+
+def test_failed_attempt_never_discards_unrelated_work(repo: Path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    """`reset --hard` is refused when the dirt outside the allowlist is somebody else's.
+
+    The stray file lands *during* the attempt — a colleague saving work in the same tree
+    while the search runs — so the baseline's own fence passes and the refusal is the
+    restore's decision, not an abort on the way in.
+    """
+    _raise_after_baseline(monkeypatch, RuntimeError("runner exploded"))
+    stray = repo / "someone_elses_work.txt"
+
+    def edit_and_intrude(contract, champion, ledger, root) -> None:  # type: ignore[no-untyped-def]
+        path = root / "value.txt"
+        path.write_text(f"{float(path.read_text()) + 1.0}\n", encoding="utf-8")
+        stray.write_text("hours of it\n", encoding="utf-8")
+
+    with pytest.raises(RuntimeError, match="runner exploded"):
+        search(_contract(repo), "r", repo / "out", 3, edit_and_intrude, root=repo)
+
+    assert stray.read_text(encoding="utf-8") == "hours of it\n"  # untouched by the cleanup