@parcha/pi-durable-disk 0.0.0-stage → 0.1.0-beta.13

package/bin/archil-scoped

@@ -0,0 +1,165 @@
+#!/bin/sh
+# archil, with `mount` started in its own transient scope (<unit>-fuse-<n>.scope) when the caller runs inside a system
+# service, so the FUSE daemon that `archil mount` forks lives outside the instance unit's control group: stopping or
+# restarting the instance (KillMode=control-group) kills every command it started but never its mount, and an
+# in-place restart finds its claim still held. Any other verb, and any caller outside a system service, runs
+# archil unchanged. Run through sudo; install it root-owned, since root executes it.
+#
+# `mount` reads its token as one line on stdin and hands it to archil only in the environment of that exec. The token
+# is never an argument and never in an environment sudo sees: sudo logs every variable it preserves. An empty line or
+# no line refuses the mount.
+#
+# `retire <root>/runs/<run> <tag>` is for a kernel that refuses every unmount of a FUSE mount it still lists (Sysbox, as
+# Daytona runs sandboxes: umount2 fails with ENOENT). It moves the run's fuse.archil mount aside to
+# <root>/.released/<run>-<tag> and SIGKILLs its daemon, the process whose argument vector is this archil's `mount`
+# naming exactly that mountpoint, so the run's path is free for its next mount. The caller checks the delegation in
+# first; a dead mount has none left. Nothing else is moved or signalled.
+#
+# `stray <root>/runs/<run> <tag>` is for a run's mountpoint that is no mount and not empty (files a process wrote by
+# path after the run's mount vanished), which archil refuses to mount over. The directory is moved, whole, to
+# <root>/.stray/<run>-<tag> and replaced by an empty one with its owner and mode, made inside .stray first and renamed
+# into place. Nothing in it is read, copied or brought into the run; the output names only the entry counts.
+#
+# `stale <root>/runs/<run>` is for an archil daemon left on a run's mountpoint with no mount in the table (a client that
+# dropped its mount after an authentication failure, or whose mount was lazily unmounted while a process still held a
+# reference into it, keeps its process and the mountpoint's control socket), which makes every later mount there fail
+# with "an older Archil process is still running". It SIGKILLs the daemons whose argument vector is this archil's `mount`
+# naming exactly that mountpoint, and refuses while a mount is listed there (a live mount's daemon is never stale).
+#
+# The run's user may own <root>, so root never follows a link there: <root> and <root>/runs must be their own real
+# paths, the holding directory (.released or .stray) a real directory owned by root (made 0700 when absent), and the
+# destination new (never one that exists).
+set -eu
+ARCHIL=/usr/bin/archil
+MOUNT=/usr/bin/mount
+MOUNTS=/proc/self/mounts
+PROC=/proc
+KILL=kill
+OWNER=0
+
+listed() { awk -v m="$1" -v t="$2" '$2 == m && (t == "" || $3 == t) { f = 1 } END { exit !f }' "$MOUNTS"; }
+
+# The run's path and, for a verb that moves it, the tag: a plain <root>/runs/<run>, a one-segment tag, no link in <root>
+# or <root>/runs. Sets mp, tag and root.
+run_path() {
+  mp=$1 tag=${2-}
+  case "$mp" in */./*|*/../*|*/.|*/..|*//*) echo "archil-scoped: $mp is not a plain path" >&2; exit 2 ;; esac
+  printf '%s\n' "$mp" | grep -Eqx '/[A-Za-z0-9._/-]+/runs/[A-Za-z0-9][A-Za-z0-9._-]{0,127}' || { echo "archil-scoped: $mp is not <root>/runs/<run>" >&2; exit 2; }
+  [ "$#" -lt 2 ] || printf '%s\n' "$tag" | grep -Eqx '[A-Za-z0-9][A-Za-z0-9._-]{0,63}' || { echo "archil-scoped: tag $tag is not one safe path segment" >&2; exit 2; }
+  root=${mp%/runs/*}
+  for p in "$root" "$root/runs"; do
+    [ "$(realpath -e "$p" 2>/dev/null)" = "$p" ] || { echo "archil-scoped: $p is not its own real path (a link, or missing)" >&2; exit 2; }
+  done
+}
+
+# <root>/<name> as a real directory owned by root, made 0700 when absent. Sets held.
+holding() {
+  held="$root/$1"
+  if [ ! -e "$held" ] && [ ! -L "$held" ]; then
+    mkdir -m 0700 "$held" || { echo "archil-scoped: cannot create $held" >&2; exit 6; }
+  fi
+  if [ -L "$held" ] || [ ! -d "$held" ] || [ "$(stat -c %u "$held")" != "$OWNER" ]; then
+    echo "archil-scoped: $held is not a real directory owned by root" >&2
+    exit 6
+  fi
+}
+
+# The archil daemons of $mp: processes whose argument vector is this archil's `mount` naming exactly $mp. Sets pids.
+# One grep over every cmdline finds the few that hold $mp as a whole argument (a per-process pipeline costs seconds on a
+# host with thousands of processes); each of those is then matched exactly.
+daemons_of() {
+  pids=
+  cands=$(grep -zlFx -- "$mp" "$PROC"/[0-9]*/cmdline 2>/dev/null) || true
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if tr '\0' '\n' < "$f" 2>/dev/null | awk -v a="$ARCHIL" -v m="$mp" 'NR == 1 { x = ($0 == a) } NR == 2 { y = ($0 == "mount") } NR > 2 && $0 == m { z = 1 } END { exit !(x && y && z) }'; then
+      d=${f%/cmdline}
+      pids="$pids ${d##*/}"
+    fi
+  done <<EOF
+$cands
+EOF
+}
+
+# SIGKILL $pids and wait up to 5 s for them to be gone.
+kill_daemons() {
+  [ -n "$pids" ] || return 0
+  $KILL -KILL $pids 2>/dev/null || true
+  n=0 left=$pids
+  while [ -n "$left" ] && [ "$n" -lt 50 ]; do
+    sleep 0.1
+    n=$((n + 1))
+    left=
+    for p in $pids; do if [ -d "$PROC/$p" ]; then left="$left $p"; fi; done
+  done
+  [ -z "$left" ] || { echo "archil-scoped: archil daemon$left still alive" >&2; exit 5; }
+}
+
+retire() {
+  run_path "$1" "$2"
+  listed "$mp" fuse.archil || { echo "archil-scoped: no fuse.archil mount at $mp" >&2; exit 3; }
+  holding .released
+  dest="$held/${mp##*/}-$tag"
+  daemons_of
+  mkdir -m 0700 "$dest" 2>/dev/null || { echo "archil-scoped: $dest exists or cannot be made" >&2; exit 6; }
+  [ "$(realpath -e "$dest")" = "$dest" ] || { echo "archil-scoped: $dest is not its own real path" >&2; exit 6; }
+  "$MOUNT" --move "$mp" "$dest" || { echo "archil-scoped: mount --move $mp $dest failed" >&2; exit 4; }
+  if listed "$mp" ""; then echo "archil-scoped: $mp is still mounted after the move" >&2; exit 4; fi
+  kill_daemons
+  echo "archil-scoped: moved $mp to $dest; killed:${pids:- none}"
+}
+
+stale() {
+  run_path "$1"
+  if listed "$mp" ""; then echo "archil-scoped: $mp is mounted; its daemon is not stale" >&2; exit 3; fi
+  daemons_of
+  if [ -z "$pids" ]; then echo "archil-scoped: no archil daemon for $mp"; return; fi
+  if listed "$mp" ""; then echo "archil-scoped: $mp was mounted meanwhile; its daemon is not stale" >&2; exit 3; fi
+  kill_daemons
+  echo "archil-scoped: killed stale archil daemon(s) of $mp:$pids"
+}
+
+stray() {
+  run_path "$1" "$2"
+  if [ -L "$mp" ] || [ ! -d "$mp" ] || [ "$(realpath -e "$mp")" != "$mp" ]; then
+    echo "archil-scoped: $mp is not a real directory" >&2
+    exit 2
+  fi
+  if listed "$mp" ""; then echo "archil-scoped: $mp is a mount" >&2; exit 3; fi
+  entries=$(find "$mp" -mindepth 1 -maxdepth 1 | wc -l)
+  if [ "$entries" -eq 0 ]; then echo "archil-scoped: $mp is empty; nothing moved"; return; fi
+  total=$(find "$mp" -mindepth 1 | wc -l)
+  holding .stray
+  dest="$held/${mp##*/}-$tag"
+  fresh="$held/.fresh-${mp##*/}-$tag"
+  for p in "$dest" "$fresh"; do
+    if [ -e "$p" ] || [ -L "$p" ]; then echo "archil-scoped: $p exists" >&2; exit 6; fi
+  done
+  # Both renames stay on one filesystem: mv would otherwise copy, as root, whatever the directory holds.
+  [ "$(stat -c %d "$root/runs")" = "$(stat -c %d "$held")" ] || { echo "archil-scoped: $held is on another filesystem than $root/runs" >&2; exit 6; }
+  set -- $(stat -c '%u %g %a' "$mp")
+  { mkdir -m 0700 "$fresh" && chown "$1:$2" "$fresh" && chmod "$3" "$fresh"; } || { echo "archil-scoped: cannot prepare $fresh" >&2; exit 6; }
+  mv -T "$mp" "$dest" || { rmdir "$fresh"; echo "archil-scoped: moving $mp to $dest failed" >&2; exit 4; }
+  mv -T "$fresh" "$mp" || { echo "archil-scoped: $mp could not be replaced by an empty directory" >&2; exit 4; }
+  echo "archil-scoped: moved stray $mp to $dest; entries=$entries total=$total"
+}
+
+case "${1:-}" in
+  retire | stray)
+    [ "$#" -eq 3 ] || { echo "usage: archil-scoped $1 <root>/runs/<run> <tag>" >&2; exit 2; }
+    "$1" "$2" "$3"
+    exit 0
+    ;;
+  stale)
+    [ "$#" -eq 2 ] || { echo "usage: archil-scoped stale <root>/runs/<run>" >&2; exit 2; }
+    stale "$2"
+    exit 0
+    ;;
+esac
+[ "${1:-}" = mount ] || exec "$ARCHIL" "$@"
+token=
+IFS= read -r token || true
+[ -n "$token" ] || { echo "archil-scoped: no mount token on stdin" >&2; exit 2; }
+unit=$(sed -n 's|^0::/system\.slice/\(.*/\)\{0,1\}\([A-Za-z0-9:_.-]*\)\.service$|\2|p' /proc/self/cgroup)
+[ -n "$unit" ] || ARCHIL_MOUNT_TOKEN="$token" exec "$ARCHIL" "$@"
+ARCHIL_MOUNT_TOKEN="$token" exec /usr/bin/systemd-run --scope --quiet --collect --unit="$unit-fuse-$(date +%s%N)" -- "$ARCHIL" "$@"

package/dist/app.d.ts

@@ -0,0 +1,40 @@
+import type { Harness } from "@earendil-works/pi-durable";
+import type { RunRef } from "./claim.js";
+import { PdaError } from "./errors.js";
+import type { DurableRun, OpenDurableRunOptions } from "./run.js";
+/** Where the run lives on this host; known before it opens, so the app can build paths into its options. */
+export interface AppContext {
+    readonly ref: RunRef;
+    readonly root: string;
+    readonly work: string;
+    readonly store: string;
+}
+/** pi's HarnessOptions without `env` (registry, models, settings, conversationCreated, now, onReport), plus the hooks below. */
+export type AppOptions = OpenDurableRunOptions["harness"] & {
+    /**
+     * Awaited once per incarnation after the Harness is open and before it resumes (`OpenDurableRunOptions.beforeResume`):
+     * no resumed task takes a step until it settles. A rejection fails the open (exit 1, retried).
+     */
+    beforeResume?: OpenDurableRunOptions["beforeResume"];
+    /**
+     * Called once per incarnation after the run is open and resumed; `run.generation` tells a first start from a resume.
+     * Work that must keep the instance up belongs in pi's tasks and tools: parking sees only those.
+     */
+    onOpen?(run: DurableRun): void | Promise<void>;
+    /** pi's `root()` options for when `serve` creates the root conversation (its agent: model, extensions). */
+    root?: Parameters<Harness["root"]>[1];
+    /** Record a parking run's wake (park.ts `ParkOptions.wake`); default run.json `sleeping` with `wakeAt`. */
+    wake?(run: DurableRun, at: number | null): Promise<void>;
+};
+/** What `--app` names: `export default async (ctx) => ({ registry, models, onOpen })`. */
+export type AppModule = (ctx: AppContext) => AppOptions | Promise<AppOptions>;
+/**
+ * The app module is missing, does not load, has no default export function, throws, returns no options, or its
+ * `onOpen` failed. Exit 1: not terminal, so the unit retries within systemd's start limit.
+ */
+export declare class AppError extends PdaError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function loadApp(path: string, ctx: AppContext): Promise<AppOptions>;

package/dist/app.js

@@ -0,0 +1,47 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// The app an instance hosts (`pi-durable-disk run --app <module>`): an ES module whose default export is a function
+// of where the run lives that returns pi's Harness options (without `env`, which the run builds on its claim), an
+// optional `beforeResume` for what must settle before the run resumes, an optional `onOpen` for the app to submit or
+// resume work once the run is open and resumed, how `serve` creates the root conversation, and how a parking run records
+// its wake.
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PdaError } from "./errors.js";
+/**
+ * The app module is missing, does not load, has no default export function, throws, returns no options, or its
+ * `onOpen` failed. Exit 1: not terminal, so the unit retries within systemd's start limit.
+ */
+export class AppError extends PdaError {
+    constructor(message, options = {}) {
+        super("APP_FAILED", message, options);
+    }
+}
+export async function loadApp(path, ctx) {
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(path)).href)));
+    }
+    catch (err) {
+        throw new AppError(`cannot load the app module ${path}: ${err.message}`, { cause: err });
+    }
+    if (typeof mod.default !== "function")
+        throw new AppError(`the app module ${path} has no default export function`);
+    let options;
+    try {
+        options = await mod.default(ctx);
+    }
+    catch (err) {
+        throw new AppError(`the app module ${path} threw: ${err.message}`, { cause: err });
+    }
+    if (typeof options !== "object" || options === null || !options.registry || !options.models) {
+        throw new AppError(`the app module ${path} returned no Harness options (registry and models)`);
+    }
+    return options;
+}

package/dist/claim.d.ts

@@ -0,0 +1,222 @@
+import type { Delegation } from "disk";
+export type RunRef = {
+    disk: string;
+    region: string;
+    id: string;
+};
+/** The control-plane calls the claim uses; an archil `Disk` (SDK `disk` 1.7.0) satisfies it. Supervisor side only. */
+export interface ControlApi {
+    putObject(key: string, body: string, options: {
+        uid: number;
+        gid: number;
+        mode: number;
+    }): Promise<unknown>;
+    addUser(user: {
+        type: "token";
+        nickname: string;
+        ttl: string;
+        oneUse: boolean;
+    }): Promise<{
+        identifier?: string;
+        token?: string;
+    }>;
+    removeUser(type: "token", identifier: string): Promise<void>;
+    listDelegations(): Promise<Delegation[]>;
+    revokeDelegation(delegation: Pick<Delegation, "clientId" | "inodeId">): Promise<void>;
+    /**
+     * `Disk.exec`: a shell command in a container with the disk mounted in shared mode, at the disk root. The claim uses it
+     * only to resolve `runs/<id>` to its inode when the control API lists a delegation without a path. Without it, such a
+     * delegation cannot be attributed, and `findDelegations` fails rather than read the run as unheld.
+     */
+    exec?(command: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr?: string;
+    }>;
+}
+/** How this host runs the archil client. `archil mount`, `sync`, `delegations` and `unmount` all need root. */
+export interface ArchilHost {
+    /**
+     * The archil command: `bin/archil-scoped` or a root-owned copy of it (default: this package's). Its `mount` takes the
+     * token as one line on stdin; plain `/usr/bin/archil` does not, so a mount through it fails unauthenticated.
+     */
+    archil?: string;
+    fusermount?: string;
+    /** The sudo binary, or false when the process is root. Default: /usr/bin/sudo unless uid 0. */
+    sudo?: string | false;
+    procMounts?: string;
+    /** The process table the claim reads to find a stale archil daemon on the run's mountpoint. Default /proc. */
+    proc?: string;
+    /** `staleGrace`: how long a daemon left on an unmounted mountpoint may take to exit by itself before it is killed. */
+    timeoutMs?: {
+        mount?: number;
+        sync?: number;
+        unmount?: number;
+        cli?: number;
+        staleGrace?: number;
+    };
+    /** File access on the mount; replaceable so tests can inject a dead mount (ENOTCONN) or a fence (EIO). */
+    fs?: {
+        stat?(path: string): Promise<unknown>;
+        persist?(path: string, data: string): Promise<void>;
+    };
+}
+export interface AcquireOptions {
+    ref: RunRef;
+    /** The mount token. It travels only on the archil wrapper's stdin; never in argv or an environment, never printed or written. */
+    token: string;
+    /** Default /mnt/archil; the claim mounts at `<mountRoot>/runs/<id>` so paths are identical on every host. */
+    mountRoot?: string;
+    /** `archil mount --force`: the takeover fallback when the control API cannot revoke. */
+    force?: boolean;
+    host?: ArchilHost;
+}
+export interface Claim {
+    readonly ref: RunRef;
+    readonly disk: string;
+    readonly root: string;
+    readonly work: string;
+    readonly store: string;
+    /** True when an in-place restart found its own live mount and kept it; no token was used. */
+    readonly reused: boolean;
+    /** Entries found in the mountpoint before mounting, moved aside whole and never brought into the run; else null. */
+    readonly stray?: {
+        to: string;
+        entries: number;
+    } | null;
+    readonly forced: boolean;
+    readonly timings: {
+        mountMs: number;
+        verifyMs: number;
+    };
+    readonly fenced: boolean;
+    /** Mark the claim lost (the store's facade calls this on an I/O-class error); later barriers throw at once. */
+    markFenced(cause?: unknown): void;
+    /**
+     * Where the run's environment records the commands it starts, so that the next open of this claim ends what a killed
+     * incarnation left running (`reapCommands`, before the Harness opens). Set by a claim that nothing else cleans up after,
+     * as a local run's; a mount's host ends them with its unit's cgroup or its container.
+     */
+    readonly commands?: string;
+    /** `archil sync`: every pending write on the mount is durable when it resolves. A failure fences the claim. */
+    barrier(): Promise<{
+        ms: number;
+    }>;
+    /**
+     * Barrier, then `archil unmount` (flush and check the delegation in); a dead mount is cleaned with `fusermount -u`.
+     * Where the kernel refuses every unmount of a FUSE mount with ENOENT (Sysbox, Daytona's sandboxes): `archil checkin`,
+     * then the mount is moved aside and its daemon killed (`moved`).
+     */
+    release(): Promise<{
+        via: Unmounted;
+    }>;
+}
+export declare const DEFAULT_MOUNT_ROOT = "/mnt/archil";
+/** This package's `bin/archil-scoped`. A deployment installs a root-owned copy and passes its path as `archil`. */
+export declare const ARCHIL_SCOPED: string;
+/** The file the claim writes and fsyncs to prove it holds the delegation; written on every acquire. */
+export declare const CLAIM_PROBE = ".claim";
+/** How a mount left its path: unmounted by archil, by fusermount, moved aside (Sysbox), or there was none. */
+export type Unmounted = "archil" | "fusermount" | "moved" | "none";
+export declare function runPath(id: string): string;
+/** PutObject of the `/`-terminated key; uid/gid are required or the directory is root:root. 409: held. */
+export declare function createRunDir(control: ControlApi, id: string, owner: {
+    uid: number;
+    gid: number;
+    mode?: number;
+}): Promise<void>;
+/** A mount token's lifetime: one day, a Go duration (the control plane rejects "1d"). */
+export declare const MOUNT_TOKEN_TTL = "24h";
+export declare const TOKEN_PREFIX = "pda-";
+/** `<prefix><run id>-g<attempt>-<base36 ms>`: the token user names the run and start attempt it was minted for. */
+export declare function tokenNickname(runId: string, attempt: number, at?: number, prefix?: string): string;
+/** The run, attempt and minting time a nickname from `tokenNickname` names; null for anything else. */
+export declare function parseTokenNickname(nickname: string, prefix?: string): {
+    runId: string;
+    attempt: number;
+    at: number;
+} | null;
+/**
+ * A reusable mount token with a one-day TTL by default, minted per start attempt. Not single-use: the client
+ * re-authenticates at its background endpoint refresh, 5 min after the mount and every 5 min after, and the control plane
+ * rejects a spent single-use token for good, after which every write on the mount fails (client 0.8.42). A token
+ * whose TTL passes fences its mount the same way at the next refresh, so an instance never outlives its token by more
+ * than one refresh. The nickname is given, or built from `run` so the user can be traced back to its run.
+ */
+export declare function mintMountToken(control: ControlApi, opts: {
+    nickname?: string;
+    run?: {
+        id: string;
+        attempt: number;
+    };
+    prefix?: string;
+    ttl?: string;
+    oneUse?: boolean;
+    now?: () => number;
+}): Promise<{
+    token: string;
+    identifier: string;
+    nickname: string;
+}>;
+export declare function removeMountToken(control: ControlApi, identifier: string): Promise<void>;
+/**
+ * Delegations on `runs/<id>` and anything under it; never a sibling or a parent. The control API resolves a delegation's
+ * path best-effort: it can list one with no path, live or orphaned, on a never-reused run. So when nothing matches by
+ * path and some entry has none, the pathless entries are attributed by inode (`pathlessResolver`): those on the inode
+ * `runs/<id>` names now are the run's. A pathless entry that cannot be attributed fails CONTROL_API_FAILED: an unseen
+ * holder must never read as none, or a caller starts over it.
+ */
+export declare function findDelegations(control: Pick<ControlApi, "listDelegations" | "exec">, id: string, resolve?: PathlessResolver): Promise<Delegation[]>;
+/** `findDelegations` over a listing the caller already holds; share `resolve` across the runs of one listing or pass. */
+export declare function matchDelegations(all: readonly Delegation[], id: string, resolve: PathlessResolver): Promise<Delegation[]>;
+/** The run id whose directory each inode is, or null when it is no run directory (deleted, or not under `runs/`). */
+export type PathlessResolver = (pathless: readonly Delegation[]) => Promise<ReadonlyMap<number, string | null>>;
+/**
+ * Attributes pathless delegations by inode: one `exec` maps every inode not seen before to the run directory that has
+ * it (`find runs -inum`, whose inode numbers are the control API's inode ids). Share one across a listing or a supervisor
+ * pass: it costs one exec per batch of new inodes, never one per run. The output names only the inodes asked for, so it
+ * stays small however many runs the disk holds. A failed exec fails this call and every later one, with no new exec.
+ * Inodes on no run directory are reported once on stderr: they block nothing, and only a revoke by client and inode
+ * removes them.
+ */
+export declare function pathlessResolver(control: Pick<ControlApi, "exec">): PathlessResolver;
+/**
+ * The delegations `held`'s clients also hold on their own private directories (`privateDirs`: inode to the client whose
+ * private directory it is). A killed client leaves them orphaned, and nothing ties them to a run: they block no run, but
+ * they pile up and resurface in listings. A client that holds anything else beyond `held` may hold another run, so none
+ * of its delegations is a companion.
+ */
+export declare function companionsOf(all: readonly Delegation[], held: readonly Delegation[], privateDirs: ReadonlyMap<number, string>): Delegation[];
+/**
+ * Revoke the companions of `held` (`companionsOf`): only for clients the caller is already revoking because it fences or
+ * deletes a run, never as a sweep. From `all` or a fresh listing. Best effort, and hygiene only: a companion blocks no
+ * run, so one left behind (or a failed listing or `exec`) costs a listing entry. Returns the ones revoked.
+ */
+export declare function revokeCompanions(control: Pick<ControlApi, "listDelegations" | "revokeDelegation" | "exec">, held: readonly Delegation[], all?: readonly Delegation[]): Promise<Delegation[]>;
+/**
+ * Revoke every delegation on the run through the control API, then its holders' private directories
+ * (`revokeCompanions`). The old holder's next fsync returns EIO. Returns the run's own delegations.
+ */
+export declare function revoke(control: ControlApi, id: string): Promise<Delegation[]>;
+/**
+ * Revoke what `revoke` revokes, skipping every revoke that fails: for cleanup, where deleting the tree next checks what
+ * is left. Only the listing (and a pathless resolution) can fail it. Returns the run's own delegations.
+ */
+export declare function revokeBestEffort(control: Pick<ControlApi, "listDelegations" | "revokeDelegation" | "exec">, id: string): Promise<Delegation[]>;
+/** Revoke through the control API, then mount plainly; if the API path fails, mount with `--force`. */
+export declare function takeOver(control: ControlApi, opts: AcquireOptions): Promise<Claim>;
+/**
+ * Unmount whatever the run has at `mountpoint`: `archil unmount` flushes and checks the delegation in; a dead mount
+ * (which `archil unmount` refuses) is cleaned with `fusermount -u`; a live mount refused with ENOENT (Sysbox) is checked
+ * in and moved aside. Any other live mount that refuses is never forced.
+ */
+export declare function unmountClaim(mountpoint: string, host?: ArchilHost): Promise<Unmounted>;
+/**
+ * Take the run's claim: mount `<disk>:/runs/<id>` exclusively at `<mountRoot>/runs/<id>` and verify it. A live mount of
+ * the same run already there is kept (in-place restart); a dead one is cleaned first. With no mount there, a stale archil
+ * daemon on the mountpoint is killed (`stale`) and entries in it are moved aside to `<mountRoot>/.stray` (`stray`) before
+ * the mount. Throws HeldError (exit 76) only when another client holds the delegation, FencedError (exit 75) when the
+ * verifying write is refused, MOUNTPOINT_NOT_EMPTY when the mountpoint cannot be emptied or archil still finds it not
+ * empty, MOUNT_FAILED (exit 1) for a daemon of this host that is still running there.
+ */
+export declare function acquire(opts: AcquireOptions): Promise<Claim>;