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

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

@@ -18,25 +18,34 @@ export function servicesDir(platform = process.platform) {
   return path.join(process.env.XDG_DATA_HOME || path.join(home, '.local/share'), 'passioncode-fabric/services');
 }
 
+// FABRIC_DATA_HOME (FAA-192): an absolute folder on a durable volume holds the data folder, <home>/<id>, on a host whose
+// own disk does not persist; logs and cache stay where the OS puts them. A relative value is refused.
+function durable(id, dirs) {
+  const value = process.env.FABRIC_DATA_HOME;
+  if (!value) return dirs;
+  if (!path.isAbsolute(value)) throw new ServiceError('FABRIC_DATA_HOME is an absolute folder on a durable volume.');
+  return { ...dirs, data: path.join(value, id) };
+}
+
 export function serviceDirs(id, platform = process.platform) {
   if (!ID.test(id)) throw new ServiceError(`Service id ${id} must match ${ID}.`);
   const home = os.homedir();
   if (platform === 'darwin') {
-    return {
+    return durable(id, {
       data: path.join(home, 'Library/Application Support', id),
       logs: path.join(home, 'Library/Logs', id),
       cache: path.join(home, 'Library/Caches', id),
-    };
+    });
   }
   if (platform === 'win32') {
     const data = path.join(localAppData(), id);
-    return { data, logs: path.join(data, 'Logs'), cache: path.join(data, 'Cache') };
+    return durable(id, { data, logs: path.join(data, 'Logs'), cache: path.join(data, 'Cache') });
   }
-  return {
+  return durable(id, {
     data: path.join(process.env.XDG_DATA_HOME || path.join(home, '.local/share'), id),
     logs: path.join(process.env.XDG_STATE_HOME || path.join(home, '.local/state'), id, 'logs'),
     cache: path.join(process.env.XDG_CACHE_HOME || path.join(home, '.cache'), id),
-  };
+  });
 }
 
 /**
@@ -50,6 +59,10 @@ export function instanceDirs(id, instance = 'default', platform = process.platfo
   const folder = `${id}.${instance}`;
   if (platform === 'win32') {
     const data = path.join(path.dirname(personal.data), folder);
+    if (process.env.FABRIC_DATA_HOME) { // logs and cache stay on the local disk, beside the default's
+      const local = path.join(path.dirname(path.dirname(personal.logs)), folder);
+      return { data, logs: path.join(local, 'Logs'), cache: path.join(local, 'Cache') };
+    }
     return { data, logs: path.join(data, 'Logs'), cache: path.join(data, 'Cache') };
   }
   if (platform === 'darwin') return Object.fromEntries(Object.entries(personal).map(([key, dir]) => [key, path.join(path.dirname(dir), folder)]));

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

@@ -1,6 +1,8 @@
 // Which OS account owns each end of a loopback TCP connection (DEC-0154 HA-2, FAA-226, layer L0); the twin of
-// fabric_peer_owner.py, which is Project Observatory's peer_owner 1.1.0 vendored by commit. Node 18+, no dependency;
-// nothing here imports another kit module.
+// fabric_peer_owner.py, which is Project Observatory's peer_owner vendored by commit (its 1.3.1 line). Node 18+, no
+// dependency; the one kit module it may load is fabric-socket-proof.mjs beside it (DEC-0155 RT-2, FAA-292): on a
+// restricted macOS table a server end or listener one of this account's own processes holds is this account's, and
+// without that file this one answers as before.
 //
 // WHY. Loopback is one per computer, not one per OS account: every account's processes reach every listener on
 // 127.0.0.1, so a loopback socket proves nothing about who is on the other end. A client about to send a credential
@@ -47,7 +49,7 @@ import net from 'node:net';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
-export const PEER_OWNER_VERSION = '1.2.0+kit.6'; // the Python twin's, Observatory's 1.2.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.3.1+kit.7'; // the Python twin's, Observatory's 1.3.1 line with the kit's differences
 export const THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -478,10 +480,36 @@ async function oneOwner(found, how, opts, noneReason = null) {
   return owner(UNKNOWN, { method: how, reason: 'several-rows' });
 }
 
+// fabric-socket-proof.mjs beside this file, loaded once (DEC-0155 RT-2, FAA-292); null when it is not there.
+let socketProof;
+
+// `fallback`, unless it is a restricted macOS table's unknown and fabric-socket-proof finds the socket (`accepted`) or
+// the 127.0.0.1 listener (`ownListener`, FAA-272) in this account's own processes; else it stands. A test that injects
+// a table (`read`, `run`) reaches this host's processes only through the `socketProof` it names.
+async function proved(ask, args, fallback, opts = {}) {
+  if (fallback.kind !== UNKNOWN || !String(fallback.reason ?? '').startsWith(TABLE_RESTRICTED)) return fallback;
+  if ((opts.platform ?? process.platform) !== 'darwin') return fallback;
+  let module = opts.socketProof;
+  if (module === undefined) {
+    if (opts.read || opts.run) return fallback;
+    if (socketProof === undefined) socketProof = await import('./fabric-socket-proof.mjs').catch(() => null);
+    module = socketProof;
+  }
+  let p = null;
+  try {
+    p = module ? await module[ask](...args) : null;
+  } catch {
+    p = null; // a proof that fails proves nothing; the table's answer stands (fail closed)
+  }
+  return p?.proved ? owner(THIS_ACCOUNT, { uid: opts.ownUid ?? ownUid(), pid: p.pid, method: p.method, reason: p.reason }) : fallback;
+}
+
 // The owner of the CLIENT socket of the connection between `server` and `client` ([host, port] each), as a server sees
 // them: the row whose local address is the client's and whose remote address is the server's.
-export function peerAt(server, client, opts) {
-  return ownerOf(address(client[0], client[1]), address(server[0], server[1]), opts);
+export async function peerAt(server, client, opts) {
+  const c = address(client[0], client[1]);
+  const s = address(server[0], server[1]);
+  return proved('accepted', [c, s, { wait: false }], await ownerOf(c, s, opts), opts);
 }
 
 // For a server's accepted socket: who connected. Reads nothing from the socket.
@@ -494,9 +522,11 @@ export function peer(socket, opts) {
 // address is this socket's own, the server process's accepted socket, so a listener swapped after listen cannot pass
 // for the one that answers. On Linux a connection not yet accept()ed has no owner of its own (inode 0): its listener
 // answers (the contract's CT-254, HA-2's Linux source).
-export function serverEnd(socket, opts) {
-  if (!socket.remoteAddress || !socket.localAddress) return Promise.resolve(owner(UNKNOWN, { reason: 'socket: not connected' }));
-  return ownerOf(address(socket.remoteAddress, socket.remotePort), address(socket.localAddress, socket.localPort), opts, true);
+export async function serverEnd(socket, opts) {
+  if (!socket.remoteAddress || !socket.localAddress) return owner(UNKNOWN, { reason: 'socket: not connected' });
+  const s = address(socket.remoteAddress, socket.remotePort);
+  const own = address(socket.localAddress, socket.localPort);
+  return proved('accepted', [s, own, { wait: true }], await ownerOf(s, own, opts, true), opts);
 }
 
 const LISTEN_ORDER = ['127.0.0.1', '*', '::1'];
@@ -524,12 +554,12 @@ export async function listener(port, opts = {}) {
   try {
     table = await (read ?? readTable)(opts);
   } catch (err) {
-    const who = owner(UNKNOWN, { method: method(), reason: err instanceof TableUnreadable ? err.message : `table: ${err.name}` });
+    const who = await proved('ownListener', [port], owner(UNKNOWN, { method: method(), reason: err instanceof TableUnreadable ? err.message : `table: ${err.name}` }), opts);
     if (!injected) listeners.set(port, [at, who]);
     return who;
   }
-  const who = restricted(table.rows, table.how, opts) ? await restrictedListener(table.rows, port, table.how, opts)
-    : await oneOwner(pickListener(table.rows, port), table.how, opts);
+  const who = await proved('ownListener', [port], restricted(table.rows, table.how, opts)
+    ? await restrictedListener(table.rows, port, table.how, opts) : await oneOwner(pickListener(table.rows, port), table.how, opts), opts);
   if (!injected) listeners.set(port, [at, who]);
   return who;
 }
@@ -552,18 +582,23 @@ export function refusal(who, port, expectPid = null) {
   return null;
 }
 
-// macOS, when the socket table is restricted (FAA-267, DEC-0155 RT-3): whether process `pid`, this account's, listens on
-// exactly 127.0.0.1:<port> (never the IPv4 wildcard, which lsof prints as it prints an IPv6-only one, nor ::1; FAA-312).
+// macOS, when the socket table is restricted (FAA-267, DEC-0155 RT-3): whether process `pid` listens on exactly
+// 127.0.0.1:<port> (never the IPv4 wildcard, which lsof prints as it prints an IPv6-only one, nor ::1; FAA-312).
 // `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, and never a set-uid one (its real and effective uid differ, DEC-0155).
-export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine, ownEuid } = {}) {
+// launchd job it installed) may vouch with it, and never a set-uid one for this account (its real and effective uid
+// differ, DEC-0155). `owner`: the uid `pid` must run as, this account's by default, or null when the caller checks it
+// itself (a LaunchDaemon's UserName, FAA-286); anything else is a RangeError.
+export async function pidListens(pid, port, { run = runProgram, platform = process.platform, ownUid: mine, ownEuid, owner: want = THIS_ACCOUNT } = {}) {
+  if (want !== null && want !== THIS_ACCOUNT && !(Number.isInteger(want) && want >= 0)) throw new RangeError('owner is this-account, a uid or null');
   if (platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
   const real = mine ?? ownUid();
   const effective = ownEuid ?? (typeof process.geteuid === 'function' ? process.geteuid() : real);
-  if (effective !== real) return false;
+  if (want === THIS_ACCOUNT && effective !== real) return false;
   try {
-    const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
-    if (uid === null || uid !== real) return false;
+    if (want !== null) {
+      const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
+      if (uid === null || uid !== (want === THIS_ACCOUNT ? real : want)) 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' && p === port);
   } catch {
@@ -591,8 +626,9 @@ 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'}` });
       }
+      // The vouch proves a listener on exactly 127.0.0.1, so only a connection that reached it (FAA-273 item 12).
       if (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED) && vouchPid
-        && await pidListens(vouchPid, port, ask)) {
+        && normHost(socket.remoteAddress) === '127.0.0.1' && 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' });
       }

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

@@ -124,12 +124,25 @@ const REPOSITORY_AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 // boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
 const REPOSITORY_KEYS = 'sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}';
 const KEY_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))(?:${REPOSITORY_KEYS})`);
-const JWT_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))${JWT_SHAPE.source}`);
+/** Whether JWT_SHAPE matches at a word's start: the text's start, or after a `.`, `_` or `-` (FAA-321), read in one
+ * pass as jwtSpans: only a run's first `eyJ` at a word's start is tried (fabric_secrets.jwt_at_a_word). */
+export function jwtAtAWord(text) {
+  for (let at = text.indexOf('eyJ'); at >= 0;) {
+    if (at > 0 && !'._-'.includes(text[at - 1])) { at = text.indexOf('eyJ', at + 1); continue; }
+    const one = runEnd(text, at + 3);
+    if (one - at - 3 >= 2 && text[one] === '.') {
+      const two = runEnd(text, one + 1);
+      if (two - one - 1 >= 2 && text[two] === '.') return true;
+    }
+    at = text.indexOf('eyJ', one);
+  }
+  return false;
+}
 const SPECIAL_QUERY = /^(?:https?|wss?|ftp|file):/i; // whose query also encodes `'`, as the URL standard does
 
 /** Whether a path segment reads as a repository's name: lower case, or letters with no digit, with no provider key's
  * or JWT's shape at its start or after a `.`, `_` or `-` (0.62.0 readings 9 and 10), so a letters-only key is a key. */
-export const repositoryName = (piece) => REPOSITORY_NAME.test(piece) && !KEY_AT_A_WORD.test(piece) && !JWT_AT_A_WORD.test(piece);
+export const repositoryName = (piece) => REPOSITORY_NAME.test(piece) && !KEY_AT_A_WORD.test(piece) && !jwtAtAWord(piece);
 
 /** Every `%XX` escape of an ASCII character decoded, the rest as written (fabric_secrets.ascii_decoded, readings 11). */
 export const asciiDecoded = (text) => text.replace(/%([0-7][0-9A-Fa-f])/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));

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

@@ -0,0 +1,180 @@
+// This OS account's own TCP sockets, read from its own processes (layer L0; DEC-0155 RT-2, FAA-292; FAA-272); the twin
+// of fabric_socket_proof.py. Node 18+, no dependency; nothing here imports another kit module.
+//
+// macOS 27.2 shows an ad-hoc-signed runtime (Homebrew's Node) only its own sockets, so fabric-peer-owner reads such a
+// table as table-restricted and cannot tell who accepted a connection. The question can still be asked of this
+// account's own processes, which the restriction leaves readable: whether one of them holds the very socket that
+// accepted the connection (RT-2, the accepted-socket proof), or a listener bound exactly to 127.0.0.1:<port> (HA-2's
+// macOS row, FAA-272). Another account's process is not listed, so a proof only ever says "this account's" or "not
+// proved"; never another account's, the system's or nobody's.
+//
+//   await accepted(server, client, { wait })   the socket at `server` connected to `client` is in one of this
+//                                              account's processes (`wait`: read again for ACCEPT_WAIT_MS until the
+//                                              server has called accept())
+//   await ownListener(port)                    a listener of this account on exactly 127.0.0.1:<port>
+//
+// Node has no ctypes, so the twin reads RT-2's other named source, `lsof -nP -a -u <uid> -iTCP:<port> -sTCP:<state>
+// -F pun`, matching the exact address pair and the numeric uid, where the Python twin reads the same records through
+// libproc (lsof only when libproc is unavailable). The twins agree on answers, not on the program they run (DEC-0155
+// Compatibility); test/fixtures/peer-owner/socket-proof-cases.json holds both. The proof is "a process of this uid
+// holds the descriptor", weaker than a table's so_uid: a socket passed with SCM_RIGHTS to a process of this uid reads
+// as this account's, which a caller that knows the server's pid closes with expectPid. One socket several of this
+// account's processes hold is proved with pid null, reason several-processes. A process whose real and effective uids
+// differ is refused (setuid-context). Reasons: table-restricted (read, nothing of this account matches) or
+// `table-restricted: <detail>` (the proof could not be read). Bounded by TIMEOUT_MS and MAX_OUTPUT_BYTES.
+
+import { execFile } from 'node:child_process';
+import net from 'node:net';
+
+export const TABLE_RESTRICTED = 'table-restricted';
+export const LSOF_METHOD = 'lsof';
+export const LSOF = '/usr/sbin/lsof';
+export const TIMEOUT_MS = 2000;
+export const ACCEPT_WAIT_MS = 500;
+export const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+const proof = (proved, pid, method, reason) => Object.freeze({ proved, pid, method, reason });
+const digits = (text) => /^[0-9]+$/.test(text);
+
+// One spelling per address, as fabric-peer-owner's normHost (the same rule, kept here so this module stands alone): an
+// IPv4-mapped IPv6 address is its IPv4 form, the unspecified address `*`, an IPv6 address RFC 5952's.
+function host(text) {
+  let h = String(text ?? '').replace(/^\[(.*)\]$/, '$1');
+  if (h === '*' || h === '') return '*';
+  if (h === 'localhost') return '127.0.0.1';
+  h = h.split('%', 1)[0];
+  if (net.isIPv4(h)) return h === '0.0.0.0' ? '*' : h.split('.').map((x) => String(Number(x))).join('.');
+  if (!net.isIPv6(h)) return h;
+  const t = new URL(`http://[${h}]/`).hostname.slice(1, -1);
+  if (t === '::') return '*';
+  const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(t);
+  if (!mapped) return t;
+  const hi = parseInt(mapped[1], 16);
+  const lo = parseInt(mapped[2], 16);
+  const v4 = [hi >> 8, hi & 255, lo >> 8, lo & 255].join('.');
+  return v4 === '0.0.0.0' ? '*' : v4;
+}
+
+// Whether `new URL(...).hostname` names this computer's loopback: localhost or a name under .localhost, ::1, or an IPv4
+// address in 127/8 (new URL has already read 127.1, 2130706433, 0x7f.1 and a trailing dot as 127.x.y.z); never an
+// IPv4-mapped address, which new URL writes in hex. The one rule fabric-http's checkUrl and fabric-delegation's key set
+// source read (FAA-187 (15)); the twin of fabric_socket_proof.loopback_host.
+export function loopbackHost(hostname) {
+  const h = String(hostname ?? '').toLowerCase().replace(/^\[(.*)\]$/, '$1');
+  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
+  return /^127\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/.test(h) && h.split('.').every((x) => Number(x) <= 255);
+}
+
+function lsofAddress(text) {
+  const at = text.lastIndexOf(':');
+  if (at < 0) return null;
+  const port = text.slice(at + 1);
+  if (!digits(port) || Number(port) > 65535) return null;
+  return [host(text.slice(0, at)), Number(port)];
+}
+
+// `lsof -nP -a -u <uid> -iTCP:<port> -sTCP:<state> -F pun`: the `n` lines of every process block whose `u` line is
+// exactly `uid` (a block of another uid, or with no uid, is not read). A name with `->` is a connection, one without a
+// listener. The same socket listed by several processes (one address pair) is one socket with pid null.
+export function parseLsofSockets(text, uid) {
+  const found = new Map();
+  let pid = null;
+  let owner = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const tag = line.slice(0, 1);
+    const value = line.slice(1);
+    if (tag === 'p') {
+      pid = digits(value) ? Number(value) : null;
+      owner = null;
+    } else if (tag === 'u') {
+      owner = digits(value) ? Number(value) : null;
+    } else if (tag === 'n' && pid !== null && owner === uid) {
+      const arrow = value.indexOf('->');
+      const local = lsofAddress(arrow < 0 ? value : value.slice(0, arrow));
+      const remote = arrow < 0 ? ['*', 0] : lsofAddress(value.slice(arrow + 2));
+      if (!local || !remote) continue;
+      const key = JSON.stringify([local, remote, arrow < 0]);
+      if (!found.has(key)) found.set(key, { local, remote, listening: arrow < 0, pids: [] });
+      found.get(key).pids.push(pid);
+    }
+  }
+  return [...found.values()].map(({ local, remote, listening, pids }) => ({
+    local, remote, listening, pid: new Set(pids).size === 1 ? pids[0] : null,
+  }));
+}
+
+const same = (a, b) => a[0] === b[0] && a[1] === b[1];
+
+function proved(hits, how) {
+  if (hits.length === 0) return proof(false, null, how, TABLE_RESTRICTED);
+  const pids = new Set(hits.map((s) => s.pid));
+  if (pids.size === 1 && !pids.has(null)) return proof(true, hits[0].pid, how, null);
+  return proof(true, null, how, 'several-processes');
+}
+
+// RT-2 over this account's sockets: the one at `server` connected to `client`; two with that pair are several-rows.
+export function acceptedIn(sockets, server, client, how) {
+  const hits = sockets.filter((s) => !s.listening && same(s.local, server) && same(s.remote, client));
+  if (hits.length > 1) return proof(false, null, how, 'several-rows');
+  return proved(hits, how);
+}
+
+// FAA-272 over this account's sockets: a listener bound exactly to 127.0.0.1:<port> (DEC-0155 RT-4: our wildcard or
+// ::1 listener, and root's, cannot be told from a hidden one).
+export function listenerIn(sockets, port, how) {
+  return proved(sockets.filter((s) => s.listening && same(s.local, ['127.0.0.1', port])), how);
+}
+
+class ProofUnreadable extends Error {}
+
+// One bounded run of lsof; its exit 1 with nothing printed is "no socket matched", not a failure.
+export function runLsof(file, args, timeout = TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { timeout, maxBuffer: MAX_OUTPUT_BYTES, encoding: 'utf8' }, (err, stdout) => {
+      if (!err) return resolve(stdout);
+      if (err.code === 1 && !String(stdout ?? '').trim()) return resolve('');
+      const why = typeof err.code === 'number' ? `exit ${err.code}` : (err.killed ? 'timeout' : (err.code ?? 'error'));
+      reject(new ProofUnreadable(`lsof: ${err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' ? `output over ${MAX_OUTPUT_BYTES} bytes` : why}`));
+    });
+  });
+}
+
+// The reader a question uses: lsof on macOS, none elsewhere.
+export const method = (platform = process.platform) => (platform === 'darwin' ? LSOF_METHOD : 'none');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function ask(port, state, pick, waitMs, { platform = process.platform, uid, euid, run = runLsof, now = () => Date.now() } = {}) {
+  const start = now();
+  if (platform !== 'darwin') return proof(false, null, 'none', `${TABLE_RESTRICTED}: unsupported-platform`);
+  const real = uid ?? process.getuid();
+  const effective = euid ?? (typeof process.geteuid === 'function' ? process.geteuid() : real);
+  if (real !== effective) return proof(false, null, LSOF_METHOD, `${TABLE_RESTRICTED}: setuid-context`);
+  let pause = 5;
+  for (;;) {
+    let have;
+    try {
+      have = parseLsofSockets(await run(LSOF, ['-nP', '-a', '-u', String(real), `-iTCP:${port}`, `-sTCP:${state}`, '-F', 'pun']), real);
+    } catch (err) {
+      return proof(false, null, LSOF_METHOD, `${TABLE_RESTRICTED}: ${err?.message ?? 'lsof: error'}`);
+    }
+    const answer = pick(have);
+    if (answer.proved || now() + pause > start + Math.min(waitMs, TIMEOUT_MS)) return answer;
+    await sleep(pause);
+    pause = Math.min(pause * 2, 50);
+  }
+}
+
+// RT-2: whether the socket at `server` connected to `client` ([host, port] each) is in one of this account's processes.
+// `wait`: read again for ACCEPT_WAIT_MS, since the server's accepted socket exists only once it calls accept().
+// `platform`, `uid`, `euid`, `run` and `now` are the tests'.
+export function accepted(server, client, { wait = false, ...opts } = {}) {
+  const s = [host(server[0]), Number(server[1])];
+  const c = [host(client[0]), Number(client[1])];
+  return ask(s[1], 'ESTABLISHED', (have) => acceptedIn(have, s, c, LSOF_METHOD), wait ? ACCEPT_WAIT_MS : 0, opts);
+}
+
+// FAA-272: whether one of this account's processes listens on exactly 127.0.0.1:<port>.
+export function ownListener(port, opts = {}) {
+  return ask(Number(port), 'LISTEN', (have) => listenerIn(have, Number(port), LSOF_METHOD), 0, opts);
+}

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, LSOF, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parseLsofListeners, parsePsUid,
+import { CheckedAgent, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parsePsUid, pidListens,
   runProgram, serverEnd } from './fabric-peer-owner.mjs';
 import http from 'node:http';
 import net from 'node:net';
@@ -60,7 +60,7 @@ function noMarkerArgument(argv) {
 // 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) => {
+export 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);
@@ -609,16 +609,9 @@ function loopbackWellKnown(port, agent, host = '127.0.0.1') {
 }
 
 // Whether launchd's job `pid` listens on exactly 127.0.0.1:<port>, never the wildcard, asked of the process itself (`lsof -p`),
-// which a restricted socket table does not hide. Only for a LaunchDaemon root bootstrapped, whose pid launchd named.
-async function jobListens(pid, port, run = runProgram, platform = process.platform) {
-  if (platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
-  try {
-    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' && p === port); // exact bind, as RT-3
-  } catch {
-    return false;
-  }
-}
+// which a restricted socket table does not hide. Only for a LaunchDaemon root bootstrapped, whose pid launchd named. The
+// peer owner's one lsof reader, the uid left to the caller, which checks the job's UserName itself (FAA-286 item 1).
+const jobListens = (pid, port, run = runProgram, platform = process.platform) => pidListens(pid, port, { run, platform, owner: null });
 
 // The uid account `name` has on this machine (`id -u`), or null when it has none.
 function accountUid(name, run) {