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

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

@@ -22,6 +22,7 @@ import fabric_service as fs  # noqa: E402 - beside this file
 from fabric_http import redact_url  # noqa: E402
 from fabric_secrets import ascii_decoded, repository_name, secret_argument  # noqa: E402
 import fabric_peer_owner as po  # noqa: E402 - DEC-0154 HA-2
+import fabric_supervisors as _sup  # noqa: E402 - where a LaunchDaemon's plist lives (FAA-278)
 import socket  # noqa: E402
 
 
@@ -47,7 +48,17 @@ def listener_owner_verdict(port: int) -> Tuple[str, str]:
     except ConnectionRefusedError:
         return "NOT_RUN", "nothing listens on %s (down)" % where
     except OSError as exc:  # a full backlog, a timeout: the well-known rule reports what answers, each call checked
-        return "NOT_RUN", "could not connect to %s to tell its owner (%s)" % (where, type(exc).__name__)
+        # The listener table still names who holds the port (0.74.0 product reading 10, FAA-260 item 12): another
+        # account's or root's listener is foreign-user without a connection; any other owner is named beside NOT_RUN.
+        held = po.listener(port)
+        if held.kind in (po.ANOTHER_ACCOUNT, po.SYSTEM):
+            why = "another OS account's process" if held.kind == po.ANOTHER_ACCOUNT else "a system account's process"
+            return "FAIL", ("foreign-user: %s is listened on by %s (its listener read by %s; the connect failed with %s); "
+                            "no credential was sent and nothing it answers is read as this service's"
+                            % (where, why, held.method, type(exc).__name__))
+        named = held.kind if held.kind != po.UNKNOWN else "unknown (%s)" % held.reason
+        return "NOT_RUN", "could not connect to %s to tell its owner (%s); its listener reads as %s" % (
+            where, type(exc).__name__, named)
     try:
         owner = po.server_end(sock)
     finally:
@@ -60,6 +71,39 @@ def listener_owner_verdict(port: int) -> Tuple[str, str]:
     return "FAIL", ("foreign-user: %s is held by %s (read by %s); no credential was sent and nothing it answers is read "
                     "as this service's" % (where, why, owner.method))
 
+def port_claim_verdict(path: Path, d: Dict[str, Any], directory: Path, port: int, remote: bool) -> Tuple[str, str]:
+    """`descriptor.port-claim`: (verdict, evidence). Another descriptor here declares this `id.instance`, or a local
+    origin on the same port, compared by the port as the writers refuse it, so `:08080` beside `:8080` is one port
+    (0.74.0 seam reading 10, FAA-260)."""
+    me = "%s.%s" % (d.get("id"), d.get("instance", "default"))
+    clashes = []
+    for other_path, other in fs.read_descriptors(directory):
+        key = "%s.%s" % (other.get("id"), other.get("instance", "default"))
+        if other_path.resolve() == path.resolve():
+            continue
+        if key == me:
+            clashes.append("%s declared again in %s" % (me, other_path.name))
+        # DEC-0069: a descriptor without an origin (an app's) claims no port, so two of them never clash.
+        elif not remote and "origin" in d and fs.placement_of(other) != "remote" and port and _port_or_none(
+                other.get("origin")) == port:
+            clashes.append("port %d also claimed by %s" % (port, key))
+    if remote:
+        unique = "a remote origin claims no port here"
+    elif "origin" not in d:
+        unique = "an app's descriptor names no origin, so it claims no port (FAC-SEM-010)"
+    else:
+        unique = "no other descriptor here declares port %d (HA-1's claim on the computer is FAA-225)" % port
+    return ("FAIL" if clashes else "PASS"), ("; ".join(clashes) or unique)
+
+
+def _port_or_none(origin: Any) -> Optional[int]:
+    """The port a local origin claims, or None for an origin the descriptor rules refuse (descriptor.valid names it)."""
+    try:
+        return fs.port_of(str(origin))
+    except fs.ServiceError:
+        return None
+
+
 _LOCAL_PATH = re.compile(r"[/~.\\]|[A-Za-z]:[/\\]")  # how a local path starts, never a user before an `@`
 _SCP_HOST = re.compile(r"[^@/:\\]+:")  # what follows the `@` of user[:password]@host:path
 _SPECIAL = re.compile(r"(?:https?|wss?|ftp|file):", re.I)  # the URL standard's special schemes, read with or without `//`
@@ -91,9 +135,48 @@ import fabric_actions as fa  # noqa: E402 - beside this file (DEC-0121)
 import fabric_a2a as fa2  # noqa: E402 - beside this file (DEC-0122)
 
 
-def plist_problems(plist: dict, label: object, token: object = None) -> list:
-    """What makes a service's launchd job unfit to stay up: identity, restart, secrets."""
+def other_domain_copy(label: object, domain: str, user_name: object = None) -> Optional[str]:
+    """The other launchd domain when it also has job `label` loaded, a second copy (FAA-286 item 6), else None. For a
+    LaunchDaemon (`system`) that is a gui/<uid> domain: first the one of its plist's UserName (`user_name`), where a
+    leftover LaunchAgent of a dedicated account runs (FAA-317), then the probe's own."""
+    if domain == "system":
+        uids = [_sup._account_uid(user_name)] if isinstance(user_name, str) and user_name else []
+        uids.append(getattr(os, "getuid", lambda: 0)())
+        others = ["gui/%d" % uid for i, uid in enumerate(uids) if uid is not None and uid not in uids[:i]]
+    else:
+        others = ["system"]
+    for other in others:
+        try:
+            out = subprocess.run(["launchctl", "print", "%s/%s" % (other, label)], capture_output=True, text=True,
+                                 timeout=10)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if out.returncode == 0:
+            return other
+    return None
+
+
+def in_launch_daemons(plist_path: Path) -> bool:
+    """Whether a plist sits in /Library/LaunchDaemons, where launchd loads it at boot as a LaunchDaemon (FAA-278): the
+    supervisors' own rule, imported (FAA-317), which a test may point elsewhere through their SYSTEM_DAEMONS."""
+    return _sup._in_daemons(plist_path)
+
+
+def plist_problems(plist: dict, label: object, token: object = None, *, system: bool = False,
+                   commands: object = None) -> list:
+    """What makes a service's launchd job unfit to stay up: identity, restart, secrets. A LaunchDaemon (`system`) also
+    needs UserName, or it runs as root (FAA-286 item 22), and its descriptor's commands an absolute path, since a
+    `~` would be root's home when the job's update runs as root (item 23)."""
     problems = []
+    if system and not (isinstance(plist.get("UserName"), str) and plist.get("UserName")):
+        problems.append("a LaunchDaemon without UserName runs as root, and every client refuses root's listener "
+                        "(DEC-0154 HA-2)")
+    if system and isinstance(commands, dict):
+        for name, argv in sorted(commands.items()):
+            first = argv[0] if isinstance(argv, list) and argv else argv
+            if isinstance(first, str) and first.startswith("~"):
+                problems.append("commands.%s starts with ~, which is root's home for a LaunchDaemon: write the absolute "
+                                "path" % name)
     if plist.get("Label") != label:
         problems.append("Label %r" % plist.get("Label"))
     if plist.get("RunAtLoad") is not True:
@@ -729,3 +812,63 @@ def service_checkout(descriptor: Any, repo: Optional[str]) -> Tuple[Optional[Pat
         if same_repository(_git_out(Path(top), "remote", "get-url", "origin") or "", source):
             return Path(top), "the checkout of %s that holds %s" % (shown_repository(source), place)
     return None, "no checkout of %s holds the descriptor's commands, manifest or launchd job; pass --repo" % shown_repository(source)
+
+
+# FAA-298: a service with limits of its own holds work visibly (fabric_holds), never silently.
+_HOLD_USE = "HoldBook|waiting_message|waitingMessage|hold_job|holdJob"  # git grep -E is POSIX: no word boundary
+#: the kit's own copies, and a vendored copy of this file (its pattern names the kit's words): neither is a use
+_HOLD_KIT_FILES = ("fabric_holds.py", "fabric-holds.mjs", "check_service_rules.py")
+#: only code holds work: a README or a note naming HoldBook is no use of it (0.81.0 seam reading)
+_HOLD_CODE = ("*.py", "*.mjs", "*.js", "*.ts")
+
+
+def declared_limits(wk: Any, usage_report: Any = None) -> List[str]:
+    """The limits a service declares: the load declaration's `limits` (DEC-0104), and the usage report's `budget` and
+    `budgets` (DEC-0021, DEC-0027) when the probe read one. An invalid load declaration reads as not declared."""
+    import fabric_load  # noqa: E402 - beside this file
+    found: List[str] = []
+    view = fabric_load.load_view(wk)
+    limits = (view.get("load") or {}).get("limits") if view.get("valid") else None
+    if isinstance(limits, dict):
+        found += ["load %s %s" % (name, limits[name]) for name in ("concurrency", "perCaller", "queueMax") if name in limits]
+    if isinstance(usage_report, dict):
+        budget = usage_report.get("budget")
+        if isinstance(budget, dict) and "limitUsd" in budget:
+            found.append("usage budget USD %s a %s" % (budget.get("limitUsd"), budget.get("period")))
+        budgets = usage_report.get("budgets")
+        if isinstance(budgets, list) and budgets:
+            found.append("usage budgets (%d)" % len(budgets))
+    return found
+
+
+def holds_verdict(limits: List[str], repo: Optional[Path], why: str,
+                  budget: float = OPENS_IN_HOST_BUDGET) -> Tuple[str, str]:
+    """`limits.holds` over one checkout: PASS when a tracked file outside the kit's own copy and the tests holds work
+    through fabric_holds (HoldBook, waiting_message, hold_job) in a code file (.py, .mjs, .js, .ts); NOT_RUN when it
+    declares none, or its checkout or git cannot be read in the budget. A service that declares limits and holds none
+    through the kit is NOT_RUN with a migration note naming fabric_holds, never FAIL: services built before the module
+    existed could not have adopted it, and whether one holds work silently or refuses it cannot be read from its tree."""
+    if not limits:
+        return "NOT_RUN", "the service declares no limits (a load declaration's limits, a usage report's budget or budgets)"
+    if repo is None:
+        return "NOT_RUN", why
+    if not shutil.which("git"):
+        return "NOT_RUN", "git is not installed"
+    try:
+        listed = subprocess.run(["git", "-C", str(repo), "grep", "-I", "-l", "-z", "-E", _HOLD_USE, "--"]
+                                + list(_HOLD_CODE), capture_output=True,
+                                timeout=max(0.05, budget))
+    except subprocess.TimeoutExpired:
+        return "NOT_RUN", "the %.1f s budget ran out while git read %s" % (budget, repo)
+    except OSError as exc:
+        return "NOT_RUN", "git could not read %s: %s" % (repo, exc)
+    if listed.returncode not in (0, 1):
+        return "NOT_RUN", "git grep could not read %s" % repo
+    users = [p for p in listed.stdout.decode("utf-8", "surrogateescape").split("\0")
+             if p and p.rsplit("/", 1)[-1] not in _HOLD_KIT_FILES and not _TEST_PATH.search(p)]
+    if users:
+        return "PASS", "declares %s; %s hold(s) work through fabric_holds" % ("; ".join(limits), ", ".join(users[:5]))
+    return "NOT_RUN", ("migration: declares %s, and no tracked code file outside the kit and the tests holds work "
+                       "through fabric_holds (HoldBook, waiting_message, hold_job) yet. Adopt fabric_holds so each hold "
+                       "is said on the job, the operator is pushed once per hold and takes a scoped lift (FAA-298, "
+                       "references/interop.md); until then this rule is not run" % "; ".join(limits))

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

@@ -3,7 +3,7 @@
 // connectionsExtension builds the `extensions` entry a service declares, `state` from its own checks and its degraded[].
 // Part of the Node service kit (FAA-62, layer L3); the twin of fabric_connections.py. Node 20+, no dependency.
 import { ServiceError } from './fabric-base.mjs';
-import { BEARER_INSIDE, JWT_SHAPE, longSecret, secretUrl } from './fabric-secrets.mjs';
+import { BEARER_INSIDE, hasJwt, longSecret, secretUrl } from './fabric-secrets.mjs';
 import { isObject } from './fabric-jsvalue.mjs';
 
 export const CONNECTIONS_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/connections/0.1';
@@ -112,8 +112,9 @@ const longRun = (value) =>
     const cut = at < 0 ? -1 : piece.indexOf('://', at);
     return longSecret(cut < 0 ? piece : piece.slice(0, cut));
   });
+// hasJwt reads a JWT in one pass, where JWT_SHAPE backtracks from every `eyJ` of a long run (FAA-313).
 const credential = (value, runs) =>
-  JWT_SHAPE.test(value) || KEY_SHAPE.test(value) || BEARER_INSIDE.test(value) || (runs && longRun(value)) || urlsIn(value).some(secretUrl);
+  hasJwt(value) || KEY_SHAPE.test(value) || BEARER_INSIDE.test(value) || (runs && longRun(value)) || urlsIn(value).some(secretUrl);
 
 /** What the schema cannot state: an id named twice, a credential in any string member. */
 function beyondShape(list) {

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

@@ -9,6 +9,8 @@
 //     effects: { 'example.write': 'draft' }, issuer: wk.auth.delegation.issuer });
 //   const verdict = await gate(toolName, req.headers);   // before the tool runs
 //   if (!verdict.ok) return refusalToolResult(verdict);
+//
+// Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import crypto from 'node:crypto';
 import fs from 'node:fs';

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

@@ -2,11 +2,12 @@
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_descriptor.py. Node 20+, no dependency.
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import net from 'node:net';
 import path from 'node:path';
 import { credentialName, repositoryCredential, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { ID, INSTANCE, LOCAL_PATH, PRIMARY_CAPABILITY, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
-import { ANOTHER_ACCOUNT } from './fabric-peer-owner.mjs'; // L0: who listens on a port (DEC-0154 HA-2, FAA-225)
+import { ANOTHER_ACCOUNT, SYSTEM, THIS_ACCOUNT, UNKNOWN, normHost, owner as peerOwnerOf, peer as peerOfSocket } from './fabric-peer-owner.mjs'; // L0: who listens on a port and who connected (DEC-0154 HA-2, FAA-225, FAA-227)
 import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
 import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
@@ -17,7 +18,7 @@ import { ROUTES } from './fabric-usage.mjs';
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
 
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.6';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.7';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -329,6 +330,82 @@ server.once('error', async () => {
 server.listen({ port: Number(port), host: '127.0.0.1', exclusive: true }, () => server.close(() => say(null)));
 `;
 
+// How a loopback server treats the OS account of the process that connected (DEC-0154 HA-2's server side, HA-3;
+// FAA-227): `refuse` (the default) closes a connection whose peer is another OS account's before reading a byte of it
+// and serves the rest, labelled; `strict` also refuses a peer whose owner cannot be told and a system account other
+// than root (uid 0, which can read every account's files and installs a LaunchDaemon); `off` reads no table. The twin
+// of fabric_descriptor.py's PEER_CHECKS and LoopbackHTTPServer.
+export const PEER_CHECKS = Object.freeze(['refuse', 'strict', 'off']);
+
+/** Why a server refuses the peer `owner` (a fabric-peer-owner owner) under `mode`, or null to serve it: the owner's
+ * kind, or for `unknown` its reason; never an address or anything the peer sent. */
+export function connectionRefusal(owner, mode = 'refuse') {
+  if (!PEER_CHECKS.includes(mode)) throw new ServiceError(`peerCheck must be one of ${PEER_CHECKS.join(', ')}.`);
+  if (mode === 'off' || owner === null || owner === undefined) return null;
+  const kind = owner.kind ?? UNKNOWN;
+  if (kind === ANOTHER_ACCOUNT) return kind;
+  if (mode === 'strict' && kind !== THIS_ACCOUNT) {
+    if (kind === SYSTEM && owner.uid === 0) return null;
+    return owner.reason || kind;
+  }
+  return null;
+}
+
+/** Whether a connection's peer address is a loopback one (127.0.0.0/8, ::1, or either IPv4-mapped): the only peers
+ * whose owner can be another account of this computer (DEC-0154 HA-2). An address that cannot be read counts as
+ * loopback, so its owner is still read from the table. The twin of fabric_descriptor.py's is_loopback_peer. */
+export function isLoopbackPeer(address) {
+  if (typeof address !== 'string') return true;
+  const host = normHost(address);
+  if (net.isIPv4(host)) return host.split('.')[0] === '127';
+  if (net.isIPv6(host)) return host === '::1';
+  return true;
+}
+
+const connectionOwners = new WeakMap();
+
+/** The owner of the peer behind an HTTP request's socket (`req.socket`) a loopbackServer served, or null. */
+export function connectionOwner(socket) {
+  return connectionOwners.get(socket) ?? null;
+}
+
+/** A net.Server to listen on in place of `httpServer` (DEC-0154 HA-2's server side, FAA-227): each connection arrives
+ * paused, its peer is told from the computer's socket table (`peer`, fabric-peer-owner's by default), and only a peer
+ * `peerCheck` serves is handed to `httpServer` (never listened on itself), which then reads the request; a refused one
+ * is destroyed unread, counted in `peerRefusals`, and reported to `onRefused(owner, reason)` (default: one line on
+ * stderr with the owner's kind, uid and pid). Handlers find their peer's owner with `connectionOwner(req.socket)`.
+ * The check applies to loopback peers only: a peer at another address (a server bound to 0.0.0.0) is no local
+ * account, so its table is not read and it is served under `refuse` and `strict` alike, with no owner.
+ * Close the returned server to stop accepting; `httpServer.closeAllConnections()` ends the served ones. */
+export function loopbackServer(httpServer, { peerCheck = 'refuse', peer = peerOfSocket, onRefused } = {}) {
+  connectionRefusal(null, peerCheck);
+  const report = onRefused ?? ((who, reason) => process.stderr.write(
+    `fabric: refused a loopback peer (${reason}, uid ${who?.uid ?? 'None'}, pid ${who?.pid ?? 'None'}) before reading it (DEC-0154)\n`));
+  const gate = net.createServer({ pauseOnConnect: true }, async (socket) => {
+    let who = null;
+    if (peerCheck !== 'off' && isLoopbackPeer(socket.remoteAddress)) {
+      try {
+        who = await peer(socket);
+      } catch (err) {
+        who = peerOwnerOf(UNKNOWN, { reason: `reader: ${err?.name ?? 'Error'}` });
+      }
+    }
+    const reason = connectionRefusal(who, peerCheck);
+    if (reason !== null) {
+      gate.peerRefusals += 1;
+      socket.destroy();
+      report(who, reason);
+      return;
+    }
+    if (socket.destroyed) return;
+    if (who !== null) connectionOwners.set(socket, who);
+    httpServer.emit('connection', socket);
+    socket.resume();
+  });
+  gate.peerRefusals = 0;
+  return gate;
+}
+
 /** Who listens on 127.0.0.1:<port> now, as [kind, uid] from the kit's fabric-peer-owner, or null when nothing holds it
  * (FAA-225, DEC-0154 HA-2). */
 export function portOwner(port) {

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

@@ -0,0 +1,269 @@
+// Work a service holds by its own limits, said to its caller and its operator (FAA-298): a held job's statusMessage in
+// the contract's pause grammar (`quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`; the
+// pinned interop-job schema is closed, so `waiting {reason, since, until, message}` rides statusMessage, never a field
+// of the job), one push per hold, and the operator's scoped lift. The twin of fabric_holds.py, held to the same
+// vectors (test/fixtures/holds/waiting-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
+// Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { ServiceError, nowIso } from './fabric-base.mjs';
+import { atomicWrite } from './fabric-paths.mjs';
+import { decisionShape } from './fabric-actions.mjs';
+import { QUOTA_EXHAUSTED, codePoints, pauseMessage, readJobPause, utcTime } from './fabric-interop-rules.mjs';
+import { secretValue } from './fabric-secrets.mjs';
+
+/** The limits a hold names: a daily quota, a per-caller share, a concurrency cap, a money cap. */
+export const HOLD_REASONS = Object.freeze(['daily-quota', 'caller-share', 'concurrency', 'money']);
+/** How the push names each reason to a person. */
+export const REASON_WORDS = Object.freeze({
+  'daily-quota': 'the daily quota', 'caller-share': 'its per-caller share',
+  concurrency: 'the concurrency cap', money: 'the money cap',
+});
+/** The push's kind: a decision for the operator (level notice, notify true). */
+export const HOLD_EVENT_KIND = 'limit.held';
+/** The record of a lift applied (level info, no notify). */
+export const LIFT_EVENT_KIND = 'limit.lifted';
+/** The decision action a lift carries (DEC-0121 AP-2 shape). */
+export const LIFT_ACTION = 'limit.lift';
+const MAX_STATUS_MESSAGE = 500;
+const WAITING = /^waiting (daily-quota|caller-share|concurrency|money) since ([0-9][0-9TZ:.-]*?)(?:: ([\s\S]+))?$/;
+const SIZES = ['jobs', 'usd', 'limit'];
+
+const instant = (value, name) => {
+  if (!Number.isFinite(utcTime(value))) throw new ServiceError(`${name} is a UTC instant (Z, at most 3 fraction digits).`);
+  return value;
+};
+const reasonOk = (reason, what) => {
+  if (!HOLD_REASONS.includes(reason)) throw new ServiceError(`A ${what}'s reason is one of ${HOLD_REASONS.join(', ')}.`);
+};
+// One run of ECMAScript's whitespace, written out as fabric_secrets.JS_SPACE is, the class both twins squash with
+// (FAA-316): Python's str.split() also takes U+001C to U+001F and U+0085 and not U+FEFF.
+const SPACES = /[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/g;
+const squash = (text) => String(text).replace(SPACES, ' ').replace(/^ | $/g, '');
+
+/** A held job's statusMessage; the message is shortened, never refused, to fit 500 characters. */
+export function waitingMessage(reason, since, until = null, message = null) {
+  reasonOk(reason, 'hold');
+  instant(since, 'since');
+  if (until !== null && until !== undefined) instant(until, 'until');
+  else until = null;
+  let text = `waiting ${reason} since ${since}`;
+  const head = QUOTA_EXHAUSTED.length + (until === null ? 0 : ' until '.length + until.length) + ': '.length;
+  if (message !== null && message !== undefined) {
+    const squashed = squash(message);
+    const room = MAX_STATUS_MESSAGE - head - codePoints(text) - ': '.length;
+    if (squashed && room > 0) {
+      text += ': ' + (codePoints(squashed) <= room ? squashed : [...squashed].slice(0, room - 3).join('').replace(/ $/, '') + '...');
+    }
+  }
+  return pauseMessage(until === null ? { text } : { resetsAt: until, text });
+}
+
+/** `{reason, since, until?, message?}` of a fabric.job.get answer whose job a limit holds, else null. */
+export function readWaiting(answer) {
+  const pause = readJobPause(answer);
+  if (!pause.paused) return null;
+  let rest = answer.job.statusMessage.slice(QUOTA_EXHAUSTED.length);
+  if ('resetsAt' in pause) rest = rest.slice(' until '.length + pause.resetsAt.length);
+  if (!rest.startsWith(': ')) return null;
+  const match = WAITING.exec(rest.slice(2));
+  if (!match || !Number.isFinite(utcTime(match[2]))) return null;
+  const waiting = { reason: match[1], since: match[2] };
+  if ('resetsAt' in pause) waiting.until = pause.resetsAt;
+  if (match[3] !== undefined) waiting.message = match[3];
+  return waiting;
+}
+
+/** Put one job of a fabric-interop JobStore on hold (JobStore.pause with the waiting text). */
+export function holdJob(jobs, jobId, reason, since, until = null, message = null) {
+  let text = waitingMessage(reason, since, until, message).slice(QUOTA_EXHAUSTED.length);
+  if (until !== null && until !== undefined) text = text.slice(' until '.length + until.length);
+  return jobs.pause(jobId, until === null || until === undefined ? { text: text.slice(2) } : { resetsAt: until, text: text.slice(2) });
+}
+
+/** The push's one sentence: who, what, why, when it frees by itself, and the question. */
+export function holdSentence(caller, work, reason, until) {
+  const frees = until !== null && until !== undefined ? `it frees by itself at ${until}`
+    : (['concurrency', 'caller-share'].includes(reason) ? 'it frees by itself when a running job ends' : 'it does not free by itself');
+  return `${work} for ${caller} is held by ${REASON_WORDS[reason]}; ${frees}. Raise the limit for it?`;
+}
+
+function text(value, name, high = 200) {
+  if (typeof value !== 'string' || !squash(value) || value.length > high) throw new ServiceError(`${name} is a text of 1 to ${high} characters.`);
+  if (secretValue(value)) throw new ServiceError(`${name} looks like a credential; a hold names callers and work, never a secret.`);
+  return squash(value);
+}
+
+const newId = () => crypto.randomUUID().replaceAll('-', '');
+
+/**
+ * The holds a service's limits put on work and the operator's lifts, in one file (0600, written atomically).
+ * `events`, when given, is a function `({kind, level, text, subject, notify}) => event` that writes the push and the
+ * lift record to the service's event log; without it they are returned for the service to write.
+ */
+export class HoldBook {
+  constructor(file, { events = null, clock = nowIso } = {}) {
+    this.file = file;
+    this.events = events;
+    this.clock = clock;
+  }
+
+  load() {
+    if (!fs.existsSync(this.file)) return { holds: [], lifts: [] };
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+    } catch {
+      throw new ServiceError('The hold book is not JSON; it is kept as it is.');
+    }
+    if (data === null || typeof data !== 'object' || !Array.isArray(data.holds) || !Array.isArray(data.lifts)) {
+      throw new ServiceError('The hold book is not {holds, lifts}; it is kept as it is.');
+    }
+    return data;
+  }
+
+  save(data) { atomicWrite(this.file, JSON.stringify(data, null, 1) + '\n', 0o600); }
+
+  now(now) { return instant(now ?? this.clock(), 'now'); }
+
+  emit(kind, level, sentence, subject, notify) {
+    const event = { kind, level, text: sentence, subject };
+    if (notify) event.notify = true;
+    return this.events ? this.events(event) : event;
+  }
+
+  static expire(data, at) {
+    for (const hold of data.holds) {
+      if (hold.closed === null && hold.until !== null && utcTime(hold.until) <= at) {
+        hold.closed = 'expired';
+        hold.closedAt = hold.until;
+      }
+    }
+  }
+
+  static live(lift, at) {
+    if (lift.from !== null && lift.from !== undefined && utcTime(lift.from) > at) return false;
+    if (lift.until !== null && lift.until !== undefined && utcTime(lift.until) <= at) return false;
+    return (lift.left ?? 1) > 0;
+  }
+
+  /** Hold `work` for `caller` by `reason`: {hold, statusMessage, push}; push only when this call opened the hold. */
+  hold({ caller, work, reason, until = null, message = null, jobId = null, now = null }) {
+    caller = text(caller, 'caller');
+    work = text(work, 'work');
+    reasonOk(reason, 'hold');
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) {
+      throw new ServiceError(`until ${until} has passed: the limit no longer holds the work.`);
+    }
+    const data = this.load();
+    HoldBook.expire(data, utcTime(at));
+    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    const opened = hold === undefined;
+    if (opened) {
+      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null };
+      data.holds.push(hold);
+    }
+    if (jobId !== null && !hold.jobs.includes(String(jobId))) hold.jobs.push(String(jobId));
+    this.save(data);
+    const statusMessage = waitingMessage(reason, hold.since, hold.until, message);
+    const push = opened ? this.emit(HOLD_EVENT_KIND, 'notice', holdSentence(caller, work, reason, until),
+      { type: 'limit', id: `${reason}:${caller}`.slice(0, 200), label: REASON_WORDS[reason] }, true) : null;
+    return { hold: { ...hold }, statusMessage, push };
+  }
+
+  /** Close the open hold of (reason, caller): the limit freed the work. The next hold pushes again. */
+  release({ reason, caller, now = null }) {
+    const at = this.now(now);
+    const data = this.load();
+    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    if (!hold) return null;
+    hold.closed = 'released';
+    hold.closedAt = at;
+    this.save(data);
+    return { ...hold };
+  }
+
+  openHolds(now = null) {
+    const data = this.load();
+    HoldBook.expire(data, utcTime(this.now(now)));
+    return data.holds.filter((h) => h.closed === null).map((h) => ({ ...h }));
+  }
+
+  /** Record the operator's answer as a scoped lift: exactly one of jobs, usd or limit (limit needs until). */
+  lift({ reason, decision, caller = null, jobId = null, jobs = null, usd = null, limit = null, until = null, now = null }) {
+    reasonOk(reason, 'lift');
+    if (!decisionShape(decision) || decision.action !== LIFT_ACTION) {
+      throw new ServiceError("A lift carries the operator's decision (decision.schema.json, action limit.lift, their "
+        + "words verbatim): operatorDecision({ action: 'limit.lift', instruction: words }).");
+    }
+    const sizes = { jobs, usd, limit };
+    const given = SIZES.filter((name) => sizes[name] !== null && sizes[name] !== undefined);
+    if (given.length !== 1) throw new ServiceError('A lift is one of jobs, usd or limit.');
+    const kind = given[0];
+    const size = sizes[kind];
+    if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0 || (kind !== 'usd' && !Number.isInteger(size))) {
+      throw new ServiceError(`A lift's ${kind} is a positive ${kind === 'usd' ? 'number' : 'integer'}.`);
+    }
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) throw new ServiceError("A lift's window ends after now.");
+    if (kind === 'limit' && until === null) {
+      throw new ServiceError('A raised limit needs its window\'s end (until): it falls back when the window ends.');
+    }
+    const record = { id: newId(), reason, caller: caller === null ? null : text(caller, 'caller'),
+      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at };
+    if (kind !== 'limit') record.left = size;
+    const data = this.load();
+    HoldBook.expire(data, utcTime(at));
+    for (const hold of data.holds) {
+      if (hold.closed === null && hold.reason === reason && (record.caller === null || record.caller === hold.caller)
+        && (jobId === null || hold.jobs.includes(String(jobId)))) {
+        hold.closed = 'lifted';
+        hold.closedAt = at;
+        hold.lift = record.id;
+      }
+    }
+    data.lifts.push(record);
+    this.save(data);
+    const scope = record.caller ? `for ${record.caller}` : 'for every caller';
+    const amount = { jobs: `${size} more job(s)`, usd: `USD ${size} more`, limit: `the limit at ${size}` }[kind];
+    this.emit(LIFT_EVENT_KIND, 'info', `The operator lifted ${REASON_WORDS[reason]} ${scope}: ${amount}${until ? ` until ${until}` : ''}.`,
+      { type: 'limit', id: `${reason}:${record.caller ?? '*'}`, label: REASON_WORDS[reason] }, false);
+    return { ...record };
+  }
+
+  static matching(data, reason, caller, jobId, at, kind) {
+    return data.lifts.filter((l) => l.reason === reason && kind in l && HoldBook.live(l, at)
+      && (l.caller === null || l.caller === caller) && (l.job === null || l.job === jobId));
+  }
+
+  /** Whether a lift lets work past the limit: {admitted: true, lift, left} spends one job or `costUsd`, else {admitted: false}. */
+  admit({ reason, caller, jobId = null, costUsd = null, now = null }) {
+    const at = utcTime(this.now(now));
+    const data = this.load();
+    const kind = costUsd !== null ? 'usd' : 'jobs';
+    const found = HoldBook.matching(data, reason, caller, jobId === null ? null : String(jobId), at, kind)
+      .sort((a, b) => ((a.job === null) - (b.job === null)) || ((a.caller === null) - (b.caller === null)));
+    for (const lift of found) {
+      const need = kind === 'usd' ? costUsd : 1;
+      if (lift.left >= need) {
+        lift.left = kind === 'usd' ? Math.round((lift.left - need) * 1e6) / 1e6 : lift.left - 1;
+        this.save(data);
+        return { admitted: true, lift: lift.id, left: lift.left };
+      }
+    }
+    return { admitted: false };
+  }
+
+  /** The limit in force: `base`, or the highest live raised limit for (reason, caller). */
+  limit({ reason, base, caller = null, now = null }) {
+    const at = utcTime(this.now(now));
+    return Math.max(base, ...HoldBook.matching(this.load(), reason, caller, null, at, 'limit').map((l) => l.limit));
+  }
+
+  /** Every lift with `live`: whether it still applies now. */
+  lifts(now = null) {
+    const at = utcTime(this.now(now));
+    return this.load().lifts.map((l) => ({ ...l, live: HoldBook.live(l, at) }));
+  }
+}