@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_descriptor.py

@@ -1,14 +1,18 @@
 """How a service is found (fabric-service/0.1): its descriptor, peers and app descriptors (DEC-0061, DEC-0069),
 build identity and the well-known document, the loopback HTTP server. Part of the service kit (FAA-65, layer L3)."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import hashlib
 import http.server
+import ipaddress
 import json
 import os
 import re
+import socket
 import socketserver
 import subprocess
+import threading
 import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -29,6 +33,7 @@ from fabric_base import (
     expand,
     now_iso,
 )
+import fabric_peer_owner  # noqa: E402 - L0: who listens on a port (DEC-0154 HA-2, FAA-225)
 from fabric_paths import (
     atomic_write,
     ensure_private_dir,
@@ -85,19 +90,101 @@ _NOT_LAUNCHD = ("systemd", "task-scheduler", "node", "person")
 _AUTH_HEADER = re.compile(r"[A-Za-z][A-Za-z0-9-]{0,63}")
 
 
+#: How a loopback server treats the OS account of the process that connected (DEC-0154 HA-2's server side, HA-3;
+#: FAA-227): `refuse` (the default) closes a connection whose peer is another OS account's before reading a byte of
+#: it and serves the rest, labelled; `strict` also refuses a peer whose owner cannot be told and a system account
+#: other than root (uid 0, which can read every account's files and installs a LaunchDaemon); `off` reads no table.
+PEER_CHECKS = ("refuse", "strict", "off")
+
+
+def connection_refusal(owner: Any, mode: str = "refuse") -> Optional[str]:
+    """Why a server refuses the peer `owner` (a fabric_peer_owner.Owner) under `mode`, or None to serve it. The reason
+    is the owner's kind, or for `unknown` its reason; it names no address and nothing the peer sent."""
+    if mode not in PEER_CHECKS:
+        raise ValueError("peer_check must be one of %s" % ", ".join(PEER_CHECKS))
+    if mode == "off" or owner is None:
+        return None
+    kind = getattr(owner, "kind", fabric_peer_owner.UNKNOWN)
+    if kind == fabric_peer_owner.ANOTHER_ACCOUNT:
+        return kind
+    if mode == "strict" and kind != fabric_peer_owner.THIS_ACCOUNT:
+        if kind == fabric_peer_owner.SYSTEM and getattr(owner, "uid", None) == 0:
+            return None
+        return getattr(owner, "reason", None) or kind
+    return None
+
+
+def is_loopback_peer(client_address: Any) -> bool:
+    """Whether an accepted connection's peer address is a loopback one (127.0.0.0/8, ::1, or either IPv4-mapped): the
+    only peers whose owner can be another account of this computer (DEC-0154 HA-2). An address that cannot be read
+    counts as loopback, so its owner is still read from the table."""
+    try:
+        return ipaddress.ip_address(fabric_peer_owner.norm_host(str(client_address[0]))).is_loopback
+    except Exception:
+        return True
+
+
 class LoopbackHTTPServer(http.server.ThreadingHTTPServer):
     """ThreadingHTTPServer for a loopback service: threads are daemons, and the bind asks
     no resolver. HTTPServer.server_bind() calls socket.getfqdn() between bind() and listen();
     on a Mac with a slow resolver the port then stays bound but silent, so a host sees
-    neither an answer nor a refusal."""
+    neither an answer nor a refusal.
+
+    Each accepted connection's peer is told from the computer's socket table (`fabric_peer_owner.peer`) in the
+    connection's own thread, before the handler reads a byte (DEC-0154 HA-2's server side, FAA-227). `peer_check`
+    (`PEER_CHECKS`) decides which owners are closed unread; a served handler finds its peer's owner with
+    `self.server.peer_owner()`. A refusal writes one line to stderr with the owner's kind, uid and pid and nothing the
+    peer sent (`peer_refused`), and counts in `peer_refusals`. The check applies to loopback peers only: a peer at
+    another address (a service bound to 0.0.0.0) is no local account, so its table is not read and it is served under
+    `refuse` and `strict` alike, with `peer_owner()` None."""
 
     daemon_threads = True
+    peer_check = "refuse"
+    #: The reader of an accepted socket's peer; a test replaces it.
+    peer_reader = staticmethod(lambda sock: fabric_peer_owner.peer(sock))
+
+    def __init__(self, server_address: Any, handler: Any, bind_and_activate: bool = True, *,
+                 peer_check: Optional[str] = None) -> None:
+        mode = self.peer_check if peer_check is None else peer_check
+        connection_refusal(None, mode)  # refuses an unknown mode before the port is bound
+        self.peer_check = mode
+        self.peer_refusals = 0
+        self._peer = threading.local()
+        super().__init__(server_address, handler, bind_and_activate)
 
     def server_bind(self) -> None:
         socketserver.TCPServer.server_bind(self)
         host, port = self.server_address[:2]
         self.server_name, self.server_port = host, port
 
+    def peer_owner(self) -> Any:
+        """The owner of the peer this thread's handler serves (None under `peer_check="off"`)."""
+        return getattr(self._peer, "owner", None)
+
+    def finish_request(self, request: Any, client_address: Any) -> None:
+        owner = None
+        if self.peer_check != "off" and is_loopback_peer(client_address):
+            try:
+                owner = self.peer_reader(request)
+            except Exception as exc:  # a reader that fails is an owner nobody can tell, never a crash of the server
+                owner = fabric_peer_owner.Owner(fabric_peer_owner.UNKNOWN, None, None, "none",
+                                                "reader: %s" % type(exc).__name__)
+        reason = connection_refusal(owner, self.peer_check)
+        if reason is not None:
+            self.peer_refusals += 1
+            self.peer_refused(owner, reason)
+            return  # process_request_thread closes the socket unread (shutdown_request)
+        self._peer.owner = owner
+        try:
+            super().finish_request(request, client_address)
+        finally:
+            self._peer.owner = None
+
+    def peer_refused(self, owner: Any, reason: str) -> None:
+        """One line on stderr per refused connection; override to log it elsewhere. Never the peer's bytes."""
+        _sys.stderr.write("fabric: refused a loopback peer (%s, uid %s, pid %s) before reading it (DEC-0154)\n"
+                          % (reason, getattr(owner, "uid", None), getattr(owner, "pid", None)))
+
 
 def descriptor_path(service_id: str, instance: str = "default", directory: Optional[Path] = None) -> Path:
     return (directory or services_dir()) / ("%s.%s.json" % (service_id, instance))
@@ -477,8 +564,35 @@ def source_refusal(descriptor: Dict[str, Any], directory: Optional[Path] = None)
     return "Descriptor %s %s. %s" % (me, NO_SOURCE_REPOSITORY, PASS_SOURCE)
 
 
-def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2) -> Path:
-    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim).
+def port_owner(port: int) -> Optional[Tuple[str, Optional[int]]]:
+    """Who listens on 127.0.0.1:<port> now, as (kind, uid) from the kit's fabric_peer_owner, or None when a plain bind
+    of that address succeeds (nothing holds it, and the socket table is not read). FAA-225, DEC-0154 HA-2."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        try:
+            probe.bind(("127.0.0.1", port))
+            return None
+        except OSError:
+            pass
+    owner = fabric_peer_owner.listener(port)
+    return owner.kind, owner.uid
+
+
+def port_listener_refusal(port: int, reader: Optional[Any] = None) -> Optional[str]:
+    """Why an install may not take ``port``: another OS account listens on it (FAA-225). This account, the system
+    (launchd holds a socket-activated job's socket), nobody and an unreadable table pass: the refusal is for a port
+    that is surely another account's. The recorded port per account and its claim file wait on contract DEC-0160."""
+    found = (reader or port_owner)(port)
+    if not found or found[0] != fabric_peer_owner.ANOTHER_ACCOUNT:
+        return None
+    uid = " (uid %d)" % found[1] if isinstance(found[1], int) else ""
+    return ("Port %d is listened on by another OS account%s: choose a port no other account holds (DEC-0154, "
+            "FAA-225)." % (port, uid))
+
+
+def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2,
+                     port_owner: Optional[Any] = None) -> Path:
+    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim), and a port another
+    OS account listens on (FAA-225; ``port_owner(port) -> (kind, uid) | None`` reads it, the kit's own by default).
 
     FAA-198: a new descriptor names its ``source.repository``; rewriting one already installed without it only
     warns (``NoSourceRepositoryWarning``), so an installed agent's update keeps working."""
@@ -505,6 +619,9 @@ def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = Non
             continue
         if other_port == port:
             raise ServiceError("Port %d is already claimed by %s (%s)." % (port, key, path))
+    held = port_listener_refusal(port, port_owner) if port is not None else None
+    if held:
+        raise ServiceError(held)
     ensure_private_dir(root)
     target = descriptor_path(descriptor["id"], descriptor["instance"], root)
     atomic_write(target, (json.dumps(descriptor, indent=2, ensure_ascii=False) + "\n").encode(), 0o600)

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_holds.py

@@ -0,0 +1,316 @@
+"""Work a service holds by its own limits, said to its caller and its operator (FAA-298). Part of the service kit
+(layer L3, after fabric_interop).
+
+A service that holds work by a limit of its own (a daily quota, a per-caller share, a concurrency cap, a money cap)
+says so three ways:
+
+- to the caller, on the job: `waiting_message(reason, since, until, message)` is the job's `statusMessage`. The pinned
+  `interop-job` schema is closed (`additionalProperties: false`), so `waiting {reason, since, until, message}` cannot
+  be a field of the job; it rides the contract's pause grammar (DEC-0087) as its text:
+  `quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`. A caller that reads only the pause
+  grammar waits (and until `until`, when given); `read_waiting(answer)` gives the four parts back. `JobStore.pause`
+  takes the same statusMessage through `hold_job`.
+- to the operator, once per hold: `HoldBook.hold` opens a hold per (reason, caller), or joins the open one, and returns
+  the push only when it opens: one `notify` event naming the caller, the work, the reason and when the hold frees by
+  itself, with the question whether to raise the limit. Further jobs held by the same limit for the same caller join
+  the hold silently; a hold is closed by `release`, by its `until` passing, or by a lift that covers it.
+- the answer, as a scoped lift: `HoldBook.lift` records the operator's words (a DEC-0121 decision, action
+  `limit.lift`) with its scope (the reason, optionally one caller and one job) and its size (a number of jobs, an
+  amount of money, or a raised limit for a time window such as 100 a day for today). `admit` spends a jobs or money
+  lift; `limit` gives the limit in force. A lift falls back by itself when its window ends or its amount is spent.
+
+`HoldBook` keeps one JSON file (0600, written atomically); a ThreadingHTTPServer's handlers share it under the store
+lock. It holds caller names, work labels, reasons and the operator's words, never a credential: `hold` refuses a text
+the contract's detector reads as one.
+"""
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from fabric_base import ServiceError, now_iso, store_lock  # noqa: E402
+from fabric_paths import atomic_write  # noqa: E402
+from fabric_actions import decision_shape  # noqa: E402
+from fabric_interop_rules import pause_message, read_job_pause, utc_time, QUOTA_EXHAUSTED  # noqa: E402
+import fabric_secrets  # noqa: E402
+
+#: The limits a hold names: a daily quota, a per-caller share, a concurrency cap, a money cap.
+HOLD_REASONS = ("daily-quota", "caller-share", "concurrency", "money")
+#: How the push names each reason to a person.
+REASON_WORDS = {"daily-quota": "the daily quota", "caller-share": "its per-caller share",
+                "concurrency": "the concurrency cap", "money": "the money cap"}
+#: The push's kind: a decision for the operator (level notice, notify true; events-and-notifications.md).
+HOLD_EVENT_KIND = "limit.held"
+#: The record of a lift applied (level info, no notify).
+LIFT_EVENT_KIND = "limit.lifted"
+#: The decision action a lift carries (DEC-0121 AP-2 shape).
+LIFT_ACTION = "limit.lift"
+_MAX_STATUS_MESSAGE = 500
+_WAITING = re.compile(r"^waiting (daily-quota|caller-share|concurrency|money) since ([0-9][0-9TZ:.-]*?)(?:: ([\s\S]+))?\Z")
+_SIZES = ("jobs", "usd", "limit")
+
+
+def _instant(value: Any, name: str) -> str:
+    if utc_time(value) is None:
+        raise ServiceError("%s is a UTC instant (Z, at most 3 fraction digits)." % name)
+    return value
+
+
+def waiting_message(reason: str, since: str, until: Optional[str] = None, message: Optional[str] = None) -> str:
+    """A held job's statusMessage: the pause grammar, its text `waiting <reason> since <since>[: <message>]`. The
+    message is shortened, never refused, to fit the contract's 500 characters; a reason or an instant outside the
+    grammar raises ServiceError."""
+    if reason not in HOLD_REASONS:
+        raise ServiceError("A hold's reason is one of %s." % ", ".join(HOLD_REASONS))
+    _instant(since, "since")
+    if until is not None:
+        _instant(until, "until")
+    text = "waiting %s since %s" % (reason, since)
+    head = len(QUOTA_EXHAUSTED) + (0 if until is None else len(" until ") + len(until)) + len(": ")
+    if message is not None:
+        message = " ".join(str(message).split())
+        room = _MAX_STATUS_MESSAGE - head - len(text) - len(": ")
+        if message and room > 0:
+            text += ": " + (message if len(message) <= room else message[:room - 3].rstrip() + "...")
+    return pause_message(until, text)
+
+
+def read_waiting(answer: Any) -> Optional[Dict[str, Any]]:
+    """`{reason, since, until?, message?}` of a fabric.job.get answer whose job a limit holds (`waiting_message`), else
+    None: a plain pause, a queue position or a finished job is not a hold."""
+    pause = read_job_pause(answer)
+    if not pause.get("paused"):
+        return None
+    status = answer["job"]["statusMessage"]
+    rest = status[len(QUOTA_EXHAUSTED):]
+    if "resetsAt" in pause:
+        rest = rest[len(" until ") + len(pause["resetsAt"]):]
+    if not rest.startswith(": "):
+        return None
+    match = _WAITING.match(rest[2:])
+    if not match or utc_time(match.group(2)) is None:
+        return None
+    waiting: Dict[str, Any] = {"reason": match.group(1), "since": match.group(2)}
+    if "resetsAt" in pause:
+        waiting["until"] = pause["resetsAt"]
+    if match.group(3) is not None:
+        waiting["message"] = match.group(3)
+    return waiting
+
+
+def hold_job(jobs: Any, job_id: str, reason: str, since: str, until: Optional[str] = None,
+             message: Optional[str] = None) -> Dict[str, Any]:
+    """Put one job of a fabric_interop JobStore on hold: working, its statusMessage `waiting_message(...)`, its
+    pollIntervalMs reaching `until` (JobStore.pause). Returns the job."""
+    text = waiting_message(reason, since, until, message)[len(QUOTA_EXHAUSTED):]
+    if until is not None:
+        text = text[len(" until ") + len(until):]
+    return jobs.pause(job_id, resets_at=until, text=text[2:])
+
+
+def hold_sentence(caller: str, work: str, reason: str, until: Optional[str]) -> str:
+    """The push's one sentence: who, what, why, when it frees by itself, and the question."""
+    frees = ("it frees by itself at %s" % until) if until is not None else (
+        "it frees by itself when a running job ends" if reason in ("concurrency", "caller-share")
+        else "it does not free by itself")
+    return "%s for %s is held by %s; %s. Raise the limit for it?" % (work, caller, REASON_WORDS[reason], frees)
+
+
+def _text(value: Any, name: str, high: int = 200) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > high:
+        raise ServiceError("%s is a text of 1 to %d characters." % (name, high))
+    if fabric_secrets.secret_value(value):
+        raise ServiceError("%s looks like a credential; a hold names callers and work, never a secret." % name)
+    return " ".join(value.split())
+
+
+class HoldBook:
+    """The holds a service's limits put on work and the operator's lifts, in one file (FAA-298).
+
+    `events`, when given, is the service's event log (an object with `append(kind, level, text, subject=..., **extra)`,
+    such as fabric_events.JsonlEventLog): the push and the lift record are written there. Without it they are returned
+    for the service to write."""
+
+    def __init__(self, path: Path, events: Any = None, clock: Callable[[], str] = now_iso):
+        self.path = Path(path)
+        self.events = events
+        self.clock = clock
+        self._lock = store_lock(self.path)
+
+    # --- the file -------------------------------------------------------------------------
+    def _load(self) -> Dict[str, Any]:
+        if not self.path.exists():
+            return {"holds": [], "lifts": []}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except ValueError:
+            raise ServiceError("The hold book %s is not JSON; it is kept as it is." % self.path.name) from None
+        if not isinstance(data, dict) or not isinstance(data.get("holds"), list) or not isinstance(data.get("lifts"), list):
+            raise ServiceError("The hold book %s is not {holds, lifts}; it is kept as it is." % self.path.name)
+        return data
+
+    def _save(self, data: Dict[str, Any]) -> None:
+        atomic_write(self.path, (json.dumps(data, ensure_ascii=False, indent=1) + "\n").encode(), 0o600)
+
+    def _now(self, now: Optional[str]) -> str:
+        return _instant(now if now is not None else self.clock(), "now")
+
+    def _emit(self, kind: str, level: str, text: str, subject: Dict[str, str], notify: bool) -> Dict[str, Any]:
+        if self.events is not None:
+            return self.events.append(kind, level, text, subject=subject, notify=notify)
+        out: Dict[str, Any] = {"kind": kind, "level": level, "text": text, "subject": subject}
+        if notify:
+            out["notify"] = True
+        return out
+
+    @staticmethod
+    def _expire(data: Dict[str, Any], at: int) -> None:
+        for hold in data["holds"]:
+            if hold.get("closed") is None and hold.get("until") is not None and utc_time(hold["until"]) <= at:
+                hold["closed"], hold["closedAt"] = "expired", hold["until"]
+
+    @staticmethod
+    def _live(lift: Dict[str, Any], at: int) -> bool:
+        if lift.get("from") is not None and utc_time(lift["from"]) > at:
+            return False
+        if lift.get("until") is not None and utc_time(lift["until"]) <= at:
+            return False
+        return lift.get("left", 1) > 0
+
+    # --- holds ----------------------------------------------------------------------------
+    def hold(self, *, caller: str, work: str, reason: str, until: Optional[str] = None, message: Optional[str] = None,
+             job_id: Optional[str] = None, now: Optional[str] = None) -> Dict[str, Any]:
+        """Hold `work` for `caller` by `reason`. Returns {hold, statusMessage, push}: `push` is the notify event when this
+        call opened the hold, None when the work joined an open one (one push per hold)."""
+        caller, work = _text(caller, "caller"), _text(work, "work")
+        if reason not in HOLD_REASONS:
+            raise ServiceError("A hold's reason is one of %s." % ", ".join(HOLD_REASONS))
+        at = self._now(now)
+        if until is not None and utc_time(_instant(until, "until")) <= utc_time(at):
+            raise ServiceError("until %s has passed: the limit no longer holds the work." % until)
+        with self._lock:
+            data = self._load()
+            self._expire(data, utc_time(at))
+            hold = next((h for h in data["holds"] if h.get("closed") is None and h["reason"] == reason
+                         and h["caller"] == caller), None)
+            opened = hold is None
+            if opened:
+                hold = {"id": uuid.uuid4().hex, "reason": reason, "caller": caller, "work": work, "since": at,
+                        "until": until, "jobs": [], "closed": None}
+                data["holds"].append(hold)
+            if job_id is not None and job_id not in hold["jobs"]:
+                hold["jobs"].append(str(job_id))
+            self._save(data)
+        status = waiting_message(reason, hold["since"], hold["until"], message)
+        push = None
+        if opened:
+            push = self._emit(HOLD_EVENT_KIND, "notice", hold_sentence(caller, work, reason, until),
+                              {"type": "limit", "id": "%s:%s" % (reason, caller)[:200], "label": REASON_WORDS[reason]}, True)
+        return {"hold": dict(hold), "statusMessage": status, "push": push}
+
+    def release(self, *, reason: str, caller: str, now: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """Close the open hold of (reason, caller): the limit freed the work. The next hold pushes again."""
+        at = self._now(now)
+        with self._lock:
+            data = self._load()
+            hold = next((h for h in data["holds"] if h.get("closed") is None and h["reason"] == reason
+                         and h["caller"] == caller), None)
+            if hold is None:
+                return None
+            hold["closed"], hold["closedAt"] = "released", at
+            self._save(data)
+            return dict(hold)
+
+    def open_holds(self, now: Optional[str] = None) -> List[Dict[str, Any]]:
+        data = self._load()
+        self._expire(data, utc_time(self._now(now)))
+        return [dict(h) for h in data["holds"] if h.get("closed") is None]
+
+    # --- lifts ----------------------------------------------------------------------------
+    def lift(self, *, reason: str, decision: Dict[str, Any], caller: Optional[str] = None, job_id: Optional[str] = None,
+             jobs: Optional[int] = None, usd: Optional[float] = None, limit: Optional[int] = None,
+             until: Optional[str] = None, now: Optional[str] = None) -> Dict[str, Any]:
+        """Record the operator's answer as a scoped lift: exactly one of `jobs` (that many more jobs), `usd` (that much
+        more money) or `limit` (the limit raised to that value, which needs `until`, the window's end). `decision` is
+        the operator's words in decision.schema.json's shape with action `limit.lift`. The open hold it covers closes
+        as lifted. Returns the lift."""
+        if reason not in HOLD_REASONS:
+            raise ServiceError("A lift's reason is one of %s." % ", ".join(HOLD_REASONS))
+        if not decision_shape(decision) or decision.get("action") != LIFT_ACTION:
+            raise ServiceError("A lift carries the operator's decision (decision.schema.json, action limit.lift, their "
+                               "words verbatim): fabric_actions.operator_decision('limit.lift', words).")
+        sizes = {"jobs": jobs, "usd": usd, "limit": limit}
+        given = [name for name in _SIZES if sizes[name] is not None]
+        if len(given) != 1:
+            raise ServiceError("A lift is one of jobs, usd or limit.")
+        size = sizes[given[0]]
+        if isinstance(size, bool) or not isinstance(size, (int, float)) or size <= 0 or (
+                given[0] != "usd" and int(size) != size):
+            raise ServiceError("A lift's %s is a positive %s." % (given[0], "number" if given[0] == "usd" else "integer"))
+        at = self._now(now)
+        if until is not None and utc_time(_instant(until, "until")) <= utc_time(at):
+            raise ServiceError("A lift's window ends after now.")
+        if given[0] == "limit" and until is None:
+            raise ServiceError("A raised limit needs its window's end (until): it falls back when the window ends.")
+        record: Dict[str, Any] = {"id": uuid.uuid4().hex, "reason": reason, "caller": None if caller is None else _text(caller, "caller"),
+                                  "job": None if job_id is None else str(job_id), "from": at, "until": until,
+                                  given[0]: size, "decision": dict(decision), "at": at}
+        if given[0] != "limit":
+            record["left"] = size
+        with self._lock:
+            data = self._load()
+            self._expire(data, utc_time(at))
+            for hold in data["holds"]:
+                if hold.get("closed") is None and hold["reason"] == reason and record["caller"] in (None, hold["caller"]) and (
+                        job_id is None or str(job_id) in hold["jobs"]):
+                    hold["closed"], hold["closedAt"], hold["lift"] = "lifted", at, record["id"]
+            data["lifts"].append(record)
+            self._save(data)
+        scope = ("for %s" % record["caller"]) if record["caller"] else "for every caller"
+        amount = {"jobs": "%s more job(s)", "usd": "USD %s more", "limit": "the limit at %s"}[given[0]] % size
+        self._emit(LIFT_EVENT_KIND, "info", "The operator lifted %s %s: %s%s." % (
+            REASON_WORDS[reason], scope, amount, (" until %s" % until) if until else ""),
+            {"type": "limit", "id": "%s:%s" % (reason, record["caller"] or "*"), "label": REASON_WORDS[reason]}, False)
+        return dict(record)
+
+    def _matching(self, data: Dict[str, Any], reason: str, caller: Optional[str], job_id: Optional[str], at: int,
+                  kind: str) -> List[Dict[str, Any]]:
+        return [l for l in data["lifts"] if l["reason"] == reason and kind in l and self._live(l, at)
+                and l.get("caller") in (None, caller) and l.get("job") in (None, job_id)]
+
+    def admit(self, *, reason: str, caller: str, job_id: Optional[str] = None, cost_usd: Optional[float] = None,
+              now: Optional[str] = None) -> Dict[str, Any]:
+        """Whether a lift lets work past the limit that would hold it: {admitted: True, lift} spends one job of a jobs
+        lift, or `cost_usd` of a money lift (the narrowest scope first: a job's, a caller's, every caller's), else
+        {admitted: False}. A raised limit is read with `limit`, not spent here."""
+        at = utc_time(self._now(now))
+        with self._lock:
+            data = self._load()
+            kind = "usd" if cost_usd is not None else "jobs"
+            for lift in sorted(self._matching(data, reason, caller, None if job_id is None else str(job_id), at, kind),
+                               key=lambda l: (l.get("job") is None, l.get("caller") is None)):
+                need = cost_usd if kind == "usd" else 1
+                if lift["left"] >= need:
+                    lift["left"] = round(lift["left"] - need, 6) if kind == "usd" else lift["left"] - 1
+                    self._save(data)
+                    return {"admitted": True, "lift": lift["id"], "left": lift["left"]}
+            return {"admitted": False}
+
+    def limit(self, *, reason: str, base: float, caller: Optional[str] = None, now: Optional[str] = None) -> float:
+        """The limit in force: `base`, or the highest live raised limit for (reason, caller); `base` again once the
+        window ends."""
+        at = utc_time(self._now(now))
+        raised = [l["limit"] for l in self._matching(self._load(), reason, caller, None, at, "limit")]
+        return max([base] + raised)
+
+    def lifts(self, now: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Every lift with `live`: whether it still applies now."""
+        at = utc_time(self._now(now))
+        return [dict(l, live=self._live(l, at)) for l in self._load()["lifts"]]

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_http.py

@@ -28,6 +28,7 @@ The transport is injected in tests: `transport(method, url, headers, body, timeo
 `(status, headers, body_bytes)` or raises `OSError` (a connection error, `TimeoutError` included) or `HttpError`.
 Standard library only. Part of the service kit (FAA-65, layer L4).
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import datetime as _dt
@@ -64,7 +65,7 @@ class HttpError(Exception):
     refused URL or a body over the cap; `url` is redacted; `body` holds at most 2048 bytes of an answer's body."""
 
     def __init__(self, message: str, *, status: Optional[int] = None, url: str = "", attempts: int = 0,
-                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http"):
+                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http", reason: Optional[str] = None):
         super().__init__(message)
         self.status = status
         self.url = url
@@ -72,6 +73,9 @@ class HttpError(Exception):
         self.retry_after_s = retry_after_s
         self.body = bytes(body[:2048])
         self.kind = kind  # http (an answer), connection, timeout, too-large, refused, foreign-user
+        #: For foreign-user, why (FAA-272): `table-restricted` (this process sees no other process's sockets, which
+        #: never clears), the owner's kind (`another-account`, `system`) or the check's reason (`no-row`).
+        self.reason = reason
 
 
 class Response:
@@ -357,13 +361,43 @@ class _CheckedHTTPConnection(_po.CheckedHTTPConnection):
         self.vouch_pid = None  # a loopback URL is never a process this caller started (FAA-267)
 
 
+def _peer_is_loopback(sock: Any) -> bool:
+    """Whether a connected socket reached this computer's loopback, by the address it connected to, not by the URL's
+    spelling: a name the hosts file maps to 127.0.0.1, `0.0.0.0`, `::ffff:127.0.0.1` and a proxy on loopback all
+    arrive here (0.74.0 unit readings 7, 8 and 11; FAA-260)."""
+    try:
+        host = str(sock.getpeername()[0]).split("%", 1)[0]
+        address = ipaddress.ip_address(host)
+    except (OSError, ValueError, TypeError, IndexError, AttributeError):
+        return False
+    mapped = getattr(address, "ipv4_mapped", None)
+    return bool((mapped or address).is_loopback or address.is_unspecified)
+
+
+class _PlainHTTPConnection(http.client.HTTPConnection):
+    """Plain http to a host not spelled as loopback (`insecure=True`) or to a proxy from the environment: when the
+    connected socket's peer is a loopback address, its server end is told as `_CheckedHTTPConnection` tells it, and
+    another account's, root's or an unknown owner is refused before a byte is sent (DEC-0154 HA-2, FAA-260)."""
+
+    def connect(self) -> None:
+        super().connect()
+        if not _peer_is_loopback(self.sock):
+            return
+        owner = _po.server_end(self.sock)
+        port = self.sock.getpeername()[1]
+        refused = _po.refusal(owner, port, None)
+        if refused is not None:
+            self.close()
+            raise _po.ListenerRefused(refused[0], "%s; nothing was sent" % refused[1], owner)
+
+
 def _opener(watchdog: _Watchdog, direct: bool = False) -> urllib.request.OpenerDirector:
     """`direct`: a loopback URL never goes through a proxy from the environment (`http_proxy`), so the connection the
     owner check reads is the one to the URL's own port (DEC-0154 HA-2), and a bearer never reaches a proxy."""
     class Http(urllib.request.HTTPHandler):
         def http_open(self, req):
             local = _is_loopback((urllib.parse.urlsplit(req.full_url).hostname or "").lower())
-            return self.do_open(_watched(_CheckedHTTPConnection if local else http.client.HTTPConnection, watchdog), req)
+            return self.do_open(_watched(_CheckedHTTPConnection if local else _PlainHTTPConnection, watchdog), req)
 
     class Https(urllib.request.HTTPSHandler):
         def https_open(self, req):
@@ -385,7 +419,10 @@ def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optio
         return _send(req, timeout_s, max_bytes, end, watchdog)
     except _po.ListenerRefused as exc:
         where = "%s %s" % (method, redact_url(url))
-        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user") from None
+        owner = getattr(exc, "owner", None)
+        why = str(getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", "") or "unknown")
+        reason = _po.TABLE_RESTRICTED if why.startswith(_po.TABLE_RESTRICTED) else why.split(":", 1)[0]
+        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user", reason=reason) from None
     except (OSError, http.client.HTTPException) as exc:
         if watchdog.fired:
             raise TimeoutError("the answer did not arrive within the deadline")

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_hub.py

@@ -67,6 +67,20 @@ class HubError(Exception):
         return "HubError(%r, %r)" % (self.code, self.message)
 
 
+def listener_refusal(exc: Any) -> HubError:
+    """The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned
+    contract's state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted`
+    when this process's socket table hides other processes' sockets, which never clears, so it is not retryable;
+    otherwise the owner's kind or the check's reason (`another-account`, `no-row`), retryable as before."""
+    owner = getattr(exc, "owner", None)
+    why = (getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", None) or "unknown")
+    reason = _po.TABLE_RESTRICTED if str(why).startswith(_po.TABLE_RESTRICTED) else str(why).split(":", 1)[0]
+    kind = getattr(owner, "kind", None)
+    shown = "%s: %s" % (kind, owner.reason) if kind and getattr(owner, "reason", None) else str(kind or why)
+    return HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent." % shown,
+                    reason != _po.TABLE_RESTRICTED, {"reason": reason})
+
+
 # --- where Fabric is --------------------------------------------------------------------------------------------
 
 def fabric_root(platform: str = sys.platform, env: Optional[Dict[str, str]] = None) -> Path:
@@ -233,8 +247,7 @@ def post_mcp(origin: str, body: Dict[str, Any], bearer: str, session: Optional[s
         raw = resp.read(4 * 1024 * 1024)
         got = {k.lower(): v for k, v in resp.getheaders()}
     except _po.ListenerRefused as exc:
-        raise HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent."
-                       % (exc.owner.kind if exc.owner else exc.code), True) from None
+        raise listener_refusal(exc) from None
     except (OSError, http.client.HTTPException) as exc:
         raise HubError("hub-unavailable", "Fabric's hub did not answer (%s)." % exc.__class__.__name__, True) from None
     finally:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_interop.py

@@ -825,7 +825,7 @@ class McpToolServer:
             gated = self._gate_action(action, "fabric.job.get", {"id": job_id, "inputResponses": {key: value}}, None, None,
                                       headers, tier, meta, caller, mandate)
             if not gated["ok"]:
-                return gated
+                return dict(gated, capability=private.get("capability"))  # the one read names the fault (FAA-186)
             records[key] = gated["record"]
         return {"ok": True, "records": records}
 
@@ -933,7 +933,7 @@ class McpToolServer:
                 if not inputs["ok"] and "invalid" in inputs:
                     return self._error(rid, -32602, inputs["invalid"])
                 if not inputs["ok"]:
-                    stored = self.jobs.private(str(arguments.get("id", ""))).get("capability")
+                    stored = inputs.get("capability")  # read once, by _gate_inputs (FAA-186)
                     self._fault(stored if isinstance(stored, str) else name, inputs)  # as the start heard it (FAA-179)
                     import fabric_delegation as _fd  # noqa: E402 - DL-19
                     return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(inputs["refusal"], traceparent=span)}