Stop validator cache from freezing transient engine failures + add TTL (#272)

rector-mcp's warm daemon intermittently trips rector's own
"System error: ClassReflection must be resolved for class XTest" reflection
bug on test classes — warm-process-state dependent, not file dependent (a
clean re-run and plain rector CLI pass the same file). That failure was
cached keyed on file content and replayed on every later run, frozen
duration and all; 2100 entries were poisoned this way across a test suite.

- rector-mcp.py: drop rector `System error:` results at the source — an
  engine glitch is not a code finding.
- supertool.py `_validator_result_is_cacheable()`: never cache
  non-deterministic engine failures (mcp/orchestrator/rector.exit codes,
  `System error:` messages). Real findings stay cached.
- supertool.py `_validator_cache_read()`: TTL on entries
  (`validator_cache_ttl_hours`, default 24, 0=off). The key only hashes file
  content, so an entry can outlive an updated adapter/rector.php or a
  transient failure. Expire on access, self-healing.
- Tests for both behaviors; docs + CHANGELOG + example config.

Author: fdaviddpt

.supertool.example.json

@@ -3,6 +3,8 @@
   "rtk": false,
   "parallel": 0,
   "adviseForNewTest": false,
+  "validator_cache": true,
+  "validator_cache_ttl_hours": 24,
   "presets": [
     "git",
     "github",

CHANGELOG.md

@@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`watch` preset — background event pollers with async wake into Claude Code.** New ops `watch:SOURCE:ID[:only=...]`, `unwatch:SOURCE:ID`, `watches`. Each invocation forks a detached poller that emits state-change events to a UDS socket, a status file, and macOS Notification Center. Source-plugin contract makes new sources ~50 lines. Bundled sources: `github-pr` (PR state, checks, reviews, comments, merge/close, conflicts) and `gitlab-mr` (MR state, pipeline, merge/close, conflicts). Closes [#165](https://github.com/Digital-Process-Tools/claude-supertool/issues/165). See [docs/presets/watch.md](docs/presets/watch.md).
 - **`notifiers/claude-channel/` — MCP channel server for async wake.** TypeScript / Bun server that binds the watch UDS socket and pushes events into a running Claude Code session via the Channels feature (research preview, requires Claude Code v2.1.80+). Events arrive as `<channel source="claude-channel" watcher_source="<source>" id="<id>" event="<event>" ...>` tags. UDS file mode 0600 + localhost-only auth model. Launch with `claude --dangerously-load-development-channels server:claude-channel`. See [notifiers/claude-channel/README.md](notifiers/claude-channel/README.md).
 - **`glob` brace expansion.** `glob:src/**/*.{json,xml}` now fans out into `*.json` + `*.xml` (shell/fd/ripgrep semantics) and dedupes results, instead of silently returning 0 files. Supports multiple groups (`{a,b}.{x,y}` → 4) and nesting (`{a,b{1,2}}` → 3). Patterns without braces are unchanged. Closes [#161](https://github.com/Digital-Process-Tools/claude-supertool/issues/161).
+- **`validator_cache_ttl_hours` config** (default `24`, `0` disables). Validator cache entries expire this long after being written. The cache key only hashes file content, so without a TTL an entry outlives changes it can't see — an updated adapter/`rector.php`, or a transient engine failure. Expiry is on access (stale → miss → re-run → rewrite); no cron needed.
+
+### Fixed
+
+- **Validator cache no longer freezes transient engine failures.** `rector-mcp`'s warm daemon intermittently trips rector's own `System error: "ClassReflection must be resolved for class X"` reflection bug on test classes — warm-process-state dependent, not file dependent (a clean re-run and plain `rector` CLI pass the same file). That failure was cached keyed on file content and replayed on every later run, including its frozen `duration_ms`; 2100 entries were poisoned this way across a test suite. Two-layer fix: (1) `validators/rector-mcp/rector-mcp.py` drops `System error:` results at the source — an engine glitch is not a code finding; (2) the validator cache now excludes non-deterministic engine failures (MCP transport errors, non-zero exits, `System error:` messages) from being written. Real findings (PHPStan types, `rector.refactor`) stay cached.
 
 ## [0.14.0] — 2026-05-23
 

README.md

@@ -161,7 +161,9 @@ Example: edit a `.json` file with a missing comma → `jsonlint` catches it →
 
 18 validators bundled out of the box (PHP, XML, JSON, YAML, INI, Python syntax + types, Bash, JS, TS, SCSS, Markdown, Ruby, Dockerfile, Go, Terraform, Rust, TOML). Graceful skip when toolchain missing.
 
-Full reference: [docs/validators.md](docs/validators.md) — bundled list, how they hook in, adding your own.
+Results are cached per file-content hash and skipped on unchanged files, with a TTL (`validator_cache_ttl_hours`, default 24h) so stale results self-heal. Non-deterministic engine failures are never cached.
+
+Full reference: [docs/validators.md](docs/validators.md) — bundled list, how they hook in, caching, adding your own.
 
 ---
 

docs/validators.md

@@ -178,6 +178,10 @@ Results are auto-cached at `~/.cache/supertool/validators/`, keyed on `sha256(fi
 
 Disable caching per-call with the `SUPERTOOL_NO_VALIDATOR_CACHE=1` env var, or per-project with `"validator_cache": false` in `.supertool.json`.
 
+**TTL.** Entries expire `validator_cache_ttl_hours` after they're written (default `24`; set `0` to disable expiry). The key only hashes file content, so an entry can outlive changes it can't see — an updated validator adapter, a changed `rector.php`, or a transient engine failure a clean re-run would now pass. Expiry is on access: a stale entry is treated as a miss, re-runs, and is rewritten with a fresh timestamp. No cron needed.
+
+**Engine failures are never cached.** Non-deterministic infrastructure errors — MCP transport errors, non-zero adapter exits, and rector's `System error: ...` reflection failures — are excluded from the cache. Real findings (PHPStan types, `rector.refactor` suggestions) are deterministic and stay cached. This prevents a transient warm-daemon hiccup from freezing a failure that replays on every later run. (See `validators/rector-mcp/rector-mcp.py`, which also drops rector `System error:` results at the source.)
+
 ## Manual run
 
 Run validators explicitly against any file without an edit op:

supertool.py

@@ -8582,9 +8582,25 @@ def _validator_cache_read(key: str) -> Optional[Dict[str, Any]]:
     import hashlib
     import hmac
     import json
+    import time
     p = _validator_cache_path(key)
     if not p.exists():
         return None
+    # TTL: the cache key only hashes file content, so an entry can outlive changes
+    # it can't see — an updated validator adapter / rector.php, or a transient engine
+    # failure that a clean re-run would now pass. Expire on access (treat as a miss,
+    # which re-runs and rewrites with a fresh mtime) so no staleness survives past the
+    # window. Config `validator_cache_ttl_hours` (default 24; 0 disables expiry).
+    try:
+        _ttl_hours = float(_load_config().get("validator_cache_ttl_hours", 24))
+    except (TypeError, ValueError):
+        _ttl_hours = 24.0
+    if _ttl_hours > 0:
+        try:
+            if time.time() - p.stat().st_mtime > _ttl_hours * 3600:
+                return None
+        except OSError:
+            return None
     try:
         wrapped = json.loads(p.read_text())
     except (OSError, json.JSONDecodeError):
@@ -8614,6 +8630,43 @@ def _validator_cache_write(key: str, data: Dict[str, Any]) -> None:
         pass
 
 
+# Engine-failure error codes/messages that are NON-deterministic: a clean re-run
+# can flip them. These must never be cached (the cache key is the file's content
+# hash, so a frozen failure replays on every later run until the file changes).
+_NONDETERMINISTIC_ERROR_CODES = {"mcp", "orchestrator", "rector.exit"}
+
+
+def _validator_result_is_cacheable(data: Dict[str, Any]) -> bool:
+    """True unless the result is a non-deterministic engine/transport failure.
+
+    WHY THIS EXISTS (2026-06, the 2100-poisoned-entries incident):
+    rector-mcp's warm daemon intermittently trips rector's own known bug —
+    `System error: "ClassReflection must be resolved for class XTest"` — on test
+    classes. It depends on warm-process state, NOT on the file: a cold/clean
+    daemon (and plain `rector` CLI) reflect the same file fine. But the failed
+    result got cached keyed on file content, so every subsequent run replayed the
+    stale error — same message, same frozen duration_ms — long after the live
+    daemon recovered. 2100 test files were silently "failing" rector this way.
+
+    Real findings stay cacheable (phpstan types, `rector.refactor` suggestions are
+    deterministic — same input, same output, caching them is the whole point).
+    Only engine glitches — MCP transport errors, non-zero exits, and rector's
+    "System error:" reflection failures — are filtered out here so a transient
+    hiccup can't pin itself into the cache. See validators/rector-mcp/rector-mcp.py
+    which also drops "System error:" at the source.
+    """
+    if data.get("ok"):
+        return True
+    for err in data.get("errors") or []:
+        if not isinstance(err, dict):
+            continue
+        if err.get("code") in _NONDETERMINISTIC_ERROR_CODES:
+            return False
+        if str(err.get("msg") or "").startswith("System error:"):
+            return False
+    return True
+
+
 def _validator_run_one(name: str, spec: Dict[str, Any], file: str) -> Optional[Dict[str, Any]]:
     """Run one validator adapter on `file`. Returns SCHEMA.md-compliant dict.
 
@@ -8676,7 +8729,7 @@ def _validator_run_one(name: str, spec: Dict[str, Any], file: str) -> Optional[D
         data["elapsed_s"] = _elapsed
         if target != file:
             data["resolved_to"] = target
-        if cache_key:
+        if cache_key and _validator_result_is_cacheable(data):
             _validator_cache_write(cache_key, data)
         return data
     except subprocess.TimeoutExpired:

tests/test_security_hardening_150.py

@@ -13,6 +13,7 @@
 import os
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 import pytest
@@ -163,3 +164,67 @@ def test_different_secret_invalidates_cache(self, cache_dir, tmp_path):
         # Force regeneration with a fresh secret.
         supertool._validator_cache_secret()
         assert supertool._validator_cache_read("k4") is None
+
+
+class TestValidatorCacheTtl:
+    """TTL expiry on the validator cache read path (validator_cache_ttl_hours)."""
+
+    @pytest.fixture
+    def cache_dir(self, tmp_path, monkeypatch):
+        original_home = Path.home
+        monkeypatch.setattr(Path, "home", classmethod(lambda cls: tmp_path))
+        yield tmp_path / ".cache" / "supertool" / "validators"
+        monkeypatch.setattr(Path, "home", original_home)
+
+    def _set_ttl(self, monkeypatch, hours):
+        monkeypatch.setattr(supertool, "_load_config",
+                            lambda: {"validator_cache_ttl_hours": hours})
+
+    def test_fresh_entry_is_a_hit(self, cache_dir, monkeypatch):
+        self._set_ttl(monkeypatch, 24)
+        data = {"tool": "fake", "ok": True, "count": 0}
+        supertool._validator_cache_write("ttl1", data)
+        assert supertool._validator_cache_read("ttl1") == data
+
+    def test_expired_entry_is_a_miss(self, cache_dir, monkeypatch):
+        self._set_ttl(monkeypatch, 24)
+        data = {"tool": "fake", "ok": True, "count": 0}
+        supertool._validator_cache_write("ttl2", data)
+        # Backdate the file mtime well past the 24h window.
+        old = time.time() - 100 * 3600
+        os.utime(supertool._validator_cache_path("ttl2"), (old, old))
+        assert supertool._validator_cache_read("ttl2") is None
+
+    def test_ttl_zero_disables_expiry(self, cache_dir, monkeypatch):
+        self._set_ttl(monkeypatch, 0)
+        data = {"tool": "fake", "ok": True, "count": 0}
+        supertool._validator_cache_write("ttl3", data)
+        old = time.time() - 100 * 3600
+        os.utime(supertool._validator_cache_path("ttl3"), (old, old))
+        assert supertool._validator_cache_read("ttl3") == data
+
+
+class TestValidatorResultIsCacheable:
+    """Non-deterministic engine failures must not be cached (poisoning guard)."""
+
+    def test_ok_result_is_cacheable(self):
+        assert supertool._validator_result_is_cacheable({"ok": True, "errors": []})
+
+    def test_real_finding_is_cacheable(self):
+        data = {"ok": False, "errors": [
+            {"code": "rector.refactor", "msg": "Would apply SomeRector"}]}
+        assert supertool._validator_result_is_cacheable(data)
+
+    def test_rector_system_error_not_cacheable(self):
+        data = {"ok": False, "errors": [
+            {"code": "rector.error",
+             "msg": 'System error: "ClassReflection must be resolved for class XTest"'}]}
+        assert not supertool._validator_result_is_cacheable(data)
+
+    def test_mcp_transport_error_not_cacheable(self):
+        data = {"ok": False, "errors": [{"code": "mcp", "msg": "connection refused"}]}
+        assert not supertool._validator_result_is_cacheable(data)
+
+    def test_exit_code_failure_not_cacheable(self):
+        data = {"ok": False, "errors": [{"code": "rector.exit", "msg": "rector exit 1"}]}
+        assert not supertool._validator_result_is_cacheable(data)

validators/rector-mcp/rector-mcp.py

@@ -191,10 +191,17 @@ def format_response(file_path: str, mcp_resp: dict, duration_ms: int) -> dict:
                 "diff": diff,
             })
         if errors:
-            base["ok"] = False
             for e in errors:
-                base["count"] += 1
                 msg = e.get("message", str(e)) if isinstance(e, dict) else str(e)
+                # Rector's warm in-process engine intermittently fails to resolve a
+                # BetterReflection for the analyzed class and emits
+                # "System error: ... must be resolved". It's an engine/reflection
+                # failure, NOT a code finding — plain rector CLI runs the same file
+                # clean — so suppress it: don't fail, don't print, don't get cached.
+                if msg.startswith("System error:"):
+                    continue
+                base["ok"] = False
+                base["count"] += 1
                 # Cap msg — rector can dump diffs that explode validator output.
                 # Override via env: RECTOR_MCP_MSG_MAX_CHARS.
                 _cap = int(os.environ.get("RECTOR_MCP_MSG_MAX_CHARS", "2000"))