pi-dev-team 0.2.0

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

@@ -0,0 +1,681 @@
+#!/usr/bin/env python3
+"""csharp_stryker_net_wrapper.py — reference wrapper for Stryker.NET.
+
+Cross-platform authoritative: macOS, Linux, Windows Git Bash, and native
+Windows all execute the same code path through Python 3's ``subprocess``,
+``signal``, and ``pathlib`` — no shell-tooling divergence.
+
+Copy this file AND ``csharp_stryker_net_status_loop.py`` together into your
+repo's ``scripts/`` directory, and run in place of a bare ``dotnet stryker``
+invocation (override defaults via CLI flags or the corresponding env vars).
+
+Contract preserved from the bash version:
+
+- ``DOTNET_ROOT`` probe across macOS Homebrew (Apple Silicon + Intel),
+  Debian/Ubuntu, Fedora/RHEL, user-scope, and Windows install paths
+- Pre-building ``${SLN}`` and ``${SHIM_PROJECT}`` BEFORE hiding ``.sln``
+  (Stryker's own build step can't rebuild whole-solution after the hide)
+- Hiding ``.sln`` during the run + restoring it on any exit path — normal
+  exit, non-zero exit, SIGINT (Ctrl-C), SIGTERM, KeyboardInterrupt
+- Refusing (exit 2) when a stale ``.sln.stryker-hidden`` coexists with a
+  fresh ``.sln`` (idempotent — never silently clobbers either)
+- Running Stryker as a subprocess so we can kill it on any signal — no
+  orphaned Stryker processes in CI or backgrounded contexts
+- Direct log redirect (never a bare ``| tee`` — see #550)
+
+Refs: #554, #557, #558, #559, #564, #567 (Windows verification), #572
+(bash → Python migration epic).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+from collections.abc import Callable, Sequence
+from pathlib import Path, PureWindowsPath
+
+# =============================================================================
+# Exit codes — same as the bash version, byte-compatible. EXIT_RESTORE_SLN_FAILED
+# is new (#1955) — no bash-version precedent, since restore_sln() previously
+# reported no outcome for main() to surface.
+# =============================================================================
+EXIT_OK = 0
+EXIT_STALE_HIDDEN_SLN = 2
+EXIT_NO_DOTNET_SDK = 3
+EXIT_RESTORE_SLN_FAILED = 4
+
+
+# =============================================================================
+# DOTNET_ROOT probe — the 7-position chain documented in the spec.
+# =============================================================================
+def default_probe_candidates() -> list[str]:
+    """Return the ordered default probe list. Named function so callers (and
+    tests) can point at a single authoritative source instead of copying the
+    literal path list.
+    """
+    home = str(Path.home())
+    return [
+        "/opt/homebrew/opt/dotnet/libexec",  # 1: macOS Apple Silicon Homebrew
+        "/usr/local/opt/dotnet/libexec",  # 2: macOS Intel Homebrew
+        "/usr/share/dotnet",  # 3: Debian/Ubuntu package
+        "/usr/lib/dotnet",  # 4: Fedora/RHEL package
+        f"{home}/.dotnet",  # 5: user-scope (dotnet-install.sh)
+        "/c/Program Files/dotnet",  # 6: Windows Git Bash Program Files
+        "/c/program files/dotnet",  # 7: Windows lowercase drive mount
+        # Native-Windows path (drive letter, no MSYS mount). Sensible extension
+        # of the bash contract on the native-Windows target.
+        r"C:\Program Files\dotnet",
+    ]
+
+
+def probe_dotnet_root(candidates: Sequence[str]) -> str | None:
+    """Return the first candidate whose SDK layout is present, or None.
+
+    A candidate hits when any of these are true:
+      - ``<c>/dotnet`` is an executable file
+      - ``<c>/dotnet.exe`` is an executable file
+      - ``<c>/shared`` is a directory
+
+    Empty candidate strings are skipped so callers can concatenate lists
+    without worrying about stray separators.
+    """
+    for candidate in candidates:
+        if not candidate:
+            continue
+        c = Path(candidate)
+        dotnet_bin = c / "dotnet"
+        dotnet_exe = c / "dotnet.exe"
+        shared_dir = c / "shared"
+        if (
+            (dotnet_bin.is_file() and os.access(dotnet_bin, os.X_OK))
+            or (dotnet_exe.is_file() and os.access(dotnet_exe, os.X_OK))
+            or shared_dir.is_dir()
+        ):
+            return str(c)
+    return None
+
+
+def resolve_dotnet_root(
+    preset: str | None,
+    candidates: Sequence[str],
+) -> tuple[str | None, str | None]:
+    """Return ``(dotnet_root, error_message)``.
+
+    - Preset value wins if truthy — matches the bash ``${DOTNET_ROOT:-}`` guard.
+    - Probe the candidate list next.
+    - Fall back to the directory containing ``dotnet`` on PATH.
+    - Return (None, error_message) when nothing resolves.
+    """
+    if preset:
+        return preset, None
+    hit = probe_dotnet_root(candidates)
+    if hit is not None:
+        return hit, None
+    on_path = shutil.which("dotnet")
+    if on_path:
+        return str(Path(on_path).resolve().parent), None
+    msg = _no_sdk_message(candidates)
+    return None, msg
+
+
+def _no_sdk_message(candidates: Sequence[str]) -> str:
+    lines = [
+        "error: no .NET SDK found; DOTNET_ROOT is unset and no candidate resolved",
+        "  probed:",
+    ]
+    for c in candidates:
+        if c:
+            lines.append(f"    {c}")
+    lines.append("  also tried: dirname of `dotnet` on PATH — dotnet not on PATH")
+    lines.append(
+        "set DOTNET_ROOT explicitly, or install .NET: https://dotnet.microsoft.com/download"
+    )
+    return "\n".join(lines) + "\n"
+
+
+# =============================================================================
+# Stale-hidden-.sln refusal
+# =============================================================================
+def check_stale_hidden_sln(sln: Path, sln_hidden: Path) -> str | None:
+    """Return an error message if a stale hidden .sln coexists with a fresh
+    one; otherwise None. Refusal is deterministic — the wrapper produces no
+    side effects when it refuses.
+    """
+    if sln_hidden.exists() and sln.exists():
+        return (
+            f"error: stale {sln_hidden} present alongside fresh {sln}\n"
+            f"resolve manually before rerunning "
+            f"(delete the stale hidden file if the fresh {sln} is correct)\n"
+        )
+    return None
+
+
+# =============================================================================
+# .sln hide/restore — used inside a try/finally so restore runs on any exit.
+# =============================================================================
+def hide_sln(sln: Path, sln_hidden: Path) -> None:
+    """Move .sln to .sln.stryker-hidden. Idempotent — a no-op if already hidden."""
+    if sln.exists() and not sln_hidden.exists():
+        sln.rename(sln_hidden)
+
+
+def restore_sln(sln: Path, sln_hidden: Path) -> bool:
+    """Restore .sln from .sln.stryker-hidden. Guarded so we never clobber a
+    fresh .sln written mid-run (rare but real — some IDEs rewrite the file).
+
+    Returns True only when the hidden file existed and was renamed back to
+    ``sln`` successfully. Returns False (#1955) — never raises — in every
+    case where restoration didn't happen: the guard's precondition wasn't
+    met (``sln_hidden`` doesn't exist at all — the hide never happened, or
+    something else already removed it — or a fresh ``sln`` already exists
+    alongside the hidden one, the same stale-coexistence condition
+    ``check_stale_hidden_sln`` refuses at the START of a run, observed here
+    at the END instead), or ``.rename()`` itself raises (``OSError`` /
+    ``PermissionError``, e.g. a locked file on Windows).
+
+    Mirrors ``mutation_kill_shared.git_revert``'s bool-return contract so
+    callers can react uniformly. This module stays dependency-free by
+    design (the module docstring: "copy this file... into your repo's
+    scripts/ directory") — a caller that needs a hard failure signal rather
+    than a bool it must check should raise its own exception on a False
+    return; see ``mutation_kill_loop.py``'s ``run_scoped_stryker``, which
+    raises ``mutation_kill_shared.RevertFailed``, mirroring #1939's
+    ``git_revert`` handling.
+    """
+    if not sln_hidden.exists() or sln.exists():
+        return False
+    try:
+        sln_hidden.rename(sln)
+    except OSError:
+        return False
+    return True
+
+
+# =============================================================================
+# Main
+# =============================================================================
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    """Parse header-var overrides and pass-through Stryker args.
+
+    Everything after ``--`` (or unknown flags) is forwarded verbatim to
+    ``dotnet stryker``. Header vars can be set via env or CLI flag; CLI wins.
+    """
+    p = argparse.ArgumentParser(
+        prog="csharp_stryker_net_wrapper.py",
+        description="Reference wrapper for Stryker.NET — cross-platform via Python.",
+        add_help=True,
+    )
+    p.add_argument(
+        "--sln",
+        default=os.environ.get("SLN", "Foo.sln"),
+        help="Solution file to hide during run (default: %(default)s)",
+    )
+    p.add_argument(
+        "--shim-project",
+        default=os.environ.get("SHIM_PROJECT", ""),
+        help="Optional shim test project to pre-build. Empty = none.",
+    )
+    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(
+        "--logfile",
+        default=os.environ.get("LOGFILE", "StrykerOutput/wrapper.log"),
+        help="Log redirect target (default: %(default)s)",
+    )
+    p.add_argument(
+        "--stryker-concurrency",
+        default=os.environ.get("STRYKER_MUTANT_CONCURRENCY"),
+        help=(
+            "Stryker's own mutant-testing-process concurrency (its -c/"
+            "--concurrency flag). Deliberately NOT -c/--concurrency here — "
+            "see csharp-stryker-net.md. Env equivalent: "
+            "STRYKER_MUTANT_CONCURRENCY. Default: max(1, cpu_count - 2)."
+        ),
+    )
+    return p.parse_known_args(list(argv))[0], p.parse_known_args(list(argv))[1]
+
+
+# =============================================================================
+# Concurrency default — Stryker's own `-c`/`--concurrency` mutant-testing-
+# process count. Defaults to cores-2 instead of Stryker's flat default of 5.
+# =============================================================================
+def default_concurrency(cpu_count: int | None) -> int:
+    """Return ``max(1, (cpu_count or 2) - 2)``.
+
+    ``cpu_count`` is normally ``os.cpu_count()``, which returns ``None`` when
+    the machine's core count can't be determined — falls back to 2 so the
+    computed default is still 1 (never 0 or negative).
+    """
+    return max(1, (cpu_count or 2) - 2)
+
+
+def _pass_through_concurrency_flag(stryker_args: Sequence[str]) -> str | None:
+    """Return the pass-through concurrency flag (``-c`` or ``--concurrency``)
+    present in ``stryker_args``, or ``None``. Consolidates the "does the
+    caller already specify concurrency" check used by both the explicit-
+    value and computed-default injection paths.
+    """
+    for flag in ("-c", "--concurrency"):
+        if flag in stryker_args:
+            return flag
+    return None
+
+
+def build_stryker_argv(stryker_bin: str, stryker_args: Sequence[str]) -> list[str]:
+    r"""Return the full argv for launching Stryker.NET.
+
+    ``dotnet stryker ...`` is the invocation shape for a **local** tool-
+    manifest install — the skill's preferred path (see csharp-stryker-net.md
+    "Prefer a local install"). A local tool's own command name
+    (``dotnet-stryker``) is never placed on ``PATH``; it is only reachable
+    through dotnet's own verb-resolution convention (``dotnet <verb>`` finds
+    a local ``dotnet-<verb>`` tool). A **global** install, by contrast, does
+    put a bare ``dotnet-stryker`` executable on ``PATH``, invoked directly
+    with no subcommand.
+
+    Auto-detected from ``stryker_bin`` alone — no separate flag: when its
+    filename stem (case-insensitive, extension and directory stripped) is
+    ``"dotnet"``, insert the ``stryker`` verb. Matching on the stem rather
+    than the raw string (#2145) means an absolute path (``/usr/bin/dotnet``)
+    or a Windows-style name (``dotnet.exe``) is recognized identically to
+    the bare ``"dotnet"`` — a functionally-equivalent value that previously
+    fell through to the bare-executable branch below with no ``stryker``
+    verb inserted, silently reproducing the failure this module exists to
+    fix. Checked with both ``Path`` (the host-native flavor — ``WindowsPath``
+    on Windows, ``PosixPath`` elsewhere) and ``PureWindowsPath`` explicitly,
+    so a backslash-separated Windows path (e.g. ``C:\Program
+    Files\dotnet\dotnet.exe``) is recognized even when this module runs
+    under a POSIX-flavored Python (Cygwin/MSYS2), where plain ``Path`` alone
+    would treat the whole string as one opaque filename component and never
+    find the ``"dotnet"`` stem. Any other value (e.g. an explicit
+    ``dotnet-stryker`` override for a global install) is used as the bare
+    executable, unchanged.
+    """
+    if (
+        Path(stryker_bin).stem.lower() == "dotnet"
+        or PureWindowsPath(stryker_bin).stem.lower() == "dotnet"
+    ):
+        return [stryker_bin, "stryker", *stryker_args]
+    return [stryker_bin, *stryker_args]
+
+
+def build_project(project: str, cwd: Path | None = None) -> int:
+    """Run ``dotnet build <project> -c Debug --nologo`` in the given cwd.
+    Returns the subprocess exit code.
+    """
+    return subprocess.call(
+        ["dotnet", "build", project, "-c", "Debug", "--nologo"],
+        cwd=cwd,
+    )
+
+
+def run_stryker(
+    stryker_bin: str,
+    stryker_args: Sequence[str],
+    logfile: Path,
+    line_callback: Callable[[str], bool] | None = None,
+    cwd: Path | None = None,
+) -> int:
+    """Run Stryker with stdout+stderr captured to logfile. Returns exit code.
+
+    Signal handling: Python's default SIGINT delivery raises KeyboardInterrupt
+    in the parent, which our main() catches to run the finally block. The
+    Popen child inherits the process group by default — a tty Ctrl-C reaches
+    both. On explicit `signal` from a parent process manager, main()'s signal
+    handlers intercept and terminate the child before re-raising.
+
+    Thread-safety: csharp_stryker_net_slice_runner.py's slice-level
+    parallelism (#561) calls this function concurrently from multiple
+    ThreadPoolExecutor worker threads — one live Stryker subprocess per
+    in-flight slice at once. Every live Popen is tracked in the shared,
+    lock-guarded ``_RUNNING_STRYKER_PROCS`` set (not a single-slot global) so
+    the signal handler can terminate all of them, not just whichever slice
+    last registered (#732).
+
+    Line-callback (additive, backward-compatible — #1136 Slice 5): when
+    ``line_callback`` is ``None`` the behavior is *exactly* as before —
+    Stryker's stdout+stderr are redirected straight into ``logfile`` and we
+    block on ``proc.wait()``. When a callback is supplied, output is instead
+    streamed line by line: every line is TEE'd to ``logfile`` (so shard
+    post-mortem logs stay intact) *and* handed to the callback. A truthy
+    return — or a raised exception — requests an abort, and we ``terminate()``
+    the Stryker process. That is the same kill the SIGINT/SIGTERM handler runs
+    via ``_terminate_all_tracked_processes``; the proc stays tracked in
+    ``_RUNNING_STRYKER_PROCS`` the whole time, so a concurrent signal and a
+    callback-abort are idempotent (``terminate()`` is guarded by ``poll()``,
+    a no-op on an already-dead process). ``cwd`` runs Stryker from another
+    directory (the shard pipeline runs each shard in its own git worktree).
+    """
+    logfile.parent.mkdir(parents=True, exist_ok=True)
+    popen_cwd = str(cwd) if cwd is not None else None
+    if line_callback is None:
+        with logfile.open("wb") as log:
+            proc = subprocess.Popen(
+                build_stryker_argv(stryker_bin, stryker_args),
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                cwd=popen_cwd,
+            )
+            # Track for signal handlers.
+            with _RUNNING_STRYKER_LOCK:
+                _RUNNING_STRYKER_PROCS.add(proc)
+            try:
+                return proc.wait()
+            finally:
+                with _RUNNING_STRYKER_LOCK:
+                    _RUNNING_STRYKER_PROCS.discard(proc)
+    return _run_stryker_streaming(
+        stryker_bin, stryker_args, logfile, line_callback, popen_cwd
+    )
+
+
+# Bounds for the abort/raise reap. Stryker.NET spawns grandchild test-hosts
+# that inherit the stdout PIPE; on a timeout-abort they can hold the pipe open,
+# so we must never depend on stdout reaching EOF for either the drain or the
+# wait. These bounds only bite when a grandchild is genuinely stuck — a healthy
+# child exits in milliseconds. Portable (no os.killpg — absent on Windows).
+_ABORT_DRAIN_TIMEOUT_S = 10.0
+_ABORT_WAIT_TIMEOUT_S = 30.0
+
+
+def _terminate(proc: subprocess.Popen) -> None:
+    """Signal the child to stop if it is still running (poll-guarded no-op
+    otherwise — idempotent with the signal handler's terminate())."""
+    if proc.poll() is None:
+        proc.terminate()
+
+
+def _close_stdout(proc: subprocess.Popen) -> None:
+    """Close the child's stdout to unblock any reader blocked on an EOF a
+    surviving grandchild would otherwise withhold. Best-effort — fakes without
+    a real closable stream, or an already-closed pipe, are tolerated."""
+    try:
+        if proc.stdout is not None:
+            proc.stdout.close()
+    except (AttributeError, OSError, ValueError):
+        pass
+
+
+def _bounded_reap(proc: subprocess.Popen) -> int:
+    """Reap ``proc`` with a bounded, portable escalation:
+    ``wait(timeout)`` → ``kill()`` → ``wait(timeout)``. Guarantees the child is
+    reaped even when a grandchild holds the stdout pipe, without ever blocking
+    indefinitely. Returns the child's exit code (or -1 if it never resolved)."""
+    try:
+        return proc.wait(timeout=_ABORT_WAIT_TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        pass
+    if proc.poll() is None:
+        proc.kill()
+    try:
+        return proc.wait(timeout=_ABORT_WAIT_TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        rc = proc.poll()
+        return rc if rc is not None else -1
+
+
+def _drain_bounded(proc: subprocess.Popen, log) -> None:
+    """Tee any output Stryker already buffered into ``log`` after an abort, so
+    the post-mortem log stays complete — but bounded: the drain runs on a
+    daemon thread joined with a timeout, and the caller closes stdout after, so
+    a grandchild holding the pipe cannot hang the drain."""
+
+    def _pump() -> None:
+        try:
+            for raw in proc.stdout:  # type: ignore[union-attr]
+                log.write(raw)
+        except (AttributeError, OSError, ValueError):
+            pass
+
+    drain = threading.Thread(target=_pump, daemon=True)
+    drain.start()
+    drain.join(_ABORT_DRAIN_TIMEOUT_S)
+    log.flush()
+
+
+def _run_stryker_streaming(
+    stryker_bin: str,
+    stryker_args: Sequence[str],
+    logfile: Path,
+    line_callback: Callable[[str], bool],
+    popen_cwd: str | None,
+) -> int:
+    """Streaming variant of :func:`run_stryker` used when a line-callback is
+    supplied. Tees every line to ``logfile`` while feeding it to the callback;
+    aborts the run (terminating AND reaping the child) when the callback
+    returns truthy or raises. Split out so the callback-less path above stays
+    byte-for-byte the original behavior.
+
+    Abort/raise are bounded (#1136 review): after ``terminate()`` we drain the
+    buffered tail on a joined daemon thread, close stdout to unblock any reader,
+    and reap with a ``wait(timeout)`` → ``kill()`` → ``wait(timeout)``
+    escalation. A grandchild test-host that inherits and holds the stdout pipe
+    can therefore never hang the drain or the wait, and the child is always
+    reaped before we return or re-raise.
+    """
+    with logfile.open("wb") as log:
+        proc = subprocess.Popen(
+            build_stryker_argv(stryker_bin, stryker_args),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=popen_cwd,
+        )
+        with _RUNNING_STRYKER_LOCK:
+            _RUNNING_STRYKER_PROCS.add(proc)
+        try:
+            aborted = False
+            assert proc.stdout is not None
+            try:
+                for raw in proc.stdout:
+                    log.write(raw)  # tee: the full log is always preserved
+                    log.flush()
+                    if line_callback(raw.decode("utf-8", errors="replace")):
+                        aborted = True
+                        break
+            except BaseException:
+                # Callback raised — terminate, close, and reap (bounded) before
+                # propagating so we never orphan the Stryker process or hang on
+                # a grandchild holding the pipe (same kill path as the signal
+                # handler, plus a guaranteed reap).
+                _terminate(proc)
+                _close_stdout(proc)
+                _bounded_reap(proc)
+                raise
+            if aborted:
+                _terminate(proc)
+                # Capture the buffered tail (tee), then close stdout so the
+                # bounded reap can never wait on an EOF a grandchild withholds.
+                _drain_bounded(proc, log)
+                _close_stdout(proc)
+                return _bounded_reap(proc)
+            return proc.wait()
+        finally:
+            with _RUNNING_STRYKER_LOCK:
+                _RUNNING_STRYKER_PROCS.discard(proc)
+
+
+# Guards _RUNNING_STRYKER_PROCS, which holds every currently-running Stryker
+# Popen across all worker threads (one per in-flight slice under #561's
+# slice-level parallelism). A plain set is not thread-safe on its own; the
+# lock makes add/discard/snapshot atomic with respect to the signal handler.
+_RUNNING_STRYKER_LOCK = threading.Lock()
+_RUNNING_STRYKER_PROCS: set[subprocess.Popen] = set()
+
+
+def _terminate_all_tracked_processes() -> None:
+    """Terminate every Stryker subprocess currently tracked in
+    ``_RUNNING_STRYKER_PROCS`` — there may be several concurrently, one per
+    in-flight slice under #561's slice-level parallelism. Split out from
+    ``_install_signal_handlers`` so it's directly unit-testable without
+    needing to actually deliver an OS signal (real signal delivery is
+    inherently platform-fragile — see ``TestSignalHandlingPOSIX``).
+    """
+    with _RUNNING_STRYKER_LOCK:
+        procs = list(_RUNNING_STRYKER_PROCS)
+    for proc in procs:
+        if proc.poll() is None:
+            try:
+                proc.terminate()
+            except OSError:
+                # Best-effort cleanup during shutdown — a process that exited
+                # between poll() and terminate() must not block terminating
+                # the rest of the tracked processes.
+                pass
+
+
+def _install_signal_handlers() -> list[tuple[int, object]]:
+    """Install SIGINT + SIGTERM handlers that terminate every currently-
+    running Stryker subprocess (there may be several concurrently, one per
+    in-flight slice under #561's slice-level parallelism) before re-raising
+    KeyboardInterrupt / exiting. On Windows, SIGTERM is delivered as
+    SIGBREAK — signal.signal accepts SIGTERM but doesn't actually receive it;
+    we register SIGBREAK too where available.
+
+    Returns a list of (signum, previous_handler) tuples so ``main()`` can
+    restore the process's prior handlers on exit. This matters when
+    ``main()`` is called from another Python program (e.g. pytest) that
+    itself installs signal handlers — leaving ours in place across the
+    caller's remaining lifetime causes KeyboardInterrupt storms on
+    unrelated later code.
+    """
+
+    def _handler(signum: int, _frame) -> None:
+        _terminate_all_tracked_processes()
+        # Re-raise as KeyboardInterrupt for main()'s finally to fire cleanly.
+        raise KeyboardInterrupt(f"signal {signum}")
+
+    previous: list[tuple[int, object]] = []
+    signals_to_install = [signal.SIGINT]
+    if hasattr(signal, "SIGTERM"):
+        signals_to_install.append(signal.SIGTERM)
+    if hasattr(signal, "SIGBREAK"):
+        # Windows console Ctrl-Break.
+        signals_to_install.append(signal.SIGBREAK)
+    for sig in signals_to_install:
+        previous.append((sig, signal.getsignal(sig)))
+        signal.signal(sig, _handler)
+    return previous
+
+
+def _restore_signal_handlers(previous: list[tuple[int, object]]) -> None:
+    """Restore the signal handlers captured by _install_signal_handlers."""
+    for sig, handler in previous:
+        try:
+            signal.signal(sig, handler)
+        except (ValueError, OSError, TypeError):
+            # Non-main-thread invocation or platform quirk — leave whatever
+            # is now in place; better than crashing at cleanup time.
+            pass
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main entry point. Returns the process exit code."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args, stryker_args = parse_args(argv)
+
+    # ---- DOTNET_ROOT resolution ---------------------------------------------
+    dotnet_root, err = resolve_dotnet_root(
+        preset=os.environ.get("DOTNET_ROOT"),
+        candidates=default_probe_candidates(),
+    )
+    if err is not None:
+        sys.stderr.write(err)
+        return EXIT_NO_DOTNET_SDK
+    assert dotnet_root is not None
+    os.environ["DOTNET_ROOT"] = dotnet_root
+
+    # ---- Stale-hidden refusal (BEFORE any state mutation) -------------------
+    sln = Path(args.sln)
+    sln_hidden = Path(f"{args.sln}.stryker-hidden")
+    stale_err = check_stale_hidden_sln(sln, sln_hidden)
+    if stale_err is not None:
+        sys.stderr.write(stale_err)
+        return EXIT_STALE_HIDDEN_SLN
+
+    # ---- Install signal handlers now that we're about to spawn children ----
+    # Save previous handlers so we restore them on exit. Critical when main()
+    # is called from another Python program (pytest) — leaving our handlers
+    # in place across the caller's lifetime causes KeyboardInterrupt storms
+    # on unrelated later code.
+    previous_signal_handlers = _install_signal_handlers()
+
+    exit_code: int = EXIT_OK
+    try:
+        # Pre-build BEFORE hiding — build against a hidden .sln fails.
+        rc = build_project(args.sln)
+        if rc != 0:
+            return rc
+        if args.shim_project:
+            rc = build_project(args.shim_project)
+            if rc != 0:
+                return rc
+
+        # Hide .sln during the run.
+        hide_sln(sln, sln_hidden)
+
+        # Inject Stryker's own mutant-testing concurrency (`-c`) unless the
+        # caller's pass-through args already specify one — pass-through
+        # always wins over both an explicit --stryker-concurrency/env value
+        # and the computed default; never silently override an explicit
+        # caller-supplied value.
+        pass_through_flag = _pass_through_concurrency_flag(stryker_args)
+        if pass_through_flag is None:
+            if args.stryker_concurrency is not None:
+                value = str(args.stryker_concurrency)
+            else:
+                value = str(default_concurrency(os.cpu_count()))
+            stryker_args = [*stryker_args, "-c", value]
+        elif args.stryker_concurrency is not None:
+            idx = stryker_args.index(pass_through_flag)
+            pass_through_value = (
+                stryker_args[idx + 1] if idx + 1 < len(stryker_args) else ""
+            )
+            sys.stderr.write(
+                f'note: pass-through "{pass_through_flag} '
+                f'{pass_through_value}" overrode explicit '
+                f'"--stryker-concurrency {args.stryker_concurrency}"\n'
+            )
+
+        # Run Stryker; capture its exit code.
+        exit_code = run_stryker(
+            stryker_bin=args.stryker_bin,
+            stryker_args=stryker_args,
+            logfile=Path(args.logfile),
+        )
+    except KeyboardInterrupt:
+        # SIGINT / SIGTERM propagated through the signal handlers. The Popen
+        # child was terminate()'d already; we now fall through to the finally
+        # block for .sln restoration.
+        exit_code = 130  # conventional SIGINT exit code
+    finally:
+        # ALWAYS restore .sln — no matter which exit path.
+        restored = restore_sln(sln, sln_hidden)
+        if not restored:
+            sys.stderr.write(
+                f"error: failed to restore {sln} from {sln_hidden} — the "
+                "solution file is left hidden/renamed, which will break the "
+                "next build (#1955)\n"
+            )
+            # Don't clobber a real Stryker failure — a restore failure on
+            # top of an already-non-zero exit adds no new information the
+            # operator needs; surface it only when Stryker itself looked
+            # clean.
+            if exit_code == EXIT_OK:
+                exit_code = EXIT_RESTORE_SLN_FAILED
+        # Restore previous signal handlers — critical for library-style use.
+        _restore_signal_handlers(previous_signal_handlers)
+
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())