failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/sdk/python/tests/test_no_customer_identifiers.py

@@ -0,0 +1,214 @@
+"""This package is PUBLIC and its wheel is published to PyPI.
+
+It came out of a private monorepo, where naming a live tenant in a fixture or
+leaving an internal hostname in a docstring was harmless. Here it is permanent:
+a PyPI version cannot be recalled or reused, so anything that ships once ships
+forever. The sibling `fp-cloud-cli` hit exactly this during its own move — a real
+customer's slug and company name reached the tree in a bulk copy — which is why
+this tripwire exists on both packages.
+
+Customer names are held as SHA-256 digests, never in the clear. A deny-list that
+spells out the name it exists to keep out of a public wheel publishes that name
+just as surely as the fixture did, and this file ships in the sdist. Our OWN
+names stay readable: they are already in LICENSE and pyproject.toml, so there is
+nothing to withhold, and a contributor who trips over one needs to see which it
+was.
+
+The match is over SUBSTRINGS of each token, not whole tokens, because the
+original leak was a slug *and* a company name built from it — one name inside a
+longer one. To add an identifier:
+
+    python3 -c 'import hashlib,sys;print(hashlib.sha256(sys.argv[1].lower().encode()).hexdigest())' NAME
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import pathlib
+import re
+
+import failproofai_sdk
+
+PKG = pathlib.Path(failproofai_sdk.__file__).resolve().parent
+ROOT = PKG.parent
+
+# Our own organisation names — public in this repo already, so in the clear. A
+# fixture must still not use them: they identify a real tenant on a real deployment.
+FORBIDDEN_OWN = {
+    "exosphere",
+    "exospherehost",
+}
+
+# Customer / vendor identifiers, digest → what it is (never the name itself).
+# Kept in step with fp-cloud-cli/tests/test_no_customer_identifiers.py.
+FORBIDDEN_DIGESTS = {
+    "140bd3c7a8606c97e18fb1f01c3a94f558eab6e2c5b27a56f9c3f5a940d8e2fd": "a customer's tenant slug",
+}
+
+# Internal artefacts from the private monorepo. Unlike the names above these are
+# not confidential so much as WRONG to ship: a dev credential in a public
+# quickstart gets pasted into production, and an internal-only table name in a
+# docstring is an invitation to query something that does not exist for users.
+FORBIDDEN_INTERNALS = {
+    "dev-admin-key": "the local-dev admin credential",
+    "agenteye-enterprise": "the private customer-release org",
+    "clickhouse": "an internal storage detail users never touch",
+    "org_ch_secret": "an internal server secret name",
+}
+
+# The vocabulary fixtures are supposed to use.
+SANCTIONED_FIXTURE_ORGS = {"acme", "globex", "example", "initech", "umbrella"}
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+_URL = re.compile(r"https?://([a-z0-9.-]+)", re.I)
+
+# Substring lengths considered when hashing. The floor keeps the scan off two- and
+# three-letter noise; the ceiling bounds the work on long tokens (hex digests, base64).
+_MIN_LEN = 5
+_MAX_LEN = 24
+
+
+@functools.lru_cache(maxsize=None)
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def _hashed_hits(text: str, needles: frozenset[str] | None = None) -> set[str]:
+    """Digests from ``needles`` whose plaintext appears anywhere in ``text``.
+
+    ``text`` need not be lowercased by the caller. Returns digests, not matched
+    text: a failure message must not echo the identifier into a public CI log.
+    """
+    want = FORBIDDEN_DIGESTS.keys() if needles is None else needles
+    found = set()
+    for token in set(_TOKEN.findall(text.lower())):
+        for start in range(len(token)):
+            stop = min(len(token), start + _MAX_LEN)
+            for end in range(start + _MIN_LEN, stop + 1):
+                d = _digest(token[start:end])
+                if d in want:
+                    found.add(d)
+    return found
+
+
+def _sources() -> list[pathlib.Path]:
+    out = []
+    for base in (PKG, ROOT / "tests"):
+        out.extend(p for p in base.rglob("*.py") if "__pycache__" not in p.parts)
+    for name in ("README.md", "CHANGELOG.md", "pyproject.toml"):
+        p = ROOT / name
+        if p.is_file():
+            out.append(p)
+    for p in (ROOT / "skill").rglob("*"):
+        if p.is_file() and p.suffix in {".md", ".yaml", ".yml"}:
+            out.append(p)
+    return out
+
+
+def _scannable() -> list[pathlib.Path]:
+    """Everything but this file, which names our own orgs to deny them."""
+    return [p for p in _sources() if p.name != pathlib.Path(__file__).name]
+
+
+def _scannable_for_own_names() -> list[pathlib.Path]:
+    """As above, minus the one file our own org name legitimately belongs in.
+
+    `pyproject.toml`'s `authors` email is the published maintainer contact — it
+    is on the PyPI project page by design, and `fp-cloud-cli` publishes the same one.
+    It is still scanned for customer digests and internal artefacts below; only
+    the our-own-name rule is lifted, because that rule exists to keep a real
+    tenant out of a FIXTURE, not to redact the maintainer.
+    """
+    return [p for p in _scannable() if p.name != "pyproject.toml"]
+
+
+def test_no_real_customer_or_vendor_identifiers():
+    hits = []
+    for p in _scannable_for_own_names():
+        for i, line in enumerate(p.read_text(encoding="utf-8", errors="replace").split("\n"), 1):
+            lowered = line.lower()
+            for needle in FORBIDDEN_OWN:
+                if needle in lowered:
+                    hits.append(f"{p.relative_to(ROOT)}:{i}: {needle}")
+    # Customer digests are checked over EVERY file, pyproject.toml included —
+    # the exemption above is only for our own maintainer contact.
+    for p in _scannable():
+        for i, line in enumerate(p.read_text(encoding="utf-8", errors="replace").split("\n"), 1):
+            # Report the location and what class of identifier it is — never the name.
+            for digest in _hashed_hits(line):
+                hits.append(f"{p.relative_to(ROOT)}:{i}: {FORBIDDEN_DIGESTS[digest]}")
+    assert not hits, (
+        "real organisation names must not appear in a public package — use a fixture "
+        f"name such as {sorted(SANCTIONED_FIXTURE_ORGS)}:\n  " + "\n  ".join(hits)
+    )
+
+
+def test_no_internal_artefacts_from_the_private_monorepo():
+    """Credentials and internal names that came across in the move."""
+    hits = []
+    for p in _scannable():
+        for i, line in enumerate(p.read_text(encoding="utf-8", errors="replace").split("\n"), 1):
+            lowered = line.lower()
+            for needle, what in FORBIDDEN_INTERNALS.items():
+                if needle in lowered:
+                    hits.append(f"{p.relative_to(ROOT)}:{i}: {what}")
+    assert not hits, "internal artefacts in a public package:\n  " + "\n  ".join(hits)
+
+
+def test_the_scan_actually_has_files_to_scan():
+    """Keeps the assertions above from passing vacuously if the layout moves."""
+    files = _sources()
+    assert len(files) > 15, (
+        f"only {len(files)} files scanned — the walk is not finding the package"
+    )
+    assert any(p.name == "_writer.py" for p in files)
+    assert any(p.parent.name == "tests" for p in files)
+
+
+def test_the_hashed_scan_matches_substrings_and_only_them():
+    """The digests are opaque, so prove the matcher on a planted, invented name.
+
+    Without this, an off-by-one in the substring window turns the whole hashed
+    deny-list into an assertion that passes because it matches nothing.
+    """
+    planted = frozenset({_digest("quuxcorp")})
+    assert _hashed_hits("slug: quuxcorp", planted) == planted            # bare token
+    assert _hashed_hits('name: "QuuxcorpInc"', planted) == planted       # inside a longer name
+    assert _hashed_hits("host: quuxcorp-prod.example.com", planted) == planted
+    assert not _hashed_hits("slug: acme, name: Globex Corp", planted)    # sanctioned fixtures
+    assert not _hashed_hits("quux corp", planted)                        # not one token
+
+
+def test_no_internal_hostnames_leaked():
+    """A customer's deployment hostname identifies them as surely as their name."""
+    hits = []
+    for p in _scannable():
+        for i, line in enumerate(p.read_text(encoding="utf-8", errors="replace").split("\n"), 1):
+            for host in _URL.findall(line):
+                labels = host.lower().split(".")
+                if any(label in FORBIDDEN_OWN for label in labels) or _hashed_hits(host):
+                    hits.append(f"{p.relative_to(ROOT)}:{i}")
+    assert not hits, f"internal/customer hostnames in a public package: {hits}"
+
+
+def test_this_file_does_not_name_the_customers_it_denies():
+    """The deny-list must not restate, in the clear, what it holds as a digest.
+
+    ``_scannable()`` skips this file so the ``FORBIDDEN_OWN`` literals above do not
+    trip the scan on themselves. That exemption is about OUR names, which are public
+    in this repo already. It must never extend to a customer's: this file ships in
+    the sdist, so a name written here is published exactly like the fixture that
+    started all this. It needs its own test precisely because the exemption is what
+    blinds the main scan to it.
+    """
+    src = pathlib.Path(__file__)
+    hits = [
+        f"{src.name}:{i}: {FORBIDDEN_DIGESTS[digest]}"
+        for i, line in enumerate(src.read_text(encoding="utf-8", errors="replace").split("\n"), 1)
+        for digest in _hashed_hits(line)
+    ]
+    assert not hits, (
+        "this file names, in the clear, an identifier it exists to keep out of a "
+        "public package:\n  " + "\n  ".join(hits)
+    )

package/.next/standalone/sdk/python/tests/test_packaging.py

@@ -0,0 +1,185 @@
+"""Packaging contracts, read from `importlib.metadata` — never from pyproject.
+
+Two reasons this file never opens `pyproject.toml`:
+
+1. `tomllib` is 3.11+ and this SDK's floor is 3.10, so parsing it here would
+   make the packaging tests skip exactly on the leg that catches 3.10 problems.
+2. `pyproject.toml` is the *input*. What ships is the wheel's `METADATA`, and
+   the failure mode these tests exist to catch — an extra that silently drags
+   the wrong `failproofai_sdk` off PyPI — happens at install time, from METADATA.
+
+The rules being enforced:
+
+* **zero runtime dependencies.** `import failproofai_sdk` must work in an environment
+  with nothing else installed, so every `Requires-Dist` carries an
+  `extra == "..."` marker.
+* **no self-referential extra.** On public PyPI `failproofai_sdk` is the *CLI*; a
+  `Requires-Dist: failproofai_sdk[...]` would install the CLI over this SDK. This is
+  also why the adapters ship as extras on one distribution rather than as
+  `failproofai_sdk-langgraph` and friends.
+* **no `[all]` extra** — a resolution bomb that exists only for CI's
+  convenience.
+* **the extras and the adapter registry agree.** They are two hand-maintained
+  lists of the same set, in two files, with no codegen between them.
+"""
+
+import re
+import os
+import subprocess
+from pathlib import Path
+
+import failproofai_sdk
+import sys
+import textwrap
+
+import importlib.metadata as metadata
+
+import pytest
+
+from failproofai_sdk import integrations
+
+DIST = "failproofai_sdk"
+
+
+def requirements() -> list[str]:
+    return list(metadata.requires(DIST) or [])
+
+
+def declared_extras() -> set[str]:
+    return set(metadata.distribution(DIST).metadata.get_all("Provides-Extra") or [])
+
+
+def test_the_distribution_is_installed():
+    # Guards every other test in this file: `requires()` returns None for a
+    # dist that is not installed, and `for req in []` passes vacuously.
+    assert metadata.version(DIST)
+    assert requirements()
+
+
+def test_every_requirement_is_gated_behind_an_extra():
+    ungated = [req for req in requirements() if "extra ==" not in req]
+    assert ungated == [], (
+        "failproofai_sdk must have ZERO runtime dependencies; these would be installed "
+        f"unconditionally: {ungated}"
+    )
+
+
+#: Names a requirement here must never be. `failproofai-sdk` is self-reference —
+#: `pip install failproofai-sdk[langchain]` resolving through an extra back onto
+#: this distribution. `agenteye` is the RETIRED distribution: on public PyPI that
+#: name is the CLI, so pinning it would install the CLI over the SDK.
+_FORBIDDEN_REQUIREMENT_NAMES = frozenset({"failproofai-sdk", "agenteye"})
+
+
+def test_no_requirement_names_the_retired_distribution():
+    """Both sides normalized, which is the whole point.
+
+    This compared a dash-normalized name against `DIST`, which keeps its
+    UNDERSCORE — so `"failproofai-sdk" != "failproofai_sdk"` was true for every
+    possible input and the assertion could not fail. Negative-controlled: a
+    planted `failproofai-sdk[langchain]; extra == "all"` used to pass.
+    """
+    for req in requirements():
+        name = re.split(r"[\s\[<>=!~;(]", req.strip(), maxsplit=1)[0]
+        assert name.lower().replace("_", "-") not in _FORBIDDEN_REQUIREMENT_NAMES, (
+            f"requirement {req!r} names a distribution that must never appear here: "
+            "self-reference resolves an extra back onto this package, and `agenteye` "
+            "is the CLI on public PyPI, so either would install something else over "
+            "the SDK"
+        )
+
+
+def test_there_is_no_all_extra():
+    assert "all" not in declared_extras()
+
+
+def test_every_extra_maps_to_a_registered_adapter():
+    for extra in declared_extras() - {"dev"}:
+        # Raises ValueError if the extra is not a name (or alias) the registry
+        # knows — i.e. an extra nobody can instrument.
+        assert integrations._canonical(extra) in integrations.available()
+
+
+def test_every_registered_adapter_has_an_extra():
+    covered = {integrations._canonical(extra) for extra in declared_extras() - {"dev"}}
+    assert covered == set(integrations.available())
+
+
+def test_every_extra_requirement_pins_a_floor_and_a_ceiling():
+    # Without a ceiling, a clean build a year from now pulls the next major, the
+    # callback API shifts, and the adapter stops receiving events while raising
+    # nothing at all.
+    for req in requirements():
+        if 'extra == "dev"' in req:
+            continue
+        assert ">=" in req, f"{req} has no floor"
+        assert "<" in req, f"{req} has no ceiling"
+
+
+IMPORT_GUARD = textwrap.dedent(
+    """
+    import sys
+
+    baseline = set(sys.modules)
+    import failproofai_sdk
+
+    added = set(sys.modules) - baseline
+    third_party = sorted(
+        name for name in added
+        if name.split(".")[0] not in sys.stdlib_module_names
+        and not name.startswith("failproofai_sdk")
+    )
+    integrations = sorted(n for n in sys.modules if n.startswith("failproofai_sdk.integrations"))
+
+    assert not third_party, "import failproofai_sdk pulled in third-party modules: %r" % third_party
+    assert not integrations, "import failproofai_sdk imported the adapters: %r" % integrations
+    assert failproofai_sdk._writer is not sys.modules["failproofai_sdk._writer"], "_writer is the module"
+    print("OK")
+    """
+)
+
+
+def test_importing_the_package_stays_clean(tmp_path):
+    """A subprocess, because the assertion is about a *cold* interpreter.
+
+    In-process, every framework any other test file imported is already in
+    `sys.modules` and the check is vacuous.
+    """
+    # `cwd=tmp_path` is what makes the interpreter cold — away from the source
+    # tree, so nothing is importable by accident. PYTHONPATH then puts the
+    # package back deliberately, which is what lets this run in an environment
+    # where it is not pip-installed (a container running the suite off a mounted
+    # checkout). Without it the test does not fail loudly, it fails with
+    # ModuleNotFoundError and looks like a packaging bug that is not there.
+    env = dict(os.environ, PYTHONPATH=str(Path(failproofai_sdk.__file__).resolve().parents[1]))
+    result = subprocess.run(
+        [sys.executable, "-c", IMPORT_GUARD],
+        capture_output=True,
+        text=True,
+        cwd=str(tmp_path),
+        env=env,
+    )
+    assert result.returncode == 0, result.stderr
+    assert "OK" in result.stdout
+
+
+def test_instrument_is_lazy_until_it_is_called():
+    # `failproofai_sdk.instrument` is a thin wrapper whose import sits *inside* the
+    # function body; the guard test above proves the module-level import is
+    # absent, this proves the wrapper still exists to be called.
+    assert callable(sdk_instrument())
+
+
+def sdk_instrument():
+    import failproofai_sdk
+
+    return failproofai_sdk.instrument
+
+
+@pytest.mark.parametrize("name", ["langchain", "crewai", "llama_index", "pydantic_ai"])
+def test_the_registry_points_at_a_module_inside_this_package(name):
+    path = integrations._REGISTRY[name]
+    assert path.startswith("failproofai_sdk.integrations.")
+    # The registry entry is a STRING, imported on demand. If this ever becomes a
+    # module object, `import failproofai_sdk` stops being zero-dependency.
+    assert isinstance(path, str)

package/.next/standalone/sdk/python/tests/test_resolver_umbrella.py

@@ -0,0 +1,178 @@
+"""The spool root IS the failproofai umbrella, and no environment can move it out.
+
+This file used to assert the opposite, and the reason it flipped is worth
+keeping: the umbrella was previously behind an ``AGENTEYE_SPOOL_TO_FAILPROOFAI``
+opt-in that ALSO required ``~/.failproofai/custom-agents`` to already exist.
+Nothing ever created that directory — not this SDK, not ``failproofaid``, not
+either installer — so the second condition was never satisfied and the opt-in
+never fired once. It was documented, tested, and dead.
+
+The rule now: the SDK ships beside ``failproofaid``, which watches BOTH roots,
+so on any host running it the default is a no-op that only changes which
+directory the files appear in. The old root keeps being watched indefinitely, so
+an unupgraded SDK keeps working and batches already spooled there still drain.
+
+The case that genuinely breaks is a host running the OLDER
+``agenteye-collector``, which resolves ``$AGENTEYE_HOME`` or ``~/.agenteye`` and
+nothing else.
+
+``AGENTEYE_HOME`` USED TO BE THAT HOST'S ESCAPE HATCH, AND NO LONGER IS. It sat
+above the default in resolution, so it could aim this SDK anywhere from the
+environment — including as a side effect of an operator exporting it for the
+collector, which is the component that actually reads it. A redirect that
+silent is not a good property for the one variable named after a product this
+package no longer belongs to. Resolution is now exactly `set_base_dir()` then
+the umbrella, and the bridges for that host are listed in
+``_resolver.get_base_dir``: run ``failproofaid`` (it watches both roots), point
+the COLLECTOR at the umbrella, or call ``set_base_dir()`` explicitly.
+"""
+from pathlib import Path
+
+import pytest
+
+from failproofai_sdk import _resolver
+
+
+@pytest.fixture(autouse=True)
+def _clean(monkeypatch):
+    _resolver.set_base_dir(None)
+    monkeypatch.delenv("AGENTEYE_HOME", raising=False)
+    monkeypatch.delenv("FAILPROOFAI_HOME", raising=False)
+    yield
+    _resolver.set_base_dir(None)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# The default
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_the_default_is_the_failproofai_umbrella(tmp_path, monkeypatch):
+    """THE CHANGE. A clean machine writes to the umbrella, with nothing set."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_the_umbrella_does_not_have_to_exist_first(tmp_path, monkeypatch):
+    """The regression that made the old opt-in dead.
+
+    Requiring the directory to pre-exist means it can never be the place a first
+    batch is written — nothing creates it, so the branch is unreachable. The
+    writer mkdirs what it is about to write into, so resolution must not care.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    assert not (tmp_path / ".failproofai").exists()
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_an_existing_legacy_root_does_not_drag_the_default_back(tmp_path, monkeypatch):
+    """Presence of ``~/.agenteye`` is not a vote.
+
+    It exists on any machine that merely ran the old CLI once — it holds that
+    CLI's `cli.json` — so treating it as a signal would pin those machines to
+    the old path forever despite no collector ever having watched it.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    (tmp_path / ".agenteye" / "events").mkdir(parents=True)
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# The retired escape hatch — these assert that it is inert, not that it works
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_agenteye_home_cannot_drag_the_spool_back_to_the_legacy_root(tmp_path, monkeypatch):
+    """THE CHANGE. Exporting it does nothing to this SDK any more.
+
+    This is the assertion that makes the guarantee testable: whatever is in the
+    environment, this package writes inside the umbrella. An operator exporting
+    ``AGENTEYE_HOME`` for ``agenteye-collector`` — the component that still
+    reads it — no longer moves this SDK's spool as a side effect.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / ".agenteye"))
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_agenteye_home_cannot_point_the_spool_anywhere_else_either(tmp_path, monkeypatch):
+    """Not just the legacy root — the variable has no effect at all."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / "somewhere" / "else"))
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_an_empty_agenteye_home_is_ignored_rather_than_resolving_to_cwd(tmp_path, monkeypatch):
+    """``AGENTEYE_HOME=`` in a CI env file must not spool into the repo.
+
+    Kept although the variable is no longer read: an empty value was the shape
+    most likely to resolve to a relative path, and the test costs nothing.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.setenv("AGENTEYE_HOME", "")
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_no_environment_variable_can_take_the_spool_outside_the_umbrella(tmp_path, monkeypatch):
+    """The guarantee in one line: FAILPROOFAI_HOME MOVES the umbrella, and the
+    ``custom-agents`` segment is appended unconditionally, so there is no
+    environment in which this SDK writes somewhere that is not inside it."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path / "relocated"))
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / "hijack"))
+    resolved = _resolver.get_base_dir()
+    assert resolved == tmp_path / "relocated" / "custom-agents"
+    assert resolved.name == "custom-agents"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Precedence and the umbrella path itself
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_set_base_dir_beats_every_environment_variable(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path / "env"))
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / "legacy"))
+    _resolver.set_base_dir(tmp_path / "explicit")
+    assert _resolver.get_base_dir() == tmp_path / "explicit"
+
+
+def test_set_base_dir_is_the_only_way_to_choose_the_legacy_root(tmp_path, monkeypatch):
+    """Still possible, but only as an explicit, visible call.
+
+    That is the whole trade: the destination stays reachable for anyone who
+    genuinely wants it, and reaching it now requires saying so at the call site
+    rather than inheriting somebody else's environment.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    _resolver.set_base_dir(tmp_path / ".agenteye")
+    assert _resolver.get_base_dir() == tmp_path / ".agenteye"
+
+
+def test_failproofai_home_moves_the_umbrella(tmp_path, monkeypatch):
+    """Mirrors ``FAILPROOFAI_HOME`` in fp-home.ts; containers rely on it."""
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path / "elsewhere"))
+    assert _resolver.get_base_dir() == tmp_path / "elsewhere" / "custom-agents"
+
+
+def test_the_retired_opt_in_variable_no_longer_exists():
+    """It was the entry point to the dead branch; leaving it would mislead.
+
+    Anyone who exported it wanted the umbrella and now gets it by default, so
+    removing it changes no behaviour for them — only the docs they read.
+    """
+    assert not hasattr(_resolver, "SPOOL_OPT_IN_ENV")
+
+
+def test_the_retired_opt_in_variable_has_no_effect_if_someone_still_exports_it(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.setenv("AGENTEYE_SPOOL_TO_FAILPROOFAI", "0")
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_the_legacy_root_is_still_spelled_somewhere_findable(tmp_path, monkeypatch):
+    """The migration notes and the escape hatch both name it; one definition."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    assert _resolver.legacy_agenteye_dir() == tmp_path / ".agenteye"