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

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

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

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

@@ -73,8 +73,9 @@ class HttpError(Exception):
         self.retry_after_s = retry_after_s
         self.body = bytes(body[:2048])
         self.kind = kind  # http (an answer), connection, timeout, too-large, refused, foreign-user
-        #: For foreign-user, why (FAA-272): `table-restricted` (this process sees no other process's sockets, which
-        #: never clears), the owner's kind (`another-account`, `system`) or the check's reason (`no-row`).
+        #: For foreign-user, why (FAA-272): `table-restricted` (this process sees no other process's sockets, or on
+        #: macOS no row for this connection, DEC-0155 RT-1; it never clears), the owner's kind (`another-account`,
+        #: `system`) or the check's reason (`no-row`, from Linux and Windows only).
         self.reason = reason
 
 
@@ -361,13 +362,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_hub.py

@@ -70,8 +70,9 @@ class HubError(Exception):
 def listener_refusal(exc: Any) -> HubError:
     """The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned
     contract's state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted`
-    when this process's socket table hides other processes' sockets, which never clears, so it is not retryable;
-    otherwise the owner's kind or the check's reason (`another-account`, `no-row`), retryable as before."""
+    when this process's socket table hides other processes' sockets, or, on macOS, holds no row for this connection
+    (DEC-0155 RT-1, FAA-312), which never clears, so it is not retryable; otherwise the owner's kind or the check's
+    reason (`another-account`, or `no-row`, which only Linux and Windows give), retryable."""
     owner = getattr(exc, "owner", None)
     why = (getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", None) or "unknown")
     reason = _po.TABLE_RESTRICTED if str(why).startswith(_po.TABLE_RESTRICTED) else str(why).split(":", 1)[0]
@@ -94,25 +95,37 @@ def fabric_root(platform: str = sys.platform, env: Optional[Dict[str, str]] = No
     return Path(env.get("XDG_DATA_HOME") or str(home / ".local/share")) / "passioncode-fabric"
 
 
-def pid_alive(pid: int) -> bool:
-    """Whether a process with this id runs as this user (Fabric `hub.ts#pidAlive`); never signals it."""
+def _windows_pid_alive(pid: int, kernel: Any = None, last_error: Any = None) -> Optional[bool]:
+    """pid_alive on Windows, where os.kill(pid, 0) would send CTRL_C_EVENT: OpenProcess with query access only. Refused
+    with ERROR_ACCESS_DENIED (5), another account's or an elevated process: None, as Node's process.kill(pid, 0)
+    answers EPERM there (FAA-304); refused otherwise, no process. `kernel` and `last_error` stand in for kernel32 and
+    ctypes.get_last_error in a test."""
+    import ctypes
+    if kernel is None:
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+        last_error = ctypes.get_last_error  # type: ignore[attr-defined]
+    handle = kernel.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
+    if not handle:
+        return None if last_error() == 5 else False  # ERROR_ACCESS_DENIED: not verified, never called running
+    try:
+        code = ctypes.c_ulong()
+        return bool(kernel.GetExitCodeProcess(handle, ctypes.byref(code))) and code.value == 259  # STILL_ACTIVE
+    finally:
+        kernel.CloseHandle(handle)
+
+
+def pid_alive(pid: int) -> Optional[bool]:
+    """True: a process of this OS account runs under `pid`; False: none does. None (falsy): a process of another account
+    does (EPERM; on Windows, OpenProcess refused with access denied), as when the id hub.json names was reused: not
+    verified, never called running (FAA-304, the session hooks' answer since FAA-254). Never signals it."""
     if pid <= 0:
         return False
     if sys.platform == "win32":
-        import ctypes
-        kernel = ctypes.windll.kernel32  # type: ignore[attr-defined]
-        handle = kernel.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
-        if not handle:
-            return False
-        try:
-            code = ctypes.c_ulong()
-            return bool(kernel.GetExitCodeProcess(handle, ctypes.byref(code))) and code.value == 259  # STILL_ACTIVE
-        finally:
-            kernel.CloseHandle(handle)
+        return _windows_pid_alive(pid)
     try:
         os.kill(pid, 0)
     except PermissionError:
-        return False  # another user's process under a reused id: not this user's Fabric
+        return None  # another account's process under a reused id: not verified, and not this account's Fabric
     except OSError:
         return False
     return True
@@ -142,7 +155,8 @@ def _read_small(path: Path) -> Optional[str]:
 def locate_hub(root: Optional[Path] = None, alive: Callable[[int], bool] = pid_alive, estate: Optional[Dict[str, Any]] = None,
                now: Optional[float] = None) -> Dict[str, Any]:
     """`hub.json` read the way an agent must, every call. Answers `{origin, mcpUrl, doorTokenFile, pid, startedAt,
-    features}` or raises `HubError` (`not-running`, retryable; `not-a-hub`). Reads no token. `estate` is
+    features}` or raises `HubError` (`not-running`, retryable; `not-a-hub`, retryable when hub.json names a process of
+    another OS account, which is not verified, FAA-304). Reads no token. `estate` is
     `{"record": <estate record>, "applied": {"revision", "digest"?} | None}`: with it, a `hubKey` the document names is
     checked by `hub_key_certified` (DEC-0060); fabric-hub/0.1 names none, and then nothing is checked."""
     root = Path(root) if root is not None else fabric_root()
@@ -174,7 +188,11 @@ def locate_hub(root: Optional[Path] = None, alive: Callable[[int], bool] = pid_a
     token_file = doc.get("doorTokenFile") if isinstance(doc.get("doorTokenFile"), str) else ""
     if not os.path.isabs(token_file) or os.path.realpath(os.path.dirname(token_file)) != os.path.realpath(str(root)):
         raise not_hub("names a door token outside the registry root")
-    if not alive(pid):
+    live = alive(pid)
+    if live is None:  # FAA-304: another account's process under that id, so not this account's Fabric (as FAA-254)
+        raise HubError("not-a-hub", "Fabric's hub.json names process %d, which runs under another OS account: not "
+                       "verified." % pid, True)
+    if not live:
         raise HubError("not-running", "Fabric is not running: hub.json names process %d, which is not running." % pid, True)
     features = doc.get("features")
     features = [f for f in features if isinstance(f, str)] if isinstance(features, list) else []

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

@@ -1,5 +1,15 @@
 """One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock, the supervisor marker
-in both its forms, and the wait budget under a supervisor. Part of the service kit (FAA-65, layer L3)."""
+in both its forms, and the wait budget under a supervisor. Part of the service kit (FAA-65, layer L3).
+
+A lock that moves under its holder (FAA-303). Linux and Windows hold a name keyed by the lock's path beside the file
+lock (an abstract unix socket, a named pipe), so a folder swapped under a running copy cannot let a second copy in.
+macOS has no such name: flock (and the Node twin's O_EXLOCK) lock an inode, so after a data import swaps the data
+folder a second copy locks the new file and starts. There the holder watches its lock instead
+(``InstanceLock.watch``, started by ``hold_single_instance``): every ``LOCK_WATCH_SECONDS`` it compares the inode it
+locked with the file at the path, and once the path names another file it stops with 75 and one sentence naming the
+path, before writing anything more into a folder that is no longer the one it read. Two copies then overlap for at
+most one interval. A path-keyed name on macOS was weighed and left: it needs a file in a folder outside the data folder
+that the system never cleans and every copy can write, which the standard library cannot promise."""
 from __future__ import annotations
 
 import errno
@@ -10,6 +20,7 @@ import posixpath
 import re
 import socket
 import sys
+import threading
 import time
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Sequence
@@ -46,6 +57,11 @@ LOCK_BACKOFF_FIRST_SECONDS = 0.5
 LOCK_BACKOFF_MAX_SECONDS = 30.0
 
 
+#: How often a holder that has no path-keyed name (macOS) compares the inode it locked with the file at the lock's
+#: path (FAA-303): one stat and one fstat; two copies overlap for at most this long after a folder swap.
+LOCK_WATCH_SECONDS = 2.0
+
+
 class AlreadyRunning(ServiceError):
     def __init__(self, holder_pid: Optional[int], lock_path: Path):
         self.holder_pid = holder_pid
@@ -67,6 +83,7 @@ class InstanceLock:
         self.path = Path(data_dir) / "service.lock"
         self._fd: Optional[int] = None
         self._name: Any = None
+        self._watch: Optional[threading.Event] = None
 
     #: Windows locks a byte range, not the file: one byte far past the pid the file holds, so the
     #: holder may rewrite the pid and another process may still read it (locking past the end of
@@ -157,7 +174,41 @@ class InstanceLock:
         self._fd = fd
         return True
 
+    def watch(self, on_lost: Optional[Callable[["InstanceLock"], None]] = None,
+              interval: float = LOCK_WATCH_SECONDS) -> "InstanceLock":
+        """Re-check, every ``interval`` seconds on a daemon thread, that the file this copy locked is still the file at
+        the path (FAA-303); the first time the path names another file (a swapped folder's lock, or the one a second
+        copy made), call ``on_lost(lock)`` once and stop watching. The default stops the process with 75 and one
+        sentence (``stop_lost_holder``): it runs on the watch thread, so it cannot raise into the service. A path that
+        is gone or cannot be read now is read as nothing there yet and tried again next time: a second copy has to make
+        a file there to start, and the watch then sees that file. ``release`` ends the watch. Windows does not rename a
+        folder holding an open file: there it is a no-op, as for a lock not held."""
+        if WINDOWS or self._fd is None or self._watch is not None:
+            return self
+        fd, stop, react = self._fd, threading.Event(), on_lost or stop_lost_holder
+
+        def run() -> None:
+            while not stop.wait(interval):
+                try:
+                    here, held = os.stat(str(self.path)), os.fstat(fd)
+                except OSError:
+                    continue
+                # release() sets the event before it closes the descriptor, so a number reused after the close is never
+                # read as this lock's file: the event is checked after the stat.
+                if (here.st_dev, here.st_ino) == (held.st_dev, held.st_ino) or stop.is_set():
+                    continue
+                stop.set()
+                react(self)
+                return
+
+        self._watch = stop
+        threading.Thread(target=run, name="fabric-lock-watch", daemon=True).start()
+        return self
+
     def release(self) -> None:
+        if self._watch is not None:
+            self._watch.set()
+            self._watch = None
         if self._fd is not None:
             os.close(self._fd)
             self._fd = None
@@ -166,6 +217,22 @@ class InstanceLock:
             self._name = None
 
 
+def lost_lock_message(lock_path: Path) -> str:
+    """The one sentence a holder whose lock moved under it stops with (FAA-303)."""
+    return ("%s is no longer the file this copy locked (the data folder moved or was swapped?): stopping, so a copy "
+            "started on the folder now at that path runs alone." % lock_path)
+
+
+def stop_lost_holder(lock: InstanceLock) -> None:
+    """``InstanceLock.watch``'s default: print ``lost_lock_message`` and end the process with 75 at once. ``os._exit``,
+    not a graceful stop: a shutdown would write this copy's state into the folder now at the path, which is not the
+    one it read; the kit's journals make an abrupt stop recoverable (LC-03)."""
+    try:
+        print(lost_lock_message(lock.path), file=sys.stderr, flush=True)
+    finally:
+        os._exit(EXIT_ALREADY_RUNNING)
+
+
 def lock_name(lock_path: Path, platform: str = sys.platform) -> Optional[str]:
     """The name the Node kit holds for this lock file; None where it holds none (macOS: O_EXLOCK)."""
     if platform.startswith("linux"):
@@ -329,7 +396,8 @@ def add_supervisor_argument(parser: Any) -> Any:
 def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *,
                          sleep: Callable[[float], None] = time.sleep,
                          clock: Callable[[], float] = time.monotonic,
-                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> InstanceLock:
+                         env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None,
+                         on_lost: Optional[Callable[[InstanceLock], None]] = None) -> InstanceLock:
     """Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078).
 
     Markers that disagree exit 75 at once, before the lock, naming them. Started by hand (no
@@ -337,7 +405,10 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
     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); ``env`` and ``argv`` default to this process's."""
+    ``wait_seconds`` overrides the choice (0 = never wait); ``env`` and ``argv`` default to this process's.
+
+    Where the lock has no path-keyed name (macOS) the held lock is watched (``InstanceLock.watch``, FAA-303): a folder
+    swapped under the running copy stops it with 75; ``on_lost`` replaces that reaction."""
     marker = supervisor_marker(env, argv)
     if marker["kind"] == "conflict":
         print(marker_conflict_message(marker), file=sys.stderr)
@@ -349,7 +420,7 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
     announced = False
     while True:
         try:
-            return InstanceLock(data_dir).acquire()
+            lock = InstanceLock(data_dir).acquire()
         except AlreadyRunning as exc:
             remaining = deadline - clock()
             if remaining <= 0:
@@ -360,3 +431,5 @@ def hold_single_instance(data_dir: Path, wait_seconds: Optional[float] = None, *
                 announced = True
             sleep(min(delay, remaining))
             delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
+            continue
+        return lock.watch(on_lost) if lock_name(lock.path) is None else lock