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

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

@@ -6,6 +6,7 @@ only. The dashboard kit's fabric-button.js carries its own copy of the name and
 
 It reads as the contract's ECMAScript does (FAA-136): ECMAScript's whitespace (Python's `\\s` also takes U+0085 and
 U+001C to U+001F, and not U+FEFF), `.` stopping at every line terminator, ASCII case folding, an ASCII word boundary."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 from __future__ import annotations
 
@@ -29,8 +30,20 @@ CREDENTIAL_PAIRS: Dict[str, tuple] = {
 JS_SPACE = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
 _NOT_LINE_END = "[^\n\r\u2028\u2029]"  # ECMAScript's `.` without the s flag
 JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
-SECRET_VALUE = re.compile(r"(^bearer[%s]%s+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}"
-                          r"|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})" % (JS_SPACE, _NOT_LINE_END), re.IGNORECASE | re.ASCII)
+#: Where a provider key's prefix may start (DEC-0151): the start of a value, a character that is no ASCII letter or
+#: digit, or an escape (a percent-escape, single or double, a backslash escape, an octal, `\\x` with two hex digits,
+#: `\\u` with four, an ESC colour sequence, raw or escaped). A consuming group, as the contract writes it.
+_KEY_BOUNDARY = (r"(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt\"']|\\u[0-9A-Fa-f]{4}|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}"
+                 r"|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)")
+#: The provider keys' shapes, prefixes in their canonical case only (DEC-0151 item 7: `SK-` or `GHP_` is no key). An
+#: `sk-` key holds, within 256 characters, a digit and an upper-case letter with 16 or more characters, or a digit with
+#: 32 or more; the look-aheads are bounded to 255 characters and lazy, so a long run of prefixes reads in linear time.
+_PROVIDER_KEYS = (r"(?:sk-(?=[A-Za-z0-9_-]{0,255}?[0-9])(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})"
+                  r"|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})")
+#: The contract's SECRET_VALUE at the pin (DEC-0151): `Bearer ` at a value's start in any case, or a provider key after a
+#: boundary. No case-insensitive flag; digits are ASCII. A match includes its boundary character: callers test, never
+#: read the matched text or its index.
+SECRET_VALUE = re.compile("(^[Bb][Ee][Aa][Rr][Ee][Rr][" + JS_SPACE + "]" + _NOT_LINE_END + "+|" + _KEY_BOUNDARY + _PROVIDER_KEYS + ")")
 _LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
 _BEARER_INSIDE = re.compile(r"(?<![A-Za-z0-9_])bearer[%s]+(?=[A-Za-z0-9._~+/-]*[0-9])[A-Za-z0-9._~+/-]{12,}=*" % JS_SPACE,
                             re.IGNORECASE | re.ASCII)
@@ -142,7 +155,7 @@ def _percent_encode(text: str, also: str) -> str:
     return "".join(out)
 
 
-def _url_parts(value: str) -> Tuple[str, str, str]:
+def url_parts(value: str) -> Tuple[str, str, str]:
     """The password, query and fragment of an absolute URL as WHATWG URL parsing splits them, read by hand: urlsplit
     refuses a `[` or `]` outside an IPv6 host (`<https>://u:p[w@h/`), where `new URL` reads the password (0.56.0 unit
     r7). The fragment starts at the first `#`, the query at the first `?` before it. A special scheme's authority starts
@@ -166,6 +179,9 @@ def _url_parts(value: str) -> Tuple[str, str, str]:
             _percent_encode(fragment, "`"))
 
 
+_url_parts = url_parts  # the name before FAA-250, kept for code that reached it
+
+
 def secret_url(value: str) -> bool:
     """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
     password in its user information, or a query or fragment parameter whose name can only carry a credential and has
@@ -177,7 +193,7 @@ def secret_url(value: str) -> bool:
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
     if not _SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
-    password, query, fragment = _url_parts(value)
+    password, query, fragment = url_parts(value)
     if password:
         return True
     for part in (query, fragment):
@@ -190,7 +206,10 @@ def secret_url(value: str) -> bool:
 _REPOSITORY_URI = re.compile(r"\A([A-Za-z][A-Za-z0-9+.-]*:(?://[^/?#]*)?)([^?#]*)(.*)\Z", re.S)
 _REPOSITORY_NAME = re.compile(r"(?:[a-z0-9._-]+|[A-Za-z._-]+)\Z")  # lower case, or letters with no digit (readings 8)
 _REPOSITORY_AUTHORITY = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://")
-_KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % SECRET_VALUE.pattern, re.IGNORECASE | re.ASCII)
+#: A repository name's own key shapes, boundary-free and case-sensitive (DEC-0151): SECRET_VALUE takes a consuming
+#: boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
+_REPOSITORY_KEYS = r"sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}"
+_KEY_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))(?:%s)" % _REPOSITORY_KEYS)
 _JWT_AT_A_WORD = re.compile(r"(?:\A|(?<=[._-]))%s" % JWT_SHAPE.pattern)
 
 

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

@@ -197,6 +197,24 @@ from fabric_connections import (  # noqa: F401
     connections_rules,
     connections_view,
 )
+from fabric_load import (  # noqa: F401 - the call queue and the load report (DEC-0104, FAA-289)
+    LOAD_EXTENSION_KEY,
+    LOAD_REPORT_TYPE,
+    QUEUE_FULL_MESSAGE,
+    QUEUE_LENGTH_MAX,
+    DEFAULT_RETRY_AFTER_SECONDS,
+    job_caller_key,
+    next_queued_job,
+    admit_job,
+    queue_status_message,
+    read_queue_position,
+    job_queue_rules,
+    load_report_rules,
+    load_report_problems,
+    load_view,
+    load_extension_rules,
+    load_extension,
+)
 from fabric_descriptor import (  # noqa: F401
     DASHBOARD_EXTENSION_KEY,
     DASHBOARD_KIT,
@@ -210,6 +228,8 @@ from fabric_descriptor import (  # noqa: F401
     _NOT_LAUNCHD,
     _AUTH_HEADER,
     LoopbackHTTPServer,
+    PEER_CHECKS,
+    connection_refusal,
     descriptor_path,
     read_descriptors,
     validate_descriptor,
@@ -231,7 +251,9 @@ from fabric_descriptor import (  # noqa: F401
     fabric_button_presence,
     placement_of,
     remote_origin_problems,
+    port_listener_refusal,
     port_of,
+    port_owner,
     NO_SOURCE_REPOSITORY,
     NoSourceRepositoryWarning,
     names_repository,
@@ -316,6 +338,7 @@ from fabric_supervisors import (  # noqa: F401
     _launchctl,
     _domain,
     SYSTEM_DAEMONS,
+    USER_NAME_RULE,
     launchd_domain,
     launchd_loaded,
     launchd_pid,

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

@@ -47,6 +47,8 @@ DEFAULT_EXIT_TIMEOUT = 15
 
 _LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,250}\Z")  # what launchd and the Node twin take as a label
 _USER_NAME = re.compile(r"^[a-z_][a-z0-9_.-]{0,31}\Z")  # a macOS short name, as a LaunchDaemon's UserName takes it
+#: The short-name rule in words, printed alike by both twins (FAA-286 item 13).
+USER_NAME_RULE = "a lower-case letter or _, then up to 31 lower-case letters, digits, _, . or -"
 
 #: Where a LaunchDaemon's plist lives: a job in launchd's system domain, started at boot with no GUI login (FAA-278).
 SYSTEM_DAEMONS = Path("/Library/LaunchDaemons")
@@ -141,12 +143,40 @@ def _check(result: Any, what: str) -> None:
         raise ServiceError("%s failed: %s" % (what, (getattr(result, "stderr", "") or getattr(result, "stdout", "") or "").strip()[:200]))
 
 
+def _poll_installed(origin: str, service_id: Optional[str], instance: str, timeout: float,
+                    read: Optional[Callable[[str], Any]], sleep: Callable[[float], None], clock: Callable[[], float]) -> Any:
+    """Poll the well-known answer at `origin` until this OS account's listener answers as `service_id`.`instance`, as
+    launchd_install does (the pinned contract's Install row: every supervisor polls, FAA-253). Another account's listener,
+    or one whose owner cannot be told, is never a successful install (DEC-0154 HA-2)."""
+    if not service_id:
+        raise ServiceError("polling the install at %s needs the service_id it must answer as" % origin)
+    read = read or well_known_of
+    deadline = clock() + max(0.0, timeout)
+    while True:
+        doc = read(origin)
+        foreign = doc.reason if isinstance(doc, ForeignUserAnswer) else None
+        if not foreign and _answers(doc, service_id, instance):
+            return doc
+        if clock() >= deadline:
+            break
+        sleep(0.5)
+    if foreign:
+        raise ServiceError("%s is not this service's: %s (DEC-0154 HA-2); the port is another OS account's or its owner "
+                           "cannot be told." % (origin, foreign))
+    raise ServiceError("%s did not answer as %s.%s within %.0f s; read its log." % (origin, service_id, instance, timeout))
+
+
 def systemd_install(unit: str, text: str, *, unit_dir: Optional[Path] = None, run: Callable[..., Any] = subprocess.run,
-                    system: str = sys.platform, force_enable: bool = False) -> Path:
+                    system: str = sys.platform, force_enable: bool = False, origin: Optional[str] = None,
+                    service_id: Optional[str] = None, instance: str = "default", timeout: float = 40.0,
+                    fetch_well_known: Optional[Callable[[str], Any]] = None, sleep: Callable[[float], None] = time.sleep,
+                    clock: Callable[[], float] = time.monotonic) -> Path:
     """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 ``force_enable`` (the operator asked for it on)."""
+    the new version is what starts once they enable it — unless ``force_enable`` (the operator asked for it on).
+    With ``origin`` (and ``service_id``), it then polls the well-known answer as ``launchd_install`` does, until this
+    account's listener answers within ``timeout`` (FAA-253); ``fetch_well_known(origin)`` reads it as ``well_known_of``."""
     if not system.startswith("linux"):
         raise ServiceError("systemd is the supervisor on Linux only")
     if not _UNIT.match(unit):
@@ -163,6 +193,8 @@ def systemd_install(unit: str, text: str, *, unit_dir: Optional[Path] = None, ru
         return path
     _check(run(["systemctl", "--user", "enable", unit], capture_output=True, text=True), "systemctl --user enable")
     _check(run(["systemctl", "--user", "restart", unit], capture_output=True, text=True), "systemctl --user restart")
+    if origin is not None:
+        _poll_installed(origin, service_id, instance, timeout, fetch_well_known, sleep, clock)
     return path
 
 
@@ -227,9 +259,13 @@ _TASK_DISABLED = re.compile(r"<Settings>(?:(?!</Settings>).)*<Enabled>false</Ena
 
 
 def task_install(task: str, xml_text: str, *, run: Callable[..., Any] = subprocess.run, system: str = sys.platform,
-                 force_enable: bool = False) -> None:
+                 force_enable: bool = False, origin: Optional[str] = None, service_id: Optional[str] = None,
+                 instance: str = "default", timeout: float = 40.0, fetch_well_known: Optional[Callable[[str], Any]] = None,
+                 sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic) -> Any:
     """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 ``force_enable``."""
+    definition is what runs. A task already installed and disabled stays off (LC-14) unless ``force_enable``.
+    With ``origin`` (and ``service_id``), it then polls the well-known answer as ``launchd_install`` does and returns it
+    (FAA-253); without, it returns None as before."""
     if system != "win32":
         raise ServiceError("Task Scheduler is the supervisor on Windows only")
     query = run(["schtasks", "/Query", "/TN", task, "/XML"], capture_output=True, text=True)
@@ -248,6 +284,9 @@ def task_install(task: str, xml_text: str, *, run: Callable[..., Any] = subproce
     if existed:
         run(["schtasks", "/End", "/TN", task], capture_output=True, text=True)
     _check(run(["schtasks", "/Run", "/TN", task], capture_output=True, text=True), "schtasks /Run")
+    if origin is not None:
+        return _poll_installed(origin, service_id, instance, timeout, fetch_well_known, sleep, clock)
+    return None
 
 
 def task_uninstall(task: str, *, run: Callable[..., Any] = subprocess.run, system: str = sys.platform) -> None:
@@ -336,6 +375,9 @@ def launchd_domain(plist_path: Optional[Path] = None, domain: Optional[str] = No
     session; a ``gui/<uid>`` job starts only while its user is logged in."""
     if domain not in (None, "gui", "system"):
         raise ServiceError("domain must be gui or system")
+    if plist_path is not None and re.match(r"^(?:system|gui)(?:/[0-9]*)?\Z", str(plist_path)):
+        raise ServiceError("%s is a launchd domain, not a plist path: pass domain=%r (FAA-286)"
+                           % (plist_path, "system" if str(plist_path) == "system" else "gui"))
     if domain is None and plist_path is not None:
         folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))  # POSIX keeps a leading //
         domain = "system" if folder.lower() == str(SYSTEM_DAEMONS).lower() else "gui"  # APFS ignores case
@@ -347,6 +389,39 @@ def launchd_domain(plist_path: Optional[Path] = None, domain: Optional[str] = No
     return _domain()
 
 
+def _in_daemons(plist_path: Path) -> bool:
+    folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))
+    return folder.lower() == str(SYSTEM_DAEMONS).lower()
+
+
+def _pair_problem(plist_path: Path, domain: Optional[str]) -> Optional[str]:
+    """A domain the plist's folder contradicts (FAA-286 items 14 and 21): a system job in a LaunchAgents folder (launchd
+    also loads it into gui/<uid> at login), or a gui job in /Library/LaunchDaemons (launchd loads it at boot as root).
+    Another folder is allowed for a system job, as the tests' and a staging install's are."""
+    if domain == "system" and Path(os.path.abspath(str(plist_path))).parent.name.lower() == "launchagents":
+        return ("A LaunchDaemon's plist lives in %s: %s is in a LaunchAgents folder, which launchd also loads into "
+                "gui/<uid> at login, so the job would run twice." % (SYSTEM_DAEMONS, plist_path))
+    if domain == "gui" and _in_daemons(plist_path):
+        return ("%s is in %s, which launchd loads at boot as a LaunchDaemon: a gui/<uid> job's plist goes in "
+                "~/Library/LaunchAgents." % (plist_path, SYSTEM_DAEMONS))
+    return None
+
+
+def _leftover_agent(label: str, user_name: str) -> Optional[Path]:
+    """A LaunchAgent of ``label`` in ``user_name``'s ~/Library/LaunchAgents, which would run a second copy at its login
+    (FAA-286 item 6)."""
+    try:
+        import pwd
+        home = Path(pwd.getpwnam(user_name).pw_dir)
+    except (ImportError, KeyError, ValueError):
+        return None
+    try:
+        agents = sorted((home / "Library" / "LaunchAgents").glob("*.plist"))
+    except OSError:
+        return None
+    return next((p for p in agents if _plist_field(p, "Label") == label), None)
+
+
 def _need_root(domain: str, label: str, plist_path: Path, install: bool) -> None:
     """A system-domain job is installed and removed by root: refuse before anything is written (FAA-278)."""
     if domain != "system" or os.geteuid() == 0:
@@ -368,13 +443,16 @@ def launchd_loaded(label: str, domain: Optional[str] = None) -> bool:
     return _launchctl("print", "%s/%s" % (launchd_domain(domain=domain), label)).returncode == 0
 
 
-_PID_ROW = re.compile(r"^\s*pid\s*=\s*(\d+)\s*\Z")
+_PID_ROW = re.compile(r"^\s*pid\s*=\s*([0-9]+)\s*\Z")  # ASCII digits, as Node reads them (FAA-273)
 
 
 def launchd_pid(label: str, domain: Optional[str] = None) -> Optional[int]:
     """The running pid of this account's launchd job ``label`` (with ``domain="system"``, of the LaunchDaemon), or
     None (not running, or not readable). Reading needs no root."""
-    result = _launchctl("print", "%s/%s" % (launchd_domain(domain=domain), label))
+    try:
+        result = _launchctl("print", "%s/%s" % (launchd_domain(domain=domain), label))
+    except subprocess.TimeoutExpired:
+        return None  # a launchctl that hangs is a pid not read, never an error out of an install's poll (FAA-273)
     if result.returncode != 0:
         return None
     for line in (result.stdout or "").splitlines():
@@ -660,6 +738,9 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
     read_answer = fetch_well_known or (lambda origin_, vouch_pid=None: well_known_of(origin_, vouch_pid=vouch_pid))
     read_job = fetch_job_well_known or job_well_known_of
     plist_path = Path(plist_path)
+    pair = _pair_problem(plist_path, domain)
+    if pair:
+        raise ServiceError(pair)
     dom = launchd_domain(plist_path, domain)
     which = "system" if dom == "system" else None
     _need_root(dom, label, plist_path, True)
@@ -673,8 +754,8 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                "the job's pid and uid (FAA-278); %s is not." % origin)
         try:
             named = plistlib.loads(plist_bytes).get("UserName")
-        except Exception:  # a plist that does not parse fails plutil -lint below
-            named = None
+        except Exception as exc:  # named as what it is, never as a missing UserName (FAA-286 item 16)
+            raise ServiceError("The plist does not parse (%s): write it with launchd_plist." % type(exc).__name__)
         named = named if isinstance(named, str) else None  # a UserName that is not a string names no account
         if named:
             _refuse_held_label(label, plist_path)
@@ -691,7 +772,7 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                    "it), or uninstall that one as root first." % (plist_path, installed))
         if named and not _USER_NAME.match(named):
             raise ServiceError("UserName %s is not a macOS short name (%s): launchd takes the account's short name."
-                               % (named, _USER_NAME.pattern))
+                               % (named, USER_NAME_RULE))
         job_uid = _account_uid(named) if named else None
         if named and job_uid is None:
             raise ServiceError("UserName %s is no account of this Mac: launchd would not start the job. Name the account "
@@ -704,6 +785,12 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
             raise ServiceError("A LaunchDaemon needs UserName: without it the job runs as root, keeps its data in root's "
                                "home, and every client refuses root's listener (DEC-0154 HA-2). Write the plist with "
                                "launchd_plist(..., user_name=<the account whose Fabric and agents call it>).")
+        leftover = _leftover_agent(label, named)
+        if leftover is not None:
+            raise ServiceError("%s is a LaunchAgent of label %s: it would start a second copy at %s's login beside this "
+                               "LaunchDaemon. Remove it first (launchd_uninstall as %s; lifecycle reference, The system "
+                               "domain)." % (leftover, label, named, named))
+    existed = plist_path.exists()
     atomic_write(plist_path, plist_bytes, 0o644)
     lint = subprocess.run(["plutil", "-lint", str(plist_path)], capture_output=True, text=True)
     if lint.returncode != 0:
@@ -731,6 +818,16 @@ def launchd_install(label: str, plist_path: Path, plist_bytes: bytes, *, origin:
                                "headless Mac after a FileVault restart), so %s does not run jobs: remove the LaunchAgent "
                                "this attempt wrote (launchd_uninstall), then install it as a LaunchDaemon in the system "
                                "domain (a plist in %s with UserName, as root; FAA-278)." % (last, dom, SYSTEM_DAEMONS))
+        if dom == "system":
+            # a plist left in /Library/LaunchDaemons loads at the next boot (FAA-286 item 15): one this call wrote goes
+            if not existed:
+                try:
+                    plist_path.unlink()
+                except OSError:
+                    pass
+            raise ServiceError("launchctl bootstrap failed: %s; %s" % (last, "the plist this call wrote was removed"
+                               if not plist_path.exists() else "%s stays and loads at the next boot: remove it as root"
+                               % plist_path))
         raise ServiceError("launchctl bootstrap failed: %s" % last)
     deadline = time.time() + timeout
     if dom == "system":
@@ -794,6 +891,10 @@ def launchd_uninstall(label: str, plist_path: Path, *, timeout: float = 30.0, pu
                            "remove the data as that user.")
     if dom == "system":
         _refuse_held_label(label, Path(plist_path))  # a bootout would stop another plist's job (FAA-278)
+    holds = _plist_field(Path(plist_path), "Label") if Path(plist_path).exists() else None
+    if holds is not None and holds != label:  # FAA-286 item 9: booting out one job and unlinking another's plist
+        raise ServiceError("%s holds launchd label %s, not %s: nothing was removed. Name the plist of %s, or uninstall %s "
+                           "with its own label." % (plist_path, holds, label, label, holds))
     dirs = instance_dirs(str(service_id), instance) if purge else {}
     target = "%s/%s" % (dom, label)
     _launchctl("bootout", target)

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

@@ -137,7 +137,7 @@ def _by_project(receipts: List[Dict[str, Any]], first: str, last: str) -> List[D
     out = []
     for key in sorted(projects):
         row = projects[key]
-        runs = [_close_totals(run) for _, run in sorted(row.pop("_runs").items())]
+        runs = [_close_run(run) for _, run in sorted(row.pop("_runs").items())]
         row = _close_totals(row)
         if runs:
             row["taskRuns"] = runs
@@ -167,6 +167,17 @@ def _round_usd(value: float) -> float:
     return whole / 1e6
 
 
+def _close_run(run: Dict[str, Any]) -> Dict[str, Any]:
+    """A task run's totals, its cost rounded as `_round_usd` rounds but never above the exact cost: each run and its
+    project round apart, so many runs rounding up summed past the project and failed FAC-SEM-025 (board request
+    f5753c5a). Rounded this way the runs' sum stays within the project's rounded cost by construction."""
+    exact = run["_cost"]
+    run = _close_totals(run)
+    if run["costUsd"] is not None and run["costUsd"] > exact:
+        run["costUsd"] = _round_usd(run["costUsd"] - 0.000001)
+    return run
+
+
 def _close_totals(row: Dict[str, Any]) -> Dict[str, Any]:
     cost = row.pop("_cost")
     row["costUsd"] = None if row["calls"] and row["unpricedCalls"] == row["calls"] else _round_usd(cost)