failproofai 1.0.1 → 1.0.2-beta.0

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

@@ -0,0 +1,287 @@
+"""The SDK must write where the shipped daemons read.
+
+This is the cross-component test, and it exists because the divergence it checks
+for is invisible from either side alone: the SDK's own tests pass while writing
+to a directory nothing watches, and the daemon's own tests pass while watching a
+directory nothing writes to. Both suites green, zero events uploaded, no error
+anywhere. Silent total data loss is the failure mode this file is here to make
+loud.
+
+Two daemons read this SDK's spool, and only one of them is in this repository:
+
+  * ``failproofaid`` — here, in ``crates/fpai-collect``. Watches BOTH roots.
+    Checkable, and checked below without skipping.
+  * ``agenteye-collector`` — in the private AgentEye repository. Watches only
+    ``$AGENTEYE_HOME`` / ``~/.agenteye`` (which this SDK no longer resolves,
+    but the daemon still WATCHES). Checkable only when a checkout is on
+    disk, so it is opt-in via ``FP_AGENTEYE_ROOT``.
+
+The predecessor of this file gated EVERY test in it on a source file from that
+other repository, so all four skipped in normal runs — including the three that
+assert nothing but this SDK's own behaviour and need no other repo at all. A
+test that always skips is not a guard. Hence the split below, and hence
+``FAILPROOFAI_SDK_REQUIRE_CONTRACT=1``, which CI sets to turn the remaining
+skips into failures so "the file moved" can never quietly read as "green".
+"""
+import os
+import re
+from pathlib import Path
+
+import pytest
+
+from failproofai_sdk import _resolver
+
+# tests/ -> python/ -> sdk/ -> repo root.
+#
+# Guarded, because `parents[3]` raises IndexError on a shallower tree — and a
+# shallower tree is exactly the packaged-sdist case `_read_sibling` below is
+# written to handle gracefully. Unguarded, it raised at IMPORT, which pytest
+# reports as a collection error and which aborts the WHOLE suite rather than
+# skipping the one file that needs the repo. Reproduced by copying `sdk/python`
+# somewhere on its own and running pytest: 428 passing tests became `1 error`.
+_HERE = Path(__file__).resolve()
+REPO_ROOT = _HERE.parents[3] if len(_HERE.parents) > 3 else _HERE.parent
+FPAI_COLLECT_CONFIG = REPO_ROOT / "crates" / "fpai-collect" / "src" / "config.rs"
+FP_HOME_TS = REPO_ROOT / "src" / "hooks" / "fp-home.ts"
+
+#: Set by CI. Turns "the source I read is missing" from a skip into a failure.
+REQUIRE = os.environ.get("FAILPROOFAI_SDK_REQUIRE_CONTRACT", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+
+
+def _read_sibling(path: Path) -> str:
+    """Source of a same-repo file, or skip/fail depending on ``REQUIRE``.
+
+    Missing means one of two things: this is an installed sdist (fine — there is
+    no repo to read), or somebody moved the file (not fine). ``REQUIRE``
+    distinguishes them, because from in here they look identical.
+    """
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    message = (
+        f"{path.relative_to(REPO_ROOT) if REPO_ROOT in path.parents else path} is "
+        "missing. In a packaged sdist that is expected. In the repository it means "
+        "the file moved, and this contract is now unguarded — re-point this test at "
+        "the new location rather than deleting it."
+    )
+    if REQUIRE:
+        pytest.fail(message)
+    pytest.skip(message)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# This SDK's own resolution rule. Depends on nothing outside this package, so
+# it never skips, ever.
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_sdk_default_is_the_umbrella(tmp_path, monkeypatch):
+    """No configuration: the umbrella root, which failproofaid watches."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.delenv("AGENTEYE_HOME", raising=False)
+    monkeypatch.delenv("FAILPROOFAI_HOME", raising=False)
+    _resolver.set_base_dir(None)
+
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_the_legacy_root_is_not_reachable_through_agenteye_home(tmp_path, monkeypatch):
+    """The SDK side of the contract: this package writes to the umbrella, period.
+
+    `$AGENTEYE_HOME` used to sit above the default here, so exporting it for
+    `agenteye-collector` — the component below that genuinely reads it — moved
+    this SDK's spool too, as an unasked-for side effect. It no longer resolves
+    anything in this package. The daemon assertions further down still require
+    `failproofaid` to WATCH `~/.agenteye/events`, which is what keeps already
+    written batches and unupgraded SDKs collected.
+    """
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.delenv("FAILPROOFAI_HOME", raising=False)
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / ".agenteye"))
+    _resolver.set_base_dir(None)
+
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+def test_agenteye_home_overrides_nothing_in_this_package(tmp_path, monkeypatch):
+    """It is still the collector's variable; it is no longer ours."""
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: tmp_path))
+    monkeypatch.delenv("FAILPROOFAI_HOME", raising=False)
+    monkeypatch.setenv("AGENTEYE_HOME", str(tmp_path / "shared"))
+    _resolver.set_base_dir(None)
+
+    assert _resolver.get_base_dir() == tmp_path / ".failproofai" / "custom-agents"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# failproofaid — same repository, so these are hard assertions.
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_failproofaid_watches_the_legacy_agenteye_root():
+    """``crates/fpai-collect`` must keep reading ``~/.agenteye``.
+
+    This is the assertion that protects every already-deployed SDK. Dropping
+    this root from the daemon does not break a build or a test on the Rust side
+    — it just means an unupgraded SDK writes into a directory nothing reads.
+    """
+    src = _read_sibling(FPAI_COLLECT_CONFIG)
+
+    assert "fn agenteye_events_dir()" in src, (
+        "crates/fpai-collect no longer defines agenteye_events_dir(). Every SDK "
+        "release to date writes to ~/.agenteye/events by default; removing that "
+        "root silently strands all of them."
+    )
+    assert 'var_os("AGENTEYE_HOME")' in src
+    assert '".agenteye"' in src
+    assert 'join("events")' in src
+
+
+def test_failproofaid_watches_both_roots_in_one_list():
+    """Both spool roots must be in the daemon's watch list, not just defined."""
+    src = _read_sibling(FPAI_COLLECT_CONFIG)
+
+    match = re.search(r"for sdk_spool in \[([^\]]*)\]", src)
+    assert match, (
+        "the spool_dirs loop in crates/fpai-collect/src/config.rs was "
+        "restructured. Find where the daemon now assembles the directories it "
+        "watches and re-point this assertion; a defined-but-unwatched root reads "
+        "as working from every side."
+    )
+    watched = match.group(1)
+    assert "custom_agents_events_dir" in watched
+    assert "agenteye_events_dir" in watched
+
+
+def test_umbrella_path_agrees_with_rust_and_typescript():
+    """``~/.failproofai/custom-agents`` is spelled the same in all three languages."""
+    rust = _read_sibling(FPAI_COLLECT_CONFIG)
+    typescript = _read_sibling(FP_HOME_TS)
+
+    assert 'join("custom-agents")' in rust
+    assert '"custom-agents"' in typescript
+    assert 'atHome(home, "custom-agents")' in typescript, (
+        "src/hooks/fp-home.ts no longer derives customAgentsDir from atHome(). "
+        "atHome() is what applies FAILPROOFAI_HOME, which _resolver mirrors."
+    )
+    # The SDK's own spelling of the same path, under a fake home.
+    assert _resolver.failproofai_custom_agents_dir().name == "custom-agents"
+
+
+def test_failproofai_home_is_honoured_the_same_way_on_both_sides(tmp_path, monkeypatch):
+    """``FAILPROOFAI_HOME`` moves the umbrella root for the SDK and the TS alike."""
+    typescript = _read_sibling(FP_HOME_TS)
+    assert "process.env.FAILPROOFAI_HOME" in typescript
+
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path / "elsewhere"))
+    assert _resolver.failproofai_custom_agents_dir() == (
+        tmp_path / "elsewhere" / "custom-agents"
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# agenteye-collector — private repository. Opt-in via FP_AGENTEYE_ROOT.
+# ─────────────────────────────────────────────────────────────────────────────
+
+_AGENTEYE_ROOT = os.environ.get("FP_AGENTEYE_ROOT")
+_agenteye_collector_config = (
+    Path(_AGENTEYE_ROOT) / "collector" / "src" / "config.rs" if _AGENTEYE_ROOT else None
+)
+
+requires_agenteye_checkout = pytest.mark.skipif(
+    _agenteye_collector_config is None or not _agenteye_collector_config.is_file(),
+    reason="set FP_AGENTEYE_ROOT to an AgentEye checkout to verify the older collector",
+)
+
+
+@requires_agenteye_checkout
+def test_agenteye_collector_still_reads_only_agenteye_home_and_dot_agenteye():
+    """Pins the premise the SDK default rests on, on the older collector."""
+    src = _agenteye_collector_config.read_text(encoding="utf-8")
+    start = src.find("pub fn base_dir()")
+    assert start != -1, (
+        "the AgentEye collector's `pub fn base_dir()` is gone. It is the other "
+        "half of this contract — find where it now resolves its spool root and "
+        "re-point this test at it rather than deleting the test."
+    )
+    end = src.find("\nfn ", start)
+    body = src[start : end if end != -1 else len(src)]
+
+    assert 'var("AGENTEYE_HOME")' in body
+    assert '".agenteye"' in body
+    # The load-bearing half. This collector NOT knowing the umbrella is the
+    # entire reason `AGENTEYE_HOME` is documented as the escape hatch for hosts
+    # running it. If it ever learns the umbrella root, that advice becomes
+    # unnecessary and the migration note should be retired — deliberately, not
+    # by someone noticing years later.
+    assert "failproofai" not in body.lower(), (
+        "the AgentEye collector now mentions failproofai in base_dir(). If it "
+        "genuinely watches ~/.failproofai/custom-agents, the AGENTEYE_HOME "
+        "escape hatch this SDK documents for legacy hosts is no longer needed "
+        "— retire it on purpose, not silently."
+    )
+
+
+def test_this_file_can_be_imported_outside_the_repository():
+    """A collection error here aborts the whole suite, not just this file.
+
+    `_read_sibling` is written to skip when the repo is absent — "in a packaged
+    sdist that is expected" — but `parents[3]` raised IndexError at import
+    before any of that could run, so the graceful path was unreachable in the
+    one situation it exists for.
+    """
+    assert REPO_ROOT.is_absolute()
+    # The real repo has these; an sdist does not, and then the guards skip.
+    if FPAI_COLLECT_CONFIG.is_file():
+        assert FP_HOME_TS.is_file(), "half the contract's sources are missing"
+
+
+# --- The README is part of the contract too -----------------------------------
+#
+# The three assertions above pin the spool root across Python, Rust and
+# TypeScript, so the code cannot drift. Nothing pinned the README, and it drifted
+# on its own: after the default moved to ~/.failproofai/custom-agents, the
+# architecture diagram, the configure() comment and the JSONL example were all
+# still showing ~/.agenteye/events — contradicted by correct prose two lines away.
+#
+# That is not a cosmetic miss. A reader follows the code sample, tails a
+# directory nothing writes to, sees an empty spool, and concludes the SDK is
+# broken — which is the same "an unread spool is indistinguishable from an idle
+# one" failure this whole file exists to make loud, just relocated into the docs.
+
+README = Path(__file__).resolve().parents[1] / "README.md"
+
+# ~/.agenteye is still allowed to appear in the migration notes, which exist to
+# tell legacy hosts what to set. What is NOT allowed is presenting it as where
+# batches land today.
+_SPOOL_FILE_LINE = re.compile(r"events/(\*|event-)[^\s`]*\.jsonl")
+
+
+def test_readme_shows_the_current_spool_root_wherever_it_shows_a_batch_path():
+    offenders = [
+        f"README.md:{i}: {line.strip()}"
+        for i, line in enumerate(README.read_text(encoding="utf-8").split("\n"), 1)
+        if _SPOOL_FILE_LINE.search(line) and "custom-agents" not in line
+    ]
+    assert not offenders, (
+        "the README shows a spool batch path that is not the current default "
+        f"({_resolver.failproofai_custom_agents_dir()}); a reader will tail a "
+        "directory nothing writes to:\n  " + "\n  ".join(offenders)
+    )
+
+
+def test_readme_documents_the_current_default_for_base_dir():
+    """The `configure(base_dir=...)` comment must not name the retired root as the default."""
+    text = README.read_text(encoding="utf-8")
+    assert "~/.failproofai/custom-agents" in text, (
+        "the README never spells the current default spool root"
+    )
+    for i, line in enumerate(text.split("\n"), 1):
+        if "Default:" in line and ".agenteye" in line:
+            assert "custom-agents" in line, (
+                f"README.md:{i} gives the retired root as the default: {line.strip()}"
+            )

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

@@ -0,0 +1,360 @@
+"""The SDK creates its spool path and NOTHING else, at every level.
+
+This SDK installs into other people's agent processes and now writes inside
+`~/.failproofai`, a directory the CLI and the daemon own. So the rule is not
+merely "make the directory work" — it is that a machine which has only ever run
+this SDK must be indistinguishable, to every other component, from a machine
+that has run nothing at all.
+
+`detectLayout()` in `src/hooks/fp-config.ts` is the reason that matters. It
+decides whether a home is `absent`, `current`, `stale` or `future`, and a
+`stale` verdict authorises `resetHome()`, which deletes files. Its landmarks are
+`VERSION`, `config.json`, `config.toml`, and layout 1's seven markers. Creating
+any of those from here would hand the CLI a half-built home it believes it wrote
+— so the only safe thing to create is the spool path itself.
+
+The three cases below are the three states a machine can be in, and each asserts
+the EXACT set of paths that appear. An assertion on "the events dir exists" would
+pass just as happily if a `VERSION` file appeared beside it.
+"""
+import json
+import os
+import stat
+import time
+
+import pytest
+
+from failproofai_sdk import _resolver, _runtime
+from failproofai_sdk._events import EventNamespace
+from failproofai_sdk._writer import EventWriter
+
+#: The interval `_runtime.writer` runs on outside this suite — what a regression
+#: would have to wait out. Read off the constructor default rather than restated.
+_DEFAULT_FLUSH_INTERVAL = EventWriter.__init__.__defaults__[0]
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+    """An isolated HOME with no failproofai directory at all."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path / ".failproofai"))
+    monkeypatch.delenv("AGENTEYE_HOME", raising=False)
+    _resolver.set_base_dir(None)
+    yield tmp_path
+    _resolver.set_base_dir(None)
+
+
+def tree(root):
+    """Every path under `root`, relative and sorted. The whole filesystem effect."""
+    if not root.exists():
+        return []
+    return sorted(str(p.relative_to(root)) for p in root.rglob("*"))
+
+
+def emit_one(goal="e"):
+    writer = EventWriter(flush_interval=3600)
+    EventNamespace(writer).agent_start(session_id="s", agent_id="a", goal=goal)
+    writer.flush_now()
+    return writer
+
+
+#: What a single published batch must add, and the complete list of it.
+def spool_paths(batch_names):
+    return sorted(["custom-agents", "custom-agents/events", *[f"custom-agents/events/{n}" for n in batch_names]])
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Case 1 — the umbrella spool already exists: add a batch, create nothing else
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_when_the_spool_exists_only_a_batch_file_appears(home):
+    fp = home / ".failproofai"
+    (fp / "custom-agents" / "events").mkdir(parents=True)
+    before = tree(fp)
+
+    emit_one()
+
+    after = tree(fp)
+    added = [p for p in after if p not in before]
+    assert len(added) == 1, f"expected one new batch file, got {added}"
+    assert added[0].startswith("custom-agents/events/event-")
+    assert added[0].endswith(".jsonl")
+
+
+def test_an_existing_failproofai_home_is_not_otherwise_disturbed(home):
+    """A configured machine must come through completely untouched.
+
+    Not just "the files are still there" — unchanged. A rewritten `config.json`
+    with identical content would still be a component writing into a file it
+    does not own.
+    """
+    fp = home / ".failproofai"
+    (fp / "custom-agents" / "events").mkdir(parents=True)
+    (fp / "VERSION").write_text('{"layout":4,"cli":"1.0.1"}')
+    (fp / "config.json").write_text('{"mode":{"kind":"oss"}}')
+    (fp / "credentials.json").write_text('{"token":"secret"}')
+    (fp / "policies").mkdir()
+    (fp / "policies" / "mine.mjs").write_text("// mine")
+    (fp / "hook-activity").mkdir()
+
+    owned = {
+        p: (p.read_bytes(), p.stat().st_mtime_ns)
+        for p in (fp / "VERSION", fp / "config.json", fp / "credentials.json", fp / "policies" / "mine.mjs")
+    }
+
+    emit_one()
+
+    for path, (content, mtime) in owned.items():
+        assert path.read_bytes() == content, f"{path.name} was rewritten"
+        assert path.stat().st_mtime_ns == mtime, f"{path.name} was touched"
+    assert (fp / "hook-activity").is_dir()
+    assert sorted(p.name for p in fp.iterdir()) == [
+        "VERSION", "config.json", "credentials.json", "custom-agents", "hook-activity", "policies",
+    ]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Case 2 — the home exists, the spool does not: create only the spool
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_when_the_home_exists_only_the_spool_path_is_created(home):
+    fp = home / ".failproofai"
+    fp.mkdir()
+    (fp / "VERSION").write_text('{"layout":4,"cli":"1.0.1"}')
+    before = tree(fp)
+
+    emit_one()
+
+    added = [p for p in tree(fp) if p not in before]
+    batch = [p for p in added if p.endswith(".jsonl")]
+    assert len(batch) == 1
+    assert sorted(added) == spool_paths([batch[0].rsplit("/", 1)[-1]]), (
+        f"created something beyond the spool path: {added}"
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Case 3 — nothing exists: create the home and the spool, and stop there
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_when_nothing_exists_only_the_home_and_the_spool_are_created(home):
+    fp = home / ".failproofai"
+    assert not fp.exists()
+
+    emit_one()
+
+    assert fp.is_dir()
+    created = tree(fp)
+    batch = [p for p in created if p.endswith(".jsonl")]
+    assert len(batch) == 1
+    assert created == spool_paths([batch[0].rsplit("/", 1)[-1]]), (
+        f"a fresh home got more than the spool: {created}"
+    )
+
+
+@pytest.mark.parametrize(
+    "landmark",
+    ["VERSION", "config.json", "config.toml", "policies-config.json", "last-version", "cloud.json"],
+)
+def test_no_layout_landmark_is_ever_created(home, landmark):
+    """Each of these tells `detectLayout()` a different story, none of them true.
+
+    `VERSION`/`config.json` would report a home this SDK never built as
+    `current`; `config.toml` and layout 1's markers report it `stale`, which is
+    what authorises `resetHome()` to start deleting. The SDK has no business
+    voting on any of it.
+    """
+    emit_one()
+    assert not (home / ".failproofai" / landmark).exists()
+
+
+def test_a_home_built_only_by_the_sdk_looks_unconfigured(home):
+    """The cross-component property, asserted from this side.
+
+    Verified against the real `detectLayout()` too: a home holding only
+    `custom-agents/` returns `{kind: "absent"}` and `isConfigured()` is false.
+    Pinned here so a change on THIS side that starts writing a landmark fails in
+    the SDK's own suite rather than in the CLI's, months later.
+    """
+    emit_one()
+    fp = home / ".failproofai"
+    assert sorted(p.name for p in fp.iterdir()) == ["custom-agents"]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Repeat writes, permissions, and the failure paths
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_repeated_flushes_do_not_recreate_or_churn_the_directories(home):
+    writer = EventWriter(flush_interval=3600)
+    ns = EventNamespace(writer)
+    ns.agent_start(session_id="s", agent_id="a", goal="one")
+    writer.flush_now()
+
+    events = home / ".failproofai" / "custom-agents" / "events"
+    inode = events.stat().st_ino
+
+    for i in range(5):
+        ns.agent_start(session_id="s", agent_id="a", goal=f"more-{i}")
+        writer.flush_now()
+
+    assert events.stat().st_ino == inode, "the events directory was replaced"
+    assert len(list(events.glob("*.jsonl"))) == 6
+    assert list(events.glob("*.tmp")) == [], "a temp file was left behind"
+
+
+def test_the_process_wide_writer_cannot_flush_into_the_running_test(home):
+    """The count above is only meaningful if nothing else writes here.
+
+    `_runtime.writer` starts at import on a 0.5s interval, and the spool path is
+    resolved when a batch is WRITTEN, not when the event is submitted. So an
+    event queued while one test's `FAILPROOFAI_HOME` was current gets written
+    into whichever test is running half a second later, with no error on either
+    side — the test above then counts seven batch files where it wrote six. It
+    reached CI exactly once, on one interpreter out of five.
+
+    `conftest._quiesce_the_process_wide_writer` closes it. This asserts the
+    EFFECT rather than the interval, so it still fails if the loop acquires
+    another way to wake — and it waits well past the 0.5s default, so a
+    regression cannot pass by being fast.
+    """
+    events = home / ".failproofai" / "custom-agents" / "events"
+
+    _runtime.writer.submit(
+        {"type": "agent_start", "session_id": "leak", "agent_id": "a", "goal": "must not land here"}
+    )
+    try:
+        time.sleep(_DEFAULT_FLUSH_INTERVAL * 3)
+        assert not events.exists() or list(events.glob("*.jsonl")) == [], (
+            "the process-wide writer flushed into a test's spool"
+        )
+    finally:
+        # Drop it rather than flush it: flushing would write the event into this
+        # test's directory, which is the thing being ruled out.
+        _runtime.writer._queue.clear()
+        _runtime.writer._queued_bytes = 0
+
+
+def test_created_directories_are_owner_writable_and_not_world_writable(home):
+    emit_one()
+    for d in (
+        home / ".failproofai",
+        home / ".failproofai" / "custom-agents",
+        home / ".failproofai" / "custom-agents" / "events",
+    ):
+        mode = stat.S_IMODE(d.stat().st_mode)
+        assert mode & stat.S_IRWXU == stat.S_IRWXU, f"{d} is not owner-rwx"
+        assert not mode & stat.S_IWOTH, f"{d} is world-writable"
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason="root ignores directory permissions")
+def test_an_unwritable_home_raises_and_keeps_the_events_queued(home):
+    """A permission error must not be mistaken for a delivered batch.
+
+    `_flush` returns the drained entries to the queue and re-raises, so the next
+    interval retries them. Dropping here would lose live events to a condition
+    that is usually temporary — a home mounted read-only, a directory an
+    installer briefly re-owned.
+    """
+    fp = home / ".failproofai"
+    fp.mkdir(mode=0o500)
+    try:
+        writer = EventWriter(flush_interval=3600)
+        EventNamespace(writer).agent_start(session_id="s", agent_id="a", goal="held")
+        with pytest.raises(OSError):
+            writer.flush_now()
+        assert len(writer._queue) == 1, "events were dropped on a permission error"
+    finally:
+        fp.chmod(0o700)
+
+
+def test_agenteye_home_no_longer_bypasses_the_umbrella(home, monkeypatch):
+    """Emitting with it exported must build the umbrella and NOT the legacy tree.
+
+    The observable half of the resolver change: not just "resolution returns a
+    different path", but "the batch is on disk under ~/.failproofai and nothing
+    was created under ~/.agenteye".
+    """
+    legacy = home / ".agenteye"
+    monkeypatch.setenv("AGENTEYE_HOME", str(legacy))
+    _resolver.set_base_dir(None)
+
+    emit_one()
+
+    assert not legacy.exists(), "the legacy root was created despite the change"
+    umbrella = home / ".failproofai" / "custom-agents"
+    assert umbrella.exists(), "the umbrella was not created"
+    assert list((umbrella / "events").glob("*.jsonl")), "no batch landed in the umbrella"
+
+
+def test_the_batch_written_is_readable_and_carries_the_event(home):
+    """Creating directories is worthless if the payload does not survive it."""
+    emit_one(goal="round-trip")
+    events = home / ".failproofai" / "custom-agents" / "events"
+    (batch,) = list(events.glob("*.jsonl"))
+    rows = [json.loads(line) for line in batch.read_text(encoding="utf-8").splitlines()]
+    assert [r["goal"] for r in rows] == ["round-trip"]
+    assert rows[0]["type"] == "agent_start"
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason="root ignores file permissions")
+def test_batches_and_the_events_dir_are_not_readable_by_other_local_users(home):
+    """These files are transcripts, not metadata.
+
+    A batch carries `goal`, prompt text, tool arguments and tool output straight
+    from the host agent. Under the ordinary `umask 022` they landed `0644` inside
+    `0755` directories, so on any shared host — a build box, a bastion, a
+    container with several service accounts — every other local user could read
+    every agent transcript this SDK spools, for the whole flush+upload window and
+    indefinitely if no daemon is running.
+
+    The sibling `fp-cloud-cli` already writes its credential `0600` inside a `0700`
+    directory, so the asymmetry was an oversight rather than a house style. The
+    daemon reads these as the SAME user (its unit is `User=<user>` with `HOME`
+    set to that user's home), so tightening them costs no delivery.
+    """
+    prev = os.umask(0o022)
+    try:
+        emit_one(goal="SECRET-GOAL-TEXT")
+    finally:
+        os.umask(prev)
+
+    events = home / ".failproofai" / "custom-agents" / "events"
+    assert stat.S_IMODE(events.stat().st_mode) == 0o700, "events dir is enterable by others"
+
+    batches = list(events.glob("*.jsonl"))
+    assert batches, "nothing was published"
+    for batch in batches:
+        mode = stat.S_IMODE(batch.stat().st_mode)
+        assert mode == 0o600, f"{batch.name} is {oct(mode)}, not 0600"
+
+
+def test_a_tilde_base_dir_is_expanded_rather_than_taken_literally(home, monkeypatch, tmp_path):
+    """`configure(base_dir="~/.agenteye")` is a recipe this package prescribes.
+
+    `_resolver.get_base_dir`'s own docstring lists it as one of three supported
+    bridges for a host still running the older `agenteye-collector`, and calls it
+    the explicit, visible-at-the-call-site one. `Path("~/.agenteye")` is a
+    RELATIVE path whose first segment is the literal character `~`, so without
+    `expanduser` the writer's `mkdir(parents=True)` created a `~` directory under
+    whatever the process's cwd happened to be and spooled into it. Nothing on the
+    machine watches that path: 100% of the telemetry is lost, silently, which is
+    the exact "an unread spool is indistinguishable from an idle one" failure the
+    prose around that docstring exists to prevent.
+    """
+    monkeypatch.chdir(tmp_path)
+    _resolver.set_base_dir("~/.agenteye")
+    try:
+        resolved = _resolver.get_base_dir()
+        assert resolved.is_absolute(), f"{resolved} is relative"
+        assert resolved == home / ".agenteye"
+
+        emit_one()
+        assert not (tmp_path / "~").exists(), "spooled into a literal '~' directory"
+        assert list((home / ".agenteye" / "events").glob("*.jsonl"))
+    finally:
+        _resolver.set_base_dir(None)