pi-dev-team 0.2.0

package/skills/mutation-testing/scripts/mutation_kill_headless.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""mutation_kill_headless.py — unattended generation + CLI entry point.
+
+Split out of ``mutation_kill_loop.py`` (#1562): the ``--headless`` CLI
+argument parsing and entry point for the C#/Stryker.NET loop. The
+agent-driven (default, interactive) path never touches this module — the
+mutation-kill agent calls :func:`mutation_kill_loop.run_for_file` directly
+with its own ``generate`` hook.
+
+The ``claude --print`` invocation glue itself (``run_claude_headless``,
+``resolve_model``, ``strip_code_fences``, ``claude_cli_available``,
+``CLAUDE_CLI``) lives in ``mutation_kill_shared.py``, not here (#1601) — it's
+reused verbatim by ``mutation_kill_loop_python.py``, and none of it is
+C#-specific. This module only builds the C#-flavored prompt
+(``build_generation_prompt``) and imports the handful of shared names it
+actually calls (``CLAUDE_CLI``, ``resolve_model``, ``claude_cli_available``,
+``run_claude_headless``); ``mutation_kill_loop_python.py`` now imports the
+same names directly from ``mutation_kill_shared`` too, rather than through
+this module, which previously dragged the whole C#/Stryker.NET stack
+(``mutation_kill_loop`` and everything it imports) into the Python loop just
+to reuse five language-neutral names.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from mutation_kill_loop import Generator, RunContext, load_loop_config, run_for_file
+from mutation_kill_retry import (
+    EXIT_GENERATION_EXHAUSTED,
+    EXIT_REVERT_FAILED,
+    DowngradeEvent,
+    GenerationExhausted,
+    make_downgrade_audit_hook,
+    make_retrying_headless_call,
+)
+from mutation_kill_shared import (
+    CLAUDE_CLI,
+    RevertFailed,
+    claude_cli_available,
+    resolve_model,
+    run_claude_headless,  # noqa: F401 — re-exported for tests (headless.run_claude_headless identity check); make_headless_generator now calls it indirectly via make_retrying_headless_call (#1908)
+)
+
+# The exact message the bare-CLI startup preflight prints. Pinned so the
+# contract test can assert it verbatim.
+NO_GENERATOR_MESSAGE = (
+    "no test generator available — invoke via the mutation-kill agent "
+    "or pass --headless"
+)
+
+# Printed when --headless is requested but the Claude CLI can't be reached.
+# Names exactly how to install and authenticate it, and mutates no files.
+MISSING_CLAUDE_MESSAGE = (
+    f"--headless requires the Claude CLI but '{CLAUDE_CLI}' is not available. "
+    "Install Claude Code (`npm install -g @anthropic-ai/claude-code`) and "
+    "authenticate it (run `claude` once to log in, or set ANTHROPIC_API_KEY) — "
+    "or set CLAUDE_BIN to the CLI's path."
+)
+
+
+def build_survivor_summary(survivors: list[dict], *, limit: int = 40) -> str:
+    """Render surviving mutants as a compact, framework-agnostic list."""
+    lines = []
+    for mutant in survivors[:limit]:
+        line = mutant.get("location", {}).get("start", {}).get("line", "?")
+        mutator = mutant.get("mutatorName", "?")
+        replacement = mutant.get("replacement", "")
+        lines.append(f"- L{line} {mutator}: {replacement}".rstrip())
+    if len(survivors) > limit:
+        lines.append(f"- … and {len(survivors) - limit} more")
+    return "\n".join(lines)
+
+
+def build_generation_prompt(
+    source_file: str,
+    survivors: list[dict],
+    source_text: str,
+    test_text: str,
+    *,
+    source_limit: int = 8000,
+) -> str:
+    """Build the generation prompt.
+
+    The existing test file is the *only* pattern — assertion library, mocking
+    approach, fixtures, and naming conventions are all inferred from it. No
+    library name is hardcoded here, so the prompt is repo-agnostic (AC1).
+    """
+    return (
+        f"You are adding new test methods that KILL surviving mutations in "
+        f"{source_file}.\n\n"
+        "Match the existing test file exactly: its imports, assertion style, "
+        "mocking approach, fixtures, and naming conventions are the pattern to "
+        "follow. Do not introduce any library, helper, or convention that does "
+        "not already appear in it.\n\n"
+        f"## Surviving mutations ({len(survivors)})\n"
+        f"{build_survivor_summary(survivors)}\n\n"
+        f"## Source under test\n{source_text[:source_limit]}\n\n"
+        f"## Existing test file (the pattern to match)\n{test_text}\n\n"
+        "## Rules\n"
+        "1. Return ONLY the new test methods — no class wrapper, namespace, or "
+        "imports.\n"
+        "2. Each must compile against the helpers already in the existing test "
+        "file.\n"
+        "3. Reuse the existing file's assertion, mocking, and fixture patterns "
+        "exactly.\n"
+        "4. Match the existing naming convention.\n"
+        "5. Do not redeclare fields or helpers already present.\n"
+        "6. Do not emit closing braces for the class or namespace.\n"
+    )
+
+
+def make_headless_generator(
+    model: str | None = None,
+    *,
+    cwd: Path | None = None,
+    log: Callable[[str], None] = print,
+    on_downgrade: Callable[[DowngradeEvent], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Generator:
+    """Return a :data:`mutation_kill_loop.Generator` that shells to
+    ``claude --print``.
+
+    The returned callable builds the prompt from the existing test file (the
+    pattern) plus the survivor summary, then delegates everything else to
+    :func:`mutation_kill_retry.make_retrying_headless_call` (#1908) — the
+    3-consecutive-gateway-class-failures/1-same-model-retry/at-most-once-
+    per-file-downgrade wrapper around :func:`run_claude_headless`.
+
+    The retry/downgrade state (consecutive-failure counter, model in use,
+    whether this file already spent its one downgrade) lives in the
+    ``retrying_call`` closure below — constructed once per file, here, never
+    at module scope — so a new file's generator always starts fresh at the
+    top of the ladder regardless of a prior file's downgrade, and concurrent
+    files under ``--all --concurrency`` (each with their own closure) never
+    leak state to one another. ``round_num`` is derived from how many times
+    THIS closure has been invoked (the loop calls its ``generate`` once per
+    round), since the shared :data:`Generator` signature carries no round
+    number of its own.
+
+    ``on_downgrade``, when given, is passed straight through to
+    :func:`mutation_kill_retry.make_retrying_headless_call`. Building the
+    ``on_downgrade``/``get_label_override`` audit-trail pair
+    (:func:`mutation_kill_retry.make_downgrade_audit_hook`) is this
+    module's own ``main()``'s job now (#1908 review) — this function no
+    longer constructs one internally or attaches a
+    ``label_override_provider`` attribute to the returned ``generate``;
+    ``main()`` has ``get_label_override`` directly in scope and wires it
+    into :class:`RunContext` itself, so no attribute-smuggling is needed.
+    """
+    retrying_call = make_retrying_headless_call(
+        initial_model=model, cwd=cwd, log=log, on_downgrade=on_downgrade, sleep=sleep
+    )
+    round_counter = {"n": 0}
+
+    def generate(
+        source_file: str,
+        survivors: list[dict],
+        source_text: str,
+        test_text: str,
+    ) -> str:
+        round_counter["n"] += 1
+        prompt = build_generation_prompt(source_file, survivors, source_text, test_text)
+        return retrying_call(prompt, source_file, round_counter["n"])
+
+    return generate
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="mutation_kill_loop.py",
+        description=(
+            "Config-driven survivor-kill loop. Agent-driven by default; "
+            "--headless enables unattended generation via the Claude CLI."
+        ),
+    )
+    p.add_argument("--config", default="stryker-config.json", help="stryker-config.json path")
+    p.add_argument("--file", help="Source file to target (basename or path)")
+    p.add_argument("--output", default="StrykerOutput/agent", help="Scoped-run output dir")
+    p.add_argument("--max-rounds", type=int, default=5, help="Max rounds per file")
+    p.add_argument(
+        "--stryker-bin",
+        default=os.environ.get("STRYKER_BIN", "dotnet"),
+        help="Stryker executable name, or 'dotnet' to invoke a local-tool-"
+        "manifest install via 'dotnet stryker' (default: %(default)s)",
+    )
+    p.add_argument(
+        "--headless",
+        action="store_true",
+        help="Unattended generation via `claude --print` (CI / shard pipeline).",
+    )
+    p.add_argument(
+        "--model",
+        help=(
+            "Generation model for --headless. Default: DEV_TEAM_MUTATION_MODEL "
+            "env var, else omitted so `claude --print` uses its own default."
+        ),
+    )
+    p.add_argument("--test-file", help="Test file to extend (required with --headless)")
+    p.add_argument("--source-path", help="Source file under test (required with --headless)")
+    p.add_argument(
+        "--target-honest-score",
+        type=float,
+        default=None,
+        help=(
+            "Phase-0 mutation target (percent). Stop a file once its honest "
+            "score reaches this, since work past the threshold cannot change "
+            "the Phase-8 verdict. Default off — unset reproduces pre-#2030 "
+            "behavior exactly."
+        ),
+    )
+    p.add_argument(
+        "--min-kills-per-round",
+        type=float,
+        default=None,
+        help=(
+            "Marginal-yield floor. >=1 is an absolute kill count; 0<v<1 is a "
+            "fraction of the round's starting survivors. A round below the "
+            "floor while still under target is surfaced to the operator "
+            "([c]ontinue / [r]etry / [w]aive / [q]uit), never stopped "
+            "silently. Default off."
+        ),
+    )
+    p.add_argument("--report", help="Initial mutation report to seed round 1 (--headless)")
+    return p.parse_args(list(argv))
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point.
+
+    The CLI has no way to inject an agent generator (that path calls
+    :func:`mutation_kill_loop.run_for_file` directly). So without
+    ``--headless`` there is no generator, and we fail fast **at startup** —
+    before resolving config, probing DOTNET_ROOT, running Stryker, or
+    touching any file.
+
+    With ``--headless`` the generator shells to ``claude --print``. The Claude
+    CLI is preflight-checked *before* any file argument validation, so a
+    missing CLI fails cleanly at startup and mutates nothing.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args = parse_args(argv)
+
+    if not args.headless:
+        sys.stderr.write(f"error: {NO_GENERATOR_MESSAGE}\n")
+        return 1
+
+    model = resolve_model(args.model)
+
+    # Preflight the CLI first — a missing CLI must fail before we touch any
+    # file or validate run arguments.
+    if not claude_cli_available():
+        sys.stderr.write(f"error: {MISSING_CLAUDE_MESSAGE}\n")
+        return 3
+
+    if not (args.file and args.test_file and args.source_path):
+        sys.stderr.write(
+            "error: --headless requires --file, --test-file, and --source-path\n"
+        )
+        return 2
+
+    on_downgrade, get_label_override = make_downgrade_audit_hook()
+    generate = make_headless_generator(model, on_downgrade=on_downgrade)
+    try:
+        run_for_file(
+            args.file,
+            RunContext(
+                config=load_loop_config(Path(args.config)),
+                test_file=Path(args.test_file),
+                source_path=Path(args.source_path),
+                output_dir=Path(args.output),
+                stryker_bin=args.stryker_bin,
+                initial_report_path=Path(args.report) if args.report else None,
+                generator_label=f"headless ({model or 'default'})",
+                label_override_provider=get_label_override,
+                target_honest_score=args.target_honest_score,
+                min_kills_per_round=args.min_kills_per_round,
+            ),
+            generate=generate,
+            max_rounds=args.max_rounds,
+        )
+    except GenerationExhausted as exc:
+        # This file's retry-then-downgrade budget is fully spent (3
+        # consecutive gateway-class failures + 1 same-model retry, at the
+        # original model AND at most one fallback tier) — distinct from
+        # RevertFailed below (exit 4, working tree possibly mutated) and
+        # from the generic RuntimeError case below it (exit 5, clean but
+        # not exhausted — e.g. a non-gateway-class generation timeout). A
+        # clean exhaustion mutates nothing: generation precedes insertion
+        # within a round, and a prior round's own revert failure is itself
+        # fatal (raised as RevertFailed, never swallowed). What isn't
+        # independently re-verified here is that a revert git reports as
+        # successful actually left the tree clean (#1955) — so callers
+        # (stryker_shard_pipeline.py's shard driver) can log this file as
+        # unfixed and continue to the next file without affecting the run's
+        # exit status, instead of aborting the whole shard (#1908 review).
+        sys.stderr.write(f"error: {exc}\n")
+        return EXIT_GENERATION_EXHAUSTED
+    except RevertFailed as exc:
+        # A failed revert (or a failed-commit round-abandonment's own
+        # revert) leaves the working tree in an unknown, possibly-mutated
+        # state (#1930) — narrower and more urgent than the generic
+        # RuntimeError case below: this is the only case that can't be
+        # trusted as clean.
+        sys.stderr.write(f"error: {exc}\n")
+        return EXIT_REVERT_FAILED
+    except RuntimeError as exc:
+        # Every other RuntimeError this loop raises (a generation timeout,
+        # a mutmut/Stryker infrastructure failure, etc.) is clean with
+        # respect to inserted test content — generation precedes insertion,
+        # and a failed insertion-revert is RevertFailed, caught above. The
+        # C# solution-file restore (wrapper.restore_sln) now also reports a
+        # bool outcome (#1955) and run_scoped_stryker raises RevertFailed on
+        # a False return, so a stray hidden .sln is caught by the
+        # RevertFailed branch above, not silently reaching here. Not a
+        # retry-budget exhaustion — reuses exit 5 (#1956: this is the
+        # OUTCOME class, not a specific cause) because the shard driver only
+        # distinguishes "fatal, stop" (4) from "clean, continue" (5), not
+        # why a file wasn't fixed.
+        sys.stderr.write(f"error: {exc} — generation failed cleanly, continuing\n")
+        return EXIT_GENERATION_EXHAUSTED
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/mutation-testing/scripts/mutation_kill_insert.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""mutation_kill_insert.py — C# test-method insertion mechanics.
+
+Split out of ``mutation_kill_loop.py`` (#1562): detect-or-refuse insertion of
+generated test methods before a test class's closing brace. The heuristic
+supports only conventional block-namespace, 4-space-indented C# test classes
+— a file-scoped namespace or non-4-space indentation is refused rather than
+risk a mis-insertion.
+
+``InsertOutcome``/``InsertionRefused`` are imported from
+``mutation_kill_shared`` (#1583, relocated from ``mutation_safety_gate`` in
+#1602), not defined here — they're structurally identical to the Python
+sibling's (``mutation_kill_insert_python.py``), so both modules share one
+definition instead of two hand-maintained copies. See
+``mutation_kill_shared``'s module docstring for the unification rationale.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+import mutation_safety_gate
+from mutation_kill_shared import InsertionRefused, InsertOutcome
+
+# Matches a public test-method declaration (async Task or void), capturing the
+# method name. Framework-agnostic — no attribute or library name is assumed.
+_METHOD_RE = re.compile(
+    r"public\s+(?:async\s+)?(?:void|Task(?:<[^>]*>)?)\s+(\w+)\s*\("
+)
+
+# A file-scoped namespace declaration ends with a semicolon and has no
+# wrapping braces: ``namespace Foo.Bar;``
+_FILE_SCOPED_NS_RE = re.compile(r"^\s*namespace\s+[\w.]+\s*;", re.MULTILINE)
+
+
+def detect_duplicate_methods(test_text: str, new_text: str) -> list[str]:
+    """Return the method names in ``new_text`` that already exist in the file."""
+    existing = set(_METHOD_RE.findall(test_text))
+    incoming = _METHOD_RE.findall(new_text)
+    return [name for name in incoming if name in existing]
+
+
+def count_methods(new_text: str) -> int:
+    """Count public test-method declarations in ``new_text``."""
+    return len(_METHOD_RE.findall(new_text))
+
+
+# A deny-list of APIs a test method that merely kills mutants never
+# legitimately needs. Scoped to generated *test* text only — never to the
+# source-under-test — so it doesn't false-positive on production code that
+# does real I/O. This is a static-pattern gate, not a sandbox: a
+# sufficiently obfuscated payload (reflection-built names, string
+# concatenation) could still evade it. Guards against a prompt-injection
+# payload in the mutated source producing generated test code with
+# network/filesystem/process side effects that would still pass build+test
+# (which only check compilation and pass/fail, never behavior) and, in
+# --headless mode, get committed with zero human review. Category names are
+# a stable, test-pinned contract shared with mutation_kill_loop_python's
+# deny-list — renaming one is a breaking change for callers matching on
+# InsertOutcome.reason.
+_UNSAFE_PATTERNS: dict[str, re.Pattern[str]] = {
+    "network": re.compile(
+        r"\b(HttpClient|WebRequest|WebClient|TcpClient|UdpClient|SmtpClient|Socket|Dns|"
+        r"System\s*\.\s*Net\s*\.)\b"
+    ),
+    "process": re.compile(r"\b(Process|StartInfo|ProcessStartInfo)\b"),
+    "filesystem": re.compile(
+        r"\b(File\s*\.\s*(WriteAllText|WriteAllBytes|WriteAllLines|AppendAllText|"
+        r"AppendAllLines)(Async)?|File\s*\.\s*(Create|Delete|Move|Copy|Open|OpenWrite)|"
+        r"Directory\s*\.\s*(Delete|CreateDirectory|Move)|StreamWriter|FileStream|"
+        r"FileInfo|DirectoryInfo)\b"
+    ),
+    "environment": re.compile(
+        r"\b(Environment\s*\.\s*GetEnvironmentVariables?|ConfigurationManager\s*\.\s*AppSettings)\b"
+    ),
+    "reflection": re.compile(
+        r"\b(Assembly\s*\.\s*Load(From|File|WithPartialName)?|"
+        r"Activator\s*\.\s*CreateInstance(From)?|System\s*\.\s*Reflection\s*\.\s*Emit)\b"
+    ),
+    "interop": re.compile(r"\b(Marshal\s*\.|DllImport)\b|(?<![\w.])unsafe\b"),
+}
+
+
+def scan_for_unsafe_patterns(new_methods: str) -> list[str]:
+    """Return the category names of any unsafe pattern found in generated text.
+
+    A non-empty result refuses insertion outright — this deny-list is
+    deliberately conservative for *generated test* code specifically (a
+    legitimate mutant-killing test never needs network/filesystem/process/env
+    access), so a false positive refuses-and-logs rather than silently
+    inserting unreviewed code. Delegates to :mod:`mutation_safety_gate`,
+    shared with :mod:`mutation_kill_insert_python`, so a future bypass fix or
+    new category lands once for both languages.
+    """
+    return mutation_safety_gate.scan_for_unsafe_patterns(new_methods, _UNSAFE_PATTERNS)
+
+
+def _find_block_namespace_class_close(lines: Sequence[str]) -> int | None:
+    """Return the index of the class-closing brace, or None to refuse.
+
+    Walks from the end: finds the namespace-closing brace (a line whose
+    stripped form is ``}``), then the last line that is exactly four spaces
+    followed by ``}`` before it — the conventional block-namespace class
+    close. Any other indentation yields None (refuse).
+    """
+    ns_idx = None
+    for i in range(len(lines) - 1, -1, -1):
+        if lines[i].strip() == "}":
+            ns_idx = i
+            break
+    if ns_idx is None:
+        return None
+    for i in range(ns_idx - 1, -1, -1):
+        if lines[i].rstrip("\r\n") == "    }":
+            return i
+    return None
+
+
+def insert_before_class_close(test_file: Path, new_methods: str, text: str) -> None:
+    """Insert ``new_methods`` before the test class's closing brace.
+
+    Raises :class:`InsertionRefused` for a file-scoped namespace or any
+    non-4-space-indented class the heuristic can't safely locate. The file is
+    left untouched on refusal.
+
+    ``text`` is the current test-file content, already read by the caller
+    (:func:`apply_generated_methods`) — this function performs no read of its
+    own. A previous, optional ``test_text=`` shape let a caller pass in
+    content that bypassed reading the file's CURRENT state (including this
+    function's own refusal-guard check running against stale content rather
+    than what's actually on disk) — a real hazard even though no caller
+    exploited it. Removing the optional/None-triggered-fallback shape closes
+    that off: freshness is now entirely ``apply_generated_methods``'s
+    responsibility, which reads immediately before calling this (#1598/#1584
+    review, item 7).
+    """
+    if _FILE_SCOPED_NS_RE.search(text):
+        raise InsertionRefused(
+            f"refusing to insert into {test_file.name}: file-scoped namespace "
+            "detected — the class-close heuristic supports only block-namespace, "
+            "4-space-indented classes"
+        )
+
+    lines = text.splitlines(keepends=True)
+    cc_idx = _find_block_namespace_class_close(lines)
+    if cc_idx is None:
+        raise InsertionRefused(
+            f"refusing to insert into {test_file.name}: could not locate a "
+            "conventional 4-space class-closing brace (non-standard indentation?)"
+        )
+
+    block = (
+        ["\n"]
+        + [ln if ln.endswith("\n") else ln + "\n" for ln in new_methods.strip().splitlines()]
+        + ["\n"]
+    )
+    lines = lines[:cc_idx] + block + lines[cc_idx:]
+    test_file.write_text("".join(lines), encoding="utf-8")
+
+
+def apply_generated_methods(test_file: Path, new_methods: str) -> InsertOutcome:
+    """Insert generated methods, guarding duplicates and unsafe structure.
+
+    Returns an :class:`InsertOutcome`; the file is only ever written on the
+    ``inserted=True`` path. Empty generation, an unsafe pattern, duplicate
+    method names, and a refused insert all leave the file untouched.
+
+    Reads ``test_file`` exactly once here — immediately before the
+    duplicate-name check — and reuses that single fresh read for both the
+    check and the write (passed through to :func:`insert_before_class_close`,
+    which performs no read of its own). A prior shape let the caller (e.g.
+    ``_run_round``) thread in its OWN already-read ``test_text`` for the
+    duplicate check — but that text was read *before* the possibly
+    multi-minute ``generate()`` call, so the check ran against a stale
+    snapshot: a method name added to the file during generation (by another
+    process, or a second concurrent round) would go undetected as a
+    duplicate. Reading fresh here, after ``generate()`` has already
+    returned, closes that gap (#1598/#1584 review, item 7).
+    """
+    if not new_methods.strip():
+        return InsertOutcome(False, "no methods generated")
+
+    unsafe_categories = scan_for_unsafe_patterns(new_methods)
+    if unsafe_categories:
+        return InsertOutcome(False, f"refused — unsafe pattern(s): {unsafe_categories}")
+
+    text = test_file.read_text(encoding="utf-8")
+
+    dupes = detect_duplicate_methods(text, new_methods)
+    if dupes:
+        return InsertOutcome(False, f"duplicate method names: {dupes}")
+
+    try:
+        insert_before_class_close(test_file, new_methods, text)
+    except InsertionRefused as exc:
+        return InsertOutcome(False, str(exc))
+    return InsertOutcome(True, "inserted")

package/skills/mutation-testing/scripts/mutation_kill_insert_python.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""mutation_kill_insert_python.py — Python/pytest test-function insertion
+mechanics.
+
+Split out of ``mutation_kill_loop_python.py`` (#1583), mirroring the C#
+split ``mutation_kill_insert.py`` (#1562): detect-or-refuse insertion of
+generated pytest test functions at the end of a test file. Unlike C#'s
+"find the class-closing brace" problem, a flat pytest module has no
+enclosing structure to locate — the safe insertion point is simply
+end-of-file, PROVIDED the file already follows that flat, top-level
+``def test_*():`` convention. A file with no top-level ``def test_`` function
+at all (e.g. tests organized as ``class Test...:`` methods) doesn't match
+this convention, and the loop refuses rather than guess.
+
+``InsertOutcome``/``InsertionRefused`` are imported from
+``mutation_kill_shared`` (relocated from ``mutation_safety_gate`` in #1602;
+not defined here) — they're structurally identical to the C# sibling's, so
+both modules share one definition instead of two hand-maintained copies. See
+``mutation_kill_shared``'s module docstring for the unification rationale.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import mutation_safety_gate
+from mutation_kill_shared import InsertionRefused, InsertOutcome
+
+# A top-level (unindented) pytest test function declaration, capturing the name.
+_FUNC_RE = re.compile(r"^def\s+(test_\w+)\s*\(", re.MULTILINE)
+
+
+def detect_duplicate_functions(test_text: str, new_text: str) -> list[str]:
+    """Return the function names in ``new_text`` that already exist in the file."""
+    existing = set(_FUNC_RE.findall(test_text))
+    incoming = _FUNC_RE.findall(new_text)
+    return [name for name in incoming if name in existing]
+
+
+def count_tests(new_text: str) -> int:
+    """Count top-level ``def test_*():`` declarations in ``new_text``.
+
+    Mirrors ``mutation_kill_insert.count_methods`` — the loop uses this to
+    report how many new tests a round added in its commit message.
+    """
+    return len(_FUNC_RE.findall(new_text))
+
+
+def append_at_end_of_file(test_file: Path, new_tests: str, text: str) -> None:
+    """Append ``new_tests`` to the end of the file, with one blank line of
+    separation, and a trailing newline.
+
+    Raises :class:`InsertionRefused` when the file has no existing top-level
+    ``def test_*():`` — the flat-module convention this heuristic supports.
+    The file is left untouched on refusal.
+
+    ``text`` is the current test-file content, already read by the caller
+    (:func:`apply_generated_tests`) — this function performs no read of its
+    own, so freshness is entirely the caller's responsibility.
+    """
+    if not _FUNC_RE.search(text):
+        raise InsertionRefused(
+            f"refusing to insert into {test_file.name}: no top-level "
+            "`def test_*():` found — this heuristic supports only the flat "
+            "module convention (a class-based test file needs a different "
+            "insertion point, not appended at end-of-file)"
+        )
+
+    body = new_tests.strip()
+    separator = "" if text.endswith("\n\n") else ("\n" if text.endswith("\n") else "\n\n")
+    test_file.write_text(text + separator + body + "\n", encoding="utf-8")
+
+
+# A deny-list of APIs a test function that merely kills mutants never
+# legitimately needs. Scoped to generated *test* text only — never to the
+# source-under-test. Same rationale and same category names as
+# ``mutation_kill_insert``'s C# counterpart (kept consistent as a stable,
+# operator-facing and test-pinned contract) — this is the Python/pytest
+# equivalent, guarding this loop's own ``--headless`` unattended-commit path
+# against a prompt-injection payload in the mutated source producing
+# generated test code with network/filesystem/process side effects that
+# would still pass compile+test and get committed with zero human review.
+_UNSAFE_PATTERNS: dict[str, re.Pattern[str]] = {
+    "network": re.compile(
+        r"\b(requests\s*\.|urllib\s*\.\s*request|urllib3\s*\.|httpx\s*\.|socket\s*\.|http\s*\.\s*client)\b"
+    ),
+    "process": re.compile(
+        r"\b(subprocess\s*\.|os\s*\.\s*system|os\s*\.\s*popen|os\s*\.\s*exec\w*|"
+        r"os\s*\.\s*(spawn\w*|posix_spawn|fork|forkpty)|Popen)\b"
+    ),
+    "filesystem": re.compile(
+        r"\b(shutil\s*\.\s*rmtree|os\s*\.\s*(remove|unlink))\b"
+        r"|\.\s*(write_text|write_bytes|unlink)\s*\("
+        r"|open\s*\([^)]*[\"'][waxA]"
+    ),
+    "environment": re.compile(r"\b(os\s*\.\s*environ|os\s*\.\s*getenv)\b"),
+    "reflection": re.compile(r"\b(importlib\s*\.\s*import_module|__import__)\b"),
+    "interop": re.compile(r"\b(eval|exec)\s*\(|\bctypes\s*\.|\bpickle\s*\.\s*loads\s*\("),
+}
+
+
+def scan_for_unsafe_patterns(new_tests: str) -> list[str]:
+    """Return the category names of any unsafe pattern found in generated text.
+
+    A non-empty result refuses insertion outright — this deny-list is
+    deliberately conservative for *generated test* code specifically (a
+    legitimate mutant-killing test never needs network/filesystem/process/env
+    access), so a false positive refuses-and-logs rather than silently
+    inserting unreviewed code. Delegates to :mod:`mutation_safety_gate`,
+    shared with :mod:`mutation_kill_insert`, so a future bypass fix or new
+    category lands once for both languages.
+    """
+    return mutation_safety_gate.scan_for_unsafe_patterns(new_tests, _UNSAFE_PATTERNS)
+
+
+def apply_generated_tests(test_file: Path, new_tests: str) -> InsertOutcome:
+    """Insert generated tests, guarding duplicates and unsafe structure.
+
+    Returns an :class:`InsertOutcome`; the file is only ever written on the
+    ``inserted=True`` path. Empty generation, an unsafe pattern, duplicate
+    function names, and a refused insert all leave the file untouched.
+
+    Reads ``test_file`` exactly once here — immediately before the
+    duplicate-name check — and reuses that single fresh read for both the
+    check and the write (passed through to :func:`append_at_end_of_file`,
+    which performs no read of its own). Reading fresh here, after the
+    caller's (possibly multi-minute) generation call has already returned,
+    means a test function added to the file externally in the meantime is
+    still caught as a duplicate rather than silently double-inserted
+    (#1598/#1584 review, item 7).
+    """
+    if not new_tests.strip():
+        return InsertOutcome(False, "no tests generated")
+
+    unsafe_categories = scan_for_unsafe_patterns(new_tests)
+    if unsafe_categories:
+        return InsertOutcome(False, f"refused — unsafe pattern(s): {unsafe_categories}")
+
+    text = test_file.read_text(encoding="utf-8")
+
+    dupes = detect_duplicate_functions(text, new_tests)
+    if dupes:
+        return InsertOutcome(False, f"duplicate function names: {dupes}")
+
+    try:
+        append_at_end_of_file(test_file, new_tests, text)
+    except InsertionRefused as exc:
+        return InsertOutcome(False, str(exc))
+    return InsertOutcome(True, "inserted")