steppy-dev 0.3.0__py3-none-any.whl

steppy/_parallel/fingerprint.py

@@ -0,0 +1,141 @@
+"""Group failures by root cause instead of listing them one by one.
+
+With hundreds of scenarios, one broken selector shows up as forty stack traces.
+Reading them means scrolling past thirty-nine copies of the same information to
+discover there were only three real problems. This module collapses that: it
+normalizes each failure tail into a shape that ignores run-specific noise
+(addresses, timings, ids, paths) and hashes it, so identical causes land in one
+bucket.
+
+The normalizer is deliberately aggressive. A false merge costs the reader one
+extra glance at the grouped list; a false split puts them back where they
+started. Everything here is pure — no I/O, no Playwright, no pytest — so the
+substitutions can be unit-tested directly against real tails.
+
+Lazy-imported from the renderer, like the rest of ``_parallel``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+
+
+# Order matters: the more specific patterns run before the general ones, so a
+# `0x7f…` address isn't first mangled into `<num>x<num>`.
+_SCRUBBERS: tuple[tuple[re.Pattern, str], ...] = (
+    # Windows + POSIX absolute paths → keep only the basename.
+    (re.compile(r"(?:[A-Za-z]:)?[\\/](?:[\w.\-]+[\\/])+([\w.\-]+\.py)"), r"<path>/\1"),
+    # ISO-ish timestamps and clock times.
+    (re.compile(r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?"), "<ts>"),
+    (re.compile(r"\b\d{2}:\d{2}:\d{2}(?:[.,]\d+)?\b"), "<time>"),
+    # UUIDs, then long hex blobs (object addresses, sha digests, container ids).
+    (re.compile(r"\b[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}\b"), "<uuid>"),
+    (re.compile(r"\b0x[0-9a-fA-F]+\b"), "<addr>"),
+    (re.compile(r"\b[0-9a-fA-F]{12,}\b"), "<hex>"),
+    # Durations pytest/playwright print in messages ("Timeout 30000ms exceeded").
+    (re.compile(r"\b\d+(?:\.\d+)?\s*(?:ms|s|sec|seconds|m)\b"), "<dur>"),
+    # Source line references: `foo.py:123` and pytest's `E   File "...", line 12`.
+    (re.compile(r"(\.py)[:\"']?,?\s*line\s+\d+", re.IGNORECASE), r"\1:<line>"),
+    (re.compile(r"(\.py):\d+"), r"\1:<line>"),
+    # Ports and any remaining bare integers. Last, so the specific rules win.
+    (re.compile(r":\d{2,5}\b"), ":<port>"),
+    (re.compile(r"\b\d+\b"), "<n>"),
+)
+
+_WS = re.compile(r"[ \t]+")
+
+
+def normalize_tail(tail: str) -> str:
+    """Reduce a failure tail to its run-independent shape.
+
+    Strips leading pytest gutter markers (``E   ``), scrubs run-specific values,
+    and collapses whitespace. Two failures with the same cause but different
+    timings / element ids / worker paths normalize to the same string.
+    """
+    if not tail:
+        return ""
+    lines: list[str] = []
+    for raw in tail.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        # pytest prefixes assertion detail with `E   `; drop it so the same
+        # error reported in different phases still matches.
+        if line.startswith("E ") or line == "E":
+            line = line[1:].strip()
+        for pattern, repl in _SCRUBBERS:
+            line = pattern.sub(repl, line)
+        lines.append(_WS.sub(" ", line))
+    return "\n".join(lines)
+
+
+def fingerprint(tail: str) -> str:
+    """Stable short digest of a normalized tail. Empty tail ⇒ ``"unknown"``."""
+    normalized = normalize_tail(tail)
+    if not normalized:
+        return "unknown"
+    return hashlib.sha1(normalized.encode("utf-8")).hexdigest()[:8]
+
+
+def headline(tail: str, max_len: int = 100) -> str:
+    """The single most informative line of a failure tail, for the group label.
+
+    Prefers the last line that names an exception (that is where pytest puts the
+    actual error), else the last non-empty line — the bottom of a traceback is
+    almost always more useful than the top.
+    """
+    lines = [ln.strip().lstrip("E").strip() for ln in tail.splitlines() if ln.strip()]
+    if not lines:
+        return "(no failure detail captured)"
+    chosen = next(
+        (ln for ln in reversed(lines) if re.search(r"\b(?:Error|Exception|assert|Timeout|Failed)\b", ln)),
+        lines[-1],
+    )
+    return chosen if len(chosen) <= max_len else chosen[: max_len - 1] + "…"
+
+
+@dataclass
+class FailureGroup:
+    """One distinct cause and every scenario that hit it."""
+
+    fingerprint: str
+    headline: str
+    # (slug, nodeid, tail) — the first entry is the exemplar shown in full.
+    occurrences: list[tuple[str, str, str]] = field(default_factory=list)
+
+    @property
+    def count(self) -> int:
+        return len(self.occurrences)
+
+    @property
+    def slugs(self) -> list[str]:
+        seen, out = set(), []
+        for slug, _nodeid, _tail in self.occurrences:
+            if slug not in seen:
+                seen.add(slug)
+                out.append(slug)
+        return out
+
+
+def group_failures(rows) -> list[FailureGroup]:
+    """Bucket ``_SummaryRow``-ish objects by failure cause, biggest group first.
+
+    Each row needs ``.slug`` and ``.fail_tails`` (a list of ``(nodeid, tail)``).
+    Rows with no captured tail are grouped under a single ``unknown`` bucket
+    rather than dropped — a failure with no detail is still a failure the reader
+    needs to see.
+    """
+    groups: dict[str, FailureGroup] = {}
+    for row in rows:
+        tails = getattr(row, "fail_tails", None) or [("", "")]
+        for nodeid, tail in tails:
+            fp = fingerprint(tail)
+            group = groups.get(fp)
+            if group is None:
+                group = FailureGroup(fingerprint=fp, headline=headline(tail))
+                groups[fp] = group
+            group.occurrences.append((row.slug, nodeid, tail))
+    # Biggest first; ties broken by fingerprint so output is deterministic.
+    return sorted(groups.values(), key=lambda g: (-g.count, g.fingerprint))

steppy/_parallel/image.py

@@ -0,0 +1,380 @@
+"""Resolve, probe and build the steppy-worker Docker image.
+
+The image tag is ``<image_prefix>:<package_version>-<src_hash>`` (e.g.
+``steppy-worker:0.3.0-ab12cd34ef56``). The hash covers every ``*.py`` under
+the installed package root, so any change to steppy's source — a dev edit on
+an editable install, or a reinstall of a different build of the same version
+— produces a new tag and therefore a rebuild, instead of silently shipping
+stale code into the container.
+
+Build inputs (Dockerfile + context) are resolved through three modes, in
+priority order — see :func:`resolve_build_inputs`:
+
+``config``
+    ``parallel.dockerfile`` / ``parallel.build_context`` are set. Escape hatch
+    for a fully custom worker image.
+``repo``
+    steppy is running out of a source checkout (``<root>/src/steppy`` with a
+    sibling ``Dockerfile`` + ``pyproject.toml``). Builds from the repo root,
+    exactly as steppy always has.
+``installed``
+    Everything else — steppy installed as a wheel, with no source tree on the
+    machine. Synthesizes a self-contained build context from the installed
+    package (see :func:`synthesize_installed_context`) and builds it with the
+    bundled ``_docker/Dockerfile.installed``.
+
+Auto-build on first run is the default — :func:`ensure_worker_image` probes
+``docker images`` for the tag and builds if missing. The CLI's ``--no-build``
+flag flips ``build=False`` to fail fast instead.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from .. import DISTRIBUTION
+
+
+# Playwright base image for the synthesized worker build. Kept in lockstep
+# with the repo-root ``Dockerfile`` and ``_docker/Dockerfile.installed`` —
+# drift guard: ``tests/test_parallel_worker_image.py``. Overridable per
+# project via ``parallel.worker_base_image``.
+DEFAULT_PLAYWRIGHT_BASE = "mcr.microsoft.com/playwright/python:v1.60.0-noble"
+
+# Build-arg name declared by both Dockerfiles.
+_BASE_IMAGE_ARG = "PLAYWRIGHT_BASE"
+
+# Optional extras baked into the worker image by BOTH build modes: the repo
+# Dockerfile via ``pip install '/tmp/steppy[retry,report]'``, the installed
+# mode via :func:`runtime_requirements`. ``retry`` is load-bearing —
+# ``steppy run --workers N --retries K`` resolves host-side but executes
+# ``--reruns`` inside the container.
+BAKED_EXTRAS = ("retry", "report")
+
+# Matches ``extra == "report"`` / ``extra == 'report'`` in a requirement marker.
+_EXTRA_MARKER_RE = re.compile(r"""extra\s*==\s*['"]([^'"]+)['"]""")
+
+# Bumped whenever the worker image's CONTENT changes without any *.py under the
+# package changing — i.e. a Dockerfile or baked-extras edit. ``compute_image_tag``
+# hashes only ``*.py``, so without this a warm image would silently be reused and
+# the new content would never land. Bump = one rebuild for everyone, once.
+#   1 → original
+#   2 → [retry,report] extras baked in
+WORKER_IMAGE_CONTRACT = "2"
+
+# Subdirectory of the coordinator's run tmp dir that holds a synthesized context.
+_CONTEXT_DIRNAME = "worker-build-context"
+
+# Never copied into a synthesized build context.
+_COPY_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo")
+
+
+@dataclass(frozen=True)
+class BuildInputs:
+    """What ``docker build`` needs, plus which mode produced it."""
+
+    dockerfile: Path
+    context: Path
+    mode: str  # "config" | "repo" | "installed"
+    build_args: dict[str, str] = field(default_factory=dict)
+
+
+def _package_version() -> str:
+    """Installed steppy version, e.g. '0.3.0'. Falls back to '0-unknown' if
+    the metadata isn't readable (shouldn't happen but is non-fatal)."""
+    try:
+        return importlib.metadata.version(DISTRIBUTION)
+    except importlib.metadata.PackageNotFoundError:
+        return "0-unknown"
+
+
+def _src_content_hash(package_root: Path) -> str:
+    """Short hex digest over the package source. Used as a tag suffix so
+    worker images rebuild when the steppy source changes.
+
+    Hashes file paths + contents in sorted order — deterministic, fast on
+    the steppy package size (~10K LOC). Excludes ``__pycache__``.
+    """
+    sha = hashlib.sha256()
+    for path in sorted(package_root.rglob("*.py")):
+        if "__pycache__" in path.parts:
+            continue
+        rel = path.relative_to(package_root).as_posix().encode("utf-8")
+        sha.update(rel)
+        sha.update(b"\0")
+        sha.update(path.read_bytes())
+        sha.update(b"\0")
+    return sha.hexdigest()[:12]
+
+
+def compute_image_tag(package_root: Path, extra: str = "") -> str:
+    """Tag to append after the image prefix: ``<version>-<src_hash>``.
+
+    The hash is unconditional. It used to be added only on editable installs
+    (detected via a sibling ``pyproject.toml``), which meant a wheel install
+    collapsed to a bare ``0.3.0`` — so reinstalling a different build of the
+    same version silently reused a stale worker image.
+
+    ``extra`` folds additional build-affecting inputs (currently
+    ``parallel.worker_base_image``) into the digest. Empty by default, so
+    tags are unchanged for projects that don't set it.
+    """
+    version = _package_version()
+    digest = _src_content_hash(package_root)
+    if extra:
+        digest = hashlib.sha256((digest + "\0" + extra).encode("utf-8")).hexdigest()[:12]
+    # `-` separator (not `+`) — the Docker tag spec is [a-zA-Z0-9_.-] and rejects `+`.
+    return f"{version}-{digest}"
+
+
+def image_exists(image_ref: str) -> bool:
+    """True if ``docker images`` lists the given <image>:<tag>."""
+    try:
+        result = subprocess.run(
+            ["docker", "images", "--format", "{{.Repository}}:{{.Tag}}", image_ref],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+    if result.returncode != 0:
+        return False
+    return image_ref in result.stdout.splitlines()
+
+
+def build_image(
+    image_ref: str,
+    dockerfile: Path,
+    build_context: Path,
+    build_args: Optional[dict[str, str]] = None,
+) -> None:
+    """Run ``docker build -t <image_ref> -f <dockerfile> <context>``. Streams
+    output to stdout so the user sees progress on a long first build."""
+    cmd = ["docker", "build", "-t", image_ref]
+    for key, value in (build_args or {}).items():
+        cmd.extend(["--build-arg", f"{key}={value}"])
+    cmd.extend(["-f", str(dockerfile), str(build_context)])
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"Failed to build worker image {image_ref!r}. "
+            f"Re-run the build manually to see the full error: {' '.join(cmd)}"
+        )
+
+
+# --------------------------------------------------------------------------
+# Build-input resolution
+# --------------------------------------------------------------------------
+
+
+def _bundled_dockerfile() -> Path:
+    """Path of the wheel-bundled ``Dockerfile.installed``."""
+    path = Path(__file__).resolve().parent.parent / "_docker" / "Dockerfile.installed"
+    if not path.is_file():
+        raise RuntimeError(
+            f"Bundled worker Dockerfile missing at {path}. This means the steppy install is "
+            f"incomplete — reinstall steppy, or point `parallel.dockerfile` at a worker "
+            f"Dockerfile you control."
+        )
+    return path
+
+
+def _abs_path(raw: str, project_root: Path) -> Path:
+    """Resolve a config path: absolute wins, otherwise relative to project root."""
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        path = project_root / path
+    return Path(path)
+
+
+def _dist_info_stem(name: str) -> str:
+    """A distribution name as its ``.dist-info`` folder spells it: runs of
+    ``-``, ``_`` and ``.`` become one ``_``, lowercased (the wheel spec).
+    """
+    return re.sub(r"[-_.]+", "_", name).lower()
+
+
+def runtime_requirements() -> list[str]:
+    """steppy's runtime dependencies, read from the installed metadata.
+
+    Extras named in :data:`BAKED_EXTRAS` are **included** (with the marker
+    stripped, since the container unconditionally wants them) so this image
+    matches what the repo-root ``Dockerfile`` installs via
+    ``pip install '/tmp/steppy[retry,report]'``. Any other optional-extra
+    requirement is dropped. Non-extra environment markers are preserved
+    verbatim for pip to evaluate.
+    """
+    try:
+        reqs = importlib.metadata.requires(DISTRIBUTION)
+    except importlib.metadata.PackageNotFoundError:
+        reqs = None
+    if not reqs:
+        raise RuntimeError(
+            "Cannot read steppy's dependency metadata, so the worker image build context "
+            "cannot be synthesized. Point `parallel.dockerfile` (and optionally "
+            "`parallel.build_context`) at a worker Dockerfile you control, or run steppy "
+            "from a source checkout."
+        )
+    out: list[str] = []
+    for raw in reqs:
+        spec, _, marker = raw.partition(";")
+        if "extra" in marker:
+            named = _EXTRA_MARKER_RE.search(marker)
+            if named and named.group(1) in BAKED_EXTRAS:
+                # Strip the marker: inside the container the extra is not
+                # conditional, it is simply wanted.
+                out.append(spec.strip())
+            continue
+        line = raw.strip() if marker.strip() else spec.strip()
+        if line:
+            out.append(line)
+    return out
+
+
+def synthesize_installed_context(*, package_root: Path, staging_dir: Path) -> Path:
+    """Build a self-contained ``docker build`` context from the INSTALLED package.
+
+    Produces, under ``<staging_dir>/worker-build-context/``::
+
+        Dockerfile                  copy of the bundled _docker/Dockerfile.installed
+        requirements.txt            runtime deps from the installed metadata
+        pkg/steppy/                 copy of the installed package
+        pkg/steppy_dev-<ver>.dist-info/ so importlib.metadata works in the container
+
+    This exists because the repo-root ``Dockerfile`` COPYs ``pyproject.toml``,
+    ``hatch_build.py``, ``src/``, ``templates/``, ``skills/`` and
+    ``CHANGELOG.md`` — none of which exist when steppy was installed as a
+    wheel. The worker container only runs ``python -m steppy worker`` →
+    pytest on the already-generated tests bind-mounted from the project, so a
+    package copy is functionally equivalent to the repo build.
+    """
+    context = staging_dir / _CONTEXT_DIRNAME
+    if context.exists():
+        shutil.rmtree(context)
+    pkg_dir = context / "pkg"
+    pkg_dir.mkdir(parents=True)
+
+    shutil.copytree(package_root, pkg_dir / package_root.name, ignore=_COPY_IGNORE)
+
+    # dist-info is best-effort: without it the package still imports, only
+    # importlib.metadata.version(DISTRIBUTION) stops working inside the container.
+    # The folder is named after the distribution, not the import package, and
+    # in its normalised form (`steppy_dev-0.3.0.dist-info`).
+    for dist_info in sorted(package_root.parent.glob(f"{_dist_info_stem(DISTRIBUTION)}-*.dist-info")):
+        shutil.copytree(dist_info, pkg_dir / dist_info.name, ignore=_COPY_IGNORE)
+        break
+
+    requirements = "\n".join(runtime_requirements())
+    (context / "requirements.txt").write_text(requirements + "\n", encoding="utf-8")
+    shutil.copyfile(_bundled_dockerfile(), context / "Dockerfile")
+    return context
+
+
+def resolve_build_inputs(
+    *,
+    package_root: Path,
+    project_root: Path,
+    parallel_cfg: Any,
+    staging_dir: Path,
+) -> BuildInputs:
+    """Pick the Dockerfile + build context for the worker image.
+
+    Priority: explicit config → source checkout → synthesized from the
+    installed package. Raises ``RuntimeError`` with an actionable message
+    when explicitly configured paths don't exist.
+    """
+    base_override = getattr(parallel_cfg, "worker_base_image", None)
+    build_args = {_BASE_IMAGE_ARG: base_override} if base_override else {}
+
+    dockerfile_cfg = getattr(parallel_cfg, "dockerfile", None)
+    context_cfg = getattr(parallel_cfg, "build_context", None)
+
+    if dockerfile_cfg:
+        dockerfile = _abs_path(dockerfile_cfg, project_root)
+        if not dockerfile.is_file():
+            raise RuntimeError(
+                f"`parallel.dockerfile` is set to {dockerfile_cfg!r} but no file exists at {dockerfile}. "
+                f"Fix the path in config.yaml (relative paths resolve from the project root), "
+                f"or remove the setting to let steppy build the worker image itself."
+            )
+        context = _abs_path(context_cfg, project_root) if context_cfg else dockerfile.parent
+        if not context.is_dir():
+            raise RuntimeError(
+                f"`parallel.build_context` is set to {context_cfg!r} but no directory exists at {context}."
+            )
+        return BuildInputs(dockerfile=dockerfile, context=context, mode="config", build_args=build_args)
+
+    if context_cfg:
+        raise RuntimeError(
+            "`parallel.build_context` is set but `parallel.dockerfile` is not. "
+            "Set both to use a custom worker image, or neither to let steppy build it."
+        )
+
+    # Source checkout: <repo>/src/steppy → <repo>. Unchanged from day one.
+    repo_root = package_root.parent.parent
+    repo_dockerfile = repo_root / "Dockerfile"
+    if repo_dockerfile.is_file() and (repo_root / "pyproject.toml").is_file():
+        return BuildInputs(dockerfile=repo_dockerfile, context=repo_root, mode="repo", build_args=build_args)
+
+    context = synthesize_installed_context(package_root=package_root, staging_dir=staging_dir)
+    return BuildInputs(
+        dockerfile=context / "Dockerfile",
+        context=context,
+        mode="installed",
+        build_args=build_args,
+    )
+
+
+def ensure_worker_image(
+    *,
+    image_prefix: str,
+    package_root: Path,
+    project_root: Path,
+    parallel_cfg: Any,
+    staging_dir: Path,
+    build: bool = True,
+) -> tuple[str, str]:
+    """Return ``(image_ref, mode)``, building the image if it isn't present.
+
+    ``mode`` is ``"cached"`` when an existing local image was reused, else the
+    :class:`BuildInputs` mode that produced the build.
+
+    The local probe happens BEFORE build inputs are resolved, so a warm image
+    costs nothing — no context is synthesized. That probe is also where a
+    future registry ``docker pull`` slots in: local → pull → build.
+
+    Raises ``RuntimeError`` if the image is missing and ``build=False`` (the
+    user passed ``--no-build``), or if resolution or the build itself fails.
+    """
+    base_override = getattr(parallel_cfg, "worker_base_image", None) or ""
+    # WORKER_IMAGE_CONTRACT rides in the tag digest so an image-content change
+    # that touches no *.py (a Dockerfile / baked-extras edit) still invalidates
+    # warm images instead of being silently ignored.
+    tag_extra = f"{WORKER_IMAGE_CONTRACT}\0{base_override}"
+    image_ref = f"{image_prefix}:{compute_image_tag(package_root, extra=tag_extra)}"
+    if image_exists(image_ref):
+        return image_ref, "cached"
+    if not build:
+        raise RuntimeError(
+            f"Worker image {image_ref!r} not found locally and --no-build was passed. "
+            f"Re-run without --no-build to let steppy build it, or build it yourself and "
+            f"tag it {image_ref}."
+        )
+    inputs = resolve_build_inputs(
+        package_root=package_root,
+        project_root=project_root,
+        parallel_cfg=parallel_cfg,
+        staging_dir=staging_dir,
+    )
+    build_image(image_ref, inputs.dockerfile, inputs.context, build_args=inputs.build_args)
+    return image_ref, inputs.mode

steppy/_parallel/lastfailed.py

@@ -0,0 +1,125 @@
+"""Write pytest's ``lastfailed`` cache from a parallel run's results so
+``steppy rerun`` re-runs the scenarios that failed in *that* run.
+
+``steppy rerun`` reads ``<cwd>/.pytest_cache/v/cache/lastfailed`` and feeds
+it to ``pytest --lf``. Only the single-worker ``steppy run`` path populates
+that cache (plain pytest, cache provider active). A parallel
+``steppy run --workers N`` never touches it — workers run with
+``-p no:cacheprovider`` and the project root is bind-mounted read-only into
+each container — so after a parallel run the cache still reflects the last
+*single-worker* run (or is absent), and ``rerun`` re-runs an OLD failure set.
+
+This module closes that gap: the coordinator calls
+:func:`write_lastfailed_cache` after it aggregates results, writing the same
+cache file ``rerun`` reads. Both run modes then converge on one file, so
+"last run wins" becomes automatic and ``rerun`` needs no changes.
+
+**Granularity is file-level** — one key per failed *scenario file* (a key
+with no ``::``). ``pytest --lf`` treats a bare file path as "re-run the whole
+file": collection is restricted to the failed files via the plugin's
+``_last_failed_paths`` and, with no per-node key matching, nothing is
+deselected, so every test in each failed file runs. This is robust — it
+covers orphaned/crashed workers and the "events plugin didn't load"
+degenerate case, neither of which yields node IDs — and it never drops a
+failed scenario. (Mixing file-level and node-level keys is unsafe: a matching
+node-level key makes pytest deselect everything else, including file-level
+entries, so we keep the keys uniformly file-level.)
+
+Lazy-imported from :mod:`steppy.coordinator` so it only loads in parallel
+mode (the single-worker ``test_no_parallel_import_on_default_path`` guard
+relies on this).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from .event_bus import EventBus
+from .queue import ScenarioResult
+
+
+def write_lastfailed_cache(
+    *,
+    project_root: Path,
+    tests_dir: Path,
+    scenario_results: list[ScenarioResult],
+    orphans: dict[str, list[str]],
+    bus: EventBus,
+    failed_slugs: Optional[set[str]] = None,
+) -> Optional[Path]:
+    """Write ``project_root/.pytest_cache/v/cache/lastfailed`` from a parallel
+    run's outcome.
+
+    Returns the path written, or ``None`` if writing failed. The function
+    NEVER raises — cache writing is best-effort; any ``OSError`` is swallowed
+    so a filesystem hiccup on teardown can't crash the coordinator.
+
+    The cache is written **unconditionally** — an all-pass run writes an empty
+    dict so a subsequent ``rerun`` correctly reports "all passed" instead of
+    re-running a stale older failure set. That reset is the crux of the fix.
+
+    ``failed_slugs`` lets the caller supply the authoritative failure set. The
+    retry pass uses it to pass only the scenarios that failed *every* attempt —
+    a flaky scenario ended green, so putting it here would make ``steppy rerun``
+    re-run known-good tests. Omitted ⇒ derived from ``scenario_results`` +
+    ``orphans`` exactly as before.
+    """
+    if failed_slugs is None:
+        # Failed scenarios: authoritative per-scenario exit codes (mirrors
+        # coordinator's `failed = sum(...)`) plus orphans (claimed, never reported).
+        failed_slugs = {r.slug for r in scenario_results if r.exit_code != 0}
+        for slugs in orphans.values():
+            failed_slugs.update(slugs)
+
+    # Map slug -> real test-file path exactly as pytest spelled it inside the
+    # worker (rootdir-relative). The container mounts the same project files at
+    # /steppy/project, so the worker's rootdir-relative nodeid matches what the
+    # host `pytest --lf` will compute. Prefer this over guessing the rootdir.
+    file_part_by_slug: dict[str, str] = {}
+    for t in bus.snapshot().tests:
+        if not t.scenario_slug:
+            continue
+        file_part = t.nodeid.split("::", 1)[0]
+        # Skip synthetic nodeids (e.g. "<synthetic>::slug") and anything that
+        # isn't a real test file.
+        if file_part.endswith(".py"):
+            file_part_by_slug.setdefault(t.scenario_slug, file_part)
+
+    tests_rel = _tests_rel_posix(tests_dir, project_root)
+
+    lastfailed: dict[str, bool] = {}
+    for slug in sorted(failed_slugs):
+        key = file_part_by_slug.get(slug) or f"{tests_rel}/test_{slug}.py"
+        lastfailed[key] = True
+
+    cache_dir = project_root / ".pytest_cache" / "v" / "cache"
+    try:
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        (cache_dir / "lastfailed").write_text(json.dumps(lastfailed, indent=2, sort_keys=True), encoding="utf-8")
+    except OSError:
+        return None
+
+    # Keep the cache out of git, exactly as pytest does when it owns the dir.
+    gitignore = project_root / ".pytest_cache" / ".gitignore"
+    if not gitignore.exists():
+        try:
+            gitignore.write_text("# Created by steppy automatically.\n*\n", encoding="utf-8")
+        except OSError:
+            pass
+
+    return cache_dir / "lastfailed"
+
+
+def _tests_rel_posix(tests_dir: Path, project_root: Path) -> str:
+    """The tests dir as a posix path relative to the project root.
+
+    pytest node IDs are always posix (``/``) even on Windows, so the file-level
+    fallback key must be too. Falls back to ``tests_dir`` as-is when it isn't
+    under ``project_root``.
+    """
+    try:
+        return tests_dir.resolve().relative_to(project_root.resolve()).as_posix()
+    except (ValueError, OSError):
+        return tests_dir.as_posix()