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

package/dist/park.js

@@ -0,0 +1,229 @@
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { FencedError } from "./errors.js";
+/**
+ * The park target of a Harness the host opened over `lease`: the wake goes through `lease.setStatus`, and the release
+ * closes the Harness (running work is aborted with no outcome recorded) and then releases the lease. A rejecting close
+ * is a fence, as in `DurableRun.release`.
+ */
+export function leaseParkTarget(lease, harness, context = BACKGROUND_CONTEXT) {
+    return {
+        harness,
+        get fenced() {
+            return lease.fenced;
+        },
+        setStatus: (status, detail, options) => lease.setStatus(status, detail, options),
+        async release() {
+            try {
+                await harness.close(context);
+            }
+            catch (error) {
+                throw lease.fence(error instanceof FencedError ? error : new FencedError("closing the Harness failed, so the claim cannot be trusted", { cause: error }));
+            }
+            await lease.release();
+        },
+    };
+}
+/** localHost's threshold, far above twice its start (about 1.5 s); Cloudflare and Rivet park pi after 60 s too. */
+export const LOCAL_PARK_THRESHOLD_MS = 60_000;
+/**
+ * The deadline of a task that is only sleeping: `until` in pi's retry phase (generation and compaction), `pollAt` in
+ * its deferred poll phase. This is pi-durable's internal checkpoint shape, the same in 1.0.4 and 1.1.0
+ * (harness/generation.js, compaction.js), read here and nowhere else. Any other shape is no deadline, which counts as
+ * busy, so a pi that changes the shape keeps instances up rather than parking them mid-work. pi#10325 asks for this as
+ * a contract.
+ */
+export function waitDeadline(checkpoint) {
+    if (typeof checkpoint !== "object" || checkpoint === null || Array.isArray(checkpoint))
+        return undefined;
+    const at = checkpoint.phase === "retry" ? checkpoint.until : checkpoint.phase === "poll" ? checkpoint.pollAt : undefined;
+    return typeof at === "number" && Number.isFinite(at) ? at : undefined;
+}
+/**
+ * Whether the run's live work needs this instance. A task that runs or is ready to run does, unless it only sleeps
+ * until a deadline more than `thresholdMs` away. Waiting and completing tasks depend on other tasks, which decide; a
+ * blocked task (no registered definition can take it) never runs, so it never keeps the instance up. A closing
+ * Harness, a task state this code does not know, and unsettled submissions with no live task all count as busy.
+ */
+export function busyState(inspection, now, thresholdMs) {
+    if (inspection.scheduling === "closing")
+        return { kind: "busy" };
+    let until;
+    let live = false;
+    for (const task of inspection.tasks) {
+        const kind = task.state.kind;
+        if (kind === "waiting" || kind === "completing" || kind === "blocked")
+            continue;
+        if (kind !== "running" && kind !== "ready")
+            return { kind: "busy" };
+        live = true;
+        const deadline = waitDeadline(task.record.state.checkpoint);
+        if (deadline === undefined || deadline - now <= thresholdMs)
+            return { kind: "busy" };
+        until = Math.min(until ?? deadline, deadline);
+    }
+    if (until !== undefined)
+        return { kind: "waiting", until };
+    if (!live && inspection.tasks.length === 0 && inspection.submissions.length > 0)
+        return { kind: "busy" };
+    return { kind: "idle" };
+}
+/** The default wake: run.json `sleeping` with `wakeAt` (null: idle, started on demand), written durably. */
+export function recordWake(run, at) {
+    return run.setStatus("sleeping", { reason: at === null ? "idle" : "waiting" }, { wakeAt: at === null ? null : new Date(at).toISOString() });
+}
+/**
+ * Watch `run` and park it when its work allows. Checks after every commit (pi's listener must not call pi,
+ * so the check runs after it returns), on `check()`, and when an idle period ends. Parking stops admission, checks
+ * once more, records the wake, then releases: the wake is always written before the claim goes.
+ */
+export function watchParking(run, options) {
+    const now = options.now ?? Date.now;
+    const wake = options.wake ?? recordWake;
+    const log = options.log ?? (() => { });
+    const idleMs = options.idleMs ?? Number.POSITIVE_INFINITY;
+    let checking = false;
+    let dirty = false;
+    let stopped = false;
+    let idleSince;
+    let idleTimer;
+    let attempt;
+    const settled = {};
+    settled.promise = new Promise((resolve, reject) => Object.assign(settled, { resolve, reject }));
+    const classify = async () => {
+        const inspection = await run.harness.inspect(BACKGROUND_CONTEXT);
+        const blocked = inspection.tasks.filter((t) => t.state.kind === "blocked");
+        return { state: busyState(inspection, now(), options.thresholdMs), blocked };
+    };
+    const armIdle = (state) => {
+        if (state.kind !== "idle" || !Number.isFinite(idleMs)) {
+            idleSince = undefined;
+            clearTimeout(idleTimer);
+            return false;
+        }
+        idleSince ??= now();
+        const left = idleSince + idleMs - now();
+        if (left <= 0)
+            return true;
+        clearTimeout(idleTimer);
+        // Not unref'd: a park that is due is pending work, and nothing else may be keeping the process alive.
+        idleTimer = setTimeout(check, left);
+        return false;
+    };
+    const park = async () => {
+        const undo = options.quiesce?.() ?? (() => { });
+        const { state, blocked } = await classify();
+        const due = state.kind === "waiting" || (state.kind === "idle" && armIdle(state));
+        if (stopped || !due || options.keepAwake?.()) {
+            undo();
+            return undefined;
+        }
+        for (const t of blocked) {
+            log("blocked task does not keep the instance up", { task: t.record.id, kind: t.record.kind, reason: t.state.kind === "blocked" ? t.state.reason : null });
+        }
+        const at = state.kind === "waiting" ? state.until : null;
+        try {
+            await wake(run, at);
+        }
+        catch (error) {
+            undo();
+            // A fence already ends the instance; anything else leaves the wait to pi's own timer.
+            if (!(error instanceof FencedError) && !run.fenced)
+                log("wake not recorded; staying up through the wait", { wakeAt: at, error: error.message ?? String(error) });
+            return undefined;
+        }
+        stopped = true;
+        unsubscribe();
+        clearTimeout(idleTimer);
+        try {
+            await run.release();
+        }
+        catch (error) {
+            settled.reject(error);
+            throw error;
+        }
+        const result = { wakeAt: at, blocked: blocked.length };
+        settled.resolve(result);
+        return result;
+    };
+    async function loop() {
+        if (checking) {
+            dirty = true;
+            return;
+        }
+        checking = true;
+        try {
+            do {
+                dirty = false;
+                if (stopped || run.fenced)
+                    return;
+                if (options.keepAwake?.()) {
+                    // An open request is activity: an idle period starts again after it.
+                    armIdle({ kind: "busy" });
+                    return;
+                }
+                const { state } = await classify();
+                if (stopped)
+                    return;
+                if (state.kind === "waiting" || armIdle(state)) {
+                    attempt = park();
+                    if (await attempt)
+                        return;
+                }
+            } while (dirty && !stopped);
+        }
+        catch (error) {
+            if (!run.fenced)
+                log("park check failed", { error: error.message ?? String(error) });
+        }
+        finally {
+            checking = false;
+        }
+    }
+    function check() {
+        queueMicrotask(() => void loop());
+    }
+    const unsubscribe = run.harness.subscribeCommits(() => check());
+    settled.promise.catch(() => { });
+    check();
+    return {
+        parked: settled.promise,
+        check,
+        async stop() {
+            const inFlight = attempt;
+            stopped = true;
+            unsubscribe();
+            clearTimeout(idleTimer);
+            return inFlight ? inFlight.catch(() => undefined) : undefined;
+        },
+    };
+}
+/**
+ * Wait until no task needs this instance, or until `deadline`, rechecking after every commit.
+ * Any sleeping task counts as waiting here, however short its wait: closing ends the sleep and the next open resumes it.
+ * Returns the last classification: `busy` means the deadline passed with work running, which the release interrupts
+ * and the next open resumes (safe tools rerun, unsafe ones report the interruption).
+ */
+export async function drain(run, options) {
+    const now = options.now ?? Date.now;
+    let changed = () => { };
+    let timedOut = false;
+    const unsubscribe = run.harness.subscribeCommits(() => changed());
+    const timer = setTimeout(() => {
+        timedOut = true;
+        changed();
+    }, Math.max(0, options.deadline - Date.now()));
+    try {
+        for (;;) {
+            // Armed before the check, so a commit during the check is not missed.
+            const next = new Promise((resolve) => (changed = resolve));
+            const state = busyState(await run.harness.inspect(BACKGROUND_CONTEXT), now(), 0);
+            if (state.kind !== "busy" || timedOut)
+                return state;
+            await next;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        unsubscribe();
+    }
+}

package/dist/run.d.ts

@@ -0,0 +1,290 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import { Harness } from "@earendil-works/pi-durable";
+import type { HarnessOptions, Seq, Storage, ToolRegistration } from "@earendil-works/pi-durable";
+import type { SqliteDatabase, SqliteExecutor } from "@earendil-works/pi-durable/storage/sqlite";
+import { type AcquireOptions, type ArchilHost, type Claim, type RunRef } from "./claim.js";
+import { FencedError, PdaError } from "./errors.js";
+import { type ArchilStore, type Profile } from "./store.js";
+import { type ClaimDir, type PersistRecord, type RunRecord, type RunStatus } from "./status.js";
+/** The same-host owner lock under the run's root. */
+export declare const OWNER_LOCK = "owner.lock";
+/** pi's store under the claim's `store/` directory. */
+export declare const STORE_FILE = "run.sqlite";
+/** EX_DATAERR: the run's data refuses to open (a store behind its seal, an unreadable `run.json`); a restart cannot help. */
+export declare const EXIT_DATAERR = 65;
+/** EX_SOFTWARE: this package cannot read the head of pi's store (pi's schema moved); a restart cannot help. */
+export declare const EXIT_SOFTWARE = 70;
+export type RunErrorCode = "INVALID_ARGUMENT" | "STORE_HEAD_UNREADABLE" | "RUN_RELEASED";
+/**
+ * Bad options, a call on a released run, or a store whose head cannot be read (STORE_HEAD_UNREADABLE: the run is marked
+ * `failed` and released, exit 70).
+ */
+export declare class RunError extends PdaError {
+    constructor(code: RunErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The store's last committed sequence is below the `sealedSeq` the last clean release wrote: an acknowledged commit is
+ * missing. The run is refused before pi commits anything, and marked `failed` in `run.json`. Exit 65.
+ */
+export declare class StoreBehindSealError extends PdaError {
+    readonly sealedSeq: number;
+    /** The store's last committed sequence. */
+    readonly head: number;
+    constructor(file: string, sealedSeq: number, head: number);
+}
+/**
+ * The self-fence rule: the last heartbeat that succeeded started longer ago than the lease expiry minus its margin. `by`
+ * names who saw it: the main thread's timer, or the watchdog thread (which had already killed the commands).
+ */
+export declare class LeaseLapsedError extends FencedError {
+    readonly sinceMs: number;
+    readonly by: "timer" | "watchdog";
+    constructor(sinceMs: number, limitMs: number, by?: "timer" | "watchdog");
+}
+/** What the run needs of its environment: pi's `env` option plus a way to kill every command it started. */
+export type RunEnv = NonNullable<HarnessOptions["env"]> & {
+    cleanup(context: Context): Promise<void>;
+};
+export interface LeaseOptions {
+    /** Heartbeat period; default 20 s. */
+    readonly heartbeatMs?: number;
+    /** The lease the supervisor grants; default 90 s. */
+    readonly expiryMs?: number;
+    /** The instance fences itself at `expiryMs - marginMs` after the last successful heartbeat started; default 15 s. */
+    readonly marginMs?: number;
+    /** How often the self-fence timer looks; default 1 s. */
+    readonly checkMs?: number;
+}
+export type OpenStep = "acquire" | "owner-lock" | "run.json" | "heartbeat" | "layout" | "commands" | "store" | "seal" | "harness" | "live" | "before-resume" | "resume";
+export type ReleaseStep = "close" | "cleanup" | "barrier" | "seal" | "unlock" | "unmount";
+export interface OpenRunLeaseOptions {
+    /**
+     * The mount token from the host driver (reusable, 24 h); travels only on the archil wrapper's stdin, never in an
+     * environment. Required to mount an Archil disk (the default `acquire`); a run whose `acquire` is replaced (a local
+     * directory: `localRun`) needs none, and its `acquire` is handed an empty token.
+     */
+    readonly mountToken?: string;
+    /** Default /mnt/archil. */
+    readonly mountRoot?: string;
+    /** Mount with `--force`: the takeover fallback when the supervisor could not revoke. */
+    readonly force?: boolean;
+    readonly host?: ArchilHost;
+    /**
+     * The host driver's handle, written as run.json's `holder` with this process's pid and `since` added; `driver`
+     * defaults to `local`, `host` and `bootId` to this machine's. The supervisor hands it back to the driver to stop it.
+     */
+    readonly holder?: Readonly<Record<string, JsonValue>>;
+    readonly lease?: LeaseOptions;
+    /**
+     * The instance runs in a cgroup of its own (a systemd unit, a container). When the lease lapses, the watchdog then
+     * kills every other process in that cgroup too, beyond the instance's direct children and their process groups.
+     * Leave it off in a shared cgroup (a login session): its other processes are not the run's.
+     */
+    readonly ownCgroup?: boolean;
+    /**
+     * Kills every command the app started (pi starts each as its own process group, so the instance's own group does not
+     * reach them). Runs first on any fence, before `onFenced`, and as the first step of `release()`. Default: nothing.
+     */
+    readonly cleanup?: (context: Context) => Promise<void>;
+    /** Called once, after `cleanup`, on any fence. Default (and if it throws): a line on stderr, exit 75. */
+    readonly onFenced?: (error: FencedError) => void;
+    readonly context?: Context;
+    /** Each lifecycle step as it completes, with its duration. */
+    readonly onStep?: (step: OpenStep | ReleaseStep, ms: number) => void;
+    /** Replaceable for tests: how the claim is taken (default `acquire`). */
+    readonly acquire?: (options: AcquireOptions) => Promise<Claim>;
+    /** Replaceable for fault injection: how `run.json` is written (default `persistRecord`). */
+    readonly persist?: PersistRecord;
+    /**
+     * Replaceable for tests: how the claim's root is held open (default `openClaimDir(root)`, which requires the root to be
+     * the mount point of an Archil mount). A run root on a local directory passes `(root) => openClaimDir(root, { fstype: null })`.
+     */
+    readonly claimDir?: (root: string) => Promise<ClaimDir>;
+    /** Replaceable for tests: the monotonic clock the self-fence measures with, in ms (default `performance.now`). */
+    readonly clock?: () => number;
+}
+export interface OpenDurableRunOptions<Tool extends ToolRegistration = ToolRegistration> extends Omit<OpenRunLeaseOptions, "cleanup"> {
+    /** Default `exclusive`. */
+    readonly profile?: Profile;
+    /** pi's Harness options; the registry holds every extension before the Harness opens (recovered tasks need them). */
+    readonly harness: Omit<HarnessOptions<Tool>, "env">;
+    /** The run's environment, built on the claim; default `archilEnv(claim)`. Its `cleanup` is the lease's. */
+    readonly env?: (claim: Claim) => RunEnv;
+    /** Wraps the raw database inside the store's fence (instrumentation, fault injection). */
+    readonly decorateStore?: (database: SqliteDatabase) => SqliteDatabase;
+    /**
+     * Awaited once the Harness is open (its registry installed) and the run is live, before the Harness resumes: no
+     * resumed task takes a step until it settles, and what it admits (a submission, a write) is committed before anything
+     * a resumed task's steps commit. A host reconciles here what a resumed tool depends on (a browser, a mount). A rejection
+     * fails the open as any step does (`before-resume`), and the claim is released.
+     */
+    readonly beforeResume?: (run: BeforeResume) => void | Promise<void>;
+}
+/**
+ * What `beforeResume` sees: the open Harness, not yet resumed, the open's context, the incarnation it belongs to, and the
+ * store the Harness was opened over with its head (a recorder snapshots every document at `head` here).
+ */
+export interface BeforeResume {
+    readonly harness: Harness;
+    readonly context: Context;
+    readonly generation: number;
+    readonly record: RunRecord;
+    readonly claim: RunClaim;
+    /** The store the Harness was opened over, read-only: four reads on an object of their own, and no way to a write. */
+    readonly storage: StoreReads;
+    /**
+     * The store's last committed sequence once the Harness is open, read just before the hook runs. Until the hook commits
+     * something, the store's current state is its state at `head`: a document that keeps no history (`latest`, and session
+     * and task documents) reads only at "current", a `rewindable` one at `head` too.
+     */
+    readonly head: Seq;
+}
+/** The reads of a store that `beforeResume` gets. */
+export type StoreReads = Pick<Storage, "scanConversations" | "scanTasks" | "scanDocuments" | "document">;
+/** The claim as the app sees it: paths, the fenced flag, and a barrier whose failure fences the run. */
+export interface RunClaim {
+    readonly ref: RunRef;
+    readonly disk: string;
+    readonly root: string;
+    readonly work: string;
+    readonly store: string;
+    readonly fenced: boolean;
+    /** `archil sync` of the mount: the workspace is durable before a result commits and before a terminal status; a failure fences the run. */
+    barrier(): Promise<void>;
+}
+/**
+ * The claim's lifecycle for an app that owns its store and Harness (`openDurableRun` without the store and the Harness). Open
+ * order, all done by `openRunLease`: acquire and verify the claim, take the owner lock, write `run.json` (`running`,
+ * generation + 1, this holder, a heartbeat, the previous seal kept), start the heartbeat and the self-fence (a timer and
+ * a watchdog thread), create `store/`, `work/` and `tmp/`. The app then opens its store, calls `checkSeal` before
+ * anything commits, opens its Harness over `observe(storage)`, and calls `live()`. Once fenced, every member that
+ * writes rejects with the first fence; nothing is retried.
+ */
+export interface RunLease {
+    readonly ref: RunRef;
+    readonly claim: RunClaim;
+    /** This incarnation's generation in `run.json` (the previous one + 1). */
+    readonly generation: number;
+    /** `run.json` as last written. */
+    readonly record: RunRecord;
+    /** The seal the previous incarnation's clean release wrote; null on a first run and after a crash. */
+    readonly sealedSeq: number | null;
+    readonly fenced: boolean;
+    /**
+     * The seal check on the app's store, before anything commits: the store's head (`storeHead`) below
+     * `sealedSeq` is refused with StoreBehindSealError (65), and a head that cannot be read with RunError
+     * STORE_HEAD_UNREADABLE (70). Either way `run.json` is marked `failed` first, keeping the seal, and the app then calls
+     * `abandon` (never `release`, which would seal the lower head).
+     */
+    checkSeal(store: StoreHeadSource): Promise<void>;
+    /**
+     * `storage` reporting to the lease: every resolved commit's sequence counts toward the seal `release()` writes; a
+     * commit is refused once the watchdog found the lease lapsed, and one stuck meanwhile ends in the fence; a FencedError
+     * from a commit fences the lease. Wrap every Storage a Harness of the run opens over.
+     */
+    observe(storage: Storage): Storage;
+    /** The store is open and checked: clear the seal in `run.json` (a heartbeat write). */
+    live(): Promise<void>;
+    /**
+     * Fence the run, once: refuse every later `run.json` write (one in flight never renames), stop the timers and the
+     * watchdog, mark the claim fenced, all synchronously; then `cleanup`, then `onFenced`. Returns the first fence. The
+     * app's store facade calls it from its `onFenced`.
+     */
+    fence(error: FencedError): FencedError;
+    /** Resolves once a fence's cleanup and `onFenced` ran (when `onFenced` returns). */
+    fenceSettled(): Promise<void>;
+    /** Write a status transition. `done` and `failed` run the barrier first, so a terminal status never names workspace files that are not durable. */
+    setStatus(status: RunStatus, detail?: JsonValue | null, options?: {
+        readonly wakeAt?: string | null;
+    }): Promise<void>;
+    /** `archil sync` of the mount: the workspace is durable before a result commits and before a terminal status; a failure fences. */
+    barrier(): Promise<void>;
+    /**
+     * After the app closed every Harness and store connection: `cleanup`, barrier, seal `run.json` with the store's last
+     * sequence and the final status (`running` seals as `paused`), release the owner lock, unmount. Heartbeats continue
+     * until the seal and the self-fence past it, so a release that hangs still ends in exit 75. A failed barrier is a
+     * fence: nothing is sealed.
+     */
+    release(): Promise<void>;
+    /**
+     * Undo an open that failed after `openRunLease` (the app's store, the seal, its Harness): nothing is sealed. A fence
+     * goes to the fence path. Otherwise the timers stop, pending writes settle, `close` (the app closing what it opened)
+     * runs, the owner lock is released and the claim unmounted, except after a HeldError, whose mount another process on
+     * this host holds.
+     */
+    abandon(error: unknown, close?: () => Promise<void>): Promise<void>;
+}
+export interface DurableRun {
+    readonly ref: RunRef;
+    /** pi-durable's Harness, resumed. */
+    readonly harness: Harness;
+    readonly claim: RunClaim;
+    readonly env: RunEnv;
+    readonly store: ArchilStore;
+    readonly generation: number;
+    /** `run.json` as last written. */
+    readonly record: RunRecord;
+    readonly fenced: boolean;
+    /** Write a status transition. `done` and `failed` run the barrier first, so a terminal status never names workspace files that are not durable. */
+    setStatus(status: RunStatus, detail?: JsonValue | null, options?: {
+        readonly wakeAt?: string | null;
+    }): Promise<void>;
+    /**
+     * Close the Harness (running work is aborted with no outcome recorded, so the next open reports it interrupted),
+     * kill the run's commands, barrier, seal `run.json` with the store's last sequence and the final status (`running`
+     * seals as `paused`), release the owner lock, unmount. A rejecting close or barrier is a fence: nothing is sealed.
+     */
+    release(): Promise<void>;
+}
+export interface OwnerLock {
+    readonly file: string;
+    /** Drop the lock. An error is a fence (`ownWriteFenced`). */
+    release(): void;
+}
+/**
+ * Take the run's same-host owner lock for the life of this process. Node has no flock(2), so the lock is
+ * SQLite's exclusive POSIX lock on `<root>/owner.lock` (`locking_mode = EXCLUSIVE`, then `BEGIN EXCLUSIVE`), which the
+ * kernel drops when the process dies, however it dies. The journal stays in memory, so `owner.lock` is the only file
+ * the lock makes. Another process holding it is HeldError("owner-lock") (76); any other error is a fence, since the
+ * file is the claim's.
+ *
+ * Only this function may open `owner.lock` in the process: a POSIX lock is dropped when any descriptor the process holds
+ * on the file is closed, so a stray open and close elsewhere would silently release it.
+ */
+export declare function takeOwnerLock(root: string): OwnerLock;
+/** What `storeHead` reads: an ArchilStore, or any connection to a pi store with the file it opened. */
+export interface StoreHeadSource {
+    readonly database: Pick<SqliteExecutor, "get">;
+    readonly file: string;
+}
+/**
+ * The last sequence the store committed: the one read of pi's internal schema in this package. pi-durable's public
+ * `Storage` has no head query (1.0.4 and 1.1.0), and the seal check must run before `Harness.open` can commit (its
+ * recovery commit would reuse a lost sequence number). pi's SqliteStorage gives each commit `durable_metadata.next_seq`
+ * and stores the successor in the same transaction, so the head is `next_seq - 1`. The query only reads. A store
+ * without that table, row or column fails closed (STORE_HEAD_UNREADABLE), so a pi whose schema moved never skips the
+ * check silently; a unit test pins the read to the sequence pi's commits return.
+ *
+ * `database` is the store's fence-aware facade (`FencedDatabase`), which turns an I/O-class error into a fence; through
+ * a raw connection such an error would read as STORE_HEAD_UNREADABLE.
+ */
+export declare function storeHead(store: StoreHeadSource): Promise<number>;
+/**
+ * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, write
+ * `run.json` and start the heartbeat and the self-fence, create `store/`, `work/` and `tmp/`. Errors are typed as for
+ * `openDurableRun`: HeldError (76), FencedError (75, also passed to `onFenced`), RunRecordError (65), RunError
+ * INVALID_ARGUMENT before any claim.
+ */
+export declare function openRunLease(ref: RunRef, options: OpenRunLeaseOptions): Promise<RunLease>;
+/**
+ * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, `run.json`, heartbeat and
+ * self-fence, layout), then the store, the seal check before anything commits, pi's Harness with the app's registry,
+ * the seal cleared in `run.json`, resume.
+ *
+ * Errors are typed: HeldError (76) when another client, another process on this host or another connection holds the
+ * run; FencedError (75) when the claim cannot be trusted (also passed to `onFenced`); StoreBehindSealError (65) and
+ * RunError STORE_HEAD_UNREADABLE (70), each after marking the run `failed` and releasing the claim.
+ */
+export declare function openDurableRun<Tool extends ToolRegistration = ToolRegistration>(ref: RunRef, options: OpenDurableRunOptions<Tool>): Promise<DurableRun>;