diff --git a/docs/features/distill.md b/docs/features/distill.md
index fcd689d..f901b10 100644
--- a/docs/features/distill.md
+++ b/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
diff --git a/kypp/distill.py b/kypp/distill.py
index c058c61..0765110 100644
--- a/kypp/distill.py
+++ b/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()
diff --git a/kypp/repairs.py b/kypp/repairs.py
new file mode 100644
index 0000000..2c87f0d
--- /dev/null
+++ b/kypp/repairs.py
@@ -0,0 +1,474 @@
+"""repairs.py — §0 trace → "A fails here, B works" pitfalls, mined without a model.
+
+An agent often rediscovers the same environment fact by failing at it: `pytest` is not on PATH but
+`uv run pytest` works, `python` can't import the project but `.venv/bin/python` can, a script needs
+`PYTHONPATH=src`. Within one session this mines a failing shell command followed by a later one that
+does the same thing another way and works, and states both forms. The subject names only what failed
+(never the fix), so the same fact from a second session reuses the subject and the arbiter's K=2
+gate accepts it: one session's quirk stays a candidate, a recurring one becomes memory.
+
+Idea borrowed from TokenEconomizer's environment facts (microsoft/TokenEconomizer, Apache-2.0):
+its FormRepair and EnvValue families. Re-implemented here over §0 actions.
+"""
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .distill import Action, ClaimDraft, Trace
+
+# Shell tools as each harness names them (Claude: Bash; Codex: shell / exec_command; pillbox: bash).
+_SHELL_TOOLS = {"bash", "shell", "exec_command", "local_shell", "run_shell_command"}
+
+_OPS = {";", "&&", "||", "|", "&"}
+_SETUP = {"cd", "source", ".", "export", "set", "pushd", "unset", ":"}
+_ASSIGN = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.S)
+_WORD = re.compile(r"^[A-Za-z0-9._+-]{1,64}$")  # a command or module name we're willing to quote
+# A missing command, as bash, sh, zsh and env each word it.
+_CMD_MISSING = [re.compile(p) for p in (
+    r"(?:^|\s|:)([A-Za-z0-9._+-]+): (?:command )?not found",
+    r"command not found: ([A-Za-z0-9._+-]+)",
+    r"env: '?([A-Za-z0-9._+-]+)'?: No such file or directory",
+)]
+_MOD_MISSING = [re.compile(p) for p in (
+    r"No module named '?([A-Za-z0-9_.]+)'?",
+    r"Cannot find module '([^']+)'",
+)]
+_ENV_MISSING = [re.compile(p) for p in (
+    r"KeyError: '([A-Z][A-Z0-9_]+)'",
+    r"\b([A-Z][A-Z0-9_]{2,})\b (?:environment variable )?(?:is )?(?:not set|unset|required|missing)",
+    r"(?:environment variable|env var)s? '?([A-Z][A-Z0-9_]{2,})'? (?:is )?(?:not set|unset|required|missing)",
+    r"[Mm]issing (?:required )?(?:environment variable|env var) '?([A-Z][A-Z0-9_]{2,})'?",
+)]
+# The wrappers a fix may run the command behind (or none, with the command given by path). Any
+# other prefix (`which`, `touch`, `test -x`, `docker run -e K=V`) doesn't run it, or may carry a
+# credential.
+_WRAPPERS = {("uv", "run"), ("uvx",), ("poetry", "run"), ("pipenv", "run"), ("pdm", "run"),
+             ("hatch", "run"), ("rye", "run"), ("python", "-m"), ("python3", "-m"), ("npx",),
+             ("bunx",), ("bun", "x"), ("bun", "run"), ("pnpm", "exec"), ("pnpm", "dlx"),
+             ("npm", "exec"), ("yarn",), ("yarn", "exec"), ("bundle", "exec")}
+_INSTALLS = {"install", "add", "i", "sync"}  # a run with one of these may have installed anything
+# Arguments that only ask the command about itself: running it this way proves nothing works.
+_PROBE_ARGS = {"--version", "-V", "version", "--help", "-h", "help"}
+_PROBE_FLAGS = {"--version", "-V", "--help", "-h"}  # with any other arguments it still only probes
+# Only these variables' values are written; any other value may be a credential (a DATABASE_URL
+# carries a password), so a fact names the variable and never repeats its value.
+_SAFE_ENV = {"PYTHONPATH", "NODE_ENV", "CI", "TZ", "LANG", "LC_ALL", "RUST_BACKTRACE", "RUST_LOG",
+             "DEBUG", "PORT", "HOST", "FORCE_COLOR", "NO_COLOR", "PYTHONUNBUFFERED", "PYTHONDONTWRITEBYTECODE"}
+_USERINFO = re.compile(r"://[^/\s]*@")
+_EXIT_CODE = re.compile(r"(?:Exit code:?|\"exit_code\":|Process exited with code)\s*(-?\d+)")
+# Any absolute or home-relative path is this host's, wherever it is rooted.
+_ABS = re.compile(r"(?:^|[\s:=])[/~]")
+
+
+@dataclass
+class _Run:
+    i: int
+    command: str
+    segments: list[list[str]]  # each shell segment, tokenized, env assignments kept as leading tokens
+    proven: list[list[str]]  # the segments the run's success proves ran and succeeded
+    output: str
+    ok: bool  # confirmed to have succeeded; a run with no recorded outcome is neither
+    may_fail: bool  # failed, or its exit status could hide a failure (`pytest | tail`, `pytest; echo`)
+    where: tuple | None  # where the shell was when it ran; None when a `cd` follows a command, so the place is unclear
+    installs: bool  # runs an install or sync
+    sets_env: bool  # in a persistent shell, exports, unsets or sources something, or assigns on its own
+    reads_input: bool  # a `<` input may choose what the script does, so two runs of it can differ
+
+
+def _command_of(a: Action) -> str | None:
+    if (a.name or "").lower() not in _SHELL_TOOLS or not isinstance(a.input, dict):
+        return None
+    c = a.input.get("command", a.input.get("cmd"))
+    if isinstance(c, list):  # codex: ["bash", "-lc", "<script>"] or argv
+        c = c[-1] if len(c) >= 3 and c[1] in ("-c", "-lc") else shlex.join(map(str, c))
+    return c.strip() if isinstance(c, str) and c.strip() else None
+
+
+_MASK = {c: chr(0xE000 + i) for i, c in enumerate(";&|<>")}
+_UNMASK = str.maketrans({v: k for k, v in _MASK.items()})
+
+
+def _mask(command: str) -> str:
+    """The command with quoted or escaped `;`, `&`, `|`, `<` and `>` swapped for placeholders, so the lexer,
+    which drops quotes before it splits, never reads a printed `';'` as an operator. Comments are
+    dropped and an unquoted newline separates commands, as the shell reads them."""
+    out, quote, esc, comment = [], "", False, False
+    for c in command:
+        if comment:
+            if c != "\n":
+                continue
+            comment = False
+        if esc:
+            if c == "\n":  # a line continuation joins the lines
+                out.pop()
+            else:
+                out.append(_MASK.get(c, c))
+            esc = False
+            continue
+        if c == "\\" and quote != "'":
+            esc = True
+        elif c in "'\"" and quote in ("", c):
+            quote = "" if quote else c
+        elif quote and c in _MASK:
+            c = _MASK[c]
+        elif not quote and c == "#" and (not out or out[-1] in " \t\n;&|()"):
+            comment = True
+            continue
+        elif not quote and c in "<>" and out and out[-1].isdigit():
+            fd = len(out)
+            while fd and out[fd - 1].isdigit():
+                fd -= 1
+            if fd == 0 or out[fd - 1] in " \t;&|":  # `2>` names a descriptor; `2 >` keeps 2 as an argument
+                del out[fd:]
+        elif not quote and c == "\n":  # ends a command, unless the line ended on an operator
+            c = " " if "".join(out).rstrip()[-1:] in ("", ";", "&", "|", "(") else ";"
+        out.append(c)
+    return "".join(out)
+
+
+def _strip_redirects(toks: list[str]) -> list[str]:
+    """The command's words without its redirections (`>out`, `2>&1`, `<in`), which aren't arguments."""
+    out, skip = [], False
+    for t in toks:
+        if skip:
+            skip = False
+        elif t and set(t) <= set("<>&") and set(t) & set("<>"):
+            skip = True
+        else:
+            out.append(t)
+    return out
+
+
+def _chain(command: str) -> list[tuple[list[str], str, str]]:
+    """The command's segments as (tokens, operator before, operator after), split on shell operators
+    outside quotes (`echo 'a; b'` is one segment, `|tail` two tokens). Unbalanced quotes (a heredoc
+    or a script, not one command) yield nothing."""
+    lex = shlex.shlex(_mask(command), posix=True, punctuation_chars=True)
+    lex.whitespace_split, lex.commenters = True, ""  # _mask already dropped comments
+    try:
+        toks = list(lex)
+    except ValueError:
+        return []
+    out, cur, before = [], [], ""
+    for t in toks + [None]:  # None ends it: `''` lexes to an empty token
+        t = "|" if t == "|&" else t  # bash's `|&` is a pipe that also carries stderr
+        if t in _OPS or t is None:
+            if cur:  # `> out.log` alone runs nothing but still sets the status: keep it as `:`
+                words = _strip_redirects(cur) or [":"]
+                out.append(([w.translate(_UNMASK) for w in words], before, t or ""))
+            cur, before = [], t
+        else:
+            cur.append(t)
+    if out and out[-1][2] == ";":  # a trailing `;` ends the command; its status is still the last one's
+        out[-1] = (out[-1][0], out[-1][1], "")
+    return out
+
+
+def _segments(command: str) -> list[list[str]]:
+    """Each command in the chain, tokenized; only the first stage of a pipeline is kept."""
+    return [toks for toks, before, _ in _chain(command) if before != "|"]
+
+
+def _proven(command: str) -> list[list[str]]:
+    """The segments a successful run proves succeeded. A chain's exit status is its last command's,
+    so only a segment followed by nothing but `&&` counts; `||` may skip a segment, a pipeline exits
+    with its last stage, and `&` with the launch, so none of those prove anything."""
+    if re.search(r"\$\(|`|[<>]\(", command):  # a substitution's status is hidden by the command around it
+        return []
+    chain = _chain(command)
+    if any(before == "||" or after == "||" for _, before, after in chain):
+        return []
+    return [toks for k, (toks, before, after) in enumerate(chain)
+            if before not in ("|", "&") and all(a in ("&&", "") for _, _, a in chain[k:])]
+
+
+def _exit(a: Action) -> str | None:
+    m = _EXIT_CODE.search(a.output or "")
+    return m.group(1) if m else None
+
+
+def _failed(a: Action) -> bool:
+    return a.status == "error" or (_exit(a) or "0") != "0"
+
+
+def _succeeded(a: Action) -> bool:
+    """Confirmed success. Claude records a status; Codex records none, so its exit code decides. A
+    run still `running`, or with no status and no exit code, can't prove a repair."""
+    return not _failed(a) and (a.status == "completed" or _exit(a) == "0") and not _errs(a.output or "")
+
+
+def _walk(place: tuple, cds: list[list[str]], unknown: list[int]) -> tuple:
+    """Where these `cd`s land from `place`: a `cd /abs` lands in the same place from anywhere; one we
+    can't follow (`cd -`, `pushd`, `popd`) lands somewhere no other run can match."""
+    for t in cds:
+        if t[0] == "cd" and len(t) == 2 and t[1] not in ("-", "~") and not t[1].startswith("~"):
+            place = (t[1],) if t[1].startswith("/") else (*place, t[1])
+        else:
+            unknown[0] += 1
+            place = ("?", unknown[0])
+    return place
+
+
+def _runs(trace: Trace) -> list[_Run]:
+    runs, shell, unknown = [], None, [0]
+    for i, a in enumerate(trace.actions):
+        cmd = _command_of(a)
+        if cmd and "<<" not in cmd:  # a heredoc body isn't commands
+            segs = _segments(cmd)
+            moves = [t[0] in ("cd", "pushd", "popd") for t in segs]
+            first_cmd = moves.index(False) if False in moves else len(moves)
+            # Only Claude's Bash keeps one shell, and every `cd`, across calls, so its run starts where the
+            # last one left it; any other call starts fresh, in its named directory.
+            wd = str(a.input.get("workdir") or a.input.get("cwd") or "")
+            persists = (a.name or "").lower() == "bash" and not wd
+            base = shell or ("", "") if persists else ("", wd)
+            where = None if any(moves[first_cmd:]) else _walk(base, segs[:first_cmd], unknown)
+            if any(moves) and persists:
+                # Follow the `cd`s only when the run proves they all ran: it succeeded, chained only by `&&`.
+                # Otherwise one may have been skipped, failed, or run in a subshell (`| cat`, `&`).
+                sure = _succeeded(a) and all(op in ("", "&&") for _, _, op in _chain(cmd))
+                shell = _walk(base, [t for t, m in zip(segs, moves) if m] if sure else [["popd"]], unknown)
+            masked = any(op in ("|", ";", "||", "&") for _, _, op in _chain(cmd))
+            runs.append(_Run(i, cmd, segs, _proven(cmd), a.output or "", _succeeded(a), _failed(a) or masked, where,
+                             any(_INSTALLS & set(t) for t, _, _ in _chain(cmd)), persists and _persists_env(segs), "<" in _mask(cmd)))
+    return runs
+
+
+def _split_env(toks: list[str]) -> tuple[dict[str, str], list[str]]:
+    env, k = {}, 0
+    if toks and toks[0] in ("env", "export"):
+        k = 1
+        while k < len(toks) and toks[k].startswith("-"):  # env -i, env -u NAME: a change, kept as one
+            n = 2 if toks[k] in ("-u", "--unset", "-C", "--chdir", "-S") else 1
+            env[" ".join(toks[k:k + n])] = ""
+            k += n
+    while k < len(toks) and (m := _ASSIGN.match(toks[k])):
+        env[m.group(1)] = m.group(2)
+        k += 1
+    # `export A=1 python app` only exports names; it runs nothing
+    return env, [] if toks[:1] == ["export"] else toks[k:]
+
+
+def _base(tok: str) -> str:
+    return tok.rsplit("/", 1)[-1]
+
+
+def _first(patterns, text: str) -> str | None:
+    for p in patterns:
+        if m := p.search(text):
+            return m.group(1)
+    return None
+
+
+def _render(toks: list[str], upto: int) -> str:
+    """A form as the fact shows it: its first words, then … for the rest."""
+    return "`" + shlex.join(toks[:upto]) + (" …" if len(toks) > upto else "") + "`"
+
+
+def _invocation(toks: list[str]) -> list[str] | None:
+    """What a run of `toks[0]` runs: its script or `-m module` and their arguments, since a
+    subcommand (`manage.py migrate` vs `check`) may import or read what another doesn't. A repair
+    must run the same thing. Inline code (`-c`, `-e`) or flags ahead of the script aren't compared,
+    so those runs yield no repair (None)."""
+    rest = toks[1:]
+    if rest[:1] == ["-m"] and len(rest) >= 2:
+        return rest
+    return rest if rest and not rest[0].startswith("-") else None
+
+
+def _same(rest: list[str], args: list[str]) -> bool:
+    """A run is the same invocation only with exactly its arguments: an added `--skip-db` may skip
+    the failing import. A missing command has none to match, so any arguments do."""
+    return rest == args if args else True
+
+
+def _redact(form: list[str]) -> list[str]:
+    """Never repeat a credential into shared memory: any `name=value` (`K=V`, `-e K=V`, `--token=x`)
+    unless the name is known safe, and a URL's user:password."""
+    out = []
+    for t in form:
+        key, eq, _ = t.partition("=")
+        if eq and key not in _SAFE_ENV:
+            t = f"{key}=…"
+        out.append(_USERINFO.sub("://…@", t))
+    return out
+
+
+def _changes_env(segments: list[list[str]]) -> bool:
+    return any(_split_env(seg)[0] or seg[0] in ("export", "set", "unset", "source", ".") for seg in segments)
+
+
+def _persists_env(segments: list[list[str]]) -> bool:
+    """An env change the shell keeps for later calls: `export`, `source`, or an assignment on its own;
+    `X=1 cmd` sets it for that command only."""
+    return any(seg[0] in ("export", "set", "unset", "source", ".") or (_split_env(seg)[0] and not _split_env(seg)[1])
+               for seg in segments)
+
+
+def _working_form(head: str, args: list[str], later: _Run) -> list[str] | None:
+    """The tokens a later, successful command runs `head` with, when it runs it another way: behind a
+    wrapper (`uv run pytest`, `python -m pytest`, `npx tsc`) or by a path (`.venv/bin/pytest`)."""
+    # An assignment or `export` anywhere in the run may be what made it work, and the fix wouldn't say so.
+    if _changes_env(later.segments):
+        return None
+    for seg in later.proven:
+        _, toks = _split_env(seg)
+        for j, t in enumerate(toks):
+            if _base(t) != head or (j == 0 and t == head):
+                continue
+            prefix, rest = toks[:j], toks[j + 1:]
+            if prefix and (_base(prefix[0]), *prefix[1:]) not in _WRAPPERS:
+                break
+            if _probes(rest) or not _same(rest, args):
+                break
+            form = toks[:j + 1]
+            # a host path, URL or `user@` may carry a home dir or a token; none belongs in shared memory
+            return None if _ABS.search(" " + " ".join(form)) or any("://" in t or "@" in t for t in form) else form
+    return None
+
+
+_EDIT_TOOL = re.compile(r"edit|write|patch|replace", re.I)
+# A shell command that writes files: sed/perl -i, tee, a `>` into a file, apply_patch, write_text.
+_IN_PLACE = re.compile(r"\b(?:sed|perl)\s+-i|apply_patch|write_text")
+_SHELL_EDIT = re.compile(r"\b(?:sed|perl)\s+-i|\btee\b|apply_patch|write_text|(?<![0-9&])>>?\s*(?!/dev/null|&)[\w./]")
+
+
+def _edited_between(trace: Trace, a: _Run, b: _Run, head: str) -> bool:
+    """A file edit between the runs, or before the invocation in the working run, may have changed
+    the script itself (dropped the import), so the later run no longer tests what failed."""
+    if any(_EDIT_TOOL.search(x.name or "") or _SHELL_EDIT.search(_command_of(x) or "")
+           for x in trace.actions[a.i + 1:b.i]):
+        return True
+    def runs_head(seg: str) -> bool:  # as the command or behind a wrapper: `echo python > app.py` doesn't
+        for toks, _, _ in _chain(seg.translate(_UNMASK)):
+            w = _split_env(toks)[1]
+            j = next((k for k, t in enumerate(w) if _base(t) == head), None)
+            if j == 0 or (j and (_base(w[0]), *w[1:j]) in _WRAPPERS):
+                return True
+        return False
+    # The invocation's own `> log` is output, not an edit; any other segment's write may be one.
+    return any(_IN_PLACE.search(seg) if runs_head(seg) else _SHELL_EDIT.search(seg)
+               for seg in re.split(r"[;&|]", _mask(b.command)))
+
+
+def _same_place(a: _Run, b: _Run) -> bool:
+    """A script name means the same script only from the same, known directory."""
+    return a.where is not None and a.where == b.where
+
+
+def _installed_between(runs: list[_Run], a: _Run, b: _Run) -> bool:
+    """Any install or sync after the failure, up to and including the run that worked (`uv sync` and
+    `pip install -r` don't name what they install), may be why it worked: the fact won't hold. So may
+    an `export` or `source` between them, which persists in the shell."""
+    return any(a.i < r.i <= b.i and r.installs or a.i < r.i < b.i and r.sets_env for r in runs)
+
+
+def _probes(args: list[str]) -> bool:
+    """The arguments only ask for a version or help, which can work while the real run can't."""
+    return bool(args) and set(args) <= _PROBE_ARGS or bool(_PROBE_FLAGS & set(args))
+
+
+def _works_unchanged_later(runs: list[_Run], a: _Run, head: str, args: list[str], same_place: bool) -> bool:
+    """The same thing ran bare later, without the fix, and worked: installed or fixed mid-session."""
+    for r in runs:
+        # a run after an `export` may only work because it inherited the fix
+        if r.i > a.i and r.ok and (not same_place or _same_place(a, r)) and not any(x.sets_env for x in runs if a.i < x.i <= r.i):
+            for env, toks in map(_split_env, r.proven):
+                # unchanged: no env anywhere in the run, and a probe (`--help`) doesn't prove the real run works
+                if toks[:1] == [head] and _same(toks[1:], args) and not env and not _probes(toks[1:]):
+                    return True
+    return False
+
+
+def _errs(output: str) -> bool:
+    return any(_first(ps, output) for ps in (_CMD_MISSING, _MOD_MISSING, _ENV_MISSING))
+
+
+def _target(seg_toks: list[list[str]], missing_cmd: str | None) -> list[str] | None:
+    """The segment the error is about: the one running the missing command, else the only one that
+    isn't setup (`cd`, `source`, `export`). With two, a module or env error can't be attributed."""
+    runs = [_split_env(s) for s in seg_toks]
+    if missing_cmd:
+        return next((s for s, (_, t) in zip(seg_toks, runs) if t and _base(t[0]) == missing_cmd), None)
+    work = [s for s, (_, t) in zip(seg_toks, runs) if t and t[0] not in _SETUP]
+    return work[0] if len(work) == 1 else None
+
+
+def _env_fix(name: str, head: str, args: list[str], later: _Run) -> str | None:
+    """The later run that sets `name` and runs the same thing, as the fact shows it."""
+    for seg in later.proven:
+        env, toks = _split_env(seg)
+        others = list(later.segments)
+        if seg in others:
+            others.remove(seg)
+        if _changes_env(others):  # other setup in the run may be part of the fix
+            continue
+        if set(env) == {name} and toks[:1] == [head] and _same(toks[1:], args) and not _probes(toks[1:]):
+            value = env[name]
+            # Only a plain value is written: a URL, `?token=`, `@` or host path may carry a secret.
+            if name not in _SAFE_ENV or _ABS.search(" " + value) or "://" in value or not re.fullmatch(r"[\w.,:/+-]{0,80}", value):
+                return f"`{name}=… {head} …`"
+            return f"`{shlex.join([f'{name}={value}', head])} …`"
+    return None
+
+
+def mine(trace: Trace) -> tuple[list[ClaimDraft], set[int]]:
+    """Repair pitfalls for one trace, and the indexes of the failed actions a repair explains."""
+    from .distill import ClaimDraft  # distill imports this module; import back at call time
+
+    runs = _runs(trace)
+    drafts: dict[str, ClaimDraft] = {}
+    explained: set[int] = set()
+    for a in runs:
+        # Error text counts only from a run that failed, or one whose status could hide it (`… | tail`):
+        # a successful `rg "No module named"` just printed it.
+        if not a.may_fail or a.reads_input:
+            continue
+        missing_cmd = _first(_CMD_MISSING, a.output)
+        missing_mod = None if missing_cmd else _first(_MOD_MISSING, a.output)
+        missing_env = None if missing_cmd or missing_mod else _first(_ENV_MISSING, a.output)
+        if not (missing_cmd or missing_mod or missing_env):
+            continue
+        seg = _target([t for t, _, _ in _chain(a.command)], missing_cmd)  # every stage: `a | b` may fail in b
+        _, toks = _split_env(seg or [])
+        if _changes_env(a.segments):  # `PATH=/x pytest` failing says nothing about this environment
+            continue
+        if not toks or "/" in toks[0] or not _WORD.match(head := toks[0]):
+            continue
+        args = [] if missing_cmd else _invocation(toks)
+        if args is None:
+            continue
+        if _works_unchanged_later(runs, a, head, args, same_place=not missing_cmd):
+            continue
+        if missing_cmd:
+            subject, why = f"`{head}` is not on PATH", "fails here (command not found)"
+        elif missing_mod and _WORD.match(missing_mod):
+            subject, why = f"`{head}` can't import `{missing_mod}`", f"fails here (no module `{missing_mod}`)"
+        elif missing_env:
+            subject, why = f"`{head}` needs `{missing_env}` set", f"fails here asking for `{missing_env}`"
+        else:
+            continue
+        # Each failure needs its own repair to count as explained; the first one found writes the claim.
+        # A script or module is only the same one run from the same place.
+        for b in (r for r in runs if r.i > a.i and r.ok and not r.reads_input and (missing_cmd or _same_place(a, r))):
+            if missing_env:
+                fix = _env_fix(missing_env, head, args, b)
+            else:
+                form = _working_form(head, args, b)
+                # a relative path (`.venv/bin/pytest`, `uv run .venv/bin/pytest`) only works from where it ran
+                if form and "/" in form[-1] and not _same_place(a, b):
+                    form = None
+                fix = form and f"`{shlex.join(form)} …`"
+            # checked only for a candidate fix: each scans every run in between
+            if fix and (_installed_between(runs, a, b) or (not missing_cmd and _edited_between(trace, a, b, head))):
+                fix = None
+            if fix:
+                shown = 1 + (2 if args[:1] == ["-m"] else len(args[:1]))  # the command and script, never its arguments
+                drafts.setdefault(subject, ClaimDraft("pitfall", subject, f"{_render(_redact(toks), shown)} {why}; {fix} works.", 0.6))
+                explained.add(a.i)
+                break
+    return list(drafts.values()), explained
diff --git a/tests/test_repairs.py b/tests/test_repairs.py
new file mode 100644
index 0000000..4cd360f
--- /dev/null
+++ b/tests/test_repairs.py
@@ -0,0 +1,444 @@
+"""Repair pitfalls: a failing shell form followed by one that works, mined without a model."""
+import unittest
+
+from kypp.distill import ClaimDraft, HeuristicDistiller, WithRepairs, build_trace
+from kypp.repairs import mine
+
+
+def _bash(command, output="", status="completed"):
+    return {"sessionId": "s1", "payload": {"type": "tool_call", "name": "Bash", "status": status,
+                                           "input": {"command": command}, "output": output}}
+
+
+def _codex(command, output):
+    return {"sessionId": "s1", "payload": {"type": "tool_call", "name": "shell", "status": "unspecified",
+                                           "input": {"command": ["bash", "-lc", command]}, "output": output}}
+
+
+def _mine(*events):
+    return mine(build_trace(list(events)))[0]
+
+
+class CommandMissing(unittest.TestCase):
+    def test_wrapper_that_works_becomes_one_pitfall(self):
+        [d] = _mine(_bash("pytest -q tests", "bash: line 1: pytest: command not found", "error"),
+                    _bash("uv run pytest -q tests", "3 passed"))
+        self.assertEqual((d.type, d.subject), ("pitfall", "`pytest` is not on PATH"))
+        self.assertIn("`pytest …` fails here (command not found)", d.content)
+        self.assertIn("`uv run pytest …` works", d.content)
+
+    def test_subject_names_only_what_failed_so_sessions_agree(self):
+        a = _mine(_bash("pytest", "pytest: command not found", "error"), _bash("python -m pytest", "ok"))
+        b = _mine(_bash("pytest -x", "pytest: command not found", "error"), _bash(".venv/bin/pytest -x", "ok"))
+        self.assertEqual([d.subject for d in a], [d.subject for d in b])
+        self.assertIn("`.venv/bin/pytest …` works", b[0].content)
+
+    def test_codex_reads_failure_from_the_exit_code(self):
+        [d] = _mine(_codex("cd web && tsc --noEmit", "Exit code: 127\nOutput:\nbash: tsc: command not found"),
+                    _codex("cd web && npx tsc --noEmit", "Exit code: 0\nOutput:\n"))
+        self.assertEqual(d.subject, "`tsc` is not on PATH")
+        self.assertIn("`npx tsc …` works", d.content)
+
+    def test_codex_exec_command_exit_format(self):
+        [d] = _mine(_codex("pytest", "Process exited with code 127\nbash: pytest: command not found"),
+                    _codex("uv run pytest", "Process exited with code 0\n3 passed"))
+        self.assertEqual(d.subject, "`pytest` is not on PATH")
+
+    def test_codex_success_with_a_nonzero_exit_is_not_a_repair(self):
+        self.assertEqual(_mine(_codex("tsc", "Exit code: 127\nbash: tsc: command not found"),
+                               _codex("npx tsc", "Exit code: 2\nerror TS2304")), [])
+
+    def test_no_fact_when_the_bare_form_works_later(self):
+        self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                               _bash("uv run pytest", "ok"), _bash("pytest", "ok")), [])
+
+    def test_no_fact_when_it_was_installed_in_between(self):
+        self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                               _bash("uv pip install pytest", "ok"), _bash("python -m pytest", "ok")), [])
+
+    def test_no_fact_when_the_working_run_installed_it_first(self):
+        self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                               _bash("uv pip install pytest && uv run pytest", "ok")), [])
+
+    def test_probes_and_installs_are_not_repairs(self):
+        for later in ("which pytest", "pip install pytest", "uv add pytest", "pytest --version",
+                      "test -x .venv/bin/pytest", "test .venv/bin/pytest", "ls .venv/bin/pytest",
+                      "touch pytest", "true pytest"):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"), _bash(later, "ok")),
+                             [], later)
+
+    def test_a_host_path_form_is_not_a_fact(self):
+        self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                               _bash("/home/u/.venv/bin/pytest", "ok")), [])
+        for path in ("/opt/company/venv/bin/pytest", "/workspace/.venv/bin/pytest", "/mnt/x/pytest",
+                     "~/.local/bin/pytest", "/opt/uv run pytest"):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"), _bash(path, "ok")), [], path)
+
+    def test_an_export_between_the_runs_may_be_the_fix(self):
+        for setup in ("export PYTHONPATH=src", "source .venv/bin/activate", "PYTHONPATH=src; true"):
+            self.assertEqual(_mine(_bash("python app.py", "ModuleNotFoundError: No module named 'project'", "error"),
+                                   _bash(setup, "ok"), _bash("uv run python app.py", "ok")), [], setup)
+
+
+    def test_a_piped_run_fails_by_its_output(self):
+        [d] = _mine(_bash("pytest -q | tail -3", "bash: pytest: command not found"),
+                    _bash("uv run pytest -q", "3 passed"))
+        self.assertIn("`uv run pytest …` works", d.content)
+
+    def test_a_successful_run_that_prints_error_text_is_not_a_failure(self):
+        self.assertEqual(_mine(_bash("rg \"No module named 'turso'\" errors.log", "No module named 'turso'"),
+                               _bash("uv run rg \"No module named 'turso'\" errors.log", "No module named 'turso'")), [])
+
+    def test_a_number_before_a_spaced_redirection_is_an_argument(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv run python app.py 2 >out", "ok")), [])
+        self.assertEqual(_mine(_bash("python app.py 2 > /dev/null", "No module named 'turso'", "error"),
+                               _bash("uv run python app.py", "ok")), [])
+
+    def test_redirections_are_not_arguments(self):
+        [d] = _mine(_bash("python app.py", "No module named 'turso'", "error"),
+                    _bash("uv run python app.py >out 2>&1", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_flags_on_the_working_run_are_not_installs(self):
+        [d] = _mine(_bash("pytest", "pytest: command not found", "error"), _bash("uv run pytest -v", "ok"))
+        self.assertIn("`uv run pytest …` works", d.content)
+
+    def test_success_proves_only_segments_it_ran(self):
+        for later in ("true || uv run pytest", "uv run pytest; true", "uv run pytest | tail -3",
+                      "uv run pytest |tail -3", "uv run pytest |& tail -3", "printf '' uv run pytest",
+                      "echo $(true; uv run pytest 2>/dev/null)", "uv run pytest 2>/dev/null; > out.log", "echo `uv run pytest`", "uv run pytest >/tmp/log 2>&1 &",
+                      "echo 'example; uv run pytest && end'", "env -u PYTHONPATH uv run pytest",
+                      "echo ';' uv run pytest", 'echo "a|b" uv run pytest', "echo \\; uv run pytest"):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"), _bash(later, "ok")),
+                             [], later)
+        [d] = _mine(_bash("pytest", "pytest: command not found", "error"), _bash("cd x; uv run pytest && echo ok", "ok"))
+        self.assertIn("`uv run pytest …` works", d.content)
+
+    def test_comments_and_continuations_read_as_the_shell_does(self):
+        for later in ("# run tests\nuv run pytest", "uv run pytest;", "uv run pytest\n# done", "cd x  # into the repo\nuv run pytest", "uv run \\\n  pytest"):
+            [d] = _mine(_bash("pytest", "pytest: command not found", "error"), _bash(later, "ok"))
+            self.assertIn("`uv run pytest …` works", d.content, later)
+
+    def test_a_failure_under_its_own_env_change_says_nothing(self):
+        for failed in ("PATH=/nonexistent pytest", "export PATH=/x; pytest"):
+            self.assertEqual(_mine(_bash(failed, "pytest: command not found", "error"),
+                                   _bash("uv run pytest", "ok")), [], failed)
+
+    def test_a_multiline_command_is_read_line_by_line(self):
+        [d] = _mine(_bash("cd web\ntsc", "tsc: command not found", "error"), _bash("cd web\nnpx tsc", "ok"))
+        self.assertEqual(d.subject, "`tsc` is not on PATH")
+
+
+    def test_probe_flags_after_the_command_are_not_repairs(self):
+        for later in ("uv run pytest --version", ".venv/bin/pytest --help", "uv run pytest --help tests",
+                      "python inspect_args.py pytest"):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"), _bash(later, "ok")),
+                             [], later)
+
+    def test_a_run_with_no_recorded_outcome_proves_nothing(self):
+        for status, out in (("running", ""), ("unspecified", ""), ("unspecified", "3 passed")):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                                   _bash("uv run pytest", out, status)), [], status)
+
+    def test_credentials_in_the_working_form_are_redacted(self):
+        for later in ("docker run -e OPENAI_API_KEY=sk-live-123 img pytest -q",
+                      "docker --config x run --token SECRET image pytest"):
+            self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"), _bash(later, "ok")),
+                             [], later)
+        [d] = _mine(_bash("mycli --token=sk-1 sync", "mycli: command not found", "error"), _bash("npx mycli --token=sk-1", "ok"))
+        self.assertNotIn("sk-1", d.content)
+
+
+class ModuleMissing(unittest.TestCase):
+    def test_interpreter_that_can_import_it(self):
+        [d] = _mine(_bash("python -m kypp.distill", "ModuleNotFoundError: No module named 'turso'", "error"),
+                    _bash("uv run python -m kypp.distill", "OK"))
+        self.assertEqual(d.subject, "`python` can't import `turso`")
+        self.assertIn("(no module `turso`)", d.content)
+        self.assertIn("`uv run python …` works", d.content)
+
+
+    def test_the_same_script_name_elsewhere_is_not_the_same_script(self):
+        self.assertEqual(_mine(_bash("cd server && python app.py", "No module named 'project'", "error"),
+                               _bash("cd client && uv run python app.py", "ok")), [])
+        [d] = _mine(_bash("cd /r/server && python app.py", "No module named 'project'", "error"),
+                    _bash("cd /r/server && uv run python app.py", "ok"), _bash("cd /r/client && python app.py", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+        # the shell keeps a relative `cd`, so the second one lands somewhere else
+        self.assertEqual(_mine(_bash("cd server && python app.py", "No module named 'project'", "error"),
+                               _bash("cd server && uv run python app.py", "ok")), [])
+
+    def test_a_run_reading_stdin_may_take_another_path(self):
+        self.assertEqual(_mine(_bash("python app.py < deploy.txt", "No module named 'boto3'", "error"),
+                               _bash("uv run python app.py < status.txt", "ok")), [])
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'boto3'", "error"),
+                               _bash("uv run python app.py < status.txt", "ok")), [])
+
+    def test_unrelated_successes_stay_cheap(self):
+        import time
+        t = time.monotonic()
+        _mine(_bash("pytest", "pytest: command not found", "error"), *[_bash(f"ls d{i} && pip install x{i}", "ok") for i in range(400)])
+        self.assertLess(time.monotonic() - t, 1.0)
+
+    def test_a_bare_run_after_an_export_inherits_the_fix(self):
+        [d] = _mine(_bash("node build.js", "Error: API_BASE is not set", "error"), _bash("API_BASE=x node build.js", "ok"),
+                    _bash("export API_BASE=x", "ok"), _bash("node build.js", "ok"))
+        self.assertIn("`API_BASE", d.content)
+
+    def test_a_cd_that_may_not_have_run_leaves_the_place_unknown(self):
+        for cd, status in (("false && cd /other", "error"), ("cd /other || true", "completed"), ("cd /other; ls", "completed")):
+            self.assertEqual(_mine(_bash(cd, "", status), _bash("python app.py", "No module named 'project'", "error"),
+                                   _bash("cd /other && uv run python app.py", "ok")), [], cd)
+
+    def test_an_export_runs_nothing(self):
+        self.assertEqual(_mine(_bash("python app", "API_BASE is not set", "error"),
+                               _bash("export API_BASE=x python app", "ok")), [])
+
+    def test_a_piped_cd_leaves_the_place_unknown(self):
+        self.assertEqual(_mine(_bash("cd /other | cat", "ok"), _bash("python app.py", "No module named 'project'", "error"),
+                               _bash("cd /other && uv run python app.py", "ok")), [])
+
+    def test_a_codex_export_does_not_reach_the_next_call(self):
+        self.assertEqual(_mine(_codex("pytest", "Exit code: 127\nbash: pytest: command not found"),
+                               _codex("uv run pytest", "Exit code: 0\nok"), _codex("export FOO=bar", "Exit code: 0\n"),
+                               _codex("pytest", "Exit code: 0\nok")), [])
+
+    def test_each_codex_call_starts_a_fresh_shell(self):
+        [d] = _mine(_codex("cd backend && python app.py", "Exit code: 1\nNo module named 'project'"),
+                    _codex("cd backend && uv run python app.py", "Exit code: 0\nok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_a_cd_inside_a_compound_command_moves_the_shell(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'project'", "error"),
+                               _bash("cd other && ls", "ok"), _bash("uv run python app.py", "ok")), [])
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'project'", "error"),
+                               _bash("cd /other", "ok"), _bash("uv run python app.py", "ok")), [])
+        [d] = _mine(_bash("cd /r && python app.py", "No module named 'project'", "error"),
+                    _bash("cd /elsewhere && ls", "ok"), _bash("cd /r && uv run python app.py", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_a_script_help_probe_is_not_a_fix(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv run python app.py --help", "ok")), [])
+
+    def test_extra_arguments_are_not_the_same_run(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'psycopg'", "error"),
+                               _bash("uv run python app.py --skip-database", "ok")), [])
+        self.assertEqual(_mine(_bash("node build.js", "Error: API_BASE is not set", "error"),
+                               _bash("API_BASE=x node build.js --dry-run", "ok")), [])
+
+    def test_the_failing_form_shows_only_the_script(self):
+        [d] = _mine(_bash("python app.py --token SECRET", "No module named 'turso'", "error"),
+                    _bash("uv run python app.py --token SECRET", "ok"))
+        self.assertNotIn("SECRET", d.content)
+        self.assertIn("`python app.py …` fails here", d.content)
+
+    def test_a_cd_in_between_changes_the_place(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'project'", "error"), _bash("cd other", ""),
+                               _bash("uv run python app.py", "ok")), [])
+
+    def test_a_cd_after_the_command_leaves_the_place_unclear(self):
+        self.assertEqual(_mine(_bash("python app.py; cd server", "No module named 'turso'", "error"),
+                               _bash("cd server; uv run python app.py", "ok")), [])
+
+    def test_an_install_joined_by_a_separator_still_counts(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv sync; uv run python app.py", "ok")), [])
+
+    def test_a_failure_without_its_own_repair_is_not_explained(self):
+        drafts, explained = mine(build_trace([_bash("python app.py", "No module named 'project'", "error"),
+                                              _bash("uv run python app.py", "ok"),
+                                              _bash("python other.py", "No module named 'project'", "error")]))
+        self.assertEqual((len(drafts), explained), (1, {0}))
+
+    def test_an_edit_in_between_may_have_changed_the_script(self):
+        edit = {"sessionId": "s1", "payload": {"type": "tool_call", "name": "Edit", "status": "completed",
+                                               "input": {"file_path": "app.py"}, "output": "ok"}}
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"), edit,
+                               _bash("uv run python app.py", "ok")), [])
+
+    def test_a_shell_edit_in_between_may_have_changed_the_script(self):
+        for edit in ("sed -i '/turso/d' app.py", "python - <<'EOF'\nPath('app.py').write_text('')\nEOF",
+                     "echo 'print(1)' > app.py"):
+            self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"), _bash(edit, ""),
+                                   _bash("uv run python app.py", "ok")), [], edit)
+
+    def test_an_error_from_a_pipeline_is_not_attributed(self):
+        self.assertEqual(_mine(_bash("python producer.py | python consumer.py", "No module named 'turso'"),
+                               _bash("uv run python producer.py", "ok")), [])
+
+    def test_an_edit_in_the_working_run_itself_counts(self):
+        for later in ("sed -i '/import turso/d' app.py && uv run python app.py",
+                      "echo 'print(1)' > app.py && uv run python app.py",
+                      "echo 'print(\"python\")' > app.py && uv run python app.py",
+                      "echo python > app.py && uv run python app.py", "echo x | tee app.py; uv run python app.py"):
+            self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"), _bash(later, "ok")), [], later)
+
+    def test_a_quoted_angle_bracket_is_an_argument(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv run python app.py '>' --help", "usage")), [])
+
+    def test_an_argv_command_keeps_its_argument_boundaries(self):
+        argv = lambda c, out, st: {"sessionId": "s1", "payload": {"type": "tool_call", "name": "shell", "status": st,
+                                                                  "input": {"command": c}, "output": out}}
+        self.assertEqual(_mine(argv(["python", "app.py", "hello world"], "No module named 'turso'", "error"),
+                               argv(["uv", "run", "python", "app.py", "hello", "world"], "ok", "completed")), [])
+
+    def test_a_path_form_from_another_directory_is_not_a_fix(self):
+        self.assertEqual(_mine(_bash("pytest -q", "pytest: command not found", "error"),
+                               _bash("cd backend && .venv/bin/pytest -q", "ok")), [])
+        self.assertEqual(_mine(_bash("pytest", "pytest: command not found", "error"),
+                               _bash("cd backend && uv run .venv/bin/pytest", "ok")), [])
+
+    def test_a_url_or_user_in_the_working_form_is_never_written(self):
+        self.assertEqual(_mine(_bash("mycli", "mycli: command not found", "error"),
+                               _bash("npx https://user:TOKEN@packages.example/mycli", "ok")), [])
+
+    def test_a_redirection_only_command_is_skipped(self):
+        [d] = _mine(_bash("> out.log", ""), _bash("python app.py", "No module named 'turso'", "error"),
+                    _bash("uv run python app.py 2>/dev/null", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_unset_is_an_env_change(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("unset PYTHONHOME; uv run python app.py", "ok")), [])
+
+    def test_a_different_subcommand_is_not_the_same_run(self):
+        fail = _bash("python manage.py migrate", "No module named 'psycopg'", "error")
+        self.assertEqual(_mine(fail, _bash("uv run python manage.py check", "ok")), [])
+        [d] = _mine(fail, _bash("uv run python manage.py migrate", "ok"), _bash("python manage.py check", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_the_later_run_must_run_the_same_thing(self):
+        for later in ("uv run python -c 'print(1)'", "uv run python unrelated.py", "uv run python -m other"):
+            self.assertEqual(_mine(_bash("python -m kypp.distill", "No module named 'turso'", "error"),
+                                   _bash(later, "ok")), [], later)
+
+    def test_an_error_from_a_multi_command_run_is_not_attributed(self):
+        self.assertEqual(_mine(_bash("python app.py; node build.js", "No module named 'turso'", "error"),
+                               _bash("npx node build.js", "ok")), [])
+
+    def test_a_fix_that_also_sets_a_variable_is_not_recorded(self):
+        for later in ("PYTHONPATH=src uv run python app.py", "export PYTHONPATH=src && uv run python app.py",
+                      "env -C other uv run python app.py"):
+            self.assertEqual(_mine(_bash("python app.py", "No module named 'project'", "error"),
+                                   _bash(later, "ok")), [], later)
+
+    def test_a_sync_or_bulk_install_in_between_explains_it(self):
+        for between in ("uv sync", "pip install -r requirements.txt"):
+            self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"), _bash(between, "ok"),
+                                   _bash("uv run python app.py", "ok")), [], between)
+
+    def test_no_fact_when_the_working_run_installed_it_first(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv pip install turso && uv run python app.py", "ok")), [])
+
+    def test_inline_code_is_not_compared_so_yields_nothing(self):
+        self.assertEqual(_mine(_bash("python -c 'import turso'", "No module named 'turso'", "error"),
+                               _bash("uv run python -c 'print(1)'", "ok")), [])
+
+    def test_no_fact_when_the_bare_form_works_later(self):
+        self.assertEqual(_mine(_bash("python app.py", "No module named 'turso'", "error"),
+                               _bash("uv run python app.py", "ok"), _bash("python app.py", "ok")), [])
+
+    def test_a_later_help_probe_does_not_count_as_working_bare(self):
+        [d] = _mine(_bash("python app.py", "No module named 'turso'", "error"),
+                    _bash("uv run python app.py", "ok"), _bash("python app.py --help", "usage: app"))
+        self.assertIn("`uv run python …` works", d.content)
+
+
+class EnvMissing(unittest.TestCase):
+    def test_a_later_help_probe_does_not_count_as_working_without_it(self):
+        [d] = _mine(_bash("node build.js", "Error: API_BASE is not set", "error"),
+                    _bash("API_BASE=http://localhost:8787 node build.js", "built"), _bash("node build.js -h", "usage"))
+        self.assertEqual(d.subject, "`node` needs `API_BASE` set")
+
+    def test_setting_the_variable_works(self):
+        [d] = _mine(_bash("node build.js", "Error: API_BASE is not set", "error"),
+                    _bash("API_BASE=http://localhost:8787 node build.js", "built"))
+        self.assertEqual(d.subject, "`node` needs `API_BASE` set")
+        self.assertIn("asking for `API_BASE`; `API_BASE=… node …` works", d.content)
+
+    def test_only_known_safe_values_are_written(self):
+        [d] = _mine(_bash("python app.py", "DATABASE_URL is required", "error"),
+                    _bash("DATABASE_URL=postgresql://u:pw@h/db python app.py", "ok"))
+        self.assertNotIn("pw", d.content)
+        [d] = _mine(_bash("python -m app", "KeyError: 'PYTHONPATH'", "error"), _bash("PYTHONPATH=src python -m app", "ok"))
+        self.assertIn("`PYTHONPATH=src python …` works", d.content)
+        [d] = _mine(_bash("python app.py", "HOST is required", "error"),
+                    _bash("HOST=https://u:pw@example.com python app.py", "ok"))
+        self.assertNotIn("pw", d.content)
+        [d] = _mine(_bash("python app.py", "HOST is required", "error"),
+                    _bash("HOST='https://api.example/?token=SECRET' python app.py", "ok"))
+        self.assertNotIn("SECRET", d.content)
+
+    def test_the_later_run_must_run_the_same_script(self):
+        self.assertEqual(_mine(_bash("node build.js", "API_BASE is not set", "error"),
+                               _bash("API_BASE=x node --version", "ok")), [])
+
+    def test_a_probe_with_the_variable_set_is_not_a_fix(self):
+        self.assertEqual(_mine(_bash("node build.js", "API_BASE is not set", "error"),
+                               _bash("API_BASE=x node build.js --help", "ok")), [])
+
+    def test_no_fact_when_something_was_installed_in_between(self):
+        self.assertEqual(_mine(_bash("node build.js", "Error: API_BASE is not set", "error"), _bash("npm install", "ok"),
+                               _bash("API_BASE=http://localhost:8787 node build.js", "built")), [])
+
+    def test_a_fix_with_other_setup_in_the_run_is_not_recorded(self):
+        for later in ("export PYTHONPATH=src && API_BASE=x python app.py", "source .env && API_BASE=x python app.py"):
+            self.assertEqual(_mine(_bash("python app.py", "Error: API_BASE is not set", "error"),
+                                   _bash(later, "ok")), [], later)
+
+    def test_a_later_bare_run_after_an_export_is_not_unchanged(self):
+        [d] = _mine(_bash("node build.js", "Error: API_BASE is not set", "error"),
+                    _bash("API_BASE=http://localhost:8787 node build.js", "built"),
+                    _bash("export API_BASE=x && node build.js", "built"))
+        self.assertEqual(d.subject, "`node` needs `API_BASE` set")
+
+    def test_a_fix_with_other_variables_too_is_not_recorded(self):
+        self.assertEqual(_mine(_bash("python app.py", "API_BASE is not set", "error"),
+                               _bash("API_BASE=x PYTHONPATH=src python app.py", "ok")), [])
+
+    def test_a_later_run_with_its_own_env_change_is_not_unchanged(self):
+        [d] = _mine(_bash("python app.py", "No module named 'project'", "error"),
+                    _bash("uv run python app.py", "ok"), _bash("PYTHONPATH=src python app.py", "ok"))
+        self.assertIn("`uv run python …` works", d.content)
+
+    def test_no_fact_when_it_works_later_without_the_variable(self):
+        self.assertEqual(_mine(_bash("node build.js", "API_BASE is not set", "error"),
+                               _bash("API_BASE=x node build.js", "ok"), _bash("node build.js", "ok")), [])
+
+    def test_a_credential_value_is_never_repeated(self):
+        [d] = _mine(_bash("python run.py", "KeyError: 'OPENAI_API_KEY'", "error"),
+                    _bash("OPENAI_API_KEY=sk-live-123 python run.py", "ok"))
+        self.assertNotIn("sk-live-123", d.content)
+        self.assertIn("`OPENAI_API_KEY=… python …`", d.content)
+
+
+class HeuristicFloor(unittest.TestCase):
+    def test_explained_failures_drop_the_generic_pitfall(self):
+        trace = build_trace([_bash("pytest", "pytest: command not found", "error"),
+                             _bash("pytest -x", "pytest: command not found", "error"),
+                             _bash("uv run pytest -x", "ok")])
+        self.assertEqual([d.subject for d in HeuristicDistiller().distill(trace)], ["`pytest` is not on PATH"])
+
+    def test_unexplained_failures_keep_it(self):
+        trace = build_trace([_bash("cargo build", "error[E0425]", "error"),
+                             _bash("cargo build", "error[E0425]", "error")])
+        self.assertEqual([d.subject for d in HeuristicDistiller().distill(trace)], ["Bash repeatedly failed"])
+
+    def test_llm_path_gets_repairs_without_duplicates(self):
+        class Inner:
+            def distill(self, _t):
+                return [ClaimDraft("pitfall", "`pytest` is not on PATH", "model's wording", 0.7)]
+        trace = build_trace([_bash("pytest", "pytest: command not found", "error"), _bash("uv run pytest", "ok")])
+        self.assertEqual([d.content for d in WithRepairs(Inner()).distill(trace)], ["model's wording"])
+        class Empty:
+            def distill(self, _t):
+                return []
+        self.assertEqual(len(WithRepairs(Empty()).distill(trace)), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()