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

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

@@ -361,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):

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

@@ -700,8 +700,76 @@ def compose(draft: Dict[str, Any], files: Dict[str, bytes]) -> Tuple[Dict[str, A
     return pkg, notes
 
 
+#: The agent's source manifest (contract DEC-0149, ``fabric-source/1``): when the folder carries one, ``pack`` writes
+#: ``secrets[]`` from its secret slots and ``state[]`` from its store slots' paths, and FAC-SEM-160 holds them equal.
+SOURCE_FILE = "fabric.source.json"
+
+
+def _source_manifest(files: Dict[str, bytes]) -> Optional[Dict[str, Any]]:
+    """The folder's source manifest, or None when it has none; a refusal when it is no ``fabric-source/1`` object."""
+    if SOURCE_FILE not in files:
+        return None
+    source = _load_json(files[SOURCE_FILE], SOURCE_FILE)
+    if source.get("format") != "fabric-source/1":
+        raise PackageError("%s is not a fabric-source/1 manifest (its format member)." % SOURCE_FILE)
+    return source
+
+
+def source_members(source: Dict[str, Any]) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """``secrets[]`` from the secret slots (name, purpose, optional) and ``state[]`` from the store slots (path, purpose)."""
+    secrets: List[Dict[str, Any]] = []
+    state: List[Dict[str, Any]] = []
+    for slot in _objects(source.get("slots")):
+        if slot.get("kind") == "secret" and isinstance(slot.get("name"), str):
+            secrets.append(dict({"name": slot["name"], "purpose": slot.get("purpose")}, **({"optional": True} if slot.get("optional") is True else {})))
+        elif slot.get("kind") == "store" and isinstance(slot.get("path"), str):
+            state.append({"path": slot["path"], "purpose": slot.get("purpose")})
+    return secrets, state
+
+
+def source_package_findings(source: Any, pkg: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-160 (contract ``sourcePackageFindings``): the package's secrets[] are the source's secret slots, by name
+    and optional; its state[] paths are the store slots' paths when state[] holds any entry."""
+    if not isinstance(source, dict) or not isinstance(pkg, dict):
+        return []
+    out: List[Dict[str, str]] = []
+
+    def flag(at: str, message: str) -> None:
+        out.append({"code": "FAC-SEM-160", "instancePath": at, "message": message})
+    slots = _objects(source.get("slots"))
+    secrets = {s["name"]: s.get("optional") is True for s in slots if s.get("kind") == "secret" and isinstance(s.get("name"), str)}
+    stores = list(dict.fromkeys(s["path"] for s in slots if s.get("kind") == "store" and isinstance(s.get("path"), str)))
+    packaged = [(e, i) for i, e in enumerate(pkg.get("secrets") if isinstance(pkg.get("secrets"), list) else []) if isinstance(e, dict)]
+    names = {e.get("name") for e, _ in packaged}
+    for name in secrets:
+        if name not in names:
+            flag("/package/secrets", "the source's secret slot %s is not in the package's secrets[]" % name)
+    for entry, index in packaged:
+        name = entry.get("name")
+        if not isinstance(name, str) or name not in secrets:
+            flag("/package/secrets/%d/name" % index, "secrets[%d] is no secret slot of the source" % index)
+        elif secrets[name] != (entry.get("optional") is True):
+            flag("/package/secrets/%d/optional" % index, "secrets[%d] is %soptional in the source" % (index, "" if secrets[name] else "not "))
+    state = pkg.get("state")
+    if not isinstance(state, list) or not state:
+        return out
+    paths = {e.get("path") for e in _objects(state)}
+    for path in stores:
+        if path not in paths:
+            flag("/package/state", "a store slot's path of the source is not in the package's state[]")
+    for index, entry in ((i, e) for i, e in enumerate(state) if isinstance(e, dict)):
+        if not isinstance(entry.get("path"), str) or entry["path"] not in stores:
+            flag("/package/state/%d/path" % index, "state[%d] is no store slot of the source" % index)
+    return out
+
+
 def _all_problems(pkg: Dict[str, Any], files: Dict[str, bytes]) -> List[Dict[str, str]]:
     problems = [dict(p, rule="schema") for p in schema_problems(pkg)]
+    if SOURCE_FILE in files:
+        try:
+            problems += [dict(p, rule=p["code"]) for p in source_package_findings(_source_manifest(files), pkg)]
+        except PackageError as exc:
+            problems.append({"rule": "source", "instancePath": "/files", "message": str(exc)})
     problems += [dict(p, rule="path") for p in path_problems(pkg)]
     problems += [dict(p, rule=p["code"]) for p in package_findings(pkg)]
     problems += [{"rule": "folder", "problem": p["problem"], "instancePath": p["path"], "message": FOLDER_MESSAGES.get(p["problem"], p["problem"])}
@@ -716,6 +784,24 @@ FOLDER_MESSAGES = {
 }
 
 
+def _secrets_lacking(draft: Dict[str, Any], secrets: List[Dict[str, Any]]) -> List[str]:
+    """The names a hand-written secrets[] declares that the source manifest has no secret slot for, in their order."""
+    have = {s["name"] for s in secrets}
+    declared = draft.get("secrets") if isinstance(draft.get("secrets"), list) else []
+    lacking: List[str] = []
+    for entry in declared:
+        name = entry.get("name") if isinstance(entry, dict) else None
+        if isinstance(name, str) and name not in have and name not in lacking:
+            lacking.append(name)
+    return lacking
+
+
+def _lacking_message(lacking: List[str]) -> str:
+    return ("%s declares no secret slot for %s, which %s's secrets[] names: pack writes secrets[] from the manifest's "
+            "slots and never drops a declared secret. Add each as a slot of kind secret to %s (or take it out of "
+            "secrets[]), then pack again" % (SOURCE_FILE, ", ".join(lacking), PACKAGE_FILE, SOURCE_FILE))
+
+
 def pack(folder: Any, apply: bool = False) -> Dict[str, Any]:
     """Pack ``folder`` (see the module's doc). The answer names the digest, ``agentRef`` and every problem; with
     ``apply`` and no problem, ``fabric.package.json`` is rewritten."""
@@ -725,8 +811,24 @@ def pack(folder: Any, apply: bool = False) -> Dict[str, Any]:
         raise PackageError("Write %s in the folder first: schema, kind, id, version, publisher, licence and, for an agent, "
                            "resultSignal and evals with its receipt. pack fills in agentRef, files[] and digest." % PACKAGE_FILE)
     draft = _load_json(files[PACKAGE_FILE], PACKAGE_FILE)
+    source = _source_manifest(files)
+    written: List[str] = []
+    refused: List[Dict[str, str]] = []
+    if source is not None:  # DEC-0149: secrets[] and state[] come from the source manifest's slots
+        secrets, state = source_members(source)
+        lacking = _secrets_lacking(draft, secrets)
+        if lacking:  # a declared secret is never dropped: the manifest gains its slot first
+            refused.append({"rule": "source", "instancePath": "/secrets", "message": _lacking_message(lacking)})
+        elif secrets or "secrets" in draft:
+            draft["secrets"] = secrets
+            written.append("secrets[]")
+        if state and draft.get("state") != []:  # an empty state[] is a copy packed without state, kept
+            draft["state"] = state
+            written.append("state[]")
     pkg, notes = compose(draft, files)
-    problems = _all_problems(pkg, files)
+    if written:
+        notes.append("%s written from %s" % (" and ".join(written), SOURCE_FILE))
+    problems = refused + _all_problems(pkg, files)
     suite = pkg.get("evals", {}).get("suite") if isinstance(pkg.get("evals"), dict) else None
     if isinstance(suite, str) and suite in files and any(p.get("instancePath") == "/evals/receipt/suite" for p in problems):
         notes.append("the suite packed is %s: run it again and write that receipt" % sha256_of(files[suite]))

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

@@ -1,8 +1,11 @@
 """peer_owner: which OS account owns each end of a loopback TCP connection.
 
-    peer_owner 1.1.0+kit.4: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
-    DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py` at
-    commit f86f0622 (passioncode-ai/project-observatory-dashboard, the same licence). It differs
+    peer_owner 1.2.0+kit.5: Observatory's peer_owner 1.2.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
+    DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py`, first at
+    commit f86f0622 (1.1.0) and read against commit 2180235c (1.2.0, passioncode-ai/project-observatory-dashboard, the
+    same licence): the kit's line names 1.2.0 since kit.5 (FAA-258), whose Linux rule kit.1 to kit.4 already carried
+    and the contract's CT-254 states (v0.1.0+2026-11-07.3). Observatory's 1.3.x (this account's own sockets through
+    libproc, the contract's DEC-0155 RT-2) is not in it yet (FAA-292). It differs
     from that file in this paragraph, in `Owner` and `Row` (NamedTuples here where it has
     frozen dataclasses: a dataclass with postponed annotations needs its module in sys.modules,
     and a service may load a kit file by its path without one), and in writing `Optional[X]`
@@ -11,7 +14,8 @@
     SID before the system's (a client running as root or SYSTEM owns root's listener), and in
     two Linux and selection rules: on Linux `server_end` reads an accepted connection's own row
     and, for one not accept()ed yet (printed with uid 0 and inode 0), the listener row on its
-    local address (state 0A; Observatory's 1.2.0 reading), `peer` reads a client
+    local address (state 0A; 1.2.0's rule, where the kit names its reasons `not-accepted`, `several-rows` and `closed`
+    and Observatory `no-listener`, `listener-no-socket`, `listeners-disagree` and `no-socket`), `peer` reads a client
     row with inode 0 (a closed client) as unknown, and several rows of one owner are that owner;
     a row printed twice by a `/proc` read under churn counts once, and a `/proc` question that
     finds no row or several reads the table once more; ctypes is imported where it is used, so a
@@ -111,7 +115,7 @@ import time
 from typing import NamedTuple, Optional, Tuple
 
 # This file's own version, for projects that copy it; not the engine's (that is configuration.VERSION).
-PEER_OWNER_VERSION = "1.1.0+kit.4"  # Observatory's 1.1.0 with the kit's differences above
+PEER_OWNER_VERSION = "1.2.0+kit.5"  # Observatory's 1.2.0 with the kit's differences above
 
 THIS_ACCOUNT = "this-account"
 ANOTHER_ACCOUNT = "another-account"
@@ -122,7 +126,8 @@ KINDS = (THIS_ACCOUNT, ANOTHER_ACCOUNT, SYSTEM, UNKNOWN, NONE)
 
 #: The most table bytes one read accepts. The spec of this module asked for 1 MB; measured,
 #: `pcblist_n` costs about 860 bytes a socket, so 1 MB would hold about 1,200 sockets and a busy
-#: developer machine passes that. 4 MiB holds about 4,800.
+#: developer machine passes that. 4 MiB holds about 6,800 at the 616 bytes a socket measured on macOS 26
+#: (0.74.0 product reading 11, FAA-260).
 MAX_TABLE_BYTES = 4 * 1024 * 1024
 #: Every subprocess this module starts is stopped after this many seconds.
 TIMEOUT_SECONDS = 2.0
@@ -804,7 +809,7 @@ def _owner_of(local: tuple[str, int], remote: tuple[str, int], server: bool = Fa
         # (inet_csk_listen_stop), so that listener answers. An accepted connection's own row carries the uid of the
         # process that accepted it (sock_graft): it answers itself, so a listener swapped after another account
         # accepted the client cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's
-        # pending CT-254, FAA-258).
+        # CT-254, HA-2's Linux source, released in v0.1.0+2026-11-07.3).
         # A server row its owner already closed (an orphan) also has inode 0 and reads so: no process holds it, so
         # nothing sent to it reaches anyone (0.74.0 unit reading 6).
         return _one_owner(_listeners_of(rows, found[0].local), how, "not-accepted")
@@ -856,7 +861,7 @@ def server_end(sock: socket.socket) -> Owner:
     server's and whose remote address is this socket's own, which is the server process's
     accepted socket, so a listener swapped after `listen` cannot pass for the one that answers.
     On Linux a connection not yet accept()ed has no owner of its own (inode 0): its listener
-    answers (the contract's pending CT-254, FAA-258)."""
+    answers (the contract's CT-254, HA-2's Linux source)."""
     try:
         own, server = sock.getsockname(), sock.getpeername()
     except OSError as exc:

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

@@ -20,7 +20,7 @@ PROTOCOL_REVISIONS: Dict[str, Tuple[str, ...]] = {
     "fabric-operator-channel": ("0.1",), "fabric-package": ("1",),
     "fabric-peer-share": ("1",), "fabric-peer-share-envelope": ("1",), "fabric-peer-share-report": ("1",), "fabric-project-comms": ("0.1",), "fabric-proposal": ("1",),
     "fabric-provider": ("0.1",), "fabric-relay": ("0.1",), "fabric-secret-envelope": ("1",), "fabric-service": ("0.1",),
-    "fabric-settings-backup": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "machine-report": ("1",), "mandate": ("1",), "memory": ("0.1",), "node-summary": ("1",),
+    "fabric-settings-backup": ("1",), "fabric-source": ("1",), "heartbeat": ("1",), "learning-note": ("1",), "machine-report": ("1",), "mandate": ("1",), "memory": ("0.1",), "node-summary": ("1",),
     "operator-source": ("1",), "org-adaptation": ("1",), "org-adaptation-receipt": ("1",), "org-authority": ("1",), "org-authority-draft": ("1",), "org-key-set": ("1",), "org-key-set-draft": ("1",),
     "org-membership": ("1",), "org-root-registration": ("1",), "pairing-message": ("1",),
     "peer-share-deletion": ("1",), "peer-share-frame": ("1",), "peer-share-revocation": ("1",),

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

@@ -30,8 +30,20 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
 JS_SPACE = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
 _NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
 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]%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,})" % (JS_SPACE, _NOT_LINE_END), re.IGNORECASE | re.ASCII)
+#: Where a provider key's prefix may start (DEC-0151): the start of a value, a character that is no ASCII letter or
+#: digit, or an escape (a percent-escape, single or double, a backslash escape, an octal, `\\x` with two hex digits,
+#: `\\u` with four, an ESC colour sequence, raw or escaped). A consuming group, as the contract writes it.
+_KEY_BOUNDARY = (r"(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt\"']|\\u[0-9A-Fa-f]{4}|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}"
+                 r"|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)")
+#: The provider keys' shapes, prefixes in their canonical case only (DEC-0151 item 7: `SK-` or `GHP_` is no key). An
+#: `sk-` key holds, within 256 characters, a digit and an upper-case letter with 16 or more characters, or a digit with
+#: 32 or more; the look-aheads are bounded to 255 characters and lazy, so a long run of prefixes reads in linear time.
+_PROVIDER_KEYS = (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,})")
+#: The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key after a
+#: boundary. No case-insensitive flag; digits are ASCII. A match includes its boundary character: callers test, never
+#: read the matched text or its index.
+SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + _NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
 _LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
 _BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
                             re.IGNORECASE | re.ASCII)
@@ -194,7 +206,10 @@ def secret_url(value: str) -> bool:
 _REPOSITORY_URI = re.compile(r"\A([A-Za-z][A-Za-z0-9+.-]*:(?://[^/?#]*)?)([^?#]*)(.*)\Z", re.S)
 _REPOSITORY_NAME = re.compile(r"(?:[a-z0-9._-]+|[A-Za-z._-]+)\Z")  # lower case, or letters with no digit (readings 8)
 _REPOSITORY_AUTHORITY = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
-_KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % SECRET_VALUE.pattern, re.IGNORECASE | re.ASCII)
+#: A repository name's own key shapes, boundary-free and case-sensitive (DEC-0151): SECRET_VALUE takes a consuming
+#: boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
+_REPOSITORY_KEYS = r"sk-[A-Za-z0-9_-]{16,}|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,}"
+_KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % _REPOSITORY_KEYS)
 _JWT_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))%s" % JWT_SHAPE.pattern)
 
 

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

@@ -228,6 +228,8 @@ from fabric_descriptor import (  # noqa: F401
     _NOT_LAUNCHD,
     _AUTH_HEADER,
     LoopbackHTTPServer,
+    PEER_CHECKS,
+    connection_refusal,
     descriptor_path,
     read_descriptors,
     validate_descriptor,
@@ -336,6 +338,7 @@ from fabric_supervisors import (  # noqa: F401
     _launchctl,
     _domain,
     SYSTEM_DAEMONS,
+    USER_NAME_RULE,
     launchd_domain,
     launchd_loaded,
     launchd_pid,

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

@@ -47,6 +47,8 @@ DEFAULT_EXIT_TIMEOUT = 15
 
 _LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,250}\Z")  # what launchd and the Node twin take as a label
 _USER_NAME = re.compile(r"^[a-z_][a-z0-9_.-]{0,31}\Z")  # a macOS short name, as a LaunchDaemon's UserName takes it
+#: The short-name rule in words, printed alike by both twins (FAA-286 item 13).
+USER_NAME_RULE = "a lower-case letter or _, then up to 31 lower-case letters, digits, _, . or -"
 
 #: Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278).
 SYSTEM_DAEMONS = Path("/Library/LaunchDaemons")
@@ -373,6 +375,9 @@ def launchd_domain(plist_path: Optional[Path] = None, domain: Optional[str] = No
     session; a ``gui/<uid>`` job starts only while its user is logged in."""
     if domain not in (None, "gui", "system"):
         raise ServiceError("domain must be gui or system")
+    if plist_path is not None and re.match(r"^(?:system|gui)(?:/[0-9]*)?\Z", str(plist_path)):
+        raise ServiceError("%s is a launchd domain, not a plist path: pass domain=%r (FAA-286)"
+                           % (plist_path, "system" if str(plist_path) == "system" else "gui"))
     if domain is None and plist_path is not None:
         folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))  # POSIX keeps a leading //
         domain = "system" if folder.lower() == str(SYSTEM_DAEMONS).lower() else "gui"  # APFS ignores case
@@ -384,6 +389,39 @@ def launchd_domain(plist_path: Optional[Path] = None, domain: Optional[str] = No
     return _domain()
 
 
+def _in_daemons(plist_path: Path) -> bool:
+    folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))
+    return folder.lower() == str(SYSTEM_DAEMONS).lower()
+
+
+def _pair_problem(plist_path: Path, domain: Optional[str]) -> Optional[str]:
+    """A domain the plist's folder contradicts (FAA-286 items 14 and 21): a system job in a LaunchAgents folder (launchd
+    also loads it into gui/<uid> at login), or a gui job in /Library/LaunchDaemons (launchd loads it at boot as root).
+    Another folder is allowed for a system job, as the tests' and a staging install's are."""
+    if domain == "system" and Path(os.path.abspath(str(plist_path))).parent.name.lower() == "launchagents":
+        return ("A LaunchDaemon's plist lives in %s: %s is in a LaunchAgents folder, which launchd also loads into "
+                "gui/<uid> at login, so the job would run twice." % (SYSTEM_DAEMONS, plist_path))
+    if domain == "gui" and _in_daemons(plist_path):
+        return ("%s is in %s, which launchd loads at boot as a LaunchDaemon: a gui/<uid> job's plist goes in "
+                "~/Library/LaunchAgents." % (plist_path, SYSTEM_DAEMONS))
+    return None
+
+
+def _leftover_agent(label: str, user_name: str) -> Optional[Path]:
+    """A LaunchAgent of ``label`` in ``user_name``'s ~/Library/LaunchAgents, which would run a second copy at its login
+    (FAA-286 item 6)."""
+    try:
+        import pwd
+        home = Path(pwd.getpwnam(user_name).pw_dir)
+    except (ImportError, KeyError, ValueError):
+        return None
+    try:
+        agents = sorted((home / "Library" / "LaunchAgents").glob("*.plist"))
+    except OSError:
+        return None
+    return next((p for p in agents if _plist_field(p, "Label") == label), None)
+
+
 def _need_root(domain: str, label: str, plist_path: Path, install: bool) -> None:
     """A system-domain job is installed and removed by root: refuse before anything is written (FAA-278)."""
     if domain != "system" or os.geteuid() == 0:
@@ -700,6 +738,9 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
     read_answer = fetch_well_known or (lambda origin_, vouch_pid=None: well_known_of(origin_, vouch_pid=vouch_pid))
     read_job = fetch_job_well_known or job_well_known_of
     plist_path = Path(plist_path)
+    pair = _pair_problem(plist_path, domain)
+    if pair:
+        raise ServiceError(pair)
     dom = launchd_domain(plist_path, domain)
     which = "system" if dom == "system" else None
     _need_root(dom, label, plist_path, True)
@@ -713,8 +754,8 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                "the job's pid and uid (FAA-278); %s is not." % origin)
         try:
             named = plistlib.loads(plist_bytes).get("UserName")
-        except Exception:  # a plist that does not parse fails plutil -lint below
-            named = None
+        except Exception as exc:  # named as what it is, never as a missing UserName (FAA-286 item 16)
+            raise ServiceError("The plist does not parse (%s): write it with launchd_plist." % type(exc).__name__)
         named = named if isinstance(named, str) else None  # a UserName that is not a string names no account
         if named:
             _refuse_held_label(label, plist_path)
@@ -731,7 +772,7 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                    "it), or uninstall that one as root first." % (plist_path, installed))
         if named and not _USER_NAME.match(named):
             raise ServiceError("UserName %s is not a macOS short name (%s): launchd takes the account's short name."
-                               % (named, _USER_NAME.pattern))
+                               % (named, USER_NAME_RULE))
         job_uid = _account_uid(named) if named else None
         if named and job_uid is None:
             raise ServiceError("UserName %s is no account of this Mac: launchd would not start the job. Name the account "
@@ -744,6 +785,12 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
             raise ServiceError("A LaunchDaemon needs UserName: without it the job runs as root, keeps its data in root's "
                                "home, and every client refuses root's listener (DEC-0154 HA-2). Write the plist with "
                                "launchd_plist(..., user_name=<the account whose Fabric and agents call it>).")
+        leftover = _leftover_agent(label, named)
+        if leftover is not None:
+            raise ServiceError("%s is a LaunchAgent of label %s: it would start a second copy at %s's login beside this "
+                               "LaunchDaemon. Remove it first (launchd_uninstall as %s; lifecycle reference, The system "
+                               "domain)." % (leftover, label, named, named))
+    existed = plist_path.exists()
     atomic_write(plist_path, plist_bytes, 0o644)
     lint = subprocess.run(["plutil", "-lint", str(plist_path)], capture_output=True, text=True)
     if lint.returncode != 0:
@@ -771,6 +818,16 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                "headless Mac after a FileVault restart), so %s does not run jobs: remove the LaunchAgent "
                                "this attempt wrote (launchd_uninstall), then install it as a LaunchDaemon in the system "
                                "domain (a plist in %s with UserName, as root; FAA-278)." % (last, dom, SYSTEM_DAEMONS))
+        if dom == "system":
+            # a plist left in /Library/LaunchDaemons loads at the next boot (FAA-286 item 15): one this call wrote goes
+            if not existed:
+                try:
+                    plist_path.unlink()
+                except OSError:
+                    pass
+            raise ServiceError("launchctl bootstrap failed: %s; %s" % (last, "the plist this call wrote was removed"
+                               if not plist_path.exists() else "%s stays and loads at the next boot: remove it as root"
+                               % plist_path))
         raise ServiceError("launchctl bootstrap failed: %s" % last)
     deadline = time.time() + timeout
     if dom == "system":
@@ -834,6 +891,10 @@ def launchd_uninstall(label: str, plist_path: Path, *, timeout: float = 30.0, pu
                            "remove the data as that user.")
     if dom == "system":
         _refuse_held_label(label, Path(plist_path))  # a bootout would stop another plist's job (FAA-278)
+    holds = _plist_field(Path(plist_path), "Label") if Path(plist_path).exists() else None
+    if holds is not None and holds != label:  # FAA-286 item 9: booting out one job and unlinking another's plist
+        raise ServiceError("%s holds launchd label %s, not %s: nothing was removed. Name the plist of %s, or uninstall %s "
+                           "with its own label." % (plist_path, holds, label, label, holds))
     dirs = instance_dirs(str(service_id), instance) if purge else {}
     target = "%s/%s" % (dom, label)
     _launchctl("bootout", target)