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

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1: wire reference
 
-Pinned to `fabric-agent-contract` commit `18f8d48762edc5bfb1433657cbfe1c16196df1a6`
+Pinned to `fabric-agent-contract` commit `93e7db164c7829e2783b4b7705c4113bb5201131`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;
@@ -224,7 +224,8 @@ well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at
 The kit's module is `fabric_peer_owner` / `fabric-peer-owner.mjs` (layer L0, [kit modules](kit-modules.md)): `listener(port)`,
 `server_end(sock)` / `serverEnd(socket)`, `peer`, and a connection checked before a byte is written
 (`CheckedHTTPConnection`; Node `checkedSocket`, `CheckedAgent`). Python reads macOS through `sysctl
-net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`), Linux through `/proc/net/tcp`
+net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`; the pinned HA-2 table names
+`netstat -anv` and `pcblist64`, an older record layout of the same kernel table), Linux through `/proc/net/tcp`
 and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's token SID; Node reads `netstat -anv` and `ps`
 on macOS, the same `/proc` files on Linux, and `netstat -ano` with the owner SID from PowerShell `GetOwnerSid` against `whoami /user` on Windows (SIDs, never names). Fail closed: everything but
 `this-account` refuses, `unknown` included.
@@ -238,7 +239,8 @@ listener of this account's pid on the port counts as this account's (`CheckedHTT
 refuses (the probe, the hub client and `fabric_http` included, FAA-272), and Apple's `/usr/bin/python3` sees the
 whole table (FAA-267). A vouch is a weaker proof than the table's: it shows the job's pid listens on the port (`127.0.0.1` or the
 IPv4 wildcard for a LaunchAgent's installer, exactly `127.0.0.1` for a LaunchDaemon's), not that it accepted this connection, so a more specific bind by root over a wildcard job would pass;
-the contract's ruling on vouching is CT-261.
+the pin's ruling on vouching is DEC-0155 RT-3 (the contract's CT-261), which vouches only for a listen on exactly
+`127.0.0.1`: the kit's IPv4 wildcard vouch for a LaunchAgent departs from it until a later release (filed by FAA-258).
 
 Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
 a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`, its
@@ -248,8 +250,23 @@ a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub cl
 is never a successful install, except a LaunchDaemon's job as its root installer proves it; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
 session reports a door another account holds as `board.down` with reason `unreachable` until FAA-252. On macOS the Node
 twin reads the pid from `netstat` and the uid from `ps` a few milliseconds apart, so a pid reused in between would be
-misread; the Python twin's `sysctl` reader takes both from one record. A service's own loopback server refusing another account's peer (HA-3) is FAA-227, and the port
-claim file (HA-1) waits on the contract's CT-228.
+misread; the Python twin's `sysctl` reader takes both from one record. The server side (HA-2, HA-3; FAA-227): the kit's `LoopbackHTTPServer` and Node's `loopbackServer(httpServer)` tell
+each accepted connection's peer (`peer`) before a byte of the request is read, in the connection's own thread or
+while the socket is still paused. `peer_check` / `peerCheck` (`PEER_CHECKS`): `refuse`, the default, closes a peer of
+another OS account unread and serves the rest; `strict` also refuses an owner nobody can tell (a restricted table
+included) and a system account other than root (uid 0, which can read every account's files anyway and installs a
+LaunchDaemon; a Windows service account is refused); `off` reads no table. The check applies to loopback peers
+(127.0.0.0/8, `::1`, either IPv4-mapped): HA-2 is about another account of this computer, so a peer at any other
+address (a service bound to `0.0.0.0`) is served under `refuse` and `strict` alike without a table read, and its
+owner is none (`peer_owner()` None, `connectionOwner` null); such a peer is never T0 or T1. Use `strict` for a dashboard, an MCP
+surface or a token-free door on a computer with several counted accounts, where the interpreter sees the whole
+table (Apple's `/usr/bin/python3`, not an ad-hoc-signed one on macOS 27.2). A refusal writes one line on stderr
+(kind, uid, pid, never the peer's bytes); a handler finds its peer's owner with `self.server.peer_owner()` or
+`connectionOwner(req.socket)`. The cost is one table read per connection, not per request: a few milliseconds from
+`sysctl` or `/proc` in-process; Node on macOS and Windows runs `netstat` and `ps` or PowerShell for each, tens to
+hundreds of milliseconds, so a Node service there that answers the well-known read within 100 ms keeps its
+connections alive or chooses `off` where one account uses the computer. The port claim file (HA-1) waits on the
+contract's CT-228.
 
 ## Semantic rules a host applies
 

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

@@ -127,6 +127,25 @@ async function serviceTarget(spec, dir) {
   return { url, declared, name: `${id}.${instance}` };
 }
 
+// DEC-0154 PL-3 and HA-2 (FAA-260 items 2 and 14): a raw loopback address opens in the browser only while its port's
+// listener is this OS account's, read from the socket table just before the page opens. The browser connects on its
+// own, so this is the listener's owner, not that connection's: a listener swapped in between stays a residue
+// (SECURITY.md). A copy of this file alone cannot tell the owner and opens no loopback page.
+async function loopbackRefusal(target) {
+  let url;
+  try { url = new URL(target); } catch { return null; }
+  if (url.protocol !== 'http:') return null;
+  const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!(host === 'localhost' || host.endsWith('.localhost') || /^127\./.test(host) || host === '::1'
+    || host === '0.0.0.0' || /^::ffff:(127\.|7f)/.test(host))) return null;
+  const po = await import('./fabric-peer-owner.mjs').catch(() => null);
+  if (!po) return 'fabric-peer-owner.mjs is not beside this file: the loopback listener\'s owner cannot be told, so the page is not opened (DEC-0154 HA-2)';
+  const port = Number(url.port || 80);
+  const who = await po.listener(port);
+  if (who.kind === po.THIS_ACCOUNT) return null;
+  return `foreign-user: the listener on port ${port} reads as ${who.kind}${who.reason ? ` (${who.reason})` : ''}, so the page is not opened (DEC-0154 PL-3, HA-2)`;
+}
+
 // Runs inside the page. Everything it reports is measured from the rendered layout.
 function measure([floor, cap]) {
   const de = document.documentElement;
@@ -319,6 +338,8 @@ async function main(argv) {
   try {
     const context = await browser.newContext({ viewport: { width: Math.max(...opts.widths), height: opts.height } });
     const page = await context.newPage();
+    const refused = await loopbackRefusal(target);
+    if (refused) return notRun(refused);
     const response = await page.goto(target, { waitUntil: 'load' });
     if (response && !response.ok()) {
       return notRun(`the page answered HTTP ${response.status()}`);

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

@@ -28,8 +28,14 @@ CREDENTIAL_PAIRS = {
     'session': {'token', 'id'},
     'code': {'login', 'auth', 'access', 'session'}}
 JWT_SHAPE = re.compile(r'eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*')
-SECRET_VALUE = re.compile(r'(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}'
-                          r'|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})', re.I | re.S)
+# The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key with its
+# prefix in its canonical case after a boundary (the start, a character that is no ASCII letter or digit, or an escape);
+# an `sk-` key holds a digit and an upper-case letter with 16 or more characters, or a digit with 32 or more.
+SECRET_VALUE = re.compile(r'(^[Bb][Ee][Aa][Rr][Ee][Rr]\s.+|(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt"\']|\\u[0-9A-Fa-f]{4}'
+                          r'|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m'
+                          r'|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)'
+                          r'(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})'
+                          r'|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}))', re.S)
 LONG_RUN = re.compile(r'[A-Za-z0-9+/=_-]{40,}')
 
 
@@ -115,6 +121,11 @@ def check(data):
     require(all(isinstance(v, str) and 0 < len(v) <= 200 for v in (target, viewer)), 'missing_device')
     fallback = data.get('fallback', 'if_absent')
     require(fallback in ('if_absent', 'never'), 'invalid_fallback')
+    # DEC-0154 PL-3 and HA-2 (FAA-251): who listens on http_url's port, as the host read it from the socket table
+    # (fabric_peer_owner's kinds, or check_service.py's foreign-user). A browser opens a raw loopback address only
+    # after that listener is this OS account's; absent, it is unknown.
+    owner = data.get('listener_owner', 'unknown')
+    require(owner in ('this-account', 'another-account', 'system', 'unknown', 'none', 'foreign-user'), 'invalid_listener_owner')
     kind = action.get('kind')
     if kind == 'remote_open':
         require(set(action) <= {'kind', 'device_id', 'service', 'path'}, 'unexpected_action_field')
@@ -128,6 +139,7 @@ def check(data):
         require(set(action) == {'kind', 'url'} and action.get('url') == http, 'not_resolved_http_url')
         require(viewer == target, 'wrong_viewer_device')
         require(state == 'not_installed' and fallback == 'if_absent', 'browser_fallback_forbidden')
+        require(owner == 'this-account', 'listener_not_this_account')
     else:
         raise ValueError('unsupported_dashboard_action')
     return {'ok': True, 'kind': kind}

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
@@ -823,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",
@@ -843,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",
@@ -947,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

@@ -457,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

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

@@ -22,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
 
 
@@ -47,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:
@@ -60,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 `//`
@@ -91,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:
@@ -729,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-descriptor.mjs

@@ -2,11 +2,12 @@
 // 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 } from './fabric-peer-owner.mjs'; // L0: who listens on a port (DEC-0154 HA-2, FAA-225)
+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';
@@ -329,6 +330,82 @@ server.once('error', async () => {
 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) {