@passioncode-ai/fabric-agent-adapter 0.73.0 → 0.75.0

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

@@ -1,6 +1,6 @@
 # fabric-service/0.1: wire reference
 
-Pinned to `fabric-agent-contract` commit `eac1a594aa131851f079da8bb7b2149e1951f35f`
+Pinned to `fabric-agent-contract` commit `18f8d48762edc5bfb1433657cbfe1c16196df1a6`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;
@@ -36,6 +36,7 @@ this page is the working summary. Extension key:
 - Well-known document
 - Events page
 - Login code and the operator session
+- The listener's owner (DEC-0154 HA-2)
 - Semantic rules a host applies
 
 ## Descriptor: written by the installer
@@ -48,9 +49,9 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | Field | Rule |
 |---|---|
 | `protocol` | `"fabric-service/0.1"` |
-| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique per machine |
+| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique within one OS account's services directory (DEC-0154) |
 | `name`, `summary` | ≤ 80 and ≤ 200 characters |
-| `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim. Optional for an app's descriptor only (`manager: "person"`, DEC-0069): its live origin and process id are in the app's own liveness file, and a descriptor without an origin claims no port (`FAC-SEM-010`) |
+| `origin` | `http://127.0.0.1:<port>`; the port is a declaration no other descriptor in this account's directory makes (`FAC-SEM-010`), kept free on the computer by HA-1, whose claim the kit does not write yet (FAA-225). Optional for an app's descriptor only (`manager: "person"`, DEC-0069): its live origin and process id are in the app's own liveness file, and a descriptor without an origin claims no port (`FAC-SEM-010`) |
 | `auth` | `tokenFile` (0600; on Windows a protected ACL: owner and every granting entry the current user, SYSTEM or Administrators: service.md *Windows token files*, DEC-0032, DEC-0033); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
 | `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task), `node` (Project Observatory's node supervises it as its child, with no supervisor file, DEC-0061), `person` (an app a person installs and starts, then `app`, the installed app, DEC-0069) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032), `label` and `plist` beside any but `launchd` (DEC-0057), `app` beside any but `person`. Both kits and the probe accept all six; both kits write the unit and the task (`systemd_unit`, `task_xml` / `systemdUnit`, `taskXml`). An app's descriptor says it is installed, never that it runs: the probe checks `app` is still there (`descriptor.app-installed`) and reads no well-known document; a reader that finds the app gone treats the descriptor as stale (`app_descriptor_stale` / `appDescriptorStale`), and an app that writes its own descriptor rewrites it only when `app_descriptor_action` / `appDescriptorAction` says `write` |
 | `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
@@ -61,7 +62,7 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | `runner` | optional `{kind?, credentialKind}` (DEC-0061): `credentialKind` `subscription`, `key`, `platform-metered` or `none`: a kind, never a credential (`FAC-SEM-086` refuses a credential-shaped value here or in `installedBy`); a subscription names its vendor's runner (`claude-code`, `kimi-code`, `codex`) |
 | `peer` | optional `{endpoint, custody, residency, maxDataClass}` (DEC-0061): the service is offered to others. `endpoint` `https://<dns-name>[:<port>][/<path>]`, never a reserved name (`FAC-SEM-085`); `custody` `organization-managed`, `personal` or `processor-hosted` (an organization's cloud a processor runs under a processing agreement, DEC-0099); `residency` 1–32 ISO 3166-1 alpha-2 codes, `EU` admitted, user-assigned codes refused; `maxDataClass` `public` < `internal` < `confidential` < `restricted`. An offer needs `runner` and never runs on a subscription. A host sends a request from anyone but the operator only when `peer_refusal` / `peerRefusal` answers null (`FAC-SEM-088`); usage rows may take `route: "platform-metered"` |
 
-A local descriptor MAY say where a collector on the same machine reads its daily operations digests, under
+A local descriptor MAY say where a collector in the same OS account reads its daily operations digests, under
 `https://fabric.passioncode.ai/agent-contract/extensions/ops-digest/0.1` (`fabric-ops-digest/0.1`, DEC-0153, OD-9,
 FAC-SEM-168): 1 to 8 `{dir, source}`, `dir` a folder inside `paths.data`. A remote descriptor carries none, and the key
 is read nowhere else. The kits know the revision and neither write nor check the declaration yet (FAA-206).
@@ -205,6 +206,34 @@ The session it starts ends 12 h after its last use, 7 days after sign-in, on log
 descriptor token rotates (DEC-0039); a service may shorten either bound, never lengthen one. An
 ended session answers `401` on the dashboard page.
 
+## The listener's owner (DEC-0154 HA-2)
+
+Loopback is one per computer, not one per OS account. Before a client sends any credential to
+`http://127.0.0.1:<port>` (a descriptor's token, a delegation token, a login code's request, a session cookie, a door's
+token), and before a host calls a local service healthy, it tells the owner of the server end of its own connection
+from the computer's socket table. A listener of another OS account, of root, SYSTEM or a service account, or one whose
+owner cannot be told, is `foreign-user`: nothing is sent and nothing it answers is read as the service's. The order of
+a local service's states is `down`, `foreign-user`, `foreign` (`FAC-SEM-009`), then the well-known `status`; the
+well-known `process.pid` is never proof (`docs/specification/service.md#ha-2` at the pin).
+
+The kit's module is `fabric_peer_owner` / `fabric-peer-owner.mjs` (layer L0, [kit modules](kit-modules.md)): `listener(port)`,
+`server_end(sock)` / `serverEnd(socket)`, `peer`, and a connection checked before a byte is written
+(`CheckedHTTPConnection`; Node `checkedSocket`, `CheckedAgent`). Python reads macOS through `sysctl
+net.inet.tcp.pcblist_n` (calibrated on a connected pair of its own, else `netstat -anv`), Linux through `/proc/net/tcp`
+and `/proc/net/tcp6`, Windows through `GetExtendedTcpTable` and the owner's token SID; Node reads `netstat -anv` and `ps`
+on macOS, the same `/proc` files on Linux, and `netstat -ano` with the owner SID from PowerShell `GetOwnerSid` against `whoami /user` on Windows (SIDs, never names). Fail closed: everything but
+`this-account` refuses, `unknown` included.
+
+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),
+`check_dashboard_layout.mjs` before a local login code, and the launchd installers' poll (a listener of another account
+is never a successful install; 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
+twin reads the pid from `netstat` and the uid from `ps` a few milliseconds apart, so a pid reused in between would be
+misread; the Python twin's `sysctl` reader takes both from one record. A service's own loopback server refusing another account's peer (HA-3) is FAA-227, and the port
+claim file (HA-1) waits on the contract's CT-228.
+
 ## Semantic rules a host applies
 
 | Code | Rule |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -27,8 +27,10 @@
   (`auth.delegation-declared`). The kits verify the tokens: put `delegation_gate` /
   `delegationGate` in front of the tools (see [the delegation reference](delegation.md)).
 - Register it into a client config with the service's own command
-  (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
-  atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
+  (`<tool> mcp-register`), which first establishes that the port's listener is this OS account's (the contract's
+  DEC-0154 HA-2: `fabric_peer_owner.server_end` on a connection of its own, as `check_service.py`'s `listener.owner`
+  does; otherwise `foreign-user` and nothing is written), then writes
+  `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}` atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
   goes in `headers`, never in the URL: every log that records a URL prints its query
   string. An HTTP registration starts nothing per session: every client session talks to the
   one resident service (LC-19). A stdio server, by contrast, is a process per session; keep
@@ -39,7 +41,7 @@
 ## CLI for people and scripts
 
 `<tool> service status|start|stop|restart` (launchctl on the label, then the
-well-known document), `<tool> dashboard` (resolve the exact registered service with the `fabric-dashboards`
+well-known document from this OS account's listener, else `foreign-user`: protocol.md, The listener's owner), `<tool> dashboard` (resolve the exact registered service with the `fabric-dashboards`
 MCP, run `check_dashboard_link.py` on the action, then open its `open_link` with the host's `open` and
 `fallback=never`; never `open <url>`, `open -a Safari`, `xdg-open` or `webbrowser.open`; an installed host that
 failed is reported, never replaced by a browser; only a confirmed `not_installed` host permits an explicit browser
@@ -85,7 +87,7 @@ forbids, so it reads the card only and never calls an interface: an API-key sche
 - Created once with `ensure_token` at first start, after the instance lock.
 - Stored at the descriptor's `auth.tokenFile`, 0600, owner-checked, never a symlink.
 - Compared in constant time (`token_matches`).
-- Rotation is an operator act: write a new file, restart, re-run `mcp-register`.
+- Rotation is an operator act: write a new file, restart, re-run `mcp-register` (which checks the listener's owner again).
 - Same-user processes can read it. The protocol defends against web pages and
   mistakes, not against hostile code running as the operator; say so in SECURITY.md.
 

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

@@ -66,10 +66,12 @@ left out.
 it, and the host only shows it.
 
 **Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
-enforced or not, so the spend view shows all of them; the operator asked for that on 2026-10-07:
+enforced or not, so the spend view shows all of them; the operator asked for that on 2026-10-07. In Python
+`ledger.report` takes no `budgets`, so call `usage_report` over the ledger's receipts (Node's `ledger.report` passes
+them through):
 
 ```python
-ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+fabric_usage.usage_report(ledger.receipts(), service_id=ID, instance=INSTANCE, budget={"period": "month", "limitUsd": 100}, budgets=[
     {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
     {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
      "limitUsd": 5, "spentUsd": 0.31, "enforced": True},

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

@@ -94,7 +94,24 @@ async function serviceTarget(spec, dir) {
   const header = auth.header || 'Authorization';
   const value = (auth.scheme || 'Bearer') === 'Bearer' ? `Bearer ${token}` : token;
   const remote = d.placement === 'remote';
-  const wkRes = await fetch(`${origin}/.well-known/fabric-service`, { headers: remote && token ? { [header]: value } : {} });
+  // Only an https origin goes through fetch. Every other one, a local origin above all, is asked only on a connection
+  // whose server end is this OS account's process (DEC-0154 HA-2): fabric-http (beside this file in the kit) checks it
+  // before the token is sent, refuses with kind foreign-user, and refuses plain http to another host. The path follows
+  // the URL, never the descriptor's placement (0.74.0 unit reading 7: a "remote" descriptor naming 127.0.0.1 sent its
+  // token unchecked). A copy of this file alone cannot tell the owner, so it sends nothing to such an origin.
+  const viaKit = !/^https:\/\//i.test(origin);
+  let kitRequest = null;
+  if (viaKit) {
+    kitRequest = (await import('./fabric-http.mjs').catch(() => null))?.request;
+    if (!kitRequest) throw new Error('fabric-http.mjs and fabric-peer-owner.mjs are not beside this file: the local listener\'s owner cannot be told, so no token is sent (DEC-0154 HA-2)');
+  }
+  const call = !viaKit
+    ? async (method, url, headers) => { const r = await fetch(url, { method, headers }); return { status: r.status, ok: r.ok, json: () => r.json() }; }
+    : async (method, url, headers) => {
+      const r = await kitRequest(method, url, { headers, retries: 0, deadlineS: 10 });
+      return { status: r.status, ok: r.status >= 200 && r.status < 300, json: async () => r.json() };
+    };
+  const wkRes = await call('GET', `${origin}/.well-known/fabric-service`, remote && token ? { [header]: value } : {});
   if (!wkRes.ok) throw new Error(`well-known document answered HTTP ${wkRes.status}`);
   const wk = await wkRes.json();
   const dashboard = wk.surfaces?.dashboard;
@@ -103,7 +120,7 @@ async function serviceTarget(spec, dir) {
   let url = origin + dashboard.path;
   if (dashboard.login) {
     if (!token) throw new Error(`no readable token file for ${id}.${instance}`);
-    const res = await fetch(`${origin}/fabric/v1/login-code`, { method: 'POST', headers: { [header]: value } });
+    const res = await call('POST', `${origin}/fabric/v1/login-code`, { [header]: value });
     if (!res.ok) throw new Error(`login-code answered HTTP ${res.status}`);
     url = origin + (await res.json()).url;
   }

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

@@ -8,6 +8,13 @@
            --board-kit PATH                       (board.responder: the service's own fabric_board.py or fabric-board.mjs)
            --repo PATH                            (dashboard.opens-in-host: the service's checkout)
 
+A local placement is read only when this OS account's process holds its port (DEC-0154 HA-2): `listener.owner`
+comes before every rule that reads the port, from the computer's socket table (fabric_peer_owner). Nothing listening is NOT_RUN (`down`, and
+`well-known.answers` fails as before); another OS account's, root's or SYSTEM's listener, or one whose owner cannot be
+told, FAILs as `foreign-user`, and then no rule reads the port and no credential is sent; one `port.rules` NOT_RUN
+line names the rules not read (as it does when the well-known document gives nothing to read). Every local
+connection, a reconnect included, is checked again before a byte goes out on it.
+
 A remote placement (DEC-0019 — an online agent or dashboard at an https origin) is probed over
 TLS with the certificate verified: the well-known document must refuse a request without the
 token (401 with none of the service's data: an empty body, or an identity proxy's page, DEC-0109), the guards must refuse a foreign Host/Origin and cross-site requests,
@@ -72,6 +79,8 @@ import fabric_service as fs  # noqa: E402
 import fabric_connections as fcn  # noqa: E402
 from check_service_rules import shown_repository  # noqa: E402 - a repository in evidence carries no userinfo or query
 import fabric_interop as fi  # noqa: E402
+import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2: the listener's owner before any credential
+from check_service_rules import ForeignUser, PORT_RULES_UNREAD, listener_owner_verdict  # noqa: E402 - DEC-0154 HA-2
 
 Result = Dict[str, str]
 
@@ -153,13 +162,16 @@ class Probe:
                 conn = http.client.HTTPSConnection(self.host_name, self.port, context=context, timeout=8)
             base = {"Host": self.netloc}
         else:
-            conn = http.client.HTTPConnection("127.0.0.1", self.port, timeout=5)
+            # DEC-0154 HA-2: every local connection, a reconnect included, is checked before a byte is sent on it.
+            conn = po.CheckedHTTPConnection("127.0.0.1", self.port, timeout=5)
             base = {"Host": "127.0.0.1:%d" % self.port}
         base.update(headers or {})
         try:
             conn.request(method, path, body=body, headers=base)
             resp = conn.getresponse()
             return resp.status, merge_headers(resp.getheaders()), resp.read()
+        except po.ListenerRefused as exc:
+            raise ForeignUser("foreign-user: %s" % exc) from None
         finally:
             conn.close()
 
@@ -168,6 +180,14 @@ class Probe:
         name, value = fs.token_header(self.d.get("auth"), self.token or "")
         return {name: value}
 
+    # the listener's owner (DEC-0154 HA-2) -------------------------------
+    def listener_rule(self) -> bool:
+        """DEC-0154 HA-2, `down` then `foreign-user` then the answer (check_service_rules.listener_owner_verdict). False
+        when the port must not be read (`foreign-user`)."""
+        verdict, evidence = listener_owner_verdict(self.port)
+        self.add("listener.owner", verdict, evidence)
+        return verdict != "FAIL"
+
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:
         problems = fs.validate_descriptor(self.d)
@@ -200,7 +220,7 @@ class Probe:
         elif "origin" not in self.d:
             unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
         else:
-            unique = "port %d is unique" % self.port
+            unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % self.port
         self.add("descriptor.port-claim", "FAIL" if clashes else "PASS", "; ".join(clashes) or unique)
         # FAA-198: the repository that links the agent to its project; a new install is refused without it, an installed one
         # is named here (NOT_RUN is no pass) until its owner adds it.
@@ -261,6 +281,12 @@ class Probe:
                 self.add_no_token(no_token, None)
             self.add("well-known.answers", "FAIL", "body is not JSON")
             return
+        if not isinstance(self.wk, dict):
+            self.wk = None
+            if self.remote:
+                self.add_no_token(no_token, None)
+            self.add("well-known.answers", "FAIL", "body is not a JSON object")
+            return
         if self.remote:
             self.add_no_token(no_token, self.wk)
         self.add("well-known.answers", "PASS", "HTTP 200")
@@ -899,8 +925,16 @@ class Probe:
             return self.results
         if not self.port:
             return self.results
+        if not self.remote and not self.listener_rule():
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because the listener is not this OS "
+                     "account's (listener.owner FAIL, DEC-0154 HA-2)")
+            self.lifecycle_rules()
+            return self.results
         self.well_known_rules()
-        if self.wk is not None:
+        if self.wk is None:
+            self.add("port.rules", "NOT_RUN", "not read: " + PORT_RULES_UNREAD + ", because well-known.answers above "
+                     "got no document to read")
+        else:
             self.network_rules()
             self.auth_rules()
             self.usage_rules()

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

@@ -20,6 +20,44 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402 - beside this file
 from fabric_http import redact_url  # noqa: E402
 from fabric_secrets import ascii_decoded, repository_name, secret_argument  # noqa: E402
+import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2
+import socket  # noqa: E402
+
+
+# The rules that ask the service's port, named on one NOT_RUN line when none of them can be read (0.74.0 product
+# reading 8): a probe names what it could not check.
+PORT_RULES_UNREAD = ("every rule that reads the port (well-known, network, auth, usage, A2A, dashboard, login, "
+                     "interop, channel-agent, board)")
+
+
+class ForeignUser(ConnectionError):
+    """DEC-0154 HA-2: the server end of a local connection is not this OS account's process (`foreign-user`); nothing
+    was sent on it. A ConnectionError, so every rule that reads the port reports it as no answer."""
+
+
+def listener_owner_verdict(port: int) -> Tuple[str, str]:
+    """`listener.owner` for a local service: (verdict, evidence). `down`, then `foreign-user`, then everything the
+    listener answers: a local service is read only when this OS account's process holds its port. The owner is the
+    server end of a connection of the probe's own, on which nothing is sent (HA-2's source: the client's own connection;
+    two sockets of one account on one port, as SO_REUSEPORT workers hold, read as that account)."""
+    where = "127.0.0.1:%d" % port
+    try:
+        sock = socket.create_connection(("127.0.0.1", port), timeout=5)
+    except ConnectionRefusedError:
+        return "NOT_RUN", "nothing listens on %s (down)" % where
+    except OSError as exc:  # a full backlog, a timeout: the well-known rule reports what answers, each call checked
+        return "NOT_RUN", "could not connect to %s to tell its owner (%s)" % (where, type(exc).__name__)
+    try:
+        owner = po.server_end(sock)
+    finally:
+        sock.close()
+    if owner.kind == po.THIS_ACCOUNT:
+        return "PASS", "%s is held by this OS account's process (pid %s, read by %s)" % (
+            where, owner.pid if owner.pid is not None else "not shown", owner.method)
+    why = {po.ANOTHER_ACCOUNT: "another OS account's process", po.SYSTEM: "a system account's process"}.get(
+        owner.kind, "a process whose owner cannot be told (%s)" % owner.reason)
+    return "FAIL", ("foreign-user: %s is held by %s (read by %s); no credential was sent and nothing it answers is read "
+                    "as this service's" % (where, why, owner.method))
 
 _LOCAL_PATH = re.compile(r"[/~.\\]|[A-Za-z]:[/\\]")  # how a local path starts, never a user before an `@`
 _SCP_HOST = re.compile(r"[^@/:\\]+:")  # what follows the `@` of user[:password]@host:path

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

@@ -9,12 +9,17 @@
 // is safe: an idempotent method or an `Idempotency-Key` header; any other request only on 429. The wait before retry n
 // (from 0) is min(maxBackoffS, backoffBaseS * 2**n) * (0.5 + rand()); a `Retry-After` replaces it up to
 // maxRetryAfterS. A wait past the deadline is not taken. Plain http is refused unless the host is loopback or
-// `insecure`. An error names the method and the redacted URL, never a header or a body.
+// `insecure`. An error names the method and the redacted URL, never a header or a body. Before a byte goes to a plain
+// http loopback URL the server end of the connection is told from the socket table (DEC-0154 HA-2, FAA-226): not this
+// OS account's process, or an owner that cannot be told, is an HttpError of kind foreign-user, nothing sent, not retried.
 //
 // 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).
 
+import http from 'node:http';
+import { CheckedAgent, ListenerRefused } 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']);
 export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
@@ -30,7 +35,7 @@ export class HttpError extends Error {
     this.attempts = attempts;
     this.retryAfterS = retryAfterS;
     this.body = body.slice(0, 2048);
-    this.kind = kind; // http, connection, timeout, too-large, refused
+    this.kind = kind; // http, connection, timeout, too-large, refused, foreign-user
   }
 }
 
@@ -147,8 +152,53 @@ function checkHeaders(headers) {
   return out;
 }
 
-// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes.
+const LOOPBACK_AGENT = new CheckedAgent();
+
+// Plain http to a loopback host (DEC-0154 HA-2): node:http over a connection checked before a byte is written, no
+// redirect followed, the body read to one byte past maxBytes. fetch cannot hand its socket to the check.
+export function checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes, agent = LOOPBACK_AGENT }) {
+  const parts = new URL(url);
+  // A body goes with its Content-Length, as fetch sent it: a server that reads only Content-Length (the kit's
+  // sample_service, the stdlib handlers) would read a chunked body as empty (0.74.0 seam reading 1).
+  const sent = { ...headers };
+  if (body && !Object.keys(sent).some((k) => k.toLowerCase() === 'content-length')) sent['Content-Length'] = String(body.length);
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: parts.hostname.replace(/^\[|\]$/g, ''), port: Number(parts.port || 80),
+      path: parts.pathname + parts.search, method, headers: sent, agent }, (res) => {
+      const chunks = [];
+      let size = 0;
+      res.on('data', (c) => {
+        if (size <= maxBytes) { chunks.push(c); size += c.length; }
+        if (size > maxBytes) res.destroy();
+      });
+      res.on('close', () => {
+        clearTimeout(timer);
+        const all = Buffer.concat(chunks);
+        const got = Object.fromEntries(Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : String(v)]));
+        if (!res.complete && size <= maxBytes) reject(Object.assign(new Error('the answer broke off'), { name: 'ConnectionError' }));
+        else resolve({ status: res.statusCode, headers: got, body: new Uint8Array(all.subarray(0, maxBytes + 1)) });
+      });
+    });
+    const timer = setTimeout(() => req.destroy(Object.assign(new Error('timed out'), { name: 'TimeoutError' })),
+      Math.max(1, Math.ceil(timeoutS * 1000)));
+    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' }));
+      } else reject(err);
+    });
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http to a
+// loopback host goes through checkedLoopbackTransport.
 export async function fetchTransport({ method, url, headers, body, timeoutS, maxBytes }) {
+  const target = new URL(url);
+  if (target.protocol === 'http:' && isLoopback(target.hostname)) {
+    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes });
+  }
   const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
     signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });
   const chunks = [];

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

@@ -6,7 +6,9 @@
 //    $XDG_DATA_HOME/passioncode-fabric) the way Fabric's own locateHub does: a small regular file, never a link or a
 //    FIFO; protocol fabric-hub/0.1; origin exactly http://127.0.0.1:<port>; MCP at /mcp; a door token file inside the
 //    registry root; a pid that is alive. The port does not prove who holds it, so a binding credential is sent only
-//    after this check passes, done again before each send.
+//    after this check passes, done again before each send. The pid is never the proof (DEC-0154 HA-2): every
+//    connection to the door is checked from the socket table before a byte goes out (fabric-peer-owner.mjs), and a
+//    listener of another OS account, or one whose owner cannot be told, is HubError foreign-user with nothing sent.
 // 2. Ask once, keep the credential in a file: requestBoardAccess() asks for the board.respond grant through the door;
 //    pollAccess() writes the credential, shown once, to a 0600 file and answers without it. Tokens live in files and
 //    headers only — never argv, a URL, a log line or an error text.
@@ -25,6 +27,12 @@ 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';
+
+// 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
+// keep-alive timeout (5 s in Node) can close it under a request that reuses it.
+const HUB_AGENT = new CheckedAgent({ keepAlive: true, timeout: 2000 });
 
 export const HUB_PROTOCOL = 'fabric-hub/0.1';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
@@ -158,9 +166,10 @@ export function readCredential(file) {
 /**
  * One MCP request to <origin>/mcp with a bearer in the header; only http://127.0.0.1:<port>, no proxy. Answers
  * {status, headers, body} (body parsed JSON or null; an SSE answer read to its first data: line). A refused connection
- * is HubError hub-unavailable (retryable).
+ * is HubError hub-unavailable (retryable); a listener that is not this OS account's process is HubError foreign-user
+ * (retryable) before the bearer is sent (DEC-0154 HA-2): the connection is checked from the socket table first.
  */
-export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion } = {}) {
+export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT } = {}) {
   const m = LOOPBACK_ORIGIN.exec(origin);
   if (!m) return Promise.reject(new HubError('not-a-hub', 'Only the hub\'s loopback origin is used.'));
   const payload = method === 'DELETE' ? null : Buffer.from(JSON.stringify(body));
@@ -169,7 +178,7 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
   if (protocolVersion) headers['mcp-protocol-version'] = protocolVersion;
   if (payload) headers['content-length'] = String(payload.length);
   return new Promise((resolve, reject) => {
-    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/mcp', method, headers, timeout, agent: false }, (res) => {
+    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/mcp', method, headers, timeout, agent }, (res) => {
       const chunks = [];
       let size = 0;
       res.on('data', (c) => {
@@ -192,7 +201,9 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
       res.on('error', () => reject(new HubError('hub-unavailable', 'Fabric\'s hub did not answer (the answer broke off).', true)));
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
-    req.on('error', (e) => reject(new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
+    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)
+      : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
     if (payload) req.write(payload);
     req.end();
   });