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

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

@@ -9,8 +9,10 @@ import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabri
 import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
-import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
+import { CheckedAgent, LSOF, ListenerRefused, PS, SERVER_NOT_OWN, TABLE_RESTRICTED, UNKNOWN, parseLsofListeners, parsePsUid,
+  runProgram, serverEnd } from './fabric-peer-owner.mjs';
 import http from 'node:http';
+import net from 'node:net';
 
 export const DEFAULT_EXIT_TIMEOUT = 15;
 
@@ -263,13 +265,15 @@ function plistValue(value, depth) {
  * FABRIC_SERVICE_SUPERVISOR=launchd tells the lock to back off instead of exiting into a respawn loop (DEC-0057).
  * No secret is written: an environment name ending TOKEN/SECRET/PASSWORD/KEY (a `*_FILE` path is fine), a value or an
  * argument shaped like a credential is refused. Returns the XML text, the same bytes Python's plistlib writes.
+ * `userName` writes UserName, the account a LaunchDaemon (launchd's system domain, FAA-278) runs as: a macOS short name.
  */
-export function launchdPlist(label, programArguments, { workingDirectory, stdoutPath, environment = {}, exitTimeout = DEFAULT_EXIT_TIMEOUT } = {}) {
+export function launchdPlist(label, programArguments, { workingDirectory, stdoutPath, environment = {}, exitTimeout = DEFAULT_EXIT_TIMEOUT, userName = null } = {}) {
   launchdLabel(label);
   const argv = programArguments.map(String);
   if (!argv.length) throw new ServiceError('A launchd job starts a program; ProgramArguments is empty.');
   if (!(exitTimeout > DRAIN_SECONDS)) throw new ServiceError(`ExitTimeOut must outlast the ${DRAIN_SECONDS} s drain.`);
   if (workingDirectory === undefined || stdoutPath === undefined) throw new ServiceError('A launchd job names its working directory and its log file.');
+  if (userName !== null && userName !== undefined && !USER_NAME.test(String(userName))) throw new ServiceError(`UserName must be a macOS short name matching ${USER_NAME.source}`);
   const env = { ...environment };
   for (const [name, value] of Object.entries(env)) {
     if (/(TOKEN|SECRET|PASSWORD|KEY)$/.test(name) && !name.endsWith('_FILE')) throw new ServiceError(`Environment variable ${name} looks like a secret; pass a *_FILE path instead.`);
@@ -295,25 +299,168 @@ export function launchdPlist(label, programArguments, { workingDirectory, stdout
     StandardErrorPath: String(stdoutPath),
     EnvironmentVariables: env,
   };
+  if (userName !== null && userName !== undefined) job.UserName = String(userName); // a LaunchDaemon's account (FAA-278)
   return '<?xml version="1.0" encoding="UTF-8"?>\n'
     + '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
     + `<plist version="1.0">\n${plistValue(job, 0)}</plist>\n`;
 }
 
-function launchdDomain(platform, uid) {
+function guiDomain(platform, uid) {
   // DEC-0032: launchd is macOS's supervisor; Linux has systemd and Windows Task Scheduler.
   if (platform !== 'darwin') throw new ServiceError('launchd is the supervisor on macOS only; use systemdInstall on Linux and taskInstall on Windows.');
   return `gui/${uid ?? process.getuid()}`;
 }
 
-/** True when launchd has the job loaded (`launchctl print gui/<uid>/<label>` answers). */
-export function launchdLoaded(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  return run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`])?.status === 0;
+/** 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 launchd domain a job lives in: `system` for a LaunchDaemon (`domain: 'system'`, or a plist in
+ * /Library/LaunchDaemons), else this user's `gui/<uid>` (FAA-278). A LaunchDaemon starts at boot, before any login, so it
+ * is the form for a headless Mac that a FileVault restart leaves with no GUI session.
+ */
+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');
+  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
+    which = paths.dirname(paths.resolve(String(plistPath))).toLowerCase() === SYSTEM_DAEMONS.toLowerCase() ? 'system' : 'gui'; // APFS ignores case
+  }
+  if (which === 'system') {
+    if (platform !== 'darwin') throw new ServiceError('launchd is the supervisor on macOS only; use systemdInstall on Linux and taskInstall on Windows.');
+    return 'system';
+  }
+  return guiDomain(platform, uid);
+}
+
+// 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;
+  if (install) {
+    throw new ServiceError(`A LaunchDaemon (launchd's system domain) is installed by root, and this process is not root: run launchdInstall as root (the release, descriptor and token stay its UserName's, lifecycle reference, The system domain), or as root write ${plistPath} and run \`launchctl bootstrap system ${plistPath}\`. Status and pid read without root.`);
+  }
+  throw new ServiceError(`A LaunchDaemon (launchd's system domain) is removed by root, and this process is not root: run launchdUninstall as root, or as root run \`launchctl bootout system/${label}\`, remove ${plistPath} and run \`launchctl enable system/${label}\` (so a later install is not kept off). Status and pid read without root.`);
+}
+
+// The top-level string values of an XML plist's dict, read as CoreFoundation does: comments, the prolog and DOCTYPE
+// skipped, entities, character references and CDATA decoded in keys and values, a repeated key's last value kept, a key
+// nested deeper (an EnvironmentVariables entry named UserName) never read. null when the text cannot be read so.
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+function decodeXml(text) {
+  return text.replace(/&(?:(amp|lt|gt|quot|apos)|#([0-9]+)|#x([0-9a-fA-F]+));/g, (_, e, d, h) => {
+    if (e) return XML_ENTITIES[e];
+    const code = d ? Number(d) : parseInt(h, 16);
+    // XML 1.0's Char, as expat (Python's plistlib) reads it: a reference outside it makes the file unreadable.
+    const xmlChar = code === 0x9 || code === 0xa || code === 0xd || (code >= 0x20 && code <= 0xd7ff)
+      || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
+    if (!xmlChar) throw new RangeError('character reference outside XML 1.0');
+    return String.fromCodePoint(code);
+  });
+}
+function topStrings(text) {
+  const token = /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[^>]*>|<!\[CDATA\[([\s\S]*?)\]\]>|<(\/?)([A-Za-z][\w.:-]*)\s*[^>]*?(\/?)>|([^<]+)/g;
+  const values = Object.create(null);
+  let depth = 0;
+  let key = null;
+  let capture = null;
+  let buffer = '';
+  try {
+    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);
+      } else if (name === 'dict' || name === 'array') {
+        if (selfClosing) {
+          if (depth === 1 && key !== null) { delete values[key]; key = null; }
+        } else if (closing) {
+          depth -= 1;
+        } else {
+          if (depth === 1 && key !== null) { delete values[key]; key = null; } // a container is this key's value
+          depth += 1;
+        }
+      } else if (name && depth === 1) {
+        if (selfClosing) {
+          if (key !== null) {
+            if (name === 'string') values[key] = '';
+            else delete values[key]; // <true/>, <false/>: the last value is not a string
+          }
+          key = name === 'key' ? '' : null;
+        } else if (!closing && (name === 'key' || name === 'string')) {
+          capture = name;
+          buffer = '';
+        } else if (closing && name === capture) {
+          if (capture === 'key') key = buffer;
+          else if (key !== null) { values[key] = buffer; key = null; }
+          capture = null;
+        } else if (closing) {
+          if (key !== null) delete values[key]; // another value (integer, date, data, real) replaces the earlier string
+          key = null;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return values;
+}
+
+function topKey(text, key) {
+  const values = topStrings(text);
+  return values && Object.hasOwn(values, key) ? values[key] : null;
 }
 
-// The running pid of this account's launchd job `label`, or null (not running, or not readable).
-export function launchdPid(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  const result = run(['launchctl', 'print', `${launchdDomain(platform, uid)}/${launchdLabel(label)}`]);
+const topUserName = (text) => topKey(text, 'UserName');
+
+// A plist file's text as XML, a binary plist converted with plutil; null when it cannot be read.
+function plistXml(file, run) {
+  let text;
+  try { text = fs.readFileSync(file, 'latin1'); } catch { return null; }
+  if (!text.startsWith('bplist')) return Buffer.from(text, 'latin1').toString('utf8');
+  const converted = run(['plutil', '-convert', 'xml1', '-o', '-', String(file)]);
+  return converted?.status === 0 ? String(converted.stdout ?? '') : null;
+}
+
+// Other plists that hold launchd label `label` in the system domain (FAA-278): the plist launchd loaded the job from,
+// when it is not `plistPath`, and any plist of that label beside `plistPath`. Reading needs no root.
+function labelHolders(label, plistPath, run) {
+  const real = (p) => { try { return fs.realpathSync.native(p); } catch { return path.resolve(p); } }; // the case on disk
+  const own = real(String(plistPath));
+  const found = [];
+  const loaded = run(['launchctl', 'print', `system/${label}`]);
+  if (loaded?.status === 0) {
+    const hit = /^\s*path\s*=\s*(.+?)\s*$/m.exec(String(loaded.stdout ?? ''));
+    if (hit) found.push(hit[1]);
+  }
+  const folder = path.dirname(String(plistPath));
+  let names = [];
+  try { names = fs.readdirSync(folder).filter((name) => name.endsWith('.plist')).sort(); } catch { names = []; }
+  for (const name of names) {
+    const file = path.join(folder, name);
+    if (topKey(plistXml(file, run), 'Label') === label) found.push(file);
+  }
+  return [...new Set(found)].filter((file) => real(file) !== own);
+}
+
+function refuseHeldLabel(label, plistPath, run) {
+  const holders = labelHolders(label, plistPath, run);
+  if (holders.length) {
+    const owner = topUserName(plistXml(holders[0], run));
+    throw new ServiceError(`Label ${label} is already held by ${holders[0]}${owner ? ` (${owner}'s)` : ''}: the system domain is shared by every account of this Mac, so a label is the machine's and one plist holds it. Choose a label of your own (for example with the account in it), or remove that LaunchDaemon as root first.`);
+  }
+}
+
+const ownEuid = () => (typeof process.geteuid === 'function' ? process.geteuid() : null);
+
+/** True when launchd has the job loaded (`launchctl print gui/<uid>/<label>`, or `system/<label>` with domain 'system'). */
+export function launchdLoaded(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  return run(['launchctl', 'print', `${launchdDomain(null, { domain, platform, uid })}/${launchdLabel(label)}`])?.status === 0;
+}
+
+// The running pid of this account's launchd job `label` (with domain 'system', of the LaunchDaemon), or null (not
+// running, or not readable). Reading needs no root.
+export function launchdPid(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  const result = run(['launchctl', 'print', `${launchdDomain(null, { domain, platform, uid })}/${launchdLabel(label)}`]);
   if (result?.status !== 0) return null;
   const hit = /^\s*pid\s*=\s*([0-9]+)\s*$/m.exec(String(result.stdout ?? ''));
   return hit ? Number(hit[1]) : null;
@@ -325,8 +472,8 @@ const OVERRIDE_ROW = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/;
  * The operator's launchd override for `label`: 'disabled', 'enabled', null when none is recorded (a first install), or
  * 'unknown' when the table cannot be read. macOS 14+ prints `=> disabled|enabled`, older releases `=> true|false`.
  */
-export function launchdOverride(label, { run = defaultRun, platform = process.platform, uid } = {}) {
-  const result = run(['launchctl', 'print-disabled', launchdDomain(platform, uid)]);
+export function launchdOverride(label, { run = defaultRun, platform = process.platform, uid, domain = null } = {}) {
+  const result = run(['launchctl', 'print-disabled', launchdDomain(null, { domain, platform, uid })]);
   if (result?.status !== 0) return 'unknown';
   for (const line of String(result.stdout ?? '').split('\n')) {
     const match = OVERRIDE_ROW.exec(line);
@@ -343,8 +490,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) });
@@ -355,9 +514,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.
-  const agent = 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, host = '127.0.0.1') {
   return new Promise((resolve) => {
-    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), 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));
@@ -374,6 +538,95 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
   }).finally(() => agent.destroy());
 }
 
+// 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;
+  try {
+    const out = await run(LSOF, ['-nP', '-a', '-p', String(pid), '-i4TCP', '-sTCP:LISTEN', '-Fn']);
+    return parseLsofListeners(out).some(([host, p]) => host === '127.0.0.1' && p === port); // exact bind, as RT-3
+  } catch {
+    return false;
+  }
+}
+
+// The uid account `name` has on this machine (`id -u`), or null when it has none.
+function accountUid(name, run) {
+  if (!USER_NAME.test(String(name))) return null; // `id -u 501` answers a uid, but launchd looks UserName up by name
+  const result = run(['id', '-u', String(name)]);
+  const uid = result?.status === 0 ? String(result.stdout ?? '').trim() : '';
+  return /^[0-9]+$/.test(uid) ? Number(uid) : null;
+}
+
+// An http.Agent whose connections must be accepted by launchd's job `jobPid`, running as `jobUid`, its UserName's uid: a
+// LaunchDaemon runs as its UserName, so the installer, root, reads it as another account's, and the job's own pid and
+// uid are the proof (FAA-278; contract DEC-0161, proposed: RT-3 extended to launchd's system domain).
+class JobAgent extends http.Agent {
+  constructor({ jobPid, jobUid, ask = {}, ...options } = {}) {
+    if (!Number.isInteger(jobPid) || jobPid <= 1) throw new ServiceError("A LaunchDaemon's answer is read only on its job's pid, a positive number.");
+    if (!Number.isInteger(jobUid) || jobUid < 0) throw new ServiceError("A LaunchDaemon's answer is read only from its UserName's uid, a number.");
+    super(options);
+    this.jobPid = jobPid;
+    this.jobUid = jobUid;
+    this.ask = ask;
+  }
+
+  createConnection(options, callback) {
+    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);
+    socket.once('error', (err) => { clearTimeout(timer); callback(err); });
+    socket.once('connect', async () => {
+      clearTimeout(timer);
+      socket.pause();
+      let who;
+      try {
+        who = await serverEnd(socket, this.ask);
+      } 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)) {
+        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));
+      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));
+        return;
+      }
+      let runsAs = null;
+      try { runsAs = parsePsUid(await (this.ask.run ?? runProgram)(PS, ['-o', 'uid=', '-p', String(this.jobPid)])); } catch { runsAs = null; }
+      if (runsAs !== this.jobUid) {
+        socket.destroy();
+        // Not the restricted owner: the pid was proved, only its uid is wrong, and the error says so.
+        callback(new ListenerRefused(SERVER_NOT_OWN, `the LaunchDaemon's pid ${this.jobPid} runs as uid ${runsAs}, not its UserName's uid ${this.jobUid}; nothing was sent`));
+        return;
+      }
+      socket.removeAllListeners('error');
+      socket.resume();
+      callback(null, socket);
+    });
+  }
+}
+
+// The port of exactly http://127.0.0.1:<port> (1 to 65535, no leading zero), else null.
+function loopbackPort(origin) {
+  const m = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(String(origin));
+  return m && Number(m[1]) <= 65535 ? Number(m[1]) : null;
+}
+
+// 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 } = {}) {
+  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 }));
+}
+
 /**
  * Write and lint the plist, bootout and WAIT for the unload, bootstrap (retrying launchd's EIO 5 times), then poll the
  * well-known document until it answers with this identity; resolves to that document.
@@ -382,17 +635,52 @@ export async function wellKnownOf(origin, { vouchPid = null } = {}) {
  * operator disabled stays disabled and unloaded — the plist is still rewritten, so the new release is what starts once
  * they turn it back on — and the answer is {disabled: true, label, plist, loaded}. `forceEnable` is for an operator
  * who asked for the service to be switched on.
+ *
+ * A plist in /Library/LaunchDaemons (or `domain: 'system'`) is a LaunchDaemon in launchd's system domain, started at boot
+ * with no login (FAA-278): only root installs it, refused before anything is written otherwise, and the answer counts
+ * only when launchd's own job accepted the connection. A gui/<uid> bootstrap with no GUI session says so.
  */
 export async function launchdInstall(label, plistPath, plistText, { origin, serviceId, instance = 'default', timeout = 40, forceEnable = false,
-  run = defaultRun, platform = process.platform, uid, fetchWellKnown = wellKnownOf, sleep = pause } = {}) {
-  const domain = launchdDomain(platform, uid);
+  run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), fetchWellKnown = wellKnownOf,
+  fetchJobWellKnown = jobWellKnownOf, sleep = pause } = {}) {
+  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.');
-  const opts = { run, platform, uid };
+  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.`);
+  }
+  const named = dom === 'system' ? topUserName(plistText) : null;
+  if (dom === 'system' && named) {
+    refuseHeldLabel(label, plistPath, run);
+    const installedText = plistXml(plistPath, run);
+    const installedLabel = topKey(installedText, 'Label');
+    if (installedLabel !== null && installedLabel !== label) {
+      throw new ServiceError(`${plistPath} holds launchd label ${installedLabel}, not ${label}: writing over it would leave that job loaded from a plist that no longer describes it. Uninstall it as root first, or write this one at /Library/LaunchDaemons/${label}.plist.`);
+    }
+    const installed = topUserName(installedText);
+    if (installed && installed !== named) {
+      throw new ServiceError(`${plistPath} is ${installed}'s LaunchDaemon: the system domain is shared by every account of this Mac, so a label is the machine's. Choose a label of your own (for example with the account in it), or uninstall that one as root first.`);
+    }
+  }
+  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.`);
+  }
+  const jobUid = named ? accountUid(named, run) : null;
+  if (dom === 'system' && named && jobUid === null) {
+    throw new ServiceError(`UserName ${named} is no account of this Mac: launchd would not start the job. Name the account whose Fabric and agents call the service.`);
+  }
+  if (dom === 'system' && jobUid === 0) {
+    throw new ServiceError(`UserName ${named} is root: the job would run as root, keep its data in root's home, and every client refuses root's listener (DEC-0154 HA-2). Name the account whose Fabric and agents call the service.`);
+  }
+  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> }).");
+  }
+  const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
   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)}`);
-  const target = `${domain}/${label}`;
+  const target = `${dom}/${label}`;
   const override = launchdOverride(label, opts);
   if (forceEnable || override === null) run(['launchctl', 'enable', target]);
   else if (override === 'disabled') return { disabled: true, label, plist: String(plistPath), loaded: launchdLoaded(label, opts) };
@@ -401,13 +689,33 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
   while (launchdLoaded(label, opts) && Date.now() < unloaded) await sleep(250);
   let last = '';
   for (let attempt = 0; ; attempt += 1) {
-    const result = run(['launchctl', 'bootstrap', domain, String(plistPath)]);
+    const result = run(['launchctl', 'bootstrap', dom, String(plistPath)]);
     if (result?.status === 0) break;
     last = String(result?.stderr || result?.stdout || '').trim();
-    if (attempt === 4) throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
+    if (attempt === 4) {
+      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).`);
+      }
+      throw new ServiceError(`launchctl bootstrap failed: ${last.slice(0, 200)}`);
+    }
     await sleep(1000);
   }
   const deadline = Date.now() + timeout * 1000;
+  if (dom === 'system') {
+    let refused = null;
+    while (Date.now() < deadline) {
+      const jobPid = launchdPid(label, opts);
+      const doc = jobPid ? await fetchJobWellKnown(origin, { jobPid, jobUid }) : null;
+      const now = doc instanceof ForeignUserAnswer ? doc.reason : null;
+      refused = now ?? refused; // the last refusal stays the reason, but only this round's answer decides
+      if (!now && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
+      await sleep(500);
+    }
+    const loaded = `; the job stays loaded and its plist starts it again at boot: as root, \`launchctl bootout system/${label}\` and removing ${plistPath} (or launchdUninstall) take it away`;
+    if (refused?.startsWith(TABLE_RESTRICTED)) throw new ServiceError(`${origin} could not be proved this LaunchDaemon's: ${refused}; the job's pid did not show the listener: start the server with exec (no wrapper child), or read the job's log${loaded}.`);
+    if (refused) throw new ServiceError(`${origin} is not this LaunchDaemon's: ${refused}${loaded}.`);
+    throw new ServiceError(`${origin} did not answer as ${serviceId}.${instance} within ${timeout} s; read its log${loaded}.`);
+  }
   let foreign = null;
   let vouchPid = null;
   while (Date.now() < deadline) {
@@ -432,15 +740,20 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
  * override to enabled — launchctl has no verb that deletes an override, and a leftover `disabled` would keep a later
  * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go, and `instance` which
  * instance's, so one context's purge never reaches another's, FAA-125). A job still
- * loaded at `timeout` seconds throws, leaving the plist and the data in place.
+ * loaded at `timeout` seconds throws, leaving the plist and the data in place. A LaunchDaemon (a plist in
+ * /Library/LaunchDaemons, or `domain: 'system'`) is removed only by root, and its data belongs to its UserName, so
+ * `purge` is refused for it (FAA-278).
  */
-export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
-  const domain = launchdDomain(platform, uid);
+export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, domain = null, euid = ownEuid(), sleep = pause } = {}) {
+  const dom = launchdDomain(plistPath, { domain, platform, uid });
   launchdLabel(label);
   if (purge && !serviceId) throw new ServiceError('purge needs the service id whose data, logs and cache to remove.');
+  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 dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
-  const opts = { run, platform, uid };
-  const target = `${domain}/${label}`;
+  const opts = { run, platform, uid, domain: dom === 'system' ? 'system' : null };
+  const target = `${dom}/${label}`;
   run(['launchctl', 'bootout', target]);
   const deadline = Date.now() + timeout * 1000;
   while (launchdLoaded(label, opts)) {