@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

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. */
@@ -314,6 +343,8 @@ function guiDomain(platform, uid) {
 /** Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278). */
 export const SYSTEM_DAEMONS = '/Library/LaunchDaemons';
 const USER_NAME = /^[a-z_][a-z0-9_.-]{0,31}$/;
+/** The short-name rule in words, printed alike by both twins (FAA-286 item 13). */
+export const USER_NAME_RULE = 'a lower-case letter or _, then up to 31 lower-case letters, digits, _, . or -';
 
 /**
  * The launchd domain a job lives in: `system` for a LaunchDaemon (`domain: 'system'`, or a plist in
@@ -322,6 +353,9 @@ const USER_NAME = /^[a-z_][a-z0-9_.-]{0,31}$/;
  */
 export function launchdDomain(plistPath = null, { domain = null, platform = process.platform, uid } = {}) {
   if (![null, undefined, 'gui', 'system'].includes(domain)) throw new ServiceError('domain must be gui or system');
+  if (plistPath !== null && plistPath !== undefined && /^(?:system|gui)(?:\/[0-9]*)?$/.test(String(plistPath))) {
+    throw new ServiceError(`${plistPath} is a launchd domain, not a plist path: pass { domain: '${String(plistPath) === 'system' ? 'system' : 'gui'}' } (FAA-286)`);
+  }
   let which = domain;
   if ((which === null || which === undefined) && plistPath !== null && plistPath !== undefined) {
     const paths = platform === 'darwin' ? path.posix : path; // a macOS path, whatever host reads it
@@ -334,6 +368,34 @@ export function launchdDomain(plistPath = null, { domain = null, platform = proc
   return guiDomain(platform, uid);
 }
 
+// A domain the plist's folder contradicts (FAA-286 items 14 and 21): a system job in a LaunchAgents folder (launchd also
+// loads it into gui/<uid> at login), or a gui job in /Library/LaunchDaemons (launchd loads it at boot as root). Another
+// folder is allowed for a system job, as the tests' and a staging install's are.
+function pairProblem(plistPath, domain, platform) {
+  const paths = platform === 'darwin' ? path.posix : path;
+  const folder = paths.dirname(paths.resolve(String(plistPath)));
+  const parts = String(plistPath).split(/[\\/]+/); // the folder's own name, whatever separator a test's host path uses
+  if (domain === 'system' && String(parts[parts.length - 2] ?? '').toLowerCase() === 'launchagents') {
+    return `A LaunchDaemon's plist lives in ${SYSTEM_DAEMONS}: ${plistPath} is in a LaunchAgents folder, which launchd also loads into gui/<uid> at login, so the job would run twice.`;
+  }
+  if (domain === 'gui' && folder.toLowerCase() === SYSTEM_DAEMONS.toLowerCase()) {
+    return `${plistPath} is in ${SYSTEM_DAEMONS}, which launchd loads at boot as a LaunchDaemon: a gui/<uid> job's plist goes in ~/Library/LaunchAgents.`;
+  }
+  return null;
+}
+
+// A LaunchAgent of `label` in `userName`'s ~/Library/LaunchAgents, which would run a second copy at its login (FAA-286
+// item 6); null when there is none or the home cannot be read.
+function leftoverAgent(label, userName, run) {
+  const read = run(['dscl', '.', '-read', `/Users/${userName}`, 'NFSHomeDirectory']);
+  const home = read?.status === 0 ? /NFSHomeDirectory:\s*(\S.*?)\s*$/m.exec(String(read.stdout ?? ''))?.[1] : null;
+  if (!home) return null;
+  const folder = path.join(home, 'Library', 'LaunchAgents');
+  let names = [];
+  try { names = fs.readdirSync(folder).filter((n) => n.endsWith('.plist')).sort(); } catch { return null; }
+  return names.map((n) => path.join(folder, n)).find((file) => topKey(plistXml(file, run), 'Label') === label) ?? null;
+}
+
 // A system-domain job is installed and removed by root: refuse before anything is written (FAA-278).
 function needRoot(domain, label, plistPath, install, euid) {
   if (domain !== 'system' || euid === 0) return;
@@ -361,6 +423,9 @@ function decodeXml(text) {
 function topStrings(text) {
   const token = /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[^>]*>|<!\[CDATA\[([\s\S]*?)\]\]>|<(\/?)([A-Za-z][\w.:-]*)\s*[^>]*?(\/?)>|([^<]+)/g;
   const values = Object.create(null);
+  // The open containers: only the root dict's own keys are read (FAA-286 item 10: a root <array> holding a
+  // <key>UserName</key> is no dict, as plistlib reads it).
+  const open = [];
   let depth = 0;
   let key = null;
   let capture = null;
@@ -369,17 +434,21 @@ function topStrings(text) {
     for (let m = token.exec(String(text ?? '')); m; m = token.exec(String(text ?? ''))) {
       const [, cdata, closing, name, selfClosing, chars] = m;
       if (cdata !== undefined || chars !== undefined) {
-        if (capture) buffer += cdata !== undefined ? cdata : decodeXml(chars);
+        // every character reference, at any depth and in any value, is checked as expat checks it (FAA-286 item 10)
+        const decoded = chars !== undefined ? decodeXml(chars) : cdata;
+        if (capture) buffer += decoded;
       } else if (name === 'dict' || name === 'array') {
         if (selfClosing) {
           if (depth === 1 && key !== null) { delete values[key]; key = null; }
         } else if (closing) {
           depth -= 1;
+          open.pop();
         } else {
           if (depth === 1 && key !== null) { delete values[key]; key = null; } // a container is this key's value
           depth += 1;
+          open.push(name);
         }
-      } else if (name && depth === 1) {
+      } else if (name && depth === 1 && open[0] === 'dict') {
         if (selfClosing) {
           if (key !== null) {
             if (name === 'string') values[key] = '';
@@ -402,6 +471,7 @@ function topStrings(text) {
   } catch {
     return null;
   }
+  if (key !== null || capture !== null || depth !== 0) return null; // a dangling <key> or an open element: unreadable
   return values;
 }
 
@@ -540,8 +610,8 @@ 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) {
-  if (process.platform !== 'darwin' || !Number.isInteger(pid) || pid <= 1) return false;
+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
@@ -571,7 +641,11 @@ class JobAgent extends http.Agent {
     this.ask = ask;
   }
 
-  createConnection(options, callback) {
+  createConnection(options, given) {
+    // One answer per connection (FAA-286 item 12): an error during the async owner, lsof and ps checks would reach the
+    // callback a second time, as CheckedAgent's checkedSocket guards it.
+    let answered = false;
+    const callback = (err, socket) => { if (!answered) { answered = true; given(err, socket); } };
     const port = Number(options.port);
     const socket = net.connect({ host: '127.0.0.1', port, noDelay: true });
     const timer = setTimeout(() => socket.destroy(Object.assign(new Error('connect timeout'), { code: 'ETIMEDOUT' })), options.timeout ?? 10000);
@@ -585,14 +659,14 @@ class JobAgent extends http.Agent {
       } catch (err) {
         who = { kind: UNKNOWN, uid: null, pid: null, reason: `check: ${err?.name ?? 'Error'}` };
       }
-      if (who.pid === this.jobPid && !await jobListens(this.jobPid, port, this.ask.run)) {
+      if (who.pid === this.jobPid && !await jobListens(this.jobPid, port, this.ask.run, this.ask.platform)) {
         socket.destroy();
         // The job's pid, but lsof did not show it bound to exactly 127.0.0.1:<port>: a wildcard is never vouched for.
         callback(new ListenerRefused(SERVER_NOT_OWN, `the LaunchDaemon's pid ${this.jobPid} is not shown listening on exactly 127.0.0.1:${port} by lsof (a wildcard is never vouched for); nothing was sent`));
         return;
       }
       const proved = who.pid === this.jobPid || (who.kind === UNKNOWN && String(who.reason ?? '').startsWith(TABLE_RESTRICTED)
-        && await jobListens(this.jobPid, port, this.ask.run));
+        && await jobListens(this.jobPid, port, this.ask.run, this.ask.platform));
       if (!proved) {
         socket.destroy();
         callback(new ListenerRefused(SERVER_NOT_OWN, `the server on port ${port} is not the LaunchDaemon's pid ${this.jobPid} (${who.reason ?? who.kind}): another process holds the port, or the job's program starts the server as a child (start it with exec); nothing was sent`, who));
@@ -620,11 +694,11 @@ function loopbackPort(origin) {
 }
 
 // As wellKnownOf, for a LaunchDaemon: a loopback origin is read only when launchd's job `jobPid`, running as `jobUid`,
-// accepted the connection.
-export async function jobWellKnownOf(origin, { jobPid, jobUid } = {}) {
+// accepted the connection. `ask` reaches the owner, lsof and ps readers (a test's fakes; `platform` for lsof's).
+export async function jobWellKnownOf(origin, { jobPid, jobUid, ask = {} } = {}) {
   const port = loopbackPort(origin);
   if (port === null) throw new ServiceError(`A LaunchDaemon's answer is read only at http://127.0.0.1:<port>, where its job's pid and uid prove it; ${origin} is not.`);
-  return loopbackWellKnown(port, new JobAgent({ keepAlive: false, jobPid, jobUid }));
+  return loopbackWellKnown(port, new JobAgent({ keepAlive: false, jobPid, jobUid, ask }));
 }
 
 /**
@@ -643,9 +717,15 @@ export async function jobWellKnownOf(origin, { jobPid, jobUid } = {}) {
 export async function launchdInstall(label, plistPath, plistText, { origin, serviceId, instance = 'default', timeout = 40, forceEnable = false,
   run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), fetchWellKnown = wellKnownOf,
   fetchJobWellKnown = jobWellKnownOf, sleep = pause } = {}) {
+  const pair = pairProblem(plistPath, domain, platform);
+  if (pair) throw new ServiceError(pair);
   const dom = launchdDomain(plistPath, { domain, platform, uid });
   launchdLabel(label);
   if (!origin || !serviceId) throw new ServiceError('launchdInstall needs the origin and the service id it waits to see answer.');
+  if (/^bplist/.test(Buffer.isBuffer(plistText) ? plistText.toString('latin1', 0, 6) : String(plistText ?? '').slice(0, 6))) {
+    // named as what it is, never as a missing UserName (FAA-286 item 7): the text launchdPlist writes is XML
+    throw new ServiceError('The plist is a binary plist: pass the XML text launchdPlist writes (plutil -convert xml1 converts one).');
+  }
   needRoot(dom, label, plistPath, true, euid);
   if (dom === 'system' && loopbackPort(origin) === null) {
     throw new ServiceError(`A LaunchDaemon's origin is http://127.0.0.1:<port>: only there is its answer proved by the job's pid and uid (FAA-278); ${origin} is not.`);
@@ -664,7 +744,7 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
     }
   }
   if (dom === 'system' && named && !USER_NAME.test(named)) {
-    throw new ServiceError(`UserName ${named} is not a macOS short name (${USER_NAME.source}): launchd takes the account's short name.`);
+    throw new ServiceError(`UserName ${named} is not a macOS short name (${USER_NAME_RULE}): launchd takes the account's short name.`);
   }
   const jobUid = named ? accountUid(named, run) : null;
   if (dom === 'system' && named && jobUid === null) {
@@ -676,7 +756,12 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   if (dom === 'system' && !named) {
     throw new ServiceError("A LaunchDaemon needs UserName: without it the job runs as root, keeps its data in root's home, and every client refuses root's listener (DEC-0154 HA-2). Write the plist with launchdPlist(..., { userName: <the account whose Fabric and agents call it> }).");
   }
+  if (dom === 'system') {
+    const leftover = leftoverAgent(label, named, run);
+    if (leftover) throw new ServiceError(`${leftover} is a LaunchAgent of label ${label}: it would start a second copy at ${named}'s login beside this LaunchDaemon. Remove it first (launchdUninstall as ${named}; lifecycle reference, The system domain).`);
+  }
   const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
+  const existed = fs.existsSync(plistPath);
   atomicWrite(plistPath, plistText, 0o644);
   const lint = run(['plutil', '-lint', String(plistPath)]);
   if (lint?.status !== 0) throw new ServiceError(`plist failed plutil -lint: ${String(lint?.stdout || lint?.stderr || '').trim().slice(0, 200)}`);
@@ -696,6 +781,11 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
       if (dom !== 'system' && /:\s*125:|Domain does not support|Could not find domain/.test(last)) {
         throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}. This user has no GUI login session (an SSH session, or a headless Mac after a FileVault restart), so ${dom} does not run jobs: remove the LaunchAgent this attempt wrote (launchdUninstall), then install it as a LaunchDaemon in the system domain (a plist in ${SYSTEM_DAEMONS} with UserName, as root; FAA-278).`);
       }
+      if (dom === 'system') {
+        // a plist left in /Library/LaunchDaemons loads at the next boot (FAA-286 item 15): one this call wrote goes
+        if (!existed) { try { fs.unlinkSync(plistPath); } catch { /* named below */ } }
+        throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}; ${fs.existsSync(plistPath) ? `${plistPath} stays and loads at the next boot: remove it as root` : 'the plist this call wrote was removed'}`);
+      }
       throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
     }
     await sleep(1000);
@@ -751,6 +841,10 @@ export async function launchdUninstall(label, plistPath, { timeout = 30, purge =
   needRoot(dom, label, plistPath, false, euid);
   if (purge && dom === 'system') throw new ServiceError("A LaunchDaemon's data belongs to its UserName, not to root: uninstall without purge, then remove the data as that user.");
   if (dom === 'system') refuseHeldLabel(label, plistPath, run); // a bootout would stop another plist's job (FAA-278)
+  const holds = fs.existsSync(plistPath) ? topKey(plistXml(plistPath, run), 'Label') : null;
+  if (holds !== null && holds !== label) { // FAA-286 item 9: booting out one job and unlinking another's plist
+    throw new ServiceError(`${plistPath} holds launchd label ${holds}, not ${label}: nothing was removed. Name the plist of ${label}, or uninstall ${holds} with its own label.`);
+  }
   const dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
   const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
   const target = `${dom}/${label}`;

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_board_session.py

@@ -168,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] = {}
@@ -982,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

@@ -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]

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

@@ -13,7 +13,8 @@ not re-export this module, so a service that does not run per context keeps the
 An organization's instance whose context the record does not pin (``organizations``, DEC-0127) still starts: the helper
 checks the placement and its share grant, not the pin (decision D5 of 0.52.0). Its tokens are refused instead:
 ``fabric_estate.hub_key_certified`` reads a context's hub keys only while the record pins that organization (DL-14a,
-DEC-0128), so the service passes ``estate_context=info["context"]`` to its delegation gate. The contract lets Fabric
+DEC-0128), so the service passes ``context_gate_options(info, record)`` (its context and its pin's issuer, FAA-150) to its
+delegation gate. The contract lets Fabric
 write ``organizations`` only once every reader is pinned at or after DEC-0127, so a refusal at start would stop every
 organization instance on today's records."""
 from __future__ import annotations
@@ -33,7 +34,8 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
 from fabric_base import ServiceError, _INSTANCE  # noqa: E402
 from fabric_descriptor import descriptor_path  # noqa: E402
 from fabric_estate import parse_context  # noqa: E402
-from fabric_lock import InstanceLock, hold_single_instance  # noqa: E402
+from fabric_lock import (InstanceLock, LOCK_BACKOFF_FIRST_SECONDS, LOCK_BACKOFF_MAX_SECONDS, hold_single_instance,  # noqa: E402
+                         lock_wait_budget_seconds, supervisor_marker)
 from fabric_paths import atomic_write, instance_dirs  # noqa: E402
 from fabric_share import instance_share_grant  # noqa: E402
 from fabric_time import clock_ms  # noqa: E402
@@ -125,9 +127,49 @@ def context_instance(service_id: str, context: Any, *, record: Optional[Dict[str
     return answer
 
 
-def _refuse(service_id: Any, context: Any, code: str) -> None:
-    print("%s will not run for %s (%s): %s." % (service_id, _shown(context), code, _REASONS[code]), file=sys.stderr, flush=True)
-    raise SystemExit(EXIT_CONTEXT_REFUSED)
+def context_gate_options(info: Any, record: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """What ``delegation_gate`` takes from this instance's context (FAA-150): ``estate_context``, and for an organization
+    whose context ``record`` pins, ``issuer``: the pin's context issuer (DL-14a, DEC-0128), so an organization's instance
+    refuses a token the personal hub key signed without wiring either by hand. ``info`` is ``context_instance``'s answer
+    (or ``hold_context_instance``'s); ``record`` the verified estate revision applied. Spread it after the service's own
+    estate issuer: ``delegation_gate(..., **{"issuer": estate_issuer, **context_gate_options(info, record)})``. Raises
+    ContextRefused (``context-invalid``) for an answer with no context."""
+    context = info.get("context") if isinstance(info, dict) else None
+    parsed = parse_context(context)
+    if parsed is None:
+        raise ContextRefused("context-invalid")
+    options: Dict[str, Any] = {"estate_context": context}
+    pins = record.get("organizations") if isinstance(record, dict) else None
+    if parsed["kind"] == "org" and isinstance(pins, list):
+        for pin in pins:
+            if isinstance(pin, dict) and pin.get("org") == context and isinstance(pin.get("iss"), str):
+                options["issuer"] = pin["iss"]
+                break
+    return options
+
+
+def _refuse(service_id: Any, context: Any, code: str, wait_seconds: Optional[float] = 0.0, *,
+            sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic,
+            env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> None:
+    """One sentence naming the code, then exit 78. Under a supervisor that restarts on exit (launchd's KeepAlive with
+    ThrottleInterval 10, systemd's Restart=always) an exit at once is a respawn every few seconds, forever (FAA-279);
+    so a supervised copy first waits the lock's back-off (0.5 s doubling to 30 s, 300 s in all), holding nothing, and
+    exits 78 when it runs out: a few restarts an hour. ``wait_seconds`` overrides the choice as the lock's does."""
+    if wait_seconds is None:
+        wait_seconds = lock_wait_budget_seconds(supervisor_marker(env, argv))
+    wait_seconds = max(0.0, wait_seconds)
+    tail = " Waiting %.0f s before exiting, so its supervisor does not restart it every few seconds." % wait_seconds \
+        if wait_seconds > 0 else ""
+    print("%s will not run for %s (%s): %s.%s" % (service_id, _shown(context), code, _REASONS[code], tail),
+          file=sys.stderr, flush=True)
+    deadline = clock() + wait_seconds
+    delay = LOCK_BACKOFF_FIRST_SECONDS
+    while True:
+        remaining = deadline - clock()
+        if remaining <= 0:
+            raise SystemExit(EXIT_CONTEXT_REFUSED)
+        sleep(min(delay, remaining))
+        delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
 
 
 def _marker_matches(path: Path, expected: Dict[str, str]) -> Optional[bool]:
@@ -152,7 +194,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
                           env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None,
                           services_directory: Optional[Path] = None) -> Tuple[Dict[str, Any], InstanceLock]:
     """Run as ``context``'s one instance, before any side effect (brief D17): ``context_instance`` (a refusal prints one
-    sentence naming the code and exits 78, nothing created); then ``hold_single_instance`` on the instance's data
+    sentence naming the code and exits 78, nothing created; a supervised copy backs off first, FAA-279); then ``hold_single_instance`` on the instance's data
     folder (its markers, its supervised wait, its exit 75); then the marker ``<data>/fabric-context.json``: absent, it
     is written (0600, atomic); equal, it is kept; another context or instance, or unreadable, releases the lock and
     exits 78 (``context-mismatch``). Returns the instance and the held lock."""
@@ -160,7 +202,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         info = context_instance(service_id, context, record=record, machine_id=machine_id, agent_ref=agent_ref, at=at,
                                 personal_instance=personal_instance, services_directory=services_directory)
     except ContextRefused as refused:
-        _refuse(service_id, context, refused.code)
+        _refuse(service_id, context, refused.code, wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     lock = hold_single_instance(info["dirs"]["data"], wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     expected = {"service": service_id, "instance": info["instance"], "context": context}
     marker = Path(info["dirs"]["data"]) / CONTEXT_MARKER
@@ -173,5 +215,5 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         raise
     if matches is False:
         lock.release()
-        _refuse(service_id, context, "context-mismatch")
+        _refuse(service_id, context, "context-mismatch", wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     return info, lock