conftest.py

"""Repo-root pytest configuration: the host-mutation floor.

``test/conftest.py`` holds the bulk of the suite's isolation, but it only applies
to ``test/``. ``[tool:pytest] testpaths`` also collects ``transfer`` and
``src/kiro_crew/apps/builtins`` (~108 test modules that ship inside the package,
next to the code they cover), and those get no ``test/conftest.py`` fixtures at
all -- only this file, plus that app's own ``tests/conftest.py`` where one exists.
Anything that must hold for EVERY test therefore has to live here, at the
rootdir, which is the one conftest pytest applies to every testpath.

Only the HOST-MUTATION FLOOR belongs in this file: the guards that must hold for a
test collected from any testpath, because what they protect is the
developer's machine rather than the correctness of one suite. Everything that is
merely suite-specific isolation stays in ``test/conftest.py``.

The floor has eight parts, and each one exists because the "remember to isolate
this" contract failed at least once:

* **Services.** ``$XDG_CONFIG_HOME`` is redirected and the stdlib spawn funnels
  refuse a ``systemctl``/``launchctl`` invocation carrying a mutating verb, so no
  test can reconfigure or restart the operator's real gateway (issue #1722).
* **The data home.** ``KIROCREW_HOME`` is pinned per test, and the ``~/.kiro``
  paths that production binds at IMPORT time (which the env var cannot reach) are
  pinned with it. Without this, the ~108 test modules that ship inside the package
  under ``src/kiro_crew/apps/builtins/*/tests/`` -- which see this conftest and no
  other -- write the operator's live ``~/.kiro/crew`` the moment they touch
  ``config_dir()``. ``KIROCREW_WORKSPACE`` is pinned alongside it for the same
  reason: ``workspace_root()`` is a SEPARATE default from ``config_dir()`` (it
  falls back to ``~/workplace/kirocrew-workspace``, not under the data home at
  all), so pinning only ``KIROCREW_HOME`` leaves it resolving to the operator's
  real ``~/workplace`` the moment a test reaches an agent working directory.
* **Credential environment.** Recognised fixed credentials and validated
  ``JIRA_TOKEN_<HEX>`` keys are restored after every test, so a fabricated
  ``.env`` cannot silently override the next test's credentials in the same
  worker.
* **The inherited shell environment.** The entries ``name_grant`` refuses as
  inherited preloads are removed for each test's duration and restored
  afterwards: the ``_ENV_PRELOAD_VARS`` names (``BASH_ENV``, ``ENV``, ...) and
  exported bash functions (``BASH_FUNC_*`` keys, or the legacy bare-name
  spelling whose value starts with ``() {``). RHEL-family hosts export ``which``
  as a function from ``/etc/profile.d/which2.sh``, and that refusal is checked
  before every narrower code, so 79 of 163 name-grant tests observed the wrong
  refusal on those hosts while Ubuntu CI stayed green (issue #8395).
* **The agent-spec home.** ``kiro_agents_dir()`` is a LAZY resolver, so neither of
  the two above reaches it, and a test that reaches the spec write path rewrites
  the machine-wide ``<kiro home>/agents/kirocrew.json`` -- the file that decides
  which MCP servers the operator's real agent has (issue #4912). The per-module
  override seams are pinned instead of ``KIRO_HOME``, which cannot be pinned
  without overriding ~35 tests' own ``Path.home()`` isolation.
* **The system temp directory.** ``tempfile``'s base is redirected to a per-run
  directory for the whole process, so a bare ``mkdtemp()`` whose cleanup is missing
  or skipped leaves its directory somewhere this run owns and removes, instead of
  accumulating in the shared temp root forever. What was left behind is REPORTED
  first, so the leak is a red rather than silent inode consumption. On macOS the
  base is additionally moved to ``/tmp`` -- the prefix Linux and CI already use --
  because the launchd per-user temp dir is long enough to break an AF_UNIX bind and
  random enough to read as a credential. See :data:`_SHORT_TMP_BASE`.
* **The sandbox mount-source sweep.** The periodic janitor's candidate roots
  (the operator's real ``/run/user/$UID`` and ``/dev/shm``) and its /proc pin
  scan are both pinned to inert stand-ins -- the roots to an empty directory,
  the scan to fail-closed -- so no test deletes real orphaned bind-mount
  sources from the developer's machine or depends on host process state.
* **The repository checkout.** The run fails when it ends with residue anywhere in
  the checkout, which is how a subprocess spawned without ``cwd=`` announces
  itself.

One consequence of living at the rootdir: the module name ``conftest`` is now
resolvable from the repository root as well as from ``test/``, and 11 test modules
import helpers by bare name (``from conftest import requires_git``). Under pytest's
default ``prepend`` import mode each test module's own directory goes on
``sys.path`` first, so those imports still bind to ``test/conftest.py`` -- but the
name IS shadowed, so switching to ``--import-mode=importlib`` would need those
imports made explicit first. The visible effect today is that isort now classifies
``conftest`` as first-party (a root-level module is inside its default
``src_paths``), which is why this change also reorders that import in the modules
that use it.

Why this floor exists (issue #1722): a test asserting that a staged cutover can
be *cancelled* rewrote the operator's real ``kirocrew-gateway.service`` drop-in
to point at its own pytest temp dir. pytest deleted the temp dir at the end of
the run; the drop-in survived, so systemd looped on ``203/EXEC`` — 548 failed
starts over 25 minutes. The test never intended to touch the host: it called the
real ``_make_live()`` because that function was the subject under test, and two
of that function's seams (the drop-in path and the subprocess layer) were left
for each test to remember to stub.

The fixtures below remove that "remember to" from the contract. None of them
changes the behaviour of a test that already isolates itself correctly: every one
sets a value a test can still override, and a test that sets its own
``KIROCREW_HOME`` or its own temp dir keeps winning.

Imports at MODULE level are stdlib + pytest only, on purpose: a rootdir conftest is
imported before every collection, so pulling ``kiro_crew`` in here would make the
whole suite depend on import-time side effects of the package under test. The
fixtures that do need ``kiro_crew`` import it in their own body, which runs at test
setup -- by which point the test module has already imported the package anyway --
and tolerate an ImportError so a partial checkout cannot break collection.
"""

from __future__ import annotations

import asyncio
import asyncio.base_events
import atexit
import contextlib
import functools
import gc
import getpass
import importlib
import linecache
import logging
import os
import pathlib
import shutil
import subprocess
import sys
import tempfile
import threading
import time
import warnings

import _pytest.outcomes
import _pytest.runner
import pytest

# ── ACP frame recorder switch (rootdir floor) ───────────────────────────────
# ``kiro_crew.acp._frame_record`` starts its writer thread at IMPORT time when
# ``KIROCREW_ACP_RECORD_FRAMES`` is set, and ``acp.client`` (hence the dashboard
# server, the session handle, the Slack handler, ...) imports it transitively. An
# operator running the suite with a live recording configured would otherwise
# have every collected test module's fake frames appended to their real corpus
# file -- from ANY testpath, including the ~108 modules under
# ``src/kiro_crew/apps/builtins/*/tests/`` that never see ``test/conftest.py``.
# Cleared here, at rootdir-conftest import, which precedes every test module's
# first ``kiro_crew`` import; tests that need the switch set it themselves
# through monkeypatch.
os.environ.pop("KIROCREW_ACP_RECORD_FRAMES", None)

# ── how this run names the directories it leaves in the platform temp root ────
#
# Defined up here, far from :func:`_create_tmp_root` and the rest of the temp-base
# section, because the import-time data-home floor below is created BEFORE any of
# that runs and has to be named by the same stem: a stray directory is attributable
# to the run that made it or it is attributable to nobody.


#: Prefix for the run's own temp base, a sibling of the platform temp root.
#:
#: The name is ``kc-pytest-<user>-<pid>``. The pid is what lets a later run tell an
#: ABANDONED root (its process is gone) from one a concurrent run is still using. The
#: user segment is not decoration: on POSIX the platform temp root is SHARED between
#: accounts, so a bare pid collides across users -- two accounts can hold the same pid
#: at the same time, and the second would try to reuse a directory it cannot write.
#: Windows gives each account its own temp root, so there the segment is redundant and
#: harmless.
_TMP_ROOT_PREFIX = "kc-pytest-"


def _tmp_root_prefix_for_run() -> str:
    """``kc-pytest-<user>-<pid>-`` -- the stem this run's temp root is created under.

    The user segment is not decoration: on POSIX the platform temp root is SHARED between
    accounts, so a bare pid collides across users -- two accounts can hold the same pid at
    the same time. The pid is what lets a later run tell an ABANDONED root from one a
    concurrent run is still using. The trailing hyphen is where ``mkdtemp`` appends its
    random component; see :func:`_create_tmp_root` for why that randomness is required and
    not cosmetic.
    """
    try:
        raw = getpass.getuser()
    except Exception:  # noqa: BLE001 - no passwd entry and no env fallback
        raw = "u"
    user = "".join(ch if ch.isalnum() else "_" for ch in raw)[:24] or "u"
    return f"{_TMP_ROOT_PREFIX}{user}-{os.getpid()}-"


# ── The data-home floor, installed at IMPORT time ────────────────────────────
#
# Every per-test redirect of ``KIROCREW_HOME`` is a value laid over whatever the
# process started with, so the danger is never a wrong value -- it is the ABSENCE
# of one. ``config.paths._valid_override_home`` reads the variable and, finding it
# unset, falls through to ``_default_home()``: the operator's real ``~/.kiro/crew``.
# Anything that can return the variable to "unset" mid-session therefore aims the
# whole suite at live data, and a single ``monkeypatch.undo()`` on the shared
# function-scoped instance does exactly that -- it reverts every patch on that
# stack, including a redirect some fixture installed. One such undo truncated an
# operator's real 36 MB ``memory.db`` to 29 bytes, with no backup.
#
# Setting the variable HERE, before pytest imports a fixture or a test module,
# removes "unset" from the set of reachable states: an undo restores the value the
# process started with, which is now this scratch directory rather than nothing.
# That closes the entire class at the process level, so it holds no matter which
# fixture owns a redirect, whether that fixture used a private ``MonkeyPatch``, or
# what a future test does to the shared one.
#
# An operator's own ``KIROCREW_HOME`` is honoured untouched: someone running the
# suite against a deliberately chosen home keeps it, and only the unset case --
# the one that resolves to live data -- is given a floor.
# ``mkdtemp``, never ``mkdir(exist_ok=True)`` on a pid-derived name -- the same rule
# :func:`_create_tmp_root` states and for the same reason: a pid-derived name is
# PREDICTABLE, so another local account can pre-create it as a SYMLINK to a directory
# it controls, and ``exist_ok=True`` succeeds against a symlink-to-directory. This
# directory becomes the data home the whole session falls back to, so every secret,
# token and ``memory.db`` the suite fabricates would land where that account chose.
# ``mkdtemp`` creates with O_EXCL at mode 0700 and fails rather than adopting.
# These literals are also the session guard's source of truth below. They must
# exist before choosing the import-time floor so even an inherited temp root
# inside live memory cannot influence that choice.
_REAL_DATA_HOMES = (
    pathlib.Path.home() / ".kiro" / "crew",
    pathlib.Path.home() / ".kirocrew",
)


def _create_host_home_floor() -> pathlib.Path:
    """Create the import-time floor without consulting temp environment vars.

    Named with :func:`_tmp_root_prefix_for_run` plus ``home-``, so the directory reads
    ``kc-pytest-<user>-<pid>-home-<random>`` and sorts beside the temp root the same run
    creates later. That naming is the whole point: this floor is removed only by the
    ``atexit`` handler below, which a SIGKILL (a CI timeout, a watchdog, an agent-driven
    run's kill) does not run, and ``_tmp_residue`` scans only under the run's OWN temp
    base -- so a surviving floor is invisible to the residue report and the account plus
    pid in its name is the only signal a human has for attributing it. The earlier
    ``kirocrew-test-floor-`` name identified neither the account nor the run, so a stray
    one could not be told from another user's or from a run still in progress.
    """
    if os.name == "nt":
        candidates = (
            pathlib.Path.home() / "AppData" / "Local" / "Temp",
            pathlib.Path(os.environ.get("SystemRoot", r"C:\Windows")) / "Temp",
            pathlib.Path(os.environ.get("ProgramData", r"C:\ProgramData")),
        )
    else:
        candidates = (pathlib.Path("/tmp"), pathlib.Path("/var/tmp"), pathlib.Path("/usr/tmp"))
    for candidate in candidates:
        try:
            base = candidate.resolve(strict=True)
        except OSError:
            continue
        unsafe = False
        for real in _REAL_DATA_HOMES:
            try:
                live = real.resolve()
            except OSError:
                live = real.absolute()
            if base == live or live in base.parents or base in live.parents:
                unsafe = True
                break
        if unsafe or not base.is_dir():
            continue
        try:
            prefix = f"{_tmp_root_prefix_for_run()}home-"
            return pathlib.Path(tempfile.mkdtemp(dir=base, prefix=prefix))
        except OSError:
            continue
    raise RuntimeError("no writable system temp directory exists outside live Kiro Crew homes")


_HOST_HOME_FLOOR: "pathlib.Path | None" = None
if not os.environ.get("KIROCREW_HOME"):
    _HOST_HOME_FLOOR = _create_host_home_floor()
    os.environ["KIROCREW_HOME"] = str(_HOST_HOME_FLOOR)

    @atexit.register
    def _remove_host_home_floor() -> None:
        """Remove the floor, so it does not accumulate in the platform temp root.

        This is the ONLY removal, and it is deliberately the only one. ``atexit`` is
        skipped by the SIGKILL that produces the residue actually MEASURED on developer
        hosts (one stray floor per aborted run), but no in-process hook does better: a
        session-fixture finalizer or ``pytest_unconfigure`` is skipped by the same signal,
        and under ``-n auto`` the process that OWNS the floor is the CONTROLLER -- it sets
        ``KIROCREW_HOME`` at conftest import, every execnet worker inherits it and so takes
        the branch above as false, and the controller runs no session fixtures at all.
        Sweeping OTHER runs' floors is ruled out by the same unsoundness argument
        :func:`_isolate_tempfile_base` spells out for the temp root: the name is
        pre-createable by another local account and a pid means nothing across PID
        namespaces. So a killed run leaves TWO directories for the platform to reclaim --
        the run's temp root and this floor -- and the floor leaks MORE often, because it is
        created at conftest import and therefore survives even a run aborted during
        collection, before any session fixture existed to make a temp root.

        Nothing reports it either: ``_tmp_residue`` scans only under the run's own temp
        base, and this floor is a SIBLING of that base in the platform temp root, so
        neither the residue warning nor ``KIROCREW_TMP_RESIDUE_STRICT`` can see it or
        anything a test wrote into it. That invisibility is why the directory carries
        ``_tmp_root_prefix_for_run()`` in its name.
        """
        if _HOST_HOME_FLOOR is not None:
            shutil.rmtree(_HOST_HOME_FLOOR, ignore_errors=True)


def _refuse_a_real_data_home() -> None:
    """Refuse to run at all if the session would resolve a real data home.

    A second, independent barrier to the floor above, and the one that fails LOUD.
    The floor prevents the accident; this catches the case where someone exports
    ``KIROCREW_HOME`` to their real home by hand -- copying a command out of a
    runbook, or reusing a shell that was pointed at live data -- which no amount of
    per-test isolation can distinguish from a deliberate choice.

    Called from ``pytest_configure`` rather than being a second hook of that name:
    a module defines one, and a duplicate silently replaces the earlier definition
    instead of running alongside it.
    """
    resolved = pathlib.Path(os.environ["KIROCREW_HOME"]).expanduser()
    for real in _REAL_DATA_HOMES:
        try:
            here, live = resolved.resolve(), real.resolve()
        except OSError:  # an unreadable component cannot be the live home
            continue
        # CONTAINMENT in both directions, not equality. A PARENT is the dangerous
        # miss: ``~/.kiro`` is kiro-cli's own home and resolves the whole live tree
        # underneath it, and ``~`` resolves everything. A CHILD is refused too, since
        # the suite deletes directories it believes it created.
        if here == live or live in here.parents or here in live.parents:
            raise pytest.UsageError(
                f"KIROCREW_HOME points at the live data home {real}. The suite writes, "
                f"truncates and deletes under it, so running here destroys real memory, "
                f"sessions and config. Unset KIROCREW_HOME or point it at a scratch dir."
            )


# ── Hypothesis example database (rootdir floor) ─────────────────────────────
# ``test/conftest.py`` registers the "default"/"thorough" profiles but never sets
# ``database=``, so hypothesis falls back to its own default: ``.hypothesis/examples``
# resolved against the CURRENT WORKING DIRECTORY, i.e. the repo root, for every test
# collected from ANY testpath -- including the ~108 modules under
# ``src/kiro_crew/apps/builtins/*/tests/`` that never import ``test/conftest.py`` at all.
# That writes an untracked directory into the checkout on every run (git status shows it
# under "Ignored files" since ``.gitignore`` covers it, but it still needs a place to live
# that is not the source tree).
#
# Profiles are process-global, so whichever profile is active when a ``@given`` test runs
# applies regardless of which testpath collected it. Registering a "default" profile here
# at module level would not stick: ``test/conftest.py`` re-registers "default" by name
# right after this module loads (pytest imports the rootdir conftest first, then
# ``test/conftest.py`` -- see ``pytest_load_initial_conftests``), and ``register_profile``
# without ``parent=`` builds a fresh settings object from scratch, silently resetting
# ``database`` back to the on-disk default. Doing the redirect from ``pytest_configure``
# instead runs after both conftests' module-level code, so it lands last: ``parent=`` keeps
# whatever ``max_examples``/``deadline``/health-check suppression ``test/conftest.py`` set,
# and only ``database`` is overridden.
_HYPOTHESIS_DB_DIR: str | None = None


def _redirect_hypothesis_database() -> None:
    """Point the active hypothesis profile's example database off the checkout.

    Uses a stable per-user directory under the platform cache root
    (``$XDG_CACHE_HOME`` or ``~/.cache``, ``kirocrew/hypothesis``) rather than
    ``database=None`` or a per-run temp dir: the shrunk counterexample hypothesis
    saves is what makes a property-test failure replay on the NEXT run instead of
    costing a full re-search, so the database has to outlive the process. What
    moves is only WHERE it lives -- out of the checkout and into the same cache
    tree the xdist slot files already use -- not whether it persists. Tolerates
    hypothesis being absent (a partial checkout, or an environment where it was
    never installed), an unwritable cache root (falls back to ``database=None``
    rather than to the checkout), and no profile named "default" existing yet,
    since this floor must not be the reason collection fails for a suite that
    does not use hypothesis at all.
    """
    global _HYPOTHESIS_DB_DIR
    try:
        from hypothesis import settings as _hyp_settings
        from hypothesis.database import DirectoryBasedExampleDatabase
    except ImportError:
        return
    try:
        _current = _hyp_settings.get_profile(_hyp_settings._current_profile)
    except Exception:  # noqa: BLE001 - no active profile to inherit from
        return
    if _HYPOTHESIS_DB_DIR is None:
        cache_root = os.environ.get("XDG_CACHE_HOME") or os.path.join(
            os.path.expanduser("~"), ".cache"
        )
        candidate = os.path.join(cache_root, "kirocrew", "hypothesis")
        try:
            os.makedirs(candidate, exist_ok=True)
            _HYPOTHESIS_DB_DIR = candidate
        except OSError:
            _HYPOTHESIS_DB_DIR = ""
        # The example database is only one tenant of ``.hypothesis/``: the
        # unicode-data cache (``storage_directory("unicode_data", ...)``) is written
        # through hypothesis's HOME directory, which defaults to ``.hypothesis``
        # under the CWD, i.e. the checkout. Move the home too, so the whole tree
        # lands in the cache dir; the env var is what a spawned child reads.
        if _HYPOTHESIS_DB_DIR:
            try:
                from hypothesis.configuration import set_hypothesis_home_dir

                set_hypothesis_home_dir(_HYPOTHESIS_DB_DIR)
                os.environ.setdefault("HYPOTHESIS_STORAGE_DIRECTORY", _HYPOTHESIS_DB_DIR)
            except Exception:  # noqa: BLE001 - an older hypothesis without the hook
                pass
    database = DirectoryBasedExampleDatabase(_HYPOTHESIS_DB_DIR) if _HYPOTHESIS_DB_DIR else None
    _hyp_settings.register_profile(
        _hyp_settings._current_profile,
        parent=_current,
        database=database,
    )
    _hyp_settings.load_profile(_hyp_settings._current_profile)


def _redirect_bytecode_cache() -> None:
    """Write every ``.pyc`` this run compiles under the per-user cache, not the checkout.

    Importing a module writes its bytecode beside the source, and the suite imports
    a lot that is not a package: ``scripts/*.py``, ``packaging/signing/*.py``, every
    skill's ``scripts/`` helper, ``.github/scripts``, all loaded by path through
    ``spec_from_file_location`` + ``exec_module``. Each such import left a
    ``__pycache__/`` in the tree (fifteen of them per full run at the last count),
    after two audits had closed individual sites with a scoped
    ``sys.dont_write_bytecode`` (``test/skill_script_helpers.py`` is the helper for
    that). A per-site opt-out is the "remember to" contract this file exists to
    delete, so the class is closed here instead: ``sys.pycache_prefix`` sends the
    bytecode of EVERY import to a mirror tree under the cache root, and the env var
    does the same for every interpreter a test spawns. The cache still persists
    across runs (it is keyed on the absolute source path), so warm imports stay
    warm; only WHERE the files land changes. Same cache root, same fallback posture
    and same tolerance of an unwritable root as the hypothesis redirect above.
    Runs in ``pytest_configure``, before any test module or ``test/conftest.py`` is
    imported, so the test tree's own bytecode moves too.
    """
    if os.environ.get("PYTHONDONTWRITEBYTECODE"):
        return  # nothing is written anywhere; nothing to redirect
    cache_root = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
    candidate = os.path.join(cache_root, "kirocrew", "pycache")
    try:
        os.makedirs(candidate, exist_ok=True)
    except OSError:
        return
    sys.pycache_prefix = candidate
    os.environ["PYTHONPYCACHEPREFIX"] = candidate


class _AsyncFixtureScanGate:
    """Run pytest-asyncio's fixture scan only when a fixture was registered since.

    pytest-asyncio 0.20.3 hooks ``pytest_pycollect_makeitem`` and, for EVERY test
    function name it sees, walks EVERY fixture definition the session has registered
    so far to wrap the async ones (``_preprocess_async_fixtures``). Fixtures already
    wrapped are skipped by a set lookup, but the ~1,400 synchronous ones are
    re-inspected with ``asyncio.iscoroutinefunction`` on each call. That is
    O(tests x fixtures): cProfile of a ``--collect-only`` over this suite (112,246
    tests) counted 87,244 scans x ~1,420 fixtures = 123.8 million coroutine checks,
    1,098 of the 1,285 profiled seconds -- 85% of collection. Every xdist worker pays
    it in full, and under coverage instrumentation each check costs ~2.3x more, which
    is what made the CI shards' ~33-minute "collection" phase.

    The scan's result only changes when a fixture is ADDED, and pytest funnels every
    registration -- conftest, module, class, unittest, plugin -- through
    ``FixtureManager._register_fixture``. So this wraps that one method to raise a
    dirty flag, and lets the scan through only while the flag is up. A scan on a clean
    flag would iterate the same definitions and find nothing new: the async marker
    (``_force_asyncio_fixture``) is set by the decorator at definition time and
    ``asyncio_mode`` is fixed for the run, so the skip is behaviour-preserving.

    Pinned to the plugin version it patches: upstream's own fix for this (v0.25.1,
    then v1.0.0) sits behind the v0.23 event-loop-scope rework this suite has not
    migrated to. When pytest-asyncio moves, delete this class and the install below.
    """

    def __init__(self, scan) -> None:
        self._scan = scan
        self.dirty = True
        self.scans = 0

    def mark_dirty(self) -> None:
        self.dirty = True

    def __call__(self, config, processed_fixturedefs) -> None:
        if not self.dirty:
            return
        self._scan(config, processed_fixturedefs)
        self.scans += 1
        self.dirty = False


def _gate_pytest_asyncio_fixture_scan() -> None:
    """Install :class:`_AsyncFixtureScanGate` once per process (each xdist worker)."""
    try:
        import pytest_asyncio.plugin as pa
    except ImportError:  # pragma: no cover - plugin absent; nothing to gate
        return
    from _pytest.fixtures import FixtureManager

    scan = getattr(pa, "_preprocess_async_fixtures", None)
    register = getattr(FixtureManager, "_register_fixture", None)
    if isinstance(scan, _AsyncFixtureScanGate):
        return  # already installed (pytest_configure re-entered in-process)
    if scan is None or register is None:
        # Both seams are private to their packages. A version that renamed either
        # must not turn into a crash before collection; it turns into the slow
        # collection this gate exists to remove, said out loud so the pin is revisited.
        warnings.warn(
            "pytest-asyncio fixture-scan gate not installed: a private seam moved "
            "(pytest_asyncio.plugin._preprocess_async_fixtures / "
            "_pytest.fixtures.FixtureManager._register_fixture); collection will be slow",
            RuntimeWarning,
            stacklevel=2,
        )
        return
    gate = _AsyncFixtureScanGate(scan)

    @functools.wraps(register)
    def _register_fixture(self, *args, **kwargs):
        gate.mark_dirty()
        return register(self, *args, **kwargs)

    FixtureManager._register_fixture = _register_fixture
    pa._preprocess_async_fixtures = gate


def _root_can_create_real_symlink() -> bool:
    """Probe real-link capability for tests collected outside ``test/`` too.

    Ordinary Windows shells commonly lack ``SeCreateSymbolicLinkPrivilege``.
    This is a capability probe, not an OS guess: Developer Mode/elevated Windows
    runners retain the security coverage, while only the exact tests inventoried
    in ``test/requires-real-symlinks.txt`` skip on an incapable host.
    """
    with tempfile.TemporaryDirectory() as tmp:
        target = os.path.join(tmp, "target")
        os.mkdir(target)
        try:
            os.symlink(
                target,
                os.path.join(tmp, "link"),
                target_is_directory=True,
            )
        except (OSError, NotImplementedError, AttributeError):
            return False
        return True


_ROOT_HAS_REAL_SYMLINKS = _root_can_create_real_symlink()


#: Service managers whose *mutating* subcommands reconfigure, start, or stop a
#: real service. Matched on BASENAME against every token of the argv, not just
#: ``argv[0]``, because in this codebase the interesting name is usually not
#: first: ``dev_fleet._run_cmd`` rewrites ``argv[0]`` to a trusted absolute path
#: and then routes the spawn through ``sandboxed_spawn_argv``, and
#: ``SystemdBackend.restart_detached`` invokes through ``systemd-run``, so the
#: real program ends up in the middle of the final argv behind a wrapper.
#:
#: Deliberately NOT here:
#:
#: * ``systemd-run`` — in this codebase it is not a service-control tool at all.
#:   ``sandbox`` wraps essentially EVERY subprocess in
#:   ``systemd-run --user --scope --slice=kirocrew-agents.slice -p MemoryMax=…``
#:   to apply cgroup resource limits, so denying it would refuse an ordinary
#:   ``git config`` spawn. Its one service-control use (``restart_detached``)
#:   passes ``systemctl restart`` as the wrapped command, which this guard
#:   catches on the inner token instead.
#: * ``sudo`` — a privilege prefix, not an action. Whether the spawn mutates
#:   anything is decided by the command it wraps, and ``sudo systemctl restart``
#:   is already caught on ``systemctl``.
_SERVICE_MANAGERS = frozenset({"systemctl", "launchctl", "schtasks", "schtasks.exe"})

#: Subcommands of the managers above that CHANGE host service state.
#:
#: The verb matters as much as the binary. ``systemctl show``, ``systemctl cat``
#: and ``systemctl is-active`` are read-only queries, and tests legitimately run
#: them through the sandbox to inspect the environment they are running in — a
#: guard keyed on the binary alone would fail those for no safety gain. Only the
#: verbs below actually write.
_MUTATING_VERBS = frozenset(
    {
        # systemctl
        "start",
        "stop",
        "restart",
        "try-restart",
        "reload",
        "reload-or-restart",
        "try-reload-or-restart",
        "daemon-reload",
        "daemon-reexec",
        "enable",
        "disable",
        "reenable",
        "mask",
        "unmask",
        "preset",
        "revert",
        "set-property",
        "set-environment",
        "unset-environment",
        "import-environment",
        "edit",
        "link",
        "isolate",
        "kill",
        # launchctl
        "load",
        "unload",
        "bootstrap",
        "bootout",
        "kickstart",
        "remove",
        "submit",
        "setenv",
        "unsetenv",
        "attach",
        # schtasks (Windows Task Scheduler). Verbs are `/Create`-style switches
        # and case-insensitive on the command line, so they are matched lowercased.
        "/create",
        "/delete",
        "/run",
        "/end",
        "/change",
    }
)

#: Programs that have no read-only mode worth allowing in a test: any invocation
#: rewrites host policy.
_ALWAYS_REFUSED = frozenset({"apparmor_parser"})

#: Test modules permitted to really mutate host service state.
#:
#: EMPTY, and it should stay that way. Every suite that exercises these paths
#: today already stubs them — ``test_service.py`` patches
#: ``service.linux.subprocess.run`` / ``service.macos.subprocess.run``,
#: ``test_pod.py`` and ``test_pod_launchd.py`` stub at the module boundary, and
#: the ``dev_fleet`` make-live tests stub ``_run_cmd``. So this guard breaks no
#: existing test, and an addition here means a test is about to restart a real
#: service on whoever runs the suite. Same shape as ``_ALLOWED`` in
#: ``test/test_spawn_preexec_guard.py``: an entry needs a comment saying why the
#: host mutation is acceptable.
#:
#: The two entries below are the real-service end-to-end suites, and they are the
#: reason the guard also recognises the pod CLI (see ``_POD_MUTATING_VERBS``): a
#: test that drives ``kirocrew pod up`` through a CHILD interpreter reaches
#: ``systemctl start`` / ``launchctl bootstrap`` / ``schtasks /Create`` one
#: process removed, where the in-process manager check cannot see it. Both
#: suites self-skip unless an operator sets their own opt-in variable
#: (``KIROCREW_E2E_SCENARIOS`` / ``KIROCREW_E2E_POD_WINDOWS``), run against a
#: hermetic plane (their own root, env dir, port base and unit prefix), and tear
#: down every pod, the plane root and the plane's template unit in ``finally``.
_HOST_SERVICE_EXEC_ALLOWED_MODULES: frozenset[str] = frozenset(
    {
        # The pod scenario suite (nightly ``pod-scenarios``): boots one real pod
        # per session on the ``kirocrew-e2e-pod`` plane and reclaims it.
        "e2e.scenarios.test_cron_fire",
        "e2e.scenarios.test_service_install_dry_run",
        "e2e.scenarios.test_settings_save",
        "e2e.scenarios.test_subagent_spawn",
        "e2e.scenarios.test_wheel_install",
        # The Windows pod boot canary: one real Task Scheduler task on a
        # per-run plane, removed by ``pod down`` before the test returns.
        "test_pod_windows_boot",
    }
)

#: ``kirocrew pod`` verbs that create, start, stop or delete a host service
#: definition (a systemd unit, a launchd agent, a Task Scheduler task). The pod
#: CLI is how a test reaches a service manager without naming one, so a spawn of
#: ``kirocrew pod <verb>`` or ``python -m kiro_crew pod <verb>`` is refused for
#: every module not listed above. Read-only verbs (``ls``, ``status``, ``api``,
#: ``logs``) stay allowed.
_POD_MUTATING_VERBS = frozenset({"up", "down", "install", "prune", "restart"})


def _tokens(argv: object, *, shell: bool = False) -> list[str]:
    """Normalise every spawn-API argv shape into a list of string tokens.

    Accepts a string (shell form, or a lone program), a ``PathLike``, or a
    sequence of either. Anything uninterpretable yields no tokens: this guard
    refuses on a POSITIVE match only, so an exotic argv shape can never turn into
    a spurious failure in an unrelated suite.
    """
    if isinstance(argv, (str, bytes, os.PathLike)):
        raw = os.fsdecode(argv)
        return raw.split() if shell else [raw]
    if isinstance(argv, (list, tuple)):
        out = []
        for item in argv:
            if isinstance(item, (str, bytes, os.PathLike)):
                out.append(os.fsdecode(item))
        return out
    return []


def _basename(token: str) -> str:
    # PurePath handles both separators, so a Windows C:\...\sc.exe form and a
    # POSIX /usr/bin/systemctl normalise the same way.
    return pathlib.PurePath(token.replace("\\", "/")).name


def _refusal_reason(argv: object, *, shell: bool = False) -> str | None:
    """Describe why *argv* mutates host service state, or ``None`` if it does not.

    A service manager alone is not enough — the argv must also carry a mutating
    verb AFTER the manager token. Scanning only the tail keeps a unit named after
    a verb, or a wrapper flag, from being read as the action.
    """
    tokens = _tokens(argv, shell=shell)
    for index, token in enumerate(tokens):
        name = _basename(token)
        if name in _ALWAYS_REFUSED:
            return f"{name!r} rewrites host security policy"
        if name not in _SERVICE_MANAGERS:
            continue
        for candidate in tokens[index + 1 :]:
            # `schtasks` verbs are `/Create`-style switches: `_basename` would
            # strip the slash, so the raw token is compared lowercased as well.
            if _basename(candidate) in _MUTATING_VERBS or candidate.lower() in _MUTATING_VERBS:
                return f"{name} {candidate!r} changes host service state"
    pod_reason = _pod_cli_refusal(tokens)
    if pod_reason:
        return pod_reason
    return None


def _pod_cli_refusal(tokens: list[str]) -> str | None:
    """Name the ``kirocrew pod`` mutation in *tokens*, or ``None``.

    Matches the console script (``kirocrew``, ``kirocrew.exe``) and the module
    form (``python -m kiro_crew``), then requires the literal ``pod`` subcommand
    followed by a verb from :data:`_POD_MUTATING_VERBS`. Anything looser would
    refuse a test that merely passes ``"pod"`` as an argument to something else.
    """
    for index, token in enumerate(tokens):
        name = _basename(token)
        if name in {"kirocrew", "kirocrew.exe"}:
            rest = tokens[index + 1 :]
        elif token == "-m" and index + 1 < len(tokens) and tokens[index + 1] == "kiro_crew":
            rest = tokens[index + 2 :]
        else:
            continue
        if len(rest) >= 2 and rest[0] == "pod" and rest[1] in _POD_MUTATING_VERBS:
            return f"kirocrew pod {rest[1]!r} changes host service state"
        return None
    return None


def _refuse(reason: str, argv: object) -> None:
    """Fail the test with the stub it is missing, not just 'permission denied'."""
    raise AssertionError(
        f"Test tried to run a command that mutates host service state: {reason} "
        f"(see issue #1722).\n"
        f"  argv: {argv!r}\n"
        f"This spawn must be stubbed. Depending on the code under test:\n"
        f"  - dev_fleet make-live: stub BOTH `_run_cmd` and `_dropin_path`\n"
        f"  - kiro_crew.service.*: patch `service.<platform>.subprocess.run`\n"
        f"  - pod runtime: stub the runtime's `systemctl` / `launchctl` helper\n"
        f"Read-only queries (`systemctl show`, `cat`, `is-active`) are allowed and "
        f"need no stub.\n"
        f"If this test genuinely must drive a real service, add its module to "
        f"_HOST_SERVICE_EXEC_ALLOWED_MODULES in the root conftest.py with a "
        f"comment explaining why."
    )


@pytest.fixture(scope="session")
def _xdg_config_root(tmp_path_factory):
    """One tmp dir per session (per xdist worker) to stand in for ``~/.config``.

    Session-scoped so the redirect below costs one ``mkdir`` for the whole run
    rather than one per test: nothing here is written by a passing test — the
    point of the guard is that these writes should not happen at all — so a
    per-test directory would isolate nothing and add a syscall to every test.
    """
    return tmp_path_factory.mktemp("xdg")


@pytest.fixture
def _floor_monkeypatch():
    """The isolation floor's OWN ``MonkeyPatch`` -- never the shared ``monkeypatch``.

    Every floor fixture below patches through this instance instead of the
    ``monkeypatch`` fixture a test also receives. The two are undone
    independently, and that is the point: ``monkeypatch.undo()`` reverts EVERY
    record on the instance it is called on, so a test that called it mid-way to
    drop one of its own patches -- ~90 sites do, to restore a function before a
    final assertion -- also dropped the floor's ``KIROCREW_HOME`` pin, and
    whatever ran after that resolved the OPERATOR's real data home. Five full
    runs on a developer machine left ``~/.kiro/crew/trash/session-storage.lock``
    (``test_session_storage`` ran ``empty_trash()`` against the real trash) and
    ``~/.kiro/crew/inbound-spool/refused.jsonl.lock`` behind this way.

    A test that pins something itself still wins: its ``monkeypatch`` is set up
    after the floor and torn down before it, so its value overrides during the
    test and the floor's value is what gets put back first, then the original.
    """
    mp = pytest.MonkeyPatch()
    # In-process CLI calls clear the sandbox markers and publish the UTF-8
    # process contract. Preserve the worker's exact outer environment for the
    # next test, including absent and explicitly empty values.
    cli_process_environment = {
        name: os.environ.get(name)
        for name in (
            "KIROCREW_SANDBOX_ACTIVE",
            "KIROCREW_SANDBOX_LEVEL",
            "PYTHONUTF8",
            "PYTHONIOENCODING",
        )
    }
    try:
        yield mp
    finally:
        mp.undo()
        for name, value in cli_process_environment.items():
            if value is None:
                os.environ.pop(name, None)
            else:
                os.environ[name] = value


@pytest.fixture
def monkeypatch(_floor_monkeypatch):
    """pytest's own ``monkeypatch``, re-declared to order it AFTER the floor.

    Body-identical to ``_pytest.monkeypatch.monkeypatch``; the only change is the
    dependency on ``_floor_monkeypatch``, which is what GUARANTEES the order the
    docstring above relies on: the floor is set up before the test's ``monkeypatch``
    and torn down after it, whatever autouse fixture in whatever conftest happens to
    request ``monkeypatch`` first. A test's ``setenv("KIROCREW_HOME", ...)`` therefore
    records the pinned value, restores it on the test's undo, and the floor's undo then
    restores the operator's. A test cannot tell the difference otherwise: same type,
    same scope, same undo semantics for everything IT patched.
    ``test_host_isolation_floor.py::TestTheDataHomeIsPinnedForEveryTestpath`` pins it.
    """
    mp = pytest.MonkeyPatch()
    yield mp
    mp.undo()


@pytest.fixture(autouse=True)
def _isolate_xdg_config_home(_xdg_config_root, _floor_monkeypatch):
    """Point ``$XDG_CONFIG_HOME`` at a tmp dir so no test writes a real unit file.

    ``dev_fleet._dropin_path()`` resolves the make-live systemd drop-in as
    ``$XDG_CONFIG_HOME/systemd/user/kirocrew-gateway.service.d/make-live.conf``,
    falling back to ``~/.config`` when the variable is unset — which is the
    default on most developer machines and in CI. So a test that reaches the
    cutover path without stubbing ``_dropin_path`` writes the operator's real
    drop-in. That is what took the gateway down in #1722.

    Redirecting the variable fixes the whole class rather than one call site,
    because the production code already honours it (its docstring notes a literal
    ``~/.config`` would be the wrong directory on a host that sets XDG). It is
    also not dev-fleet-specific: ``pptx_maker/backend/paths.py`` resolves against
    the same variable, so its tests stop touching the real config dir too.

    A test that wants its own value still wins — it sets XDG later, and reverts
    independently.
    """
    monkeypatch = _floor_monkeypatch
    monkeypatch.setenv("XDG_CONFIG_HOME", str(_xdg_config_root))


@pytest.fixture(autouse=True)
def _isolate_launchd_paths(_xdg_config_root, _floor_monkeypatch):
    """Pin the launchd install paths, which ``$XDG_CONFIG_HOME`` cannot reach.

    The macOS half of Make Live does not resolve through XDG at all. Its paths are
    module globals bound at IMPORT time from ``Path.home()``::

        PLIST_DIR    = ~/Library/LaunchAgents
        PLIST_PATH   = PLIST_DIR / "dev.kirocrew.gateway.plist"
        LOG_DIR      = ~/Library/Logs/...        (+ STDOUT_LOG, STDERR_LOG)
        LIVE_PROGRAM = launchd_live_program()    (under ~/Library/Application Support)

    That is the same import-time-binding class the suite already documents (#874):
    an env var read *after* the module captured the path changes nothing, so the
    redirect above leaves the launchd side wide open.

    It is reachable today, not hypothetically. ``macos.install()`` calls
    ``write_live_program(render_live_program(kirocrew_bin()))`` with no path
    argument, so the launcher lands on the real ``LIVE_PROGRAM`` even in a test that
    carefully pinned every ``PLIST_*`` constant — which
    ``test_install_writes_plist_and_loads`` does. Raised in review of #1722.

    Every binding is patched rather than just the canonical one, because both
    consumers import by value: ``dev_fleet.gateway_service`` holds its own
    ``PLIST_PATH`` and its own ``launchd_live_program`` reference, and
    ``LaunchdBackend.live_program()`` calls that function fresh on each use instead
    of reading the constant.

    ``gateway_service`` is patched only when it is already imported. It is a heavy
    module and forcing it in for all ~31k tests would cost more than it protects; a
    test that imports it later binds from the already-patched ``service.macos``, so
    it inherits the tmp paths anyway.

    Tolerant by design: an unimportable module is skipped rather than failing
    collection, and every attribute uses ``raising=False`` so a renamed constant
    does not become a suite-wide error.
    """
    monkeypatch = _floor_monkeypatch
    root = pathlib.Path(_xdg_config_root) / "launchd"
    launcher = root / "live-gateway"
    plist_dir = root / "LaunchAgents"
    plist_path = plist_dir / "dev.kirocrew.gateway.plist"
    log_dir = root / "Logs"

    eager: dict[str, dict[str, object]] = {
        "kiro_crew.service.macos": {
            "PLIST_DIR": plist_dir,
            "PLIST_PATH": plist_path,
            "LOG_DIR": log_dir,
            "STDOUT_LOG": log_dir / "gateway.log",
            "STDERR_LOG": log_dir / "gateway.err",
            "LIVE_PROGRAM": launcher,
        },
        "kiro_crew.service.common": {"launchd_live_program": lambda: launcher},
    }
    lazy: dict[str, dict[str, object]] = {
        "kiro_crew.apps.builtins.dev_fleet.gateway_service": {
            "PLIST_PATH": plist_path,
            "launchd_live_program": lambda: launcher,
        },
    }

    for name, attrs in eager.items():
        try:
            imported = importlib.import_module(name)
        except Exception:  # pragma: no cover - a partial checkout must not break collection
            continue
        for attr, value in attrs.items():
            monkeypatch.setattr(imported, attr, value, raising=False)

    for name, attrs in lazy.items():
        already = sys.modules.get(name)
        if already is None:
            continue
        for attr, value in attrs.items():
            monkeypatch.setattr(already, attr, value, raising=False)


#: Originals of the sandbox-sweep functions the host-isolation floor patches,
#: stashed here (conftest-owned) rather than as attributes on the production
#: module. Tests reach them via the ``sandbox_sweep_original`` fixture — a
#: fixture rather than an importable name, because ``import conftest`` from a
#: test resolves to ``test/conftest.py``, not this rootdir file.
_SANDBOX_SWEEP_ORIGINALS: dict = {}


@pytest.fixture()
def sandbox_sweep_original():
    """Accessor for the pre-patch sandbox-sweep functions stashed by the floor."""
    return _SANDBOX_SWEEP_ORIGINALS.__getitem__


@pytest.fixture(scope="session")
def _sandbox_mount_source_root(tmp_path_factory):
    """An empty stand-in tmpfs root for the sandbox mount-source sweep.

    Session-scoped and owned by no individual test, because nothing ever writes
    into it -- it exists only so the sweep has a harmless directory to scan.
    """
    return tmp_path_factory.mktemp("sb-mount-src")


@pytest.fixture(autouse=True)
def _isolate_sandbox_mount_source_roots(_sandbox_mount_source_root, _floor_monkeypatch):
    """Point the sandbox mount-source sweep away from the host's real tmpfs.

    ``sandbox._cleanup_stale_sandbox_mount_sources()`` -- reached from every
    ``cleanup_stale_sandbox_profiles()`` call, including the periodic sweep in
    ``session.py`` -- resolves its candidate roots from the REAL host:
    ``/run/user/$UID``, ``/dev/shm``, and the system tempdir. The tempdir is
    already redirected by the floor above, but the first two are the operator's
    live runtime tmpfs, so an unpinned test would (a) delete real orphaned
    bind-mount sources from the developer's machine -- a host mutation, however
    garbage-shaped -- and (b) have its removal COUNT inflated by whatever real
    orphans the host happens to carry, turning exact-count assertions into
    host-state-dependent flakes.

    A test that wants the sweep's real behaviour passes ``roots=`` explicitly or
    monkeypatches ``_mount_source_candidate_roots`` itself (a later patch wins
    and reverts independently); the real function stays reachable through this
    conftest's ``sandbox_sweep_original`` accessor so its resolution logic
    remains testable without mutating the production module.

    Eagerly imported -- ``sandbox`` is a low-level dependency most of the suite
    already pulls in, so this costs nothing and a lazy patch would leave the
    first importer unprotected -- but tolerant of a partial checkout: an
    unimportable module is skipped rather than failing collection. The setattr
    itself is STRICT: a silent miss on a renamed attribute would revert the
    whole suite to sweeping the operator's real tmpfs, which is exactly what
    this fixture exists to prevent.
    """
    monkeypatch = _floor_monkeypatch
    try:
        sandbox_mod = importlib.import_module("kiro_crew.sandbox")
    except Exception:  # pragma: no cover - a partial checkout must not break collection
        return
    _SANDBOX_SWEEP_ORIGINALS.setdefault(
        "_mount_source_candidate_roots", sandbox_mod._mount_source_candidate_roots
    )
    monkeypatch.setattr(
        sandbox_mod,
        "_mount_source_candidate_roots",
        lambda: [str(_sandbox_mount_source_root)],
    )
    # Second half of the same floor: the pin scan reads the operator's real
    # /proc. Default it to fail-closed (nothing pinned, coverage unproven) so
    # a test that forgets to fix the scan's answer is INERT -- the sweep then
    # refuses to remove directories -- instead of silently depending on host
    # /proc state. A test fixes the answer by monkeypatching
    # ``_mount_pinned_source_names`` itself; ``TestMountPinnedSourceNames``
    # imports the function by name at module import, so the parser's own unit
    # tests are unaffected by this module-attribute patch.
    _SANDBOX_SWEEP_ORIGINALS.setdefault(
        "_mount_pinned_source_names", sandbox_mod._mount_pinned_source_names
    )
    monkeypatch.setattr(
        sandbox_mod,
        "_mount_pinned_source_names",
        lambda proc_root="/proc", **_kw: (set(), False),
    )
    # Third half, same floor, for the LEGACY (pre-prefix ``tmp*``) sweep. It
    # resolves its own narrower root chain -- the launcher's two tmpfs roots,
    # deliberately excluding the redirected system tempdir -- so without this it
    # would scan the developer's real /run/user/$UID and /dev/shm, and there it
    # matches names no Kiro Crew build has created since #6268: an unpinned test
    # could delete a stranger's temp entry on the host. The bind scan is
    # defaulted fail-closed for the same reason as the pin scan above: a test
    # that forgets to fix its answer gets an INERT sweep (coverage unproven ->
    # removes nothing, stamps nothing) rather than one reading host /proc.
    _SANDBOX_SWEEP_ORIGINALS.setdefault("_launcher_tmpfs_roots", sandbox_mod._launcher_tmpfs_roots)
    monkeypatch.setattr(
        sandbox_mod,
        "_launcher_tmpfs_roots",
        lambda: [str(_sandbox_mount_source_root)],
    )
    _SANDBOX_SWEEP_ORIGINALS.setdefault(
        "_bound_source_basenames", sandbox_mod._bound_source_basenames
    )

    def _unproven_bound_sources(proc_root="/proc", *, coverage=None, **_kw):
        # Fail closed on BOTH claims the legacy gate accepts, so no test can
        # reach the developer's real runtime tmpfs through it.
        if coverage is not None:
            coverage.covered = False
        return (set(), False)

    monkeypatch.setattr(sandbox_mod, "_bound_source_basenames", _unproven_bound_sources)


@pytest.fixture(autouse=True)
def _pin_kill_and_reap_group_probe(_floor_monkeypatch):
    """Stop ``kill_and_reap``'s group-kill skip from reading host process state.

    ``platform_compat.kill_and_reap()`` skips the process-GROUP kill when the
    child shares the gateway's own group (spawned without
    ``start_new_session``, so it leads no tree of its own). That decision is a
    live ``os.getpgid()`` probe -- and almost every test of this path hands it a
    SYNTHETIC pid (4242 is the shared convention) with the tree kill mocked. The
    probe then resolves that fake pid against the runner's REAL process table:
    when some genuine process happens to own it AND sits in the pytest run's own
    process group, the skip fires, no tree kill is recorded, and the assertion
    fails. Under xdist the runner spawns plenty of low-pid children in exactly
    that group, which is why this flaked in batches -- four tests across three
    files in one run -- and passed on re-run.

    The pin is the child-leads-its-own-group answer, i.e. tree kill attempted,
    which is what every one of those tests is written to assert. It is safe as a
    floor because the skip is an optimisation, not a safety guard: it exists so
    a routine timeout does not trip :func:`kill_process_tree`'s broadcast
    refusal on every same-group child. That refusal is the actual protection and
    is untouched here, so even a real same-group child reached through this
    fixture is refused a group signal and falls through to the pid-scoped kill.
    Pinning the shared ``_OWN_PGID`` instead WOULD disarm that refusal, which is
    why the seam is this one function.

    A test that wants the skip patches ``_shares_own_process_group`` itself -- a
    later patch wins and reverts independently (see
    ``TestKillAndReap::test_skips_the_group_kill_for_a_same_group_child``).
    Tolerant of a partial checkout, and STRICT on the attribute: a silent miss
    on a rename would quietly restore the flake this exists to remove.
    """
    monkeypatch = _floor_monkeypatch
    try:
        platform_compat = importlib.import_module("kiro_crew.platform_compat")
    except Exception:  # pragma: no cover - a partial checkout must not break collection
        return
    monkeypatch.setattr(platform_compat, "_shares_own_process_group", lambda _pid: False)


@pytest.fixture(autouse=True)
def _no_credential_env_residue():
    """Restore the credential env vars a test may have had INJECTED into it.

    ``KiroCrewConfig.load_credentials()`` deliberately propagates every credential
    it reads into ``os.environ`` with ``setdefault``, so a spawned child (sandboxed
    agent, MCP server, cron subprocess) inherits it through ``Popen``'s default
    ``env=os.environ.copy()``. Any test that points ``env_path()`` at a fabricated
    ``.env`` therefore leaves those fake credentials in the WORKER's environment,
    for every test that follows it.

    The usual guard does not catch this, which is what makes it worth a floor:
    ``monkeypatch.delenv(KEY, raising=False)`` on a key that is ABSENT records
    nothing to undo, so a value written during the test is restored to nothing.

    And the residue is not inert -- ``load_credentials`` lets ``os.environ`` WIN
    over the file it just read, so the next test pointing at a different ``.env``
    is answered with the previous test's token. Observed between
    ``test_handlers_messaging_coverage.py`` and ``test_review_fixes.py``: a Slack
    token from one file's temp ``.env`` silently satisfied the other's assertion,
    and only when both landed in the same worker.

    Bounded to the recognised fixed keys and the validated ``JIRA_TOKEN_<HEX>``
    shape. Two linear environment scans per test also catch a dynamic key that
    did not exist at setup, without masking an unrelated environment change.
    """
    from kiro_crew.config.loader import _JIRA_TOKEN_RE, CREDENTIAL_KEYS

    fixed = frozenset(CREDENTIAL_KEYS)

    def _is_credential(key: str) -> bool:
        return key in fixed or _JIRA_TOKEN_RE.match(key) is not None

    before = {key: value for key, value in os.environ.items() if _is_credential(key)}
    try:
        yield
    finally:
        current = {key for key in os.environ if _is_credential(key)}
        for key in current | before.keys():
            if key not in before:
                os.environ.pop(key, None)
            else:
                os.environ[key] = before[key]


@pytest.fixture(autouse=True)
def _scrub_inherited_preload_env(_floor_monkeypatch):
    """Hide the entries ``name_grant`` refuses as inherited preloads, then restore them.

    RHEL-family distributions (Amazon Linux 2023, RHEL, CentOS Stream, Fedora) ship
    ``/etc/profile.d/which2.sh``, which exports ``which`` as a shell function -- so
    ``BASH_FUNC_which%%`` sits in ``os.environ`` of any login shell before pytest even
    starts. ``name_grant._inherited_preload()`` fires its AMBIGUOUS_ENV refusal on
    exactly that shape, and that refusal is checked before every narrower code, so on
    such a host 79 of the 163 tests in ``test/test_name_grant.py`` observed
    ``inherited_env_can_redefine_programs`` instead of the code they assert, while
    Ubuntu CI (no ``which2.sh``) stayed green (issue #8395). The detector's OTHER half
    is host state just as easily: a login profile exporting ``BASH_ENV``, or a
    container image setting ``ENV``, reproduces the same failure shape with no
    ``which2.sh`` anywhere. The PRODUCT behaviour is correct -- an inherited preload
    genuinely can redefine a program the agent runs -- the gap was that this floor
    pins the data home, the credential env and the temp base, but not the environment
    the run inherited.

    The predicate is IMPORTED from ``name_grant`` rather than restated, so the scrub
    and the detector cannot drift apart, and it mirrors BOTH halves the detector
    checks: the ``_ENV_PRELOAD_VARS`` names (matched truthy, exactly as the detector's
    ``os.environ.get(var)`` reads them -- an empty value triggers no refusal and is
    left alone), and the exported-function pair (the ``BASH_FUNC_`` key prefix, plus
    the legacy bare-name spelling whose value starts with ``() {``). It is also
    deliberately no WIDER than that predicate: this is not a general "no exported
    functions" floor -- how wide the detector should be is ``name_grant``'s design
    question, and the scrub merely mirrors its answer. The import is deliberately
    UNGUARDED, like ``_no_credential_env_residue``'s: an ImportError escape hatch
    would disarm the scrub silently on a broken checkout and hand back the exact
    79-failure pattern this fixture exists to remove, as a wall of wrong refusal
    codes instead of one clear error.

    The removals use the private host-floor stack. A shared ``monkeypatch.undo()``
    cannot restore an inherited preload during the test. The public ``monkeypatch``
    fixture depends on ``_floor_monkeypatch``, so its stack unwinds first at teardown:
    an override of the SAME inherited key first reverts to "absent", and only then
    does this fixture's ``delenv`` record restore the inherited value. Reversing
    those steps would delete the restored host value and leak the scrub into the
    next test. ``test_name_grant.py::TestInheritedHostEnvironment``
    pins exactly that same-key case, and
    ``test_host_isolation_floor.py::TestInheritedShellEnvironmentIsScrubbed`` drives
    one real cycle of this fixture directly.

    The deliberate AMBIGUOUS_ENV tests lose nothing: they construct their entries
    inside the test body, after the scrub. The teardown sweep below is the
    ``_no_credential_env_residue`` half of the contract: a matching entry still
    present at teardown is either a raw ``os.environ`` write (no undo record --
    swept here, stays gone) or a monkeypatch-managed one (its undo re-deletes
    tolerantly or restores what it recorded), so nothing this fixture scrubbed and
    nothing a test leaked survives past the test on this worker.
    """
    monkeypatch = _floor_monkeypatch
    from kiro_crew.name_grant import (
        _BASH_FUNC_KEY_PREFIX,
        _BASH_FUNC_VALUE_PREFIX,
        _ENV_PRELOAD_VARS,
    )

    def _is_inherited_preload(key: str, value: str) -> bool:
        if key in _ENV_PRELOAD_VARS:
            return bool(value)
        return key.startswith(_BASH_FUNC_KEY_PREFIX) or value.startswith(_BASH_FUNC_VALUE_PREFIX)

    for key in [k for k, v in os.environ.items() if _is_inherited_preload(k, v)]:
        monkeypatch.delenv(key)
    try:
        yield
    finally:
        for key in [k for k, v in os.environ.items() if _is_inherited_preload(k, v)]:
            os.environ.pop(key, None)


@pytest.fixture(autouse=True)
def _block_host_service_mutation(request, _floor_monkeypatch):
    """Fail loudly if a test really starts, stops, or reconfigures a service.

    Redirecting ``$XDG_CONFIG_HOME`` above stops a test from *writing* a real
    unit file, but not from *running* ``systemctl --user daemon-reload`` or
    ``systemctl --user restart kirocrew-gateway.service``. Those restart the
    developer's live gateway even when the drop-in they read is pristine, so the
    second half of the floor has to be an execution guard.

    Patched at the deepest stdlib funnels rather than at the names call sites
    happen to use, so the guard cannot be bypassed by import style:

    * ``subprocess.Popen.__init__`` — every sync spawn funnels here, including
      ``run``, ``check_call`` and ``check_output``, and including a module that
      did ``from subprocess import run`` (that ``run`` still resolves ``Popen``
      through its own module globals).
    * ``BaseEventLoop.subprocess_exec`` / ``subprocess_shell`` — every
      ``asyncio.create_subprocess_*`` funnels here, so patching these also covers
      ``from asyncio import create_subprocess_exec``.
    * ``os.execve`` — ``live_target.maybe_reexec()`` execs into another checkout,
      which would REPLACE the pytest process with a real gateway. Guarded
      unconditionally: no argv inspection makes that sane in a test.

      ``os.execv`` is deliberately NOT guarded. The two exec paths in this
      codebase use different funnels, and the difference is load-bearing:
      ``maybe_reexec`` needs ``execve`` because it hands the gateway a modified
      environment across the exec, while ``spawn/exec_shim`` uses ``execv``
      precisely because it passes its inherited environment through untouched
      ("execv, not execve: the environment this process was given IS the
      environment the caller built"). The shim's exec also happens in a CHILD
      process (it is spawned as ``python -c <shim source>``), so trapping
      ``execv`` here protects nothing and only breaks the shim's in-process unit
      tests of its own 127-on-exec-failure contract.
      ``test_host_service_guard.py`` ratchets the assumption that
      ``live_target`` still execs through ``execve``.

    The mechanism follows ``test/test_update_git_guard.py``, which already
    monkeypatches ``create_subprocess_exec`` to raise on an unwanted spawn. The
    difference is scope: this one is autouse, so it holds for tests nobody
    thought to write a guard for.

    Everything else is delegated to the real implementation untouched — which
    matters more than it sounds, because ``sandbox`` wraps nearly every spawn in
    this codebase in ``systemd-run --scope`` for cgroup limits. A guard keyed on
    binaries rather than verbs refused ``git config``.
    """
    monkeypatch = _floor_monkeypatch
    if request.module is not None and request.module.__name__ in _HOST_SERVICE_EXEC_ALLOWED_MODULES:
        return

    real_popen_init = subprocess.Popen.__init__
    real_exec = asyncio.base_events.BaseEventLoop.subprocess_exec
    real_shell = asyncio.base_events.BaseEventLoop.subprocess_shell

    def guarded_popen_init(self, args=(), *rest, **kwargs):
        reason = _refusal_reason(args, shell=bool(kwargs.get("shell")))
        if reason:
            _refuse(reason, args)
        return real_popen_init(self, args, *rest, **kwargs)

    def guarded_subprocess_exec(self, protocol_factory, program=None, *args, **kwargs):
        argv = [program, *args]
        reason = _refusal_reason(argv)
        if reason:
            _refuse(reason, argv)
        return real_exec(self, protocol_factory, program, *args, **kwargs)

    def guarded_subprocess_shell(self, protocol_factory, cmd=None, **kwargs):
        reason = _refusal_reason(cmd, shell=True)
        if reason:
            _refuse(reason, cmd)
        return real_shell(self, protocol_factory, cmd, **kwargs)

    def guarded_exec(*argv, **kwargs):
        raise AssertionError(
            "Test called os.execve, which would REPLACE the pytest process with "
            f"another checkout's gateway (see issue #1722). argv: {argv!r}\n"
            "Stub the re-exec seam instead (e.g. live_target.maybe_reexec)."
        )

    monkeypatch.setattr(subprocess.Popen, "__init__", guarded_popen_init)
    monkeypatch.setattr(
        asyncio.base_events.BaseEventLoop, "subprocess_exec", guarded_subprocess_exec
    )
    monkeypatch.setattr(
        asyncio.base_events.BaseEventLoop, "subprocess_shell", guarded_subprocess_shell
    )
    monkeypatch.setattr(os, "execve", guarded_exec)


# ── no systemd user session for the test process tree ─────────────────


#: The session-bus locators the operator's shell carried, captured before the floor
#: removes them. ``real_user_session`` hands exactly these back to the one test that
#: needs the real user manager.
_REAL_USER_SESSION_ENV_AT_START: dict[str, str] = {
    name: os.environ[name]
    for name in ("XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS")
    if name in os.environ
}


def _reset_cgroup_scope_probe() -> None:
    """Drop ``sandbox``'s memoised cgroup-scope probe so the next call re-reads the env."""
    sb = sys.modules.get("kiro_crew.sandbox")
    if sb is not None:
        sb._CGROUP_SCOPE_PROBE = None


@pytest.fixture(autouse=True, scope="session")
def _no_systemd_user_session():
    """Run the whole session, children included, without a systemd user session.

    ``sandbox.cgroup_scope_argv`` wraps a spawn in ``systemd-run --user --scope
    --slice=kirocrew-agents-<token>.slice`` whenever its probe finds a user session,
    and the token is a hash of the data home. This floor pins a FRESH ``KIROCREW_HOME``
    per test, so on a developer host every test that reaches the wrapper -- and every
    ``kirocrew`` CLI child a test spawns, which probes for itself -- creates a NEW
    transient slice, and systemd never garbage-collects a slice: five full runs left
    over 4,000 ``kirocrew-agents-*.slice`` units loaded in the operator's user manager.
    The same session bus is what let a late reconcile thread run a real
    ``systemctl --user set-property`` on the operator's agents slice after its test's
    monkeypatch was undone.

    The probe's own documented gate is ``XDG_RUNTIME_DIR`` ("no systemd user
    session"), so removing the bus locators for the session is the whole fix: it
    reaches children through the inherited environment, it cannot be outrun by a
    thread, and it matches CI, where the runner has no user session either. The
    host-service guard above cannot do this job -- it sees in-process spawns only.

    A test that needs the real user manager opts in with :func:`real_user_session`.
    """
    for name in _REAL_USER_SESSION_ENV_AT_START:
        os.environ.pop(name, None)
    _reset_cgroup_scope_probe()
    try:
        yield
    finally:
        os.environ.update(_REAL_USER_SESSION_ENV_AT_START)
        _reset_cgroup_scope_probe()


@pytest.fixture
def real_user_session(monkeypatch):
    """Opt ONE test back into the operator's real systemd user session.

    Skips where the operator has none. On teardown the per-instance agents slice the
    test's pinned data home maps to is stopped, because systemd would otherwise keep
    it loaded forever (see :func:`_no_systemd_user_session`). That stop is issued
    through ``os.posix_spawn`` on purpose: it is cleanup of a unit this very test
    created, and the host-service guard's ``Popen`` funnel would refuse the verb.
    """
    if "XDG_RUNTIME_DIR" not in _REAL_USER_SESSION_ENV_AT_START:
        pytest.skip("no systemd user session on this host")
    for name, value in _REAL_USER_SESSION_ENV_AT_START.items():
        monkeypatch.setenv(name, value)
    import kiro_crew.sandbox as sb

    monkeypatch.setattr(sb, "_CGROUP_SCOPE_PROBE", None)
    try:
        yield
    finally:
        slice_name = sb._agents_slice_name()
        systemctl = shutil.which("systemctl")
        if systemctl and slice_name != sb._CGROUP_AGENTS_SLICE:
            pid = os.posix_spawn(
                systemctl, [systemctl, "--user", "stop", "-q", slice_name], os.environ
            )
            os.waitpid(pid, 0)
        sb._CGROUP_SCOPE_PROBE = None


# ── the process working directory is shared state too ─────────────────


#: The working directory pytest started in, captured once. Restoring to THIS rather than
#: to a per-test snapshot is both simpler and more correct: it is the only value that is
#: certain to still exist, and it is where every test expects to begin.
_SESSION_CWD: str | None = None

#: Tests between ``linecache`` clears. Measured on a 1,266-test slice: 500 saves
#: 22.8 MiB and 100 saves 28.0 MiB, with no measurable difference in wall time, so the
#: CPU side of this trade is flat enough to take the memory. The cache is per-process,
#: so under ``-n auto`` each worker clears on its own count.
_LINECACHE_CLEAR_EVERY = 100
_TESTS_SINCE_LINECACHE_CLEAR = 0

#: How many objects ``pytest_collection_finish`` moved into the permanent generation.
#: ``None`` until it has run, which is what distinguishes "this hook did its job" from
#: the few hundred objects the interpreter had already frozen on its own.
_FROZEN_AT_COLLECTION: int | None = None


#: A short, path-shaped temp prefix for Darwin. macOS resolves the per-user temp dir to
#: ``/var/folders/<2 chars>/<30 random chars>/T``, which is both LONG and free of any
#: character outside ``[A-Za-z0-9/]`` -- and two limits the suite has nothing to do with
#: fall straight out of that:
#:
#: * ``sun_path`` for an AF_UNIX socket is 104 bytes on Darwin (108 on Linux), so a
#:   socket under a pytest temp dir cannot be bound at all: ``OSError: AF_UNIX path too
#:   long`` is raised before the behaviour under test runs.
#: * ``security._BARE_SECRET_RUN_RE`` matches a >=40-character run of ``[A-Za-z0-9+/]``,
#:   and ``/`` is IN that class, so a temp path is ONE contiguous run. The 30-character
#:   random segment carries that run over the 4.3-bits/char entropy floor whose whole
#:   job is to keep file paths out, so any temp path echoed through a redactor comes
#:   back ``[REDACTED: credential]`` and the assertion sees a mangled path.
#:
#: Both are properties of the HOST's temp prefix rather than of the code under test:
#: these same tests pass on Linux and in CI, where ``gettempdir()`` is ``/tmp``. Giving
#: macOS the prefix Linux already has is the smallest change that removes both, and it
#: removes them for every test at once instead of teaching each one about a platform
#: limit it is not about.
#:
#: The posture does not change. ``/tmp`` is world-writable with a sticky bit on Linux
#: too, pytest still builds its per-user ``pytest-of-<user>`` tree inside it, and this
#: file's own temp root is still ``mkdtemp``-created with O_EXCL and mode 0700 -- see
#: :func:`_create_tmp_root` for why that is what makes a shared parent safe.
_SHORT_TMP_BASE = "/tmp"


def _prefer_short_tmp_base() -> None:
    """Point this run's temp base at :data:`_SHORT_TMP_BASE` on Darwin.

    Called from ``pytest_configure``, which is early enough: pytest resolves its
    ``basetemp`` lazily from ``tempfile.gettempdir()`` on the first ``mktemp`` /
    ``getbasetemp()``, and that cannot happen before a fixture runs. Both the module
    global and the env vars are set, because ``gettempdir()`` MEMOISES into
    ``tempfile.tempdir`` and a spawned child reads the env instead.
    """
    if sys.platform != "darwin" or not os.path.isdir(_SHORT_TMP_BASE):
        return
    tempfile.tempdir = _SHORT_TMP_BASE
    for name in _TMP_ENV_VARS:
        os.environ[name] = _SHORT_TMP_BASE


#: Module nodeids whose COLLECTION built the process-global metrics recorder.
#:
#: Filled by :func:`pytest_make_collect_report`, asserted empty by
#: ``test_host_isolation_floor.py::TestNoMetricIsEmittedAtImport``. A metric emitted
#: while a test module is being imported (a default argument evaluated at
#: definition time, a module constant built through a factory that counts itself)
#: runs ``get_recorder()`` before any test's pins exist. The recorder's first build
#: reads the OPERATOR's real config; with ``telemetry.enabled`` there, it starts a
#: ``PeriodicExportingMetricReader`` whose exporter is bound to the real
#: ``~/.kiro/crew/metrics`` and which exports every minute for the life of the xdist
#: worker. The per-test exporter-leak guard cannot see it (the thread predates every
#: test), and the per-test ``KIROCREW_TELEMETRY=0`` pin cannot reach it (it is already
#: built). The third full-run audit found four worker pids writing the operator's
#: metrics dir on every run from exactly one such default argument.
IMPORT_TIME_METRIC_EMITTERS: list[str] = []


def _metrics_provider_module():
    return sys.modules.get("kiro_crew.metrics.provider")


def _pin_telemetry_off_for_the_process() -> None:
    """``KIROCREW_TELEMETRY=0`` from process start, not just from each test's setup.

    The per-test pin (``_no_model_download``) covers the test body; this covers the
    stretch BEFORE the first test (conftest imports and the collection of every
    module), which is where an import-time metric emission builds the recorder. With
    the env pin in force the build is a no-op recorder that reads no config and starts
    no thread, so even an emitter this guard has not yet named cannot reach the host.
    Tests that exercise telemetry delete the variable themselves, as they already did.
    """
    os.environ["KIROCREW_TELEMETRY"] = "0"


@pytest.hookimpl(hookwrapper=True)
def pytest_make_collect_report(collector):
    """Name the module whose import built the metrics recorder, and undo it.

    The detection is ``metrics.provider._ever_built`` flipping across one module's
    collection: the flag is set by every build, including the no-op one the env pin
    above turns it into, so an emitter is caught whether or not it reached the host.
    ``reset_for_testing()`` then drops what was built (stopping an exporter thread if
    one exists), so the next module starts clean and the attribution stays per-module.
    Fail the collection report on the detecting worker: file shards do not all
    collect the test that asserts the record, and xdist forwards collection errors
    to the controller even when that worker executes no tests.
    """
    provider = _metrics_provider_module()
    built_before = bool(provider is not None and getattr(provider, "_ever_built", False))
    outcome = yield
    if not isinstance(collector, pytest.Module):
        return
    provider = _metrics_provider_module()
    if provider is None or not getattr(provider, "_ever_built", False):
        return
    if built_before:
        # Built before this module was reached, by a conftest import. Named as such
        # rather than blamed on whichever module happened to be first.
        IMPORT_TIME_METRIC_EMITTERS.append(f"conftest import (before {collector.nodeid})")
    else:
        IMPORT_TIME_METRIC_EMITTERS.append(collector.nodeid)
    with contextlib.suppress(Exception):
        provider.reset_for_testing()
    report = outcome.get_result()
    if not report.failed:
        report.outcome = "failed"
        report.longrepr = (
            f"Import-time metric emission: {IMPORT_TIME_METRIC_EMITTERS[-1]}. "
            "Build the value inside the test or fixture instead."
        )


def _pin_crew_log_off_for_the_process() -> None:
    """``KIROCREW_CREW_LOG=0`` for the whole run, so a test opts IN to the crew log.

    The gateway records a crew log by default. A test that drives the chat path for
    some other reason would otherwise write one into its data home, and the logs
    this suite asserts on would pick up entries from code the test never meant to
    exercise. Every crew-log test sets the variable itself: ``"1"`` to record,
    ``"0"`` to assert the off path, and ``monkeypatch.delenv`` to assert the default.
    """
    os.environ["KIROCREW_CREW_LOG"] = "0"


def pytest_configure(config: pytest.Config) -> None:
    """Record the working directory pytest started in, before any test can move it."""
    _refuse_a_real_data_home()
    _pin_telemetry_off_for_the_process()
    _pin_crew_log_off_for_the_process()
    _prefer_short_tmp_base()
    _install_short_tmp_root()
    _redirect_hypothesis_database()
    _redirect_bytecode_cache()
    _gate_pytest_asyncio_fixture_scan()
    global _SESSION_CWD
    try:
        _SESSION_CWD = os.getcwd()
    except OSError:  # pragma: no cover - pytest could not have started here
        _SESSION_CWD = str(_REPO_ROOT)


@pytest.hookimpl(trylast=True)
def pytest_warning_recorded(warning_message, when, nodeid, location) -> None:
    """Drop a recorded warning's ``source`` object once the warning has been rendered.

    Every warning this suite emits is retained for the whole session, and one kind of
    warning brings a whole test's object graph with it.

    The chain: ``_pytest/warnings.py`` records each warning with
    ``pytest_warning_recorded.call_historic(...)``, and pluggy appends those kwargs to
    ``_HookCaller._call_history`` -- a list it never clears, because a historic hook
    exists precisely to be replayed to plugins registered later. So the
    ``warnings.WarningMessage`` survives to the end of the run. Ordinarily that is a
    few hundred bytes. But ``WarningMessage.source`` is the OBJECT the warning is
    about, and for ``RuntimeWarning: coroutine '...' was never awaited`` that object is
    the coroutine: it holds its frame, its frame holds every local, and those locals
    hold whatever the test built. One un-awaited coroutine therefore pins an entire
    test's graph for the session, in every worker.

    ``trylast`` is what makes this free of diagnostic loss, and it is not a
    preference. ``TerminalReporter.pytest_warning_recorded`` renders the warning to a
    plain string IMMEDIATELY -- including ``tracemalloc_message(source)``, the
    "Object allocated at:" traceback when tracemalloc is tracing and the "Enable
    tracemalloc" hint when it is not -- and stores that string. Running last means the
    text is already built before the reference goes, so nothing a reader would have
    seen is lost. Clearing it ``tryfirst`` WOULD lose that suffix, which is why the
    ordering is pinned by a test.

    Kept as a BACKSTOP rather than for its average saving, and the distinction is
    measured. Where un-awaited coroutines cluster it is large: ``test_dashboard_chat.py``
    emits 60 of them across 590 tests, and clearing ``source`` takes that file from 284
    to 219 MiB. On a mixed slice it is worth nothing at all -- an AsyncMock-dense
    3,401-test set emits 11 and measures +1.7 MiB, i.e. noise. So this is not a
    general-purpose win; it removes a tail risk whose cost is one attribute write per
    warning, and which scales with however many un-awaited coroutines the suite acquires
    later.

    The residual edge: a plugin registered AFTER a warning was recorded receives the
    replay with ``source`` already gone. Conftest plugins are all registered before
    tests run, so in this repo that is unreachable.
    """
    warning_message.source = None


def pytest_collection_finish(session: pytest.Session) -> None:
    """Move the collected item tree out of the garbage collector's reach.

    Collecting every testpath leaves roughly three million objects alive, and they
    are alive for the rest of the run by design -- the item tree, its fixture closures,
    the rewritten assertion code. The garbage collector does not know that, so every
    full pass walks all of them looking for cycles it will never find. Worse, on the
    interpreters this suite supports the full collection is scheduled from a measure of
    how much long-lived material exists, so that static population also DELAYS
    collection: a test's own cyclic garbage waits longer before anything reclaims it.
    (The exact scheduling differs across 3.10-3.13 -- 3.13 replaced the generational
    threshold with an incremental collector -- but the static set is unscanned either
    way, which is the part this depends on.)

    ``gc.freeze()`` moves everything currently tracked into a permanent generation that
    is never scanned. Measured over 3,798 test executions: full passes went 1 -> 3 and
    the objects they reclaimed went 61,604 -> 423,380, a 6.9x improvement in how much
    cyclic garbage is actually collected during a run.

    The end-RSS effect is small on its own (-3.5 MiB) because freed memory stays in the
    allocator's arena rather than returning to the OS. What it buys is that the garbage
    is reclaimed at all, which is why it is worth keeping despite the modest number.

    Placed at collection finish, not at configure: before collection there is nothing
    worth freezing, and after the first test the population is no longer purely static.
    Freezing is safe here for the same reason it helps -- these objects were going to
    live for the whole session anyway. Verified rather than assumed: live tracked objects
    at session end are slightly FEWER with the freeze than without (3,221,373 vs
    3,235,522), uncollectable stays 0, and the frozen count itself falls during the run,
    so refcount reclamation still works inside the permanent generation. Only cyclic
    garbage created BEFORE the freeze could leak, and collection creates none.

    It also helps the sandbox's ``fork``-based probes rather than hurting them: this is
    the documented pre-fork optimization, and the 16 sandbox suites pass identically
    with and without it.

    Records the delta rather than leaving the effect to be inferred from
    ``gc.get_freeze_count()``: the interpreter already has a few hundred objects frozen
    before this runs, so a bare "is anything frozen" assertion passes with this hook
    deleted.
    """
    global _FROZEN_AT_COLLECTION
    gc.collect()
    before = gc.get_freeze_count()
    gc.freeze()
    _FROZEN_AT_COLLECTION = gc.get_freeze_count() - before


def pytest_runtest_logfinish(nodeid: str, location) -> None:
    """Periodically drop ``linecache``'s copy of every source file that was read.

    ``linecache`` keeps the full TEXT of every file it is asked for, and nothing evicts
    it, so a worker accumulates source it will not look at again. Measured on a
    1,266-test slice: 90 files / 0.8 MiB after collection, growing to 170 files /
    11.4 MiB by the end of the run, and the ceiling is the 27.7 MiB of text in ``src``.

    The fillers are ``inspect.getsource`` (used by 128 test modules) and traceback
    rendering, one module at a time -- NOT the source-scanning guard tests, which read
    with ``Path.read_text()`` and add no linecache entries at all. The biggest single
    entries are simply the biggest modules (``dashboard/chat_runner.py`` at 408 KiB,
    ``slack/gateway.py`` at 388 KiB).

    This is the one of the three retention guards that pays on an ORDINARY slice rather
    than on a particular file, and it grows with the run: measured over 12,660 test
    executions, end RSS 1025 -> 924 MiB (-101 MiB, -10%), with the repeat-visit slope
    falling from 19.6 to 12.4 MiB per 1,000 tests.

    ``logfinish`` rather than teardown for tidiness, not safety: a failure report is
    unaffected either way. ``report.longrepr`` is a string already rendered at
    ``pytest_runtest_makereport``, and ``inspect.findsource`` calls
    ``linecache.checkcache()`` before ``getlines``, so a cleared or stale entry is
    simply re-read. Verified by running a two-failure file with no clearing, clearing at
    teardown, and clearing here: the ``FAILURES`` sections are byte-identical.

    Every N tests rather than every test because the cache is also what makes the next
    traceback cheap. The interval is a memory/CPU trade with a very flat CPU side --
    clearing 5x more often buys another ~5 MiB at no measurable time cost.
    """
    global _TESTS_SINCE_LINECACHE_CLEAR
    _TESTS_SINCE_LINECACHE_CLEAR += 1
    if _TESTS_SINCE_LINECACHE_CLEAR >= _LINECACHE_CLEAR_EVERY:
        _TESTS_SINCE_LINECACHE_CLEAR = 0
        linecache.clearcache()


def pytest_xdist_auto_num_workers(config: pytest.Config) -> int | None:
    """Budget ``-n auto`` by memory and by what other runs on this host hold.

    Registered HERE, at the rootdir, because a budget that only covers ``test/``
    is absent from ``transfer`` and from the in-package app suites -- and absent
    reads exactly like "decided not to clamp", so the gap is silent. Over-spawning
    workers takes the whole machine down, which makes this a host-protection
    concern and puts it on the same floor as the rest of them.

    The policy lives in :mod:`xdist_budget`; this is only the registration.
    Imported in-body to keep this file's module-level imports stdlib + pytest, and
    returning ``None`` on an ImportError hands the decision back to xdist's own
    default rather than breaking startup on a partial checkout.
    """
    try:
        import xdist_budget
    except ImportError:  # pragma: no cover - partial checkout
        return None
    return xdist_budget.resolve_workers()


def _join_install_receipt_workers() -> None:
    """Join any ``install_receipt.dispatch()`` worker before this test's pins lift.

    ``dispatch()`` hands the receipt write to a daemon thread. The worker receives
    every environment-derived input (the data home, the config fields) from the
    dispatching thread and reads nothing itself -- but a thread still alive when
    ``monkeypatch`` undoes ``KIROCREW_HOME`` is a thread whose WRITE lands after the
    test that owned it is gone. The per-test probe in the 5x hygiene run saw exactly
    that: the ``kirocrew-install-receipt`` thread alive after teardown in 3 of 5
    runs, and once a receipt secret written into the operator's real ``~/.kiro/crew``.

    Structural rather than opt-in, for the same reason as the CWD restore below: the
    test that leaks is never the test that fails, so relying on each
    dispatch-triggering test to remember ``wait_for_pending_receipt_writes()`` is the
    shape that let this through. It lives in the ``tryfirst`` teardown hook for the
    ordering reason documented on ``pytest_runtest_teardown``: an autouse fixture
    from this conftest is an OUTER fixture and would tear down AFTER ``monkeypatch``
    had already restored the environment. With no worker registered this is one
    lock acquire; the module is looked up rather than imported so a test run that
    never touches the receipt path pays nothing.
    """
    mod = sys.modules.get("kiro_crew.apps.install_receipt")
    waiter = getattr(mod, "wait_for_pending_receipt_writes", None)
    if waiter is not None:
        waiter()


#: How long the executor join waits before giving up on a wedged job. Long enough for
#: a config read on a loaded host; short enough that a job blocked forever surfaces as
#: a slow teardown rather than a hung worker (pytest-timeout is not armed here).
_EXECUTOR_JOIN_SECS = 10.0


def _join_test_loop_executor(item) -> None:
    """Retire the test loop's leftovers before this test's pins lift.

    Two things outlive a test on its own event loop, and pytest-asyncio 0.20 ends the
    loop with a bare ``loop.close()`` that waits for neither:

    * **Pending tasks.** A task the code under test detached and the test never awaited
      is destroyed with the loop, and a coroutine destroyed mid-await gets
      ``GeneratorExit`` thrown into it -- so its ``finally`` blocks run at garbage
      collection, whenever that is. ``_run_chat``'s queue-cycle ``finally`` reaches a
      synchronous ``KiroCrewConfig.load()``; run after the ``KIROCREW_HOME`` pin is gone,
      that resolves the OPERATOR's data home. A fresh fake ``HOME`` grew ``~/.kiro/crew``
      and the breadcrumb after four subagent ``on_done`` tests exactly this way, and not
      one of them failed.
    * **Default-executor jobs.** ``asyncio.to_thread`` and ``run_in_executor(None, ...)``
      hand work to the loop's default ``ThreadPoolExecutor``; ``close()`` shuts it down
      without waiting, so a running or queued ``KiroCrewConfig.load()`` finishes after
      the pins are gone. A started thread cannot be cancelled by anything the loop does.

    This does what :func:`asyncio.run` does at shutdown -- cancel every pending task,
    run the loop until they have finished, then join the executor -- and does it in the
    same place and for the same reason as :func:`_join_install_receipt_workers`: the
    ``tryfirst`` teardown hook runs before ANY fixture teardown, so the pins still hold.
    Both steps are bounded by ``_EXECUTOR_JOIN_SECS``; a task that will not finish or a
    job that will not return costs one slow teardown, never a hung worker.

    The executor is then made usable again. ``shutdown_default_executor`` latches the
    loop into refusing every later ``run_in_executor(None, ...)``, and an inner
    fixture's async teardown may still need one; clearing the latch and the pool
    reference lets such a call build a fresh executor, exactly as a never-used loop
    would. Both names are CPython's ``BaseEventLoop`` attributes, guarded so a loop
    implementation without them is simply left alone.
    """
    loop = getattr(item, "funcargs", {}).get("event_loop")
    if loop is None or not isinstance(loop, asyncio.AbstractEventLoop):
        return
    if loop.is_closed() or loop.is_running():
        return
    try:
        pending = [task for task in asyncio.all_tasks(loop) if not task.done()]
        if pending:
            for task in pending:
                task.cancel()
            loop.run_until_complete(asyncio.wait(pending, timeout=_EXECUTOR_JOIN_SECS))
        if getattr(loop, "_default_executor", None) is not None:
            loop.run_until_complete(loop.shutdown_default_executor(timeout=_EXECUTOR_JOIN_SECS))
            for name, reset in (("_executor_shutdown_called", False), ("_default_executor", None)):
                if hasattr(loop, name):
                    setattr(loop, name, reset)
    except Exception:  # pragma: no cover - a wedged loop must not turn teardown red
        return


# Durations and phases pytest_runtest_logreport has already seen for the item whose
# runtest protocol is in flight, keyed by node id. The escape guard uses both to
# preserve one report per phase and to charge only time no logged report covers.
_escape_logged_reports: dict[str, tuple[float, set[str]]] = {}


@pytest.hookimpl(tryfirst=True)
def pytest_runtest_logreport(report):
    """Track logged phases and durations for the in-flight escape guard."""
    logged = _escape_logged_reports.get(report.nodeid)
    if logged is not None:
        duration, phases = logged
        _escape_logged_reports[report.nodeid] = (
            duration + max(report.duration, 0.0),
            phases | {report.when},
        )


@pytest.hookimpl(tryfirst=True)
def pytest_runtest_makereport(item, call):
    """Stop the item timeout before teardown report processing begins.

    All three timed phases are finished once teardown's ``CallInfo`` completes.
    Report serialization and ``logfinish`` must not be interrupted by that timer:
    those hooks run outside every ``CallInfo``, where an alarm would escape the
    protocol instead of becoming a normal test report.
    """
    if call.when == "teardown" and hasattr(item.ihook, "pytest_timeout_cancel_timer"):
        item.ihook.pytest_timeout_cancel_timer(item=item)


@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_protocol(item, nextitem):
    """Turn a ``Failed`` that escapes the runtest protocol into that test's failure.

    Every ``pytest.fail`` raised inside setup, call or teardown is caught by
    ``CallInfo.from_call`` and becomes a report. The one that is NOT is
    pytest-timeout's: with ``timeout_func_only`` off, its SIGALRM handler can fire
    anywhere in the protocol -- while pytest is rendering a failure report, between
    phases -- and ``pytest.fail("Timeout >120.0s")`` then propagates out of
    ``pytest_runtest_protocol`` with no report logged. Under xdist that is fatal
    to the whole session, not the test: ``xdist.remote`` sends
    ``runtest_protocol_complete`` only when this hook RETURNS, so the controller
    either takes the worker's traceback as an INTERNALERROR or, when the worker
    goes on to finish, trips ``dsession.worker_workerfinished``'s
    ``assert not crashitem`` for the still-assigned item. Either way one slow
    test on an overloaded runner erases the shard's results.

    Outermost wrapper (``tryfirst``), so it sees what every inner wrapper --
    pytest-timeout's own included, which has already cancelled its timer by the
    time the outcome reaches here -- let through. Only ``Failed`` is repaired: an
    ``Exit`` escaping here is ``pytest.exit`` doing its job.

    The invariant is one report per phase. The earliest of setup and call without a
    logged report carries the escape, and teardown always runs unless it already
    logged. This leaves three branches: no call report synthesizes the earliest
    missing setup/call report, a call report without teardown puts the escape on the
    teardown report, and a logged teardown emits nothing extra.

    The teardown ``makereport`` hook disarms pytest-timeout before teardown report
    logging starts. All timed phases are complete there, so serialization and
    ``logfinish`` cannot create another timer escape. A logged teardown therefore
    reached the controller before branch three can be entered. An alarm in the setup
    or call logreport chain after this tracker runs but before xdist sends the report
    can still leave that original phase absent on the controller. The synthesized
    failure or teardown error makes that item fail loudly rather than pass green.

    ``_escape_logged_reports`` records phases and durations at the start of each
    logreport chain. ``pytest-split`` sums report durations by node id, so a
    synthesized report owns only protocol time not charged to a logged phase. A
    normal call keeps its elapsed time, while the replacement teardown owns only
    teardown time. The hook then returns normally so xdist completes the item.

    Teardown is required because live fixtures left on ``SetupState`` break the next
    item on the worker. A clean teardown receives the escaped failure. Its own error
    wins when teardown fails. Control-flow exceptions keep pytest's normal reraise
    and interactive handling.
    """
    protocol_start_perf = time.perf_counter()
    _escape_logged_reports[item.nodeid] = (0.0, set())
    try:
        outcome = yield
    finally:
        already_logged, logged_phases = _escape_logged_reports.pop(item.nodeid, (0.0, set()))
    protocol_stop = time.time()
    protocol_duration = time.perf_counter() - protocol_start_perf
    excinfo = outcome.excinfo
    if excinfo is None or not isinstance(excinfo[1], _pytest.outcomes.Failed):
        return
    escaped = excinfo[1]
    if "call" not in logged_phases:
        carrier = next(phase for phase in ("setup", "call") if phase not in logged_phases)

        def _reraise():
            raise escaped

        call = _pytest.runner.CallInfo.from_call(_reraise, carrier)
        call.duration = max(protocol_duration - already_logged, 0.0)
        call.stop = protocol_stop
        call.start = protocol_stop - call.duration
        report = item.ihook.pytest_runtest_makereport(item=item, call=call)
        item.ihook.pytest_runtest_logreport(report=report)
        _pytest.runner.call_and_report(item, "teardown", log=True, nextitem=nextitem)
    elif "teardown" not in logged_phases:
        call = _pytest.runner.CallInfo.from_call(
            lambda: item.ihook.pytest_runtest_teardown(item=item, nextitem=nextitem),
            "teardown",
            reraise=_pytest.runner.get_reraise_exceptions(item.config),
        )
        if call.excinfo is None:
            call = _pytest.runner.CallInfo(
                None,
                pytest.ExceptionInfo.from_exc_info(excinfo),
                start=call.start,
                stop=call.stop,
                duration=call.duration,
                when="teardown",
                _ispytest=True,
            )
        report = item.ihook.pytest_runtest_makereport(item=item, call=call)
        item.ihook.pytest_runtest_logreport(report=report)
        if _pytest.runner.check_interactive_exception(call, report):
            item.ihook.pytest_exception_interact(node=item, call=call, report=report)
    item.ihook.pytest_runtest_logfinish(nodeid=item.nodeid, location=item.location)
    outcome.force_result(True)


@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_teardown(item, nextitem):
    """Put the process working directory back, BEFORE any fixture teardown runs.

    A ``tryfirst`` HOOKWRAPPER: everything before the ``yield`` runs before any other
    teardown impl (so before any fixture unwinds), and the one thing after it (the
    verdict of ``_refuse_a_resolved_real_default_home``) runs after every fixture has
    been torn down. That split is load-bearing: the check must READ its evidence before
    the test's ``monkeypatch`` restores the global, but it must RAISE only once the
    floor has unwound, because an exception raised before the default teardown impl
    skips fixture finalization for the whole item and leaves every pin in place for
    the rest of the worker (1,245 downstream errors when it was first tried).

    The CWD is per-PROCESS, so under xdist one test's ``os.chdir`` silently becomes every
    later test's starting directory on that worker. That was survivable while the
    directory it pointed at outlived the run. It is not survivable now: with
    ``tmp_path_retention_policy = failed`` pytest removes a passing test's ``tmp_path`` at
    that test's own teardown, so a test that chdirs into ``tmp_path`` and does not come
    back leaves the worker sitting in a DELETED directory -- and then ``Path.cwd()`` raises
    ``FileNotFoundError`` in every later test that reaches it, including deep inside
    production code (``taskrunner.TaskRunner.__init__`` does ``work_dir or Path.cwd()``).

    Measured instance and its numbers:
    ``docs/system-specs/common/testing-conventions.md`` § Rules. It reads as "the suite is
    flaky" -- many files, each passing in isolation -- rather than as one missing line.

    **A ``tryfirst`` teardown hook rather than an autouse fixture, and the difference is
    load-bearing on Windows.** A fixture here would be an OUTER one (the rootdir conftest
    is set up before the test's own fixtures), so it would tear down LAST -- after
    ``tmp_path`` cleanup had already tried to remove a directory the process was still
    sitting in. Windows refuses to delete a process's current working directory, so the
    cleanup fails there. Making the fixture depend on ``tmp_path`` would invert the order,
    but at the price of allocating a directory for every test in the suite, which is
    exactly the per-test cost this change removed elsewhere. A ``tryfirst`` hookimpl runs
    before the default ``pytest_runtest_teardown``, which is what performs fixture
    finalization -- so the CWD is restored before ANY teardown, at no per-test cost.

    Restoring rather than failing is deliberate. The damage a leaked CWD does is to OTHER
    tests, so the floor's job is to stop it propagating; naming every offender is a
    separate cleanup, and one a red suite would not help with. A test that wants to change
    directory for its own duration keeps working, and ``monkeypatch.chdir`` (which reverts
    itself, and whose undo lands on the same value) remains the right tool inside a test.
    """
    _join_install_receipt_workers()
    _join_test_loop_executor(item)
    resolved_real_home = (
        _resolved_real_default_home() if item.stash.get(_HOME_PIN_ARMED, False) else None
    )
    _restore_session_cwd()
    yield
    if resolved_real_home is not None:
        _refuse_a_resolved_real_default_home(resolved_real_home)


def _restore_session_cwd() -> None:
    if _SESSION_CWD is None:  # pragma: no cover - configure always runs first
        return
    try:
        if os.getcwd() == _SESSION_CWD:
            return
    except OSError:
        # The CWD was deleted under us, so the comparison itself raises. Getting back to a
        # real directory is the whole point, so fall through and do it unconditionally.
        pass
    try:
        os.chdir(_SESSION_CWD)
    except OSError:  # pragma: no cover - the starting directory would have to be gone
        pass


# ── no test may leave a telemetry exporter running ────────────────────

#: Thread-name marker for OpenTelemetry's periodic metric exporter. Matched on the
#: name because the SDK is an optional import: naming the class would make this
#: guard depend on it being installed.
_OTEL_THREAD_MARKER = "Otel"


def _live_exporter_threads() -> set:
    """The exporter threads alive right now, as OBJECTS.

    Objects, not names: the SDK gives every ``PeriodicExportingMetricReader`` ticker
    the same name, so a name-keyed set makes a second leak indistinguishable from the
    first one still running.
    """
    return {t for t in threading.enumerate() if _OTEL_THREAD_MARKER in t.name and t.is_alive()}


def _stop_leaked_exporter(thread) -> None:
    """Best-effort: stop *thread* through the reader that owns it.

    The reader is unreachable from ``metrics.provider`` by this point -- a stubbed
    ``shutdown`` is exactly what orphans it -- but the thread's target is the
    reader's own bound method, so the thread still knows its owner. Reaching through
    ``__self__`` is the only handle left, and stopping the thread is what keeps one
    leak from reddening everything that follows it on this worker.

    A thread we cannot reach is WARNED about rather than passed over: it means the
    guard reported the leak and then left it running, which is the state that
    corrupts every later fork child on the worker, so it must not be silent.
    """
    owner = getattr(getattr(thread, "_target", None), "__self__", None)
    if owner is None:
        warnings.warn(
            f"telemetry exporter thread {thread.name!r} cannot be stopped: its target "
            "exposes no owning reader, so it will keep running for the rest of this "
            "worker and every later fork child will be multithreaded",
            stacklevel=2,
        )
        return
    try:
        owner.shutdown(timeout_millis=1)
    except Exception as exc:  # pragma: no cover - SDK-shape dependent
        warnings.warn(
            f"could not stop telemetry exporter thread {thread.name!r}: {exc!r}",
            stacklevel=2,
        )


@pytest.fixture(autouse=True)
def _no_leaked_telemetry_exporter():
    """Fail the test that leaves an OTel exporter thread alive, then clean up.

    A leaked ``PeriodicExportingMetricReader`` is not just an idle thread. The SDK
    registers an ``os.register_at_fork(after_in_child=...)`` hook that RESTARTS that
    thread in every fork child, so from then on the sandbox's userns probe forks a
    child that is multithreaded -- and ``unshare(CLONE_NEWUSER)`` implies
    ``CLONE_THREAD``, which the kernel refuses with EINVAL unless the caller is
    single-threaded. EINVAL is classified permanent, so the worker caches "this host
    has no sandbox backend" and every later sandboxed spawn fails closed. Measured:
    one leak reddened 19 tests across two app suites, all of which pass alone, and
    none of which is a metrics test.

    The thread also keeps its own reader alive (its target is a bound method), so no
    amount of dropping references clears it; only a real ``shutdown()`` does. That is
    why a test that observes the shutdown call must SPY on it and delegate, never
    replace it.

    Attributed by DIFFERENCE, not by observation: a thread alive at setup was left by
    an earlier test, so only threads that appeared during this one are reported. That
    is what makes the message name the culprit. The first version reported whatever
    test was running when a leak was first seen, which on a Windows shard blamed three
    tests in ``test_perf_boot_path.py`` that run every line of their subject in a
    SUBPROCESS and cannot leak a thread into the worker at all.

    Cleaning up after failing is deliberate: the leak damages every LATER test, so
    letting it stand would turn one defect into a red suite -- and with cleanup, the
    difference cannot double-report either.
    """
    before = _live_exporter_threads()
    yield
    leaked = _live_exporter_threads() - before
    if not leaked:
        return
    provider = sys.modules.get("kiro_crew.metrics.provider")
    if provider is not None:
        with contextlib.suppress(Exception):
            provider.reset_for_testing()
    for thread in leaked:
        _stop_leaked_exporter(thread)
    raise AssertionError(
        "this test STARTED a telemetry exporter thread and left it running: "
        f"{sorted(t.name for t in leaked)}. A metrics provider must be shut down for "
        "real (reset_for_testing()), and a test that stubs `shutdown` must delegate "
        "to it -- see "
        "conftest._no_leaked_telemetry_exporter."
    )


# ── the logging record factory goes back after every test ─────────────


@pytest.fixture(autouse=True)
def _restore_log_record_factory():
    """Put ``logging``'s record factory back, so one test cannot rewrite every later record.

    ``logging.setLogRecordFactory`` is ONE process-global slot. The wrapper the suite
    reaches -- ``log_redaction``'s, installed by ``cli._setup_cli_logging`` for a
    long-lived command -- is deliberately destructive to every record it then creates: it
    materializes ``msg`` and clears ``args`` so a handler cannot re-format, and it renders
    ``exc_info`` into ``exc_text`` and clears ``exc_info`` so a handler cannot re-render an
    unredacted traceback. Correct for redaction, and invisible to the test that leaves it
    installed, because the damage lands on whatever unrelated test later asserts on
    ``record.exc_info``, ``record.args``, or a deferred ``%s``.

    Measured: two tests failed this way in a release run and neither is a logging test --
    ``test_pid_lifecycle.py::TestFindOrphanMcpCandidates::
    test_unexpected_probe_error_keeps_traceback`` asserting a probe failure kept its
    traceback, and ``test_log_redaction`` itself hitting ``RecursionError`` because
    installing over the already-installed wrapper captured it as its own base factory.

    **Sharding hides this class, so the floor cannot rely on a full-suite run to find it.**
    CI assigns whole files to a shard before import on every platform, and a leak only
    damages tests in the SAME process, so PR CI
    usually cannot observe it at all; the
    release job runs the suite whole and is otherwise the first place it appears -- as
    failures in files unrelated to the cause, long after the diff merged. Restoring here
    removes the class outright rather than improving the odds of noticing it.

    Restoring rather than failing is deliberate, for the same reason the CWD restore in
    ``pytest_runtest_teardown`` above does not blame either: installing this factory is a
    legitimate, unavoidable side effect of every test that drives the real ``cli.main()``
    or ``_setup_cli_logging`` in-process, which production does once per process and never
    undoes. Blaming them would demand pure bookkeeping with no test value, and the damage
    is to OTHER tests, so stopping it propagating is the whole job.
    ``log_redaction.uninstall_log_redaction()`` is there for a test that wants to assert on
    the uninstalled state itself; the install/uninstall contract is pinned by
    ``test_log_redaction.py``, not by this floor.

    The restore target is what this test INHERITED, not a pristine ``LogRecord``. That is
    what lets a higher-scoped fixture install one for the whole class or module without
    this floor tearing it out from under the second test, and it is also why this is a
    fixture rather than the cheaper ``pytest_runtest_teardown`` hookimpl the CWD restore
    uses: a conftest ``pytest_runtest_setup`` runs BEFORE the item's own fixtures, so its
    snapshot would miss such an installer and the teardown would then rip it out after the
    class's FIRST test. Measured cost of the fixture protocol over the hookimpl: ~50us per
    test, ~3s of CPU across the suite, spread over the xdist workers.

    The BOUNDARY that follows from the same choice: a class-, module- or session-scoped
    fixture that installs a factory and never removes it leaks PAST its own scope, because
    every later test inherits it and so restores to it. No fixture in this repo does that
    -- every installer sits in a test body, which is inside this fixture's window -- but a
    new higher-scoped one has to uninstall itself; the floor cannot tell that case from a
    deliberate one.
    """
    before = logging.getLogRecordFactory()
    yield
    if logging.getLogRecordFactory() is not before:
        logging.setLogRecordFactory(before)


# ── the CLI log queue listener goes back after every test ────────────


@pytest.fixture(autouse=True)
def _restore_log_queue_listener():
    """Stop the ``QueueListener`` a test leaves running, so no later test inherits it.

    ``cli._LOG_QUEUE_LISTENER`` is ONE process-global slot, per worker, and the sibling of
    the record factory above: ``_setup_cli_logging`` installs BOTH in the same
    ``command in _LONG_LIVED_COMMANDS`` branch, so every test that drives the real
    ``cli.main()`` for ``serve`` / ``gateway`` / ``chat`` leaks both. The factory half has
    been floored since it was found; this half was not, and it is the one the SHORT-LIVED
    branch then trips over. ``_setup_cli_logging("status", ...)`` takes the ``else`` path,
    which correctly never touches the global -- the listener a long-lived command started
    genuinely still exists -- so a test asserting "a short-lived verb starts no listener"
    reads the PREVIOUS test's listener and fails at its own first line.

    Measured: two tests in ``test_cli_logging.py`` assert that global is ``None`` after a
    short-lived setup -- ``TestDrainBeforeHardExit::test_no_listener_is_a_silent_no_op``
    and ``TestQueueOffLoop::test_short_lived_command_keeps_sync_handler`` -- and both go
    red whenever ``test_cli.py`` or ``test_cpp_seam_failclosed.py`` precede them on the
    worker, reading ``assert <QueueListener object ...> is None``. That file's own
    ``_pristine_logging`` cannot absorb it: it clears the global in TEARDOWN only, which
    makes the file self-clean but leaves it defenceless against a leak that is already
    present at its SETUP. Under ``-n auto --dist loadgroup`` which worker an ordinary test
    lands on varies run to run, so it surfaces as an intermittent failure rather than a
    reproducible ordering bug -- it cost upstream PR #6798 a red ``Backend Tests (3.10, 1)``
    shard while ``(3.12, 1)`` passed at the identical commit.

    STOPPING rather than only reassigning, which is where this differs from the factory:
    the leak is a live daemon thread holding the file handler's open descriptor on a
    ``gateway.log`` under a ``tmp_path`` the next test deletes, so dropping the reference
    alone would clear the assertion and keep the thread and the fd. ``cli`` is reached
    through ``sys.modules`` rather than imported, as ``_no_leaked_telemetry_exporter``
    does: a worker that never imported it cannot hold a listener, and importing it here
    would charge every testpath ~0.5s and ~54MB for the ratchet in
    ``test_cli_lazy_imports.py`` to then measure in a subprocess anyway.

    Restoring rather than blaming, for the same reason as ``_restore_log_record_factory``
    above: starting the listener is what the entry point under test is FOR, and production
    starts it once per process and never undoes it. The damage is to OTHER tests, so
    stopping it propagating is the whole job.

    HANDLERS stay untouched, the boundary ``_restore_logger_levels`` below draws and for
    its reasons. The ``_CliLogQueueHandler`` left on the ``kiro_crew`` logger therefore
    outlives the listener it fed, holding an unattended queue; it is the same handler
    accumulation that fixture already records as a separate defect, and
    ``test_cli_logging.py``'s ``_pristine_logging`` is what absorbs it today by clearing
    both handler lists at setup.

    The restore target is what the test INHERITED, so a higher-scoped fixture that starts
    a listener for a whole class or module is not torn out from under its second test --
    and, as there, such a fixture has to stop its own listener, because every later test
    then inherits it and so restores to it.
    """
    cli = sys.modules.get("kiro_crew.cli")
    before = getattr(cli, "_LOG_QUEUE_LISTENER", None)
    yield
    cli = sys.modules.get("kiro_crew.cli")
    if cli is None:
        return
    after = getattr(cli, "_LOG_QUEUE_LISTENER", None)
    if after is before:
        return
    if after is not None:
        # Drains and joins the listener thread, then closes the file handler. Suppressed
        # because a floor must not fail a test for state it is only cleaning up, and the
        # restore below has to happen either way.
        with contextlib.suppress(Exception):
            cli._stop_log_queue_listener()
    cli._LOG_QUEUE_LISTENER = before


# ── the hooks system's process-wide dispatcher goes back after every test ──


@pytest.fixture(autouse=True)
def _restore_hooks_integration_globals():
    """Put ``hooks_integration._lifecycle_dispatcher`` / ``_route_registry`` back.

    ``init_hooks_system`` -- which every test that builds the real dashboard app
    reaches through ``server.py`` -- assigns BOTH module globals and nothing in
    production ever clears them: a gateway sets them once at boot. In a worker they
    therefore carry the LAST such test's ``LifecycleDispatcher`` into every later
    test, together with whatever that test passed as ``cron_service`` -- routinely
    a ``MagicMock``. The trust-revoke teardown (``teardown_app_runtime`` ->
    ``on_app_disable`` -> ``_cleanup_app_crons``) reads that global and awaits the
    stale mock's cron store, gets ``object MagicMock can't be used in 'await'
    expression``, and reports ``hooks disable failed`` -- so the route answers 409
    ``teardown_incomplete`` for an app whose teardown had nothing to do.

    Measured on a five-run hygiene sweep: seven to nine of
    ``test_trusted_apps_api.py``'s revoke tests were red in EVERY round with that
    body, a different subset each round, and all of them pass alone -- the file
    is a victim, not the leak. Reproduced by replaying one worker's 1,874 files
    in order at ``-n0`` with a debug hook on the handler, which named the stale
    dispatcher and its ``MagicMock`` cron service. Restored rather than blamed,
    like the log-record factory above: the assignment is production's, the
    tests that trigger it are exercising real boot code, and any of ~170 files
    that build the app can be the one that lands before the victim. Reached
    through ``sys.modules`` so a worker that never imported the module pays
    nothing and no import is charged to the lazy-import ratchets.
    """
    hi = sys.modules.get("kiro_crew.apps.hooks_integration")
    before = None
    if hi is not None:
        before = (
            getattr(hi, "_lifecycle_dispatcher", None),
            getattr(hi, "_route_registry", None),
        )
    yield
    hi = sys.modules.get("kiro_crew.apps.hooks_integration")
    if hi is None:
        return
    if before is None:
        # Imported DURING the test: whatever it set is the test's, and the module
        # started life with both slots empty.
        before = (None, None)
    hi._lifecycle_dispatcher, hi._route_registry = before


# ── logger levels go back after every test ──────────────────────────


#: What a logger nobody has configured looks like. ``logging.getLogger(name)`` builds
#: exactly this, so a name MISSING from the "before" snapshot restores to it rather than
#: being passed over -- otherwise a test that creates a logger and configures it leaks
#: through the one gap a snapshot cannot see.
_PRISTINE_LOGGER: tuple[int, bool] = (logging.NOTSET, False)


def _logger_levels() -> dict[str, tuple[int, bool]]:
    """``(level, disabled)`` for the root logger and every logger by name.

    ``loggerDict`` also holds ``PlaceHolder`` entries for the un-instantiated middle of a
    dotted name; those carry no level and are skipped. The root logger is not in it at
    all, so it is added under ``""`` -- the name ``logging.getLogger`` maps back to it.
    """
    snapshot: dict[str, tuple[int, bool]] = {
        name: (obj.level, obj.disabled)
        for name, obj in list(logging.Logger.manager.loggerDict.items())
        if isinstance(obj, logging.Logger)
    }
    root = logging.getLogger()
    snapshot[""] = (root.level, root.disabled)
    return snapshot


@pytest.fixture(autouse=True)
def _restore_logger_levels():
    """Put every logger's level and ``disabled`` flag back after each test.

    A level is PROCESS-GLOBAL and HIERARCHICAL, which together are what make a leak here
    so hard to attribute: ``Logger.debug`` checks the EFFECTIVE level, so an explicit
    level left on ``kiro_crew`` decides what every ``kiro_crew.*`` logger in the worker
    may emit, and it outranks the root level ``caplog.at_level()`` sets. The victim then
    sees ``caplog.text == ""`` -- not the wrong text, NOTHING -- from a test that passes
    alone, in a file that has nothing to do with the cause.

    Measured: ``test_slack_gateway_more_coverage.py::TestDeliverCronResponse::
    test_options_post_failure_still_delivers_text`` asserts on a ``logger.debug`` line and
    reds whenever ``test_cli.py::TestCronCli::test_cli_argparse_cron_add_agent_flag``
    shares its worker -- an ARGPARSE test, in a file with no connection to Slack. It
    drives the real ``cli.main()``, whose ``_setup_cli_logging`` pins ``kiro_crew`` at
    WARNING, exactly as production does once per process and never undoes. Test modules
    across the suite drive ``main()`` that way.

    Restoring rather than blaming, for the same reason as ``_restore_log_record_factory``
    above: configuring logging is what the entry point under test is FOR, so demanding
    per-module bookkeeping from every test that reaches it buys no coverage and is one
    forgotten fixture away from reappearing. The damage is to OTHER tests, so stopping it
    propagating is the whole job.

    **HANDLERS are deliberately not restored, and the boundary is not squeamishness.** A
    handler is routinely paired with a module-global that records it as installed --
    ``dashboard.handlers.updates._log_ring_handler_installed`` is the live example -- and
    a floor can detach the handler but cannot know to clear the flag. That leaves the
    module in a state neither a test nor production can otherwise reach: the singleton
    reports installed while nothing is attached, so the next caller is handed a handler
    that receives nothing. Restoring the ROOT logger's handler list is unsafe for a
    second, independent reason: pytest's ``catching_logs`` adds one per test PHASE and
    removes it at the phase boundary, so a list snapshotted during setup would be written
    back during teardown, re-attaching the setup phase's handler and dropping the one the
    teardown phase is capturing through.

    The handlers ``_setup_cli_logging`` leaves on ``kiro_crew`` do accumulate -- each open
    on a ``gateway.log`` under a ``tmp_path`` the next test deletes -- but that is a
    separate defect from this one, and it is not what empties ``caplog``.
    ``test_cli_logging.py``'s own ``_pristine_logging`` fixture is what absorbs it today,
    by clearing both handler lists at setup rather than by trusting its inheritance.

    Measured cost: ~30us per snapshot at ~450 live loggers, so ~60us per test.
    """
    before_disable = logging.Logger.manager.disable
    before = _logger_levels()
    yield
    for name, after in _logger_levels().items():
        level, disabled = before.get(name, _PRISTINE_LOGGER)
        if after == (level, disabled):
            continue
        logger = logging.getLogger(name)
        logger.setLevel(level)
        logger.disabled = disabled
    if logging.Logger.manager.disable != before_disable:
        logging.disable(before_disable)


# ── the sandbox probe cache is warm for every test, in every testpath ──


#: The verdict this worker's ONE real probe produced, so a later test that finds the
#: cache cold can be handed the same answer instead of paying another probe. ``None``
#: means "not established" -- either the probe has not run yet, or it came back
#: transient and left nothing to cache.
_probe_verdict: str | None = None
_probe_attempted = False


def pytest_runtest_setup(item):
    """Keep ``sandbox._backend`` warm for every test, at one probe per worker.

    ``detect_backend()`` reached from a running event loop with a COLD cache
    deliberately refuses to probe -- the probe forks and waits, which must never
    happen on the loop -- and returns "none" with a self-described transient reason.
    Production fills the cache at gateway boot so that path is not reachable; a
    pytest worker has no boot, so the first async test to spawn through
    ``wrap_argv`` gets a hard ``SandboxUnavailableError`` reading "this host has no
    OS sandbox backend" on a host whose sandbox works perfectly.

    This lived in ``test/conftest.py``, which the in-package app suites never load,
    so the ~1490 tests under ``src/kiro_crew/apps/builtins/*/tests/`` had no warm
    cache at all -- 19 of them failed that way in a full run while every one passed
    when its own file was run alone. Whether an app test file happened to land on an
    xdist worker that had already run something under ``test/`` decided the verdict.

    Acting at SETUP rather than once per session is what makes it order-independent:
    the six ``test_sandbox_*.py`` files reset the cache in their own teardown
    (correctly -- they test the cache), and a session-scoped prewarm cannot undo that
    for whatever runs next on the worker.

    **RESTORING the first verdict, not re-probing.** A probe is not cheap on every
    host and its cost is not portable: it forks and then closes every inherited
    descriptor, which is O(``RLIMIT_NOFILE``) -- measured 1ms at a 1024 limit, 102ms
    at 524288 -- and on macOS it spawns a real ``sandbox-exec``. Re-probing per reset
    took ``test_sandbox_argv.py`` from 3.7s to 18.6s across its 145 tests. The answer
    cannot change within a process, so the second and later tests get the recorded
    one by assignment.

    Probing at most ONCE also bounds the transient case, which is the one that would
    otherwise be unbounded: a transient verdict is deliberately never cached, so
    "probe whenever cold" on a fork-starved host means two forks and a 50ms sleep for
    every test in the run. A probe failure is swallowed either way -- a host genuinely
    without a sandbox must still run the tests that do not need one.
    """
    global _probe_verdict, _probe_attempted
    try:
        from kiro_crew import sandbox

        if not _probe_attempted:
            _probe_attempted = True
            sandbox.detect_backend()
            _probe_verdict = sandbox._backend
        elif sandbox._backend is None and _probe_verdict is not None:
            sandbox._backend = _probe_verdict
    except Exception:  # pragma: no cover - never let the warm-up fail a test
        pass


# ── tracked Windows gaps apply to every testpath ──────────────────────


#: Ceiling on a test node id. pytest exports the running item's node id as the
#: ``PYTEST_CURRENT_TEST`` environment variable on every setup/call/teardown, and
#: Windows caps one environment variable at 32767 characters -- ``os.environ``
#: raises ``ValueError`` above that, so the item ERRORS at setup on Windows while
#: passing everywhere else. A parametrized case whose value is a large payload (a
#: 700 KB base64 audio blob, once) is how that happens; every report line for the
#: item then carries the blob too, and the Windows shard ran to its 40-minute cap
#: with its log dropped. The margin below the OS limit leaves room for pytest's
#: `` (setup)`` suffix and an xdist group tag. Collection fails with the offending
#: id named, which is the message the shard log never got to show.
MAX_NODEID_CHARS = 30000


def _refuse_oversized_nodeids(items) -> None:
    oversized = [item for item in items if len(item.nodeid) > MAX_NODEID_CHARS]
    if not oversized:
        return
    worst = max(oversized, key=lambda item: len(item.nodeid))
    raise pytest.UsageError(
        f"{len(oversized)} test node id(s) exceed {MAX_NODEID_CHARS} characters "
        f"(longest: {len(worst.nodeid)}, {worst.nodeid[:160]!r}...). Windows caps an "
        "environment variable at 32767 characters and pytest exports the node id as "
        "PYTEST_CURRENT_TEST, so these error at setup there. Give the parametrize "
        "an explicit ids= list instead of letting the payload become the id."
    )


def pytest_collection_modifyitems(config, items):
    """Apply exact capability skips, then the tracked known-gap skips for this OS.

    Real-symlink tests are listed individually rather than intercepting
    ``os.symlink`` globally.  A global interception also catches production
    compatibility helpers before they can handle WinError 1314 and fall back to
    a junction, silently dropping the Windows behavior those tests exist to
    cover.  Exact collection markers leave every non-link path untouched.

    The lists live in ``test/windows-expected-failures.txt``,
    ``test/macos-expected-failures.txt`` and
    ``test/codebuild-expected-failures.txt`` -- one node id per line, captured from
    the first CI runs on that OS or runner. Each is a burn-down backlog: fixed
    tests get their line deleted, and anything NOT on the list still fails the
    job, so the line holds for the tests that pass today. All three go through the
    same ``_apply_tracked_gap_list`` matcher; do not add a fourth mechanism.

    Two of the three are keyed on the OS and the third on the runner, because the
    environment it describes is a Linux one that ``sys.platform`` cannot tell from
    the hosted Linux shards passing the same tests in the same run. See
    :func:`on_self_hosted_runner`.

    Lives HERE rather than in ``test/conftest.py`` because the lists already name node
    ids under ``src/kiro_crew/apps/builtins/auto_improvement/tests/``, and a hook rooted
    at ``test/`` is never registered when only in-package tests are collected -- which is
    exactly what CI's reduced-scope Windows job does when a diff touches no path under
    ``test/``. Those entries are also absent from ``BACKEND_DESELECTS``, so they were
    collected unskipped and the shard went red for a gap that was already tracked.

    The list files themselves stay under ``test/``, read by path from here. Node ids are
    always spelled with ``/`` even on Windows, so the in-package entries need no
    translation.
    """
    _refuse_oversized_nodeids(items)
    if not _ROOT_HAS_REAL_SYMLINKS:
        listfile = _REPO_ROOT / "test" / "requires-real-symlinks.txt"
        try:
            text = listfile.read_text(encoding="utf-8")
        except OSError:  # pragma: no cover - list file absent in a partial checkout
            text = ""
        requires_real_symlink = {
            _base_nodeid(ln.strip())
            for ln in text.splitlines()
            if ln.strip() and not ln.startswith("#")
        }
        marker = pytest.mark.skip(
            reason="test requires real symlink creation; host lacks that capability"
        )
        for item in items:
            if _base_nodeid(item.nodeid) in requires_real_symlink:
                item.add_marker(marker)

    pc = platform_compat_or_none()
    if pc is None:
        return
    if pc.IS_WINDOWS:
        _apply_tracked_gap_list(items, "windows-expected-failures.txt", "Windows")
    elif pc.IS_MACOS:
        _apply_tracked_gap_list(items, "macos-expected-failures.txt", "macOS")
    elif on_self_hosted_runner():
        _apply_tracked_gap_list(
            items, "codebuild-expected-failures.txt", "self-hosted Linux runner"
        )


def on_self_hosted_runner() -> bool:
    """Whether this run is on a self-hosted CI runner rather than a hosted one.

    The third gap list is keyed on the RUNNER rather than the OS, because the
    environment that fails those tests is a Linux one: no IPv6 loopback, no ``link``
    on the filesystem, and an unprivileged user whose resolved home is ``/root``.
    ``sys.platform`` cannot tell it from the hosted Linux shards that pass the same
    tests in the same run, so the list would either apply everywhere or nowhere.

    ``RUNNER_ENVIRONMENT`` is GitHub's own answer to that question, and ``ci.yml``
    already gates this job's non-root boundary assertion on the same value
    (``runner.environment == 'self-hosted'``). Keying off it reuses the signal the
    workflow already treats as identifying the runner instead of inventing a second
    one, and needs nothing added to the job's environment.

    Absent outside CI, so a developer machine reads as hosted and applies no list --
    which is right: a local run has none of the three constraints.
    """
    return os.environ.get("RUNNER_ENVIRONMENT") == "self-hosted"


def _apply_tracked_gap_list(items, listname: str, platform_label: str) -> None:
    """Mark every collected item named in ``test/<listname>`` as a STRICT xfail.

    ONE mechanism serves all three gap lists. macOS and the self-hosted Linux runner
    reuse it rather than growing a second matcher, so the node-id spelling rule
    (``_base_nodeid``: no ``[params]``, no ``@group``) and the burn-down semantics --
    anything NOT listed still fails the job -- are identical for every list by
    construction.

    **``xfail(strict=True)``, not ``skip``, because these files call themselves a
    burn-down backlog and say "fix the test and DELETE the line".** A skip does not
    execute the test, so nothing can ever report that a gap CLOSED: the list could
    only ever grow, and 241 node ids were retired rather than tracked. Under a
    strict xfail a listed test that still fails is green (the gap is known), and one
    that starts PASSING fails the job with XPASS -- which is precisely the signal
    that the line should be deleted, delivered by the same run that earned it.

    Safe for the entries whose failure is intended platform behaviour rather than a
    gap: those still FAIL on the platform they are listed for, so they xfail green
    exactly as before. They only never burn down, which is an honesty problem with
    the list's framing (see the frame-recorder group in
    ``macos-expected-failures.txt``) and not a mis-fire of this mechanism.

    **A listed test that HANGS must not be in this list, and the platform is why.**
    Executing rather than skipping costs CI minutes, which is fine; what is not
    fine is a hang. On Windows there is no ``SIGALRM``, so pytest-timeout cannot
    interrupt the test -- it kills the process, which is why the Windows shards pass
    ``--max-worker-restart=0``. MEASURED: one listed entry
    (``test_config_loader.py::TestAgentWorkspaceBindingsProperties::test_workspace_path_resolution``)
    hangs on a native Windows host, and running the list killed the session at 22%
    with no summary line printed at all. A hanging test therefore cannot be tracked
    here; it needs an explicit ``skipif`` at the test, with the reason, so nothing
    about it is silent.

    **An entry MAY name one parametrization, and that is what makes strict xfail
    expressible at all.** Stripping ``[params]`` from every entry (see
    :func:`_base_nodeid` for why the strip exists) means one line covers every
    parametrization of a test -- which is right when they all fail, and impossible
    when they do not: ``test_seed_audit_uses_rail_tag_not_raw_path`` has two params
    that fail on Windows and one that passes, so a single base entry would either
    un-track the two or red the job forever on the one. So a line WITHOUT ``[`` is
    matched against the param-stripped id, exactly as before, and a line WITH ``[``
    is matched against the id with its params intact. The ``@group`` suffix is
    stripped on both sides either way, because that one is an xdist artifact rather
    than part of the test's identity.
    """
    listfile = _REPO_ROOT / "test" / listname
    try:
        text = listfile.read_text(encoding="utf-8")
    except OSError:  # pragma: no cover - list file absent in a partial checkout
        return
    entries = [ln.strip() for ln in text.splitlines() if ln.strip() and not ln.startswith("#")]
    expected_base = {_base_nodeid(e) for e in entries if "[" not in e}
    expected_exact = {_ungrouped_nodeid(e) for e in entries if "[" in e}
    if not expected_base and not expected_exact:
        return
    marker = pytest.mark.xfail(
        reason=f"known {platform_label} gap -- tracked in test/{listname}; "
        "delete the line when it starts passing",
        strict=True,
    )
    for item in items:
        if (
            _base_nodeid(item.nodeid) in expected_base
            or _ungrouped_nodeid(item.nodeid) in expected_exact
        ):
            item.add_marker(marker)


def _ungrouped_nodeid(nodeid: str) -> str:
    """A node id with only the xdist ``@group`` suffix removed, params kept.

    The counterpart to :func:`_base_nodeid` for a gap-list entry that names ONE
    parametrization. ``@group`` still has to go -- it is added by
    ``--dist loadgroup`` and absent under ``-n0``, so leaving it in would make the
    same entry match in one invocation and not the other -- but ``[params]`` is part
    of what the entry is identifying and stays.
    """
    return nodeid.split("@")[0]


def _base_nodeid(nodeid: str) -> str:
    """A node id reduced to file + class + function, with params and xdist group gone.

    Under ``--dist loadgroup`` -- which ``setup.cfg`` supplies to EVERY run -- xdist
    rewrites each item's nodeid to ``<nodeid>@<group>`` for anything carrying an
    ``xdist_group`` mark. Splitting on ``[`` alone therefore compares different strings
    in different invocations: a PARAMETRIZED id loses the suffix with its params, while
    an UNPARAMETRIZED one keeps it. So a plain entry silently stopped matching the
    grouped tests under the default invocation, and an entry written WITH the suffix to
    compensate then stopped matching under ``-n0``, where xdist never adds it.

    Stripping both parts makes one spelling -- the plain node id -- correct in every
    mode, which is the only spelling the list file documents.
    """
    return nodeid.split("[")[0].split("@")[0]


def platform_compat_or_none():
    """``kiro_crew.platform_compat``, or ``None`` when it cannot be imported.

    Imported lazily so this rootdir conftest keeps its module-level imports to the
    stdlib: it is loaded before every collection, and a module-scope import of the
    package under test would make the whole suite depend on that package's import-time
    side effects.
    """
    try:
        from kiro_crew import platform_compat
    except ImportError:  # pragma: no cover - partial checkout
        return None
    return platform_compat


# ── the system temp directory is host state too ───────────────────────


# ``_TMP_ROOT_PREFIX`` and ``_tmp_root_prefix_for_run`` are defined ABOVE the
# import-time data-home floor rather than here, beside their main consumer, because
# ``_create_host_home_floor`` calls the helper at conftest IMPORT time -- long before
# this line executes -- to name the floor after the run that made it. Everything else
# about the run's temp naming stays in this section.


def _create_tmp_root(parent: pathlib.Path) -> pathlib.Path:
    """Create this run's temp root under *parent*, atomically and unguessably.

    ``mkdtemp`` rather than ``mkdir(exist_ok=True)`` on a name derived from the pid, and
    the difference is a local privilege boundary rather than a style choice. The platform
    temp root is world-writable with a sticky bit on POSIX, and a pid-derived name is
    PREDICTABLE -- so another local account can pre-create that exact name as a SYMLINK to
    a directory it controls. ``mkdir(..., exist_ok=True)`` succeeds against a
    symlink-to-directory, the session redirect then follows it, and every temp write in
    the run -- including whatever secrets a test fixture fabricates -- lands somewhere the
    other account chose and can read.

    ``mkdtemp`` closes that in three ways at once: it appends a random component, so the
    name cannot be guessed ahead of time; it creates with ``O_EXCL``, so it fails rather
    than adopting anything that already exists; and it sets mode ``0o700``, so the
    directory is unreadable to other accounts once made. It also makes the name
    UNPREDICTABLE to this suite, which is what lets the invariant below hold: a run can
    only ever name the root it created itself.

    The pid stays in the name for a human reading a stray directory, not for machinery:
    nothing parses it. See :func:`_isolate_tempfile_base` for why this run never touches a
    root it did not create.
    """
    return pathlib.Path(tempfile.mkdtemp(prefix=_tmp_root_prefix_for_run(), dir=parent))


#: Env var carrying this run's SHORT temp root, so xdist workers reuse the controller's.
_SHORT_TMP_ROOT_ENV = "KIROCREW_TEST_SHORT_TMP_ROOT"

#: The temp roots THIS process created, captured at creation. The bytecode-mirror prune
#: reads this instead of ``tempfile.gettempdir()``, which by session teardown has been
#: restored to the platform temp root -- a mirror shared with every concurrent run.
_RUN_TEMP_ROOTS: list[str] = []

#: Set only in the process that CREATED the short root, so a worker never removes it.
_SHORT_TMP_ROOT_OWNED: str | None = None


def _install_short_tmp_root() -> None:
    """Mint one run-owned SHORT temp root and publish it for the whole run.

    A handful of fixtures cannot use ``tmp_path``: an ``AF_UNIX`` ``sun_path`` caps the
    bind/connect STRING at 108 bytes on Linux and 104 on macOS, and a path asserted in
    message metadata must not trip ``redact_credentials()`` (a macOS ``tmp_path`` carries
    high-entropy directory ids that do). Those fixtures reached for a literal ``/tmp``,
    which put ~40 anonymous ``/tmp/tmpXXXX`` and ``/tmp/kcsock-XXXX`` directories on the
    host, owned by nobody: the residue guard's allow-list and the hygiene probe both
    recognise the ``kc-pytest-<user>-<pid>-`` stem and nothing else, so a stray directory
    spelled any other way names no run and no test.

    ``tempfile.gettempdir()`` cannot serve here, which is the whole reason this root
    exists separately: under a long ``TMPDIR`` -- the run's own isolated base, a harness
    that pins ``TMPDIR`` under the checkout -- ``<base>/kcsock-xxxxxxxx/gw-prewarm.sock``
    is already past ``sun_path`` before a filename is appended (measured at 122 bytes
    against the 108-byte cap), and ``test_mcp_gateway_transport``'s ``_SUN_PATH_BUDGET``
    test goes red. So the root is created under the PLATFORM temp root, where the path is
    short by construction, and carries the run's own stem so it is attributable.

    Created in ``pytest_configure`` and published through the environment: an xdist worker
    is a child of the controller, inherits the variable, and therefore shares the one root
    instead of minting its own. Only the creating process removes it (``_SHORT_TMP_ROOT_OWNED``).
    """
    global _SHORT_TMP_ROOT_OWNED
    if os.environ.get(_SHORT_TMP_ROOT_ENV):
        return  # an xdist worker (or a nested session): the controller already made it
    parent = None if os.name == "nt" else "/tmp"
    if parent is not None and not os.path.isdir(parent):
        parent = None  # unusual POSIX host; the platform default still satisfies both rules
    try:
        root = tempfile.mkdtemp(prefix=f"{_tmp_root_prefix_for_run()}short-", dir=parent)
    except OSError:
        return  # no short root available; short_tmp_base() falls back to its old behaviour
    # No chmod: ``mkdtemp`` already creates the directory 0o700, which is what this root
    # needs in a world-writable temp dir. Setting it again only invites a permissions
    # linter to argue about a mode the stdlib picked.
    os.environ[_SHORT_TMP_ROOT_ENV] = root
    _SHORT_TMP_ROOT_OWNED = root


def _remove_short_tmp_root() -> None:
    """Remove the short root, but only in the process that created it."""
    global _SHORT_TMP_ROOT_OWNED
    root, _SHORT_TMP_ROOT_OWNED = _SHORT_TMP_ROOT_OWNED, None
    if root:
        shutil.rmtree(root, ignore_errors=True)
        if os.environ.get(_SHORT_TMP_ROOT_ENV) == root:
            del os.environ[_SHORT_TMP_ROOT_ENV]


#: Env vars ``tempfile`` consults, so a CHILD process inherits the redirect too.
#: A test that spawns a helper which writes to its temp dir would otherwise put
#: that file in the real ``/tmp``, where nothing prunes it.
_TMP_ENV_VARS = ("TMPDIR", "TEMP", "TMP")

#: Opt-in diagnostic: give every test its OWN temp base, named after the test.
#:
#: Off by default because a directory per test is precisely the per-test cost the
#: suite's fixture audit exists to avoid (paid ~26.5k times). It is the escape hatch
#: for the one question the session-scoped guard below cannot answer: a single stray
#: directory in a 26k-test run names no culprit. Re-run the suspect subset with
#: ``KIROCREW_TMP_PER_TEST=1`` and the residue's parent directory IS the test id.
_TMP_PER_TEST_ENV = "KIROCREW_TMP_PER_TEST"

#: Whether this run is in that mode, read ONCE at conftest import.
#:
#: Read here rather than per test because it decides whether the per-test fixture below
#: is DEFINED at all, and an autouse fixture that exists costs whether or not its body
#: does anything: its name joins the fixture closure of every collected item (~106 bytes
#: each, so ~5.8 MiB per xdist worker retained for the whole session) and the fixture
#: protocol sets it up once per test (~50us, ~3 CPU-seconds across a full run). A
#: whole-run operator switch is the right thing to read once: each xdist worker is a
#: fresh process that inherits the environment, so the answer cannot differ between the
#: registration decision and the teardown that reads it.
_TMP_PER_TEST = bool(os.environ.get(_TMP_PER_TEST_ENV))

#: Names under the run's temp base that are NOT this suite's residue.
#:
#: Each entry is something OTHER than a test creating a directory it forgot to remove,
#: which is the only thing this guard is about. Measured from CI, where the surfaces this
#: developer host cannot reach are exercised:
#:
#: * ``pytest-of-`` -- a NESTED pytest's own ``basetemp`` tree. Several tests spawn one,
#:   and it resolves ``gettempdir()`` after the redirect has taken effect, so it computes
#:   its basetemp inside ours. A child runner's bookkeeping, with its own retention.
#: * ``kirocrew-computer-shots`` -- the computer-use screenshot spool, which production
#:   deliberately keeps under ``tempfile.gettempdir()`` as a persistent ring buffer
#:   (pinned by ``test_computer_use_capture.py``). Long-lived BY DESIGN, so its presence
#:   is the feature working, not a test leaking.
#: * ``playwright-`` / ``.org.chromium.`` -- created by the browser and its driver, which
#:   inherit the redirected ``TMPDIR`` like any other child. Third-party scratch this
#:   suite does not own and cannot register cleanup for.
_TMP_RESIDUE_ALLOWED_PREFIXES: tuple[str, ...] = (
    "pytest-of-",
    "kirocrew-computer-shots",
    "playwright-",
    ".org.chromium.",
)

#: Make temp residue FAIL the run rather than warn.
#:
#: Off by default, and that is a staged rollout rather than a soft opinion. The guard
#: found real residue on CI surfaces this host cannot reach, and the entries that remain
#: after the exclusions above are single ``mkstemp`` FILES rather than the ``mkdtemp``
#: directories the rule is written about -- one inode each, several of them created by
#: production code a test merely reached. Failing the suite on that set today would block
#: every unrelated change while the set is attributed, and a guard that blocks unrelated
#: work is a guard somebody deletes.
#:
#: So: the residue is removed either way (which is the whole inode win), and it is
#: REPORTED either way. Set this to make it fatal -- in a burn-down branch, or in CI once
#: the remaining set is empty. Same shape as ``windows-expected-failures.txt``: a known
#: set, visible, with a way to hold the line once it is closed.
_TMP_RESIDUE_STRICT_ENV = "KIROCREW_TMP_RESIDUE_STRICT"


def _redirect_tempfile_base(base: pathlib.Path) -> None:
    """Point ``tempfile`` AND every child process at *base*.

    ``tempfile.tempdir`` is the module global ``gettempdir()`` memoises into, so
    assigning it directly is what covers code already holding a reference to the
    module; the env vars are what cover a child process, which re-derives its own.
    Both are needed: patching only the global leaves subprocess writes in the real
    temp dir, and setting only the env vars is a no-op for a process that already
    resolved ``gettempdir()`` once.

    All three names are set because the platforms disagree on which one is real:
    ``TMPDIR`` is the POSIX spelling and ``TEMP``/``TMP`` are what Windows and the
    tools spawned there read. Setting a name the running platform ignores is inert,
    so there is no need to branch.
    """
    base.mkdir(parents=True, exist_ok=True)
    tempfile.tempdir = str(base)
    for name in _TMP_ENV_VARS:
        os.environ[name] = str(base)


def _remove_tree(path: pathlib.Path) -> bool:
    """Delete *path*, defeating Windows read-only files. True when it is gone.

    ``shutil.rmtree(..., ignore_errors=True)`` is the reflexive spelling and it is the
    WRONG one here: on Windows a mode-444 file cannot be unlinked, a git checkout is
    full of them (loose objects are written read-only), and ``ignore_errors`` swallows
    every such failure so the caller reports success over a tree still on disk. Five
    test modules combine a bare ``mkdtemp()`` with a real ``git`` spawn, so that is not
    hypothetical. ``platform_compat.rmtree_force`` clears the attribute and retries, and
    returns a filesystem-derived boolean rather than the hook's opinion.
    """
    try:
        from kiro_crew import platform_compat as _pc
    except ImportError:  # pragma: no cover - partial checkout
        shutil.rmtree(path, ignore_errors=True)
        return not path.exists()
    return _pc.rmtree_force(path)


def _stop_git_discovery_above_the_temp_roots(base, tmp_path_factory) -> None:
    """Fence git's repository discovery at this run's temp roots.

    A test that builds "a directory that is not a repository" under ``tmp_path`` is
    asserting a property of the HOST unless something bounds git's upward walk: when the
    temp root sits inside a checkout -- an operator with ``TMPDIR=./tmp``, a harness that
    pins its scratch under the worktree -- ``git rev-parse`` climbs out of ``tmp_path`` and
    answers about the enclosing repository instead. The 2026-09-20 sweep measured 66 tests
    failing exactly that way across two clusters, and the shape is worse in a LINKED
    worktree, where the ``.git`` the walk finds is a FILE and a marker-based probe declines
    before the arm under test ever runs.

    ``GIT_CEILING_DIRECTORIES`` is git's own seam for this and is read by every ``git``
    child the suite spawns, so one write here covers the production helpers a test cannot
    reach. Per-site fixtures still exist and are still correct -- they document intent, and
    they cover the walks this cannot fence (an ``install.sh`` marker search, a nested pytest
    session's ``rootdir``) -- but this is what keeps the NEXT test from inheriting the
    checkout by default. Absolute, symlink-resolved paths: git ignores a ceiling entry that
    is not both.
    """
    entries: list[str] = []
    for candidate in (base, tmp_path_factory.getbasetemp(), os.environ.get(_SHORT_TMP_ROOT_ENV)):
        if not candidate:
            continue
        try:
            resolved = os.path.realpath(str(candidate))
        except OSError:  # pragma: no cover - unreadable temp root
            continue
        if resolved not in entries:
            entries.append(resolved)
    existing = os.environ.get("GIT_CEILING_DIRECTORIES")
    if existing:
        entries.append(existing)
    if entries:
        os.environ["GIT_CEILING_DIRECTORIES"] = os.pathsep.join(entries)


@pytest.fixture(scope="session", autouse=True)
def _isolate_tempfile_base(tmp_path_factory):
    """Give the run its own ``tempfile`` base, then report and remove what leaked.

    AUTOSDE forbids a bare ``tempfile.mkdtemp()`` / ``TemporaryDirectory()`` whose
    destruction is not registered in the same scope, because those directories
    survive the run and accumulate across runs until they exhaust inodes -- MEASURED
    on this host, a ``/tmp`` tmpfs with a fixed 1,048,576-inode budget starts
    returning ENOSPC to unrelated processes with 90% of its BYTES still free.
    Enforcing that per call site is a contract every new test has to remember, and
    the shape that breaks it is invisible when reading the test:
    ``unittest.TestCase`` tearDown does NOT run when setUp raises, so a ``setUp:
    mkdtemp()`` paired with a ``tearDown: rmtree()`` leaks on every setUp failure --
    and it is the FAILING run, the one nobody is watching closely, that leaves the
    residue.

    Redirecting the base fixes the class instead of the call sites: whatever the suite
    creates without cleaning up lands in one directory this fixture owns, so the teardown
    can both NAME it (residue is still a defect) and REMOVE it (so the accumulation stops
    regardless of whether anyone acts on the report).

    The report WARNS by default and fails only under ``KIROCREW_TMP_RESIDUE_STRICT`` --
    see ``_TMP_RESIDUE_STRICT_ENV`` for why that is a staged rollout and not a shrug.

    Under ``-n auto`` each xdist worker is its own process, so each gets its own
    root and reports only its own leaks; the controller runs no tests and creates
    none.

    **A run only ever deletes the root it created itself.** There is deliberately no sweep
    of other roots, and that is a design decision rather than an omission. Reclaiming a
    root left by a killed run means deciding that some OTHER directory is abandoned, and
    every available signal for that is unsound: the name can be pre-created by another
    local account, and a pid is meaningless across PID namespaces -- two containers sharing
    a bind-mounted temp directory can each hold the same pid, so "that process is gone" is
    a statement about the wrong namespace and the reward for getting it wrong is deleting
    a live run's data. The platform already owns this job (``systemd-tmpfiles`` on a timer,
    macOS's periodic cleanup, and a tmpfs cleared on reboot), and it owns it with
    information this process does not have. So a run killed before its teardown leaves one
    directory behind for the platform to reclaim -- bounded, and far smaller than the
    375,780-inode-per-run accumulation this redirect removes.

    **Why the platform's own temp dir rather than pytest's ``basetemp``.** Nesting
    under ``basetemp`` would have been tidier -- pytest already prunes it -- but it
    adds ``pytest-of-<user>/pytest-<n>/popen-gw<k>/`` to the front of every
    ``mkdtemp()`` path in the suite, roughly 60 characters. Windows still caps a
    path at 260 unless long paths are enabled, and a macOS ``AF_UNIX`` ``sun_path``
    is capped at ~104 bytes, so that nesting would trade an inode leak for a
    platform-specific path-length failure. A sibling of the platform temp root named
    ``kc-pytest-<pid>`` is SHORTER than what pytest's own ``tmp_path`` already
    hands out, so no existing path gets longer on any platform.

    Two things deliberately stay outside the redirect:

    * ``test/tmpdir_helpers.short_tmp_base()`` forces ``/tmp`` on POSIX, because
      macOS's per-user temp root alone already exceeds the ``AF_UNIX`` cap. Those
      sites clean up after themselves.
    * A test that patches ``tempfile.gettempdir`` or passes its own ``dir=`` still
      wins, as it should.
    """
    # Resolve pytest's basetemp FIRST, and discard the value: the call is what matters.
    # pytest computes basetemp lazily from `tempfile.gettempdir()` on first use, so
    # forcing it now pins it OUTSIDE the redirect below. Skip this and pytest's whole
    # basetemp lands INSIDE the run's temp root, where the teardown here would delete
    # it -- taking with it every failed test's retained `tmp_path`, which
    # `tmp_path_retention_policy = failed` exists to keep -- and adding ~25 characters
    # to every temp path in the suite, straight into the Windows 260-character cap and
    # the macOS AF_UNIX 104-byte cap. That ordering was previously accidental: an
    # unrelated fixture 300 lines above happened to call `mktemp` first.
    tmp_path_factory.getbasetemp()
    previous_tempdir = tempfile.tempdir
    previous_env = {name: os.environ.get(name) for name in _TMP_ENV_VARS}
    parent = pathlib.Path(tempfile.gettempdir())
    base = _create_tmp_root(parent)
    # Record the root at CREATION. The bytecode-mirror prune runs from
    # ``pytest_sessionfinish``, which is AFTER this fixture's finalizer has restored
    # ``tempfile.tempdir``: reading ``tempfile.gettempdir()` there resolves to the platform
    # temp root, and pruning that mirror would delete every concurrent run's bytecode.
    _RUN_TEMP_ROOTS.append(str(base))
    _redirect_tempfile_base(base)
    previous_ceiling = os.environ.get("GIT_CEILING_DIRECTORIES")
    _stop_git_discovery_above_the_temp_roots(base, tmp_path_factory)
    try:
        yield base
    finally:
        if previous_ceiling is None:
            os.environ.pop("GIT_CEILING_DIRECTORIES", None)
        else:
            os.environ["GIT_CEILING_DIRECTORIES"] = previous_ceiling
        tempfile.tempdir = previous_tempdir
        for name, value in previous_env.items():
            if value is None:
                os.environ.pop(name, None)
            else:
                os.environ[name] = value
        # The same value the per-test fixture's REGISTRATION was decided on, so the
        # scan depth here cannot disagree with whether that fixture ever ran.
        per_test = _TMP_PER_TEST
        leaked = _tmp_residue(base, per_test=per_test)
        # Removed even when it is empty, and even when the report below raises:
        # leaving the root behind would itself be the accumulation this guards.
        _remove_tree(base)
        if not leaked:
            return
        report = _tmp_residue_report(base, leaked, per_test=per_test)
        if os.environ.get(_TMP_RESIDUE_STRICT_ENV):
            raise AssertionError(report)
        warnings.warn(report, stacklevel=1)


def _tmp_residue(base: pathlib.Path, *, per_test: bool) -> list[str]:
    """Names left under *base*, excluding what is not a leak.

    In per-test mode the immediate children are the per-test bases the fixture itself
    created, so the scan descends one level and reports ``<test id>/<name>``. Without
    that, every test in the run would be reported as its own leak and the mode would
    answer nothing. The allow-list is applied to the LEAF in that mode: the by-design
    entries it names (the screenshot spool, a nested basetemp) land inside the per-test
    base, so matching only the base's name would report every one of them as a leak
    of the test that happened to reach the feature.
    """
    try:
        children = sorted(base.iterdir())
    except OSError:
        return []
    residue: list[str] = []
    for child in children:
        if child.name.startswith(_TMP_RESIDUE_ALLOWED_PREFIXES):
            continue
        if not per_test:
            residue.append(child.name)
            continue
        try:
            residue.extend(
                f"{child.name}/{leaf.name}"
                for leaf in sorted(child.iterdir())
                if not leaf.name.startswith(_TMP_RESIDUE_ALLOWED_PREFIXES)
            )
        except OSError:
            continue
    return residue


def _tmp_residue_report(base: pathlib.Path, leaked: list[str], *, per_test: bool) -> str:
    """The message naming what the run left behind, and how to find its owner."""
    shown = leaked[:20]
    more = f"    ... and {len(leaked) - len(shown)} more\n" if len(leaked) > len(shown) else ""
    hint = (
        "Each name above is a test id, so the leak is in that test."
        if per_test
        else f"Re-run the suspect subset with {_TMP_PER_TEST_ENV}=1 and each residue "
        f"name becomes the id of the test that leaked it."
    )
    return (
        f"{len(leaked)} temporary entr{'y' if len(leaked) == 1 else 'ies'} outlived "
        f"this run under {base}:\n"
        + "".join(f"    {name}\n" for name in shown)
        + more
        + "\nThis is reported at session teardown, so it is attributed to the last "
        "test this worker ran -- that test is almost certainly NOT the culprit.\n"
        "A test must register the destruction of anything it creates in the SAME "
        "scope. Use pytest's tmp_path, or pair every tempfile.mkdtemp() with "
        "self.addCleanup(shutil.rmtree, path, ignore_errors=True) on the line "
        "after it -- NOT an rmtree in tearDown, which unittest skips entirely when "
        "setUp raises.\n" + hint
    )


if _TMP_PER_TEST:

    @pytest.fixture(autouse=True)
    def _isolate_tempfile_base_per_test(_isolate_tempfile_base, request):
        """Opt-in: give this test its own temp base so a leak names its own test.

        DEFINED only in that mode, rather than defined always with an env-guarded early
        return, so the steady-state cost is zero rather than "one environment read per
        test". The read was never the expensive half: an autouse fixture that exists is
        added to the fixture closure of every collected item (~106 bytes per item, ~5.8
        MiB per xdist worker held for the whole session) and goes through setup/teardown
        once per test (~3 CPU-seconds across a full run) even when its body returns
        immediately -- which, since nothing in the tree sets the variable, it did 100% of
        the time. See ``_TMP_PER_TEST``; the diagnostic itself is unchanged.

        Named from the NODEID, not ``node.name``. The bare function name carries no module
        or class, and 807 function names are duplicated across this suite (``test_defaults``
        appears 17 times, ``test_invalid_json_is_400`` 29), so a name-keyed directory would
        report a leak against a name shared by dozens of tests -- answering the wrong
        question in the one mode that exists to answer it precisely. The nodeid is kept
        TAIL-first under the length cap, because the distinguishing part is at the end.
        """
        safe = "".join(ch if (ch.isalnum() or ch in "-._") else "_" for ch in request.node.nodeid)
        _redirect_tempfile_base(_isolate_tempfile_base / safe[-100:])


# ── the operator's data home is host state too ────────────────────────


@pytest.fixture(scope="session")
def _isolation_root(tmp_path_factory):
    """One session-scoped parent for the per-test isolation dirs below.

    ``tmp_path_factory.mktemp`` picks its numbered suffix by scanning the whole
    basetemp, so its cost grows with the number of entries already there. The
    autouse fixtures that need a directory ``mkdir`` under this root instead, which
    is a single syscall and does not scan.

    Named ``i`` rather than something descriptive to keep the paths short: Windows
    still caps a path at 260 characters unless long paths are enabled, and
    everything a test writes under ``KIROCREW_HOME`` nests inside here.
    """
    return tmp_path_factory.mktemp("i")


@pytest.fixture
def _isolation_dirs(_isolation_root):
    """Return an allocator for this test's isolation PATHS.

    Each call returns ``<root>/<counter>-<name>``, so one test's paths cannot collide
    with another's (the counter is per-process, and pytest-xdist gives every worker
    its own ``basetemp``). Flat rather than nested, to keep Windows paths short.

    **A path, not a directory: nothing is created.** Every consumer only needs somewhere
    to POINT, and creates the directory itself if it ever writes -- ``config_dir()``
    creates the data home, ``create_agent_folder`` creates the subagent registry,
    ``OLLAMA_MODELS`` is only ever read. Creating them eagerly cost a ``mkdir`` per name
    on every test and left the directories behind for the whole session, because they are
    not ``tmp_path`` dirs and no retention policy reaches them.

    MEASURED on one full ``test/`` run at ``-n 8``: 366,716 of the run's 372,126
    basetemp inodes -- 98.5% -- were these directories, ~317k of them empty. On a
    ``/tmp`` tmpfs with a fixed 1,048,576-inode budget that is a third of the machine's
    entire allowance spent on directories nothing ever opened, and it is what made a
    second concurrent run fail with ENOSPC while 90% of the bytes were free.

    A future consumer that genuinely needs the directory to exist should ``mkdir`` at its
    own call site, where the reason is visible, rather than through a flag here.
    """
    made: dict[str, pathlib.Path] = {}
    _isolation_dirs.seq += 1  # type: ignore[attr-defined]
    stem = _isolation_dirs.seq  # type: ignore[attr-defined]

    def _get(name: str) -> pathlib.Path:
        path = made.get(name)
        if path is None:
            path = _isolation_root / f"{stem}-{name}"
            made[name] = path
        return path

    return _get


_isolation_dirs.seq = 0  # type: ignore[attr-defined]


#: Set on an item by ``_isolate_kirocrew_home`` once its pins are in force. The
#: teardown check reads it: a test skipped at setup (a ``skipif`` marker) never ran
#: the floor, so ``paths._resolved_home`` still holds whatever collection resolved
#: (the operator's real home, legitimately) and must not be blamed for it.
_HOME_PIN_ARMED = pytest.StashKey[bool]()


@pytest.fixture(autouse=True)
def _isolate_kirocrew_home(request, _isolation_dirs, _floor_monkeypatch):
    """Pin ``KIROCREW_HOME`` and ``KIROCREW_WORKSPACE`` to per-test tmp dirs, for EVERY testpath.

    The pin is applied through a PRIVATE ``pytest.MonkeyPatch`` instance, not the
    shared function-scoped ``monkeypatch`` fixture. The shared instance is one undo
    stack for every fixture and helper the test touched, so a test helper that calls
    ``monkeypatch.undo()`` to revert its own patch also reverts THIS pin -- and every
    path the test resolves afterwards lands in the operator's live ``~/.kiro/crew``.
    That is not hypothetical: a memory-store test did exactly that and then wrote
    ``b"this is not a sqlite database"`` over an operator's real 36 MB ``memory.db``,
    which had no backup. With its own instance the pin can only be undone by this
    fixture's teardown. The public ``monkeypatch`` fixture depends on
    ``_floor_monkeypatch``, so the test's overrides unwind before the floor and a
    later shared undo cannot reinstall a stale per-test home.

    This lives at the rootdir rather than in ``test/conftest.py`` because the leak it
    closes is worst in the testpaths that conftest does not reach. The ~108 test
    modules under ``src/kiro_crew/apps/builtins/*/tests/`` ship inside the package and
    see only this file, so before this fixture existed here any of them that touched
    ``config_dir()`` resolved the operator's live data home -- and that resolution is
    not read-only: ``config_dir()`` CREATES the home and its marker on first use, and
    can run the one-time ``~/.kirocrew`` -> ``~/.kiro/crew`` migration as a side
    effect. Two of the eight app suites had grown their own redirect fixture; the
    other six had not, which is exactly the "remember to" contract this file exists to
    delete.

    A test that sets its own ``KIROCREW_HOME`` still wins: ``monkeypatch.setenv``
    applied later in setup overrides this, and reverts independently.

    ``config.paths._resolved_home`` is reset with it. ``config_dir()`` memoises the
    resolved home in that module global for the process lifetime, and under xdist one
    worker runs thousands of tests in one process, so a value cached by an earlier
    test would otherwise leak into a later one. Resetting it also invalidates
    ``_config_dir_memo``, which is keyed on that global by identity.

    ``KIROCREW_PROJECT_DIR`` is cleared for a different reason -- to match CI on a dev
    box. It is auto-set to the repo root when running from a checkout, so
    ``skills._project_skills_dir()`` resolves the repo's real ``skills/`` and a test
    driving ``_ensure_builtin_skills`` against a tmp dir sees live skills as a
    "source", flipping relocation behaviour: green in CI, red locally.

    ``KIROCREW_BOUND_PORT`` is cleared because ``_export_bound_port`` writes it into
    the real process environment when a test boots a server, so a port exported by one
    test would leak into every later test's port resolution on that worker.
    ``KIROCREW_DEV_MODE`` / ``KIROCREW_STRICT_ON_LOOP_PERSIST`` are cleared so a
    developer who exports them does not flip the off-loop-IO guards strict for the
    whole suite.

    ``KIRO_HOME`` is deliberately NOT pinned here, even though the lazy
    ``config.paths.kiro_home()`` does name the operator's real machine-wide kiro-cli
    home. The env var takes precedence over ``Path.home()`` by design, and ~35 tests
    isolate that resolver the other way round -- ``patch("pathlib.Path.home",
    return_value=tmp_path)`` -- so pinning the variable overrides their own isolation
    and they read an empty directory instead of the tree they just built. A test that
    reaches ``kiro_home()`` therefore isolates it itself, with whichever of the two
    levers it already uses.

    ``KIROCREW_WORKSPACE`` is pinned alongside ``KIROCREW_HOME`` for the same
    reason as the rest of this fixture: ``config.loader.workspace_root()`` is its
    own default, independent of ``config_dir()`` -- with no override and no saved
    ``<config_dir>/workspace_dir`` file it falls back to the platform's
    ``_default_workspace_base()`` plus ``kirocrew-workspace``, which on Linux/macOS
    is the operator's real ``~/workplace``. Any test that reaches an agent working
    directory (``workspace_root()``, ``_session_work_dir()``, ``outbox_dir()``)
    without setting its own ``KIROCREW_WORKSPACE`` therefore ``mkdir``s and writes
    into that real tree. Unlike ``config_dir()``, ``workspace_root()`` reads the env
    var fresh on every call and caches nothing, so there is no module-global memo to
    reset here -- setting the variable is the whole fix.

    ``KIROCREW_POD_ROOT`` and ``KIROCREW_POD_ENV_DIR`` are pinned for the same reason
    again, and this one is BY DESIGN unreachable from ``KIROCREW_HOME``:
    ``pod.config.PodConfig.load()`` derives ``pods_dir`` from ``_default_home()`` --
    the operator's real ``~/.kiro/crew/pods`` -- precisely so a pod process running
    with its own isolated ``KIROCREW_HOME`` cannot redirect the HOST's pod registry
    into a throwaway home, and ``pod_root`` from ``Path.home()/.kirocrew-pods``. Both
    are read fresh from the environment on every ``load()``. Without this pin a test
    that boots a pod, or records a refusal, writes ``<name>.env`` / ``<name>.refused``
    into the operator's real pod plane: five full-suite runs left
    ``~/.kiro/crew/pods/viability-*.refused`` behind on the developer's machine, from
    a fixture that was simply ``PodConfig.load()``. ``test_pod.py::TestConfig::
    test_defaults`` still asserts the unpinned defaults -- it clears every
    ``KIROCREW_POD_*`` variable itself first, which is the documented way to test
    the default resolution.
    """
    monkeypatch = _floor_monkeypatch
    monkeypatch.setenv("KIROCREW_HOME", str(_isolation_dirs("kirocrew-home")))
    monkeypatch.setenv("KIROCREW_WORKSPACE", str(_isolation_dirs("workspace")))
    monkeypatch.setenv("KIROCREW_POD_ROOT", str(_isolation_dirs("pod-root")))
    monkeypatch.setenv("KIROCREW_POD_ENV_DIR", str(_isolation_dirs("pods")))
    # Cleared for the test AND removed again at teardown. ``monkeypatch.delenv`` on a
    # variable that is absent records no undo, so a value the code under test WRITES
    # -- ``_export_bound_port`` publishing KIROCREW_BOUND_PORT when a server boots,
    # ``cli.main`` pinning KIROCREW_PROJECT_DIR -- outlived its test and reached the
    # next one on the worker (observed for both in a full run). Recording the
    # absence first makes teardown delete whatever landed.
    for _name in (
        "KIROCREW_PROJECT_DIR",
        "KIROCREW_BOUND_PORT",
        "KIROCREW_DEV_MODE",
        "KIROCREW_STRICT_ON_LOOP_PERSIST",
    ):
        if _name in os.environ:
            monkeypatch.delenv(_name)
        else:
            monkeypatch.setenv(_name, "")  # the undo for this entry is "was absent"
            monkeypatch.delenv(_name)
    _reset_path_resolver_degradation(monkeypatch)
    paths = sys.modules.get("kiro_crew.config.paths")
    if paths is not None:
        monkeypatch.setattr(paths, "_resolved_home", None, raising=False)
        monkeypatch.setattr(
            paths,
            "_write_recovery_breadcrumb",
            _breadcrumb_guard(paths._write_recovery_breadcrumb),
            raising=False,
        )
    request.node.stash[_HOME_PIN_ARMED] = True


def _reset_path_resolver_degradation(monkeypatch) -> None:
    """Give every test an unstalled sensitive-path resolver, and leave none behind.

    ``security.paths`` remembers resolver degradation and cumulative wait in four
    PROCESS-GLOBAL structures, and a charged prefix makes ``is_sensitive_path()``
    answer True for every path beneath it, without touching the filesystem, until
    the cooldown lapses. Since ``_stall_prefix`` keys on the mount, one test whose
    resolution is merely slow on a loaded runner can therefore fail every LATER
    test on the same xdist worker whose paths live under the same prefix -- observed
    as 77 ``ArtifactError: refusing to use sensitive path as artifact root`` errors
    across four unrelated files on one Windows shard, from a single charged stall.
    Resetting on both sides makes that cascade impossible to inherit and impossible
    to export, so a test that provokes a stall on purpose still sees only its own.

    ``_path_resolve_degraded`` and ``_path_resolve_wedged`` are re-exported by the
    ``kiro_crew.security`` facade, so they are set THROUGH it: the facade mirrors a
    write onto the owning submodule, while patching the owner alone would leave the
    facade holding the original object and break the export-identity contract
    ``test_security_facade`` pins. ``_path_resolve_load_probes`` and
    ``_path_resolve_thread_waits`` are NOT re-exported, so they must be set on the
    submodule -- a facade write for those names would mirror nowhere and silently
    do nothing.
    """
    security = sys.modules.get("kiro_crew.security")
    paths = sys.modules.get("kiro_crew.security.paths")
    if security is not None:
        monkeypatch.setattr(security, "_path_resolve_degraded", {}, raising=False)
        monkeypatch.setattr(security, "_path_resolve_wedged", [], raising=False)
    if paths is not None:
        monkeypatch.setattr(paths, "_path_resolve_load_probes", {}, raising=False)
        monkeypatch.setattr(paths, "_path_resolve_thread_waits", {}, raising=False)


def _breadcrumb_guard(real):
    """Refuse the recovery breadcrumb while ``Path.home()`` is the operator's.

    ``config_dir()`` on its DEFAULT path writes ``~/.kirocrew.breadcrumb`` (outside
    ``~/.kiro`` on purpose) naming the home it resolved. A test that relocates the
    default with ``paths._resolve_default_home = lambda: tmp_path / ...`` and nothing
    else therefore rewrites the operator's real breadcrumb to point at a pytest tmp
    dir: the third audit found six such writes per run, each repaired only because
    the live gateway rewrote the file later. The teardown check cannot see this one
    (``_resolved_home`` holds the tmp stand-in), so the guard sits on the writer:
    with ``Path.home()`` still the real home it FAILS the test naming the fix; with
    a faked home (``monkeypatch.setattr(Path, "home", ...)``) it delegates, so the
    tests OF the breadcrumb keep exercising the real writer against their fake home.
    """

    def _guarded(data_home):
        try:
            home_is_real = pathlib.Path.home().resolve() == _REAL_USER_HOME.resolve()
        except OSError:  # pragma: no cover - a faked home that does not exist
            home_is_real = False
        if home_is_real:
            raise AssertionError(
                "this test would write the operator's real ~/.kirocrew.breadcrumb "
                f"(pointing it at {data_home}): the default-home path was taken with "
                "Path.home() still the real home. Relocate the WHOLE default, not just the "
                "resolver: monkeypatch HOME and pathlib.Path.home to a dir under tmp_path, "
                "or stub paths._write_recovery_breadcrumb when the breadcrumb is not what "
                "the test is about; see conftest._breadcrumb_guard."
            )
        return real(data_home)

    return _guarded


def _is_the_operators_default_home(path) -> bool:
    """Whether *path* is the real ``~/.kiro/crew`` (not a tmp stand-in for it)."""
    try:
        return pathlib.Path(path).resolve() == (_REAL_USER_HOME / ".kiro" / "crew").resolve()
    except OSError:
        return False


def _resolved_real_default_home():
    """The operator's real home if ``paths._resolved_home`` holds it right now, else None."""
    paths = sys.modules.get("kiro_crew.config.paths")
    resolved = getattr(paths, "_resolved_home", None) if paths is not None else None
    if resolved is not None and _is_the_operators_default_home(resolved):
        return resolved
    return None


def _refuse_a_resolved_real_default_home(resolved) -> None:
    """Fail the test that let ``config_dir()`` fall through to the operator's home.

    ``paths._resolved_home`` is only ever written by ``_resolve_default_home()``, i.e.
    by a ``config_dir()`` / ``data_home()`` call made with NO override in force. So a
    value equal to the operator's real ``~/.kiro/crew`` at teardown means the test
    dropped the pin (``monkeypatch.delenv("KIROCREW_HOME")``) to exercise the default
    path and let production resolve, and CREATE, the real data home, plus the
    recovery breadcrumb beside it. Five tests did in the third full-run audit; each
    passed. A test of the default path relocates the default too
    (``monkeypatch.setattr(paths, "_resolve_default_home", lambda: tmp_path / "d")``,
    or ``_resolved_home`` itself); ``test_lazy_data_home_paths.py`` is the shape.

    The evidence is read by ``pytest_runtest_teardown`` BEFORE the test's own
    ``monkeypatch`` unwinds (a test that set ``_resolved_home = None`` through
    monkeypatch and then resolved the real home would otherwise have it restored to
    ``None`` before any fixture could look), and the failure is raised AFTER every
    fixture has been torn down, so the floor's pins are always restored. One attribute
    read and one path comparison per test, so it costs nothing on the ~92k tests that
    never touch the global.
    """
    raise AssertionError(
        "this test resolved the operator's REAL default data home "
        f"({resolved}): it dropped the KIROCREW_HOME pin and let config_dir() / "
        "data_home() fall through to ~/.kiro/crew, which CREATES that directory. "
        "A test of the default path pins the default too: "
        "monkeypatch.setattr(kiro_crew.config.paths, '_resolve_default_home', "
        "lambda: tmp_path / 'default'); see test_lazy_data_home_paths.py and "
        "conftest._refuse_a_resolved_real_default_home."
    )


@pytest.fixture(autouse=True, scope="session")
def _isolate_sel_default_dir(tmp_path_factory):
    """Redirect the Security Event Log's default dir to a session-local tmp dir.

    SEL is a process SINGLETON whose writer is a DAEMON THREAD, and
    ``_init_locked`` binds ``self._dir`` once, from whatever ``_default_dir()``
    resolved at that moment. Two consequences, and the second is why this belongs at
    the rootdir rather than in ``test/conftest.py``:

    * Every event any test emits through the default ``sel()`` appends to ONE file.
      Unredirected that is the operator's real ``security_events.jsonl`` -- a
      non-atomic append, shared across xdist workers.
    * Whichever test calls ``sel()`` FIRST fixes the directory for the whole
      process, and the writer thread keeps using it after that test ends. When the
      first caller is a test whose home is a per-test tmp dir, the thread outlives
      the tmp dir and RE-CREATES it on the next flush -- ``_flush_batch`` opens with
      ``self._dir.mkdir(parents=True, exist_ok=True)``. So the directory reappears
      *after* the test's own cleanup removed it, and no amount of tidying in the
      test can win against a thread that rebuilds the path. MEASURED: this is
      exactly what left one stray ``mkdtemp`` directory behind per run of the
      ops-mission-control suite. Full telling:
      ``docs/system-specs/common/testing-conventions.md`` § Rules.

    Session scope is what fixes both: the thread's directory is stable for the whole
    run and belongs to no individual test, so nothing deletes it underneath the
    writer, and the thread is not churned per test.

    Patches the ``_default_dir()`` accessor rather than a captured constant, because
    the module resolves its default lazily so that importing ``kiro_crew.sel`` never
    triggers the one-time data-home migration as an import side effect. Tests that
    manage their own ``SecurityEventLog`` (passing ``base_dir`` and resetting
    ``_instance``) are unaffected.
    """
    try:
        from kiro_crew import sel as _sel
    except ImportError:  # pragma: no cover - partial checkout
        yield
        return
    original_default = _sel._default_dir
    original_instance = _sel.SecurityEventLog._instance
    sel_dir = tmp_path_factory.mktemp("sel")
    _sel._default_dir = lambda: sel_dir
    _sel.SecurityEventLog._instance = None
    try:
        yield
    finally:
        _sel._default_dir = original_default
        _sel.SecurityEventLog._instance = original_instance


@pytest.fixture
def sel_private_root(tmp_path_factory):
    """Bind the SEL singleton to a directory PRIVATE to the requesting test.

    ``_isolate_sel_default_dir`` above gives every test on a worker ONE shared
    SEL directory, which is the right default tier: the writer is a daemon
    thread on a process singleton, and a per-test ``tmp_path`` would be deleted
    underneath it (see that fixture's docstring). But one shared root also
    means one shared CHAIN LOCK, and a test whose assertion transitively
    depends on a fail-closed critical audit WINNING that lock can be refused by
    a concurrent writer it never created — the loop-side acquire is a single
    non-blocking attempt by design (issue #7029, the issue-radar trust flake).

    This is the per-test tier of the same seam. It rebinds the singleton to a
    fresh directory nothing else writes, so no other test — on this worker or
    any other — can hold this test's chain lock:

    * The directory comes from ``tmp_path_factory``, whose numbered dirs are
      never deleted mid-run (a lingering writer can never resurrect a removed
      path) and whose basetemp is already per-xdist-worker (``popen-gwN``), so
      the isolation holds across workers as well as across tests.
    * The instance is built ``sync=True``: every event is written inline on its
      caller's thread and NO background writer starts, so the only writers on
      this root are the test's own threads — which the module-level chain-hold
      registry already lets join one another.
    * ``_default_dir()`` is deliberately NOT repointed: the displaced shared
      directory stays reachable through it, which is what lets a differential
      test hold the SHARED root's lock and prove this test no longer contends
      for it.

    Teardown restores the PRIOR singleton (not ``None``), so later tests on
    this worker resume the session default exactly where it left off instead of
    minting a second instance — and a second writer thread — on the same
    directory.
    """
    try:
        from kiro_crew.sel import SecurityEventLog
    except ImportError:  # pragma: no cover - partial checkout
        yield None
        return
    root = tmp_path_factory.mktemp("sel-private")
    prior_instance = SecurityEventLog._instance
    SecurityEventLog._instance = None
    SecurityEventLog._initialized = False
    try:
        # Inside the try: ``__new__`` publishes to ``_instance`` before
        # ``__init__`` runs, so a failing ``_init_locked`` would otherwise
        # orphan the half-built object AND lose ``prior_instance`` — every
        # later test on this worker would then re-init against the shared
        # default with a second writer thread, the exact hazard the restore
        # exists to prevent.
        SecurityEventLog(base_dir=root, sync=True)
        yield root
    finally:
        SecurityEventLog._instance = prior_instance
        # Class attribute only (each instance shadows it in __new__); reset to
        # the declared default for symmetry with test_sel.py's convention —
        # the restored instance keeps its own per-instance _initialized=True.
        SecurityEventLog._initialized = False


#: ``~/.kiro`` paths production binds at IMPORT time, which ``KIROCREW_HOME`` cannot
#: reach: the module captured an absolute path from ``Path.home()`` before any test
#: set an environment variable, so the env override is read too late to matter.
#:
#: This directory is a SEPARATE isolation axis from the data home. ``~/.kiro`` is
#: kiro-cli's own home -- machine-wide, shared with the real installed agent -- so a
#: test that writes ``~/.kiro/settings/mcp.json`` edits the MCP servers of the
#: operator's live agent, not a copy of them.
#:
#: Each entry is ``(module, attribute, path relative to the per-test kiro home)``.
#: The relative paths keep production's real SHAPE (``.kiro/settings/mcp.json``, not a
#: flattened name) because several tests assert on the path's suffix, and a
#: same-shaped tmp path keeps those assertions meaningful.
#:
#: ``test/test_host_isolation_floor.py`` ratchets this table against the
#: ``Path.home()`` bindings ``src/kiro_crew`` actually has, so a new one cannot land
#: unpinned.
_SHARED_KIRO_PATHS: tuple[tuple[str, str, str], ...] = (
    ("kiro_crew.agent", "_KIRO_MCP_JSON", ".kiro/settings/mcp.json"),
    ("kiro_crew.agent", "_CC_MCP_JSON", ".claude.json"),
    ("kiro_crew.agent", "_DEFAULT_KIRO_HOOKS_DIR", ".kiro/hooks"),
    ("kiro_crew.learn", "_DEFAULT_DIR", ".kiro/crew"),
    ("kiro_crew.apps.bridges", "_LEGACY_SHARED_MCP_PATH", ".kiro/settings/mcp.json"),
    ("kiro_crew.dashboard.handlers.mcp", "_GLOBAL_MCP_JSON", ".kiro/settings/mcp.json"),
    # A DERIVED sibling (`_GLOBAL_MCP_JSON.with_suffix(".lock")`), and it has to move
    # WITH its json or the pair is worse than either alone: `_McpFileLockSync.__enter__`
    # creates `_GLOBAL_MCP_JSON.parent` and then touches `_MCP_LOCK_PATH`, so redirecting
    # only the json makes the code create a tmp directory and then touch a lock in the
    # REAL one -- whose parent nothing created, giving `FileNotFoundError` on any host
    # where `~/.kiro/settings` does not already exist. It passed on a developer box only
    # because that directory was there, and on CI only because an earlier test had
    # leaked into it. This is the sibling-binding case the ratchet's own docstring says
    # it cannot see, which is why the set is enumerated here by hand.
    ("kiro_crew.dashboard.handlers.mcp", "_MCP_LOCK_PATH", ".kiro/settings/mcp.lock"),
    # RELATIVE in production (``home / _AUTH_STAGING_RELATIVE``, home = ``Path.home()``),
    # and it must stay so: the sandbox hides ``~/.kiro/crew-auth-staging`` by that
    # HOME-relative spelling, so deriving it from the data home instead would leave a
    # relocated ``KIROCREW_HOME``'s staging tree visible to the sandboxed CLI. Pinning
    # the constant to an ABSOLUTE tmp path still lands, because ``pathlib`` discards
    # the left operand when the right one is absolute -- so the mkdir+chmod that
    # ``KiroPrerequisiteService`` performs on construction stops reaching the
    # operator's real ``~/.kiro`` (fifteen dashboard-server tests did).
    ("kiro_crew.kiro_prerequisite", "_AUTH_STAGING_RELATIVE", ".kiro/crew-auth-staging"),
)


@pytest.fixture(autouse=True)
def _isolate_shared_kiro_paths(_isolation_dirs, _floor_monkeypatch):
    """Redirect the import-time ``~/.kiro`` bindings to a per-test tmp tree.

    Patches only a module ALREADY in ``sys.modules``, the same tolerance
    ``_isolate_launchd_paths`` uses: several of these modules are heavy, and importing
    them for all ~26.5k tests would cost far more than the leak they close.

    That filter is not a coverage gap, but the reason is narrower than "collection
    imports everything": a module that is not loaded has no binding for a test to
    REACH, so there is nothing to leak. The residual hole is a module first imported
    inside a test's own body, after this fixture has already run for that test.

    Creates nothing. Every path here names a file whose absence is the normal
    fresh-install state, so a READER handles it already, and every test in the suite
    that WRITES one of them patches the same attribute itself (which wins over this
    fixture). Pre-creating the ``.kiro/settings`` parents instead cost a ``mkdir`` per
    entry on every test in the suite -- see ``_isolation_dirs`` for what that added up
    to. So a test that touches none of these modules pays one ``sys.modules`` lookup
    per entry and no syscall at all.
    """
    monkeypatch = _floor_monkeypatch
    targets = [
        (module, attr, relative)
        for module, attr, relative in _SHARED_KIRO_PATHS
        if sys.modules.get(module) is not None
    ]
    if not targets:
        return
    root = _isolation_dirs("kiro-home")
    for module, attr, relative in targets:
        monkeypatch.setattr(
            sys.modules[module], attr, root.joinpath(*relative.split("/")), raising=False
        )


# ── other real host paths a test must not reach ───────────────────────
#
# Same test as the data home above: each of these protects something on the
# operator's machine rather than the correctness of one suite, so it holds for every
# testpath. They were in ``test/conftest.py``, which the ~108 in-package test modules
# never load -- so an in-package test that spawned a subagent wrote the real registry,
# and one that reached the embeddings boot path could start a 610MB download.


@pytest.fixture(autouse=True)
def _isolate_subagents_dir(_isolation_dirs, _floor_monkeypatch):
    """Pin the subagent registry dir to a tmp dir for the whole suite.

    ``kiro_crew.subagent_persistence._SUBAGENTS_DIR`` is bound at import time to
    ``config_dir() / "subagents"``, so the ``KIROCREW_HOME`` safety net above
    cannot retroactively redirect it. Any test that calls ``SubagentManager.spawn``
    or ``create_agent_folder`` without isolating this global itself would write
    stub agent folders into the operator's real ``~/.kirocrew/subagents/``. On the
    next gateway start, orphan reconciliation sweeps those stubs and floods the
    logs with "lost to gateway restart" warnings (e.g. tasks ``t`` / ``ls /tmp``).
    The registry lives beneath its own per-test home so sibling protected
    identity records are isolated too, including runs with repeated ids.
    """

    monkeypatch = _floor_monkeypatch
    monkeypatch.setattr(
        "kiro_crew.subagent_persistence._SUBAGENTS_DIR",
        _isolation_dirs("subagents") / "subagents",
    )


#: Modules carrying the documented ``KIRO_AGENTS_DIR`` override hook (``None`` = live).
#: Each is ``(module, attribute)``; the fixture below points them all at ONE per-test
#: directory, so the hook production already offers "a caller (test/tooling)" is set
#: by default instead of per test.
_AGENT_SPEC_HOOKS: tuple[tuple[str, str], ...] = (
    ("kiro_crew.agent", "KIRO_AGENTS_DIR"),
    ("kiro_crew.agent_discovery", "_KIRO_AGENTS_DIR"),
    ("kiro_crew.apps.bridges", "KIRO_AGENTS_DIR"),
    ("kiro_crew.cli_doctor", "KIRO_AGENTS_DIR"),
    ("kiro_crew.doctor_deadpath", "KIRO_AGENTS_DIR"),
)

#: The real user home, captured at IMPORT -- before any test can patch
#: ``Path.home``. The pin below compares against it to tell "nobody redirected the
#: home, so use the per-test dir" from "this test redirected it, so follow the test".
#: ``patch("<module>.Path.home", ...)`` is the dominant isolation idiom in this suite
#: and it is global by construction (``from pathlib import Path`` binds the same class
#: object everywhere, so patching an attribute on it patches it for every module), which
#: is why the pin can detect it at all.
_REAL_USER_HOME = pathlib.Path.home()


@pytest.fixture(scope="session")
def _agent_spec_seam_modules():
    """Import the HOOK modules once per worker process.

    Ordering is what this buys: the per-test fixture below can only patch a module that
    is already imported, and these four carry the write seams #4912 names, so "whatever
    collection happened to import" is not a strong enough guarantee for them.

    Scoped to the hook table on purpose. The resolver-binding table is far wider and
    includes the heaviest modules in the repo (``slack.gateway``), which no worker should
    import to protect a binding that module cannot reach unless a test imported it
    anyway. Those keep the patch-if-imported tolerance ``_isolate_shared_kiro_paths``
    uses.

    ``ImportError`` is tolerated per module, matching the convention the other fixtures
    here follow: a partial checkout must not break collection, and a module that cannot
    import has no binding to leak.
    """
    for module, _attr in _AGENT_SPEC_HOOKS:
        try:
            importlib.import_module(module)
        except ImportError:  # pragma: no cover - partial checkout
            continue


@pytest.fixture(autouse=True)
def _isolate_agent_spec_home(_agent_spec_seam_modules, _isolation_dirs, _floor_monkeypatch):
    """Pin the AGENT-SPEC home to a per-test tmp dir, for EVERY testpath.

    A third isolation axis, distinct from both the data home and the import-time
    ``~/.kiro`` bindings above. The agent specs are the file kiro-cli reads to learn
    which MCP servers exist, and ``kiro_agents_dir()`` is a LAZY resolver
    (``kiro_home()`` -> ``$KIRO_HOME`` or ``Path.home()/.kiro``), so neither
    ``KIROCREW_HOME`` nor ``_SHARED_KIRO_PATHS`` reaches it -- the shared-path ratchet's
    own docstring records that lazy resolvers are outside its scope.

    Without this, any test reaching the write path (``rebuild_agent_config`` and the
    per-agent writers around it, ``apps.bridges._register_agents``) rewrites the
    operator's machine-wide ``<kiro home>/agents/kirocrew.json``. Confirmed live
    (#4912): a suite run inside a throwaway clone left every managed server's
    ``command`` pointing into that clone's venv and pinned the per-test data home into
    their ``env``, because ``_managed_mcp_env`` stamps the WRITER's paths. Both stop
    existing when the run ends, so afterwards every new session on the machine spawned
    ``kirocrew-core`` from a deleted venv against a data home recreated empty ->
    ``read_local_secret()`` returned "" -> every internal HTTP call failed
    ``internal_auth_mismatch`` (``received=absent``), killing ``spawn_run``,
    ``learn_add`` and ``cron_*`` while in-process tools kept working. A gateway restart
    healed it, and the next suite run re-broke it, which is what made it look
    intermittent and unfixable.

    ``KIRO_HOME`` is NOT the lever used here, deliberately -- see
    ``_isolate_kirocrew_home`` for why pinning that variable is refused: ~35 tests
    isolate ``kiro_home()`` the other way round with
    ``patch("pathlib.Path.home", ...)``, and an env pin overrides their own isolation
    so they read an empty directory instead of the tree they just built. Pinning the
    per-module seams instead leaves both of those levers untouched.

    One directory for every entry, not one each: production resolves a single agents
    dir, so a test that writes a spec through one seam and reads it through another
    (``rebuild_agent_config`` then ``agent_discovery``) has to see the same tree.

    Unlike ``_isolate_shared_kiro_paths``, the HOOK half does not settle for patching
    whatever happens to be in ``sys.modules``. That fixture's residual hole -- a module
    first imported inside a test's own body, after the fixture already ran -- is
    tolerable for a path that is only read, and not for these: ``rebuild_agent_config``
    and ``apps.bridges._register_agents`` WRITE, and a test that imports its subject in
    its own body is a normal shape here. ``_agent_spec_seam_modules`` therefore imports
    those four once per worker process. MEASURED cold on this tree: agent 177 ms,
    cli_doctor 87 ms, bridges 33 ms, agent_discovery 19 ms -- ~315 ms per worker for a
    whole session, against a shard that runs for minutes. Per-TEST import would have
    been the unaffordable shape, which is what that other fixture's tolerance is really
    about.

    The resolver-binding half keeps the patch-if-imported tolerance: it is wide and
    includes the repo's heaviest modules, and a module nobody imported has no bound name
    for a test to reach.

    Creates nothing -- an absent agents dir is the normal fresh-install state, and
    every writer ``mkdir(parents=True)`` first.

    A test that sets its own value still wins, through EITHER lever. ``monkeypatch``
    applied later in setup overrides the seams directly; and a test that sets
    ``KIRO_HOME`` -- the documented env override, which several tests use to place the
    agents dir under their own ``tmp_path`` -- is deferred to by the replacement
    resolver installed here. Deferring is safe because the variable is CLEARED first,
    so anything visible afterwards was chosen by the test rather than exported by the
    operator (whose value would name another real home).
    """
    monkeypatch = _floor_monkeypatch
    monkeypatch.delenv("KIRO_HOME", raising=False)
    root = _isolation_dirs("kiro-agents")
    paths = sys.modules.get("kiro_crew.config.paths")

    def _pinned_agents_dir() -> pathlib.Path:
        """The per-test dir, unless this test redirected the home itself."""
        if paths is None:  # pragma: no cover - defensive: package not importable
            return root
        if os.environ.get("KIRO_HOME") or pathlib.Path.home() != _REAL_USER_HOME:
            return paths.ambient_agents_dir()
        return root

    for module, attr in _AGENT_SPEC_HOOKS:
        mod = sys.modules.get(module)
        if mod is not None:
            monkeypatch.setattr(mod, attr, root, raising=False)
    if paths is not None:
        monkeypatch.setattr(paths, "_agents_dir_override", _pinned_agents_dir)
    return paths.ambient_agents_dir if paths is not None else None


@pytest.fixture
def unpinned_agent_spec_home(_isolate_agent_spec_home, monkeypatch):
    """Opt out of the agent-spec pin, for a test that ASSERTS on the real layout.

    Two drift guards need the real resolution rather than an isolated copy: one checks
    that ``security``'s ``.kiro/agents`` literal is still the home-relative tail of
    ``kiro_agents_dir()``, the other that ``apps.bridges`` still targets the
    machine-wide registry (which is why a pod may not run ``app``). Pinned to a tmp
    path, both assert about a path that does not ship -- weakening the guard to satisfy
    an isolation fixture, which is backwards. Same call the shared-path ratchet's
    ``_EXCLUDED`` makes for its security anchors.

    READ-ONLY use only. This hands back the real machine-wide location, so a test that
    WRITES through it edits the operator's live agent. Nothing here stops that; the
    two current users only assert.
    """
    for module, attr in _AGENT_SPEC_HOOKS:
        mod = sys.modules.get(module)
        if mod is not None:
            monkeypatch.setattr(mod, attr, None, raising=False)
    paths = sys.modules.get("kiro_crew.config.paths")
    if paths is not None:
        monkeypatch.setattr(paths, "_agents_dir_override", None)
    return _isolate_agent_spec_home


#: The operator's real kiro-cli home, captured before any test can repoint
#: ``Path.home``/``KIRO_HOME``. The sessions-dir floor compares against THIS, so a
#: test that relocates the home is followed and only the real store is fenced.
_REAL_KIRO_HOME_AT_START = (pathlib.Path.home() / ".kiro").resolve()


def _is_under(path: pathlib.Path, root: pathlib.Path) -> bool:
    try:
        resolved = path.resolve()
    except OSError:  # pragma: no cover - unresolvable path cannot be the real home
        return False
    return resolved == root or root in resolved.parents


#: Single-slot memo for :func:`_test_owned_roots`.
#:
#: Both roots are session constants -- pytest memoises its basetemp per worker, and
#: ``_isolate_tempfile_base`` sets the ``tempfile`` base exactly once -- yet the two
#: ``resolve()`` walks below were re-done once per test by the autouse
#: :func:`_isolate_kiro_sessions_dir`, MEASURED at 26.9us and ~6 ``lstat`` calls each,
#: for one answer that cannot change. Keyed on both inputs, so
#: ``KIROCREW_TMP_PER_TEST`` -- the one mode that repoints ``tempfile``'s base per test
#: -- simply misses and pays exactly what it pays today. ONE slot rather than a dict:
#: in that mode an unbounded cache would grow an entry per test.
_OWNED_ROOTS_MEMO: "tuple[tuple[str, str | None], tuple[pathlib.Path, ...]] | None" = None


def _test_owned_roots(tmp_path_factory) -> tuple[pathlib.Path, ...]:
    """This run's own temp trees: pytest's basetemp and the redirected ``tempfile`` base.

    A path under either was created by a fixture or by the test itself, so it is never
    the operator's -- even when the tree sits INSIDE a guarded root. That happens
    routinely: a Kiro Crew agent session sets ``TMPDIR`` to its scratch dir under
    ``~/.kiro/crew/scratch/``, which puts both trees under the real ``~/.kiro``. A fence
    keyed on the real home alone would then redirect a test that relocated kiro-cli's
    home to its OWN ``tmp_path`` away from the tree it just built.

    Memoised on its two inputs; see ``_OWNED_ROOTS_MEMO``. The key reads
    ``tempfile.gettempdir()`` -- the CALL, not the ``tempfile.tempdir`` global -- because
    a test that patches ``gettempdir`` still wins (``_isolate_tempfile_base`` says so),
    and keying on the global would make the memo blind to such a patch. The call costs
    0.09us once ``tempdir`` is set, so honouring it is free.
    """
    global _OWNED_ROOTS_MEMO
    basetemp = tmp_path_factory.getbasetemp()
    try:
        tmp_base: "str | None" = tempfile.gettempdir()
    except OSError:  # pragma: no cover - no usable temp dir at all
        tmp_base = None
    key = (str(basetemp), tmp_base)
    if _OWNED_ROOTS_MEMO is not None and _OWNED_ROOTS_MEMO[0] == key:
        return _OWNED_ROOTS_MEMO[1]
    roots = [basetemp.resolve()]
    if tmp_base is not None:
        try:
            roots.append(pathlib.Path(tmp_base).resolve())
        except OSError:  # pragma: no cover - unresolvable temp base
            pass
    value = tuple(roots)
    _OWNED_ROOTS_MEMO = (key, value)
    return value


@pytest.fixture(autouse=True)
def _isolate_kiro_sessions_dir(_isolation_dirs, _floor_monkeypatch, tmp_path_factory):
    """Pin kiro-cli's transcript store (``<kiro home>/sessions/cli``), for EVERY testpath.

    A fourth ``~/.kiro`` isolation axis, distinct from the data home, the import-time
    ``_SHARED_KIRO_PATHS`` bindings, and the agent-spec home above. ``kiro_sessions_dir()``
    is a LAZY resolver (``kiro_home()`` -> ``$KIRO_HOME`` or ``Path.home()/.kiro``), so
    neither ``KIROCREW_HOME`` nor an import-time path pin reaches it -- the same reason
    the agent-spec home needed its own fixture instead of folding into one of those.

    Without this, a test that reaches session teardown (``AcpSessionHandle.destroy()`` ->
    ``_cleanup_transcript``, which calls ``kiro_sessions_dir()`` directly with no override)
    deletes ``<sid>.json``/``.jsonl`` out of the operator's REAL kiro-cli session store --
    confirmed live: ``sA.json``, ``sA.jsonl``, ``new-sid.json(l)`` and even a fabricated
    ``<MagicMock ...>`` filename were removed from ``~/.kiro/sessions/cli`` by
    ``test_acp_runtime.py`` and ``test_session_transfer.py`` session-teardown tests and
    ``test_dashboard_chat_rewind.py``'s chained-history tests.

    Installs the override via the single accessor's function BODY, exactly like
    :func:`_isolate_agent_spec_home` does for ``_agents_dir_override``: ``kiro_sessions_dir``
    is bound by name in several modules (``session_map``, ``acp.client``,
    ``dashboard.session_transfer``, ...), and copies the function OBJECT, so patching only
    ``paths.kiro_sessions_dir`` would never reach them.

    ``session_map.py`` additionally exposes its OWN opt-in override
    (``_KIRO_SESSIONS_DIR``, ``None`` = defer to ``kiro_sessions_dir()``) for existing
    monkeypatch call sites -- pinned here too so a test that reads through that module
    sees the same tree as one that reads through the resolver directly.

    Creates nothing -- an absent sessions dir is the normal fresh-install state, and
    every writer creates its own parent first. A test that sets its own value still wins,
    through any lever: ``monkeypatch`` applied later in setup overrides both hooks, and a
    test that relocates kiro-cli's home itself -- ``KIRO_HOME``, ``HOME``, or a patched
    ``Path.home`` -- is followed there rather than pinned, because the override only
    fences the operator's REAL store (see ``_pinned_sessions_dir``). A test that asserts
    on the real default layout opts out with :func:`unpinned_kiro_sessions_dir`.
    """
    monkeypatch = _floor_monkeypatch
    root = _isolation_dirs("kiro-sessions-cli")
    # Imported unconditionally, never patch-if-imported: this floor guards a DELETE
    # path, and a test that imports its subject inside its own body would otherwise
    # find no module at setup, leave the override ``None``, and remove transcripts
    # from the operator's real store at teardown -- the exact failure the floor
    # exists to close. ``config.paths`` is the stdlib-only leaf, so the import costs
    # milliseconds once per worker; ``ImportError`` is tolerated so a partial
    # checkout cannot break collection (a module that cannot import has no seam).
    try:
        paths = importlib.import_module("kiro_crew.config.paths")
    except ImportError:  # pragma: no cover - partial checkout
        paths = None
    if paths is not None:
        real_kiro_home = paths.kiro_home
        own_roots = _test_owned_roots(tmp_path_factory)

        def _test_owned(path: pathlib.Path) -> bool:
            return any(_is_under(path, owned) for owned in own_roots)

        def _pinned_sessions_dir() -> pathlib.Path:
            # A GUARD, not a redirect. The lazy resolver is deliberately left to
            # each test (see the module docstring): ~35 tests relocate it with
            # ``patch("pathlib.Path.home", ...)`` or ``KIRO_HOME``, and they must
            # keep reading the tree they just built. So resolve it the way
            # production would, and only when that lands in the operator's REAL
            # ``~/.kiro`` -- the one place a test may never delete from -- answer
            # the isolation dir instead.
            unpinned = real_kiro_home() / "sessions" / "cli"
            if _is_under(unpinned, _REAL_KIRO_HOME_AT_START) and not _test_owned(unpinned):
                return root
            return unpinned

        monkeypatch.setattr(paths, "_sessions_dir_override", _pinned_sessions_dir)
    # ``session_map`` defers to ``kiro_sessions_dir()`` when its own override is
    # unset, so the resolver pin above is the floor; this only keeps a module that IS
    # loaded reading the same tree through its own lever.
    session_map = sys.modules.get("kiro_crew.session_map")
    if session_map is not None:
        monkeypatch.setattr(session_map, "_KIRO_SESSIONS_DIR", root, raising=False)


@pytest.fixture
def unpinned_kiro_sessions_dir(_isolate_kiro_sessions_dir, monkeypatch):
    """Opt out of the sessions-dir pin, for a test that ASSERTS on the real layout.

    The two drift guards in ``test_agent_home_isolation`` check that the resolver
    still derives the transcript store from ``kiro_home()`` -- pinned, they would
    assert about a tmp path that does not ship. READ-ONLY use only: this hands back
    the operator's real store, and a test that deletes through it is the harm the
    pin exists to prevent.
    """
    paths = sys.modules.get("kiro_crew.config.paths")
    if paths is not None:
        monkeypatch.setattr(paths, "_sessions_dir_override", None)
    session_map = sys.modules.get("kiro_crew.session_map")
    if session_map is not None:
        monkeypatch.setattr(session_map, "_KIRO_SESSIONS_DIR", None, raising=False)


@pytest.fixture(autouse=True)
def _no_model_download(_floor_monkeypatch, _isolation_dirs):
    """Never let a test download model weights over the network.

    Embeddings are always-on, so any test that boots the gateway/server
    startup path would otherwise kick ``start_background_model_download()``.
    The env escape hatch is honored by ``ModelDownloadManager.ensure_model``,
    ``start_background_model_download`` and ``stt.models.ModelStore.ensure`` (the
    whisper weights, 148MB at the default) — a test that wants to exercise a
    download path monkeypatches that manager's HTTP calls directly (see
    test_embeddings.py, test_stt_engine.py) rather than unsetting this.

    ``OLLAMA_MODELS`` is additionally pinned to an empty tmp dir so the
    legacy-blob salvage fast-path (``_salvage_legacy_ollama_blob``) can never
    read the developer's real ``~/.ollama`` store — without this, download
    tests would pass/fail machine-dependently on hosts that ran the
    Ollama-era embeddings.

    The same floor covers hosted feature-video media
    (``KIROCREW_SKIP_FEATURE_VIDEO_DOWNLOAD``), honored by
    ``feature_videos_cache.ensure_all`` and
    ``start_background_feature_video_download``: the gateway boot path kicks that
    transfer too, and a test that stands up the server must not reach a CDN.
    """
    monkeypatch = _floor_monkeypatch
    monkeypatch.setenv("KIROCREW_SKIP_MODEL_DOWNLOAD", "1")
    monkeypatch.setenv("KIROCREW_SKIP_FEATURE_VIDEO_DOWNLOAD", "1")
    monkeypatch.setenv("OLLAMA_MODELS", str(_isolation_dirs("ollama-models")))
    # Force telemetry OFF for every test. `_consent_enabled` reads this env var BEFORE
    # the config flag, which is what makes it a reliable gate: ~15 tests patch
    # `KiroCrewConfig.load` with a bare MagicMock, whose `telemetry.enabled` is TRUTHY,
    # so a real recorder starts and `Path(cfg.local_dir)` resolves the mock to the
    # RELATIVE path `MagicMock/load().telemetry.local_dir/...` -- writing metrics and a
    # lock file into the repo root, plus a background reader thread that outlives the
    # test. Tests that exercise telemetry delete this var themselves (test/metrics/).
    monkeypatch.setenv("KIROCREW_TELEMETRY", "0")


@pytest.fixture(autouse=True)
def _no_default_builtin_skills_sync(request, _floor_monkeypatch):
    """Stop a bare ``SkillsLoader()`` / ``ContextBuilder()`` from syncing builtins.

    ``SkillsLoader.__init__`` defaults ``install_builtins=True``, which calls
    ``_ensure_builtin_skills`` — a stat walk plus capped content hashing over
    the whole builtin-skills tree, then a real copy to disk on first divergence
    (~20s on a loaded host). ``ContextBuilder.__init__`` builds exactly that
    default (``self.skills = skills or SkillsLoader()``) whenever a test omits
    ``skills=``, so every such call site pays the sync even though the test
    under it almost never asserts anything about builtin skills. ~70 call
    sites across ``test/`` construct ``ContextBuilder()`` bare; fixing it here
    once is cheaper than a per-call-site ``skills=SkillsLoader(install_builtins=False)``
    that every new call site would have to remember.

    Patches the constructor itself, not a module-level flag, because that is
    the seam production code actually reads — ``install_builtins`` is a plain
    keyword default baked into ``SkillsLoader.__init__``'s signature, not a
    config value the class re-reads later. The wrapper only rewrites an
    OMITTED argument: a caller that explicitly passes ``install_builtins=`` in
    either form (keyword or positional) is left alone, so ``test_skills.py``
    passing ``install_builtins=False`` and ``test_crystallize_skill.py``
    asserting on a real sync with ``install_builtins=True`` both keep getting
    exactly what they asked for. A test whose contract IS the default — the
    event-loop guard in ``test_builtin_skill_sync_safety.py`` asserts that a
    bare ``SkillsLoader(skills_path=...)`` syncs when built off a running loop
    — opts out with ``@pytest.mark.real_builtin_skills_sync`` (registered in
    ``setup.cfg``) and gets the constructor untouched.
    """
    monkeypatch = _floor_monkeypatch
    if request.node.get_closest_marker("real_builtin_skills_sync") is not None:
        return

    from kiro_crew.skills import SkillsLoader

    original_init = SkillsLoader.__init__

    @functools.wraps(original_init)
    def _init_without_builtins_by_default(self, *args, **kwargs):
        # 2nd positional slot (after self, i.e. args[0]) is skills_path; the
        # 3rd (args[1]) is install_builtins. Only default it when the caller
        # supplied neither the keyword nor that positional slot.
        if "install_builtins" not in kwargs and len(args) < 2:
            kwargs["install_builtins"] = False
        original_init(self, *args, **kwargs)

    monkeypatch.setattr(SkillsLoader, "__init__", _init_without_builtins_by_default)


@pytest.fixture(autouse=True)
def _no_central_policy_fetch(_floor_monkeypatch):
    """Keep every test off the operator's fleet policy endpoint, and stop the poller.

    Two independent hazards, both of which have to be closed here rather than in
    ``test/conftest.py``: the ~108 test modules under
    ``src/kiro_crew/apps/builtins/*/tests/`` never see that file, and several of them
    call ``boot_platform``.

    **The environment.** ``KIROCREW_POLICY_URL`` and its siblings make
    ``load_security_policy`` fetch a ceiling over the network. A developer running
    the suite on a centrally-governed machine would otherwise have every boot-path
    test hit their own fleet endpoint — and, with the fail-closed default, watch
    unrelated tests abort when it is slow or unreachable.

    **The thread.** ``policy_distribution`` keeps a module-global refresher whose
    daemon thread INSTALLS A CEILING into the process-global context. A leaked one
    outlives ``_reset_platform_context``, so it would swap a fetched ceiling into
    whichever test happened to be running when its interval elapsed — the "singleton
    with a daemon thread beats every filesystem cleanup" class, and a maximally
    confusing one, since the victim is a test that never mentioned governance.
    Stopping it is a real ``stop()``, not a dropped reference: the thread's target is
    a bound method, so nothing else clears it.
    """
    monkeypatch = _floor_monkeypatch
    # Swept by PREFIX rather than by an enumerated list. A hand-written list here
    # would go stale the moment a sibling variable is added, silently reintroducing
    # the exact hazard this fixture exists to close — and this fixture must not import
    # the policy module at setup to read its canonical tuple, because that would put
    # the governance evaluator on every test's import path.
    for var in [k for k in os.environ if k.startswith("KIROCREW_POLICY_")]:
        monkeypatch.delenv(var, raising=False)
    yield
    # Imported at teardown, not at setup: the module pulls in the governance
    # evaluator, and an autouse fixture must not add that to every test's import
    # cost. If it was never imported, no refresher can be running.
    module = sys.modules.get("kiro_crew.platform.policy_distribution")
    if module is not None:
        with contextlib.suppress(Exception):
            module.stop_refresher(0.5)
        # Every process-global the module keeps — the fetch cooldown, the digest of
        # the document this process installed, and the cache-directory memo. Each is
        # invisible to a test that does not know it exists, and each leaks into the
        # next test a different way.
        with contextlib.suppress(Exception):
            module.reset_process_state()


@pytest.fixture(autouse=True)
def _reset_platform_context(_floor_monkeypatch):
    """Clear the process-global PlatformContext between tests, and pin the profile.

    A test that composes a non-default context (e.g. an enterprise-overlay probe)
    must not leak it into the next test.  ``current_context()`` lazily rebuilds
    the standalone default on next access.

    Also pins ``KIROCREW_PROFILE=standalone`` so the profile a test boots under
    comes from the test, never from the operator's shell: a dev box with a real
    SSO-marker directory, or a shell whose parent process exported
    ``KIROCREW_PROFILE`` set to the enterprise profile (a Kiro Crew agent session
    does exactly that for every child it spawns), would otherwise make
    ``boot_platform`` resolve the enterprise profile and fail CLOSED (no companion installed) for every test
    that drives ``run_gateway`` / boot / the governance hook.  A test that wants
    the enterprise profile overrides this env via its own ``monkeypatch.setenv`` (it
    runs after this autouse fixture), or composes the context directly via
    ``set_context`` without booting.

    Lives HERE, at the rootdir, for the same reason ``_isolate_kirocrew_home`` does:
    the ~108 test modules under ``src/kiro_crew/apps/builtins/*/tests/`` never see
    ``test/conftest.py``.  With the pin only there, an inherited
    ``KIROCREW_PROFILE=enterprise`` reddens 150+ builtin-app tests (every governance-gated
    route answers 500, every gated notification is dropped) while ``test/`` stays
    green.
    """
    from kiro_crew.platform.bootstrap import _reset_boot_state
    from kiro_crew.platform.context import reset_context

    _floor_monkeypatch.setenv("KIROCREW_PROFILE", "standalone")
    reset_context()
    _reset_boot_state()
    yield
    reset_context()
    _reset_boot_state()


@pytest.fixture(autouse=True)
def _isolate_agent_state_sidecar(_isolation_dirs, _floor_monkeypatch):
    """Pin the agent_state sidecar to a tmp dir for the whole suite.

    ``kiro_crew.agent_state`` stores per-agent bookkeeping (model_managed,
    cc_model) in ``~/.kirocrew/agent_model_state.json`` via ``config_dir()``.
    Tests that exercise the install / refresh / migration / PATCH paths would
    otherwise read and write the operator's real sidecar. Redirect
    ``config_dir`` — referenced as a module attribute at call time — to a fresh
    tmp dir so every test starts from empty state.
    """
    monkeypatch = _floor_monkeypatch
    sidecar_root = _isolation_dirs("agent-state")
    monkeypatch.setattr("kiro_crew.agent_state.config_dir", lambda: sidecar_root)


# ── the repository checkout is host state too ─────────────────────────


#: Repository root. This file lives at the rootdir, so its parent IS the root.
_REPO_ROOT = pathlib.Path(__file__).resolve().parent

#: Name prefixes the TEST RUNNER owns, exempt regardless of what git says.
#:
#: These are created by pytest and coverage, not by a test, so they are outside
#: what this guard is looking for. They are also all declared in `.gitignore`
#: (`/.pytest_cache`, `/.coverage`, `/.coverage.*`, `/.cache`), so on a host where
#: `git check-ignore` classifies them this list changes nothing. It exists because
#: that classification proved platform-dependent: MEASURED, the same
#: `.pytest_cache` at the same commit reports ignored on Linux and NOT ignored on
#: the Windows runner, which fired this guard on three shards where every test
#: passed. Matched by prefix rather than exact name because coverage writes
#: per-process files (`.coverage.<host>.<pid>.<rand>`).
_ROOT_RESIDUE_ALLOWED_PREFIXES: tuple[str, ...] = (".pytest_cache", ".coverage", ".cache")


def _runner_owned(name: str) -> bool:
    """Whether *name* is test-runner scratch rather than something a test wrote."""
    return name.startswith(_ROOT_RESIDUE_ALLOWED_PREFIXES)


#: Root listing taken before collection, so only what the RUN adds is reported.
#: A developer's own untracked scratch file must not fail their suite.
_ROOT_BASELINE: set[str] | None = None


def _root_entries() -> set[str] | None:
    """Immediate children of the repository root, or ``None`` if unreadable."""
    try:
        return {child.name for child in _REPO_ROOT.iterdir()}
    except OSError:
        return None


def _not_ignored(names: set[str]) -> list[str] | None:
    """*names* that git would NOT ignore, or ``None`` when git cannot classify.

    Deferring to ``git check-ignore`` rather than a pattern list here keeps this
    guard honest about one thing: ``.pytest_cache``, ``.coverage`` and the build
    trees are already declared ignorable, and duplicating that list would drift.

    ``None`` is a THIRD answer, not a failure. ``check-ignore`` exits 0 when it
    ignored something, 1 when it ignored nothing, and 128 when it could not look
    at all -- a non-git export of the test tree, or a checkout git refuses for
    dubious ownership, which is what a uid mismatch under a mounted volume
    produces. MEASURED: 1 and 128 both come back with EMPTY stdout, so the exit
    code is the only thing that separates "nothing here is ignored" from "I never
    got to look". Reading 128 as the former would report every toolchain artifact
    the run created as residue and fail the whole suite on an environment where
    the question is unanswerable. A guard that cries wolf gets deleted, and then
    it protects nothing -- so the caller reports that it could not check and
    leaves the verdict alone.
    """
    if not names:
        return []
    try:
        proc = subprocess.run(
            ["git", "check-ignore", "--stdin"],
            cwd=str(_REPO_ROOT),
            input="\n".join(sorted(names)),
            capture_output=True,
            text=True,
            timeout=30,
            check=False,
        )
    except (OSError, subprocess.SubprocessError):
        return None
    if proc.returncode not in (0, 1):
        return None
    ignored = {line.strip() for line in proc.stdout.splitlines() if line.strip()}
    return [name for name in sorted(names) if name not in ignored]


def pytest_sessionstart(session: pytest.Session) -> None:
    """Snapshot the repository root, on the controller only.

    Under ``-n auto`` every worker shares this filesystem, so letting each one
    snapshot and report would turn a single stray file into one failure per
    worker. The controller's session brackets all of them, which is exactly the
    window this guard wants.
    """
    global _ROOT_BASELINE
    if hasattr(session.config, "workerinput"):
        return
    _ROOT_BASELINE = _root_entries()


def _drain_windows_proactor_finalizers() -> None:
    """Suppress 'Event loop is closed' from ProactorEventLoop transport finalizers.

    On Windows with Python 3.12+, ``asyncio.run()`` creates a ProactorEventLoop,
    runs the coroutine, then CLOSES the loop. The IocpProactor's transport objects
    store a reference to their own loop (``self._loop``). When those transports are
    garbage-collected later, their ``__del__`` methods call
    ``self._loop.call_soon()`` on the *original* closed loop — not whatever loop is
    currently set. This raises ``RuntimeError: Event loop is closed`` as an
    unraisable exception.

    On an xdist worker process, unraisable exceptions write to stderr and cause
    exit code 1 — failing the CI shard with no named test failure (issue #4764).

    The fix: install a ``sys.unraisablehook`` that silences ``RuntimeError: Event
    loop is closed`` from asyncio transport ``__del__`` methods, and an ``atexit``
    handler that forces GC while the hook is still active to drain pending
    finalizers before interpreter shutdown (where unraisablehook itself may be
    torn down).
    """
    _original_unraisablehook = sys.unraisablehook

    def _suppress_closed_loop(unraisable: sys.UnraisableHookArgs) -> None:
        """Suppress 'Event loop is closed' from transport __del__."""
        exc = unraisable.exc_value
        if isinstance(exc, RuntimeError) and str(exc) == "Event loop is closed":
            # Silently swallow — the transport is being finalized after its loop
            # closed, which is harmless (the I/O is already done).
            return
        # Everything else goes to the original hook.
        if _original_unraisablehook is not None:
            _original_unraisablehook(unraisable)
        else:
            sys.__unraisablehook__(unraisable)

    sys.unraisablehook = _suppress_closed_loop

    # Force GC while the hook is active to drain finalizers before interpreter
    # shutdown tears down sys.unraisablehook itself.
    gc.collect()
    gc.collect()

    def _final_gc_pass() -> None:
        """Last-resort GC at interpreter exit while the hook is still installed."""
        try:
            gc.collect()
        except (TypeError, AttributeError):
            pass

    atexit.register(_final_gc_pass)


def _prune_bytecode_mirror_of_this_runs_temp_roots(session: pytest.Session) -> None:
    """Drop the ``sys.pycache_prefix`` mirror trees keyed on THIS run's temp roots.

    :func:`_redirect_bytecode_cache` sends every ``.pyc`` to a per-user cache mirror, and
    its "the cache persists so warm imports stay warm" argument holds for sources in the
    CHECKOUT, whose absolute paths are stable. It does not hold for a source under
    ``tmp_path`` or the run's isolated temp base: those paths are new on every run, so the
    mirror gains one dead tree per run that nothing ever reads and nothing owns. Measured
    on one developer host before this guard: 14,816 orphaned ``.pyc`` files, 5.3 GB, across
    161 dead run roots.

    The suite compiles throwaway sources deliberately (``load_app_module``, a skill script
    imported by path, a packaging step's precompile), so the answer is not to stop writing
    bytecode -- it is that the writer must own the retirement of what it wrote. Scoped to
    the roots this run created, so a concurrent run's mirror is never touched.
    """
    prefix = getattr(sys, "pycache_prefix", None)
    if not prefix:
        return
    roots: list[str] = []
    try:
        roots.append(str(session.config._tmp_path_factory.getbasetemp()))  # type: ignore[attr-defined]
    except Exception:  # noqa: BLE001 - no basetemp was ever materialised
        pass
    for candidate in (*_RUN_TEMP_ROOTS, os.environ.get(_SHORT_TMP_ROOT_ENV) or ""):
        if candidate:
            roots.append(candidate)
    for root in roots:
        try:
            absolute = os.path.abspath(root)
        except OSError:  # pragma: no cover - unreadable cwd
            continue
        # The mirror path is the prefix plus the source's absolute path with its leading
        # separator dropped; on Windows the drive colon is replaced the same way CPython
        # does, so the join is done from the parts rather than by string surgery.
        drive, tail = os.path.splitdrive(absolute)
        mirrored = os.path.join(prefix, drive.replace(":", "") + tail.lstrip(os.sep))
        if os.path.isdir(mirrored):
            shutil.rmtree(mirrored, ignore_errors=True)


def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
    """Fail the run when the suite left new, non-ignored entries at the root.

    A test writes there without any ``touch`` or ``open`` in its own source: a
    child process inherits pytest's CWD, which is the repository root, so a
    subprocess spawned without ``cwd=`` puts every relative write into the
    checkout. That is invisible to a reviewer reading the test, it survives the
    run, and an empty file produced this way has already been committed and
    shipped. Detected here rather than cleaned: deleting an unexpected file is
    not this guard's call to make.

    Also releases the xdist worker slots this run holds, because a module may
    define ``pytest_sessionfinish`` only once and appending a second definition
    silently shadows this guard. Done FIRST, and before the early return below:
    the kernel would drop the locks at process exit anyway, but returning capacity
    at the end of the run rather than at interpreter teardown is the whole point,
    and the early return would otherwise skip it.
    """
    try:
        import xdist_budget

        xdist_budget.release_worker_slots()
    except ImportError:  # pragma: no cover - partial checkout
        pass

    _remove_short_tmp_root()
    _prune_bytecode_mirror_of_this_runs_temp_roots(session)

    # ── Windows ProactorEventLoop teardown cleanup (#4764) ─────────────────
    # On Windows + Python 3.12, asyncio.run() creates and closes a
    # ProactorEventLoop each call. The closed loop's IocpProactor leaves
    # pending I/O Completion Port handles whose __del__ methods fire during
    # interpreter shutdown and call loop.call_soon() on the closed loop,
    # raising "RuntimeError: Event loop is closed". This unraisable exception
    # writes to stderr and causes the xdist worker process to exit with code 1
    # — failing the CI shard with no named test failure.
    #
    # Fix: before the worker exits, ensure a FRESH open event loop is set as
    # current, run a gc.collect() to drain pending finalizers while the loop
    # is still usable, then install an atexit handler that keeps a usable loop
    # available during interpreter finalization.
    if sys.platform == "win32":
        _drain_windows_proactor_finalizers()

    if hasattr(session.config, "workerinput") or _ROOT_BASELINE is None:
        return
    current = _root_entries()
    if current is None:
        return
    added = {name for name in current - _ROOT_BASELINE if not _runner_owned(name)}
    residue = _not_ignored(added)
    reporter = session.config.pluginmanager.get_plugin("terminalreporter")
    if residue is None:
        # Said out loud rather than skipped silently: if this ever starts
        # happening in CI, the guard has stopped working and the log is the only
        # place that would say so.
        if reporter is not None:
            reporter.write_line(
                "repository-root residue check skipped: git could not classify "
                f"{_REPO_ROOT} (not a checkout, or refused)"
            )
        return
    if not residue:
        return
    # Only promote a clean run to a failure. A non-zero *exitstatus* already
    # carries a more specific verdict than "tests failed" -- INTERRUPTED (2) and
    # INTERNAL_ERROR (3) tell a caller the run did not complete, and overwriting
    # either with TESTS_FAILED would report a finished, failing suite instead.
    # The residue is reported either way, since it is real regardless of how the
    # run ended.
    if exitstatus == pytest.ExitCode.OK:
        session.exitstatus = pytest.ExitCode.TESTS_FAILED
    if reporter is None:
        return
    reporter.write_sep("=", "repository root residue", red=True)
    reporter.write_line(
        f"{len(residue)} new entr{'y' if len(residue) == 1 else 'ies'} at "
        f"{_REPO_ROOT}, left behind by this run:"
    )
    for name in residue:
        reporter.write_line(f"    {name}")
    reporter.write_line("")
    reporter.write_line(
        "A test must not write into the checkout. The usual cause is a "
        "subprocess spawned without cwd=: it inherits pytest's CWD, which is "
        "this directory, so every relative write lands here. Pass "
        "cwd=<a directory under tmp_path> to the spawn, and scope any assertion "
        "about the file to where that child actually ran."
    )


# ── Check-run annotations that name the failing test (issue #7296) ──────────
#
# A red shard is read from its check run's ANNOTATIONS, not from the log: that
# is what the PR page shows, what a fork contributor sees, and all that survives
# in a triage report. Nothing in this repo wrote one, so the annotations came
# from the `python` problem matcher that `actions/setup-python` registers by
# default, whose pattern is a traceback frame (`File "...", line N, in f`)
# followed by `raise SomeError('msg')`.
#
# MEASURED on the six Backend Tests jobs cited in #7296: that pattern matched
# pytest's WARNINGS SUMMARY every time and a pytest failure not once. All six
# reds were annotated only `Event loop is closed` at line 545 -- which is
# `asyncio/base_events.py:545` inside `_check_closed`, reached from a
# `PytestUnraisableExceptionWarning` about a garbage-collected coroutine, i.e. a
# WARNING. The reds themselves were ordinary named failures (a `git add`
# timeout, a missing diag.jsonl, sandbox-dependent project tests) and appeared
# in no annotation at all. Four unrelated PRs were triaged as an event-loop
# teardown flake on the strength of that, and the class had been "fixed" four
# times before.
#
# Replacing the matcher with a better matcher is not the fix. `--color=yes` is
# in the addopts, so the summary line a matcher would have to scrape reads
# `\x1b[31mFAILED\x1b[0m test/x.py::\x1b[1mtest_y\x1b[0m - AssertionError: ...`
# with escape sequences INSIDE the node id. The report objects already carry the
# path, the line and the node id as data, so the annotation is emitted from them
# here and nothing is parsed back out of rendered output.

#: Failures that get their own annotation before the rest are only counted.
#: GitHub keeps a bounded number per check run and drops the excess with no
#: notice, so past this point the annotation list stops being something anyone
#: reads and the short test summary in the log is the better artifact.
_MAX_ANNOTATED_FAILURES = 10

#: Annotation messages are cut to this many characters. A full assertion diff is
#: a page long, does not fit the check-run UI, and is already in the log.
_MAX_ANNOTATION_CHARS = 400


def _gha_escape(value: str, *, is_property: bool) -> str:
    """Escape *value* for a GitHub Actions workflow command.

    The runner splits a command on ``,`` and on ``::``, and every pytest node id
    contains ``::`` -- unescaped, the annotation is truncated at the first one
    and names the FILE instead of the test, which is most of the defect this
    exists to fix. Property values need the two structural characters escaped on
    top of the data set, per the workflow-commands spec.
    """
    escaped = value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
    if is_property:
        escaped = escaped.replace(":", "%3A").replace(",", "%2C")
    return escaped


def _report_location(report: object) -> tuple[str, int | None]:
    """Repository-relative path and 1-based line for *report*, best effort.

    ``report.location`` is a ``(path, lineno, domain)`` triple whose line is
    0-BASED, while an annotation line is 1-based. A collection error carries no
    line at all, and a guessed one points the reader at the wrong statement, so
    ``None`` means "omit ``line=``" rather than "line 1".
    """
    location = getattr(report, "location", None) or ()
    path = location[0] if len(location) >= 1 and isinstance(location[0], str) else ""
    if not path:
        path = str(getattr(report, "fspath", "") or "")
    raw_line = location[1] if len(location) >= 2 else None
    line = raw_line + 1 if isinstance(raw_line, int) and raw_line >= 0 else None
    return path, line


def _cut(reason: str) -> str:
    """*reason* trimmed to :data:`_MAX_ANNOTATION_CHARS`."""
    reason = reason.strip()
    if len(reason) > _MAX_ANNOTATION_CHARS:
        return reason[: _MAX_ANNOTATION_CHARS - 3] + "..."
    return reason


def _failure_reason(report: object) -> str:
    """One-line reason for *report*, cut to :data:`_MAX_ANNOTATION_CHARS`.

    Prefers the line pytest marks with ``E`` in the first column, which is the
    error itself. ``longrepr.reprcrash.message`` looks like the obvious source
    and is right for an assertion, but for a FIXTURE error it is the preamble --
    MEASURED, an annotation built from it reads ``file <path>, line 5`` and
    spends its whole width saying nothing, while the ``E`` line two rows down
    says ``fixture 'x' not found``. Source lines in the same block are indented,
    so anchoring at column 0 does not mistake a statement for the verdict.

    ``reprcrash`` is the fallback, then the first rendered line; a report with
    none of the three still gets an annotation, because the node id was the part
    that was missing.
    """
    rendered = str(getattr(report, "longreprtext", "") or "")
    for raw in rendered.splitlines():
        if raw.startswith("E ") and raw[1:].strip():
            return _cut(raw[1:])
    crash = getattr(getattr(report, "longrepr", None), "reprcrash", None)
    reason = str(getattr(crash, "message", "") or "")
    if not reason.strip():
        reason = rendered
    lines = [line for line in reason.strip().splitlines() if line.strip()]
    if not lines:
        return "no failure detail in the report"
    return _cut(lines[0])


def pytest_terminal_summary(
    terminalreporter: object, exitstatus: int, config: pytest.Config
) -> None:
    """Emit one ``::error`` annotation per failing test. See the note above.

    Controller-only: under xdist a worker's reports are sent back and counted
    here, so annotating from the worker too would double every line. Gated on
    ``GITHUB_ACTIONS`` because outside Actions these lines are noise nothing
    interprets, and a green run writes nothing at all.
    """
    if os.environ.get("GITHUB_ACTIONS") != "true":
        return
    if hasattr(config, "workerinput"):  # pragma: no cover - xdist worker
        return
    stats = getattr(terminalreporter, "stats", None) or {}
    reports = [report for key in ("failed", "error") for report in stats.get(key, [])]
    if not reports:
        return
    write = getattr(terminalreporter, "write_line", None)
    if write is None:  # pragma: no cover - no terminal reporter (e.g. -p no:terminal)
        return
    for report in reports[:_MAX_ANNOTATED_FAILURES]:
        nodeid = str(getattr(report, "nodeid", "") or "") or "<unknown test>"
        path, line = _report_location(report)
        properties = []
        if path:
            properties.append(f"file={_gha_escape(path, is_property=True)}")
        if line is not None:
            properties.append(f"line={line}")
        properties.append(f"title={_gha_escape(nodeid, is_property=True)}")
        message = _gha_escape(f"{nodeid} - {_failure_reason(report)}", is_property=False)
        write(f"::error {','.join(properties)}::{message}")
    hidden = len(reports) - _MAX_ANNOTATED_FAILURES
    if hidden > 0:
        write(
            f"::notice::{len(reports)} tests failed or errored on this job; the first "
            f"{_MAX_ANNOTATED_FAILURES} are annotated. The remaining {hidden} are in "
            "this job's short test summary."
        )