agent-bios 0.13.0 → 0.14.0

package/learn/collect-learning.py

@@ -27,8 +27,10 @@ Input:  the semantic payload as one JSON object on stdin.
 Host:   --host claude|codex (default: the tool prefix of supporting_sessions[0]).
 Home:   --config-dir, else $CLAUDE_CONFIG_DIR / $CODEX_HOME by host, else ~/.claude / ~/.codex.
 After the local writes it best-effort uploads not-yet-delivered records to
-{ingest-url}/api/ingest/learnings via a watermark over learnings.jsonl (Phase 2
-transport; skipped when the dashboard hook is not installed, or with --no-upload).
+{base}/api/ingest/learnings via a watermark over learnings.jsonl. The base and
+token resolve from the agent-bios-owned slot ~/.config/agent-bios/{ingest-url,
+token} — the one transport contract, written by whoever adopts this install;
+skipped when it is unset, or with --no-upload.
 """
 import argparse
 import datetime
@@ -38,8 +40,10 @@ import os
 import pathlib
 import shutil
 import sys
+import http.client
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 import uuid
 
@@ -314,35 +318,139 @@ UPLOAD_LIMIT = 25          # max POSTs per invocation
 UPLOAD_BUDGET_S = 5.0      # total wall-clock budget for the whole drain
 UPLOAD_TIMEOUT_S = 3.0     # per-request socket timeout
 PERMANENT_STATUSES = frozenset({400, 413})  # never succeeds → settle as dead
+# A record or token urllib cannot turn into a request will never succeed either,
+# so it settles like a 400 rather than stopping the drain: classed transient, one
+# poison record wedged every later upload behind it and reported the wedge as a
+# server outage (PR #44 regression review).
+UNSENDABLE = "unsendable"
 
 
-def transport_config(home):
-    """Read the dashboard hook's token + ingest base URL (READ-ONLY; the hook dir
-    is dashboard-owned — we never write it). Returns ((token, base), None) or
-    (None, reason) when the hook is not installed (Q-E: caller prints a notice)."""
-    hook_dir = home / "hooks"
-    token_file = hook_dir / "token"
-    if not token_file.is_file():
-        return None, "dashboard hook not installed (no token)"
+def invalid_base(base):
+    """None when `base` can carry a POST, else the reason. urllib turns a
+    scheme-less or host-less value into a ValueError at request construction,
+    which is a crash rather than a contract answer."""
     try:
-        token = token_file.read_text(encoding="utf-8").strip()
+        parts = urllib.parse.urlsplit(base)
+    except ValueError as e:
+        return f"unparseable ({e})"
+    if parts.scheme not in ("http", "https"):
+        return "no http(s) scheme"
+    try:
+        parts.port                    # raises for a port urllib will not accept
+    except ValueError as e:
+        return f"unusable port ({e})"
+    try:
+        parts.hostname.encode("idna")   # a label urllib cannot encode at send
+    except (UnicodeError, AttributeError):
+        if parts.hostname:
+            return "host is not encodable"
+    if not parts.hostname:
+        # netloc alone is not enough: a value that is only a scheme and a port
+        # has a netloc and no host at all.
+        return "no host"
+    if "?" in base or "#" in base:
+        # The request path is APPENDED to this value as a string, so a base
+        # carrying a query or fragment produces `...?tenant=1/api/ingest/...` —
+        # a different selector than the contract names, which a server may
+        # answer 2xx to. The concatenation is the reason, so the refusal belongs
+        # here rather than at the send.
+        #
+        # Asked of the RAW value, not of `parts.query`/`parts.fragment`: urlsplit
+        # represents a bare `https://h.test?` as an empty string, which is falsy,
+        # so a truthiness test accepted exactly the delimiters that corrupt the
+        # selector. Present-but-empty is not absent.
+        return "carries a query or fragment"
+    return None
+
+
+def transport_config(slot_root=None):
+    """Resolve the upload transport (READ-ONLY; the slot is never written here).
+
+    ONE contract, no fallback: the agent-bios-owned slot
+    ~/.config/agent-bios/{ingest-url,token}, one slot for both hosts. A slot
+    with either file present is claimed and must be complete and non-empty,
+    failing loud rather than degrading. Nothing about any organization is known
+    here — filling the slot is the adopter's side of the contract
+    (ENDPOINTS.md §Transport configuration), which is what lets this file ship
+    to anyone.
+
+    Returns ((token, base), None) or (None, reason); caller prints a notice."""
+    slot = (slot_root or pathlib.Path.home()) / ".config" / "agent-bios"
+    slot_token, slot_url = slot / "token", slot / "ingest-url"
+    # Two questions, deliberately separated. FIRST: can the slot be looked at at
+    # all? A path predicate answers False for both "absent" and "cannot look" (an
+    # EACCES at or above the slot), and reading the second as the first silently
+    # selected the legacy endpoint. Only ENOENT means absent; every other OSError
+    # is a claim we cannot read. The listing is CONSUMED because iterdir() may be
+    # a lazy generator — an unconsumed call can raise nothing at all.
+    # SECOND (below): is each file there? That is asked of the filesystem rather
+    # than of the listing's names, because a name-set test is case-sensitive and
+    # a case-insensitive filesystem (APFS) then stopped claiming a working slot
+    # holding TOKEN/INGEST-URL, resolving the legacy endpoint with no notice.
+    try:
+        list(slot.iterdir())
+    except FileNotFoundError:
+        pass
+    except NotADirectoryError:
+        return None, (f"transport slot {slot} is not a directory "
+                      "(a claimed slot never falls back)")
     except OSError as e:
-        return None, f"cannot read hook token ({e})"
-    if not token:
-        return None, "dashboard hook token is empty"
-    base = ""
-    # The installer writes `dashboard-url`; a migrated install may also have
-    # `ingest-url`. Prefer ingest-url, fall back to dashboard-url.
-    for name in ("ingest-url", "dashboard-url"):
-        f = hook_dir / name
-        if f.is_file():
-            candidate = f.read_text(encoding="utf-8").strip()
-            if candidate:
-                base = candidate
-                break
-    if not base:
-        return None, "dashboard hook ingest URL not found"
-    return (token, base.rstrip("/")), None
+        return None, (f"transport slot {slot} cannot be read ({e}) — "
+                      "a claimed slot never falls back")
+    # EXISTENCE and SHAPE are separate questions, and collapsing them is what
+    # this seam keeps getting wrong. `is_file()` answers False for a directory
+    # and for a dangling symlink as readily as for an absent path, so a slot
+    # holding either stopped being claimed and fell through to the legacy
+    # endpoint with no notice. `lstat` answers only "is something here",
+    # without following the link or judging its type; the shape is then a
+    # separate, loud requirement.
+    def present(path):
+        try:
+            os.lstat(path)
+        except FileNotFoundError:
+            return False
+        except OSError:
+            return True          # something is there and we cannot look at it
+        return True
+
+    if present(slot_token) or present(slot_url):
+        for f, what in ((slot_token, "token"), (slot_url, "ingest-url")):
+            if not present(f):
+                return None, (f"transport slot {slot} is missing {what} "
+                              "(a claimed slot never falls back)")
+            if not f.is_file():
+                return None, (f"transport slot {slot} has {what} but it is not a "
+                              "readable file (a claimed slot never falls back)")
+        # One read per try, so the reason can name the file that actually
+        # failed — a shared try knows only that something did.
+        values = {}
+        for f, what in ((slot_token, "token"), (slot_url, "ingest-url")):
+            try:
+                values[what] = f.read_text(encoding="utf-8").strip()
+            except (OSError, ValueError) as e:
+                # ValueError covers UnicodeDecodeError: a slot file that is not
+                # UTF-8 is a broken claim, and raising here killed learn! the
+                # same way a bad URL did.
+                return None, f"cannot read transport slot file {f} ({e})"
+        token, base = values["token"], values["ingest-url"]
+        if not token:
+            return None, f"transport slot token is empty ({slot_token})"
+        if not token.isascii() or not token.isprintable():
+            # A token urllib will not put in a header is a config error, and
+            # discovering that at send time costs the whole drain.
+            return None, (f"transport slot token is not usable as a header value "
+                          f"({slot_token})")
+        if not base:
+            return None, f"transport slot ingest-url is empty ({slot_url})"
+        bad = invalid_base(base)
+        if bad:
+            # Validated where the value is PRODUCED: a hand-typed url reaching
+            # http_post raised out of the drain and killed learn! after its
+            # local writes, and a transient skip would have hidden the typo.
+            return None, (f"transport slot ingest-url is not a usable endpoint "
+                          f"({bad}: {base!r} in {slot_url})")
+        return (token, base.rstrip("/")), None
+    return None, f"no transport configured (no {slot} slot)"
 
 
 def read_jsonl_records(jsonl):
@@ -391,6 +499,10 @@ def save_state(home, state, present_ids):
 
 
 def classify_status(status):
+    if status == UNSENDABLE:
+        # Before any numeric comparison: this is not a status at all, and the
+        # range checks below raise TypeError on it.
+        return "permanent"
     if status is None:
         return "transient"           # network error / timeout
     if 200 <= status < 300:
@@ -400,29 +512,72 @@ def classify_status(status):
     return "transient"               # 401/403/404/429/503/5xx → retry next time
 
 
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Refuse redirects: urllib re-sends a redirected POST as a bodyless GET, so
+    a 3xx (e.g. an http→https proxy hop) would settle the record while delivering
+    nothing. The 3xx surfaces as its own status instead → transient (fix the
+    configured URL; the record stays queued)."""
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+_NO_REDIRECT_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
 def http_post(base, token, record, timeout=UPLOAD_TIMEOUT_S):
-    """POST one record; return the HTTP status int, or None on a network error."""
-    body = json.dumps(record, ensure_ascii=False).encode("utf-8")
-    req = urllib.request.Request(base + INGEST_PATH, data=body, method="POST")
-    req.add_header("Content-Type", "application/json")
-    req.add_header("X-Hook-Token", token)
+    """POST one record. Returns the HTTP status int, None when the endpoint could
+    not be reached or used (transient — the record stays queued), or UNSENDABLE
+    when THIS RECORD can never be serialized (permanent — it settles).
+
+    Construction is inside the try with the send: a value urllib refuses to turn
+    into a request (a scheme-less base, a header it cannot encode) is an
+    unreachable endpoint like any other, and raising here killed learn! after
+    its local writes. transport_config rejects such a base up front, with the
+    file named — this is the belt behind that."""
+    try:
+        body = json.dumps(record, ensure_ascii=False).encode("utf-8")
+    except (ValueError, UnicodeError):
+        # THIS RECORD can never be sent — settle it so the queue keeps moving.
+        return UNSENDABLE
     try:
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
+        req = urllib.request.Request(base + INGEST_PATH, data=body, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("X-Hook-Token", token)
+        with _NO_REDIRECT_OPENER.open(req, timeout=timeout) as resp:
             return resp.status
     except urllib.error.HTTPError as e:
         return e.code
-    except (urllib.error.URLError, TimeoutError, OSError):
+    except (urllib.error.URLError, TimeoutError, OSError,
+            http.client.HTTPException, ValueError, UnicodeError):
+        # A broken hop — a refused connection, a timeout, a gateway emitting a
+        # malformed status line — is the network, so the record stays pending.
+        #
+        # The same answer covers the endpoint and its configuration: a base
+        # urllib rejects (InvalidURL inherits both HTTPException and
+        # ValueError), a host label it cannot encode, a token it will not put in
+        # a header. Those are transient BY DESIGN — the records must survive so
+        # that fixing the configured value delivers them — and transport_config
+        # refuses such values up front anyway, with the file named. A second
+        # `return None` used to sit below this one to say so; it was
+        # unreachable, and a statement no execution can reach is a comment
+        # wearing code's clothes. Measured, not noticed.
         return None
 
 
 def drain_uploads(home, post_fn=http_post, now=time.monotonic,
-                  limit=UPLOAD_LIMIT, budget_s=UPLOAD_BUDGET_S):
-    """Best-effort upload of not-yet-settled learnings. post_fn/now are injectable
-    for the self-test (no sockets). Returns a summary dict."""
-    config, reason = transport_config(home)
+                  limit=UPLOAD_LIMIT, budget_s=UPLOAD_BUDGET_S, slot_root=None):
+    """Best-effort upload of not-yet-settled learnings. post_fn/now/slot_root are
+    injectable for tests (no sockets, no $HOME mutation). Returns a summary dict.
+
+    `status` separates two skips a single value used to blur: "unconfigured" is
+    the benign default install, "misconfigured" is a transport that WAS claimed
+    and is broken — the caller says so differently, because the second is the
+    one a user must act on."""
+    config, reason = transport_config(slot_root=slot_root)
     if config is None:
-        return {"status": "skipped", "reason": reason,
-                "uploaded": 0, "dead": 0, "pending": None}
+        claimed = reason is not None and not reason.startswith("no transport configured")
+        return {"status": "misconfigured" if claimed else "unconfigured",
+                "reason": reason, "uploaded": 0, "dead": 0, "pending": None}
     token, base = config
 
     records = read_jsonl_records(home / "personal" / "learnings.jsonl")
@@ -461,9 +616,16 @@ def drain_uploads(home, post_fn=http_post, now=time.monotonic,
 
 
 def print_upload_summary(s):
-    if s["status"] == "skipped":
+    if s["status"] == "misconfigured":
+        # Not the benign skip: a transport was claimed and is broken, so the
+        # record will keep not uploading until someone fixes the file named.
+        print(f"  upload -> NOT SENT: {s['reason']}")
+        print("           the record is captured and stays queued; fix the file "
+              "above, then run learn! again")
+        return
+    if s["status"] == "unconfigured":
         print(f"  upload -> skipped ({s['reason']}); "
-              "retries on a later learn! once the hook is installed")
+              "retries on a later learn! once a transport is configured")
         return
     tail = f" (stopped: {s['reason']})" if s["reason"] else ""
     print(f"  upload -> uploaded={s['uploaded']} dead={s['dead']} "
@@ -477,18 +639,44 @@ def _self_test():
     non-zero on any failure."""
     import tempfile
 
-    def make_home(records, with_token=True):
-        home = pathlib.Path(tempfile.mkdtemp(prefix="learn-selftest-"))
+    # One scratch tree for the whole run, removed at the end: every mkdtemp here
+    # used to survive the process, and the gate that calls this ran on every
+    # commit — 10k directories before anyone counted.
+    scratch = pathlib.Path(tempfile.mkdtemp(prefix="learn-selftest-"))
+    made = {"n": 0}
+
+    def scratch_dir(tag):
+        made["n"] += 1
+        d = scratch / f"{tag}-{made['n']}"
+        d.mkdir(parents=True)
+        return d
+
+    # The slot root is passed EXPLICITLY rather than steered through $HOME: a
+    # test that has to mutate the environment to stay off the operator's live
+    # endpoint is patching the caller instead of the seam.
+    empty_root = scratch_dir("empty-root")
+
+    def make_slot(name, token="tok", url="https://example.test/"):
+        """A slot the core accepts — the ADOPTER's side of the contract, planted
+        explicitly. Transport no longer follows from the home a record is
+        written to: the home holds the records, the slot root holds the
+        endpoint, and the tests keep them separate because the code does."""
+        root = scratch_dir(name)
+        slot = root / ".config" / "agent-bios"
+        slot.mkdir(parents=True)
+        (slot / "token").write_text(token + "\n", encoding="utf-8")
+        (slot / "ingest-url").write_text(url + "\n", encoding="utf-8")
+        return root
+
+    live_root = make_slot("live-root")
+
+    def make_home(records):
+        home = scratch_dir("home")
         (home / "personal").mkdir(parents=True)
         with open(home / "personal" / "learnings.jsonl", "w", encoding="utf-8") as f:
             for r in records:
                 f.write(r if isinstance(r, str) else json.dumps(r))
                 f.write("\n")
-        if with_token:
-            (home / "hooks").mkdir(parents=True)
-            (home / "hooks" / "token").write_text("tok", encoding="utf-8")
-            (home / "hooks" / "dashboard-url").write_text(
-                "https://example.test/", encoding="utf-8")
         return home
 
     def rec(n):
@@ -500,19 +688,19 @@ def _self_test():
     checks = []
 
     # 1) no token → skipped, no state file written (watermark unadvanced).
-    h = make_home([rec(1)], with_token=False)
-    s = drain_uploads(h)
-    checks.append(("no-token skip", s["status"] == "skipped"
+    h = make_home([rec(1)])
+    s = drain_uploads(h, slot_root=empty_root)
+    checks.append(("no-token skip", s["status"] == "unconfigured"
                    and not (h / "personal" / STATE_NAME).is_file()))
 
     # 2) all ok → all uploaded, pending 0; re-run uploads nothing new.
     h = make_home([rec(1), rec(2), rec(3)])
-    s = drain_uploads(h, post_fn=lambda *a: 200)
+    s = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: 200)
     calls = {"n": 0}
     def count_post(*a):
         calls["n"] += 1
         return 200
-    s2 = drain_uploads(h, post_fn=count_post)
+    s2 = drain_uploads(h, slot_root=live_root, post_fn=count_post)
     checks.append(("all-ok then idempotent re-run",
                    s["uploaded"] == 3 and s["pending"] == 0
                    and calls["n"] == 0 and s2["uploaded"] == 0))
@@ -520,8 +708,8 @@ def _self_test():
     # 3) transient (500) → nothing settled, drain stops, pending == N; a later
     #    200 run delivers everything (multi-day-outage recovery).
     h = make_home([rec(1), rec(2)])
-    s = drain_uploads(h, post_fn=lambda *a: 500)
-    s2 = drain_uploads(h, post_fn=lambda *a: 200)
+    s = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: 500)
+    s2 = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: 200)
     checks.append(("transient stop then recover",
                    s["uploaded"] == 0 and s["pending"] == 2
                    and s["reason"] == "transient"
@@ -529,24 +717,24 @@ def _self_test():
 
     # 4) permanent (400) → settled as dead, not retried.
     h = make_home([rec(1)])
-    s = drain_uploads(h, post_fn=lambda *a: 400)
+    s = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: 400)
     hits = {"n": 0}
     def once(*a):
         hits["n"] += 1
         return 400
-    s2 = drain_uploads(h, post_fn=once)
+    s2 = drain_uploads(h, slot_root=live_root, post_fn=once)
     checks.append(("permanent drop, not retried",
                    s["dead"] == 1 and s["pending"] == 0 and hits["n"] == 0))
 
     # 5) network error (None) is transient.
     h = make_home([rec(1)])
-    s = drain_uploads(h, post_fn=lambda *a: None)
+    s = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: None)
     checks.append(("network error is transient",
                    s["uploaded"] == 0 and s["pending"] == 1))
 
     # 6) poison line skipped, valid records still delivered.
     h = make_home(["{ not json", rec(1), ""])
-    s = drain_uploads(h, post_fn=lambda *a: 200)
+    s = drain_uploads(h, slot_root=live_root, post_fn=lambda *a: 200)
     checks.append(("poison line skipped", s["uploaded"] == 1 and s["pending"] == 0))
 
     # 7) wall-clock budget stops the drain (fake clock jumps past the deadline).
@@ -555,8 +743,31 @@ def _self_test():
         clock["t"] += 10.0
         return clock["t"]
     h = make_home([rec(1), rec(2)])
-    s = drain_uploads(h, post_fn=lambda *a: 200, now=fake_now, budget_s=5.0)
-    checks.append(("budget stop", s["reason"] == "budget"))
+    budget_sent = {"n": 0}
+    def budget_post(*a):
+        budget_sent["n"] += 1
+        return 200
+    s = drain_uploads(h, slot_root=live_root, post_fn=budget_post, now=fake_now, budget_s=5.0)
+    # ZERO sends, not just the reason: the deadline is checked BEFORE a send,
+    # and a reordering that posts first still reports reason "budget".
+    checks.append(("budget stop", s["reason"] == "budget" and budget_sent["n"] == 0))
+
+    # 7b) the BOUNDARY, not just the far side: a clock still inside the budget
+    #     must send. A deadline test widened to "will probably overrun" passes
+    #     the check above while suppressing a send that was still allowed.
+    inside = {"t": 0.0}
+    def near_now():
+        inside["t"] += 0.1          # 0.1, 0.2, ... — never reaches a 5.0s budget
+        return inside["t"]
+    h = make_home([rec(1)])
+    sent_inside = {"n": 0}
+    def inside_post(*a):
+        sent_inside["n"] += 1
+        return 200
+    s = drain_uploads(h, slot_root=live_root, post_fn=inside_post,
+                      now=near_now, budget_s=5.0)
+    checks.append(("a send still inside the budget is not suppressed",
+                   sent_inside["n"] == 1 and s["uploaded"] == 1))
 
     # 8) capture-time secret redaction is wired into build_record, so secrets in
     #    free text never reach the durable log / upload / curator export.
@@ -598,6 +809,326 @@ def _self_test():
                    import_line_index(f"# e\n```\n{CLAUDE_CENTRAL_IMPORT}\n```\n",
                                      CLAUDE_CENTRAL_IMPORT) is None))
 
+    # 11) transport resolution: the slot is the whole contract, and the
+    #     instrument is held to the exact planted values — a bare non-None
+    #     result would pass on a value nobody planted.
+    own_root = scratch_dir("own-root")
+    slot = own_root / ".config" / "agent-bios"
+    slot.mkdir(parents=True)
+    (slot / "token").write_text("own-tok\n", encoding="utf-8")
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=own_root)
+    checks.append(("the slot resolves to exactly what was planted",
+                   cfg == ("own-tok", "https://own.test") and why is None))
+
+    # 12) a claimed slot missing a half fails loud — BOTH directions, since
+    #     either half alone claims the slot.
+    (slot / "ingest-url").unlink()
+    cfg, why = transport_config(slot_root=own_root)
+    checks.append(("claimed slot never falls back (url missing)",
+                   cfg is None and "missing ingest-url" in (why or "")))
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+    (slot / "token").unlink()
+    cfg, why = transport_config(slot_root=own_root)
+    checks.append(("claimed slot never falls back (token missing)",
+                   cfg is None and "missing token" in (why or "")))
+    (slot / "token").write_text("own-tok\n", encoding="utf-8")
+
+    # 12c) an unreadable slot is loud, never a silent legacy fallback — and the
+    #      EACCES is planted one level ABOVE the slot, which is where a path
+    #      predicate answers "absent" instead of "cannot look". Skipped for
+    #      uid 0, which ignores the permission bits and would make this control
+    #      quietly test nothing (or fail for the wrong reason).
+    if os.geteuid() != 0:
+        os.chmod(own_root / ".config", 0o600)
+        try:
+            cfg, why = transport_config(slot_root=own_root)
+        finally:
+            os.chmod(own_root / ".config", 0o700)
+        checks.append(("unreadable slot is loud (EACCES above it)",
+                       cfg is None and "cannot be read" in (why or "")))
+
+    # 12c-2) the two remaining shapes of "something is there and we cannot read
+    #        it", both found by measuring which statements the self-test never
+    #        executed rather than by imagining them. This seam has leaked six
+    #        times on exactly this question, and these branches existed for it
+    #        while nothing exercised them.
+    notdir_root = scratch_dir("notdir-root")
+    (notdir_root / ".config").mkdir(parents=True)
+    (notdir_root / ".config" / "agent-bios").write_text("not a directory\n",
+                                                        encoding="utf-8")
+    cfg, why = transport_config(slot_root=notdir_root)
+    checks.append(("a file where the slot directory belongs is loud",
+                   cfg is None and "is not a directory" in (why or "")))
+
+    if os.geteuid() != 0:
+        # Readable but not searchable (r without x): the listing succeeds and
+        # naming the entries works, while lstat on them raises EACCES. A slot
+        # that answers "cannot look" per FILE rather than per directory.
+        nox_root = scratch_dir("nox-root")
+        nox_slot = nox_root / ".config" / "agent-bios"
+        nox_slot.mkdir(parents=True)
+        (nox_slot / "token").write_text("t\n", encoding="utf-8")
+        (nox_slot / "ingest-url").write_text("https://x.test/\n", encoding="utf-8")
+        os.chmod(nox_slot, 0o400)
+        try:
+            cfg, why = transport_config(slot_root=nox_root)
+        finally:
+            os.chmod(nox_slot, 0o700)
+        checks.append(("a slot whose entries cannot be stat'ed is loud, not absent",
+                       cfg is None and "not a readable file" in (why or "")))
+
+    # 13) an empty slot value is its own loud failure, not a skip or fallback —
+    #     each half through its own door (a shared door would let one branch's
+    #     rejection vanish while the other keeps the check green).
+    (slot / "ingest-url").write_text("\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=own_root)
+    checks.append(("empty slot url is loud",
+                   cfg is None and "transport slot ingest-url is empty" in (why or "")))
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+    (slot / "token").write_text("\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=own_root)
+    checks.append(("empty slot token is loud",
+                   cfg is None and "transport slot token is empty" in (why or "")))
+    (slot / "token").write_text("own-tok\n", encoding="utf-8")
+
+    # 13b) a base urllib cannot turn into a request is rejected where the value
+    #      is PRODUCED, naming the file — reaching http_post with it raised out
+    #      of the drain and killed learn! after the local writes.
+    # The host-less case is spelled in two pieces so this fixture is not itself
+    # a hardcoded URL in a shipped file (gates/check-endpoints.py urls leg).
+    for bad, needle in (("dashboard.example.com", "no http(s) scheme"),
+                        ("https:" "//", "no host"),
+                        ("ftp://x.example", "no http(s) scheme"),
+                        # The path is appended by concatenation, so these two
+                        # produce a selector the contract never names.
+                        ("https://own.test/?tenant=1", "query or fragment"),
+                        ("https://own.test/#x", "query or fragment"),
+                        # The EMPTY delimiters, which urlsplit reports as ""
+                        # and a truthiness test therefore accepted.
+                        ("https://own.test/?", "query or fragment"),
+                        ("https://own.test/#", "query or fragment"),
+                        # A value urlsplit itself refuses. The reason must come
+                        # back as a reason, not as a raise out of the drain.
+                        ("http:" "//[::1", "unparseable")):
+        (slot / "ingest-url").write_text(bad + "\n", encoding="utf-8")
+        cfg, why = transport_config(slot_root=own_root)
+        checks.append((f"unusable slot url is loud ({bad!r})",
+                       cfg is None and needle in (why or "")))
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+
+    # 13c) and a misconfigured transport is reported through its OWN channel:
+    #      the benign "nothing configured" default and a broken claimed slot
+    #      are the two cases a single "skipped" status used to blur.
+    (slot / "ingest-url").write_text("not-a-url\n", encoding="utf-8")
+    h = make_home([rec(1)])
+    s = drain_uploads(h, slot_root=own_root, post_fn=lambda *a: 200)
+    checks.append(("broken slot reports misconfigured, not skipped",
+                   s["status"] == "misconfigured" and s["uploaded"] == 0))
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+
+    # 12d) a slot entry that EXISTS but is not a readable file is claimed and
+    #      loud, never a silent legacy fallback: a dangling symlink and a
+    #      directory both answer False to is_file(), exactly as an absent path
+    #      does, and that is the third shape this seam has leaked through.
+    shape_root = scratch_dir("shape-root")
+    shape_slot = shape_root / ".config" / "agent-bios"
+    shape_slot.mkdir(parents=True)
+    (shape_slot / "token").symlink_to(shape_root / "nothing-here")
+    (shape_slot / "ingest-url").symlink_to(shape_root / "nothing-here-either")
+    cfg, why = transport_config(slot_root=shape_root)
+    checks.append(("dangling slot symlinks are loud, not a silent fallback",
+                   cfg is None and "not a readable file" in (why or "")))
+    (shape_slot / "token").unlink()
+    (shape_slot / "token").mkdir()
+    cfg, why = transport_config(slot_root=shape_root)
+    checks.append(("a directory where a slot file belongs is loud",
+                   cfg is None and "not a readable file" in (why or "")))
+
+    # 12d-2) the reason names the FILE that is unreadable, and a non-UTF-8 slot
+    #        file is a misconfiguration rather than a crash — the whole point of
+    #        catching ValueError beside OSError on every config read.
+    utf_root = scratch_dir("utf-root")
+    utf_slot = utf_root / ".config" / "agent-bios"
+    utf_slot.mkdir(parents=True)
+    (utf_slot / "token").write_bytes(b"\xff\xfe not utf-8")
+    (utf_slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+
+    def resolved(root):
+        """A RAISE is the failure this pair exists to catch, so it becomes a
+        reason string rather than killing the self-test alongside its subject."""
+        try:
+            return transport_config(slot_root=root)
+        except Exception as e:                       # noqa: BLE001
+            return None, f"RAISED {type(e).__name__}: {e}"
+
+    cfg, why = resolved(utf_root)
+    checks.append(("a non-UTF-8 slot file is loud and names itself",
+                   cfg is None and str(utf_slot / "token") in (why or "")))
+
+    # 12e-2) a token urllib cannot put in a header is refused at the source; a
+    #        config-caused send failure must stay TRANSIENT so the records
+    #        survive the fix, while a record-caused one settles.
+    (utf_slot / "token").write_text("tok en\twith control\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=utf_root)
+    checks.append(("an unusable token is refused at the source",
+                   cfg is None and "header value" in (why or "")))
+    checks.append(("a config-caused send failure stays transient (records survive)",
+                   classify_status(http_post("https:" "//" + "a" * 64 + ".test", "t",
+                                             rec(1), timeout=0.2)) == "transient"))
+    checks.append(("and a host urllib cannot encode is refused at the source",
+                   invalid_base("https:" "//" + "a" * 64 + ".test") is not None))
+
+    # 12f) the hostname requirement, on a base that HAS a netloc: reverting to a
+    #      netloc test passes every other fixture, since the host-less one is a
+    #      bare scheme with an empty netloc.
+    # Spelled in pieces so this fixture is not itself a hardcoded URL in a
+    # shipped file (the urls leg), while still being a netloc with no host.
+    checks.append(("a netloc without a host is refused",
+                   invalid_base("https:" "//" ":443") is not None))
+
+    # 12e) a base whose port urllib rejects is refused where the value is
+    #      produced; if one reaches http_post anyway it settles rather than
+    #      wedging, because InvalidURL inherits the network exception too.
+    checks.append(("an unusable port is refused at the source",
+                   invalid_base("http://host.test:abc") is not None))
+    checks.append(("and an unparseable base stays transient at send (config, "
+                   "not a dead record)",
+                   classify_status(http_post("http://host.test:abc", "t",
+                                             rec(1), timeout=0.2)) == "transient"))
+
+    # 13d) a record or token that can never be SENT settles like a 400 instead
+    #      of stopping the drain: classed transient, one poison record wedged
+    #      every later upload behind it and reported the wedge as an outage.
+    poison = json.loads('{"learning_id": "0f8c1c2a-4d1e-4abc-9def-000000000099",'
+                        ' "schema_version": 1, "domain": "core",'
+                        ' "created": "2026-08-20T00:00:00Z",'
+                        ' "supporting_sessions": ["claude:abcd1234"],'
+                        ' "lesson": "\\ud800"}')
+    checks.append(("unsendable record settles permanent, never transient",
+                   classify_status(http_post("https://x.test", "tok", poison,
+                                             timeout=0.2)) == "permanent"))
+    h = make_home([poison, rec(1)])
+    # By VALUE, not identity: the drain re-parses each record out of the JSONL,
+    # so `is` compares against an object the drain never sees.
+    s = drain_uploads(h, slot_root=own_root,
+                      post_fn=lambda base, tok, r: (http_post(base, tok, r, 0.2)
+                                                    if r.get("lesson") != "x" * 12
+                                                    else 200))
+    checks.append(("a poison record does not wedge the queue behind it",
+                   s["dead"] == 1 and s["uploaded"] == 1 and s["pending"] == 0))
+
+    # 13d-2) the classifier is checked EXHAUSTIVELY, not on sampled statuses.
+    #        A sampled matrix tests the codes someone thought of: 202 was in no
+    #        sample and no static literal, so a carve-out excluding it from 2xx
+    #        would have made every accepted-but-async delivery retry forever
+    #        while every test stayed green. The rule is derived from the same
+    #        constants the contract publishes, so this compares behaviour with
+    #        declaration rather than with a second copy of itself.
+    wrong = []
+    for status in range(100, 600):
+        want = ("ok" if 200 <= status < 300
+                else "permanent" if status in PERMANENT_STATUSES
+                else "transient")
+        if classify_status(status) != want:
+            wrong.append((status, classify_status(status), want))
+    checks.append((f"classify_status agrees with the declared sets on every "
+                   f"status 100-599 (first divergences: {wrong[:3]})", not wrong))
+    # and the two values that are not statuses at all keep their own answers
+    checks.append(("a network error is transient and UNSENDABLE is permanent",
+                   classify_status(None) == "transient"
+                   and classify_status(UNSENDABLE) == "permanent"))
+
+    # 13e) presence is asked of the FILESYSTEM, not of a listing's names: on a
+    #      case-insensitive filesystem a slot holding TOKEN/INGEST-URL is the
+    #      same slot, and a name-set test silently reported it unconfigured.
+    ci_root = scratch_dir("ci-root")
+    ci_slot = ci_root / ".config" / "agent-bios"
+    ci_slot.mkdir(parents=True)
+    (ci_slot / "TOKEN").write_text("ci-tok\n", encoding="utf-8")
+    (ci_slot / "INGEST-URL").write_text("https://ci.test/\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=ci_root)
+    if (ci_slot / "token").is_file():          # only meaningful where the FS folds case
+        checks.append(("case-folded slot is still claimed",
+                       cfg == ("ci-tok", "https://ci.test") and why is None))
+    else:
+        checks.append(("case-folded slot check skipped (case-sensitive filesystem)",
+                       cfg is None or cfg[1] != "https://ci.test"))
+
+    # 13f) the promise is that a broken slot names THE FILE, and that the two
+    #      skips read differently to a user — the message is the whole product of
+    #      a loud failure, so it is asserted rather than assumed.
+    import io, contextlib
+    def summary_text(s):
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            print_upload_summary(s)
+        return buf.getvalue()
+
+    (slot / "ingest-url").write_text("not-a-url\n", encoding="utf-8")
+    cfg, why = transport_config(slot_root=own_root)
+    broken = summary_text({"status": "misconfigured", "reason": why,
+                           "uploaded": 0, "dead": 0, "pending": None})
+    benign = summary_text({"status": "unconfigured", "reason": "no transport configured",
+                           "uploaded": 0, "dead": 0, "pending": None})
+    checks.append(("a broken slot's reason names the file",
+                   str(slot / "ingest-url") in (why or "")))
+    checks.append(("the two skips read differently to a user",
+                   "NOT SENT" in broken and "NOT SENT" not in benign
+                   and broken != benign))
+    (slot / "ingest-url").write_text("https://own.test/\n", encoding="utf-8")
+
+    # 14) no slot → the skip reason names the slot it looked for, and names it
+    #     as an absolute path: under a redirected HOME a tilde would be a lie
+    #     about where the adopter must write.
+    cfg, why = transport_config(slot_root=empty_root)
+    checks.append(("default resolves no transport",
+                   cfg is None and "no transport configured" in (why or "")
+                   and str(empty_root / ".config" / "agent-bios") in (why or "")))
+
+    # 15) the drain posts to the slot's base — the resolved value reaches the
+    #     wire, rather than merely being returned by the resolver.
+    h = make_home([rec(1)])
+    seen = []
+    def spy(base, token, record):
+        seen.append((base, token))
+        return 200
+    s = drain_uploads(h, slot_root=own_root, post_fn=spy)
+    checks.append(("drain posts to the slot base",
+                   s["uploaded"] == 1 and seen == [("https://own.test", "own-tok")]))
+
+    # 16) the organization provider is gone from the core, measured through the
+    #     DRAIN rather than the resolver: a home carrying the old dashboard hook
+    #     files, with no slot, must degrade to unconfigured and send nothing. A
+    #     re-added fallback would resolve that home and upload — which is the
+    #     failure this asserts against, and why the check is made where a send
+    #     could actually happen.
+    orphan = make_home([rec(1)])
+    (orphan / "hooks").mkdir(parents=True)
+    (orphan / "hooks" / "token").write_text("tok", encoding="utf-8")
+    (orphan / "hooks" / "dashboard-url").write_text("https://example.test/",
+                                                    encoding="utf-8")
+    sent = {"n": 0}
+    def orphan_post(*a):
+        sent["n"] += 1
+        return 200
+    s = drain_uploads(orphan, slot_root=empty_root, post_fn=orphan_post)
+    checks.append(("a host-home hook dir is not a transport",
+                   s["status"] == "unconfigured" and sent["n"] == 0))
+
+    # 17) the POST limit is a hard cap, measured: limit=1 over two records sends
+    #     exactly one and stops with reason "limit" — an off-by-one flip in the
+    #     comparison sends a 26th POST that no anchor can see.
+    h = make_home([rec(1), rec(2)])
+    capped = {"n": 0}
+    def cap(*a):
+        capped["n"] += 1
+        return 200
+    s = drain_uploads(h, slot_root=live_root, post_fn=cap, limit=1)
+    checks.append(("post limit is a hard cap",
+                   capped["n"] == 1 and s["uploaded"] == 1 and s["reason"] == "limit"))
+
+    shutil.rmtree(scratch, ignore_errors=True)
     failed = [name for name, ok in checks if not ok]
     if failed:
         for name in failed: