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

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