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

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -45,7 +45,8 @@ Starting, stopping and restarting go through the supervisor and nothing else:
 atomic, mode 0600) and the uninstaller removes it; a running service never writes its own, except an app
 ([below](#an-apps-own-descriptor-and-the-node)). It names the supervisor and its file (`label` and `plist`, `unit`,
 or `task`; none for `node` and `person`), the `origin` `http://127.0.0.1:<port>` (a port is a claim: an installer
-refuses a port another instance declares), the service's directories, and commands as argument arrays that never
+refuses a port another instance declares, and one another OS account listens on, read with the kit's
+`fabric_peer_owner`, FAA-225; the recorded port per account and its claim file wait on contract DEC-0160), the service's directories, and commands as argument arrays that never
 carry a credential. Only `doctor` and `update` are commands a host may run.
 
 **Started is not ready.** Readiness is the well-known document, `GET /.well-known/fabric-service`: answered without
@@ -205,6 +206,10 @@ if the holder leaves, and exits 75 only when the wait runs out: a few starts an
 360. It touches nothing while it waits. Two installs sharing one data directory are still the
 defect to remove; the back-off only stops the loop from costing the machine.
 
+A context refusal (`fabric_context`, exit 78: no record, a revoked grant, a folder of another context) is the same
+loop under `KeepAlive`, so a supervised copy waits the same back-off, holding nothing and with the lock released,
+before it exits 78 (FAA-279); started by hand it exits 78 at once.
+
 The marker (contract DEC-0057, CT-01) is the variable `FABRIC_SERVICE_SUPERVISOR=<manager>` or
 the argument `--fabric-supervisor <manager>` (also `--fabric-supervisor=<manager>`), after the
 executable and before any `--`; `<manager>` is `launchd`, `systemd`, `task-scheduler` or `node`
@@ -323,7 +328,7 @@ descriptor says `"lifecycle": {"manager": "systemd", "unit": "<id>.<instance>.se
 
 | Verb | Command |
 |---|---|
-| install, upgrade | `systemd_install` / `systemdInstall`: write `~/.config/systemd/user/<unit>`, `daemon-reload`, `enable`, `restart` (so the new unit is what runs). A unit already installed that `is-enabled` reports `disabled` stays off: the file is rewritten and nothing starts (LC-14), unless `force_enable` |
+| install, upgrade | `systemd_install` / `systemdInstall`: write `~/.config/systemd/user/<unit>`, `daemon-reload`, `enable`, `restart` (so the new unit is what runs). A unit already installed that `is-enabled` reports `disabled` stays off: the file is rewritten and nothing starts (LC-14), unless `force_enable`. With `origin` and `service_id` it then polls the well-known answer as `launchd_install` does until this account's listener answers (another account's is refused, DEC-0154 HA-2; FAA-253); Node's `systemdInstall` then returns a promise |
 | stop, keep off | `systemctl --user disable --now <unit>` |
 | uninstall | `systemd_uninstall` / `systemdUninstall`: `disable --now`, remove the unit, `daemon-reload` |
 
@@ -340,7 +345,7 @@ CI job has the real `schtasks` create, read back and delete such a task. The des
 
 | Verb | Command |
 |---|---|
-| install, upgrade | `task_install` / `taskInstall`: `schtasks /Create /TN <task> /XML <file> /F` from a UTF-16 file it then removes, then `/End` (when it existed) and `/Run`. A task already installed and disabled stays off: it is recreated and disabled again (LC-14), unless `force_enable` |
+| install, upgrade | `task_install` / `taskInstall`: `schtasks /Create /TN <task> /XML <file> /F` from a UTF-16 file it then removes, then `/End` (when it existed) and `/Run`. A task already installed and disabled stays off: it is recreated and disabled again (LC-14), unless `force_enable`. With `origin` and `service_id` it then polls as `launchd_install` does and returns the answer (FAA-253); Node's `taskInstall` then returns a promise |
 | stop, keep off | `schtasks /End /TN <task>`, then `schtasks /Change /TN <task> /DISABLE` |
 | uninstall | `task_uninstall` / `taskUninstall`: `/End`, then `/Delete /F` |
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -241,8 +241,9 @@ IPv4 wildcard for a LaunchAgent's installer, exactly `127.0.0.1` for a LaunchDae
 the contract's ruling on vouching is CT-261.
 
 Every kit client that sends a credential to loopback checks first: `check_service.py` (rule `listener.owner`, the first that reads the port for
-a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`),
-`fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user`, never retried),
+a local placement; `FAIL` `foreign-user` and no rule reads the port), the hub client (`HubError` `foreign-user`, its
+`data.reason` and sentence the owner's reason: `table-restricted`, then not retryable, or the owner's kind or `no-row`, FAA-272),
+`fabric_http` / `fabric-http.mjs` for a plain `http://` loopback URL (`HttpError` kind `foreign-user` with the same `reason`, never retried),
 `check_dashboard_layout.mjs` before a local login code, and the launchd installers' poll (a listener of another account
 is never a successful install, except a LaunchDaemon's job as its root installer proves it; the systemd and Task Scheduler installers do not poll yet, FAA-253). A running board
 session reports a door another account holds as `board.down` with reason `unreachable` until FAA-252. On macOS the Node

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/remote-placement.md

@@ -10,6 +10,7 @@ DEC-0019, at the commit this skill pins. This page is the how-to.
 - [On the platform](#on-the-platform)
 - [Checking it](#checking-it)
 - [What a host does and will not do](#what-a-host-does-and-will-not-do)
+- [Registered from several hosts](#registered-from-several-hosts)
 - [Rotation](#rotation)
 
 ## Is it a remote service?
@@ -68,8 +69,9 @@ watch the gate fail.
 ## On the platform
 
 - **Token**: a random value of at least 16 characters (32 bytes recommended), set as a secret;
-  the same value is written on the operator's computer by `registerRemote`. Compare in constant
-  time (`tokenMatches`).
+  the same value is written on the registering host by `registerRemote`. Compare in constant
+  time (`tokenMatches`). A service registered from more than one host holds one token per host
+  ([Registered from several hosts](#registered-from-several-hosts)).
 - **Session key**: 32 random bytes, a separate secret; rotating it signs every operator out.
 - **Codes and sessions**: `MemoryCodeStore`: a restart forgets every outstanding code, so none
   can be replayed, and every session record, so a deploy signs the operator out (DEC-0039: the
@@ -122,10 +124,49 @@ The login rules keep every `Set-Cookie` of the answer and judge the session cook
 | start, stop, restart, update | not offered |
 | a host older than the remote placement | shows the service as invalid and never contacts it |
 
+## Registered from several hosts
+
+One cloud service is often registered from more than one host: the operator's two computers, or an organization's
+space beside a personal one (FAA-280). Each registering host gets **its own token**; a token is never copied from one
+host to another, so one host can be revoked or rotated without touching the others.
+
+- **On the platform**, keep one secret per host (`FABRIC_HOST_TOKEN_<HOST>`, each at least 16 characters) and accept
+  a request whose bearer matches any of them. Compare it with every token, each with `tokenMatches` /
+  `token_matches`, with no early return, so the answer's timing does not say which host's token matched:
+
+  ```python
+  def host_of(authorization, tokens):  # tokens: {host name: token}; the kit's comparison, once per token
+      matched = [host for host, token in sorted(tokens.items()) if fs.token_matches(authorization, token)]
+      return matched[0] if matched else None  # None: a 401 with an empty body, as with one token
+  ```
+
+  `well_known_allowed` / `wellKnownAllowed` take one token: call it once per token the same way, or gate the route on
+  `host_of(...) is not None`.
+- **On each host**, run `registerRemote` / `register_remote` with that host's token only. The descriptor is the same
+  on every host but its `tokenFile`, which holds that host's value and nothing else (0600, never printed).
+- **Sign-in**: `LoginCodes` binds a session to one token's revision. Give each host its own `LoginCodes` with
+  `token=` that host's token and its own store (`MemoryCodeStore`, or a durable row per host); the session key may be
+  shared. Issue the login code from the instance whose token the bearer matched; redeem a code and check a session by
+  trying each instance in turn (a code another instance issued is not in its store, and a session cookie carries
+  another token's revision, so neither changes anything there). Removing or rotating one host's token then ends that
+  host's sessions only. One `LoginCodes` whose `token=` is a callable returning every token joined also works, and
+  signs every host out when any one rotates.
+- **The probe**: `check_service.py <id>` run on a host sends that host's token, so `well-known.requires-token` passes
+  on each; the request without a token, or with a value no host holds, still gets the `401` with an empty body.
+- **Revoking a host**: delete its secret on the platform and restart; that host then sees `401` and shows the service
+  `down`, never `foreign`. Remove its descriptor there with `remove_descriptor` / `removeDescriptor`.
+- **Adding a host**: create its secret, restart, then `registerRemote` on the new host. The other hosts' tokens and
+  sessions do not change.
+
+A token per host still gives each host the descriptor token's whole authority over the service. A remote surface no
+host token reaches (callers with their own delegation, the page opened only with Fabric Dashboards' one-time code)
+is the "local and cloud" form, FAA-204, which waits on the contract recording that form.
+
 ## Rotation
 
 Rotate the token by setting the new value on the platform and re-running `registerRemote` on the
-operator's computer with it; the old token stops working the moment the platform restarts with the
+registering host with it (on a service registered from several hosts, only that host's token,
+[above](#registered-from-several-hosts)); the old token stops working the moment the platform restarts with the
 new value, and so does every session begun under it when `LoginCodes` has `token=`. The re-run keeps the
 installed `source` when it passes none (one the kit refuses, edited by hand, is dropped with the warning); pass
 `runner`, `peer`, `summary`, `doctor` and `installedBy` / `installed_by` again, since a re-run writes only what it is

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

@@ -133,12 +133,20 @@ def check(data):
     return {'ok': True, 'kind': kind}
 
 
+def read_input(limit=65536):
+    # The handoff's bytes, decoded as UTF-8 with a byte order mark dropped: Windows before Python 3.15 decodes a text
+    # stdin with its code page, which misreads a Cyrillic handoff (FAA-210). A stream without bytes is read as text.
+    stream = getattr(sys.stdin, 'buffer', None)
+    raw = stream.read(limit + 1) if stream is not None else sys.stdin.read(limit + 1)
+    require(len(raw) <= limit, 'input_too_large')
+    return raw.decode('utf-8-sig') if isinstance(raw, bytes) else raw.lstrip('\ufeff')
+
+
 def main():
     try:
-        raw = sys.stdin.read(65537)
-        require(len(raw) <= 65536, 'input_too_large')
-        result = check(json.loads(raw))
-    except (ValueError, TypeError, KeyError, AttributeError):
+        result = check(json.loads(read_input()))
+    # RecursionError: Python 3.9 to 3.13 raise it on a deeply nested document under the cap
+    except (ValueError, TypeError, KeyError, AttributeError, RecursionError):
         # Fixed reasons only: never echo a submitted URL, token or JSON blob.
         result = {'ok': False, 'reason': 'dashboard_handoff_refused'}
     print(json.dumps(result))

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

@@ -673,12 +673,14 @@ class Probe:
         self.events_trace_rule(self.events)
 
     def channel_agent_rule(self) -> None:
-        """DEC-0150 (FAA-197): the channel agent's declaration, read from the manifest the descriptor names, else from the
-        well-known answer (CA-1); one read as not declared is NOT_RUN with its evidence, never a FAIL (D3), except a string
-        shaped like a credential in it or in a copy the probe reads beside it (CA-5)."""
+        """DEC-0150 (FAA-197): the declaration, from the manifest the descriptor names, else the well-known answer (CA-1); one
+        read as not declared is NOT_RUN, never a FAIL (D3), except a credential's shape in it or a copy beside it (CA-5)."""
         manifest, _, where = self.load_manifest()
-        self.add("channel-agent.declaration", *cac.declaration_verdict(
-            manifest, bool(self.d.get("fabricManifest")), where, self.wk, getattr(self, "wk_bytes", None)))
+        try:  # a copy of the probe without its schema file is NOT_RUN, and the later rules run (FAA-250)
+            verdict = cac.declaration_verdict(manifest, bool(self.d.get("fabricManifest")), where, self.wk, getattr(self, "wk_bytes", None))
+        except (OSError, ValueError) as exc:
+            verdict = ("NOT_RUN", "the probe cannot read %s beside it (%s)" % (cac.cas.SCHEMA_FILE.name, type(exc).__name__))
+        self.add("channel-agent.declaration", *verdict)
 
     def configuration_rule(self) -> None:
         """DEC-0046: a well-known `configuration` is {slots, resolved} as the schema types it; absent is NOT_RUN."""

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

@@ -18,7 +18,8 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from fabric_jsvalue import indexed_objects, js_keys  # noqa: E402
-from fabric_secrets import JS_SPACE, JWT_SHAPE, SECRET_VALUE, _url_parts, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
+from fabric_secrets import JS_SPACE, JWT_SHAPE, SECRET_VALUE, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
+from fabric_secrets import url_parts as _whatwg_url_parts  # noqa: E402 - public since FAA-250
 import check_service_channel_agent_schema as cas  # noqa: E402
 
 KEY = "https://fabric.passioncode.ai/agent-contract/extensions/channel-agent/0.1"
@@ -62,6 +63,9 @@ _IGNORABLE = ((0x00AD, 0x00AD), (0x034F, 0x034F), (0x061C, 0x061C), (0x115F, 0x1
               (0x200B, 0x200F), (0x202A, 0x202E), (0x2060, 0x206F), (0x3164, 0x3164), (0xFE00, 0xFE0F), (0xFEFF, 0xFEFF),
               (0xFFA0, 0xFFA0), (0xFFF0, 0xFFF8), (0x1BCA0, 0x1BCA3), (0x1D173, 0x1D17A), (0xE0000, 0xE0FFF))
 _FILLERS = frozenset("\u115f\u1160\u3164\uffa0\u2800\ufffc")
+#: Format characters (\p{Cf}) assigned after Unicode 13, which Python 3.9's unicodedata reads as unassigned (FAA-250):
+#: U+0890..0891 (Unicode 14) and U+13439..1343F (Unicode 15); the white-space and control categories gained none since.
+_LATER_FORMATS = ((0x0890, 0x0891), (0x13439, 0x1343F))
 
 
 def utf16(text: str) -> str:
@@ -75,7 +79,7 @@ def utf16(text: str) -> str:
 def _blank_char(char: str) -> bool:
     code = ord(char)
     return (char in JS_SPACE or char in _FILLERS or unicodedata.category(char) in ("Cf", "Cc", "Zs", "Zl", "Zp")
-            or any(low <= code <= high for low, high in _IGNORABLE))
+            or any(low <= code <= high for low, high in _IGNORABLE + _LATER_FORMATS))
 
 
 def blank(text: str) -> bool:
@@ -397,7 +401,7 @@ def url_parts(text: str) -> Optional[Tuple[str, str]]:
             return None
         if host and not _host_ok(host, special):
             return None
-    _, query, fragment = _url_parts(text)
+    _, query, fragment = _whatwg_url_parts(text)
     has_query = "?" in rest.partition("#")[0]
     has_fragment = "#" in rest
     return ("?" + query if has_query and query else "", "#" + fragment if has_fragment and fragment else "")
@@ -823,8 +827,9 @@ def declaration_verdict(manifest: Optional[Dict[str, Any]], manifest_named: bool
     where = "the manifest's provider.extensions" if site == "manifest" else "the well-known answer's extensions"
     shapes = _credential_shapes(others + copy)
     if shapes:  # a credential's shape in a copy no reader reads still sits in a document the service publishes (CA-5)
-        return "FAIL", "%d string(s) shaped like a credential outside the read declaration: %s (DEC-0150 CA-5)%s" % (
-            len(shapes), _shown(shapes), tail)
+        also = ("; on the read declaration itself, %d finding(s): %s" % (len(own), _shown(own))) if own else ""
+        return "FAIL", "%d string(s) shaped like a credential outside the read declaration: %s (DEC-0150 CA-5)%s%s" % (
+            len(shapes), _shown(shapes), also, tail)
     if declared and own:
         if not channel_agent_view(doc, site)["declared"] and not _credential_shapes(own):
             # D3: what the contract's reader reads as not declared (an older form, a repeat, a dangling reference) is

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

@@ -3,6 +3,7 @@ network guard's verdict, the board responder's fixture conversation, a session c
 whether two repository URLs name one repository, a service's actions declaration (DEC-0121) and whether its checkout
 opens its pages in a browser (FAA-118), and its A2A member and public Agent Card (DEC-0122). ``check_service.py`` runs them against a live service.
 Standard library only, Python 3.9+."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import email.utils

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

@@ -104,6 +104,8 @@ export class Responder extends SlotKeeper {
     this.state = 'idle';
     this.waitUntil = 0;
     this.stopping = false;
+    /** Whether shutdown found work to drain, published before it waits; null before shutdown starts (FAA-186). */
+    this.draining = null;
     this.claimKeys = {};
     this.probing = new Set(); // moved slots whose move-back claim lost its answer: asked again under the same key
     this.said = {};
@@ -939,6 +941,7 @@ export class Responder extends SlotKeeper {
   async shutdown(drain = DRAIN_SECONDS) {
     this.stopping = true;
     const work = this.current;
+    this.draining = Boolean(work); // what this shutdown waits for (FAA-186)
     if (work && !work.done) {
       await Promise.race([work.promise, new Promise((resolve) => setTimeout(resolve, drain * 1000).unref?.())]);
       if (!work.done) work.ctx.stopped = true;

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

@@ -254,6 +254,7 @@ export class SlotKeeper {
       if (!(e instanceof BoardError)) throw e;
       this.retryLater(capability, entries, e);
       if (SESSION_CODES.has(e.code)) throw e;
+      if (e.code === 'idempotency_window_expired') await this.status(); // the epoch moved: read it before the retry (FAA-186)
     }
   }
 }

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

@@ -6,7 +6,7 @@
 // An organization's instance whose context the record does not pin (`organizations`, DEC-0127) still starts: the helper
 // checks the placement and its share grant, not the pin (decision D5 of 0.52.0). Its tokens are refused instead:
 // hubKeyCertified reads a context's hub keys only while the record pins that organization (DL-14a, DEC-0128), so the
-// service passes `estateContext: context` to its delegation gate. A refusal at start would stop every organization
+// service passes contextGateOptions(info, record) (its context and its pin's issuer, FAA-150) to its delegation gate. A refusal at start would stop every organization
 // instance on today's records, which pin none until every reader is pinned at or after DEC-0127.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -14,7 +14,7 @@ import path from 'node:path';
 import { INSTANCE, ServiceError } from './fabric-base.mjs';
 import { descriptorPath } from './fabric-descriptor.mjs';
 import { parseContext } from './fabric-estate.mjs';
-import { InstanceLock, holdSingleInstance } from './fabric-lock.mjs';
+import { InstanceLock, LOCK_BACKOFF_FIRST_SECONDS, LOCK_BACKOFF_MAX_SECONDS, holdSingleInstance, lockWaitBudgetSeconds, supervisorMarker } from './fabric-lock.mjs';
 import { atomicWrite, instanceDirs, servicesDir } from './fabric-paths.mjs';
 import { instanceShareGrant } from './fabric-share.mjs';
 import { clockMs } from './fabric-time.mjs';
@@ -112,9 +112,29 @@ function markerMatches(file, expected) {
   return found !== null && typeof found === 'object' && Object.entries(expected).every(([key, value]) => found[key] === value);
 }
 
+/**
+ * What delegationGate takes from this instance's context (FAA-150): `estateContext`, and for an organization whose
+ * context `record` pins, `issuer`: the pin's context issuer (DL-14a, DEC-0128), so an organization's instance refuses a
+ * token the personal hub key signed. `info` is contextInstance's (or holdContextInstance's) answer; spread it after the
+ * service's own estate issuer: `delegationGate({ ..., issuer: estateIssuer, ...contextGateOptions(info, record) })`.
+ * Throws ContextRefused (`context-invalid`) for an answer with no context.
+ */
+export function contextGateOptions(info, record) {
+  const context = info !== null && typeof info === 'object' ? info.context : undefined;
+  const parsed = parseContext(context);
+  if (!parsed) throw new ContextRefused('context-invalid');
+  const options = { estateContext: context };
+  const pins = record !== null && typeof record === 'object' && !Array.isArray(record) ? record.organizations : undefined;
+  if (parsed.kind === 'org' && Array.isArray(pins)) {
+    const pin = pins.find((p) => p !== null && typeof p === 'object' && p.org === context && typeof p.iss === 'string');
+    if (pin) options.issuer = pin.iss;
+  }
+  return options;
+}
+
 /**
  * Run as `context`'s one instance, before any side effect (brief D17): contextInstance (a refusal writes one sentence
- * naming the code and exits 78, nothing created); then holdSingleInstance on the instance's data folder (its markers,
+ * naming the code and exits 78, nothing created; a supervised copy backs off first, FAA-279); then holdSingleInstance on the instance's data folder (its markers,
  * its supervised wait, its exit 75); then `<data>/fabric-context.json`: absent, written (0600, atomic); equal, kept;
  * another context or instance, or unreadable, releases the lock and exits 78 (`context-mismatch`). Resolves to the
  * instance with its held `lock`; `exit` is injectable as holdSingleInstance has it, and its answer is returned.
@@ -123,8 +143,20 @@ export async function holdContextInstance(id, context, {
   record, machineId, agentRef, at, personalInstance = 'default', servicesDirectory, platform = process.platform,
   waitSeconds, sleep, clock, exit = (code) => process.exit(code), env, argv,
 } = {}) {
-  const refuse = (code) => {
-    process.stderr.write(`${id} will not run for ${shown(context)} (${code}): ${REASONS[code]}.\n`);
+  // FAA-279: under a supervisor that restarts on exit an exit 78 at once is a respawn every few seconds, forever; a
+  // supervised copy first waits the lock's back-off (0.5 s doubling to 30 s, 300 s in all), holding nothing.
+  const refuse = async (code) => {
+    const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
+    const wait = Math.max(0, waitSeconds ?? lockWaitBudgetSeconds(marker));
+    const tail = wait > 0 ? ` Waiting ${Math.round(wait)} s before exiting, so its supervisor does not restart it every few seconds.` : '';
+    process.stderr.write(`${id} will not run for ${shown(context)} (${code}): ${REASONS[code]}.${tail}\n`);
+    const now = clock ?? (() => performance.now() / 1000);
+    const pause = sleep ?? ((seconds) => new Promise((resolve) => { setTimeout(resolve, seconds * 1000); }));
+    const deadline = now() + wait;
+    for (let delay = LOCK_BACKOFF_FIRST_SECONDS, remaining = deadline - now(); remaining > 0; remaining = deadline - now()) {
+      await pause(Math.min(delay, remaining));
+      delay = Math.min(delay * 2, LOCK_BACKOFF_MAX_SECONDS);
+    }
     return exit(EXIT_CONTEXT_REFUSED);
   };
   let info;

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

@@ -1,10 +1,12 @@
 // How a service is found (fabric-service/0.1): its descriptor, peers and app descriptors (DEC-0061, DEC-0069), build identity and the well-known document.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_descriptor.py. Node 20+, no dependency.
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { credentialName, repositoryCredential, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { ID, INSTANCE, LOCAL_PATH, PRIMARY_CAPABILITY, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
+import { ANOTHER_ACCOUNT } from './fabric-peer-owner.mjs'; // L0: who listens on a port (DEC-0154 HA-2, FAA-225)
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
 import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
@@ -313,9 +315,43 @@ export function sourceRefusal(d, dir = servicesDir()) {
   return `Descriptor ${d?.id}.${instance} ${NO_SOURCE_REPOSITORY}. ${PASS_SOURCE}`;
 }
 
-// FAA-198: a new descriptor names its source.repository; rewriting one already installed without it only warns
-// (process.emitWarning, code FABRIC_NO_SOURCE_REPOSITORY), so an installed agent's update keeps working.
-export function writeDescriptor(d, dir = servicesDir()) {
+// The child that answers portOwner: a plain listen on 127.0.0.1:<port> that succeeds means nothing holds it (the table
+// is not read); one that fails asks fabric-peer-owner's listener. A child, because writeDescriptor is synchronous.
+const PORT_OWNER_CHILD = `
+import net from 'node:net';
+const [port, url] = process.argv.slice(1);
+const say = (value) => process.stdout.write(JSON.stringify(value));
+const server = net.createServer();
+server.once('error', async () => {
+  try { const { listener } = await import(url); const who = await listener(Number(port)); say([who.kind, Number.isInteger(who.uid) ? who.uid : null]); }
+  catch { say(['unknown', null]); }
+});
+server.listen({ port: Number(port), host: '127.0.0.1', exclusive: true }, () => server.close(() => say(null)));
+`;
+
+/** Who listens on 127.0.0.1:<port> now, as [kind, uid] from the kit's fabric-peer-owner, or null when nothing holds it
+ * (FAA-225, DEC-0154 HA-2). */
+export function portOwner(port) {
+  const done = spawnSync(process.execPath, ['--input-type=module', '-e', PORT_OWNER_CHILD, String(port),
+    new URL('./fabric-peer-owner.mjs', import.meta.url).href], { encoding: 'utf8', timeout: 10000 });
+  try { return JSON.parse(done.stdout); } catch { return ['unknown', null]; }
+}
+
+/** Why an install may not take `port`: another OS account listens on it (FAA-225). This account, the system (launchd
+ * holds a socket-activated job's socket), nobody and an unreadable table pass. The recorded port per account and its
+ * claim file wait on contract DEC-0160. */
+export function portListenerRefusal(port, reader = portOwner) {
+  const found = reader(port);
+  if (!Array.isArray(found) || found[0] !== ANOTHER_ACCOUNT) return null;
+  const uid = Number.isInteger(found[1]) ? ` (uid ${found[1]})` : '';
+  return `Port ${port} is listened on by another OS account${uid}: choose a port no other account holds (DEC-0154, FAA-225).`;
+}
+
+/** Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim), and a port another OS
+ * account listens on (FAA-225; `portOwner(port) -> [kind, uid] | null` reads it, the kit's own by default).
+ * FAA-198: a new descriptor names its source.repository; rewriting one already installed without it only warns
+ * (process.emitWarning, code FABRIC_NO_SOURCE_REPOSITORY), so an installed agent's update keeps working. */
+export function writeDescriptor(d, dir = servicesDir(), { portOwner: reader = portOwner } = {}) {
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const me = `${d.id}.${d.instance}`;
@@ -334,6 +370,8 @@ export function writeDescriptor(d, dir = servicesDir()) {
     try { otherPort = portOf(String(other.origin ?? '')); } catch { continue; }
     if (otherPort === port) throw new ServiceError(`Port ${port} is already claimed by ${key} (${file}).`);
   }
+  const held = port === null ? null : portListenerRefusal(port, reader);
+  if (held) throw new ServiceError(held);
   ensurePrivateDir(dir);
   const target = descriptorPath(d.id, d.instance, dir);
   atomicWrite(target, `${JSON.stringify(d, null, 2)}\n`, 0o600);

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

@@ -16,9 +16,11 @@
 // The transport is injected in tests: async ({ method, url, headers, body, timeoutS, maxBytes }) =>
 // { status, headers, body: Uint8Array }, throwing on a connection error (a `TimeoutError` name is a timeout) or an
 // HttpError. Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+//
+// Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import http from 'node:http';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 
 export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
 export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
@@ -27,7 +29,7 @@ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 export class HttpError extends Error {
   constructor(message, { status = null, url = '', attempts = 0, retryAfterS = null, body = new Uint8Array(0),
-    kind = 'http' } = {}) {
+    kind = 'http', reason = null } = {}) {
     super(message);
     this.name = 'HttpError';
     this.status = status;
@@ -36,6 +38,8 @@ export class HttpError extends Error {
     this.retryAfterS = retryAfterS;
     this.body = body.slice(0, 2048);
     this.kind = kind; // http, connection, timeout, too-large, refused, foreign-user
+    // For foreign-user, why (FAA-272): table-restricted (never clears), the owner's kind, or the check's reason.
+    this.reason = reason;
   }
 }
 
@@ -184,7 +188,9 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
     req.on('error', (err) => {
       clearTimeout(timer);
       if (err instanceof ListenerRefused) {
-        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user' }));
+        const why = String(err.owner?.reason ?? err.owner?.kind ?? err.code ?? 'unknown');
+        const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user', reason }));
       } else reject(err);
     });
     if (body) req.write(body);

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

@@ -27,7 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { atomicWrite, ensurePrivateDir, readToken } from './fabric-service.mjs';
 import { hubKeyCertified } from './fabric-estate.mjs';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 
 // DEC-0154 HA-2: every connection to the door is checked before a byte goes out; kept alive, so a busy session reads the
 // socket table once per connection, not once per call. A free socket is closed after 2 s idle, before a server's own
@@ -53,6 +53,20 @@ export class HubError extends Error {
   }
 }
 
+/**
+ * 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
+ * runtime'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.
+ */
+export function listenerRefusal(e) {
+  const kind = e?.owner?.kind ?? null;
+  const why = String(e?.owner?.reason ?? kind ?? e?.code ?? 'unknown');
+  const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+  const shown = kind && e?.owner?.reason ? `${kind}: ${e.owner.reason}` : String(kind ?? why);
+  return new HubError('foreign-user', `The hub's port is not held by this OS account's process (${shown}); nothing was sent.`, reason !== TABLE_RESTRICTED, { reason });
+}
+
 /** Fabric's registry root, where hub.json lives (Fabric agentRegistry.ts#registryDirs). */
 export function fabricRoot(platform = process.platform, env = process.env) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
@@ -202,7 +216,7 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
     req.on('error', (e) => reject(e instanceof ListenerRefused
-      ? new HubError('foreign-user', `The hub's port is not held by this OS account's process (${e.owner?.kind ?? e.code}); nothing was sent.`, true)
+      ? listenerRefusal(e)
       : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
     if (payload) req.write(payload);
     req.end();