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

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

@@ -80,7 +80,7 @@ import fabric_connections as fcn  # noqa: E402
 from check_service_rules import shown_repository  # noqa: E402 - a repository in evidence carries no userinfo or query
 import fabric_interop as fi  # noqa: E402
 import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2: the listener's owner before any credential
-from check_service_rules import ForeignUser, PORT_RULES_UNREAD, listener_owner_verdict  # noqa: E402 - DEC-0154 HA-2
+from check_service_rules import ForeignUser, PORT_RULES_UNREAD, in_launch_daemons, listener_owner_verdict, other_domain_copy, port_claim_verdict  # noqa: E402 - DEC-0154 HA-2
 
 Result = Dict[str, str]
 
@@ -97,7 +97,7 @@ from check_service_rules import usage_problems  # noqa: E402,F401 - moved (FAA-6
 from check_service_rules import same_repository  # noqa: E402,F401 - moved (FAA-65)
 from check_service_rules import merge_headers, session_cookie  # noqa: E402,F401 - FAA-115
 from check_service_rules import well_known_actions_verdict, action_tools_verdict, actions_declared_verdict  # noqa: E402 - DEC-0121
-from check_service_rules import opens_in_host_verdict, service_checkout  # noqa: E402 - FAA-118
+from check_service_rules import opens_in_host_verdict, service_checkout, declared_limits, holds_verdict  # noqa: E402 - FAA-118, FAA-298
 from check_service_rules import well_known_a2a_verdict, a2a_card_verdict  # noqa: E402 - DEC-0122
 import fabric_a2a as fa2  # noqa: E402 - DEC-0122
 import check_service_channel_agent as cac  # noqa: E402 - DEC-0150, FAA-197
@@ -153,6 +153,7 @@ class Probe:
 
     def request(self, method: str, path: str, headers: Optional[Dict[str, str]] = None,
                 body: Optional[bytes] = None) -> Tuple[int, Dict[str, str], bytes]:
+        """`connected_at`: when a local connect and its owner check ended, so the answer is timed from there (r11)."""
         if self.remote:
             context = ssl.create_default_context(cafile=self.ca_file) if self.ca_file else ssl.create_default_context()
             if self.connect:
@@ -167,6 +168,9 @@ class Probe:
             base = {"Host": "127.0.0.1:%d" % self.port}
         base.update(headers or {})
         try:
+            if not self.remote:
+                conn.connect()
+                self.connected_at = time.perf_counter()
             conn.request(method, path, body=body, headers=base)
             resp = conn.getresponse()
             return resp.status, merge_headers(resp.getheaders()), resp.read()
@@ -203,25 +207,7 @@ class Probe:
         else:
             mode = stat.S_IMODE(os.stat(self.path).st_mode)
             self.add("descriptor.private", "PASS" if mode & 0o077 == 0 else "FAIL", "mode %o" % mode)
-        me = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
-        clashes = []
-        for path, other in fs.read_descriptors(self.dir):
-            key = "%s.%s" % (other.get("id"), other.get("instance", "default"))
-            if path.resolve() == self.path.resolve():
-                continue
-            if key == me:
-                clashes.append("%s declared again in %s" % (me, path.name))
-            # DEC-0069: a descriptor without an origin (an app's) claims no port, so two of them never clash.
-            elif (not self.remote and "origin" in self.d and fs.placement_of(other) != "remote"
-                  and other.get("origin") == self.d.get("origin")):
-                clashes.append("port %d also claimed by %s" % (self.port, key))
-        if self.remote:
-            unique = "a remote origin claims no port here"
-        elif "origin" not in self.d:
-            unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
-        else:
-            unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % self.port
-        self.add("descriptor.port-claim", "FAIL" if clashes else "PASS", "; ".join(clashes) or unique)
+        self.add("descriptor.port-claim", *port_claim_verdict(self.path, self.d, self.dir, self.port, self.remote))
         # FAA-198: the repository that links the agent to its project; a new install is refused without it, an installed one
         # is named here (NOT_RUN is no pass) until its owner adds it.
         # A source descriptor.valid refuses is no pass either, and the evidence never carries a URL's userinfo or query,
@@ -260,9 +246,9 @@ class Probe:
         try:
             timings = []
             for _ in range(3):
-                started = time.perf_counter()
+                started = self.connected_at = time.perf_counter()
                 status, headers, body = self.request("GET", "/.well-known/fabric-service", protected)
-                timings.append((time.perf_counter() - started) * 1000)
+                timings.append((time.perf_counter() - max(started, self.connected_at)) * 1000)
         except OSError as exc:
             if self.remote:
                 self.add_no_token(no_token, None)
@@ -276,7 +262,7 @@ class Probe:
         try:
             self.wk = json.loads(body)
             self.wk_bytes = len(body)  # D4 of the 0.73.0 brief: a well-known answer shares a 2 MiB cap
-        except ValueError:
+        except (ValueError, RecursionError):  # Python 3.9 to 3.13 raise RecursionError on deep nesting (unit reading 10)
             if self.remote:
                 self.add_no_token(no_token, None)
             self.add("well-known.answers", "FAIL", "body is not JSON")
@@ -467,7 +453,7 @@ class Probe:
             self.add("usage.report", "FAIL", "HTTP %d with the token" % status)
             return
         try:
-            report = json.loads(body)
+            report = self.usage_report = json.loads(body)  # FAA-298: limits.holds reads its budgets
         except ValueError:
             self.add("usage.report", "FAIL", "not JSON")
             return
@@ -673,12 +659,14 @@ class Probe:
         self.events_trace_rule(self.events)
 
     def channel_agent_rule(self) -> None:
-        """DEC-0150 (FAA-197): the channel agent's declaration, read from the manifest the descriptor names, else from the
-        well-known answer (CA-1); one read as not declared is NOT_RUN with its evidence, never a FAIL (D3), except a string
-        shaped like a credential in it or in a copy the probe reads beside it (CA-5)."""
+        """DEC-0150 (FAA-197): the declaration, from the manifest the descriptor names, else the well-known answer (CA-1); one
+        read as not declared is NOT_RUN, never a FAIL (D3), except a credential's shape in it or a copy beside it (CA-5)."""
         manifest, _, where = self.load_manifest()
-        self.add("channel-agent.declaration", *cac.declaration_verdict(
-            manifest, bool(self.d.get("fabricManifest")), where, self.wk, getattr(self, "wk_bytes", None)))
+        try:  # a copy of the probe without its schema file is NOT_RUN, and the later rules run (FAA-250)
+            verdict = cac.declaration_verdict(manifest, bool(self.d.get("fabricManifest")), where, self.wk, getattr(self, "wk_bytes", None))
+        except (OSError, ValueError) as exc:
+            verdict = ("NOT_RUN", "the probe cannot read %s beside it (%s)" % (cac.cas.SCHEMA_FILE.name, type(exc).__name__))
+        self.add("channel-agent.declaration", *verdict)
 
     def configuration_rule(self) -> None:
         """DEC-0046: a well-known `configuration` is {slots, resolved} as the schema types it; absent is NOT_RUN."""
@@ -821,7 +809,7 @@ class Probe:
         except (OSError, ValueError) as exc:
             self.add("lifecycle.plist", "FAIL", "cannot read %s: %s" % (plist_path, exc))
             return
-        problems = plist_problems(plist, life.get("label"), self.token)
+        problems = plist_problems(plist, life.get("label"), self.token, system=in_launch_daemons(plist_path), commands=self.d.get("commands"))
         self.add("lifecycle.plist", "FAIL" if problems else "PASS", "; ".join(problems) or "%s: RunAtLoad, KeepAlive, no secrets" % plist_path.name)
         marker = marker_problem(plist)
         self.add("lifecycle.supervisor-marker", "FAIL" if marker else "PASS",
@@ -841,6 +829,9 @@ class Probe:
             self.add("lifecycle.one-copy", "FAIL", "launchd job %s is not loaded in %s" % (life.get("label"), domain))
         elif not match:
             self.add("lifecycle.one-copy", "FAIL", "launchd job loaded but not running")
+        elif other_domain_copy(life.get("label"), domain):  # loaded in both domains: two copies (FAA-286 item 6)
+            self.add("lifecycle.one-copy", "FAIL", "launchd job %s is loaded in %s and in %s: two copies; uninstall one"
+                     % (life.get("label"), domain, other_domain_copy(life.get("label"), domain)))
         else:
             same = int(match.group(1)) == served
             self.add("lifecycle.one-copy", "PASS" if same else "FAIL",
@@ -945,8 +936,8 @@ class Probe:
             self.login_rules()
             self.interop_rules()
             self.channel_agent_rule()
-            verdict, evidence = board_responder_verdict(self.wk, self.board_kit)
-            self.add("board.responder", verdict, evidence)
+            self.add("limits.holds", *holds_verdict(declared_limits(self.wk, getattr(self, "usage_report", None)), *service_checkout(self.d, self.repo)))
+            self.add("board.responder", *board_responder_verdict(self.wk, self.board_kit))
         self.lifecycle_rules()
         return self.results
 

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

@@ -18,7 +18,8 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from fabric_jsvalue import indexed_objects, js_keys  # noqa: E402
-from fabric_secrets import JS_SPACE, JWT_SHAPE, SECRET_VALUE, _url_parts, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
+from fabric_secrets import JS_SPACE, JWT_SHAPE, SECRET_VALUE, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
+from fabric_secrets import url_parts as _whatwg_url_parts  # noqa: E402 - public since FAA-250
 import check_service_channel_agent_schema as cas  # noqa: E402
 
 KEY = "https://fabric.passioncode.ai/agent-contract/extensions/channel-agent/0.1"
@@ -62,6 +63,9 @@ _IGNORABLE = ((0x00AD, 0x00AD), (0x034F, 0x034F), (0x061C, 0x061C), (0x115F, 0x1
               (0x200B, 0x200F), (0x202A, 0x202E), (0x2060, 0x206F), (0x3164, 0x3164), (0xFE00, 0xFE0F), (0xFEFF, 0xFEFF),
               (0xFFA0, 0xFFA0), (0xFFF0, 0xFFF8), (0x1BCA0, 0x1BCA3), (0x1D173, 0x1D17A), (0xE0000, 0xE0FFF))
 _FILLERS = frozenset("\u115f\u1160\u3164\uffa0\u2800\ufffc")
+#: Format characters (\p{Cf}) assigned after Unicode 13, which Python 3.9's unicodedata reads as unassigned (FAA-250):
+#: U+0890..0891 (Unicode 14) and U+13439..1343F (Unicode 15); the white-space and control categories gained none since.
+_LATER_FORMATS = ((0x0890, 0x0891), (0x13439, 0x1343F))
 
 
 def utf16(text: str) -> str:
@@ -75,7 +79,7 @@ def utf16(text: str) -> str:
 def _blank_char(char: str) -> bool:
     code = ord(char)
     return (char in JS_SPACE or char in _FILLERS or unicodedata.category(char) in ("Cf", "Cc", "Zs", "Zl", "Zp")
-            or any(low <= code <= high for low, high in _IGNORABLE))
+            or any(low <= code <= high for low, high in _IGNORABLE + _LATER_FORMATS))
 
 
 def blank(text: str) -> bool:
@@ -397,7 +401,7 @@ def url_parts(text: str) -> Optional[Tuple[str, str]]:
             return None
         if host and not _host_ok(host, special):
             return None
-    _, query, fragment = _url_parts(text)
+    _, query, fragment = _whatwg_url_parts(text)
     has_query = "?" in rest.partition("#")[0]
     has_fragment = "#" in rest
     return ("?" + query if has_query and query else "", "#" + fragment if has_fragment and fragment else "")
@@ -453,7 +457,8 @@ def secrets(value: Any, root: str, budget: Budget) -> List[Dict[str, str]]:
     def flag(at: str, what: str, text: str, ident: bool) -> None:
         if budget.named < SECRET_FINDINGS:
             budget.named += 1
-            rename = "; an id that starts with sk- is read as a key; rename it" if ident and re.match(r"sk-", text, re.I | re.A) else ""
+            # canonical case only (DEC-0151): an upper-case SK- is no key, so the advice would name the wrong cause
+            rename = "; an id that starts with sk- is read as a key; rename it" if ident and text.startswith("sk-") else ""
             findings.append(_finding("FAC-SEM-165", at, "%s is shaped like a credential: a token is named by its vault slot, never written%s (DEC-0150 CA-5)" % (what, rename)))
         else:
             budget.more += 1
@@ -823,8 +828,9 @@ def declaration_verdict(manifest: Optional[Dict[str, Any]], manifest_named: bool
     where = "the manifest's provider.extensions" if site == "manifest" else "the well-known answer's extensions"
     shapes = _credential_shapes(others + copy)
     if shapes:  # a credential's shape in a copy no reader reads still sits in a document the service publishes (CA-5)
-        return "FAIL", "%d string(s) shaped like a credential outside the read declaration: %s (DEC-0150 CA-5)%s" % (
-            len(shapes), _shown(shapes), tail)
+        also = ("; on the read declaration itself, %d finding(s): %s" % (len(own), _shown(own))) if own else ""
+        return "FAIL", "%d string(s) shaped like a credential outside the read declaration: %s (DEC-0150 CA-5)%s%s" % (
+            len(shapes), _shown(shapes), also, tail)
     if declared and own:
         if not channel_agent_view(doc, site)["declared"] and not _credential_shapes(own):
             # D3: what the contract's reader reads as not declared (an older form, a repeat, a dangling reference) is

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

@@ -3,6 +3,7 @@ network guard's verdict, the board responder's fixture conversation, a session c
 whether two repository URLs name one repository, a service's actions declaration (DEC-0121) and whether its checkout
 opens its pages in a browser (FAA-118), and its A2A member and public Agent Card (DEC-0122). ``check_service.py`` runs them against a live service.
 Standard library only, Python 3.9+."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import email.utils
@@ -21,6 +22,7 @@ import fabric_service as fs  # noqa: E402 - beside this file
 from fabric_http import redact_url  # noqa: E402
 from fabric_secrets import ascii_decoded, repository_name, secret_argument  # noqa: E402
 import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2
+import fabric_supervisors as _sup  # noqa: E402 - where a LaunchDaemon's plist lives (FAA-278)
 import socket  # noqa: E402
 
 
@@ -46,7 +48,17 @@ def listener_owner_verdict(port: int) -> Tuple[str, str]:
     except ConnectionRefusedError:
         return "NOT_RUN", "nothing listens on %s (down)" % where
     except OSError as exc:  # a full backlog, a timeout: the well-known rule reports what answers, each call checked
-        return "NOT_RUN", "could not connect to %s to tell its owner (%s)" % (where, type(exc).__name__)
+        # The listener table still names who holds the port (0.74.0 product reading 10, FAA-260 item 12): another
+        # account's or root's listener is foreign-user without a connection; any other owner is named beside NOT_RUN.
+        held = po.listener(port)
+        if held.kind in (po.ANOTHER_ACCOUNT, po.SYSTEM):
+            why = "another OS account's process" if held.kind == po.ANOTHER_ACCOUNT else "a system account's process"
+            return "FAIL", ("foreign-user: %s is listened on by %s (its listener read by %s; the connect failed with %s); "
+                            "no credential was sent and nothing it answers is read as this service's"
+                            % (where, why, held.method, type(exc).__name__))
+        named = held.kind if held.kind != po.UNKNOWN else "unknown (%s)" % held.reason
+        return "NOT_RUN", "could not connect to %s to tell its owner (%s); its listener reads as %s" % (
+            where, type(exc).__name__, named)
     try:
         owner = po.server_end(sock)
     finally:
@@ -59,6 +71,39 @@ def listener_owner_verdict(port: int) -> Tuple[str, str]:
     return "FAIL", ("foreign-user: %s is held by %s (read by %s); no credential was sent and nothing it answers is read "
                     "as this service's" % (where, why, owner.method))
 
+def port_claim_verdict(path: Path, d: Dict[str, Any], directory: Path, port: int, remote: bool) -> Tuple[str, str]:
+    """`descriptor.port-claim`: (verdict, evidence). Another descriptor here declares this `id.instance`, or a local
+    origin on the same port, compared by the port as the writers refuse it, so `:08080` beside `:8080` is one port
+    (0.74.0 seam reading 10, FAA-260)."""
+    me = "%s.%s" % (d.get("id"), d.get("instance", "default"))
+    clashes = []
+    for other_path, other in fs.read_descriptors(directory):
+        key = "%s.%s" % (other.get("id"), other.get("instance", "default"))
+        if other_path.resolve() == path.resolve():
+            continue
+        if key == me:
+            clashes.append("%s declared again in %s" % (me, other_path.name))
+        # DEC-0069: a descriptor without an origin (an app's) claims no port, so two of them never clash.
+        elif not remote and "origin" in d and fs.placement_of(other) != "remote" and port and _port_or_none(
+                other.get("origin")) == port:
+            clashes.append("port %d also claimed by %s" % (port, key))
+    if remote:
+        unique = "a remote origin claims no port here"
+    elif "origin" not in d:
+        unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
+    else:
+        unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % port
+    return ("FAIL" if clashes else "PASS"), ("; ".join(clashes) or unique)
+
+
+def _port_or_none(origin: Any) -> Optional[int]:
+    """The port a local origin claims, or None for an origin the descriptor rules refuse (descriptor.valid names it)."""
+    try:
+        return fs.port_of(str(origin))
+    except fs.ServiceError:
+        return None
+
+
 _LOCAL_PATH = re.compile(r"[/~.\\]|[A-Za-z]:[/\\]")  # how a local path starts, never a user before an `@`
 _SCP_HOST = re.compile(r"[^@/:\\]+:")  # what follows the `@` of user[:password]@host:path
 _SPECIAL = re.compile(r"(?:https?|wss?|ftp|file):", re.I)  # the URL standard's special schemes, read with or without `//`
@@ -90,9 +135,37 @@ import fabric_actions as fa  # noqa: E402 - beside this file (DEC-0121)
 import fabric_a2a as fa2  # noqa: E402 - beside this file (DEC-0122)
 
 
-def plist_problems(plist: dict, label: object, token: object = None) -> list:
-    """What makes a service's launchd job unfit to stay up: identity, restart, secrets."""
+def other_domain_copy(label: object, domain: str) -> Optional[str]:
+    """The other launchd domain when it also has job `label` loaded, a second copy (FAA-286 item 6), else None."""
+    other = ("gui/%d" % getattr(os, "getuid", lambda: 0)()) if domain == "system" else "system"
+    try:
+        out = subprocess.run(["launchctl", "print", "%s/%s" % (other, label)], capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return other if out.returncode == 0 else None
+
+
+def in_launch_daemons(plist_path: Path) -> bool:
+    """Whether a plist sits in /Library/LaunchDaemons, where launchd loads it at boot as a LaunchDaemon (FAA-278)."""
+    folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))
+    return folder.lower() == str(_sup.SYSTEM_DAEMONS).lower()  # the supervisors' own, which a test may point elsewhere
+
+
+def plist_problems(plist: dict, label: object, token: object = None, *, system: bool = False,
+                   commands: object = None) -> list:
+    """What makes a service's launchd job unfit to stay up: identity, restart, secrets. A LaunchDaemon (`system`) also
+    needs UserName, or it runs as root (FAA-286 item 22), and its descriptor's commands an absolute path, since a
+    `~` would be root's home when the job's update runs as root (item 23)."""
     problems = []
+    if system and not (isinstance(plist.get("UserName"), str) and plist.get("UserName")):
+        problems.append("a LaunchDaemon without UserName runs as root, and every client refuses root's listener "
+                        "(DEC-0154 HA-2)")
+    if system and isinstance(commands, dict):
+        for name, argv in sorted(commands.items()):
+            first = argv[0] if isinstance(argv, list) and argv else argv
+            if isinstance(first, str) and first.startswith("~"):
+                problems.append("commands.%s starts with ~, which is root's home for a LaunchDaemon: write the absolute "
+                                "path" % name)
     if plist.get("Label") != label:
         problems.append("Label %r" % plist.get("Label"))
     if plist.get("RunAtLoad") is not True:
@@ -728,3 +801,63 @@ def service_checkout(descriptor: Any, repo: Optional[str]) -> Tuple[Optional[Pat
         if same_repository(_git_out(Path(top), "remote", "get-url", "origin") or "", source):
             return Path(top), "the checkout of %s that holds %s" % (shown_repository(source), place)
     return None, "no checkout of %s holds the descriptor's commands, manifest or launchd job; pass --repo" % shown_repository(source)
+
+
+# FAA-298: a service with limits of its own holds work visibly (fabric_holds), never silently.
+_HOLD_USE = "HoldBook|waiting_message|waitingMessage|hold_job|holdJob"  # git grep -E is POSIX: no word boundary
+#: the kit's own copies, and a vendored copy of this file (its pattern names the kit's words): neither is a use
+_HOLD_KIT_FILES = ("fabric_holds.py", "fabric-holds.mjs", "check_service_rules.py")
+#: only code holds work: a README or a note naming HoldBook is no use of it (0.81.0 seam reading)
+_HOLD_CODE = ("*.py", "*.mjs", "*.js", "*.ts")
+
+
+def declared_limits(wk: Any, usage_report: Any = None) -> List[str]:
+    """The limits a service declares: the load declaration's `limits` (DEC-0104), and the usage report's `budget` and
+    `budgets` (DEC-0021, DEC-0027) when the probe read one. An invalid load declaration reads as not declared."""
+    import fabric_load  # noqa: E402 - beside this file
+    found: List[str] = []
+    view = fabric_load.load_view(wk)
+    limits = (view.get("load") or {}).get("limits") if view.get("valid") else None
+    if isinstance(limits, dict):
+        found += ["load %s %s" % (name, limits[name]) for name in ("concurrency", "perCaller", "queueMax") if name in limits]
+    if isinstance(usage_report, dict):
+        budget = usage_report.get("budget")
+        if isinstance(budget, dict) and "limitUsd" in budget:
+            found.append("usage budget USD %s a %s" % (budget.get("limitUsd"), budget.get("period")))
+        budgets = usage_report.get("budgets")
+        if isinstance(budgets, list) and budgets:
+            found.append("usage budgets (%d)" % len(budgets))
+    return found
+
+
+def holds_verdict(limits: List[str], repo: Optional[Path], why: str,
+                  budget: float = OPENS_IN_HOST_BUDGET) -> Tuple[str, str]:
+    """`limits.holds` over one checkout: PASS when a tracked file outside the kit's own copy and the tests holds work
+    through fabric_holds (HoldBook, waiting_message, hold_job) in a code file (.py, .mjs, .js, .ts); NOT_RUN when it
+    declares none, or its checkout or git cannot be read in the budget. A service that declares limits and holds none
+    through the kit is NOT_RUN with a migration note naming fabric_holds, never FAIL: services built before the module
+    existed could not have adopted it, and whether one holds work silently or refuses it cannot be read from its tree."""
+    if not limits:
+        return "NOT_RUN", "the service declares no limits (a load declaration's limits, a usage report's budget or budgets)"
+    if repo is None:
+        return "NOT_RUN", why
+    if not shutil.which("git"):
+        return "NOT_RUN", "git is not installed"
+    try:
+        listed = subprocess.run(["git", "-C", str(repo), "grep", "-I", "-l", "-z", "-E", _HOLD_USE, "--"]
+                                + list(_HOLD_CODE), capture_output=True,
+                                timeout=max(0.05, budget))
+    except subprocess.TimeoutExpired:
+        return "NOT_RUN", "the %.1f s budget ran out while git read %s" % (budget, repo)
+    except OSError as exc:
+        return "NOT_RUN", "git could not read %s: %s" % (repo, exc)
+    if listed.returncode not in (0, 1):
+        return "NOT_RUN", "git grep could not read %s" % repo
+    users = [p for p in listed.stdout.decode("utf-8", "surrogateescape").split("\0")
+             if p and p.rsplit("/", 1)[-1] not in _HOLD_KIT_FILES and not _TEST_PATH.search(p)]
+    if users:
+        return "PASS", "declares %s; %s hold(s) work through fabric_holds" % ("; ".join(limits), ", ".join(users[:5]))
+    return "NOT_RUN", ("migration: declares %s, and no tracked code file outside the kit and the tests holds work "
+                       "through fabric_holds (HoldBook, waiting_message, hold_job) yet. Adopt fabric_holds so each hold "
+                       "is said on the job, the operator is pushed once per hold and takes a scoped lift (FAA-298, "
+                       "references/interop.md); until then this rule is not run" % "; ".join(limits))

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-session.mjs

@@ -104,6 +104,8 @@ export class Responder extends SlotKeeper {
     this.state = 'idle';
     this.waitUntil = 0;
     this.stopping = false;
+    /** Whether shutdown found work to drain, published before it waits; null before shutdown starts (FAA-186). */
+    this.draining = null;
     this.claimKeys = {};
     this.probing = new Set(); // moved slots whose move-back claim lost its answer: asked again under the same key
     this.said = {};
@@ -939,6 +941,7 @@ export class Responder extends SlotKeeper {
   async shutdown(drain = DRAIN_SECONDS) {
     this.stopping = true;
     const work = this.current;
+    this.draining = Boolean(work); // what this shutdown waits for (FAA-186)
     if (work && !work.done) {
       await Promise.race([work.promise, new Promise((resolve) => setTimeout(resolve, drain * 1000).unref?.())]);
       if (!work.done) work.ctx.stopped = true;

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-slots.mjs

@@ -254,6 +254,7 @@ export class SlotKeeper {
       if (!(e instanceof BoardError)) throw e;
       this.retryLater(capability, entries, e);
       if (SESSION_CODES.has(e.code)) throw e;
+      if (e.code === 'idempotency_window_expired') await this.status(); // the epoch moved: read it before the retry (FAA-186)
     }
   }
 }

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-context.mjs

@@ -6,7 +6,7 @@
 // An organization's instance whose context the record does not pin (`organizations`, DEC-0127) still starts: the helper
 // checks the placement and its share grant, not the pin (decision D5 of 0.52.0). Its tokens are refused instead:
 // hubKeyCertified reads a context's hub keys only while the record pins that organization (DL-14a, DEC-0128), so the
-// service passes `estateContext: context` to its delegation gate. A refusal at start would stop every organization
+// service passes contextGateOptions(info, record) (its context and its pin's issuer, FAA-150) to its delegation gate. A refusal at start would stop every organization
 // instance on today's records, which pin none until every reader is pinned at or after DEC-0127.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -14,7 +14,7 @@ import path from 'node:path';
 import { INSTANCE, ServiceError } from './fabric-base.mjs';
 import { descriptorPath } from './fabric-descriptor.mjs';
 import { parseContext } from './fabric-estate.mjs';
-import { InstanceLock, holdSingleInstance } from './fabric-lock.mjs';
+import { InstanceLock, LOCK_BACKOFF_FIRST_SECONDS, LOCK_BACKOFF_MAX_SECONDS, holdSingleInstance, lockWaitBudgetSeconds, supervisorMarker } from './fabric-lock.mjs';
 import { atomicWrite, instanceDirs, servicesDir } from './fabric-paths.mjs';
 import { instanceShareGrant } from './fabric-share.mjs';
 import { clockMs } from './fabric-time.mjs';
@@ -112,9 +112,29 @@ function markerMatches(file, expected) {
   return found !== null && typeof found === 'object' && Object.entries(expected).every(([key, value]) => found[key] === value);
 }
 
+/**
+ * What delegationGate takes from this instance's context (FAA-150): `estateContext`, and for an organization whose
+ * context `record` pins, `issuer`: the pin's context issuer (DL-14a, DEC-0128), so an organization's instance refuses a
+ * token the personal hub key signed. `info` is contextInstance's (or holdContextInstance's) answer; spread it after the
+ * service's own estate issuer: `delegationGate({ ..., issuer: estateIssuer, ...contextGateOptions(info, record) })`.
+ * Throws ContextRefused (`context-invalid`) for an answer with no context.
+ */
+export function contextGateOptions(info, record) {
+  const context = info !== null && typeof info === 'object' ? info.context : undefined;
+  const parsed = parseContext(context);
+  if (!parsed) throw new ContextRefused('context-invalid');
+  const options = { estateContext: context };
+  const pins = record !== null && typeof record === 'object' && !Array.isArray(record) ? record.organizations : undefined;
+  if (parsed.kind === 'org' && Array.isArray(pins)) {
+    const pin = pins.find((p) => p !== null && typeof p === 'object' && p.org === context && typeof p.iss === 'string');
+    if (pin) options.issuer = pin.iss;
+  }
+  return options;
+}
+
 /**
  * Run as `context`'s one instance, before any side effect (brief D17): contextInstance (a refusal writes one sentence
- * naming the code and exits 78, nothing created); then holdSingleInstance on the instance's data folder (its markers,
+ * naming the code and exits 78, nothing created; a supervised copy backs off first, FAA-279); then holdSingleInstance on the instance's data folder (its markers,
  * its supervised wait, its exit 75); then `<data>/fabric-context.json`: absent, written (0600, atomic); equal, kept;
  * another context or instance, or unreadable, releases the lock and exits 78 (`context-mismatch`). Resolves to the
  * instance with its held `lock`; `exit` is injectable as holdSingleInstance has it, and its answer is returned.
@@ -123,8 +143,20 @@ export async function holdContextInstance(id, context, {
   record, machineId, agentRef, at, personalInstance = 'default', servicesDirectory, platform = process.platform,
   waitSeconds, sleep, clock, exit = (code) => process.exit(code), env, argv,
 } = {}) {
-  const refuse = (code) => {
-    process.stderr.write(`${id} will not run for ${shown(context)} (${code}): ${REASONS[code]}.\n`);
+  // FAA-279: under a supervisor that restarts on exit an exit 78 at once is a respawn every few seconds, forever; a
+  // supervised copy first waits the lock's back-off (0.5 s doubling to 30 s, 300 s in all), holding nothing.
+  const refuse = async (code) => {
+    const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
+    const wait = Math.max(0, waitSeconds ?? lockWaitBudgetSeconds(marker));
+    const tail = wait > 0 ? ` Waiting ${Math.round(wait)} s before exiting, so its supervisor does not restart it every few seconds.` : '';
+    process.stderr.write(`${id} will not run for ${shown(context)} (${code}): ${REASONS[code]}.${tail}\n`);
+    const now = clock ?? (() => performance.now() / 1000);
+    const pause = sleep ?? ((seconds) => new Promise((resolve) => { setTimeout(resolve, seconds * 1000); }));
+    const deadline = now() + wait;
+    for (let delay = LOCK_BACKOFF_FIRST_SECONDS, remaining = deadline - now(); remaining > 0; remaining = deadline - now()) {
+      await pause(Math.min(delay, remaining));
+      delay = Math.min(delay * 2, LOCK_BACKOFF_MAX_SECONDS);
+    }
     return exit(EXIT_CONTEXT_REFUSED);
   };
   let info;

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-descriptor.mjs

@@ -1,10 +1,13 @@
 // 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.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_descriptor.py. Node 20+, no dependency.
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import net from 'node:net';
 import path from 'node:path';
 import { credentialName, repositoryCredential, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { ID, INSTANCE, LOCAL_PATH, PRIMARY_CAPABILITY, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
+import { ANOTHER_ACCOUNT, SYSTEM, THIS_ACCOUNT, UNKNOWN, normHost, owner as peerOwnerOf, peer as peerOfSocket } from './fabric-peer-owner.mjs'; // L0: who listens on a port and who connected (DEC-0154 HA-2, FAA-225, FAA-227)
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
 import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
@@ -313,9 +316,119 @@ export function sourceRefusal(d, dir = servicesDir()) {
   return `Descriptor ${d?.id}.${instance} ${NO_SOURCE_REPOSITORY}. ${PASS_SOURCE}`;
 }
 
-// FAA-198: a new descriptor names its source.repository; rewriting one already installed without it only warns
-// (process.emitWarning, code FABRIC_NO_SOURCE_REPOSITORY), so an installed agent's update keeps working.
-export function writeDescriptor(d, dir = servicesDir()) {
+// The child that answers portOwner: a plain listen on 127.0.0.1:<port> that succeeds means nothing holds it (the table
+// is not read); one that fails asks fabric-peer-owner's listener. A child, because writeDescriptor is synchronous.
+const PORT_OWNER_CHILD = `
+import net from 'node:net';
+const [port, url] = process.argv.slice(1);
+const say = (value) => process.stdout.write(JSON.stringify(value));
+const server = net.createServer();
+server.once('error', async () => {
+  try { const { listener } = await import(url); const who = await listener(Number(port)); say([who.kind, Number.isInteger(who.uid) ? who.uid : null]); }
+  catch { say(['unknown', null]); }
+});
+server.listen({ port: Number(port), host: '127.0.0.1', exclusive: true }, () => server.close(() => say(null)));
+`;
+
+// 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. The twin
+// of fabric_descriptor.py's PEER_CHECKS and LoopbackHTTPServer.
+export const PEER_CHECKS = Object.freeze(['refuse', 'strict', 'off']);
+
+/** Why a server refuses the peer `owner` (a fabric-peer-owner owner) under `mode`, or null to serve it: the owner's
+ * kind, or for `unknown` its reason; never an address or anything the peer sent. */
+export function connectionRefusal(owner, mode = 'refuse') {
+  if (!PEER_CHECKS.includes(mode)) throw new ServiceError(`peerCheck must be one of ${PEER_CHECKS.join(', ')}.`);
+  if (mode === 'off' || owner === null || owner === undefined) return null;
+  const kind = owner.kind ?? UNKNOWN;
+  if (kind === ANOTHER_ACCOUNT) return kind;
+  if (mode === 'strict' && kind !== THIS_ACCOUNT) {
+    if (kind === SYSTEM && owner.uid === 0) return null;
+    return owner.reason || kind;
+  }
+  return null;
+}
+
+/** Whether a 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. The twin of fabric_descriptor.py's is_loopback_peer. */
+export function isLoopbackPeer(address) {
+  if (typeof address !== 'string') return true;
+  const host = normHost(address);
+  if (net.isIPv4(host)) return host.split('.')[0] === '127';
+  if (net.isIPv6(host)) return host === '::1';
+  return true;
+}
+
+const connectionOwners = new WeakMap();
+
+/** The owner of the peer behind an HTTP request's socket (`req.socket`) a loopbackServer served, or null. */
+export function connectionOwner(socket) {
+  return connectionOwners.get(socket) ?? null;
+}
+
+/** A net.Server to listen on in place of `httpServer` (DEC-0154 HA-2's server side, FAA-227): each connection arrives
+ * paused, its peer is told from the computer's socket table (`peer`, fabric-peer-owner's by default), and only a peer
+ * `peerCheck` serves is handed to `httpServer` (never listened on itself), which then reads the request; a refused one
+ * is destroyed unread, counted in `peerRefusals`, and reported to `onRefused(owner, reason)` (default: one line on
+ * stderr with the owner's kind, uid and pid). Handlers find their peer's owner with `connectionOwner(req.socket)`.
+ * The check applies to loopback peers only: a peer at another address (a server 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 no owner.
+ * Close the returned server to stop accepting; `httpServer.closeAllConnections()` ends the served ones. */
+export function loopbackServer(httpServer, { peerCheck = 'refuse', peer = peerOfSocket, onRefused } = {}) {
+  connectionRefusal(null, peerCheck);
+  const report = onRefused ?? ((who, reason) => process.stderr.write(
+    `fabric: refused a loopback peer (${reason}, uid ${who?.uid ?? 'None'}, pid ${who?.pid ?? 'None'}) before reading it (DEC-0154)\n`));
+  const gate = net.createServer({ pauseOnConnect: true }, async (socket) => {
+    let who = null;
+    if (peerCheck !== 'off' && isLoopbackPeer(socket.remoteAddress)) {
+      try {
+        who = await peer(socket);
+      } catch (err) {
+        who = peerOwnerOf(UNKNOWN, { reason: `reader: ${err?.name ?? 'Error'}` });
+      }
+    }
+    const reason = connectionRefusal(who, peerCheck);
+    if (reason !== null) {
+      gate.peerRefusals += 1;
+      socket.destroy();
+      report(who, reason);
+      return;
+    }
+    if (socket.destroyed) return;
+    if (who !== null) connectionOwners.set(socket, who);
+    httpServer.emit('connection', socket);
+    socket.resume();
+  });
+  gate.peerRefusals = 0;
+  return gate;
+}
+
+/** Who listens on 127.0.0.1:<port> now, as [kind, uid] from the kit's fabric-peer-owner, or null when nothing holds it
+ * (FAA-225, DEC-0154 HA-2). */
+export function portOwner(port) {
+  const done = spawnSync(process.execPath, ['--input-type=module', '-e', PORT_OWNER_CHILD, String(port),
+    new URL('./fabric-peer-owner.mjs', import.meta.url).href], { encoding: 'utf8', timeout: 10000 });
+  try { return JSON.parse(done.stdout); } catch { return ['unknown', null]; }
+}
+
+/** 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 recorded port per account and its
+ * claim file wait on contract DEC-0160. */
+export function portListenerRefusal(port, reader = portOwner) {
+  const found = reader(port);
+  if (!Array.isArray(found) || found[0] !== ANOTHER_ACCOUNT) return null;
+  const uid = Number.isInteger(found[1]) ? ` (uid ${found[1]})` : '';
+  return `Port ${port} is listened on by another OS account${uid}: choose a port no other account holds (DEC-0154, FAA-225).`;
+}
+
+/** 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; `portOwner(port) -> [kind, uid] | null` 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
+ * (process.emitWarning, code FABRIC_NO_SOURCE_REPOSITORY), so an installed agent's update keeps working. */
+export function writeDescriptor(d, dir = servicesDir(), { portOwner: reader = portOwner } = {}) {
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const me = `${d.id}.${d.instance}`;
@@ -334,6 +447,8 @@ export function writeDescriptor(d, dir = servicesDir()) {
     try { otherPort = portOf(String(other.origin ?? '')); } catch { continue; }
     if (otherPort === port) throw new ServiceError(`Port ${port} is already claimed by ${key} (${file}).`);
   }
+  const held = port === null ? null : portListenerRefusal(port, reader);
+  if (held) throw new ServiceError(held);
   ensurePrivateDir(dir);
   const target = descriptorPath(d.id, d.instance, dir);
   atomicWrite(target, `${JSON.stringify(d, null, 2)}\n`, 0o600);