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

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

@@ -20,7 +20,8 @@
 // Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import http from 'node:http';
-import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
+import net from 'node:net';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED, UNKNOWN, method as tableMethod, owner as ownerOf, refusal, serverEnd } 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']);
@@ -158,6 +159,61 @@ function checkHeaders(headers) {
 
 const LOOPBACK_AGENT = new CheckedAgent();
 
+// Whether a connected socket reached this computer's loopback, by the address it connected to, not by the URL's
+// spelling: a name the hosts file maps to 127.0.0.1, `0.0.0.0` and `[::ffff:127.0.0.1]` arrive here (FAA-260).
+export function peerIsLoopback(address) {
+  const a = String(address ?? '').split('%', 1)[0].toLowerCase();
+  if (a === '::1' || a === '0.0.0.0' || a === '::') return true;
+  const v4 = /^(?:::ffff:)?(\d{1,3})\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.exec(a);
+  if (v4) return v4[1] === '127';
+  const hex = /^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/.exec(a);
+  return hex !== null && (parseInt(hex[1], 16) >> 8) === 127;
+}
+
+// An http.Agent for plain http to a host not spelled as loopback (`insecure`): when the connected socket's peer is a
+// loopback address, its server end is told as CheckedAgent tells it and refused before a byte is written unless it is
+// this OS account's process (DEC-0154 HA-2; 0.74.0 unit readings 7 and 8, FAA-260). Another peer is used as it is.
+export class PeerCheckedAgent extends http.Agent {
+  constructor({ ask = {}, ...options } = {}) {
+    super(options);
+    this.ask = ask;
+  }
+
+  createConnection(options, callback) {
+    let done = false;
+    const finish = (err, socket) => { if (!done) { done = true; callback(err, socket); } };
+    const port = Number(options.port);
+    const socket = net.connect({ host: options.host, port, noDelay: true, autoSelectFamily: true,
+      ...(options.lookup ? { lookup: options.lookup } : {}) });
+    socket.once('error', (err) => finish(err));
+    socket.once('connect', async () => {
+      if (!peerIsLoopback(socket.remoteAddress)) {
+        socket.removeAllListeners('error');
+        finish(null, socket);
+        return;
+      }
+      socket.pause();
+      let who;
+      try {
+        who = await serverEnd(socket, this.ask);
+      } catch (err) {
+        who = ownerOf(UNKNOWN, { method: tableMethod(), reason: `check: ${err?.name ?? 'Error'}` });
+      }
+      const refused = refusal(who, port, null);
+      if (refused) {
+        socket.destroy();
+        finish(new ListenerRefused(refused[0], `${refused[1]}; nothing was sent`, who));
+        return;
+      }
+      socket.removeAllListeners('error');
+      socket.resume();
+      finish(null, socket);
+    });
+  }
+}
+
+const PLAIN_AGENT = new PeerCheckedAgent();
+
 // 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 }) {
@@ -198,12 +254,15 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
   });
 }
 
-// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http to a
-// loopback host goes through checkedLoopbackTransport.
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http goes
+// through checkedLoopbackTransport, its connection checked when it reaches loopback (FAA-260).
 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 });
+  if (target.protocol === 'http:') {
+    // plain http never goes through fetch: a URL spelled as loopback is checked on every connection, any other is
+    // checked when its connected peer is a loopback address (FAA-260)
+    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes,
+      ...(isLoopback(target.hostname) ? {} : { agent: PLAIN_AGENT }) });
   }
   const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
     signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });

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

@@ -56,8 +56,9 @@ export class HubError extends Error {
 /**
  * The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned contract's
  * state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted` when this
- * runtime's socket table hides other processes' sockets, which never clears, so it is not retryable; otherwise the
- * owner's kind or the check's reason (`another-account`, `no-row`), retryable as before.
+ * runtime's socket table hides other processes' sockets, or, on macOS, holds no row for this connection (DEC-0155
+ * RT-1, FAA-312), which never clears, so it is not retryable; otherwise the owner's kind or the check's reason
+ * (`another-account`, or `no-row`, which only Linux and Windows give), retryable.
  */
 export function listenerRefusal(e) {
   const kind = e?.owner?.kind ?? null;
@@ -75,14 +76,18 @@ export function fabricRoot(platform = process.platform, env = process.env) {
   return path.join(env.XDG_DATA_HOME || path.join(home, '.local/share'), 'passioncode-fabric');
 }
 
-/** Whether a process with this id runs as this user (Fabric hub.ts#pidAlive): EPERM is another user's process. */
+/**
+ * true: a process of this OS account runs under pid; false: none does. null (falsy): a process of another account does
+ * (EPERM), as when the id hub.json names was reused: not verified, never called running (FAA-304, the session hooks'
+ * answer since FAA-254). Never signals it.
+ */
 export function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (e) {
+    return e?.code === 'EPERM' ? null : false;
   }
 }
 
@@ -108,7 +113,8 @@ function readSmall(file) {
 
 /**
  * hub.json read the way an agent must, every call. Answers {origin, mcpUrl, doorTokenFile, pid, startedAt, features} or
- * throws HubError (not-running, retryable; not-a-hub). Reads no token. `estate` is {record, applied}: with it, a hubKey
+ * throws HubError (not-running, retryable; not-a-hub, retryable when hub.json names another OS account's process, not
+ * verified, FAA-304). Reads no token. `estate` is {record, applied}: with it, a hubKey
  * the document names is checked by hubKeyCertified (DEC-0060); fabric-hub/0.1 names none.
  */
 export function locateHub(root = fabricRoot(), { alive = pidAlive, estate, now } = {}) {
@@ -142,7 +148,10 @@ export function locateHub(root = fabricRoot(), { alive = pidAlive, estate, now }
     sameRoot = false;
   }
   if (!sameRoot) throw notHub('names a door token outside the registry root');
-  if (!alive(doc.pid)) throw new HubError('not-running', `Fabric is not running: hub.json names process ${doc.pid}, which is not running.`, true);
+  const live = alive(doc.pid);
+  // FAA-304: another account's process under that id, so not this account's Fabric (as FAA-254)
+  if (live === null) throw new HubError('not-a-hub', `Fabric's hub.json names process ${doc.pid}, which runs under another OS account: not verified.`, true);
+  if (!live) throw new HubError('not-running', `Fabric is not running: hub.json names process ${doc.pid}, which is not running.`, true);
   const features = Array.isArray(doc.features) ? doc.features.filter((f) => typeof f === 'string') : [];
   if (estate && doc.hubKey && typeof doc.hubKey === 'object') {
     const verdict = hubKeyCertified(estate.record, doc.hubKey.kid, doc.hubKey.x, now ?? Date.now() / 1000, estate.applied ?? undefined);

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

@@ -1,5 +1,15 @@
 // One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock and the supervisor marker.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_lock.py. Node 20+ (22+ for the Linux lock), no dependency.
+//
+// A lock that moves under its holder (FAA-303). Linux and Windows hold a name keyed by the lock's path (an abstract
+// unix socket, a named pipe), so a folder swapped under a running copy cannot let a second copy in. macOS has no such
+// name: O_EXLOCK (and the Python twin's flock) lock an inode, so after a data import swaps the data folder a second
+// copy locks the new file and starts. There the holder watches its lock instead (InstanceLock#watch, started by
+// holdSingleInstance): every LOCK_WATCH_SECONDS it compares the inode it locked with the file at the path, and once
+// the path names another file it stops with 75 and one sentence naming the path, before writing anything more into a
+// folder that is no longer the one it read. Two copies then overlap for at most one interval. A path-keyed name on
+// macOS was weighed and left: it needs a file in a folder outside the data folder that the system never cleans and
+// every copy can write, which Node alone cannot promise.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
@@ -15,6 +25,12 @@ export const LOCK_BACKOFF_FIRST_SECONDS = 0.5;
 
 export const LOCK_BACKOFF_MAX_SECONDS = 30;
 
+/**
+ * How often a holder that has no path-keyed name (macOS) compares the inode it locked with the file at the lock's path
+ * (FAA-303): one stat and one fstat; two copies overlap for at most this long after a folder swap.
+ */
+export const LOCK_WATCH_SECONDS = 2;
+
 const O_EXLOCK = 0x20; // BSD/macOS: open(2) takes flock(LOCK_EX); absent from fs.constants
 
 export class AlreadyRunning extends ServiceError {
@@ -34,6 +50,7 @@ export class InstanceLock {
     this.path = path.join(dataDir, 'service.lock');
     this.fd = null;
     this.server = null;
+    this.timer = null;
   }
 
   async acquire() {
@@ -124,14 +141,65 @@ export class InstanceLock {
     return true;
   }
 
+  /**
+   * Re-check, every `intervalSeconds` on an unref'd timer, that the file this copy locked is still the file at the path
+   * (FAA-303); the first time the path names another file (a swapped folder's lock, or the one a second copy made),
+   * call `onLost(lock)` once and stop watching. The default stops the process with 75 and one sentence
+   * (stopLostHolder). A path that is gone or cannot be read now is read as nothing there yet and tried again next time:
+   * a second copy has to make a file there to start, and the watch then sees that file. `release` ends the watch. Only
+   * a lock held as a file is watched (macOS): elsewhere the descriptor is null and the path-keyed name keeps a second
+   * copy out, so this is a no-op, as for a lock not held.
+   */
+  watch({ onLost, intervalSeconds = LOCK_WATCH_SECONDS } = {}) {
+    if (this.fd === null || this.timer !== null) return this;
+    const fd = this.fd;
+    const react = onLost ?? stopLostHolder;
+    this.timer = setInterval(() => {
+      let here;
+      let held;
+      try {
+        here = fs.statSync(this.path);
+        held = fs.fstatSync(fd);
+      } catch {
+        return;
+      }
+      if (here.dev === held.dev && here.ino === held.ino) return;
+      clearInterval(this.timer);
+      this.timer = null;
+      react(this);
+    }, intervalSeconds * 1000);
+    this.timer.unref();
+    return this;
+  }
+
   release() {
+    if (this.timer !== null) clearInterval(this.timer);
     if (this.fd !== null) fs.closeSync(this.fd);
     if (this.server) this.server.close();
+    this.timer = null;
     this.fd = null;
     this.server = null;
   }
 }
 
+/** The one sentence a holder whose lock moved under it stops with (FAA-303). */
+export function lostLockMessage(lockPath) {
+  return `${lockPath} is no longer the file this copy locked (the data folder moved or was swapped?): stopping, so a copy started on the folder now at that path runs alone.`;
+}
+
+/**
+ * InstanceLock#watch's default: write lostLockMessage and end the process with 75 at once. Not a graceful stop: a
+ * shutdown would write this copy's state into the folder now at the path, which is not the one it read; the kit's
+ * journals make an abrupt stop recoverable (LC-03).
+ */
+export function stopLostHolder(lock) {
+  try {
+    fs.writeSync(2, `${lostLockMessage(lock.path)}\n`);
+  } finally {
+    process.exit(EXIT_ALREADY_RUNNING);
+  }
+}
+
 let abstractNamesSeen = null;
 
 /**
@@ -253,10 +321,12 @@ const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 100
  * supervisor that restarts on exit (launchd's KeepAlive) an immediate exit is a respawn every ThrottleInterval,
  * forever; so a supervised copy first backs off in-process (0.5 s doubling to 30 s,
  * LOCK_WAIT_SUPERVISED_SECONDS in all), takes over if the holder leaves, and exits 75 only when
- * the wait runs out. `waitSeconds` overrides the choice (0 = never wait).
+ * the wait runs out. `waitSeconds` overrides the choice (0 = never wait). Where the lock is held as a file (macOS)
+ * the held lock is watched (InstanceLock#watch, FAA-303): a folder swapped under the running copy stops it with 75;
+ * `onLost` replaces that reaction.
  */
 export async function holdSingleInstance(dataDir, {
-  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv,
+  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv, onLost,
 } = {}) {
   // DEC-0057: markers that disagree exit 75 at once, before the lock, naming them.
   const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
@@ -270,7 +340,7 @@ export async function holdSingleInstance(dataDir, {
   let announced = false;
   for (;;) {
     try {
-      return await new InstanceLock(dataDir).acquire();
+      return (await new InstanceLock(dataDir).acquire()).watch({ onLost });
     } catch (error) {
       if (!(error instanceof AlreadyRunning)) throw error;
       const remaining = deadline - clock();

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

@@ -509,9 +509,71 @@ const FOLDER_MESSAGES = {
   'provider-manifest': 'provider-manifest: the provider manifest must be a JSON object, and when it carries costPresets fabric.package.json must carry the same costPresets (copy them; pack does not)',
 };
 
+/**
+ * The agent's source manifest (contract DEC-0149, `fabric-source/1`): when the folder carries one, `pack` writes
+ * `secrets[]` from its secret slots and `state[]` from its store slots' paths, and FAC-SEM-160 holds them equal.
+ */
+export const SOURCE_FILE = 'fabric.source.json';
+
+function sourceManifest(files) {
+  if (!files.has(SOURCE_FILE)) return undefined;
+  const source = parseStrict(files.get(SOURCE_FILE), SOURCE_FILE);
+  if (source.format !== 'fabric-source/1') throw new PackageError(`${SOURCE_FILE} is not a fabric-source/1 manifest (its format member).`);
+  return source;
+}
+
+/** `secrets[]` from the secret slots (name, purpose, optional) and `state[]` from the store slots (path, purpose). */
+export function sourceMembers(source) {
+  const secrets = [];
+  const state = [];
+  for (const slot of objects(source.slots)) {
+    if (slot.kind === 'secret' && isString(slot.name)) secrets.push({ name: slot.name, purpose: slot.purpose, ...(slot.optional === true ? { optional: true } : {}) });
+    else if (slot.kind === 'store' && isString(slot.path)) state.push({ path: slot.path, purpose: slot.purpose });
+  }
+  return { secrets, state };
+}
+
+/**
+ * FAC-SEM-160 (contract `sourcePackageFindings`): the package's secrets[] are the source's secret slots, by name and
+ * optional; its state[] paths are the store slots' paths when state[] holds any entry.
+ */
+export function sourcePackageFindings(source, pkg) {
+  if (!isObject(source) || !isObject(pkg)) return [];
+  const out = [];
+  const flag = (instancePath, message) => out.push({ code: 'FAC-SEM-160', instancePath, message });
+  const slots = objects(source.slots);
+  const secrets = new Map(slots.filter((s) => s.kind === 'secret' && isString(s.name)).map((s) => [s.name, s.optional === true]));
+  const stores = new Set(slots.filter((s) => s.kind === 'store' && isString(s.path)).map((s) => s.path));
+  const packaged = (Array.isArray(pkg.secrets) ? pkg.secrets : []).flatMap((e, i) => (isObject(e) ? [[e, i]] : []));
+  const names = new Set(packaged.map(([e]) => e.name));
+  for (const name of secrets.keys()) if (!names.has(name)) flag('/package/secrets', `the source's secret slot ${name} is not in the package's secrets[]`);
+  for (const [entry, index] of packaged) {
+    if (!isString(entry.name) || !secrets.has(entry.name)) flag(`/package/secrets/${index}/name`, `secrets[${index}] is no secret slot of the source`);
+    else if (secrets.get(entry.name) !== (entry.optional === true)) flag(`/package/secrets/${index}/optional`, `secrets[${index}] is ${secrets.get(entry.name) ? '' : 'not '}optional in the source`);
+  }
+  if (!Array.isArray(pkg.state) || pkg.state.length === 0) return out;
+  const paths = new Set(objects(pkg.state).map((e) => e.path));
+  for (const p of stores) if (!paths.has(p)) flag('/package/state', "a store slot's path of the source is not in the package's state[]");
+  pkg.state.forEach((entry, index) => {
+    if (isObject(entry) && (!isString(entry.path) || !stores.has(entry.path))) flag(`/package/state/${index}/path`, `state[${index}] is no store slot of the source`);
+  });
+  return out;
+}
+
+function sourceProblems(pkg, files) {
+  if (!files.has(SOURCE_FILE)) return [];
+  try {
+    return sourcePackageFindings(sourceManifest(files), pkg).map((p) => ({ ...p, rule: p.code }));
+  } catch (error) {
+    if (!(error instanceof PackageError)) throw error;
+    return [{ rule: 'source', instancePath: '/files', message: error.message }];
+  }
+}
+
 function allProblems(pkg, files) {
   return [
     ...schemaProblems(pkg).map((p) => ({ ...p, rule: 'schema' })),
+    ...sourceProblems(pkg, files),
     ...pathProblems(pkg).map((p) => ({ ...p, rule: 'path' })),
     ...packageFindings(pkg).map((p) => ({ ...p, rule: p.code })),
     ...checkPackageFolder(pkg, files).map((p) => ({ rule: 'folder', problem: p.problem, instancePath: p.path, message: FOLDER_MESSAGES[p.problem] ?? p.problem })),
@@ -525,6 +587,21 @@ function writeAtomic(file, text) {
   fs.renameSync(temp, file);
 }
 
+/** The names a hand-written secrets[] declares that the source manifest has no secret slot for, in their order. */
+function secretsLacking(draft, secrets) {
+  const have = new Set(secrets.map((s) => s.name));
+  const lacking = [];
+  for (const entry of Array.isArray(draft.secrets) ? draft.secrets : []) {
+    const name = isObject(entry) ? entry.name : undefined;
+    if (isString(name) && !have.has(name) && !lacking.includes(name)) lacking.push(name);
+  }
+  return lacking;
+}
+
+function lackingMessage(lacking) {
+  return `${SOURCE_FILE} declares no secret slot for ${lacking.join(', ')}, which ${PACKAGE_FILE}'s secrets[] names: pack writes secrets[] from the manifest's slots and never drops a declared secret. Add each as a slot of kind secret to ${SOURCE_FILE} (or take it out of secrets[]), then pack again`;
+}
+
 /** Pack `folder`; with `apply` and no problem, fabric.package.json is rewritten. */
 export function pack(folder, { apply = false } = {}) {
   const files = readFolder(folder);
@@ -532,8 +609,28 @@ export function pack(folder, { apply = false } = {}) {
     throw new PackageError(`Write ${PACKAGE_FILE} in the folder first: schema, kind, id, version, publisher, licence and, for an agent, resultSignal and evals with its receipt. pack fills in agentRef, files[] and digest.`);
   }
   const draft = parseStrict(files.get(PACKAGE_FILE), PACKAGE_FILE);
+  const source = sourceManifest(files);
+  const written = [];
+  const refused = [];
+  if (source !== undefined) {
+    // DEC-0149: secrets[] and state[] come from the source manifest's slots; an empty state[] is a copy without state.
+    const members = sourceMembers(source);
+    const lacking = secretsLacking(draft, members.secrets);
+    if (lacking.length > 0) {
+      // a declared secret is never dropped: the manifest gains its slot first
+      refused.push({ rule: 'source', instancePath: '/secrets', message: lackingMessage(lacking) });
+    } else if (members.secrets.length > 0 || Object.hasOwn(draft, 'secrets')) {
+      Object.defineProperty(draft, 'secrets', { value: members.secrets, enumerable: true, writable: true, configurable: true });
+      written.push('secrets[]');
+    }
+    if (members.state.length > 0 && !(Array.isArray(draft.state) && draft.state.length === 0)) {
+      Object.defineProperty(draft, 'state', { value: members.state, enumerable: true, writable: true, configurable: true });
+      written.push('state[]');
+    }
+  }
   const { pkg, notes } = compose(draft, files);
-  const problems = allProblems(pkg, files);
+  if (written.length > 0) notes.push(`${written.join(' and ')} written from ${SOURCE_FILE}`);
+  const problems = [...refused, ...allProblems(pkg, files)];
   const suite = isObject(pkg.evals) ? pkg.evals.suite : undefined;
   if (isString(suite) && files.has(suite) && problems.some((p) => p.instancePath === '/evals/receipt/suite')) notes.push(`the suite packed is ${sha256Of(files.get(suite))}: run it again and write that receipt`);
   const answer = { ok: problems.length === 0, applied: false, digest: pkg.digest, files: pkg.files.length, problems, notes };

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

@@ -40,12 +40,14 @@
 // privilege. The parsers are pure functions over captured text (test/fixtures/peer-owner/).
 
 import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { open } from 'node:fs/promises';
 import http from 'node:http';
 import net from 'node:net';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 
-export const PEER_OWNER_VERSION = '1.1.0+kit.4'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
+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 THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -62,6 +64,8 @@ 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';
+// A macOS table that lists sockets but not the reader's own connection (DEC-0155 RT-1, FAA-312).
+export const NO_ROW_RESTRICTED = `${TABLE_RESTRICTED}: no row for this connection`;
 export const SERVER_NOT_OWN = 'server-not-own';
 export const SERVER_UNVERIFIED = 'server-unverified';
 export const SERVER_NOT_THIS_WORKSPACE = 'server-not-this-workspace';
@@ -290,10 +294,10 @@ export function runProgram(file, args, timeout = TIMEOUT_MS) {
   });
 }
 
-export function method() {
-  if (process.platform === 'darwin') return 'netstat';
-  if (process.platform === 'linux') return 'proc';
-  if (process.platform === 'win32') return 'netstat-windows';
+export function method(platform = process.platform) {
+  if (platform === 'darwin') return 'netstat';
+  if (platform === 'linux') return 'proc';
+  if (platform === 'win32') return 'netstat-windows';
   return 'none';
 }
 
@@ -319,9 +323,18 @@ async function readProc(name) {
   return Buffer.concat(chunks);
 }
 
-export async function readTable({ run = runProgram } = {}) {
-  const how = method();
-  if (how === 'netstat') return { rows: parseNetstat(await run(NETSTAT, ['-anv', '-p', 'tcp'])), how };
+export async function readTable({ run = runProgram, platform = process.platform } = {}) {
+  const how = method(platform);
+  if (how === 'netstat') {
+    let text;
+    try {
+      text = await run(NETSTAT, ['-anv', '-p', 'tcp']);
+    } catch (err) {
+      // A netstat that fails, exits non-zero or times out is a restricted table (DEC-0155 RT-1, FAA-312).
+      throw new TableUnreadable(`${TABLE_RESTRICTED}: ${err instanceof TableUnreadable ? err.message : `netstat: ${err?.name ?? 'error'}`}`);
+    }
+    return { rows: parseNetstat(text), how };
+  }
   if (how === 'proc') {
     const rows = [];
     for (const [name, family] of [['/proc/net/tcp', 4], ['/proc/net/tcp6', 6]]) {
@@ -387,6 +400,21 @@ export async function resolve(row, how, { run = runProgram, ownUid: mine, ownSid
 
 // -- the questions ----------------------------------------------------------------------------------------------------
 
+// DEC-0155 RT-1 (FAA-312): a macOS table holding no row of another uid (sysctl, the Python twin's, which carries uids)
+// or of another process (netstat, which carries pids) is restricted, and a missing row proves nothing. Never on Linux
+// or Windows, which carry the owner on each row.
+export function restricted(rows, how, { ownUid: mine, ownPid } = {}) {
+  if (how === 'sysctl') {
+    const own = mine ?? ownUid();
+    return !rows.some((r) => r.uid !== null && r.uid !== undefined && r.uid !== own);
+  }
+  if (how === 'netstat') {
+    const own = ownPid ?? process.pid;
+    return !rows.some((r) => r.pid !== null && r.pid !== undefined && r.pid !== own);
+  }
+  return false;
+}
+
 // The live connected rows with exactly this local and remote address: one, or the caller cannot tell.
 // A row printed twice is one socket: Linux resumes a /proc read that sockets came and went under by position, and can
 // print the same row again (0.74.0 seam reading 6); rows equal in every field count once.
@@ -414,13 +442,14 @@ async function ownerOf(local, remote, opts = {}, server = false) {
     // A /proc read under churn can skip a row or print one twice; one more read before answering unknown.
     if (table.how !== 'proc' || found.length === 1) break;
   }
-  if (found.length === 0) return owner(UNKNOWN, { method: table.how, reason: 'no-row' });
+  // A macOS table without the reader's own connection is restricted (DEC-0155 RT-1, FAA-312).
+  if (found.length === 0) return owner(UNKNOWN, { method: table.how, reason: ['sysctl', 'netstat'].includes(table.how) ? NO_ROW_RESTRICTED : 'no-row' });
   if (found.length > 1) return owner(UNKNOWN, { method: table.how, reason: 'several-rows' });
   if (table.how === 'proc' && server && found[0].uid === null) {
     // Linux: a connection not yet accept()ed is printed with uid 0 and inode 0; it belongs to the listener on its local
     // address and dies with it, so that listener answers. An accepted connection's own row carries the uid of the
     // process that accepted it: it answers itself, so a listener swapped after another account accepted the client
-    // cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's pending CT-254, FAA-258).
+    // cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's CT-254, released).
     // A server row its owner already closed (an orphan) also has inode 0 and reads so: no process holds it, so nothing
     // sent to it reaches anyone (0.74.0 unit reading 6).
     return oneOwner(listenersOf(table.rows, found[0].local), table.how, opts, 'not-accepted');
@@ -464,7 +493,7 @@ export function peer(socket, opts) {
 // For a client's connected socket: who accepted it. The row whose local address is the server's and whose remote
 // 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 pending CT-254, FAA-258).
+// 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);
@@ -491,23 +520,28 @@ export async function listener(port, opts = {}) {
   const at = now();
   const hit = injected ? undefined : listeners.get(port);
   if (hit && at - hit[0] < LISTENER_TTL_MS) return hit[1];
-  let found;
-  let how;
   let table;
   try {
     table = await (read ?? readTable)(opts);
-    how = table.how;
-    found = pickListener(table.rows, port);
   } catch (err) {
     const who = owner(UNKNOWN, { method: method(), reason: err instanceof TableUnreadable ? err.message : `table: ${err.name}` });
     if (!injected) listeners.set(port, [at, who]);
     return who;
   }
-  const who = await oneOwner(found, how, opts);
+  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);
   if (!injected) listeners.set(port, [at, who]);
   return who;
 }
 
+// DEC-0155 RT-4 (FAA-312): under a restricted table only this account's own bind on exactly 127.0.0.1 is its own; its
+// wildcard or ::1 listener, root's, and a port with no row are an owner that cannot be told.
+async function restrictedListener(rows, port, how, opts) {
+  const who = await oneOwner(rows.filter((r) => r.listening && r.local[0] === '127.0.0.1' && r.local[1] === port), how, opts);
+  if (who.kind === THIS_ACCOUNT) return who;
+  return owner(UNKNOWN, { method: how, reason: `${TABLE_RESTRICTED}: no listener of this account on exactly 127.0.0.1:${port}` });
+}
+
 // [code, why] when a client must not send on a connection whose server end is `who`, else null.
 export function refusal(who, port, expectPid = null) {
   if (who.kind === ANOTHER_ACCOUNT || who.kind === SYSTEM) return [SERVER_NOT_OWN, `the server on port ${port} belongs to ${who.kind}`];
@@ -518,16 +552,20 @@ 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 } = {}) {
+// 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).
+// `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 } = {}) {
   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;
   try {
     const uid = parsePsUid(await run(PS, ['-o', 'uid=', '-p', String(pid)]));
-    if (uid === null || uid !== (mine ?? ownUid())) return false;
+    if (uid === null || uid !== real) 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);
+    return parseLsofListeners(out).some(([host, p]) => host === '127.0.0.1' && p === port);
   } catch {
     return false;
   }
@@ -587,3 +625,32 @@ export class CheckedAgent extends http.Agent {
       expectPid: this.expectPid, vouchPid: this.vouchPid, ...this.ask }).then((socket) => callback(null, socket), (err) => callback(err));
   }
 }
+
+const USAGE = 'usage: fabric-peer-owner.mjs listener <port> [--json]\n';
+
+// `listener <port> [--json]`: the kind of who listens on 127.0.0.1:<port>, which the dashboard link gate takes as
+// listener_owner (FAA-315), or the whole owner as JSON; 2 on a usage error. `listener` and `write` are the tests'.
+export async function main(argv, { listener: ask = listener, write = (text) => process.stdout.write(text) } = {}) {
+  const asJson = argv.length === 3 && argv[2] === '--json';
+  const port = Number(argv[1]);
+  if (argv.length !== 2 + Number(asJson) || argv[0] !== 'listener' || !/^[0-9]+$/.test(argv[1] ?? '') || port < 1 || port > 65535) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const who = await ask(port);
+  write(asJson ? `${JSON.stringify({ kind: who.kind, uid: who.uid, pid: who.pid, method: who.method, reason: who.reason })}\n` : `${who.kind}\n`);
+  return 0;
+}
+
+// Whether node was started on this file, by real paths (a symlinked install folder, as check_dashboard_layout.mjs).
+function startedDirectly() {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (startedDirectly()) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => { process.stderr.write(`${err?.message ?? err}\n`); process.exitCode = 1; });
+}

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

@@ -12,7 +12,7 @@ export const PROTOCOL_REVISIONS = new Map(Object.entries({
   'fabric-interop': ['0.1', '0.2'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-machine-report': ['1'], 'fabric-ops-digest': ['0.1'], 'fabric-operator-channel': ['0.1'],
   'fabric-package': ['1'],
   'fabric-peer-share': ['1'], 'fabric-peer-share-envelope': ['1'], 'fabric-peer-share-report': ['1'], 'fabric-project-comms': ['0.1'], 'fabric-proposal': ['1'], 'fabric-provider': ['0.1'], 'fabric-relay': ['0.1'],
-  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'], 'machine-report': ['1'], mandate: ['1'],
+  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], 'fabric-source': ['1'], heartbeat: ['1'], 'learning-note': ['1'], 'machine-report': ['1'], mandate: ['1'],
   memory: ['0.1'], 'node-summary': ['1'], 'operator-source': ['1'], 'org-adaptation': ['1'], 'org-adaptation-receipt': ['1'], 'org-authority': ['1'], 'org-authority-draft': ['1'],
   'org-key-set': ['1'], 'org-key-set-draft': ['1'], 'org-membership': ['1'], 'org-root-registration': ['1'], 'pairing-message': ['1'],
   'peer-share-deletion': ['1'], 'peer-share-frame': ['1'], 'peer-share-revocation': ['1'], pipeline: ['0.1'], 'repair-request': ['1'], 'repair-result': ['1'],