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

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

@@ -45,7 +45,7 @@ import http from 'node:http';
 import net from 'node:net';
 import os from 'node:os';
 
-export const PEER_OWNER_VERSION = '1.1.0+kit.1'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.1.0+kit.3'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
 export const THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -58,6 +58,10 @@ export const WINDOWS_TIMEOUT_MS = 5000;
 export const LISTENER_TTL_MS = 1000;
 export const NETSTAT = '/usr/sbin/netstat';
 export const PS = '/bin/ps';
+export const LSOF = '/usr/sbin/lsof';
+// The reason a socket table hides other processes' sockets from this one (FAA-267): macOS 27.2 gives an ad-hoc-signed
+// runtime an empty netstat.
+export const TABLE_RESTRICTED = 'table-restricted';
 export const SERVER_NOT_OWN = 'server-not-own';
 export const SERVER_UNVERIFIED = 'server-unverified';
 export const SERVER_NOT_THIS_WORKSPACE = 'server-not-this-workspace';
@@ -143,6 +147,7 @@ function netstatAddress(text) {
 // leading and the trailing columns, both counted from the header; a header without process:pid is unreadable.
 export function parseNetstat(text) {
   const lines = String(text).split(/\r?\n/);
+  if (!lines.some((line) => line.trim())) throw new TableUnreadable(`${TABLE_RESTRICTED}: netstat printed nothing to this process`);
   const header = lines.findIndex((line) => line.includes('process:pid') && line.includes('Proto'));
   if (header < 0) throw new TableUnreadable('netstat-format: no process:pid column');
   const names = lines[header].split(/\s+/).filter(Boolean);
@@ -165,6 +170,18 @@ export function parseNetstat(text) {
   return rows;
 }
 
+// `lsof -nP -a -p PID -i4TCP -sTCP:LISTEN -Fn`: the `n` lines, 127.0.0.1:47480, *:47480 or [::1]:47480.
+export function parseLsofListeners(text) {
+  const found = [];
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!line.startsWith('n') || !line.includes(':')) continue;
+    const at = line.lastIndexOf(':');
+    const port = line.slice(at + 1);
+    if (/^[0-9]+$/.test(port)) found.push([normHost(line.slice(1, at).replace(/^\[|\]$/g, '')), Number(port)]);
+  }
+  return found;
+}
+
 // `ps -o uid= -p PID`: one number, or nothing when the process is gone.
 export function parsePsUid(text) {
   const t = String(text).trim();
@@ -497,10 +514,25 @@ export function refusal(who, port, expectPid = null) {
   return null;
 }
 
+// macOS, when the socket table is restricted (FAA-267): whether process `pid`, this account's, listens on 127.0.0.1:<port>
+// or the IPv4 wildcard (IPv4 alone: a v6-only wildcard never vouches for a 127.0.0.1 connection). `lsof -p` asks the process itself, which the restriction does not hide. Only a caller that started
+// `pid` itself (a launchd job it installed) may vouch with it.
+export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine } = {}) {
+  if (platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
+    if (uid === null || uid !== (mine ?? ownUid())) return false;
+    const out = await run(LSOF, ['-nP', '-a', '-p', String(pid), '-i4TCP', '-sTCP:LISTEN', '-Fn']);
+    return parseLsofListeners(out).some(([host, p]) => (host === '127.0.0.1' || host === '*') && p === port);
+  } catch {
+    return false;
+  }
+}
+
 // A connected socket to host:port whose server end is this account's (and, with expectPid, that process's). The check
 // runs on the very socket the caller then writes on, so no listener can change between the check and the request.
 // Rejects with ListenerRefused (the socket destroyed, nothing written) or with the connection's own error.
-export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, expectPid = null, ...ask } = {}) {
+export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, expectPid = null, vouchPid = null, ...ask } = {}) {
   return new Promise((resolveSocket, reject) => {
     const socket = net.connect({ host, port, noDelay: true }); // as a plain http.Agent's socket
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), timeoutMs);
@@ -515,6 +547,11 @@ export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, exp
         // A reader that throws (an injected one; the readers themselves answer unknown) fails closed.
         who = owner(UNKNOWN, { method: method(), reason: `check: ${err?.name ?? 'Error'}` });
       }
+      if (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED) && vouchPid
+        && await pidListens(vouchPid, port, ask)) {
+        // The table hides other processes (FAA-267); the process this caller started holds the listener.
+        who = owner(THIS_ACCOUNT, { uid: ask.ownUid ?? ownUid(), pid: vouchPid, method: 'lsof-pid' });
+      }
       const refused = refusal(who, port, expectPid);
       if (refused) {
         socket.destroy();
@@ -532,14 +569,15 @@ export function checkedSocket(port, { host = '127.0.0.1', timeoutMs = 10000, exp
 // when it is made. A refusal reaches the request as its 'error', a ListenerRefused. Free sockets do not keep the process
 // alive (Node unrefs them).
 export class CheckedAgent extends http.Agent {
-  constructor({ expectPid = null, ask = {}, ...options } = {}) {
+  constructor({ expectPid = null, vouchPid = null, ask = {}, ...options } = {}) {
     super(options);
     this.expectPid = expectPid;
+    this.vouchPid = vouchPid;
     this.ask = ask;
   }
 
   createConnection(options, callback) {
     checkedSocket(Number(options.port), { host: options.host ?? '127.0.0.1', timeoutMs: options.timeout ?? 10000,
-      expectPid: this.expectPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
+      expectPid: this.expectPid, vouchPid: this.vouchPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
   }
 }

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

@@ -148,6 +148,7 @@ export {
   cookieValue,
 } from './fabric-auth.mjs';
 export {
+  LEVEL_ALIASES,
   LEVELS,
   EVENTS_DEFAULT_LIMIT,
   EVENTS_MAX_LIMIT,
@@ -177,6 +178,7 @@ export {
   taskUninstall,
   launchdPlist,
   launchdLoaded,
+  launchdPid,
   launchdOverride,
   launchdInstall,
   launchdUninstall,

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

@@ -9,7 +9,7 @@ import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabri
 import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 import http from 'node:http';
 
 export const DEFAULT_EXIT_TIMEOUT = 15;
@@ -55,13 +55,22 @@ function noMarkerArgument(argv) {
   if (markerArguments(argv).length) throw new ServiceError(`${SUPERVISOR_ARG} is written by the supervisor file's writer; leave it out of the program arguments.`);
 }
 
+// An environment value: read path-aware (secretArgument) only when it reads as a path (it starts as one, has at least two
+// separators and a lower-case word between them), so a release folder under Application Support is no key (FAA-266) while
+// a base64 key whose `/` splits it stays one; any other value keeps the strict secretValue.
+const secretEnvValue = (value) => {
+  const pieces = value.split(/[\\/]/);
+  const path = /^(?:[/~.]|[A-Za-z]:[\\/])/.test(value) && pieces.length >= 3 && pieces.some((x) => /^[a-z][a-z0-9_-]{2,}$/.test(x));
+  return path ? secretArgument(value) : secretValue(value);
+};
+
 function noSecretInSupervisorFile(argv, environment) {
   // No supervisor file carries a secret (service.md): not in an argument, an environment name or its value.
   for (const arg of argv) {
     if (secretArgument(arg)) throw new ServiceError('An argument carries a credential; a supervisor file never does (read it from the token file or a secret reference).');
   }
   for (const [name, value] of Object.entries(environment ?? {})) {
-    if (credentialName(name) || secretValue(String(value))) throw new ServiceError(`Environment ${name} looks like a credential; a supervisor file never carries one.`);
+    if (credentialName(name) || secretEnvValue(String(value))) throw new ServiceError(`Environment ${name} looks like a credential; a supervisor file never carries one.`);
   }
 }
 
@@ -264,7 +273,7 @@ export function launchdPlist(label, programArguments, { workingDirectory, stdout
   const env = { ...environment };
   for (const [name, value] of Object.entries(env)) {
     if (/(TOKEN|SECRET|PASSWORD|KEY)$/.test(name) && !name.endsWith('_FILE')) throw new ServiceError(`Environment variable ${name} looks like a secret; pass a *_FILE path instead.`);
-    if (secretValue(String(value))) throw new ServiceError(`Environment ${name} holds a value shaped like a credential; a plist never carries one.`);
+    if (secretEnvValue(String(value))) throw new ServiceError(`Environment ${name} holds a value shaped like a credential; a plist never carries one.`);
   }
   for (const arg of argv) {
     if (secretArgument(arg)) throw new ServiceError('An argument carries a credential; a plist never does (read it from the token file or a secret reference).');
@@ -302,6 +311,14 @@ export function launchdLoaded(label, { run = defaultRun, platform = process.plat
   return run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`])?.status === 0;
 }
 
+// The running pid of this account's launchd job `label`, or null (not running, or not readable).
+export function launchdPid(label, { run = defaultRun, platform = process.platform, uid } = {}) {
+  const result = run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`]);
+  if (result?.status !== 0) return null;
+  const hit = /^\s*pid\s*=\s*([0-9]+)\s*$/m.exec(String(result.stdout ?? ''));
+  return hit ? Number(hit[1]) : null;
+}
+
 const OVERRIDE_ROW = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/;
 
 /**
@@ -326,7 +343,7 @@ export class ForeignUserAnswer {
 // The well-known answer at a loopback origin, read only on a connection whose server end is this OS account's process
 // (DEC-0154 HA-2): null when nothing answers or the answer is not JSON, a ForeignUserAnswer when the listener is another
 // account's or its owner cannot be told.
-export async function wellKnownOf(origin) {
+export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   const m = /^http:\/\/127\.0\.0\.1:([0-9]{1,5})$/.exec(origin);
   if (!m) {
     try {
@@ -338,7 +355,7 @@ export async function wellKnownOf(origin) {
   }
   // A CheckedAgent without keep-alive: the request goes on the very socket it checked, and the socket closes after the
   // answer, so a poll leaves no connection open behind it.
-  const agent = new CheckedAgent({ keepAlive: false });
+  const agent = new CheckedAgent({ keepAlive: false, vouchPid });
   return new Promise((resolve) => {
     const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/.well-known/fabric-service', agent,
       timeout: 2000 }, (res) => {
@@ -350,7 +367,9 @@ export async function wellKnownOf(origin) {
       res.on('error', () => resolve(null));
     });
     req.on('timeout', () => req.destroy());
-    req.on('error', (err) => resolve(err instanceof ListenerRefused ? new ForeignUserAnswer(`foreign-user: ${err.message}`) : null));
+    req.on('error', (err) => resolve(err instanceof ListenerRefused
+      ? new ForeignUserAnswer(`${String(err.owner?.reason ?? '').startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : 'foreign-user'}: ${err.message}`)
+      : null));
     req.end();
   }).finally(() => agent.destroy());
 }
@@ -390,13 +409,18 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   }
   const deadline = Date.now() + timeout * 1000;
   let foreign = null;
+  let vouchPid = null;
   while (Date.now() < deadline) {
-    const doc = await fetchWellKnown(origin);
+    const doc = await fetchWellKnown(origin, { vouchPid });
     foreign = doc instanceof ForeignUserAnswer ? doc.reason : null;
+    if (foreign?.startsWith(TABLE_RESTRICTED)) vouchPid = launchdPid(label, opts); // only a restricted table needs it (FAA-267)
     if (!foreign && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
     await sleep(500);
   }
   // DEC-0154 HA-2 and service.md's Install row: a listener of another account is never a successful install.
+  if (foreign?.startsWith(TABLE_RESTRICTED)) {
+    throw new ServiceError(`${origin} could not be proved this service's: ${foreign} (DEC-0154 HA-2); this runtime sees no other process's sockets and the job's pid did not show the listener: run the installer from a runtime that sees them, or read the job's log.`);
+  }
   if (foreign) {
     throw new ServiceError(`${origin} is not this service's: ${foreign} (DEC-0154 HA-2); the port is another OS account's or its owner cannot be told.`);
   }

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import re
+from types import MappingProxyType
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
@@ -33,6 +34,10 @@ EVENTS_MAX_LIMIT = 200
 LEVELS = ("info", "notice", "warning", "error")
 
 
+# The dashboard kit names its chip `warn`; an event written at that name is stored at the feed's `warning` (FAA-276).
+LEVEL_ALIASES = MappingProxyType({"warn": "warning"})
+
+
 _KIND = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,5}\Z")
 
 
@@ -45,13 +50,15 @@ _SPAN_ID = re.compile(r"^(?!0{16}\Z)[0-9a-f]{16}\Z")
 def make_event(event_id: Any, at: str, kind: str, level: str, text: str, *, subject: Optional[Dict[str, str]] = None,
                link: Optional[str] = None, notify: bool = False, trace_id: Optional[str] = None,
                span_id: Optional[str] = None, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """One activity event: one sentence a person reads, never a machine id. `data` (DEC-0070) adds machine-readable
+    """One activity event: one sentence a person reads, never a machine id. `level` is one of `LEVELS`; `warn`, the
+    dashboard chip's name, is stored as `warning`. `data` (DEC-0070) adds machine-readable
     fields beside the sentence, `{schema, value}`, never a secret: it is refused here, so no feed carries one.
 
     An event about traced work carries its trace as a pair, `trace_id` and `span_id`
     (fabric-interop/0.1 C3.4 c); fabric_interop.trace_ids(traceparent) gives both."""
+    level = LEVEL_ALIASES.get(level, level) if isinstance(level, str) else level
     if level not in LEVELS:
-        raise ServiceError("level must be one of %s." % ", ".join(LEVELS))
+        raise ServiceError("level must be one of %s (or `warn` for `warning`)." % ", ".join(LEVELS))
     if not _KIND.match(kind):
         raise ServiceError("kind %r must be dotted lowercase." % kind)
     text = " ".join(str(text).split())

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

@@ -354,6 +354,7 @@ class _CheckedHTTPConnection(_po.CheckedHTTPConnection):
                  **kwargs: Any) -> None:
         http.client.HTTPConnection.__init__(self, host, port, timeout=timeout, **kwargs)
         self.expect_pid = None
+        self.vouch_pid = None  # a loopback URL is never a process this caller started (FAA-267)
 
 
 def _opener(watchdog: _Watchdog, direct: bool = False) -> urllib.request.OpenerDirector:

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

@@ -1,6 +1,6 @@
 """peer_owner: which OS account owns each end of a loopback TCP connection.
 
-    peer_owner 1.1.0+kit.1: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
+    peer_owner 1.1.0+kit.3: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
     DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py` at
     commit f86f0622 (passioncode-ai/project-observatory-dashboard, the same licence). It differs
     from that file in this paragraph, in `Owner` and `Row` (NamedTuples here where it has
@@ -15,7 +15,11 @@
     row with inode 0 (a closed client) as unknown, and several rows of one owner are that owner;
     a row printed twice by a `/proc` read under churn counts once, and a `/proc` question that
     finds no row or several reads the table once more; ctypes is imported where it is used, so a
-    Python without it reads netstat on macOS and imports the module everywhere.
+    Python without it reads netstat on macOS and imports the module everywhere. Since kit.2 (FAA-267), on
+    macOS: the sysctl calibration also requires a child process's listener, an empty netstat reads as
+    `TABLE_RESTRICTED`, and a caller may vouch for a listener with a pid it started (`pid_listens`,
+    `parse_lsof_listeners`, `LSOF`, `CheckedHTTPConnection(vouch_pid=...)`, `own_connection(vouch_pid=...)`); since kit.3
+    the child's port is waited on with `selectors` and read under one deadline (FAA-273).
     A limit /proc sets: it carries a socket's creator and no pid, so a listening socket that root
     created and handed to another account (systemd socket activation with User=) reads as root's. Standard library only, no import of another kit module.
     The kit's tests are `test/test_fabric_peer_owner.py`, over `test/fixtures/peer-owner/`;
@@ -64,6 +68,12 @@ addresses are `unknown` (`several-rows`), never a guess.
   accept) and the listener and both ends of the pair must read back with their exact addresses,
   this process's uid and its pid. A layout that fails calibration is not used again in that
   process.
+- macOS 27.2 restricts both tables for an ad-hoc-signed interpreter (a Homebrew Python, measured on 2026-11-07 on a
+  host agent's Mac): sysctl lists only this process's own sockets and netstat prints nothing. The calibration therefore
+  also requires a child process's listener, and an empty netstat is `unknown` with reason `table-restricted`, never
+  another account's (FAA-267). A caller that started the server itself (an installer and its launchd job) may vouch
+  with that pid: `lsof -p PID` asks the process, which the restriction leaves readable, and `CheckedHTTPConnection`
+  accepts its listener on the port as this account's (`vouch_pid`). Apple's own `/usr/bin/python3` sees the tables.
 - macOS, fallback (`netstat`): `/usr/sbin/netstat -anv -p tcp`, its `process:pid` column, then
   `ps -o uid= -p PID` for the owner of the one row a question needs. Measured: about 20 ms over
   846 sockets, and it names the pids of root's listeners, which `lsof` run by an ordinary account
@@ -100,7 +110,7 @@ import time
 from typing import NamedTuple, Optional, Tuple
 
 # This file's own version, for projects that copy it; not the engine's (that is configuration.VERSION).
-PEER_OWNER_VERSION = "1.1.0+kit.1"  # Observatory's 1.1.0 with the kit's differences above
+PEER_OWNER_VERSION = "1.1.0+kit.3"  # Observatory's 1.1.0 with the kit's differences above
 
 THIS_ACCOUNT = "this-account"
 ANOTHER_ACCOUNT = "another-account"
@@ -120,6 +130,11 @@ LISTENER_TTL = 1.0
 
 NETSTAT = "/usr/sbin/netstat"
 PS = "/bin/ps"
+LSOF = "/usr/sbin/lsof"
+
+#: The reason a socket table hides other processes' sockets from this one (FAA-267: macOS 27.2 shows an ad-hoc-signed
+#: interpreter, such as a Homebrew Python, only its own sockets through sysctl and nothing through netstat).
+TABLE_RESTRICTED = "table-restricted"
 
 #: Client codes of `own_connection` (ListenerRefused.code).
 SERVER_NOT_OWN = "server-not-own"
@@ -221,6 +236,8 @@ def parse_netstat(text: str) -> list[Row]:
     `process:pid` column is what is left between the leading and the trailing columns, both
     counted from the header. A header without `process:pid` (an older macOS) is unreadable."""
     lines = text.splitlines()
+    if not any(line.strip() for line in lines):
+        raise TableUnreadable(f"{TABLE_RESTRICTED}: netstat printed nothing to this process")
     header = next((i for i, line in enumerate(lines) if "process:pid" in line and "Proto" in line), None)
     if header is None:
         raise TableUnreadable("netstat-format: no process:pid column")
@@ -259,6 +276,18 @@ def _netstat_address(text: str) -> Optional[tuple[str, int]]:
         return None
 
 
+def parse_lsof_listeners(text: str) -> list[tuple[str, int]]:
+    """`lsof -nP -a -p PID -i4TCP -sTCP:LISTEN -Fn`: the `n` lines, `127.0.0.1:47480`, `*:47480` or `[::1]:47480`."""
+    found: list[tuple[str, int]] = []
+    for line in text.splitlines():
+        if not line.startswith("n") or ":" not in line:
+            continue
+        host, port = line[1:].rsplit(":", 1)
+        if port.isdigit():
+            found.append((norm_host(host.strip("[]")), int(port)))
+    return found
+
+
 def parse_ps_uid(text: str) -> Optional[int]:
     """`ps -o uid= -p PID`: one number, or nothing when the process is gone."""
     text = text.strip()
@@ -468,10 +497,75 @@ def calibration_holds(rows: list[Row], server: tuple[str, int], client: tuple[st
     return (one(server, ("*", 0), True) and one(server, client, False) and one(client, server, False))
 
 
+_CHILD_LISTENER = ("import socket,sys\ns=socket.socket();s.bind(('127.0.0.1',0));s.listen(1)\n"
+                   "print(s.getsockname()[1],flush=True);sys.stdin.read()")
+
+
+def _child_line(child: "subprocess.Popen[bytes]", deadline: float) -> Optional[bytes]:
+    """The child's first line, or None when no newline came by `deadline`. It waits with `selectors` (kqueue on
+    macOS: no FD_SETSIZE ceiling at fd 1024, which `select.select` refuses) and reads what is there, so a partial line
+    from an interpreter that then waits cannot hold the caller past the deadline (FAA-273 item 13, and the `selectors`
+    half of item 11)."""
+    import selectors  # POSIX: this reader runs on macOS alone
+    got = b""
+    try:
+        with selectors.DefaultSelector() as sel:
+            sel.register(child.stdout, selectors.EVENT_READ)
+            while b"\n" not in got and len(got) < 64:
+                left = deadline - time.monotonic()
+                if left <= 0 or not sel.select(left):
+                    return None
+                chunk = os.read(child.stdout.fileno(), 64)
+                if not chunk:
+                    return None
+                got += chunk
+    except (OSError, ValueError):
+        return None
+    return got.split(b"\n", 1)[0] if b"\n" in got else None
+
+
+def _child_listener_seen(rows_of) -> Optional[bool]:
+    """Whether the table shows a listener of a child process of this one: False when it does not (the table shows
+    this process alone, FAA-267), None when no child could be started (a frozen or embedded host has no interpreter to
+    start), or it gave no port line within TIMEOUT_SECONDS (silence, a partial or non-numeric line, an early exit, a
+    pipe that cannot be read). The calibration trusts only True."""
+    if not sys.executable or getattr(sys, "frozen", False):
+        return None
+    try:
+        child = subprocess.Popen([sys.executable, "-I", "-c", _CHILD_LISTENER], stdin=subprocess.PIPE,
+                                 stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+    except OSError:
+        return None
+    deadline = time.monotonic() + TIMEOUT_SECONDS
+    port = None
+    try:
+        line = _child_line(child, deadline)
+        if line is None or not line.strip().isdigit():
+            return None
+        port = int(line.strip())
+        try:
+            return any(r.listening and r.local == ("127.0.0.1", port) and r.pid == child.pid for r in rows_of())
+        except (TableUnreadable, OSError, struct.error, ValueError):
+            return False
+    finally:
+        # One deadline for the whole check: a child that gave no port is killed at once, and one that did gets what is
+        # left of the deadline to exit on its closed stdin before it is killed.
+        try:
+            child.stdin.close()
+            if port is None:
+                child.kill()
+            child.wait(timeout=max(0.0, deadline - time.monotonic()))
+        except (OSError, subprocess.TimeoutExpired):
+            child.kill()
+            child.wait()
+        child.stdout.close()
+
+
 def _calibrate_sysctl() -> bool:
     """Open a connected pair of this process's own (listen, connect, accept) and read it back
-    (`calibration_holds`). A layout that does not hold is never trusted in this process, and
-    `netstat` answers instead."""
+    (`calibration_holds`), then require a child process's listener in the table too: a table that shows this process
+    alone (FAA-267) would pass the first check and find nobody else. A layout that does not hold is never trusted in
+    this process, and `netstat` answers instead."""
     probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     client = accepted = None
     try:
@@ -480,8 +574,10 @@ def _calibrate_sysctl() -> bool:
         client = socket.create_connection(probe.getsockname(), timeout=TIMEOUT_SECONDS)
         accepted, _ = probe.accept()
         rows = parse_pcblist_n(_sysctl_blob())
-        return calibration_holds(rows, _address(probe.getsockname()), _address(client.getsockname()),
-                                 uid=_posix_uid(), pid=os.getpid())
+        if not calibration_holds(rows, _address(probe.getsockname()), _address(client.getsockname()),
+                                 uid=_posix_uid(), pid=os.getpid()):
+            return False
+        return _child_listener_seen(lambda: parse_pcblist_n(_sysctl_blob())) is True
     except (TableUnreadable, OSError, struct.error, ValueError):
         return False
     finally:
@@ -805,6 +901,23 @@ def refusal(owner: Owner, port: int, expect_pid: Optional[int] = None) -> Option
     return None
 
 
+def pid_listens(pid: int, port: int) -> bool:
+    """macOS, when the socket table is restricted (FAA-267): whether process `pid`, this account's, listens on
+    127.0.0.1:<port> or the IPv4 wildcard (IPv4 alone: a v6-only wildcard never vouches for a 127.0.0.1 connection).
+    `lsof -p` asks the process itself (libproc), which the restriction does not hide. Only a caller that started `pid`
+    itself (a launchd job it installed) may vouch with it."""
+    if sys.platform != "darwin" or not isinstance(pid, int) or isinstance(pid, bool) or pid <= 1:
+        return False
+    try:
+        uid = parse_ps_uid(_run([PS, "-o", "uid=", "-p", str(pid)]))
+        if uid is None or uid != _posix_uid():
+            return False
+        out = _run([LSOF, "-nP", "-a", "-p", str(pid), "-i4TCP", "-sTCP:LISTEN", "-Fn"])
+    except TableUnreadable:
+        return False
+    return any(host in ("127.0.0.1", "*") and p == port for host, p in parse_lsof_listeners(out))
+
+
 class CheckedHTTPConnection(http.client.HTTPConnection):
     """An `http.client.HTTPConnection` whose every `connect()` checks the server end before
     returning. `http.client` connects again by itself (`auto_open`) when the server answered
@@ -812,9 +925,11 @@ class CheckedHTTPConnection(http.client.HTTPConnection):
     different listener; so the check is in `connect()`, not once in `own_connection`. A refused
     connect closes the socket and raises ListenerRefused before any byte of a request is sent."""
 
-    def __init__(self, host: str, port: int, *, expect_pid: Optional[int] = None, timeout: float = 10.0) -> None:
+    def __init__(self, host: str, port: int, *, expect_pid: Optional[int] = None, timeout: float = 10.0,
+                 vouch_pid: Optional[int] = None) -> None:
         super().__init__(host, port, timeout=timeout)
         self.expect_pid = expect_pid
+        self.vouch_pid = vouch_pid
 
     def set_tunnel(self, *args, **kwargs):  # noqa: D401 - a tunnel would put a proxy's socket under the check
         raise ListenerRefused(SERVER_UNVERIFIED, "a tunnel would check the proxy, not the server; nothing was sent")
@@ -822,6 +937,10 @@ class CheckedHTTPConnection(http.client.HTTPConnection):
     def connect(self) -> None:
         super().connect()
         owner = server_end(self.sock)
+        if (owner.kind == UNKNOWN and (owner.reason or "").startswith(TABLE_RESTRICTED) and getattr(self, "vouch_pid", None)
+                and pid_listens(self.vouch_pid, self.port)):
+            # The table hides other processes (FAA-267); the process this caller started holds the listener.
+            owner = Owner(THIS_ACCOUNT, _posix_uid(), self.vouch_pid, "lsof-pid")
         refused = refusal(owner, self.port, self.expect_pid)
         if refused is not None:
             self.close()
@@ -829,7 +948,7 @@ class CheckedHTTPConnection(http.client.HTTPConnection):
 
 
 def own_connection(port: int, *, expect_pid: Optional[int] = None, timeout: float = 10.0,
-                   host: str = "127.0.0.1") -> CheckedHTTPConnection:
+                   host: str = "127.0.0.1", vouch_pid: Optional[int] = None) -> CheckedHTTPConnection:
     """A `CheckedHTTPConnection` to `host:port`, connected, whose server end is this account's
     (and, with `expect_pid`, that process's). The check runs on the very connection the caller
     then sends on, so no listener can change between the check and the request, and it runs
@@ -839,7 +958,10 @@ def own_connection(port: int, *, expect_pid: Optional[int] = None, timeout: floa
         server-not-own             another account's or the system's process accepted it
         server-unverified          its owner could not be told (nothing is sent: fail closed)
         server-not-this-workspace  this account's process, but not the pid expected
+
+    `vouch_pid`, as on `CheckedHTTPConnection` and the Node twin's `checkedSocket`: a pid the caller started
+    (FAA-267).
     """
-    conn = CheckedHTTPConnection(host, port, expect_pid=expect_pid, timeout=timeout)
+    conn = CheckedHTTPConnection(host, port, expect_pid=expect_pid, timeout=timeout, vouch_pid=vouch_pid)
     conn.connect()
     return conn

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

@@ -275,6 +275,7 @@ from fabric_auth import (  # noqa: F401
 from fabric_events import (  # noqa: F401
     EVENTS_DEFAULT_LIMIT,
     EVENTS_MAX_LIMIT,
+    LEVEL_ALIASES,
     LEVELS,
     _KIND,
     _TRACE_ID,
@@ -314,6 +315,7 @@ from fabric_supervisors import (  # noqa: F401
     _launchctl,
     _domain,
     launchd_loaded,
+    launchd_pid,
     fetch_well_known,
     _OVERRIDE_ROW,
     launchd_override,

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

@@ -53,6 +53,20 @@ def _no_marker_argument(argv: Sequence[str]) -> None:
         raise ServiceError("%s is written by the supervisor file's writer; leave it out of the program arguments" % SUPERVISOR_ARG)
 
 
+_PATH_ANCHOR = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/])")
+_PATH_WORD = re.compile(r"[a-z][a-z0-9_-]{2,}")
+
+
+def _secret_env_value(value: str) -> bool:
+    """An environment value: read path-aware (`secret_argument`) only when it reads as a path (it starts as one, has at
+    least two separators and a lower-case word between them), so a release folder under Application Support is no key
+    (FAA-266) while a base64 key whose `/` splits it stays one; any other value keeps the strict `secret_value`."""
+    import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
+    pieces = re.split(r"[\\/]", value)
+    path = bool(_PATH_ANCHOR.match(value)) and len(pieces) >= 3 and any(_PATH_WORD.fullmatch(x) for x in pieces)
+    return fabric_secrets.secret_argument(value) if path else fabric_secrets.secret_value(value)
+
+
 def _no_secret_in_supervisor_file(argv: Sequence[str], environment: Optional[Dict[str, str]]) -> None:
     """No supervisor file carries a secret (service.md): not in an argument, an environment name or its value."""
     import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
@@ -60,7 +74,7 @@ def _no_secret_in_supervisor_file(argv: Sequence[str], environment: Optional[Dic
         if fabric_secrets.secret_argument(arg):
             raise ServiceError("an argument carries a credential; a supervisor file never does (read it from the token file or a secret reference)")
     for name, value in (environment or {}).items():
-        if fabric_secrets.credential_name(name) or fabric_secrets.secret_value(str(value)):
+        if fabric_secrets.credential_name(name) or _secret_env_value(str(value)):
             raise ServiceError("environment %s looks like a credential; a supervisor file never carries one" % name)
 
 
@@ -263,7 +277,7 @@ def launchd_plist(label: str, program_arguments: Sequence[str], *, working_direc
     for key, value in env.items():
         if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)\Z", key) and not key.endswith("_FILE"):
             raise ServiceError("Environment variable %s looks like a secret; pass a *_FILE path instead." % key)
-        if fabric_secrets.secret_value(str(value)):
+        if _secret_env_value(str(value)):  # path-aware only for a path: a release folder is no key (FAA-266)
             raise ServiceError("Environment %s holds a value shaped like a credential; a plist never carries one." % key)
     for arg in argv:
         if fabric_secrets.secret_argument(arg):
@@ -307,19 +321,38 @@ def launchd_loaded(label: str) -> bool:
     return _launchctl("print", "%s/%s" % (_domain(), label)).returncode == 0
 
 
-def _read_well_known(origin: str, timeout: float = 2.0) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+_PID_ROW = re.compile(r"^\s*pid\s*=\s*(\d+)\s*\Z")
+
+
+def launchd_pid(label: str) -> Optional[int]:
+    """The running pid of this account's launchd job ``label``, or None (not running, or not readable)."""
+    result = _launchctl("print", "%s/%s" % (_domain(), label))
+    if result.returncode != 0:
+        return None
+    for line in (result.stdout or "").splitlines():
+        hit = _PID_ROW.match(line)
+        if hit:
+            return int(hit.group(1))
+    return None
+
+
+def _read_well_known(origin: str, timeout: float = 2.0,
+                     vouch_pid: Optional[int] = None) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
     """(the well-known answer or None, why the listener was refused or None). A loopback origin is read only on a
     connection whose server end is this OS account's process (DEC-0154 HA-2): another account's, root's, or one whose
-    owner cannot be told is `foreign-user`, never this service's answer."""
+    owner cannot be told is never this service's answer, labelled `foreign-user`, or `table-restricted` when the socket
+    table hides other processes. `vouch_pid`, the pid of a launchd job this
+    caller started, proves the listener when the socket table hides other processes (FAA-267)."""
     parts = urllib.parse.urlsplit(origin)
     if parts.scheme == "http" and parts.hostname == "127.0.0.1" and parts.port:
-        conn = _po.CheckedHTTPConnection("127.0.0.1", parts.port, timeout=timeout)
+        conn = _po.CheckedHTTPConnection("127.0.0.1", parts.port, timeout=timeout, vouch_pid=vouch_pid)
         try:
             conn.request("GET", "/.well-known/fabric-service", headers={"Host": "127.0.0.1:%d" % parts.port})
             response = conn.getresponse()
             return (json.loads(response.read().decode()) if response.status == 200 else None), None
         except _po.ListenerRefused as exc:
-            return None, "foreign-user: %s" % exc
+            restricted = exc.owner is not None and (exc.owner.reason or "").startswith(_po.TABLE_RESTRICTED)
+            return None, "%s: %s" % (_po.TABLE_RESTRICTED if restricted else "foreign-user", exc)
         except (OSError, ValueError, http.client.HTTPException):
             return None, None
         finally:
@@ -392,14 +425,20 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
     else:
         raise ServiceError("launchctl bootstrap failed: %s" % last)
     deadline = time.time() + timeout
-    foreign = None
+    foreign = vouch = None
     while time.time() < deadline:
-        doc, foreign = _read_well_known(origin)
+        doc, foreign = _read_well_known(origin, vouch_pid=vouch)
+        if foreign and foreign.startswith(_po.TABLE_RESTRICTED):
+            vouch = launchd_pid(label)  # only a restricted table needs the job's pid (FAA-267)
         if doc and doc.get("service", {}).get("id") == service_id and doc.get("service", {}).get("instance") == instance:
             return doc
         time.sleep(0.5)
     if foreign:
         # DEC-0154 HA-2 and service.md's Install row: a listener of another account is never a successful install.
+        if foreign.startswith(_po.TABLE_RESTRICTED):
+            raise ServiceError("%s could not be proved this service's: %s (DEC-0154 HA-2); this interpreter sees no other "
+                               "process's sockets and the job's pid did not show the listener: run the installer from "
+                               "Apple's /usr/bin/python3, or read the job's log." % (origin, foreign))
         raise ServiceError("%s is not this service's: %s (DEC-0154 HA-2); the port is another OS account's or its owner "
                            "cannot be told." % (origin, foreign))
     raise ServiceError("%s did not answer as %s.%s within %.0f s; read its log." % (origin, service_id, instance, timeout))