@passioncode-ai/fabric-agent-adapter 0.77.0 → 0.79.1

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

@@ -0,0 +1,198 @@
+// Who is calling an agent that sits behind `tailscale serve`, and what that person may open (FAA-297). The twin of
+// fabric_tailnet.py; both answer test/fixtures/tailnet/vectors.json alike. No dependencies beyond node:crypto and
+// node:net.
+//
+// The header `Tailscale-User-Login` is believed only on the agent's own serve listener (a loopback port or a Unix
+// socket that only serve reaches) and only from a loopback peer; on any other listener a request carrying it is
+// refused. What a person may open comes from a `tailnet-perimeter/1` file generated from the organization's access
+// registry (it names its source in `generatedFrom`); MCP also takes a personal key, stored as its SHA-256, owned by one
+// login and no wider than that login's groups. Refusals are 401 or 403 with a stable `code`.
+
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { isIP } from 'node:net';
+
+export const PERIMETER_SCHEMA = 'tailnet-perimeter/1';
+export const IDENTITY_HEADER = 'tailscale-user-login';
+export const SERVE_HEADERS = Object.freeze(['tailscale-user-login', 'tailscale-user-name', 'tailscale-user-profile-pic']);
+export const LISTENER_SERVE = 'serve';
+export const SURFACES = Object.freeze(['dashboard', 'mcp']);
+
+const LOGIN = /^[A-Za-z0-9._%+-]{1,128}@[A-Za-z0-9.-]{1,125}$/;
+const NAME = /^[a-z][a-z0-9._:/-]{0,127}$/;
+const KEY_HASH = /^sha256:[0-9a-f]{64}$/;
+const KEY_ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+export const REFUSALS = Object.freeze({
+  'serve-header-off-serve': 403,
+  'peer-not-loopback': 403,
+  'identity-missing': 401,
+  'identity-ambiguous': 401,
+  'identity-malformed': 401,
+  'not-in-perimeter': 403,
+  'dashboard-not-granted': 403,
+  'capability-not-granted': 403,
+  'key-required': 401,
+  'key-unknown': 401,
+  'key-not-yours': 403,
+  'key-wider-than-group': 403,
+});
+
+/** A perimeter or key list that cannot be used: `code` names why, `where` the place, never a value. */
+export class PerimeterError extends Error {
+  constructor(code, where = '') {
+    super(`${code}${where ? ` at ${where}` : ''}`);
+    this.name = 'PerimeterError';
+    this.code = code;
+    this.where = where;
+  }
+}
+
+/** The stored form of a personal key: `sha256:<hex>` of its UTF-8 bytes. */
+export function hashKey(value) {
+  if (typeof value !== 'string' || !value) throw new TypeError('a key is a non-empty string');
+  return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+const sortedSet = (values) => [...new Set(values)].sort();
+const isRecordValue = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const pyKeySort = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function names(value, where) {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === 'string' && NAME.test(v))) {
+    throw new PerimeterError('perimeter-invalid', where);
+  }
+  return sortedSet(value);
+}
+
+/** Check a parsed `tailnet-perimeter/1` document and answer its normalized form; throw PerimeterError otherwise. */
+export function loadPerimeter(doc) {
+  if (!isRecordValue(doc) || doc.schema !== PERIMETER_SCHEMA) throw new PerimeterError('perimeter-schema', 'schema');
+  const source = doc.generatedFrom;
+  if (!isRecordValue(source) || !['registry', 'revision', 'at'].every((k) => typeof source[k] === 'string' && source[k])) {
+    throw new PerimeterError('perimeter-not-generated', 'generatedFrom');
+  }
+  const groups = doc.groups;
+  if (!isRecordValue(groups) || Object.keys(groups).length === 0) throw new PerimeterError('perimeter-invalid', 'groups');
+  const out = {};
+  for (const name of Object.keys(groups).sort(pyKeySort)) {
+    const group = groups[name];
+    const where = NAME.test(name) ? `groups.${name}` : 'groups';
+    if (!NAME.test(name) || !isRecordValue(group)) throw new PerimeterError('perimeter-invalid', where);
+    const members = group.members;
+    if (!Array.isArray(members) || !members.every((m) => typeof m === 'string' && LOGIN.test(m))) {
+      throw new PerimeterError('perimeter-invalid', `${where}.members`);
+    }
+    out[name] = {
+      members: sortedSet(members.map((m) => m.toLowerCase())),
+      dashboards: names(group.dashboards ?? [], `${where}.dashboards`),
+      capabilities: names(group.capabilities ?? [], `${where}.capabilities`),
+    };
+  }
+  return {
+    schema: PERIMETER_SCHEMA,
+    generatedFrom: { registry: source.registry, revision: source.revision, at: source.at },
+    groups: out,
+  };
+}
+
+/** Check a list of personal keys `{id, login, sha256, capabilities}` (the hash only, never the key). */
+export function loadKeys(keys) {
+  if (!Array.isArray(keys)) throw new PerimeterError('keys-invalid', 'keys');
+  const out = [];
+  const seen = new Set();
+  keys.forEach((key, i) => {
+    const where = `keys[${i}]`;
+    if (!isRecordValue(key) || typeof key.id !== 'string' || !KEY_ID.test(key.id)
+        || typeof key.login !== 'string' || !LOGIN.test(key.login)
+        || typeof key.sha256 !== 'string' || !KEY_HASH.test(key.sha256)) {
+      throw new PerimeterError('keys-invalid', where);
+    }
+    if (seen.has(key.id) || out.some((k) => k.sha256 === key.sha256)) throw new PerimeterError('keys-duplicate', where);
+    seen.add(key.id);
+    out.push({ id: key.id, login: key.login.toLowerCase(), sha256: key.sha256,
+      capabilities: names(key.capabilities ?? [], `${where}.capabilities`) });
+  });
+  return out;
+}
+
+function headerValues(headers, name) {
+  // A list of pairs, a Map or a fetch Headers (anything with entries()), or a plain object such as Node's req.headers.
+  const plain = headers === null || headers === undefined || Object.getPrototypeOf(headers) === Object.prototype
+    || Object.getPrototypeOf(headers) === null;
+  const pairs = Array.isArray(headers) ? headers
+    : !plain && typeof headers.entries === 'function' ? [...headers.entries()]
+      : Object.entries(headers ?? {});
+  const found = [];
+  for (const [key, value] of pairs) {
+    if (typeof key === 'string' && key.toLowerCase() === name) found.push(...(Array.isArray(value) ? value : [value]));
+  }
+  return found.map((v) => (typeof v === 'string' ? v : ''));
+}
+
+function isLoopback(address) {
+  if (address === 'unix') return true;
+  if (typeof address !== 'string') return false;
+  const ip = address.split('%', 1)[0];
+  const family = isIP(ip);
+  if (family === 4) return ip.split('.')[0] === '127';
+  if (family !== 6) return false;
+  const host = new URL(`http://[${ip}]/`).hostname; // the canonical compressed form: [::1], [::ffff:7f00:1]
+  return host === '[::1]' || /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(host);
+}
+
+const refuse = (code, login = null, groups = []) => ({ allowed: false, status: REFUSALS[code], code, login, groups });
+
+function bearer(headers) {
+  const values = headerValues(headers, 'authorization');
+  if (values.length !== 1) return null;
+  const text = values[0].trim();
+  const space = text.indexOf(' ');
+  if (space < 0) return null;
+  const scheme = text.slice(0, space);
+  const rest = text.slice(space + 1).trim();
+  return scheme.toLowerCase() === 'bearer' && rest && !rest.includes(' ') ? rest : null;
+}
+
+function sameDigest(a, b) {
+  const x = Buffer.from(a, 'utf8');
+  const y = Buffer.from(b, 'utf8');
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * Decide one request. `listener` is which of the agent's listeners took it (`serve` for serve's own); `peer` the
+ * connecting address (`unix` for a Unix socket); `perimeter` and `keys` as loadPerimeter and loadKeys answer;
+ * `surface` `dashboard` or `mcp`; `target` the dashboard's or the capability's name. Answers
+ * {allowed, status, code, login, groups}: status 200 with code `ok`, else 401 or 403 with the refusal's code.
+ */
+export function authorize({ listener, peer, headers, perimeter, surface, target, keys = null }) {
+  if (!SURFACES.includes(surface)) throw new TypeError(`surface is one of ${SURFACES.join(', ')}`);
+  if (listener !== LISTENER_SERVE) {
+    if (SERVE_HEADERS.some((h) => headerValues(headers, h).length)) return refuse('serve-header-off-serve');
+    throw new TypeError("authorize decides serve's listener; the Fabric listener keeps its session key");
+  }
+  if (!isLoopback(peer)) return refuse('peer-not-loopback');
+  const logins = headerValues(headers, IDENTITY_HEADER);
+  if (logins.length === 0) return refuse('identity-missing');
+  if (logins.length > 1) return refuse('identity-ambiguous');
+  let login = logins[0].trim();
+  if (!LOGIN.test(login)) return refuse('identity-malformed');
+  login = login.toLowerCase();
+  const groups = Object.keys(perimeter.groups).filter((n) => perimeter.groups[n].members.includes(login)).sort(pyKeySort);
+  if (groups.length === 0) return refuse('not-in-perimeter', login);
+  const dashboards = new Set(groups.flatMap((n) => perimeter.groups[n].dashboards));
+  const capabilities = new Set(groups.flatMap((n) => perimeter.groups[n].capabilities));
+  if (surface === 'dashboard') {
+    if (!dashboards.has(target)) return refuse('dashboard-not-granted', login, groups);
+    return { allowed: true, status: 200, code: 'ok', login, groups };
+  }
+  const presented = bearer(headers);
+  if (presented === null) return refuse('key-required', login, groups);
+  const digest = hashKey(presented);
+  const key = (keys ?? []).find((k) => sameDigest(k.sha256, digest));
+  if (!key) return refuse('key-unknown', login, groups);
+  if (key.login !== login) return refuse('key-not-yours', login, groups);
+  if (!key.capabilities.every((c) => capabilities.has(c))) return refuse('key-wider-than-group', login, groups);
+  if (!key.capabilities.includes(target)) return refuse('capability-not-granted', login, groups);
+  return { allowed: true, status: 200, code: 'ok', login, groups, key: key.id };
+}

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

@@ -16,6 +16,12 @@ PROTOCOL = "fabric-service/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/service/0.1"
 
 
+# DEC-0140 PR-1 (contract project-comms.md, interop.md's C3.1 amendment): the capability of a Project's primary
+# responder, a session's. No service serves it as a tool or declares it (surfaces.mcp.capabilities, an action's tool),
+# and the board kit never enrolls a service's responder for it (FAA-244).
+PRIMARY_CAPABILITY = "project.work"
+
+
 # Lifecycle rules: references/lifecycle.md, the rule for this kit's users, which implements the public
 # contract's service specification (Lifecycle). A launchd-supervised copy that finds the lock held backs
 # off in-process for this long before its exit 75 (LC-03, F8): under KeepAlive with ThrottleInterval 10

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

@@ -52,6 +52,9 @@ class BoardSession:
                              timeout=timeout if timeout is not None and timeout > 0 else self.timeout,
                              method=method, protocol_version=self.protocol_version if self.mcp_session else None)
         except _hub.HubError as exc:
+            if exc.code == "foreign-user":  # FAA-252: another OS account's process holds the port; nothing was sent
+                raise BoardError("foreign-user", "The hub's port is held by another OS account's process; nothing was sent.",
+                                 True) from exc
             raise BoardError("unreachable", "Fabric's hub did not answer; a write may have been stored, so send it again with "
                              "the same idempotency key.", True) from exc
 

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

@@ -148,6 +148,9 @@ class Responder(SlotKeeper):
         caps = list(capabilities)
         if not caps or any(not isinstance(c, str) or not _CAPABILITY.fullmatch(c) for c in caps) or len(set(caps)) != len(caps):
             raise BoardError("invalid_arguments", "Name each capability once, [a-z][a-z0-9._-]{1,127}.")
+        if _fs.PRIMARY_CAPABILITY in caps:  # FAA-244: DEC-0140 PR-1, a session's slot, never a service's
+            raise BoardError("invalid_arguments", "%s is a Project's primary responder's, a session's: a service answers "
+                             "the capabilities it declares (DEC-0140 PR-1)." % _fs.PRIMARY_CAPABILITY)
         self.hub, self.project = hub, _hub._project(project_id)
         #: FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; None reads none).
         self.mandate_from, self.agent_id, self.wall = _link.mandate_options(agent_id, mandate_from), agent_id, wall
@@ -258,7 +261,7 @@ class Responder(SlotKeeper):
         status = self._status()
         if missing:
             self._emit("board.access.needed", "warning", "The operator has not let this service answer %s on this Project; ask in "
-                       "Fabric (Agents & access)." % ", ".join(missing), notify=True, episode=",".join(missing),
+                       "Fabric (Settings → Agent access)." % ", ".join(missing), notify=True, episode=",".join(missing),
                        capabilities=missing)
         self.slots = {}
         self._recover(status, [c for c in self.capabilities if c in grant.capabilities])
@@ -430,7 +433,8 @@ class Responder(SlotKeeper):
         try:
             self._receipt("com.reply", self._call("com.reply", dict(self._reply_extra(entry), fence=self._fence(old, probe["key"]))))
         except BoardError as exc:
-            if exc.code in ("unreachable", "session-ended", "authority_changed", "not_authorized", "not_available", "capacity_exceeded"):
+            if exc.code in ("unreachable", "foreign-user", "session-ended", "authority_changed", "not_authorized", "not_available",
+                            "capacity_exceeded"):  # foreign-user: nothing was sent now, so nothing is known (0.79.0 seam)
                 raise
         else:
             entry["replied"] = True
@@ -549,7 +553,7 @@ class Responder(SlotKeeper):
             self.state = "not-authorized"
             self._drop_session()
             self._emit("board.access.needed", "warning", "This service may not answer requests for this Project: the operator "
-                       "has to allow it in Fabric (Agents & access). Nothing is claimed until then.", notify=True,
+                       "has to allow it in Fabric (Settings → Agent access). Nothing is claimed until then.", notify=True,
                        episode="access", reason=code)
         elif code == "held":
             self.state = "paused"
@@ -564,9 +568,13 @@ class Responder(SlotKeeper):
         else:
             self.state = "down"
             # In recovery with no slot held a refusal reconnects (seam 6); with some held they are served (seam 7).
-            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol")) and not keep:
+            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol",
+                                       "foreign-user")) and not keep:
                 self._drop_session()
-            self._emit("board.down", "warning", "Fabric's board cannot be reached; the responder tries again with a growing pause.",
+            # FAA-252: a port another OS account holds is said as such; nothing was sent there
+            self._emit("board.down", "warning", "Fabric's board port is held by another OS account's process; nothing was sent, "
+                       "and the responder tries again with a growing pause." if code == "foreign-user" else
+                       "Fabric's board cannot be reached; the responder tries again with a growing pause.",
                        episode="down", reason=code)
         return wait
 

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

@@ -20,7 +20,7 @@ HOLD_RETRY_MAX_SECONDS = 900.0
 #: Refusals that are about the board session, not one capability: they end recovery and go to the responder's fault.
 SESSION_CODES = frozenset(["unreachable", "session-ended", "not_authorized", "authority_changed", "credential", "no-epoch",
                            "schema-unsupported", "checkpoint", "receipt-shape", "idempotency_conflict", "not-running",
-                           "not-a-hub", "hub-unavailable", "protocol", "not_available"])
+                           "not-a-hub", "hub-unavailable", "protocol", "not_available", "foreign-user"])
 
 _whole = lambda v: int(v) if isinstance(v, float) and v.is_integer() else v  # noqa: E731 - 2.0 is 2, as Node reads it
 
@@ -78,7 +78,7 @@ class SlotKeeper:
                 if _is_int(generation, 1) and (answer.get("repeated") is True or not moved):
                     rest = {"project": self.project, "generation": generation}
             except BoardError as exc:
-                if exc.code in ("unreachable", "session-ended"):
+                if exc.code in ("unreachable", "session-ended", "foreign-user"):  # foreign-user: the earlier ask is unknown
                     raise
                 if exc.code == "idempotency_window_expired":
                     rest = {}  # a retired epoch refuses even a repeat: unknown, so no record (a first start, never a move)

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

@@ -45,6 +45,7 @@ from fabric_jsvalue import (  # noqa: E402 - the core (FAA-65)
     jcs,
 )
 from fabric_paths import atomic_write as _atomic_write  # noqa: E402 - the kit's private writer (FAA-85)
+import fabric_peer_owner as _po  # noqa: E402 - a loopback key set is read from this account's listener only (FAA-255)
 from fabric_mandate import effect_closure  # noqa: E402,F401 - defined once beside the mandate that reads it too (DEC-0125)
 
 REFUSAL_CODES = (
@@ -672,9 +673,21 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
         return None
 
 
-def _opener(deadline: Dict[str, Any]) -> urllib.request.OpenerDirector:
+class _CheckedHTTPConnection(_po.CheckedHTTPConnection):
+    """Plain http, which a key set source allows on loopback only (DEC-0154 HA-2, FAA-255): every connect, a reconnect
+    included, tells the server end's owner and refuses (closed, nothing sent) unless it is this OS account's process,
+    so keys another account's listener serves are never read; built the way urllib builds a connection."""
+
+    def __init__(self, host: str, port: Optional[int] = None, timeout: Any = 10.0, **kwargs: Any) -> None:
+        http.client.HTTPConnection.__init__(self, host, port, timeout=timeout, **kwargs)
+        self.expect_pid = None
+        self.vouch_pid = None  # an issuer's URL is never a process this caller started (FAA-267)
+
+
+def _opener(deadline: Dict[str, Any], direct: bool = False) -> urllib.request.OpenerDirector:
     """No redirect, and a timer that shuts the socket down at the deadline: a socket timeout bounds one read, so an
-    issuer trickling a byte a second would otherwise hold the caller for as long as it likes (finding 13)."""
+    issuer trickling a byte a second would otherwise hold the caller for as long as it likes (finding 13). `direct`:
+    a loopback source never goes through a proxy from the environment, so the owner check reads the URL's own port."""
     def watched(base: type) -> type:
         class Watched(base):  # type: ignore[misc, valid-type]
             def connect(self) -> None:
@@ -695,11 +708,13 @@ def _opener(deadline: Dict[str, Any]) -> urllib.request.OpenerDirector:
 
     class Http(urllib.request.HTTPHandler):
         def http_open(self, req: Any) -> Any:
-            return self.do_open(watched(http.client.HTTPConnection), req)
+            return self.do_open(watched(_CheckedHTTPConnection), req)  # http is loopback only (the source check)
 
     class Https(urllib.request.HTTPSHandler):
         def https_open(self, req: Any) -> Any:
             return self.do_open(watched(http.client.HTTPSConnection), req, context=self._context)
+    if direct:
+        return urllib.request.build_opener(urllib.request.ProxyHandler({}), _NoRedirect, Http, Https)
     return urllib.request.build_opener(_NoRedirect, Http, Https)
 
 
@@ -709,7 +724,8 @@ def _fetch(source: str) -> Any:
         request = urllib.request.Request(source.partition("#")[0], headers={"Accept": "application/json"})
         deadline: Dict[str, Any] = {"end": time.monotonic() + JWKS_FETCH_SECONDS, "fired": False, "timer": None}
         try:
-            with _opener(deadline).open(request, timeout=JWKS_FETCH_SECONDS) as response:  # https or loopback http only
+            direct = source.lower().startswith("http://")
+            with _opener(deadline, direct).open(request, timeout=JWKS_FETCH_SECONDS) as response:  # https or loopback http only
                 body = b""
                 while len(body) <= 65536 and not deadline["fired"]:
                     chunk = response.read1(65537 - len(body))
@@ -724,6 +740,8 @@ def _fetch(source: str) -> Any:
             raise
         except http.client.HTTPException as exc:  # a garbage status line or headers: the issuer cannot be read
             raise ConnectionError(type(exc).__name__) from None
+        except _po.ListenerRefused as exc:  # FAA-255: another account's listener, or one that cannot be told
+            raise ConnectionError("foreign-user: %s" % exc) from None
         finally:
             if deadline["timer"] is not None:
                 deadline["timer"].cancel()

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

@@ -18,6 +18,7 @@ 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 (
+    PRIMARY_CAPABILITY,
     PROTOCOL,
     ServiceError,
     _ID,
@@ -49,7 +50,7 @@ from fabric_usage import (
 DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
 
 
-DASHBOARD_KIT = "fabric-dashboard-kit@1.1.5"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.1.6"
 
 
 REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
@@ -628,6 +629,11 @@ def configuration_problems(doc: Any) -> List[str]:
     return problems
 
 
+#: FAA-244: DEC-0140 PR-1 reserves the primary responder's capability; a service never publishes it.
+_RESERVED = ("%%s: %s is reserved for a Project's primary responder, a session (DEC-0140 PR-1); a service never "
+             "serves it as a tool or declares it." % PRIMARY_CAPABILITY)
+
+
 def build_well_known(*, service_id: str, instance: str, name: str, version: str, build: Dict[str, Any],
                      started_at: str, status: str, degraded: Sequence[Dict[str, str]],
                      surfaces: Dict[str, Any], summary: Optional[Sequence[Dict[str, Any]]] = None,
@@ -664,6 +670,10 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
         problems = a2a_surface_problems(surfaces["a2a"])
         if problems:
             raise ServiceError("surfaces.a2a: %s." % "; ".join(problems))
+    mcp_surface = surfaces.get("mcp")
+    listed = mcp_surface.get("capabilities") if isinstance(mcp_surface, dict) else None
+    if isinstance(listed, list) and PRIMARY_CAPABILITY in listed:
+        raise ServiceError(_RESERVED % "surfaces.mcp.capabilities")
     doc: Dict[str, Any] = {
         "protocol": PROTOCOL,
         "service": {"id": service_id, "instance": instance, "name": name, "version": version, "build": build},
@@ -698,6 +708,9 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
                                                 "surfaces": surfaces})
             if findings:
                 raise ServiceError("Actions declaration: %s." % "; ".join(f["message"] for f in findings))
+            if any(isinstance(a, dict) and a.get("tool") == PRIMARY_CAPABILITY
+                   for a in extensions[ACTIONS_EXTENSION_KEY].get("actions") or []):
+                raise ServiceError(_RESERVED % "an action's tool")
         doc["extensions"] = dict(extensions)
     if configuration is not None:
         problems = configuration_problems(configuration)

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

@@ -73,8 +73,42 @@ class InstanceLock:
     #: a file is allowed there).
     WINDOWS_LOCK_OFFSET = 1 << 30
 
+    #: How many times acquire re-opens service.lock when the file it locked is no longer the file at its path (a
+    #: folder swapped under it by a data import), before it gives up with an error naming the path (FAA-293).
+    INODE_RETRIES = 3
+
     def acquire(self) -> "InstanceLock":
         ensure_private_dir(self.path.parent)
+        for _ in range(self.INODE_RETRIES):
+            if self._acquire_once():
+                return self
+        raise ServiceError("%s kept moving while it was locked (a folder swapped under the data folder?): no copy "
+                           "holds a file that is no longer at its path; start again once the folder is settled." % self.path)
+
+    def _locked_file_is_at_path(self, fd: int) -> bool:
+        """The inode this copy locked is the file at the path now (FAA-293). Windows does not rename a folder holding
+        an open file, and its lock is a byte range on this handle, so the check is POSIX only."""
+        if WINDOWS:
+            return True
+        try:
+            here, held = os.stat(str(self.path)), os.fstat(fd)
+        except FileNotFoundError:
+            return False
+        return (here.st_dev, here.st_ino) == (held.st_dev, held.st_ino)
+
+    def _let_go(self, fd: int) -> None:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        name, self._name = self._name, None
+        if name is not None:
+            try:
+                _drop_lock_name(name)
+            except OSError:
+                pass
+
+    def _acquire_once(self) -> bool:
         fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | _O_BINARY, 0o600)
         try:
             if WINDOWS:
@@ -92,6 +126,9 @@ class InstanceLock:
             if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES, getattr(errno, "EDEADLOCK", -1)):
                 raise AlreadyRunning(_read_pid(self.path), self.path) from None
             raise
+        if not self._locked_file_is_at_path(fd):  # another copy may hold the file at the path: re-open that one
+            os.close(fd)
+            return False
         try:
             self._name = _hold_lock_name(self.path)
         except BaseException:
@@ -114,8 +151,11 @@ class InstanceLock:
                     except OSError:  # as with the close: nothing to add to the first error
                         pass
             raise
+        if not self._locked_file_is_at_path(fd):  # swapped while the pid was written: this copy holds nothing real
+            self._let_go(fd)
+            return False
         self._fd = fd
-        return self
+        return True
 
     def release(self) -> None:
         if self._fd is not None:

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

@@ -366,6 +366,10 @@ class Client:
                 if answer is not None:
                     answer["attempts"] = attempts
                     return answer
+                if outcome == "foreign-user":  # FAA-257: the fallback would go to the same refused listener
+                    raise OpenRouterError("The base URL's port is held by another OS account's process, or its owner "
+                                          "cannot be told; nothing was sent (DEC-0154 HA-2)", kind="foreign-user",
+                                          attempts=attempts)
                 if outcome in _STOP_AT_ONCE.values():
                     raise OpenRouterError("OpenRouter refused the key or the request (%s)" % status, kind=outcome,
                                           attempts=attempts)
@@ -390,6 +394,8 @@ class Client:
                 # the provider may have billed a call whose answer never arrived whole (a cut connection looks the
                 # same as a refused one from here): counted, never as $0; over-counting is the safe side
                 self.ledger.record(self._unmeasured(asked, task_run_id, worst))
+            if err.kind == "foreign-user":  # nothing was sent: nothing billed, and no other model there (FAA-257)
+                return "foreign-user", err.status, None, None
             return ("retry" if err.kind in ("connection", "timeout") else "refused"), err.status, None, None
         status = response.status
         if status in _STOP_AT_ONCE:

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

@@ -22,6 +22,7 @@ from fabric_time import DAY_MS as _DAY_MS, utc_date_ms as _utc_date_ms  # noqa:
 from fabric_base import (  # noqa: F401
     PROTOCOL,
     EXTENSION_KEY,
+    PRIMARY_CAPABILITY,
     SUPERVISOR_ENV,
     DRAIN_SECONDS,
     _ID,
@@ -314,9 +315,14 @@ from fabric_supervisors import (  # noqa: F401
     launchd_plist,
     _launchctl,
     _domain,
+    SYSTEM_DAEMONS,
+    launchd_domain,
     launchd_loaded,
     launchd_pid,
     fetch_well_known,
+    well_known_of,
+    job_well_known_of,
+    ForeignUserAnswer,
     _OVERRIDE_ROW,
     launchd_override,
     launchd_install,