@passioncode-ai/fabric-agent-adapter 0.17.0 → 0.19.0

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

@@ -3,11 +3,13 @@
 // Normative source: fabric-agent-contract docs/specification/service.md (DEC-0015; the remote
 // placement — an online agent or dashboard at an https origin — DEC-0019; the usage report DEC-0021).
 
+import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { credentialName, secretArgument, secretValue } from './fabric-secrets.mjs';
 
 export const PROTOCOL = 'fabric-service/0.1';
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/service/0.1';
@@ -49,6 +51,14 @@ const CODE = /^[A-Za-z0-9_-]{16,256}$/;
 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']);
+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}$/;
+export const WINDOWS_TRUSTED = Object.freeze(['S-1-5-18', 'S-1-5-32-544']);
+export const DEFAULT_EXIT_TIMEOUT = 15;
 
 export class ServiceError extends Error {}
 export class AlreadyRunning extends ServiceError {
@@ -61,29 +71,42 @@ export class AlreadyRunning extends ServiceError {
 
 export const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
 
-export function expand(p) {
-  const out = p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
-  if (!path.isAbsolute(out)) throw new ServiceError(`Path ${p} must be absolute or start with ~/.`);
+/** Paths in a descriptor may start with ~/ (or ~\\ on Windows); everything else must be absolute,
+ * and a network share is never a local path (DEC-0032). */
+export function expand(p, platform = process.platform) {
+  if (!LOCAL_PATH.test(String(p))) throw new ServiceError(`Path ${p} must be absolute or start with ~/.`);
+  const out = /^~[\\/]/.test(p) ? path.join(os.homedir(), p.slice(2)) : p;
+  // On Windows an absolute path names its drive: `/x` is relative to the current drive (the Python kit refuses it too).
+  const absolute = platform === 'win32' ? /^[A-Za-z]:[\\/]/.test(out) : path.posix.isAbsolute(out);
+  if (!absolute) throw new ServiceError(`Path ${p} must be absolute or start with ~/.`);
   return out;
 }
 
-export function servicesDir() {
+// DEC-0032: LOCALAPPDATA, not APPDATA, so token files never roam with the profile.
+const localAppData = () => process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+
+export function servicesDir(platform = process.platform) {
   if (process.env.FABRIC_SERVICES_DIR) return expand(process.env.FABRIC_SERVICES_DIR);
   const home = os.homedir();
-  if (process.platform === 'darwin') return path.join(home, 'Library/Application Support/ai.passioncode.fabric/services');
+  if (platform === 'darwin') return path.join(home, 'Library/Application Support/ai.passioncode.fabric/services');
+  if (platform === 'win32') return path.join(localAppData(), 'passioncode-fabric', 'services');
   return path.join(process.env.XDG_DATA_HOME || path.join(home, '.local/share'), 'passioncode-fabric/services');
 }
 
-export function serviceDirs(id) {
+export function serviceDirs(id, platform = process.platform) {
   if (!ID.test(id)) throw new ServiceError(`Service id ${id} must match ${ID}.`);
   const home = os.homedir();
-  if (process.platform === 'darwin') {
+  if (platform === 'darwin') {
     return {
       data: path.join(home, 'Library/Application Support', id),
       logs: path.join(home, 'Library/Logs', id),
       cache: path.join(home, 'Library/Caches', id),
     };
   }
+  if (platform === 'win32') {
+    const data = path.join(localAppData(), id);
+    return { data, logs: path.join(data, 'Logs'), cache: path.join(data, 'Cache') };
+  }
   return {
     data: path.join(process.env.XDG_DATA_HOME || path.join(home, '.local/share'), id),
     logs: path.join(process.env.XDG_STATE_HOME || path.join(home, '.local/state'), id, 'logs'),
@@ -93,7 +116,8 @@ export function serviceDirs(id) {
 
 export function ensurePrivateDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
-  fs.chmodSync(dir, 0o700);
+  if (process.platform === 'win32') windowsProtect(dir, { folder: true });
+  else fs.chmodSync(dir, 0o700);
   return dir;
 }
 
@@ -102,13 +126,16 @@ export function atomicWrite(file, data, mode = 0o600) {
   const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}`);
   const fd = fs.openSync(tmp, 'wx', mode);
   try {
+    // On Windows the file's ACL is its privacy (DEC-0032): set explicitly and protected — before the bytes go in —
+    // so it does not depend on what the folder hands down. A rename keeps it.
+    if (process.platform === 'win32') windowsProtect(tmp, { folder: false });
     fs.writeSync(fd, data);
     fs.fsyncSync(fd);
   } finally {
     fs.closeSync(fd);
   }
   try {
-    fs.chmodSync(tmp, mode);
+    if (process.platform !== 'win32') fs.chmodSync(tmp, mode);
     fs.renameSync(tmp, file);
   } catch (error) {
     fs.rmSync(tmp, { force: true });
@@ -140,11 +167,15 @@ export class InstanceLock {
       fs.fsyncSync(this.fd);
       return this;
     }
-    // Linux: an abstract unix socket is exclusive, has no file, and dies with the process.
-    const name = `\0fabric-service-${crypto.createHash('sha256').update(path.resolve(this.path)).digest('hex').slice(0, 32)}`;
+    // Linux: an abstract unix socket; Windows: a named pipe. Each is exclusive, has no file, and dies
+    // with the process. The Python kit holds the same name beside its file lock (fabric_service.lock_name).
+    const name = lockName(this.path);
+    if (!name) throw new ServiceError(`No instance lock on ${process.platform}: the kit supports macOS, Linux and Windows.`);
     this.server = net.createServer();
     await new Promise((resolve, reject) => {
-      this.server.once('error', (error) => reject(error.code === 'EADDRINUSE' ? new AlreadyRunning(readPid(this.path), this.path) : error));
+      // Windows reports a held pipe as EADDRINUSE (access denied) or, when its holder capped the instances, EBUSY.
+      const held = (code) => code === 'EADDRINUSE' || (process.platform === 'win32' && code === 'EBUSY');
+      this.server.once('error', (error) => reject(held(error.code) ? new AlreadyRunning(readPid(this.path), this.path) : error));
       this.server.listen(name, resolve);
     });
     this.server.unref();
@@ -160,6 +191,15 @@ export class InstanceLock {
   }
 }
 
+/** The name the lock is held under on Linux (abstract socket) and Windows (named pipe); null on macOS. */
+export function lockName(lockPath, platform = process.platform) {
+  const digest = (text) => crypto.createHash('sha256').update(text).digest('hex').slice(0, 32);
+  if (platform === 'linux') return `\0fabric-service-${digest(path.posix.resolve(lockPath))}`;
+  // Windows paths compare without case: C:\Users and c:\users are one lock.
+  if (platform === 'win32') return `\\\\.\\pipe\\fabric-service-${digest(path.win32.resolve(lockPath).toLowerCase())}`;
+  return null;
+}
+
 function readPid(file) {
   try {
     const text = fs.readFileSync(file, 'utf8').trim();
@@ -171,6 +211,9 @@ function readPid(file) {
 
 /** 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]);
 
 const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));
 
@@ -184,7 +227,7 @@ const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 100
 export async function holdSingleInstance(dataDir, {
   waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code),
 } = {}) {
-  const wait = waitSeconds ?? (supervisedByLaunchd() ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
+  const wait = waitSeconds ?? (supervised() ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
   const deadline = clock() + Math.max(0, wait);
   let delay = LOCK_BACKOFF_FIRST_SECONDS;
   let announced = false;
@@ -218,16 +261,110 @@ export function ensureToken(file) {
   return token;
 }
 
+/**
+ * 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.
+ */
 export function readToken(file) {
   const info = fs.lstatSync(file);
   if (info.isSymbolicLink()) throw new ServiceError(`Token file ${file} is a symlink; refusing it.`);
-  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) throw new ServiceError(`Token file ${file} belongs to another user.`);
-  if (info.mode & 0o077) throw new ServiceError(`Token file ${file} is readable by others; set mode 0600.`);
+  if (process.platform === 'win32') {
+    const problem = windowsTokenProblem(file, info);
+    if (problem) throw new ServiceError(problem);
+  } else {
+    if (typeof process.getuid === 'function' && info.uid !== process.getuid()) throw new ServiceError(`Token file ${file} belongs to another user.`);
+    if (info.mode & 0o077) throw new ServiceError(`Token file ${file} is readable by others; set mode 0600.`);
+  }
   const token = fs.readFileSync(file, 'utf8').trim();
   if (token.length < 16) throw new ServiceError(`Token file ${file} holds no usable token.`);
   return token;
 }
 
+// --- Windows ACLs (DEC-0032) ------------------------------------------------------
+// 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.
+
+/**
+ * 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.
+ */
+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.`;
+  }
+  return null;
+}
+
+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 })",
+  '$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 }))',
+].join('; ');
+
+function windowsHelper(command, args, extraEnv = {}) {
+  // No PSModulePath: the script uses .NET only, and a module path inherited from PowerShell 7 makes
+  // Windows PowerShell load the wrong modules.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => k.toLowerCase() !== 'psmodulepath'));
+  const result = spawnSync(command, args, { env: { ...env, ...extraEnv }, encoding: 'utf8', windowsHide: true, timeout: 30_000 });
+  if (result.error || result.status !== 0) {
+    throw new ServiceError(`${command} failed: ${(result.error?.message || result.stderr || result.stdout || '').trim().slice(0, 200)}`);
+  }
+  return result.stdout;
+}
+
+/** The ACL report PowerShell prints, reduced to (owner, granting SIDs, current user). */
+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 };
+}
+
+/** (owner SID, SIDs of every allow ACE 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 }));
+}
+
+let userSid = null;
+export function windowsUserSid() {
+  if (!userSid) {
+    const line = windowsHelper('whoami.exe', ['/user', '/fo', 'csv', '/nh']).trim();
+    userSid = (line.match(/"(S-1-[0-9-]+)"\s*$/) ?? [])[1];
+    if (!userSid) throw new ServiceError('whoami /user printed no SID.');
+  }
+  return userSid;
+}
+
+/**
+ * A protected list (inheritance off): this user, SYSTEM, Administrators, full control; a folder hands it down.
+ * `/reset` first drops any explicit entry already there (`/inheritance:r` keeps those), so the three are all that remain.
+ */
+export function windowsProtect(target, { folder }) {
+  const grant = folder ? '(OI)(CI)F' : 'F';
+  windowsHelper('icacls.exe', [target, '/reset']);
+  windowsHelper('icacls.exe', [target, '/inheritance:r', '/grant:r', ...[windowsUserSid(), ...WINDOWS_TRUSTED].map((sid) => `*${sid}:${grant}`)]);
+}
+
+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);
+}
+
 export function tokenMatches(presented, token, scheme = 'Bearer') {
   if (!presented) return false;
   let value = presented;
@@ -278,22 +415,39 @@ export function validateDescriptor(d) {
   if (remote) problems.push(...remoteOriginProblems(d.origin));
   else if (!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 ?? [])]) {
+    if (!LOCAL_PATH.test(String(value))) problems.push(`paths must be local paths, never a network share: ${JSON.stringify(value)}`);
+  }
+  if (!(typeof (d.auth?.header ?? 'Authorization') === 'string' && AUTH_HEADER.test(d.auth?.header ?? 'Authorization'))) problems.push(`auth.header must match ${AUTH_HEADER.source}`);
+  if (!['Bearer', 'none'].includes(d.auth?.scheme ?? 'Bearer')) problems.push('auth.scheme is Bearer or none');
   if ((d.auth?.header ?? 'Authorization') !== 'Authorization' && (d.auth?.scheme ?? 'Bearer') !== 'none') {
     problems.push('a custom auth header carries the raw token: scheme must be none');
   }
-  if (!['launchd', 'none'].includes(d.lifecycle?.manager)) problems.push('lifecycle.manager must be launchd or none');
-  if (d.lifecycle?.manager === 'launchd' && !(d.lifecycle.label && String(d.lifecycle.plist ?? '').endsWith('.plist'))) {
+  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 (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-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}`);
+    if (life[field] !== undefined && manager !== owner) problems.push(`lifecycle.${field} belongs to manager ${owner} only`);
+    if (life[field] !== undefined && !pattern.test(String(life[field]))) problems.push(`lifecycle.${field} must match ${pattern.source}`);
+  }
   if (remote) {
-    if (d.lifecycle?.manager !== 'none') problems.push('a remote service is supervised by its platform: lifecycle.manager must be none');
-    for (const field of ['label', 'plist']) if (d.lifecycle?.[field] !== undefined) problems.push(`a remote service has no launchd ${field}`);
+    if (manager !== 'none') problems.push('a remote service is supervised by its platform: lifecycle.manager must be none');
+    for (const [field, of] of [['label', 'launchd'], ['plist', 'launchd'], ['unit', 'systemd'], ['task', 'Task Scheduler']]) {
+      if (life[field] !== undefined) problems.push(`a remote service has no ${of} ${field}`);
+    }
     if (d.commands?.update !== undefined) problems.push('a remote service declares no update command');
   }
   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`);
-    else if (!/^(~\/|\/)/.test(argv[0])) problems.push(`command ${name} must start with an absolute or ~/ executable`);
+    else if (!LOCAL_PATH.test(argv[0])) problems.push(`command ${name} must start with an absolute or ~/ executable`);
   }
   return problems;
 }
@@ -507,7 +661,14 @@ function closeRow(row) {
  * model; days without calls are omitted. A row whose calls are all unpriced costs null; totals
  * are the sums of the model rows (FAC-SEM-025).
  */
-export function usageReport(receipts, { id, instance = 'default', now = Date.now(), budget } = {}) {
+/**
+ * `budgets` (DEC-0027) lists every spending limit the service applies, enforced or not. A machine limit with a
+ * calendar `period` and no `spentUsd` is counted here from the receipts, the way `budget` is, so the two never
+ * disagree; a per-order limit (`per_job`, `approval`) gets `spentUsd: null`; every other limit states its own spend.
+ * A report whose limits break FAC-SEM-031 is refused (`usageLimitProblems`).
+ */
+export function usageReport(receipts, { id, instance = 'default', now = Date.now(), budget, budgets } = {}) {
+  receipts = Array.from(receipts); // read twice: the days, then a rolling window
   const first = utcDate(now - (USAGE_DAYS - 1) * 86_400_000), last = utcDate(now);
   const days = new Map();
   for (const r of receipts) {
@@ -538,14 +699,439 @@ export function usageReport(receipts, { id, instance = 'default', now = Date.now
   const report = { protocol: PROTOCOL, service: { id, instance }, generatedAt: new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z'), currency: 'USD', days: outDays };
   if (budget !== undefined) {
     if (!['day', 'month'].includes(budget?.period) || typeof budget.limitUsd !== 'number' || !(budget.limitUsd > 0)) throw new ServiceError('budget is {period: day|month, limitUsd > 0}.');
-    const prefix = budget.period === 'day' ? last : last.slice(0, 7);
-    const window = outDays.filter((d) => d.date.startsWith(prefix));
-    const unknown = window.length > 0 && window.every((d) => d.costUsd === null);
-    report.budget = { period: budget.period, limitUsd: budget.limitUsd, spentUsd: unknown ? null : Math.round(window.reduce((n, d) => n + (d.costUsd ?? 0), 0) * 1e6) / 1e6 };
+    report.budget = { period: budget.period, limitUsd: budget.limitUsd, spentUsd: spentIn(outDays, budget.period, last) };
+  }
+  if (budgets !== undefined) {
+    report.budgets = budgets.map((given) => {
+      if (!isPlainObject(given)) throw new ServiceError('Each limit in budgets is an object.');
+      const limit = { ...given };
+      if (!('spentUsd' in limit)) {
+        if (PER_ORDER_KINDS.includes(limit.kind)) limit.spentUsd = null;
+        else if (limit.scope === 'machine' && ['day', 'month'].includes(limit.period)) limit.spentUsd = spentIn(outDays, limit.period, last);
+        else if (limit.scope === 'machine' && isNumber(limit.windowSeconds)) limit.spentUsd = spentSince(receipts, now - limit.windowSeconds * 1000, now);
+      }
+      return limit;
+    });
+    const problems = usageLimitProblems(report);
+    if (problems.length) throw new ServiceError(`The report's limits are not coherent: ${problems.join('; ')}`);
   }
   return report;
 }
 
+/** Spend in a rolling window, from the receipts' own times; null when every call in it is unpriced. */
+function spentSince(receipts, start, end) {
+  const iso = (ms) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const lo = iso(start), hi = iso(end);
+  const inside = [...receipts].filter((r) => String(r.at ?? '') > lo && String(r.at ?? '') <= hi);
+  if (inside.length && inside.every((r) => r.costUsd === null || r.costUsd === undefined)) return null;
+  return Math.round(inside.reduce((n, r) => n + (r.costUsd ?? 0), 0) * 1e6) / 1e6;
+}
+
+/** Spend in the current UTC day or month; null when every call in it is unpriced. */
+function spentIn(outDays, period, last) {
+  const prefix = period === 'day' ? last : last.slice(0, 7);
+  const window = outDays.filter((d) => d.date.startsWith(prefix));
+  const unknown = window.length > 0 && window.every((d) => d.costUsd === null);
+  return unknown ? null : Math.round(window.reduce((n, d) => n + (d.costUsd ?? 0), 0) * 1e6) / 1e6;
+}
+
+// --- every spending limit (DEC-0027, FAC-SEM-031) --------------------------------------------
+
+export const LIMIT_SCOPES = Object.freeze(['machine', 'project', 'pool', 'job']);
+export const PER_ORDER_KINDS = Object.freeze(['per_job', 'approval']);
+const LIMIT_ID = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+const LIMIT_KIND = /^[a-z][a-z0-9_]{0,31}$/;
+const LIMIT_FIELDS = ['id', 'scope', 'subject', 'kind', 'period', 'windowSeconds', 'since', 'limitUsd', 'spentUsd', 'enforced', 'tripped'];
+const TIMESTAMP = /^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?([Zz]|[+-]([0-9]{2}):([0-9]{2}))$/;
+
+/** A JSON Schema `date-time` (RFC 3339): a real calendar date and time, `Z` or an offset. */
+export function isTimestamp(value) {
+  const m = typeof value === 'string' ? value.match(TIMESTAMP) : null;
+  if (!m) return false;
+  const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  const calendar = date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+  const offset = m[9] === undefined || (Number(m[9]) <= 23 && Number(m[10]) <= 59);
+  return calendar && hour <= 23 && minute <= 59 && second <= 60 && offset;
+}
+const isNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The `budgets` of a usage report against `service-usage.schema.json` `$defs/limit` and FAC-SEM-031 — the twin of
+ * fabric_service.usage_limit_problems. A breach is not a problem, and an unknown kind is never refused.
+ */
+export function usageLimitProblems(report) {
+  const problems = [];
+  const limits = report?.budgets;
+  if (limits === undefined) return problems;
+  if (!Array.isArray(limits) || limits.length > 64) return ['budgets is a list of at most 64 limits'];
+  const seen = new Set();
+  limits.forEach((limit, i) => {
+    const at = `/budgets/${i}`;
+    if (!isPlainObject(limit)) { problems.push(`${at} is not an object`); return; }
+    for (const key of Object.keys(limit)) if (!LIMIT_FIELDS.includes(key)) problems.push(`${at}/${key} is not a limit field`);
+    for (const key of ['id', 'scope', 'kind', 'limitUsd', 'spentUsd', 'enforced']) if (!(key in limit)) problems.push(`${at} is missing ${key}`);
+    if ('id' in limit && !(typeof limit.id === 'string' && LIMIT_ID.test(limit.id))) problems.push(`${at}/id must match ${LIMIT_ID.source}`);
+    if ('scope' in limit && !LIMIT_SCOPES.includes(limit.scope)) problems.push(`${at}/scope must be one of ${LIMIT_SCOPES.join(', ')}`);
+    if ('subject' in limit && !(typeof limit.subject === 'string' && limit.subject.length >= 1 && limit.subject.length <= 128)) problems.push(`${at}/subject is 1 to 128 characters`);
+    if ('kind' in limit && !(typeof limit.kind === 'string' && LIMIT_KIND.test(limit.kind))) problems.push(`${at}/kind must match ${LIMIT_KIND.source}`);
+    if ('period' in limit && !['day', 'month'].includes(limit.period)) problems.push(`${at}/period is day or month`);
+    if ('windowSeconds' in limit && !(Number.isInteger(limit.windowSeconds) && limit.windowSeconds >= 1)) problems.push(`${at}/windowSeconds is a whole number of seconds, at least 1`);
+    if ('since' in limit && !isTimestamp(limit.since)) problems.push(`${at}/since is a UTC timestamp`);
+    if ('limitUsd' in limit && !(limit.limitUsd === null || (isNumber(limit.limitUsd) && limit.limitUsd > 0))) problems.push(`${at}/limitUsd is a dollar amount above zero, or null`);
+    if ('spentUsd' in limit && !(limit.spentUsd === null || (isNumber(limit.spentUsd) && limit.spentUsd >= 0))) problems.push(`${at}/spentUsd is a dollar amount, zero or more, or null`);
+    for (const key of ['enforced', 'tripped']) if (key in limit && typeof limit[key] !== 'boolean') problems.push(`${at}/${key} is true or false`);
+
+    const flag = (where, message) => problems.push(`FAC-SEM-031 ${at}/${where}: ${message}`);
+    const id = String(limit.id ?? '');
+    if (seen.has(id)) flag('id', `limit id ${id} appears twice`);
+    seen.add(id);
+    const named = limit.scope === 'project' || limit.scope === 'pool';
+    if (named && !('subject' in limit)) flag('subject', `a ${limit.scope} limit names its ${limit.scope} in subject`);
+    if (!named && 'subject' in limit) flag('subject', `a ${limit.scope} limit has no subject`);
+    const windows = ['period', 'windowSeconds', 'since'].filter((f) => f in limit);
+    if (windows.length > 1) flag(windows[1], `a limit has one window, not ${windows.join(' and ')}`);
+    const kind = String(limit.kind ?? '');
+    const seconds = isNumber(limit.windowSeconds) ? limit.windowSeconds : null;
+    if (PER_ORDER_KINDS.includes(kind)) {
+      if (windows.length) flag(windows[0], `${kind} bounds one order and has no window`);
+      if (limit.spentUsd !== null) flag('spentUsd', `${kind} bounds one order, so nothing is spent against it (null)`);
+    } else if (kind === 'daily') {
+      if (!(limit.period === 'day' || seconds === 86400)) flag('period', 'a daily limit counts the UTC day (period day) or the last 24 hours (windowSeconds 86400)');
+    } else if (kind === 'monthly') {
+      if (!(limit.period === 'month' || (seconds !== null && seconds >= 28 * 86400 && seconds <= 31 * 86400))) flag('period', 'a monthly limit counts the UTC month (period month) or a rolling 28–31 days (windowSeconds)');
+    } else if (kind === 'velocity') {
+      if (seconds === null) flag('windowSeconds', 'a velocity limit counts a rolling window (windowSeconds)');
+    } else if (kind === 'pool' || kind === 'emergency') {
+      if (!windows.length) flag('period', `a ${kind} limit names the window it counts (period, windowSeconds or since)`);
+    }
+    const known = PER_ORDER_KINDS.includes(kind) || ['daily', 'monthly', 'pool', 'emergency'].includes(kind);
+    if (known && 'limitUsd' in limit && limit.limitUsd === null) flag('limitUsd', `a ${kind} limit is a dollar amount; only a relative limit (velocity) may leave it null`);
+    if (limit.tripped === true && limit.enforced !== true) flag('tripped', 'a limit that is not enforced cannot have stopped work');
+  });
+  const budget = report.budget;
+  if (isPlainObject(budget) && limits.length) {
+    const kind = budget.period === 'day' ? 'daily' : 'monthly';
+    const same = (x, y) => (x === null || y === null ? x === y : isNumber(x) && isNumber(y) && Math.abs(x - y) <= 0.000001);
+    const twin = limits.some((l) => isPlainObject(l) && l.scope === 'machine' && l.enforced === true && l.kind === kind && l.period === budget.period && same(l.limitUsd, budget.limitUsd) && same(l.spentUsd, budget.spentUsd));
+    if (!twin) problems.push(`FAC-SEM-031 /budget: budget repeats one enforced machine ${kind} limit with period ${budget.period} in budgets[], so old and new readers agree`);
+  }
+  return problems;
+}
+
+// --- the feed client (DEC-0025, FAC-SEM-036) -------------------------------------------------
+
+/**
+ * The one header a client sends the service token in, as the descriptor's `auth` declares it: `header` defaults
+ * to Authorization and `scheme` to Bearer; `none` carries the raw token. Never assume `Authorization: Bearer`.
+ */
+export function tokenHeader(auth, token) {
+  const declared = isPlainObject(auth) ? auth : {};
+  const name = typeof declared.header === 'string' ? declared.header : 'Authorization';
+  const scheme = typeof declared.scheme === 'string' ? declared.scheme : 'Bearer';
+  return { name, value: scheme === 'none' ? token : `Bearer ${token}` };
+}
+
+// --- settings backups (DEC-0025, FAC-SEM-035) ------------------------------------------------
+// The twins of fabric_service.make_settings_backup and the rest; both kits write byte-identical files.
+
+export const SETTINGS_BACKUP_FORMAT = 'fabric-settings-backup/1';
+export const SETTINGS_BACKUP_KEEP = 14;
+export const SETTINGS_BACKUP_MAX_AGE_SECONDS = 24 * 60 * 60;
+const TABLE = /^[a-z][a-z0-9_]{0,62}$/;
+const SECRET_TABLE = /^((.+_)?(account_connections?|account_connection_drafts?|tokens?|secrets?|credentials?|passwords?|login_codes?)|(operator_)?sessions?)$/;
+const COLUMN = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+const SECRET_COLUMN = /^(?:.+_)?(?:[Tt]oken|[Ss]ecret|[Pp]assword|[Pp]assphrase|[Aa]pi_?[Kk]ey|[Pp]rivate_[Kk]ey|[Cc]ookie|[Ll]ogin_[Cc]ode|[Oo]tp|[Cc]redential)s?$/;
+const REASON = /^[a-z][a-z0-9_.-]{0,63}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const URI = /^[A-Za-z][A-Za-z0-9+.-]*:\S*$/;
+const MAX_CELL_CHARS = 1048576;
+const MAX_ROW_VALUES = 512;
+const STALE_TEMP_MS = 60 * 60 * 1000;
+const BACKUP_NAME = /^settings-[0-9]{8}T[0-9]{12}Z\.json$/;
+
+function byCodePoint(a, b) {
+  const x = Array.from(a), y = Array.from(b);
+  for (let i = 0; i < Math.min(x.length, y.length); i += 1) {
+    const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+    if (d !== 0) return d;
+  }
+  return x.length - y.length;
+}
+
+/**
+ * The settings canonical form (DEC-0025, DEC-0043): keys sorted by code point at every level, `", "` and `": "`,
+ * strings escaped as JSON requires and nothing else, integers in decimal — Python's
+ * `json.dumps(value, sort_keys=True, ensure_ascii=False)`. Refuses a fraction, an unsafe integer and non-JSON.
+ */
+export function settingsCanonicalJson(value) {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value)) throw new ServiceError(`${value} has no canonical form: a settings backup stores a fraction as its decimal string`);
+    return String(value);
+  }
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(settingsCanonicalJson).join(', ')}]`;
+  if (isPlainObject(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    return `{${Object.keys(value).sort(byCodePoint).map((key) => `${JSON.stringify(key)}: ${settingsCanonicalJson(value[key])}`).join(', ')}}`;
+  }
+  throw new ServiceError(`${typeof value} is not a JSON value`);
+}
+
+/** The `sha256` a settings backup carries: SHA-256 of the UTF-8 canonical JSON of `tables`. */
+export const settingsBackupDigest = (tables) => crypto.createHash('sha256').update(settingsCanonicalJson(tables), 'utf8').digest('hex');
+
+/** Why a reader refuses this settings backup: its shape and FAC-SEM-035. Empty means intact. */
+export function settingsBackupProblems(doc) {
+  if (!isPlainObject(doc)) return ['a settings backup is a JSON object'];
+  const problems = [];
+  if (doc.format !== SETTINGS_BACKUP_FORMAT) problems.push(`format must be ${SETTINGS_BACKUP_FORMAT}, not ${JSON.stringify(doc.format ?? null)}: a reader refuses a format it does not know`);
+  for (const key of ['format', 'service', 'created_at', 'reason', 'sha256', 'counts', 'tables']) if (!(key in doc)) problems.push(`missing ${key}`);
+  for (const key of Object.keys(doc)) if (!['format', 'service', 'created_at', 'reason', 'sha256', 'counts', 'tables', 'extensions'].includes(key)) problems.push(`${key} is not a settings backup field`);
+  if ('extensions' in doc) {
+    if (!isPlainObject(doc.extensions)) problems.push('extensions is an object');
+    else for (const key of Object.keys(doc.extensions)) if (!URI.test(key)) problems.push(`extensions key ${JSON.stringify(key)} is not a URI`);
+  }
+  if ('service' in doc) {
+    const s = doc.service;
+    if (!isPlainObject(s) || Object.keys(s).sort().join() !== 'id,instance,schema,version') problems.push('service is {id, instance, version, schema}');
+    else {
+      if (!ID.test(String(s.id))) problems.push(`service.id must match ${ID.source}`);
+      if (!INSTANCE.test(String(s.instance))) problems.push(`service.instance must match ${INSTANCE.source}`);
+      if (!(typeof s.version === 'string' && s.version.length <= 64)) problems.push('service.version is a string of at most 64 characters');
+      if (!((Number.isInteger(s.schema) && s.schema >= 0) || (typeof s.schema === 'string' && s.schema.length >= 1 && s.schema.length <= 64))) problems.push('service.schema is a whole number or a short string');
+    }
+  }
+  if ('created_at' in doc && !isTimestamp(doc.created_at)) problems.push('created_at is a UTC timestamp');
+  if ('reason' in doc && !(typeof doc.reason === 'string' && REASON.test(doc.reason))) problems.push(`reason must match ${REASON.source}`);
+  if ('sha256' in doc && !(typeof doc.sha256 === 'string' && SHA256.test(doc.sha256))) problems.push('sha256 is 64 lowercase hex digits');
+  const tables = isPlainObject(doc.tables) ? doc.tables : {};
+  const counts = isPlainObject(doc.counts) ? doc.counts : {};
+  if ('tables' in doc && !isPlainObject(doc.tables)) problems.push('tables is an object');
+  if ('counts' in doc && !isPlainObject(doc.counts)) problems.push('counts is an object');
+  let canonical = true;
+  for (const name of [...Object.keys(tables), ...Object.keys(counts).filter((n) => !Object.hasOwn(tables, n))]) {
+    if (LONE_SURROGATE.test(name)) canonical = false;
+    if (!TABLE.test(name) || SECRET_TABLE.test(name)) problems.push(`table ${name} is never backed up: it can only hold connections, tokens, secrets, credentials, passwords, login codes or sessions (or its name is not a table name)`);
+  }
+  for (const [name, count] of Object.entries(counts)) if (!(Number.isInteger(count) && count >= 0)) problems.push(`counts.${name} is a whole number`);
+  for (const [name, table] of Object.entries(tables)) {
+    if (!isPlainObject(table) || Object.keys(table).sort().join() !== 'columns,rows') { problems.push(`tables.${name} is {columns, rows}`); continue; }
+    let columns = table.columns;
+    if (!(Array.isArray(columns) && columns.length >= 1 && columns.length <= 512 && new Set(columns.map(String)).size === columns.length)) {
+      problems.push(`tables.${name}.columns is 1 to 512 distinct names`);
+      if (!Array.isArray(columns)) columns = [];
+    }
+    for (const column of columns) {
+      if (!(typeof column === 'string' && COLUMN.test(column)) || SECRET_COLUMN.test(String(column))) problems.push(`column ${name}.${column} is refused: its name says it holds a credential value (name the secret, never store it: secret_name, token_slot)`);
+    }
+    if (!Array.isArray(table.rows)) { problems.push(`tables.${name}.rows is a list`); continue; }
+    table.rows.forEach((row, i) => {
+      const at = `/tables/${name}/rows/${i}`;
+      if (!Array.isArray(row)) { problems.push(`${at} is a list of values`); return; }
+      if (row.length !== columns.length) problems.push(`FAC-SEM-035 ${at}: row has ${row.length} values for ${columns.length} columns`);
+      if (row.length > MAX_ROW_VALUES) problems.push(`${at} holds more than ${MAX_ROW_VALUES} values`);
+      row.forEach((cell, j) => {
+        if (typeof cell === 'number' && !Number.isSafeInteger(cell)) {
+          canonical = false;
+          problems.push(`FAC-SEM-035 ${at}/${j}: a fraction or an unsafe integer has no canonical form; store it as a string`);
+        } else if (typeof cell === 'string' && cell.length > MAX_CELL_CHARS) {
+          problems.push(`${at}/${j} is longer than ${MAX_CELL_CHARS} characters`);
+        } else if (typeof cell === 'string' && LONE_SURROGATE.test(cell)) {
+          canonical = false;
+          problems.push(`FAC-SEM-035 ${at}/${j}: a string with a lone surrogate cannot be encoded as UTF-8`);
+        } else if (!(cell === null || ['boolean', 'number', 'string'].includes(typeof cell))) {
+          canonical = false;
+          problems.push(`${at}/${j} is not a JSON scalar`);
+        }
+      });
+    });
+    if (counts[name] !== table.rows.length) problems.push(`FAC-SEM-035 /counts/${name}: counts says ${counts[name] ?? 'nothing'} for ${table.rows.length} rows`);
+  }
+  for (const name of Object.keys(counts)) if (!Object.hasOwn(tables, name)) problems.push(`FAC-SEM-035 /counts/${name}: counts names ${name}, which the backup does not carry`);
+  if (canonical && isPlainObject(doc.tables)) {
+    let digest = null;
+    try {
+      digest = settingsBackupDigest(tables);
+    } catch (error) {
+      problems.push(`FAC-SEM-035 /tables: the tables have no canonical form (${error.message})`);
+    }
+    if (digest !== null && doc.sha256 !== digest) problems.push('FAC-SEM-035 /sha256: the checksum does not match the tables: the file is damaged and a reader refuses it');
+  }
+  return problems;
+}
+
+/** Where every service keeps its settings backups — outside its data directory (DEC-0025). */
+export function settingsBackupRoot(platform = process.platform) {
+  if (platform === 'darwin') return path.join(os.homedir(), 'Library/Application Support/PassionCode');
+  if (platform === 'win32') return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'PassionCode');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'PassionCode');
+}
+
+export function settingsBackupDir(id, instance = 'default', root = settingsBackupRoot()) {
+  if (!ID.test(id)) throw new ServiceError(`Service id ${id} must match ${ID}.`);
+  if (!INSTANCE.test(instance)) throw new ServiceError(`instance must match ${INSTANCE}`);
+  return path.join(root, 'settings-backups', id, instance);
+}
+
+const microStamp = (ms) => `${new Date(ms).toISOString().slice(0, 23)}000Z`;
+
+/** A snapshot of the operator's decisions and bindings (the tables on the service's allow-list). Refuses a file a reader would refuse. */
+export function makeSettingsBackup({ id, instance = 'default', version, schema, tables, reason, now = Date.now() }) {
+  const doc = {
+    format: SETTINGS_BACKUP_FORMAT, service: { id, instance, version, schema }, created_at: microStamp(now), reason, sha256: '',
+    counts: Object.fromEntries(Object.entries(tables).map(([name, table]) => [name, (table?.rows ?? []).length])), tables,
+  };
+  try {
+    doc.sha256 = settingsBackupDigest(tables);
+  } catch (error) {
+    throw new ServiceError(`This snapshot has no canonical form: ${error.message}`);
+  }
+  const problems = settingsBackupProblems(doc);
+  if (problems.length) throw new ServiceError(`This snapshot would be refused: ${problems.join('; ')}`);
+  return doc;
+}
+
+const backupName = (doc) => `settings-${doc.created_at.replace(/[-:]/g, '').replace(/\.(\d+)Z$/, (_, f) => `${(f + '000000').slice(0, 6)}Z`)}.json`;
+
+/** The snapshot files, newest first. */
+export function settingsBackups(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((n) => BACKUP_NAME.test(n)).sort().reverse().map((n) => path.join(dir, n));
+}
+
+/** The first number written with a fraction or an exponent outside a string (`1.0`, `1e2`); JSON.parse would read
+ *  `1.0` as the integer 1, where the Python reader — and the canonical form — sees a fraction. */
+function fractionLexeme(text) {
+  let inString = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (inString) {
+      if (c === '\\') i += 1;
+      else if (c === '"') inString = false;
+    } else if (c === '"') {
+      inString = true;
+    } else if (c === '-' || (c >= '0' && c <= '9')) {
+      const lexeme = text.slice(i).match(/^-?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/)[0];
+      if (/[.eE]/.test(lexeme)) return lexeme;
+      i += lexeme.length - 1;
+    }
+  }
+  return null;
+}
+
+/** A snapshot a reader may trust, or ServiceError naming why it is refused (FAC-SEM-035). */
+export function readSettingsBackup(file) {
+  let doc;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(file));
+    const fraction = fractionLexeme(text);
+    if (fraction) throw new Error(`${fraction} is not an integer: a fraction is stored as its decimal string`);
+    doc = JSON.parse(text);
+  } catch (error) {
+    throw new ServiceError(`Settings backup ${file} cannot be read: ${error.message}`);
+  }
+  const problems = settingsBackupProblems(doc);
+  if (problems.length) throw new ServiceError(`Settings backup ${file} is refused: ${problems.join('; ')}`);
+  return doc;
+}
+
+/**
+ * Write a snapshot: atomically, 0600 in a 0700 directory, named by its time. A temporary file an interrupted write
+ * left is removed first; a snapshot whose checksum equals the newest file's is not written again (null). After a
+ * write, all but the `keep` newest are removed (at least 14).
+ */
+export function writeSettingsBackup(doc, dir, { keep = SETTINGS_BACKUP_KEEP } = {}) {
+  const problems = settingsBackupProblems(doc);
+  if (problems.length) throw new ServiceError(`This snapshot would be refused: ${problems.join('; ')}`);
+  ensurePrivateDir(dir);
+  // Only a temporary file an interrupted write left: one a concurrent writer is still filling is younger.
+  for (const left of fs.readdirSync(dir)) {
+    const at = path.join(dir, left);
+    try {
+      if (left.startsWith('.settings-') && fs.statSync(at).mtimeMs < Date.now() - STALE_TEMP_MS) fs.rmSync(at, { force: true });
+    } catch { /* gone meanwhile */ }
+  }
+  const existing = settingsBackups(dir);
+  if (existing.length) {
+    try {
+      if (readSettingsBackup(existing[0]).sha256 === doc.sha256) return null;
+    } catch { /* a damaged newest file is no reason to skip a good snapshot */ }
+  }
+  const file = path.join(dir, backupName(doc));
+  atomicWrite(file, `${JSON.stringify(doc, null, 2)}\n`, 0o600);
+  // The newest by name, but never the one just written: a clock that stepped back must not delete it.
+  for (const old of settingsBackups(dir).filter((f) => f !== file).slice(Math.max(keep, SETTINGS_BACKUP_KEEP) - 1)) fs.rmSync(old, { force: true });
+  return file;
+}
+
+/** True when there is no snapshot or the newest is older than 24 hours. */
+export function backupDue(dir, now = Date.now()) {
+  const newest = settingsBackups(dir)[0];
+  if (!newest) return true;
+  const m = path.basename(newest).match(/^settings-(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})\d{3}Z\.json$/);
+  // A name no calendar has: take a fresh snapshot rather than trust it (Date.UTC would roll it over).
+  if (!isTimestamp(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`)) return true;
+  const at = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6], +m[7]);
+  return (now - at) / 1000 > SETTINGS_BACKUP_MAX_AGE_SECONDS;
+}
+
+/** The source of an automatic restore: the newest intact snapshot with content; damaged ones are returned with the reason. */
+export function newestIntactBackup(dir) {
+  const skipped = [];
+  for (const file of settingsBackups(dir)) {
+    let doc;
+    try {
+      doc = readSettingsBackup(file);
+    } catch (error) {
+      skipped.push({ file, reason: error.message });
+      continue;
+    }
+    if (Object.values(doc.counts).some((n) => n > 0)) return { file, doc, skipped };
+  }
+  return { file: null, doc: null, skipped };
+}
+
+/**
+ * What restoring `doc` would do — it adds and never overwrites (DEC-0025). `current[table]` is `{columns, key,
+ * required, existing}` (existing primary keys as arrays). The twin of fabric_service.restore_plan.
+ */
+export function restorePlan(doc, current) {
+  const problems = settingsBackupProblems(doc);
+  if (problems.length) throw new ServiceError(`A damaged snapshot is never restored: ${problems.join('; ')}`);
+  const plan = { source: { created_at: doc.created_at, sha256: doc.sha256 }, tables: {}, unknownTables: [] };
+  for (const [name, table] of Object.entries(doc.tables)) {
+    const now = current[name];
+    if (!now) { plan.unknownTables.push(name); continue; }
+    const columns = now.columns ?? [], key = now.key ?? [], required = now.required ?? [];
+    const existing = new Set((now.existing ?? []).map((k) => JSON.stringify([...k])));
+    const shared = table.columns.filter((c) => columns.includes(c));
+    const missing = required.filter((c) => !table.columns.includes(c));
+    const entry = {
+      insert: [], present: 0, droppedColumns: table.columns.filter((c) => !columns.includes(c)),
+      defaultedColumns: columns.filter((c) => !table.columns.includes(c)), missingRequired: missing, refused: [],
+    };
+    const planned = new Set();
+    for (const row of table.rows) {
+      const values = Object.fromEntries(table.columns.map((c, i) => [c, row[i]]));
+      const ident = key.map((c) => values[c] ?? null);
+      if (key.some((c) => !table.columns.includes(c))) entry.refused.push({ key: ident, reason: 'the primary key is not in the snapshot' });
+      else if (planned.has(JSON.stringify(ident))) entry.refused.push({ key: ident, reason: 'the snapshot holds this key twice' });
+      else if (existing.has(JSON.stringify(ident))) entry.present += 1;
+      else if (missing.length) entry.refused.push({ key: ident, reason: `required column ${missing.join(', ')} is not in the snapshot` });
+      else {
+        planned.add(JSON.stringify(ident));
+        entry.insert.push(Object.fromEntries(shared.map((c) => [c, values[c]])));
+      }
+    }
+    plan.tables[name] = entry;
+  }
+  return plan;
+}
+
 /** Usage receipts for services that keep none yet: append-only JSON lines, 0600, pruned to the window (LC-12).
  *  One writer process (the service holds its instance lock); every method is synchronous, so calls never interleave. */
 export class JsonlUsageLedger {
@@ -959,3 +1545,174 @@ export function cookieValue(header, name = SESSION_COOKIE) {
   }
   return null;
 }
+
+// --- systemd and Task Scheduler (DEC-0032, service.md "Supervisor") -------------------------
+// The twins of fabric_service.systemd_unit / task_xml and their install and uninstall. `run(argv)`
+// returns spawnSync's {status, stdout, stderr}; the tests pass a recorder instead of the real tools.
+
+const defaultRun = (argv) => spawnSync(argv[0], argv.slice(1), { encoding: 'utf8', windowsHide: true });
+
+function plain(value, what) {
+  // A supervisor file is line- and XML-structured: no control character in anything written into it.
+  if (/[\x00-\x1f\x7f]/.test(value)) throw new ServiceError(`${what} holds a control character (a line break, a tab, a NUL); a supervisor file cannot carry it.`);
+  return value;
+}
+
+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) {
+    if (secretArgument(arg)) throw new ServiceError('An argument carries a credential; a supervisor file never does (read it from the token file or a secret reference).');
+  }
+  for (const [name, value] of Object.entries(environment ?? {})) {
+    if (credentialName(name) || secretValue(String(value))) throw new ServiceError(`Environment ${name} looks like a credential; a supervisor file never carries one.`);
+  }
+}
+
+function check(result, what) {
+  if (result?.status !== 0) throw new ServiceError(`${what} failed: ${String(result?.stderr || result?.stdout || result?.error?.message || '').trim().slice(0, 200)}`);
+}
+
+const systemdQuote = (value) => `"${plain(value, 'An argument').replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%').replace(/\$/g, '$$$$')}"`;
+
+/**
+ * A systemd user unit (DEC-0032): Restart=always, RestartSec=10, TimeoutStopSec above the drain time,
+ * WantedBy=default.target. The service is told who supervises it (FABRIC_SERVICE_SUPERVISOR=systemd).
+ */
+export function systemdUnit(unit, programArguments, { workingDirectory, environment = {}, description, stopTimeout = DEFAULT_EXIT_TIMEOUT } = {}) {
+  if (!UNIT.test(unit)) throw new ServiceError(`unit must match ${UNIT.source}`);
+  const argv = programArguments.map(String);
+  if (!argv.length || !argv[0].startsWith('/')) throw new ServiceError('A systemd unit starts an absolute executable.');
+  if (!(stopTimeout > DRAIN_SECONDS)) throw new ServiceError(`TimeoutStopSec must outlast the ${DRAIN_SECONDS} s drain.`);
+  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';
+  const cwd = plain(String(workingDirectory), 'The working directory');
+  if (!cwd.startsWith('/')) throw new ServiceError("A systemd unit's working directory is absolute.");
+  return [
+    '[Unit]', `Description=${plain(description ?? unit, 'The description').replace(/%/g, '%%')}`, '',
+    '[Service]', 'Type=simple', `ExecStart=${argv.map(systemdQuote).join(' ')}`,
+    // Not quoted: systemd reads WorkingDirectory= as the rest of the line, quotes included.
+    `WorkingDirectory=${cwd.replace(/%/g, '%%')}`,
+    ...Object.keys(env).sort().map((k) => `Environment=${systemdQuote(`${k}=${env[k]}`)}`),
+    'Restart=always', 'RestartSec=10', `TimeoutStopSec=${Math.trunc(stopTimeout)}`, 'KillMode=mixed', '',
+    '[Install]', 'WantedBy=default.target', '',
+  ].join('\n');
+}
+
+const systemdDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
+
+/**
+ * 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).
+ */
+export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+  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 });
+  const file = path.join(unitDir, unit);
+  const state = fs.existsSync(file) ? String(run(['systemctl', '--user', 'is-enabled', unit])?.stdout ?? '').trim() : '';
+  atomicWrite(file, text, 0o644);
+  check(run(['systemctl', '--user', 'daemon-reload']), 'systemctl --user daemon-reload');
+  if (state === 'disabled' && !forceEnable) return file;
+  check(run(['systemctl', '--user', 'enable', unit]), 'systemctl --user enable');
+  check(run(['systemctl', '--user', 'restart', unit]), 'systemctl --user restart');
+  return file;
+}
+
+/** Stop it and keep it off across logins (`disable --now`), then remove the unit. */
+export function systemdUninstall(unit, { unitDir = systemdDir(), run = defaultRun, platform = process.platform } = {}) {
+  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}`);
+  run(['systemctl', '--user', 'disable', '--now', unit]);
+  fs.rmSync(path.join(unitDir, unit), { force: true });
+  check(run(['systemctl', '--user', 'daemon-reload']), 'systemctl --user daemon-reload');
+}
+
+/** One command line from arguments, quoted the way the Microsoft C runtime parses it (Python's list2cmdline). */
+export function windowsCommandLine(args) {
+  return args.map((arg) => {
+    const quote = arg === '' || /[ \t]/.test(arg);
+    let out = quote ? '"' : '';
+    let slashes = 0;
+    for (const c of arg) {
+      if (c === '\\') { slashes += 1; continue; }
+      if (c === '"') { out += '\\'.repeat(slashes * 2 + 1) + '"'; slashes = 0; continue; }
+      out += '\\'.repeat(slashes) + c;
+      slashes = 0;
+    }
+    return out + '\\'.repeat(quote ? slashes * 2 : slashes) + (quote ? '"' : '');
+  }).join(' ');
+}
+
+const xml = (text) => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/**
+ * A per-user Scheduled Task (DEC-0032): a logon trigger, restart on failure every minute, no execution
+ * time limit, run only when the user is logged on, created without administrator rights.
+ */
+export function taskXml(task, programArguments, { workingDirectory, description, user } = {}) {
+  if (!TASK.test(task)) throw new ServiceError(`task must match ${TASK.source}`);
+  const argv = programArguments.map(String);
+  if (!argv.length || !/^[A-Za-z]:[\\/]/.test(argv[0])) throw new ServiceError('A task starts a drive-absolute executable (C:\\...).');
+  for (const arg of argv) plain(arg, 'An argument');
+  plain(String(workingDirectory), 'The working directory');
+  plain(description ?? task, 'The description');
+  noSecretInSupervisorFile(argv, {});
+  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');
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>${xml(description ?? task)}</Description><URI>${xml(task)}</URI></RegistrationInfo>
+  <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${xml(who)}</UserId></LogonTrigger></Triggers>
+  <Principals><Principal id="Author"><UserId>${xml(who)}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <Enabled>true</Enabled>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>${xml(argv[0])}</Command><Arguments>${xml(windowsCommandLine(argv.slice(1)))}</Arguments><WorkingDirectory>${xml(workingDirectory)}</WorkingDirectory></Exec></Actions>
+</Task>
+`;
+}
+
+const TASK_DISABLED = /<Settings>(?:(?!<\/Settings>)[\s\S])*<Enabled>false<\/Enabled>/;
+
+/**
+ * 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`.
+ */
+export function taskInstall(task, xmlText, { run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+  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;
+  const keepOff = existed && !forceEnable && TASK_DISABLED.test(String(query?.stdout ?? ''));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fabric-task-'));
+  const file = path.join(dir, 'task.xml');
+  try {
+    // schtasks reads the encoding the declaration names: UTF-16 little-endian with its byte order mark.
+    fs.writeFileSync(file, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(xmlText, 'utf16le')]));
+    check(run(['schtasks', '/Create', '/TN', task, '/XML', file, '/F']), 'schtasks /Create');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  if (keepOff) {
+    check(run(['schtasks', '/Change', '/TN', task, '/DISABLE']), 'schtasks /Change /DISABLE');
+    return;
+  }
+  if (existed) run(['schtasks', '/End', '/TN', task]);
+  check(run(['schtasks', '/Run', '/TN', task]), 'schtasks /Run');
+}
+
+/** End the running task, then delete it. */
+export function taskUninstall(task, { run = defaultRun, platform = process.platform } = {}) {
+  if (platform !== 'win32') throw new ServiceError('Task Scheduler is the supervisor on Windows only.');
+  run(['schtasks', '/End', '/TN', task]);
+  check(run(['schtasks', '/Delete', '/TN', task, '/F']), 'schtasks /Delete');
+}