@passioncode-ai/fabric-agent-adapter 0.22.0 → 0.24.0

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

@@ -52,8 +52,13 @@ const TRACE_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 const SPAN_ID = /^(?!0{16}$)[0-9a-f]{16}$/;
 const O_EXLOCK = 0x20; // BSD/macOS: open(2) takes flock(LOCK_EX); absent from fs.constants
 // DEC-0032: a local path starts with ~/ (or ~\ on Windows), / (never //) or a drive letter; a network share never does.
-const LOCAL_PATH = /^(~[\\/]|\/(?!\/)|[A-Za-z]:[\\/])/;
-export const MANAGERS = Object.freeze(['launchd', 'systemd', 'task-scheduler', 'none']);
+// DEC-0057: `//server/…` and `/\\server…` are shares on Windows too, so a leading slash is followed by neither.
+const LOCAL_PATH = /^(~[\\/]|\/(?![\\/])|[A-Za-z]:[\\/])/;
+// DEC-0061: `node` (Project Observatory's node supervises its children, no supervisor file); DEC-0069: `person` (an app a
+// person installs and starts; its descriptor says it is installed, never that it runs).
+export const MANAGERS = Object.freeze(['launchd', 'systemd', 'task-scheduler', 'node', 'person', 'none']);
+/** Managers that write no launchd label or plist (DEC-0057, DEC-0061, DEC-0069). */
+const NOT_LAUNCHD = Object.freeze(['systemd', 'task-scheduler', 'node', 'person']);
 const AUTH_HEADER = /^[A-Za-z][A-Za-z0-9-]{0,63}$/;
 const UNIT = /^[A-Za-z0-9][A-Za-z0-9:_.@-]{0,250}\.service$/;
 const TASK = /^\\[A-Za-z0-9 ._\\-]{1,254}$/;
@@ -63,7 +68,8 @@ export const DEFAULT_EXIT_TIMEOUT = 15;
 export class ServiceError extends Error {}
 export class AlreadyRunning extends ServiceError {
   constructor(holderPid, lockPath) {
-    super(`Another copy is already running (${holderPid ? `process ${holderPid}` : 'another process'} holds ${lockPath}).`);
+    // FAC-SEM-078: a copy that cannot learn the holder's pid says the holder is unknown.
+    super(`Another copy is already running (${holderPid ? `process ${holderPid}` : 'an unknown process'} holds ${lockPath}).`);
     this.holderPid = holderPid;
     this.lockPath = lockPath;
   }
@@ -209,25 +215,92 @@ function readPid(file) {
   }
 }
 
+/** The managers a supervisor marker may name (DEC-0057): the three systems' supervisors and Project Observatory's node. */
+export const SUPERVISORS = Object.freeze(['launchd', 'systemd', 'task-scheduler', 'node']);
+/** The argument form of the marker, for a supervisor whose start carries no environment (a Scheduled Task's action). */
+export const SUPERVISOR_ARG = '--fabric-supervisor';
+
+/**
+ * The marker values an argument vector carries after the executable and before `--`. A bare `--fabric-supervisor`
+ * followed by nothing, by `--` or by another `--…` flag is a marker with an empty value and consumes nothing.
+ */
+function markerArguments(argv) {
+  const values = [];
+  if (!Array.isArray(argv)) return values;
+  for (let index = 1; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (item === '--') break;
+    if (item === SUPERVISOR_ARG) {
+      const next = argv[index + 1];
+      if (typeof next === 'string' && !next.startsWith('--')) {
+        values.push(next);
+        index += 1;
+      } else {
+        values.push('');
+      }
+    } else if (typeof item === 'string' && item.startsWith(`${SUPERVISOR_ARG}=`)) {
+      values.push(item.slice(SUPERVISOR_ARG.length + 1));
+    }
+  }
+  return values;
+}
+
+/**
+ * How this copy was started (DEC-0057), from `FABRIC_SERVICE_SUPERVISOR=<manager>` and `--fabric-supervisor <manager>` /
+ * `--fabric-supervisor=<manager>` (`env` and `argv` default to this process's; `argv[0]` is the executable or script):
+ * `{kind: 'supervised', manager, forms}` when every marker present names the same manager of SUPERVISORS;
+ * `{kind: 'conflict', values, forms}` when they disagree (an empty or bare argument beside a variable disagrees with it):
+ * the copy exits 75 at once, before it takes the lock; `{kind: 'manual', forms, unreadable?}` with no marker (only an
+ * empty variable counts as none) or one that names no manager. Never inferred from the parent process. The contract's
+ * `supervisorMarker`.
+ */
+export function supervisorMarker({ env = process.env, argv = process.argv.slice(1) } = {}) {
+  const variable = env?.[SUPERVISOR_ENV];
+  const fromEnv = typeof variable === 'string' && variable !== '' ? [variable] : [];
+  const fromArgs = markerArguments(argv);
+  const forms = [...(fromEnv.length ? ['environment'] : []), ...(fromArgs.length ? ['argument'] : [])];
+  const values = [...new Set([...fromEnv, ...fromArgs])];
+  if (values.length > 1) return { kind: 'conflict', values, forms };
+  if (values.length === 0) return { kind: 'manual', forms };
+  return SUPERVISORS.includes(values[0]) ? { kind: 'supervised', manager: values[0], forms } : { kind: 'manual', unreadable: values[0], forms };
+}
+
+/** How long a copy started so may wait for the lock, in seconds: 300 when supervised, else not at all. */
+export const lockWaitBudgetSeconds = (marker) => (marker?.kind === 'supervised' ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
+
+/** The one sentence a copy whose markers disagree exits with, naming the markers present. */
+export function markerConflictMessage(marker) {
+  const shown = marker.values.map((v) => JSON.stringify(v)).join(', ');
+  return marker.forms.length === 2
+    ? `${SUPERVISOR_ENV} and ${SUPERVISOR_ARG} disagree (${shown}); not starting unsupervised.`
+    : `${SUPERVISOR_ARG} is given with different values (${shown}); not starting unsupervised.`;
+}
+
+/** True when a supervisor that restarts on exit started this process and said so with the marker. */
+export const supervised = (start) => supervisorMarker(start).kind === 'supervised';
 /** True when launchd started this process from a plist that says so (FABRIC_SERVICE_SUPERVISOR=launchd). */
-export const supervisedByLaunchd = () => process.env[SUPERVISOR_ENV] === 'launchd';
-export const SUPERVISORS = Object.freeze(['launchd', 'systemd', 'task-scheduler']);
-/** True when a supervisor that restarts on exit started this process and said so (launchd, systemd). */
-export const supervised = () => SUPERVISORS.includes(process.env[SUPERVISOR_ENV]);
+export const supervisedByLaunchd = (start) => supervisorMarker(start).manager === 'launchd';
 
 const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));
 
 /**
- * Take the lock or exit 75 with one sentence naming the holder. Started by hand, a held lock exits
- * 75 at once. Under launchd (KeepAlive) an immediate exit is a respawn every ThrottleInterval,
+ * Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078). Markers that
+ * disagree exit 75 before the lock. Started by hand, a held lock exits 75 at once. Under a
+ * supervisor that restarts on exit (launchd's KeepAlive) an immediate exit is a respawn every ThrottleInterval,
  * forever; so a supervised copy first backs off in-process (0.5 s doubling to 30 s,
  * LOCK_WAIT_SUPERVISED_SECONDS in all), takes over if the holder leaves, and exits 75 only when
  * the wait runs out. `waitSeconds` overrides the choice (0 = never wait).
  */
 export async function holdSingleInstance(dataDir, {
-  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code),
+  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv,
 } = {}) {
-  const wait = waitSeconds ?? (supervised() ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
+  // DEC-0057: markers that disagree exit 75 at once, before the lock, naming them.
+  const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
+  if (marker.kind === 'conflict') {
+    process.stderr.write(`${markerConflictMessage(marker)}\n`);
+    return exit(EXIT_ALREADY_RUNNING);
+  }
+  const wait = waitSeconds ?? lockWaitBudgetSeconds(marker);
   const deadline = clock() + Math.max(0, wait);
   let delay = LOCK_BACKOFF_FIRST_SECONDS;
   let announced = false;
@@ -263,9 +336,8 @@ export function ensureToken(file) {
 
 /**
  * Refuse a symlink, a file owned by someone else, or one others can read. On Windows the rule is
- * service.md "Windows token files" (DEC-0032, DEC-0033): a regular file whose real path is in the
- * profile, owned by the current user, SYSTEM or Administrators, every granting ACE naming one of
- * those three; a refusal names the SID, never the contents.
+ * service.md "Windows token files" (DEC-0032, DEC-0033, DEC-0057): windowsTokenAclProblem over the
+ * file's flags, owner and ACEs; a refusal names the SID, never the contents.
  */
 export function readToken(file) {
   const info = fs.lstatSync(file);
@@ -286,30 +358,68 @@ export function readToken(file) {
 // Node has no ACL API. Windows PowerShell (5.1, present on every Windows) reads the list through .NET
 // and icacls writes it; both get the path through the environment, never argv, and print no contents.
 
+export const SYSTEM_SID = 'S-1-5-18';
+export const ADMINISTRATORS_SID = 'S-1-5-32-544';
+/** A string SID: revision 1, an identifier authority and up to 15 sub-authorities of 32 bits each. */
+const SID_TEXT = /^S-1-\d{1,15}(-\d{1,10}){0,15}$/i;
+/** A readable SID in upper case (SIDs compare case-insensitively on their S), or undefined. */
+const sidOf = (value) => (typeof value === 'string' && SID_TEXT.test(value) && value.split('-').slice(3).every((part) => Number(part) <= 0xffffffff) ? value.toUpperCase() : undefined);
+
 /**
- * service.md "Windows token files", rules 2 and 3, on SIDs already read: the owner is the current
- * user, SYSTEM or Administrators (DEC-0033), and every SID an allow ACE grants anything to is one of
- * those three. Deny ACEs are not passed in: they do not change the decision.
+ * service.md "Windows token files" (DEC-0032, DEC-0033, DEC-0057, FAC-SEM-079) on what a reader has read: `file` is
+ * `{isRegularFile, isReparsePoint, realPathInProfile, ownerSid, aces: [{type, sid, mask}]}`, the mask the ACE's unsigned
+ * 32-bit access mask. The first refusal `{problem, at, sid?, message}`, or null when the file may be read: a regular
+ * file, not a reparse point, inside the profile; owned by the user, SYSTEM or Administrators; every allow ACE with a
+ * non-zero mask naming one of those three; deny ACEs ignored; any other ACE type refused; anything unreadable refused.
+ * The contract's `windowsTokenAclProblem`; a refusal names the SID, never the contents.
  */
-export function tokenAclProblem(file, owner, granting, user) {
-  if (owner !== user && !WINDOWS_TRUSTED.includes(owner)) {
-    return `Token file ${file} is owned by ${owner || 'nobody'}, not by this user (${user}), SYSTEM or Administrators.`;
-  }
-  for (const sid of granting) {
-    if (sid !== user && !WINDOWS_TRUSTED.includes(sid)) return `Token file ${file} grants access to ${sid}; only this user, SYSTEM and Administrators may hold any.`;
+export function windowsTokenAclProblem(file, currentUserSid) {
+  const refuse = (problem, at, message, sid) => (sid === undefined ? { problem, at, message } : { problem, at, sid, message });
+  const user = sidOf(currentUserSid);
+  if (user === undefined) return refuse('unreadable', '/currentUserSid', "the current user's SID is unreadable");
+  if (typeof file !== 'object' || file === null || Array.isArray(file)) return refuse('unreadable', '/file', "the token file's metadata is unreadable");
+  for (const flag of ['isRegularFile', 'isReparsePoint', 'realPathInProfile']) {
+    if (typeof file[flag] !== 'boolean') return refuse('unreadable', `/file/${flag}`, `${flag} is unreadable`);
+  }
+  if (file.isReparsePoint) return refuse('reparse-point', '/file/isReparsePoint', 'the token file is a reparse point (a symlink or a junction)');
+  if (!file.isRegularFile) return refuse('not-regular-file', '/file/isRegularFile', 'the token file is not a regular file');
+  if (!file.realPathInProfile) return refuse('outside-profile', '/file/realPathInProfile', "the token file's real path lies outside the user's profile");
+  const trusted = new Set([user, SYSTEM_SID, ADMINISTRATORS_SID]);
+  const owner = sidOf(file.ownerSid);
+  if (owner === undefined) return refuse('unreadable', '/file/ownerSid', 'the owner SID is unreadable');
+  if (!trusted.has(owner)) return refuse('owner', '/file/ownerSid', `the token file is owned by ${owner}, not by the current user, SYSTEM or Administrators`, owner);
+  if (!Array.isArray(file.aces)) return refuse('unreadable', '/file/aces', 'the ACL is unreadable');
+  for (const [index, ace] of file.aces.entries()) {
+    const at = `/file/aces/${index}`;
+    if (typeof ace !== 'object' || ace === null || Array.isArray(ace)) return refuse('unreadable', at, `ACE ${index} is unreadable`);
+    if (typeof ace.type !== 'string') return refuse('unreadable', `${at}/type`, `ACE ${index} has an unreadable type`);
+    const trustee = sidOf(ace.sid);
+    if (trustee === undefined) return refuse('unreadable', `${at}/sid`, `ACE ${index} names an unreadable SID`);
+    if (typeof ace.mask !== 'number' || !Number.isInteger(ace.mask) || ace.mask < 0 || ace.mask > 0xffffffff) return refuse('unreadable', `${at}/mask`, `ACE ${index} has an unreadable access mask`);
+    if (ace.type === 'deny') continue;
+    if (ace.type !== 'allow') return refuse('ace-type', `${at}/type`, `ACE ${index} for ${trustee} is of a type the rule does not read`, trustee);
+    if (ace.mask === 0) continue;
+    if (!trusted.has(trustee)) return refuse('ace-sid', `${at}/sid`, `the token file grants access to ${trustee}; only the current user, SYSTEM and Administrators may hold any`, trustee);
   }
   return null;
 }
 
+/** windowsTokenAclProblem as one sentence naming the file and the refusal, or null. */
+export function tokenFileProblem(file, metadata, user) {
+  const problem = windowsTokenAclProblem(metadata, user);
+  return problem ? `Token file ${file} refused: ${problem.message}.` : null;
+}
+
+// The raw descriptor, through .NET: every ACE's type, its trustee's SID and its access mask as read (a signed int;
+// parseAclReport converts it to the unsigned mask). An inherit-only ACE applies to children only and is left out.
 const ACL_SCRIPT = [
   "$ErrorActionPreference = 'Stop'",
-  '$sid = [System.Security.Principal.SecurityIdentifier]',
   '$acl = [System.IO.File]::GetAccessControl($env:FABRIC_ACL_PATH)',
-  "$null_dacl = $acl.GetSecurityDescriptorSddlForm('Access') -match 'NO_ACCESS_CONTROL' -or $acl.GetSecurityDescriptorSddlForm('Access') -eq ''",
-  // InheritOnly (2) applies to children, not to the file itself.
-  "$granting = @($acl.GetAccessRules($true, $true, $sid) | Where-Object { $_.AccessControlType -eq 'Allow' -and -not ([int]$_.PropagationFlags -band 2) } | ForEach-Object { $_.IdentityReference.Value })",
+  "$raw = New-Object System.Security.AccessControl.RawSecurityDescriptor($acl.GetSecurityDescriptorSddlForm('Owner, Access'))",
+  '$dacl = $raw.DiscretionaryAcl',
+  "$aces = @(if ($dacl) { $dacl | Where-Object { -not ([int]$_.AceFlags -band 8) } | ForEach-Object { @{ type = [string]$_.AceType; sid = $(if ($_.SecurityIdentifier) { $_.SecurityIdentifier.Value } else { '' }); mask = [int64]$_.AccessMask } } })",
   '$user = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value',
-  '[Console]::Out.Write((ConvertTo-Json -Compress @{ owner = $acl.GetOwner($sid).Value; granting = $granting; nullDacl = [bool]$null_dacl; user = $user }))',
+  '[Console]::Out.Write((ConvertTo-Json -Compress -Depth 4 @{ owner = $raw.Owner.Value; aces = $aces; nullDacl = [bool](-not $dacl); user = $user }))',
 ].join('; ');
 
 function windowsHelper(command, args, extraEnv = {}) {
@@ -323,14 +433,24 @@ function windowsHelper(command, args, extraEnv = {}) {
   return result.stdout;
 }
 
-/** The ACL report PowerShell prints, reduced to (owner, granting SIDs, current user). */
+/** .NET's AceType names as the rule's ACE type: allow and deny are read, every other type is refused (DEC-0057). */
+const ACE_TYPES = { AccessAllowed: 'allow', AccessDenied: 'deny', AccessAllowedObject: 'allow-object', AccessDeniedObject: 'deny-object',
+  AccessAllowedCallback: 'allow-callback', AccessDeniedCallback: 'deny-callback', AccessAllowedCallbackObject: 'allow-object-callback',
+  AccessDeniedCallbackObject: 'deny-object-callback' };
+
+/**
+ * The ACL report PowerShell prints, as (owner SID, ACEs `{type, sid, mask}`, current user). The mask arrives signed
+ * (GENERIC_READ 0x80000000 is negative in .NET) and is read as the unsigned 32-bit mask; a NULL DACL grants everyone
+ * everything and is read as an allow ACE for Everyone (S-1-1-0).
+ */
 export function parseAclReport(text) {
   const report = JSON.parse(text);
-  const granting = report.nullDacl ? ['S-1-1-0'] : [].concat(report.granting ?? []);
-  return { owner: report.owner ?? '', granting, user: report.user };
+  const aces = report.nullDacl ? [{ type: 'allow', sid: 'S-1-1-0', mask: 0x1f01ff }]
+    : [].concat(report.aces ?? []).map((ace) => ({ type: ACE_TYPES[ace.type] ?? String(ace.type), sid: ace.sid, mask: Number.isInteger(ace.mask) ? ace.mask >>> 0 : ace.mask }));
+  return { owner: report.owner ?? '', aces, user: report.user };
 }
 
-/** (owner SID, SIDs of every allow ACE on the file itself, the current user's SID). */
+/** (owner SID, the ACEs on the file itself, the current user's SID). */
 export function windowsAcl(file) {
   return parseAclReport(windowsHelper('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', ACL_SCRIPT], { FABRIC_ACL_PATH: file }));
 }
@@ -356,13 +476,14 @@ export function windowsProtect(target, { folder }) {
 }
 
 function windowsTokenProblem(file, info) {
-  if (!info.isFile()) return `Token file ${file} is not a regular file (a link or junction); refusing it.`;
   const profile = fs.realpathSync.native(process.env.USERPROFILE || os.homedir()).toLowerCase();
   const real = fs.realpathSync.native(file).toLowerCase();
   const inside = path.win32.relative(profile, real);
-  if (!inside || inside.startsWith('..') || path.win32.isAbsolute(inside)) return `Token file ${file} lies outside the user's profile; refusing it.`;
-  const { owner, granting, user } = windowsAcl(file);
-  return tokenAclProblem(file, owner, granting, user);
+  const { owner, aces, user } = windowsAcl(file);
+  return tokenFileProblem(file, {
+    isRegularFile: info.isFile(), isReparsePoint: info.isSymbolicLink(),
+    realPathInProfile: Boolean(inside) && !inside.startsWith('..') && !path.win32.isAbsolute(inside), ownerSid: owner, aces,
+  }, user);
 }
 
 export function tokenMatches(presented, token, scheme = 'Bearer') {
@@ -404,7 +525,9 @@ export function validateDescriptor(d) {
   const problems = [];
   const remote = placementOf(d) === 'remote';
   if (d.placement !== undefined && !PLACEMENTS.includes(d.placement)) problems.push('placement must be local or remote');
-  const required = ['protocol', 'id', 'instance', 'name', 'origin', 'auth', 'lifecycle', 'installedAt', 'installedBy'];
+  // DEC-0069: an app's descriptor says it is installed, never that it runs; its live origin is in its own liveness file.
+  const app = d.lifecycle?.manager === 'person';
+  const required = ['protocol', 'id', 'instance', 'name', ...(app ? [] : ['origin']), 'auth', 'lifecycle', 'installedAt', 'installedBy'];
   for (const key of remote ? required : [...required, 'paths']) {
     if (!(key in d)) problems.push(`missing ${key}`);
   }
@@ -413,7 +536,7 @@ export function validateDescriptor(d) {
   if (!ID.test(d.id)) problems.push(`id must match ${ID}`);
   if (!INSTANCE.test(d.instance)) problems.push(`instance must match ${INSTANCE}`);
   if (remote) problems.push(...remoteOriginProblems(d.origin));
-  else if (!ORIGIN.test(d.origin)) problems.push('origin must be http://127.0.0.1:<port>');
+  else if (d.origin !== undefined && !ORIGIN.test(d.origin)) problems.push('origin must be http://127.0.0.1:<port>');
   if (!d.auth?.tokenFile) problems.push('auth.tokenFile is required');
   else if (!LOCAL_PATH.test(String(d.auth.tokenFile))) problems.push('auth.tokenFile must be a local path, never a network share');
   for (const value of [...(d.paths?.data !== undefined ? [d.paths.data] : []), ...(d.paths?.logs ?? [])]) {
@@ -426,11 +549,19 @@ export function validateDescriptor(d) {
   }
   const life = d.lifecycle ?? {};
   const manager = life.manager;
-  if (!MANAGERS.includes(manager)) problems.push('lifecycle.manager must be launchd, systemd, task-scheduler or none');
+  if (!MANAGERS.includes(manager)) problems.push('lifecycle.manager must be launchd, systemd, task-scheduler, node, person or none');
+  // DEC-0069: `app` is the installed app of a person's descriptor, and nothing else's.
+  if (manager === 'person' && life.app === undefined) problems.push("a person's app declares lifecycle.app, the installed app");
+  if (life.app !== undefined && manager !== 'person') problems.push('lifecycle.app belongs to manager person only');
+  if (life.app !== undefined && !LOCAL_PATH.test(String(life.app))) problems.push('lifecycle.app must be a local path');
   if (manager === 'launchd' && !(life.label && String(life.plist ?? '').endsWith('.plist'))) {
     problems.push('a launchd service declares label and plist');
   }
   if (life.plist !== undefined && !LOCAL_PATH.test(String(life.plist))) problems.push('lifecycle.plist must be a local path');
+  // DEC-0057, DEC-0061, DEC-0069: a descriptor names one supervisor; launchd's label and plist never sit beside another.
+  for (const field of ['label', 'plist']) {
+    if (life[field] !== undefined && NOT_LAUNCHD.includes(manager)) problems.push(`lifecycle.${field} belongs to launchd, not to ${manager}`);
+  }
   // DEC-0032: `unit` goes with systemd and `task` with Task Scheduler, and with nothing else.
   for (const [field, owner, pattern] of [['unit', 'systemd', UNIT], ['task', 'task-scheduler', TASK]]) {
     if (manager === owner && life[field] === undefined) problems.push(`a ${owner} service declares ${field}`);
@@ -444,6 +575,7 @@ export function validateDescriptor(d) {
     }
     if (d.commands?.update !== undefined) problems.push('a remote service declares no update command');
   }
+  problems.push(...descriptorMemberProblems(d));
   for (const [name, argv] of Object.entries(d.commands ?? {})) {
     if (!['doctor', 'update'].includes(name)) problems.push(`unknown command ${name}`);
     else if (!Array.isArray(argv) || !argv.length || !argv.every((a) => typeof a === 'string')) problems.push(`command ${name} must be an argument array`);
@@ -453,6 +585,127 @@ export function validateDescriptor(d) {
 }
 
 /** DEC-0019: `local` unless the descriptor says `remote`. */
+// --- DEC-0061 and DEC-0069: who installed it, how its model calls sign in, offered to others, an app's own descriptor ---
+
+/** The organization edition's data classes, least sensitive first (DEC-0061, DEC-0053). */
+export const PEER_DATA_CLASSES = Object.freeze(['public', 'internal', 'confidential', 'restricted']);
+/** The kind of a runner's sign-in, never a credential's value (DEC-0061). */
+export const CREDENTIAL_KINDS = Object.freeze(['subscription', 'key', 'platform-metered', 'none']);
+/** A subscription runs only in its vendor's runner (DEC-0046): runner kind → login. */
+export const SUBSCRIPTION_RUNNERS = Object.freeze({ 'claude-code': 'claude', 'kimi-code': 'kimi', codex: 'chatgpt' });
+const PEER_ENDPOINT = /^https:\/\/((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63})(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?(\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*)?$/;
+const RESIDENCY = /^(A[B-Z]|[B-PR-WY][A-Z]|Q[A-L]|Z[A-Y])$/;
+const RUNNER_KIND_NAME = /^[a-z][a-z0-9-]{1,62}$/;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v, low = 1, high = 200) => typeof v === 'string' && v.length >= low && v.length <= high;
+/** A JSON Pointer token (RFC 6901 §4). */
+const pointer = (name) => String(name).replace(/~/g, '~0').replace(/\//g, '~1');
+
+/**
+ * DEC-0061 and DEC-0069 on a descriptor's `installedBy`, `runner` and `peer`, as the schema shapes them, with FAC-SEM-085
+ * (a peer on a reserved name) and FAC-SEM-086 (a credential-shaped value in `runner` or `installedBy`, named by its
+ * place, never its value).
+ */
+export function descriptorMemberProblems(d) {
+  const problems = [];
+  const life = isObj(d.lifecycle) ? d.lifecycle : {};
+  const by = d.installedBy;
+  const places = [];
+  if (typeof by === 'string') {
+    if (!text(by)) problems.push('installedBy is the installer and its version, 1 to 200 characters');
+    places.push(['/installedBy', by]);
+  } else if (isObj(by)) {
+    for (const k of Object.keys(by)) if (!['by', 'role', 'tool'].includes(k)) problems.push(`installedBy has no member ${k}`);
+    if (!['person', 'node', 'organization'].includes(by.by)) problems.push('installedBy.by is person, node or organization');
+    if (by.by === 'person' && !['operator', 'administrator'].includes(by.role)) problems.push('installedBy.role is operator or administrator for a person');
+    if (by.by !== 'person' && 'role' in by) problems.push('installedBy.role belongs to a person only');
+    if (!text(by.tool)) problems.push('installedBy.tool is the installer and its version, 1 to 200 characters');
+    for (const [k, v] of Object.entries(by)) places.push([`/installedBy/${pointer(k)}`, v]);
+  } else problems.push("installedBy is the installer's name or {by, role?, tool}");
+  if (life.manager === 'person' && !(isObj(by) && by.by === 'person')) problems.push("an app's descriptor names who installed it as a person: installedBy {by: person, role, tool} (DEC-0069)");
+  let runner = d.runner;
+  if ('runner' in d) {
+    if (!isObj(runner)) { problems.push('runner is {kind?, credentialKind}'); runner = {}; }
+    for (const k of Object.keys(runner)) if (!['kind', 'credentialKind'].includes(k)) problems.push(`runner has no member ${k}`);
+    if (!CREDENTIAL_KINDS.includes(runner.credentialKind)) problems.push('runner.credentialKind is subscription, key, platform-metered or none');
+    if ('kind' in runner && !(typeof runner.kind === 'string' && RUNNER_KIND_NAME.test(runner.kind))) problems.push("runner.kind is a runner kind's name");
+    if (runner.credentialKind === 'subscription' && !Object.hasOwn(SUBSCRIPTION_RUNNERS, runner.kind)) problems.push("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex");
+    for (const [k, v] of Object.entries(runner)) places.push([`/runner/${pointer(k)}`, v]);
+  }
+  if ('peer' in d) {
+    let peer = d.peer;
+    if (!isObj(peer)) { problems.push('peer is {endpoint, custody, residency, maxDataClass}'); peer = {}; }
+    for (const k of Object.keys(peer)) if (!['endpoint', 'custody', 'residency', 'maxDataClass'].includes(k)) problems.push(`peer has no member ${k}`);
+    const m = typeof peer.endpoint === 'string' && peer.endpoint.length <= 2048 ? PEER_ENDPOINT.exec(peer.endpoint) : null;
+    if (!m) problems.push('peer.endpoint is https://<dns-name>[:<port>][/<path>], no query, fragment, userinfo or IP literal');
+    else if (RESERVED_HOST.test(m[1])) problems.push(`FAC-SEM-085: a service offered to others cannot be reached at the reserved name ${m[1]}`);
+    if (!['organization-managed', 'personal'].includes(peer.custody)) problems.push('peer.custody is organization-managed or personal');
+    const r = peer.residency;
+    if (!Array.isArray(r) || r.length < 1 || r.length > 32 || new Set(r.map((x) => JSON.stringify(x))).size !== r.length || !r.every((x) => typeof x === 'string' && RESIDENCY.test(x))) {
+      problems.push('peer.residency is 1 to 32 distinct ISO 3166-1 alpha-2 codes in upper case, EU admitted, no user-assigned code');
+    }
+    if (!PEER_DATA_CLASSES.includes(peer.maxDataClass)) problems.push('peer.maxDataClass is public, internal, confidential or restricted');
+    if (!('runner' in d)) problems.push('a service offered to others declares runner (DEC-0061)');
+    else if (isObj(runner) && runner.credentialKind === 'subscription') problems.push('a service offered to others never runs on a subscription (DEC-0061)');
+  }
+  for (const [place, value] of places) {
+    if (typeof value === 'string' && secretArgument(value)) problems.push(`FAC-SEM-086: ${place} holds a value shaped like a credential; it names a kind, a role or an installer`);
+  }
+  return problems;
+}
+
+/**
+ * The host's check before it routes a request from anyone but the service's operator (DEC-0061, FAC-SEM-088):
+ * `not-offered`, `peer-invalid`, `data-class-unknown` or `above-max-data-class`; null when it may. The contract's `peerRefusal`.
+ */
+export function peerRefusal(descriptor, dataClass) {
+  if (!isObj(descriptor) || !isObj(descriptor.peer)) return 'not-offered';
+  const max = typeof descriptor.peer.maxDataClass === 'string' ? PEER_DATA_CLASSES.indexOf(descriptor.peer.maxDataClass) : -1;
+  if (max < 0) return 'peer-invalid';
+  const asked = typeof dataClass === 'string' ? PEER_DATA_CLASSES.indexOf(dataClass) : -1;
+  if (asked < 0) return 'data-class-unknown';
+  return asked > max ? 'above-max-data-class' : null;
+}
+
+/**
+ * What an app that writes its own descriptor does with it on a start (DEC-0069): `keep` from a translocated copy (macOS
+ * App Translocation); otherwise `write` when there is none, when it is not an app's descriptor, or when its version
+ * (`installedBy.tool`) or its path (`lifecycle.app`) differs; `keep` otherwise. The contract's `appDescriptorAction`.
+ */
+export function appDescriptorAction(existing, tool, appPath) {
+  if (appPath.includes('/AppTranslocation/')) return 'keep';
+  if (!isObj(existing) || !isObj(existing.installedBy)) return 'write';
+  const recorded = isObj(existing.lifecycle) ? existing.lifecycle.app : undefined;
+  return existing.installedBy.tool === tool && recorded === appPath ? 'keep' : 'write';
+}
+
+/** Whether a reader treats a descriptor as stale (DEC-0069): an app's descriptor whose installed app it did not find. */
+export function appDescriptorStale(descriptor, appPresent) {
+  if (!isObj(descriptor) || !isObj(descriptor.lifecycle) || descriptor.lifecycle.manager !== 'person') return false;
+  return !appPresent;
+}
+
+/** Whether `lifecycle.app` of an app's descriptor exists on this machine (a bundle is a folder, an executable a file). */
+export function appPresent(descriptor) {
+  const app = isObj(descriptor?.lifecycle) ? descriptor.lifecycle.app : undefined;
+  try { return typeof app === 'string' && fs.existsSync(expand(app)); } catch { return false; }
+}
+
+/** Fabric's own descriptor (Fabric ADR-0139): `services/fabric.default.json`. */
+export const FABRIC_SERVICE = Object.freeze(['fabric', 'default']);
+
+/**
+ * `present` or `absent` for Fabric's button (DEC-0040 FB-5, DEC-0069, Fabric SCN-142): present when Fabric's own
+ * descriptor is registered and, for an app's descriptor, its app is still installed; a server sets `data-fabric="absent"`
+ * on the button's script otherwise. The button only follows a link, so the liveness file is not read here.
+ */
+export function fabricButtonPresence(dir = servicesDir()) {
+  let found;
+  try { found = JSON.parse(fs.readFileSync(descriptorPath(...FABRIC_SERVICE, dir), 'utf8')); } catch { return 'absent'; }
+  if (!isObj(found) || validateDescriptor(found).length) return 'absent';
+  return appDescriptorStale(found, appPresent(found)) ? 'absent' : 'present';
+}
+
 export function placementOf(d) {
   return d?.placement === 'remote' ? 'remote' : 'local';
 }
@@ -476,8 +729,8 @@ export function writeDescriptor(d, dir = servicesDir()) {
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const me = `${d.id}.${d.instance}`;
-  // DEC-0019: only a local placement claims a port on this computer.
-  const port = placementOf(d) === 'remote' ? null : portOf(d.origin);
+  // DEC-0019: only a local placement claims a port on this computer; DEC-0069: an app's descriptor names none.
+  const port = placementOf(d) === 'remote' || d.origin === undefined ? null : portOf(d.origin);
   for (const [file, other] of readDescriptors(dir)) {
     const key = `${other.id}.${other.instance ?? 'default'}`;
     if (key === me) continue;
@@ -540,6 +793,8 @@ const PROFILE_ID = /^[a-z][a-z0-9-]{0,62}$/;
 const RUNNER_KIND = /^[a-z][a-z0-9-]{1,62}$/;
 const MODEL_ID = /^[a-z0-9][a-z0-9._-]{0,63}\/[a-z0-9][a-z0-9._:-]{0,127}$/;
 export const ROUTES = Object.freeze(['subscription', 'key']);
+/** A usage row's route (DEC-0046, DEC-0061): beside a configuration's two, the hosting platform's own metered models. */
+export const USAGE_ROUTES = Object.freeze([...ROUTES, 'platform-metered']);
 
 /** DEC-0046: the well-known `configuration` — {slots, resolved} as service-well-known.schema.json types it. */
 export function configurationProblems(doc) {
@@ -645,7 +900,7 @@ export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, c
   if (costUsd !== null && (typeof costUsd !== 'number' || !Number.isFinite(costUsd) || costUsd < 0)) throw new ServiceError('costUsd must be a non-negative number or null.');
   const basis = costBasis ?? (costUsd === null ? 'unknown' : 'provider');
   if (!COST_BASES.includes(basis) || (costUsd === null) !== (basis === 'unknown')) throw new ServiceError('costBasis is provider or price-list with a cost, unknown without one.');
-  if (route !== undefined && !ROUTES.includes(route)) throw new ServiceError('route is subscription or key (DEC-0046).');
+  if (route !== undefined && !USAGE_ROUTES.includes(route)) throw new ServiceError('route is subscription, key or platform-metered (DEC-0046, DEC-0061).');
   return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis, ...(route === undefined ? {} : { route }) };
 }
 
@@ -1529,13 +1784,20 @@ export function remoteTokenFile(id, instance = 'default', dir = servicesDir()) {
  * a secret. Returns the descriptor path. `token` is read from the caller — a file or stdin —
  * never from an argument vector.
  */
-export function registerRemote({ id, instance = 'default', name, summary, origin, token, doctor, dir = servicesDir(), installedBy = 'fabric-service register-remote' }) {
+/**
+ * DEC-0019, installer side: register an online service on THIS computer — the token file (0600, never printed) and the
+ * descriptor. DEC-0061: `installedBy` defaults to `{by: 'person', role: 'operator', tool: 'fabric-service register-remote'}`
+ * (a person runs this); `runner` (`{kind?, credentialKind}`) says how its model calls sign in, as a kind and never a
+ * credential; `peer` (`{endpoint, custody, residency, maxDataClass}`) offers it to others and needs `runner`.
+ */
+export function registerRemote({ id, instance = 'default', name, summary, origin, token, doctor, dir = servicesDir(),
+  installedBy = { by: 'person', role: 'operator', tool: 'fabric-service register-remote' }, runner, peer }) {
   if (!token || String(token).trim().length < 16) throw new ServiceError('the service token must be at least 16 characters.');
   const tokenFile = remoteTokenFile(id, instance, dir);
   const d = {
     protocol: PROTOCOL, id, instance, name, ...(summary ? { summary } : {}), placement: 'remote', origin,
     auth: { tokenFile }, lifecycle: { manager: 'none' }, ...(doctor ? { commands: { doctor } } : {}),
-    installedAt: nowIso(), installedBy,
+    installedAt: nowIso(), installedBy, ...(runner ? { runner: { ...runner } } : {}), ...(peer ? { peer: { ...peer } } : {}),
   };
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
@@ -1564,6 +1826,11 @@ function plain(value, what) {
   return value;
 }
 
+/** The supervisor file's writer writes the marker itself; one already in the arguments could only disagree with it. */
+function noMarkerArgument(argv) {
+  if (markerArguments(argv).length) throw new ServiceError(`${SUPERVISOR_ARG} is written by the supervisor file's writer; leave it out of the program arguments.`);
+}
+
 function noSecretInSupervisorFile(argv, environment) {
   // No supervisor file carries a secret (service.md): not in an argument, an environment name or its value.
   for (const arg of argv) {
@@ -1592,7 +1859,8 @@ export function systemdUnit(unit, programArguments, { workingDirectory, environm
   const env = { ...environment };
   for (const name of Object.keys(env)) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new ServiceError(`Environment name ${JSON.stringify(name)} is not a variable name.`);
   noSecretInSupervisorFile(argv, env);
-  env[SUPERVISOR_ENV] ??= 'systemd';
+  noMarkerArgument(programArguments.map(String));
+  env[SUPERVISOR_ENV] = 'systemd'; // the unit's writer writes the marker, whatever the caller passed
   const cwd = plain(String(workingDirectory), 'The working directory');
   if (!cwd.startsWith('/')) throw new ServiceError("A systemd unit's working directory is absolute.");
   return [
@@ -1666,6 +1934,10 @@ export function taskXml(task, programArguments, { workingDirectory, description,
   plain(String(workingDirectory), 'The working directory');
   plain(description ?? task, 'The description');
   noSecretInSupervisorFile(argv, {});
+  noMarkerArgument(argv);
+  // A task's Exec action carries no environment, so the marker is an argument (DEC-0057), before any `--`.
+  const cut = argv.includes('--') ? argv.indexOf('--') : argv.length;
+  argv.splice(cut, 0, SUPERVISOR_ARG, 'task-scheduler');
   const who = user ?? (process.env.USERNAME ? `${process.env.USERDOMAIN ?? ''}\\${process.env.USERNAME}` : '');
   if (!who) throw new ServiceError('Name the user the task runs as (DOMAIN\\user); USERNAME is not set.');
   plain(who, 'The user');