fix(fit,runtime): guard against all-candidate failures and stale pipeline (0.3.3)

When all surrogate candidates fail to train, search_best_surrogate() returns
(None, None, None). build_global() and _build_accepting_stage() now check for
a None clf before proceeding and return a structured failure state instead of
crashing with a TypeError.

Router.load() would silently load a stale pipeline.joblib left on disk from a
previous fit, even when manifest.json reports selected_method: null. It now
raises a clear ValueError explaining the state so the caller is never silently
served a pipeline the parity gate already rejected.

Author: adrida

CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to TRACER are recorded here. This project follows semantic
 versioning.
 
+## 0.3.3 (2026-06)
+
+### Fixed
+- `build_global()` and `_build_accepting_stage()` no longer crash with a
+  `TypeError` when all surrogate candidates fail to train. They now return a
+  structured failure state, consistent with every other non-deployable path.
+- `Router.load()` now raises a clear `ValueError` when `manifest.json`
+  reports `selected_method: null`, instead of silently loading a stale
+  `pipeline.joblib` left on disk from a previous fit.
+
+## 0.3.2 (2026-06)
+
+### Fixed
+- `load_traces()` now reports the correct 1-indexed file line number in
+  `ValueError` messages. Previously the count excluded blank lines, so
+  the reported line was lower than the actual position of the bad record.
+
 ## 0.3.1 (2026-06)
 
 ### Changed

src/tracer/__init__.py

@@ -78,7 +78,7 @@ def __getattr__(name: str):
     return obj
 
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     # Core API

src/tracer/cloud/client.py

@@ -39,7 +39,7 @@ class CloudError(RuntimeError):
 
 # A real User-Agent: the default "Python-urllib/x" trips Cloudflare's bot
 # protection on app.tracerml.ai (HTTP 403, CF error 1010).
-USER_AGENT = "tracer-cli/0.3.2 (+https://tracerml.ai)"
+USER_AGENT = "tracer-cli/0.3.3 (+https://tracerml.ai)"
 
 
 def _http(

src/tracer/fit/pipeline.py

@@ -252,6 +252,10 @@ def build_global(split, target_ta, alpha: float = 0.1, log: Optional[LogFn] = No
     clf, name, val_m = search_best_surrogate(
         split["X_train"], split["y_train"], split["X_val"], split["y_val"],
         on_candidate=_candidate_log(log), skip=skip)
+    if clf is None:
+        log("  build_global: all surrogate candidates failed (no model trained)")
+        return {"method": "global", "stages": [], "summary": {
+            "status": "no_stage", "coverage_cal_total": 0.0}}
     log(f"  build_global: surrogate done in {time.perf_counter()-t0:.1f}s  best={name} f1={val_m['teacher_f1']:.3f}")
     preds_cal = clf.predict(split["X_cal"])
     n_cal = len(preds_cal)
@@ -297,6 +301,9 @@ def _build_accepting_stage(X_tr, y_tr, X_val, y_val, X_cal, y_cal, target_ta, st
     log(f"  {stage_name}: surrogate sweep on {len(X_tr)} train / {len(X_val)} val")
     clf, name, val_m = search_best_surrogate(
         X_tr, y_tr, X_val, y_val, on_candidate=_candidate_log(log), skip=skip)
+    if clf is None:
+        log(f"  {stage_name}: all surrogate candidates failed (no model trained)")
+        return None
     log(f"  {stage_name}: surrogate done in {time.perf_counter()-t0:.1f}s  best={name} f1={val_m['teacher_f1']:.3f}")
     preds_val, probs_val = _predict(clf, X_val)
     preds_cal, probs_cal = _predict(clf, X_cal)

src/tracer/runtime/router.py

@@ -56,6 +56,12 @@ def load(cls, artifact_dir: Union[str, Path], embedder=None) -> "Router":
         import json as _json
         artifact_dir = Path(artifact_dir)
         manifest = load_manifest(artifact_dir / "manifest.json")
+        if manifest.selected_method is None:
+            raise ValueError(
+                f"No router is deployed in {artifact_dir}: the parity gate did not "
+                "certify any method (selected_method is null in manifest.json). "
+                "Run tracer.fit() again with more data or a lower target_teacher_agreement."
+            )
         bundle = load_pipeline(artifact_dir)
         stages = bundle["pipeline"]["stages"]
         label_space = bundle["label_space"]