@passioncode-ai/fabric-agent-adapter 0.22.0 → 0.24.0

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

@@ -87,9 +87,14 @@ _TRACE_ID = re.compile(r"^(?!0{32}$)[0-9a-f]{32}$")
 _SPAN_ID = re.compile(r"^(?!0{16}$)[0-9a-f]{16}$")
 # DEC-0032: a local path is POSIX (`/…`, `~/…`) or Windows (`C:\…`, `C:/…`, `~\…`); a network
 # share (`\\server\…`, `\\?\…`) is never a local path.
-_LOCAL_PATH = re.compile(r"^(~[\\/]|/(?!/)|[A-Za-z]:[\\/])")
+# DEC-0057: `//server/…` and `/\\server…` are shares on Windows too, so a leading slash is followed by neither.
+_LOCAL_PATH = re.compile(r"^(~[\\/]|/(?![\\/])|[A-Za-z]:[\\/])")
 # DEC-0032: the supervisor per system and the field that names its job.
-MANAGERS = ("launchd", "systemd", "task-scheduler", "none")
+# DEC-0061: `node` (Project Observatory's node supervises its children, no supervisor file); DEC-0069: `person` (an app
+# a person installs and starts; its descriptor says it is installed, never that it runs).
+MANAGERS = ("launchd", "systemd", "task-scheduler", "node", "person", "none")
+#: Managers that write no launchd label or plist (DEC-0057, DEC-0061, DEC-0069).
+_NOT_LAUNCHD = ("systemd", "task-scheduler", "node", "person")
 _AUTH_HEADER = re.compile(r"[A-Za-z][A-Za-z0-9-]{0,63}")
 _UNIT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9:_.@-]{0,250}\.service$")
 _TASK = re.compile(r"^\\[A-Za-z0-9 ._\\-]{1,254}$")
@@ -106,7 +111,8 @@ class AlreadyRunning(ServiceError):
     def __init__(self, holder_pid: Optional[int], lock_path: Path):
         self.holder_pid = holder_pid
         self.lock_path = lock_path
-        who = "process %d" % holder_pid if holder_pid else "another process"
+        # FAC-SEM-078: a copy that cannot learn the holder's pid says the holder is unknown.
+        who = "process %d" % holder_pid if holder_pid else "an unknown process"
         super().__init__("Another copy is already running (%s holds %s)." % (who, lock_path))
 
 
@@ -336,35 +342,118 @@ def _read_pid(path: Path) -> Optional[int]:
         return None
 
 
-SUPERVISORS = ("launchd", "systemd", "task-scheduler")
+#: The managers a supervisor marker may name (DEC-0057): the three systems' supervisors and Project Observatory's node.
+SUPERVISORS = ("launchd", "systemd", "task-scheduler", "node")
+#: The argument form of the marker, for a supervisor whose start carries no environment (a Scheduled Task's action).
+SUPERVISOR_ARG = "--fabric-supervisor"
 
 
-def supervised() -> bool:
-    """True when a supervisor that restarts on exit started this process and said so in
-    ``FABRIC_SERVICE_SUPERVISOR`` (``launchd_plist`` and ``systemd_unit`` set it)."""
-    return os.environ.get(SUPERVISOR_ENV) in SUPERVISORS
-
-
-def supervised_by_launchd() -> bool:
+def _marker_arguments(argv: Sequence[Any]) -> List[str]:
+    """The marker values an argument vector carries after the executable and before ``--``. A bare
+    ``--fabric-supervisor`` followed by nothing, by ``--`` or by another ``--…`` flag is a marker with an empty value
+    and consumes nothing."""
+    values: List[str] = []
+    index = 1
+    while index < len(argv):
+        item = argv[index]
+        if item == "--":
+            break
+        if item == SUPERVISOR_ARG:
+            following = argv[index + 1] if index + 1 < len(argv) else None
+            if isinstance(following, str) and not following.startswith("--"):
+                values.append(following)
+                index += 1
+            else:
+                values.append("")
+        elif isinstance(item, str) and item.startswith(SUPERVISOR_ARG + "="):
+            values.append(item[len(SUPERVISOR_ARG) + 1:])
+        index += 1
+    return values
+
+
+def supervisor_marker(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+    """How this copy was started (DEC-0057), from ``FABRIC_SERVICE_SUPERVISOR=<manager>`` and
+    ``--fabric-supervisor <manager>`` / ``--fabric-supervisor=<manager>`` (``env`` and ``argv`` default to this process's):
+
+    - ``{"kind": "supervised", "manager", "forms"}`` — every marker present names the same manager of SUPERVISORS;
+    - ``{"kind": "conflict", "values", "forms"}`` — the markers disagree: the copy is unsupervised and exits 75 at once,
+      before it takes the lock (an empty or bare argument beside a variable disagrees with it);
+    - ``{"kind": "manual", "forms", "unreadable"?}`` — no marker (only an empty variable counts as none), or one that
+      names no manager.
+
+    A copy never infers supervision from its parent process. The contract's ``supervisorMarker``."""
+    env = os.environ if env is None else env
+    argv = sys.argv if argv is None else argv
+    variable = env.get(SUPERVISOR_ENV) if isinstance(env, dict) or hasattr(env, "get") else None
+    from_env = [variable] if isinstance(variable, str) and variable != "" else []
+    from_args = _marker_arguments(list(argv) if isinstance(argv, (list, tuple)) else [])
+    forms = (["environment"] if from_env else []) + (["argument"] if from_args else [])
+    values: List[str] = []
+    for value in from_env + from_args:
+        if value not in values:
+            values.append(value)
+    if len(values) > 1:
+        return {"kind": "conflict", "values": values, "forms": forms}
+    if not values:
+        return {"kind": "manual", "forms": forms}
+    if values[0] in SUPERVISORS:
+        return {"kind": "supervised", "manager": values[0], "forms": forms}
+    return {"kind": "manual", "unreadable": values[0], "forms": forms}
+
+
+def lock_wait_budget_seconds(marker: Dict[str, Any]) -> float:
+    """How long a copy started so may wait for the lock: 300 s when supervised, else not at all."""
+    return LOCK_WAIT_SUPERVISED_SECONDS if marker.get("kind") == "supervised" else 0.0
+
+
+def marker_conflict_message(marker: Dict[str, Any]) -> str:
+    """The one sentence a copy whose markers disagree exits with, naming the markers present."""
+    shown = ", ".join(repr(v) for v in marker["values"])
+    if marker["forms"] == ["environment", "argument"]:
+        return "%s and %s disagree (%s); not starting unsupervised." % (SUPERVISOR_ENV, SUPERVISOR_ARG, shown)
+    return "%s is given with different values (%s); not starting unsupervised." % (SUPERVISOR_ARG, shown)
+
+
+def supervised(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> bool:
+    """True when a supervisor that restarts on exit started this process and said so with the marker
+    (``launchd_plist`` and ``systemd_unit`` set the variable, ``task_xml`` writes the argument, a node sets either)."""
+    return supervisor_marker(env, argv)["kind"] == "supervised"
+
+
+def supervised_by_launchd(env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> bool:
     """True when launchd started this process from a plist written by ``launchd_plist``.
 
     The plist says so explicitly (``FABRIC_SERVICE_SUPERVISOR=launchd``); the parent process or
     ``XPC_SERVICE_NAME`` is not evidence — a terminal inside an app carries one too."""
-    return os.environ.get(SUPERVISOR_ENV) == "launchd"
+    return supervisor_marker(env, argv).get("manager") == "launchd"
+
+
+def add_supervisor_argument(parser: Any) -> Any:
+    """Let a service's own argparse parser accept the marker in both spellings, and a bare one, and ignore it
+    (DEC-0057: argparse exits 2 on an unknown flag). The kit reads the marker from ``sys.argv`` itself."""
+    import argparse
+    parser.add_argument(SUPERVISOR_ARG, nargs="?", const="", default=None, help=argparse.SUPPRESS)
+    return parser
 
 
 def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *,
                          sleep: Callable[[float], None] = time.sleep,
-                         clock: Callable[[], float] = time.monotonic) -> InstanceLock:
-    """Take the lock or exit 75 with one sentence naming the holder.
+                         clock: Callable[[], float] = time.monotonic,
+                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> InstanceLock:
+    """Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078).
 
-    Started by hand, a held lock exits 75 at once. Under launchd (KeepAlive) an immediate exit
-    is a respawn every ThrottleInterval, forever; so a supervised copy first backs off in-process
+    Markers that disagree exit 75 at once, before the lock, naming them. Started by hand (no
+    marker), a held lock exits 75 at once. Under a supervisor that restarts on exit an immediate
+    exit is a respawn every few seconds, forever; so a supervised copy first backs off in-process
     (0.5 s doubling to 30 s, ``LOCK_WAIT_SUPERVISED_SECONDS`` in all), takes over if the holder
     leaves, and exits 75 only when the wait runs out. Nothing has been touched while it waits.
-    ``wait_seconds`` overrides the choice (0 = never wait)."""
+    ``wait_seconds`` overrides the choice (0 = never wait); ``env`` and ``argv`` default to this process's."""
+    marker = supervisor_marker(env, argv)
+    if marker["kind"] == "conflict":
+        print(marker_conflict_message(marker), file=sys.stderr)
+        raise SystemExit(EXIT_ALREADY_RUNNING)
     if wait_seconds is None:
-        wait_seconds = LOCK_WAIT_SUPERVISED_SECONDS if supervised() else 0.0
+        wait_seconds = lock_wait_budget_seconds(marker)
     deadline = clock() + max(0.0, wait_seconds)
     delay = LOCK_BACKOFF_FIRST_SECONDS
     announced = False
@@ -390,19 +479,146 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
 WINDOWS_TRUSTED = ("S-1-5-18", "S-1-5-32-544")
 
 
-def token_acl_problem(path: Path, owner: str, granting: Sequence[str], user: str) -> Optional[str]:
-    """service.md "Windows token files", rules 2 and 3, on SIDs already read: the owner is the
-    current user, SYSTEM or Administrators (DEC-0033: a file an elevated administrator creates is
-    owned by Administrators), and every SID an allow ACE grants anything to is one of those three.
-    Deny ACEs are not passed in: they do not change the decision."""
-    if owner != user and owner not in WINDOWS_TRUSTED:
-        return "Token file %s is owned by %s, not by this user (%s), SYSTEM or Administrators." % (path, owner or "nobody", user)
-    for sid in granting:
-        if sid != user and sid not in WINDOWS_TRUSTED:
-            return "Token file %s grants access to %s; only this user, SYSTEM and Administrators may hold any." % (path, sid)
+def token_file_problem(path: Path, file: Dict[str, Any], user: str) -> Optional[str]:
+    """windows_token_acl_problem as one sentence naming the file and the refusal, or None."""
+    problem = windows_token_acl_problem(file, user)
+    return None if problem is None else "Token file %s refused: %s." % (path, problem["message"])
+
+
+SYSTEM_SID = "S-1-5-18"
+ADMINISTRATORS_SID = "S-1-5-32-544"
+#: A string SID: revision 1, an identifier authority and up to 15 sub-authorities of 32 bits each.
+_SID_TEXT = re.compile(r"S-1-[0-9]{1,15}(?:-[0-9]{1,10}){0,15}", re.IGNORECASE | re.ASCII)
+
+
+def _sid(value: Any) -> Optional[str]:
+    """A readable SID in upper case (SIDs compare case-insensitively on their S), or None."""
+    if not isinstance(value, str) or not _SID_TEXT.fullmatch(value):
+        return None
+    return value.upper() if all(int(part) <= 0xFFFFFFFF for part in value.split("-")[3:]) else None
+
+
+def windows_token_acl_problem(file: Any, current_user_sid: Any) -> Optional[Dict[str, Any]]:
+    """service.md "Windows token files" (DEC-0032, DEC-0033, DEC-0057, FAC-SEM-079) on what a reader has read:
+    ``file`` is ``{isRegularFile, isReparsePoint, realPathInProfile, ownerSid, aces: [{type, sid, mask}]}``, the mask
+    the ACE's unsigned 32-bit access mask. The first refusal ``{problem, at, sid?, message}``, or None when the file may
+    be read: a regular file, not a reparse point, inside the profile; owned by the user, SYSTEM or Administrators; every
+    allow ACE with a non-zero mask naming one of those three; deny ACEs ignored; any other ACE type refused; anything
+    unreadable refused. The contract's ``windowsTokenAclProblem``; a refusal names the SID, never the contents."""
+    def refuse(problem: str, at: str, message: str, sid: Optional[str] = None) -> Dict[str, Any]:
+        out = {"problem": problem, "at": at, "message": message}
+        if sid is not None:
+            out["sid"] = sid
+        return out
+    user = _sid(current_user_sid)
+    if user is None:
+        return refuse("unreadable", "/currentUserSid", "the current user's SID is unreadable")
+    if not isinstance(file, dict):
+        return refuse("unreadable", "/file", "the token file's metadata is unreadable")
+    for flag in ("isRegularFile", "isReparsePoint", "realPathInProfile"):
+        if not isinstance(file.get(flag), bool):
+            return refuse("unreadable", "/file/" + flag, flag + " is unreadable")
+    if file["isReparsePoint"]:
+        return refuse("reparse-point", "/file/isReparsePoint", "the token file is a reparse point (a symlink or a junction)")
+    if not file["isRegularFile"]:
+        return refuse("not-regular-file", "/file/isRegularFile", "the token file is not a regular file")
+    if not file["realPathInProfile"]:
+        return refuse("outside-profile", "/file/realPathInProfile", "the token file's real path lies outside the user's profile")
+    trusted = {user, SYSTEM_SID, ADMINISTRATORS_SID}
+    owner = _sid(file.get("ownerSid"))
+    if owner is None:
+        return refuse("unreadable", "/file/ownerSid", "the owner SID is unreadable")
+    if owner not in trusted:
+        return refuse("owner", "/file/ownerSid", "the token file is owned by %s, not by the current user, SYSTEM or Administrators" % owner, owner)
+    aces = file.get("aces")
+    if not isinstance(aces, list):
+        return refuse("unreadable", "/file/aces", "the ACL is unreadable")
+    for index, ace in enumerate(aces):
+        at = "/file/aces/%d" % index
+        if not isinstance(ace, dict):
+            return refuse("unreadable", at, "ACE %d is unreadable" % index)
+        if not isinstance(ace.get("type"), str):
+            return refuse("unreadable", at + "/type", "ACE %d has an unreadable type" % index)
+        trustee = _sid(ace.get("sid"))
+        if trustee is None:
+            return refuse("unreadable", at + "/sid", "ACE %d names an unreadable SID" % index)
+        mask = ace.get("mask")
+        if (not isinstance(mask, (int, float)) or isinstance(mask, bool) or (isinstance(mask, float) and not mask.is_integer())
+                or not 0 <= mask <= 0xFFFFFFFF):
+            return refuse("unreadable", at + "/mask", "ACE %d has an unreadable access mask" % index)
+        if ace["type"] == "deny":
+            continue
+        if ace["type"] != "allow":
+            return refuse("ace-type", at + "/type", "ACE %d for %s is of a type the rule does not read" % (index, trustee), trustee)
+        if mask == 0:
+            continue
+        if trustee not in trusted:
+            return refuse("ace-sid", at + "/sid", "the token file grants access to %s; only the current user, SYSTEM and Administrators may hold any" % trustee, trustee)
     return None
 
 
+#: SDDL ACE types (MS-DTYP §2.5.1.1) as the rule's ACE type: allow and deny are read, every other type is refused.
+_SDDL_ACE_TYPES = {"A": "allow", "D": "deny", "OA": "allow-object", "OD": "deny-object", "XA": "allow-callback",
+                   "XD": "deny-callback", "ZA": "allow-object-callback"}
+#: SDDL access-right aliases (MS-DTYP §2.5.1.1, "ace_rights") and their masks.
+_SDDL_RIGHTS = {"GA": 0x10000000, "GR": 0x80000000, "GW": 0x40000000, "GX": 0x20000000, "RC": 0x20000, "SD": 0x10000,
+                "WD": 0x40000, "WO": 0x80000, "RP": 0x10, "WP": 0x20, "CC": 0x1, "DC": 0x2, "LC": 0x4, "SW": 0x8,
+                "LO": 0x80, "DT": 0x40, "CR": 0x100, "FA": 0x1F01FF, "FR": 0x120089, "FW": 0x120116, "FX": 0x1200A0,
+                "KA": 0xF003F, "KR": 0x20019, "KX": 0x20019, "KW": 0x20006}
+
+
+def _sddl_ace_strings(dacl: str) -> List[str]:
+    """The top-level parenthesized ACE strings of an SDDL DACL; a callback ACE's conditional expression may nest."""
+    aces, depth, start = [], 0, 0
+    for index, char in enumerate(dacl):
+        if char == "(":
+            if depth == 0:
+                start = index + 1
+            depth += 1
+        elif char == ")" and depth:
+            depth -= 1
+            if depth == 0:
+                aces.append(dacl[start:index])
+    return aces
+
+
+def _sddl_mask(rights: str) -> Optional[int]:
+    """An SDDL rights field as the unsigned 32-bit mask, or None when it cannot be read."""
+    if re.fullmatch(r"0[xX][0-9a-fA-F]{1,8}", rights):
+        return int(rights, 16)
+    if len(rights) % 2:
+        return None
+    mask = 0
+    for i in range(0, len(rights), 2):
+        if rights[i:i + 2] not in _SDDL_RIGHTS:
+            return None
+        mask |= _SDDL_RIGHTS[rights[i:i + 2]]
+    return mask
+
+
+def acl_from_sddl(sddl: str, canonical: Callable[[str], str] = lambda sid: sid) -> Tuple[str, List[Dict[str, Any]]]:
+    """(owner SID, the ACEs that apply to the object itself as ``{type, sid, mask}``) from an SDDL owner-and-DACL
+    string. ``canonical`` turns an SDDL alias (SY, BA, WD…) into its SID. A missing or NULL DACL grants everyone
+    everything and is read as an allow ACE for Everyone (S-1-1-0); an inherit-only ACE (flag IO) applies to children
+    only and is not read; an unreadable rights field gives mask None, which the rule refuses."""
+    owner = sddl.split("O:", 1)[1].split("G:", 1)[0].split("D:", 1)[0] if "O:" in sddl else ""
+    dacl = sddl.split("D:", 1)[1] if "D:" in sddl else ""
+    owner_sid = canonical(owner) if owner else ""
+    if not dacl or dacl.startswith("NO_ACCESS_CONTROL"):
+        return owner_sid, [{"type": "allow", "sid": "S-1-1-0", "mask": 0x1F01FF}]
+    aces = []
+    for text in _sddl_ace_strings(dacl):
+        fields = text.split(";", 6)
+        if len(fields) < 6:  # unreadable: the rule refuses it
+            aces.append({"type": None, "sid": None, "mask": None})
+            continue
+        kind, flags, rights, trustee = fields[0], fields[1], fields[2], fields[5]
+        if "IO" in [flags[i:i + 2] for i in range(0, len(flags), 2)]:
+            continue
+        aces.append({"type": _SDDL_ACE_TYPES.get(kind, kind), "sid": canonical(trustee), "mask": _sddl_mask(rights)})
+    return owner_sid, aces
+
+
 if WINDOWS:  # pragma: no cover - exercised by the Windows CI job
     import ctypes
     from ctypes import wintypes
@@ -430,7 +646,6 @@ if WINDOWS:  # pragma: no cover - exercised by the Windows CI job
     _kernel32.GetCurrentProcess.restype = wintypes.HANDLE
     _kernel32.LocalFree.argtypes = [_PVOID]
     _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
-    _ACE = re.compile(r"\(([^;()]*);([^;()]*);([^;()]*);([^;()]*);([^;()]*);([^;()]*)(?:;[^()]*)?\)")
     _CANONICAL: Dict[str, str] = {}
 
     def _win_error(what: str, code: Optional[int] = None) -> OSError:
@@ -492,17 +707,9 @@ if WINDOWS:  # pragma: no cover - exercised by the Windows CI job
         finally:
             _kernel32.LocalFree(sd)
 
-    def windows_acl(path: Path) -> Tuple[str, List[str]]:
-        """(owner SID, SIDs of every allow ACE on the object itself); a missing or NULL list grants
-        everyone everything, reported as Everyone (S-1-1-0)."""
-        text = _sddl(path)
-        owner = text.split("O:", 1)[1].split("G:", 1)[0].split("D:", 1)[0] if "O:" in text else ""
-        dacl = text.split("D:", 1)[1] if "D:" in text else ""
-        if not dacl or dacl.startswith("NO_ACCESS_CONTROL"):
-            return _canonical_sid(owner) if owner else "", ["S-1-1-0"]
-        granting = [_canonical_sid(trustee) for kind, flags, _r, _o, _i, trustee in _ACE.findall(dacl)
-                    if kind in ("A", "OA", "XA", "ZA") and "IO" not in flags]
-        return (_canonical_sid(owner) if owner else ""), granting
+    def windows_acl(path: Path) -> Tuple[str, List[Dict[str, Any]]]:
+        """(owner SID, the ACEs on the object itself as ``{type, sid, mask}``), read from its SDDL (acl_from_sddl)."""
+        return acl_from_sddl(_sddl(path), _canonical_sid)
 
     def _win_protect(path: Path, folder: bool) -> None:
         """A protected list (inheritance off): this user, SYSTEM, Administrators, full control;
@@ -553,14 +760,16 @@ if WINDOWS:  # pragma: no cover - exercised by the Windows CI job
         return ctypes.get_last_error() != 2
 
     def _win_token_problem(path: Path, info: os.stat_result) -> Optional[str]:
-        if getattr(info, "st_file_attributes", 0) & _REPARSE_POINT or not stat.S_ISREG(info.st_mode):
-            return "Token file %s is not a regular file (a link or junction); refusing it." % path
         profile = os.path.normcase(os.path.realpath(os.environ.get("USERPROFILE") or str(Path.home())))
         real = os.path.normcase(os.path.realpath(str(path)))
-        if os.path.commonpath([profile, real]) != profile:
-            return "Token file %s lies outside the user's profile; refusing it." % path
-        owner, granting = windows_acl(path)
-        return token_acl_problem(path, owner, granting, windows_user_sid())
+        try:
+            inside = os.path.commonpath([profile, real]) == profile
+        except ValueError:  # another drive
+            inside = False
+        owner, aces = windows_acl(path)
+        file = {"isRegularFile": stat.S_ISREG(info.st_mode), "isReparsePoint": bool(getattr(info, "st_file_attributes", 0) & _REPARSE_POINT),
+                "realPathInProfile": inside, "ownerSid": owner, "aces": aces}
+        return token_file_problem(path, file, windows_user_sid())
 else:
     def _create_first_pipe(name: str) -> Any:  # noqa: ARG001
         raise ServiceError("named pipes exist only on Windows")
@@ -594,9 +803,9 @@ def ensure_token(path: Path) -> str:
 def read_token(path: Path) -> str:
     """Refuse a symlink, a file owned by someone else, or one others can read.
 
-    On Windows the rule is service.md "Windows token files" (DEC-0032, DEC-0033): a regular file
-    whose real path is in the profile, owned by the current user, SYSTEM or Administrators, every
-    granting ACE naming one of those three; a refusal names the SID, never the contents."""
+    On Windows the rule is service.md "Windows token files" (DEC-0032, DEC-0033, DEC-0057):
+    windows_token_acl_problem over the file's flags, owner and ACEs; a refusal names the SID,
+    never the contents."""
     path = Path(path)
     info = os.lstat(path)
     if stat.S_ISLNK(info.st_mode):
@@ -681,7 +890,10 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     remote = placement_of(descriptor) == "remote"
     if "placement" in descriptor and descriptor["placement"] not in PLACEMENTS:
         problems.append("placement must be local or remote")
-    required = ("protocol", "id", "instance", "name", "origin", "auth", "lifecycle", "installedAt", "installedBy")
+    life_in = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    app = life_in.get("manager") == "person"
+    # DEC-0069: an app's descriptor says it is installed, never that it runs; its live origin is in its own liveness file.
+    required = ("protocol", "id", "instance", "name", "auth", "lifecycle", "installedAt", "installedBy") + (() if app else ("origin",))
     if not remote:
         required = required + ("paths",)
     for key in required:
@@ -697,7 +909,7 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
         problems.append("instance must match %s" % _INSTANCE.pattern)
     if remote:
         problems.extend(remote_origin_problems(descriptor["origin"]))
-    elif not _ORIGIN.match(str(descriptor["origin"])):
+    elif "origin" in descriptor and not _ORIGIN.match(str(descriptor["origin"])):
         problems.append("origin must be http://127.0.0.1:<port>")
     auth = descriptor.get("auth") or {}
     if "tokenFile" not in auth:
@@ -719,11 +931,22 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     life = descriptor.get("lifecycle") or {}
     manager = life.get("manager")
     if manager not in MANAGERS:
-        problems.append("lifecycle.manager must be launchd, systemd, task-scheduler or none")
+        problems.append("lifecycle.manager must be launchd, systemd, task-scheduler, node, person or none")
+    # DEC-0069: `app` is the installed app of a person's descriptor, and nothing else's.
+    if manager == "person" and "app" not in life:
+        problems.append("a person's app declares lifecycle.app, the installed app")
+    if "app" in life and manager != "person":
+        problems.append("lifecycle.app belongs to manager person only")
+    if "app" in life and not _LOCAL_PATH.match(str(life["app"])):
+        problems.append("lifecycle.app must be a local path")
     if manager == "launchd" and not (life.get("label") and str(life.get("plist", "")).endswith(".plist")):
         problems.append("a launchd service declares label and plist")
     if "plist" in life and not _LOCAL_PATH.match(str(life["plist"])):
         problems.append("lifecycle.plist must be a local path")
+    # DEC-0057, DEC-0061, DEC-0069: a descriptor names one supervisor; launchd's label and plist never sit beside another.
+    for field in ("label", "plist"):
+        if field in life and manager in _NOT_LAUNCHD:
+            problems.append("lifecycle.%s belongs to launchd, not to %s" % (field, manager))
     # DEC-0032: `unit` goes with systemd and `task` with Task Scheduler, and with nothing else.
     for field, owner, pattern in (("unit", "systemd", _UNIT), ("task", "task-scheduler", _TASK)):
         if manager == owner and field not in life:
@@ -740,6 +963,7 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
                 problems.append("a remote service has no %s %s" % (of, field))
         if "update" in (descriptor.get("commands") or {}):
             problems.append("a remote service declares no update command")
+    problems.extend(descriptor_member_problems(descriptor))
     for name, argv in (descriptor.get("commands") or {}).items():
         if name not in ("doctor", "update"):
             problems.append("unknown command %s" % name)
@@ -750,6 +974,166 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     return problems
 
 
+# --- DEC-0061 and DEC-0069: who installed it, how its model calls sign in, offered to others, an app's own descriptor ---
+
+#: The organization edition's data classes, least sensitive first (DEC-0061, DEC-0053).
+PEER_DATA_CLASSES = ("public", "internal", "confidential", "restricted")
+#: The kind of a runner's sign-in, never a credential's value (DEC-0061).
+CREDENTIAL_KINDS = ("subscription", "key", "platform-metered", "none")
+#: A subscription runs only in its vendor's runner (DEC-0046): runner kind → login.
+SUBSCRIPTION_RUNNERS = {"claude-code": "claude", "kimi-code": "kimi", "codex": "chatgpt"}
+_PEER_ENDPOINT = re.compile(r"^https://(?P<host>([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63})(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?(/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*)?$", re.ASCII)
+_RESIDENCY = re.compile(r"^(A[B-Z]|[B-PR-WY][A-Z]|Q[A-L]|Z[A-Y])$", re.ASCII)
+_RUNNER_KIND_NAME = re.compile(r"^[a-z][a-z0-9-]{1,62}$", re.ASCII)
+
+
+def _pointer(name: str) -> str:
+    """A JSON Pointer token (RFC 6901 §4)."""
+    return str(name).replace("~", "~0").replace("/", "~1")
+
+
+def _text(value: Any, low: int = 1, high: int = 200) -> bool:
+    return isinstance(value, str) and low <= len(value) <= high
+
+
+def descriptor_member_problems(descriptor: Dict[str, Any]) -> List[str]:
+    """DEC-0061 and DEC-0069 on a descriptor's `installedBy`, `runner` and `peer`, as the schema shapes them, with
+    FAC-SEM-085 (a peer on a reserved name) and FAC-SEM-086 (a credential-shaped value in `runner` or `installedBy`,
+    named by its place, never its value)."""
+    import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
+    problems: List[str] = []
+    life = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    by = descriptor.get("installedBy")
+    places: List[Tuple[str, Any]] = []
+    if isinstance(by, str):
+        if not _text(by):
+            problems.append("installedBy is the installer and its version, 1 to 200 characters")
+        places.append(("/installedBy", by))
+    elif isinstance(by, dict):
+        problems += ["installedBy has no member %s" % k for k in by if k not in ("by", "role", "tool")]
+        if by.get("by") not in ("person", "node", "organization"):
+            problems.append("installedBy.by is person, node or organization")
+        if by.get("by") == "person" and by.get("role") not in ("operator", "administrator"):
+            problems.append("installedBy.role is operator or administrator for a person")
+        if by.get("by") != "person" and "role" in by:
+            problems.append("installedBy.role belongs to a person only")
+        if not _text(by.get("tool")):
+            problems.append("installedBy.tool is the installer and its version, 1 to 200 characters")
+        places += [("/installedBy/%s" % _pointer(k), v) for k, v in by.items()]
+    else:
+        problems.append("installedBy is the installer's name or {by, role?, tool}")
+    if life.get("manager") == "person" and not (isinstance(by, dict) and by.get("by") == "person"):
+        problems.append("an app's descriptor names who installed it as a person: installedBy {by: person, role, tool} (DEC-0069)")
+    runner = descriptor.get("runner")
+    if "runner" in descriptor:
+        if not isinstance(runner, dict):
+            problems.append("runner is {kind?, credentialKind}")
+            runner = {}
+        problems += ["runner has no member %s" % k for k in runner if k not in ("kind", "credentialKind")]
+        if runner.get("credentialKind") not in CREDENTIAL_KINDS:
+            problems.append("runner.credentialKind is subscription, key, platform-metered or none")
+        if "kind" in runner and not (isinstance(runner["kind"], str) and _RUNNER_KIND_NAME.match(runner["kind"])):
+            problems.append("runner.kind is a runner kind's name")
+        if runner.get("credentialKind") == "subscription" and runner.get("kind") not in SUBSCRIPTION_RUNNERS:
+            problems.append("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex")
+        places += [("/runner/%s" % _pointer(k), v) for k, v in runner.items()]
+    if "peer" in descriptor:
+        peer = descriptor.get("peer")
+        if not isinstance(peer, dict):
+            problems.append("peer is {endpoint, custody, residency, maxDataClass}")
+            peer = {}
+        problems += ["peer has no member %s" % k for k in peer if k not in ("endpoint", "custody", "residency", "maxDataClass")]
+        endpoint = peer.get("endpoint")
+        match = _PEER_ENDPOINT.match(endpoint) if isinstance(endpoint, str) and len(endpoint) <= 2048 else None
+        if not match:
+            problems.append("peer.endpoint is https://<dns-name>[:<port>][/<path>], no query, fragment, userinfo or IP literal")
+        elif _RESERVED_HOST.search(match.group("host")):
+            problems.append("FAC-SEM-085: a service offered to others cannot be reached at the reserved name %s" % match.group("host"))
+        if peer.get("custody") not in ("organization-managed", "personal"):
+            problems.append("peer.custody is organization-managed or personal")
+        residency = peer.get("residency")
+        if (not isinstance(residency, list) or not 1 <= len(residency) <= 32 or len(set(map(json.dumps, residency))) != len(residency)
+                or not all(isinstance(r, str) and _RESIDENCY.match(r) for r in residency)):
+            problems.append("peer.residency is 1 to 32 distinct ISO 3166-1 alpha-2 codes in upper case, EU admitted, no user-assigned code")
+        if peer.get("maxDataClass") not in PEER_DATA_CLASSES:
+            problems.append("peer.maxDataClass is public, internal, confidential or restricted")
+        if "runner" not in descriptor:
+            problems.append("a service offered to others declares runner (DEC-0061)")
+        elif isinstance(runner, dict) and runner.get("credentialKind") == "subscription":
+            problems.append("a service offered to others never runs on a subscription (DEC-0061)")
+    for place, value in places:
+        if isinstance(value, str) and fabric_secrets.secret_argument(value):
+            problems.append("FAC-SEM-086: %s holds a value shaped like a credential; it names a kind, a role or an installer" % place)
+    return problems
+
+
+def peer_refusal(descriptor: Any, data_class: Any) -> Optional[str]:
+    """The host's check before it routes a request from anyone but the service's operator (DEC-0061, FAC-SEM-088):
+    `not-offered` (no `peer`), `peer-invalid` (its maximum is not one of the four classes), `data-class-unknown` (the
+    request's class is not one of them, exactly as written) or `above-max-data-class`; None when it may. The contract's
+    `peerRefusal`."""
+    if not isinstance(descriptor, dict) or not isinstance(descriptor.get("peer"), dict):
+        return "not-offered"
+    ceiling = descriptor["peer"].get("maxDataClass")
+    if not isinstance(ceiling, str) or ceiling not in PEER_DATA_CLASSES:
+        return "peer-invalid"
+    if not isinstance(data_class, str) or data_class not in PEER_DATA_CLASSES:
+        return "data-class-unknown"
+    return "above-max-data-class" if PEER_DATA_CLASSES.index(data_class) > PEER_DATA_CLASSES.index(ceiling) else None
+
+
+def app_descriptor_action(existing: Any, tool: str, app_path: str) -> str:
+    """What an app that writes its own descriptor does with it on a start (DEC-0069): `keep` when it runs from a
+    translocated copy (macOS App Translocation); otherwise `write` when there is none, when it is not an app's descriptor,
+    when its version (`installedBy.tool`) or its path (`lifecycle.app`) differs; `keep` otherwise. The contract's
+    `appDescriptorAction`."""
+    if "/AppTranslocation/" in app_path:
+        return "keep"
+    if not isinstance(existing, dict) or not isinstance(existing.get("installedBy"), dict):
+        return "write"
+    recorded = existing["lifecycle"].get("app", _MISSING_APP) if isinstance(existing.get("lifecycle"), dict) else _MISSING_APP
+    return "keep" if existing["installedBy"].get("tool", _MISSING_APP) == tool and recorded == app_path else "write"
+
+
+_MISSING_APP = object()
+
+
+def app_descriptor_stale(descriptor: Any, app_present: bool) -> bool:
+    """Whether a reader treats a descriptor as stale (DEC-0069): an app's descriptor whose installed app it did not find.
+    A supervised service's descriptor is never stale by this test. The contract's `appDescriptorStale`."""
+    life = descriptor.get("lifecycle") if isinstance(descriptor, dict) else None
+    return isinstance(life, dict) and life.get("manager") == "person" and not app_present
+
+
+def app_present(descriptor: Dict[str, Any]) -> bool:
+    """Whether `lifecycle.app` of an app's descriptor exists on this machine (a bundle is a folder, an executable a file)."""
+    life = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    app = life.get("app")
+    try:
+        return isinstance(app, str) and expand(app).exists()
+    except ServiceError:  # not a local path: nothing installed there
+        return False
+
+
+#: Fabric's own descriptor (Fabric ADR-0139): `services/fabric.default.json`.
+FABRIC_SERVICE = ("fabric", "default")
+
+
+def fabric_button_presence(directory: Optional[Path] = None) -> str:
+    """`present` or `absent` for Fabric's button (DEC-0040 FB-5, DEC-0069, Fabric SCN-142): present when Fabric's own
+    descriptor is registered and, for an app's descriptor, its app is still installed. A server sets
+    `data-fabric="absent"` on the button's script otherwise. The button only follows a link, so the liveness file is
+    not read here; a caller that sends anything reads it."""
+    path = descriptor_path(*FABRIC_SERVICE, directory=directory)
+    try:
+        found = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return "absent"
+    if not isinstance(found, dict) or validate_descriptor(found):
+        return "absent"
+    return "absent" if app_descriptor_stale(found, app_present(found)) else "present"
+
+
 def placement_of(descriptor: Dict[str, Any]) -> str:
     """DEC-0019: ``local`` unless the descriptor says ``remote``."""
     return "remote" if (descriptor or {}).get("placement") == "remote" else "local"
@@ -781,11 +1165,11 @@ def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = Non
         raise ServiceError("Descriptor is invalid: %s." % "; ".join(problems))
     root = directory or services_dir()
     me = "%s.%s" % (descriptor["id"], descriptor["instance"])
-    # DEC-0019: only a local placement claims a port on this computer.
-    port = None if placement_of(descriptor) == "remote" else port_of(descriptor["origin"])
+    # DEC-0019: only a local placement claims a port on this computer; DEC-0069: an app's descriptor names none.
+    port = None if placement_of(descriptor) == "remote" or "origin" not in descriptor else port_of(descriptor["origin"])
     for path, other in read_descriptors(root):
         key = "%s.%s" % (other.get("id"), other.get("instance", "default"))
-        if key == me or port is None:  # a remote origin's port is another computer's
+        if key == me or port is None:  # a remote origin's port is another computer's; an app claims none
             continue
         try:
             other_port = port_of(str(other.get("origin", "")))
@@ -887,6 +1271,8 @@ _PROFILE_ID = re.compile(r"^[a-z][a-z0-9-]{0,62}$")
 _RUNNER_KIND = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
 _MODEL_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}/[a-z0-9][a-z0-9._:-]{0,127}$")
 ROUTES = ("subscription", "key")
+#: A usage row's route (DEC-0046, DEC-0061): beside a configuration's two, the hosting platform's own metered models.
+USAGE_ROUTES = ROUTES + ("platform-metered",)
 
 
 def configuration_problems(doc: Any) -> List[str]:
@@ -1080,12 +1466,12 @@ def make_usage_receipt(provider: str, model: str, *, input_tokens: int, output_t
     basis = cost_basis or ("unknown" if cost_usd is None else "provider")
     if basis not in COST_BASES or (cost_usd is None) != (basis == "unknown"):
         raise ServiceError("cost_basis is provider or price-list with a cost, unknown without one.")
-    if route is not None and route not in ROUTES:
-        raise ServiceError("route is subscription or key (DEC-0046).")
+    if route is not None and route not in USAGE_ROUTES:
+        raise ServiceError("route is subscription, key or platform-metered (DEC-0046, DEC-0061).")
     receipt = {"at": at or now_iso(), "provider": provider, "model": model, **counts,
                "costUsd": None if cost_usd is None else float(cost_usd), "costBasis": basis}
     if route is not None:
-        receipt["route"] = route  # the operator's own login in its vendor's runner, or an issued key
+        receipt["route"] = route  # the operator's own login in its vendor's runner, an issued key, or the platform's metered models
     return receipt
 
 
@@ -2137,18 +2523,30 @@ def remote_token_file(service_id: str, instance: str = "default", directory: Opt
 
 def register_remote(*, service_id: str, name: str, origin: str, token: str, instance: str = "default",
                     summary: Optional[str] = None, doctor: Optional[List[str]] = None,
-                    directory: Optional[Path] = None, installed_by: str = "fabric-service register-remote") -> Path:
+                    directory: Optional[Path] = None, installed_by: Any = None,
+                    runner: Optional[Dict[str, str]] = None, peer: Optional[Dict[str, Any]] = None) -> Path:
     """DEC-0019, installer side: register an online service on THIS computer — the token file
-    (0600, never printed) and the descriptor. The same token is set on the platform as a secret."""
+    (0600, never printed) and the descriptor. The same token is set on the platform as a secret.
+
+    DEC-0061: ``installed_by`` defaults to ``{"by": "person", "role": "operator", "tool": "fabric-service
+    register-remote"}`` (a person runs this); pass ``role: "administrator"`` for an organization's administrator, or a
+    string as before. ``runner`` (``{kind?, credentialKind}``) says how its model calls sign in, as a kind and never a
+    credential; ``peer`` (``{endpoint, custody, residency, maxDataClass}``) offers it to others and needs ``runner``."""
     if not token or len(token.strip()) < 16:
         raise ServiceError("the service token must be at least 16 characters.")
     root = directory or services_dir()
     token_file = remote_token_file(service_id, instance, root)
     descriptor: Dict[str, Any] = {"protocol": PROTOCOL, "id": service_id, "instance": instance, "name": name,
                                   "placement": "remote", "origin": origin, "auth": {"tokenFile": str(token_file)},
-                                  "lifecycle": {"manager": "none"}, "installedAt": now_iso(), "installedBy": installed_by}
+                                  "lifecycle": {"manager": "none"}, "installedAt": now_iso(),
+                                  "installedBy": installed_by if installed_by is not None else
+                                  {"by": "person", "role": "operator", "tool": "fabric-service register-remote"}}
     if summary:
         descriptor["summary"] = summary
+    if runner is not None:
+        descriptor["runner"] = dict(runner)
+    if peer is not None:
+        descriptor["peer"] = dict(peer)
     if doctor:
         descriptor["commands"] = {"doctor": list(doctor)}
     problems = validate_descriptor(descriptor)
@@ -2171,6 +2569,12 @@ def cookie_value(cookie_header: Optional[str], name: str = SESSION_COOKIE) -> Op
 
 # --- systemd and Task Scheduler (DEC-0032, service.md "Supervisor") ------------------
 
+def _no_marker_argument(argv: Sequence[str]) -> None:
+    """The supervisor file's writer writes the marker itself; one already in the arguments could only disagree with it."""
+    if _marker_arguments(list(argv)):
+        raise ServiceError("%s is written by the supervisor file's writer; leave it out of the program arguments" % SUPERVISOR_ARG)
+
+
 def _no_secret_in_supervisor_file(argv: Sequence[str], environment: Optional[Dict[str, str]]) -> None:
     """No supervisor file carries a secret (service.md): not in an argument, an environment name or its value."""
     import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
@@ -2209,7 +2613,8 @@ def systemd_unit(unit: str, program_arguments: Sequence[str], *, working_directo
         raise ServiceError("TimeoutStopSec must outlast the %d s drain" % DRAIN_SECONDS)
     env = dict(environment or {})
     _no_secret_in_supervisor_file(argv, env)
-    env.setdefault(SUPERVISOR_ENV, "systemd")
+    _no_marker_argument(argv)
+    env[SUPERVISOR_ENV] = "systemd"  # the unit's writer writes the marker, whatever the caller passed
     # A unit is a Linux file: a Path built anywhere (a test on Windows, an installer's planner) names a POSIX path.
     cwd = _plain(working_directory.as_posix() if isinstance(working_directory, PurePath) else str(working_directory),
                  "the working directory")
@@ -2291,6 +2696,10 @@ def task_xml(task: str, program_arguments: Sequence[str], *, working_directory:
                                                            (description or task, "the description")]:
         _plain(value, what)
     _no_secret_in_supervisor_file(argv, None)
+    _no_marker_argument(argv)
+    # A task's Exec action carries no environment, so the marker is an argument (DEC-0057), before any `--`.
+    cut = argv.index("--") if "--" in argv else len(argv)
+    argv = argv[:cut] + [SUPERVISOR_ARG, "task-scheduler"] + argv[cut:]
     who = user or ("%s\\%s" % (os.environ.get("USERDOMAIN", ""), os.environ["USERNAME"]) if os.environ.get("USERNAME") else "")
     if not who:
         raise ServiceError("name the user the task runs as (DOMAIN\\user); USERNAME is not set")
@@ -2363,6 +2772,7 @@ def launchd_plist(label: str, program_arguments: Sequence[str], *, working_direc
         if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)$", key) and not key.endswith("_FILE"):
             raise ServiceError("Environment variable %s looks like a secret; pass a *_FILE path instead." % key)
     env.setdefault("PATH", "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin")
+    _no_marker_argument([str(a) for a in program_arguments])
     env[SUPERVISOR_ENV] = "launchd"
     plist = {
         "Label": label,