okstra 0.153.0 → 0.154.0

package/docs/project-structure-overview.md

@@ -243,7 +243,7 @@ Important modules:
 | `build_tools.py` | allowlist SSOT for deciding whether a plan's command cell invokes the project build toolchain (`npm`/`pytest`/`cargo`/`gradle`/… behind transparent leaders like `sudo`/`env`). The planning worktree has no dependencies installed, so `validators/validate-run.py` uses this to warn (advisory) when a toolchain stage declares no install precondition. Intentionally an allowlist, not a denylist, so unknown tokens go undetected rather than firing on `grep`/`sed` in every plan |
 | `stage_citations.py` | shared grammar SSOT for reading the Stage Map stage numbers a prose cell cites (`Stages 1, 2, and 3`, ranges, etc.). One definition serves two readers that must not drift — the coverage check in `validators/validate-run.py` proving every stage traces to a requirement, and `incremental_scope.py`'s back-trace resolving which stages an answered clarification touches |
 | `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
-| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
+| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `python` → Cosmic Ray, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). The Python adapter activates only when the worktree has both an installed `cosmic-ray` executable and `cosmic-ray.toml`; Okstra never installs it. It verifies that `module-path` covers every changed Python target and that no target is excluded, snapshots the configured Python source bytes and modes, restores them after every run, and filters the JSONL dump to diff-added lines. A completed session with no applicable operator on a changed line is `nothing-to-verify`; malformed configuration, command/report failures, incomplete trials, and failed source restoration are blocking `integrity-inspection` results. `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
@@ -386,7 +386,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 | `validate-schedule.py` | Schedule section/order/code validation |
 | `validate-implementation-plan-stages.py` | enforces the Stage Map structure — checks the S1–S8 rules (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` sections, ≤ 8 steps per stage, etc.) |
 | `validate_improvement_report.py` | enforces the 11-item contract of the improvement-discovery final-report. Automatically invoked by `validate-run.py` when `task_type == "improvement-discovery"` |
-| `detect_self_mock.py` | self-mock detector — runs BOTH gates and writes the run's sidecar. Gate A (static) scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Gate B (mutation) runs in the same call: `--changed-file` takes the stage's WHOLE changed set (each adapter selects its own production sources out of it), `--diff` and `--worktree` scope it, and `scripts/okstra_ctl/mutation_probe.py` writes the result into the sidecar's `mutation` block; the received set is recorded as `changedFiles` so the gate can prove gate B was not handed an empty input. `overall` and the exit code follow BOTH gates — a mutation FAIL with a clean static scan still exits 1. The same `--waivers` file feeds both (gate A reads its `signal` entries, gate B its `mutant` ones). Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
+| `detect_self_mock.py` | self-mock detector — runs BOTH gates and writes the run's sidecar. Gate A (static) scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Python strings and comments are token-masked without changing line positions before those regexes run, so examples in docstrings and comments do not become findings while executable `patch.object(self, ...)` and `sut._private` accesses remain detectable. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Gate B (mutation) runs in the same call: `--changed-file` takes the stage's WHOLE changed set (each adapter selects its own production sources out of it), `--diff` and `--worktree` scope it, and `scripts/okstra_ctl/mutation_probe.py` writes the result into the sidecar's `mutation` block; the received set is recorded as `changedFiles` so the gate can prove gate B was not handed an empty input. `overall` and the exit code follow BOTH gates — a mutation FAIL with a clean static scan still exits 1. The same `--waivers` file feeds both (gate A reads its `signal` entries, gate B its `mutant` ones). Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.153.0",
+  "version": "0.154.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.153.0",
-  "builtAt": "2026-08-05T13:40:55.050Z",
+  "package": "0.154.0",
+  "builtAt": "2026-08-05T16:08:35.394Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/mutation_probe.py

@@ -61,16 +61,22 @@ branches and would pass by falling between them.
 
 `ADAPTERS` is keyed by the `self_mock_signals.EXT_TO_LANG` vocabulary — the same
 lang names gate A resolves a changed file to — so both gates answer to one set
-of language keys: `ts_js` (Stryker), `rust` (cargo-mutants), and `java`/`kotlin`
-(PIT, whose diff scoping is not wired up yet — see `PitAdapter`).
+of language keys: `ts_js` (Stryker), `python` (Cosmic Ray), `rust`
+(cargo-mutants), and `java`/`kotlin` (PIT, whose diff scoping is not wired up
+yet — see `PitAdapter`).
 """
 from __future__ import annotations
 
+import fnmatch
 import json
+import os
 import re
 import shutil
+import stat
 import subprocess
 import sys
+import tempfile
+import tomllib
 from pathlib import Path
 from typing import NamedTuple, Protocol
 
@@ -413,6 +419,414 @@ class StrykerAdapter:
             return None
 
 
+COSMIC_RAY_CONFIG_PATH = Path("cosmic-ray.toml")
+
+_COSMIC_WORKER_OUTCOMES = (
+    "normal",
+    "abnormal",
+    "exception",
+    "no-test",
+    "skipped",
+)
+_COSMIC_TEST_OUTCOMES = ("killed", "survived", "incompetent", None)
+_COSMIC_CONCLUSIVE = ("killed", "survived")
+_COSMIC_SESSION_FAILURES = (
+    "init-failed",
+    "baseline-failed",
+    "exec-failed",
+    "dump-failed",
+)
+
+
+class SourceState(NamedTuple):
+    """Bytes and permissions Cosmic Ray must leave unchanged."""
+
+    data: bytes
+    mode: int
+
+
+class CosmicRayScope(NamedTuple):
+    """Validated configuration and every Python source it may mutate."""
+
+    config_path: Path
+    sources: tuple[Path, ...]
+
+
+class CosmicRayConfig(NamedTuple):
+    """The source roots and exclusions declared by ``cosmic-ray.toml``."""
+
+    module_paths: tuple[Path, ...]
+    excluded_patterns: tuple[str, ...]
+
+
+class CosmicRaySession(NamedTuple):
+    """The external CLI's dump, or the command that prevented one."""
+
+    dump_text: str | None
+    failure_reason: str | None
+
+
+class CosmicRayScopeError(ValueError):
+    """A stable unsupported reason for an unsafe or incomplete config scope."""
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+        self.reason = reason
+
+
+def _cosmic_ray_executable(worktree: Path | None) -> Path | None:
+    """Find an installed Cosmic Ray executable without starting a process."""
+    if worktree is None:
+        return None
+    root = Path(worktree)
+    local_paths = (
+        Path(".venv/bin/cosmic-ray"),
+        Path("venv/bin/cosmic-ray"),
+        Path(".venv/Scripts/cosmic-ray.exe"),
+        Path("venv/Scripts/cosmic-ray.exe"),
+    )
+    for relative in local_paths:
+        candidate = root / relative
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return candidate
+    found = shutil.which("cosmic-ray")
+    return Path(found) if found else None
+
+
+def _is_within(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def _cosmic_config(config_path: Path, root: Path) -> CosmicRayConfig:
+    try:
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise CosmicRayScopeError("config-unreadable") from exc
+    config = data.get("cosmic-ray")
+    raw = config.get("module-path") if isinstance(config, dict) else None
+    values = [raw] if isinstance(raw, str) else raw
+    if not isinstance(values, list) or not values:
+        raise CosmicRayScopeError("config-unreadable")
+    if any(not isinstance(value, str) or not value.strip() for value in values):
+        raise CosmicRayScopeError("config-unreadable")
+    paths = tuple(
+        (root / value).resolve()
+        if not Path(value).is_absolute()
+        else Path(value).resolve()
+        for value in values
+    )
+    if any(not _is_within(path, root) for path in paths):
+        raise CosmicRayScopeError("config-unreadable")
+    exclusions: list[str] = []
+    for key in ("excluded-modules", "exclude-modules"):
+        raw_exclusions = config.get(key, [])
+        if not isinstance(raw_exclusions, list) or any(
+            not isinstance(pattern, str) or not pattern.strip()
+            for pattern in raw_exclusions
+        ):
+            raise CosmicRayScopeError("config-unreadable")
+        exclusions.extend(raw_exclusions)
+    return CosmicRayConfig(paths, tuple(exclusions))
+
+
+def _cosmic_target_is_excluded(
+    target: Path,
+    root: Path,
+    patterns: tuple[str, ...],
+) -> bool:
+    relative = target.relative_to(root).as_posix()
+    return any(
+        fnmatch.fnmatchcase(relative, pattern) or Path(relative).match(pattern)
+        for pattern in patterns
+    )
+
+
+def _configured_cosmic_sources(
+    module_paths: tuple[Path, ...],
+    root: Path,
+) -> tuple[Path, ...]:
+    sources: set[Path] = set()
+    for module_path in module_paths:
+        if module_path.is_file() and module_path.suffix == ".py":
+            candidates = (module_path,)
+        elif module_path.is_dir():
+            candidates = tuple(module_path.rglob("*.py"))
+        else:
+            raise CosmicRayScopeError("config-unreadable")
+        for candidate in candidates:
+            if candidate.is_symlink():
+                raise CosmicRayScopeError("config-unreadable")
+            resolved = candidate.resolve()
+            if not _is_within(resolved, root) or not resolved.is_file():
+                raise CosmicRayScopeError("config-unreadable")
+            sources.add(resolved)
+    return tuple(sorted(sources))
+
+
+def _read_cosmic_ray_scope(worktree: Path, targets: list[Path]) -> CosmicRayScope:
+    root = Path(worktree).resolve()
+    config_path = root / COSMIC_RAY_CONFIG_PATH
+    config = _cosmic_config(config_path, root)
+    resolved_targets = tuple(
+        (root / target).resolve() if not target.is_absolute() else target.resolve()
+        for target in targets
+    )
+    if any(
+        not _is_within(target, root)
+        or _cosmic_target_is_excluded(target, root, config.excluded_patterns)
+        for target in resolved_targets
+    ):
+        raise CosmicRayScopeError("config-target-mismatch")
+    if any(
+        not any(
+            target == module_path
+            or (module_path.is_dir() and _is_within(target, module_path))
+            for module_path in config.module_paths
+        )
+        for target in resolved_targets
+    ):
+        raise CosmicRayScopeError("config-target-mismatch")
+    sources = _configured_cosmic_sources(config.module_paths, root)
+    if any(target not in sources for target in resolved_targets):
+        raise CosmicRayScopeError("config-target-mismatch")
+    return CosmicRayScope(config_path, sources)
+
+
+def _snapshot_source_state(sources: tuple[Path, ...]) -> dict[Path, SourceState]:
+    return {
+        path: SourceState(
+            path.read_bytes(),
+            stat.S_IMODE(path.stat(follow_symlinks=False).st_mode),
+        )
+        for path in sources
+    }
+
+
+def _restore_source_state(states: dict[Path, SourceState]) -> bool:
+    restored = True
+    for path, expected in states.items():
+        try:
+            if path.is_symlink() or (path.exists() and not path.is_file()):
+                restored = False
+                continue
+            if not path.exists() or path.read_bytes() != expected.data:
+                path.write_bytes(expected.data)
+            path.chmod(expected.mode)
+            actual = SourceState(
+                path.read_bytes(),
+                stat.S_IMODE(path.stat(follow_symlinks=False).st_mode),
+            )
+            restored = restored and actual == expected
+        except OSError:
+            restored = False
+    return restored
+
+
+def _run_cosmic_ray_session(
+    executable: Path,
+    config_path: Path,
+    session_path: Path,
+    worktree: Path,
+) -> CosmicRaySession:
+    root = Path(worktree)
+    try:
+        config_arg = str(config_path.relative_to(root))
+    except ValueError:
+        config_arg = str(config_path)
+    commands = (
+        ("init", [str(executable), "init", config_arg, str(session_path)]),
+        (
+            "baseline",
+            [str(executable), "baseline", "--report", config_arg, str(session_path)],
+        ),
+        ("exec", [str(executable), "exec", config_arg, str(session_path)]),
+        ("dump", [str(executable), "dump", str(session_path)]),
+    )
+    for verb, argv in commands:
+        try:
+            completed = subprocess.run(
+                argv,
+                cwd=str(root),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError:
+            return CosmicRaySession(None, f"{verb}-failed")
+        if completed.returncode != 0:
+            return CosmicRaySession(None, f"{verb}-failed")
+        if verb == "dump":
+            return CosmicRaySession(completed.stdout, None)
+    return CosmicRaySession(None, "dump-failed")
+
+
+def _cosmic_diff_file(diff: object, worktree: Path) -> str | None:
+    if not isinstance(diff, list) or any(not isinstance(line, str) for line in diff):
+        return None
+    new_paths = [line[4:].split("\t", 1)[0] for line in diff if line.startswith("+++ ")]
+    if len(new_paths) != 1 or new_paths[0] == "/dev/null":
+        return None
+    raw = new_paths[0]
+    if raw.startswith("b/"):
+        raw = raw[2:]
+    candidate = Path(raw)
+    root = Path(worktree).resolve()
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+    else:
+        if ".." in candidate.parts:
+            return None
+        absolute_style = (Path("/") / candidate).resolve()
+        resolved = (
+            absolute_style if _is_within(absolute_style, root) else root / candidate
+        )
+    if not _is_within(resolved, root):
+        return None
+    return str(resolved.relative_to(root))
+
+
+def _parse_cosmic_ray_dump(
+    dump_text: str,
+    diff_path: Path | None,
+    worktree: Path,
+) -> ParsedReport | None:
+    scope = read_diff(diff_path)
+    if scope is None:
+        return None
+    survivors: list[dict] = []
+    observed = 0
+    conclusive = 0
+    for raw in dump_text.splitlines():
+        if not raw.strip():
+            continue
+        try:
+            row = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(row, dict):
+            return None
+        worker = row.get("worker_outcome")
+        outcome = row.get("test_outcome")
+        file = _cosmic_diff_file(row.get("diff"), worktree)
+        line = _coerce_line(row.get("line_number"))
+        operator = row.get("operator")
+        occurrence = row.get("occurrence")
+        if (
+            worker not in _COSMIC_WORKER_OUTCOMES
+            or outcome not in _COSMIC_TEST_OUTCOMES
+        ):
+            return None
+        if worker == "normal" and outcome is None:
+            return None
+        if file is None or line is None or line < 1:
+            return None
+        if not isinstance(operator, str) or not operator.strip():
+            return None
+        if not isinstance(occurrence, int) or isinstance(occurrence, bool):
+            return None
+        if line not in scope.touched.get(selfmock_path_key(file), ()):
+            continue
+        observed += 1
+        if worker == "normal" and outcome in _COSMIC_CONCLUSIVE:
+            conclusive += 1
+        if worker == "normal" and outcome == "survived":
+            survivors.append(
+                {
+                    "file": file,
+                    "line": line,
+                    "mutant": f"{operator}#{occurrence}",
+                    "status": outcome,
+                }
+            )
+    return ParsedReport(survivors, conclusive, observed)
+
+
+def _cosmic_session_verdict(
+    session: CosmicRaySession,
+    diff_path: Path | None,
+    worktree: Path,
+    tool: str,
+) -> ProbeResult:
+    if not isinstance(session, CosmicRaySession):
+        return unsupported("report-unparsed", tool=tool)
+    if session.failure_reason is not None:
+        if session.failure_reason not in _COSMIC_SESSION_FAILURES:
+            return unsupported("report-unparsed", tool=tool)
+        return unsupported(session.failure_reason, tool=tool)
+    if not isinstance(session.dump_text, str):
+        return unsupported("report-unparsed", tool=tool)
+    parsed = _parse_cosmic_ray_dump(session.dump_text, diff_path, worktree)
+    if parsed is None:
+        return unsupported("report-unparsed", tool=tool)
+    if parsed.observed == 0:
+        return unsupported("no-mutable-changed-lines", tool=tool)
+    return _verdict_from_parsed(parsed, diff_path, worktree, tool)
+
+
+class CosmicRayAdapter:
+    """Gate B for Python, wrapping an explicitly configured Cosmic Ray CLI."""
+
+    name = "cosmic-ray"
+
+    def __init__(self, runner=_run_cosmic_ray_session):
+        self._runner = runner
+
+    def is_declared(self, worktree: Path | None) -> bool:
+        if worktree is None:
+            return False
+        root = Path(worktree)
+        return (root / COSMIC_RAY_CONFIG_PATH).is_file() and (
+            _cosmic_ray_executable(root) is not None
+        )
+
+    def run(
+        self,
+        targets: list[Path],
+        diff_path: Path | None,
+        worktree: Path | None,
+    ) -> ProbeResult:
+        if worktree is None:
+            return unsupported("config-unreadable", tool=self.name)
+        root = Path(worktree)
+        executable = _cosmic_ray_executable(root)
+        if executable is None:
+            return unsupported("tool-not-declared", tool=self.name)
+        try:
+            scope = _read_cosmic_ray_scope(root, targets)
+            states = _snapshot_source_state(scope.sources)
+        except CosmicRayScopeError as exc:
+            return unsupported(exc.reason, tool=self.name)
+        except OSError:
+            return unsupported("source-integrity-failed", tool=self.name)
+        result: ProbeResult
+        try:
+            with tempfile.TemporaryDirectory(prefix="okstra-cosmic-ray-") as temp_dir:
+                session_path = Path(temp_dir) / "session.sqlite"
+                session = self._runner(
+                    executable,
+                    scope.config_path,
+                    session_path,
+                    root,
+                )
+                result = _cosmic_session_verdict(
+                    session,
+                    diff_path,
+                    root,
+                    self.name,
+                )
+        except OSError:
+            result = unsupported("exec-failed", tool=self.name)
+        finally:
+            sources_restored = _restore_source_state(states)
+        if not sources_restored:
+            return unsupported("source-integrity-failed", tool=self.name)
+        return result
+
+
 CARGO_OUTCOMES_PATH = Path("mutants.out/outcomes.json")
 
 # cargo-mutants' own vocabulary: `caught` (a test failed, good), `missed` (no
@@ -665,6 +1079,7 @@ class PitAdapter:
 _PIT = PitAdapter()
 ADAPTERS: dict[str, Adapter] = {
     "ts_js": StrykerAdapter(),
+    "python": CosmicRayAdapter(),
     "rust": CargoMutantsAdapter(),
     "java": _PIT,
     "kotlin": _PIT,
@@ -1107,6 +1522,7 @@ CAPABILITY_GAP_REASONS = frozenset(
 NOTHING_TO_VERIFY_REASONS = frozenset(
     {
         "no-mutants-generated",
+        "no-mutable-changed-lines",
         "diff-adds-no-line",
     }
 )
@@ -1127,6 +1543,13 @@ INTEGRITY_INSPECTION_REASONS = frozenset(
         "report-unparsed",
         "adapter-malformed-status",
         "no-conclusive-mutants",
+        "config-unreadable",
+        "config-target-mismatch",
+        "init-failed",
+        "baseline-failed",
+        "exec-failed",
+        "dump-failed",
+        "source-integrity-failed",
     }
 )
 

package/runtime/validators/detect_self_mock.py

@@ -41,8 +41,10 @@ redirecting ``--waivers`` at a self-authored file blocks instead of passing.
 from __future__ import annotations
 
 import argparse
+import io
 import json
 import sys
+import tokenize
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -91,16 +93,39 @@ def scannable_files(paths: list[Path]) -> list[Path]:
     return [p for p in paths if is_scannable(p)]
 
 
+def _mask_python_non_code(text: str) -> str:
+    """Blank Python strings and comments without moving any match positions."""
+    chars = list(text)
+    line_offsets = [0]
+    for line in text.splitlines(keepends=True):
+        line_offsets.append(line_offsets[-1] + len(line))
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(text).readline)
+        for token in tokens:
+            if token.type not in {tokenize.STRING, tokenize.COMMENT}:
+                continue
+            start = line_offsets[token.start[0] - 1] + token.start[1]
+            end = line_offsets[token.end[0] - 1] + token.end[1]
+            for index in range(start, end):
+                if chars[index] not in "\r\n":
+                    chars[index] = " "
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        # Broken source is scanned conservatively so a syntax error cannot hide a hit.
+        return text
+    return "".join(chars)
+
+
 def scan_files(paths: list[Path]) -> list[dict]:
     """Return one hit dict ``{file, line, signal}`` per signal match."""
     hits: list[dict] = []
     for p in scannable_files(paths):
         lang = EXT_TO_LANG[p.suffix]
         text = p.read_text(encoding="utf-8", errors="replace")
+        scan_text = _mask_python_non_code(text) if lang == "python" else text
         file_hits: list[dict] = []
         for sig in SIGNALS.get(lang, []):
-            for m in sig.pattern.finditer(text):
-                line = text[: m.start()].count("\n") + 1
+            for m in sig.pattern.finditer(scan_text):
+                line = scan_text[: m.start()].count("\n") + 1
                 file_hits.append({"file": str(p), "line": line, "signal": sig.name})
         hits.extend(sorted(file_hits, key=lambda h: (h["line"], h["signal"])))
     return hits