@runuai/host 0.9.149 → 0.9.151

package/lib/credential-consumers/engine-anchor.ts

@@ -0,0 +1,1876 @@
+/**
+ * ADR-154 §6: every process a leased engine starts from is admitted by the
+ * runner where it really starts, and everything it leads to stays owned
+ * until a cleanup has killed it.
+ *
+ * - The gate. Before the runner hands a launch to a provider, it writes a
+ *   single-use admission into the runtime, as root, under a root-only
+ *   directory (`/run/uai/engine-gates/<task>/<run>/<account>/admit-<token>`,
+ *   the launch's revision and version in it, and the runtime instance it
+ *   was written in: a stopped container's next start, or a machine's next
+ *   boot, admits nothing written before). The provider starts the
+ *   launch as root through the supervisor, which admits it by consuming
+ *   that token. A cleanup closes the runner's admission first (no new
+ *   token is written for the accounts it takes), waits for the writes
+ *   under way, then revokes every token left for its runs and accounts and
+ *   reads them back gone. So a launch handed over before a cleanup that
+ *   starts after it (a machine still looking up its address, a durable
+ *   runner still being deployed) finds no token and never starts. A token
+ *   is never reused, so a write that lands late admits nothing.
+ * - The floor. An account's admissions are also held to the newest version
+ *   the runner has moved it to (`floor-<revision hash>`, monotonic): before
+ *   a newer version of an account is served, the runner raises the floor
+ *   in every running runtime of the task (`raiseEngineAdmissionFloors`; a
+ *   stopped one's admissions end with its instance). A launch admitted on
+ *   the older version that has not started by then never does.
+ * - The slot. An agent's launches are admitted for its spawn's slot (the
+ *   slot's id in each admission). When the runner retires a slot (the agent
+ *   removed, changed or started again, its session ended), it marks the
+ *   slot retired in the runtime (`retired-<slot>`, under the task's lock,
+ *   `retireEngineLaunchSlot`): every admission of that slot not yet used is
+ *   revoked, with what it carried, and none of its own is written or used
+ *   after. So a launch handed to its provider just before the retirement,
+ *   and not yet started there, never starts with the agent's old task token,
+ *   however late it gets there.
+ * - The subjects. An admission is for an AI account's exact material, or
+ *   for an agent's task token alone (the Managed Engine, ADR-128, which
+ *   runs on Uai's gateway with that token as its bearer). Each has its own
+ *   namespace in the runtime: an account's admissions are under its id's
+ *   segment, which never starts with "_" (`idPathSegment`); every task-token
+ *   admission is under `TASK_TOKEN_SEGMENT`. A cleanup of named accounts
+ *   never reaches a task-token admission; a whole run's reaches both.
+ * - The anchor. The supervisor the provider starts (the launcher, W) forks
+ *   the anchor (R), a child subreaper named `uai-anchor`, before anything is
+ *   admitted. R takes the task's gate lock, consumes the token, writes its
+ *   receipt (`live-<token>`: its pid, its start time and the runtime
+ *   instance it runs in), forks the engine (C), which drops to the task
+ *   user (groups, gid, uid; the capabilities go with root), and releases
+ *   the lock: a cleanup, which revokes under the same lock, either finds
+ *   the token gone and the receipt written, or revokes it before R looks.
+ *   Everything C starts, double-forked, setsid or with its environment
+ *   cleared, as the task user or as root through sudo, reparents to R,
+ *   never to PID 1. R tells W how C ended and W ends the same way, so turns
+ *   and sessions end as before; R reaps until it has no child left, and
+ *   only then, under the lock, removes its receipt and exits: what an
+ *   engine leaves running keeps running, owned. A removed receipt is the
+ *   kernel's word (no child left) that nothing R owned still runs.
+ * - The cleanup (`stopAnchoredEngines`), as root: revoke, then, for every
+ *   receipt of its runs and accounts, kill everything under R, over and
+ *   over, until R ends on its own. The cleanup never kills R: when R has
+ *   ended, its receipt says how. Gone, R proved its subtree empty. Still
+ *   there, R died with things it owned possibly reparented away: the anchor
+ *   is lost, absence is never proof, and the runtime must be stopped
+ *   (`EngineAnchorLost`). The receipt stays as the witness until that
+ *   runtime instance is gone (a stopped container's next start, a machine's
+ *   next boot): every cleanup until then fails the same way. An R still
+ *   there at the bound (stopped, wedged), or anything else the cleanup
+ *   killed that will not end, is lost the same way: stopping the runtime is
+ *   the one proof left, where retrying would wait on it forever.
+ * - Whose they are. Gates, floors, receipts and anchors are root's: the
+ *   task user can neither forge an admission nor kill an anchor. Inside its
+ *   runtime the task user can become root (the task image's sudo), so none
+ *   of this holds against task code that sets out to defeat it; such code
+ *   already holds the credential it was given (ADR-154 §Limits). It
+ *   contains the runner's own launches and everything engines start in
+ *   ordinary use.
+ * - A runtime that cannot run it (no Python 3.9, no pidfds, no subreaper)
+ *   refuses the launch: a leased engine stays down rather than run unowned.
+ */
+
+import { randomBytes } from "node:crypto";
+
+import { idPathSegment } from "../../src/cloud-credentials";
+import { LAUNCH_SECRET_ENV_NAMES, isLaunchSecretEnvName } from "../engine-credential-env";
+import type {
+  TaskEnvironmentAnchor,
+  TaskEnvironmentExecResult,
+  TaskEnvironmentHandle,
+  TaskEnvironmentProcess,
+} from "../task-environment/types";
+
+/** The anchor's process name (comm), how a cleanup knows it. */
+export const ENGINE_ANCHOR_NAME = "uai-anchor";
+/** The launcher's process name. */
+export const ENGINE_LAUNCH_NAME = "uai-launch";
+/** Where a runtime's engine gates live, root's alone. */
+export const ENGINE_GATE_ROOT = "/run/uai/engine-gates";
+/** The run marker every process of a leased engine inherits from its spawn. */
+export const ENGINE_RUN_ENV = "UAI_ENGINE_RUN";
+/** The account marker every process of a leased engine inherits: the
+ *  credential it runs on. */
+export const ENGINE_ACCOUNT_ENV = "UAI_ENGINE_ACCOUNT";
+
+/** Where a launch's carried engine credentials wait when the gate area is
+ *  not held in memory (ADR-154 §6: a tmpfs, or nowhere). */
+export const ENGINE_CARRIER_FALLBACK_ROOT = "/dev/shm/uai-engine-gates";
+
+let gateRoot = ENGINE_GATE_ROOT;
+let carrierFallbackRoot = ENGINE_CARRIER_FALLBACK_ROOT;
+
+/** The areas a carried credential may wait in, in the order tried. */
+function carrierRoots(): string {
+  return [gateRoot, carrierFallbackRoot].join("\n");
+}
+
+/** Where every task-token admission is, in a namespace of its own: no
+ *  account's segment starts with "_" (`idPathSegment`). */
+export const TASK_TOKEN_SEGMENT = "_task-token";
+/** A task-token admission's revision: it has no account material, and no
+ *  floor is ever raised for it. */
+const TASK_TOKEN_REVISION = "task-token";
+
+/** What a launch is admitted for (ADR-154 §6): an AI account's exact
+ *  material, or an agent's task token alone (the Managed Engine). */
+export type EngineLaunchSubject =
+  | { subject: "account"; credentialId: string; revision: string; version: number }
+  | { subject: "task-token" };
+
+/** What a launch is admitted as: the task's run, its subject, and the
+ *  agent's launch slot it belongs to (`newEngineLaunchSlotId`; null for a
+ *  one-shot that belongs to no agent's spawn). */
+export type EngineLaunchIdentity = { taskId: string; runEpoch: number; slotId: string | null } & EngineLaunchSubject;
+
+/** A new launch slot's id: one per spawn, never reused. */
+export function newEngineLaunchSlotId(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/** The segment, revision and version an admission is written under, and
+ *  its slot ("-": none). */
+function gateSegment(subject: EngineLaunchSubject): string {
+  return subject.subject === "account" ? idPathSegment(subject.credentialId) : TASK_TOKEN_SEGMENT;
+}
+
+function gateRevision(subject: EngineLaunchSubject): string {
+  return subject.subject === "account" ? subject.revision : TASK_TOKEN_REVISION;
+}
+
+function gateVersion(subject: EngineLaunchSubject): string {
+  return subject.subject === "account" ? String(subject.version) : "0";
+}
+
+function gateSlot(identity: EngineLaunchIdentity): string {
+  return identity.slotId ?? "-";
+}
+
+/** The newest version of an account's revision a launch may start on. */
+export interface EngineAdmissionFloor {
+  credentialId: string;
+  revision: string;
+  version: number;
+}
+
+/** The launch was not admitted: it starts nothing. */
+export class EngineLaunchRefused extends Error {
+  constructor(message = "this AI account may not start an engine now") {
+    super(message);
+    this.name = "EngineLaunchRefused";
+  }
+}
+
+/** An anchor ended without proving its subtree empty, or the runtime's gate
+ *  area is not the runner's: only stopping the runtime proves its engines
+ *  gone. */
+export class EngineAnchorLost extends Error {
+  constructor() {
+    super("an engine supervisor in the task runtime was lost; only stopping the runtime proves its engines gone");
+    this.name = "EngineAnchorLost";
+  }
+}
+
+/**
+ * Shared by the helpers: the gate area, every directory to the task's
+ * opened without following a link, those above the root root's or this
+ * user's and letting nobody else rename what is in them, the root and below
+ * this user's alone; the task's lock; an account's floor; the runtime
+ * instance (the kernel's boot and its PID 1's start: a stopped container's
+ * next start, or a machine's next boot, is another instance, with none of
+ * the last one's processes).
+ */
+const GATE_PRELUDE_BASE = String.raw`
+import errno
+import fcntl
+import hashlib
+import os
+import re
+import stat
+import sys
+import time
+
+SEGMENT = re.compile(r"[A-Za-z0-9_-]{1,128}\Z")
+TOKEN = re.compile(r"[0-9a-f]{32}\Z")
+NUMBER = re.compile(r"(?:0|[1-9][0-9]{0,15})\Z")
+DIRECTORY = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+ME = os.geteuid()
+
+
+class Refused(Exception):
+    pass
+
+
+def revision_ok(revision):
+    return 0 < len(revision) <= 512 and "\n" not in revision and "\t" not in revision
+
+
+def checked(fd, kind):
+    st = os.fstat(fd)
+    if not kind(st.st_mode) or st.st_uid != ME or st.st_mode & 0o077:
+        raise Refused("not this user's alone")
+    return st
+
+
+def private(parent, name, create):
+    if create:
+        try:
+            os.mkdir(name, 0o700, dir_fd=parent)
+        except FileExistsError:
+            pass
+    fd = os.open(name, DIRECTORY, dir_fd=parent)
+    try:
+        checked(fd, stat.S_ISDIR)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def guarded(fd):
+    st = os.fstat(fd)
+    if st.st_uid not in (0, ME) or (st.st_mode & 0o022 and not st.st_mode & stat.S_ISVTX):
+        raise Refused("an unsafe directory above the gates")
+
+
+def task_directory(root, task, create):
+    parts = root.split("/")[1:]
+    if not root.startswith("/") or not SEGMENT.match(task) or any(part in ("", ".", "..") for part in parts):
+        raise Refused("a malformed gate root")
+    fd = os.open("/", DIRECTORY)
+    try:
+        for part in parts[:-1]:
+            guarded(fd)
+            if create:
+                try:
+                    os.mkdir(part, 0o755, dir_fd=fd)
+                except FileExistsError:
+                    pass
+            child = os.open(part, DIRECTORY, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        guarded(fd)
+        gates = private(fd, parts[-1], create)
+    finally:
+        os.close(fd)
+    try:
+        return private(gates, task, create)
+    finally:
+        os.close(gates)
+
+
+def locked(directory):
+    fd = os.open(".lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600, dir_fd=directory)
+    try:
+        if checked(fd, stat.S_ISREG).st_nlink != 1:
+            raise Refused("a linked lock")
+        fcntl.flock(fd, fcntl.LOCK_EX)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def descend(directory, names, create):
+    try:
+        for name in names:
+            child = private(directory, name, create)
+            os.close(directory)
+            directory = child
+    except BaseException:
+        os.close(directory)
+        raise
+    return directory
+
+
+def read_private(directory, name):
+    fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_CLOEXEC, dir_fd=directory)
+    try:
+        if checked(fd, stat.S_ISREG).st_nlink != 1:
+            raise Refused("a linked gate file")
+        return os.read(fd, 4096)
+    finally:
+        os.close(fd)
+
+
+def write_private(directory, name, content):
+    fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600, dir_fd=directory)
+    try:
+        if os.write(fd, content) != len(content):
+            raise Refused("a short write")
+    except BaseException:
+        os.close(fd)
+        os.unlink(name, dir_fd=directory)
+        raise
+    os.close(fd)
+
+
+def floor_name(revision):
+    return "floor-" + hashlib.sha256(revision.encode()).hexdigest()[:40]
+
+
+def floor_of(directory, revision):
+    try:
+        held = read_private(directory, floor_name(revision))
+    except FileNotFoundError:
+        return 0
+    if not NUMBER.match(held.decode().strip()):
+        raise Refused("a malformed floor")
+    return int(held)
+
+
+RETIRED = "retired-"
+
+
+def slot_ok(slot):
+    return slot == "-" or TOKEN.match(slot) is not None
+
+
+def retired(directory, slot):
+    if slot == "-":
+        return False
+    try:
+        os.stat(RETIRED + slot, dir_fd=directory, follow_symlinks=False)
+    except FileNotFoundError:
+        return False
+    return True
+
+
+BOOT_ID = "/proc/sys/kernel/random/boot_id"
+INIT_STAT = "/proc/1/stat"
+
+
+def instance():
+    with open(BOOT_ID, "rb") as source:
+        boot = source.read().strip()
+    with open(INIT_STAT, "rb") as source:
+        data = source.read()
+    return boot + b":" + data[data.rindex(b")") + 2:].split()[19]
+
+
+TMPFS_MAGIC = 0x01021994
+SECRET = "secret-"
+SECRET_SECONDS = 120
+SECRET_BYTES = 65536
+VALUE_BYTES = 8192
+CARRIER_FD = 9
+
+
+def tmpfs(fd):
+    import ctypes
+
+    found = ctypes.create_string_buffer(512)
+    if ctypes.CDLL(None, use_errno=True).fstatfs(fd, found) != 0:
+        raise OSError(ctypes.get_errno(), "fstatfs")
+    return ctypes.c_long.from_buffer(found).value == TMPFS_MAGIC
+
+
+def carried(data):
+    import json
+
+    if len(data) > SECRET_BYTES:
+        raise Refused("an oversized carried credential")
+    values = json.loads(data.decode("utf-8"))
+    if not isinstance(values, dict) or not values:
+        raise Refused("a malformed carried credential")
+    for name, value in values.items():
+        if (
+            name not in CARRIED
+            or not isinstance(value, str)
+            or not value
+            or "\0" in value
+            or len(value.encode("utf-8")) > VALUE_BYTES
+        ):
+            raise Refused("a malformed carried credential")
+    return values
+
+
+def account_area(root, task, run, account, create):
+    return descend(task_directory(root, task, create), (run, account), create)
+
+
+def drop_secret(roots, task, run, account, token):
+    for root in roots:
+        try:
+            area = account_area(root, task, run, account, False)
+        except FileNotFoundError:
+            continue
+        try:
+            os.unlink(SECRET + token, dir_fd=area)
+        except FileNotFoundError:
+            pass
+        finally:
+            os.close(area)
+
+
+def inject(fd):
+    data = b""
+    while len(data) <= SECRET_BYTES:
+        chunk = os.read(fd, 65536)
+        if not chunk:
+            break
+        data += chunk
+    os.close(fd)
+    for name, value in carried(data).items():
+        os.environ[name] = value
+`;
+
+/**
+ * Shared by the helpers, with the prelude above: what a launch's carried
+ * engine credentials may be (ADR-154 §6). They wait in memory only (a
+ * tmpfs), each in a file of its own beside its admission, root's alone,
+ * for two minutes at most; a cleanup, a revocation or a floor removes one
+ * without ever reading it.
+ */
+const GATE_PRELUDE =
+  GATE_PRELUDE_BASE +
+  `
+CARRIED = frozenset(${JSON.stringify([...LAUNCH_SECRET_ENV_NAMES].sort())})
+`;
+
+/**
+ * Writes one admission, as root. argv: gate root, task, run, account
+ * segment, token, revision, version, slot ("-": none), the areas a carried
+ * credential may wait in (one per line, in order), and "carry" when the
+ * launch carries engine credentials (as JSON on stdin) or "-". A carried
+ * credential is written first, into the first of those areas held in memory
+ * (a tmpfs), and the admission names where it is. Prints that area, or "-".
+ * Every carried credential of the task past its bound goes first, unread.
+ * Exits 2 on malformed arguments or a malformed carried credential, 4 when
+ * the gate area is not the runner's, the version is below the account's
+ * floor, the slot is retired, no area is held in memory, or a write fails.
+ */
+export const ENGINE_GATE_WRITE_HELPER =
+  GATE_PRELUDE +
+  String.raw`
+root, task, run, account, token, revision, version, slot, carriers, carry = sys.argv[1:11]
+roots = [candidate for candidate in carriers.split("\n") if candidate]
+if not (
+    NUMBER.match(run)
+    and SEGMENT.match(account)
+    and TOKEN.match(token)
+    and NUMBER.match(version)
+    and revision_ok(revision)
+    and slot_ok(slot)
+):
+    sys.exit(2)
+if carry not in ("carry", "-") or not roots:
+    sys.exit(2)
+payload = None
+if carry == "carry":
+    try:
+        payload = sys.stdin.buffer.read(SECRET_BYTES + 1)
+        carried(payload)
+    except (Refused, ValueError, UnicodeDecodeError):
+        sys.exit(2)
+
+
+def stale(directory, name):
+    try:
+        return time.time() - os.stat(name, dir_fd=directory, follow_symlinks=False).st_mtime > SECRET_SECONDS
+    except FileNotFoundError:
+        return False
+
+
+def expire():
+    # Past its bound, a carried credential goes, and so does the admission
+    # that named one: neither is ever read for its value.
+    for area_root in [root] + [candidate for candidate in roots if candidate != root]:
+        try:
+            directory = task_directory(area_root, task, False)
+        except FileNotFoundError:
+            continue
+        try:
+            for run_name in os.listdir(directory):
+                if not NUMBER.match(run_name):
+                    continue
+                run_directory = private(directory, run_name, False)
+                try:
+                    for account_name in os.listdir(run_directory):
+                        if not SEGMENT.match(account_name):
+                            continue
+                        area = private(run_directory, account_name, False)
+                        try:
+                            for name in os.listdir(area):
+                                if name.startswith(SECRET) and stale(area, name):
+                                    os.unlink(name, dir_fd=area)
+                                elif name.startswith("admit-") and area_root == root and stale(area, name):
+                                    held = read_private(area, name).split(b"\n")
+                                    if len(held) > 3 and held[3] != b"-":
+                                        os.unlink(name, dir_fd=area)
+                                        drop_secret(roots, task, run_name, account_name, name[len("admit-"):])
+                        finally:
+                            os.close(area)
+                finally:
+                    os.close(run_directory)
+        finally:
+            os.close(directory)
+
+
+def hold(payload):
+    for candidate in roots:
+        area = account_area(candidate, task, run, account, True)
+        try:
+            if not tmpfs(area):
+                continue
+            write_private(area, SECRET + token, payload)
+            return candidate
+        finally:
+            os.close(area)
+    raise Refused("no area held in memory for an engine's credentials")
+
+
+held_at = "-"
+try:
+    directory = task_directory(root, task, True)
+    lock = locked(directory)
+    expire()
+    directory = descend(directory, (run, account), True)
+    if int(version) < floor_of(directory, revision):
+        raise Refused("an older version")
+    if retired(directory, slot):
+        raise Refused("a retired launch slot")
+    if payload is not None:
+        held_at = hold(payload)
+    try:
+        write_private(
+            directory,
+            "admit-" + token,
+            (revision + "\n" + version + "\n").encode()
+            + instance()
+            + b"\n"
+            + held_at.encode()
+            + b"\n"
+            + slot.encode()
+            + b"\n",
+        )
+    except BaseException:
+        if held_at != "-":
+            drop_secret([held_at], task, run, account, token)
+        raise
+except (OSError, Refused, ValueError):
+    sys.exit(4)
+os.write(1, held_at.encode() + b"\n")
+`;
+
+/**
+ * Raises accounts' floors, as root, and revokes their admissions below
+ * them, with what they carried, unread. argv: gate root, task, run, the
+ * floors (one per line: account segment, revision, version,
+ * tab-separated), the areas a carried credential may wait in (one per
+ * line). A floor only ever rises. Exits 2 on malformed arguments, 4 when
+ * the gate area is not the runner's or a write fails.
+ */
+export const ENGINE_GATE_FLOOR_HELPER =
+  GATE_PRELUDE +
+  String.raw`
+root, task, run, wanted, carriers = sys.argv[1:6]
+roots = [candidate for candidate in carriers.split("\n") if candidate]
+floors = []
+for line in wanted.split("\n"):
+    if not line:
+        continue
+    parts = line.split("\t")
+    if len(parts) != 3 or not SEGMENT.match(parts[0]) or not revision_ok(parts[1]) or not NUMBER.match(parts[2]):
+        sys.exit(2)
+    floors.append(parts)
+if not NUMBER.match(run) or not floors:
+    sys.exit(2)
+try:
+    directory = task_directory(root, task, True)
+    lock = locked(directory)
+    for account, revision, version in floors:
+        account_directory = descend(os.dup(directory), (run, account), True)
+        try:
+            name = floor_name(revision)
+            if int(version) > floor_of(account_directory, revision):
+                staged = name + ".next"
+                try:
+                    os.unlink(staged, dir_fd=account_directory)
+                except FileNotFoundError:
+                    pass
+                write_private(account_directory, staged, version.encode() + b"\n")
+                os.rename(staged, name, src_dir_fd=account_directory, dst_dir_fd=account_directory)
+            floor = floor_of(account_directory, revision)
+            for entry in os.listdir(account_directory):
+                if not entry.startswith("admit-"):
+                    continue
+                held = read_private(account_directory, entry).decode().split("\n")
+                if len(held) < 2 or (held[0] == revision and NUMBER.match(held[1]) and int(held[1]) < floor):
+                    os.unlink(entry, dir_fd=account_directory)
+                    drop_secret(roots, task, run, account, entry[len("admit-"):])
+        finally:
+            os.close(account_directory)
+except (OSError, Refused, ValueError, UnicodeDecodeError):
+    sys.exit(4)
+`;
+
+/**
+ * The supervisor. argv: gate root, task, run, account segment, token,
+ * revision, version, slot ("-": none), the area its carried credentials
+ * wait in ("-": none), the user the engine drops to ("-": the provider drops
+ * it itself), "--", the engine's argv. The anchor opens what the launch
+ * carries and removes it from its area, but never reads it, and closes it
+ * right after it forks the engine; the engine reads it once it has dropped
+ * to the task user (or, when the provider drops it, hands it on as fd 9 to
+ * the injector the provider runs right after its drop).
+ */
+export const ENGINE_ANCHOR_SHIM =
+  GATE_PRELUDE +
+  String.raw`
+import ctypes
+import signal
+
+
+def refuse(message):
+    try:
+        os.write(2, b"uai: " + message.encode() + b"\n")
+    finally:
+        os._exit(126)
+
+
+arguments = sys.argv[1:]
+if len(arguments) < 12 or arguments[10] != "--":
+    refuse("a malformed engine launch")
+root, task, run, account, token, revision, version, slot, held_at, user = arguments[:10]
+argv = arguments[11:]
+if not (
+    NUMBER.match(run)
+    and SEGMENT.match(account)
+    and TOKEN.match(token)
+    and NUMBER.match(version)
+    and revision_ok(revision)
+    and slot_ok(slot)
+    and (held_at == "-" or held_at.startswith("/"))
+):
+    refuse("a malformed engine launch")
+
+
+def claim(area_root):
+    # The carried credential's file, open, and gone from its area. Never
+    # read here.
+    area = account_area(area_root, task, run, account, False)
+    try:
+        fd = os.open(SECRET + token, os.O_RDONLY | os.O_NOFOLLOW | os.O_CLOEXEC, dir_fd=area)
+        try:
+            st = checked(fd, stat.S_ISREG)
+            single = st.st_nlink == 1
+            os.unlink(SECRET + token, dir_fd=area)
+            if not single or time.time() - st.st_mtime > SECRET_SECONDS or not tmpfs(fd):
+                raise Refused("a carried credential not held as it was written")
+        except BaseException:
+            os.close(fd)
+            raise
+        return fd
+    finally:
+        os.close(area)
+if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
+    refuse("this runtime cannot supervise an engine")
+libc = ctypes.CDLL(None, use_errno=True)
+STOPS = (signal.SIGTERM, signal.SIGINT, signal.SIGHUP, signal.SIGQUIT)
+pending = []
+engine = None
+
+
+def forward(signum, frame):
+    if engine is None:
+        pending.append(signum)
+        return
+    if engine is False:
+        return
+    try:
+        signal.pidfd_send_signal(engine, signum)
+    except ProcessLookupError:
+        pass
+
+
+for signum in STOPS:
+    signal.signal(signum, forward)
+libc.prctl(15, b"uai-launch", 0, 0, 0)
+reader, writer = os.pipe()
+anchor = os.fork()
+if anchor == 0:
+    # R: the anchor, owning everything the engine starts before it admits.
+    os.close(reader)
+    for signum in STOPS + (signal.SIGPIPE,):
+        signal.signal(signum, signal.SIG_IGN)
+    if libc.prctl(36, 1, 0, 0, 0) != 0 or libc.prctl(15, b"uai-anchor", 0, 0, 0) != 0:
+        refuse("this runtime cannot supervise an engine")
+    try:
+        with open("/proc/self/oom_score_adj", "rb") as source:
+            score = source.read().strip()
+    except OSError:
+        score = None
+    try:
+        with open("/proc/self/oom_score_adj", "wb") as sink:
+            sink.write(b"-1000")
+    except OSError:
+        pass
+    receipt = "live-" + token
+    secret = None
+    try:
+        directory = task_directory(root, task, False)
+        lock = locked(directory)
+        directory = descend(directory, (run, account), False)
+        gate = "admit-" + token
+        held = read_private(directory, gate)
+        if held != (
+            (revision + "\n" + version + "\n").encode()
+            + instance()
+            + b"\n"
+            + held_at.encode()
+            + b"\n"
+            + slot.encode()
+            + b"\n"
+        ):
+            raise Refused("another launch's gate, or another runtime instance's")
+        if int(version) < floor_of(directory, revision):
+            raise Refused("an older version")
+        if retired(directory, slot):
+            raise Refused("a retired launch slot")
+        os.unlink(gate, dir_fd=directory)
+        if held_at != "-":
+            secret = claim(held_at)
+        with open("/proc/self/stat", "rb") as source:
+            line = source.read()
+        started = line[line.rindex(b")") + 2:].split()[19]
+        write_private(directory, receipt, b"%d %s %s\n" % (os.getpid(), started, instance()))
+    except (OSError, Refused, ValueError):
+        if held_at != "-":
+            try:
+                drop_secret([held_at], task, run, account, token)
+            except (OSError, Refused):
+                pass
+        refuse("this AI account may not start an engine now")
+    engine = os.fork()
+    if engine == 0:
+        # C: the engine, as the task user.
+        try:
+            os.close(writer)
+            os.close(lock)
+            os.close(directory)
+            for signum in STOPS + (signal.SIGPIPE,):
+                signal.signal(signum, signal.SIG_DFL)
+            if score is not None:
+                try:
+                    with open("/proc/self/oom_score_adj", "wb") as sink:
+                        sink.write(score)
+                except OSError:
+                    pass
+            if user != "-":
+                import pwd
+
+                entry = pwd.getpwnam(user)
+                superuser = pwd.getpwuid(0)
+                os.initgroups(entry.pw_name, entry.pw_gid)
+                os.setresgid(entry.pw_gid, entry.pw_gid, entry.pw_gid)
+                os.setresuid(entry.pw_uid, entry.pw_uid, entry.pw_uid)
+                if entry.pw_uid != 0:
+                    try:
+                        os.setuid(0)
+                    except PermissionError:
+                        pass
+                    else:
+                        os._exit(126)
+                if os.environ.get("HOME", superuser.pw_dir) == superuser.pw_dir:
+                    os.environ["HOME"] = entry.pw_dir
+                for name, theirs, ours in (
+                    ("USER", superuser.pw_name, entry.pw_name),
+                    ("LOGNAME", superuser.pw_name, entry.pw_name),
+                    ("SHELL", superuser.pw_shell, entry.pw_shell),
+                    ("MAIL", "/var/mail/" + superuser.pw_name, "/var/mail/" + entry.pw_name),
+                ):
+                    if os.environ.get(name) == theirs:
+                        os.environ[name] = ours
+                if os.environ.get("XDG_RUNTIME_DIR") == "/run/user/0":
+                    mine = "/run/user/%d" % entry.pw_uid
+                    if os.path.isdir(mine):
+                        os.environ["XDG_RUNTIME_DIR"] = mine
+                    else:
+                        del os.environ["XDG_RUNTIME_DIR"]
+            if secret is not None:
+                if user != "-":
+                    # Dropped: the engine's own credentials, read now.
+                    inject(secret)
+                elif secret == CARRIER_FD:
+                    os.set_inheritable(secret, True)
+                else:
+                    os.dup2(secret, CARRIER_FD)
+                    os.close(secret)
+        except BaseException:
+            os._exit(126)
+        try:
+            os.execvp(argv[0], argv)
+        except BaseException:
+            os._exit(127)
+    if secret is not None:
+        os.close(secret)
+    fcntl.flock(lock, fcntl.LOCK_UN)
+    try:
+        os.write(writer, b"%d\n" % engine)
+    except OSError:
+        pass
+    null = os.open(os.devnull, os.O_RDWR)
+    for stream in (0, 1, 2):
+        os.dup2(null, stream)
+    os.close(null)
+    reported = False
+    while True:
+        try:
+            pid, status = os.wait()
+        except ChildProcessError:
+            break
+        if pid == engine and not reported:
+            reported = True
+            try:
+                os.write(writer, b"%d\n" % status)
+                os.close(writer)
+            except OSError:
+                pass
+    # No child left: nothing it owned still runs. The receipt goes, under
+    # the lock, as the word of it.
+    fcntl.flock(lock, fcntl.LOCK_EX)
+    try:
+        os.unlink(receipt, dir_fd=directory)
+    except OSError:
+        pass
+    os._exit(0)
+
+# W: the launcher, standing for the engine to whoever started it.
+os.close(writer)
+received = b""
+
+
+def line():
+    global received
+    while b"\n" not in received:
+        chunk = os.read(reader, 64)
+        if not chunk:
+            return None
+        received += chunk
+    value, _, received = received.partition(b"\n")
+    return int(value)
+
+
+child = line()
+if child is None:
+    os._exit(126)
+try:
+    handle = os.pidfd_open(child)
+    with open("/proc/%d/stat" % child, "rb") as source:
+        data = source.read()
+    if int(data[data.rindex(b")") + 2:].split()[1]) != anchor:
+        os.close(handle)
+        handle = False
+except OSError:
+    handle = False
+engine = handle
+for signum in pending:
+    forward(signum, None)
+status = line()
+if status is None:
+    os._exit(126)
+if os.WIFSIGNALED(status):
+    signum = os.WTERMSIG(status)
+    try:
+        signal.signal(signum, signal.SIG_DFL)
+    except (OSError, ValueError):
+        pass
+    signal.pthread_sigmask(signal.SIG_UNBLOCK, [signum])
+    os.kill(os.getpid(), signum)
+    os._exit(128 + signum)
+os._exit(os.WEXITSTATUS(status))
+`;
+
+/**
+ * The cleanup, as root. argv: gate root, task, run (this and older),
+ * "named" or "all", the account segments (named; one per line), the bound
+ * in seconds, the areas a carried credential may wait in (one per line):
+ * every carried credential of what it takes goes with its admission,
+ * unread. "all" takes every subject's, a task token's included, and once
+ * everything is proven gone, the runs' floors and retired slots with them.
+ * Exits 0 when every selected anchor ended having proved its
+ * subtree empty and nothing it was admitted for remains; 5 when something
+ * must be killed on a kernel or Python without pidfds; 6 when an anchor of
+ * this runtime instance ended without proving its subtree empty (its
+ * receipt is kept: every cleanup fails so until the instance is gone), or
+ * when anything selected (an anchor that cannot reap, stopped or wedged, a
+ * process that will not die) is still there at the bound: only stopping the
+ * runtime proves it gone; 7 when the gate area is not the runner's.
+ */
+export const ENGINE_ANCHOR_STOP_HELPER =
+  GATE_PRELUDE +
+  String.raw`
+import select
+import signal
+import time
+
+root, task, through, mode, wanted, seconds, carriers = sys.argv[1:8]
+through = int(through)
+roots = [candidate for candidate in carriers.split("\n") if candidate]
+accounts = set(name for name in wanted.split("\n") if name)
+deadline = time.monotonic() + float(seconds)
+ANCHOR = b"uai-anchor"
+LAUNCH = b"uai-launch"
+
+
+def selected(run, account):
+    return (
+        NUMBER.match(run) is not None
+        and int(run) <= through
+        and SEGMENT.match(account) is not None
+        and (mode == "all" or account in accounts)
+    )
+
+
+def described(pid):
+    try:
+        with open("/proc/%d/stat" % pid, "rb") as source:
+            data = source.read()
+        owner = os.stat("/proc/%d" % pid).st_uid
+    except (FileNotFoundError, ProcessLookupError):
+        return None
+    fields = data[data.rindex(b")") + 2:].split()
+    return data[data.index(b"(") + 1:data.rindex(b")")], fields[0], int(fields[1]), int(fields[19]), owner
+
+
+def table():
+    processes = {}
+    for entry in os.listdir("/proc"):
+        if entry.isdigit():
+            process = described(int(entry))
+            if process is not None:
+                processes[int(entry)] = process
+    return processes
+
+
+def under(processes, ancestor):
+    children = {}
+    for pid, process in processes.items():
+        children.setdefault(process[2], []).append(pid)
+    found = []
+    stack = list(children.get(ancestor, ()))
+    while stack:
+        pid = stack.pop()
+        stack.extend(children.get(pid, ()))
+        if processes[pid][1] not in (b"Z", b"X"):
+            found.append(pid)
+    return found
+
+
+def launch_of(pid):
+    try:
+        with open("/proc/%d/cmdline" % pid, "rb") as source:
+            parts = source.read().split(b"\0")
+        at = parts.index(b"-c")
+        named = [part.decode() for part in parts[at + 2:at + 6]]
+    except (FileNotFoundError, ProcessLookupError, ValueError, UnicodeDecodeError):
+        return None
+    if len(named) != 4 or named[0] != root or named[1] != task:
+        return None
+    return named[2], named[3]
+
+
+def pin(pid, started):
+    if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
+        sys.exit(5)
+    try:
+        handle = os.pidfd_open(pid)
+    except (FileNotFoundError, ProcessLookupError):
+        return None
+    except OSError as error:
+        if error.errno == errno.ENOSYS:
+            sys.exit(5)
+        raise
+    now = described(pid)
+    if now is None or now[3] != started:
+        os.close(handle)
+        return None
+    return handle
+
+
+def kill(handle):
+    try:
+        signal.pidfd_send_signal(handle, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
+def kill_all(processes, pids):
+    for pid in pids:
+        handle = pin(pid, processes[pid][3])
+        if handle is not None:
+            kill(handle)
+            os.close(handle)
+
+
+def drain(handle, anchor):
+    """Kill everything under the anchor until the anchor ends: it ends on its
+    own once it has no child left. False when it has not by the bound."""
+    poller = select.poll()
+    poller.register(handle, select.POLLIN)
+    while not poller.poll(0):
+        processes = table()
+        kill_all(processes, under(processes, anchor))
+        if time.monotonic() > deadline:
+            return False
+        poller.poll(20)
+    return True
+
+
+def receipt_left(run, account, name):
+    fcntl.flock(lock, fcntl.LOCK_EX)
+    try:
+        try:
+            account_directory = descend(os.dup(directory), (run, account), False)
+        except FileNotFoundError:
+            return False
+        try:
+            os.stat(name, dir_fd=account_directory, follow_symlinks=False)
+            return True
+        except FileNotFoundError:
+            return False
+        finally:
+            os.close(account_directory)
+    finally:
+        fcntl.flock(lock, fcntl.LOCK_UN)
+
+
+try:
+    current = instance()
+except OSError:
+    sys.exit(7)
+try:
+    directory = task_directory(root, task, False)
+except FileNotFoundError:
+    directory = None
+except (OSError, Refused):
+    sys.exit(7)
+
+receipts = []
+if directory is not None:
+    try:
+        lock = locked(directory)
+        for run in os.listdir(directory):
+            if run == ".lock" or not NUMBER.match(run) or int(run) > through:
+                continue
+            run_directory = private(directory, run, False)
+            try:
+                for account in os.listdir(run_directory):
+                    if not selected(run, account):
+                        continue
+                    account_directory = private(run_directory, account, False)
+                    try:
+                        for name in os.listdir(account_directory):
+                            if name.startswith("admit-") or name.startswith(SECRET):
+                                os.unlink(name, dir_fd=account_directory)
+                            elif name.startswith("live-"):
+                                pid, started, owner = read_private(account_directory, name).split()
+                                if owner != current:
+                                    # That runtime instance is gone, and
+                                    # every process of it.
+                                    os.unlink(name, dir_fd=account_directory)
+                                else:
+                                    receipts.append((run, account, name, int(pid), int(started)))
+                            elif not (name.startswith("floor-") or name.startswith(RETIRED)):
+                                raise Refused("an unknown gate entry")
+                        if any(name.startswith("admit-") for name in os.listdir(account_directory)):
+                            raise Refused("a revoked gate came back")
+                    finally:
+                        os.close(account_directory)
+            finally:
+                os.close(run_directory)
+        # What waits elsewhere in memory for what it takes goes too, unread.
+        for area_root in roots:
+            if area_root == root:
+                continue
+            try:
+                area_directory = task_directory(area_root, task, False)
+            except FileNotFoundError:
+                continue
+            try:
+                for run in os.listdir(area_directory):
+                    if not NUMBER.match(run) or int(run) > through:
+                        continue
+                    run_directory = private(area_directory, run, False)
+                    try:
+                        for account in os.listdir(run_directory):
+                            if not selected(run, account):
+                                continue
+                            account_directory = private(run_directory, account, False)
+                            try:
+                                for name in os.listdir(account_directory):
+                                    if name.startswith(SECRET):
+                                        os.unlink(name, dir_fd=account_directory)
+                            finally:
+                                os.close(account_directory)
+                            try:
+                                os.rmdir(account, dir_fd=run_directory)
+                            except OSError:
+                                pass
+                    finally:
+                        os.close(run_directory)
+                    try:
+                        os.rmdir(run, dir_fd=area_directory)
+                    except OSError:
+                        pass
+            finally:
+                os.close(area_directory)
+        fcntl.flock(lock, fcntl.LOCK_UN)
+    except (OSError, Refused, ValueError):
+        sys.exit(7)
+
+lost = False
+for run, account, name, pid, started in receipts:
+    handle = pin(pid, started)
+    if handle is not None:
+        try:
+            process = described(pid)
+            if process is not None and process[0] == ANCHOR and process[4] == ME and not drain(handle, pid):
+                # Alive at the bound (stopped, wedged): it cannot prove its
+                # subtree empty, and nothing here can.
+                lost = True
+                continue
+        finally:
+            os.close(handle)
+    # The anchor has ended (or was never this process): its receipt says
+    # how. Gone, it proved its subtree empty; left, it died owning what may
+    # still run elsewhere, and the receipt stays as the witness.
+    if receipt_left(run, account, name):
+        lost = True
+
+# Launchers, and anchors never admitted: they hold the launch's
+# environment, and start nothing now. An anchor that owns anything without a
+# receipt of this instance was not admitted here: lost. An admitted one is
+# never killed here either: its receipt decided above.
+admitted = set((pid, started) for _, _, _, pid, started in receipts)
+processes = table()
+for pid, process in processes.items():
+    if process[0] not in (ANCHOR, LAUNCH) or process[4] != ME or process[1] in (b"Z", b"X"):
+        continue
+    if (pid, process[3]) in admitted:
+        continue
+    launch = launch_of(pid)
+    if launch is None or not selected(*launch):
+        continue
+    if process[0] == ANCHOR and under(processes, pid):
+        lost = True
+        continue
+    handle = pin(pid, process[3])
+    if handle is None:
+        continue
+    try:
+        kill(handle)
+        poller = select.poll()
+        poller.register(handle, select.POLLIN)
+        if not poller.poll(max(deadline - time.monotonic(), 0.5) * 1000):
+            # Killed and still there at the bound.
+            lost = True
+    finally:
+        os.close(handle)
+
+if lost:
+    sys.exit(6)
+if mode == "all" and directory is not None:
+    fcntl.flock(lock, fcntl.LOCK_EX)
+    for run in os.listdir(directory):
+        if run == ".lock" or not NUMBER.match(run) or int(run) > through:
+            continue
+        run_directory = private(directory, run, False)
+        for account in os.listdir(run_directory):
+            account_directory = private(run_directory, account, False)
+            for name in os.listdir(account_directory):
+                if name.startswith("floor-") or name.startswith(RETIRED):
+                    os.unlink(name, dir_fd=account_directory)
+            os.close(account_directory)
+            try:
+                os.rmdir(account, dir_fd=run_directory)
+            except OSError:
+                pass
+        os.close(run_directory)
+        try:
+            os.rmdir(run, dir_fd=directory)
+        except OSError:
+            pass
+    fcntl.flock(lock, fcntl.LOCK_UN)
+`;
+
+/**
+ * Revokes one admission, as root, with what it carried, unread: a launch
+ * refused after it was admitted, or that its provider could not start.
+ * argv: gate root, task, run, account segment, token, the areas a carried
+ * credential may wait in (one per line). Exits 0 once neither is left
+ * (whether or not the launch had already used them), 2 on malformed
+ * arguments, 7 when the gate area is not the runner's.
+ */
+export const ENGINE_GATE_REVOKE_HELPER =
+  GATE_PRELUDE +
+  String.raw`
+root, task, run, account, token, carriers = sys.argv[1:7]
+roots = [candidate for candidate in carriers.split("\n") if candidate]
+if not (NUMBER.match(run) and SEGMENT.match(account) and TOKEN.match(token)):
+    sys.exit(2)
+try:
+    try:
+        directory = task_directory(root, task, False)
+    except FileNotFoundError:
+        sys.exit(0)
+    lock = locked(directory)
+    try:
+        area = descend(os.dup(directory), (run, account), False)
+    except FileNotFoundError:
+        area = None
+    if area is not None:
+        try:
+            os.unlink("admit-" + token, dir_fd=area)
+        except FileNotFoundError:
+            pass
+        finally:
+            os.close(area)
+    drop_secret(roots, task, run, account, token)
+except (OSError, Refused):
+    sys.exit(7)
+`;
+
+/**
+ * Retires one launch slot, as root: marks it retired (`retired-<slot>`),
+ * then revokes every admission of it not yet used, with what it carried,
+ * unread. From then on, under the same lock, no admission of the slot is
+ * written or used. Where its run and subject have no gate area, nothing of
+ * it is there to retire, and nothing is made: a launch handed over has its
+ * admission written first, so its area is there. argv: gate root, task,
+ * run, account segment, slot, the areas a carried credential may wait in
+ * (one per line). Exits 0 once the slot is marked and none of its
+ * admissions is left (or nothing of it is there), 2 on malformed
+ * arguments, 7 when the gate area is not the runner's or a write fails.
+ */
+export const ENGINE_GATE_RETIRE_HELPER =
+  GATE_PRELUDE +
+  String.raw`
+root, task, run, account, slot, carriers = sys.argv[1:7]
+roots = [candidate for candidate in carriers.split("\n") if candidate]
+if not (NUMBER.match(run) and SEGMENT.match(account) and TOKEN.match(slot)):
+    sys.exit(2)
+try:
+    try:
+        directory = task_directory(root, task, False)
+    except FileNotFoundError:
+        sys.exit(0)
+    lock = locked(directory)
+    try:
+        directory = descend(directory, (run, account), False)
+    except FileNotFoundError:
+        sys.exit(0)
+    if not retired(directory, slot):
+        write_private(directory, RETIRED + slot, b"")
+    for entry in os.listdir(directory):
+        if not entry.startswith("admit-"):
+            continue
+        held = read_private(directory, entry).split(b"\n")
+        # The slot's own, and any written before admissions named their
+        # slot (one line short): revoked.
+        if len(held) < 6 or held[4] == slot.encode():
+            os.unlink(entry, dir_fd=directory)
+            drop_secret(roots, task, run, account, entry[len("admit-"):])
+except (OSError, Refused, ValueError):
+    sys.exit(7)
+`;
+
+/**
+ * The injector a provider that drops to the task user itself runs right
+ * after that drop (ADR-154 §6): it reads the launch's carried credentials
+ * from fd 9, the supervisor's hand-off, into its own environment, closes
+ * it, and runs the rest of its argv. argv: "9", "--", the process.
+ */
+export const ENGINE_CREDENTIAL_INJECTOR =
+  GATE_PRELUDE +
+  String.raw`
+arguments = sys.argv[1:]
+if len(arguments) < 3 or arguments[0] != str(CARRIER_FD) or arguments[1] != "--":
+    os._exit(126)
+try:
+    inject(CARRIER_FD)
+except BaseException:
+    os._exit(126)
+try:
+    os.execvp(arguments[2], arguments[2:])
+except BaseException:
+    os._exit(127)
+`;
+
+const ENGINE_ANCHOR_STOP_SECONDS = 15;
+let anchorStopSeconds = ENGINE_ANCHOR_STOP_SECONDS;
+
+/** The helpers' Python ignores the task's module paths (-I) and runs with
+ *  no preloads from the environment it is exec'd with. */
+const CLEAN_PYTHON_ENV: Readonly<Record<string, string>> = Object.freeze({
+  LD_AUDIT: "",
+  LD_LIBRARY_PATH: "",
+  LD_PRELOAD: "",
+  PYTHONHOME: "",
+  PYTHONPATH: "",
+});
+
+/** The supervisor's argv for one admitted launch, up to the user it drops
+ *  to (the provider appends that, "--" and the launch's own argv);
+ *  `heldAt`, the area its carried credentials wait in ("-": none). */
+export function engineAnchorPrefix(
+  identity: EngineLaunchIdentity,
+  token: string,
+  heldAt = "-",
+): [string, ...string[]] {
+  return [
+    "/usr/bin/python3",
+    "-I",
+    "-c",
+    ENGINE_ANCHOR_SHIM,
+    gateRoot,
+    identity.taskId,
+    String(identity.runEpoch),
+    gateSegment(identity),
+    token,
+    gateRevision(identity),
+    gateVersion(identity),
+    gateSlot(identity),
+    heldAt,
+  ];
+}
+
+/** The injector a provider that drops to the task user itself runs right
+ *  after its drop, before the launch, when the launch carries credentials. */
+const INJECTOR_PREFIX: readonly [string, ...string[]] = Object.freeze([
+  "/usr/bin/python3",
+  "-I",
+  "-c",
+  ENGINE_CREDENTIAL_INJECTOR,
+  "9",
+  "--",
+]) as unknown as readonly [string, ...string[]];
+
+/** One written admission: the anchor its launch starts under, and its
+ *  revocation. */
+export interface EngineAdmission {
+  readonly anchor: TaskEnvironmentAnchor;
+  /** Revoke the admission and what it carried, unread: the launch never
+   *  started, or must not. Resolves once neither is left, whether or not the
+   *  launch had already used them. Rejects when that could not be done
+   *  now; the revocation is then retained and retried until done, or until
+   *  a cleanup's stop of its run supersedes it (`retainedEngineRevocations`). */
+  revoke(): Promise<void>;
+}
+
+/**
+ * Admit one launch of `identity` in the task's runtime: write its token,
+ * as root, the exec admitted by `admit` at the provider's last moment.
+ * `carried`, the engine credentials the launch carries (ADR-154 §6, for a
+ * provider whose process environment would otherwise put them on a command
+ * line), travel on the helper's stdin and wait in memory beside the token
+ * until the supervisor hands them to the engine. Resolves to the admission.
+ * Rejects with `EngineLaunchRefused` when it could not be written (a
+ * version below the account's floor, a retired slot, or no memory to hold
+ * what it carries, included): the launch must not start.
+ */
+export async function admitEngineLaunch(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  identity: EngineLaunchIdentity,
+  admit: () => void,
+  carried: Readonly<Record<string, string>> | null = null,
+): Promise<EngineAdmission> {
+  const token = randomBytes(16).toString("hex");
+  const result = await environment.exec({
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-c",
+      ENGINE_GATE_WRITE_HELPER,
+      gateRoot,
+      identity.taskId,
+      String(identity.runEpoch),
+      gateSegment(identity),
+      token,
+      gateRevision(identity),
+      gateVersion(identity),
+      gateSlot(identity),
+      carrierRoots(),
+      carried === null ? "-" : "carry",
+    ],
+    user: "root",
+    env: CLEAN_PYTHON_ENV,
+    projectEnvProfile: "maintenance",
+    ...(carried === null ? {} : { stdin: Buffer.from(JSON.stringify(carried), "utf8") }),
+    timeoutMs: 30_000,
+    maxOutputBytes: 4 * 1024,
+    admit,
+  });
+  const heldAt = Buffer.from(result.stdout).toString("utf8").trim();
+  if (result.exitCode !== 0 || (carried === null ? heldAt !== "-" : !heldAt.startsWith("/"))) {
+    // The helper ran, and may have written the token and what it carries
+    // though its report was lost: both are revoked, unread, before the
+    // launch is refused (retained when that cannot be done now).
+    await revokeOrRetain(environment, identity, token).catch(() => {});
+    throw new EngineLaunchRefused("the task runtime could not admit the engine launch");
+  }
+  const anchor: TaskEnvironmentAnchor =
+    carried === null
+      ? { prefix: engineAnchorPrefix(identity, token) }
+      : { prefix: engineAnchorPrefix(identity, token, heldAt), injector: INJECTOR_PREFIX };
+  return { anchor, revoke: () => revokeOrRetain(environment, identity, token) };
+}
+
+/** A revocation, or a slot's retirement, not done yet: retried until it is,
+ *  or a cleanup's stop of its run supersedes it. */
+interface RetainedRevocation {
+  readonly environment: Pick<TaskEnvironmentHandle, "exec">;
+  readonly identity: EngineLaunchIdentity;
+  /** The admission revoked; null: the identity's slot, retired. */
+  readonly token: string | null;
+  attempts: number;
+}
+
+const retained = new Map<string, RetainedRevocation>();
+/** Revocations and slot retirements under way. A cleanup that proves them
+ *  done (`dischargeEngineRevocations`) marks them, and one so marked that
+ *  fails after is not retained: nothing is left to do, nor retried. */
+const underWay = new Set<{
+  readonly environment: Pick<TaskEnvironmentHandle, "exec">;
+  readonly identity: EngineLaunchIdentity;
+  discharged: boolean;
+}>();
+const REVOCATION_RETRY_FIRST_MS = 1_000;
+const REVOCATION_RETRY_MOST_MS = 60_000;
+let revocationRetryFirstMs = REVOCATION_RETRY_FIRST_MS;
+
+function retainedKey(identity: EngineLaunchIdentity, token: string | null): string {
+  return [identity.taskId, identity.runEpoch, gateSegment(identity), token ?? `slot:${gateSlot(identity)}`].join("\0");
+}
+
+/** Revoke one admission (`token`), or retire the identity's slot (null). */
+function revocation(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  identity: EngineLaunchIdentity,
+  token: string | null,
+): Promise<void> {
+  return token === null ? retireSlot(environment, identity) : revokeEngineAdmission(environment, identity, token);
+}
+
+/**
+ * Revoke one admission and what it carried, or retire a slot. When that
+ * cannot be done now (its runtime unreachable for a moment), it is retained
+ * and retried, backing off, until it is done or a cleanup's stop of its run
+ * in that runtime supersedes it: an admission and its plaintext are never
+ * left only because one attempt failed. Rejects all the same.
+ */
+async function revokeOrRetain(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  identity: EngineLaunchIdentity,
+  token: string | null,
+): Promise<void> {
+  const key = retainedKey(identity, token);
+  const attempt = { environment, identity, discharged: false };
+  underWay.add(attempt);
+  try {
+    await revocation(environment, identity, token);
+  } catch (error) {
+    if (!attempt.discharged && !retained.has(key)) {
+      const entry: RetainedRevocation = { environment, identity, token, attempts: 0 };
+      retained.set(key, entry);
+      console.warn(
+        `[engine-anchor] ${identity.taskId}: ${
+          token === null ? "a retired launch slot could not be closed" : "an engine admission could not be revoked"
+        } yet; retrying (${error instanceof Error ? error.message : String(error)})`,
+      );
+      retryRevocation(key, entry);
+    }
+    throw error;
+  } finally {
+    underWay.delete(attempt);
+  }
+  // Done: whatever was retained for it is too.
+  retained.delete(key);
+}
+
+function retryRevocation(key: string, entry: RetainedRevocation): void {
+  const delay = Math.min(REVOCATION_RETRY_MOST_MS, revocationRetryFirstMs * 2 ** entry.attempts);
+  const timer = setTimeout(() => {
+    if (retained.get(key) !== entry) return;
+    entry.attempts += 1;
+    revocation(entry.environment, entry.identity, entry.token).then(
+      () => {
+        if (retained.get(key) === entry) retained.delete(key);
+      },
+      () => {
+        if (retained.get(key) === entry) retryRevocation(key, entry);
+      },
+    );
+  }, delay);
+  timer.unref?.();
+}
+
+/** The revocations and slot retirements retained for `taskId` (every
+ *  task's when absent): what a cleanup of their runs has yet to supersede.
+ *  `credentialId` null: an agent's task token's. */
+export function retainedEngineRevocations(
+  taskId?: string,
+): Array<{ taskId: string; runEpoch: number; credentialId: string | null; slot: boolean }> {
+  return [...retained.values()]
+    .filter((entry) => taskId === undefined || entry.identity.taskId === taskId)
+    .map(({ identity, token }) => ({
+      taskId: identity.taskId,
+      runEpoch: identity.runEpoch,
+      credentialId: identity.subject === "account" ? identity.credentialId : null,
+      slot: token === null,
+    }));
+}
+
+/**
+ * A cleanup proved every admission of these runs and accounts (of every
+ * subject, a task token's included, when none is named) revoked in
+ * `environment` (its stop revokes every one not yet used), or, when no
+ * environment is named, in every runtime they were written in: the
+ * revocations and slot retirements retained for them are done.
+ */
+export function dischargeEngineRevocations(
+  scope: { taskId: string; runEpoch: number; credentialIds?: readonly string[] },
+  environment?: Pick<TaskEnvironmentHandle, "exec">,
+): void {
+  const named = scope.credentialIds === undefined ? null : new Set(scope.credentialIds);
+  const covered = (entry: { identity: EngineLaunchIdentity; environment: object }): boolean =>
+    entry.identity.taskId === scope.taskId &&
+    entry.identity.runEpoch <= scope.runEpoch &&
+    (!named || (entry.identity.subject === "account" && named.has(entry.identity.credentialId))) &&
+    (!environment || sameRuntime(environment, entry.environment));
+  for (const [key, entry] of retained) {
+    if (covered(entry)) retained.delete(key);
+  }
+  // One still under way is done too: should it fail now, it is not kept.
+  for (const attempt of underWay) {
+    if (covered(attempt)) attempt.discharged = true;
+  }
+}
+
+/** Whether two task environments are the same runtime. */
+export function sameRuntime(left: object, right: object): boolean {
+  if (left === right) return true;
+  const identity = (environment: object): unknown => (environment as { durableIdentity?: unknown }).durableIdentity;
+  return typeof identity(left) === "string" && identity(left) === identity(right);
+}
+
+/** Revoke one admission and what it carried, as root, unread. */
+async function revokeEngineAdmission(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  identity: EngineLaunchIdentity,
+  token: string,
+): Promise<void> {
+  const result = await environment.exec({
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-c",
+      ENGINE_GATE_REVOKE_HELPER,
+      gateRoot,
+      identity.taskId,
+      String(identity.runEpoch),
+      gateSegment(identity),
+      token,
+      carrierRoots(),
+    ],
+    user: "root",
+    env: CLEAN_PYTHON_ENV,
+    projectEnvProfile: "maintenance",
+    timeoutMs: 30_000,
+    maxOutputBytes: 4 * 1024,
+  });
+  if (result.exitCode !== 0) throw new Error("the task runtime could not revoke an engine admission");
+}
+
+/**
+ * Retire `identity`'s launch slot in one task runtime (ADR-154 §6): from
+ * then on no admission of it is written or used there, and every one it
+ * wrote that no launch has used is revoked, with what it carried, unread.
+ * Resolves once that is so. Rejects when it could not be done now; it is
+ * then retained and retried, backing off, until it is done or a cleanup's
+ * stop of its run supersedes it.
+ */
+export function retireEngineLaunchSlot(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  identity: EngineLaunchIdentity & { slotId: string },
+): Promise<void> {
+  return revokeOrRetain(environment, identity, null);
+}
+
+/** Retire one slot, as root. */
+async function retireSlot(environment: Pick<TaskEnvironmentHandle, "exec">, identity: EngineLaunchIdentity): Promise<void> {
+  if (identity.slotId === null) throw new Error("a launch with no slot cannot be retired");
+  const result = await environment.exec({
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-c",
+      ENGINE_GATE_RETIRE_HELPER,
+      gateRoot,
+      identity.taskId,
+      String(identity.runEpoch),
+      gateSegment(identity),
+      identity.slotId,
+      carrierRoots(),
+    ],
+    user: "root",
+    env: CLEAN_PYTHON_ENV,
+    projectEnvProfile: "maintenance",
+    timeoutMs: 30_000,
+    maxOutputBytes: 4 * 1024,
+  });
+  if (result.exitCode !== 0) throw new Error("the task runtime could not retire an engine launch slot");
+}
+
+/**
+ * Raise, in one task runtime, each account's floor for `runEpoch` to the
+ * version given (a floor never falls), and revoke its admissions below it:
+ * from then on, nothing admitted on an older version of that revision
+ * starts there. Rejects when it could not.
+ */
+export async function raiseEngineAdmissionFloors(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  request: { taskId: string; runEpoch: number; floors: readonly EngineAdmissionFloor[] },
+): Promise<void> {
+  if (request.floors.length === 0) return;
+  const result = await environment.exec({
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-",
+      gateRoot,
+      request.taskId,
+      String(request.runEpoch),
+      request.floors
+        .map((floor) => `${idPathSegment(floor.credentialId)}\t${floor.revision}\t${floor.version}`)
+        .join("\n"),
+      carrierRoots(),
+    ],
+    user: "root",
+    env: CLEAN_PYTHON_ENV,
+    projectEnvProfile: "maintenance",
+    stdin: Buffer.from(ENGINE_GATE_FLOOR_HELPER, "utf8"),
+    timeoutMs: 30_000,
+    maxOutputBytes: 4 * 1024,
+  });
+  if (result.exitCode !== 0) throw new Error("the task runtime could not hold back an AI account's older version");
+}
+
+/**
+ * Stop, in one task runtime, every anchored launch of `credentialIds` (of
+ * every account when absent) for `runEpoch` and older runs, and everything
+ * each started, and prove none is left; revoke every admission not yet
+ * used. Rejects with `EngineAnchorLost` when only stopping the runtime can
+ * prove it, otherwise with an error when it cannot be proven at all.
+ */
+export async function stopAnchoredEngines(
+  environment: Pick<TaskEnvironmentHandle, "exec">,
+  request: { taskId: string; runEpoch: number; credentialIds?: readonly string[] },
+): Promise<void> {
+  const named = request.credentialIds;
+  const result = await environment.exec({
+    argv: [
+      "/usr/bin/python3",
+      "-I",
+      "-",
+      gateRoot,
+      request.taskId,
+      String(request.runEpoch),
+      named === undefined ? "all" : "named",
+      (named ?? []).map(idPathSegment).join("\n"),
+      String(anchorStopSeconds),
+      carrierRoots(),
+    ],
+    user: "root",
+    env: CLEAN_PYTHON_ENV,
+    projectEnvProfile: "maintenance",
+    stdin: Buffer.from(ENGINE_ANCHOR_STOP_HELPER, "utf8"),
+    timeoutMs: (anchorStopSeconds + 10) * 1000,
+    maxOutputBytes: 4 * 1024,
+  });
+  if (result.exitCode === 6 || result.exitCode === 7) throw new EngineAnchorLost();
+  if (result.exitCode !== 0) {
+    throw new Error("an engine on a removed AI account could not be proven stopped");
+  }
+  // Every admission of these runs and accounts not yet used is revoked here.
+  dischargeEngineRevocations(request, environment);
+}
+
+/** Whether a request starts something that carries, or may carry, leased
+ *  engine material: what a task's engines run as, or anything with an
+ *  engine credential, an agent's task token or a leased engine's marker in
+ *  its environment. */
+export function launchesEngine(request: {
+  projectEnvProfile: string;
+  env?: Readonly<Record<string, string>>;
+  inheritEnv?: readonly string[];
+}): boolean {
+  return (
+    request.projectEnvProfile === "task" ||
+    Object.keys(request.env ?? {}).some(
+      (name) => isLaunchSecretEnvName(name) || name === ENGINE_RUN_ENV || name === ENGINE_ACCOUNT_ENV,
+    ) ||
+    (request.inheritEnv ?? []).some(isLaunchSecretEnvName)
+  );
+}
+
+/** The process-start methods an adapter may call on its environment. */
+const LAUNCHES: ReadonlySet<PropertyKey> = new Set(["exec", "spawn", "spawnSession", "launchDetachedSession"]);
+
+/** How the launches through an anchored environment are admitted. */
+export interface EngineLaunchGate {
+  /** Admit one launch, carrying `carried` (see `admitEngineLaunch`):
+   *  resolves to its admission, or rejects and it starts nothing. */
+  admit(carried: Readonly<Record<string, string>> | null): Promise<EngineAdmission>;
+  /** Whether a launch may still start; asked once more just before the
+   *  launch is handed to the provider, and again at the provider's last
+   *  moment (the request's `admit`), after anything it awaits first. */
+  held(): boolean;
+}
+
+/**
+ * ADR-154 §6, for a provider that carries a launch's engine credentials in
+ * its admission (`credentialDelivery: "admission"`): the request without
+ * them, and them, with the agent's task token under any of its names. A
+ * credential with a value is carried, never left in the request's
+ * environment, nor its name inherited from the runner's own; an explicit
+ * blank stays, so no other value of that name reaches the engine.
+ */
+export function carriedCredentials<
+  R extends { env?: Readonly<Record<string, string>>; inheritEnv?: readonly string[] },
+>(request: R): { delivered: R; carried: Record<string, string> | null } {
+  const env: Record<string, string> = {};
+  const carried: Record<string, string> = {};
+  for (const [name, value] of Object.entries(request.env ?? {})) {
+    if (isLaunchSecretEnvName(name) && value !== "") carried[name] = value;
+    else env[name] = value;
+  }
+  const delivered: R = {
+    ...request,
+    ...(request.env === undefined ? {} : { env }),
+    ...(request.inheritEnv === undefined
+      ? {}
+      : { inheritEnv: request.inheritEnv.filter((name) => !isLaunchSecretEnvName(name)) }),
+  };
+  return { delivered, carried: Object.keys(carried).length > 0 ? carried : null };
+}
+
+function isProcess(value: unknown): value is TaskEnvironmentProcess {
+  return typeof value === "object" && value !== null && "completion" in value;
+}
+
+/** A bounded exec's or detached launch's result that reports no exit, or a
+ *  failed one. */
+function failedResult(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "exitCode" in value &&
+    (value as Pick<TaskEnvironmentExecResult, "exitCode">).exitCode !== 0
+  );
+}
+
+/**
+ * `environment`, with every engine launch an adapter makes through it (a
+ * session, a one-shot turn, a durable runner, a bounded exec) admitted by
+ * `gate` and started under the anchor it resolves to; a launch it refuses
+ * rejects unstarted. The gate is asked again at the provider's last moment,
+ * after the request's own last-moment check: a launch whose gate closed
+ * while its provider waited (a machine looking up its address) starts
+ * nothing. On a provider that carries engine credentials in the
+ * admission, the launch's credentials go there, never into its command. An
+ * admission refused after it was written, or whose launch the provider
+ * could not start (it threw, or a bounded exec or detached launch reports
+ * no exit or a failed one), is revoked before the launch returns; one that
+ * carried credentials is revoked once its bounded exec or process has ended
+ * too, so nothing it carried outlives it unused (a detached launch's own
+ * supervisor uses it, or it expires). A revocation that cannot be done now
+ * is retained and retried (`EngineAdmission.revoke`), never dropped.
+ * Anything else passes through, bound to the original.
+ */
+export function anchoredEnvironment<T extends object>(environment: T, gate: EngineLaunchGate): T {
+  const carries = (environment as { credentialDelivery?: unknown }).credentialDelivery === "admission";
+  return new Proxy(environment, {
+    get(target, property) {
+      const value: unknown = Reflect.get(target, property, target);
+      if (typeof value !== "function") return value;
+      const method = value as (...args: unknown[]) => unknown;
+      if (!LAUNCHES.has(property)) return method.bind(target);
+      return async (
+        request: {
+          projectEnvProfile: string;
+          env?: Readonly<Record<string, string>>;
+          inheritEnv?: readonly string[];
+        },
+        ...rest: unknown[]
+      ) => {
+        if (!launchesEngine(request)) return method.call(target, request, ...rest);
+        const { delivered, carried } = carries ? carriedCredentials(request) : { delivered: request, carried: null };
+        const admission = await gate.admit(carried);
+        // A failure is retained by the admission and retried there.
+        const revoke = (): Promise<void> => admission.revoke().catch(() => undefined);
+        if (!gate.held()) {
+          await revoke();
+          throw new EngineLaunchRefused();
+        }
+        const own = (delivered as { admit?: () => void }).admit;
+        const admit = (): void => {
+          own?.();
+          if (!gate.held()) throw new EngineLaunchRefused();
+        };
+        let started: unknown;
+        try {
+          started = await method.call(target, { ...delivered, anchor: admission.anchor, admit }, ...rest);
+        } catch (error) {
+          await revoke();
+          throw error;
+        }
+        if ((property === "exec" || property === "launchDetachedSession") && failedResult(started)) {
+          // The provider reports no start, or a failed one: what it was
+          // admitted with may be left unused, so it is revoked first.
+          await revoke();
+          return started;
+        }
+        if (carried !== null) {
+          if (property === "exec") void revoke();
+          else if (isProcess(started)) void started.completion.then(revoke, revoke);
+        }
+        return started;
+      };
+    },
+  });
+}
+
+/** Tests only: where carried credentials wait when the gate area is not
+ *  held in memory. */
+export function setEngineCarrierRootForTests(root: string | null): void {
+  carrierFallbackRoot = root ?? ENGINE_CARRIER_FALLBACK_ROOT;
+}
+
+/** Tests only: where the gates live (a directory the test user owns). */
+export function setEngineGateRootForTests(root: string | null): void {
+  gateRoot = root ?? ENGINE_GATE_ROOT;
+}
+
+/** Tests only: the cleanup's bound, in seconds. */
+export function setEngineAnchorStopBoundForTests(seconds: number | null): void {
+  anchorStopSeconds = seconds ?? ENGINE_ANCHOR_STOP_SECONDS;
+}
+
+/** Tests only: the first retry of a retained revocation, in milliseconds,
+ *  and every retained revocation forgotten. */
+export function resetEngineRevocationsForTests(firstRetryMs: number | null = null): void {
+  revocationRetryFirstMs = firstRetryMs ?? REVOCATION_RETRY_FIRST_MS;
+  retained.clear();
+  // One still under way keeps nothing for the next test.
+  for (const attempt of underWay) attempt.discharged = true;
+  underWay.clear();
+}