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

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

@@ -27,6 +27,9 @@ export class AlreadyRunning extends ServiceError {
 }
 
 export class InstanceLock {
+  /** How many times acquire re-opens service.lock that moved under it before it gives up (FAA-293). */
+  static INODE_RETRIES = 3;
+
   constructor(dataDir) {
     this.path = path.join(dataDir, 'service.lock');
     this.fd = null;
@@ -36,27 +39,12 @@ export class InstanceLock {
   async acquire() {
     ensurePrivateDir(path.dirname(this.path));
     if (process.platform === 'darwin') {
-      const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK | fs.constants.O_NONBLOCK;
-      try {
-        this.fd = fs.openSync(this.path, flags, 0o600);
-      } catch (error) {
-        if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
-        throw error;
-      }
-      try {
-        fs.ftruncateSync(this.fd, 0);
-        fs.writeSync(this.fd, String(process.pid));
-        fs.fsyncSync(this.fd);
-      } catch (error) { // a full disk or an I/O error: let the lock go, or nobody can (the caller drops this object)
-        const fd = this.fd;
-        this.fd = null;
-        try {
-          fs.closeSync(fd);
-        } catch { // a deferred write error (NFS) at the close: the lock still goes, the first error stands
-        }
-        throw error;
+      // FAA-293: a folder swapped under service.lock (a data import) leaves this copy holding a file that is no longer
+      // at the path while another copy holds the one that is. Re-open a bounded number of times, then fail clearly.
+      for (let attempt = 0; attempt < InstanceLock.INODE_RETRIES; attempt += 1) {
+        if (this.acquireDarwinOnce()) return this;
       }
-      return this;
+      throw new ServiceError(`${this.path} kept moving while it was locked (a folder swapped under the data folder?): no copy holds a file that is no longer at its path; start again once the folder is settled.`);
     }
     // Linux: an abstract unix socket; Windows: a named pipe. Each is exclusive, has no file, and dies
     // with the process. The Python kit holds the same name beside its file lock (fabric_service.lock_name).
@@ -90,6 +78,52 @@ export class InstanceLock {
     return this;
   }
 
+  lockedFileIsAtPath(fd) {
+    let here;
+    try {
+      here = fs.statSync(this.path);
+    } catch (error) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    }
+    const held = fs.fstatSync(fd);
+    return here.dev === held.dev && here.ino === held.ino;
+  }
+
+  acquireDarwinOnce() {
+    const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK | fs.constants.O_NONBLOCK;
+    try {
+      this.fd = fs.openSync(this.path, flags, 0o600);
+    } catch (error) {
+      if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
+      throw error;
+    }
+    if (!this.lockedFileIsAtPath(this.fd)) { // another copy may hold the file at the path: re-open that one
+      fs.closeSync(this.fd);
+      this.fd = null;
+      return false;
+    }
+    try {
+      fs.ftruncateSync(this.fd, 0);
+      fs.writeSync(this.fd, String(process.pid));
+      fs.fsyncSync(this.fd);
+    } catch (error) { // a full disk or an I/O error: let the lock go, or nobody can (the caller drops this object)
+      const fd = this.fd;
+      this.fd = null;
+      try {
+        fs.closeSync(fd);
+      } catch { // a deferred write error (NFS) at the close: the lock still goes, the first error stands
+      }
+      throw error;
+    }
+    if (!this.lockedFileIsAtPath(this.fd)) { // swapped while the pid was written: this copy holds nothing real
+      fs.closeSync(this.fd);
+      this.fd = null;
+      return false;
+    }
+    return true;
+  }
+
   release() {
     if (this.fd !== null) fs.closeSync(this.fd);
     if (this.server) this.server.close();

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

@@ -277,6 +277,9 @@ export class Client {
         }
         attempts.push({ model: current, status: result.status, outcome: result.outcome });
         if (result.answer) return { ...result.answer, attempts };
+        if (result.outcome === 'foreign-user') { // FAA-257: the fallback would go to the same refused listener
+          throw new OpenRouterError('The base URL\'s port is held by another OS account\'s process, or its owner cannot be told; nothing was sent (DEC-0154 HA-2)', { kind: 'foreign-user', attempts });
+        }
         if (Object.values(STOP_AT_ONCE).includes(result.outcome)) {
           throw new OpenRouterError(`OpenRouter refused the key or the request (${result.status})`, { kind: result.outcome, attempts });
         }
@@ -299,6 +302,7 @@ export class Client {
         // may have been billed (a cut connection looks like a refused one from here): counted, never as $0
         this.ledger.record(this.unmeasured(asked, taskRunId, worst));
       }
+      if (err.kind === 'foreign-user') return { outcome: 'foreign-user', status: err.status }; // nothing sent, nothing billed (FAA-257)
       return { outcome: ['connection', 'timeout'].includes(err.kind) ? 'retry' : 'refused', status: err.status };
     }
     const { status } = response;

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.3'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
+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 THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -154,6 +154,10 @@ export function parseNetstat(text) {
   const at = names.indexOf('process:pid');
   const leading = at - names.slice(0, at).filter((w) => w === 'Address').length;
   const trailing = names.length - at - 1;
+  // The caller's own connection is in any table it can see: a header and no tcp row is the restricted table (FAA-273).
+  if (!lines.slice(header + 1).some((line) => (line.split(/\s+/).filter(Boolean)[0] ?? '').startsWith('tcp'))) {
+    throw new TableUnreadable(`${TABLE_RESTRICTED}: netstat printed only its header to this process`);
+  }
   const rows = [];
   for (const line of lines.slice(header + 1)) {
     const tok = line.split(/\s+/).filter(Boolean);
@@ -534,7 +538,9 @@ export async function pidListens(pid, port, { run = runProgram, platform = proce
 // 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, vouchPid = null, ...ask } = {}) {
   return new Promise((resolveSocket, reject) => {
-    const socket = net.connect({ host, port, noDelay: true }); // as a plain http.Agent's socket
+    // autoSelectFamily: Node 18 connects to the first address only, and localhost resolves to ::1 first on Linux, so a
+    // listener on 127.0.0.1 was never reached; Python tries every address, as Node 20 and later do by default.
+    const socket = net.connect({ host, port, noDelay: true, autoSelectFamily: true }); // as a plain http.Agent's socket
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), timeoutMs);
     socket.once('error', (err) => { clearTimeout(timer); reject(err); });
     socket.once('connect', async () => {

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

@@ -66,7 +66,10 @@ export function rawValues(query) {
     if (piece === '') continue;
     const at = piece.indexOf('=');
     const name = [...new URLSearchParams(at < 0 ? piece : piece.slice(0, at)).keys()][0] ?? '';
-    values.set(name, [...(values.get(name) ?? []), at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1))]);
+    const value = at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1));
+    const list = values.get(name);
+    if (list) list.push(value); // appended in place: copying the list per piece made a long query quadratic (FAA-245)
+    else values.set(name, [value]);
   }
   return values;
 }

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

@@ -5,6 +5,7 @@
 export {
   PROTOCOL,
   EXTENSION_KEY,
+  PRIMARY_CAPABILITY,
   SUPERVISOR_ENV,
   DRAIN_SECONDS,
   ServiceError,
@@ -42,6 +43,10 @@ export {
 } from './fabric-protocols.mjs';
 export { ACTIONS_EXTENSION_KEY, actionDecision, actionRules, actionsExtension, actionsExtensionRules, actionsView, decisionShape } from './fabric-actions.mjs';
 export { CONNECTIONS_EXTENSION_KEY, connectionsExtension, connectionsRules, connectionsView } from './fabric-connections.mjs';
+export { // the call queue and the load report (DEC-0104, FAA-289)
+  DEFAULT_RETRY_AFTER_SECONDS, LOAD_EXTENSION_KEY, LOAD_REPORT_TYPE, QUEUE_FULL_MESSAGE, QUEUE_LENGTH_MAX, admitJob, jobCallerKey, jobQueueRules,
+  loadExtension, loadExtensionRules, loadReportProblems, loadReportRules, loadView, nextQueuedJob, queueStatusMessage, readQueuePosition,
+} from './fabric-load.mjs';
 export {
   EXIT_ALREADY_RUNNING,
   LOCK_WAIT_SUPERVISED_SECONDS,
@@ -117,7 +122,9 @@ export {
   fabricButtonPresence,
   placementOf,
   remoteOriginProblems,
+  portListenerRefusal,
   portOf,
+  portOwner,
   NO_SOURCE_REPOSITORY,
   namesRepository,
   sourceRefusal,
@@ -179,6 +186,7 @@ export {
   launchdPlist,
   SYSTEM_DAEMONS,
   launchdDomain,
+  wellKnownOf,
   jobWellKnownOf,
   ForeignUserAnswer,
   launchdLoaded,

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

@@ -115,12 +115,33 @@ export function systemdUnit(unit, programArguments, { workingDirectory, environm
 
 const systemdDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
 
+// FAA-253: the well-known answer at `origin`, polled until this OS account's listener answers as serviceId.instance, as
+// launchdInstall does (the pinned contract's Install row: every supervisor polls). Another account's listener, or one
+// whose owner cannot be told, is never a successful install (DEC-0154 HA-2).
+async function pollInstalled(origin, { serviceId, instance = 'default', timeout = 40, fetchWellKnown = wellKnownOf, sleep = pause, clock = Date.now } = {}) {
+  if (!serviceId) throw new ServiceError(`polling the install at ${origin} needs the serviceId it must answer as`);
+  const deadline = clock() + Math.max(0, timeout) * 1000;
+  let foreign = null;
+  for (;;) {
+    const doc = await fetchWellKnown(origin);
+    foreign = doc instanceof ForeignUserAnswer ? doc.reason : null;
+    if (!foreign && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
+    if (clock() >= deadline) break;
+    await sleep(500);
+  }
+  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.`);
+  throw new ServiceError(`${origin} did not answer as ${serviceId}.${instance} within ${timeout} s; read its log.`);
+}
+
 /**
  * Write the user unit, enable it so it comes back after a login, and (re)start it so the new unit is what runs.
  * The operator's intent wins (LC-14): a unit already installed and disabled stays off — the file is rewritten, so the
- * new version is what starts once they enable it — unless `forceEnable` (the operator asked for it on).
+ * new version is what starts once they enable it — unless `forceEnable` (the operator asked for it on). With `origin`
+ * (and `serviceId`) it then polls the well-known answer as launchdInstall does and resolves to the unit file once this
+ * account's listener answers (FAA-253); without `origin` it stays synchronous.
  */
-export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defaultRun, platform = process.platform, forceEnable = false,
+  origin, serviceId, instance, timeout, fetchWellKnown, sleep, clock } = {}) {
   if (platform !== 'linux') throw new ServiceError('systemd is the supervisor on Linux only.');
   if (!UNIT.test(unit)) throw new ServiceError(`unit must match ${UNIT.source}`);
   fs.mkdirSync(unitDir, { recursive: true });
@@ -128,10 +149,14 @@ export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defau
   const state = fs.existsSync(file) ? String(run(['systemctl', '--user', 'is-enabled', unit])?.stdout ?? '').trim() : '';
   atomicWrite(file, text, 0o644);
   checkRun(run(['systemctl', '--user', 'daemon-reload']), 'systemctl --user daemon-reload');
-  if (state === 'disabled' && !forceEnable) return file;
-  checkRun(run(['systemctl', '--user', 'enable', unit]), 'systemctl --user enable');
-  checkRun(run(['systemctl', '--user', 'restart', unit]), 'systemctl --user restart');
-  return file;
+  const started = !(state === 'disabled' && !forceEnable);
+  if (started) {
+    checkRun(run(['systemctl', '--user', 'enable', unit]), 'systemctl --user enable');
+    checkRun(run(['systemctl', '--user', 'restart', unit]), 'systemctl --user restart');
+  }
+  if (origin === undefined) return file;
+  // FAA-253: with an origin it resolves once this account's listener answers; a unit kept off is not polled.
+  return started ? pollInstalled(origin, { serviceId, instance, timeout, fetchWellKnown, sleep, clock }).then(() => file) : Promise.resolve(file);
 }
 
 /** Stop it and keep it off across logins (`disable --now`), then remove the unit. */
@@ -203,9 +228,12 @@ const TASK_DISABLED = /<Settings>(?:(?!<\/Settings>)[\s\S])*<Enabled>false<\/Ena
 
 /**
  * Create (or replace) the task from its XML without administrator rights, then (re)start it so the new definition
- * is what runs. A task already installed and disabled stays off (LC-14) unless `forceEnable`.
+ * is what runs. A task already installed and disabled stays off (LC-14) unless `forceEnable`. With `origin` (and
+ * `serviceId`) it then polls the well-known answer as launchdInstall does and resolves to it (FAA-253); a task kept off
+ * resolves to undefined, unpolled. Without `origin` it stays synchronous.
  */
-export function taskInstall(task, xmlText, { run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+export function taskInstall(task, xmlText, { run = defaultRun, platform = process.platform, forceEnable = false,
+  origin, serviceId, instance, timeout, fetchWellKnown, sleep, clock } = {}) {
   if (platform !== 'win32') throw new ServiceError('Task Scheduler is the supervisor on Windows only.');
   const query = run(['schtasks', '/Query', '/TN', task, '/XML']);
   const existed = query?.status === 0;
@@ -221,10 +249,11 @@ export function taskInstall(task, xmlText, { run = defaultRun, platform = proces
   }
   if (keepOff) {
     checkRun(run(['schtasks', '/Change', '/TN', task, '/DISABLE']), 'schtasks /Change /DISABLE');
-    return;
+    return origin === undefined ? undefined : Promise.resolve(undefined);
   }
   if (existed) run(['schtasks', '/End', '/TN', task]);
   checkRun(run(['schtasks', '/Run', '/TN', task]), 'schtasks /Run');
+  return origin === undefined ? undefined : pollInstalled(origin, { serviceId, instance, timeout, fetchWellKnown, sleep, clock });
 }
 
 /** End the running task, then delete it. */
@@ -490,8 +519,20 @@ 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, { vouchPid = null } = {}) {
-  const m = /^http:\/\/127\.0\.0\.1:([0-9]{1,5})$/.exec(origin);
+// Every loopback spelling (127.0.0.1, another 127/8 address, localhost, [::1]) goes on a checked connection, never the
+// unchecked way (FAA-257): the host, without brackets, and the port, or null.
+function loopbackOrigin(origin) {
+  let url;
+  try { url = new URL(String(origin)); } catch { return null; }
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  const loop = host === 'localhost' || host === '::1' || (net.isIPv4(host) && host.startsWith('127.'));
+  if (url.protocol !== 'http:' || !loop) return null;
+  // new URL drops a default port: http://127.0.0.1:80 has port '', read as 80 as Python's urlsplit reads it (0.79.0 seam)
+  return { host, port: Number(url.port || 80) };
+}
+
+export async function wellKnownOf(origin, { vouchPid = null, ask = undefined } = {}) {
+  const m = loopbackOrigin(origin);
   if (!m) {
     try {
       const response = await fetch(`${origin}/.well-known/fabric-service`, { signal: AbortSignal.timeout(2000) });
@@ -502,14 +543,14 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   }
   // 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.
-  return loopbackWellKnown(Number(m[1]), new CheckedAgent({ keepAlive: false, vouchPid }));
+  return loopbackWellKnown(m.port, new CheckedAgent({ keepAlive: false, vouchPid, ...(ask ? { ask } : {}) }), m.host);
 }
 
 // The well-known answer at 127.0.0.1:<port> over `agent`, whose connections check their server end: null when nothing
 // answers or the answer is not JSON, a ForeignUserAnswer when the agent refused the listener.
-function loopbackWellKnown(port, agent) {
+function loopbackWellKnown(port, agent, host = '127.0.0.1') {
   return new Promise((resolve) => {
-    const req = http.request({ host: '127.0.0.1', port, path: '/.well-known/fabric-service', agent,
+    const req = http.request({ host, port, path: '/.well-known/fabric-service', agent,
       timeout: 2000 }, (res) => {
       const chunks = [];
       res.on('data', (c) => chunks.push(c));

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

@@ -70,7 +70,14 @@ function byProject(receipts, first, last) {
   const close = ({ cost, ...rest }) => ({ ...rest, costUsd: rest.calls && rest.unpricedCalls === rest.calls ? null : Math.round(cost * 1e6) / 1e6 });
   return [...projects.keys()].sort().map((key) => {
     const { runs, ...row } = projects.get(key);
-    const taskRuns = [...runs.keys()].sort().map((id) => close(runs.get(id)));
+    // A run's cost rounds as the project's does but never above its exact cost: each run and the project round apart,
+    // so many runs rounding up summed past the project and failed FAC-SEM-025 (board request f5753c5a).
+    const closeRun = (run) => {
+      const out = close(run);
+      if (out.costUsd !== null && out.costUsd > run.cost) out.costUsd = Math.round((out.costUsd - 0.000001) * 1e6) / 1e6;
+      return out;
+    };
+    const taskRuns = [...runs.keys()].sort().map((id) => closeRun(runs.get(id)));
     return { ...close(row), ...(taskRuns.length ? { taskRuns } : {}) };
   });
 }

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

@@ -16,6 +16,12 @@ PROTOCOL = "fabric-service/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/service/0.1"
 
 
+# DEC-0140 PR-1 (contract project-comms.md, interop.md's C3.1 amendment): the capability of a Project's primary
+# responder, a session's. No service serves it as a tool or declares it (surfaces.mcp.capabilities, an action's tool),
+# and the board kit never enrolls a service's responder for it (FAA-244).
+PRIMARY_CAPABILITY = "project.work"
+
+
 # Lifecycle rules: references/lifecycle.md, the rule for this kit's users, which implements the public
 # contract's service specification (Lifecycle). A launchd-supervised copy that finds the lock held backs
 # off in-process for this long before its exit 75 (LC-03, F8): under KeepAlive with ThrottleInterval 10

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

@@ -52,6 +52,9 @@ class BoardSession:
                              timeout=timeout if timeout is not None and timeout > 0 else self.timeout,
                              method=method, protocol_version=self.protocol_version if self.mcp_session else None)
         except _hub.HubError as exc:
+            if exc.code == "foreign-user":  # FAA-252: another OS account's process holds the port; nothing was sent
+                raise BoardError("foreign-user", "The hub's port is held by another OS account's process; nothing was sent.",
+                                 True) from exc
             raise BoardError("unreachable", "Fabric's hub did not answer; a write may have been stored, so send it again with "
                              "the same idempotency key.", True) from exc
 

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

@@ -148,6 +148,9 @@ class Responder(SlotKeeper):
         caps = list(capabilities)
         if not caps or any(not isinstance(c, str) or not _CAPABILITY.fullmatch(c) for c in caps) or len(set(caps)) != len(caps):
             raise BoardError("invalid_arguments", "Name each capability once, [a-z][a-z0-9._-]{1,127}.")
+        if _fs.PRIMARY_CAPABILITY in caps:  # FAA-244: DEC-0140 PR-1, a session's slot, never a service's
+            raise BoardError("invalid_arguments", "%s is a Project's primary responder's, a session's: a service answers "
+                             "the capabilities it declares (DEC-0140 PR-1)." % _fs.PRIMARY_CAPABILITY)
         self.hub, self.project = hub, _hub._project(project_id)
         #: FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; None reads none).
         self.mandate_from, self.agent_id, self.wall = _link.mandate_options(agent_id, mandate_from), agent_id, wall
@@ -165,6 +168,7 @@ class Responder(SlotKeeper):
         self.state = "idle"
         self.wait_until = 0.0
         self.stopping = False
+        self.shutting_down, self.draining = threading.Event(), None  # shutdown began; it found work to drain (FAA-186)
         self.claim_keys: Dict[str, str] = {}
         self._probing: set = set()  # moved slots whose move-back claim lost its answer: asked again under the same key
         self._said: Dict[str, str] = {}
@@ -258,7 +262,7 @@ class Responder(SlotKeeper):
         status = self._status()
         if missing:
             self._emit("board.access.needed", "warning", "The operator has not let this service answer %s on this Project; ask in "
-                       "Fabric (Agents & access)." % ", ".join(missing), notify=True, episode=",".join(missing),
+                       "Fabric (Settings → Agent access)." % ", ".join(missing), notify=True, episode=",".join(missing),
                        capabilities=missing)
         self.slots = {}
         self._recover(status, [c for c in self.capabilities if c in grant.capabilities])
@@ -430,7 +434,8 @@ class Responder(SlotKeeper):
         try:
             self._receipt("com.reply", self._call("com.reply", dict(self._reply_extra(entry), fence=self._fence(old, probe["key"]))))
         except BoardError as exc:
-            if exc.code in ("unreachable", "session-ended", "authority_changed", "not_authorized", "not_available", "capacity_exceeded"):
+            if exc.code in ("unreachable", "foreign-user", "session-ended", "authority_changed", "not_authorized", "not_available",
+                            "capacity_exceeded"):  # foreign-user: nothing was sent now, so nothing is known (0.79.0 seam)
                 raise
         else:
             entry["replied"] = True
@@ -549,7 +554,7 @@ class Responder(SlotKeeper):
             self.state = "not-authorized"
             self._drop_session()
             self._emit("board.access.needed", "warning", "This service may not answer requests for this Project: the operator "
-                       "has to allow it in Fabric (Agents & access). Nothing is claimed until then.", notify=True,
+                       "has to allow it in Fabric (Settings → Agent access). Nothing is claimed until then.", notify=True,
                        episode="access", reason=code)
         elif code == "held":
             self.state = "paused"
@@ -564,9 +569,13 @@ class Responder(SlotKeeper):
         else:
             self.state = "down"
             # In recovery with no slot held a refusal reconnects (seam 6); with some held they are served (seam 7).
-            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol")) and not keep:
+            if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol",
+                                       "foreign-user")) and not keep:
                 self._drop_session()
-            self._emit("board.down", "warning", "Fabric's board cannot be reached; the responder tries again with a growing pause.",
+            # FAA-252: a port another OS account holds is said as such; nothing was sent there
+            self._emit("board.down", "warning", "Fabric's board port is held by another OS account's process; nothing was sent, "
+                       "and the responder tries again with a growing pause." if code == "foreign-user" else
+                       "Fabric's board cannot be reached; the responder tries again with a growing pause.",
                        episode="down", reason=code)
         return wait
 
@@ -974,8 +983,8 @@ class Responder(SlotKeeper):
     def shutdown(self, drain: float = DRAIN_SECONDS) -> None:
         """Stop claiming, give running work up to `drain` seconds to finish and be completed, then leave the session
         (its DELETE releases the slots). What is still open stays in the checkpoint for the next start."""
-        self.stopping = True
-        work = self.current
+        self.stopping, work = True, self.current
+        self.draining = work is not None; self.shutting_down.set()  # noqa: E702 - published before it waits (FAA-186)
         if work is not None and not work.done.wait(drain):
             work.ctx.stopped.set()
         if work is not None and work.done.is_set() and self.session is not None:

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

@@ -20,7 +20,7 @@ HOLD_RETRY_MAX_SECONDS = 900.0
 #: Refusals that are about the board session, not one capability: they end recovery and go to the responder's fault.
 SESSION_CODES = frozenset(["unreachable", "session-ended", "not_authorized", "authority_changed", "credential", "no-epoch",
                            "schema-unsupported", "checkpoint", "receipt-shape", "idempotency_conflict", "not-running",
-                           "not-a-hub", "hub-unavailable", "protocol", "not_available"])
+                           "not-a-hub", "hub-unavailable", "protocol", "not_available", "foreign-user"])
 
 _whole = lambda v: int(v) if isinstance(v, float) and v.is_integer() else v  # noqa: E731 - 2.0 is 2, as Node reads it
 
@@ -78,7 +78,7 @@ class SlotKeeper:
                 if _is_int(generation, 1) and (answer.get("repeated") is True or not moved):
                     rest = {"project": self.project, "generation": generation}
             except BoardError as exc:
-                if exc.code in ("unreachable", "session-ended"):
+                if exc.code in ("unreachable", "session-ended", "foreign-user"):  # foreign-user: the earlier ask is unknown
                     raise
                 if exc.code == "idempotency_window_expired":
                     rest = {}  # a retired epoch refuses even a repeat: unknown, so no record (a first start, never a move)
@@ -247,3 +247,5 @@ class SlotKeeper:
             self._retry_later(capability, entries or [], exc)
             if exc.code in SESSION_CODES:
                 raise
+            if exc.code == "idempotency_window_expired":
+                self._status()  # the epoch moved: read it before the retry, which no held slot would do (FAA-186)

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

@@ -4,8 +4,10 @@
 `degraded[]`. Part of the service kit (FAA-62, layer L3). Standard library only."""
 from __future__ import annotations
 
+import bisect
 import ipaddress
 import re
+import unicodedata
 import urllib.parse
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
 
@@ -173,6 +175,92 @@ _FORBIDDEN_HOST = set("\x00\t\n\r #/:<>?@[\\]^|")
 _FORBIDDEN_DOMAIN = _FORBIDDEN_HOST | set(chr(c) for c in range(0x20)) | {"%", "\x7f"}
 
 
+# FAA-98: UTS46 narrowed, not ported. A non-ASCII host is refused only where every Node from 20 to 26 refuses it, so
+# the doubt stays on the closed side (its URL's credentials are read). The two tables are measured by
+# test/fixtures/idna/make_idna_tables.mjs (idna-tables.json, held equal by test_the_idna_tables_are_the_measured_ones):
+# code points refused in every context, and code points removed between letters. The contextual rules read Unicode 3.2
+# classes (`unicodedata.ucd_3_2_0`) and skip what that Unicode does not know, since Node's own UTS46 data lags its
+# Unicode: an Arabic letter of Unicode 14 is no right-to-left letter to it.
+_IDNA_DISALLOWED = (
+    (0x80, 0xa0), (0xa8, 0xa8), (0xaf, 0xaf), (0xb4, 0xb4), (0xb8, 0xb8), (0x2d8, 0x2dd), (0x37a, 0x37a),
+    (0x384, 0x385), (0x600, 0x605), (0x61c, 0x61c), (0x6dd, 0x6dd), (0x70f, 0x70f), (0x890, 0x891), (0x8e2, 0x8e2),
+    (0x1680, 0x1680), (0x1fbd, 0x1fbd), (0x1fbf, 0x1fc1), (0x1fcd, 0x1fcf), (0x1fdd, 0x1fdf), (0x1fed, 0x1fee),
+    (0x1ffd, 0x1ffe), (0x2000, 0x200a), (0x200e, 0x200f), (0x2017, 0x2017), (0x2024, 0x2026), (0x2028, 0x202f),
+    (0x203e, 0x203e), (0x2047, 0x2049), (0x205f, 0x205f), (0x2066, 0x2069), (0x2100, 0x2101), (0x2105, 0x2106),
+    (0x2488, 0x249b), (0x2a74, 0x2a74), (0x2ff0, 0x3000), (0x309b, 0x309c), (0x31ef, 0x31ef), (0x33c2, 0x33c2),
+    (0x33c7, 0x33c7), (0x33d8, 0x33d8), (0xe000, 0xf8ff), (0xfc5e, 0xfc63), (0xfdfa, 0xfdfb), (0xfe12, 0xfe13),
+    (0xfe16, 0xfe16), (0xfe19, 0xfe19), (0xfe30, 0xfe30), (0xfe47, 0xfe4c), (0xfe52, 0xfe52), (0xfe55, 0xfe56),
+    (0xfe5f, 0xfe5f), (0xfe64, 0xfe65), (0xfe68, 0xfe68), (0xfe6a, 0xfe6b), (0xfe70, 0xfe70), (0xfe72, 0xfe72),
+    (0xfe74, 0xfe74), (0xfe76, 0xfe76), (0xfe78, 0xfe78), (0xfe7a, 0xfe7a), (0xfe7c, 0xfe7c), (0xfe7e, 0xfe7e),
+    (0xff03, 0xff03), (0xff05, 0xff05), (0xff0f, 0xff0f), (0xff1a, 0xff1a), (0xff1c, 0xff1c), (0xff1e, 0xff20),
+    (0xff3b, 0xff3e), (0xff5c, 0xff5c), (0xffe3, 0xffe3), (0xfff9, 0xfffd), (0x110bd, 0x110bd), (0x110cd, 0x110cd),
+    (0x13430, 0x1343f), (0x1f100, 0x1f100), (0xe0001, 0xe0001), (0xe0020, 0xe007f), (0xf0000, 0xffffd),
+    (0x100000, 0x10fffd),
+)
+_IDNA_IGNORED = (
+    (0xad, 0xad), (0x34f, 0x34f), (0x180b, 0x180d), (0x180f, 0x180f), (0x200b, 0x200b), (0x2060, 0x2060),
+    (0x2064, 0x2064), (0xfe00, 0xfe0f), (0xfeff, 0xfeff), (0x1bca0, 0x1bca3), (0xe0100, 0xe01ef),
+)
+_IDNA_DOTS = re.compile("[.\u3002\uff0e\uff61]")
+_U32 = unicodedata.ucd_3_2_0
+_RTL_OK = {"R", "AL", "AN", "EN", "ES", "CS", "ET", "ON", "BN", "NSM"}
+_JOINERS = "\u200c\u200d"
+
+
+def _in_ranges(ranges: Sequence[tuple], cp: int) -> bool:
+    i = bisect.bisect_right(ranges, (cp, 0x10ffff)) - 1
+    return i >= 0 and ranges[i][0] <= cp <= ranges[i][1]
+
+
+def _known(c: str) -> bool:
+    return _U32.category(c) != "Cn" and unicodedata.category(c) != "Cn"
+
+
+def _joiner_refused(label: str, i: int) -> bool:
+    """CheckJoiners as Node 20 to 26 all read it: they find a joining context, or a virama, anywhere in the label
+    (`\u0628a\u200c\u0627` and `\u0628\u200c\u0627\u200d` parse), so only a joiner with nothing but ASCII beside it
+    in its label has none for certain."""
+    return all(c.isascii() for j, c in enumerate(label) if j != i)
+
+
+def _bidi_refused(label: str) -> bool:
+    """RFC 5893 as Node 20 to 26 all read it: only a label holding R, AL or AN is judged, and its first code point is
+    not (Node 26 alone refuses a label opening with a digit or a hyphen)."""
+    if not label or not all(_known(c) for c in label) or any(c in _JOINERS for c in label):
+        return False  # Node 20 to 26 pass a label holding a joiner over (`\u05d0a\u094d\u200d` parses)
+    k = [_U32.bidirectional(c) for c in label]
+    if not any(x in ("R", "AL", "AN") for x in k):
+        return False
+    body = list(k)
+    while body and body[-1] == "NSM":
+        body.pop()
+    if not body or body[-1] not in ("R", "AL", "EN", "AN"):
+        return True
+    return k[0] in ("R", "AL") and (any(x not in _RTL_OK for x in k) or ("EN" in k and "AN" in k))
+
+
+def _idna_host(host: str) -> Optional[str]:
+    """None where WHATWG's domain-to-ASCII refuses a non-ASCII host for certain; else the host as UTS46 maps it, read
+    as NFKC with case folding (exact enough for the ASCII rules that follow, which read digits and dots)."""
+    if any(_in_ranges(_IDNA_DISALLOWED, ord(c)) for c in host):
+        return None
+    kept = "".join(c for c in host if not _in_ranges(_IDNA_IGNORED, ord(c)))
+    if kept == "":
+        return None  # nothing left: an empty host
+    if not all(_known(c) for c in kept):
+        return host  # a code point this Python's Unicode does not know: the contextual rules are not read
+    mapped = unicodedata.normalize("NFC", unicodedata.normalize("NFKC", unicodedata.normalize("NFKC", kept).casefold()))
+    for label in _IDNA_DOTS.split(mapped):
+        first = label[:1]
+        if first and first not in "\u17b4\u17b5" and _U32.category(first)[0] == "M" and unicodedata.category(first)[0] == "M":
+            return None  # a label opening with a mark (U+17B4 and U+17B5 are ignored by the newer Nodes)
+        if any(c in _JOINERS and _joiner_refused(label, i) for i, c in enumerate(label)):
+            return None
+        if _bidi_refused(label):
+            return None
+    return _IDNA_DOTS.sub(".", mapped)
+
+
 def _ipv4_number(part: str) -> Optional[int]:
     if part == "":
         return None  # an empty part fails WHATWG's IPv4 parser (`1..2`); `0x` alone is 0
@@ -198,10 +286,16 @@ def _domain_ok(host: str) -> bool:
             return False
     if any(c in _FORBIDDEN_DOMAIN for c in host):
         return False
-    # A non-ASCII host goes through UTS46 in WHATWG; this module does not port it. When unsure, the host is taken as
-    # valid, so its URL's credentials are read: the doubt then hides a list rather than publish one (round-2 reading).
+    # A non-ASCII host goes through UTS46 in WHATWG; this module reads it narrowly (_idna_host, FAA-98). When unsure,
+    # the host is taken as valid, so its URL's credentials are read: the doubt then hides a list rather than publish one
+    # (round-2 reading). A host UTS46 maps to ASCII is read by the ASCII rules below (`１２７.０.０.１` is an address).
     if any(ord(c) > 0x7f for c in host):
-        return True
+        mapped = _idna_host(host)
+        if mapped is None:
+            return False
+        if not mapped.isascii() or any(c in _FORBIDDEN_DOMAIN for c in mapped):
+            return True
+        host = mapped
     labels = host.split(".")
     if labels and labels[-1] == "" and len(labels) > 1:
         labels = labels[:-1]