distill: mine "A fails here, B works" repair pitfalls

docs/features/distill.md

@@ -4,6 +4,7 @@ paths:
   - "kypp/distill.py"
   - "kypp/batch_distill.py"
   - "kypp/episodes.py"
+  - "kypp/repairs.py"
   - "scripts/eval_episodes.py"
   - "eval/episodes/*"
   - "docs/episode-extraction-evaluation.md"
@@ -12,6 +13,7 @@ entry:
   - "kypp/batch_distill.py"
 tests:
   - "tests/test_episodes.py"
+  - "tests/test_repairs.py"
 ---
 # Distillation
 
@@ -20,6 +22,22 @@ distiller runs when `KYPP_DISTILL_MODEL` is set (`claude`, `codex` or an ollama
 
 ## Gotchas
 - Without `KYPP_DISTILL_MODEL` you only get heuristic, failure-mined pitfalls.
+- Repair pitfalls (`kypp/repairs.py`) run with or without a model: a shell command that fails
+  with command-not-found, a missing module or a missing env var, followed in the same session by a
+  form that works (`uv run pytest`, `.venv/bin/python`, `V=x cmd`). The subject names only what
+  failed, so a second session's repair lands on the same subject and the K=2 gate accepts it; a
+  one-session quirk stays a candidate. A repair suppresses the generic "`<tool>` repeatedly
+  failed" pitfall for the failures it explains.
+- A repair needs a later run with a confirmed success (Claude's `completed`, Codex's exit 0) that
+  runs the same thing: the same script or `-m module` for a missing module or env var (inline
+  `-c` code never counts). Only a segment followed by nothing but `&&`, outside any `||` or pipe,
+  counts as having succeeded, since a chain exits with its last command. It is
+  skipped when the original works later without the fix, when the thing was installed in between,
+  when the later run only probes (`--version`, `--help`), or when the working form is a host path.
+- Values are written only for a short allowlist of env vars (`PYTHONPATH`, `NODE_ENV`, ...), and
+  never one with `@` in it. A fix runs the command by path or behind a known wrapper (`_WRAPPERS`:
+  `uv run`, `python -m`, `npx`, ...). Nothing else counts, so `touch pytest` isn't a fix, and flags
+  and their values (`--token X`, `-e K=V`) never reach a claim.
 - If the LLM distiller fails, it falls back to the heuristic distiller rather than raising.
 - With `TYPESAFE_API_KEY` or `KYPP_DECIDER_URL` (a local strands-decider) set, and `kypp[s1]`
   installed, a System One gate drops drafts scoring

kypp/distill.py

@@ -27,7 +27,7 @@
 from typing import TYPE_CHECKING, Protocol
 
 from . import episodes as _episodes
-from . import s1
+from . import repairs, s1
 from .vocab import OLLAMA_DEFAULT_HOST, TYPES  # single-sourced vocabulary (turso-free leaf)
 
 if TYPE_CHECKING:
@@ -169,14 +169,32 @@ def distill(self, trace: Trace) -> list[ClaimDraft]:
                 f"in this session's observations", 0.6))
         if trace.run_failed:
             drafts.append(ClaimDraft("pitfall", "run failed", _trunc(trace.run_failed), 0.5))
+        fixes, explained = repairs.mine(trace)
         for name, n in trace.tool_failures.items():
-            if n >= 2:
-                sample = next(a for a in trace.actions if a.failed and a.name == name)
+            unexplained = [a for i, a in enumerate(trace.actions)
+                           if a.failed and a.name == name and i not in explained]
+            # A failure a repair explains is said better by the repair ("A fails, B works").
+            if n >= 2 and unexplained:
+                sample = unexplained[0]
                 drafts.append(ClaimDraft(
                     "pitfall", f"{name} repeatedly failed",
                     _trunc(f"`{name}` errored {n}x this run; e.g. {sample.output}"), 0.4,
                     code_refs=_refs_from(sample.input)))
-        return drafts
+        return drafts + fixes
+
+
+class WithRepairs:
+    """Add the deterministic repair pitfalls to another distiller's drafts. The LLM distiller is told
+    to skip environment artifacts; a repair is one only until a second session hits it, and then
+    the K=2 gate accepts it."""
+
+    def __init__(self, inner: Distiller):
+        self.inner = inner
+
+    def distill(self, trace: Trace) -> list[ClaimDraft]:
+        drafts = self.inner.distill(trace)
+        taken = {d.subject for d in drafts}
+        return drafts + [d for d in repairs.mine(trace)[0] if d.subject not in taken]
 
 
 # LLM_DISTILL_PROMPT + _SCHEMA are what the model is ASKED for (model-agnostic, code-grounded claims).
@@ -404,7 +422,8 @@ def distiller_from_env() -> Distiller:
     A configured System One model (see kypp.s1) adds the write gate on top. The seam-config analog
     of store.store_from_env."""
     model = os.environ.get("KYPP_DISTILL_MODEL")
-    inner = (FallbackDistiller(LLMDistiller(_complete_from_model(model), episodes=_episodes.extractor_from_env()),
+    inner = (FallbackDistiller(WithRepairs(LLMDistiller(_complete_from_model(model),
+                                                        episodes=_episodes.extractor_from_env())),
                                HeuristicDistiller())
              if model else HeuristicDistiller())
     via = s1.client()